%!PS-Adobe-2.0 %%Creator: dvips(k) 5.96.1 Copyright 2007 Radical Eye Software %%Title: paper-letter/lib.dvi %%CreationDate: Fri Dec 19 16:19:36 2008 %%Pages: 1044 %%PageOrder: Ascend %%BoundingBox: 0 0 612 792 %%DocumentFonts: Helvetica Helvetica-Oblique Times-Roman Times-Bold %%+ CMSY10 Times-Italic Courier Helvetica-Bold Courier-Bold CMR10 CMMI10 %%+ CMMI7 CMSY7 CMSY5 Times-BoldItalic Courier-Oblique CMSY9 CMEX10 CMR7 %%DocumentPaperSizes: Letter %%EndComments %DVIPSWebPage: (www.radicaleye.com) %DVIPSCommandLine: dvips -N0 -t letter -o paper-letter/lib.ps %+ paper-letter/lib.dvi %DVIPSParameters: dpi=600 %DVIPSSource: TeX output 2008.12.19:1619 %%BeginProcSet: tex.pro 0 0 %! /TeXDict 300 dict def TeXDict begin/N{def}def/B{bind def}N/S{exch}N/X{S N}B/A{dup}B/TR{translate}N/isls false N/vsize 11 72 mul N/hsize 8.5 72 mul N/landplus90{false}def/@rigin{isls{[0 landplus90{1 -1}{-1 1}ifelse 0 0 0]concat}if 72 Resolution div 72 VResolution div neg scale isls{ landplus90{VResolution 72 div vsize mul 0 exch}{Resolution -72 div hsize mul 0}ifelse TR}if Resolution VResolution vsize -72 div 1 add mul TR[ matrix currentmatrix{A A round sub abs 0.00001 lt{round}if}forall round exch round exch]setmatrix}N/@landscape{/isls true N}B/@manualfeed{ statusdict/manualfeed true put}B/@copies{/#copies X}B/FMat[1 0 0 -1 0 0] N/FBB[0 0 0 0]N/nn 0 N/IEn 0 N/ctr 0 N/df-tail{/nn 8 dict N nn begin /FontType 3 N/FontMatrix fntrx N/FontBBox FBB N string/base X array /BitMaps X/BuildChar{CharBuilder}N/Encoding IEn N end A{/foo setfont}2 array copy cvx N load 0 nn put/ctr 0 N[}B/sf 0 N/df{/sf 1 N/fntrx FMat N df-tail}B/dfs{div/sf X/fntrx[sf 0 0 sf neg 0 0]N df-tail}B/E{pop nn A definefont setfont}B/Cw{Cd A length 5 sub get}B/Ch{Cd A length 4 sub get }B/Cx{128 Cd A length 3 sub get sub}B/Cy{Cd A length 2 sub get 127 sub} B/Cdx{Cd A length 1 sub get}B/Ci{Cd A type/stringtype ne{ctr get/ctr ctr 1 add N}if}B/CharBuilder{save 3 1 roll S A/base get 2 index get S /BitMaps get S get/Cd X pop/ctr 0 N Cdx 0 Cx Cy Ch sub Cx Cw add Cy setcachedevice Cw Ch true[1 0 0 -1 -.1 Cx sub Cy .1 sub]{Ci}imagemask restore}B/D{/cc X A type/stringtype ne{]}if nn/base get cc ctr put nn /BitMaps get S ctr S sf 1 ne{A A length 1 sub A 2 index S get sf div put }if put/ctr ctr 1 add N}B/I{cc 1 add D}B/bop{userdict/bop-hook known{ bop-hook}if/SI save N @rigin 0 0 moveto/V matrix currentmatrix A 1 get A mul exch 0 get A mul add .99 lt{/QV}{/RV}ifelse load def pop pop}N/eop{ SI restore userdict/eop-hook known{eop-hook}if showpage}N/@start{ userdict/start-hook known{start-hook}if pop/VResolution X/Resolution X 1000 div/DVImag X/IEn 256 array N 2 string 0 1 255{IEn S A 360 add 36 4 index cvrs cvn put}for pop 65781.76 div/vsize X 65781.76 div/hsize X}N /p{show}N/RMat[1 0 0 -1 0 0]N/BDot 260 string N/Rx 0 N/Ry 0 N/V{}B/RV/v{ /Ry X/Rx X V}B statusdict begin/product where{pop false[(Display)(NeXT) (LaserWriter 16/600)]{A length product length le{A length product exch 0 exch getinterval eq{pop true exit}if}{pop}ifelse}forall}{false}ifelse end{{gsave TR -.1 .1 TR 1 1 scale Rx Ry false RMat{BDot}imagemask grestore}}{{gsave TR -.1 .1 TR Rx Ry scale 1 1 false RMat{BDot} imagemask grestore}}ifelse B/QV{gsave newpath transform round exch round exch itransform moveto Rx 0 rlineto 0 Ry neg rlineto Rx neg 0 rlineto fill grestore}B/a{moveto}B/delta 0 N/tail{A/delta X 0 rmoveto}B/M{S p delta add tail}B/b{S p tail}B/c{-4 M}B/d{-3 M}B/e{-2 M}B/f{-1 M}B/g{0 M} B/h{1 M}B/i{2 M}B/j{3 M}B/k{4 M}B/w{0 rmoveto}B/l{p -4 w}B/m{p -3 w}B/n{ p -2 w}B/o{p -1 w}B/q{p 1 w}B/r{p 2 w}B/s{p 3 w}B/t{p 4 w}B/x{0 S rmoveto}B/y{3 2 roll p a}B/bos{/SS save N}B/eos{SS restore}B end %%EndProcSet %%BeginProcSet: 8r.enc 0 0 % File 8r.enc TeX Base 1 Encoding Revision 2.0 2002-10-30 % % @@psencodingfile@{ % author = "S. Rahtz, P. MacKay, Alan Jeffrey, B. Horn, K. Berry, % W. Schmidt, P. Lehman", % version = "2.0", % date = "27nov06", % filename = "8r.enc", % email = "tex-fonts@@tug.org", % docstring = "This is the encoding vector for Type1 and TrueType % fonts to be used with TeX. This file is part of the % PSNFSS bundle, version 9" % @} % % The idea is to have all the characters normally included in Type 1 fonts % available for typesetting. This is effectively the characters in Adobe % Standard encoding, ISO Latin 1, Windows ANSI including the euro symbol, % MacRoman, and some extra characters from Lucida. % % Character code assignments were made as follows: % % (1) the Windows ANSI characters are almost all in their Windows ANSI % positions, because some Windows users cannot easily reencode the % fonts, and it makes no difference on other systems. The only Windows % ANSI characters not available are those that make no sense for % typesetting -- rubout (127 decimal), nobreakspace (160), softhyphen % (173). quotesingle and grave are moved just because it's such an % irritation not having them in TeX positions. % % (2) Remaining characters are assigned arbitrarily to the lower part % of the range, avoiding 0, 10 and 13 in case we meet dumb software. % % (3) Y&Y Lucida Bright includes some extra text characters; in the % hopes that other PostScript fonts, perhaps created for public % consumption, will include them, they are included starting at 0x12. % These are /dotlessj /ff /ffi /ffl. % % (4) hyphen appears twice for compatibility with both ASCII and Windows. % % (5) /Euro was assigned to 128, as in Windows ANSI % % (6) Missing characters from MacRoman encoding incorporated as follows: % % PostScript MacRoman TeXBase1 % -------------- -------------- -------------- % /notequal 173 0x16 % /infinity 176 0x17 % /lessequal 178 0x18 % /greaterequal 179 0x19 % /partialdiff 182 0x1A % /summation 183 0x1B % /product 184 0x1C % /pi 185 0x1D % /integral 186 0x81 % /Omega 189 0x8D % /radical 195 0x8E % /approxequal 197 0x8F % /Delta 198 0x9D % /lozenge 215 0x9E % /TeXBase1Encoding [ % 0x00 /.notdef /dotaccent /fi /fl /fraction /hungarumlaut /Lslash /lslash /ogonek /ring /.notdef /breve /minus /.notdef /Zcaron /zcaron % 0x10 /caron /dotlessi /dotlessj /ff /ffi /ffl /notequal /infinity /lessequal /greaterequal /partialdiff /summation /product /pi /grave /quotesingle % 0x20 /space /exclam /quotedbl /numbersign /dollar /percent /ampersand /quoteright /parenleft /parenright /asterisk /plus /comma /hyphen /period /slash % 0x30 /zero /one /two /three /four /five /six /seven /eight /nine /colon /semicolon /less /equal /greater /question % 0x40 /at /A /B /C /D /E /F /G /H /I /J /K /L /M /N /O % 0x50 /P /Q /R /S /T /U /V /W /X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore % 0x60 /quoteleft /a /b /c /d /e /f /g /h /i /j /k /l /m /n /o % 0x70 /p /q /r /s /t /u /v /w /x /y /z /braceleft /bar /braceright /asciitilde /.notdef % 0x80 /Euro /integral /quotesinglbase /florin /quotedblbase /ellipsis /dagger /daggerdbl /circumflex /perthousand /Scaron /guilsinglleft /OE /Omega /radical /approxequal % 0x90 /.notdef /.notdef /.notdef /quotedblleft /quotedblright /bullet /endash /emdash /tilde /trademark /scaron /guilsinglright /oe /Delta /lozenge /Ydieresis % 0xA0 /.notdef /exclamdown /cent /sterling /currency /yen /brokenbar /section /dieresis /copyright /ordfeminine /guillemotleft /logicalnot /hyphen /registered /macron % 0xB0 /degree /plusminus /twosuperior /threesuperior /acute /mu /paragraph /periodcentered /cedilla /onesuperior /ordmasculine /guillemotright /onequarter /onehalf /threequarters /questiondown % 0xC0 /Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla /Egrave /Eacute /Ecircumflex /Edieresis /Igrave /Iacute /Icircumflex /Idieresis % 0xD0 /Eth /Ntilde /Ograve /Oacute /Ocircumflex /Otilde /Odieresis /multiply /Oslash /Ugrave /Uacute /Ucircumflex /Udieresis /Yacute /Thorn /germandbls % 0xE0 /agrave /aacute /acircumflex /atilde /adieresis /aring /ae /ccedilla /egrave /eacute /ecircumflex /edieresis /igrave /iacute /icircumflex /idieresis % 0xF0 /eth /ntilde /ograve /oacute /ocircumflex /otilde /odieresis /divide /oslash /ugrave /uacute /ucircumflex /udieresis /yacute /thorn /ydieresis ] def %%EndProcSet %%BeginProcSet: texps.pro 0 0 %! TeXDict begin/rf{findfont dup length 1 add dict begin{1 index/FID ne 2 index/UniqueID ne and{def}{pop pop}ifelse}forall[1 index 0 6 -1 roll exec 0 exch 5 -1 roll VResolution Resolution div mul neg 0 0]FontType 0 ne{/Metrics exch def dict begin Encoding{exch dup type/integertype ne{ pop pop 1 sub dup 0 le{pop}{[}ifelse}{FontMatrix 0 get div Metrics 0 get div def}ifelse}forall Metrics/Metrics currentdict end def}{{1 index type /nametype eq{exit}if exch pop}loop}ifelse[2 index currentdict end definefont 3 -1 roll makefont/setfont cvx]cvx def}def/ObliqueSlant{dup sin S cos div neg}B/SlantFont{4 index mul add}def/ExtendFont{3 -1 roll mul exch}def/ReEncodeFont{CharStrings rcheck{/Encoding false def dup[ exch{dup CharStrings exch known not{pop/.notdef/Encoding true def}if} forall Encoding{]exch pop}{cleartomark}ifelse}if/Encoding exch def}def end %%EndProcSet %%BeginFont: CMR7 %!PS-AdobeFont-1.1: CMR7 1.0 %%CreationDate: 1991 Aug 20 16:39:21 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.0) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMR7) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def end readonly def /FontName /CMR7 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 50 /two put readonly def /FontBBox{-27 -250 1122 750}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052A014267B7904EB3C0D3BD0B83D891 016CA6CA4B712ADEB258FAAB9A130EE605E61F77FC1B738ABC7C51CD46EF8171 9098D5FEE67660E69A7AB91B58F29A4D79E57022F783EB0FBBB6D4F4EC35014F D2DECBA99459A4C59DF0C6EBA150284454E707DC2100C15B76B4C19B84363758 469A6C558785B226332152109871A9883487DD7710949204DDCF837E6A8708B8 2BDBF16FBC7512FAA308A093FE5CF5B8CABB9FFC6CC3F1E9AE32F234EB60FE7D E34995B1ACFF52428EA20C8ED4FD73E3935CEBD40E0EAD70C0887A451E1B1AC8 47AEDE4191CCDB8B61345FD070FD30C4F375D8418DDD454729A251B3F61DAE7C 8882384282FDD6102AE8EEFEDE6447576AFA181F27A48216A9CAD730561469E4 78B286F22328F2AE84EF183DE4119C402771A249AAC1FA5435690A28D1B47486 1060C8000D3FE1BF45133CF847A24B4F8464A63CEA01EC84AA22FD005E74847E 01426B6890951A7DD1F50A5F3285E1F958F11FC7F00EE26FEE7C63998EA1328B C9841C57C80946D2C2FC81346249A664ECFB08A2CE075036CEA7359FCA1E90C0 F686C3BB27EEFA45D548F7BD074CE60E626A4F83C69FE93A5324133A78362F30 8E8DCC80DD0C49E137CDC9AC08BAE39282E26A7A4D8C159B95F227BDA2A281AF A9DAEBF31F504380B20812A211CF9FEB112EC29A3FB3BD3E81809FC6293487A7 455EB3B879D2B4BD46942BB1243896264722CB59146C3F65BD59B96A74B12BB2 9A1354AF174932210C6E19FE584B1B14C00E746089CBB17E68845D7B3EA05105 EEE461E3697FCF835CBE6D46C75523478E766832751CF6D96EC338BDAD57D53B 52F5340FAC9FE0456AD13101824234B262AC0CABA43B62EBDA39795BAE6CFE97 563A50AAE1F195888739F2676086A9811E5C9A4A7E0BF34F3E25568930ADF80F 0BDDAC3B634AD4BA6A59720EA4749236CF0F79ABA4716C340F98517F6F06D9AB 7ED8F46FC1868B5F3D3678DF71AA772CF1F7DD222C6BF19D8EF0CFB7A76FC6D1 0AD323C176134907AB375F20CFCD667AB094E2C7CB2179C4283329C9E435E7A4 1E042AD0BAA059B3F862236180B34D3FCED833472577BACD472A4DE3E3F6222F 7A252B780C86447859579C68FE065411FD8ADADF4FC7DE51F8FD675D89D8660B E7C97553F2D04925B72675324E1F1812AAA3BD881E968F16EDE2BDEC29955667 9E28B8AFCDC4E73FC735123B91F110188E4158D075070E40460602F27C12ADA7 A45B6318E24F206E2CA486BC1A90C9AD86B84CA04B57354721DDC0A60E6C3A73 429B900B12A14AB1A57500F5DA0A649E0E3899029331E48ADCE3457B064F4D4F D4C9D6AA67E2CC75B822A090EB31C4E78B3FFA9F9F3DB10177C5AB6561041870 015CF27E4FDA0F155F1642F2BD0D4CBE322B29DA184C025DDF95869B5218A24C 90802F8C9FC82FFED0A466A364C162DDF246F203E46D650355B4C10EDE176886 2474B6FB50199C2F24CF819F44949E8DED68D4167E6657E434923FB5500BD442 56A0B82C3B 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMEX10 %!PS-AdobeFont-1.1: CMEX10 1.00 %%CreationDate: 1992 Jul 23 21:22:48 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.00) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMEX10) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def end readonly def /FontName /CMEX10 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 80 /summationtext put dup 115 /radicalBigg put readonly def /FontBBox{-24 -2960 1454 772}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052A014267B7904EB3C0D3BD0B83D891 016CA6CA4B712ADEB258FAAB9A130EE605E61F77FC1B738ABC7C51CD46EF8171 9098D5FEE67660E69A7AB91B58F29A4D79E57022F783EB0FBBB6D4F4EC35014F D2DECBA99459A4C59DF0C6EBA150284454E707DC2100C15B76B4C19B84363758 469A6C558785B226332152109871A9883487DD7710949204DDCF837E6A8708B8 2BDBF16FBC7512FAA308A093FE5CF5B8CAC6A7BEB5D02276E511FFAF2AE11910 DE076F24311D94D07CACC323F360887F1EA11BDDA7927FF3325986FDB0ABDFC8 8E4B40E7988921D551EC0867EBCA44C05657F0DC913E7B3004A5F3E1337B6987 FEBC45F989C8DC6DC0AD577E903F05D0D54208A0AE7F28C734F130C133B48422 BED48639A2B74E4C08F2E710E24A99F347E0F4394CE64EACB549576E89044E52 EABE595BC964156D9D8C2BAB0F49664E951D7C1A3D1789C47F03C7051A63D5E8 DF04FAAC47351E82CAE0794AA9692C6452688A74A7A6A7AD09B8A9783C235EC1 EA2156261B8FB331827145DE315B6EC1B3D8B67B3323F761EAF4C223BB214C4C 6B062D1B281F5041D068319F4911058376D8EFBA59884BA3318C5BC95684F281 E0591BC0D1B2A4592A137FF301610019B8AC46AE6E48BC091E888E4487688350 E9AD5074EE4848271CE4ACC38D8CBC8F3DB32813DDD5B341AF9A6601281ABA38 4A978B98483A63FCC458D0E3BCE6FD830E7E09B0DB987A6B63B74638FC9F21A5 8C68479E1A85225670D79CDDE5AC0B77F5A994CA700B5F0FF1F97FC63EFDE023 8135F04A9D20C31998B12AE06676C362141AAAA395CDEF0A49E0141D335965F2 FB4198499799CECCC8AA5D255264784CD30A3E8295888EFBC2060ADDD7BAC45A EEEECDFF7A47A88E69D84C9E572616C1AC69A34B5F0D0DE8EE4EDF9F4ADE0387 680924D8D5B73EF04EAD7F45977CA8AD73D4DD45DE1966A3B8251C0386164C35 5880DD2609C80E96D1AB861C9259748E98F6711D4E241A269ED51FF328344664 3AF9F18DCE671611DB2F5D3EA77EE734D2BED623F973E6840B8DAD1E2C3C2666 DD4DD1C1C9C622FAEAB9D3E54476B49A2A026565F10A95536B67FDFDA5E9E69D 8B247654FF9A4D74E77A5441E350724A552B878A13AFB446B4DDD357A86F0837 94F258DA75532811AF41958507DB2C1819547657ACD9D4E81A667B89B0EE8E23 AA9B8BE4A45B48119FE65DD884037E05CE097127774CDFE6091C7E6C362D27D1 15E0C7B74AA32B6BA491EAB95CBD5340142BCC0515D3CD47A2B2E345DC5B5444 036CB75A23D92ADE4098E4174598DFC1ADD846746F18277C7684E9491ABBE612 2C0A255A4421AAF6E0B683B39506B0CCB4BF861083E9040777323114E0A34E41 092F1D6877D7572B4F4EE3E358F3D89F1E9D68A95078ACD137FCEC5A01E7553D B07B4D31EE5CFFB3470B96E2F62DDB2BF9F30F6D55B9130F07F2B3DB2D8954C9 D7B6F0D1191D7CDB7255A78C964825ABDB02487418EDD30BA5C29E7FAA96492A 8E79842122EA72C7053655D26588FE06F91273810464769C921E5AAE15A75323 198B80144DD5D6E3E701EEE7404504E200E05C9FDF103ADED90F4950D79F3584 3E7B7AEC3F2F052EA689EC6D3F51DB5741750DE16716669C93166B0286872EB4 E4A78F 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMSY9 %!PS-AdobeFont-1.1: CMSY9 1.0 %%CreationDate: 1991 Aug 15 07:22:27 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.0) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMSY9) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.035 def /isFixedPitch false def end readonly def /FontName /CMSY9 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 110 /backslash put readonly def /FontBBox{-30 -958 1146 777}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052F09F9C8ADE9D907C058B87E9B6964 7D53359E51216774A4EAA1E2B58EC3176BD1184A633B951372B4198D4E8C5EF4 A213ACB58AA0A658908035BF2ED8531779838A960DFE2B27EA49C37156989C85 E21B3ABF72E39A89232CD9F4237FC80C9E64E8425AA3BEF7DED60B122A52922A 221A37D9A807DD01161779DDE7D31FF2B87F97C73D63EECDDA4C49501773468A 27D1663E0B62F461F6E40A5D6676D0037D33F24E2FAC2B0009AD3C8350CDF8CC 65BCA87979C36D14CB552E9A985E48BE4E88ECA16DF418749AF04FDD2B0E1380 D281BB2476BB45FF30946B247DFD7F57305FA87E50CA338121C71CDFDF927A9C 77FF14CB4A1D6D80356FB1171ED38C37702350497B44E42CE31DB2F493807DAA 15B887C671199A54C4C1294BC520F5538C15556BC43C9F62342B121C6DCD6C5F 491DA47FF360201EE21C08A781ED0589A6DF91B99FE118B9B29E4F068672E52F 1A06C514D91C4C937D4E642503392B1CD1BE8C2F499A1AD3753691F4D1DAB520 BDD769BBCDAF968237D9A46AD1899410D3594B3AF945E894F1DE5176A6E251CA 0F18B516FC05626A7304DB1E7B5BCF5A9E5EC8BE59C6BBC21B87F6789768C630 5758F0A7B847BBFDB156DDCE8089E499002240DFA847142E7361BBB5301D9021 E17CF2305E7BAA2F556CDF147EACBFCF444772DC14B954EC09BD666280B159BC 8E5C78FE11B8145EA7D6E7799B3F0E7486EA5808A32B6A4068041C23D9D0D8AD AB1CC078FA184EF3892F5BD9952F9B93ADA2CBC45985503FC7D967A94F374476 53F27028B241C5C7600951D452047B680F935C5A3EEBB8B2515F9C3675ADF0 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMSY5 %!PS-AdobeFont-1.1: CMSY5 1.0 %%CreationDate: 1991 Aug 15 07:21:16 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.0) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMSY5) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.035 def /isFixedPitch false def end readonly def /FontName /CMSY5 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 99 /floorright put dup 100 /ceilingleft put readonly def /FontBBox{21 -944 1448 791}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052F09F9C8ADE9D907C058B87E9B6964 7D53359E51216774A4EAA1E2B58EC3176BD1184A633B951372B4198D4E8C5EF4 A213ACB58AA0A658908035BF2ED8531779838A960DFE2B27EA49C37156989C85 E21B3ABF72E39A89232CD9F4237FC80C9E64E8425AA3BEF7DED60B122A52922A 221A37D9A807DD01161779DDE7D5FC1B2109839E5B52DFBAF552B11EFFB6A16C F03FB920C15AE724EFDF0CCBF00A838D34440FF9FED532F44036AD22561184C5 283722DDFA7285E62754372D716D704AC0E00B2F6AB67154241C7449AA047833 94CEDB08E8C92907FE72A0B05AE36A7B9226ACD6E7890A0B528FDDE84A950FC6 801DE75CF2E739E9121149CCB8B1C87A106822648D84A3D3FBF295EE6C4BF403 BBE9A1C1F6DAEDD1E642ACC486E609703D7612BFFD10C324F5DC710811F7F614 3691B400E3773987424C0D2B0D8A736873C6371DDB2442F05E018A2B5CA9A4AA 17AABB95D09E5890CFFFED5AC01495D89A53D3C9AD5A9C23D5050E53AD0EDBCB 74CFD3E2297008B9B01947831838A5B7BF29DF7D79A3F534A81ACBE9E424B488 9787119A37A367694753F76DB105736707A84BB23F4C3DAE1E0B78A3CC6A1106 C7773513D26BBC0F5430E65C267E5E6DE15CD7892809F70EA60A2E408BD51350 B50F4A68C7BCF87675D469BDE3B7659B333C16A75AACA615D5167C62645525A6 BFF13F92A1451C13650B0D2B0436242F29EDE4208039ED6C5CFEA7EFE27D553D 5A159E4F81F07C531EFB5276A46B78840437598568CD948FA43DD678B024DCF6 BEA8B9591B57D126861A0C94FDA0E007D08FD7D9C1EB19900E106C1CC23190F7 C2805A6772AEB2ACC12238F965C54541E05622BED8879846246919CFFED562B5 74FB409A25F97FAA02A98AB3289D40779FA7CBE47F35F6829741CDBDAC0D8230 C49DD2E702B2660E99871FD026B30697530DCE 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMSY7 %!PS-AdobeFont-1.1: CMSY7 1.0 %%CreationDate: 1991 Aug 15 07:21:52 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.0) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMSY7) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.035 def /isFixedPitch false def end readonly def /FontName /CMSY7 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 0 /minus put readonly def /FontBBox{-15 -951 1252 782}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052F09F9C8ADE9D907C058B87E9B6964 7D53359E51216774A4EAA1E2B58EC3176BD1184A633B951372B4198D4E8C5EF4 A213ACB58AA0A658908035BF2ED8531779838A960DFE2B27EA49C37156989C85 E21B3ABF72E39A89232CD9F4237FC80C9E64E8425AA3BEF7DED60B122A52922A 221A37D9A807DD01161779DDE7D251491EBF65A98C9FE2B1CF8D725A70281949 8F4AFFE638BBA6B12386C7F32BA350D62EA218D5B24EE612C2C20F43CD3BFD0D F02B185B692D7B27BEC7290EEFDCF92F95DDEB507068DE0B0B0351E3ECB8E443 E611BE0A41A1F8C89C3BC16B352C3443AB6F665EAC5E0CC4229DECFC58E15765 424C919C273E7FA240BE7B2E951AB789D127625BBCB7033E005050EB2E12B1C8 E5F3AD1F44A71957AD2CC53D917BFD09235601155886EE36D0C3DD6E7AA2EF9C C402C77FF1549E609A711FC3C211E64E8F263D60A57E9F2B47E3480B978AAF63 868AEA25DA3D5413467B76D2F02F8097D2841EDA6677731A6ACFEC0BABF1016A 089B2D24F47B9D66B677886B90AA787AD865B5F78EE434AA47B7B0F1244A4215 251FDCC670FD01A92226E2C667C2344298D001575BDF782D969D836ECA11E229 C7A17E28F70F9B17273FF243452DA885068A8BCB5165534F3996CBD8D97307DB 593D606C197AFC259E691C242F6E1E651575B6852AAD54567905E6F542DCA109 7F6DA24DC9112FBF7CE48B387953787B2BCB841873AED2DFA83339D39E14F4DD 3A51584527AC3A93630D121E2AE0C89D9C3F2FFA767743B1276BE1E648041010 0FD510F1A8 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMMI7 %!PS-AdobeFont-1.1: CMMI7 1.100 %%CreationDate: 1996 Jul 23 07:53:53 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.100) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMMI7) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.04 def /isFixedPitch false def end readonly def /FontName /CMMI7 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 105 /i put dup 106 /j put dup 107 /k put readonly def /FontBBox{0 -250 1171 750}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA0529731C99A784CCBE85B4993B2EEBDE 3B12D472B7CF54651EF21185116A69AB1096ED4BAD2F646635E019B6417CC77B 532F85D811C70D1429A19A5307EF63EB5C5E02C89FC6C20F6D9D89E7D91FE470 B72BEFDA23F5DF76BE05AF4CE93137A219ED8A04A9D7D6FDF37E6B7FCDE0D90B 986423E5960A5D9FBB4C956556E8DF90CBFAEC476FA36FD9A5C8175C9AF513FE D919C2DDD26BDC0D99398B9F4D03D77639DF1232A4D6233A9CAF69B151DFD33F C0962EAC6E3EBFB8AD256A3C654EAAF9A50C51BC6FA90B61B60401C235AFAB7B B078D20B4B8A6D7F0300CF694E6956FF9C29C84FCC5C9E8890AA56B1BC60E868 DA8488AC4435E6B5CE34EA88E904D5C978514D7E476BF8971D419363125D4811 4D886EDDDCDDA8A6B0FDA5CF0603EA9FA5D4393BEBB26E1AB11C2D74FFA6FEE3 FAFBC6F05B801C1C3276B11080F5023902B56593F3F6B1F37997038F36B9E3AB 76C2E97E1F492D27A8E99F3E947A47166D0D0D063E4E6A9B535DC9F1BED129C5 123775D5D68787A58C93009FD5DA55B19511B95168C83429BD2D878207C39770 012318EA7AA39900C97B9D3859E3D0B04750B8390BF1F1BC29DC22BCAD50ECC6 A3C633D0937A59E859E5185AF9F56704708D5F1C50F78F43DFAC43C4E7DC9413 44CEFE43279AFD3C167C942889A352F2FF806C2FF8B3EB4908D50778AA58CFFC 4D1B14597A06A994ED8414BBE8B26E74D49F6CF54176B7297CDA112A69518050 01337CBA5478EB984CDD22020DAED9CA8311C33FBCC84177F5CE870E709FC608 D28B3A7208EFF72988C136142CE79B4E9C7B3FE588E9824ABC6F04D141E589B3 914A73A42801305439862414F893D5B6C327A7EE2730DEDE6A1597B09C258F05 261BC634F64C9F8477CD51634BA648FC70F659C90DC042C0D6B68CD1DF36D615 24F362B85A58D65A8E6DFD583EF9A79A428F2390A0B5398EEB78F4B5A89D9AD2 A517E0361749554ABD6547072398FFDD863E40501C316F28FDDF8B550FF8D663 9843D0BEA42289F85BD844891DB42EC7C51229D33EE7E83B1290404C799B8E8C 889787CDC7AA8BEF7021B3C18A0A61A68CCEA80153A2EA222DFDF13E0E13DEA7 EE2F000EA5C508338A63A443BD2D56B7B58399495ACF0759FC1AE1A706BAD434 CEFD7EAB3DED5EF5B3BCD40401AD84671B951270297D363E20546BB77B7FF7BD 7694B87F0CCE3506ACC76BB779B67084ABEA9B6FC2B8FCC2AEE8AB59B110602F CE744CF53D2A1409AFD91F102985DC7C7535BDABA271FDFA5BC3EEFE42466446 82678B6FA9CE9DD4A4BC220E8035C70E2F10646BFE5497A1781322D12E85B7DF F614A90534F031D17F1991F1D8AB346471F8D4244FF4865497B401F1D8C2604F F61F609D0F91B6A4C17B1F9527A077A6340E34F4FDF7E010B3C6491403D430A3 7D9924EE69298515F3F0E29B5D22548AFA67CB714FD6CA0667D236E7CD95721F 27410FA552401697D4AE267B538ACC52C45CBA57E0414AB02C2A8CA8537C4397 894CC63810B8CDABFEDECBEBA6906CC285F9EF5840D8738A2F5C0824CF8B81F3 E7EE123659EBAE30D2C390C2AF67C014AFDA63DC83BB2F6E90A60E6225A25E37 385D7E260EEA30943FA55F1BA04CA5D395E8419F83F738812C00CBD554F168A1 2F8E77AAA41C005CAF9E8E6A2A94F6B7B26A19F3914B84F114DD0A0137D92790 F6029C8229EEF7D4C969EC38DDBA15E5A3474544498046077C22BE4382EB36DA B3613284B1E1E650535D0C13C9DA8D526423CB4911CC2DB2F9A5195F4EE39F7D 2360831984C62D959554D96DC255614A5383DC10894272B31F245005D9FA16E0 72201EEAB8794AF7977171FC82E071EB9F4B3DE68781D096210F44C735C1F373 F2C5614F5DF4487BAE683C476C9C098A769DA4DA87975A98E4892E754ED2E287 79EE96869F1D8319DD646B2D8F5F76B5F2A4916BF6C1266D1481247926998E20 6602D828E06ABD6777716E038859FB968EEC359591F300EAB716EDBC8598FE58 8BA0F80BDFF43F5D7A9FD7495A2737B82679FBA781E09B24DF3174FEE4A2A957 7BBD8730F752CEBFF1148B4EAD5F6F0AF28CC938CFB3005CF2D3BD1C31B35F34 88C0D3E375ACAA95B2685B9547259CD211FE38267181C36758953E64E211A557 56BE05AF71E62E27D76FC8F05B3F911A26440181640D98B5 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMMI10 %!PS-AdobeFont-1.1: CMMI10 1.100 %%CreationDate: 1996 Jul 23 07:53:57 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.100) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMMI10) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.04 def /isFixedPitch false def end readonly def /FontName /CMMI10 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 25 /pi put dup 60 /less put dup 62 /greater put dup 83 /S put dup 110 /n put readonly def /FontBBox{-32 -250 1048 750}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA0529731C99A784CCBE85B4993B2EEBDE 3B12D472B7CF54651EF21185116A69AB1096ED4BAD2F646635E019B6417CC77B 532F85D811C70D1429A19A5307EF63EB5C5E02C89FC6C20F6D9D89E7D91FE470 B72BEFDA23F5DF76BE05AF4CE93137A219ED8A04A9D7D6FDF37E6B7FCDE0D90B 986423E5960A5D9FBB4C956556E8DF90CBFAEC476FA36FD9A5C8175C9AF513FE D919C2DDD26BDC0D99398B9F4D03D5993DFC0930297866E1CD0A319B6B1FD958 9E394A533A081C36D456A09920001A3D2199583EB9B84B4DEE08E3D12939E321 990CD249827D9648574955F61BAAA11263A91B6C3D47A5190165B0C25ABF6D3E 6EC187E4B05182126BB0D0323D943170B795255260F9FD25F2248D04F45DFBFB DEF7FF8B19BFEF637B210018AE02572B389B3F76282BEB29CC301905D388C721 59616893E774413F48DE0B408BC66DCE3FE17CB9F84D205839D58014D6A88823 D9320AE93AF96D97A02C4D5A2BB2B8C7925C4578003959C46E3CE1A2F0EAC4BF 8B9B325E46435BDE60BC54D72BC8ACB5C0A34413AC87045DC7B84646A324B808 6FD8E34217213E131C3B1510415CE45420688ED9C1D27890EC68BD7C1235FAF9 1DAB3A369DD2FC3BE5CF9655C7B7EDA7361D7E05E5831B6B8E2EEC542A7B38EE 03BE4BAC6079D038ACB3C7C916279764547C2D51976BABA94BA9866D79F13909 95AA39B0F03103A07CBDF441B8C5669F729020AF284B7FF52A29C6255FCAACF1 74109050FBA2602E72593FBCBFC26E726EE4AEF97B7632BC4F5F353B5C67FED2 3EA752A4A57B8F7FEFF1D7341D895F0A3A0BE1D8E3391970457A967EFF84F6D8 47750B1145B8CC5BD96EE7AA99DDC9E06939E383BDA41175233D58AD263EBF19 AFC0E2F840512D321166547B306C592B8A01E1FA2564B9A26DAC14256414E4C8 42616728D918C74D13C349F4186EC7B9708B86467425A6FDB3A396562F7EE4D8 40B43621744CF8A23A6E532649B66C2A0002DD04F8F39618E4F572819DD34837 B5A08E643FDCA1505AF6A1FA3DDFD1FA758013CAED8ACDDBBB334D664DFF5B53 956017667271C1FD06DBA26AC7504FCD81979D968F25FBFE41415A19DB200E5A A16A4EE56C2109238728E81D132600DBF4F1CC05035CF813FBCD0AFFABC43952 6E6EA2E5DF0D20BE5E46858B712993A39CAD40F69549AA316B72FA5FC90E08DD 6E7AE893FA8FDCDD1C3898AF54C939C6211713CD74A973F4587FA0A5D9975F3D 811B547CA2B4F2E63B7165B505613AFAC72E84B7FE3C9010B18E66C44040C516 708C7C7215FA107B43349F8821EE43F0FED5F943ABE2B3E56AC8F05DA56B302A 8EAE71F174E5AE2A153C1F90D7D80B17A4E99FD0F78F041A7D91D939E799234A E19758401C1E6FE24A14B7C8FB65EB3C0AE43B231CE8707B816774DAAD6B41B4 626788E0E3AF5EC629FFB6C4E8A2D2184B77CF0ED9BBEE68D88509C5E303B1C9 77E141020CFF5DCF6709A7E75C1518013A1F48E3FE020D07012762FA504AA9F0 2B14EAE0592830B7B1D2CB587D2C48D9DFFC6FC121FA2878B02A5BD8AC2FEA53 BA33804EB84E08B2759E5CF668EF10110739B35B230377A35ED38F0C78AF4673 6299794F9ADE96DA0EC1D0C59FB4ECFEA34498C07235C47565788E5233244FAD 13C6197E092C870971B32C0693BEDD275CEF54E1F0AC4F9A2FE7A904DB2A33B5 F15164347137B2F76943C0B765EB4EB4602E17070BCBBE36F9E0B5D8ADA00C71 2D206CE3F4CA82BC1866E2B49430AB8FE31B69A6F3CF4CEDF775ACAB6876C8EE 5C127B20B43CAE64BA7B396D919293164B8DE9A0BE492FC4ED545840A7DA47F9 218E3944BD90893723768D093DD5A33396E3DB16EB7BF1D30E66D0A7152540EE 1346499141CC2FBACE38248DA47287CA7BCB384437BF34CA012C0CF01D2D74DB 9F2DBD0B54925E96664217F6F57AC8A5FF5971CF319D0DDFBE625CCDCD6F4A66 1B772CE576C7130D2965C8D069E6FFDA2C14433DE480B47CEDE42C6CEF3E010A E109FEE82A0B85C462F191DAEC36146E2F6CC174B5490D0EF24627D15B2F25F2 D23CFF5E24A5BC412FD07A2D505718F439578CF77EAB8F8FF7C29674093D0210 C521FB0A686756A8CD273461135F1DBB047789EC295A1BD87B94C1961AFB88AC C0B4987C78A68F3D89C76DA9F42E5A427DF8AD4D6A7649D4FC80BECE1C5F0005 60852D65595274D6F00B31E9667F050C40F7243B6E794F5050CA5ED84FF7FBDD 66F6DB8B97EB28F445932CFD321EC084ABE18BD7BF215EFDF55F5CE2B7EC4E48 4AC59B4D8A873D0EDE15C9E72D23E59F920B7AE315D172091FD1E122E0A88CB4 303CC1619A79EC16EAD9A52CF580BB6E5D70BFF510E71F44EC9842D0061EDAE7 965422ABC80ACA5D937E2E2859B5E76317BAAF35B60D9C66B64F0A03E0F96CE3 25DE8C75700121F0052D3E2DB4C71550E497E3BE8A49456AAB75171407E6D24B D6595803A84C65667274A4777D6E2E40190715A0FB8747713A3256D750F9E534 9D6BFACE2E74C58317E8326A 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMR10 %!PS-AdobeFont-1.1: CMR10 1.00B %%CreationDate: 1992 Feb 19 19:54:52 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.00B) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMR10) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def end readonly def /FontName /CMR10 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 48 /zero put readonly def /FontBBox{-251 -250 1009 969}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052A014267B7904EB3C0D3BD0B83D891 016CA6CA4B712ADEB258FAAB9A130EE605E61F77FC1B738ABC7C51CD46EF8171 9098D5FEE67660E69A7AB91B58F29A4D79E57022F783EB0FBBB6D4F4EC35014F D2DECBA99459A4C59DF0C6EBA150284454E707DC2100C15B76B4C19B84363758 469A6C558785B226332152109871A9883487DD7710949204DDCF837E6A8708B8 2BDBF16FBC7512FAA308A093FE5CF7158F1163BC1F3352E22A1452E73FECA8A4 87100FB1FFC4C8AF409B2067537220E605DA0852CA49839E1386AF9D7A1A455F D1F017CE45884D76EF2CB9BC5821FD25365DDEA6E45F332B5F68A44AD8A530F0 92A36FAC8D27F9087AFEEA2096F839A2BC4B937F24E080EF7C0F9374A18D565C 295A05210DB96A23175AC59A9BD0147A310EF49C551A417E0A22703F94FF7B75 409A5D417DA6730A69E310FA6A4229FC7E4F620B0FC4C63C50E99E179EB51E4C 4BC45217722F1E8E40F1E1428E792EAFE05C5A50D38C52114DFCD24D54027CBF 2512DD116F0463DE4052A7AD53B641A27E81E481947884CE35661B49153FA19E 0A2A860C7B61558671303DE6AE06A80E4E450E17067676E6BBB42A9A24ACBC3E B0CA7B7A3BFEA84FED39CCFB6D545BB2BCC49E5E16976407AB9D94556CD4F008 24EF579B6800B6DC3AAF840B3FC6822872368E3B4274DD06CA36AF8F6346C11B 43C772CC242F3B212C4BD7018D71A1A74C9A94ED0093A5FB6557F4E0751047AF D72098ECA301B8AE68110F983796E581F106144951DF5B750432A230FDA3B575 5A38B5E7972AABC12306A01A99FCF8189D71B8DBF49550BAEA9CF1B97CBFC7CC 96498ECC938B1A1710B670657DE923A659DB8757147B140A48067328E7E3F9C3 7D1888B284904301450CE0BC15EEEA00E48CCD6388F3FC3C8578EF9A20A0E06E 4F7ADDAF0E7D1E182D115BF1AD931977325AD391E72E2B13CC108E3726C11099 E2000623188AAAC9F3E233EB253BDD8B0A4759A66A113E066238B0086AC1B634 5ABFF90E4B5ED3FA69C22541981B2BFC9710AEF6B50A8BB53431C7B4D380D721 639E005D6B4688EE16BFF48443E7C9E5FB5BC5883E271CB0342893C0BBC0A879 B7220832FB50103F72F8B5D9997DB7BAA3BE20F6D6864F5F17DA35425B9A3637 8FCCBC334A452022CB427FA0904409E6D90AE76E35BF48CA0B77D5BCF8096B20 2A5E990C23B250161FC323A1C65751FB7DF8E86BC3BFB106B65532E1ABF2B429 09E21218026F15617A49024A956D242260028A76B6D80537566F7355D6B51F44 5C32540DE5D32B05D8B634A1FB597609B4DCEDD5938D08CFAF887989179C8005 8D76767E6C3033F388921630FE3F00CC5C1692574D57BC470CDC4F2D6AA2DAEC B79FC7D83A9FCA7DA32DA626968B8679F9BE2143E7F14682B3EC33B3156A79A1 CACB6FF79FD2534BF1902BA7E94F5588D85B0F74051DEFA8AEEA489D50942A05 DD739E291FB6A16061CC11E93B3142EB3C22101FC5875CDE9538045BAD19F5CB 6C5E0BF7D05154BD146E1EE828C5EBD8E6 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont %%BeginFont: CMSY10 %!PS-AdobeFont-1.1: CMSY10 1.0 %%CreationDate: 1991 Aug 15 07:20:57 % Copyright (C) 1997 American Mathematical Society. All Rights Reserved. 11 dict begin /FontInfo 7 dict dup begin /version (1.0) readonly def /Notice (Copyright (C) 1997 American Mathematical Society. All Rights Reserved) readonly def /FullName (CMSY10) readonly def /FamilyName (Computer Modern) readonly def /Weight (Medium) readonly def /ItalicAngle -14.035 def /isFixedPitch false def end readonly def /FontName /CMSY10 def /PaintType 0 def /FontType 1 def /FontMatrix [0.001 0 0 0.001 0 0] readonly def /Encoding 256 array 0 1 255 {1 index exch /.notdef put} for dup 6 /plusminus put dup 13 /circlecopyrt put dup 15 /bullet put dup 20 /lessequal put dup 49 /infinity put dup 102 /braceleft put dup 103 /braceright put dup 106 /bar put dup 110 /backslash put readonly def /FontBBox{-29 -960 1116 775}readonly def currentdict end currentfile eexec D9D66F633B846A97B686A97E45A3D0AA052F09F9C8ADE9D907C058B87E9B6964 7D53359E51216774A4EAA1E2B58EC3176BD1184A633B951372B4198D4E8C5EF4 A213ACB58AA0A658908035BF2ED8531779838A960DFE2B27EA49C37156989C85 E21B3ABF72E39A89232CD9F4237FC80C9E64E8425AA3BEF7DED60B122A52922A 221A37D9A807DD01161779DDE7D31FF2B87F97C73D63EECDDA4C49501773468A 27D1663E0B62F461F6E40A5D6676D1D12B51E641C1D4E8E2771864FC104F8CBF 5B78EC1D88228725F1C453A678F58A7E1B7BD7CA700717D288EB8DA1F57C4F09 0ABF1D42C5DDD0C384C7E22F8F8047BE1D4C1CC8E33368FB1AC82B4E96146730 DE3302B2E6B819CB6AE455B1AF3187FFE8071AA57EF8A6616B9CB7941D44EC7A 71A7BB3DF755178D7D2E4BB69859EFA4BBC30BD6BB1531133FD4D9438FF99F09 4ECC068A324D75B5F696B8688EEB2F17E5ED34CCD6D047A4E3806D000C199D7C 515DB70A8D4F6146FE068DC1E5DE8BC57034F6B6A67AB666E15104577F342F68 CDE6AB4EE8B00E12BF5F0D8EB5EDAC26DE611045BDAE79069D290F2A18804F99 D85590E85071433DB7584D9E91007121779FDD1F6D3196E758D62DACCF2DE16A 32C361BE397028863C92EEE0108E2396E0422E302188D7B35ACFDA46CF7250BA 5BC6330FEC85714703E5D2A453ABBF267ECA42918E5593BCE44E06C139ABD2F4 7C287E0F5920962E73611FC35F2295B1486B91C02E51373C1203F7B59B50B887 46CBFB590B6FBD0340C3E8085744E8B4D4021F27955E4449DF14A70BF2352B24 62FE9D0FAE62B0383762F88ED1EA0373AFC6D56DD8641C3D1F28D976312ED4D2 0F5026F28781BEDAB9FAFF2106D7FBADF137473910747D7D734E1ECFC64E6A77 75B91BB10CD31D8B907389739FA048E8EF8646B39C56C016CB2061EED3B33344 2EB17A6895793CFD55E40C183E4CF5B31B16F44C8C5F1C90E0A224A6B2D4FD2C 30D227C2B07BB810565B42D4975A301B266CF4D09896D4850DE7D0FD4EB135E2 97BCFF5777C59511252F18C2A2F72BAFE81E9117AAA6EE76A6E529F07407F8AE F087D9FC680EDCDBEF7A9D80F7F7334B7CF271D668C4B14EF68185C369A35B94 09281D6A5DDF7347DEEDB952CFEDFA82A023B071F6A31A6EBF392F0475A7D0E7 89D59617003C2DC539788D5E938A3972321BD02162DB23F72842B1EF10CF3725 8DDE74077AFC80559AE16C1E5362B2A778AD8AF02ACC7F7E09411CB4FD088BF3 0B1F513FC63A595185BF7D9B56090ADD1DAA44263410BA0767095423D475BCAE 90C96F868D9ED910321B78AAF0FAE54B89ED907076DBB24E8BCD8573EB5F55C5 5187D487A92F2C94563EB368D808D408C47E59690C168798726E57A95F3D8D60 5738CE6F2C6E1C12A566EEB2EF2696EC0CB465862C9A3D256A9306E68CAC3D63 ABF1B222A3F9C5EFE7650E60EDC9EE79F38EA7B1A16C90C6C03F940DE9A1B3EF B46FC8852820FF975778E460B1FF881AA73DE2BF8A26FEC5A953838603CE57CF B987BA8D4B763FDE9C0FAB4930B172654D6E926A2EF3E245936594F60FC3A485 8C7D39BE0CB59BEADFE54B53359E6D49B9AFE2EF8FDB7EAC9964200F20D5C704 2ADA07A9B13BA2C604384CFD717E13569FBCF1B928075494AFA72A7E2CA42716 7CE2948BE08DF0BC0A4DCC4304E2FD91D58A1B83FB64599783AF46F45E9FE9AF BC9372EAD9716B3EFEC08A32B623F454ACD56C5038DB289AC4EDB39FF717B81B EFEA59D3CCDB306595D068DD829581E8CB2898553CD4BF4AE89E623B3069DB41 F660AEA46F73CC97D67DDD3E29FABD1A0B8C1228AD9AAFEDE69525B09212EAF8 F2644165676472A1F1FA1BD3B7489F87A5F751C9BF2CC75583A32FFD13018231 369A84854ED95D6D9E62EC93EDBA3B5C71B22CE997BBEDF6B75201D448F24F37 E65DF72F51DE3E272854B14C1A0A31F53D54A98F60D282D00697018CC292562A F25D03EA77828A38119E50803B9C2655A765F8669FF70601E0FDDECF61AF8541 30395681B8EA5E3293D4AAC76A8AA9110C5B89D1D5BF40ACD799ABF128FE677D ABED92446EE5EBD85BF661E348B3033CE808B6130A699AE30A82EC09270FAB36 95DDF3B79624276AFEAE82D8B6897BFC0C4E8CFD1169B777300E3B08726E6DDC E28503A2928F8FFCAE767F6DF56A74F6AB1521B3F2D08D82D0753AECE4EBB12F 2395AEE3DCC62E395C62CB660C20E0F09B47CB3F5ABA04FFE5C706203421B18C 22B6C8FE963D659FE06F48BEEBB233FF76F1A87E8D5C59D9FDB07E0B636836EA 67FFCCD2CC9E730DDEA08CA1EFF9154DAA0388357AFAF5527D69171142FD11E8 087C1766523F1BAEDE374A06C5B4B2AE0BC57BBD08B4211FC54EB11FE9ADAE92 667E92F354A2F614E6E7B614FD34E6FC786D460FC3BB2E9BFF4CE99D213836C6 BB4954C1E91B22505CACC1AF01F01A29 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000 cleartomark %%EndFont TeXDict begin 40258431 52099146 1000 600 600 (paper-letter/lib.dvi) @start /Fa 134[42 5[42 28 1[46 6[18 46 4[42 46 46 20[46 4[65 71[{TeXBase1Encoding ReEncodeFont}11 83.022 /Helvetica-Oblique rf /Fb 134[60 4[33 60 40 1[66 66 66 4[27 66 66 1[66 1[60 66 66 19[100 66 4[93 73 70[{TeXBase1Encoding ReEncodeFont}18 119.552 /Helvetica-Oblique rf /Fc 131[72 124[{ TeXBase1Encoding ReEncodeFont}1 119.552 /Courier-Bold rf /Fd 134[33 33 2[37 22 26 2[37 33 1[55 18 2[18 1[33 22 29 54[17 22 45[{TeXBase1Encoding ReEncodeFont}15 66.4176 /Times-Bold rf /Fe 134[35 35 4[35 35 1[35 6[35 2[35 35 54[35 46[{TeXBase1Encoding ReEncodeFont}9 58.1154 /Courier rf /Ff 138[32 16 29 19 1[32 32 2[13 2[13 32 32 1[32 1[29 32 32 38[16 10[16 16 19 45[{TeXBase1Encoding ReEncodeFont}18 58.1154 /Helvetica rf /Fg 205[33 50[{}1 58.1154 /CMR7 rf /Fh 140[83 34[88 80[{}2 83.022 /CMEX10 rf /Fi 167[58 9[58 4[27 73[{TeXBase1Encoding ReEncodeFont}3 79.701 /Times-Roman rf /Fj 133[53 9[66 6[33 1[60 4[66 47[60 50[{TeXBase1Encoding ReEncodeFont}6 119.552 /Times-Bold rf /Fk 145[38 110[{}1 74.7198 /CMSY9 rf /Fl 167[69 4[53 4[69 4[32 5[64 1[69 65[{TeXBase1Encoding ReEncodeFont}6 95.6413 /Times-Roman rf /Fm 133[60 1[60 60 60 60 60 60 60 60 60 60 60 60 60 2[60 60 60 60 60 60 60 60 60 1[60 11[60 4[60 60 6[60 4[60 8[60 9[60 4[60 60 40[{ TeXBase1Encoding ReEncodeFont}33 99.6264 /Courier rf /Fn 134[50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 1[50 50 1[50 50 50 50 50 50 1[50 4[50 50 1[50 2[50 50 50 1[50 50 50 50 50 50 1[50 50 50 50 50 50 50 50 50 2[50 50 50 4[50 3[50 50 50 50 1[50 50 1[50 1[50 50 50 39[{ TeXBase1Encoding ReEncodeFont}59 83.022 /Courier-Oblique rf /Fo 134[37 42 55 1[46 23 32 32 1[42 42 46 65 23 2[23 46 42 28 37 42 37 42 42 16[51 12[55 19[23 21 43[46 2[{ TeXBase1Encoding ReEncodeFont}26 83.022 /Times-BoldItalic rf /Fp 155[28 28 99[{}2 41.511 /CMSY5 rf /Fq 176[38 8[30 32 69[{TeXBase1Encoding ReEncodeFont}3 53.134 /Times-Roman rf /Fr 255[52{}1 58.1154 /CMSY7 rf /Fs 148[35 27 23 105[{}3 58.1154 /CMMI7 rf /Ft 145[50 26[51 20[65 1[65 34[47 25[{}5 83.022 /CMMI10 rf /Fu 207[42 48[{}1 83.022 /CMR10 rf /Fv 104[100 55 27[50 50 50 72 50 55 28 50 33 55 55 55 55 83 22 50 22 22 55 55 28 55 55 50 55 55 6[61 1[66 94 66 72 61 66 72 78 66 78 72 83 55 1[50 28 72 78 61 66 72 72 66 66 1[55 4[28 55 55 55 55 55 55 55 55 55 55 28 28 33 28 2[33 33 37[50 2[{TeXBase1Encoding ReEncodeFont}71 99.6264 /Helvetica rf /Fw 134[29 3[33 18 1[26 2[33 33 1[18 2[18 33 33 18 29 1[29 1[33 9[55 4[41 1[41 2[55 77[{ TeXBase1Encoding ReEncodeFont}18 66.4176 /Times-Italic rf /Fx 133[72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 72 1[72 6[72 72 72 72 72 72 72 72 72 72 72 72 72 2[72 72 72 72 72 72 72 72 72 8[72 1[72 72 72 72 72 3[72 4[72 72 40[{TeXBase1Encoding ReEncodeFont} 58 119.552 /Courier rf /Fy 134[37 37 1[37 1[21 29 25 1[37 37 37 58 3[21 37 1[25 33 37 33 1[33 46[37 37 2[19 4[25 25 40[{TeXBase1Encoding ReEncodeFont}22 74.7198 /Times-Roman rf /Fz 133[40 40 40 1[40 40 40 40 40 40 40 40 40 40 40 40 1[40 40 40 40 40 40 40 40 40 1[40 1[40 1[40 40 4[40 40 40 2[40 1[40 40 3[40 2[40 40 3[40 14[40 40 40 1[40 1[40 2[40 40 2[40 37[{TeXBase1Encoding ReEncodeFont}46 66.4176 /Courier rf /FA 103[45 15[45 10[45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 1[45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 33[{ TeXBase1Encoding ReEncodeFont}94 74.7198 /Courier rf /FB 190[36 7[25 25 25 25 25 25 25 25 25 25 48[{ TeXBase1Encoding ReEncodeFont}11 49.8132 /Times-Roman rf /FC 162[40 1[40 5[86 85[{TeXBase1Encoding ReEncodeFont}3 119.552 /Times-Roman rf /FD 119[50 10[50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 1[50 1[50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 1[50 50 50 50 1[50 50 50 50 50 50 50 50 50 50 50 1[50 50 50 50 50 50 50 50 1[50 50 50 50 50 33[{TeXBase1Encoding ReEncodeFont} 88 83.022 /Courier-Bold rf /FE 104[120 66 1[40 40 24[60 60 60 86 60 66 33 60 40 66 66 66 66 100 27 60 27 27 66 66 33 66 66 60 66 66 6[73 80 80 113 80 86 73 80 86 93 80 93 86 100 66 80 60 33 86 93 73 80 86 86 80 80 1[66 4[33 66 66 66 66 66 66 66 66 66 66 33 33 40 33 70 1[40 40 27 35[60 60 2[{TeXBase1Encoding ReEncodeFont}78 119.552 /Helvetica rf /FF 190[42 7[29 29 29 29 29 29 29 29 29 29 48[{TeXBase1Encoding ReEncodeFont}11 58.1154 /Times-Roman rf /FG 166[80 80 113 80 86 73 80 86 2[93 86 1[73 2[33 86 93 73 80 1[86 86 86 65[{TeXBase1Encoding ReEncodeFont}19 119.552 /Helvetica-Bold rf /FH 71[22 32[66 2[29 29 24[29 33 33 48 33 33 18 26 22 33 33 33 33 52 18 33 18 18 33 33 22 29 33 29 33 29 22 6[48 48 63 1[48 41 37 44 1[37 48 48 59 41 1[26 22 48 48 37 41 48 44 44 48 5[18 18 33 33 1[33 33 33 33 33 33 33 18 17 22 17 2[22 22 22 1[55 3[22 29[37 37 2[{TeXBase1Encoding ReEncodeFont}75 66.4176 /Times-Roman rf /FI 104[83 46 27[42 42 42 60 42 46 23 42 28 46 46 46 46 69 18 42 18 18 46 46 23 46 46 42 46 46 6[51 1[55 78 55 60 51 55 60 65 55 65 60 69 46 55 42 23 60 65 51 55 60 60 55 55 1[46 4[23 46 46 46 46 46 46 46 46 46 46 23 23 28 23 48 32 28 28 18 35[42 42 2[{ TeXBase1Encoding ReEncodeFont}76 83.022 /Helvetica rf /FJ 103[50 15[50 10[50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 1[50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 33[{TeXBase1Encoding ReEncodeFont}94 83.022 /Courier rf /FK 64[42 29[32 12[46 46 24[32 37 37 55 37 42 23 32 32 42 42 42 42 60 23 37 23 23 42 42 23 37 42 37 42 42 3[32 1[32 46 1[51 69 51 60 46 42 51 60 51 60 55 69 46 55 37 28 60 60 51 51 60 55 51 51 3[56 2[28 42 42 1[42 42 42 42 42 42 42 23 21 28 21 1[42 28 28 28 35[42 42 2[{TeXBase1Encoding ReEncodeFont}78 83.022 /Times-Italic rf /FL 80[28 26[42 42 24[37 42 42 60 42 46 28 32 37 46 46 42 46 69 23 46 28 23 46 42 28 37 46 37 46 42 28 5[55 60 60 83 60 60 55 46 60 65 51 65 60 78 55 65 42 32 65 65 51 55 60 60 55 60 1[42 1[47 2[28 42 42 42 42 42 42 42 42 42 42 23 21 28 21 2[28 28 28 5[28 30[46 2[{TeXBase1Encoding ReEncodeFont}78 83.022 /Times-Bold rf /FM 145[42 3[23 2[42 42 52[83 28[65 4[42 1[83 6[65 6[{}9 83.022 /CMSY10 rf /FN 64[37 6[28 3[28 11[28 6[28 8[28 83 42 1[37 37 10[28 13[37 42 42 60 42 42 23 32 28 42 42 42 42 65 23 42 23 23 42 42 28 37 42 37 42 37 28 2[28 1[28 51 60 60 78 60 60 51 46 55 60 46 60 60 74 51 60 32 28 60 60 46 51 60 55 55 60 76 37 1[47 1[23 23 42 42 42 42 42 42 42 42 42 42 23 21 28 21 47 42 28 28 28 65 69 42 42 1[28 29[46 46 2[{TeXBase1Encoding ReEncodeFont} 97 83.022 /Times-Roman rf /FO 103[25 29[37 37 37 54 37 42 21 37 25 42 42 42 42 62 17 37 17 17 42 42 21 42 42 37 42 42 3[21 1[21 1[50 50 71 50 54 46 50 54 58 50 58 54 62 42 1[37 21 54 58 46 50 54 54 50 50 76 42 1[44 2[21 42 42 42 42 42 42 42 42 42 42 21 21 25 2[29 4[66 42 42 31[37 37 2[{TeXBase1Encoding ReEncodeFont}76 74.7198 /Helvetica rf /FP 134[50 50 72 1[55 33 1[44 2[50 55 4[28 55 50 33 44 55 2[50 13[55 2[61 9[61 70[{TeXBase1Encoding ReEncodeFont} 18 99.6264 /Times-Bold rf /FQ 139[28 1[33 4[78 28 2[28 50 2[44 1[44 50 44 11[72 15[61 72 9[28 50 50 5[50 50 50 3[25 44[{TeXBase1Encoding ReEncodeFont}20 99.6264 /Times-Roman rf /FR 137[72 80 40 72 48 2[80 80 120 1[72 1[32 3[80 80 2[80 14[104 5[80 1[72 2[112 88 1[104 21[40 1[40 44[{TeXBase1Encoding ReEncodeFont}21 143.462 /Helvetica rf /FS 140[72 6[32 6[80 3[80 14[104 28[80 1[80 80 3[40 46[{TeXBase1Encoding ReEncodeFont}9 143.462 /Helvetica-Oblique rf /FT 133[103 103 103 149 103 115 57 103 69 1[115 115 115 172 46 103 46 46 115 115 57 115 115 103 115 115 8[138 195 1[149 126 138 149 1[138 161 149 172 115 2[57 149 161 126 138 149 149 138 138 19[69 42[103 2[{ TeXBase1Encoding ReEncodeFont}47 206.559 /Helvetica rf end %%EndProlog %%BeginSetup %%Feature: *Resolution 600dpi TeXDict begin %%BeginPaperSize: Letter /setpagedevice where { pop << /PageSize [612 792] >> setpagedevice } { /letter where { pop letter } if } ifelse %%EndPaperSize end %%EndSetup %%Page: 1 1 TeXDict begin 1 0 bop 0 83 3901 9 v 1560 446 a FT(Python)58 b(Libr)n(ar)6 b(y)56 b(Ref)-6 b(erence)3015 676 y FS(Release)38 b(2.5.3)2684 1852 y FR(Guido)g(v)l(an)i(Rossum)2365 2035 y(F)-6 b(red)39 b(L.)g(Dr)o(ak)m(e)n(,)f(Jr)-7 b(.,)39 b(editor)3044 4091 y FQ(19th)24 b(December)l(,)h(2008)2676 5201 y FP(Python)g(Softwar)n(e)h(F)n(oundation)3019 5317 y FQ(Email:)k FO(docs@p)n(ython.org)p eop end %%Page: 2 2 TeXDict begin 2 1 bop 0 83 a FN(Cop)o(yright)380 80 y(c)357 83 y FM(\015)20 b FN(2001-2008)d(Python)i(Softw)o(are)h(F)o(oundation.) i(All)f(rights)f(reserv)o(ed.)0 230 y(Cop)o(yright)380 227 y(c)357 230 y FM(\015)g FN(2000)f(BeOpen.com.)24 b(All)c(rights)g(reserv)o(ed.)0 377 y(Cop)o(yright)380 374 y(c)357 377 y FM(\015)g FN(1995-2000)d(Corporation)h(for)h (National)h(Research)g(Initiati)n(v)o(es.)k(All)d(rights)f(reserv)o (ed.)0 524 y(Cop)o(yright)380 521 y(c)357 524 y FM(\015)g FN(1991-1995)d(Stichting)j(Mathematisch)f(Centrum.)24 b(All)d(rights)f(reserv)o(ed.)0 671 y(See)h(the)f(end)f(of)h(this)h (document)d(for)i(complete)f(license)h(and)g(permissions)f (information.)p eop end %%Page: 1 3 TeXDict begin 1 2 bop 1796 1914 a FL(Abstract)0 2144 y FN(Python)20 b(is)i(an)g(e)o(xtensible,)e(interpreted,)f (object-oriented)g(programming)f(language.)26 b(It)c(supports)e(a)i (wide)f(range)f(of)h(applications,)0 2244 y(from)e(simple)h(te)o(xt)g (processing)f(scripts)i(to)f(interacti)n(v)o(e)f(W)-7 b(eb)21 b(bro)n(wsers.)0 2391 y(While)26 b(the)g FK(Python)f(Refer)m (ence)h(Manual)e FN(describes)i(the)g(e)o(xact)f(syntax)h(and)f (semantics)h(of)g(the)g(language,)f(it)i(does)f(not)f(describe)0 2490 y(the)i(standard)e(library)h(that)h(is)h(distrib)n(uted)e(with)h (the)f(language,)h(and)f(which)g(greatly)g(enhances)g(its)i(immediate)d (usability)-5 b(.)44 b(This)0 2590 y(library)20 b(contains)g(b)n (uilt-in)h(modules)f(\(written)g(in)h(C\))h(that)f(pro)o(vide)e(access) j(to)f(system)h(functionality)c(such)j(as)h(\002le)g(I/O)f(that)g(w)o (ould)0 2690 y(otherwise)28 b(be)h(inaccessible)f(to)h(Python)e (programmers,)h(as)h(well)g(as)h(modules)d(written)i(in)g(Python)e (that)i(pro)o(vide)d(standardized)0 2789 y(solutions)c(for)g(man)o(y)f (problems)h(that)g(occur)g(in)g(e)n(v)o(eryday)f(programming.)28 b(Some)22 b(of)h(these)g(modules)e(are)i(e)o(xplicitly)e(designed)g(to) 0 2889 y(encourage)d(and)i(enhance)e(the)i(portability)f(of)h(Python)f (programs.)0 3036 y(This)j(library)f(reference)g(manual)g(documents)f (Python')-5 b(s)21 b(standard)g(library)-5 b(,)21 b(as)i(well)f(as)h (man)o(y)e(optional)g(library)f(modules)h(\(which)0 3135 y(may)i(or)g(may)g(not)f(be)i(a)n(v)n(ailable,)f(depending)e(on)i (whether)f(the)h(underlying)e(platform)g(supports)i(them)f(and)h(on)g (the)g(con\002guration)0 3235 y(choices)j(made)g(at)h(compile)f (time\).)43 b(It)27 b(also)g(documents)e(the)h(standard)g(types)g(of)g (the)h(language)e(and)h(its)h(b)n(uilt-in)f(functions)f(and)0 3335 y(e)o(xceptions,)18 b(man)o(y)h(of)h(which)g(are)g(not)g(or)g (incompletely)e(documented)g(in)i(the)g(Reference)f(Manual.)0 3482 y(This)26 b(manual)f(assumes)i(basic)f(kno)n(wledge)e(about)h(the) h(Python)f(language.)41 b(F)o(or)25 b(an)h(informal)f(introduction)f (to)i(Python,)g(see)h(the)0 3581 y FK(Python)h(T)-5 b(utorial)p FN(;)34 b(the)29 b FK(Python)e(Refer)m(ence)i(Manual)f FN(remains)g(the)h(highest)g(authority)e(on)i(syntactic)f(and)h (semantic)g(questions.)0 3681 y(Finally)-5 b(,)19 b(the)i(manual)e (entitled)h FK(Extending)e(and)i(Embedding)e(the)i(Python)f(Interpr)m (eter)h FN(describes)g(ho)n(w)f(to)i(add)e(ne)n(w)h(e)o(xtensions)f(to) 0 3780 y(Python)g(and)h(ho)n(w)f(to)i(embed)e(it)i(in)f(other)f (applications.)p eop end %%Page: 2 4 TeXDict begin 2 3 bop eop end %%Page: 1 5 TeXDict begin 1 4 bop 2764 747 a FT(CONTENTS)0 1594 y FL(1)83 b(Intr)o(oduction)3281 b(1)0 1777 y(2)83 b(Built-in)21 b(Objects)3167 b(3)125 1876 y FN(2.1)110 b(Built-in)21 b(Functions)68 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)143 b(3)125 1976 y(2.2)110 b(Non-essential)20 b(Built-in)g(Functions)89 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)102 b(16)125 2076 y(2.3)110 b(Built-in)21 b(Exceptions)26 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(17)125 2175 y(2.4)110 b(Built-in)21 b(Constants)69 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)102 b(22)0 2358 y FL(3)83 b(Built-in)21 b(T)-6 b(ypes)3193 b(23)125 2457 y FN(3.1)110 b(T)m(ruth)20 b(V)-9 b(alue)20 b(T)-6 b(esting)20 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)102 b(23)125 2557 y(3.2)110 b(Boolean)20 b(Operations)f(\227)i FJ(and)p FN(,)f FJ(or)p FN(,)g FJ(not)93 b FN(.)41 b(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(23)125 2657 y(3.3)110 b(Comparisons)50 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)102 b(24)125 2756 y(3.4)110 b(Numeric)20 b(T)-7 b(ypes)20 b(\227)g FJ(int)p FN(,)g FJ(float)p FN(,)g FJ(long)p FN(,)g FJ(complex)93 b FN(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 102 b(25)125 2856 y(3.5)110 b(Iterator)19 b(T)-7 b(ypes)90 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(26)125 2956 y(3.6)110 b(Sequence)19 b(T)-7 b(ypes)20 b(\227)h FJ(str)p FN(,)f FJ(unicode)p FN(,)f FJ(list)p FN(,)h FJ(tuple)p FN(,)g FJ(buffer)p FN(,)f FJ(xrange)70 b FN(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(27)125 3055 y(3.7)110 b(Set)21 b(T)-7 b(ypes)20 b(\227)h FJ(set)p FN(,)f FJ(frozenset)86 b FN(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(36)125 3155 y(3.8)110 b(Mapping)19 b(T)-7 b(ypes)20 b(\227)h FJ(dict)84 b FN(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(37)125 3254 y(3.9)110 b(File)21 b(Objects)86 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)102 b(39)125 3354 y(3.10)68 b(Conte)o(xt)20 b(Manager)f(T)-7 b(ypes)68 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(42)125 3454 y(3.11)68 b(Other)20 b(Built-in)g(T)-7 b(ypes)53 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(42)125 3553 y(3.12)68 b(Special)21 b(Attrib)n(utes)80 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(45)0 3736 y FL(4)83 b(String)20 b(Ser)o(vices)3160 b(47)125 3836 y FN(4.1)110 b FJ(string)20 b FN(\227)h(Common)e(string)h(operations)50 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(47)125 3935 y(4.2)110 b FJ(re)21 b FN(\227)g(Re)o(gular)e(e)o (xpression)f(operations)71 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)102 b(52)125 4035 y(4.3)110 b FJ(struct)20 b FN(\227)h(Interpret)d(strings)j(as)f(pack)o(ed)g(binary) e(data)47 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(62)125 4134 y(4.4)110 b FJ(difflib)20 b FN(\227)h(Helpers)f(for)f (computing)f(deltas)46 b(.)c(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)102 b(65)125 4234 y(4.5)110 b FJ(StringIO)20 b FN(\227)g(Read)h(and)e(write)i(strings)f(as)h(\002les)32 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(74)125 4334 y(4.6)110 b FJ(cStringIO)19 b FN(\227)i(F)o(aster)g(v)o (ersion)e(of)g FJ(StringIO)62 b FN(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)102 b(75)125 4433 y(4.7)110 b FJ(textwrap)20 b FN(\227)g(T)-6 b(e)o(xt)20 b(wrapping)f(and)g(\002lling)61 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(75)125 4533 y(4.8)110 b FJ(codecs)20 b FN(\227)h(Codec)f(re)o(gistry) f(and)g(base)i(classes)80 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)102 b(77)125 4633 y(4.9)110 b FJ(unicodedata)19 b FN(\227)i(Unicode)e(Database)82 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(90)125 4732 y(4.10)68 b FJ(stringprep)19 b FN(\227)i(Internet)e(String)h(Preparation)38 b(.)j(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)102 b(91)125 4832 y(4.11)68 b FJ(fpformat)20 b FN(\227)g(Floating)g(point)f (con)m(v)o(ersions)79 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)102 b(93)0 5015 y FL(5)83 b(Data)19 b(T)-6 b(ypes)3295 b(95)125 5114 y FN(5.1)110 b FJ(datetime)20 b FN(\227)g(Basic)i(date)e (and)f(time)i(types)51 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)102 b(95)125 5214 y(5.2)110 b FJ(calendar)20 b FN(\227)g(General)g(calendar)n(-related)e(functions)64 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(113)125 5313 y(5.3)110 b FJ(collections)19 b FN(\227)i(High-performance)16 b(container)i(datatypes)34 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(116)p 0 5549 3901 4 v 3882 5649 a FI(i)p eop end %%Page: 2 6 TeXDict begin 2 5 bop 125 83 a FN(5.4)110 b FJ(heapq)20 b FN(\227)h(Heap)f(queue)f(algorithm)61 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(121)125 183 y(5.5)110 b FJ(bisect)20 b FN(\227)h(Array)e(bisection)h(algorithm) 78 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(124)125 282 y(5.6)110 b FJ(array)20 b FN(\227)h(Ef)n(\002cient)f (arrays)f(of)h(numeric)f(v)n(alues)53 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(125)125 382 y(5.7)110 b FJ(sets)20 b FN(\227)h(Unordered)d(collections)h(of)h(unique)f(elements)k(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(128)125 482 y(5.8)110 b FJ(sched)20 b FN(\227)h(Ev)o(ent)e(scheduler)81 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(131)125 581 y(5.9)110 b FJ(mutex)20 b FN(\227)h(Mutual)f(e)o(xclusion)e(support)77 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(132)125 681 y(5.10)68 b FJ(Queue)20 b FN(\227)h(A)g(synchronized)c (queue)i(class)64 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(133)125 780 y(5.11)68 b FJ(weakref)20 b FN(\227)h(W)-7 b(eak)20 b(references)27 b(.)41 b(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(134)125 880 y(5.12)68 b FJ(UserDict)20 b FN(\227)g(Class)i(wrapper)d (for)g(dictionary)g(objects)70 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(138)125 980 y(5.13)68 b FJ(UserList)20 b FN(\227)g(Class)i(wrapper)d (for)g(list)j(objects)56 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(139)125 1079 y(5.14)68 b FJ(UserString)19 b FN(\227)i(Class)h(wrapper)c(for)i(string)g(objects)56 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(140)125 1179 y(5.15)68 b FJ(types)20 b FN(\227)h(Names)f(for)g(b)n(uilt-in)f (types)55 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(140)125 1279 y(5.16)68 b FJ(new)21 b FN(\227)f(Creation)g(of)g(runtime)f(internal)g(objects)26 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(143)125 1378 y(5.17)68 b FJ(copy)20 b FN(\227)h(Shallo)n(w)f(and)g (deep)f(cop)o(y)g(operations)24 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)60 b(143)125 1478 y(5.18)68 b FJ(pprint)20 b FN(\227)h(Data)f(pretty)g(printer)74 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(144)125 1577 y(5.19)68 b FJ(repr)20 b FN(\227)h(Alternate)f FJ(repr\(\))f FN(implementation)52 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(147)0 1760 y FL(6)83 b(Numeric)20 b(and)h(Mathematical)e (Modules)2348 b(149)125 1860 y FN(6.1)110 b FJ(math)20 b FN(\227)h(Mathematical)e(functions)63 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(149)125 1959 y(6.2)110 b FJ(cmath)20 b FN(\227)h(Mathematical)e(functions)g (for)h(comple)o(x)e(numbers)30 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(151)125 2059 y(6.3)110 b FJ(decimal)20 b FN(\227)h(Decimal)f (\003oating)f(point)h(arithmetic)31 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(153)125 2159 y(6.4)110 b FJ(random)20 b FN(\227)h(Generate)e(pseudo-random)d(numbers)42 b(.)f(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(169)125 2258 y(6.5)110 b FJ(itertools)19 b FN(\227)i(Functions)f(creating)f(iterators)g(for)h (ef)n(\002cient)g(looping)67 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(172)125 2358 y(6.6)110 b FJ(functools)19 b FN(\227)i(Higher)f(order)e(functions)h (and)h(operations)e(on)i(callable)g(objects.)48 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(181)125 2457 y(6.7)110 b FJ(operator)20 b FN(\227)g(Standard)f (operators)g(as)i(functions.)f(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(182)0 2640 y FL(7)83 b(Inter)o(net)20 b(Data)f(Handling) 2816 b(189)125 2740 y FN(7.1)110 b FJ(email)20 b FN(\227)h(An)f(email)g (and)g(MIME)g(handling)e(package)62 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)60 b(189)125 2839 y(7.2)110 b FJ(mailcap)20 b FN(\227)h(Mailcap)e(\002le)i(handling.)30 b(.)42 b(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(218)125 2939 y(7.3)110 b FJ(mailbox)20 b FN(\227)h(Manipulate)e(mailbox)o(es)f (in)j(v)n(arious)e(formats)k(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(218)125 3039 y(7.4)110 b FJ(mhlib)20 b FN(\227)h(Access)g(to)f(MH)h (mailbox)o(es)k(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(237)125 3138 y(7.5)110 b FJ(mimetools)19 b FN(\227)i(T)-7 b(ools)20 b(for)g(parsing)f(MIME)h(messages)78 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(239)125 3238 y(7.6)110 b FJ(mimetypes)19 b FN(\227)i(Map)f(\002lenames)g(to)g(MIME)g (types)80 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(241)125 3337 y(7.7)110 b FJ(MimeWriter)19 b FN(\227)i(Generic)f(MIME) f(\002le)i(writer)70 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(243)125 3437 y(7.8)110 b FJ(mimify)20 b FN(\227)h(MIME)f (processing)e(of)i(mail)h(messages)54 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(244)125 3537 y(7.9)110 b FJ(multifile)19 b FN(\227)i(Support)e(for)g(\002les)j(containing)c(distinct)i(parts)53 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(245)125 3636 y(7.10)68 b FJ(rfc822)20 b FN(\227)h(P)o(arse)f(RFC)i(2822)d(mail)h(headers)75 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(247)125 3736 y(7.11)68 b FJ(base64)20 b FN(\227)h(RFC)g(3548:)j (Base16,)c(Base32,)g(Base64)g(Data)h(Encodings)50 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(251)125 3836 y(7.12)68 b FJ(binhex)20 b FN(\227)h(Encode)e(and) g(decode)g(binhe)o(x4)f(\002les)34 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(253)125 3935 y(7.13)68 b FJ(binascii)20 b FN(\227)g(Con)m(v)o(ert)f(between)g(binary)g(and)j FH(A)t(S)t(C)t(I)t(I)67 b FN(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(253)125 4035 y(7.14)68 b FJ(quopri)20 b FN(\227)h(Encode)e(and)g (decode)g(MIME)h(quoted-printable)c(data)64 b(.)41 b(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(255)125 4134 y(7.15)68 b FJ(uu)21 b FN(\227)g(Encode)d(and)i(decode)f (uuencode)f(\002les)56 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(256)0 4317 y FL(8)83 b(Structur)o(ed)19 b(Markup)i(Pr)o(ocessing)f(T)-8 b(ools)2344 b(257)125 4417 y FN(8.1)110 b FJ(HTMLParser)19 b FN(\227)i(Simple)f(HTML)g(and)g (XHTML)g(parser)64 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(257)125 4516 y(8.2)110 b FJ(sgmllib)20 b FN(\227)h(Simple)f(SGML)g (parser)52 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(259)125 4616 y(8.3)110 b FJ(htmllib)20 b FN(\227)h(A)f(parser)g(for)f(HTML)h(documents)36 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(262)125 4716 y(8.4)110 b FJ(htmlentitydefs)19 b FN(\227)h(De\002nitions)g(of)g (HTML)g(general)f(entities)46 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(264)125 4815 y(8.5)110 b FJ(xml.parsers.expat)18 b FN(\227)j(F)o(ast)g(XML)f (parsing)f(using)h(Expat)51 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(264)125 4915 y(8.6)110 b FJ(xml.dom)20 b FN(\227)h(The)e(Document)g(Object)h (Model)g(API)69 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(272)125 5015 y(8.7)110 b FJ(xml.dom.minidom)18 b FN(\227)j (Lightweight)e(DOM)h(implementation)72 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(282)125 5114 y(8.8)110 b FJ(xml.dom.pulldom)18 b FN(\227)j(Support)e (for)g(b)n(uilding)g(partial)h(DOM)h(trees)60 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(287)125 5214 y(8.9)110 b FJ(xml.sax)20 b FN(\227)h(Support)d (for)i(SAX2)g(parsers)j(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(288)125 5313 y(8.10)68 b FJ(xml.sax.handler)18 b FN(\227)j(Base)g(classes)h(for)d(SAX)i(handlers)29 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(289)p 0 5549 3901 4 v 0 5649 a FI(ii)p eop end %%Page: 3 7 TeXDict begin 3 6 bop 125 83 a FN(8.11)68 b FJ(xml.sax.saxutils)18 b FN(\227)j(SAX)g(Utilities)48 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(293)125 183 y(8.12)68 b FJ(xml.sax.xmlreader) 18 b FN(\227)j(Interf)o(ace)e(for)g(XML)h(parsers)77 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(294)125 282 y(8.13)68 b FJ(xml.etree.ElementTree)17 b FN(\227)k(The)f(ElementT)m(ree)f(XML)h (API)64 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(298)0 465 y FL(9)83 b(File)20 b(F)n(ormats)3197 b(303)125 565 y FN(9.1)110 b FJ(csv)21 b FN(\227)f(CSV)i(File)f(Reading)e(and)h(Writing)58 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(303)125 664 y(9.2)110 b FJ(ConfigParser)19 b FN(\227)i (Con\002guration)d(\002le)j(parser)75 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(310)125 764 y(9.3)110 b FJ(robotparser)19 b FN(\227)i(P)o(arser)f(for)f(robots.txt)27 b(.)41 b(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(313)125 863 y(9.4)110 b FJ(netrc)20 b FN(\227)h(netrc)f(\002le)h(processing)68 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)60 b(314)125 963 y(9.5)110 b FJ(xdrlib)20 b FN(\227)h(Encode)e(and)g(decode)g(XDR)i(data)61 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(315)0 1146 y FL(10)41 b(Cryptographic)18 b(Ser)o(vices)2814 b(319)125 1245 y FN(10.1)68 b FJ(hashlib)20 b FN(\227)h(Secure)e (hashes)h(and)g(message)g(digests)37 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(319)125 1345 y(10.2)68 b FJ(hmac)20 b FN(\227)h(K)n(e)o(yed-Hashing)d(for)h(Message)h(Authentication)73 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(321)125 1445 y(10.3)68 b FJ(md5)21 b FN(\227)f(MD5)g(message)g(digest)g(algorithm)46 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(321)125 1544 y(10.4)68 b FJ(sha)21 b FN(\227)f(SHA-1)g(message)g (digest)g(algorithm)48 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(322)0 1727 y FL(11)41 b(File)20 b(and)h(Dir)o(ectory)d (Access)2746 b(325)125 1826 y FN(11.1)68 b FJ(os.path)20 b FN(\227)h(Common)d(pathname)h(manipulations)53 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(325)125 1926 y(11.2)68 b FJ(fileinput)19 b FN(\227)i(Iterate)f(o)o(v)o(er)f(lines)h (from)g(multiple)f(input)h(streams)34 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(328)125 2026 y(11.3)68 b FJ(stat)20 b FN(\227)h(Interpreting)d FJ(stat\(\))i FN(results)26 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(330)125 2125 y(11.4)68 b FJ(statvfs)20 b FN(\227)h(Constants)f(used)g(with)g FJ(os.statvfs\(\))35 b FN(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(332)125 2225 y(11.5)68 b FJ(filecmp)20 b FN(\227)h(File)g(and)e (Directory)g(Comparisons)68 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)60 b(333)125 2325 y(11.6)68 b FJ(tempfile)20 b FN(\227)g(Generate)g(temporary)e(\002les)j(and)f(directories)64 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(334)125 2424 y(11.7)68 b FJ(glob)20 b FN(\227)j(U)t FH(N)t(I)t(X)g FN(style)e(pathname)d (pattern)i(e)o(xpansion)j(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(336)125 2524 y(11.8)68 b FJ(fnmatch)20 b FN(\227)j(U)t FH(N)t(I)t(X)g FN(\002lename)c(pattern)h(matching)53 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(337)125 2623 y(11.9)68 b FJ(linecache)19 b FN(\227)i(Random)e(access)i(to)f(te) o(xt)h(lines)54 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(338)125 2723 y(11.10)26 b FJ(shutil)20 b FN(\227)h(High-le)n(v)o(el)d (\002le)j(operations)29 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)60 b(338)125 2823 y(11.11)26 b FJ(dircache)20 b FN(\227)g(Cached)g(directory)f(listings)70 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(340)0 3005 y FL(12)41 b(Data)19 b(Compr)o(ession)h(and)h(Ar)o(chi)o (ving)2465 b(343)125 3105 y FN(12.1)68 b FJ(zlib)20 b FN(\227)h(Compression)e(compatible)g(with)h FL(gzip)60 b FN(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(343)125 3205 y(12.2)68 b FJ(gzip)20 b FN(\227)h(Support)e(for)g FL(gzip)i FN(\002les)81 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(345)125 3304 y(12.3)68 b FJ(bz2)21 b FN(\227)f(Compression)f(compatible)g(with)h FL(bzip2)64 b FN(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(346)125 3404 y(12.4)68 b FJ(zipfile)20 b FN(\227)h(W)-7 b(ork)20 b(with)g(ZIP)g(archi)n(v)o(es)35 b(.)41 b(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(348)125 3504 y(12.5)68 b FJ(tarfile)20 b FN(\227)h(Read)f(and)g(write)g(tar)g (archi)n(v)o(e)f(\002les)44 b(.)d(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(351)0 3686 y FL(13)41 b(Data)19 b(P)n(ersistence)3064 b(359)125 3786 y FN(13.1)68 b FJ(pickle)20 b FN(\227)h(Python)e(object) g(serialization)52 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(359)125 3885 y(13.2)68 b FJ(cPickle)20 b FN(\227)h(A)f(f)o(aster)h FJ(pickle)54 b FN(.)41 b(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(370)125 3985 y(13.3)68 b FJ(copy_reg)20 b FN(\227)g(Re)o(gister)h FJ(pickle)e FN(support)g(functions)78 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(371)125 4085 y(13.4)68 b FJ(shelve)20 b FN(\227)h(Python)e (object)g(persistence)27 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(371)125 4184 y(13.5)68 b FJ(marshal)20 b FN(\227)h(Internal)e(Python)g(object)g(serialization)34 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(374)125 4284 y(13.6)68 b FJ(anydbm)20 b FN(\227)h(Generic)e(access)i(to)f (DBM-style)h(databases)59 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(375)125 4384 y(13.7)68 b FJ(whichdb)20 b FN(\227)h(Guess)f(which)g (DBM)h(module)e(created)g(a)i(database)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(376)125 4483 y(13.8)68 b FJ(dbm)21 b FN(\227)f(Simple)g (\223database\224)g(interf)o(ace)35 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(376)125 4583 y(13.9)68 b FJ(gdbm)20 b FN(\227)h(GNU')-5 b(s)21 b(reinterpretation)d (of)i(dbm)72 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(377)125 4682 y(13.10)26 b FJ(dbhash)20 b FN(\227)h(DBM-style)f (interf)o(ace)f(to)i(the)f(BSD)h(database)f(library)61 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(378)125 4782 y(13.11)26 b FJ(bsddb)20 b FN(\227)h(Interf)o(ace)e(to)h(Berk)o(ele)o(y)g(DB)h(library)34 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(379)125 4882 y(13.12)26 b FJ(dumbdbm)20 b FN(\227)h(Portable)e(DBM)i (implementation)44 b(.)d(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(382)125 4981 y(13.13)26 b FJ(sqlite3)20 b FN(\227)h(DB-API)f(2.0)g (interf)o(ace)f(for)h(SQLite)g(databases)82 b(.)41 b(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(383)0 5164 y FL(14)41 b(Generic)20 b(Operating)f(System)h(Ser)o (vices)2399 b(395)125 5264 y FN(14.1)68 b FJ(os)21 b FN(\227)g(Miscellaneous)e(operating)f(system)j(interf)o(aces)39 b(.)j(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(395)125 5363 y(14.2)68 b FJ(time)20 b FN(\227)h(T)m(ime)f(access)h(and)f(con)m (v)o(ersions)76 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)60 b(415)p 0 5549 3901 4 v 3845 5649 a FI(iii)p eop end %%Page: 4 8 TeXDict begin 4 7 bop 125 83 a FN(14.3)68 b FJ(optparse)20 b FN(\227)g(More)g(po)n(werful)e(command)h(line)h(option)f(parser)74 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(420)125 183 y(14.4)68 b FJ(getopt)20 b FN(\227)h(P)o(arser)f(for)f(command)g(line)h(options)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(448)125 282 y(14.5)68 b FJ(logging)20 b FN(\227)h(Logging)d(f)o (acility)i(for)f(Python)39 b(.)i(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(450)125 382 y(14.6)68 b FJ(getpass)20 b FN(\227)h(Portable)e(passw)o(ord)h(input)j(.)41 b(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(472)125 482 y(14.7)68 b FJ(curses)20 b FN(\227)h(T)-6 b(erminal)19 b(handling)f(for)i(character)n(-cell)f(displays)69 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)60 b(472)125 581 y(14.8)68 b FJ(curses.textpad)19 b FN(\227)h(T)-6 b(e)o(xt)20 b(input)g(widget)f(for)h(curses)g (programs)h(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(487)125 681 y(14.9)68 b FJ(curses.wrapper)19 b FN(\227)h(T)-6 b(erminal)20 b(handler)e(for)i(curses)g(programs)36 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(488)125 780 y(14.10)26 b FJ(curses.ascii)19 b FN(\227)i(Utilities)g (for)f(ASCII)g(characters)32 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(488)125 880 y(14.11)26 b FJ(curses.panel)19 b FN(\227)i(A)f(panel) g(stack)g(e)o(xtension)f(for)h(curses.)42 b(.)g(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(491)125 980 y(14.12)26 b FJ(platform)20 b FN(\227)g(Access)h(to)g (underlying)c(platform')-5 b(s)19 b(identifying)f(data.)82 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(492)125 1079 y(14.13)26 b FJ(errno)20 b FN(\227)h(Standard)e(errno)g(system)h(symbols)71 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(494)125 1179 y(14.14)26 b FJ(ctypes)20 b FN(\227)h(A)g(foreign)d (function)g(library)i(for)f(Python.)56 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(500)0 1362 y FL(15)41 b(Optional)19 b(Operating)g(System)i (Ser)o(vices)2366 b(535)125 1461 y FN(15.1)68 b FJ(select)20 b FN(\227)h(W)-7 b(aiting)20 b(for)g(I/O)g(completion)32 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(535)125 1561 y(15.2)68 b FJ(thread)20 b FN(\227)h(Multiple)f(threads) f(of)h(control)44 b(.)d(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(536)125 1660 y(15.3)68 b FJ(threading)19 b FN(\227)i(Higher)n(-le)n(v)o(el)e(threading)f(interf)o(ace)39 b(.)j(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(538)125 1760 y(15.4)68 b FJ(dummy_thread)19 b FN(\227)i(Drop-in)d(replacement)h (for)g(the)i FJ(thread)e FN(module)53 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(546)125 1860 y(15.5)68 b FJ(dummy_threading)18 b FN(\227)j(Drop-in)e (replacement)f(for)i(the)g FJ(threading)f FN(module)65 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(547)125 1959 y(15.6)68 b FJ(mmap)20 b FN(\227)h(Memory-mapped)16 b(\002le)21 b(support)63 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(547)125 2059 y(15.7)68 b FJ(readline)20 b FN(\227)g(GNU)h(readline)e(interf)o(ace)59 b(.)41 b(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(549)125 2159 y(15.8)68 b FJ(rlcompleter)19 b FN(\227)i(Completion)e(function)f (for)i(GNU)g(readline)77 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(551)0 2341 y FL(16)41 b(Unix)20 b(Speci\002c)h(Ser)o(vices)2876 b(553)125 2441 y FN(16.1)68 b FJ(posix)20 b FN(\227)h(The)f(most)g (common)e(POSIX)j(system)f(calls)55 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)60 b(553)125 2540 y(16.2)68 b FJ(pwd)21 b FN(\227)f(The)g(passw) o(ord)g(database)68 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(554)125 2640 y(16.3)68 b FJ(spwd)20 b FN(\227)h(The)f(shado)n(w)f(passw)o(ord)h(database)57 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(555)125 2740 y(16.4)68 b FJ(grp)21 b FN(\227)f(The)g(group)f (database)62 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(556)125 2839 y(16.5)68 b FJ(crypt)20 b FN(\227)h(Function)e(to)h(check)i(U)t FH(N)t(I)t(X)h FN(passw)o(ords)60 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(556)125 2939 y(16.6)68 b FJ(dl)21 b FN(\227)g(Call)g(C)g(functions)e(in)h(shared)f(objects)76 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(557)125 3039 y(16.7)68 b FJ(termios)20 b FN(\227)h(POSIX)f(style)h (tty)f(control)43 b(.)e(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(558)125 3138 y(16.8)68 b FJ(tty)21 b FN(\227)f(T)-6 b(erminal)20 b(control)f(functions)76 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(559)125 3238 y(16.9)68 b FJ(pty)21 b FN(\227)f(Pseudo-terminal) e(utilities)25 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(560)125 3337 y(16.10)26 b FJ(fcntl)20 b FN(\227)h(The)f FJ(fcntl\(\))f FN(and)h FJ(ioctl\(\))f FN(system)i(calls)53 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(560)125 3437 y(16.11)26 b FJ(pipes)20 b FN(\227)h(Interf)o(ace)e(to)h (shell)h(pipelines)47 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(562)125 3537 y(16.12)26 b FJ(posixfile)19 b FN(\227)i(File-lik)o(e)g(objects)e(with)i(locking)e(support)40 b(.)h(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(563)125 3636 y(16.13)26 b FJ(resource)20 b FN(\227)g(Resource)g(usage)g(information)28 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(565)125 3736 y(16.14)26 b FJ(nis)21 b FN(\227)f(Interf)o(ace)f(to)i (Sun')-5 b(s)20 b(NIS)g(\(Y)-8 b(ello)n(w)20 b(P)o(ages\))73 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(568)125 3836 y(16.15)26 b FJ(syslog)20 b FN(\227)j(U)t FH(N)t(I)t(X)g FN(syslog)d(library)f(routines)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(568)125 3935 y(16.16)26 b FJ(commands)20 b FN(\227)g(Utilities)i(for)d(running)f(commands)41 b(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(569)0 4118 y FL(17)41 b(Inter)o(pr)o(ocess)20 b(Communication)f(and)i(Netw)o(orking)2022 b(571)125 4218 y FN(17.1)68 b FJ(subprocess)19 b FN(\227)i(Subprocess)e (management)37 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(571)125 4317 y(17.2)68 b FJ(socket)20 b FN(\227)h(Lo)n(w-le)n(v)o (el)d(netw)o(orking)g(interf)o(ace)80 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(577)125 4417 y(17.3)68 b FJ(signal)20 b FN(\227)h(Set)g(handlers)e(for)g(asynchronous)f(e)n(v)o(ents)78 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(588)125 4516 y(17.4)68 b FJ(popen2)20 b FN(\227)h(Subprocesses)e(with)h (accessible)h(I/O)f(streams)57 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(590)125 4616 y(17.5)68 b FJ(asyncore)20 b FN(\227)g(Asynchronous)e (sock)o(et)i(handler)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(592)125 4716 y(17.6)68 b FJ(asynchat)20 b FN(\227)g (Asynchronous)e(sock)o(et)i(command/response)d(handler)65 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(595)0 4898 y FL(18)41 b(Inter)o(net)20 b(Pr)o(otocols)e (and)i(Support)2544 b(599)125 4998 y FN(18.1)68 b FJ(webbrowser)19 b FN(\227)i(Con)m(v)o(enient)d(W)-7 b(eb-bro)n(wser)19 b(controller)49 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(599)125 5098 y(18.2)68 b FJ(cgi)21 b FN(\227)f(Common)f(Gate)n(w)o(ay)h(Interf) o(ace)f(support.)45 b(.)c(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(602)125 5197 y(18.3)68 b FJ(cgitb)20 b FN(\227)h(T)m(raceback)e (manager)f(for)i(CGI)g(scripts)69 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(609)125 5297 y(18.4)68 b FJ(wsgiref)20 b FN(\227)h(WSGI)f(Utilities)i(and)d(Reference)h(Implementation)25 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(610)125 5396 y(18.5)68 b FJ(urllib)20 b FN(\227)h(Open)e(arbitrary)g(resources)g(by)h(URL)76 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(617)p 0 5549 3901 4 v 0 5649 a FI(iv)p eop end %%Page: 5 9 TeXDict begin 5 8 bop 125 83 a FN(18.6)68 b FJ(urllib2)20 b FN(\227)h(e)o(xtensible)e(library)g(for)g(opening)g(URLs)60 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(622)125 183 y(18.7)68 b FJ(httplib)20 b FN(\227)h(HTTP)f(protocol)e(client)53 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(632)125 282 y(18.8)68 b FJ(ftplib)20 b FN(\227)h(FTP)g (protocol)d(client)43 b(.)e(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(636)125 382 y(18.9)68 b FJ(gopherlib)19 b FN(\227)i(Gopher)e(protocol)f(client)37 b(.)k(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(640)125 482 y(18.10)26 b FJ(poplib)20 b FN(\227)h(POP3)f(protocol)f (client)54 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(640)125 581 y(18.11)26 b FJ(imaplib)20 b FN(\227)h(IMAP4)e(protocol)g(client)74 b(.)41 b(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(642)125 681 y(18.12)26 b FJ(nntplib)20 b FN(\227)h(NNTP)f(protocol)f(client)43 b(.)f(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(647)125 780 y(18.13)26 b FJ(smtplib)20 b FN(\227)h(SMTP)f (protocol)f(client)43 b(.)f(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(651)125 880 y(18.14)26 b FJ(smtpd)20 b FN(\227)h(SMTP)g(Serv)o(er)35 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(655)125 980 y(18.15)26 b FJ(telnetlib)19 b FN(\227)i(T)-6 b(elnet)20 b(client)66 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(656)125 1079 y(18.16)26 b FJ(uuid)20 b FN(\227)h(UUID)f(objects)g(according)e(to)j (RFC)g(4122)j(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(658)125 1179 y(18.17)26 b FJ(urlparse)20 b FN(\227)g(P)o(arse)h(URLs) g(into)f(components)53 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(661)125 1279 y(18.18)26 b FJ(SocketServer)19 b FN(\227)i(A)f(frame)n(w)o(ork)e(for)i(netw)o(ork)f(serv)o(ers)30 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(664)125 1378 y(18.19)26 b FJ(BaseHTTPServer)19 b FN(\227)h(Basic)i(HTTP)e(serv)o(er)27 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(667)125 1478 y(18.20)26 b FJ(SimpleHTTPServer)18 b FN(\227)j(Simple)f(HTTP)g(request)g(handler)67 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)60 b(670)125 1577 y(18.21)26 b FJ(CGIHTTPServer)19 b FN(\227)h(CGI-capable)f(HTTP)i(request)e(handler)28 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(671)125 1677 y(18.22)26 b FJ(cookielib)19 b FN(\227)i(Cookie)f(handling)e(for)i(HTTP)g(clients) 28 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(672)125 1777 y(18.23)26 b FJ(Cookie)20 b FN(\227)h(HTTP)f(state)h(management)48 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(680)125 1876 y(18.24)26 b FJ(xmlrpclib)19 b FN(\227)i(XML-RPC)g (client)f(access)44 b(.)d(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(684)125 1976 y(18.25)26 b FJ(SimpleXMLRPCServer)18 b FN(\227)j(Basic)g(XML-RPC)g(serv)o(er)40 b(.)h(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(688)125 2076 y(18.26)26 b FJ(DocXMLRPCServer)18 b FN(\227)j(Self-documenting)c(XML-RPC)k(serv)o(er)28 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(691)0 2258 y FL(19)41 b(Multimedia)20 b(Ser)o(vices)2925 b(693)125 2358 y FN(19.1)68 b FJ(audioop)20 b FN(\227)h(Manipulate)e(ra)o(w)g(audio)h(data)63 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(693)125 2457 y(19.2)68 b FJ(imageop)20 b FN(\227)h(Manipulate)e(ra)o (w)g(image)h(data)45 b(.)c(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(696)125 2557 y(19.3)68 b FJ(aifc)20 b FN(\227)h(Read)g (and)e(write)i(AIFF)f(and)g(AIFC)h(\002les)74 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(697)125 2657 y(19.4)68 b FJ(sunau)20 b FN(\227)h(Read)f(and)g(write)g(Sun)g(A) -5 b(U)21 b(\002les)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(699)125 2756 y(19.5)68 b FJ(wave)20 b FN(\227)h(Read)g(and)e(write)i(W)-10 b(A)f(V)20 b(\002les)54 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(702)125 2856 y(19.6)68 b FJ(chunk)20 b FN(\227)h(Read)f(IFF)h (chunk)o(ed)d(data)29 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(704)125 2956 y(19.7)68 b FJ(colorsys)20 b FN(\227)g(Con)m(v)o(ersions)f(between)g(color)g (systems)30 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(705)125 3055 y(19.8)68 b FJ(rgbimg)20 b FN(\227)h(Read)f(and)g(write) g(\223SGI)h(RGB\224)g(\002les)44 b(.)d(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(705)125 3155 y(19.9)68 b FJ(imghdr)20 b FN(\227)h(Determine)e(the)h(type)g(of)g(an)g(image)75 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(706)125 3254 y(19.10)26 b FJ(sndhdr)20 b FN(\227)h(Determine)e(type)h (of)g(sound)f(\002le)50 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(707)125 3354 y(19.11)26 b FJ(ossaudiodev)19 b FN(\227)i(Access)g(to)f(OSS-compatible)f(audio)g(de)n(vices)72 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(707)0 3537 y FL(20)41 b(Graphical)19 b(User)i(Interfaces)f(with)g(Tk)2429 b(713)125 3636 y FN(20.1)68 b FJ(Tkinter)20 b FN(\227)h(Python)e(interf)o(ace)g(to)h (Tcl/Tk)72 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(713)125 3736 y(20.2)68 b FJ(Tix)21 b FN(\227)f(Extension)f (widgets)h(for)g(Tk)58 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(725)125 3836 y(20.3)68 b FJ(ScrolledText)19 b FN(\227)i(Scrolled)e(T)-6 b(e)o(xt)20 b(W)m(idget)58 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(730)125 3935 y(20.4)68 b FJ(turtle)20 b FN(\227)h(T)l(urtle)f (graphics)f(for)g(Tk)81 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(730)125 4035 y(20.5)68 b(Idle)49 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)60 b(733)125 4134 y(20.6)68 b(Other)20 b(Graphical)f(User)i (Interf)o(ace)e(P)o(ackages)64 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(736)0 4317 y FL(21)41 b(Inter)o (nationalization)2938 b(739)125 4417 y FN(21.1)68 b FJ(gettext)20 b FN(\227)h(Multilingual)e(internationalization)e(services)78 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(739)125 4516 y(21.2)68 b FJ(locale)20 b FN(\227)h(Internationalization)c(services)61 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(749)0 4699 y FL(22)41 b(Pr)o(ogram)18 b(Framew)o(orks)2861 b(757)125 4799 y FN(22.1)68 b FJ(cmd)21 b FN(\227)f(Support)f(for)h (line-oriented)e(command)g(interpreters)73 b(.)42 b(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(757)125 4898 y(22.2)68 b FJ(shlex)20 b FN(\227)h(Simple)f(le)o (xical)g(analysis)36 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(759)0 5081 y FL(23)41 b(De)o(v)o(elopment)19 b(T)-8 b(ools)2980 b(763)125 5181 y FN(23.1)68 b FJ(pydoc)20 b FN(\227)h(Documentation)d(generator)g(and) i(online)f(help)h(system)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(763)125 5280 y(23.2)68 b FJ(doctest)20 b FN(\227)h(T)-6 b(est)21 b(interacti)n(v)o(e)d(Python)h(e)o(xamples)42 b(.)f(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(764)125 5380 y(23.3)68 b FJ(unittest)20 b FN(\227)g(Unit)h(testing)f(frame)n(w)o(ork)64 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(789)p 0 5549 3901 4 v 3858 5649 a FI(v)p eop end %%Page: 6 10 TeXDict begin 6 9 bop 125 83 a FN(23.4)68 b FJ(test)20 b FN(\227)h(Re)o(gression)f(tests)h(package)e(for)g(Python)i(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(801)125 183 y(23.5)68 b FJ(test.test_support)18 b FN(\227)j(Utility)f (functions)f(for)h(tests)56 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(803)0 365 y FL(24)41 b(The)21 b(Python)e(Deb)n(ugger)2872 b(805)125 465 y FN(24.1)68 b(Deb)n(ugger)19 b(Commands)75 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(806)125 565 y(24.2)68 b(Ho)n(w)20 b(It)h(W)-7 b(orks)85 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)60 b(809)0 747 y FL(25)41 b(The)21 b(Python)e(Pr)o (o\002lers)2913 b(811)125 847 y FN(25.1)68 b(Introduction)18 b(to)i(the)g(pro\002lers)71 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(811)125 946 y(25.2)68 b(Instant)20 b(User')-5 b(s)21 b(Manual)67 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(812)125 1046 y(25.3)68 b(What)21 b(Is)g(Deterministic)e(Pro\002ling?)30 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(814)125 1146 y(25.4)68 b(Reference)20 b(Manual)f(\226)h FJ(profile)g FN(and)f FJ(cProfile)69 b FN(.)42 b(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(814)125 1245 y(25.5)68 b(Limitations)44 b(.)d(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(817)125 1345 y(25.6)68 b(Calibration)53 b(.)41 b(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(817)125 1445 y(25.7)68 b(Extensions)20 b(\227)g(Deri)n(ving)f(Better)i(Pro\002lers)53 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(818)125 1544 y(25.8)68 b FJ(hotshot)20 b FN(\227)h(High)e (performance)f(logging)g(pro\002ler)52 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(819)125 1644 y(25.9)68 b FJ(timeit)20 b FN(\227)h(Measure)e(e)o(x)o(ecution)f(time)j(of)f(small)g(code)g (snippets)66 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(821)125 1743 y(25.10)26 b FJ(trace)20 b FN(\227)h(T)m(race)f(or)g(track)f(Python)g (statement)h(e)o(x)o(ecution)j(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(823)0 1926 y FL(26)41 b(Python)19 b(Runtime)i(Ser)o(vices)2756 b(827)125 2026 y FN(26.1)68 b FJ(sys)21 b FN(\227)f(System-speci\002c)g (parameters)f(and)g(functions)79 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(827)125 2125 y(26.2)68 b FJ(__builtin__)19 b FN(\227)i(Built-in)f(objects)49 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(834)125 2225 y(26.3)68 b FJ(__main__)20 b FN(\227)g(T)-7 b(op-le)n(v)o(el)19 b(script)h(en)m(vironment)67 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(834)125 2325 y(26.4)68 b FJ(warnings)20 b FN(\227)g(W)-7 b(arning)20 b(control)48 b(.)41 b(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(834)125 2424 y(26.5)68 b FJ(contextlib)19 b FN(\227)i(Utilities)g (for)f FJ(with)p FN(-statement)f(conte)o(xts.)29 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)60 b(837)125 2524 y(26.6)68 b FJ(atexit)20 b FN(\227)h(Exit)f(handlers)60 b(.)41 b(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(839)125 2623 y(26.7)68 b FJ(traceback)19 b FN(\227)i(Print)f(or)g (retrie)n(v)o(e)f(a)i(stack)f(traceback)51 b(.)41 b(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(840)125 2723 y(26.8)68 b FJ(__future__)19 b FN(\227)i(Future)f(statement)g(de\002nitions)59 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(842)125 2823 y(26.9)68 b FJ(gc)21 b FN(\227)g(Garbage)d(Collector)i(interf)o (ace)28 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(843)125 2922 y(26.10)26 b FJ(inspect)20 b FN(\227)h(Inspect)e(li)n(v)o(e)h(objects)63 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(845)125 3022 y(26.11)26 b FJ(site)20 b FN(\227)h(Site-speci\002c)f (con\002guration)e(hook)37 b(.)k(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)60 b(850)125 3122 y(26.12)26 b FJ(user)20 b FN(\227)h(User)n(-speci\002c)f(con\002guration)e(hook)73 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(851)125 3221 y(26.13)26 b FJ(fpectl)20 b FN(\227)h(Floating)e(point)h (e)o(xception)e(control)57 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(852)0 3404 y FL(27)41 b(Custom)20 b(Python)f(Inter)o(pr)o (eters)2647 b(855)125 3504 y FN(27.1)68 b FJ(code)20 b FN(\227)h(Interpreter)d(base)j(classes)81 b(.)41 b(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(855)125 3603 y(27.2)68 b FJ(codeop)20 b FN(\227)h(Compile)f(Python)f (code)30 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(857)0 3786 y FL(28)41 b(Restricted)20 b(Execution)2909 b(859)125 3885 y FN(28.1)68 b FJ(rexec)20 b FN(\227)h(Restricted)f(e)o(x)o(ecution)e(frame)n(w)o(ork)50 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(860)125 3985 y(28.2)68 b FJ(Bastion)20 b FN(\227)h(Restricting)f (access)h(to)f(objects)73 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(863)0 4168 y FL(29)41 b(Importing)20 b(Modules)2961 b(865)125 4267 y FN(29.1)68 b FJ(imp)21 b FN(\227)f(Access)h(the)f FJ(import)g FN(internals)41 b(.)g(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(865)125 4367 y(29.2)68 b FJ(zipimport)19 b FN(\227)i(Import)e (modules)g(from)g(Zip)h(archi)n(v)o(es)h(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(868)125 4467 y(29.3)68 b FJ(pkgutil)20 b FN(\227)h(P)o(ackage)e(e)o(xtension)f(utility)56 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(870)125 4566 y(29.4)68 b FJ(modulefinder)19 b FN(\227)i(Find)f (modules)f(used)h(by)g(a)g(script)81 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(870)125 4666 y(29.5)68 b FJ(runpy)20 b FN(\227)h(Locating)e (and)h(e)o(x)o(ecuting)e(Python)h(modules.)66 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(871)0 4848 y FL(30)41 b(Python)19 b(Language)g(Ser)o(vices)2715 b(873)125 4948 y FN(30.1)68 b FJ(parser)20 b FN(\227)h(Access)g(Python)e(parse)h (trees)73 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(873)125 5048 y(30.2)68 b FJ(symbol)20 b FN(\227)h(Constants)f (used)g(with)g(Python)f(parse)h(trees)76 b(.)41 b(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(882)125 5147 y(30.3)68 b FJ(token)20 b FN(\227)h (Constants)f(used)g(with)h(Python)e(parse)h(trees)63 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(883)125 5247 y(30.4)68 b FJ(keyword)20 b FN(\227)h(T)-6 b(esting)20 b(for)f(Python)g(k)o(e)o(yw)o(ords)53 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(883)125 5347 y(30.5)68 b FJ(tokenize)20 b FN(\227)g(T)-7 b(ok)o(enizer)19 b(for)h(Python)f (source)i(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(883)p 0 5549 3901 4 v 0 5649 a FI(vi)p eop end %%Page: 7 11 TeXDict begin 7 10 bop 125 83 a FN(30.6)68 b FJ(tabnanny)20 b FN(\227)g(Detection)g(of)g(ambiguous)e(indentation)80 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(885)125 183 y(30.7)68 b FJ(pyclbr)20 b FN(\227)h(Python)e(class)i(bro)n(wser)e (support)25 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)60 b(886)125 282 y(30.8)68 b FJ(py_compile)19 b FN(\227)i(Compile)f (Python)f(source)g(\002les)50 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(887)125 382 y(30.9)68 b FJ(compileall)19 b FN(\227)i(Byte-compile)e(Python)g(libraries)48 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(887)125 482 y(30.10)26 b FJ(dis)21 b FN(\227)f(Disassembler)g(for)g(Python)f(byte)h (code)48 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(888)125 581 y(30.11)26 b FJ(pickletools)19 b FN(\227)i(T)-7 b(ools)20 b(for)g(pickle)f(de)n(v)o(elopers.)76 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(896)125 681 y(30.12)26 b FJ(distutils)19 b FN(\227)i(Building)f(and)f(installing)h (Python)f(modules)28 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(896)0 863 y FL(31)41 b(Python)19 b(compiler)h(package)2750 b(897)125 963 y FN(31.1)68 b(The)20 b(basic)h(interf)o(ace)44 b(.)d(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(897)125 1063 y(31.2)68 b(Limitations)44 b(.)d(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(898)125 1162 y(31.3)68 b(Python)19 b(Abstract)h(Syntax)74 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(898)125 1262 y(31.4)68 b(Using)20 b(V)-5 b(isitors)21 b(to)g(W)-7 b(alk)20 b(ASTs)i(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)60 b(903)125 1362 y(31.5)68 b(Bytecode)20 b(Generation)33 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(904)0 1544 y FL(32)41 b(Abstract)19 b(Syntax)g(T)-6 b(r)o(ees)2865 b(905)125 1644 y FN(32.1)68 b(Abstract)20 b(Grammar)55 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(905)0 1826 y FL(33)41 b(Miscellaneous)20 b(Ser)o(vices)2842 b(909)125 1926 y FN(33.1)68 b FJ(formatter)19 b FN(\227)i(Generic)f (output)f(formatting)43 b(.)f(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)60 b(909)0 2109 y FL(34)41 b(SGI)20 b(IRIX)i(Speci\002c)e(Ser)o (vices)2699 b(913)125 2208 y FN(34.1)68 b FJ(al)21 b FN(\227)g(Audio)e(functions)g(on)g(the)i(SGI)32 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) 60 b(913)125 2308 y(34.2)68 b FJ(AL)21 b FN(\227)g(Constants)f(used)g (with)g(the)g FJ(al)h FN(module)78 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(915)125 2408 y(34.3)68 b FJ(cd)21 b FN(\227)g(CD-R)m(OM)f(access)h(on)f(SGI)g(systems)34 b(.)41 b(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(915)125 2507 y(34.4)68 b FJ(fl)21 b FN(\227)g(FORMS)g(library)e(for)g (graphical)g(user)h(interf)o(aces)38 b(.)j(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)60 b(919)125 2607 y(34.5)68 b FJ(FL)21 b FN(\227)g(Constants)f (used)g(with)g(the)g FJ(fl)h FN(module)78 b(.)42 b(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(923)125 2707 y(34.6)68 b FJ(flp)21 b FN(\227)f(Functions)g(for)f(loading)g(stored)h(FORMS)h (designs)74 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(924)125 2806 y(34.7)68 b FJ(fm)21 b FN(\227)g FK(F)-9 b(ont)19 b(Mana)o(g)o(er)h FN(interf)o(ace)43 b(.)e(.)g(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(924)125 2906 y(34.8)68 b FJ(gl)21 b FN(\227)g FK(Gr)o(aphics)e(Libr)o(ary)h FN(interf)o(ace)58 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(925)125 3005 y(34.9)68 b FJ(DEVICE)20 b FN(\227)h(Constants)f(used)g(with)g(the)h FJ(gl)f FN(module)66 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(927)125 3105 y(34.10)26 b FJ(GL)21 b FN(\227)g(Constants)f(used)g (with)g(the)g FJ(gl)h FN(module)78 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)60 b(927)125 3205 y(34.11)26 b FJ(imgfile)20 b FN(\227)h(Support)d(for)i(SGI)g(imglib)g(\002les)81 b(.)42 b(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(927)125 3304 y(34.12)26 b FJ(jpeg)20 b FN(\227)h(Read)g(and)e(write)i (JPEG)f(\002les)42 b(.)g(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)60 b(928)0 3487 y FL(35)41 b(SunOS)21 b(Speci\002c)f(Ser)o(vices)2798 b(931)125 3587 y FN(35.1)68 b FJ(sunaudiodev)19 b FN(\227)i(Access)g(to)f(Sun)g(audio)f(hardw)o (are)57 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(931)125 3686 y(35.2)68 b FJ(SUNAUDIODEV)19 b FN(\227)i(Constants)f(used)g(with) g FJ(sunaudiodev)73 b FN(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(932)0 3869 y FL(36)41 b(MS)21 b(W)o(indo)o(ws)f(Speci\002c)h(Ser)o(vices)2572 b(933)125 3968 y FN(36.1)68 b FJ(msilib)20 b FN(\227)h(Read)f(and)g (write)g(Microsoft)f(Installer)h(\002les)72 b(.)41 b(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)60 b(933)125 4068 y(36.2)68 b FJ(msvcrt)20 b FN(\226)g(Useful)g(routines)g(from)f(the)h(MS)h(VC)1813 4061 y(++)1927 4068 y(runtime)75 b(.)42 b(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(939)125 4168 y(36.3)68 b FJ(_winreg)20 b FN(\226)g(W)m(indo)n(ws)g (re)o(gistry)f(access)49 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)60 b(941)125 4267 y(36.4)68 b FJ(winsound)20 b FN(\227)g(Sound-playing)d(interf)o(ace)i(for)h(W)m (indo)n(ws)j(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(945)0 4450 y FL(A)65 b(Undocumented)20 b(Modules)2786 b(947)125 4550 y FN(A.1)92 b(Frame)n(w)o(orks)76 b(.)41 b(.)h(.)f(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.) f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)g(.)60 b(947)125 4649 y(A.2)92 b(Miscellaneous)20 b(useful)f(utilities)78 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.) h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(947)125 4749 y(A.3)92 b(Platform)20 b(speci\002c)g(modules)57 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.) h(.)f(.)g(.)g(.)60 b(947)125 4848 y(A.4)92 b(Multimedia)39 b(.)i(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(947)125 4948 y(A.5)92 b(Obsolete)70 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f (.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(948)125 5048 y(A.6)92 b(SGI-speci\002c)20 b(Extension)f(modules)41 b(.)g(.)g(.)h(.)f(.)g(.)g (.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(948)0 5230 y FL(B)70 b(Reporting)19 b(Bugs)3095 b(949)p 0 5549 3901 4 v 3822 5649 a FI(vii)p eop end %%Page: 8 12 TeXDict begin 8 11 bop 0 83 a FL(C)65 b(History)19 b(and)h(License)2941 b(951)125 183 y FN(C.1)97 b(History)20 b(of)g(the)g(softw)o(are)34 b(.)41 b(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h(.)f(.) g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)h (.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(951)125 282 y(C.2)97 b(T)-6 b(erms)20 b(and)g(conditions)f(for)g(accessing)h(or)g(otherwise) g(using)f(Python)47 b(.)41 b(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.) g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(952)125 382 y(C.3)97 b(Licenses)21 b(and)e(Ackno)n(wledgements)e(for)j (Incorporated)d(Softw)o(are)54 b(.)41 b(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g (.)g(.)h(.)f(.)g(.)h(.)f(.)g(.)g(.)h(.)f(.)g(.)g(.)60 b(955)0 565 y FL(Module)21 b(Index)3279 b(965)0 747 y(Index)3572 b(969)p 0 5549 3901 4 v 0 5649 a FI(viii)p eop end %%Page: 1 13 TeXDict begin 1 12 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3641 427 y FG(ONE)p 0 515 V 2821 978 a FT(Introduction)0 1457 y FN(The)20 b(\223Python)f(library\224)g(contains)g(se)n(v)o(eral)h (dif)n(ferent)e(kinds)i(of)g(components.)0 1604 y(It)j(contains)f(data) g(types)h(that)g(w)o(ould)f(normally)f(be)h(considered)f(part)i(of)f (the)h(\223core\224)e(of)i(a)g(language,)e(such)i(as)g(numbers)e(and)h (lists.)0 1703 y(F)o(or)f(these)h(types,)g(the)g(Python)e(language)g (core)h(de\002nes)h(the)f(form)g(of)g(literals)i(and)e(places)h(some)f (constraints)g(on)g(their)h(semantics,)0 1803 y(b)n(ut)e(does)f(not)h (fully)f(de\002ne)h(the)f(semantics.)25 b(\(On)20 b(the)g(other)f (hand,)f(the)i(language)e(core)i(does)f(de\002ne)g(syntactic)h (properties)e(lik)o(e)j(the)0 1902 y(spelling)f(and)f(priorities)h(of)g (operators.\))0 2049 y(The)h(library)f(also)h(contains)g(b)n(uilt-in)f (functions)g(and)g(e)o(xceptions)g(\227)i(objects)e(that)i(can)f(be)g (used)f(by)h(all)h(Python)e(code)g(without)h(the)0 2149 y(need)d(of)h(an)f FJ(import)h FN(statement.)24 b(Some)18 b(of)h(these)g(are)g(de\002ned)f(by)g(the)h(core)f(language,)f(b)n(ut)i (man)o(y)f(are)g(not)h(essential)g(for)f(the)h(core)0 2249 y(semantics)h(and)g(are)g(only)f(described)g(here.)0 2395 y(The)j(b)n(ulk)g(of)g(the)g(library)-5 b(,)21 b(ho)n(we)n(v)o(er) m(,)g(consists)i(of)f(a)g(collection)g(of)g(modules.)30 b(There)22 b(are)g(man)o(y)f(w)o(ays)i(to)f(dissect)h(this)g (collection.)0 2495 y(Some)j(modules)g(are)g(written)g(in)h(C)g(and)f (b)n(uilt)h(in)g(to)f(the)h(Python)e(interpreter;)j(others)e(are)g (written)h(in)f(Python)g(and)g(imported)e(in)0 2595 y(source)i(form.)44 b(Some)27 b(modules)f(pro)o(vide)e(interf)o(aces)j(that)g(are)g(highly) e(speci\002c)i(to)g(Python,)h(lik)o(e)f(printing)e(a)i(stack)h(trace;)i (some)0 2694 y(pro)o(vide)18 b(interf)o(aces)h(that)h(are)g(speci\002c) g(to)g(particular)f(operating)f(systems,)i(such)g(as)h(access)f(to)g (speci\002c)h(hardw)o(are;)d(others)i(pro)o(vide)0 2794 y(interf)o(aces)i(that)g(are)g(speci\002c)h(to)f(a)h(particular)e (application)g(domain,)g(lik)o(e)h(the)h(W)-7 b(orld)22 b(W)m(ide)g(W)-7 b(eb)m(.)32 b(Some)22 b(modules)f(are)h(a)n(v)n (ailable)0 2894 y(in)i(all)g(v)o(ersions)f(and)g(ports)g(of)g(Python;)h (others)g(are)f(only)g(a)n(v)n(ailable)g(when)g(the)h(underlying)d (system)i(supports)g(or)g(requires)g(them;)0 2993 y(yet)18 b(others)g(are)h(a)n(v)n(ailable)e(only)h(when)g(a)g(particular)g (con\002guration)d(option)i(w)o(as)j(chosen)d(at)i(the)f(time)h(when)f (Python)f(w)o(as)i(compiled)0 3093 y(and)h(installed.)0 3240 y(This)g(manual)e(is)i(or)o(ganized)d(\223from)h(the)h(inside)g (out:\224)25 b(it)20 b(\002rst)g(describes)f(the)g(b)n(uilt-in)g(data)g (types,)g(then)g(the)g(b)n(uilt-in)g(functions)f(and)0 3339 y(e)o(xceptions,)k(and)h(\002nally)g(the)g(modules,)g(grouped)d (in)k(chapters)e(of)h(related)g(modules.)33 b(The)23 b(ordering)e(of)i(the)g(chapters)f(as)i(well)g(as)0 3439 y(the)c(ordering)e(of)i(the)g(modules)f(within)h(each)g(chapter)f(is)i (roughly)e(from)g(most)h(rele)n(v)n(ant)f(to)h(least)h(important.)0 3586 y(This)i(means)f(that)g(if)h(you)f(start)g(reading)f(this)i (manual)f(from)f(the)i(start,)g(and)f(skip)g(to)h(the)f(ne)o(xt)g (chapter)f(when)h(you)g(get)g(bored,)f(you)0 3685 y(will)f(get)f(a)h (reasonable)e(o)o(v)o(ervie)n(w)f(of)i(the)g(a)n(v)n(ailable)g(modules) f(and)g(application)g(areas)i(that)f(are)g(supported)e(by)i(the)g (Python)f(library)-5 b(.)0 3785 y(Of)21 b(course,)e(you)h(don')o(t)e FK(have)i FN(to)h(read)f(it)h(lik)o(e)f(a)h(no)o(v)o(el)e(\227)i(you)f (can)g(also)h(bro)n(wse)e(the)i(table)f(of)g(contents)g(\(in)g(front)g (of)g(the)g(manual\),)0 3885 y(or)26 b(look)g(for)g(a)i(speci\002c)e (function,)h(module)e(or)i(term)f(in)h(the)g(inde)o(x)e(\(in)i(the)f (back\).)44 b(And)26 b(\002nally)-5 b(,)27 b(if)g(you)f(enjo)o(y)g (learning)g(about)0 3984 y(random)20 b(subjects,)i(you)f(choose)g(a)h (random)f(page)g(number)f(\(see)i(module)e FJ(random)p FN(\))h(and)h(read)f(a)h(section)g(or)g(tw)o(o.)30 b(Re)o(gardless)21 b(of)0 4084 y(the)j(order)f(in)i(which)f(you)f(read)h(the)g(sections)h (of)f(this)g(manual,)h(it)g(helps)f(to)g(start)h(with)g(chapter)e(2,)i (\223Built-in)f(T)-7 b(ypes,)25 b(Exceptions)0 4184 y(and)20 b(Functions,)-6 b(\224)19 b(as)i(the)f(remainder)e(of)i(the)g(manual)f (assumes)i(f)o(amiliarity)e(with)i(this)f(material.)0 4330 y(Let)g(the)h(sho)n(w)f(be)o(gin!)p 0 5549 3901 4 v 3854 5649 a FI(1)p eop end %%Page: 2 14 TeXDict begin 2 13 bop 0 5549 3901 4 v 0 5649 a FI(2)p eop end %%Page: 3 15 TeXDict begin 3 14 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3623 427 y FG(TW)n(O)p 0 515 V 2454 978 a FT(Built-in)56 b(Objects)0 1465 y FN(Names)27 b(for)g(b)n(uilt-in)f(e)o(xceptions)f(and)i (functions)f(and)g(a)i(number)d(of)i(constants)f(are)h(found)f(in)h(a)g (separate)g(symbol)f(table.)45 b(This)0 1565 y(table)19 b(is)h(searched)e(last)i(when)f(the)g(interpreter)f(looks)g(up)h(the)g (meaning)f(of)h(a)g(name,)g(so)g(local)h(and)e(global)g(user)n (-de\002ned)g(names)h(can)0 1664 y(o)o(v)o(erride)f(b)n(uilt-in)h (names.)25 b(Built-in)20 b(types)g(are)g(described)f(together)g(here)h (for)f(easy)i(reference.)2828 1634 y FF(1)0 1811 y FN(The)g(tables)h (in)f(this)h(chapter)f(document)e(the)j(priorities)e(of)i(operators)e (by)h(listing)g(them)g(in)h(order)e(of)h(ascending)f(priority)g (\(within)h(a)0 1911 y(table\))e(and)g(grouping)d(operators)i(that)h (ha)n(v)o(e)g(the)g(same)h(priority)d(in)j(the)f(same)h(box.)j(Binary)c (operators)f(of)h(the)g(same)g(priority)f(group)0 2010 y(from)k(left)h(to)g(right.)32 b(\(Unary)22 b(operators)f(group)g(from) h(right)g(to)h(left,)h(b)n(ut)e(there)h(you)f(ha)n(v)o(e)g(no)g(real)h (choice.\))32 b(See)23 b(chapter)f(5)h(of)g(the)0 2110 y FK(Python)c(Refer)m(ence)h(Manual)f FN(for)g(the)h(complete)f (picture)h(on)g(operator)e(priorities.)0 2437 y FE(2.1)121 b(Built-in)32 b(Functions)0 2670 y FN(The)g(Python)f(interpreter)g(has) i(a)f(number)f(of)h(functions)f(b)n(uilt)h(into)h(it)g(that)f(are)g(al) o(w)o(ays)h(a)n(v)n(ailable.)61 b(The)o(y)31 b(are)i(listed)g(here)e (in)0 2770 y(alphabetical)19 b(order)-5 b(.)0 2917 y FD(__import__)p FJ(\()p FK(name)p FC([)p FK(,)17 b(globals)p FC([)p FK(,)i(locals)p FC([)p FK(,)h(fr)l(omlist)q FC([)p FK(,)h(le)o(vel)12 b FC(])g(])g(])g(])p FJ(\))208 3016 y FN(This)18 b(function)f(is)i(in)m(v)n(ok)o(ed)d(by)i(the)g FJ(import)g FN(statement.)24 b(It)19 b(mainly)e(e)o(xists)i(so)f(that)h (you)e(can)h(replace)g(it)h(with)f(another)f(func-)208 3116 y(tion)22 b(that)h(has)g(a)g(compatible)f(interf)o(ace,)g(in)h (order)f(to)h(change)e(the)i(semantics)g(of)f(the)h FJ(import)g FN(statement.)32 b(F)o(or)23 b(e)o(xamples)208 3216 y(of)c(why)f(and)h (ho)n(w)g(you)g(w)o(ould)g(do)g(this,)h(see)g(the)f(standard)g(library) f(modules)h FJ(ihooks)g FN(and)g FJ(rexec)p FN(.)24 b(See)c(also)g(the) f(b)n(uilt-in)208 3315 y(module)26 b FJ(imp)p FN(,)k(which)e(de\002nes) g(some)g(useful)g(operations)e(out)i(of)g(which)g(you)f(can)h(b)n(uild) g(your)f(o)n(wn)g FJ(__import__\(\))208 3415 y FN(function.)208 3548 y(F)o(or)46 b(e)o(xample,)52 b(the)46 b(statement)h(`)p FJ(import)h(spam)p FN(')f(results)g(in)g(the)f(follo)n(wing)g(call:)78 b FJ(__import__\('spam',)208 3647 y(globals\(\),)27 b(locals\(\),)48 b([],)h(-1\))p FN(;)30 b(the)d(statement)f(`)p FJ(from)49 b(spam.ham)f(import)h(eggs)p FN(')26 b(results)h(in)g(`)p FJ(_-)208 3747 y(_import__\('spam.ham',)45 b(globals\(\),)j (locals\(\),)h(['eggs'],)f(-1\))p FN('.)72 b(Note)37 b(that)f(e)n(v)o(en)f(though)208 3847 y FJ(locals\(\))27 b FN(and)h FJ(['eggs'])f FN(are)h(passed)g(in)g(as)h(ar)o(guments,)f (the)h FJ(__import__\(\))d FN(function)h(does)h(not)f(set)j(the)e(lo-) 208 3946 y(cal)23 b(v)n(ariable)f(named)g FJ(eggs)p FN(;)j(this)e(is)h (done)e(by)h(subsequent)f(code)g(that)h(is)h(generated)e(for)g(the)i (import)e(statement.)33 b(\(In)23 b(f)o(act,)208 4046 y(the)g(standard)g(implementation)e(does)i(not)h(use)f(its)i FK(locals)e FN(ar)o(gument)f(at)i(all,)h(and)e(uses)h(its)g FK(globals)f FN(only)g(to)g(determine)g(the)208 4145 y(package)18 b(conte)o(xt)h(of)h(the)g FJ(import)g FN(statement.\))208 4278 y(When)15 b(the)h FK(name)e FN(v)n(ariable)h(is)h(of)g(the)f(form) g FJ(package.module)p FN(,)f(normally)-5 b(,)14 b(the)i(top-le)n(v)o (el)e(package)g(\(the)h(name)g(up)g(till)i(the)208 4378 y(\002rst)f(dot\))e(is)i(returned,)e FK(not)h FN(the)h(module)d(named)i (by)f FK(name)p FN(.)23 b(Ho)n(we)n(v)o(er)m(,)14 b(when)h(a)g (non-empty)e FK(fr)l(omlist)18 b FN(ar)o(gument)13 b(is)j(gi)n(v)o(en,) f(the)208 4478 y(module)j(named)g(by)i FK(name)f FN(is)h(returned.)j (This)d(is)h(done)d(for)h(compatibility)f(with)i(the)g(bytecode)e (generated)g(for)h(the)g(dif)n(ferent)208 4577 y(kinds)27 b(of)g(import)g(statement;)k(when)c(using)g(`)p FJ(import)48 b(spam.ham.eggs)p FN(',)28 b(the)f(top-le)n(v)o(el)f(package)g FJ(spam)i FN(must)g(be)208 4677 y(placed)h(in)h(the)g(importing)f (namespace,)i(b)n(ut)f(when)f(using)h(`)p FJ(from)49 b(spam.ham)f(import)h(eggs)p FN(',)31 b(the)f FJ(spam.ham)208 4776 y FN(subpackage)23 b(must)i(be)g(used)g(to)h(\002nd)f(the)g FJ(eggs)g FN(v)n(ariable.)40 b(As)26 b(a)f(w)o(orkaround)e(for)h(this)i (beha)n(vior)m(,)f(use)g FJ(getattr\(\))f FN(to)208 4876 y(e)o(xtract)19 b(the)h(desired)g(components.)i(F)o(or)e(e)o(xample,)f (you)g(could)g(de\002ne)h(the)g(follo)n(wing)f(helper:)p 0 4947 1560 4 v 90 5003 a FB(1)120 5026 y FH(Most)e(descriptions)i (sorely)f(lack)g(e)o(xplanations)j(of)c(the)h(e)o(xceptions)h(that)f (may)f(be)h(raised)g(\227)f(this)h(will)f(be)h(\002x)o(ed)f(in)g(a)h (future)g(v)o(ersion)g(of)f(this)g(manual.)p 0 5549 3901 4 v 3854 5649 a FI(3)p eop end %%Page: 4 16 TeXDict begin 4 15 bop 444 174 a FA(def)44 b(my_import\(name\):)623 266 y(mod)g(=)h(__import__\(name\))623 357 y(components)e(=)i (name.split\('.'\))623 448 y(for)f(comp)h(in)f(components[1:]:)802 540 y(mod)h(=)f(getattr\(mod,)f(comp\))623 631 y(return)h(mod)208 821 y FK(le)o(vel)21 b FN(speci\002es)i(whether)d(to)i(use)g(absolute)f (or)g(relati)n(v)o(e)g(imports.)29 b(The)21 b(def)o(ault)g(is)i FJ(-1)f FN(which)f(indicates)g(both)g(absolute)g(and)208 920 y(relati)n(v)o(e)c(imports)h(will)h(be)g(attempted.)k FJ(0)c FN(means)g(only)e(perform)g(absolute)h(imports.)23 b(Positi)n(v)o(e)c(v)n(alues)f(for)g FK(le)o(vel)h FN(indicate)f(the) 208 1020 y(number)h(of)i(parent)f(directories)h(to)g(search)g(relati)n (v)o(e)g(to)g(the)g(directory)f(of)h(the)g(module)f(calling)h FJ(__import__)p FN(.)56 b(Changed)208 1120 y(in)21 b(v)o(ersion)f(2.5:) h(The)g(le)n(v)o(el)g(parameter)f(w)o(as)j(added.)86 b(Changed)20 b(in)i(v)o(ersion)e(2.5:)h(K)n(e)o(yw)o(ord)f(support)g (for)h(parameters)f(w)o(as)208 1219 y(added.)0 1366 y FD(abs)p FJ(\()p FK(x)p FJ(\))208 1466 y FN(Return)f(the)i(absolute)e (v)n(alue)h(of)g(a)h(number)-5 b(.)24 b(The)c(ar)o(gument)e(may)i(be)g (a)h(plain)e(or)i(long)e(inte)o(ger)g(or)h(a)h(\003oating)f(point)f (number)-5 b(.)208 1565 y(If)20 b(the)g(ar)o(gument)e(is)j(a)f(comple)o (x)f(number)m(,)f(its)j(magnitude)d(is)j(returned.)0 1712 y FD(all)p FJ(\()p FK(iter)o(able)p FJ(\))208 1812 y FN(Return)e(T)m(rue)h(if)g(all)h(elements)f(of)g(the)g FK(iter)o(able)g FN(are)g(true.)25 b(Equi)n(v)n(alent)18 b(to:)668 2036 y FA(def)44 b(all\(iterable\):)847 2127 y(for)h(element)e(in)i(iterable:)1027 2219 y(if)f(not)g(element:)1206 2310 y(return)g(False)847 2401 y(return)g(True)208 2649 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 2796 y FD(any)p FJ(\()p FK(iter)o(able)p FJ(\))208 2895 y FN(Return)g(T)m(rue)h(if)g (an)o(y)g(element)f(of)h(the)g FK(iter)o(able)g FN(is)h(true.)k(Equi)n (v)n(alent)18 b(to:)668 3119 y FA(def)44 b(any\(iterable\):)847 3211 y(for)h(element)e(in)i(iterable:)1027 3302 y(if)f(element:)1206 3393 y(return)g(True)847 3485 y(return)g(False)208 3732 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 3879 y FD(basestring)p FJ(\(\))208 3979 y FN(This)27 b(abstract)g(type)f(is)i(the)f (superclass)g(for)f FJ(str)h FN(and)g FJ(unicode)p FN(.)44 b(It)28 b(cannot)e(be)h(called)f(or)h(instantiated,)h(b)n(ut)f(it)h (can)f(be)208 4078 y(used)c(to)g(test)i(whether)d(an)i(object)f(is)h (an)g(instance)f(of)g FJ(str)g FN(or)h FJ(unicode)p FN(.)34 b FJ(isinstance\(obj,)47 b(basestring\))22 b FN(is)208 4178 y(equi)n(v)n(alent)c(to)i FJ(isinstance\(obj,)47 b(\(str,)i(unicode\)\))p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4325 y FD(bool)p FJ(\()p FC([)p FK(x)12 b FC(])p FJ(\))208 4425 y FN(Con)m(v)o(ert)24 b(a)j(v)n(alue)e(to)h(a)g(Boolean,)h(using)e (the)h(standard)f(truth)h(testing)g(procedure.)40 b(If)26 b FK(x)g FN(is)h(f)o(alse)g(or)e(omitted,)i(this)f(returns)208 4524 y FJ(False)p FN(;)g(otherwise)d(it)j(returns)d FJ(True)p FN(.)37 b FJ(bool)24 b FN(is)i(also)e(a)h(class,)h(which)e(is)h(a)g (subclass)g(of)f FJ(int)p FN(.)37 b(Class)26 b FJ(bool)e FN(cannot)g(be)208 4624 y(subclassed)19 b(further)-5 b(.)24 b(Its)d(only)e(instances)h(are)h FJ(False)e FN(and)h FJ(True)p FN(.)208 4757 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.1.)75 b(Changed)19 b(in)i(v)o(ersion)d(2.3:)i(If)g(no)g(ar)o(gument)e(is)j (gi)n(v)o(en,)d(this)j(function)e(returns)g FJ(False)p FN(.)0 4904 y FD(callable)p FJ(\()p FK(object)q FJ(\))208 5003 y FN(Return)h(true)h(if)h(the)f FK(object)i FN(ar)o(gument)c (appears)h(callable,)h(f)o(alse)h(if)g(not.)28 b(If)21 b(this)h(returns)e(true,)h(it)h(is)g(still)h(possible)e(that)g(a)h (call)208 5103 y(f)o(ails,)h(b)n(ut)g(if)g(it)g(is)h(f)o(alse,)g (calling)e FK(object)i FN(will)f(ne)n(v)o(er)e(succeed.)32 b(Note)23 b(that)g(classes)h(are)e(callable)h(\(calling)f(a)h(class)g (returns)f(a)208 5202 y(ne)n(w)e(instance\);)f(class)i(instances)f(are) g(callable)g(if)h(the)o(y)e(ha)n(v)o(e)h(a)h FJ(__call__\(\))d FN(method.)0 5349 y FD(chr)p FJ(\()p FK(i)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(4)2833 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 5 17 TeXDict begin 5 16 bop 208 83 a FN(Return)24 b(a)h(string)f(of)h(one)f (character)f(whose)k FH(A)t(S)t(C)t(I)t(I)h FN(code)c(is)i(the)e(inte)o (ger)g FK(i)p FN(.)39 b(F)o(or)24 b(e)o(xample,)g FJ(chr\(97\))g FN(returns)g(the)h(string)208 183 y FJ('a')p FN(.)i(This)21 b(is)h(the)f(in)m(v)o(erse)f(of)h FJ(ord\(\))p FN(.)27 b(The)21 b(ar)o(gument)e(must)i(be)g(in)g(the)g(range)f([0..255],)e (inclusi)n(v)o(e;)j FJ(ValueError)f FN(will)208 282 y(be)g(raised)g(if) g FK(i)h FN(is)g(outside)f(that)g(range.)0 429 y FD(classmethod)p FJ(\()p FK(function)p FJ(\))208 529 y FN(Return)f(a)i(class)g(method)e (for)g FK(function)p FN(.)208 661 y(A)k(class)g(method)f(recei)n(v)o (es)f(the)i(class)h(as)f(implicit)g(\002rst)g(ar)o(gument,)e(just)i (lik)o(e)g(an)f(instance)g(method)g(recei)n(v)o(es)g(the)g(instance.) 208 761 y(T)-7 b(o)20 b(declare)f(a)i(class)g(method,)e(use)h(this)h (idiom:)444 985 y FA(class)44 b(C:)623 1076 y(@classmethod)623 1167 y(def)g(f\(cls,)g(arg1,)g(arg2,)g(...\):)g(...)208 1357 y FN(The)21 b FJ(@classmethod)g FN(form)g(is)i(a)g(function)e (decorator)f(\226)i(see)h(the)f(description)f(of)h(function)f (de\002nitions)g(in)h(chapter)g(7)g(of)208 1456 y(the)e FK(Python)f(Refer)m(ence)g(Manual)g FN(for)h(details.)208 1589 y(It)27 b(can)h(be)g(called)f(either)g(on)g(the)h(class)h(\(such)e (as)h FJ(C.f\(\))p FN(\))f(or)g(on)h(an)f(instance)g(\(such)g(as)i FJ(C\(\).f\(\))p FN(\).)46 b(The)27 b(instance)h(is)208 1688 y(ignored)20 b(e)o(xcept)h(for)h(its)i(class.)32 b(If)22 b(a)h(class)g(method)e(is)i(called)g(for)e(a)i(deri)n(v)o(ed)e (class,)i(the)g(deri)n(v)o(ed)d(class)j(object)f(is)i(passed)e(as)208 1788 y(the)e(implied)f(\002rst)i(ar)o(gument.)208 1921 y(Class)f(methods)e(are)h(dif)n(ferent)e(than)i(C)1350 1914 y(++)1464 1921 y(or)f(Ja)n(v)n(a)i(static)g(methods.)j(If)c(you)f (w)o(ant)h(those,)g(see)h FJ(staticmethod\(\))d FN(in)i(this)208 2020 y(section.)208 2153 y(F)o(or)25 b(more)h(information)e(on)i(class) h(methods,)f(consult)g(the)g(documentation)d(on)j(the)h(standard)e (type)g(hierarchy)f(in)j(chapter)208 2252 y(3)d(of)h(the)f FK(Python)g(Refer)m(ence)g(Manual)f FN(\(at)i(the)g(bottom\).)75 b(Ne)n(w)25 b(in)g(v)o(ersion)e(2.2.)116 b(Changed)24 b(in)g(v)o(ersion)g(2.4:)g(Function)208 2352 y(decorator)18 b(syntax)h(added.)0 2499 y FD(cmp)p FJ(\()p FK(x,)h(y)p FJ(\))208 2599 y FN(Compare)f(the)h(tw)o(o)g(objects)g FK(x)h FN(and)f FK(y)h FN(and)e(return)g(an)h(inte)o(ger)f(according)g (to)h(the)g(outcome.)k(The)c(return)f(v)n(alue)g(is)i(ne)o(gati)n(v)o (e)d(if)208 2698 y FK(x)49 b FJ(<)h FK(y)p FN(,)20 b(zero)g(if)h FK(x)50 b FJ(==)f FK(y)21 b FN(and)e(strictly)i(positi)n(v)o(e)e(if)h FK(x)50 b FJ(>)g FK(y)p FN(.)0 2845 y FD(compile)p FJ(\()p FK(string)o(,)19 b(\002lename)o(,)g(kind)r FC([)p FK(,)g(\003a)o(gs)p FC([)p FK(,)h(dont)p 1573 2845 25 4 v 28 w(inherit)13 b FC(])f(])p FJ(\))208 2945 y FN(Compile)17 b(the)g FK(string)h FN(into)f(a)h(code)e(object.)24 b(Code)17 b(objects)g(can)h(be)f(e)o(x) o(ecuted)e(by)i(an)h FJ(exec)f FN(statement)g(or)g(e)n(v)n(aluated)f (by)h(a)h(call)208 3044 y(to)i FJ(eval\(\))p FN(.)k(The)c FK(\002lename)f FN(ar)o(gument)f(should)h(gi)n(v)o(e)h(the)g(\002le)h (from)e(which)h(the)g(code)f(w)o(as)i(read;)f(pass)h(some)f (recognizable)208 3144 y(v)n(alue)e(if)i(it)g(w)o(asn')o(t)f(read)g (from)f(a)i(\002le)g(\()p FJ('')e FN(is)i(commonly)d(used\).)24 b(The)19 b FK(kind)i FN(ar)o(gument)c(speci\002es)j(what)f(kind)g(of) 208 3244 y(code)h(must)h(be)g(compiled;)e(it)j(can)f(be)g FJ('exec')f FN(if)h FK(string)g FN(consists)h(of)e(a)i(sequence)d(of)i (statements,)g FJ('eval')f FN(if)h(it)h(consists)208 3343 y(of)17 b(a)i(single)f(e)o(xpression,)e(or)i FJ('single')f FN(if)h(it)h(consists)f(of)g(a)g(single)g(interacti)n(v)o(e)f (statement)h(\(in)f(the)h(latter)h(case,)f(e)o(xpression)208 3443 y(statements)i(that)g(e)n(v)n(aluate)f(to)i(something)d(else)j (than)f FJ(None)g FN(will)h(be)f(printed\).)208 3575 y(When)f(compiling)e(multi-line)h(statements,)h(tw)o(o)h(ca)n(v)o(eats) f(apply:)24 b(line)19 b(endings)f(must)h(be)g(represented)f(by)h(a)g (single)g(ne)n(wline)208 3675 y(character)31 b(\()p FJ('\\n')p FN(\),)j(and)d(the)i(input)e(must)i(be)f(terminated)f(by)h(at)g(least)h (one)f(ne)n(wline)g(character)-5 b(.)60 b(If)32 b(line)h(endings)e(are) 208 3775 y(represented)18 b(by)i FJ('\\r\\n')p FN(,)f(use)i(the)f (string)g FJ(replace\(\))f FN(method)g(to)h(change)f(them)h(into)f FJ('\\n')p FN(.)208 3907 y(The)24 b(optional)g(ar)o(guments)f FK(\003a)o(gs)i FN(and)f FK(dont)p 1511 3907 V 29 w(inherit)i FN(\(which)e(are)h(ne)n(w)g(in)g(Python)f(2.2\))g(control)g(which)h (future)e(statements)208 4007 y(\(see)d(PEP)h(236\))f(af)n(fect)g(the)g (compilation)f(of)h FK(string)p FN(.)26 b(If)21 b(neither)e(is)j (present)e(\(or)g(both)f(are)i(zero\))e(the)i(code)f(is)h(compiled)e (with)208 4106 y(those)k(future)f(statements)i(that)f(are)h(in)f(ef)n (fect)g(in)h(the)g(code)e(that)i(is)g(calling)f(compile.)34 b(If)24 b(the)f FK(\003a)o(gs)g FN(ar)o(gument)e(is)k(gi)n(v)o(en)d (and)208 4206 y FK(dont)p 362 4206 V 28 w(inherit)h FN(is)f(not)f(\(or) f(is)i(zero\))e(then)h(the)g(future)f(statements)h(speci\002ed)g(by)g (the)g FK(\003a)o(gs)g FN(ar)o(gument)d(are)j(used)g(in)h(addition)d (to)208 4306 y(those)i(that)h(w)o(ould)f(be)h(used)g(an)o(yw)o(ay)-5 b(.)28 b(If)21 b FK(dont)p 1590 4306 V 29 w(inherit)i FN(is)g(a)f(non-zero)e(inte)o(ger)h(then)g(the)h FK(\003a)o(gs)f FN(ar)o(gument)f(is)i(it)h(\226)f(the)g(future)208 4405 y(statements)e(in)g(ef)n(fect)g(around)e(the)i(call)h(to)f(compile)g (are)g(ignored.)208 4538 y(Future)g(statements)i(are)g(speci\002ed)f (by)g(bits)h(which)f(can)h(be)f(bitwise)h(or)n(-ed)f(together)f(to)i (specify)f(multiple)g(statements.)29 b(The)208 4637 y(bit\002eld)22 b(required)e(to)i(specify)g(a)g(gi)n(v)o(en)f(feature)h(can)g(be)g (found)e(as)j(the)f FJ(compiler_flag)f FN(attrib)n(ute)g(on)h(the)g FJ(_Feature)208 4737 y FN(instance)d(in)i(the)f FJ(__future__)f FN(module.)0 4884 y FD(complex)p FJ(\()p FC([)p FK(r)m(eal)p FC([)p FK(,)f(ima)o(g)12 b FC(])g(])p FJ(\))208 4984 y FN(Create)23 b(a)h(comple)o(x)e(number)g(with)h(the)h(v)n(alue)f FK(r)m(eal)g FN(+)h FK(ima)o(g)p FN(*j)f(or)g(con)m(v)o(ert)f(a)i (string)f(or)g(number)f(to)i(a)f(comple)o(x)f(number)-5 b(.)34 b(If)208 5083 y(the)18 b(\002rst)h(parameter)e(is)i(a)g(string,) g(it)g(will)g(be)f(interpreted)f(as)i(a)g(comple)o(x)e(number)f(and)i (the)g(function)f(must)i(be)f(called)g(without)208 5183 y(a)28 b(second)f(parameter)-5 b(.)48 b(The)28 b(second)g(parameter)e (can)i(ne)n(v)o(er)f(be)h(a)h(string.)48 b(Each)28 b(ar)o(gument)e(may) i(be)g(an)o(y)f(numeric)g(type)208 5282 y(\(including)f(comple)o(x\).) 46 b(If)28 b FK(ima)o(g)g FN(is)h(omitted,)g(it)g(def)o(aults)f(to)g (zero)f(and)h(the)g(function)e(serv)o(es)i(as)h(a)g(numeric)d(con)m(v)o (ersion)208 5382 y(function)18 b(lik)o(e)i FJ(int\(\))p FN(,)g FJ(long\(\))g FN(and)f FJ(float\(\))p FN(.)25 b(If)20 b(both)f(ar)o(guments)f(are)i(omitted,)f(returns)h FJ(0j)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)3027 b(5)p eop end %%Page: 6 18 TeXDict begin 6 17 bop 0 83 a FD(delattr)p FJ(\()p FK(object,)18 b(name)p FJ(\))208 183 y FN(This)g(is)i(a)f(relati)n(v)o(e)f(of)h FJ(setattr\(\))p FN(.)k(The)c(ar)o(guments)d(are)j(an)g(object)f(and)g (a)h(string.)24 b(The)19 b(string)f(must)h(be)g(the)f(name)h(of)f(one) 208 282 y(of)k(the)g(object')-5 b(s)22 b(attrib)n(utes.)32 b(The)22 b(function)e(deletes)j(the)f(named)f(attrib)n(ute,)h(pro)o (vided)e(the)j(object)e(allo)n(ws)i(it.)32 b(F)o(or)22 b(e)o(xample,)208 382 y FJ(delattr\()p FK(x)p FJ(,)48 b(')p FK(foobar)r FJ('\))18 b FN(is)j(equi)n(v)n(alent)e(to)h FJ(del)50 b FK(x)p FJ(.)p FK(foobar)r FN(.)0 529 y FD(dict)p FJ(\()p FC([)p FK(ar)m(g)12 b FC(])p FJ(\))208 628 y FN(Return)18 b(a)h(ne)n(w)g(dictionary)e(initialized)i(from)e(an)i (optional)f(positional)g(ar)o(gument)e(or)j(from)f(a)h(set)h(of)e(k)o (e)o(yw)o(ord)f(ar)o(guments.)23 b(If)208 728 y(no)16 b(ar)o(guments)e(are)j(gi)n(v)o(en,)f(return)f(a)i(ne)n(w)f(empty)g (dictionary)-5 b(.)22 b(If)16 b(the)h(positional)e(ar)o(gument)g FK(ar)m(g)h FN(is)h(a)g(mapping)e(object,)i(return)208 828 y(a)25 b(dictionary)f(mapping)f(the)i(same)g(k)o(e)o(ys)g(to)g(the) h(same)f(v)n(alues)g(as)h(does)f(the)g(mapping)e(object.)39 b(Otherwise)25 b(the)g(positional)208 927 y(ar)o(gument)h(must)j(be)f (a)h(sequence,)h(a)f(container)e(that)i(supports)f(iteration,)h(or)g (an)f(iterator)g(object.)50 b(The)29 b(elements)f(of)h(the)208 1027 y(ar)o(gument)20 b(must)i(each)g(also)h(be)f(of)g(one)g(of)g (those)g(kinds,)g(and)g(each)g(must)g(in)h(turn)e(contain)h(e)o(xactly) f(tw)o(o)i(objects.)31 b(The)22 b(\002rst)208 1127 y(is)g(used)e(as)i (a)g(k)o(e)o(y)e(in)i(the)f(ne)n(w)g(dictionary)-5 b(,)19 b(and)h(the)h(second)g(as)g(the)h(k)o(e)o(y')-5 b(s)20 b(v)n(alue.)27 b(If)21 b(a)h(gi)n(v)o(en)e(k)o(e)o(y)g(is)i(seen)g (more)e(than)g(once,)208 1226 y(the)g(last)h(v)n(alue)e(associated)h (with)h(it)g(is)g(retained)e(in)h(the)g(ne)n(w)g(dictionary)-5 b(.)208 1355 y(If)19 b(k)o(e)o(yw)o(ord)f(ar)o(guments)g(are)i(gi)n(v)o (en,)e(the)i(k)o(e)o(yw)o(ords)e(themselv)o(es)i(with)g(their)f (associated)h(v)n(alues)f(are)h(added)f(as)h(items)h(to)f(the)208 1455 y(dictionary)-5 b(.)22 b(If)d(a)g(k)o(e)o(y)g(is)h(speci\002ed)f (both)f(in)h(the)g(positional)g(ar)o(gument)d(and)j(as)h(a)f(k)o(e)o (yw)o(ord)f(ar)o(gument,)e(the)j(v)n(alue)g(associated)208 1554 y(with)26 b(the)h(k)o(e)o(yw)o(ord)e(is)i(retained)f(in)h(the)f (dictionary)-5 b(.)42 b(F)o(or)27 b(e)o(xample,)f(these)h(all)g(return) f(a)h(dictionary)e(equal)h(to)g FJ({"one":)208 1654 y(2,)49 b("two":)99 b(3})p FN(:)349 1859 y FM(\017)o FJ(dict\({'one':)f(2,)49 b('two':)99 b(3}\))349 1984 y FM(\017)o FJ(dict\({'one':)f(2,)49 b('two':)99 b(3}.items\(\)\))349 2108 y FM(\017)o FJ(dict\({'one':)f (2,)49 b('two':)99 b(3}.iteritems\(\)\))349 2233 y FM(\017)o FJ(dict\(zip\(\('one',)47 b('two'\),)i(\(2,)g(3\)\)\))349 2358 y FM(\017)o FJ(dict\([['two',)f(3],)h(['one',)f(2]]\))349 2482 y FM(\017)o FJ(dict\(one=2,)g(two=3\))349 2607 y FM(\017)o FJ(dict\([\(['one',)f('two'][i-2],)h(i\))h(for)h(i)f(in)h (\(2,)f(3\)]\))208 2812 y FN(Ne)n(w)18 b(in)g(v)o(ersion)f(2.2.)74 b(Changed)16 b(in)j(v)o(ersion)d(2.3:)i(Support)f(for)g(b)n(uilding)g (a)h(dictionary)f(from)g(k)o(e)o(yw)o(ord)f(ar)o(guments)g(added.)0 2959 y FD(dir)p FJ(\()p FC([)p FK(object)d FC(])p FJ(\))208 3058 y FN(W)m(ithout)25 b(ar)o(guments,)g(return)f(the)i(list)h(of)e (names)h(in)g(the)g(current)e(local)i(symbol)f(table.)41 b(W)m(ith)26 b(an)g(ar)o(gument,)f(attempts)g(to)208 3158 y(return)15 b(a)i(list)h(of)f(v)n(alid)f(attrib)n(utes)h(for)f (that)h(object.)23 b(This)17 b(information)d(is)k(gleaned)d(from)h(the) h(object')-5 b(s)16 b FJ(__dict__)g FN(attrib)n(ute,)208 3258 y(if)h(de\002ned,)f(and)h(from)f(the)h(class)h(or)f(type)g (object.)23 b(The)17 b(list)h(is)g(not)f(necessarily)f(complete.)23 b(If)17 b(the)g(object)g(is)h(a)g(module)d(object,)208 3357 y(the)21 b(list)h(contains)f(the)g(names)g(of)g(the)g(module')-5 b(s)21 b(attrib)n(utes.)28 b(If)21 b(the)g(object)g(is)h(a)g(type)e(or) h(class)i(object,)d(the)i(list)g(contains)f(the)208 3457 y(names)26 b(of)h(its)h(attrib)n(utes,)h(and)d(recursi)n(v)o(ely)f(of)i (the)g(attrib)n(utes)g(of)g(its)h(bases.)46 b(Otherwise,)28 b(the)f(list)h(contains)f(the)g(object')-5 b(s)208 3557 y(attrib)n(utes')22 b(names,)g(the)g(names)h(of)f(its)h(class')-5 b(s)24 b(attrib)n(utes,)f(and)e(recursi)n(v)o(ely)g(of)h(the)g(attrib)n (utes)h(of)f(its)h(class')-5 b(s)24 b(base)f(classes.)208 3656 y(The)c(resulting)h(list)h(is)g(sorted)f(alphabetically)-5 b(.)23 b(F)o(or)c(e)o(xample:)444 3876 y FA(>>>)44 b(import)g(struct) 444 3968 y(>>>)g(dir\(\))444 4059 y(['__builtins__',)e('__doc__',)h ('__name__',)g('struct'])444 4150 y(>>>)h(dir\(struct\))444 4242 y(['__doc__',)f('__name__',)g('calcsize',)g('error',)g('pack',)h ('unpack'])208 4427 y FL(Note:)24 b FN(Because)d FJ(dir\(\))f FN(is)h(supplied)f(primarily)e(as)k(a)e(con)m(v)o(enience)e(for)i(use)g (at)h(an)f(interacti)n(v)o(e)f(prompt,)g(it)i(tries)g(to)g(supply)208 4527 y(an)f(interesting)f(set)j(of)e(names)g(more)g(than)g(it)h(tries)g (to)f(supply)g(a)h(rigorously)d(or)i(consistently)g(de\002ned)f(set)j (of)e(names,)g(and)g(its)208 4626 y(detailed)f(beha)n(vior)g(may)g (change)g(across)i(releases.)0 4773 y FD(divmod)p FJ(\()p FK(a,)e(b)p FJ(\))208 4873 y FN(T)-7 b(ak)o(e)26 b(tw)o(o)h(\(non)e (comple)o(x\))f(numbers)h(as)i(ar)o(guments)d(and)i(return)f(a)i(pair)f (of)g(numbers)e(consisting)i(of)g(their)g(quotient)f(and)208 4972 y(remainder)18 b(when)h(using)g(long)g(di)n(vision.)24 b(W)m(ith)d(mix)o(ed)d(operand)g(types,)i(the)g(rules)g(for)f(binary)g (arithmetic)g(operators)f(apply)-5 b(.)208 5072 y(F)o(or)18 b(plain)g(and)h(long)f(inte)o(gers,)f(the)i(result)g(is)h(the)f(same)g (as)g FJ(\()p FK(a)49 b FJ(//)h FK(b)p FJ(,)f FK(a)g FJ(\045)h FK(b)p FJ(\))p FN(.)24 b(F)o(or)18 b(\003oating)g(point)g (numbers)g(the)h(result)208 5172 y(is)g FJ(\()p FK(q)p FJ(,)49 b FK(a)g FJ(\045)h FK(b)p FJ(\))p FN(,)18 b(where)g FK(q)h FN(is)g(usually)f FJ(math.floor\()p FK(a)47 b FJ(/)j FK(b)p FJ(\))18 b FN(b)n(ut)h(may)f(be)g(1)h(less)h(than)e (that.)24 b(In)18 b(an)o(y)g(case)h FK(q)3659 5187 y FJ(*)3759 5172 y FK(b)49 b FJ(+)208 5271 y FK(a)g FJ(\045)h FK(b)17 b FN(is)h(v)o(ery)d(close)j(to)f FK(a)p FN(,)g(if)g FK(a)50 b FJ(\045)f FK(b)17 b FN(is)h(non-zero)d(it)j(has)f(the)g(same) g(sign)g(as)h FK(b)p FN(,)f(and)g FJ(0)49 b(<=)h(abs\()p FK(a)e FJ(\045)i FK(b)p FJ(\))f(<)h(abs\()p FK(b)p FJ(\))p FN(.)208 5400 y(Changed)18 b(in)j(v)o(ersion)e(2.3:)g(Using)h FJ(divmod\(\))g FN(with)g(comple)o(x)e(numbers)h(is)i(deprecated.)p 0 5549 3901 4 v 0 5649 a FI(6)2833 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 7 19 TeXDict begin 7 18 bop 0 83 a FD(enumerate)p FJ(\()p FK(iter)o(able)p FJ(\))208 183 y FN(Return)29 b(an)h(enumerate)f (object.)54 b FK(iter)o(able)30 b FN(must)g(be)h(a)f(sequence,)h(an)g (iterator)m(,)g(or)f(some)g(other)f(object)h(which)g(supports)208 282 y(iteration.)38 b(The)24 b FJ(next\(\))g FN(method)g(of)g(the)h (iterator)f(returned)f(by)i FJ(enumerate\(\))e FN(returns)h(a)h(tuple)f (containing)f(a)j(count)208 382 y(\(from)f(zero\))i(and)g(the)g (corresponding)d(v)n(alue)i(obtained)g(from)g(iterating)h(o)o(v)o(er)f FK(iter)o(able)p FN(.)45 b FJ(enumerate\(\))26 b FN(is)i(useful)f(for) 208 482 y(obtaining)18 b(an)i(inde)o(x)o(ed)e(series:)26 b FJ(\(0,)49 b(seq[0]\))p FN(,)20 b FJ(\(1,)49 b(seq[1]\))p FN(,)19 b FJ(\(2,)49 b(seq[2]\))p FN(,)19 b(.)12 b(.)g(.)g(.)52 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 628 y FD(eval)p FJ(\()p FK(e)n(xpr)m(ession)p FC([)p FK(,)g(globals)p FC([)p FK(,)g(locals)12 b FC(])g(])p FJ(\))208 728 y FN(The)j(ar)o(guments)f(are)i(a)g(string)g(and)f(optional)f(globals)i (and)f(locals.)24 b(If)15 b(pro)o(vided,)f FK(globals)h FN(must)h(be)g(a)g(dictionary)-5 b(.)22 b(If)15 b(pro)o(vided,)208 828 y FK(locals)20 b FN(can)g(be)g(an)o(y)f(mapping)f(object.)51 b(Changed)19 b(in)h(v)o(ersion)f(2.4:)g(formerly)g FK(locals)h FN(w)o(as)h(required)d(to)i(be)h(a)f(dictionary)-5 b(.)208 960 y(The)19 b FK(e)n(xpr)m(ession)i FN(ar)o(gument)d(is)j(parsed)e (and)h(e)n(v)n(aluated)f(as)i(a)f(Python)g(e)o(xpression)e (\(technically)h(speaking,)g(a)h(condition)f(list\))208 1060 y(using)26 b(the)h FK(globals)f FN(and)g FK(locals)h FN(dictionaries)f(as)h(global)f(and)h(local)f(name)h(space.)45 b(If)26 b(the)h FK(globals)f FN(dictionary)f(is)j(present)208 1160 y(and)g(lacks)i(')p 591 1160 25 4 v 620 1160 V 59 w(b)n(uiltins)p 898 1160 V 927 1160 V 59 w(',)i(the)d(current)f (globals)g(are)h(copied)f(into)h FK(globals)f FN(before)g FK(e)n(xpr)m(ession)h FN(is)h(parsed.)52 b(This)29 b(means)208 1259 y(that)e FK(e)n(xpr)m(ession)g FN(normally)e(has)i(full)g(access)g (to)h(the)f(standard)e FJ(__builtin__)h FN(module)f(and)i(restricted)f (en)m(vironments)208 1359 y(are)d(propagated.)33 b(If)24 b(the)g FK(locals)f FN(dictionary)f(is)j(omitted)e(it)i(def)o(aults)e (to)h(the)g FK(globals)f FN(dictionary)-5 b(.)33 b(If)24 b(both)f(dictionaries)g(are)208 1458 y(omitted,)g(the)g(e)o(xpression)e (is)k(e)o(x)o(ecuted)c(in)i(the)h(en)m(vironment)c(where)i FJ(eval)i FN(is)g(called.)34 b(The)23 b(return)f(v)n(alue)g(is)i(the)g (result)f(of)208 1558 y(the)d(e)n(v)n(aluated)f(e)o(xpression.)k (Syntax)c(errors)h(are)g(reported)e(as)j(e)o(xceptions.)i(Example:)444 1782 y FA(>>>)44 b(x)h(=)f(1)444 1873 y(>>>)g(print)g(eval\('x+1'\))444 1965 y(2)208 2154 y FN(This)19 b(function)f(can)h(also)g(be)g(used)g (to)h(e)o(x)o(ecute)e(arbitrary)f(code)i(objects)g(\(such)g(as)g(those) h(created)e(by)h FJ(compile\(\))p FN(\).)k(In)c(this)208 2254 y(case)24 b(pass)g(a)g(code)f(object)g(instead)g(of)g(a)h(string.) 35 b(The)23 b(code)g(object)g(must)h(ha)n(v)o(e)f(been)g(compiled)f (passing)h FJ('eval')g FN(as)i(the)208 2353 y FK(kind)d FN(ar)o(gument.)208 2486 y(Hints:)42 b(dynamic)27 b(e)o(x)o(ecution)f (of)i(statements)h(is)g(supported)e(by)h(the)g FJ(exec)h FN(statement.)49 b(Ex)o(ecution)27 b(of)h(statements)h(from)208 2585 y(a)h(\002le)g(is)h(supported)d(by)h(the)h FJ(execfile\(\))f FN(function.)52 b(The)29 b FJ(globals\(\))g FN(and)g FJ(locals\(\))g FN(functions)g(returns)g(the)208 2685 y(current)d(global)g(and)h(local)g(dictionary)-5 b(,)27 b(respecti)n(v)o(ely)-5 b(,)27 b(which)g(may)g(be)h(useful)e(to)i(pass) g(around)d(for)i(use)h(by)f FJ(eval\(\))g FN(or)208 2785 y FJ(execfile\(\))p FN(.)0 2932 y FD(execfile)p FJ(\()p FK(\002lename)p FC([)p FK(,)17 b(globals)p FC([)p FK(,)i(locals)12 b FC(])g(])p FJ(\))208 3031 y FN(This)29 b(function)e(is)j(similar)g (to)f(the)g FJ(exec)g FN(statement,)i(b)n(ut)e(parses)g(a)h(\002le)g (instead)f(of)f(a)i(string.)51 b(It)30 b(is)g(dif)n(ferent)d(from)i (the)208 3131 y FJ(import)17 b FN(statement)h(in)g(that)g(it)h(does)f (not)g(use)g(the)g(module)f(administration)f(\227)j(it)g(reads)f(the)g (\002le)g(unconditionally)d(and)j(does)208 3230 y(not)h(create)h(a)h (ne)n(w)f(module.)1040 3200 y FF(2)208 3363 y FN(The)i(ar)o(guments)e (are)j(a)g(\002le)g(name)f(and)g(tw)o(o)h(optional)f(dictionaries.)31 b(The)22 b(\002le)h(is)h(parsed)e(and)g(e)n(v)n(aluated)f(as)i(a)g (sequence)f(of)208 3463 y(Python)f(statements)i(\(similarly)g(to)g(a)g (module\))f(using)g(the)h FK(globals)f FN(and)g FK(locals)h FN(dictionaries)f(as)i(global)e(and)g(local)h(names-)208 3562 y(pace.)41 b(If)26 b(pro)o(vided,)f FK(locals)h FN(can)f(be)h(an)o(y)f(mapping)f(object.)85 b(Changed)25 b(in)h(v)o(ersion)e(2.4:)i(formerly)e FK(locals)i FN(w)o(as)g(required) 208 3662 y(to)d(be)h(a)g(dictionary)-5 b(.)70 b(If)24 b(the)g FK(locals)f FN(dictionary)f(is)j(omitted)e(it)i(def)o(aults)e (to)h(the)g FK(globals)f FN(dictionary)-5 b(.)33 b(If)24 b(both)f(dictionaries)208 3762 y(are)g(omitted,)g(the)g(e)o(xpression)f (is)j(e)o(x)o(ecuted)c(in)j(the)f(en)m(vironment)d(where)j FJ(execfile\(\))f FN(is)i(called.)35 b(The)23 b(return)f(v)n(alue)h(is) 208 3861 y FJ(None)p FN(.)208 3994 y FL(W)-5 b(ar)o(ning:)22 b FN(The)16 b(def)o(ault)g FK(locals)g FN(act)h(as)g(described)e(for)h (function)f FJ(locals\(\))h FN(belo)n(w:)23 b(modi\002cations)15 b(to)h(the)h(def)o(ault)f FK(locals)208 4093 y FN(dictionary)21 b(should)h(not)h(be)g(attempted.)33 b(P)o(ass)24 b(an)f(e)o(xplicit)g FK(locals)g FN(dictionary)e(if)j(you)e(need)g(to)i(see)f(ef)n(fects)g (of)g(the)g(code)g(on)208 4193 y FK(locals)31 b FN(after)f(function)g FJ(execfile\(\))g FN(returns.)56 b FJ(execfile\(\))30 b FN(cannot)g(be)h(used)g(reliably)g(to)g(modify)e(a)j(function')-5 b(s)208 4293 y(locals.)0 4440 y FD(file)p FJ(\()p FK(\002lename)p FC([)p FK(,)18 b(mode)p FC([)p FK(,)h(b)n(ufsize)12 b FC(])g(])p FJ(\))208 4539 y FN(Constructor)28 b(function)h(for)g(the)h FJ(file)g FN(type,)i(described)d(further)f(in)i(section)g(3.9,)i (\223File)f(Objects\224.)54 b(The)30 b(constructor')-5 b(s)208 4639 y(ar)o(guments)18 b(are)i(the)g(same)g(as)h(those)f(of)g (the)g FJ(open\(\))g FN(b)n(uilt-in)g(function)e(described)h(belo)n(w) -5 b(.)208 4772 y(When)20 b(opening)f(a)i(\002le,)g(it')-5 b(s)22 b(preferable)d(to)i(use)g FJ(open\(\))f FN(instead)h(of)f(in)m (v)n(oking)f(this)i(constructor)e(directly)-5 b(.)25 b FJ(file)c FN(is)g(more)208 4871 y(suited)f(to)g(type)g(testing)g (\(for)f(e)o(xample,)g(writing)g(`)p FJ(isinstance\(f,)47 b(file\))p FN('\).)208 5004 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 5151 y FD(filter)p FJ(\()p FK(function,)e(iter)o(able)p FJ(\))208 5250 y FN(Construct)26 b(a)i(list)g(from)e(those)i(elements)f (of)g FK(iter)o(able)f FN(for)h(which)g FK(function)f FN(returns)g(true.)46 b FK(iter)o(able)27 b FN(may)f(be)i(either)f(a)g (se-)p 0 5321 1560 4 v 90 5377 a FB(2)120 5400 y FH(It)17 b(is)g(used)g(relati)n(v)o(ely)k(rarely)d(so)f(does)g(not)h(w)o(arrant) h(being)f(made)f(into)h(a)f(statement.)p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)3027 b(7)p eop end %%Page: 8 20 TeXDict begin 8 19 bop 208 83 a FN(quence,)22 b(a)j(container)d(which)h (supports)f(iteration,)i(or)f(an)h(iterator)m(,)f(If)h FK(iter)o(able)f FN(is)h(a)g(string)g(or)f(a)h(tuple,)g(the)g(result)f (also)h(has)208 183 y(that)c(type;)f(otherwise)g(it)i(is)g(al)o(w)o (ays)f(a)g(list.)26 b(If)20 b FK(function)e FN(is)j FJ(None)p FN(,)f(the)g(identity)f(function)f(is)j(assumed,)e(that)h(is,)g(all)h (elements)208 282 y(of)e FK(iter)o(able)h FN(that)h(are)f(f)o(alse)g (are)g(remo)o(v)o(ed.)208 415 y(Note)80 b(that)h FJ(filter\(function,) 47 b FK(iter)o(able)p FJ(\))80 b FN(is)i(equi)n(v)n(alent)d(to)i FJ([item)49 b(for)g(item)g(in)h FK(iter)o(able)e FJ(if)208 515 y(function\(item\)])57 b FN(if)k(function)d(is)j(not)e FJ(None)h FN(and)g FJ([item)49 b(for)g(item)g(in)g FK(iter)o(able)g FJ(if)h(item])59 b FN(if)208 614 y(function)18 b(is)j FJ(None)p FN(.)0 761 y FD(float)p FJ(\()p FC([)p FK(x)12 b FC(])p FJ(\))208 861 y FN(Con)m(v)o(ert)25 b(a)j(string)f(or)h(a)f (number)f(to)i(\003oating)e(point.)46 b(If)27 b(the)h(ar)o(gument)d(is) j(a)g(string,)h(it)f(must)f(contain)g(a)g(possibly)g(signed)208 960 y(decimal)d(or)g(\003oating)g(point)g(number)m(,)f(possibly)h (embedded)e(in)j(whitespace.)37 b(Otherwise,)26 b(the)e(ar)o(gument)e (may)i(be)h(a)g(plain)208 1060 y(or)g(long)h(inte)o(ger)f(or)h(a)g (\003oating)g(point)f(number)m(,)g(and)h(a)g(\003oating)g(point)f (number)g(with)h(the)g(same)g(v)n(alue)g(\(within)f(Python')-5 b(s)208 1160 y(\003oating)19 b(point)g(precision\))g(is)i(returned.)i (If)e(no)e(ar)o(gument)f(is)j(gi)n(v)o(en,)e(returns)g FJ(0.0)p FN(.)208 1293 y FL(Note:)31 b FN(When)24 b(passing)f(in)h(a)g (string,)g(v)n(alues)g(for)f(NaN)h(and)f(In\002nity)g(may)g(be)h (returned,)e(depending)f(on)j(the)g(underlying)d(C)208 1392 y(library)-5 b(.)33 b(The)23 b(speci\002c)h(set)h(of)e(strings)h (accepted)e(which)h(cause)h(these)g(v)n(alues)f(to)g(be)h(returned)e (depends)g(entirely)h(on)g(the)h(C)208 1492 y(library)19 b(and)g(is)i(kno)n(wn)e(to)h(v)n(ary)-5 b(.)0 1639 y FD(frozenset)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 1738 y FN(Return)30 b(a)i(frozenset)d(object)i(whose)g (elements)f(are)h(tak)o(en)g(from)f FK(iter)o(able)p FN(.)57 b(Frozensets)30 b(are)h(sets)i(that)e(ha)n(v)o(e)f(no)h(update) 208 1838 y(methods)17 b(b)n(ut)i(can)g(be)f(hashed)g(and)g(used)h(as)g (members)f(of)g(other)g(sets)i(or)f(as)g(dictionary)e(k)o(e)o(ys.)24 b(The)19 b(elements)f(of)h(a)g(frozenset)208 1938 y(must)i(be)h (immutable)e(themselv)o(es.)28 b(T)-7 b(o)21 b(represent)g(sets)h(of)g (sets,)g(the)g(inner)e(sets)j(should)e(also)g(be)h FJ(frozenset)e FN(objects.)29 b(If)208 2037 y FK(iter)o(able)19 b FN(is)i(not)f (speci\002ed,)g(returns)f(a)i(ne)n(w)f(empty)f(set,)i FJ(frozenset\([]\))p FN(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 2184 y FD(getattr)p FJ(\()p FK(object,)g(name)p FC([)p FK(,)h(default)13 b FC(])p FJ(\))208 2284 y FN(Return)27 b(the)i(v)n(alue)e(of)h(the)g(named)f(attrib)n(uted)h(of)g FK(object)q FN(.)49 b FK(name)27 b FN(must)h(be)h(a)f(string.)49 b(If)28 b(the)g(string)g(is)h(the)g(name)e(of)h(one)208 2383 y(of)f(the)g(object')-5 b(s)27 b(attrib)n(utes,)i(the)f(result)f (is)h(the)g(v)n(alue)e(of)i(that)f(attrib)n(ute.)46 b(F)o(or)27 b(e)o(xample,)h FJ(getattr\(x,)48 b('foobar'\))208 2483 y FN(is)28 b(equi)n(v)n(alent)e(to)h FJ(x.foobar)p FN(.)46 b(If)27 b(the)h(named)e(attrib)n(ute)h(does)g(not)h(e)o(xist,)h FK(default)f FN(is)g(returned)e(if)i(pro)o(vided,)e(otherwise)208 2583 y FJ(AttributeError)18 b FN(is)j(raised.)0 2729 y FD(globals)p FJ(\(\))208 2829 y FN(Return)k(a)h(dictionary)e (representing)f(the)j(current)f(global)f(symbol)h(table.)41 b(This)26 b(is)h(al)o(w)o(ays)f(the)g(dictionary)e(of)h(the)h(current) 208 2929 y(module)f(\(inside)h(a)h(function)e(or)h(method,)h(this)g(is) h(the)e(module)g(where)g(it)h(is)g(de\002ned,)g(not)g(the)f(module)g (from)f(which)h(it)i(is)208 3028 y(called\).)0 3175 y FD(hasattr)p FJ(\()p FK(object,)18 b(name)p FJ(\))208 3275 y FN(The)25 b(ar)o(guments)g(are)h(an)g(object)f(and)h(a)h (string.)42 b(The)26 b(result)g(is)i FJ(True)e FN(if)g(the)g(string)g (is)h(the)f(name)g(of)g(one)g(of)g(the)g(object')-5 b(s)208 3374 y(attrib)n(utes,)29 b FJ(False)e FN(if)h(not.)46 b(\(This)28 b(is)g(implemented)e(by)h(calling)g FJ(getattr\()p FK(object)q FJ(,)47 b FK(name)p FJ(\))27 b FN(and)g(seeing)g(whether)g (it)208 3474 y(raises)20 b(an)g(e)o(xception)f(or)h(not.\))0 3621 y FD(hash)p FJ(\()p FK(object)q FJ(\))208 3721 y FN(Return)h(the)h(hash)g(v)n(alue)g(of)f(the)i(object)e(\(if)h(it)h (has)f(one\).)30 b(Hash)23 b(v)n(alues)e(are)h(inte)o(gers.)30 b(The)o(y)21 b(are)h(used)g(to)g(quickly)f(compare)208 3820 y(dictionary)d(k)o(e)o(ys)i(during)e(a)j(dictionary)d(lookup.)23 b(Numeric)c(v)n(alues)h(that)g(compare)f(equal)h(ha)n(v)o(e)f(the)h (same)h(hash)e(v)n(alue)h(\(e)n(v)o(en)208 3920 y(if)g(the)o(y)g(are)g (of)g(dif)n(ferent)e(types,)i(as)h(is)g(the)f(case)h(for)e(1)i(and)e (1.0\).)0 4067 y FD(help)p FJ(\()p FC([)p FK(object)13 b FC(])p FJ(\))208 4166 y FN(In)m(v)n(ok)o(e)26 b(the)h(b)n(uilt-in)h (help)f(system.)48 b(\(This)27 b(function)f(is)j(intended)d(for)h (interacti)n(v)o(e)g(use.\))47 b(If)28 b(no)f(ar)o(gument)f(is)i(gi)n (v)o(en,)h(the)208 4266 y(interacti)n(v)o(e)20 b(help)g(system)i (starts)g(on)f(the)g(interpreter)f(console.)28 b(If)21 b(the)g(ar)o(gument)e(is)k(a)e(string,)g(then)g(the)h(string)f(is)h (look)o(ed)e(up)208 4366 y(as)i(the)h(name)e(of)h(a)h(module,)e (function,)f(class,)k(method,)d(k)o(e)o(yw)o(ord,)f(or)i(documentation) d(topic,)j(and)g(a)h(help)e(page)h(is)h(printed)208 4465 y(on)i(the)h(console.)42 b(If)26 b(the)g(ar)o(gument)e(is)j(an)o(y)e (other)g(kind)h(of)f(object,)i(a)g(help)e(page)h(on)f(the)h(object)g (is)h(generated.)84 b(Ne)n(w)26 b(in)208 4565 y(v)o(ersion)18 b(2.2.)0 4712 y FD(hex)p FJ(\()p FK(x)p FJ(\))208 4811 y FN(Con)m(v)o(ert)30 b(an)i(inte)o(ger)g(number)e(\(of)i(an)o(y)f (size\))i(to)f(a)h(he)o(xadecimal)d(string.)61 b(The)31 b(result)i(is)g(a)g(v)n(alid)e(Python)g(e)o(xpression.)208 4911 y(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(F)o(ormerly)g(only)g (returned)g(an)h(unsigned)e(literal.)0 5058 y FD(id)p FJ(\()p FK(object)q FJ(\))208 5157 y FN(Return)26 b(the)h (\223identity\224)f(of)h(an)g(object.)45 b(This)27 b(is)h(an)f(inte)o (ger)f(\(or)g(long)h(inte)o(ger\))e(which)i(is)h(guaranteed)c(to)k(be)f (unique)e(and)208 5257 y(constant)k(for)h(this)h(object)e(during)g(its) i(lifetime.)56 b(T)-7 b(w)o(o)30 b(objects)g(with)h(non-o)o(v)o (erlapping)25 b(lifetimes)30 b(may)g(ha)n(v)o(e)g(the)g(same)208 5357 y FJ(id\(\))20 b FN(v)n(alue.)k(\(Implementation)17 b(note:)25 b(this)20 b(is)i(the)e(address)g(of)f(the)i(object.\))p 0 5549 3901 4 v 0 5649 a FI(8)2833 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 9 21 TeXDict begin 9 20 bop 0 83 a FD(input)p FJ(\()p FC([)p FK(pr)l(ompt)13 b FC(])p FJ(\))208 183 y FN(Equi)n(v)n(alent)18 b(to)j FJ(eval\(raw_input\()p FK(pr)l(ompt)q FJ(\)\))p FN(.)h FL(W)-5 b(ar)o(ning:)25 b FN(This)20 b(function)f(is)i(not)g (safe)f(from)g(user)g(errors!)25 b(It)20 b(e)o(xpects)208 282 y(a)e(v)n(alid)h(Python)e(e)o(xpression)g(as)i(input;)f(if)h(the)g (input)f(is)h(not)f(syntactically)g(v)n(alid,)g(a)h FJ(SyntaxError)e FN(will)i(be)g(raised.)24 b(Other)208 382 y(e)o(xceptions)f(may)h(be)h (raised)g(if)g(there)g(is)h(an)f(error)f(during)f(e)n(v)n(aluation.)38 b(\(On)24 b(the)h(other)f(hand,)h(sometimes)g(this)h(is)f(e)o(xactly) 208 482 y(what)20 b(you)f(need)g(when)h(writing)g(a)g(quick)g(script)g (for)f(e)o(xpert)g(use.\))208 610 y(If)k(the)h FJ(readline)f FN(module)f(w)o(as)i(loaded,)g(then)f FJ(input\(\))g FN(will)h(use)g(it)h(to)e(pro)o(vide)f(elaborate)h(line)g(editing)g (and)g(history)208 709 y(features.)208 838 y(Consider)c(using)h(the)g FJ(raw_input\(\))f FN(function)f(for)i(general)f(input)g(from)g(users.) 0 985 y FD(int)p FJ(\()p FC([)p FK(x)p FC([)p FK(,)g(r)o(adix)12 b FC(])g(])p FJ(\))208 1084 y FN(Con)m(v)o(ert)27 b(a)i(string)g(or)g (number)e(to)i(a)g(plain)g(inte)o(ger)-5 b(.)50 b(If)29 b(the)g(ar)o(gument)d(is)k(a)g(string,)g(it)g(must)f(contain)f(a)h (possibly)f(signed)208 1184 y(decimal)17 b(number)f(representable)g(as) j(a)f(Python)f(inte)o(ger)m(,)g(possibly)g(embedded)f(in)i(whitespace.) 23 b(The)18 b FK(r)o(adix)g FN(parameter)e(gi)n(v)o(es)208 1283 y(the)i(base)h(for)g(the)f(con)m(v)o(ersion)f(\(which)h(is)h(10)g (by)f(def)o(ault\))g(and)g(may)h(be)g(an)o(y)f(inte)o(ger)f(in)i(the)g (range)f([2,)h(36],)f(or)g(zero.)24 b(If)19 b FK(r)o(adix)208 1383 y FN(is)k(zero,)f(the)h(proper)e(radix)g(is)j(guessed)e(based)g (on)g(the)g(contents)g(of)g(string;)i(the)e(interpretation)f(is)i(the)g (same)g(as)g(for)f(inte)o(ger)208 1483 y(literals.)i(If)18 b FK(r)o(adix)f FN(is)i(speci\002ed)e(and)g FK(x)h FN(is)h(not)e(a)h (string,)g FJ(TypeError)e FN(is)j(raised.)24 b(Otherwise,)17 b(the)h(ar)o(gument)d(may)i(be)h(a)g(plain)208 1582 y(or)k(long)f(inte) o(ger)g(or)h(a)h(\003oating)f(point)f(number)-5 b(.)30 b(Con)m(v)o(ersion)20 b(of)i(\003oating)g(point)f(numbers)g(to)h(inte)o (gers)g(truncates)f(\(to)n(w)o(ards)208 1682 y(zero\).)37 b(If)25 b(the)g(ar)o(gument)d(is)k(outside)e(the)h(inte)o(ger)f(range)g (a)h(long)f(object)g(will)i(be)e(returned)f(instead.)39 b(If)25 b(no)f(ar)o(guments)f(are)208 1782 y(gi)n(v)o(en,)18 b(returns)i FJ(0)p FN(.)0 1928 y FD(isinstance)p FJ(\()p FK(object,)d(classinfo)p FJ(\))208 2028 y FN(Return)22 b(true)g(if)i(the)e FK(object)i FN(ar)o(gument)d(is)i(an)g(instance)g (of)f(the)h FK(classinfo)g FN(ar)o(gument,)e(or)h(of)h(a)g(\(direct)f (or)h(indirect\))e(subclass)208 2128 y(thereof.)i(Also)e(return)d(true) i(if)g FK(classinfo)g FN(is)h(a)g(type)e(object)h(\(ne)n(w-style)f (class\))h(and)g FK(object)h FN(is)g(an)f(object)f(of)h(that)g(type)g (or)f(of)h(a)208 2227 y(\(direct)h(or)g(indirect\))g(subclass)h (thereof.)29 b(If)21 b FK(object)i FN(is)g(not)f(a)g(class)h(instance)e (or)h(an)f(object)h(of)f(the)h(gi)n(v)o(en)f(type,)g(the)h(function)208 2327 y(al)o(w)o(ays)k(returns)e(f)o(alse.)42 b(If)25 b FK(classinfo)g FN(is)i(neither)e(a)h(class)g(object)f(nor)g(a)h(type) f(object,)h(it)g(may)f(be)h(a)g(tuple)f(of)g(class)i(or)e(type)208 2427 y(objects,)19 b(or)h(may)g(recursi)n(v)o(ely)e(contain)h(other)h (such)f(tuples)h(\(other)f(sequence)g(types)h(are)g(not)g(accepted\).)k (If)c FK(classinfo)g FN(is)h(not)208 2526 y(a)e(class,)h(type,)e(or)h (tuple)f(of)h(classes,)h(types,)f(and)f(such)h(tuples,)g(a)g FJ(TypeError)f FN(e)o(xception)f(is)j(raised.)49 b(Changed)18 b(in)h(v)o(ersion)208 2626 y(2.2:)g(Support)g(for)g(a)i(tuple)f(of)g (type)f(information)f(w)o(as)j(added.)0 2773 y FD(issubclass)p FJ(\()p FK(class,)d(classinfo)p FJ(\))208 2872 y FN(Return)29 b(true)g(if)g FK(class)h FN(is)h(a)f(subclass)f(\(direct)g(or)g (indirect\))f(of)i FK(classinfo)p FN(.)52 b(A)30 b(class)g(is)h (considered)c(a)j(subclass)g(of)f(itself.)208 2972 y FK(classinfo)23 b FN(may)h(be)g(a)h(tuple)e(of)h(class)h(objects,)g(in) f(which)f(case)i(e)n(v)o(ery)e(entry)g(in)h FK(classinfo)g FN(will)h(be)f(check)o(ed.)35 b(In)24 b(an)o(y)f(other)208 3072 y(case,)f(a)h FJ(TypeError)d FN(e)o(xception)g(is)j(raised.)61 b(Changed)21 b(in)h(v)o(ersion)f(2.3:)g(Support)g(for)g(a)h(tuple)g(of) g(type)f(information)f(w)o(as)208 3171 y(added.)0 3318 y FD(iter)p FJ(\()p FK(o)p FC([)p FK(,)f(sentinel)12 b FC(])p FJ(\))208 3418 y FN(Return)26 b(an)g(iterator)g(object.)44 b(The)26 b(\002rst)i(ar)o(gument)c(is)k(interpreted)d(v)o(ery)g(dif)n (ferently)g(depending)f(on)i(the)h(presence)e(of)i(the)208 3517 y(second)15 b(ar)o(gument.)21 b(W)m(ithout)15 b(a)h(second)f(ar)o (gument,)g FK(o)h FN(must)f(be)h(a)h(collection)e(object)g(which)g (supports)g(the)h(iteration)f(protocol)208 3617 y(\(the)28 b FJ(__iter__\(\))g FN(method\),)h(or)g(it)g(must)g(support)f(the)h (sequence)f(protocol)f(\(the)i FJ(__getitem__\(\))e FN(method)g(with) 208 3717 y(inte)o(ger)h(ar)o(guments)f(starting)j(at)g FJ(0)p FN(\).)53 b(If)29 b(it)h(does)g(not)f(support)f(either)h(of)g (those)h(protocols,)g FJ(TypeError)e FN(is)j(raised.)53 b(If)208 3816 y(the)31 b(second)g(ar)o(gument,)g FK(sentinel)p FN(,)j(is)f(gi)n(v)o(en,)f(then)f FK(o)h FN(must)f(be)h(a)g(callable)f (object.)58 b(The)31 b(iterator)g(created)g(in)g(this)h(case)208 3916 y(will)27 b(call)h FK(o)f FN(with)h(no)f(ar)o(guments)e(for)h (each)h(call)h(to)f(its)h FJ(next\(\))f FN(method;)i(if)f(the)f(v)n (alue)f(returned)g(is)i(equal)f(to)g FK(sentinel)p FN(,)208 4016 y FJ(StopIteration)18 b FN(will)j(be)f(raised,)g(otherwise)f(the)h (v)n(alue)g(will)h(be)f(returned.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e (2.2.)0 4162 y FD(len)p FJ(\()p FK(s)p FJ(\))208 4262 y FN(Return)i(the)g(length)g(\(the)g(number)f(of)i(items\))f(of)h(an)f (object.)29 b(The)21 b(ar)o(gument)f(may)h(be)g(a)h(sequence)f (\(string,)g(tuple)g(or)g(list\))i(or)208 4362 y(a)d(mapping)f (\(dictionary\).)0 4509 y FD(list)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 4608 y FN(Return)29 b(a)i(list)h(whose)e(items)h (are)f(the)g(same)h(and)f(in)g(the)h(same)f(order)f(as)j FK(iter)o(able)p FN(')-5 b(s)30 b(items.)56 b FK(iter)o(able)30 b FN(may)g(be)g(either)g(a)208 4708 y(sequence,)24 b(a)i(container)d (that)i(supports)f(iteration,)h(or)g(an)g(iterator)f(object.)39 b(If)25 b FK(iter)o(able)g FN(is)g(already)f(a)i(list,)h(a)e(cop)o(y)f (is)i(made)208 4807 y(and)21 b(returned,)e(similar)j(to)g FK(iter)o(able)p FJ([:])p FN(.)28 b(F)o(or)21 b(instance,)g FJ(list\('abc'\))f FN(returns)h FJ(['a',)49 b('b',)g('c'])21 b FN(and)g FJ(list\()208 4907 y(\(1,)49 b(2,)g(3\))h(\))20 b FN(returns)g FJ([1,)49 b(2,)g(3])p FN(.)25 b(If)20 b(no)g(ar)o(gument)e(is)j(gi)n(v)o(en,)e(returns)g(a)i(ne)n(w)f(empty)f (list,)i FJ([])p FN(.)0 5054 y FD(locals)p FJ(\(\))208 5154 y FN(Update)29 b(and)g(return)f(a)i(dictionary)e(representing)g (the)h(current)g(local)g(symbol)g(table.)53 b FL(W)-5 b(ar)o(ning:)43 b FN(The)30 b(contents)f(of)g(this)208 5253 y(dictionary)18 b(should)h(not)h(be)g(modi\002ed;)f(changes)g(may) h(not)g(af)n(fect)g(the)g(v)n(alues)g(of)f(local)i(v)n(ariables)e(used) h(by)g(the)g(interpreter)-5 b(.)0 5400 y FD(long)p FJ(\()p FC([)p FK(x)p FC([)p FK(,)19 b(r)o(adix)12 b FC(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)3027 b(9)p eop end %%Page: 10 22 TeXDict begin 10 21 bop 208 83 a FN(Con)m(v)o(ert)15 b(a)j(string)f(or)f(number)g(to)h(a)h(long)e(inte)o(ger)-5 b(.)23 b(If)17 b(the)g(ar)o(gument)e(is)j(a)g(string,)f(it)h(must)f (contain)f(a)h(possibly)g(signed)f(number)208 183 y(of)24 b(arbitrary)f(size,)j(possibly)e(embedded)f(in)i(whitespace.)38 b(The)24 b FK(r)o(adix)h FN(ar)o(gument)d(is)k(interpreted)d(in)h(the)h (same)g(w)o(ay)g(as)g(for)208 282 y FJ(int\(\))p FN(,)20 b(and)h(may)f(only)g(be)h(gi)n(v)o(en)f(when)g FK(x)i FN(is)g(a)g(string.)27 b(Otherwise,)20 b(the)h(ar)o(gument)e(may)i(be)g (a)g(plain)g(or)f(long)h(inte)o(ger)e(or)i(a)208 382 y(\003oating)e(point)g(number)m(,)f(and)h(a)i(long)e(inte)o(ger)g(with) h(the)g(same)g(v)n(alue)g(is)h(returned.)i(Con)m(v)o(ersion)18 b(of)h(\003oating)h(point)f(numbers)208 482 y(to)h(inte)o(gers)f (truncates)h(\(to)n(w)o(ards)f(zero\).)24 b(If)c(no)g(ar)o(guments)e (are)i(gi)n(v)o(en,)f(returns)g FJ(0L)p FN(.)0 628 y FD(map)p FJ(\()p FK(function,)f(iter)o(able)o(,)i(...)p FJ(\))208 728 y FN(Apply)27 b FK(function)g FN(to)h(e)n(v)o(ery)f(item) h(of)g FK(iter)o(able)g FN(and)g(return)f(a)h(list)h(of)f(the)h (results.)49 b(If)28 b(additional)f FK(iter)o(able)h FN(ar)o(guments)e(are)208 828 y(passed,)21 b FK(function)f FN(must)i(tak)o(e)f(that)h(man)o(y)e(ar)o(guments)f(and)i(is)i(applied) d(to)i(the)f(items)h(from)f(all)h(iterables)f(in)h(parallel.)28 b(If)21 b(one)208 927 y(iterable)g(is)h(shorter)f(than)g(another)g(it)h (is)h(assumed)e(to)h(be)f(e)o(xtended)f(with)i FJ(None)f FN(items.)30 b(If)22 b FK(function)e FN(is)j FJ(None)p FN(,)f(the)f(identity)208 1027 y(function)i(is)j(assumed;)i(if)d(there) g(are)g(multiple)g(ar)o(guments,)f FJ(map\(\))h FN(returns)f(a)i(list)g (consisting)f(of)g(tuples)g(containing)f(the)208 1127 y(corresponding)11 b(items)16 b(from)e(all)i(iterables)f(\(a)h(kind)e (of)h(transpose)g(operation\).)21 b(The)15 b FK(iter)o(able)g FN(ar)o(guments)e(may)i(be)g(a)h(sequence)208 1226 y(or)j(an)o(y)h (iterable)g(object;)f(the)i(result)f(is)h(al)o(w)o(ays)g(a)f(list.)0 1373 y FD(max)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)f(ar)m(gs...)12 b FC(][)p FK(k)o(e)n(y)g FC(])p FJ(\))208 1473 y FN(W)m(ith)22 b(a)i(single)e(ar)o(gument)e FK(iter)o(able)p FN(,)j(return)e(the)i (lar)o(gest)f(item)h(of)f(a)h(non-empty)d(iterable)i(\(such)g(as)i(a)f (string,)f(tuple)h(or)f(list\).)208 1572 y(W)m(ith)e(more)f(than)h(one) g(ar)o(gument,)d(return)i(the)i(lar)o(gest)e(of)h(the)g(ar)o(guments.) 208 1705 y(The)i(optional)f FK(k)o(e)n(y)i FN(ar)o(gument)d (speci\002es)k(a)f(one-ar)o(gument)c(ordering)h(function)h(lik)o(e)i (that)g(used)g(for)f FJ(list.sort\(\))p FN(.)31 b(The)208 1805 y FK(k)o(e)n(y)20 b FN(ar)o(gument,)e(if)j(supplied,)f(must)h(be)f (in)h(k)o(e)o(yw)o(ord)e(form)h(\(for)g(e)o(xample,)f(`)p FJ(max\(a,b,c,key=func\))p FN('\).)50 b(Changed)19 b(in)208 1904 y(v)o(ersion)f(2.5:)i(Added)f(support)g(for)h(the)g(optional)f FK(k)o(e)n(y)h FN(ar)o(gument.)0 2051 y FD(min)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)f(ar)m(gs...)12 b FC(][)p FK(k)o(e)n(y)g FC(])p FJ(\))208 2151 y FN(W)m(ith)20 b(a)g(single)g(ar)o(gument)e FK(iter)o(able)p FN(,)h(return)g(the)h (smallest)g(item)g(of)g(a)g(non-empty)e(iterable)h(\(such)g(as)i(a)f (string,)g(tuple)f(or)h(list\).)208 2250 y(W)m(ith)g(more)f(than)h(one) g(ar)o(gument,)d(return)i(the)i(smallest)f(of)g(the)h(ar)o(guments.)208 2383 y(The)h(optional)f FK(k)o(e)n(y)i FN(ar)o(gument)d(speci\002es)k (a)f(one-ar)o(gument)c(ordering)h(function)h(lik)o(e)i(that)g(used)g (for)f FJ(list.sort\(\))p FN(.)31 b(The)208 2483 y FK(k)o(e)n(y)20 b FN(ar)o(gument,)e(if)j(supplied,)f(must)h(be)f(in)h(k)o(e)o(yw)o(ord) e(form)h(\(for)g(e)o(xample,)f(`)p FJ(min\(a,b,c,key=func\))p FN('\).)50 b(Changed)19 b(in)208 2583 y(v)o(ersion)f(2.5:)i(Added)f (support)g(for)h(the)g(optional)f FK(k)o(e)n(y)h FN(ar)o(gument.)0 2729 y FD(object)p FJ(\(\))208 2829 y FN(Return)d(a)i(ne)n(w)f (featureless)g(object.)24 b FJ(object)18 b FN(is)h(a)g(base)g(for)e (all)i(ne)n(w)f(style)h(classes.)26 b(It)18 b(has)h(the)f(methods)g (that)g(are)g(common)208 2929 y(to)i(all)h(instances)f(of)g(ne)n(w)g (style)g(classes.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)208 3062 y(Changed)28 b(in)h(v)o(ersion)f(2.3:)h(This)h(function)e(does)h (not)g(accept)g(an)o(y)g(ar)o(guments.)50 b(F)o(ormerly)-5 b(,)30 b(it)g(accepted)e(ar)o(guments)g(b)n(ut)208 3161 y(ignored)18 b(them.)0 3308 y FD(oct)p FJ(\()p FK(x)p FJ(\))208 3408 y FN(Con)m(v)o(ert)h(an)h(inte)o(ger)g(number)f(\(of)h (an)o(y)g(size\))h(to)f(an)h(octal)g(string.)26 b(The)20 b(result)h(is)g(a)g(v)n(alid)g(Python)e(e)o(xpression.)52 b(Changed)19 b(in)208 3507 y(v)o(ersion)f(2.4:)i(F)o(ormerly)f(only)g (returned)f(an)i(unsigned)f(literal.)0 3654 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(mode)p FC([)p FK(,)h(b)n(ufsize) 12 b FC(])g(])p FJ(\))208 3754 y FN(Open)21 b(a)i(\002le,)g(returning)e (an)h(object)g(of)g(the)g FJ(file)g FN(type)g(described)f(in)i(section) f(3.9,)g(\223File)g(Objects\224.)32 b(If)22 b(the)g(\002le)h(cannot)f (be)208 3853 y(opened,)d FJ(IOError)h FN(is)i(raised.)27 b(When)20 b(opening)f(a)j(\002le,)f(it')-5 b(s)22 b(preferable)d(to)i (use)g FJ(open\(\))g FN(instead)f(of)h(in)m(v)n(oking)e(the)i FJ(file)208 3953 y FN(constructor)d(directly)-5 b(.)208 4086 y(The)25 b(\002rst)h(tw)o(o)f(ar)o(guments)e(are)j(the)f(same)g (as)i(for)d FJ(stdio)p FN(')-5 b(s)26 b FJ(fopen\(\))p FN(:)34 b FK(\002lename)24 b FN(is)j(the)e(\002le)h(name)f(to)g(be)g (opened,)g(and)208 4185 y FK(mode)19 b FN(is)i(a)g(string)f(indicating) f(ho)n(w)g(the)h(\002le)h(is)g(to)g(be)f(opened.)208 4318 y(The)g(most)i(commonly-used)17 b(v)n(alues)k(of)g FK(mode)g FN(are)g FJ('r')g FN(for)f(reading,)g FJ('w')h FN(for)g(writing)f(\(truncating)f(the)i(\002le)h(if)g(it)g(already)208 4418 y(e)o(xists\),)j(and)f FJ('a')h FN(for)f(appending)e(\(which)h(on) i FK(some)h FN(U)t FH(N)t(I)t(X)i FN(systems)d(means)f(that)h FK(all)g FN(writes)g(append)e(to)i(the)f(end)g(of)h(the)208 4518 y(\002le)j(re)o(gardless)f(of)h(the)g(current)f(seek)h (position\).)47 b(If)28 b FK(mode)g FN(is)h(omitted,)g(it)g(def)o (aults)e(to)i FJ('r')p FN(.)48 b(When)28 b(opening)e(a)j(binary)208 4617 y(\002le,)22 b(you)f(should)g(append)f FJ('b')h FN(to)h(the)g FK(mode)f FN(v)n(alue)g(to)h(open)e(the)i(\002le)h(in)e (binary)g(mode,)g(which)g(will)h(impro)o(v)o(e)e(portability)-5 b(.)208 4717 y(\(Appending)22 b FJ('b')j FN(is)h(useful)e(e)n(v)o(en)g (on)h(systems)g(that)g(don')o(t)f(treat)h(binary)e(and)i(te)o(xt)g (\002les)h(dif)n(ferently)-5 b(,)23 b(where)h(it)i(serv)o(es)f(as)208 4816 y(documentation.\))c(See)g(belo)n(w)e(for)h(more)f(possible)h(v)n (alues)g(of)g FK(mode)p FN(.)208 4949 y(The)d(optional)f FK(b)n(ufsize)j FN(ar)o(gument)c(speci\002es)j(the)g(\002le')-5 b(s)19 b(desired)e(b)n(uf)n(fer)f(size:)25 b(0)17 b(means)h(unb)n(uf)n (fered,)d(1)j(means)f(line)h(b)n(uf)n(fered,)208 5049 y(an)o(y)24 b(other)g(positi)n(v)o(e)g(v)n(alue)g(means)h(use)g(a)h(b)n (uf)n(fer)d(of)i(\(approximately\))d(that)j(size.)40 b(A)25 b(ne)o(gati)n(v)o(e)e FK(b)n(ufsize)i FN(means)g(to)g(use)h(the) 208 5149 y(system)e(def)o(ault,)h(which)f(is)h(usually)f(line)h(b)n(uf) n(fered)e(for)h(tty)g(de)n(vices)g(and)g(fully)g(b)n(uf)n(fered)f(for)h (other)g(\002les.)38 b(If)25 b(omitted,)g(the)208 5248 y(system)20 b(def)o(ault)f(is)j(used.)960 5218 y FF(3)p 0 5319 1560 4 v 90 5375 a FB(3)120 5398 y FH(Specifying)g(a)e(b)o(uf)n (fer)h(size)g(currently)h(has)f(no)f(ef)n(fect)i(on)e(systems)g(that)h (don')o(t)g(ha)o(v)o(e)g Fz(setvbuf\(\))p FH(.)28 b(The)20 b(interf)o(ace)j(to)d(specify)i(the)f(b)o(uf)n(fer)f(size)h(is)f(not)h (done)p 0 5549 3901 4 v 0 5649 a FI(10)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 11 23 TeXDict begin 11 22 bop 208 83 a FN(Modes)23 b FJ('r+')p FN(,)g FJ('w+')h FN(and)f FJ('a+')g FN(open)f(the)i(\002le)g(for)f (updating)e(\(note)i(that)h FJ('w+')f FN(truncates)g(the)g(\002le\).)35 b(Append)22 b FJ('b')h FN(to)208 183 y(the)c(mode)f(to)i(open)e(the)h (\002le)h(in)g(binary)e(mode,)g(on)h(systems)g(that)h(dif)n(ferentiate) d(between)i(binary)f(and)g(te)o(xt)i(\002les;)g(on)f(systems)208 282 y(that)h(don')o(t)e(ha)n(v)o(e)i(this)h(distinction,)e(adding)g (the)h FJ('b')g FN(has)g(no)g(ef)n(fect.)208 415 y(In)g(addition)f(to)h (the)g(standard)f FJ(fopen\(\))h FN(v)n(alues)g FK(mode)g FN(may)f(be)i FJ('U')f FN(or)g FJ('rU')p FN(.)g(Python)f(is)i(usually)f (b)n(uilt)g(with)h(uni)n(v)o(ersal)208 515 y(ne)n(wline)c(support;)g (supplying)f FJ('U')i FN(opens)f(the)h(\002le)h(as)g(a)f(te)o(xt)g (\002le,)h(b)n(ut)f(lines)g(may)f(be)h(terminated)f(by)g(an)o(y)h(of)f (the)h(follo)n(wing:)208 614 y(the)h(U)t FH(N)t(I)t(X)i FN(end-of-line)15 b(con)m(v)o(ention)g FJ('\\n')p FN(,)j(the)g (Macintosh)f(con)m(v)o(ention)d FJ('\\r')p FN(,)k(or)g(the)f(W)m(indo)n (ws)h(con)m(v)o(ention)c FJ('\\r\\n')p FN(.)208 714 y(All)33 b(of)f(these)g(e)o(xternal)f(representations)g(are)h(seen)g(as)h FJ('\\n')g FN(by)e(the)i(Python)e(program.)59 b(If)32 b(Python)g(is)h(b)n(uilt)f(without)208 814 y(uni)n(v)o(ersal)22 b(ne)n(wline)g(support)g(a)i FK(mode)f FN(with)h FJ('U')f FN(is)h(the)g(same)f(as)h(normal)f(te)o(xt)g(mode.)33 b(Note)24 b(that)f(\002le)h(objects)f(so)h(opened)208 913 y(also)19 b(ha)n(v)o(e)g(an)g(attrib)n(ute)g(called)g FJ(newlines)f FN(which)h(has)g(a)h(v)n(alue)e(of)h FJ(None)g FN(\(if)g(no)g(ne)n(wlines)g(ha)n(v)o(e)f(yet)i(been)e(seen\),)h FJ('\\n')p FN(,)208 1013 y FJ('\\r')p FN(,)g FJ('\\r\\n')p FN(,)h(or)g(a)g(tuple)g(containing)e(all)j(the)f(ne)n(wline)g(types)g (seen.)208 1146 y(Python)f(enforces)g(that)h(the)g(mode,)f(after)h (stripping)f FJ('U')p FN(,)h(be)o(gins)f(with)h FJ('r')p FN(,)g FJ('w')h FN(or)f FJ('a')p FN(.)208 1279 y(Changed)e(in)j(v)o (ersion)e(2.5:)g(Restriction)h(on)g(\002rst)h(letter)g(of)e(mode)h (string)g(introduced.)0 1425 y FD(ord)p FJ(\()p FK(c)p FJ(\))208 1525 y FN(Gi)n(v)o(en)k(a)i(string)f(of)g(length)f(one,)i (return)e(an)h(inte)o(ger)g(representing)e(the)i(Unicode)f(code)h (point)f(of)h(the)h(character)e(when)h(the)208 1625 y(ar)o(gument)j(is) k(a)g(unicode)d(object,)k(or)e(the)g(v)n(alue)g(of)g(the)g(byte)f(when) h(the)g(ar)o(gument)e(is)j(an)f(8-bit)f(string.)57 b(F)o(or)31 b(e)o(xample,)208 1724 y FJ(ord\('a'\))21 b FN(returns)g(the)i(inte)o (ger)e FJ(97)p FN(,)i FJ(ord\(u'\\u2020'\))d FN(returns)h FJ(8224)p FN(.)31 b(This)23 b(is)g(the)f(in)m(v)o(erse)g(of)g FJ(chr\(\))f FN(for)h(8-bit)208 1824 y(strings)e(and)f(of)h FJ(unichr\(\))g FN(for)f(unicode)g(objects.)25 b(If)20 b(a)h(unicode)d(ar)o(gument)g(is)j(gi)n(v)o(en)e(and)h(Python)f(w)o(as) i(b)n(uilt)g(with)f(UCS2)208 1924 y(Unicode,)i(then)h(the)g(character') -5 b(s)22 b(code)h(point)f(must)i(be)f(in)g(the)g(range)f([0..65535])e (inclusi)n(v)o(e;)k(otherwise)e(the)i(string)e(length)208 2023 y(is)f(tw)o(o,)f(and)g(a)g FJ(TypeError)f FN(will)i(be)f(raised.)0 2170 y FD(pow)p FJ(\()p FK(x,)g(y)p FC([)p FK(,)g(z)12 b FC(])p FJ(\))208 2270 y FN(Return)29 b FK(x)h FN(to)g(the)g(po)n(wer) e FK(y)p FN(;)35 b(if)30 b FK(z)h FN(is)g(present,)g(return)d FK(x)j FN(to)f(the)f(po)n(wer)g FK(y)p FN(,)j(modulo)c FK(z)j FN(\(computed)c(more)i(ef)n(\002ciently)g(than)208 2369 y FJ(pow\()p FK(x)p FJ(,)49 b FK(y)p FJ(\))g(\045)h FK(z)p FN(\).)25 b(The)20 b(tw)o(o-ar)o(gument)d(form)i FJ(pow\()p FK(x)p FJ(,)49 b FK(y)p FJ(\))21 b FN(is)g(equi)n(v)n(alent) d(to)j(using)e(the)i(po)n(wer)e(operator:)k FK(x)3581 2384 y FJ(**)3681 2369 y FK(y)p FN(.)208 2502 y(The)i(ar)o(guments)e (must)j(ha)n(v)o(e)f(numeric)f(types.)41 b(W)m(ith)26 b(mix)o(ed)e(operand)g(types,)i(the)g(coercion)e(rules)h(for)g(binary)f (arithmetic)208 2602 y(operators)i(apply)-5 b(.)46 b(F)o(or)27 b(int)h(and)f(long)g(int)h(operands,)g(the)g(result)f(has)h(the)g(same) g(type)f(as)i(the)e(operands)f(\(after)i(coercion\))208 2701 y(unless)e(the)h(second)f(ar)o(gument)f(is)j(ne)o(gati)n(v)o(e;)g (in)f(that)f(case,)j(all)f(ar)o(guments)c(are)j(con)m(v)o(erted)d(to)j (\003oat)g(and)g(a)g(\003oat)g(result)g(is)208 2801 y(deli)n(v)o(ered.) 56 b(F)o(or)30 b(e)o(xample,)j FJ(10)1174 2816 y(**)1274 2801 y(2)d FN(returns)h FJ(100)p FN(,)i(b)n(ut)f FJ(10)2058 2816 y(**)2158 2801 y(-2)e FN(returns)g FJ(0.01)p FN(.)58 b(\(This)31 b(last)h(feature)e(w)o(as)i(added)e(in)208 2901 y(Python)25 b(2.2.)42 b(In)26 b(Python)f(2.1)h(and)g(before,)g(if) g(both)g(ar)o(guments)e(were)i(of)g(inte)o(ger)f(types)h(and)g(the)g (second)g(ar)o(gument)e(w)o(as)208 3000 y(ne)o(gati)n(v)o(e,)18 b(an)j(e)o(xception)e(w)o(as)i(raised.\))26 b(If)21 b(the)g(second)f (ar)o(gument)e(is)k(ne)o(gati)n(v)o(e,)c(the)j(third)f(ar)o(gument)f (must)h(be)h(omitted.)26 b(If)21 b FK(z)208 3100 y FN(is)i(present,)e FK(x)i FN(and)f FK(y)g FN(must)h(be)f(of)g(inte)o(ger)f(types,)h(and)f FK(y)i FN(must)f(be)g(non-ne)o(gati)n(v)o(e.)27 b(\(This)22 b(restriction)f(w)o(as)i(added)e(in)i(Python)208 3200 y(2.2.)38 b(In)24 b(Python)g(2.1)g(and)h(before,)f(\003oating)g(3-ar)o (gument)e FJ(pow\(\))i FN(returned)f(platform-dependent)e(results)k (depending)d(on)208 3299 y(\003oating-point)17 b(rounding)h (accidents.\))0 3446 y FD(property)p FJ(\()p FC([)p FK(fg)o(et)q FC([)p FK(,)h(fset)q FC([)p FK(,)i(fdel)p FC([)p FK(,)f(doc)12 b FC(])g(])g(])g(])p FJ(\))208 3546 y FN(Return)19 b(a)i(property)d (attrib)n(ute)i(for)f(ne)n(w-style)h(classes)h(\(classes)g(that)f(deri) n(v)o(e)f(from)g FJ(object)p FN(\).)208 3678 y FK(fg)o(et)29 b FN(is)f(a)g(function)e(for)h(getting)g(an)g(attrib)n(ute)g(v)n(alue,) i(lik)o(e)n(wise)f FK(fset)i FN(is)e(a)g(function)e(for)h(setting,)i (and)e FK(fdel)g FN(a)h(function)e(for)208 3778 y(del'ing,)18 b(an)i(attrib)n(ute.)25 b(T)-7 b(ypical)20 b(use)g(is)h(to)g(de\002ne)e (a)i(managed)d(attrib)n(ute)i(x:)444 4002 y FA(class)44 b(C\(object\):)623 4094 y(def)g(__init__\(self\):)f(self._x)g(=)i(None) 623 4185 y(def)f(getx\(self\):)f(return)h(self._x)623 4276 y(def)g(setx\(self,)g(value\):)f(self._x)h(=)h(value)623 4368 y(def)f(delx\(self\):)f(del)i(self._x)623 4459 y(x)g(=)f (property\(getx,)f(setx,)h(delx,)g("I'm)g(the)g('x')h(property."\))208 4649 y FN(If)23 b(gi)n(v)o(en,)g FK(doc)g FN(will)i(be)e(the)h (docstring)e(of)i(the)f(property)f(attrib)n(ute.)35 b(Otherwise,)24 b(the)f(property)f(will)i(cop)o(y)f FK(fg)o(et)q FN(')-5 b(s)25 b(docstring)208 4748 y(\(if)20 b(it)h(e)o(xists\).)k(This)20 b(mak)o(es)g(it)h(possible)f(to)g(create)g(read-only)e(properties)h (easily)h(using)g FJ(property\(\))f FN(as)i(a)f(decorator:)p 0 4819 1560 4 v 0 4896 a FH(using)f(a)f(method)h(that)g(calls)h Fz(setvbuf\(\))p FH(,)c(because)k(that)f(may)f(dump)g(core)h(when)g (called)h(after)g(an)o(y)e(I/O)h(has)f(been)h(performed,)g(and)g (there')l(s)h(no)e(reliable)j(w)o(ay)d(to)0 4975 y(determine)h(whether) g(this)e(is)g(the)h(case.)p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)2981 b(11)p eop end %%Page: 12 24 TeXDict begin 12 23 bop 444 174 a FA(class)44 b(Parrot\(object\):)623 266 y(def)g(__init__\(self\):)802 357 y(self._voltage)f(=)i(100000)623 540 y(@property)623 631 y(def)f(voltage\(self\):)802 722 y("""Get)g(the)h(current)e(voltage.""")802 814 y(return)h (self._voltage)208 1003 y FN(turns)19 b(the)i FJ(voltage\(\))e FN(method)f(into)i(a)h(\223getter\224)f(for)f(a)i(read-only)d(attrib)n (ute)h(with)i(the)f(same)g(name.)208 1136 y(Ne)n(w)g(in)g(v)o(ersion)f (2.2.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.5:)h(Use)h FK(fg)o(et)q FN(')-5 b(s)21 b(docstring)e(if)h(no)g FK(doc)g FN(gi)n(v)o(en.)0 1283 y FD(range)p FJ(\()p FC([)p FK(start,)12 b FC(])19 b FK(stop)p FC([)p FK(,)h(step)12 b FC(])p FJ(\))208 1382 y FN(This)19 b(is)i(a)f(v)o(ersatile)f(function)e(to)j (create)f(lists)i(containing)d(arithmetic)h(progressions.)j(It)e(is)h (most)e(often)g(used)g(in)h FJ(for)f FN(loops.)208 1482 y(The)25 b(ar)o(guments)f(must)h(be)h(plain)f(inte)o(gers.)41 b(If)25 b(the)h FK(step)g FN(ar)o(gument)d(is)k(omitted,)f(it)h(def)o (aults)e(to)h FJ(1)p FN(.)42 b(If)25 b(the)h FK(start)i FN(ar)o(gument)208 1582 y(is)h(omitted,)g(it)g(def)o(aults)f(to)g FJ(0)p FN(.)50 b(The)27 b(full)i(form)e(returns)g(a)i(list)g(of)f (plain)g(inte)o(gers)f FJ([)p FK(start)q FJ(,)50 b FK(start)i FJ(+)e FK(step)p FJ(,)f FK(start)j FJ(+)d(2)208 1696 y(*)307 1681 y FK(step)p FJ(,)h(...])p FN(.)43 b(If)26 b FK(step)h FN(is)g(positi)n(v)o(e,)g(the)f(last)i(element)d(is)j(the)e (lar)o(gest)g FK(start)52 b FJ(+)d FK(i)2833 1696 y FJ(*)2933 1681 y FK(step)26 b FN(less)i(than)e FK(stop)p FN(;)j(if)e FK(step)g FN(is)208 1781 y(ne)o(gati)n(v)o(e,)f(the)i(last)g(element)f (is)h(the)g(smallest)g FK(start)51 b FJ(+)f FK(i)1987 1796 y FJ(*)2086 1781 y FK(step)28 b FN(greater)e(than)h FK(stop)p FN(.)47 b FK(step)28 b FN(must)f(not)g(be)g(zero)g(\(or)g (else)208 1881 y FJ(ValueError)18 b FN(is)k(raised\).)i(Example:)444 2105 y FA(>>>)44 b(range\(10\))444 2196 y([0,)g(1,)h(2,)f(3,)h(4,)f(5,) h(6,)f(7,)h(8,)f(9])444 2287 y(>>>)g(range\(1,)g(11\))444 2379 y([1,)g(2,)h(3,)f(4,)h(5,)f(6,)h(7,)f(8,)h(9,)f(10])444 2470 y(>>>)g(range\(0,)g(30,)g(5\))444 2561 y([0,)g(5,)h(10,)f(15,)g (20,)h(25])444 2653 y(>>>)f(range\(0,)g(10,)g(3\))444 2744 y([0,)g(3,)h(6,)f(9])444 2835 y(>>>)g(range\(0,)g(-10,)g(-1\))444 2927 y([0,)g(-1,)g(-2,)h(-3,)f(-4,)g(-5,)h(-6,)f(-7,)g(-8,)h(-9])444 3018 y(>>>)f(range\(0\))444 3109 y([])444 3201 y(>>>)g(range\(1,)g(0\)) 444 3292 y([])0 3519 y FD(raw_input)p FJ(\()p FC([)p FK(pr)l(ompt)13 b FC(])p FJ(\))208 3618 y FN(If)21 b(the)h FK(pr)l(ompt)i FN(ar)o(gument)19 b(is)k(present,)f(it)g(is)h(written)f (to)g(standard)f(output)g(without)g(a)h(trailing)g(ne)n(wline.)29 b(The)22 b(function)e(then)208 3718 y(reads)g(a)h(line)g(from)e(input,) h(con)m(v)o(erts)f(it)i(to)g(a)g(string)g(\(stripping)e(a)i(trailing)f (ne)n(wline\),)f(and)h(returns)g(that.)26 b(When)d FH(E)t(O)t(F)g FN(is)e(read,)208 3818 y FJ(EOFError)e FN(is)i(raised.)k(Example:)444 4042 y FA(>>>)44 b(s)h(=)f(raw_input\('-->)f('\))444 4133 y(-->)h(Monty)g(Python's)g(Flying)f(Circus)444 4224 y(>>>)h(s)444 4316 y("Monty)g(Python's)f(Flying)h(Circus")208 4505 y FN(If)27 b(the)g FJ(readline)f FN(module)g(w)o(as)i(loaded,)f (then)g FJ(raw_input\(\))e FN(will)j(use)f(it)h(to)g(pro)o(vide)d (elaborate)h(line)h(editing)f(and)208 4605 y(history)19 b(features.)0 4752 y FD(reduce)p FJ(\()p FK(function,)e(iter)o(able)p FC([)p FK(,)j(initializer)14 b FC(])p FJ(\))208 4851 y FN(Apply)25 b FK(function)f FN(of)i(tw)o(o)g(ar)o(guments)e(cumulati) n(v)o(ely)g(to)i(the)g(items)h(of)f FK(iter)o(able)p FN(,)g(from)f(left)i(to)f(right,)g(so)h(as)g(to)f(reduce)f(the)208 4951 y(iterable)h(to)g(a)h(single)f(v)n(alue.)44 b(F)o(or)26 b(e)o(xample,)g FJ(reduce\(lambda)47 b(x,)j(y:)99 b(x+y,)49 b([1,)g(2,)h(3,)f(4,)h(5]\))26 b FN(calcu-)208 5050 y(lates)c FJ(\(\(\(\(1+2\)+3\)+4\)+5\))p FN(.)k(The)21 b(left)h(ar)o(gument,)d FK(x)p FN(,)k(is)f(the)g(accumulated)d(v)n(alue)i(and)g(the)h(right)f (ar)o(gument,)e FK(y)p FN(,)j(is)h(the)208 5150 y(update)17 b(v)n(alue)h(from)f(the)i FK(iter)o(able)p FN(.)24 b(If)18 b(the)g(optional)g FK(initializer)j FN(is)e(present,)f(it)h(is)g (placed)f(before)f(the)i(items)g(of)f(the)g(iterable)g(in)208 5250 y(the)g(calculation,)f(and)g(serv)o(es)h(as)g(a)h(def)o(ault)e (when)g(the)h(iterable)g(is)h(empty)-5 b(.)23 b(If)18 b FK(initializer)i FN(is)f(not)f(gi)n(v)o(en)e(and)i FK(iter)o(able)f FN(contains)208 5349 y(only)i(one)h(item,)g(the)g (\002rst)h(item)f(is)h(returned.)p 0 5549 3901 4 v 0 5649 a FI(12)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 13 25 TeXDict begin 13 24 bop 0 83 a FD(reload)p FJ(\()p FK(module)p FJ(\))208 183 y FN(Reload)17 b(a)h(pre)n(viously)e(imported)g FK(module)p FN(.)23 b(The)18 b(ar)o(gument)d(must)j(be)g(a)g(module)e (object,)i(so)g(it)g(must)g(ha)n(v)o(e)f(been)g(successfully)208 282 y(imported)g(before.)23 b(This)c(is)g(useful)g(if)g(you)f(ha)n(v)o (e)g(edited)g(the)h(module)e(source)i(\002le)g(using)f(an)h(e)o (xternal)f(editor)g(and)g(w)o(ant)h(to)g(try)208 382 y(out)j(the)h(ne)n(w)f(v)o(ersion)f(without)h(lea)n(ving)g(the)h (Python)e(interpreter)-5 b(.)31 b(The)23 b(return)e(v)n(alue)h(is)i (the)e(module)g(object)g(\(the)g(same)h(as)208 482 y(the)d FK(module)f FN(ar)o(gument\).)208 614 y(When)h FJ(reload\(module\))e FN(is)j(e)o(x)o(ecuted:)349 828 y FM(\017)o FN(Python)h(modules')f (code)h(is)h(recompiled)e(and)h(the)g(module-le)n(v)o(el)e(code)i(ree)o (x)o(ecuted,)f(de\002ning)g(a)i(ne)n(w)f(set)i(of)e(objects)390 927 y(which)27 b(are)g(bound)f(to)h(names)g(in)g(the)h(module')-5 b(s)26 b(dictionary)-5 b(.)44 b(The)27 b FJ(init)g FN(function)f(of)h (e)o(xtension)e(modules)i(is)h(not)390 1027 y(called)20 b(a)h(second)e(time.)349 1160 y FM(\017)o FN(As)24 b(with)e(all)h (other)f(objects)g(in)h(Python)e(the)i(old)f(objects)g(are)h(only)f (reclaimed)f(after)h(their)g(reference)f(counts)h(drop)f(to)390 1259 y(zero.)349 1392 y FM(\017)o FN(The)f(names)g(in)g(the)g(module)f (namespace)g(are)h(updated)f(to)h(point)g(to)g(an)o(y)g(ne)n(w)g(or)f (changed)g(objects.)349 1525 y FM(\017)o FN(Other)j(references)f(to)i (the)f(old)g(objects)g(\(such)g(as)h(names)f(e)o(xternal)f(to)i(the)f (module\))f(are)h(not)g(rebound)e(to)i(refer)g(to)h(the)390 1625 y(ne)n(w)d(objects)g(and)g(must)g(be)g(updated)f(in)h(each)g (namespace)f(where)g(the)o(y)h(occur)f(if)i(that)f(is)h(desired.)208 1838 y(There)e(are)h(a)h(number)d(of)i(other)f(ca)n(v)o(eats:)208 1971 y(If)26 b(a)g(module)f(is)i(syntactically)f(correct)f(b)n(ut)h (its)h(initialization)f(f)o(ails,)i(the)e(\002rst)h FJ(import)f FN(statement)g(for)g(it)h(does)f(not)f(bind)208 2070 y(its)c(name)f(locally)-5 b(,)20 b(b)n(ut)g(does)h(store)f(a)h (\(partially)f(initialized\))g(module)f(object)h(in)h FJ(sys.modules)p FN(.)k(T)-7 b(o)21 b(reload)e(the)i(module)208 2170 y(you)i(must)i(\002rst)h FJ(import)e FN(it)h(again)f(\(this)h (will)h(bind)e(the)g(name)h(to)g(the)f(partially)g(initialized)h (module)e(object\))h(before)f(you)208 2270 y(can)d FJ(reload\(\))f FN(it.)208 2402 y(When)j(a)g(module)f(is)i(reloaded,)e(its)i (dictionary)e(\(containing)e(the)k(module')-5 b(s)21 b(global)g(v)n(ariables\))g(is)i(retained.)30 b(Rede\002nitions)208 2502 y(of)25 b(names)g(will)h(o)o(v)o(erride)e(the)h(old)g (de\002nitions,)h(so)g(this)g(is)h(generally)d(not)h(a)h(problem.)39 b(If)26 b(the)f(ne)n(w)g(v)o(ersion)g(of)g(a)h(module)208 2602 y(does)20 b(not)g(de\002ne)g(a)h(name)f(that)h(w)o(as)g(de\002ned) f(by)g(the)h(old)f(v)o(ersion,)f(the)i(old)f(de\002nition)g(remains.)25 b(This)c(feature)f(can)g(be)h(used)208 2701 y(to)h(the)h(module')-5 b(s)22 b(adv)n(antage)e(if)j(it)h(maintains)e(a)h(global)f(table)g(or)h (cache)f(of)g(objects)h(\227)g(with)g(a)g FJ(try)f FN(statement)h(it)g (can)g(test)208 2801 y(for)c(the)h(table')-5 b(s)21 b(presence)e(and)h (skip)g(its)h(initialization)f(if)g(desired:)444 3025 y FA(try:)623 3116 y(cache)444 3208 y(except)44 b(NameError:)623 3299 y(cache)g(=)h({})208 3489 y FN(It)25 b(is)g(le)o(gal)f(though)f (generally)g(not)i(v)o(ery)e(useful)i(to)g(reload)e(b)n(uilt-in)i(or)f (dynamically)f(loaded)g(modules,)i(e)o(xcept)f(for)g FJ(sys)p FN(,)208 3588 y FJ(__main__)18 b FN(and)h FJ(__builtin__)p FN(.)k(In)c(man)o(y)f(cases,)i(ho)n(we)n(v)o(er)m(,)c(e)o(xtension)i (modules)g(are)i(not)e(designed)g(to)i(be)f(initialized)208 3688 y(more)g(than)h(once,)f(and)h(may)f(f)o(ail)i(in)f(arbitrary)f(w)o (ays)h(when)g(reloaded.)208 3821 y(If)28 b(a)g(module)f(imports)g (objects)h(from)f(another)g(module)g(using)g FJ(from)h FN(.)12 b(.)g(.)63 b FJ(import)27 b FN(.)12 b(.)g(.)g(,)31 b(calling)d FJ(reload\(\))f FN(for)h(the)208 3920 y(other)22 b(module)f(does)i(not)g(rede\002ne)f(the)h(objects)g(imported)e(from)h (it)i(\227)f(one)g(w)o(ay)g(around)e(this)j(is)g(to)f(re-e)o(x)o(ecute) e(the)i FJ(from)208 4020 y FN(statement,)c(another)g(is)i(to)f(use)h FJ(import)f FN(and)f(quali\002ed)h(names)f(\()p FK(module)p FN(.)p FK(name)p FN(\))e(instead.)208 4153 y(If)29 b(a)i(module)d (instantiates)i(instances)g(of)g(a)g(class,)k(reloading)28 b(the)i(module)e(that)i(de\002nes)g(the)g(class)h(does)f(not)f(af)n (fect)h(the)208 4252 y(method)18 b(de\002nitions)i(of)f(the)h (instances)g(\227)h(the)o(y)e(continue)g(to)h(use)h(the)f(old)f(class)i (de\002nition.)j(The)c(same)g(is)h(true)f(for)f(deri)n(v)o(ed)208 4352 y(classes.)0 4499 y FD(repr)p FJ(\()p FK(object)q FJ(\))208 4599 y FN(Return)f(a)i(string)f(containing)f(a)i(printable)e (representation)f(of)i(an)g(object.)24 b(This)c(is)g(the)f(same)h(v)n (alue)f(yielded)f(by)h(con)m(v)o(ersions)208 4698 y(\(re)n(v)o(erse)k (quotes\).)38 b(It)25 b(is)g(sometimes)g(useful)f(to)h(be)g(able)f(to)h (access)g(this)h(operation)d(as)i(an)g(ordinary)d(function.)37 b(F)o(or)25 b(man)o(y)208 4798 y(types,)i(this)g(function)e(mak)o(es)h (an)h(attempt)f(to)h(return)e(a)i(string)f(that)h(w)o(ould)f(yield)g (an)g(object)g(with)h(the)g(same)f(v)n(alue)g(when)208 4897 y(passed)20 b(to)g FJ(eval\(\))p FN(.)0 5044 y FD(reversed)p FJ(\()p FK(seq)p FJ(\))208 5144 y FN(Return)e(a)h(re)n(v)o(erse)e (iterator)-5 b(.)24 b FK(seq)19 b FN(must)g(be)f(an)h(object)f(which)g (supports)f(the)i(sequence)e(protocol)g(\(the)h FJ(__len__\(\))g FN(method)208 5244 y(and)h(the)h FJ(__getitem__\(\))f FN(method)g(with)h(inte)o(ger)f(ar)o(guments)f(starting)i(at)h FJ(0)p FN(\).)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)2981 b(13)p eop end %%Page: 14 26 TeXDict begin 14 25 bop 0 83 a FD(round)p FJ(\()p FK(x)p FC([)p FK(,)19 b(n)12 b FC(])p FJ(\))208 183 y FN(Return)22 b(the)g(\003oating)g(point)f(v)n(alue)h FK(x)h FN(rounded)d(to)j FK(n)f FN(digits)h(after)f(the)g(decimal)g(point.)31 b(If)22 b FK(n)g FN(is)i(omitted,)e(it)h(def)o(aults)f(to)g(zero.)208 282 y(The)j(result)g(is)i(a)f(\003oating)f(point)f(number)-5 b(.)40 b(V)-9 b(alues)25 b(are)h(rounded)d(to)j(the)f(closest)h (multiple)f(of)g(10)h(to)f(the)h(po)n(wer)e(minus)h FK(n)p FN(;)208 382 y(if)e(tw)o(o)g(multiples)g(are)g(equally)f(close,)h (rounding)e(is)j(done)e(a)o(w)o(ay)g(from)g(0)i(\(so.)33 b(for)22 b(e)o(xample,)g FJ(round\(0.5\))g FN(is)i FJ(1.0)f FN(and)208 482 y FJ(round\(-0.5\))18 b FN(is)j FJ(-1.0)p FN(\).)0 628 y FD(set)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 728 y FN(Return)17 b(a)h(set)g(whose)g(elements)f (are)h(tak)o(en)f(from)g FK(iter)o(able)p FN(.)23 b(The)18 b(elements)f(must)h(be)f(immutable.)23 b(T)-7 b(o)18 b(represent)f(sets)h(of)g(sets,)208 828 y(the)k(inner)g(sets)i(should)e (be)h FJ(frozenset)e FN(objects.)33 b(If)22 b FK(iter)o(able)h FN(is)h(not)e(speci\002ed,)h(returns)f(a)h(ne)n(w)g(empty)f(set,)i FJ(set\([]\))p FN(.)208 927 y(Ne)n(w)c(in)g(v)o(ersion)f(2.4.)0 1074 y FD(setattr)p FJ(\()p FK(object,)f(name)o(,)h(value)p FJ(\))208 1174 y FN(This)g(is)h(the)f(counterpart)e(of)i FJ(getattr\(\))p FN(.)24 b(The)19 b(ar)o(guments)e(are)i(an)g(object,)g (a)h(string)f(and)f(an)h(arbitrary)f(v)n(alue.)24 b(The)19 b(string)208 1273 y(may)j(name)g(an)h(e)o(xisting)f(attrib)n(ute)h(or)g (a)g(ne)n(w)g(attrib)n(ute.)33 b(The)22 b(function)f(assigns)j(the)f(v) n(alue)f(to)h(the)g(attrib)n(ute,)g(pro)o(vided)e(the)208 1373 y(object)e(allo)n(ws)i(it.)k(F)o(or)20 b(e)o(xample,)f FJ(setattr\()p FK(x)p FJ(,)48 b(')p FK(foobar)r FJ(',)g(123\))20 b FN(is)h(equi)n(v)n(alent)d(to)i FK(x)p FJ(.)p FK(foobar)51 b FJ(=)e(123)p FN(.)0 1520 y FD(slice)p FJ(\()p FC([)p FK(start,)12 b FC(])19 b FK(stop)p FC([)p FK(,)h(step)12 b FC(])p FJ(\))208 1620 y FN(Return)25 b(a)i(slice)g(object)e (representing)f(the)i(set)h(of)f(indices)g(speci\002ed)g(by)g FJ(range\()p FK(start)q FJ(,)49 b FK(stop)p FJ(,)g FK(step)p FJ(\))p FN(.)43 b(The)26 b FK(start)i FN(and)208 1719 y FK(step)c FN(ar)o(guments)f(def)o(ault)g(to)i FJ(None)p FN(.)38 b(Slice)25 b(objects)f(ha)n(v)o(e)g(read-only)e(data)i(attrib)n (utes)h FJ(start)p FN(,)g FJ(stop)f FN(and)g FJ(step)g FN(which)208 1819 y(merely)h(return)g(the)h(ar)o(gument)d(v)n(alues)j (\(or)f(their)h(def)o(ault\).)42 b(The)o(y)25 b(ha)n(v)o(e)g(no)h (other)f(e)o(xplicit)g(functionality;)i(ho)n(we)n(v)o(er)d(the)o(y)208 1918 y(are)c(used)g(by)h(Numerical)e(Python)h(and)g(other)g(third)g (party)f(e)o(xtensions.)26 b(Slice)21 b(objects)f(are)h(also)g (generated)e(when)h(e)o(xtended)208 2018 y(inde)o(xing)e(syntax)h(is)i (used.)k(F)o(or)20 b(e)o(xample:)k(`)p FJ(a[start:stop:step])p FN(')16 b(or)k(`)p FJ(a[start:stop,)47 b(i])p FN('.)0 2165 y FD(sorted)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)18 b(cmp)p FC([)p FK(,)i(k)o(e)n(y)p FC([)p FK(,)f(r)m(e)o(ver)o(se)12 b FC(])g(])g(])p FJ(\))208 2265 y FN(Return)19 b(a)i(ne)n(w)f(sorted)g (list)h(from)e(the)h(items)h(in)f FK(iter)o(able)p FN(.)208 2397 y(The)g(optional)g(ar)o(guments)g FK(cmp)p FN(,)h FK(k)o(e)n(y)p FN(,)g(and)f FK(r)m(e)o(ver)o(se)i FN(ha)n(v)o(e)f(the)g (same)h(meaning)d(as)j(those)f(for)g(the)g FJ(list.sort\(\))f FN(method)208 2497 y(\(described)e(in)i(section)g(3.6.4\).)208 2630 y FK(cmp)i FN(speci\002es)h(a)g(custom)f(comparison)f(function)g (of)h(tw)o(o)h(ar)o(guments)e(\(iterable)h(elements\))g(which)g(should) g(return)f(a)i(ne)o(ga-)208 2729 y(ti)n(v)o(e,)i(zero)f(or)g(positi)n (v)o(e)f(number)g(depending)f(on)i(whether)f(the)i(\002rst)g(ar)o (gument)d(is)k(considered)c(smaller)j(than,)g(equal)e(to,)j(or)208 2829 y(lar)o(ger)18 b(than)i(the)g(second)g(ar)o(gument:)j(`)p FK(cmp)p FJ(=lambda)47 b FK(x)p FJ(,)p FK(y)p FJ(:)99 b(cmp\(x.lower\(\),)47 b(y.lower\(\)\))p FN(')208 2962 y FK(k)o(e)n(y)33 b FN(speci\002es)i(a)f(function)e(of)i(one)f(ar)o (gument)f(that)i(is)g(used)g(to)g(e)o(xtract)f(a)i(comparison)c(k)o(e)o (y)j(from)f(each)g(list)i(element:)208 3062 y(`)p FK(k)o(e)n(y)p FJ(=str.lower)p FN(')208 3194 y FK(r)m(e)o(ver)o(se)20 b FN(is)g(a)g(boolean)d(v)n(alue.)24 b(If)19 b(set)h(to)g FJ(True)p FN(,)f(then)g(the)g(list)h(elements)f(are)h(sorted)e(as)i(if) g(each)f(comparison)e(were)i(re)n(v)o(ersed.)208 3327 y(In)e(general,)g(the)i FK(k)o(e)n(y)e FN(and)h FK(r)m(e)o(ver)o(se)h FN(con)m(v)o(ersion)c(processes)j(are)g(much)f(f)o(aster)h(than)g (specifying)e(an)i(equi)n(v)n(alent)f FK(cmp)h FN(function.)208 3427 y(This)g(is)i(because)e FK(cmp)h FN(is)h(called)e(multiple)g (times)h(for)g(each)f(list)i(element)e(while)h FK(k)o(e)n(y)f FN(and)h FK(r)m(e)o(ver)o(se)g FN(touch)f(each)g(element)g(only)208 3526 y(once.)208 3659 y(Ne)n(w)i(in)g(v)o(ersion)f(2.4.)0 3806 y FD(staticmethod)p FJ(\()p FK(function)p FJ(\))208 3906 y FN(Return)g(a)i(static)g(method)e(for)g FK(function)p FN(.)208 4039 y(A)h(static)h(method)e(does)h(not)g(recei)n(v)o(e)f(an)h (implicit)g(\002rst)h(ar)o(gument.)i(T)-7 b(o)20 b(declare)g(a)g (static)h(method,)e(use)h(this)h(idiom:)444 4263 y FA(class)44 b(C:)623 4354 y(@staticmethod)623 4445 y(def)g(f\(arg1,)g(arg2,)g (...\):)g(...)208 4635 y FN(The)19 b FJ(@staticmethod)e FN(form)h(is)j(a)e(function)f(decorator)f(\226)j(see)g(the)f (description)f(of)h(function)e(de\002nitions)i(in)g(chapter)f(7)i(of) 208 4735 y(the)g FK(Python)f(Refer)m(ence)g(Manual)g FN(for)h(details.)208 4867 y(It)27 b(can)h(be)g(called)f(either)g(on)g (the)h(class)h(\(such)e(as)h FJ(C.f\(\))p FN(\))f(or)g(on)h(an)f (instance)g(\(such)g(as)i FJ(C\(\).f\(\))p FN(\).)46 b(The)27 b(instance)h(is)208 4967 y(ignored)18 b(e)o(xcept)h(for)h(its) h(class.)208 5100 y(Static)36 b(methods)e(in)i(Python)f(are)g(similar)h (to)g(those)f(found)f(in)i(Ja)n(v)n(a)g(or)f(C)2510 5093 y(++)2604 5100 y(.)72 b(F)o(or)35 b(a)i(more)d(adv)n(anced)g(concept,)k (see)208 5199 y FJ(classmethod\(\))18 b FN(in)i(this)h(section.)p 0 5549 3901 4 v 0 5649 a FI(14)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 15 27 TeXDict begin 15 26 bop 208 83 a FN(F)o(or)25 b(more)f(information)f (on)i(static)h(methods,)f(consult)g(the)g(documentation)e(on)i(the)g (standard)f(type)h(hierarchy)e(in)j(chapter)208 183 y(3)e(of)h(the)f FK(Python)g(Refer)m(ence)g(Manual)f FN(\(at)i(the)g(bottom\).)75 b(Ne)n(w)25 b(in)g(v)o(ersion)e(2.2.)116 b(Changed)24 b(in)g(v)o(ersion)g(2.4:)g(Function)208 282 y(decorator)18 b(syntax)h(added.)0 429 y FD(str)p FJ(\()p FC([)p FK(object)13 b FC(])p FJ(\))208 529 y FN(Return)29 b(a)i(string)e(containing)f(a)j (nicely)e(printable)g(representation)f(of)i(an)g(object.)53 b(F)o(or)30 b(strings,)i(this)f(returns)e(the)h(string)208 628 y(itself.)25 b(The)20 b(dif)n(ference)d(with)j FJ(repr\()p FK(object)q FJ(\))f FN(is)i(that)f FJ(str\()p FK(object)q FJ(\))f FN(does)h(not)f(al)o(w)o(ays)h(attempt)g(to)g(return)f(a)h (string)g(that)g(is)208 728 y(acceptable)f(to)j FJ(eval\(\))p FN(;)f(its)h(goal)e(is)i(to)f(return)f(a)h(printable)f(string.)27 b(If)21 b(no)g(ar)o(gument)d(is)k(gi)n(v)o(en,)e(returns)g(the)h(empty) f(string,)208 828 y FJ('')p FN(.)0 975 y FD(sum)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)f(start)13 b FC(])p FJ(\))208 1074 y FN(Sums)29 b FK(start)j FN(and)d(the)h(items)g(of)f(an)h FK(iter)o(able)f FN(from)f(left)i(to)g(right)f(and)g(returns)g(the)g (total.)54 b FK(start)32 b FN(def)o(aults)d(to)g FJ(0)p FN(.)54 b(The)29 b FK(it-)208 1174 y(er)o(able)p FN(')-5 b(s)25 b(items)i(are)f(normally)e(numbers,)i(and)g(are)f(not)h(allo)n (wed)g(to)g(be)g(strings.)42 b(The)26 b(f)o(ast,)i(correct)d(w)o(ay)h (to)g(concatenate)208 1273 y(a)h(sequence)f(of)g(strings)h(is)h(by)f (calling)f FJ(''.join\()p FK(sequence)p FJ(\))p FN(.)43 b(Note)27 b(that)g FJ(sum\(range\()p FK(n)p FJ(\),)47 b FK(m)p FJ(\))27 b FN(is)h(equi)n(v)n(alent)d(to)208 1373 y FJ(reduce\(operator.add,)46 b(range\()p FK(n)p FJ(\),)h FK(m)p FJ(\))42 b FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 1520 y FD(super)p FJ(\()p FK(type)p FC([)p FK(,)g(object-or)n(-type)12 b FC(])p FJ(\))208 1620 y FN(Return)25 b(the)g(superclass)h(of)f FK(type)p FN(.)41 b(If)26 b(the)f(second)g(ar)o(gument)e(is)k(omitted)e (the)g(super)g(object)g(returned)f(is)j(unbound.)38 b(If)26 b(the)208 1719 y(second)k(ar)o(gument)f(is)j(an)f(object,)i FJ(isinstance\()p FK(obj)p FJ(,)47 b FK(type)p FJ(\))30 b FN(must)i(be)f(true.)57 b(If)31 b(the)h(second)e(ar)o(gument)f(is)j (a)f(type,)208 1819 y FJ(issubclass\()p FK(type2)p FJ(,)46 b FK(type)p FJ(\))20 b FN(must)g(be)g(true.)25 b FJ(super\(\))19 b FN(only)h(w)o(orks)f(for)h(ne)n(w-style)f(classes.)208 1948 y(A)h(typical)g(use)g(for)g(calling)g(a)g(cooperati)n(v)o(e)e (superclass)i(method)f(is:)444 2169 y FA(class)44 b(C\(B\):)623 2260 y(def)g(meth\(self,)g(arg\):)802 2352 y(super\(C,)g (self\).meth\(arg\))208 2538 y FN(Note)28 b(that)g FJ(super)f FN(is)i(implemented)d(as)j(part)f(of)f(the)h(binding)f(process)g(for)h (e)o(xplicit)f(dotted)g(attrib)n(ute)h(lookups)e(such)i(as)208 2637 y(`)p FJ(super\(C,)48 b(self\).__getitem__\(name\))p FN('.)20 b(Accordingly)-5 b(,)16 b FJ(super)j FN(is)h(unde\002ned)c (for)j(implicit)g(lookups)e(using)208 2737 y(statements)j(or)g (operators)e(such)i(as)h(`)p FJ(super\(C,)48 b(self\)[name])p FN('.)h(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 2884 y FD(tuple)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 2983 y FN(Return)18 b(a)h(tuple)f(whose)g(items)h(are)f(the)h(same)g(and)e (in)i(the)g(same)f(order)g(as)h FK(iter)o(able)p FN(')-5 b(s)18 b(items.)25 b FK(iter)o(able)18 b FN(may)g(be)h(a)g(sequence,)e (a)208 3083 y(container)g(that)i(supports)e(iteration,)i(or)f(an)h (iterator)f(object.)24 b(If)19 b FK(iter)o(able)f FN(is)i(already)d(a)j (tuple,)e(it)i(is)f(returned)e(unchanged.)22 b(F)o(or)208 3183 y(instance,)17 b FJ(tuple\('abc'\))f FN(returns)h FJ(\('a',)48 b('b',)i('c'\))17 b FN(and)g FJ(tuple\([1,)48 b(2,)i(3]\))17 b FN(returns)g FJ(\(1,)49 b(2,)g(3\))p FN(.)25 b(If)208 3282 y(no)19 b(ar)o(gument)f(is)j(gi)n(v)o(en,)e (returns)g(a)i(ne)n(w)f(empty)f(tuple,)h FJ(\(\))p FN(.)0 3429 y FD(type)p FJ(\()p FK(object)q FJ(\))208 3529 y FN(Return)30 b(the)h(type)f(of)g(an)h FK(object)q FN(.)56 b(The)31 b(return)e(v)n(alue)h(is)i(a)f(type)f(object.)56 b(The)31 b FJ(isinstance\(\))e FN(b)n(uilt-in)h(function)f(is)208 3628 y(recommended)17 b(for)i(testing)h(the)h(type)e(of)h(an)g(object.) 208 3758 y(W)m(ith)g(three)g(ar)o(guments,)e FJ(type)i FN(functions)e(as)j(a)g(constructor)d(as)j(detailed)f(belo)n(w)-5 b(.)0 3905 y FD(type)p FJ(\()p FK(name)o(,)19 b(bases,)h(dict)q FJ(\))208 4004 y FN(Return)28 b(a)h(ne)n(w)g(type)g(object.)51 b(This)29 b(is)h(essentially)f(a)g(dynamic)f(form)g(of)g(the)h FJ(class)g FN(statement.)51 b(The)29 b FK(name)f FN(string)h(is)208 4104 y(the)c(class)i(name)e(and)g(becomes)g(the)h FJ(__name__)e FN(attrib)n(ute;)k(the)e FK(bases)g FN(tuple)f(itemizes)h(the)g(base)g (classes)g(and)g(becomes)208 4204 y(the)f FJ(__bases__)g FN(attrib)n(ute;)i(and)e(the)h FK(dict)h FN(dictionary)d(is)i(the)g (namespace)e(containing)g(de\002nitions)h(for)f(class)j(body)d(and)208 4303 y(becomes)19 b(the)h FJ(__dict__)f FN(attrib)n(ute.)25 b(F)o(or)20 b(e)o(xample,)e(the)i(follo)n(wing)f(tw)o(o)h(statements)h (create)f(identical)f FJ(type)h FN(objects:)533 4524 y FA(>>>)45 b(class)f(X\(object\):)533 4615 y(...)224 b(a)45 b(=)f(1)533 4707 y(...)533 4798 y(>>>)h(X)f(=)h(type\('X',)e (\(object,\),)h(dict\(a=1\)\))208 4954 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 5101 y FD(unichr)p FJ(\()p FK(i)p FJ(\))208 5201 y FN(Return)k(the)h(Unicode)f(string)h(of)g(one)f (character)g(whose)h(Unicode)f(code)g(is)i(the)f(inte)o(ger)f FK(i)p FN(.)38 b(F)o(or)23 b(e)o(xample,)h FJ(unichr\(97\))208 5300 y FN(returns)17 b(the)i(string)g FJ(u'a')p FN(.)24 b(This)19 b(is)h(the)e(in)m(v)o(erse)g(of)h FJ(ord\(\))f FN(for)g(Unicode)g(strings.)24 b(The)19 b(v)n(alid)f(range)g(for)g(the) h(ar)o(gument)d(de-)208 5400 y(pends)f(ho)n(w)h(Python)f(w)o(as)i (con\002gured)d(\226)i(it)h(may)f(be)g(either)g(UCS2)h([0..0xFFFF])e (or)h(UCS4)g([0..0x10FFFF].)e FJ(ValueError)p 0 5549 3901 4 v 0 5649 a FI(2.1.)52 b(Built-in)25 b(Functions)2981 b(15)p eop end %%Page: 16 28 TeXDict begin 16 27 bop 208 83 a FN(is)21 b(raised)f(otherwise.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 230 y FD(unicode)p FJ(\()p FC([)p FK(object)q FC([)p FK(,)f(encoding)g FC([)p FK(,)i(err)l(or)o(s)12 b FC(])g(])g(])p FJ(\))208 330 y FN(Return)19 b(the)i(Unicode)e(string)g(v)o(ersion)g(of)h FK(object)h FN(using)f(one)g(of)g(the)g(follo)n(wing)e(modes:)208 462 y(If)27 b FK(encoding)f FN(and/or)h FK(err)l(or)o(s)j FN(are)e(gi)n(v)o(en,)g FJ(unicode\(\))f FN(will)i(decode)d(the)i (object)g(which)f(can)h(either)g(be)g(an)f(8-bit)h(string)208 562 y(or)c(a)i(character)d(b)n(uf)n(fer)h(using)h(the)g(codec)f(for)g FK(encoding)p FN(.)38 b(The)24 b FK(encoding)f FN(parameter)h(is)i(a)f (string)g(gi)n(ving)e(the)i(name)g(of)g(an)208 662 y(encoding;)c(if)i (the)f(encoding)f(is)i(not)f(kno)n(wn,)f FJ(LookupError)g FN(is)j(raised.)31 b(Error)22 b(handling)e(is)k(done)d(according)f(to)j FK(err)l(or)o(s)p FN(;)208 761 y(this)h(speci\002es)h(the)f(treatment)f (of)h(characters)f(which)h(are)g(in)m(v)n(alid)f(in)h(the)h(input)e (encoding.)35 b(If)24 b FK(err)l(or)o(s)i FN(is)f FJ('strict')e FN(\(the)208 861 y(def)o(ault\),)e(a)i FJ(ValueError)e FN(is)i(raised)f(on)g(errors,)g(while)g(a)h(v)n(alue)e(of)h FJ('ignore')g FN(causes)g(errors)g(to)g(be)g(silently)h(ignored,)208 960 y(and)e(a)h(v)n(alue)g(of)f FJ('replace')g FN(causes)i(the)f(of)n (\002cial)f(Unicode)g(replacement)f(character)m(,)h FJ(U+FFFD)p FN(,)g(to)h(be)g(used)g(to)g(replace)208 1060 y(input)d(characters)g (which)h(cannot)f(be)h(decoded.)j(See)e(also)f(the)h FJ(codecs)e FN(module.)208 1193 y(If)27 b(no)h(optional)f(parameters)f (are)i(gi)n(v)o(en,)h FJ(unicode\(\))d FN(will)j(mimic)f(the)g(beha)n (viour)e(of)h FJ(str\(\))h FN(e)o(xcept)f(that)h(it)g(returns)208 1293 y(Unicode)22 b(strings)i(instead)g(of)g(8-bit)f(strings.)36 b(More)23 b(precisely)-5 b(,)24 b(if)g FK(object)h FN(is)g(a)f(Unicode) f(string)h(or)f(subclass)h(it)h(will)g(return)208 1392 y(that)20 b(Unicode)f(string)h(without)f(an)o(y)h(additional)e (decoding)h(applied.)208 1525 y(F)o(or)j(objects)g(which)g(pro)o(vide)f (a)i FJ(__unicode__\(\))e FN(method,)g(it)j(will)f(call)g(this)g (method)f(without)f(ar)o(guments)g(to)i(create)f(a)208 1625 y(Unicode)f(string.)33 b(F)o(or)23 b(all)h(other)e(objects,)h(the) g(8-bit)g(string)f(v)o(ersion)g(or)h(representation)e(is)j(requested)d (and)i(then)f(con)m(v)o(erted)208 1724 y(to)e(a)h(Unicode)e(string)g (using)h(the)g(codec)g(for)f(the)h(def)o(ault)g(encoding)e(in)i FJ('strict')g FN(mode.)208 1857 y(Ne)n(w)g(in)g(v)o(ersion)f(2.0.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.2:)h(Support)e(for)i FJ(__unicode__\(\))e FN(added.)0 2004 y FD(vars)p FJ(\()p FC([)p FK(object)13 b FC(])p FJ(\))208 2104 y FN(W)m(ithout)23 b(ar)o(guments,)h(return)f(a)i(dictionary)e(corresponding)e(to)j(the)h (current)e(local)i(symbol)e(table.)38 b(W)m(ith)25 b(a)g(module,)f (class)208 2203 y(or)29 b(class)i(instance)f(object)g(as)g(ar)o(gument) e(\(or)h(an)o(ything)f(else)j(that)f(has)h(a)f FJ(__dict__)f FN(attrib)n(ute\),)j(returns)d(a)h(dictionary)208 2303 y(corresponding)19 b(to)k(the)g(object')-5 b(s)23 b(symbol)f(table.)33 b(The)23 b(returned)e(dictionary)g(should)h(not)h(be)g(modi\002ed:)29 b(the)23 b(ef)n(fects)g(on)g(the)208 2402 y(corresponding)16 b(symbol)k(table)g(are)g(unde\002ned.)1624 2372 y FF(4)0 2549 y FD(xrange)p FJ(\()p FC([)p FK(start,)12 b FC(])19 b FK(stop)p FC([)p FK(,)h(step)12 b FC(])p FJ(\))208 2649 y FN(This)25 b(function)e(is)j(v)o(ery)e(similar)h(to)g FJ(range\(\))p FN(,)g(b)n(ut)g(returns)f(an)h(\223xrange)f(object\224)g (instead)h(of)f(a)i(list.)40 b(This)25 b(is)h(an)f(opaque)208 2749 y(sequence)d(type)h(which)g(yields)g(the)h(same)f(v)n(alues)g(as)i (the)e(corresponding)d(list,)25 b(without)e(actually)g(storing)g(them)g (all)h(simul-)208 2848 y(taneously)-5 b(.)39 b(The)25 b(adv)n(antage)e(of)i FJ(xrange\(\))g FN(o)o(v)o(er)f FJ(range\(\))h FN(is)h(minimal)f(\(since)g FJ(xrange\(\))g FN(still)h(has)g(to)f(create)h(the)208 2948 y(v)n(alues)20 b(when)h(ask)o(ed)g(for)f(them\))h(e)o(xcept)f(when)h(a)g(v)o(ery)f (lar)o(ge)g(range)h(is)h(used)f(on)f(a)i(memory-starv)o(ed)c(machine)i (or)g(when)h(all)208 3048 y(of)e(the)i(range')-5 b(s)19 b(elements)h(are)g(ne)n(v)o(er)f(used)h(\(such)g(as)g(when)g(the)g (loop)g(is)h(usually)e(terminated)g(with)i FJ(break)p FN(\).)208 3180 y FL(Note:)29 b FJ(xrange\(\))22 b FN(is)i(intended)d (to)i(be)g(simple)g(and)f(f)o(ast.)34 b(Implementations)21 b(may)h(impose)g(restrictions)h(to)g(achie)n(v)o(e)e(this.)208 3280 y(The)k(C)i(implementation)d(of)i(Python)e(restricts)j(all)f(ar)o (guments)e(to)i(nati)n(v)o(e)g(C)h(longs)e(\(\224short\224)g(Python)g (inte)o(gers\),)h(and)f(also)208 3380 y(requires)19 b(that)h(the)g (number)f(of)h(elements)f(\002t)i(in)g(a)f(nati)n(v)o(e)g(C)h(long.)0 3526 y FD(zip)p FJ(\()p FC([)p FK(iter)o(able)o(,)e(...)12 b FC(])p FJ(\))208 3626 y FN(This)24 b(function)f(returns)g(a)i(list)g (of)f(tuples,)h(where)f(the)g FK(i)p FN(-th)g(tuple)g(contains)f(the)i FK(i)p FN(-th)f(element)g(from)f(each)h(of)g(the)g(ar)o(gument)208 3726 y(sequences)d(or)h(iterables.)32 b(The)22 b(returned)f(list)i(is)h (truncated)d(in)h(length)g(to)h(the)f(length)g(of)g(the)h(shortest)f (ar)o(gument)e(sequence.)208 3825 y(When)f(there)g(are)g(multiple)g(ar) o(guments)e(which)i(are)h(all)g(of)f(the)g(same)h(length,)e FJ(zip\(\))i FN(is)g(similar)g(to)f FJ(map\(\))g FN(with)h(an)f (initial)208 3925 y(ar)o(gument)f(of)i FJ(None)p FN(.)27 b(W)m(ith)21 b(a)g(single)g(sequence)e(ar)o(gument,)g(it)i(returns)f(a) h(list)h(of)e(1-tuples.)26 b(W)m(ith)21 b(no)f(ar)o(guments,)f(it)i (returns)208 4025 y(an)f(empty)f(list.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.0.)208 4157 y(Changed)25 b(in)j(v)o(ersion)e (2.4:)g(F)o(ormerly)-5 b(,)27 b FJ(zip\(\))g FN(required)e(at)i(least)h (one)f(ar)o(gument)e(and)h FJ(zip\(\))h FN(raised)g(a)h FJ(TypeError)208 4257 y FN(instead)20 b(of)f(returning)g(an)h(empty)f (list.)0 4584 y FE(2.2)121 b(Non-essential)35 b(Built-in)d(Functions)0 4817 y FN(There)19 b(are)i(se)n(v)o(eral)e(b)n(uilt-in)h(functions)f (that)h(are)g(no)g(longer)f(essential)i(to)f(learn,)g(kno)n(w)f(or)h (use)g(in)h(modern)d(Python)h(programming.)0 4917 y(The)o(y)g(ha)n(v)o (e)h(been)f(k)o(ept)h(here)g(to)g(maintain)f(backw)o(ards)g (compatibility)g(with)h(programs)f(written)h(for)f(older)g(v)o(ersions) h(of)g(Python.)0 5064 y(Python)j(programmers,)f(trainers,)j(students)f (and)f(bookwriters)g(should)g(feel)h(free)g(to)g(bypass)g(these)h (functions)d(without)i(concerns)0 5163 y(about)19 b(missing)h (something)f(important.)p 0 5235 1560 4 v 90 5290 a FB(4)120 5314 y FH(In)e(the)i(current)g(implementation,)i(local)e(v)n(ariable)i (bindings)e(cannot)g(normally)g(be)f(af)n(fected)j(this)d(w)o(ay)l(,)f (b)o(ut)h(v)n(ariables)j(retrie)n(v)o(ed)f(from)e(other)g(scopes)h (\(such)f(as)0 5392 y(modules\))g(can)g(be.)i(This)d(may)g(change.)p 0 5549 3901 4 v 0 5649 a FI(16)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 17 29 TeXDict begin 17 28 bop 0 83 a FD(apply)p FJ(\()p FK(function,)18 b(ar)m(gs)p FC([)p FK(,)h(k)o(e)n(ywor)m(ds)12 b FC(])p FJ(\))208 183 y FN(The)18 b FK(function)f FN(ar)o(gument)f(must)i(be)h (a)g(callable)f(object)g(\(a)g(user)n(-de\002ned)f(or)h(b)n(uilt-in)g (function)f(or)h(method,)f(or)h(a)h(class)g(object\))208 282 y(and)h(the)h FK(ar)m(gs)g FN(ar)o(gument)d(must)j(be)g(a)g (sequence.)26 b(The)20 b FK(function)g FN(is)h(called)g(with)g FK(ar)m(gs)g FN(as)g(the)g(ar)o(gument)e(list;)j(the)f(number)e(of)208 382 y(ar)o(guments)e(is)k(the)f(length)e(of)i(the)g(tuple.)k(If)c(the)f (optional)g FK(k)o(e)n(ywor)m(ds)g FN(ar)o(gument)e(is)k(present,)e(it) h(must)g(be)g(a)g(dictionary)e(whose)208 482 y(k)o(e)o(ys)i(are)h (strings.)28 b(It)22 b(speci\002es)f(k)o(e)o(yw)o(ord)f(ar)o(guments)f (to)i(be)g(added)f(to)i(the)f(end)f(of)h(the)g(ar)o(gument)e(list.)29 b(Calling)21 b FJ(apply\(\))208 581 y FN(is)e(dif)n(ferent)f(from)f (just)j(calling)e FK(function)p FJ(\()p FK(ar)m(gs)p FJ(\))p FN(,)f(since)i(in)g(that)g(case)g(there)g(is)g(al)o(w)o(ays)h (e)o(xactly)e(one)g(ar)o(gument.)k(The)d(use)g(of)208 681 y FJ(apply\(\))g FN(is)i(e)o(xactly)e(equi)n(v)n(alent)g(to)h FK(function)p FJ(\()1684 696 y(*)1734 681 y FK(ar)m(gs)p FJ(,)1976 696 y(**)2076 681 y FK(k)o(e)n(ywor)m(ds)p FJ(\))p FN(.)208 814 y FL(Depr)o(ecated)f(since)i(r)o(elease)e(2.3.)24 b FN(Use)d(the)f(e)o(xtended)f(call)h(syntax)g(with)2380 829 y FJ(*)2430 814 y(args)g FN(and)2791 829 y FJ(**)2891 814 y(keywords)f FN(instead.)0 960 y FD(buffer)p FJ(\()p FK(object)q FC([)p FK(,)f(of)o(fset)q FC([)p FK(,)j(size)12 b FC(])g(])p FJ(\))208 1060 y FN(The)j FK(object)i FN(ar)o(gument)c (must)j(be)g(an)f(object)g(that)h(supports)f(the)h(b)n(uf)n(fer)e(call) i(interf)o(ace)f(\(such)g(as)i(strings,)f(arrays,)g(and)f(b)n(uf)n (fers\).)208 1160 y(A)k(ne)n(w)g(b)n(uf)n(fer)e(object)i(will)g(be)g (created)f(which)g(references)g(the)h FK(object)h FN(ar)o(gument.)i (The)c(b)n(uf)n(fer)g(object)g(will)i(be)f(a)g(slice)h(from)208 1259 y(the)i(be)o(ginning)e(of)j FK(object)g FN(\(or)f(from)g(the)g (speci\002ed)h FK(of)o(fset)q FN(\).)32 b(The)22 b(slice)i(will)f(e)o (xtend)e(to)i(the)g(end)f(of)g FK(object)i FN(\(or)e(will)h(ha)n(v)o(e) f(a)208 1359 y(length)d(gi)n(v)o(en)g(by)h(the)g FK(size)h FN(ar)o(gument\).)0 1506 y FD(coerce)p FJ(\()p FK(x,)e(y)p FJ(\))208 1605 y FN(Return)24 b(a)h(tuple)f(consisting)g(of)g(the)h(tw) o(o)g(numeric)e(ar)o(guments)g(con)m(v)o(erted)f(to)j(a)g(common)e (type,)i(using)f(the)g(same)h(rules)g(as)208 1705 y(used)19 b(by)h(arithmetic)g(operations.)j(If)d(coercion)f(is)i(not)f(possible,) f(raise)i FJ(TypeError)p FN(.)0 1852 y FD(intern)p FJ(\()p FK(string)p FJ(\))208 1952 y FN(Enter)k FK(string)h FN(in)h(the)f (table)g(of)g(\223interned\224)e(strings)i(and)g(return)e(the)j (interned)d(string)i(\226)g(which)g(is)h FK(string)f FN(itself)h(or)f(a)g(cop)o(y)-5 b(.)208 2051 y(Interning)26 b(strings)j(is)h(useful)e(to)h(gain)f(a)i(little)f(performance)d(on)j (dictionary)e(lookup)g(\226)i(if)g(the)g(k)o(e)o(ys)f(in)h(a)h (dictionary)d(are)208 2151 y(interned,)19 b(and)h(the)g(lookup)f(k)o(e) o(y)h(is)i(interned,)d(the)h(k)o(e)o(y)g(comparisons)f(\(after)h (hashing\))f(can)h(be)h(done)f(by)g(a)h(pointer)e(compare)208 2250 y(instead)29 b(of)g(a)h(string)f(compare.)50 b(Normally)-5 b(,)30 b(the)g(names)f(used)g(in)g(Python)f(programs)g(are)h (automatically)f(interned,)i(and)208 2350 y(the)23 b(dictionaries)f (used)i(to)f(hold)g(module,)g(class)h(or)f(instance)h(attrib)n(utes)f (ha)n(v)o(e)g(interned)f(k)o(e)o(ys.)70 b(Changed)22 b(in)i(v)o(ersion)e(2.3:)208 2450 y(Interned)e(strings)i(are)g(not)g (immortal)f(\(lik)o(e)h(the)o(y)g(used)g(to)g(be)g(in)g(Python)g(2.2)f (and)h(before\);)f(you)g(must)i(k)o(eep)e(a)i(reference)d(to)208 2549 y(the)g(return)f(v)n(alue)g(of)h FJ(intern\(\))f FN(around)g(to)h(bene\002t)g(from)f(it.)0 2877 y FE(2.3)121 b(Built-in)32 b(Exceptions)0 3110 y FN(Exceptions)27 b(should)g(be)h(class)h(objects.)49 b(The)28 b(e)o(xceptions)e(are)i (de\002ned)g(in)g(the)g(module)f FJ(exceptions)p FN(.)48 b(This)28 b(module)f(ne)n(v)o(er)0 3209 y(needs)d(to)g(be)g(imported)e (e)o(xplicitly:)33 b(the)24 b(e)o(xceptions)e(are)i(pro)o(vided)e(in)i (the)g(b)n(uilt-in)g(namespace)e(as)j(well)g(as)g(the)f FJ(exceptions)0 3309 y FN(module.)0 3456 y FL(Note:)36 b FN(In)26 b(past)g(v)o(ersions)f(of)h(Python)f(string)h(e)o(xceptions) e(were)i(supported.)41 b(In)26 b(Python)e(1.5)i(and)f(ne)n(wer)h(v)o (ersions,)g(all)h(standard)0 3555 y(e)o(xceptions)16 b(ha)n(v)o(e)i(been)f(con)m(v)o(erted)e(to)j(class)h(objects)f(and)f (users)h(are)g(encouraged)d(to)j(do)f(the)h(same.)25 b(String)17 b(e)o(xceptions)f(will)j(raise)f(a)0 3655 y FJ(DeprecationWarning)e FN(in)j(Python)e(2.5)h(and)g(ne)n(wer)-5 b(.)24 b(In)19 b(future)e(v)o(ersions,)h(support)f(for)h(string)g(e)o (xceptions)f(will)j(be)e(remo)o(v)o(ed.)0 3802 y(T)-7 b(w)o(o)19 b(distinct)f(string)g(objects)g(with)h(the)f(same)g(v)n (alue)g(are)g(considered)f(dif)n(ferent)g(e)o(xceptions.)22 b(This)d(is)g(done)e(to)i(force)e(programmers)0 3901 y(to)i(use)h(e)o(xception)d(names)i(rather)f(than)h(their)f(string)h(v) n(alue)g(when)f(specifying)g(e)o(xception)f(handlers.)23 b(The)c(string)g(v)n(alue)f(of)h(all)h(b)n(uilt-)0 4001 y(in)j(e)o(xceptions)e(is)i(their)g(name,)f(b)n(ut)h(this)g(is)h(not)e (a)h(requirement)d(for)i(user)n(-de\002ned)f(e)o(xceptions)g(or)i(e)o (xceptions)e(de\002ned)g(by)i(library)0 4101 y(modules.)0 4248 y(F)o(or)28 b(class)g(e)o(xceptions,)g(in)h(a)f FJ(try)g FN(statement)g(with)g(an)f FJ(except)h FN(clause)g(that)g (mentions)f(a)h(particular)f(class,)j(that)e(clause)g(also)0 4347 y(handles)j(an)o(y)h(e)o(xception)e(classes)k(deri)n(v)o(ed)c (from)i(that)g(class)h(\(b)n(ut)f(not)g(e)o(xception)f(classes)i(from)e (which)h FK(it)h FN(is)g(deri)n(v)o(ed\).)59 b(T)-7 b(w)o(o)0 4447 y(e)o(xception)18 b(classes)k(that)e(are)g(not)g(related)g(via)g (subclassing)f(are)h(ne)n(v)o(er)f(equi)n(v)n(alent,)f(e)n(v)o(en)i(if) g(the)o(y)g(ha)n(v)o(e)f(the)h(same)h(name.)0 4594 y(The)c(b)n(uilt-in) h(e)o(xceptions)e(listed)i(belo)n(w)f(can)h(be)g(generated)e(by)h(the)h (interpreter)e(or)i(b)n(uilt-in)f(functions.)23 b(Except)17 b(where)g(mentioned,)0 4693 y(the)o(y)23 b(ha)n(v)o(e)f(an)h (\223associated)g(v)n(alue\224)g(indicating)e(the)j(detailed)e(cause)i (of)f(the)g(error)-5 b(.)33 b(This)24 b(may)e(be)h(a)h(string)f(or)g(a) h(tuple)e(containing)0 4793 y(se)n(v)o(eral)f(items)h(of)f(information) e(\(e.g.,)h(an)i(error)e(code)h(and)g(a)g(string)g(e)o(xplaining)f(the) h(code\).)28 b(The)21 b(associated)g(v)n(alue)g(is)h(the)f(second)0 4893 y(ar)o(gument)14 b(to)i(the)g FJ(raise)f FN(statement.)24 b(F)o(or)15 b(string)h(e)o(xceptions,)f(the)h(associated)g(v)n(alue)f (itself)i(will)f(be)g(stored)g(in)g(the)g(v)n(ariable)f(named)0 4992 y(as)30 b(the)f(second)g(ar)o(gument)e(of)i(the)g FJ(except)g FN(clause)g(\(if)g(an)o(y\).)51 b(F)o(or)29 b(class)h(e)o(xceptions,)g(that)f(v)n(ariable)g(recei)n(v)o(es)f(the)h (e)o(xception)0 5092 y(instance.)49 b(If)28 b(the)g(e)o(xception)e (class)j(is)g(deri)n(v)o(ed)e(from)g(the)h(standard)f(root)h(class)h FJ(BaseException)p FN(,)f(the)g(associated)g(v)n(alue)g(is)0 5191 y(present)d(as)h(the)g(e)o(xception)e(instance')-5 b(s)25 b FJ(args)h FN(attrib)n(ute.)41 b(If)25 b(there)h(is)g(a)g (single)g(ar)o(gument)d(\(as)j(is)h(preferred\),)d(it)i(is)h(bound)d (to)i(the)0 5291 y FJ(message)19 b FN(attrib)n(ute.)p 0 5549 3901 4 v 0 5649 a FI(2.3.)52 b(Built-in)25 b(Exceptions)2935 b(17)p eop end %%Page: 18 30 TeXDict begin 18 29 bop 0 83 a FN(User)24 b(code)e(can)h(raise)h(b)n (uilt-in)f(e)o(xceptions.)33 b(This)23 b(can)g(be)h(used)f(to)g(test)h (an)g(e)o(xception)d(handler)h(or)h(to)h(report)e(an)h(error)f (condition)0 183 y(\223just)g(lik)o(e\224)g(the)g(situation)f(in)h (which)f(the)h(interpreter)e(raises)i(the)g(same)g(e)o(xception;)e(b)n (ut)i(be)n(w)o(are)f(that)h(there)f(is)i(nothing)c(to)j(pre)n(v)o(ent)0 282 y(user)e(code)g(from)f(raising)g(an)i(inappropriate)c(error)-5 b(.)0 429 y(The)25 b(b)n(uilt-in)g(e)o(xception)e(classes)j(can)f(be)h (sub-classed)e(to)h(de\002ne)g(ne)n(w)g(e)o(xceptions;)i(programmers)22 b(are)j(encouraged)e(to)i(at)h(least)0 529 y(deri)n(v)o(e)19 b(ne)n(w)g(e)o(xceptions)g(from)g(the)g FJ(Exception)g FN(class)i(and)f(not)f FJ(BaseException)p FN(.)k(More)c(information)f (on)h(de\002ning)g(e)o(xcep-)0 628 y(tions)h(is)h(a)n(v)n(ailable)f(in) g(the)h FK(Python)e(T)-5 b(utorial)20 b FN(under)f(the)h(heading)f (\223User)n(-de\002ned)f(Exceptions.)-6 b(\224)0 775 y(The)20 b(follo)n(wing)e(e)o(xceptions)h(are)h(only)f(used)h(as)h (base)g(classes)g(for)e(other)h(e)o(xceptions.)0 922 y FL(exception)f FD(BaseException)208 1022 y FN(The)26 b(base)g(class)i(for)d(all)i(b)n(uilt-in)f(e)o(xceptions.)42 b(It)27 b(is)g(not)g(meant)e(to)i(be)f(directly)g(inherited)f(by)h (user)n(-de\002ned)f(classes)j(\(for)208 1121 y(that)h(use)h FJ(Exception)p FN(\).)52 b(If)29 b FJ(str\(\))g FN(or)h FJ(unicode\(\))e FN(is)j(called)e(on)g(an)h(instance)f(of)g(this)h (class,)j(the)d(representation)208 1221 y(of)25 b(the)h(ar)o (gument\(s\))d(to)j(the)f(instance)h(are)g(returned)d(or)j(the)g (emptry)e(string)i(when)f(there)g(were)h(no)f(ar)o(guments.)40 b(If)25 b(only)g(a)208 1321 y(single)h(ar)o(gument)f(is)j(passed)f(in,) h(it)g(is)g(stored)e(in)h(the)g FJ(message)f FN(attrib)n(ute.)45 b(If)27 b(more)f(than)g(one)g(ar)o(gument)f(is)j(passed)f(in,)208 1420 y FJ(message)22 b FN(is)j(set)f(to)g(the)g(empty)e(string.)35 b(These)23 b(semantics)h(are)f(meant)g(to)h(re\003ect)g(the)f(f)o(act)h (that)g FJ(message)e FN(is)j(to)f(store)f(a)208 1520 y(te)o(xt)d(message)h(e)o(xplaining)e(why)h(the)i(e)o(xception)d(had)h (been)h(raised.)27 b(If)21 b(more)f(data)h(needs)g(to)g(be)g(attached)f (to)i(the)f(e)o(xception,)208 1620 y(attach)d(it)i(through)c(arbitrary) i(attrib)n(utes)g(on)h(the)g(instance.)24 b(All)19 b(ar)o(guments)e (are)i(also)g(stored)f(in)h FJ(args)g FN(as)h(a)f(tuple,)f(b)n(ut)h(it) h(will)208 1719 y(e)n(v)o(entually)e(be)i(deprecated)e(and)i(thus)g (its)h(use)g(is)g(discouraged.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.) 0 1866 y FL(exception)g FD(Exception)208 1966 y FN(All)j(b)n(uilt-in,)f (non-system-e)o(xiting)d(e)o(xceptions)i(are)h(deri)n(v)o(ed)f(from)g (this)i(class.)30 b(All)22 b(user)n(-de\002ned)e(e)o(xceptions)g (should)g(also)208 2065 y(be)g(deri)n(v)o(ed)e(from)h(this)i(class.)52 b(Changed)18 b(in)j(v)o(ersion)e(2.5:)g(Changed)g(to)i(inherit)e(from)g FJ(BaseException)p FN(.)0 2212 y FL(exception)g FD(StandardError)208 2312 y FN(The)99 b(base)h(class)i(for)d(all)i(b)n(uilt-in)e(e)o (xceptions)g(e)o(xcept)g FJ(StopIteration)p FN(,)118 b FJ(GeneratorExit)p FN(,)208 2411 y FJ(KeyboardInterrupt)17 b FN(and)j FJ(SystemExit)p FN(.)j FJ(StandardError)c FN(itself)i(is)g(deri)n(v)o(ed)d(from)h FJ(Exception)p FN(.)0 2558 y FL(exception)g FD(ArithmeticError)208 2658 y FN(The)26 b(base)i(class)g(for)e(those)h(b)n(uilt-in)g(e)o(xceptions) f(that)h(are)g(raised)g(for)g(v)n(arious)f(arithmetic)g(errors:)39 b FJ(OverflowError)p FN(,)208 2758 y FJ(ZeroDivisionError)p FN(,)17 b FJ(FloatingPointError)p FN(.)0 2904 y FL(exception)i FD(LookupError)208 3004 y FN(The)h(base)h(class)h(for)e(the)h(e)o (xceptions)f(that)h(are)g(raised)f(when)h(a)g(k)o(e)o(y)f(or)h(inde)o (x)f(used)g(on)h(a)g(mapping)e(or)i(sequence)f(is)i(in)m(v)n(alid:)208 3104 y FJ(IndexError)p FN(,)c FJ(KeyError)p FN(.)24 b(This)d(can)f(be)g (raised)g(directly)f(by)h FJ(sys.setdefaultencoding\(\))p FN(.)0 3251 y FL(exception)f FD(EnvironmentError)208 3350 y FN(The)c(base)g(class)i(for)e(e)o(xceptions)f(that)i(can)f (occur)f(outside)h(the)h(Python)e(system:)24 b FJ(IOError)p FN(,)15 b FJ(OSError)p FN(.)23 b(When)15 b(e)o(xceptions)208 3450 y(of)k(this)g(type)g(are)h(created)e(with)i(a)f(2-tuple,)f(the)i (\002rst)g(item)f(is)i(a)n(v)n(ailable)e(on)f(the)i(instance')-5 b(s)19 b FJ(errno)g FN(attrib)n(ute)g(\(it)h(is)g(assumed)208 3549 y(to)g(be)f(an)h(error)f(number\),)e(and)i(the)h(second)f(item)h (is)h(a)n(v)n(ailable)e(on)h(the)g FJ(strerror)e FN(attrib)n(ute)i (\(it)g(is)h(usually)e(the)h(associated)208 3649 y(error)f(message\).) 24 b(The)c(tuple)g(itself)g(is)i(also)e(a)n(v)n(ailable)g(on)g(the)g FJ(args)g FN(attrib)n(ute.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.5.2.) 208 3782 y(When)27 b(an)g FJ(EnvironmentError)d FN(e)o(xception)i(is)i (instantiated)e(with)i(a)f(3-tuple,)h(the)f(\002rst)h(tw)o(o)f(items)h (are)f(a)n(v)n(ailable)g(as)208 3881 y(abo)o(v)o(e,)19 b(while)i(the)g(third)f(item)h(is)h(a)n(v)n(ailable)e(on)h(the)f FJ(filename)g FN(attrib)n(ute.)27 b(Ho)n(we)n(v)o(er)m(,)19 b(for)h(backw)o(ards)g(compatibility)-5 b(,)19 b(the)208 3981 y FJ(args)h FN(attrib)n(ute)f(contains)h(only)f(a)i(2-tuple)e(of)h (the)g(\002rst)h(tw)o(o)f(constructor)f(ar)o(guments.)208 4114 y(The)g FJ(filename)g FN(attrib)n(ute)h(is)g FJ(None)g FN(when)f(this)i(e)o(xception)d(is)j(created)e(with)h(other)f(than)g(3) h(ar)o(guments.)j(The)d FJ(errno)f FN(and)208 4214 y FJ(strerror)k FN(attrib)n(utes)h(are)h(also)f FJ(None)h FN(when)f(the)g(instance)g(w)o(as)h(created)f(with)h(other)e(than)h(2)h (or)f(3)g(ar)o(guments.)36 b(In)24 b(this)208 4313 y(last)d(case,)f FJ(args)g FN(contains)f(the)i(v)o(erbatim)d(constructor)h(ar)o(guments) f(as)j(a)f(tuple.)0 4460 y(The)g(follo)n(wing)e(e)o(xceptions)h(are)h (the)g(e)o(xceptions)f(that)h(are)g(actually)g(raised.)0 4607 y FL(exception)f FD(AssertionError)208 4707 y FN(Raised)h(when)g (an)g FJ(assert)g FN(statement)g(f)o(ails.)0 4853 y FL(exception)f FD(AttributeError)208 4953 y FN(Raised)g(when)g(an)f(attrib)n(ute)h (reference)e(or)i(assignment)f(f)o(ails.)26 b(\(When)18 b(an)h(object)g(does)f(not)h(support)f(attrib)n(ute)g(references)g(or) 208 5053 y(attrib)n(ute)h(assignments)h(at)h(all,)f FJ(TypeError)f FN(is)i(raised.\))0 5200 y FL(exception)e FD(EOFError)208 5299 y FN(Raised)26 b(when)f(one)g(of)g(the)h(b)n(uilt-in)f(functions)g (\()p FJ(input\(\))f FN(or)i FJ(raw_input\(\))p FN(\))d(hits)k(an)e (end-of-\002le)f(condition)g(\()r FH(E)t(O)t(F)r FN(\))208 5399 y(without)18 b(reading)f(an)o(y)h(data.)24 b(\(N.B.:)h(the)19 b FJ(read\(\))f FN(and)g FJ(readline\(\))g FN(methods)f(of)i(\002le)g (objects)g(return)e(an)i(empty)f(string)p 0 5549 3901 4 v 0 5649 a FI(18)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 19 31 TeXDict begin 19 30 bop 208 83 a FN(when)19 b(the)o(y)h(hit)i FH(E)t(O)t(F)r FN(.\))0 230 y FL(exception)d FD(FloatingPointError)208 330 y FN(Raised)28 b(when)f(a)i(\003oating)e(point)g(operation)f(f)o (ails.)49 b(This)28 b(e)o(xception)e(is)j(al)o(w)o(ays)f(de\002ned,)h (b)n(ut)f(can)f(only)h(be)f(raised)h(when)208 429 y(Python)19 b(is)j(con\002gured)c(with)j(the)g FL(--with-fpectl)f FN(option,)f(or)i(the)f FJ(WANT_SIGFPE_HANDLER)e FN(symbol)i(is)i (de\002ned)e(in)h(the)208 529 y(`)p FO(p)n(ycon\002g.h)p FN(')d(\002le.)0 676 y FL(exception)h FD(GeneratorExit)208 775 y FN(Raise)39 b(when)e(a)i(generator')-5 b(s)36 b FJ(close\(\))i FN(method)f(is)i(called.)78 b(It)39 b(directly)e (inherits)h(from)f FJ(Exception)g FN(instead)h(of)208 875 y FJ(StandardError)18 b FN(since)i(it)h(is)g(technically)e(not)h (an)g(error)-5 b(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1022 y FL(exception)g FD(IOError)208 1121 y FN(Raised)j(when)f(an)g (I/O)h(operation)e(\(such)h(as)i(a)f FJ(print)f FN(statement,)h(the)f (b)n(uilt-in)g FJ(open\(\))h FN(function)e(or)h(a)h(method)e(of)i(a)g (\002le)208 1221 y(object\))d(f)o(ails)i(for)e(an)h(I/O-related)f (reason,)h(e.g.,)f(\223\002le)i(not)f(found\224)e(or)i(\223disk)g (full\224.)208 1354 y(This)e(class)i(is)g(deri)n(v)o(ed)d(from)h FJ(EnvironmentError)p FN(.)k(See)d(the)f(discussion)h(abo)o(v)o(e)e (for)h(more)g(information)e(on)i(e)o(xception)208 1453 y(instance)h(attrib)n(utes.)0 1600 y FL(exception)g FD(ImportError)208 1700 y FN(Raised)i(when)g(an)g FJ(import)f FN(statement)h(f)o(ails)h (to)f(\002nd)g(the)g(module)f(de\002nition)g(or)h(when)f(a)i FJ(from)49 b FN(.)12 b(.)g(.)112 b FJ(import)21 b FN(f)o(ails)g(to)208 1800 y(\002nd)e(a)i(name)f(that)g(is)h(to)f(be)h(imported.)0 1946 y FL(exception)e FD(IndexError)208 2046 y FN(Raised)28 b(when)f(a)g(sequence)g(subscript)g(is)h(out)f(of)h(range.)45 b(\(Slice)28 b(indices)f(are)h(silently)f(truncated)f(to)i(f)o(all)g (in)g(the)f(allo)n(wed)208 2146 y(range;)19 b(if)h(an)g(inde)o(x)f(is)j (not)d(a)i(plain)f(inte)o(ger)m(,)e FJ(TypeError)h FN(is)i(raised.\))0 2293 y FL(exception)e FD(KeyError)208 2392 y FN(Raised)h(when)g(a)g (mapping)f(\(dictionary\))f(k)o(e)o(y)h(is)i(not)f(found)f(in)h(the)g (set)h(of)f(e)o(xisting)f(k)o(e)o(ys.)0 2539 y FL(exception)g FD(KeyboardInterrupt)208 2639 y FN(Raised)h(when)e(the)i(user)f(hits)h (the)g(interrupt)e(k)o(e)o(y)g(\(normally)g FJ(Control-C)g FN(or)h FJ(Delete)p FN(\).)24 b(During)18 b(e)o(x)o(ecution,)g(a)i (check)e(for)208 2738 y(interrupts)i(is)i(made)e(re)o(gularly)-5 b(.)26 b(Interrupts)20 b(typed)g(when)h(a)g(b)n(uilt-in)g(function)e FJ(input\(\))i FN(or)g FJ(raw_input\(\))f FN(is)i(w)o(aiting)208 2838 y(for)f(input)g(also)i(raise)f(this)h(e)o(xception.)28 b(The)22 b(e)o(xception)e(inherits)i(from)f FJ(BaseException)f FN(so)i(as)h(to)f(not)g(be)g(accidentally)208 2938 y(caught)i(by)h (code)g(that)h(catches)f FJ(Exception)f FN(and)h(thus)h(pre)n(v)o(ent)e (the)h(interpreter)f(from)g(e)o(xiting.)82 b(Changed)24 b(in)i(v)o(ersion)208 3037 y(2.5:)19 b(Changed)g(to)h(inherit)g(from)f FJ(BaseException)p FN(.)0 3184 y FL(exception)g FD(MemoryError)208 3284 y FN(Raised)h(when)g(an)g(operation)e(runs)h(out)h(of)g(memory)e (b)n(ut)i(the)g(situation)g(may)g(still)h(be)f(rescued)f(\(by)g (deleting)h(some)f(objects\).)208 3383 y(The)c(associated)h(v)n(alue)g (is)h(a)f(string)g(indicating)f(what)h(kind)f(of)h(\(internal\))f (operation)f(ran)i(out)g(of)f(memory)-5 b(.)22 b(Note)16 b(that)g(because)208 3483 y(of)k(the)i(underlying)c(memory)h (management)g(architecture)h(\(C')-5 b(s)22 b FJ(malloc\(\))e FN(function\),)f(the)i(interpreter)f(may)g(not)h(al)o(w)o(ays)208 3583 y(be)k(able)g(to)g(completely)f(reco)o(v)o(er)f(from)h(this)h (situation;)j(it)e(ne)n(v)o(ertheless)d(raises)j(an)f(e)o(xception)e (so)j(that)f(a)h(stack)f(traceback)208 3682 y(can)20 b(be)g(printed,)e(in)j(case)f(a)h(run-a)o(w)o(ay)d(program)g(w)o(as)j (the)f(cause.)0 3829 y FL(exception)f FD(NameError)208 3929 y FN(Raised)i(when)g(a)h(local)f(or)g(global)f(name)h(is)h(not)f (found.)26 b(This)21 b(applies)g(only)g(to)g(unquali\002ed)f(names.)27 b(The)21 b(associated)g(v)n(alue)208 4028 y(is)g(an)f(error)f(message)h (that)g(includes)g(the)g(name)f(that)i(could)e(not)h(be)g(found.)0 4175 y FL(exception)f FD(NotImplementedError)208 4275 y FN(This)25 b(e)o(xception)e(is)j(deri)n(v)o(ed)d(from)h FJ(RuntimeError)p FN(.)38 b(In)24 b(user)h(de\002ned)f(base)h(classes,) j(abstract)c(methods)g(should)g(raise)208 4374 y(this)c(e)o(xception)f (when)g(the)o(y)h(require)e(deri)n(v)o(ed)h(classes)i(to)g(o)o(v)o (erride)c(the)k(method.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(1.5.2.)0 4521 y FL(exception)g FD(OSError)208 4621 y FN(This)g(class)h(is)g (deri)n(v)o(ed)d(from)h FJ(EnvironmentError)f FN(and)h(is)i(used)f (primarily)f(as)h(the)h FJ(os)f FN(module')-5 b(s)18 b FJ(os.error)g FN(e)o(xcep-)208 4721 y(tion.)42 b(See)26 b FJ(EnvironmentError)e FN(abo)o(v)o(e)h(for)g(a)h(description)f(of)h (the)g(possible)g(associated)g(v)n(alues.)85 b(Ne)n(w)27 b(in)f(v)o(ersion)208 4820 y(1.5.2.)0 4967 y FL(exception)19 b FD(OverflowError)208 5067 y FN(Raised)28 b(when)f(the)h(result)g(of)g (an)g(arithmetic)f(operation)f(is)j(too)e(lar)o(ge)g(to)h(be)g (represented.)46 b(This)28 b(cannot)f(occur)g(for)g(long)208 5166 y(inte)o(gers)g(\(which)g(w)o(ould)g(rather)h(raise)g FJ(MemoryError)e FN(than)i(gi)n(v)o(e)f(up\).)48 b(Because)28 b(of)g(the)g(lack)g(of)g(standardization)e(of)208 5266 y(\003oating)e(point)h(e)o(xception)e(handling)h(in)h(C,)h(most)f (\003oating)g(point)f(operations)g(also)i(aren')o(t)e(check)o(ed.)39 b(F)o(or)25 b(plain)g(inte)o(gers,)208 5366 y(all)c(operations)e(that)h (can)g(o)o(v)o(er\003o)n(w)f(are)i(check)o(ed)e(e)o(xcept)g(left)i (shift,)g(where)e(typical)i(applications)e(prefer)g(to)i(drop)e(bits)i (than)p 0 5549 3901 4 v 0 5649 a FI(2.3.)52 b(Built-in)25 b(Exceptions)2935 b(19)p eop end %%Page: 20 32 TeXDict begin 20 31 bop 208 83 a FN(raise)20 b(an)g(e)o(xception.)0 230 y FL(exception)f FD(ReferenceError)208 330 y FN(This)g(e)o (xception)f(is)i(raised)f(when)g(a)h(weak)f(reference)e(proxy)-5 b(,)17 b(created)i(by)g(the)g FJ(weakref.proxy\(\))e FN(function,)h(is)i(used)f(to)208 429 y(access)h(an)g(attrib)n(ute)f (of)h(the)g(referent)f(after)g(it)i(has)f(been)f(garbage)f(collected.) 24 b(F)o(or)c(more)f(information)e(on)j(weak)f(references,)208 529 y(see)29 b(the)h FJ(weakref)e FN(module.)104 b(Ne)n(w)29 b(in)h(v)o(ersion)e(2.2:)g(Pre)n(viously)g(kno)n(wn)g(as)i(the)f FJ(weakref.ReferenceError)208 628 y FN(e)o(xception.)0 775 y FL(exception)19 b FD(RuntimeError)208 875 y FN(Raised)31 b(when)f(an)g(error)f(is)j(detected)e(that)g(doesn')o(t)f(f)o(all)i(in) g(an)o(y)f(of)g(the)h(other)e(cate)o(gories.)55 b(The)30 b(associated)h(v)n(alue)f(is)h(a)208 975 y(string)25 b(indicating)f(what)h(precisely)g(went)g(wrong.)40 b(\(This)25 b(e)o(xception)e(is)k(mostly)e(a)h(relic)f(from)g(a)g(pre)n(vious)f(v)o (ersion)g(of)i(the)208 1074 y(interpreter;)18 b(it)j(is)g(not)f(used)g (v)o(ery)f(much)g(an)o(y)h(more.\))0 1221 y FL(exception)f FD(StopIteration)208 1321 y FN(Raised)36 b(by)g(an)g(iterator')-5 b(s)35 b FJ(next\(\))h FN(method)e(to)i(signal)g(that)g(there)g(are)g (no)f(further)g(v)n(alues.)71 b(This)37 b(is)f(deri)n(v)o(ed)f(from)208 1420 y FJ(Exception)28 b FN(rather)g(than)h FJ(StandardError)p FN(,)g(since)h(this)g(is)g(not)f(considered)e(an)i(error)g(in)g(its)h (normal)e(application.)208 1520 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 1667 y FL(exception)g FD(SyntaxError)208 1766 y FN(Raised)33 b(when)e(the)i(parser)f(encounters)e(a)j(syntax)f(error)-5 b(.)61 b(This)33 b(may)e(occur)h(in)g(an)h FJ(import)f FN(statement,)j(in)d(an)h FJ(exec)208 1866 y FN(statement,)20 b(in)h(a)g(call)g(to)f(the)h(b)n(uilt-in)f(function)f FJ(eval\(\))h FN(or)g FJ(input\(\))p FN(,)g(or)g(when)g(reading)f(the)i (initial)g(script)f(or)h(standard)208 1966 y(input)e(\(also)h (interacti)n(v)o(ely\).)208 2098 y(Instances)e(of)g(this)h(class)h(ha)n (v)o(e)e(attrib)n(utes)h FJ(filename)p FN(,)f FJ(lineno)p FN(,)g FJ(offset)g FN(and)g FJ(text)h FN(for)f(easier)h(access)g(to)g (the)f(details.)208 2198 y FJ(str\(\))h FN(of)h(the)g(e)o(xception)f (instance)h(returns)f(only)g(the)h(message.)0 2345 y FL(exception)f FD(SystemError)208 2445 y FN(Raised)31 b(when)f(the)h(interpreter)e(\002nds)i(an)g(internal)f(error)m(,)i(b)n (ut)f(the)g(situation)g(does)f(not)h(look)f(so)h(serious)g(to)g(cause)g (it)g(to)208 2544 y(abandon)18 b(all)i(hope.)k(The)c(associated)g(v)n (alue)g(is)h(a)f(string)g(indicating)f(what)h(went)g(wrong)f(\(in)h(lo) n(w-le)n(v)o(el)f(terms\).)208 2677 y(Y)-9 b(ou)23 b(should)h(report)f (this)i(to)g(the)g(author)e(or)h(maintainer)f(of)i(your)e(Python)g (interpreter)-5 b(.)37 b(Be)26 b(sure)e(to)h(report)e(the)i(v)o(ersion) e(of)208 2777 y(the)c(Python)g(interpreter)f(\()p FJ(sys.version)p FN(;)g(it)i(is)g(also)g(printed)f(at)h(the)f(start)h(of)g(an)f (interacti)n(v)o(e)g(Python)f(session\),)h(the)h(e)o(xact)208 2876 y(error)27 b(message)g(\(the)h(e)o(xception')-5 b(s)27 b(associated)h(v)n(alue\))f(and)g(if)i(possible)f(the)g(source)f (of)h(the)g(program)e(that)i(triggered)f(the)208 2976 y(error)-5 b(.)0 3123 y FL(exception)19 b FD(SystemExit)208 3222 y FN(This)h(e)o(xception)e(is)j(raised)f(by)g(the)g FJ(sys.exit\(\))e FN(function.)24 b(When)19 b(it)i(is)g(not)f(handled,) e(the)i(Python)f(interpreter)g(e)o(xits;)h(no)208 3322 y(stack)h(traceback)f(is)i(printed.)27 b(If)21 b(the)g(associated)g(v)n (alue)g(is)h(a)g(plain)e(inte)o(ger)m(,)g(it)i(speci\002es)g(the)f (system)h(e)o(xit)f(status)h(\(passed)e(to)208 3422 y(C')-5 b(s)21 b FJ(exit\(\))f FN(function\);)f(if)i(it)g(is)h FJ(None)p FN(,)e(the)h(e)o(xit)f(status)h(is)h(zero;)e(if)h(it)g(has)g (another)e(type)h(\(such)g(as)h(a)g(string\),)f(the)h(object')-5 b(s)208 3521 y(v)n(alue)19 b(is)i(printed)e(and)h(the)g(e)o(xit)g (status)h(is)g(one.)208 3654 y(Instances)d(ha)n(v)o(e)h(an)g(attrib)n (ute)g FJ(code)g FN(which)g(is)h(set)g(to)f(the)g(proposed)f(e)o(xit)h (status)h(or)f(error)f(message)h(\(def)o(aulting)e(to)i FJ(None)p FN(\).)208 3754 y(Also,)g(this)g(e)o(xception)e(deri)n(v)o (es)h(directly)g(from)f FJ(BaseException)g FN(and)i(not)f FJ(StandardError)p FN(,)f(since)i(it)g(is)h(not)e(techni-)208 3853 y(cally)i(an)g(error)-5 b(.)208 3986 y(A)27 b(call)h(to)f FJ(sys.exit\(\))f FN(is)i(translated)e(into)h(an)g(e)o(xception)e(so)j (that)f(clean-up)e(handlers)h(\()p FJ(finally)g FN(clauses)i(of)f FJ(try)208 4086 y FN(statements\))i(can)g(be)h(e)o(x)o(ecuted,)g(and)f (so)h(that)g(a)g(deb)n(ugger)e(can)h(e)o(x)o(ecute)g(a)h(script)g (without)f(running)e(the)j(risk)g(of)f(losing)208 4185 y(control.)23 b(The)c FJ(os._exit\(\))e FN(function)g(can)i(be)g(used)g (if)g(it)h(is)g(absolutely)e(positi)n(v)o(ely)g(necessary)g(to)h(e)o (xit)g(immediately)f(\(for)208 4285 y(e)o(xample,)g(in)i(the)h(child)e (process)h(after)g(a)h(call)f(to)h FJ(fork\(\))p FN(\).)208 4418 y(The)g(e)o(xception)e(inherits)i(from)g FJ(BaseException)e FN(instead)j(of)f FJ(StandardError)e FN(or)j FJ(Exception)e FN(so)i(that)f(it)h(is)h(not)208 4518 y(accidentally)c(caught)h(by)h (code)f(that)i(catches)e FJ(Exception)p FN(.)27 b(This)21 b(allo)n(ws)g(the)h(e)o(xception)d(to)i(properly)e(propagate)f(up)j (and)208 4617 y(cause)f(the)g(interpreter)e(to)j(e)o(xit.)50 b(Changed)19 b(in)i(v)o(ersion)d(2.5:)i(Changed)f(to)h(inherit)g(from)f FJ(BaseException)p FN(.)0 4764 y FL(exception)g FD(TypeError)208 4864 y FN(Raised)26 b(when)f(an)g(operation)f(or)h(function)f(is)j (applied)e(to)g(an)h(object)f(of)g(inappropriate)e(type.)41 b(The)25 b(associated)h(v)n(alue)f(is)h(a)208 4963 y(string)19 b(gi)n(ving)g(details)i(about)e(the)h(type)g(mismatch.)0 5110 y FL(exception)f FD(UnboundLocalError)208 5210 y FN(Raised)g(when)g(a)g(reference)e(is)j(made)f(to)g(a)g(local)g(v)n (ariable)f(in)h(a)h(function)d(or)i(method,)f(b)n(ut)h(no)f(v)n(alue)h (has)g(been)f(bound)f(to)i(that)208 5309 y(v)n(ariable.)k(This)e(is)g (a)f(subclass)h(of)f FJ(NameError)p FN(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)p 0 5549 3901 4 v 0 5649 a FI(20)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 21 33 TeXDict begin 21 32 bop 0 83 a FL(exception)19 b FD(UnicodeError)208 183 y FN(Raised)j(when)g(a)g(Unicode-related)e(encoding)g(or)h (decoding)f(error)h(occurs.)30 b(It)23 b(is)g(a)f(subclass)h(of)e FJ(ValueError)p FN(.)61 b(Ne)n(w)22 b(in)208 282 y(v)o(ersion)c(2.0.)0 429 y FL(exception)h FD(UnicodeEncodeError)208 529 y FN(Raised)26 b(when)f(a)h(Unicode-related)d(error)i(occurs)g(during)f (encoding.)39 b(It)26 b(is)h(a)f(subclass)g(of)f FJ(UnicodeError)p FN(.)82 b(Ne)n(w)26 b(in)208 628 y(v)o(ersion)18 b(2.3.)0 775 y FL(exception)h FD(UnicodeDecodeError)208 875 y FN(Raised)26 b(when)f(a)h(Unicode-related)d(error)i(occurs)g(during)f (decoding.)39 b(It)26 b(is)h(a)f(subclass)g(of)f FJ(UnicodeError)p FN(.)82 b(Ne)n(w)26 b(in)208 975 y(v)o(ersion)18 b(2.3.)0 1121 y FL(exception)h FD(UnicodeTranslateError)208 1221 y FN(Raised)24 b(when)f(a)h(Unicode-related)d(error)h(occurs)h(during)f (translating.)34 b(It)24 b(is)h(a)f(subclass)g(of)f FJ(UnicodeError)p FN(.)70 b(Ne)n(w)23 b(in)208 1321 y(v)o(ersion)18 b(2.3.)0 1468 y FL(exception)h FD(ValueError)208 1567 y FN(Raised)25 b(when)f(a)g(b)n(uilt-in)g(operation)f(or)h(function)f(recei)n(v)o(es)h (an)g(ar)o(gument)e(that)j(has)g(the)f(right)g(type)g(b)n(ut)h(an)f (inappropriate)208 1667 y(v)n(alue,)19 b(and)g(the)i(situation)e(is)j (not)d(described)g(by)h(a)h(more)e(precise)h(e)o(xception)e(such)i(as)h FJ(IndexError)p FN(.)0 1814 y FL(exception)e FD(WindowsError)208 1913 y FN(Raised)30 b(when)g(a)h(W)m(indo)n(ws-speci\002c)e(error)g (occurs)g(or)h(when)g(the)g(error)f(number)g(does)h(not)g(correspond)d (to)k(an)f FJ(errno)208 2013 y FN(v)n(alue.)35 b(The)24 b FJ(winerror)f FN(and)h FJ(strerror)f FN(v)n(alues)h(are)g(created)f (from)g(the)h(return)f(v)n(alues)h(of)g(the)g FJ(GetLastError\(\))208 2113 y FN(and)19 b FJ(FormatMessage\(\))e FN(functions)i(from)f(the)i (W)m(indo)n(ws)f(Platform)g(API.)h(The)g FJ(errno)f FN(v)n(alue)g(maps) h(the)f FJ(winerror)208 2212 y FN(v)n(alue)i(to)i(corresponding)c FJ(errno.h)j FN(v)n(alues.)31 b(This)22 b(is)i(a)f(subclass)f(of)h FJ(OSError)p FN(.)63 b(Ne)n(w)23 b(in)f(v)o(ersion)f(2.0.)96 b(Changed)21 b(in)208 2312 y(v)o(ersion)d(2.5:)i(Pre)n(vious)f(v)o (ersions)h(put)f(the)i FJ(GetLastError\(\))d FN(codes)i(into)g FJ(errno)p FN(.)0 2459 y FL(exception)f FD(ZeroDivisionError)208 2558 y FN(Raised)26 b(when)f(the)g(second)g(ar)o(gument)e(of)i(a)h(di)n (vision)f(or)g(modulo)f(operation)g(is)i(zero.)41 b(The)25 b(associated)g(v)n(alue)g(is)i(a)f(string)208 2658 y(indicating)18 b(the)j(type)e(of)h(the)g(operands)f(and)h(the)g(operation.)0 2805 y(The)g(follo)n(wing)e(e)o(xceptions)h(are)h(used)g(as)h(w)o (arning)e(cate)o(gories;)g(see)i(the)f FJ(warnings)f FN(module)g(for)h(more)f(information.)0 2952 y FL(exception)g FD(Warning)208 3051 y FN(Base)i(class)g(for)e(w)o(arning)g(cate)o (gories.)0 3198 y FL(exception)g FD(UserWarning)208 3298 y FN(Base)i(class)g(for)e(w)o(arnings)h(generated)e(by)i(user)g(code.)0 3445 y FL(exception)f FD(DeprecationWarning)208 3544 y FN(Base)i(class)g(for)e(w)o(arnings)h(about)f(deprecated)f(features.) 0 3691 y FL(exception)h FD(PendingDeprecationWarning)208 3791 y FN(Base)i(class)g(for)e(w)o(arnings)h(about)f(features)g(which)h (will)h(be)f(deprecated)e(in)j(the)f(future.)0 3938 y FL(exception)f FD(SyntaxWarning)208 4037 y FN(Base)i(class)g(for)e(w)o (arnings)h(about)f(dubious)g(syntax)0 4184 y FL(exception)g FD(RuntimeWarning)208 4284 y FN(Base)i(class)g(for)e(w)o(arnings)h (about)f(dubious)g(runtime)g(beha)n(vior)-5 b(.)0 4431 y FL(exception)19 b FD(FutureWarning)208 4530 y FN(Base)i(class)g(for)e (w)o(arnings)h(about)f(constructs)g(that)i(will)g(change)d (semantically)i(in)g(the)g(future.)0 4677 y FL(exception)f FD(ImportWarning)208 4777 y FN(Base)i(class)g(for)e(w)o(arnings)h (about)f(probable)f(mistak)o(es)j(in)f(module)f(imports.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 4924 y FL(exception)h FD(UnicodeWarning)208 5023 y FN(Base)i(class)g(for)e(w)o(arnings)h (related)f(to)i(Unicode.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 5170 y(The)h(class)h(hierarchy)d(for)h(b)n(uilt-in)h(e)o(xceptions)f (is:)p 241 5346 23 4 v 263 5346 a Fy(hierarchy)-5 b(.txt)p 0 5549 3901 4 v 0 5649 a FI(2.3.)52 b(Built-in)25 b(Exceptions)2935 b(21)p eop end %%Page: 22 34 TeXDict begin 22 33 bop 0 88 a FE(2.4)121 b(Built-in)32 b(Constants)0 321 y FN(A)21 b(small)f(number)f(of)h(constants)f(li)n(v) o(e)h(in)h(the)f(b)n(uilt-in)g(namespace.)j(The)o(y)c(are:)0 468 y FD(False)208 567 y FN(The)g(f)o(alse)i(v)n(alue)f(of)f(the)i FJ(bool)f FN(type.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 714 y FD(True)208 814 y FN(The)g(true)h(v)n(alue)g(of)g(the)g FJ(bool)g FN(type.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 961 y FD(None)208 1060 y FN(The)k(sole)h(v)n(alue)g(of)f FJ(types.NoneType)p FN(.)34 b FJ(None)24 b FN(is)h(frequently)d(used)h (to)i(represent)d(the)i(absence)g(of)f(a)i(v)n(alue,)f(as)g(when)208 1160 y(def)o(ault)19 b(ar)o(guments)f(are)i(not)g(passed)g(to)h(a)f (function.)0 1307 y FD(NotImplemented)208 1407 y FN(Special)i(v)n(alue) g(which)g(can)g(be)h(returned)d(by)j(the)f(\223rich)g(comparison\224)e (special)j(methods)f(\()p FJ(__eq__\(\))p FN(,)f FJ(__lt__\(\))p FN(,)h(and)208 1506 y(friends\),)c(to)j(indicate)e(that)h(the)h (comparison)d(is)j(not)f(implemented)e(with)i(respect)g(to)h(the)f (other)f(type.)0 1653 y FD(Ellipsis)208 1753 y FN(Special)h(v)n(alue)f (used)h(in)h(conjunction)c(with)k(e)o(xtended)d(slicing)i(syntax.)p 0 5549 3901 4 v 0 5649 a FI(22)2787 b(Chapter)24 b(2.)52 b(Built-in)24 b(Objects)p eop end %%Page: 23 35 TeXDict begin 23 34 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3495 427 y FG(THREE)p 0 515 V 2616 978 a FT(Built-in)57 b(T)-25 b(ypes)0 1466 y FN(The)22 b(follo)n(wing)f(sections)h(describe)g(the)g (standard)f(types)h(that)h(are)f(b)n(uilt)h(into)f(the)g(interpreter)-5 b(.)30 b FL(Note:)f FN(Historically)22 b(\(until)g(release)0 1566 y(2.2\),)d(Python')-5 b(s)19 b(b)n(uilt-in)g(types)h(ha)n(v)o(e)f (dif)n(fered)f(from)h(user)n(-de\002ned)g(types)g(because)h(it)g(w)o (as)h(not)f(possible)f(to)h(use)g(the)g(b)n(uilt-in)g(types)0 1665 y(as)h(the)f(basis)h(for)e(object-oriented)f(inheritance.)23 b(This)e(limitation)e(does)h(not)g(e)o(xist)g(an)o(y)g(longer)-5 b(.)0 1812 y(The)20 b(principal)f(b)n(uilt-in)g(types)h(are)g (numerics,)f(sequences,)g(mappings,)g(\002les,)i(classes,)g(instances)f (and)g(e)o(xceptions.)0 1959 y(Some)e(operations)e(are)i(supported)f (by)g(se)n(v)o(eral)h(object)f(types;)i(in)f(particular)m(,)f (practically)g(all)i(objects)f(can)g(be)g(compared,)e(tested)i(for)0 2059 y(truth)i(v)n(alue,)f(and)h(con)m(v)o(erted)e(to)i(a)h(string)f (\(with)g(the)h FJ(repr\(\))e FN(function)g(or)h(the)g(slightly)g(dif)n (ferent)f FJ(str\(\))h FN(function\).)j(The)d(latter)0 2158 y(function)g(is)j(implicitly)f(used)g(when)f(an)h(object)f(is)i (written)f(by)g(the)g FJ(print)f FN(statement.)31 b(\(Information)18 b(on)k(the)g FJ(print)g FN(statement)0 2258 y(and)e(other)f(language)f (statements)j(can)f(be)g(found)e(in)j(the)f FK(Python)f(Refer)m(ence)g (Manual)g FN(and)h(the)g FK(Python)f(T)-5 b(utorial)p FN(.\))0 2585 y FE(3.1)121 b(T)-14 b(r)r(uth)33 b(V)-8 b(alue)34 b(T)-14 b(esting)0 2818 y FN(An)o(y)18 b(object)h(can)g(be)g (tested)h(for)e(truth)h(v)n(alue,)f(for)h(use)g(in)h(an)f FJ(if)g FN(or)g FJ(while)g FN(condition)e(or)i(as)h(operand)e(of)g(the) i(Boolean)e(operations)0 2918 y(belo)n(w)-5 b(.)24 b(The)c(follo)n (wing)e(v)n(alues)i(are)g(considered)f(f)o(alse:)125 3148 y FM(\017)41 b FJ(None)125 3314 y FM(\017)g FJ(False)125 3480 y FM(\017)g FN(zero)19 b(of)h(an)o(y)f(numeric)g(type,)h(for)f(e)o (xample,)g FJ(0)p FN(,)h FJ(0L)p FN(,)g FJ(0.0)p FN(,)g FJ(0j)p FN(.)125 3646 y FM(\017)41 b FN(an)o(y)19 b(empty)g(sequence,)g (for)h(e)o(xample,)e FJ('')p FN(,)i FJ(\(\))p FN(,)g FJ([])p FN(.)125 3812 y FM(\017)41 b FN(an)o(y)19 b(empty)g(mapping,)f (for)i(e)o(xample,)e FJ({})p FN(.)125 3978 y FM(\017)41 b FN(instances)23 b(of)g(user)n(-de\002ned)e(classes,)k(if)e(the)h (class)g(de\002nes)f(a)g FJ(__nonzero__\(\))f FN(or)g FJ(__len__\(\))h FN(method,)f(when)g(that)208 4078 y(method)c(returns)i (the)g(inte)o(ger)f(zero)h(or)f FJ(bool)i FN(v)n(alue)e FJ(False)p FN(.)2044 4047 y FF(1)0 4308 y FN(All)i(other)e(v)n(alues)h (are)g(considered)f(true)g(\227)i(so)g(objects)f(of)g(man)o(y)f(types)h (are)g(al)o(w)o(ays)g(true.)0 4454 y(Operations)k(and)g(b)n(uilt-in)g (functions)f(that)i(ha)n(v)o(e)f(a)h(Boolean)f(result)h(al)o(w)o(ays)g (return)e FJ(0)i FN(or)g FJ(False)f FN(for)g(f)o(alse)h(and)f FJ(1)h FN(or)g FJ(True)f FN(for)0 4554 y(true,)19 b(unless)h(otherwise) f(stated.)25 b(\(Important)17 b(e)o(xception:)23 b(the)d(Boolean)f (operations)f(`)p FJ(or)p FN(')h(and)g(`)p FJ(and)p FN(')g(al)o(w)o (ays)h(return)e(one)h(of)h(their)0 4654 y(operands.\))0 4981 y FE(3.2)121 b(Boolean)35 b(Oper)o(ations)f(\227)f Fx(and)p FE(,)g Fx(or)p FE(,)g Fx(not)0 5214 y FN(These)20 b(are)g(the)g(Boolean)g(operations,)e(ordered)g(by)i(ascending)f (priority:)p 0 5285 1560 4 v 90 5341 a FB(1)120 5364 y FH(Additional)g(information)h(on)d(these)h(special)h(methods)e(may)g (be)h(found)f(in)g(the)h Fw(Python)g(Refer)n(ence)h(Manual)p FH(.)p 0 5549 3901 4 v 3808 5649 a FI(23)p eop end %%Page: 24 36 TeXDict begin 24 35 bop 966 70 a FL(Operation)p 1378 100 4 100 v 98 w(Result)p 2684 100 V 1080 w(Notes)p 916 103 2068 4 v 1011 173 a FK(x)50 b FJ(or)g FK(y)p 1378 203 4 100 v 145 w FN(if)20 b FK(x)h FN(is)g(f)o(alse,)g(then)f FK(y)p FN(,)g(else)h FK(x)p 2684 203 V 525 w FN(\(1\))987 272 y FK(x)50 b FJ(and)f FK(y)p 1378 302 V 120 w FN(if)20 b FK(x)h FN(is)g(f)o(alse,)g(then)f FK(x)p FN(,)g(else)h FK(y)p 2684 302 V 525 w FN(\(1\))p 916 306 2068 4 v 1030 375 a FJ(not)49 b FK(x)p 1378 405 4 100 v 164 w FN(if)20 b FK(x)h FN(is)g(f)o(alse,)g(then)f FJ(True)p FN(,)f(else)i FJ(False)p 2684 405 V 150 w FN(\(2\))0 599 y(Notes:)0 829 y FL(\(1\))40 b FN(These)20 b(only)g(e)n(v)n(aluate)f(their)h (second)f(ar)o(gument)f(if)i(needed)f(for)h(their)g(outcome.)0 995 y FL(\(2\))40 b FN(`)p FJ(not)p FN(')21 b(has)h(a)g(lo)n(wer)f (priority)f(than)h(non-Boolean)e(operators,)i(so)g FJ(not)50 b FK(a)f FJ(==)h FK(b)21 b FN(is)i(interpreted)c(as)k FJ(not)49 b(\()p FK(a)g FJ(==)h FK(b)p FJ(\))p FN(,)21 b(and)208 1095 y FK(a)49 b FJ(==)g(not)h FK(b)20 b FN(is)h(a)g(syntax)e (error)-5 b(.)0 1422 y FE(3.3)121 b(Compar)r(isons)0 1655 y FN(Comparison)20 b(operations)h(are)g(supported)f(by)i(all)g (objects.)30 b(The)o(y)20 b(all)j(ha)n(v)o(e)e(the)h(same)g(priority)e (\(which)h(is)i(higher)e(than)g(that)h(of)g(the)0 1755 y(Boolean)17 b(operations\).)22 b(Comparisons)17 b(can)h(be)f(chained)g (arbitrarily;)g(for)g(e)o(xample,)g FK(x)50 b FJ(<)g FK(y)f FJ(<=)h FK(z)18 b FN(is)h(equi)n(v)n(alent)d(to)i FK(x)50 b FJ(<)g FK(y)g FJ(and)0 1854 y FK(y)g FJ(<=)f FK(z)p FN(,)27 b(e)o(xcept)d(that)i FK(y)f FN(is)i(e)n(v)n(aluated)c (only)i(once)f(\(b)n(ut)h(in)h(both)e(cases)i FK(z)g FN(is)g(not)f(e)n(v)n(aluated)f(at)i(all)g(when)e FK(x)50 b FJ(<)g FK(y)26 b FN(is)g(found)d(to)j(be)0 1954 y(f)o(alse\).)0 2101 y(This)20 b(table)h(summarizes)e(the)h(comparison)e(operations:) 1192 2327 y FL(Operation)p 1604 2357 V 98 w(Meaning)p 2459 2357 V 540 w(Notes)p 1142 2360 1617 4 v 1349 2430 a FJ(<)p 1604 2460 4 100 v 257 w FN(strictly)i(less)h(than)p 2459 2460 V 1324 2530 a FJ(<=)p 1604 2559 V 232 w FN(less)g(than)f(or)g (equal)p 2459 2559 V 1349 2629 a FJ(>)p 1604 2659 V 257 w FN(strictly)g(greater)f(than)p 2459 2659 V 1324 2729 a FJ(>=)p 1604 2759 V 232 w FN(greater)g(than)h(or)g(equal)p 2459 2759 V 1324 2828 a FJ(==)p 1604 2858 V 232 w FN(equal)p 2459 2858 V 1324 2928 a FJ(!=)p 1604 2958 V 232 w FN(not)g(equal)p 2459 2958 V 597 w(\(1\))1324 3028 y FJ(<>)p 1604 3058 V 232 w FN(not)g(equal)p 2459 3058 V 597 w(\(1\))1324 3127 y FJ(is)p 1604 3157 V 232 w FN(object)f(identity)p 2459 3157 V 1224 3227 a FJ(is)50 b(not)p 1604 3257 V 132 w FN(ne)o(gated)18 b(object)i(identity)p 2459 3257 V 0 3451 a(Notes:)0 3681 y FL(\(1\))40 b FJ(<>)21 b FN(and)e FJ(!=)i FN(are)f(alternate)f(spellings)h(for)g(the)g(same)h(operator)-5 b(.)23 b FJ(!=)d FN(is)i(the)e(preferred)e(spelling;)i FJ(<>)g FN(is)h(obsolescent.)0 3911 y(Objects)e(of)f(dif)n(ferent)e (types,)j(e)o(xcept)e(dif)n(ferent)g(numeric)g(types)h(and)g(dif)n (ferent)f(string)h(types,)g(ne)n(v)o(er)f(compare)g(equal;)i(such)f (objects)0 4010 y(are)j(ordered)e(consistently)i(b)n(ut)g(arbitrarily)f (\(so)h(that)g(sorting)f(a)i(heterogeneous)c(array)i(yields)h(a)h (consistent)f(result\).)27 b(Furthermore,)0 4110 y(some)c(types)f (\(for)g(e)o(xample,)g(\002le)h(objects\))f(support)g(only)g(a)h(de)o (generate)e(notion)g(of)i(comparison)d(where)i(an)o(y)g(tw)o(o)h (objects)g(of)f(that)0 4210 y(type)c(are)g(unequal.)23 b(Again,)18 b(such)g(objects)g(are)g(ordered)f(arbitrarily)g(b)n(ut)h (consistently)-5 b(.)23 b(The)18 b FJ(<)p FN(,)h FJ(<=)p FN(,)g FJ(>)g FN(and)f FJ(>=)g FN(operators)f(will)i(raise)0 4309 y(a)i FJ(TypeError)e FN(e)o(xception)f(when)i(an)o(y)f(operand)f (is)j(a)g(comple)o(x)d(number)-5 b(.)0 4456 y(Instances)24 b(of)g(a)h(class)g(normally)e(compare)f(as)j(non-equal)d(unless)j(the)f (class)50 b(de\002nes)24 b(the)h FJ(__cmp__\(\))e FN(method.)36 b(Refer)24 b(to)h(the)0 4556 y FK(Python)19 b(Refer)m(ence)h(Manual)f FN(for)g(information)f(on)i(the)g(use)g(of)g(this)h(method)e(to)h(ef)n (fect)g(object)f(comparisons.)0 4703 y FL(Implementation)f(note:)24 b FN(Objects)18 b(of)g(dif)n(ferent)e(types)i(e)o(xcept)f(numbers)g (are)h(ordered)e(by)i(their)g(type)g(names;)g(objects)g(of)g(the)g (same)0 4802 y(types)i(that)g(don')o(t)f(support)g(proper)f(comparison) g(are)i(ordered)f(by)g(their)h(address.)0 4949 y(T)-7 b(w)o(o)29 b(more)f(operations)f(with)h(the)h(same)g(syntactic)f (priority)-5 b(,)29 b(`)p FJ(in)p FN(')f(and)g(`)p FJ(not)49 b(in)p FN(',)30 b(are)f(supported)d(only)i(by)g(sequence)g(types)0 5049 y(\(belo)n(w\).)p 0 5549 3901 4 v 0 5649 a FI(24)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 25 37 TeXDict begin 25 36 bop 0 86 a FE(3.4)121 b(Numer)r(ic)33 b(T)-14 b(ypes)33 b(\227)g Fx(int)p FE(,)g Fx(float)p FE(,)f Fx(long)p FE(,)g Fx(complex)0 319 y FN(There)27 b(are)g(four)f(distinct)h(numeric)f(types:)40 b FK(plain)26 b(inte)m(g)o(er)o(s)p FN(,)j FK(long)e(inte)m(g)o(er)o(s)p FN(,)i FK(\003oating)c(point)i(number)o(s)p FN(,)h(and)f FK(comple)n(x)g(number)o(s)p FN(.)0 419 y(In)22 b(addition,)f(Booleans) h(are)g(a)h(subtype)e(of)h(plain)g(inte)o(gers.)30 b(Plain)23 b(inte)o(gers)e(\(also)i(just)f(called)h FK(inte)m(g)o(er)o(s)p FN(\))f(are)g(implemented)e(using)0 518 y FJ(long)h FN(in)g(C,)g(which) g(gi)n(v)o(es)f(them)h(at)g(least)h(32)f(bits)g(of)g(precision)f(\()p FJ(sys.maxint)f FN(is)j(al)o(w)o(ays)f(set)h(to)f(the)g(maximum)e (plain)i(inte)o(ger)0 618 y(v)n(alue)e(for)h(the)g(current)f(platform,) f(the)j(minimum)d(v)n(alue)i(is)h FJ(-sys.maxint)47 b(-)j(1)p FN(\).)25 b(Long)19 b(inte)o(gers)g(ha)n(v)o(e)h(unlimited)f (precision.)0 718 y(Floating)h(point)g(numbers)f(are)h(implemented)f (using)h FJ(double)g FN(in)g(C.)h(All)h(bets)e(on)g(their)h(precision)e (are)i(of)n(f)e(unless)i(you)f(happen)e(to)0 817 y(kno)n(w)h(the)h (machine)f(you)h(are)g(w)o(orking)e(with.)0 964 y(Comple)o(x)i(numbers) g(ha)n(v)o(e)h(a)h(real)g(and)f(imaginary)f(part,)h(which)g(are)h(each) f(implemented)f(using)h FJ(double)g FN(in)h(C.)g(T)-7 b(o)22 b(e)o(xtract)e(these)0 1064 y(parts)g(from)f(a)i(comple)o(x)d (number)h FK(z)p FN(,)i(use)f FK(z)p FJ(.real)g FN(and)g FK(z)p FJ(.imag)p FN(.)0 1211 y(Numbers)f(are)h(created)f(by)h(numeric) e(literals)j(or)f(as)g(the)g(result)g(of)g(b)n(uilt-in)f(functions)g (and)g(operators.)24 b(Unadorned)17 b(inte)o(ger)i(literals)0 1310 y(\(including)h(he)o(x)g(and)h(octal)h(numbers\))e(yield)h(plain)g (inte)o(gers)g(unless)h(the)g(v)n(alue)f(the)o(y)f(denote)h(is)i(too)e (lar)o(ge)g(to)g(be)h(represented)e(as)i(a)0 1410 y(plain)c(inte)o(ger) m(,)f(in)i(which)e(case)i(the)o(y)f(yield)g(a)h(long)e(inte)o(ger)-5 b(.)24 b(Inte)o(ger)17 b(literals)i(with)f(an)h(`)p FJ(L)p FN(')f(or)g(`)p FJ(l)p FN(')g(suf)n(\002x)g(yield)g(long)f(inte)o(gers) h(\(`)p FJ(L)p FN(')g(is)0 1510 y(preferred)g(because)j(`)p FJ(1l)p FN(')f(looks)g(too)g(much)g(lik)o(e)h(ele)n(v)o(en!\).)k (Numeric)20 b(literals)h(containing)e(a)i(decimal)f(point)g(or)h(an)f (e)o(xponent)f(sign)0 1609 y(yield)g(\003oating)g(point)g(numbers.)24 b(Appending)17 b(`)p FJ(j)p FN(')j(or)f(`)p FJ(J)p FN(')g(to)h(a)h (numeric)d(literal)i(yields)g(a)g(comple)o(x)e(number)g(with)i(a)g (zero)f(real)h(part.)0 1709 y(A)h(comple)o(x)d(numeric)h(literal)h(is)i (the)e(sum)g(of)g(a)g(real)h(and)e(an)h(imaginary)f(part.)0 1856 y(Python)k(fully)h(supports)g(mix)o(ed)f(arithmetic:)34 b(when)24 b(a)h(binary)e(arithmetic)h(operator)f(has)i(operands)d(of)j (dif)n(ferent)e(numeric)g(types,)0 1955 y(the)d(operand)e(with)i(the)g (\223narro)n(wer\224)e(type)i(is)h(widened)e(to)h(that)g(of)g(the)g (other)m(,)f(where)g(plain)h(inte)o(ger)f(is)i(narro)n(wer)d(than)h (long)h(inte)o(ger)0 2055 y(is)i(narro)n(wer)d(than)i(\003oating)g (point)f(is)i(narro)n(wer)d(than)i(comple)o(x.)26 b(Comparisons)20 b(between)g(numbers)g(of)h(mix)o(ed)f(type)h(use)g(the)g(same)0 2155 y(rule.)151 2124 y FF(2)209 2155 y FN(The)e(constructors)f FJ(int\(\))p FN(,)i FJ(long\(\))p FN(,)f FJ(float\(\))p FN(,)g(and)g FJ(complex\(\))g FN(can)g(be)h(used)g(to)f(produce)f (numbers)h(of)g(a)h(speci\002c)0 2254 y(type.)0 2401 y(All)j(numeric)e(types)i(\(e)o(xcept)e(comple)o(x\))f(support)h(the)i (follo)n(wing)e(operations,)g(sorted)h(by)g(ascending)f(priority)g (\(operations)g(in)i(the)0 2501 y(same)d(box)g(ha)n(v)o(e)f(the)h(same) h(priority;)e(all)h(numeric)f(operations)g(ha)n(v)o(e)h(a)g(higher)f (priority)g(than)h(comparison)e(operations\):)329 2705 y FL(Operation)p 883 2735 4 100 v 239 w(Result)p 3463 2735 V 2354 w(Notes)p 137 2739 3626 4 v 399 2808 a FK(x)50 b FJ(+)g FK(y)p 883 2838 4 100 v 311 w FN(sum)20 b(of)g FK(x)h FN(and)f FK(y)p 3463 2838 V 399 2908 a(x)50 b FJ(-)g FK(y)p 883 2938 V 311 w FN(dif)n(ference)18 b(of)i FK(x)h FN(and)f FK(y)p 3463 2938 V 137 2941 3626 4 v 399 3011 a(x)486 3026 y FJ(*)586 3011 y FK(y)p 883 3041 4 100 v 311 w FN(product)f(of)g FK(x)i FN(and)f FK(y)p 3463 3041 V 399 3111 a(x)50 b FJ(/)g FK(y)p 883 3141 V 311 w FN(quotient)19 b(of)h FK(x)h FN(and)e FK(y)p 3463 3141 V 2013 w FN(\(1\))374 3210 y FK(x)50 b FJ(//)g FK(y)p 883 3240 V 286 w FN(\(\003oored\))18 b(quotient)h(of)h FK(x)h FN(and)f FK(y)p 3463 3240 V 1701 w FN(\(5\))399 3310 y FK(x)50 b FJ(\045)g FK(y)p 883 3340 V 311 w FN(remainder)18 b(of)i FK(x)50 b FJ(/)g FK(y)p 3463 3340 V 1960 w FN(\(4\))p 137 3343 3626 4 v 467 3413 a FJ(-)p FK(x)p 883 3443 4 100 v 380 w(x)21 b FN(ne)o(gated)p 3463 3443 V 467 3512 a FJ(+)p FK(x)p 883 3542 V 380 w(x)g FN(unchanged)p 3463 3542 V 137 3546 3626 4 v 368 3615 a FJ(abs\()p FK(x)p FJ(\))p 883 3645 4 100 v 279 w FN(absolute)f(v)n(alue)f(or)h(magnitude) e(of)i FK(x)p 3463 3645 V 368 3715 a FJ(int\()p FK(x)p FJ(\))p 883 3745 V 279 w FK(x)h FN(con)m(v)o(erted)d(to)i(inte)o(ger)p 3463 3745 V 1913 w(\(2\))343 3815 y FJ(long\()p FK(x)p FJ(\))p 883 3845 V 254 w FK(x)h FN(con)m(v)o(erted)d(to)i(long)f(inte)o (ger)p 3463 3845 V 1745 w(\(2\))318 3914 y FJ(float\()p FK(x)p FJ(\))p 883 3944 V 229 w FK(x)i FN(con)m(v)o(erted)d(to)i (\003oating)f(point)p 3463 3944 V 187 4014 a FJ(complex\()p FK(r)m(e)p FJ(,)p FK(im)p FJ(\))p 883 4044 V 98 w FN(a)i(comple)o(x)d (number)h(with)h(real)g(part)g FK(r)m(e)p FN(,)h(imaginary)d(part)i FK(im)p FN(.)25 b FK(im)c FN(def)o(aults)f(to)g(zero.)p 3463 4044 V 194 4114 a FK(c)p FJ(.conjugate\(\))p 883 4143 V 103 w FN(conjugate)e(of)i(the)g(comple)o(x)f(number)f FK(c)p 3463 4143 V 225 4213 a FJ(divmod\()p FK(x)p FJ(,)48 b FK(y)p FJ(\))p 883 4243 V 137 w FN(the)20 b(pair)g FJ(\()p FK(x)50 b FJ(//)f FK(y)p FJ(,)h FK(x)g FJ(\045)f FK(y)p FJ(\))p 3463 4243 V 1615 w FN(\(3\)\(4\))300 4313 y FJ(pow\()p FK(x)p FJ(,)g FK(y)p FJ(\))p 883 4343 V 211 w FK(x)21 b FN(to)f(the)h(po)n(wer)e FK(y)p 3463 4343 V 374 4412 a(x)461 4427 y FJ(**)611 4412 y FK(y)p 883 4442 V 286 w(x)i FN(to)f(the)h(po)n(wer)e FK(y)p 3463 4442 V 0 4615 a FN(Notes:)0 4811 y FL(\(1\))40 b FN(F)o(or)23 b(\(plain)f(or)h(long\))e(inte)o(ger)h(di)n(vision,)g(the) h(result)g(is)h(an)f(inte)o(ger)-5 b(.)32 b(The)23 b(result)g(is)g(al)o (w)o(ays)h(rounded)c(to)n(w)o(ards)j(minus)f(in\002nity:)208 4911 y(1/2)c(is)h(0,)g(\(-1\)/2)e(is)i(-1,)g(1/\(-2\))e(is)i(-1,)f(and) g(\(-1\)/\(-2\))e(is)k(0.)k(Note)19 b(that)f(the)h(result)f(is)i(a)f (long)e(inte)o(ger)h(if)g(either)h(operand)d(is)j(a)g(long)208 5010 y(inte)o(ger)m(,)f(re)o(gardless)h(of)h(the)g(numeric)f(v)n(alue.) 0 5168 y FL(\(2\))40 b FN(Con)m(v)o(ersion)21 b(from)g(\003oating)h (point)g(to)h(\(long)e(or)h(plain\))g(inte)o(ger)g(may)g(round)f(or)h (truncate)f(as)j(in)e(C;)i(see)f(functions)e FJ(floor\(\))208 5267 y FN(and)e FJ(ceil\(\))h FN(in)g(the)g FJ(math)g FN(module)f(for)h(well-de\002ned)f(con)m(v)o(ersions.)p 0 5321 1560 4 v 90 5377 a FB(2)120 5400 y FH(As)d(a)h(consequence,)j (the)d(list)h Fz([1,)40 b(2])16 b FH(is)h(considered)i(equal)g(to)e Fz([1.0,)39 b(2.0])p FH(,)16 b(and)h(similarly)i(for)e(tuples.)p 0 5549 3901 4 v 0 5649 a FI(3.4.)52 b(Numer)q(ic)23 b(T)-10 b(ypes)23 b(\227)g FJ(int)p FI(,)f FJ(float)p FI(,)h FJ(long)p FI(,)f FJ(complex)1853 b FI(25)p eop end %%Page: 26 38 TeXDict begin 26 37 bop 0 83 a FL(\(3\))40 b FN(See)21 b(section)f(2.1,)f(\223Built-in)h(Functions,)-6 b(\224)19 b(for)h(a)g(full)g(description.)0 249 y FL(\(4\))40 b FN(Comple)o(x)19 b(\003oor)h(di)n(vision)f(operator)m(,)f(modulo)g (operator)m(,)g(and)i FJ(divmod\(\))p FN(.)208 382 y FL(Depr)o(ecated)f(since)i(r)o(elease)e(2.3.)24 b FN(Instead)c(con)m(v) o(ert)e(to)i(\003oat)h(using)e FJ(abs\(\))h FN(if)h(appropriate.)0 548 y FL(\(5\))40 b FN(Also)16 b(referred)e(to)h(as)i(inte)o(ger)d(di)n (vision.)22 b(The)15 b(resultant)g(v)n(alue)g(is)h(a)g(whole)f(inte)o (ger)m(,)g(though)e(the)j(result')-5 b(s)16 b(type)f(is)h(not)f (necessarily)208 648 y(int.)0 932 y Fv(3.4.1)100 b(Bit-str)q(ing)29 b(Oper)o(ations)g(on)g(Integer)g(T)-12 b(ypes)0 1135 y FN(Plain)29 b(and)f(long)h(inte)o(ger)e(types)i(support)f(additional) f(operations)g(that)i(mak)o(e)g(sense)g(only)f(for)h(bit-strings.)50 b(Ne)o(gati)n(v)o(e)27 b(numbers)0 1235 y(are)e(treated)g(as)h(their)f (2')-5 b(s)26 b(complement)d(v)n(alue)i(\(for)f(long)g(inte)o(gers,)i (this)f(assumes)h(a)g(suf)n(\002ciently)e(lar)o(ge)g(number)g(of)h (bits)h(that)f(no)0 1335 y(o)o(v)o(er\003o)n(w)18 b(occurs)i(during)e (the)j(operation\).)0 1481 y(The)g(priorities)f(of)h(the)g(binary)f (bit-wise)h(operations)f(are)h(all)g(lo)n(wer)g(than)g(the)g(numeric)e (operations)h(and)h(higher)e(than)i(the)g(compar)n(-)0 1581 y(isons;)g(the)f(unary)f(operation)f(`)p FJ(\230)p FN(')i(has)g(the)g(same)h(priority)e(as)h(the)h(other)e(unary)g (numeric)g(operations)f(\(`)p FJ(+)p FN(')i(and)f(`)p FJ(-)p FN('\).)0 1728 y(This)d(table)g(lists)h(the)f(bit-string)f (operations)f(sorted)i(in)g(ascending)e(priority)h(\(operations)f(in)i (the)g(same)g(box)f(ha)n(v)o(e)g(the)h(same)g(priority\):)1049 1954 y FL(Operation)p 1461 1984 4 100 v 98 w(Result)p 2565 1984 V 896 w(Notes)p 999 1987 1903 4 v 1119 2057 a FK(x)50 b FJ(|)g FK(y)p 1461 2087 4 100 v 170 w FN(bitwise)20 b FK(or)h FN(of)f FK(x)h FN(and)e FK(y)p 2565 2087 V 1119 2157 a(x)50 b FJ(\210)g FK(y)p 1461 2187 V 170 w FN(bitwise)20 b FK(e)n(xclusive)h(or)f FN(of)g FK(x)h FN(and)f FK(y)p 2565 2187 V 1119 2256 a(x)50 b FJ(&)g FK(y)p 1461 2286 V 170 w FN(bitwise)20 b FK(and)g FN(of)g FK(x)g FN(and)g FK(y)p 2565 2286 V 1092 2356 a(x)50 b FJ(<<)f FK(n)p 1461 2386 V 143 w(x)21 b FN(shifted)e(left)i(by)f FK(n)g FN(bits)p 2565 2386 V 381 w(\(1\),)f(\(2\))1092 2456 y FK(x)50 b FJ(>>)f FK(n)p 1461 2486 V 143 w(x)21 b FN(shifted)e(right)h(by)g FK(n)g FN(bits)p 2565 2486 V 335 w(\(1\),)f(\(3\))p 999 2489 1903 4 v 1187 2559 a FJ(\230)p FK(x)p 1461 2589 4 100 v 239 w FN(the)h(bits)h(of)f FK(x)g FN(in)m(v)o(erted)p 2565 2589 V 0 2783 a(Notes:)0 2996 y FL(\(1\))40 b FN(Ne)o(gati)n(v)o(e)19 b(shift)h(counts)g(are)g (ille)o(gal)f(and)h(cause)g(a)h FJ(ValueError)e FN(to)h(be)g(raised.)0 3162 y FL(\(2\))40 b FN(A)21 b(left)f(shift)h(by)f FK(n)g FN(bits)h(is)g(equi)n(v)n(alent)d(to)j(multiplication)d(by)i FJ(pow\(2,)49 b FK(n)p FJ(\))20 b FN(without)f(o)o(v)o(er\003o)n(w)g (check.)0 3328 y FL(\(3\))40 b FN(A)21 b(right)f(shift)g(by)g FK(n)g FN(bits)h(is)g(equi)n(v)n(alent)d(to)j(di)n(vision)e(by)h FJ(pow\(2,)48 b FK(n)p FJ(\))20 b FN(without)g(o)o(v)o(er\003o)n(w)e (check.)0 3655 y FE(3.5)121 b(Iter)o(ator)34 b(T)-14 b(ypes)0 3888 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 4035 y(Python)26 b(supports)h(a)h(concept)e(of)i(iteration)f(o)o(v)o (er)f(containers.)46 b(This)28 b(is)g(implemented)e(using)h(tw)o(o)h (distinct)g(methods;)i(these)e(are)0 4135 y(used)20 b(to)h(allo)n(w)f (user)n(-de\002ned)f(classes)i(to)g(support)e(iteration.)24 b(Sequences,)c(described)f(belo)n(w)g(in)i(more)f(detail,)g(al)o(w)o (ays)h(support)e(the)0 4234 y(iteration)g(methods.)0 4381 y(One)h(method)f(needs)h(to)g(be)g(de\002ned)f(for)h(container)f (objects)h(to)g(pro)o(vide)e(iteration)h(support:)0 4528 y FD(__iter__)p FJ(\(\))208 4628 y FN(Return)i(an)g(iterator)g(object.) 29 b(The)21 b(object)h(is)g(required)e(to)i(support)e(the)i(iterator)f (protocol)f(described)g(belo)n(w)-5 b(.)28 b(If)22 b(a)g(container)208 4727 y(supports)15 b(dif)n(ferent)g(types)h(of)h(iteration,)f (additional)f(methods)h(can)g(be)h(pro)o(vided)d(to)i(speci\002cally)h (request)f(iterators)g(for)g(those)208 4827 y(iteration)i(types.)25 b(\(An)19 b(e)o(xample)g(of)g(an)h(object)f(supporting)e(multiple)i (forms)g(of)g(iteration)g(w)o(ould)g(be)h(a)g(tree)f(structure)g(which) 208 4927 y(supports)g(both)g(breadth-\002rst)g(and)h(depth-\002rst)f (tra)n(v)o(ersal.\))25 b(This)20 b(method)f(corresponds)f(to)j(the)f FJ(tp_iter)g FN(slot)h(of)f(the)g(type)208 5026 y(structure)f(for)g (Python)g(objects)h(in)h(the)f(Python/C)f(API.)0 5173 y(The)24 b(iterator)g(objects)g(themselv)o(es)f(are)h(required)f(to)h (support)f(the)h(follo)n(wing)f(tw)o(o)h(methods,)g(which)g(together)f (form)g(the)i FK(iter)o(ator)0 5273 y(pr)l(otocol)p FN(:)p 0 5549 3901 4 v 0 5649 a FI(26)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 27 39 TeXDict begin 27 38 bop 0 83 a FD(__iter__)p FJ(\(\))208 183 y FN(Return)21 b(the)h(iterator)f(object)g(itself.)31 b(This)22 b(is)h(required)d(to)i(allo)n(w)g(both)f(containers)f(and)i (iterators)f(to)h(be)g(used)g(with)g(the)g FJ(for)208 282 y FN(and)h FJ(in)i FN(statements.)36 b(This)25 b(method)e (corresponds)e(to)k(the)f FJ(tp_iter)f FN(slot)i(of)f(the)g(type)g (structure)f(for)g(Python)g(objects)h(in)208 382 y(the)c(Python/C)f (API.)0 529 y FD(next)p FJ(\(\))208 628 y FN(Return)k(the)h(ne)o(xt)g (item)g(from)f(the)h(container)-5 b(.)35 b(If)24 b(there)g(are)g(no)f (further)g(items,)i(raise)f(the)h FJ(StopIteration)d FN(e)o(xception.)208 728 y(This)j(method)e(corresponds)g(to)i(the)g FJ(tp_iternext)f FN(slot)i(of)e(the)h(type)g(structure)f(for)g(Python)g (objects)h(in)g(the)g(Python/C)208 828 y(API.)0 975 y(Python)31 b(de\002nes)h(se)n(v)o(eral)f(iterator)h(objects)g(to)g(support)f (iteration)g(o)o(v)o(er)g(general)g(and)h(speci\002c)g(sequence)f (types,)k(dictionaries,)0 1074 y(and)25 b(other)g(more)h(specialized)f (forms.)41 b(The)26 b(speci\002c)g(types)g(are)g(not)f(important)g(be)o (yond)e(their)j(implementation)e(of)h(the)h(iterator)0 1174 y(protocol.)0 1321 y(The)c(intention)f(of)h(the)g(protocol)e(is)j (that)g(once)e(an)h(iterator')-5 b(s)22 b FJ(next\(\))g FN(method)f(raises)h FJ(StopIteration)p FN(,)f(it)i(will)g(continue)d (to)0 1420 y(do)k(so)g(on)g(subsequent)e(calls.)38 b(Implementations)21 b(that)j(do)g(not)g(obe)o(y)f(this)h(property)e(are)i(deemed)f(brok)o (en.)35 b(\(This)24 b(constraint)f(w)o(as)0 1520 y(added)c(in)h(Python) f(2.3;)h(in)g(Python)f(2.2,)h(v)n(arious)f(iterators)h(are)g(brok)o(en) e(according)g(to)j(this)f(rule.\))0 1667 y(Python')-5 b(s)16 b(generators)e(pro)o(vide)h(a)h(con)m(v)o(enient)e(w)o(ay)i(to)h (implement)e(the)h(iterator)g(protocol.)22 b(If)16 b(a)h(container)e (object')-5 b(s)16 b FJ(__iter__\(\))0 1766 y FN(method)22 b(is)j(implemented)d(as)i(a)g(generator)m(,)e(it)j(will)f (automatically)f(return)f(an)i(iterator)f(object)g(\(technically)-5 b(,)23 b(a)h(generator)d(object\))0 1866 y(supplying)d(the)i FJ(__iter__\(\))f FN(and)h FJ(next\(\))g FN(methods.)0 2193 y FE(3.6)121 b(Sequence)34 b(T)-14 b(ypes)32 b(\227)f Fx(str)p FE(,)g Fx(unicode)p FE(,)g Fx(list)p FE(,)g Fx(tuple)p FE(,)g Fx(buffer)p FE(,)g Fx(xrange)0 2576 y FN(There)19 b(are)h(six)h(sequence)e(types:)25 b(strings,)20 b(Unicode)f(strings,)h(lists,)h(tuples,)f(b)n(uf)n(fers,)f(and)h (xrange)e(objects.)0 2723 y(String)h(literals)i(are)f(written)f(in)h (single)g(or)g(double)e(quotes:)24 b FJ('xyzzy')p FN(,)19 b FJ("frobozz")p FN(.)24 b(See)c(chapter)f(2)h(of)g(the)g FK(Python)e(Refer)m(ence)0 2822 y(Manual)27 b FN(for)g(more)g(about)g (string)h(literals.)49 b(Unicode)26 b(strings)i(are)g(much)f(lik)o(e)i (strings,)g(b)n(ut)f(are)g(speci\002ed)g(in)g(the)g(syntax)f(using)0 2922 y(a)k(preceding)e(`)p FJ(u)p FN(')i(character:)45 b FJ(u'abc')p FN(,)33 b FJ(u"def")p FN(.)57 b(Lists)32 b(are)f(constructed)e(with)i(square)f(brack)o(ets,)j(separating)d (items)h(with)0 3021 y(commas:)e FJ([a,)49 b(b,)h(c])p FN(.)31 b(T)l(uples)23 b(are)f(constructed)f(by)h(the)g(comma)g (operator)e(\(not)i(within)g(square)g(brack)o(ets\),)g(with)g(or)g (without)0 3121 y(enclosing)i(parentheses,)h(b)n(ut)g(an)h(empty)e (tuple)h(must)g(ha)n(v)o(e)g(the)g(enclosing)f(parentheses,)h(such)g (as)h FJ(a,)50 b(b,)f(c)26 b FN(or)f FJ(\(\))p FN(.)40 b(A)26 b(single)0 3221 y(item)20 b(tuple)g(must)g(ha)n(v)o(e)g(a)h (trailing)e(comma,)g(such)h(as)h FJ(\(d,\))p FN(.)0 3368 y(Buf)n(fer)38 b(objects)g(are)g(not)g(directly)f(supported)g(by)h (Python)f(syntax,)42 b(b)n(ut)c(can)g(be)g(created)g(by)g(calling)g (the)g(b)n(uiltin)g(function)0 3467 y FJ(buffer\(\))p FN(.)24 b(The)o(y)19 b(don')o(t)g(support)f(concatenation)g(or)i (repetition.)0 3614 y(Xrange)j(objects)g(are)h(similar)g(to)f(b)n(uf)n (fers)g(in)h(that)g(there)f(is)i(no)e(speci\002c)h(syntax)f(to)h (create)f(them,)h(b)n(ut)g(the)o(y)f(are)g(created)g(using)h(the)0 3714 y FJ(xrange\(\))k FN(function.)49 b(The)o(y)28 b(don')o(t)f (support)g(slicing,)k(concatenation)c(or)h(repetition,)i(and)e(using)g FJ(in)p FN(,)j FJ(not)49 b(in)p FN(,)31 b FJ(min\(\))e FN(or)0 3813 y FJ(max\(\))20 b FN(on)g(them)f(is)j(inef)n(\002cient.)0 3960 y(Most)29 b(sequence)g(types)g(support)e(the)j(follo)n(wing)d (operations.)51 b(The)29 b(`)p FJ(in)p FN(')f(and)h(`)p FJ(not)49 b(in)p FN(')29 b(operations)f(ha)n(v)o(e)g(the)h(same)h (priori-)0 4060 y(ties)d(as)f(the)g(comparison)d(operations.)40 b(The)26 b(`)p FJ(+)p FN(')f(and)g(`)1648 4075 y FJ(*)1698 4060 y FN(')g(operations)g(ha)n(v)o(e)g(the)g(same)h(priority)f(as)h (the)g(corresponding)c(numeric)0 4159 y(operations.)369 4129 y FF(3)0 4306 y FN(This)16 b(table)g(lists)i(the)e(sequence)f (operations)f(sorted)i(in)g(ascending)e(priority)h(\(operations)f(in)i (the)g(same)h(box)e(ha)n(v)o(e)g(the)h(same)h(priority\).)0 4406 y(In)j(the)g(table,)g FK(s)h FN(and)f FK(t)i FN(are)e(sequences)f (of)h(the)h(same)f(type;)g FK(n)p FN(,)g FK(i)h FN(and)e FK(j)i FN(are)f(inte)o(gers:)p 0 4477 1560 4 v 90 4533 a FB(3)120 4556 y FH(The)o(y)d(must)f(ha)o(v)o(e)i(since)g(the)g (parser)g(can')o(t)g(tell)g(the)g(type)g(of)f(the)h(operands.)p 0 5549 3901 4 v 0 5649 a FI(3.6.)52 b(Sequence)24 b(T)-10 b(ypes)22 b(\227)h FJ(str)p FI(,)g FJ(unicode)p FI(,)f FJ(list)p FI(,)g FJ(tuple)p FI(,)g FJ(buffer)p FI(,)g FJ(xrange)1100 b FI(27)p eop end %%Page: 28 40 TeXDict begin 28 39 bop 780 70 a FL(Operation)p 1269 100 4 100 v 174 w(Result)p 2910 100 V 1434 w(Notes)p 654 103 2593 4 v 828 173 a FK(x)50 b FJ(in)f FK(s)p 1269 203 4 100 v 224 w FJ(True)20 b FN(if)h(an)f(item)g(of)g FK(s)h FN(is)g(equal)f(to)g FK(x)p FN(,)h(else)g FJ(False)p 2910 203 V 168 w FN(\(1\))728 272 y FK(x)50 b FJ(not)f(in)h FK(s)p 1269 302 V 124 w FJ(False)20 b FN(if)h(an)f(item)g(of)g FK(s)h FN(is)g(equal)f(to)g FK(x)p FN(,)h(else)f FJ(True)p 2910 302 V 169 w FN(\(1\))p 654 306 2593 4 v 859 375 a FK(s)50 b FJ(+)g FK(t)p 1269 405 4 100 v 256 w FN(the)20 b(concatenation)e(of)i FK(s)h FN(and)f FK(t)p 2910 405 V 800 w FN(\(6\))704 475 y FK(s)786 490 y FJ(*)885 475 y FK(n)p FN(,)49 b FK(n)1089 490 y FJ(*)1188 475 y FK(s)p 1269 505 V 100 w(n)20 b FN(shallo)n(w)g(copies)g(of)g FK(s)h FN(concatenated)p 2910 505 V 560 w(\(2\))p 654 508 2593 4 v 885 578 a FK(s)p FJ([)p FK(i)p FJ(])p 1269 608 4 100 v 280 w FK(i)p FN(')o(th)f(item)g(of)g FK(s)p FN(,)h(origin)e(0)p 2910 608 V 983 w(\(3\))848 677 y FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])p 1269 707 V 244 w FN(slice)i(of)f FK(s)h FN(from)e FK(i)i FN(to)f FK(j)p 2910 707 V 991 w FN(\(3\),)g(\(4\))804 777 y FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(:)p FK(k)q FJ(])p 1269 807 V 200 w FN(slice)h(of)f FK(s)h FN(from)e FK(i)i FN(to)f FK(j)h FN(with)g(step)f FK(k)p 2910 807 V 610 w FN(\(3\),)g(\(5\))p 654 810 2593 4 v 821 880 a FJ(len\()p FK(s)p FJ(\))p 1269 910 4 100 v 217 w FN(length)g(of)f FK(s)p 2910 910 V 821 980 a FJ(min\()p FK(s)p FJ(\))p 1269 1010 V 217 w FN(smallest)i(item)f(of)g FK(s)p 2910 1010 V 821 1079 a FJ(max\()p FK(s)p FJ(\))p 1269 1109 V 217 w FN(lar)o(gest)g(item)g (of)g FK(s)p 2910 1109 V 0 1296 a FN(Notes:)0 1519 y FL(\(1\))40 b FN(When)26 b FK(s)g FN(is)h(a)f(string)f(or)g(Unicode)g (string)g(object)g(the)h FJ(in)g FN(and)f FJ(not)49 b(in)26 b FN(operations)e(act)i(lik)o(e)g(a)g(substring)e(test.)42 b(In)26 b(Python)208 1618 y(v)o(ersions)19 b(before)g(2.3,)g FK(x)i FN(had)e(to)i(be)f(a)g(string)g(of)g(length)g(1.)25 b(In)19 b(Python)h(2.3)f(and)h(be)o(yond,)d FK(x)k FN(may)f(be)g(a)h (string)f(of)f(an)o(y)h(length.)0 1782 y FL(\(2\))40 b FN(V)-9 b(alues)20 b(of)f FK(n)h FN(less)h(than)e FJ(0)h FN(are)g(treated)f(as)i FJ(0)f FN(\(which)e(yields)i(an)g(empty)f (sequence)f(of)i(the)f(same)h(type)f(as)i FK(s)p FN(\).)k(Note)20 b(also)g(that)g(the)208 1881 y(copies)f(are)i(shallo)n(w;)f(nested)f (structures)h(are)g(not)g(copied.)k(This)c(often)g(haunts)f(ne)n(w)h (Python)f(programmers;)f(consider:)444 2104 y FA(>>>)44 b(lists)g(=)h([[]])1206 2117 y(*)1296 2104 y(3)444 2195 y(>>>)f(lists)444 2287 y([[],)g([],)g([]])444 2378 y(>>>)g (lists[0].append\(3\))444 2469 y(>>>)g(lists)444 2561 y([[3],)g([3],)g([3]])208 2832 y FN(What)23 b(has)h(happened)d(is)j (that)g FJ([[]])f FN(is)h(a)g(one-element)d(list)k(containing)c(an)j (empty)e(list,)j(so)f(all)g(three)f(elements)g(of)g FJ([[]])208 2946 y(*)307 2931 y(3)g FN(are)f(\(pointers)f(to\))h(this)h(single)g (empty)e(list.)32 b(Modifying)21 b(an)o(y)g(of)h(the)h(elements)f(of)g FJ(lists)g FN(modi\002es)g(this)g(single)h(list.)208 3031 y(Y)-9 b(ou)19 b(can)h(create)g(a)h(list)g(of)f(dif)n(ferent)e (lists)k(this)f(w)o(ay:)444 3254 y FA(>>>)44 b(lists)g(=)h([[])f(for)g (i)h(in)g(range\(3\)])444 3345 y(>>>)f(lists[0].append\(3\))444 3436 y(>>>)g(lists[1].append\(5\))444 3528 y(>>>)g (lists[2].append\(7\))444 3619 y(>>>)g(lists)444 3710 y([[3],)g([5],)g([7]])0 4014 y FL(\(3\))c FN(If)21 b FK(i)g FN(or)f FK(j)h FN(is)g(ne)o(gati)n(v)o(e,)d(the)j(inde)o(x)e(is) i(relati)n(v)o(e)f(to)h(the)f(end)g(of)g(the)g(string:)26 b FJ(len\()p FK(s)p FJ(\))49 b(+)h FK(i)21 b FN(or)f FJ(len\()p FK(s)p FJ(\))49 b(+)h FK(j)21 b FN(is)g(substituted.)k(But) 208 4113 y(note)19 b(that)i FJ(-0)f FN(is)h(still)g FJ(0)p FN(.)0 4277 y FL(\(4\))40 b FN(The)19 b(slice)i(of)e FK(s)h FN(from)f FK(i)h FN(to)g FK(j)g FN(is)g(de\002ned)f(as)h(the)f (sequence)g(of)g(items)h(with)f(inde)o(x)g FK(k)i FN(such)e(that)h FK(i)50 b FJ(<=)f FK(k)i FJ(<)f FK(j)p FN(.)25 b(If)20 b FK(i)g FN(or)f FK(j)h FN(is)h(greater)208 4376 y(than)f FJ(len\()p FK(s)p FJ(\))p FN(,)h(use)h FJ(len\()p FK(s)p FJ(\))p FN(.)28 b(If)21 b FK(i)h FN(is)g(omitted)f(or)f FJ(None)p FN(,)i(use)f FJ(0)p FN(.)28 b(If)21 b FK(j)h FN(is)g(omitted)f(or)g FJ(None)p FN(,)g(use)g FJ(len\()p FK(s)p FJ(\))p FN(.)28 b(If)21 b FK(i)h FN(is)h(greater)208 4476 y(than)c(or)h(equal)g(to)g FK(j)p FN(,)h(the)f(slice)h(is)g(empty) -5 b(.)0 4639 y FL(\(5\))40 b FN(The)30 b(slice)g(of)g FK(s)g FN(from)f FK(i)h FN(to)g FK(j)h FN(with)f(step)g FK(k)h FN(is)g(de\002ned)e(as)h(the)g(sequence)f(of)g(items)h(with)g (inde)o(x)f FK(x)50 b FJ(=)g FK(i)f FJ(+)h FK(n)3475 4654 y FJ(*)3525 4639 y FK(k)31 b FN(such)e(that)208 4739 y Fu(0)f FM(\024)h Ft(n)g(<)555 4702 y Fs(j)s Fr(\000)p Fs(i)p 555 4720 107 4 v 589 4767 a(k)671 4739 y FN(.)35 b(In)23 b(other)g(w)o(ords,)h(the)f(indices)g(are)h FJ(i)p FN(,)g FJ(i+k)p FN(,)g FJ(i+2)2213 4754 y(*)2263 4739 y(k)p FN(,)g FJ(i+3)2508 4754 y(*)2558 4739 y(k)f FN(and)g(so)h(on,)f (stopping)f(when)h FK(j)h FN(is)h(reached)208 4838 y(\(b)n(ut)18 b(ne)n(v)o(er)g(including)f FK(j)p FN(\).)25 b(If)19 b FK(i)h FN(or)f FK(j)h FN(is)g(greater)e(than)h FJ(len\()p FK(s)p FJ(\))p FN(,)g(use)g FJ(len\()p FK(s)p FJ(\))p FN(.)25 b(If)19 b FK(i)g FN(or)g FK(j)h FN(are)f(omitted)g(or)f FJ(None)p FN(,)h(the)o(y)g(become)208 4938 y(\223end\224)g(v)n(alues)h (\(which)f(end)h(depends)e(on)i(the)g(sign)h(of)f FK(k)q FN(\).)25 b(Note,)20 b FK(k)i FN(cannot)d(be)h(zero.)k(If)d FK(k)h FN(is)f FJ(None)p FN(,)e(it)i(is)g(treated)f(lik)o(e)h FJ(1)p FN(.)0 5101 y FL(\(6\))40 b FN(If)26 b FK(s)h FN(and)f FK(t)i FN(are)f(both)e(strings,)i(some)f(Python)g (implementations)e(such)i(as)h(CPython)e(can)h(usually)g(perform)e(an)i (in-place)f(op-)208 5201 y(timization)30 b(for)g(assignments)g(of)g (the)h(form)e FK(s)p FJ(=)p FK(s)p FJ(+)p FK(t)k FN(or)e FK(s)p FJ(+=)p FK(t)q FN(.)57 b(When)31 b(applicable,)g(this)h (optimization)d(mak)o(es)h(quadratic)208 5300 y(run-time)22 b(much)h(less)i(lik)o(ely)-5 b(.)36 b(This)24 b(optimization)e(is)j (both)e(v)o(ersion)g(and)g(implementation)f(dependent.)34 b(F)o(or)23 b(performance)208 5400 y(sensiti)n(v)o(e)g(code,)h(it)g(is) h(preferable)d(to)i(use)f(the)h FJ(str.join\(\))f FN(method)f(which)h (assures)h(consistent)g(linear)f(concatenation)p 0 5549 3901 4 v 0 5649 a FI(28)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 29 41 TeXDict begin 29 40 bop 208 83 a FN(performance)25 b(across)k(v)o (ersions)e(and)h(implementations.)98 b(Changed)27 b(in)i(v)o(ersion)e (2.4:)h(F)o(ormerly)-5 b(,)28 b(string)g(concatenation)208 183 y(ne)n(v)o(er)18 b(occurred)h(in-place.)0 468 y Fv(3.6.1)100 b(Str)q(ing)30 b(Methods)0 670 y FN(These)20 b(are)g(the)g(string)g (methods)f(which)h(both)f(8-bit)h(strings)g(and)g(Unicode)f(objects)h (support:)0 817 y FD(capitalize)p FJ(\(\))208 917 y FN(Return)f(a)i (cop)o(y)e(of)h(the)g(string)g(with)h(only)e(its)i(\002rst)g(character) e(capitalized.)208 1050 y(F)o(or)g(8-bit)h(strings,)g(this)h(method)d (is)k(locale-dependent.)0 1197 y FD(center)p FJ(\()p FK(width)p FC([)p FK(,)d(\002llc)o(har)14 b FC(])p FJ(\))208 1296 y FN(Return)27 b(centered)f(in)i(a)g(string)f(of)g(length)g FK(width)p FN(.)47 b(P)o(adding)26 b(is)i(done)f(using)g(the)g (speci\002ed)h FK(\002llc)o(har)g FN(\(def)o(ault)f(is)h(a)g(space\).) 208 1396 y(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(Support)g(for)h(the)g FK(\002llc)o(har)h FN(ar)o(gument.)0 1543 y FD(count)p FJ(\()p FK(sub)p FC([)p FK(,)e(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 1642 y FN(Return)23 b(the)h(number)f(of)g (occurrences)f(of)i(substring)f FK(sub)h FN(in)h(string)e(S)p FJ([)p FK(start)q FJ(:)p FK(end)r FJ(])p FN(.)37 b(Optional)23 b(ar)o(guments)f FK(start)27 b FN(and)c FK(end)208 1742 y FN(are)d(interpreted)e(as)j(in)f(slice)h(notation.)0 1889 y FD(decode)p FJ(\()p FC([)p FK(encoding)p FC([)p FK(,)16 b(err)l(or)o(s)c FC(])g(])p FJ(\))208 1989 y FN(Decodes)25 b(the)h(string)g(using)g(the)g(codec)f(re)o(gistered)g (for)g FK(encoding)p FN(.)41 b FK(encoding)24 b FN(def)o(aults)h(to)i (the)f(def)o(ault)f(string)h(encoding.)208 2088 y FK(err)l(or)o(s)20 b FN(may)f(be)g(gi)n(v)o(en)f(to)h(set)h(a)f(dif)n(ferent)f(error)f (handling)h(scheme.)24 b(The)18 b(def)o(ault)h(is)h FJ('strict')p FN(,)e(meaning)f(that)j(encoding)208 2188 y(errors)h(raise)i FJ(UnicodeError)p FN(.)29 b(Other)22 b(possible)g(v)n(alues)g(are)g FJ('ignore')p FN(,)g FJ('replace')f FN(and)h(an)o(y)f(other)h(name)f (re)o(gis-)208 2287 y(tered)k(via)h FJ(codecs.register_error)p FN(,)e(see)j(section)f(4.8.1.)85 b(Ne)n(w)27 b(in)f(v)o(ersion)f(2.2.) 129 b(Changed)25 b(in)h(v)o(ersion)f(2.3:)208 2387 y(Support)18 b(for)i(other)f(error)g(handling)g(schemes)h(added.)0 2534 y FD(encode)p FJ(\()p FC([)p FK(encoding)p FC([)p FK(,err)l(or)o(s)12 b FC(])g(])p FJ(\))208 2634 y FN(Return)57 b(an)h(encoded)e(v)o(ersion)g(of)i(the)g(string.)138 b(Def)o(ault)57 b(encoding)f(is)j(the)f(current)e(def)o(ault)i(string)f (encod-)208 2733 y(ing.)130 b FK(err)l(or)o(s)57 b FN(may)e(be)g(gi)n (v)o(en)f(to)i(set)g(a)g(dif)n(ferent)e(error)g(handling)g(scheme.)130 b(The)55 b(def)o(ault)g(for)g FK(err)l(or)o(s)i FN(is)208 2833 y FJ('strict')p FN(,)28 b(meaning)e(that)i(encoding)d(errors)i (raise)h(a)g FJ(UnicodeError)p FN(.)46 b(Other)27 b(possible)h(v)n (alues)f(are)h FJ('ignore')p FN(,)208 2932 y FJ('replace')p FN(,)44 b FJ('xmlcharrefreplace')p FN(,)f FJ('backslashreplace')c FN(and)h(an)o(y)g(other)g(name)h(re)o(gistered)f(via)208 3032 y FJ(codecs.register_error)p FN(,)20 b(see)25 b(section)e(4.8.1.) 34 b(F)o(or)23 b(a)h(list)g(of)g(possible)f(encodings,)f(see)j(section) e(4.8.3.)70 b(Ne)n(w)23 b(in)208 3132 y(v)o(ersion)c(2.0.)80 b(Changed)19 b(in)i(v)o(ersion)e(2.3:)h(Support)g(for)g FJ('xmlcharrefreplace')d FN(and)j FJ('backslashreplace')208 3231 y FN(and)f(other)h(error)f(handling)f(schemes)i(added.)0 3378 y FD(endswith)p FJ(\()p FK(suf)o(\002x)p FC([)p FK(,)e(start)q FC([)p FK(,)j(end)13 b FC(])f(])p FJ(\))208 3478 y FN(Return)23 b FJ(True)g FN(if)h(the)f(string)h(ends)f(with)h (the)f(speci\002ed)g FK(suf)o(\002x)p FN(,)h(otherwise)f(return)f FJ(False)p FN(.)35 b FK(suf)o(\002x)23 b FN(can)g(also)h(be)g(a)g (tuple)f(of)208 3577 y(suf)n(\002x)o(es)g(to)i(look)f(for)-5 b(.)37 b(W)m(ith)24 b(optional)g FK(start)q FN(,)i(test)f(be)o(ginning) d(at)j(that)f(position.)37 b(W)m(ith)25 b(optional)e FK(end)r FN(,)i(stop)f(comparing)e(at)208 3677 y(that)e(position.)208 3810 y(Changed)e(in)j(v)o(ersion)e(2.5:)g(Accept)h(tuples)g(as)h FK(suf)o(\002x)p FN(.)0 3957 y FD(expandtabs)p FJ(\()p FC([)p FK(tabsize)12 b FC(])p FJ(\))208 4056 y FN(Return)19 b(a)h(cop)o(y)f(of)h(the)f(string)h(where)f(all)i(tab)e(characters)g (are)h(e)o(xpanded)d(using)j(spaces.)25 b(If)19 b FK(tabsize)h FN(is)h(not)e(gi)n(v)o(en,)g(a)h(tab)g(size)208 4156 y(of)f FJ(8)i FN(characters)e(is)i(assumed.)0 4303 y FD(find)p FJ(\()p FK(sub)p FC([)p FK(,)e(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 4402 y FN(Return)18 b(the)i(lo)n(west)f(inde)o(x)f(in)i(the)f(string)g(where)g(substring)f FK(sub)h FN(is)h(found,)e(such)h(that)g FK(sub)g FN(is)h(contained)e (in)h(the)h(range)e([)p FK(start)q FN(,)208 4502 y FK(end)r FN(].)24 b(Optional)19 b(ar)o(guments)f FK(start)23 b FN(and)c FK(end)j FN(are)e(interpreted)f(as)i(in)f(slice)h(notation.)j (Return)19 b FJ(-1)i FN(if)f FK(sub)g FN(is)h(not)f(found.)0 4649 y FD(index)p FJ(\()p FK(sub)p FC([)p FK(,)f(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 4749 y FN(Lik)o(e)20 b FJ(find\(\))p FN(,)f(b)n(ut)h(raise)h FJ(ValueError)e FN(when)g(the)h(substring)g(is)h(not)f(found.)0 4895 y FD(isalnum)p FJ(\(\))208 4995 y FN(Return)f(true)h(if)h(all)f (characters)g(in)g(the)g(string)g(are)g(alphanumeric)e(and)h(there)h (is)h(at)g(least)g(one)f(character)m(,)e(f)o(alse)j(otherwise.)208 5128 y(F)o(or)e(8-bit)h(strings,)g(this)h(method)d(is)k (locale-dependent.)0 5275 y FD(isalpha)p FJ(\(\))208 5374 y FN(Return)d(true)h(if)h(all)f(characters)g(in)g(the)g(string)g (are)g(alphabetic)f(and)h(there)g(is)h(at)f(least)h(one)f(character)m (,)e(f)o(alse)j(otherwise.)p 0 5549 3901 4 v 0 5649 a FI(3.6.)52 b(Sequence)24 b(T)-10 b(ypes)22 b(\227)h FJ(str)p FI(,)g FJ(unicode)p FI(,)f FJ(list)p FI(,)g FJ(tuple)p FI(,)g FJ(buffer)p FI(,)g FJ(xrange)1100 b FI(29)p eop end %%Page: 30 42 TeXDict begin 30 41 bop 208 83 a FN(F)o(or)19 b(8-bit)h(strings,)g (this)h(method)d(is)k(locale-dependent.)0 230 y FD(isdigit)p FJ(\(\))208 330 y FN(Return)d(true)h(if)h(all)f(characters)g(in)g(the)g (string)g(are)g(digits)h(and)e(there)h(is)h(at)g(least)g(one)e (character)m(,)g(f)o(alse)h(otherwise.)208 462 y(F)o(or)f(8-bit)h (strings,)g(this)h(method)d(is)k(locale-dependent.)0 609 y FD(islower)p FJ(\(\))208 709 y FN(Return)28 b(true)g(if)i(all)f (cased)g(characters)f(in)h(the)g(string)f(are)h(lo)n(wercase)f(and)h (there)f(is)i(at)f(least)h(one)e(cased)h(character)m(,)g(f)o(alse)208 808 y(otherwise.)208 941 y(F)o(or)19 b(8-bit)h(strings,)g(this)h (method)d(is)k(locale-dependent.)0 1088 y FD(isspace)p FJ(\(\))208 1188 y FN(Return)15 b(true)h(if)g(there)g(are)g(only)f (whitespace)h(characters)f(in)h(the)g(string)g(and)f(there)h(is)h(at)f (least)h(one)f(character)m(,)f(f)o(alse)h(otherwise.)208 1321 y(F)o(or)j(8-bit)h(strings,)g(this)h(method)d(is)k (locale-dependent.)0 1468 y FD(istitle)p FJ(\(\))208 1567 y FN(Return)c(true)g(if)g(the)h(string)f(is)h(a)g(titlecased)g (string)f(and)g(there)g(is)h(at)g(least)g(one)f(character)m(,)f(for)h (e)o(xample)f(uppercase)g(characters)208 1667 y(may)i(only)h(follo)n(w) f(uncased)g(characters)g(and)h(lo)n(wercase)g(characters)f(only)g (cased)h(ones.)25 b(Return)20 b(f)o(alse)h(otherwise.)208 1800 y(F)o(or)e(8-bit)h(strings,)g(this)h(method)d(is)k (locale-dependent.)0 1946 y FD(isupper)p FJ(\(\))208 2046 y FN(Return)28 b(true)g(if)h(all)h(cased)e(characters)g(in)h(the)g (string)f(are)h(uppercase)e(and)h(there)h(is)g(at)h(least)f(one)f (cased)h(character)m(,)g(f)o(alse)208 2146 y(otherwise.)208 2279 y(F)o(or)19 b(8-bit)h(strings,)g(this)h(method)d(is)k (locale-dependent.)0 2425 y FD(join)p FJ(\()p FK(seq)p FJ(\))208 2525 y FN(Return)d(a)g(string)h(which)e(is)j(the)e (concatenation)e(of)i(the)h(strings)f(in)h(the)f(sequence)g FK(seq)p FN(.)25 b(The)19 b(separator)f(between)g(elements)i(is)208 2625 y(the)g(string)g(pro)o(viding)d(this)k(method.)0 2772 y FD(ljust)p FJ(\()p FK(width)p FC([)p FK(,)e(\002llc)o(har)14 b FC(])p FJ(\))208 2871 y FN(Return)20 b(the)g(string)h(left)f (justi\002ed)h(in)g(a)g(string)f(of)g(length)g FK(width)p FN(.)26 b(P)o(adding)19 b(is)j(done)d(using)i(the)f(speci\002ed)g FK(\002llc)o(har)i FN(\(def)o(ault)e(is)208 2971 y(a)h(space\).)29 b(The)21 b(original)f(string)h(is)i(returned)c(if)j FK(width)g FN(is)g(less)h(than)e FJ(len\()p FK(s)p FJ(\))p FN(.)58 b(Changed)20 b(in)i(v)o(ersion)e(2.4:)h(Support)f(for)h(the)208 3070 y FK(\002llc)o(har)g FN(ar)o(gument.)0 3217 y FD(lower)p FJ(\(\))208 3317 y FN(Return)e(a)i(cop)o(y)e(of)h(the)g(string)g(con)m (v)o(erted)e(to)i(lo)n(wercase.)208 3450 y(F)o(or)f(8-bit)h(strings,)g (this)h(method)d(is)k(locale-dependent.)0 3597 y FD(lstrip)p FJ(\()p FC([)p FK(c)o(har)o(s)12 b FC(])p FJ(\))208 3696 y FN(Return)17 b(a)h(cop)o(y)g(of)f(the)h(string)g(with)g(leading)f (characters)g(remo)o(v)o(ed.)22 b(The)17 b FK(c)o(har)o(s)h FN(ar)o(gument)e(is)j(a)f(string)g(specifying)e(the)i(set)h(of)208 3796 y(characters)h(to)h(be)h(remo)o(v)o(ed.)k(If)21 b(omitted)g(or)g FJ(None)p FN(,)g(the)g FK(c)o(har)o(s)g FN(ar)o(gument)e(def)o(aults)i(to)h(remo)o(ving)d(whitespace.)28 b(The)21 b FK(c)o(har)o(s)208 3896 y FN(ar)o(gument)c(is)22 b(not)d(a)i(pre\002x;)f(rather)m(,)e(all)j(combinations)d(of)i(its)h(v) n(alues)f(are)g(stripped:)623 4120 y FA(>>>)44 b(')135 b(spacious)e('.lstrip\(\))623 4211 y('spacious)g(')623 4302 y(>>>)44 b('www.example.com'.lstrip\('cmowz.'\))623 4394 y('example.com')208 4550 y FN(Changed)18 b(in)j(v)o(ersion)e (2.2.2:)g(Support)f(for)i(the)g FK(c)o(har)o(s)g FN(ar)o(gument.)0 4697 y FD(partition)p FJ(\()p FK(sep)p FJ(\))208 4797 y FN(Split)25 b(the)f(string)h(at)g(the)g(\002rst)g(occurrence)d(of)j FK(sep)p FN(,)h(and)e(return)f(a)i(3-tuple)f(containing)e(the)j(part)g (before)e(the)h(separator)m(,)h(the)208 4896 y(separator)g(itself,)k (and)e(the)g(part)f(after)h(the)g(separator)-5 b(.)45 b(If)26 b(the)h(separator)f(is)i(not)f(found,)g(return)e(a)j(3-tuple)d (containing)h(the)208 4996 y(string)19 b(itself,)i(follo)n(wed)e(by)h (tw)o(o)g(empty)f(strings.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 5143 y FD(replace)p FJ(\()p FK(old,)f(ne)o(w)p FC([)p FK(,)i(count)13 b FC(])p FJ(\))208 5242 y FN(Return)k(a)h(cop)o(y)f(of) h(the)g(string)g(with)g(all)g(occurrences)e(of)i(substring)e FK(old)k FN(replaced)d(by)g FK(ne)o(w)p FN(.)25 b(If)17 b(the)h(optional)f(ar)o(gument)f FK(count)208 5342 y FN(is)21 b(gi)n(v)o(en,)d(only)i(the)g(\002rst)h FK(count)g FN(occurrences)d(are)i(replaced.)p 0 5549 3901 4 v 0 5649 a FI(30)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 31 43 TeXDict begin 31 42 bop 0 83 a FD(rfind)p FJ(\()p FK(sub)19 b FC([)p FK(,start)j FC([)p FK(,end)13 b FC(])f(])p FJ(\))208 183 y FN(Return)k(the)h(highest)g(inde)o(x)f(in)h(the)h(string)e(where) h(substring)f FK(sub)h FN(is)h(found,)e(such)h(that)g FK(sub)g FN(is)i(contained)c(within)i(s[start,end].)208 282 y(Optional)i(ar)o(guments)f FK(start)23 b FN(and)c FK(end)j FN(are)e(interpreted)f(as)h(in)h(slice)g(notation.)i(Return)d FJ(-1)h FN(on)e(f)o(ailure.)0 429 y FD(rindex)p FJ(\()p FK(sub)p FC([)p FK(,)f(start)q FC([)p FK(,)j(end)13 b FC(])f(])p FJ(\))208 529 y FN(Lik)o(e)20 b FJ(rfind\(\))f FN(b)n(ut)h(raises)h FJ(ValueError)e FN(when)h(the)g(substring)f FK(sub)h FN(is)h(not)f(found.)0 676 y FD(rjust)p FJ(\()p FK(width)p FC([)p FK(,)f(\002llc)o(har)14 b FC(])p FJ(\))208 775 y FN(Return)21 b(the)h(string)g(right)g(justi\002ed)g(in)g(a)h (string)e(of)h(length)f FK(width)p FN(.)31 b(P)o(adding)21 b(is)i(done)e(using)h(the)g(speci\002ed)f FK(\002llc)o(har)j FN(\(def)o(ault)208 875 y(is)g(a)f(space\).)34 b(The)23 b(original)f(string)h(is)h(returned)e(if)h FK(width)g FN(is)i(less)f(than)f FJ(len\()p FK(s)p FJ(\))p FN(.)69 b(Changed)21 b(in)j(v)o(ersion)e(2.4:)g(Support)g(for)208 975 y(the)e FK(\002llc)o(har)h FN(ar)o(gument.)0 1121 y FD(rpartition)p FJ(\()p FK(sep)p FJ(\))208 1221 y FN(Split)k(the)h (string)f(at)h(the)f(last)h(occurrence)e(of)h FK(sep)p FN(,)h(and)f(return)f(a)i(3-tuple)e(containing)g(the)h(part)g(before)f (the)i(separator)m(,)f(the)208 1321 y(separator)f(itself,)k(and)d(the)h (part)g(after)f(the)h(separator)-5 b(.)42 b(If)25 b(the)h(separator)f (is)i(not)e(found,)h(return)e(a)j(3-tuple)d(containing)g(tw)o(o)208 1420 y(empty)19 b(strings,)h(follo)n(wed)f(by)g(the)i(string)e(itself.) 52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 1567 y FD(rsplit)p FJ(\()p FC([)p FK(sep)h FC([)p FK(,maxsplit)13 b FC(])f(])p FJ(\))208 1667 y FN(Return)22 b(a)i(list)g(of)f(the)g(w)o(ords)g(in)g (the)g(string,)h(using)e FK(sep)i FN(as)g(the)f(delimiter)f(string.)34 b(If)23 b FK(maxsplit)h FN(is)g(gi)n(v)o(en,)f(at)g(most)h FK(maxsplit)208 1766 y FN(splits)d(are)f(done,)f(the)i FK(rightmost)f FN(ones.)25 b(If)c FK(sep)f FN(is)i(not)e(speci\002ed)g (or)g FJ(None)p FN(,)g(an)o(y)g(whitespace)f(string)h(is)i(a)f (separator)-5 b(.)24 b(Except)208 1866 y(for)h(splitting)h(from)f(the)h (right,)g FJ(rsplit\(\))f FN(beha)n(v)o(es)h(lik)o(e)g FJ(split\(\))f FN(which)h(is)h(described)d(in)i(detail)h(belo)n(w)-5 b(.)84 b(Ne)n(w)26 b(in)208 1966 y(v)o(ersion)18 b(2.4.)0 2113 y FD(rstrip)p FJ(\()p FC([)p FK(c)o(har)o(s)12 b FC(])p FJ(\))208 2212 y FN(Return)17 b(a)i(cop)o(y)e(of)h(the)g(string) g(with)h(trailing)e(characters)h(remo)o(v)o(ed.)j(The)d FK(c)o(har)o(s)g FN(ar)o(gument)e(is)j(a)g(string)f(specifying)f(the)h (set)h(of)208 2312 y(characters)h(to)h(be)h(remo)o(v)o(ed.)k(If)21 b(omitted)g(or)g FJ(None)p FN(,)g(the)g FK(c)o(har)o(s)g FN(ar)o(gument)e(def)o(aults)i(to)h(remo)o(ving)d(whitespace.)28 b(The)21 b FK(c)o(har)o(s)208 2411 y FN(ar)o(gument)c(is)22 b(not)d(a)i(suf)n(\002x;)f(rather)m(,)f(all)h(combinations)f(of)h(its)h (v)n(alues)f(are)g(stripped:)623 2631 y FA(>>>)44 b(')135 b(spacious)e('.rstrip\(\))623 2722 y(')h(spacious')623 2814 y(>>>)44 b('mississippi'.rstrip\('ipz'\))623 2905 y('mississ')208 3061 y FN(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g (Support)f(for)i(the)g FK(c)o(har)o(s)g FN(ar)o(gument.)0 3208 y FD(split)p FJ(\()p FC([)p FK(sep)f FC([)p FK(,maxsplit)13 b FC(])f(])p FJ(\))208 3308 y FN(Return)22 b(a)i(list)g(of)f(the)g(w)o (ords)g(in)g(the)g(string,)h(using)e FK(sep)i FN(as)g(the)f(delimiter)f (string.)34 b(If)23 b FK(maxsplit)h FN(is)g(gi)n(v)o(en,)f(at)g(most)h FK(maxsplit)208 3408 y FN(splits)17 b(are)f(done.)22 b(\(thus,)16 b(the)h(list)g(will)g(ha)n(v)o(e)e(at)i(most)f FK(maxsplit)q FJ(+1)g FN(elements\).)23 b(If)16 b FK(maxsplit)h FN(is)g(not)f(speci\002ed,)h(then)e(there)h(is)h(no)208 3507 y(limit)j(on)g(the)g(number)e(of)h(splits)i(\(all)g(possible)e (splits)i(are)f(made\).)k(Consecuti)n(v)o(e)19 b(delimiters)g(are)h (not)g(grouped)e(together)g(and)208 3607 y(are)23 b(deemed)g(to)h (delimit)f(empty)g(strings)h(\(for)f(e)o(xample,)g(`)p FJ('1,,2'.split\(','\))p FN(')e(returns)i(`)p FJ(['1',)48 b('',)i('2'])p FN('\).)208 3706 y(The)28 b FK(sep)h FN(ar)o(gument)e (may)h(consist)h(of)f(multiple)h(characters)e(\(for)h(e)o(xample,)i(`)p FJ('1,)48 b(2,)i(3'.split\(',)e('\))p FN(')30 b(returns)208 3806 y(`)p FJ(['1',)48 b('2',)h('3'])p FN('\).)24 b(Splitting)c(an)g (empty)f(string)h(with)h(a)f(speci\002ed)g(separator)f(returns)h(`)p FJ([''])p FN('.)208 3934 y(If)f FK(sep)g FN(is)i(not)e(speci\002ed)g (or)g(is)i FJ(None)p FN(,)e(a)h(dif)n(ferent)d(splitting)j(algorithm)d (is)k(applied.)i(First,)e(whitespace)d(characters)h(\(spaces,)208 4034 y(tabs,)30 b(ne)n(wlines,)f(returns,)h(and)d(formfeeds\))f(are)i (stripped)g(from)f(both)g(ends.)49 b(Then,)29 b(w)o(ords)f(are)g (separated)f(by)h(arbitrary)208 4134 y(length)h(strings)i(of)f (whitespace)g(characters.)54 b(Consecuti)n(v)o(e)30 b(whitespace)f (delimiters)i(are)f(treated)g(as)h(a)g(single)f(delimiter)208 4233 y(\(`)p FJ('1)48 b(2)i(3'.split\(\))p FN(')25 b(returns)h(`)p FJ(['1',)48 b('2',)h('3'])p FN('\).)44 b(Splitting)27 b(an)f(empty)g(string)h(or)f(a)h(string)g(consisting)f(of)208 4333 y(just)20 b(whitespace)g(returns)f(an)h(empty)g(list.)0 4480 y FD(splitlines)p FJ(\()p FC([)p FK(k)o(eepends)12 b FC(])p FJ(\))208 4579 y FN(Return)20 b(a)i(list)h(of)e(the)g(lines)h (in)f(the)h(string,)f(breaking)e(at)j(line)f(boundaries.)27 b(Line)21 b(breaks)f(are)i(not)f(included)f(in)h(the)g(resulting)208 4679 y(list)g(unless)f FK(k)o(eepends)f FN(is)i(gi)n(v)o(en)e(and)h (true.)0 4826 y FD(startswith)p FJ(\()p FK(pr)m(e\002x)p FC([)p FK(,)d(start)q FC([)p FK(,)22 b(end)12 b FC(])g(])p FJ(\))208 4926 y FN(Return)24 b FJ(True)g FN(if)h(string)f(starts)i (with)f(the)f FK(pr)m(e\002x)p FN(,)h(otherwise)f(return)g FJ(False)p FN(.)38 b FK(pr)m(e\002x)24 b FN(can)h(also)f(be)h(a)g (tuple)f(of)h(pre\002x)o(es)e(to)208 5025 y(look)d(for)-5 b(.)29 b(W)m(ith)22 b(optional)f FK(start)q FN(,)i(test)f(string)g(be)o (ginning)d(at)j(that)g(position.)28 b(W)m(ith)22 b(optional)e FK(end)r FN(,)i(stop)f(comparing)f(string)h(at)208 5125 y(that)f(position.)208 5253 y(Changed)e(in)j(v)o(ersion)e(2.5:)g (Accept)h(tuples)g(as)h FK(pr)m(e\002x)p FN(.)0 5400 y FD(strip)p FJ(\()p FC([)p FK(c)o(har)o(s)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(3.6.)52 b(Sequence)24 b(T)-10 b(ypes)22 b(\227)h FJ(str)p FI(,)g FJ(unicode)p FI(,)f FJ(list)p FI(,)g FJ(tuple)p FI(,)g FJ(buffer)p FI(,)g FJ(xrange)1100 b FI(31)p eop end %%Page: 32 44 TeXDict begin 32 43 bop 208 83 a FN(Return)26 b(a)h(cop)o(y)e(of)i(the) f(string)g(with)h(the)g(leading)e(and)h(trailing)g(characters)g(remo)o (v)o(ed.)41 b(The)27 b FK(c)o(har)o(s)f FN(ar)o(gument)e(is)k(a)f (string)208 183 y(specifying)c(the)j(set)g(of)f(characters)g(to)g(be)g (remo)o(v)o(ed.)38 b(If)26 b(omitted)e(or)h FJ(None)p FN(,)i(the)e FK(c)o(har)o(s)g FN(ar)o(gument)f(def)o(aults)g(to)i(remo) o(ving)208 282 y(whitespace.)e(The)c FK(c)o(har)o(s)g FN(ar)o(gument)e(is)j(not)f(a)g(pre\002x)g(or)g(suf)n(\002x;)g(rather)m (,)e(all)j(combinations)d(of)i(its)h(v)n(alues)f(are)g(stripped:)623 506 y FA(>>>)44 b(')135 b(spacious)e('.strip\(\))623 598 y('spacious')623 689 y(>>>)44 b ('www.example.com'.strip\('cmowz.'\))623 780 y('example')208 937 y FN(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g(Support)f(for)i(the)g FK(c)o(har)o(s)g FN(ar)o(gument.)0 1084 y FD(swapcase)p FJ(\(\))208 1183 y FN(Return)f(a)i(cop)o(y)e(of)h(the)g(string)g(with)h (uppercase)d(characters)i(con)m(v)o(erted)d(to)j(lo)n(wercase)g(and)g (vice)g(v)o(ersa.)208 1316 y(F)o(or)f(8-bit)h(strings,)g(this)h(method) d(is)k(locale-dependent.)0 1463 y FD(title)p FJ(\(\))208 1563 y FN(Return)g(a)i(titlecased)g(v)o(ersion)e(of)h(the)g(string:)32 b(w)o(ords)23 b(start)g(with)h(uppercase)e(characters,)h(all)h (remaining)d(cased)j(characters)208 1662 y(are)c(lo)n(wercase.)208 1795 y(F)o(or)f(8-bit)h(strings,)g(this)h(method)d(is)k (locale-dependent.)0 1942 y FD(translate)p FJ(\()p FK(table)p FC([)p FK(,)17 b(deletec)o(har)o(s)12 b FC(])p FJ(\))208 2042 y FN(Return)25 b(a)i(cop)o(y)e(of)h(the)g(string)g(where)g(all)g (characters)g(occurring)e(in)i(the)g(optional)f(ar)o(gument)f FK(deletec)o(har)o(s)h FN(are)h(remo)o(v)o(ed,)208 2141 y(and)d(the)g(remaining)f(characters)h(ha)n(v)o(e)g(been)g(mapped)f (through)g(the)h(gi)n(v)o(en)g(translation)g(table,)h(which)f(must)h (be)f(a)h(string)g(of)208 2241 y(length)19 b(256.)208 2374 y(Y)-9 b(ou)19 b(can)h(use)h(the)f FJ(maketrans\(\))e FN(helper)i(function)e(in)i(the)h FJ(string)e FN(module)g(to)i(create)e (a)i(translation)e(table.)208 2507 y(F)o(or)k(Unicode)f(objects,)i(the) f FJ(translate\(\))f FN(method)g(does)i(not)f(accept)g(the)g(optional)f FK(deletec)o(har)o(s)h FN(ar)o(gument.)32 b(Instead,)208 2606 y(it)21 b(returns)f(a)h(cop)o(y)e(of)i(the)f FK(s)i FN(where)e(all)h(characters)f(ha)n(v)o(e)g(been)g(mapped)f(through)f (the)j(gi)n(v)o(en)e(translation)h(table)g(which)h(must)208 2706 y(be)27 b(a)h(mapping)d(of)i(Unicode)g(ordinals)f(to)i(Unicode)e (ordinals,)i(Unicode)e(strings)h(or)h FJ(None)p FN(.)46 b(Unmapped)25 b(characters)i(are)208 2805 y(left)c(untouched.)33 b(Characters)23 b(mapped)f(to)i FJ(None)f FN(are)h(deleted.)34 b(Note,)24 b(a)g(more)f(\003e)o(xible)g(approach)f(is)i(to)g(create)f (a)h(custom)208 2905 y(character)18 b(mapping)h(codec)g(using)h(the)g FJ(codecs)g FN(module)f(\(see)h FJ(encodings.cp1251)e FN(for)h(an)h(e)o(xample\).)0 3052 y FD(upper)p FJ(\(\))208 3152 y FN(Return)f(a)i(cop)o(y)e(of)h(the)g(string)g(con)m(v)o(erted)e (to)i(uppercase.)208 3284 y(F)o(or)f(8-bit)h(strings,)g(this)h(method)d (is)k(locale-dependent.)0 3431 y FD(zfill)p FJ(\()p FK(width)p FJ(\))208 3531 y FN(Return)17 b(the)i(numeric)e(string)h(left)g (\002lled)h(with)f(zeros)g(in)h(a)f(string)g(of)g(length)g FK(width)p FN(.)24 b(The)18 b(original)f(string)h(is)h(returned)e(if)h FK(width)208 3631 y FN(is)j(less)g(than)f FJ(len\()p FK(s)p FJ(\))p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.2.)0 3915 y Fv(3.6.2)100 b(Str)q(ing)30 b(F)m(or)r(matting)f(Oper)o(ations)0 4118 y FN(String)c(and)g(Unicode)f(objects)h(ha)n(v)o(e)g(one)g(unique) f(b)n(uilt-in)g(operation:)34 b(the)26 b FJ(\045)f FN(operator)f (\(modulo\).)38 b(This)26 b(is)g(also)g(kno)n(wn)d(as)k(the)0 4218 y(string)g FK(formatting)g FN(or)g FK(interpolation)f FN(operator)-5 b(.)46 b(Gi)n(v)o(en)27 b FK(format)50 b FJ(\045)p FK(values)28 b FN(\(where)e FK(format)j FN(is)g(a)f(string) f(or)g(Unicode)g(object\),)h FJ(\045)0 4318 y FN(con)m(v)o(ersion)d (speci\002cations)i(in)g FK(format)i FN(are)e(replaced)g(with)g(zero)g (or)g(more)g(elements)g(of)g FK(values)p FN(.)46 b(The)27 b(ef)n(fect)g(is)h(similar)g(to)g(the)0 4417 y(using)19 b FJ(sprintf\(\))f FN(in)h(the)g(C)i(language.)i(If)c FK(format)h FN(is)g(a)g(Unicode)e(object,)h(or)g(if)g(an)o(y)g(of)g (the)g(objects)g(being)f(con)m(v)o(erted)f(using)i(the)0 4517 y FJ(\045s)h FN(con)m(v)o(ersion)e(are)i(Unicode)f(objects,)h(the) g(result)g(will)h(also)g(be)f(a)g(Unicode)f(object.)0 4664 y(If)g FK(format)h FN(requires)e(a)i(single)f(ar)o(gument,)d FK(values)j FN(may)g(be)g(a)g(single)g(non-tuple)e(object.)2561 4634 y FF(4)2618 4664 y FN(Otherwise,)i FK(values)f FN(must)h(be)g(a)h (tuple)e(with)0 4763 y(e)o(xactly)h(the)h(number)f(of)h(items)g (speci\002ed)g(by)g(the)g(format)f(string,)h(or)g(a)h(single)f(mapping) e(object)i(\(for)f(e)o(xample,)f(a)j(dictionary\).)0 4910 y(A)j(con)m(v)o(ersion)d(speci\002er)j(contains)f(tw)o(o)h(or)f (more)g(characters)g(and)g(has)h(the)g(follo)n(wing)e(components,)g (which)i(must)f(occur)g(in)h(this)0 5010 y(order:)104 5240 y(1.)41 b(The)19 b(`)p FJ(\045)p FN(')h(character)m(,)f(which)g (marks)h(the)g(start)h(of)f(the)g(speci\002er)-5 b(.)p 0 5311 1560 4 v 90 5366 a FB(4)120 5390 y FH(T)g(o)16 b(format)h(only)h(a)f(tuple)i(you)e(should)h(therefore)h(pro)o(vide)f (a)f(singleton)j(tuple)e(whose)f(only)h(element)h(is)e(the)h(tuple)g (to)f(be)h(formatted.)p 0 5549 3901 4 v 0 5649 a FI(32)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 33 45 TeXDict begin 33 44 bop 104 83 a FN(2.)41 b(Mapping)18 b(k)o(e)o(y)i(\(optional\),)e(consisting)h(of)h(a)h(parenthesised)d (sequence)h(of)h(characters)f(\(for)h(e)o(xample,)e FJ(\(somename\))p FN(\).)104 244 y(3.)41 b(Con)m(v)o(ersion)18 b(\003ags)i(\(optional\),) e(which)i(af)n(fect)f(the)i(result)f(of)g(some)g(con)m(v)o(ersion)d (types.)104 406 y(4.)41 b(Minimum)19 b(\002eld)i(width)f(\(optional\).) k(If)d(speci\002ed)f(as)i(an)e(`)1926 421 y FJ(*)1976 406 y FN(')h(\(asterisk\),)f(the)g(actual)h(width)f(is)i(read)e(from)g (the)g(ne)o(xt)g(element)208 505 y(of)f(the)i(tuple)e(in)i FK(values)p FN(,)e(and)h(the)g(object)g(to)g(con)m(v)o(ert)e(comes)i (after)g(the)g(minimum)f(\002eld)h(width)g(and)g(optional)f(precision.) 104 667 y(5.)41 b(Precision)22 b(\(optional\),)g(gi)n(v)o(en)f(as)j(a)f (`)p FJ(.)p FN(')34 b(\(dot\))22 b(follo)n(wed)f(by)i(the)g(precision.) 32 b(If)23 b(speci\002ed)g(as)g(`)3020 682 y FJ(*)3070 667 y FN(')g(\(an)f(asterisk\),)i(the)f(actual)208 766 y(width)c(is)j(read)d(from)g(the)i(ne)o(xt)e(element)h(of)g(the)g (tuple)g(in)g FK(values)p FN(,)g(and)f(the)h(v)n(alue)g(to)g(con)m(v)o (ert)e(comes)i(after)g(the)g(precision.)104 928 y(6.)41 b(Length)19 b(modi\002er)g(\(optional\).)104 1089 y(7.)41 b(Con)m(v)o(ersion)18 b(type.)0 1307 y(When)k(the)g(right)f(ar)o (gument)e(is)k(a)g(dictionary)d(\(or)h(other)g(mapping)f(type\),)h (then)h(the)g(formats)f(in)h(the)g(string)f FK(must)i FN(include)e(a)h(paren-)0 1407 y(thesised)j(mapping)d(k)o(e)o(y)i(into) h(that)f(dictionary)f(inserted)h(immediately)g(after)g(the)g(`)p FJ(\045)p FN(')h(character)-5 b(.)37 b(The)24 b(mapping)f(k)o(e)o(y)h (selects)i(the)0 1506 y(v)n(alue)20 b(to)g(be)g(formatted)f(from)g(the) h(mapping.)j(F)o(or)d(e)o(xample:)236 1744 y FA(>>>)45 b(print)f('\045\(language\)s)e(has)j(\045\(#\)03d)e(quote)h(types.')g (\045)g(\\)685 1836 y({'language':)e("Python",)i("#":)g(2})236 1927 y(Python)g(has)g(002)h(quote)f(types.)0 2214 y FN(In)20 b(this)h(case)f(no)498 2229 y FJ(*)569 2214 y FN(speci\002ers)g(may)g (occur)f(in)h(a)h(format)e(\(since)h(the)o(y)f(require)g(a)i (sequential)e(parameter)g(list\).)0 2360 y(The)h(con)m(v)o(ersion)d (\003ag)k(characters)e(are:)50 2657 y FL(Flag)p 255 2686 4 100 v 98 w(Meaning)p 0 2690 3971 4 v 76 2760 a FN(`)p FJ(#)p FN(')p 255 2789 4 100 v 124 w(The)h(v)n(alue)g(con)m(v)o(ersion) d(will)k(use)f(the)h(\223alternate)e(form\224)g(\(where)g(de\002ned)h (belo)n(w\).)76 2859 y(`)p FJ(0)p FN(')p 255 2889 V 124 w(The)g(con)m(v)o(ersion)e(will)j(be)f(zero)f(padded)g(for)g(numeric)g (v)n(alues.)76 2959 y(`)p FJ(-)p FN(')p 255 2989 V 124 w(The)h(con)m(v)o(erted)e(v)n(alue)h(is)i(left)g(adjusted)e(\(o)o(v)o (errides)f(the)i(`)p FJ(0)p FN(')g(con)m(v)o(ersion)e(if)i(both)f(are)i (gi)n(v)o(en\).)76 3058 y(`)49 b(')p 255 3088 V 125 w(\(a)21 b(space\))e(A)i(blank)e(should)g(be)i(left)f(before)f(a)h(positi)n(v)o (e)g(number)e(\(or)i(empty)f(string\))h(produced)d(by)j(a)h(signed)e (con)m(v)o(ersion.)76 3158 y(`)p FJ(+)p FN(')p 255 3188 V 124 w(A)i(sign)f(character)f(\(`)p FJ(+)p FN(')h(or)f(`)p FJ(-)p FN('\))h(will)h(precede)e(the)h(con)m(v)o(ersion)d(\(o)o(v)o (errides)h(a)j(\224space\224)f(\003ag\).)0 3371 y(A)h(length)e (modi\002er)g(\()p FJ(h)p FN(,)h FJ(l)p FN(,)g(or)g FJ(L)p FN(\))h(may)e(be)h(present,)g(b)n(ut)g(is)h(ignored)d(as)j(it)g(is)g (not)f(necessary)g(for)f(Python.)0 3518 y(The)h(con)m(v)o(ersion)d (types)j(are:)50 3814 y FL(Con)m(v)o(ersion)p 500 3844 V 98 w(Meaning)p 4778 3844 V 3964 w(Notes)p 0 3847 5078 4 v 198 3917 a FN(`)p FJ(d)p FN(')p 500 3947 4 100 v 247 w(Signed)g(inte)o(ger)f(decimal.)p 4778 3947 V 198 4017 a(`)p FJ(i)p FN(')p 500 4047 V 247 w(Signed)h(inte)o(ger)f (decimal.)p 4778 4047 V 198 4116 a(`)p FJ(o)p FN(')p 500 4146 V 247 w(Unsigned)g(octal.)p 4778 4146 V 3807 w(\(1\))198 4216 y(`)p FJ(u)p FN(')p 500 4246 V 247 w(Unsigned)g (decimal.)p 4778 4246 V 198 4316 a(`)p FJ(x)p FN(')p 500 4346 V 247 w(Unsigned)g(he)o(xadecimal)f(\(lo)n(wercase\).)p 4778 4346 V 3143 w(\(2\))198 4415 y(`)p FJ(X)p FN(')p 500 4445 V 247 w(Unsigned)h(he)o(xadecimal)f(\(uppercase\).)p 4778 4445 V 3140 w(\(2\))198 4515 y(`)p FJ(e)p FN(')p 500 4545 V 247 w(Floating)i(point)f(e)o(xponential)f(format)h(\(lo)n (wercase\).)p 4778 4545 V 2783 w(\(3\))198 4615 y(`)p FJ(E)p FN(')p 500 4644 V 247 w(Floating)h(point)f(e)o(xponential)f (format)h(\(uppercase\).)p 4778 4644 V 2780 w(\(3\))198 4714 y(`)p FJ(f)p FN(')p 500 4744 V 247 w(Floating)h(point)f(decimal)h (format.)p 4778 4744 V 3312 w(\(3\))198 4814 y(`)p FJ(F)p FN(')p 500 4844 V 247 w(Floating)g(point)f(decimal)h(format.)p 4778 4844 V 3312 w(\(3\))198 4913 y(`)p FJ(g)p FN(')p 500 4943 V 247 w(Floating)g(point)f(format.)24 b(Uses)d(e)o(xponential) d(format)h(if)i(e)o(xponent)c(is)22 b(greater)d(than)h(-4)f(or)h(less)i (than)d(precision,)g(decimal)h(format)f(otherwise.)p 4778 4943 V 149 w(\(4\))198 5013 y(`)p FJ(G)p FN(')p 500 5043 V 247 w(Floating)h(point)f(format.)24 b(Uses)d(e)o(xponential) d(format)h(if)i(e)o(xponent)c(is)22 b(greater)d(than)h(-4)f(or)h(less)i (than)d(precision,)g(decimal)h(format)f(otherwise.)p 4778 5043 V 149 w(\(4\))198 5113 y(`)p FJ(c)p FN(')p 500 5143 V 247 w(Single)h(character)f(\(accepts)h(inte)o(ger)f(or)h (single)g(character)f(string\).)p 4778 5143 V 198 5212 a(`)p FJ(r)p FN(')p 500 5242 V 247 w(String)h(\(con)m(v)o(erts)e(an)o (y)h(p)o(ython)g(object)h(using)f FJ(repr\(\))p FN(\).)p 4778 5242 V 2617 w(\(5\))198 5312 y(`)p FJ(s)p FN(')p 500 5342 V 247 w(String)h(\(con)m(v)o(erts)e(an)o(y)h(p)o(ython)g (object)h(using)f FJ(str\(\))p FN(\).)p 4778 5342 V 2667 w(\(6\))198 5412 y(`)p FJ(\045)p FN(')p 500 5442 V 247 w(No)h(ar)o(gument)e(is)j(con)m(v)o(erted,)d(results)i(in)h(a)f(`)p FJ(\045)p FN(')g(character)f(in)h(the)g(result.)p 4778 5442 V 0 5549 3901 4 v 0 5649 a FI(3.6.)52 b(Sequence)24 b(T)-10 b(ypes)22 b(\227)h FJ(str)p FI(,)g FJ(unicode)p FI(,)f FJ(list)p FI(,)g FJ(tuple)p FI(,)g FJ(buffer)p FI(,)g FJ(xrange)1100 b FI(33)p eop end %%Page: 34 46 TeXDict begin 34 45 bop 0 83 a FN(Notes:)0 296 y FL(\(1\))40 b FN(The)21 b(alternate)g(form)f(causes)h(a)h(leading)e(zero)h(\(`)p FJ(0)p FN('\))f(to)h(be)h(inserted)e(between)h(left-hand)e(padding)g (and)i(the)g(formatting)f(of)h(the)208 396 y(number)d(if)i(the)h (leading)e(character)g(of)h(the)g(result)g(is)h(not)f(already)f(a)i (zero.)0 562 y FL(\(2\))40 b FN(The)22 b(alternate)f(form)f(causes)i(a) g(leading)e FJ('0x')i FN(or)f FJ('0X')g FN(\(depending)e(on)i(whether)g (the)g(`)p FJ(x)p FN(')h(or)f(`)p FJ(X)p FN(')g(format)g(w)o(as)h (used\))f(to)h(be)208 662 y(inserted)d(between)g(left-hand)g(padding)f (and)i(the)g(formatting)e(of)i(the)g(number)e(if)j(the)f(leading)f (character)g(of)h(the)g(result)g(is)h(not)208 761 y(already)e(a)h (zero.)0 927 y FL(\(3\))40 b FN(The)20 b(alternate)g(form)f(causes)h (the)h(result)f(to)g(al)o(w)o(ays)h(contain)e(a)i(decimal)e(point,)g(e) n(v)o(en)h(if)g(no)g(digits)g(follo)n(w)g(it.)208 1060 y(The)f(precision)h(determines)f(the)h(number)e(of)i(digits)g(after)g (the)g(decimal)g(point)f(and)h(def)o(aults)g(to)g(6.)0 1226 y FL(\(4\))40 b FN(The)19 b(alternate)g(form)f(causes)h(the)h (result)f(to)g(al)o(w)o(ays)h(contain)e(a)i(decimal)e(point,)h(and)f (trailing)h(zeroes)g(are)g(not)g(remo)o(v)o(ed)d(as)k(the)o(y)208 1326 y(w)o(ould)f(otherwise)h(be.)208 1459 y(The)f(precision)h (determines)f(the)h(number)e(of)i(signi\002cant)g(digits)g(before)f (and)h(after)f(the)i(decimal)e(point)h(and)f(def)o(aults)h(to)g(6.)0 1625 y FL(\(5\))40 b FN(The)20 b FJ(\045r)h FN(con)m(v)o(ersion)c(w)o (as)k(added)e(in)h(Python)f(2.0.)208 1757 y(The)g(precision)h (determines)f(the)h(maximal)f(number)f(of)i(characters)g(used.)0 1924 y FL(\(6\))40 b FN(If)20 b(the)h(object)e(or)h(format)f(pro)o (vided)f(is)j(a)g FJ(unicode)e FN(string,)h(the)g(resulting)f(string)h (will)h(also)g(be)f FJ(unicode)p FN(.)208 2056 y(The)f(precision)h (determines)f(the)h(maximal)f(number)f(of)i(characters)g(used.)0 2270 y(Since)g(Python)f(strings)h(ha)n(v)o(e)g(an)g(e)o(xplicit)g (length,)f FJ(\045s)h FN(con)m(v)o(ersions)e(do)i(not)g(assume)g(that)g FJ('\\0')g FN(is)h(the)f(end)g(of)g(the)g(string.)0 2417 y(F)o(or)25 b(safety)g(reasons,)h(\003oating)f(point)f(precisions)h (are)g(clipped)f(to)i(50;)h FJ(\045f)f FN(con)m(v)o(ersions)d(for)i (numbers)e(whose)i(absolute)g(v)n(alue)g(is)0 2516 y(o)o(v)o(er)19 b(1e25)g(are)h(replaced)f(by)h FJ(\045g)g FN(con)m(v)o(ersions.)1412 2486 y FF(5)1468 2516 y FN(All)h(other)e(errors)g(raise)i(e)o (xceptions.)0 2663 y(Additional)e(string)h(operations)e(are)j (de\002ned)e(in)h(standard)f(modules)g FJ(string)h FN(and)f FJ(re)p FN(.)0 2948 y Fv(3.6.3)100 b(XRange)30 b(T)-12 b(ype)0 3151 y FN(The)17 b FJ(xrange)f FN(type)h(is)g(an)g(immutable)f (sequence)g(which)g(is)i(commonly)d(used)i(for)f(looping.)22 b(The)17 b(adv)n(antage)e(of)i(the)g FJ(xrange)f FN(type)0 3250 y(is)23 b(that)f(an)g FJ(xrange)g FN(object)g(will)h(al)o(w)o(ays) f(tak)o(e)g(the)h(same)f(amount)f(of)h(memory)-5 b(,)20 b(no)i(matter)g(the)g(size)h(of)e(the)i(range)e(it)i(represents.)0 3350 y(There)c(are)h(no)g(consistent)g(performance)d(adv)n(antages.)0 3497 y(XRange)j(objects)g(ha)n(v)o(e)f(v)o(ery)g(little)i(beha)n(vior:) j(the)o(y)c(only)f(support)g(inde)o(xing,)f(iteration,)h(and)g(the)i FJ(len\(\))e FN(function.)0 3782 y Fv(3.6.4)100 b(Mutab)n(le)29 b(Sequence)i(T)-12 b(ypes)0 3985 y FN(List)19 b(objects)e(support)g (additional)g(operations)f(that)i(allo)n(w)g(in-place)f(modi\002cation) f(of)i(the)g(object.)23 b(Other)18 b(mutable)f(sequence)g(types)0 4084 y(\(when)j(added)f(to)i(the)g(language\))e(should)g(also)i (support)f(these)h(operations.)k(Strings)20 b(and)g(tuples)h(are)g (immutable)e(sequence)h(types:)0 4184 y(such)d(objects)h(cannot)e(be)i (modi\002ed)e(once)h(created.)24 b(The)17 b(follo)n(wing)f(operations)g (are)i(de\002ned)f(on)g(mutable)g(sequence)f(types)i(\(where)0 4284 y FK(x)j FN(is)g(an)f(arbitrary)f(object\):)p 0 4355 1560 4 v 90 4410 a FB(5)120 4434 y FH(These)d(numbers)g(are)h(f)o (airly)g(arbitrary)l(.)23 b(The)o(y)16 b(are)g(intended)j(to)d(a)o(v)o (oid)g(printing)i(endless)f(strings)g(of)f(meaningless)i(digits)f (without)g(hampering)h(correct)g(use)e(and)0 4513 y(without)j(ha)o (ving)f(to)f(kno)n(w)g(the)h(e)o(xact)h(precision)g(of)e(\003oating)i (point)f(v)n(alues)g(on)f(a)g(particular)k(machine.)p 0 5549 3901 4 v 0 5649 a FI(34)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 35 47 TeXDict begin 35 46 bop 537 161 a FL(Operation)p 1437 191 4 100 v 586 w(Result)p 3616 191 V 2130 w(Notes)p 0 194 4271 4 v 549 264 a FK(s)p FJ([)p FK(i)p FJ(])49 b(=)h FK(x)p 1437 294 4 100 v 599 w FN(item)20 b FK(i)h FN(of)f FK(s)h FN(is)g(replaced)e(by)h FK(x)p 3616 294 V 519 364 a(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])49 b(=)h FK(t)p 1437 394 V 570 w FN(slice)21 b(of)f FK(s)h FN(from)e FK(i)i FN(to)f FK(j)h FN(is)g(replaced)e(by)h(the)g(contents)f(of)h (the)g(iterable)g FK(t)p 3616 394 V 506 463 a FJ(del)49 b FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])p 1437 493 V 556 w FN(same)20 b(as)h FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])50 b(=)f([])p 3616 493 V 474 563 a FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(:)p FK(k)q FJ(])h(=)g FK(t)p 1437 593 V 526 w FN(the)20 b(elements)g(of)g FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(:)p FK(k)q FJ(])g FN(are)h(replaced)e (by)g(those)h(of)g FK(t)p 3616 593 V 706 w FN(\(1\))462 663 y FJ(del)49 b FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(:)p FK(k)q FJ(])p 1437 692 V 512 w FN(remo)o(v)o(es)18 b(the)i(elements)g(of)g FK(s)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(:)p FK(k)q FJ(])h FN(from)e(the)h(list)p 3616 692 V 461 762 a FK(s)p FJ(.append\()p FK(x)p FJ(\))p 1437 792 V 509 w FN(same)g(as)h FK(s)p FJ([len\()p FK(s)p FJ(\):len\()p FK(s)p FJ(\)])48 b(=)i([)p FK(x)p FJ(])p 3616 792 V 1095 w FN(\(2\))461 862 y FK(s)p FJ(.extend\()p FK(x)p FJ(\))p 1437 892 V 509 w FN(same)20 b(as)h FK(s)p FJ([len\()p FK(s)p FJ(\):len\()p FK(s)p FJ(\)])48 b(=)i FK(x)p 3616 892 V 1195 w FN(\(3\))486 961 y FK(s)p FJ(.count\()p FK(x)p FJ(\))p 1437 991 V 534 w FN(return)19 b(number)f(of)i FK(i)p FN(')-5 b(s)21 b(for)f(which)f FK(s)p FJ([)p FK(i)p FJ(])50 b(==)g FK(x)p 3616 991 V 271 1071 a(s)p FJ(.index\()p FK(x)p FC([)p FJ(,)f FK(i)p FC([)p FJ(,)g FK(j)12 b FC(])g(])p FJ(\))p 1437 1101 4 110 v 321 w FN(return)19 b(smallest)i FK(k)h FN(such)e(that)g FK(s)p FJ([)p FK(k)q FJ(])50 b(==)f FK(x)21 b FN(and)f FK(i)50 b FJ(<=)f FK(k)i FJ(<)f FK(j)p 3616 1101 V 517 w FN(\(4\))399 1171 y FK(s)p FJ(.insert\()p FK(i)p FJ(,)f FK(x)p FJ(\))p 1437 1201 4 100 v 449 w FN(same)20 b(as)h FK(s)p FJ([)p FK(i)p FJ(:)p FK(i)p FJ(])50 b(=)f([)p FK(x)p FJ(])p 3616 1201 V 1612 w FN(\(5\))497 1281 y FK(s)p FJ(.pop\()p FC([)p FK(i)12 b FC(])p FJ(\))p 1437 1310 4 110 v 545 w FN(same)20 b(as)h FK(x)50 b FJ(=)g FK(s)p FJ([)p FK(i)p FJ(];)f(del)g FK(s)p FJ([)p FK(i)p FJ(];)h(return)f FK(x)p 3616 1310 V 845 w FN(\(6\))461 1380 y FK(s)p FJ(.remove\()p FK(x)p FJ(\))p 1437 1410 4 100 v 509 w FN(same)20 b(as)h FJ(del)49 b FK(s)p FJ([)p FK(s)p FJ(.index\()p FK(x)p FJ(\)])p 3616 1410 V 1326 w FN(\(4\))454 1480 y FK(s)p FJ(.reverse\(\))p 1437 1510 V 503 w FN(re)n(v)o(erses)19 b(the)h(items)h(of)f FK(s)h FN(in)f(place)p 3616 1510 V 1391 w(\(7\))50 1590 y FK(s)p FJ(.sort\()p FC([)p FK(cmp)p FC([)p FJ(,)48 b FK(k)o(e)n(y)p FC([)p FJ(,)g FK(r)m(e)o(ver)o(se)12 b FC(])g(])g(])p FJ(\))p 1437 1619 4 110 v 99 w FN(sort)20 b(the)g(items)h(of)f FK(s)h FN(in)f(place)p 3616 1619 V 1306 w(\(7\),)g(\(8\),)f(\(9\),)g (\(10\))0 1813 y(Notes:)0 2027 y FL(\(1\))40 b FK(t)23 b FN(must)d(ha)n(v)o(e)f(the)i(same)f(length)f(as)i(the)f(slice)h(it)g (is)g(replacing.)0 2193 y FL(\(2\))40 b FN(The)23 b(C)h(implementation) d(of)h(Python)g(has)h(historically)g(accepted)f(multiple)g(parameters)g (and)g(implicitly)h(joined)f(them)g(into)h(a)208 2292 y(tuple;)c(this)i(no)f(longer)f(w)o(orks)h(in)g(Python)f(2.0.)24 b(Use)d(of)f(this)h(misfeature)e(has)h(been)g(deprecated)e(since)j (Python)e(1.4.)0 2458 y FL(\(3\))40 b FK(x)21 b FN(can)f(be)g(an)o(y)g (iterable)f(object.)0 2624 y FL(\(4\))40 b FN(Raises)22 b FJ(ValueError)d FN(when)h FK(x)h FN(is)h(not)e(found)f(in)h FK(s)p FN(.)27 b(When)20 b(a)h(ne)o(gati)n(v)o(e)e(inde)o(x)g(is)i (passed)g(as)g(the)f(second)g(or)g(third)g(parameter)208 2724 y(to)e(the)h FJ(index\(\))f FN(method,)g(the)g(list)i(length)e(is) i(added,)d(as)j(for)e(slice)i(indices.)k(If)18 b(it)i(is)f(still)h(ne)o (gati)n(v)o(e,)d(it)j(is)f(truncated)e(to)i(zero,)208 2824 y(as)k(for)f(slice)h(indices.)65 b(Changed)21 b(in)i(v)o(ersion)e (2.3:)h(Pre)n(viously)-5 b(,)22 b FJ(index\(\))g FN(didn')o(t)f(ha)n(v) o(e)h(ar)o(guments)e(for)i(specifying)f(start)208 2923 y(and)e(stop)h(positions.)0 3089 y FL(\(5\))40 b FN(When)23 b(a)h(ne)o(gati)n(v)o(e)d(inde)o(x)g(is)j(passed)f(as)h(the)f(\002rst)h (parameter)d(to)j(the)f FJ(insert\(\))f FN(method,)g(the)h(list)h (length)e(is)i(added,)e(as)i(for)208 3189 y(slice)17 b(indices.)24 b(If)17 b(it)h(is)g(still)h(ne)o(gati)n(v)o(e,)c(it)j(is) g(truncated)e(to)h(zero,)g(as)h(for)e(slice)i(indices.)49 b(Changed)16 b(in)h(v)o(ersion)f(2.3:)h(Pre)n(viously)-5 b(,)208 3289 y(all)20 b(ne)o(gati)n(v)o(e)e(indices)i(were)g(truncated) f(to)h(zero.)0 3455 y FL(\(6\))40 b FN(The)22 b FJ(pop\(\))f FN(method)f(is)i(only)f(supported)f(by)h(the)g(list)i(and)e(array)f (types.)29 b(The)21 b(optional)g(ar)o(gument)e FK(i)j FN(def)o(aults)f(to)h FJ(-1)p FN(,)g(so)f(that)208 3554 y(by)e(def)o(ault)h(the)g(last)h(item)f(is)i(remo)o(v)o(ed)17 b(and)j(returned.)0 3720 y FL(\(7\))40 b FN(The)21 b FJ(sort\(\))f FN(and)g FJ(reverse\(\))g FN(methods)f(modify)g(the)i (list)h(in)f(place)f(for)g(economy)f(of)h(space)h(when)f(sorting)g(or)g (re)n(v)o(ersing)208 3820 y(a)g(lar)o(ge)f(list.)26 b(T)-7 b(o)21 b(remind)e(you)g(that)h(the)o(y)g(operate)f(by)h(side)g(ef)n (fect,)g(the)o(y)f(don')o(t)g(return)g(the)h(sorted)f(or)h(re)n(v)o (ersed)f(list.)0 3986 y FL(\(8\))40 b FN(The)20 b FJ(sort\(\))g FN(method)f(tak)o(es)h(optional)f(ar)o(guments)f(for)i(controlling)e (the)i(comparisons.)208 4119 y FK(cmp)h FN(speci\002es)h(a)g(custom)f (comparison)e(function)h(of)i(tw)o(o)f(ar)o(guments)f(\(list)i(items\)) g(which)f(should)f(return)h(a)h(ne)o(gati)n(v)o(e,)d(zero)208 4219 y(or)i(positi)n(v)o(e)g(number)f(depending)f(on)i(whether)g(the)g (\002rst)i(ar)o(gument)c(is)k(considered)c(smaller)j(than,)f(equal)g (to,)h(or)g(lar)o(ger)e(than)208 4318 y(the)g(second)f(ar)o(gument:)k (`)p FK(cmp)p FJ(=lambda)47 b FK(x)p FJ(,)p FK(y)p FJ(:)100 b(cmp\(x.lower\(\),)47 b(y.lower\(\)\))p FN(')208 4451 y FK(k)o(e)n(y)33 b FN(speci\002es)i(a)f(function)e(of)i(one)f(ar)o (gument)f(that)i(is)g(used)g(to)g(e)o(xtract)f(a)i(comparison)c(k)o(e)o (y)j(from)f(each)g(list)i(element:)208 4551 y(`)p FK(k)o(e)n(y)p FJ(=str.lower)p FN(')208 4683 y FK(r)m(e)o(ver)o(se)20 b FN(is)g(a)g(boolean)d(v)n(alue.)24 b(If)19 b(set)h(to)g FJ(True)p FN(,)f(then)g(the)g(list)h(elements)f(are)h(sorted)e(as)i(if) g(each)f(comparison)e(were)i(re)n(v)o(ersed.)208 4816 y(In)e(general,)g(the)i FK(k)o(e)n(y)e FN(and)h FK(r)m(e)o(ver)o(se)h FN(con)m(v)o(ersion)c(processes)j(are)g(much)f(f)o(aster)h(than)g (specifying)e(an)i(equi)n(v)n(alent)f FK(cmp)h FN(function.)208 4916 y(This)g(is)i(because)e FK(cmp)h FN(is)h(called)e(multiple)g (times)h(for)g(each)f(list)i(element)e(while)h FK(k)o(e)n(y)f FN(and)h FK(r)m(e)o(ver)o(se)g FN(touch)f(each)g(element)g(only)208 5016 y(once.)208 5148 y(Changed)g(in)j(v)o(ersion)e(2.3:)g(Support)g (for)h FJ(None)g FN(as)g(an)h(equi)n(v)n(alent)d(to)i(omitting)g FK(cmp)g FN(w)o(as)h(added.)208 5281 y(Changed)d(in)j(v)o(ersion)e (2.4:)g(Support)g(for)h FK(k)o(e)n(y)g FN(and)f FK(r)m(e)o(ver)o(se)i FN(w)o(as)g(added.)p 0 5549 3901 4 v 0 5649 a FI(3.6.)52 b(Sequence)24 b(T)-10 b(ypes)22 b(\227)h FJ(str)p FI(,)g FJ(unicode)p FI(,)f FJ(list)p FI(,)g FJ(tuple)p FI(,)g FJ(buffer)p FI(,)g FJ(xrange)1100 b FI(35)p eop end %%Page: 36 48 TeXDict begin 36 47 bop 0 83 a FL(\(9\))40 b FN(Starting)24 b(with)g(Python)f(2.3,)i(the)f FJ(sort\(\))f FN(method)g(is)i (guaranteed)d(to)j(be)f(stable.)37 b(A)25 b(sort)f(is)h(stable)f(if)h (it)g(guarantees)e(not)g(to)208 183 y(change)h(the)j(relati)n(v)o(e)e (order)g(of)h(elements)g(that)g(compare)f(equal)g(\227)i(this)g(is)g (helpful)e(for)g(sorting)h(in)g(multiple)g(passes)h(\(for)208 282 y(e)o(xample,)18 b(sort)i(by)g(department,)e(then)i(by)g(salary)g (grade\).)0 448 y FL(\(10\))40 b FN(While)29 b(a)h(list)g(is)g(being)e (sorted,)j(the)e(ef)n(fect)f(of)h(attempting)f(to)h(mutate,)i(or)d(e)n (v)o(en)g(inspect,)j(the)e(list)h(is)g(unde\002ned.)50 b(The)29 b(C)208 548 y(implementation)15 b(of)j(Python)f(2.3)g(and)g (ne)n(wer)h(mak)o(es)f(the)h(list)h(appear)e(empty)g(for)h(the)g (duration,)e(and)h(raises)i FJ(ValueError)208 648 y FN(if)h(it)h(can)f (detect)g(that)g(the)g(list)i(has)e(been)g(mutated)f(during)f(a)j (sort.)0 975 y FE(3.7)121 b(Set)33 b(T)-14 b(ypes)34 b(\227)f Fx(set)p FE(,)f Fx(frozenset)0 1208 y FN(A)27 b FK(set)g FN(object)e(is)i(an)f(unordered)e(collection)h(of)h (distinct)g(hashable)f(objects.)43 b(Common)24 b(uses)j(include)e (membership)f(testing,)k(re-)0 1307 y(mo)o(ving)22 b(duplicates)i(from) f(a)h(sequence,)g(and)g(computing)e(mathematical)h(operations)f(such)i (as)h(intersection,)f(union,)g(dif)n(ference,)0 1407 y(and)c(symmetric)f(dif)n(ference.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.4.)0 1554 y(Lik)o(e)25 b(other)f(collections,)i(sets)g(support)e FK(x)50 b FJ(in)f FK(set)q FN(,)27 b FJ(len\()p FK(set)q FJ(\))p FN(,)g(and)d FJ(for)50 b FK(x)g FJ(in)f FK(set)q FN(.)41 b(Being)25 b(an)g(unordered)d(collection,)j(sets)0 1654 y(do)30 b(not)g(record)f(element)h(position)f(or)h(order)f(of)h (insertion.)55 b(Accordingly)-5 b(,)30 b(sets)h(do)f(not)g(support)f (inde)o(xing,)i(slicing,)h(or)e(other)0 1753 y(sequence-lik)o(e)18 b(beha)n(vior)-5 b(.)0 1900 y(There)26 b(are)h(currently)e(tw)o(o)i(b)n (uiltin)g(set)g(types,)h FJ(set)f FN(and)f FJ(frozenset)p FN(.)44 b(The)27 b FJ(set)g FN(type)f(is)i(mutable)e(\227)h(the)g (contents)f(can)h(be)0 2000 y(changed)e(using)h(methods)f(lik)o(e)i FJ(add\(\))f FN(and)g FJ(remove\(\))p FN(.)43 b(Since)27 b(it)g(is)h(mutable,)f(it)g(has)g(no)f(hash)g(v)n(alue)g(and)g(cannot)f (be)i(used)0 2099 y(as)f(either)f(a)h(dictionary)e(k)o(e)o(y)h(or)g(as) h(an)g(element)f(of)g(another)f(set.)42 b(The)25 b FJ(frozenset)f FN(type)h(is)i(immutable)d(and)h(hashable)f(\227)j(its)0 2199 y(contents)19 b(cannot)h(be)g(altered)f(after)h(is)h(created;)f (ho)n(we)n(v)o(er)m(,)d(it)k(can)f(be)h(used)e(as)i(a)g(dictionary)d(k) o(e)o(y)i(or)g(as)h(an)f(element)f(of)h(another)f(set.)0 2346 y(Instances)h(of)g FJ(set)g FN(and)f FJ(frozenset)g FN(pro)o(vide)g(the)h(follo)n(wing)e(operations:)657 2572 y FL(Operation)p 1488 2602 4 100 v 517 w(Equi)o(v)o(alent)p 1974 2602 V 99 w(Result)p 188 2605 3525 4 v 698 2675 a FJ(len\()p FK(s)p FJ(\))p 1488 2705 4 100 v 1974 2705 V 1045 w FN(cardinality)h(of)h(set)h FK(s)p 188 2708 3525 4 v 704 2778 a(x)50 b FJ(in)g FK(s)p 1488 2808 4 100 v 1974 2808 V 1052 w FN(test)21 b FK(x)g FN(for)f(membership)e(in)i FK(s)605 2878 y(x)50 b FJ(not)f(in)g FK(s)p 1488 2907 V 1974 2907 V 953 w FN(test)21 b FK(x)g FN(for)f(non-membership)c(in)k FK(s)536 2977 y(s)p FJ(.issubset\()p FK(t)q FJ(\))p 1488 3007 V 463 w FK(s)50 b FJ(<=)f FK(t)p 1974 3007 V 166 w FN(test)21 b(whether)e(e)n(v)o(ery)g(element)h(in)g FK(s)h FN(is)g(in)g FK(t)487 3077 y(s)p FJ(.issuperset\()p FK(t)q FJ(\))p 1488 3107 V 412 w FK(s)50 b FJ(>=)f FK(t)p 1974 3107 V 166 w FN(test)21 b(whether)e(e)n(v)o(ery)g(element)h(in)g FK(t)j FN(is)e(in)f FK(s)p 188 3110 3525 4 v 611 3180 a(s)p FJ(.union\()p FK(t)q FJ(\))p 1488 3210 4 100 v 575 w FK(s)h FN(\227)g FK(t)p 1974 3210 V 203 w FN(ne)n(w)f(set)h(with) g(elements)e(from)h(both)f FK(s)i FN(and)f FK(t)437 3279 y(s)p FJ(.intersection\()p FK(t)q FJ(\))p 1488 3309 V 408 w FK(s)h FN(&)g FK(t)p 1974 3309 V 212 w FN(ne)n(w)f(set)h(with)g (elements)e(common)g(to)h FK(s)h FN(and)f FK(t)487 3379 y(s)p FJ(.difference\()p FK(t)q FJ(\))p 1488 3409 V 477 w FK(s)h FN(-)f FK(t)p 1974 3409 V 231 w FN(ne)n(w)g(set)h(with)g (elements)e(in)i FK(s)g FN(b)n(ut)f(not)g(in)g FK(t)237 3479 y(s)p FJ(.symmetric_difference\()p FK(t)q FJ(\))p 1488 3509 V 227 w FK(s)h FN(\210)f FK(t)p 1974 3509 V 231 w FN(ne)n(w)g(set)h(with)g(elements)e(in)i(either)f FK(s)h FN(or)f FK(t)i FN(b)n(ut)e(not)g(both)648 3578 y FK(s)p FJ(.copy\(\))p 1488 3608 V 1974 3608 V 995 w FN(ne)n(w)g(set)h(with)g(a)f(shallo)n(w)g(cop)o(y)f(of)h FK(s)0 3803 y FN(Note,)55 b(the)49 b(non-operator)44 b(v)o(ersions)k(of)g FJ(union\(\))p FN(,)54 b FJ(intersection\(\))p FN(,)g FJ(difference\(\))p FN(,)f(and)48 b FJ(symmetric_-)0 3903 y(difference\(\))p FN(,)25 b FJ(issubset\(\))p FN(,)g(and)g FJ(issuperset\(\))f FN(methods)h(will)h(accept)f(an)o(y)g(iterable)g (as)h(an)g(ar)o(gument.)38 b(In)25 b(con-)0 4003 y(trast,)18 b(their)g(operator)e(based)h(counterparts)e(require)i(their)g(ar)o (guments)e(to)j(be)g(sets.)25 b(This)18 b(precludes)e(error)n(-prone)e (constructions)i(lik)o(e)0 4102 y FJ(set\('abc'\))48 b(&)i('cbs')19 b FN(in)i(f)o(a)n(v)n(or)f(of)f(the)i(more)e(readable)g FJ(set\('abc'\).intersection\('cbs'\))p FN(.)0 4249 y(Both)24 b FJ(set)f FN(and)h FJ(frozenset)e FN(support)h(set)h(to)g(set)h (comparisons.)33 b(T)-7 b(w)o(o)24 b(sets)h(are)f(equal)f(if)h(and)f (only)g(if)h(e)n(v)o(ery)e(element)h(of)h(each)0 4349 y(set)e(is)h(contained)c(in)j(the)f(other)g(\(each)g(is)h(a)g(subset)g (of)f(the)g(other\).)28 b(A)22 b(set)g(is)g(less)h(than)e(another)f (set)i(if)g(and)f(only)f(if)i(the)f(\002rst)i(set)f(is)g(a)0 4448 y(proper)c(subset)h(of)g(the)h(second)e(set)j(\(is)f(a)g(subset,)f (b)n(ut)h(is)g(not)f(equal\).)24 b(A)c(set)g(is)g(greater)f(than)g (another)f(set)i(if)g(and)f(only)f(if)i(the)g(\002rst)g(set)0 4548 y(is)h(a)g(proper)d(superset)i(of)g(the)g(second)f(set)i(\(is)g(a) g(superset,)e(b)n(ut)i(is)g(not)f(equal\).)0 4695 y(Instances)j(of)g FJ(set)g FN(are)g(compared)e(to)i(instances)g(of)g FJ(frozenset)f FN(based)h(on)g(their)f(members.)33 b(F)o(or)23 b(e)o(xample,)f(`)p FJ(set\('abc'\))0 4795 y(==)49 b(frozenset\('abc'\))p FN(')18 b(returns)h FJ(True)p FN(.)0 4941 y(The)f(subset)h(and)g (equality)e(comparisons)g(do)i(not)f(generalize)g(to)h(a)g(complete)f (ordering)e(function.)23 b(F)o(or)18 b(e)o(xample,)g(an)o(y)g(tw)o(o)h (disjoint)0 5041 y(sets)33 b(are)f(not)g(equal)f(and)g(are)h(not)g (subsets)g(of)g(each)g(other)m(,)h(so)f FK(all)h FN(of)e(the)h(follo)n (wing)f(return)f FJ(False)p FN(:)49 b FK(a)p FJ(<)p FK(b)p FN(,)34 b FK(a)p FJ(==)p FK(b)p FN(,)g(or)d FK(a)p FJ(>)p FK(b)p FN(.)0 5141 y(Accordingly)-5 b(,)17 b(sets)k(do)f(not)g (implement)f(the)h FJ(__cmp__)g FN(method.)0 5288 y(Since)k(sets)i (only)d(de\002ne)h(partial)g(ordering)f(\(subset)h(relationships\),)f (the)i(output)e(of)h(the)g FJ(list.sort\(\))f FN(method)g(is)j (unde\002ned)0 5387 y(for)20 b(lists)h(of)f(sets.)p 0 5549 3901 4 v 0 5649 a FI(36)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 37 49 TeXDict begin 37 48 bop 0 83 a FN(Set)21 b(elements)f(are)g(lik)o(e)g (dictionary)f(k)o(e)o(ys;)h(the)o(y)f(need)h(to)g(de\002ne)g(both)f FJ(__hash__)g FN(and)h FJ(__eq__)g FN(methods.)0 230 y(Binary)33 b(operations)f(that)i(mix)f FJ(set)g FN(instances)h(with)g FJ(frozenset)e FN(return)g(the)i(type)f(of)g(the)h(\002rst)g(operand.) 63 b(F)o(or)33 b(e)o(xample:)0 330 y(`)p FJ(frozenset\('ab'\))47 b(|)i(set\('bc'\))p FN(')19 b(returns)g(an)h(instance)g(of)g FJ(frozenset)p FN(.)0 476 y(The)g(follo)n(wing)e(table)j(lists)g (operations)e(a)n(v)n(ailable)g(for)h FJ(set)g FN(that)h(do)e(not)h (apply)f(to)i(immutable)e(instances)h(of)g FJ(frozenset)p FN(:)643 784 y FL(Operation)p 1649 814 4 100 v 692 w(Equi)o(v)o(alent)p 2135 814 V 99 w(Result)p 0 818 4719 4 v 573 887 a FK(s)p FJ(.update\()p FK(t)q FJ(\))p 1649 917 4 100 v 701 w FK(s)h FN(\227=)f FK(t)p 2135 917 V 180 w FN(update)f(set)i FK(s)p FN(,)g(adding)e(elements)h(from)f FK(t)249 987 y(s)p FJ(.intersection_update\()p FK(t)q FJ(\))p 1649 1017 V 384 w FK(s)i FN(&=)f FK(t)p 2135 1017 V 189 w FN(update)f(set)i FK(s)p FN(,)g(k)o(eeping)e(only)g(elements)h(found)f (in)h(both)f FK(s)i FN(and)f FK(t)299 1087 y(s)p FJ (.difference_update\()p FK(t)q FJ(\))p 1649 1116 V 452 w FK(s)h FN(-=)f FK(t)p 2135 1116 V 208 w FN(update)f(set)i FK(s)p FN(,)g(remo)o(ving)d(elements)i(found)e(in)j FK(t)50 1186 y(s)p FJ(.symmetric_difference_update\()p FK(t)q FJ(\))p 1649 1216 V 201 w FK(s)g FN(\210=)f FK(t)p 2135 1216 V 208 w FN(update)f(set)i FK(s)p FN(,)g(k)o(eeping)e(only)g (elements)h(found)f(in)h(either)g FK(s)h FN(or)f FK(t)i FN(b)n(ut)e(not)g(in)g(both)p 0 1219 4719 4 v 641 1289 a FK(s)p FJ(.add\()p FK(x)p FJ(\))p 1649 1319 4 100 v 2135 1319 V 1176 w FN(add)g(element)f FK(x)i FN(to)g(set)g FK(s)567 1389 y(s)p FJ(.remove\()p FK(x)p FJ(\))p 1649 1419 V 2135 1419 V 1100 w FN(remo)o(v)o(e)d FK(x)j FN(from)e(set)i FK(s)p FN(;)h(raises)e FJ(KeyError)g FN(if)g(not)g(present)542 1488 y FK(s)p FJ(.discard\()p FK(x)p FJ(\))p 1649 1518 V 2135 1518 V 1075 w FN(remo)o(v)o(es)f FK(x)i FN(from)e(set)i FK(s)g FN(if)f(present)660 1588 y FK(s)p FJ(.pop\(\))p 1649 1618 V 2135 1618 V 1194 w FN(remo)o(v)o(e)e(and)i(return)f(an)h (arbitrary)f(element)g(from)h FK(s)p FN(;)h(raises)g FJ(KeyError)e FN(if)h(empty)610 1688 y FK(s)p FJ(.clear\(\))p 1649 1717 V 2135 1717 V 1144 w FN(remo)o(v)o(e)e(all)j(elements)f(from) f(set)i FK(s)0 1913 y FN(Note,)d(the)g(non-operator)c(v)o(ersions)j(of) h(the)g FJ(update\(\))p FN(,)f FJ(intersection_update\(\))p FN(,)e FJ(difference_update\(\))p FN(,)g(and)0 2012 y FJ(symmetric_difference_update\(\))g FN(methods)k(will)i(accept)f(an)o (y)g(iterable)f(as)i(an)f(ar)o(gument.)0 2159 y(The)g(design)f(of)h (the)g(set)h(types)g(w)o(as)g(based)e(on)h(lessons)h(learned)e(from)g (the)h FJ(sets)g FN(module.)0 2306 y FL(See)h(Also:)0 2453 y FN(Comparison)e(to)h(the)g(b)n(uilt-in)g(set)h(types)208 2553 y(Dif)n(ferences)d(between)i(the)g FJ(sets)g FN(module)f(and)h (the)g(b)n(uilt-in)f(set)i(types.)0 2880 y FE(3.8)121 b(Mapping)34 b(T)-14 b(ypes)34 b(\227)f Fx(dict)0 3113 y FN(A)21 b FK(mapping)d FN(object)i(maps)h(immutable)e(v)n(alues)h(to) g(arbitrary)f(objects.)26 b(Mappings)19 b(are)h(mutable)f(objects.)26 b(There)19 b(is)j(currently)c(only)0 3212 y(one)24 b(standard)g (mapping)f(type,)j(the)f FK(dictionary)p FN(.)38 b(A)25 b(dictionary')-5 b(s)24 b(k)o(e)o(ys)g(are)h(almost)g(arbitrary)f(v)n (alues.)38 b(Only)25 b(v)n(alues)f(containing)0 3312 y(lists,)h(dictionaries)d(or)h(other)f(mutable)g(types)h(\(that)g(are)g (compared)e(by)i(v)n(alue)f(rather)g(than)h(by)g(object)f(identity\))g (may)h(not)g(be)g(used)0 3412 y(as)g(k)o(e)o(ys.)32 b(Numeric)21 b(types)h(used)h(for)f(k)o(e)o(ys)g(obe)o(y)f(the)h(normal)g(rules)g (for)g(numeric)f(comparison:)28 b(if)23 b(tw)o(o)f(numbers)f(compare)g (equal)0 3511 y(\(such)f(as)g FJ(1)h FN(and)f FJ(1.0)p FN(\))g(then)f(the)o(y)h(can)g(be)g(used)g(interchangeably)d(to)j(inde) o(x)f(the)h(same)h(dictionary)d(entry)-5 b(.)0 3658 y(Dictionaries)41 b(are)g(created)f(by)h(placing)f(a)i(comma-separated)c(list)k(of)f FK(k)o(e)n(y)p FJ(:)99 b FK(value)40 b FN(pairs)i(within)f(braces,)k (for)c(e)o(xample:)0 3758 y FJ({'jack':)98 b(4098,)49 b('sjoerd':)98 b(4127})20 b FN(or)g FJ({4098:)98 b('jack',)49 b(4127:)98 b('sjoerd'})p FN(.)0 3905 y(The)22 b(follo)n(wing)f (operations)g(are)i(de\002ned)e(on)h(mappings)f(\(where)h FK(a)g FN(and)g FK(b)h FN(are)f(mappings,)g FK(k)i FN(is)g(a)f(k)o(e)o (y)-5 b(,)22 b(and)f FK(v)i FN(and)f FK(x)i FN(are)e(arbitrary)0 4004 y(objects\):)p 0 5549 3901 4 v 0 5649 a FI(3.8.)52 b(Mapping)25 b(T)-10 b(ypes)22 b(\227)h FJ(dict)2731 b FI(37)p eop end %%Page: 38 50 TeXDict begin 38 49 bop 403 70 a FL(Operation)p 1169 100 4 100 v 451 w(Result)p 3891 100 V 2535 w(Notes)p 0 103 4269 4 v 440 173 a FJ(len\()p FK(a)p FJ(\))p 1169 203 4 100 v 488 w FN(the)21 b(number)d(of)i(items)h(in)f FK(a)p 3891 203 V 496 272 a(a)p FJ([)p FK(k)q FJ(])p 1169 302 V 544 w FN(the)h(item)f(of)g FK(a)g FN(with)h(k)o(e)o(y)e FK(k)p 3891 302 V 1935 w FN(\(1\),)g(\(10\))402 372 y FK(a)p FJ([)p FK(k)q FJ(])50 b(=)f FK(v)p 1169 402 V 452 w FN(set)21 b FK(a)p FJ([)p FK(k)q FJ(])g FN(to)f FK(v)p 3891 402 V 396 472 a FJ(del)49 b FK(a)p FJ([)p FK(k)q FJ(])p 1169 501 V 445 w FN(remo)o(v)o(e)19 b FK(a)p FJ([)p FK(k)q FJ(])h FN(from)f FK(a)p 3891 501 V 2120 w FN(\(1\))365 571 y FK(a)p FJ(.clear\(\))p 1169 601 V 413 w FN(remo)o(v)o(e)g(all)h(items)h(from)e FJ(a)p 3891 601 V 390 671 a FK(a)p FJ(.copy\(\))p 1169 701 V 438 w FN(a)i(\(shallo)n(w\))e(cop)o(y)h(of)g FJ(a)p 3891 701 V 446 770 a FK(k)51 b FJ(in)e FK(a)p 1169 800 V 495 w FJ(True)20 b FN(if)h FK(a)f FN(has)h(a)f(k)o(e)o(y)g FK(k)q FN(,)h(else)f FJ(False)p 3891 800 V 1651 w FN(\(2\))346 870 y FK(k)51 b FJ(not)f(in)f FK(a)p 1169 900 V 395 w FN(Equi)n(v)n(alent)19 b(to)h FJ(not)g FK(k)i FN(in)f FK(a)p 3891 900 V 1993 w FN(\(2\))296 970 y FK(a)p FJ(.has_key\()p FK(k)q FJ(\))p 1169 1000 V 344 w FN(Equi)n(v)n(alent)e(to)h FK(k)i FJ(in)f FK(a)p FN(,)f(use)g(that)g(form)f(in)i(ne)n(w)f(code)p 3891 1000 V 365 1069 a FK(a)p FJ(.items\(\))p 1169 1099 V 413 w FN(a)h(cop)o(y)e(of)h FK(a)p FN(')-5 b(s)21 b(list)g(of)f(\()p FK(k)o(e)n(y)p FN(,)g FK(value)p FN(\))f(pairs)p 3891 1099 V 1586 w(\(3\))390 1169 y FK(a)p FJ(.keys\(\))p 1169 1199 V 438 w FN(a)i(cop)o(y)e(of)h FK(a)p FN(')-5 b(s)21 b(list)g(of)f(k)o(e)o(ys)p 3891 1199 V 2002 w(\(3\))274 1279 y FK(a)p FJ(.update\()p FC([)p FK(b)12 b FC(])p FJ(\))p 1169 1309 4 110 v 320 w FN(updates)20 b FK(a)g FN(with)g(k)o(e)o(y/v)n(alue)f(pairs)h(from)f FK(b)p FN(,)h(o)o(v)o(erwriting)e(e)o(xisting)h(k)o(e)o(ys,)h(returns)f FJ(None)p 3891 1309 V 189 w FN(\(9\))50 1388 y FK(a)p FJ(.fromkeys\()p FK(seq)p FC([)p FJ(,)47 b FK(value)12 b FC(])p FJ(\))p 1169 1418 V 97 w FN(Creates)21 b(a)g(ne)n(w)f (dictionary)e(with)j(k)o(e)o(ys)e(from)h FK(seq)g FN(and)g(v)n(alues)f (set)i(to)g FK(value)p 3891 1418 V 566 w FN(\(7\))340 1488 y FK(a)p FJ(.values\(\))p 1169 1518 4 100 v 388 w FN(a)g(cop)o(y)e(of)h FK(a)p FN(')-5 b(s)21 b(list)g(of)f(v)n(alues)p 3891 1518 V 1942 w(\(3\))282 1598 y FK(a)p FJ(.get\()p FK(k)q FC([)p FJ(,)48 b FK(x)12 b FC(])p FJ(\))p 1169 1628 4 110 v 331 w FK(a)p FJ([)p FK(k)q FJ(])21 b FN(if)f FK(k)51 b FJ(in)f FK(a)p FN(,)20 b(else)g FK(x)p 3891 1628 V 2033 w FN(\(4\))108 1708 y FK(a)p FJ(.setdefault\()p FK(k)q FC([)p FJ(,)47 b FK(x)12 b FC(])p FJ(\))p 1169 1737 V 156 w FK(a)p FJ([)p FK(k)q FJ(])21 b FN(if)f FK(k)51 b FJ(in)f FK(a)p FN(,)20 b(else)g FK(x)h FN(\(also)g(setting)f(it\))p 3891 1737 V 1513 w(\(5\))282 1817 y FK(a)p FJ(.pop\()p FK(k)q FC([)p FJ(,)48 b FK(x)12 b FC(])p FJ(\))p 1169 1847 V 331 w FK(a)p FJ([)p FK(k)q FJ(])21 b FN(if)f FK(k)51 b FJ(in)f FK(a)p FN(,)20 b(else)g FK(x)h FN(\(and)f(remo)o(v)o(e)e(k\)) p 3891 1847 V 1506 w(\(8\))315 1917 y FK(a)p FJ(.popitem\(\))p 1169 1947 4 100 v 363 w FN(remo)o(v)o(e)h(and)g(return)g(an)h (arbitrary)f(\()p FK(k)o(e)n(y)p FN(,)g FK(value)p FN(\))h(pair)p 3891 1947 V 1244 w(\(6\))266 2017 y FK(a)p FJ(.iteritems\(\))p 1169 2046 V 312 w FN(return)f(an)i(iterator)e(o)o(v)o(er)g(\()p FK(k)o(e)n(y)p FN(,)g FK(value)p FN(\))h(pairs)p 3891 2046 V 1431 w(\(2\),)f(\(3\))291 2116 y FK(a)p FJ(.iterkeys\(\))p 1169 2146 V 337 w FN(return)g(an)i(iterator)e(o)o(v)o(er)g(the)h (mapping')-5 b(s)19 b(k)o(e)o(ys)p 3891 2146 V 1358 w(\(2\),)g(\(3\)) 241 2216 y FK(a)p FJ(.itervalues\(\))p 1169 2246 V 287 w FN(return)g(an)i(iterator)e(o)o(v)o(er)g(the)h(mapping')-5 b(s)19 b(v)n(alues)p 3891 2246 V 1298 w(\(2\),)g(\(3\))0 2440 y(Notes:)0 2653 y FL(\(1\))40 b FN(Raises)22 b(a)e FJ(KeyError)g FN(e)o(xception)e(if)i FK(k)j FN(is)e(not)f(in)g(the)g (map.)0 2819 y FL(\(2\))40 b FN(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 2985 y FL(\(3\))40 b FN(K)n(e)o(ys)31 b(and)g(v)n(alues)g(are)g(listed) h(in)g(an)f(arbitrary)f(order)g(which)h(is)h(non-random,)e(v)n(aries)h (across)h(Python)e(implementations,)208 3085 y(and)k(depends)f(on)h (the)g(dictionary')-5 b(s)34 b(history)f(of)i(insertions)f(and)g (deletions.)67 b(If)34 b FJ(items\(\))p FN(,)j FJ(keys\(\))p FN(,)h FJ(values\(\))p FN(,)208 3184 y FJ(iteritems\(\))p FN(,)48 b FJ(iterkeys\(\))p FN(,)i(and)44 b FJ(itervalues\(\))e FN(are)j(called)f(with)h(no)f(interv)o(ening)e(modi\002cations)h(to)208 3284 y(the)c(dictionary)-5 b(,)41 b(the)e(lists)i(will)f(directly)e (correspond.)79 b(This)39 b(allo)n(ws)h(the)f(creation)f(of)h FJ(\()p FK(value)p FJ(,)48 b FK(k)o(e)n(y)p FJ(\))39 b FN(pairs)g(using)208 3384 y FJ(zip\(\))p FN(:)22 b(`)p FJ(pairs)49 b(=)h(zip\()p FK(a)p FJ(.values\(\),)c FK(a)p FJ(.keys\(\)\))p FN('.)22 b(The)16 b(same)g(relationship)f(holds)h(for) g(the)g FJ(iterkeys\(\))208 3483 y FN(and)35 b FJ(itervalues\(\))f FN(methods:)56 b(`)p FJ(pairs)48 b(=)i(zip\()p FK(a)p FJ(.itervalues\(\),)c FK(a)p FJ(.iterkeys\(\)\))p FN(')33 b(pro)o(vides)i(the)208 3583 y(same)c(v)n(alue)f(for)g FJ(pairs)p FN(.)57 b(Another)29 b(w)o(ay)i(to)g(create)g(the)g(same)g (list)h(is)g(`)p FJ(pairs)48 b(=)i([\(v,)f(k\))g(for)h(\(k,)f(v\))g(in) 208 3682 y FK(a)p FJ(.iteritems\(\)])p FN('.)0 3849 y FL(\(4\))40 b FN(Ne)n(v)o(er)21 b(raises)g(an)g(e)o(xception)f(if)h FK(k)i FN(is)f(not)f(in)g(the)g(map,)g(instead)g(it)h(returns)e FK(x)p FN(.)28 b FK(x)22 b FN(is)g(optional;)e(when)h FK(x)h FN(is)g(not)f(pro)o(vided)d(and)j FK(k)i FN(is)208 3948 y(not)c(in)i(the)f(map,)f FJ(None)h FN(is)i(returned.)0 4114 y FL(\(5\))40 b FJ(setdefault\(\))20 b FN(is)i(lik)o(e)g FJ(get\(\))p FN(,)f(e)o(xcept)f(that)h(if)h FK(k)h FN(is)f(missing,)f FK(x)h FN(is)h(both)d(returned)g(and)g(inserted)h(into)g(the)g (dictionary)f(as)208 4214 y(the)g(v)n(alue)f(of)h FK(k)q FN(.)26 b FK(x)21 b FN(def)o(aults)f(to)g FJ(None)p FN(.)0 4380 y FL(\(6\))40 b FJ(popitem\(\))22 b FN(is)h(useful)g(to)f (destructi)n(v)o(ely)f(iterate)i(o)o(v)o(er)e(a)i(dictionary)-5 b(,)21 b(as)j(often)d(used)i(in)g(set)g(algorithms.)31 b(If)23 b(the)f(dictionary)208 4480 y(is)f(empty)-5 b(,)18 b(calling)i FJ(popitem\(\))f FN(raises)i(a)g FJ(KeyError)p FN(.)0 4646 y FL(\(7\))40 b FJ(fromkeys\(\))19 b FN(is)i(a)g(class)g (method)e(that)h(returns)g(a)g(ne)n(w)g(dictionary)-5 b(.)23 b FK(value)c FN(def)o(aults)h(to)h FJ(None)p FN(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4812 y FL(\(8\))40 b FJ(pop\(\))20 b FN(raises)h(a)g FJ(KeyError)e FN(when)g(no)h(def)o (ault)g(v)n(alue)f(is)i(gi)n(v)o(en)e(and)h(the)g(k)o(e)o(y)g(is)h(not) f(found.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4978 y FL(\(9\))40 b FJ(update\(\))20 b FN(accepts)h(either)f(another)g (mapping)e(object)j(or)f(an)h(iterable)f(of)h(k)o(e)o(y/v)n(alue)e (pairs)h(\(as)i(a)f(tuple)f(or)h(other)f(iterable)g(of)208 5077 y(length)26 b(tw)o(o\).)48 b(If)27 b(k)o(e)o(yw)o(ord)f(ar)o (guments)g(are)h(speci\002ed,)i(the)f(mapping)e(is)i(then)g(is)g (updated)e(with)i(those)g(k)o(e)o(y/v)n(alue)e(pairs:)208 5177 y(`)p FJ(d.update\(red=1,)46 b(blue=2\))p FN('.)129 b(Changed)32 b(in)i(v)o(ersion)e(2.4:)h(Allo)n(wed)f(the)i(ar)o(gument) d(to)i(be)h(an)f(iterable)g(of)208 5277 y(k)o(e)o(y/v)n(alue)18 b(pairs)i(and)g(allo)n(wed)f(k)o(e)o(yw)o(ord)g(ar)o(guments.)p 0 5549 3901 4 v 0 5649 a FI(38)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 39 51 TeXDict begin 39 50 bop 0 83 a FL(\(10\))40 b FN(If)25 b(a)g(subclass)g(of)g(dict)f(de\002nes)h(a)g(method)f FJ(__missing__)p FN(,)g(if)h(the)g(k)o(e)o(y)f FK(k)j FN(is)f(not)e(present,)i(the)e FK(a)p FN([)p FK(k)q FN(])h(operation)e (calls)i(that)208 183 y(method)20 b(with)j(the)f(k)o(e)o(y)g FK(k)i FN(as)f(ar)o(gument.)29 b(The)22 b FK(a)p FN([)p FK(k)q FN(])g(operation)e(then)i(returns)f(or)h(raises)h(whate)n(v)o (er)e(is)i(returned)e(or)h(raised)g(by)208 282 y(the)e FJ(__missing__)p FN(\()p FK(k)q FN(\))f(call)i(if)g(the)g(k)o(e)o(y)f (is)i(not)e(present.)26 b(No)21 b(other)e(operations)h(or)g(methods)g (in)m(v)n(ok)o(e)f FJ(__missing__)p FN(\(\).)208 382 y(If)27 b FJ(__missing__)e FN(is)j(not)f(de\002ned,)h FJ(KeyError)e FN(is)i(raised.)46 b FJ(__missing__)26 b FN(must)h(be)g(a)h(method;)h(it)f(cannot)e(be)i(an)208 482 y(instance)19 b(v)n(ariable.)24 b(F)o(or)c(an)g(e)o(xample,)f(see)h FJ(collections)p FN(.)p FJ(defaultdict)p FN(.)47 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 809 y FE(3.9)121 b(File)33 b(Objects)0 1042 y FN(File)d(objects)e(are)h(implemented)e(using)i(C') -5 b(s)30 b FJ(stdio)e FN(package)g(and)g(can)h(be)g(created)f(with)h (the)g(b)n(uilt-in)f(constructor)f FJ(file\(\))0 1141 y FN(described)f(in)i(section)g(2.1,)g(\223Built-in)g(Functions.)-6 b(\224)1562 1111 y FF(6)1641 1141 y FN(File)29 b(objects)e(are)h(also)g (returned)d(by)j(some)f(other)g(b)n(uilt-in)g(functions)f(and)0 1241 y(methods,)19 b(such)h(as)h FJ(os.popen\(\))e FN(and)g FJ(os.fdopen\(\))g FN(and)h(the)g FJ(makefile\(\))f FN(method)f(of)i (sock)o(et)g(objects.)0 1388 y(When)f(a)g(\002le)g(operation)e(f)o (ails)j(for)e(an)g(I/O-related)g(reason,)g(the)h(e)o(xception)e FJ(IOError)h FN(is)h(raised.)25 b(This)19 b(includes)f(situations)g (where)0 1488 y(the)i(operation)f(is)i(not)f(de\002ned)f(for)g(some)h (reason,)f(lik)o(e)i FJ(seek\(\))f FN(on)f(a)i(tty)f(de)n(vice)g(or)g (writing)f(a)i(\002le)g(opened)d(for)i(reading.)0 1634 y(Files)h(ha)n(v)o(e)f(the)g(follo)n(wing)f(methods:)0 1781 y FD(close)p FJ(\(\))208 1881 y FN(Close)24 b(the)f(\002le.)36 b(A)24 b(closed)f(\002le)h(cannot)e(be)i(read)f(or)g(written)g(an)o(y)g (more.)34 b(An)o(y)22 b(operation)g(which)h(requires)f(that)i(the)f (\002le)i(be)208 1981 y(open)19 b(will)i(raise)f(a)h FJ(ValueError)e FN(after)g(the)i(\002le)g(has)f(been)f(closed.)25 b(Calling)20 b FJ(close\(\))g FN(more)f(than)h(once)f(is)i(allo)n(wed.) 208 2113 y(As)31 b(of)f(Python)g(2.5,)i(you)e(can)g(a)n(v)n(oid)g(ha)n (ving)g(to)h(call)g(this)g(method)e(e)o(xplicitly)h(if)g(you)g(use)h (the)g FJ(with)f FN(statement.)56 b(F)o(or)208 2213 y(e)o(xample,)18 b(the)i(follo)n(wing)f(code)g(will)i(automatically)e(close)h FJ(f)h FN(when)f(the)g FJ(with)g FN(block)f(is)i(e)o(xited:)444 2437 y FA(from)44 b(__future__)f(import)h(with_statement)444 2620 y(with)g(open\("hello.txt"\))e(as)i(f:)623 2711 y(for)g(line)h(in)f(f:)802 2802 y(print)g(line)208 2992 y FN(In)19 b(older)h(v)o(ersions)f(of)h(Python,)f(you)g(w)o(ould)h(ha)n (v)o(e)f(needed)g(to)h(do)g(this)h(to)f(get)g(the)h(same)f(ef)n(fect:) 444 3216 y FA(f)44 b(=)h(open\("hello.txt"\))444 3307 y(try:)623 3399 y(for)f(line)h(in)f(f:)802 3490 y(print)g(line)444 3581 y(finally:)623 3673 y(f.close\(\))208 3862 y FL(Note:)39 b FN(Not)28 b(all)h(\223\002le-lik)o(e\224)f(types)f(in)h(Python)f (support)g(use)h(as)h(a)f(conte)o(xt)f(manager)f(for)h(the)h FJ(with)g FN(statement.)48 b(If)28 b(your)208 3962 y(code)20 b(is)i(intended)e(to)i(w)o(ork)e(with)i(an)o(y)e(\002le-lik)o(e)h (object,)g(you)g(can)g(use)g(the)g FJ(closing\(\))g FN(function)e(in)j (the)f FJ(contextlib)208 4061 y FN(module)d(instead)i(of)g(using)g(the) g(object)g(directly)-5 b(.)23 b(See)e(section)f(26.5)f(for)h(details.)0 4208 y FD(flush)p FJ(\(\))208 4308 y FN(Flush)g(the)g(internal)f(b)n (uf)n(fer)m(,)g(lik)o(e)h FJ(stdio)p FN(')-5 b(s)20 b FJ(fflush\(\))p FN(.)k(This)d(may)e(be)i(a)f(no-op)f(on)g(some)h (\002le-lik)o(e)h(objects.)0 4455 y FD(fileno)p FJ(\(\))208 4554 y FN(Return)d(the)g(inte)o(ger)f(\223\002le)i(descriptor\224)e (that)i(is)g(used)f(by)g(the)h(underlying)c(implementation)i(to)h (request)g(I/O)h(operations)e(from)208 4654 y(the)25 b(operating)e(system.)40 b(This)26 b(can)f(be)g(useful)f(for)h(other)m (,)g(lo)n(wer)g(le)n(v)o(el)f(interf)o(aces)h(that)g(use)h(\002le)g (descriptors,)f(such)g(as)h(the)208 4754 y FJ(fcntl)f FN(module)g(or)g FJ(os.read\(\))g FN(and)h(friends.)41 b FL(Note:)36 b FN(File-lik)o(e)26 b(objects)f(which)h(do)f(not)h(ha)n (v)o(e)f(a)h(real)g(\002le)h(descriptor)208 4853 y(should)19 b FK(not)h FN(pro)o(vide)e(this)i(method!)0 5000 y FD(isatty)p FJ(\(\))208 5100 y FN(Return)15 b FJ(True)g FN(if)h(the)f(\002le)i(is)f (connected)e(to)h(a)h(tty\(-lik)o(e\))f(de)n(vice,)g(else)h FJ(False)p FN(.)23 b FL(Note:)f FN(If)16 b(a)g(\002le-lik)o(e)f(object) g(is)i(not)e(associated)208 5199 y(with)20 b(a)h(real)f(\002le,)g(this) h(method)e(should)g FK(not)h FN(be)g(implemented.)p 0 5270 1560 4 v 90 5326 a FB(6)120 5349 y Fz(file\(\))15 b FH(is)i(ne)n(w)h(in)f(Python)h(2.2.)i(The)d(older)h(b)o(uilt-in)h Fz(open\(\))d FH(is)h(an)g(alias)h(for)f Fz(file\(\))p FH(.)p 0 5549 3901 4 v 0 5649 a FI(3.9.)52 b(File)24 b(Objects)3179 b(39)p eop end %%Page: 40 52 TeXDict begin 40 51 bop 0 83 a FD(next)p FJ(\(\))208 183 y FN(A)23 b(\002le)h(object)f(is)h(its)g(o)n(wn)e(iterator)m(,)h (for)f(e)o(xample)g FJ(iter\()p FK(f)12 b FJ(\))23 b FN(returns)f FK(f)36 b FN(\(unless)23 b FK(f)36 b FN(is)24 b(closed\).)33 b(When)23 b(a)g(\002le)h(is)g(used)f(as)h(an)208 282 y(iterator)m(,)d(typically)g(in)h(a)h FJ(for)f FN(loop)f(\(for)g(e) o(xample,)g FJ(for)49 b(line)g(in)h(f:)99 b(print)49 b(line)p FN(\),)21 b(the)h FJ(next\(\))g FN(method)f(is)208 382 y(called)i(repeatedly)-5 b(.)33 b(This)24 b(method)e(returns)h(the) h(ne)o(xt)f(input)g(line,)h(or)g(raises)g FJ(StopIteration)e FN(when)j FH(E)t(O)t(F)h FN(is)e(hit)g(when)208 482 y(the)17 b(\002le)i(is)g(open)e(for)g(reading)f(\(beha)n(vior)g(is)j (unde\002ned)d(when)h(the)h(\002le)h(is)f(open)f(for)g(writing\).)24 b(In)17 b(order)g(to)h(mak)o(e)f(a)i FJ(for)e FN(loop)208 581 y(the)22 b(most)f(ef)n(\002cient)h(w)o(ay)g(of)g(looping)e(o)o(v)o (er)g(the)i(lines)h(of)e(a)i(\002le)f(\(a)g(v)o(ery)f(common)f (operation\),)g(the)i FJ(next\(\))f FN(method)g(uses)208 681 y(a)g(hidden)f(read-ahead)e(b)n(uf)n(fer)-5 b(.)27 b(As)22 b(a)f(consequence)e(of)h(using)h(a)g(read-ahead)e(b)n(uf)n(fer) m(,)g(combining)g FJ(next\(\))i FN(with)g(other)f(\002le)208 780 y(methods)d(\(lik)o(e)h FJ(readline\(\))p FN(\))f(does)h(not)g(w)o (ork)g(right.)23 b(Ho)n(we)n(v)o(er)m(,)17 b(using)h FJ(seek\(\))g FN(to)g(reposition)f(the)h(\002le)h(to)g(an)f(absolute) 208 880 y(position)h(will)i(\003ush)f(the)g(read-ahead)e(b)n(uf)n(fer) -5 b(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1027 y FD(read)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 1127 y FN(Read)21 b(at)g(most)g FK(size)h FN(bytes)f(from)f(the)h (\002le)h(\(less)g(if)f(the)g(read)f(hits)k FH(E)t(O)t(F)f FN(before)d(obtaining)f FK(size)j FN(bytes\).)27 b(If)21 b(the)g FK(size)h FN(ar)o(gument)208 1226 y(is)j(ne)o(gati)n(v)o(e)c (or)j(omitted,)g(read)g(all)g(data)g(until)i FH(E)t(O)t(F)h FN(is)d(reached.)36 b(The)23 b(bytes)h(are)g(returned)e(as)j(a)g (string)e(object.)36 b(An)24 b(empty)208 1326 y(string)d(is)h(returned) e(when)j FH(E)t(O)t(F)h FN(is)e(encountered)d(immediately)-5 b(.)27 b(\(F)o(or)21 b(certain)g(\002les,)h(lik)o(e)g(ttys,)g(it)g(mak) o(es)g(sense)f(to)h(continue)208 1425 y(reading)16 b(after)h(an)j FH(E)t(O)t(F)g FN(is)e(hit.\))24 b(Note)18 b(that)g(this)g(method)e (may)i(call)g(the)g(underlying)d(C)j(function)e FJ(fread\(\))h FN(more)g(than)g(once)208 1525 y(in)24 b(an)g(ef)n(fort)g(to)g(acquire) f(as)i(close)g(to)f FK(size)i FN(bytes)e(as)h(possible.)37 b(Also)25 b(note)f(that)g(when)g(in)g(non-blocking)d(mode,)j(less)i (data)208 1625 y(than)19 b(what)h(w)o(as)h(requested)e(may)h(be)g (returned,)e(e)n(v)o(en)i(if)g(no)g FK(size)h FN(parameter)e(w)o(as)i (gi)n(v)o(en.)0 1772 y FD(readline)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 1871 y FN(Read)22 b(one)h(entire)f(line)h(from)e (the)i(\002le.)33 b(A)24 b(trailing)e(ne)n(wline)g(character)f(is)j(k)o (ept)e(in)h(the)g(string)f(\(b)n(ut)h(may)f(be)h(absent)f(when)g(a)208 1971 y(\002le)d(ends)f(with)h(an)g(incomplete)e(line\).)1331 1941 y FF(7)1389 1971 y FN(If)h(the)h FK(size)h FN(ar)o(gument)c(is)k (present)e(and)g(non-ne)o(gati)n(v)o(e,)d(it)k(is)h(a)f(maximum)e(byte) i(count)208 2070 y(\(including)f(the)i(trailing)f(ne)n(wline\))h(and)f (an)h(incomplete)f(line)h(may)g(be)g(returned.)j(An)e(empty)e(string)h (is)h(returned)d FK(only)i FN(when)210 2170 y FH(E)t(O)t(F)g FN(is)g(encountered)c(immediately)-5 b(.)22 b FL(Note:)i FN(Unlik)o(e)18 b FJ(stdio)p FN(')-5 b(s)19 b FJ(fgets\(\))p FN(,)f(the)g(returned)f(string)h(contains)g(null)h(characters)208 2270 y(\()p FJ('\\0')p FN(\))g(if)h(the)o(y)g(occurred)e(in)i(the)h (input.)0 2417 y FD(readlines)p FJ(\()p FC([)p FK(sizehint)13 b FC(])p FJ(\))208 2516 y FN(Read)28 b(until)h FH(E)t(O)t(F)h FN(using)e FJ(readline\(\))e FN(and)i(return)e(a)j(list)g(containing)d (the)i(lines)g(thus)g(read.)47 b(If)28 b(the)g(optional)e FK(sizehint)208 2616 y FN(ar)o(gument)20 b(is)k(present,)f(instead)f (of)h(reading)f(up)g(to)j FH(E)t(O)t(F)r FN(,)f(whole)e(lines)i (totalling)e(approximately)e FK(sizehint)25 b FN(bytes)e(\(possibly)208 2715 y(after)f(rounding)e(up)i(to)h(an)f(internal)g(b)n(uf)n(fer)f (size\))i(are)g(read.)31 b(Objects)23 b(implementing)d(a)j(\002le-lik)o (e)g(interf)o(ace)f(may)g(choose)f(to)208 2815 y(ignore)d FK(sizehint)k FN(if)f(it)g(cannot)e(be)h(implemented,)e(or)i(cannot)f (be)h(implemented)e(ef)n(\002ciently)-5 b(.)0 2962 y FD(xreadlines)p FJ(\(\))208 3062 y FN(This)24 b(method)f(returns)h(the) h(same)f(thing)g(as)i FJ(iter\(f\))p FN(.)76 b(Ne)n(w)25 b(in)f(v)o(ersion)g(2.1.)76 b FL(Depr)o(ecated)23 b(since)j(r)o(elease) e(2.3.)37 b FN(Use)208 3161 y(`)p FJ(for)48 b FK(line)i FJ(in)f FK(\002le)p FN(')20 b(instead.)0 3308 y FD(seek)p FJ(\()p FK(of)o(fset)q FC([)p FK(,)f(whence)12 b FC(])p FJ(\))208 3408 y FN(Set)33 b(the)g(\002le')-5 b(s)34 b(current)e(position,)j(lik)o(e)f FJ(stdio)p FN(')-5 b(s)33 b FJ(fseek\(\))p FN(.)63 b(The)32 b FK(whence)h FN(ar)o(gument)e(is)j(optional)d(and)i(def)o(aults)f(to)208 3507 y FJ(os.SEEK_SET)c FN(or)h FJ(0)h FN(\(absolute)e(\002le)i (positioning\);)i(other)d(v)n(alues)g(are)g FJ(os.SEEK_CUR)f FN(or)h FJ(1)h FN(\(seek)f(relati)n(v)o(e)g(to)h(the)208 3607 y(current)21 b(position\))h(and)g FJ(os.SEEK_END)g FN(or)g FJ(2)i FN(\(seek)e(relati)n(v)o(e)h(to)g(the)g(\002le')-5 b(s)24 b(end\).)32 b(There)22 b(is)i(no)e(return)g(v)n(alue.)33 b(Note)22 b(that)208 3707 y(if)j(the)h(\002le)g(is)h(opened)d(for)h (appending)e(\(mode)i FJ('a')g FN(or)h FJ('a+')p FN(\),)g(an)o(y)f FJ(seek\(\))g FN(operations)f(will)i(be)g(undone)d(at)k(the)e(ne)o(xt) 208 3806 y(write.)44 b(If)26 b(the)h(\002le)g(is)g(only)f(opened)f(for) h(writing)g(in)g(append)f(mode)h(\(mode)f FJ('a')p FN(\),)i(this)g (method)f(is)h(essentially)g(a)g(no-op,)208 3906 y(b)n(ut)22 b(it)h(remains)e(useful)h(for)f(\002les)i(opened)e(in)h(append)e(mode)i (with)g(reading)e(enabled)h(\(mode)g FJ('a+')p FN(\).)30 b(If)22 b(the)g(\002le)h(is)g(opened)208 4005 y(in)f(te)o(xt)g(mode)g (\(without)f FJ('b')p FN(\),)i(only)e(of)n(fsets)i(returned)d(by)i FJ(tell\(\))g FN(are)h(le)o(gal.)31 b(Use)23 b(of)f(other)g(of)n(fsets) g(causes)h(unde\002ned)208 4105 y(beha)n(vior)-5 b(.)208 4238 y(Note)20 b(that)g(not)g(all)h(\002le)f(objects)g(are)h(seekable.) 0 4385 y FD(tell)p FJ(\(\))208 4484 y FN(Return)e(the)i(\002le')-5 b(s)21 b(current)e(position,)g(lik)o(e)h FJ(stdio)p FN(')-5 b(s)20 b FJ(ftell\(\))p FN(.)208 4617 y FL(Note:)k FN(On)19 b(W)m(indo)n(ws,)g FJ(tell\(\))g FN(can)g(return)g(ille)o(gal)g(v)n (alues)g(\(after)g(an)g FJ(fgets\(\))p FN(\))g(when)g(reading)f (\002les)i(with)i(U)t FH(N)t(I)t(X)r FN(-style)208 4717 y(line-endings.)h(Use)d(binary)f(mode)g(\()p FJ('rb')p FN(\))h(to)g(circumv)o(ent)e(this)j(problem.)0 4864 y FD(truncate)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 4963 y FN(T)m(runcate)29 b(the)h(\002le')-5 b(s)32 b(size.)56 b(If)31 b(the)f(optional)g FK(size)h FN(ar)o(gument)d(is)k(present,)g (the)e(\002le)i(is)f(truncated)e(to)i(\(at)f(most\))h(that)f(size.)208 5063 y(The)23 b(size)i(def)o(aults)e(to)h(the)g(current)e(position.)35 b(The)24 b(current)e(\002le)j(position)e(is)i(not)e(changed.)34 b(Note)24 b(that)g(if)g(a)g(speci\002ed)g(size)p 0 5134 1560 4 v 90 5189 a FB(7)120 5212 y FH(The)18 b(adv)n(antage)k(of)c(lea) o(ving)i(the)g(ne)n(wline)g(on)f(is)f(that)i(returning)g(an)f(empty)g (string)h(is)e(then)i(an)e(unambiguous)k Fq(E)t(O)t(F)d FH(indication.)28 b(It)19 b(is)f(also)h(possible)h(\(in)f(cases)0 5291 y(where)g(it)g(might)g(matter)m(,)g(for)g(e)o(xample,)g(if)g(you)f (w)o(ant)h(to)g(mak)o(e)g(an)f(e)o(xact)i(cop)o(y)g(of)e(a)g(\002le)h (while)g(scanning)h(its)f(lines\))g(to)f(tell)i(whether)g(the)f(last)g (line)g(of)f(a)h(\002le)f(ended)0 5370 y(in)f(a)g(ne)n(wline)j(or)d (not)g(\(yes)g(this)h(happens!\).)p 0 5549 3901 4 v 0 5649 a FI(40)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 41 53 TeXDict begin 41 52 bop 208 83 a FN(e)o(xceeds)25 b(the)h(\002le')-5 b(s)28 b(current)d(size,)j(the)f(result)f(is)h(platform-dependent:)33 b(possibilities)27 b(include)f(that)g(the)g(\002le)i(may)d(remain)208 183 y(unchanged,)d(increase)i(to)g(the)h(speci\002ed)f(size)h(as)g(if)f (zero-\002lled,)g(or)g(increase)g(to)h(the)f(speci\002ed)g(size)h(with) f(unde\002ned)f(ne)n(w)208 282 y(content.)g(A)-6 b(v)n(ailability:)25 b(W)m(indo)n(ws,)19 b(man)o(y)i(U)t FH(N)t(I)t(X)i FN(v)n(ariants.)0 429 y FD(write)p FJ(\()p FK(str)r FJ(\))208 529 y FN(Write)f(a)g (string)f(to)h(the)f(\002le.)30 b(There)21 b(is)h(no)f(return)g(v)n (alue.)28 b(Due)21 b(to)h(b)n(uf)n(fering,)d(the)j(string)f(may)g(not)g (actually)g(sho)n(w)h(up)f(in)h(the)208 628 y(\002le)e(until)g(the)h FJ(flush\(\))e FN(or)h FJ(close\(\))f FN(method)g(is)i(called.)0 775 y FD(writelines)p FJ(\()p FK(sequence)p FJ(\))208 875 y FN(Write)e(a)g(sequence)f(of)g(strings)h(to)g(the)g(\002le.)25 b(The)18 b(sequence)g(can)g(be)h(an)o(y)f(iterable)g(object)h (producing)d(strings,)i(typically)g(a)h(list)208 975 y(of)k(strings.)35 b(There)22 b(is)j(no)e(return)f(v)n(alue.)34 b(\(The)23 b(name)g(is)i(intended)d(to)h(match)g FJ(readlines\(\))p FN(;)h FJ(writelines\(\))e FN(does)208 1074 y(not)d(add)h(line)g (separators.\))0 1221 y(Files)28 b(support)e(the)h(iterator)f (protocol.)43 b(Each)27 b(iteration)f(returns)g(the)h(same)g(result)g (as)h FK(\002le)p FJ(.readline\(\))p FN(,)e(and)h(iteration)f(ends)0 1321 y(when)20 b(the)g FJ(readline\(\))f FN(method)f(returns)i(an)g (empty)f(string.)0 1468 y(File)k(objects)f(also)g(of)n(fer)f(a)h (number)e(of)i(other)f(interesting)g(attrib)n(utes.)31 b(These)21 b(are)h(not)g(required)e(for)i(\002le-lik)o(e)g(objects,)g (b)n(ut)g(should)0 1567 y(be)e(implemented)e(if)j(the)o(y)e(mak)o(e)h (sense)h(for)e(the)h(particular)f(object.)0 1714 y FD(closed)208 1814 y FN(bool)i(indicating)g(the)i(current)e(state)i(of)f(the)g (\002le)h(object.)31 b(This)23 b(is)g(a)g(read-only)d(attrib)n(ute;)j (the)g FJ(close\(\))f FN(method)f(changes)208 1913 y(the)f(v)n(alue.)k (It)c(may)g(not)g(be)g(a)n(v)n(ailable)g(on)g(all)g(\002le-lik)o(e)h (objects.)0 2060 y FD(encoding)208 2160 y FN(The)c(encoding)f(that)i (this)h(\002le)f(uses.)25 b(When)18 b(Unicode)f(strings)h(are)g (written)f(to)h(a)h(\002le,)g(the)o(y)e(will)i(be)f(con)m(v)o(erted)d (to)j(byte)g(strings)208 2259 y(using)23 b(this)h(encoding.)33 b(In)23 b(addition,)g(when)g(the)h(\002le)g(is)g(connected)e(to)i(a)g (terminal,)f(the)h(attrib)n(ute)f(gi)n(v)o(es)g(the)h(encoding)d(that) 208 2359 y(the)d(terminal)g(is)i(lik)o(ely)e(to)h(use)g(\(that)f (information)f(might)h(be)g(incorrect)g(if)g(the)h(user)g(has)g (miscon\002gured)d(the)j(terminal\).)k(The)208 2459 y(attrib)n(ute)c (is)i(read-only)c(and)j(may)f(not)g(be)h(present)f(on)h(all)g (\002le-lik)o(e)g(objects.)25 b(It)20 b(may)f(also)h(be)g FJ(None)p FN(,)f(in)h(which)g(case)g(the)g(\002le)208 2558 y(uses)g(the)g(system)h(def)o(ault)e(encoding)f(for)i(con)m(v)o (erting)d(Unicode)i(strings.)208 2691 y(Ne)n(w)h(in)g(v)o(ersion)f (2.3.)0 2838 y FD(mode)208 2938 y FN(The)k(I/O)g(mode)g(for)g(the)g (\002le.)35 b(If)24 b(the)f(\002le)h(w)o(as)g(created)f(using)g(the)g FJ(open\(\))g FN(b)n(uilt-in)g(function,)f(this)i(will)g(be)g(the)f(v)n (alue)g(of)208 3037 y(the)d FK(mode)f FN(parameter)-5 b(.)24 b(This)d(is)g(a)f(read-only)e(attrib)n(ute)i(and)g(may)f(not)h (be)g(present)g(on)g(all)g(\002le-lik)o(e)h(objects.)0 3184 y FD(name)208 3284 y FN(If)27 b(the)h(\002le)g(object)f(w)o(as)i (created)e(using)g FJ(open\(\))p FN(,)i(the)f(name)f(of)g(the)h (\002le.)48 b(Otherwise,)29 b(some)f(string)f(that)h(indicates)g(the) 208 3383 y(source)h(of)g(the)h(\002le)g(object,)h(of)f(the)g(form)e(`)p FJ(<...)o(>)p FN('.)54 b(This)30 b(is)g(a)g(read-only)e(attrib)n(ute)h (and)g(may)h(not)f(be)h(present)f(on)g(all)208 3483 y(\002le-lik)o(e)20 b(objects.)0 3630 y FD(newlines)208 3729 y FN(If)e(Python)g(w)o(as)h(b) n(uilt)g(with)g(the)f FL(--with-uni)o(v)o(ersal-newlines)g FN(option)g(to)h FL(con\002gur)o(e)e FN(\(the)i(def)o(ault\))e(this)j (read-only)c(attrib)n(ute)208 3829 y(e)o(xists,)23 b(and)f(for)h (\002les)g(opened)e(in)i(uni)n(v)o(ersal)f(ne)n(wline)g(read)g(mode)g (it)i(k)o(eeps)e(track)g(of)h(the)g(types)f(of)h(ne)n(wlines)f (encountered)208 3929 y(while)17 b(reading)f(the)h(\002le.)24 b(The)17 b(v)n(alues)g(it)h(can)f(tak)o(e)g(are)g FJ('\\r')p FN(,)h FJ('\\n')p FN(,)f FJ('\\r\\n')p FN(,)g FJ(None)g FN(\(unkno)n(wn,)e(no)h(ne)n(wlines)h(read)g(yet\))208 4028 y(or)h(a)h(tuple)f(containing)f(all)i(the)g(ne)n(wline)f(types)g (seen,)h(to)g(indicate)f(that)g(multiple)g(ne)n(wline)g(con)m(v)o (entions)e(were)j(encountered.)208 4128 y(F)o(or)g(\002les)j(not)d (opened)g(in)h(uni)n(v)o(ersal)f(ne)n(wline)h(read)f(mode)g(the)i(v)n (alue)e(of)h(this)h(attrib)n(ute)f(will)h(be)f FJ(None)p FN(.)0 4275 y FD(softspace)208 4374 y FN(Boolean)15 b(that)i(indicates) f(whether)f(a)i(space)f(character)f(needs)h(to)g(be)h(printed)e(before) g(another)f(v)n(alue)i(when)g(using)g(the)g FJ(print)208 4474 y FN(statement.)39 b(Classes)27 b(that)e(are)g(trying)f(to)i (simulate)f(a)g(\002le)h(object)f(should)f(also)h(ha)n(v)o(e)g(a)g (writable)g FJ(softspace)f FN(attrib)n(ute,)208 4574 y(which)e(should)g(be)i(initialized)f(to)g(zero.)33 b(This)24 b(will)g(be)f(automatic)f(for)h(most)g(classes)i(implemented)c(in)i (Python)f(\(care)h(may)208 4673 y(be)k(needed)e(for)i(objects)f(that)i (o)o(v)o(erride)c(attrib)n(ute)j(access\);)k(types)c(implemented)e(in)i (C)h(will)g(ha)n(v)o(e)e(to)h(pro)o(vide)e(a)j(writable)208 4773 y FJ(softspace)j FN(attrib)n(ute.)61 b FL(Note:)49 b FN(This)32 b(attrib)n(ute)g(is)h(not)f(used)g(to)h(control)e(the)h FJ(print)g FN(statement,)j(b)n(ut)e(to)f(allo)n(w)h(the)208 4873 y(implementation)18 b(of)h FJ(print)h FN(to)h(k)o(eep)e(track)h (of)g(its)h(internal)e(state.)p 0 5549 3901 4 v 0 5649 a FI(3.9.)52 b(File)24 b(Objects)3179 b(41)p eop end %%Page: 42 54 TeXDict begin 42 53 bop 0 88 a FE(3.10)121 b(Conte)l(xt)36 b(Manager)f(T)-14 b(ypes)0 321 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.) 0 468 y(Python')-5 b(s)16 b FJ(with)g FN(statement)g(supports)g(the)g (concept)f(of)i(a)g(runtime)e(conte)o(xt)g(de\002ned)h(by)g(a)h(conte)o (xt)e(manager)-5 b(.)22 b(This)17 b(is)g(implemented)0 567 y(using)31 b(tw)o(o)i(separate)e(methods)g(that)h(allo)n(w)g(user)n (-de\002ned)e(classes)k(to)e(de\002ne)f(a)i(runtime)d(conte)o(xt)h (that)h(is)h(entered)e(before)g(the)0 667 y(statement)20 b(body)f(is)i(e)o(x)o(ecuted)d(and)i(e)o(xited)f(when)h(the)g (statement)g(ends.)0 814 y(The)g FK(conte)n(xt)g(mana)o(g)o(ement)f(pr) l(otocol)h FN(consists)h(of)f(a)h(pair)f(of)g(methods)g(that)g(need)g (to)h(be)f(pro)o(vided)e(for)i(a)h(conte)o(xt)e(manager)g(object)0 914 y(to)h(de\002ne)g(a)h(runtime)e(conte)o(xt:)0 1060 y FD(__enter__)p FJ(\(\))208 1160 y FN(Enter)27 b(the)i(runtime)e (conte)o(xt)g(and)h(return)g(either)g(this)h(object)f(or)g(another)f (object)h(related)g(to)h(the)f(runtime)f(conte)o(xt.)49 b(The)208 1260 y(v)n(alue)21 b(returned)e(by)j(this)g(method)e(is)j (bound)c(to)j(the)g(identi\002er)f(in)h(the)f FJ(as)h FN(clause)g(of)f FJ(with)h FN(statements)g(using)f(this)h(conte)o(xt) 208 1359 y(manager)-5 b(.)208 1492 y(An)15 b(e)o(xample)g(of)g(a)h (conte)o(xt)e(manager)h(that)g(returns)g(itself)h(is)h(a)f(\002le)g (object.)23 b(File)17 b(objects)e(return)g(themselv)o(es)g(from)p 3564 1492 25 4 v 3594 1492 V 74 w(enter)p 3791 1492 V 3820 1492 V 59 w(\(\))208 1592 y(to)20 b(allo)n(w)g FJ(open\(\))g FN(to)g(be)g(used)g(as)h(the)f(conte)o(xt)f(e)o(xpression)g(in)h(a)h FJ(with)f FN(statement.)208 1725 y(An)80 b(e)o(xample)g(of)g(a)h(conte) o(xt)f(manager)f(that)h(returns)g(a)h(related)f(object)h(is)g(the)g (one)f(returned)f(by)208 1824 y FJ(decimal.Context.get_manager\(\))p FN(.)f(These)39 b(managers)f(set)j(the)e(acti)n(v)o(e)g(decimal)g (conte)o(xt)f(to)i(a)g(cop)o(y)f(of)208 1924 y(the)24 b(original)g(decimal)g(conte)o(xt)g(and)g(then)h(return)e(the)i(cop)o (y)-5 b(.)38 b(This)25 b(allo)n(ws)g(changes)f(to)h(be)g(made)f(to)h (the)g(current)e(decimal)208 2023 y(conte)o(xt)18 b(in)j(the)f(body)f (of)h(the)g FJ(with)g FN(statement)g(without)f(af)n(fecting)g(code)h (outside)f(the)h FJ(with)g FN(statement.)0 2170 y FD(__exit__)p FJ(\()p FK(e)n(xc)p 564 2170 V 28 w(type)o(,)g(e)n(xc)p 880 2170 V 30 w(val,)g(e)n(xc)p 1162 2170 V 30 w(tb)p FJ(\))208 2270 y FN(Exit)15 b(the)g(runtime)g(conte)o(xt)f(and)h (return)f(a)i(Boolean)f(\003ag)g(indicating)f(if)i(an)o(y)f(e)o (xpection)e(that)j(occurred)d(should)i(be)g(suppressed.)208 2370 y(If)21 b(an)g(e)o(xception)f(occurred)f(while)j(e)o(x)o(ecuting)d (the)i(body)g(of)g(the)g FJ(with)g FN(statement,)h(the)f(ar)o(guments)f (contain)g(the)h(e)o(xception)208 2469 y(type,)e(v)n(alue)h(and)f (traceback)g(information.)j(Otherwise,)e(all)h(three)f(ar)o(guments)e (are)i FJ(None)p FN(.)208 2602 y(Returning)g(a)i(true)f(v)n(alue)f (from)h(this)h(method)e(will)i(cause)g(the)f FJ(with)g FN(statement)h(to)f(suppress)g(the)h(e)o(xception)d(and)i(continue)208 2702 y(e)o(x)o(ecution)j(with)j(the)g(statement)g(immediately)e(follo)n (wing)g(the)i FJ(with)g FN(statement.)44 b(Otherwise)27 b(the)g(e)o(xception)e(continues)208 2801 y(propagating)e(after)k(this) h(method)e(has)h(\002nished)g(e)o(x)o(ecuting.)44 b(Exceptions)25 b(that)j(occur)e(during)f(e)o(x)o(ecution)g(of)i(this)h(method)208 2901 y(will)20 b(replace)g(an)o(y)f(e)o(xception)g(that)h(occurred)e (in)i(the)h(body)d(of)i(the)h FJ(with)f FN(statement.)208 3034 y(The)g(e)o(xception)g(passed)h(in)g(should)f(ne)n(v)o(er)g(be)h (reraised)g(e)o(xplicitly)f(-)i(instead,)f(this)g(method)f(should)g (return)h(a)g(f)o(alse)h(v)n(alue)e(to)208 3133 y(indicate)d(that)i (the)f(method)f(completed)g(successfully)h(and)g(does)g(not)g(w)o(ant)g (to)h(suppress)f(the)g(raised)g(e)o(xception.)23 b(This)18 b(allo)n(ws)208 3233 y(conte)o(xt)g(management)g(code)i(\(such)f(as)i FJ(contextlib.nested)p FN(\))c(to)k(easily)f(detect)g(whether)f(or)h (not)g(an)g FJ(__exit__\(\))208 3333 y FN(method)e(has)j(actually)e(f)o (ailed.)0 3480 y(Python)31 b(de\002nes)h(se)n(v)o(eral)g(conte)o(xt)e (managers)h(to)i(support)e(easy)h(thread)f(synchronisation,)h(prompt)f (closure)g(of)h(\002les)h(or)f(other)0 3579 y(objects,)19 b(and)f(simpler)h(manipulation)e(of)i(the)g(acti)n(v)o(e)g(decimal)f (arithmetic)h(conte)o(xt.)k(The)c(speci\002c)g(types)g(are)g(not)g (treated)g(specially)0 3679 y(be)o(yond)f(their)i(implementation)e(of)i (the)g(conte)o(xt)f(management)f(protocol.)0 3826 y(Python')-5 b(s)24 b(generators)f(and)h(the)h FJ(contextlib.contextfactory)20 b FN(decorator)j(pro)o(vide)f(a)j(con)m(v)o(enient)d(w)o(ay)j(to)g (implement)0 3925 y(these)g(protocols.)36 b(If)24 b(a)h(generator)d (function)h(is)i(decorated)e(with)h(the)h FJ(contextlib.contextfactory) 20 b FN(decorator)m(,)j(it)i(will)0 4025 y(return)g(a)h(conte)o(xt)e (manager)h(implementing)e(the)j(necessary)f FJ(__enter__\(\))g FN(and)g FJ(__exit__\(\))f FN(methods,)i(rather)f(than)h(the)0 4125 y(iterator)20 b(produced)d(by)j(an)g(undecorated)e(generator)g (function.)0 4271 y(Note)g(that)f(there)g(is)i(no)e(speci\002c)h(slot)g (for)f(an)o(y)f(of)i(these)f(methods)g(in)h(the)f(type)g(structure)g (for)g(Python)f(objects)h(in)h(the)g(Python/C)e(API.)0 4371 y(Extension)g(types)i(w)o(anting)f(to)g(de\002ne)g(these)h (methods)f(must)h(pro)o(vide)d(them)i(as)i(a)f(normal)e(Python)h (accessible)g(method.)23 b(Compared)0 4471 y(to)d(the)h(o)o(v)o(erhead) c(of)j(setting)g(up)g(the)g(runtime)f(conte)o(xt,)g(the)h(o)o(v)o (erhead)e(of)i(a)g(single)g(class)h(dictionary)e(lookup)f(is)j(ne)o (gligible.)0 4798 y FE(3.11)121 b(Other)34 b(Built-in)f(T)-14 b(ypes)0 5031 y FN(The)20 b(interpreter)e(supports)i(se)n(v)o(eral)f (other)g(kinds)h(of)g(objects.)25 b(Most)20 b(of)g(these)g(support)f (only)h(one)f(or)h(tw)o(o)h(operations.)p 0 5549 3901 4 v 0 5649 a FI(42)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 43 55 TeXDict begin 43 54 bop 0 83 a Fv(3.11.1)101 b(Modules)0 286 y FN(The)20 b(only)g(special)h(operation)e(on)i(a)g(module)e(is)j (attrib)n(ute)e(access:)27 b FK(m)p FJ(.)p FK(name)p FN(,)20 b(where)g FK(m)i FN(is)f(a)h(module)d(and)h FK(name)g FN(accesses)i(a)f(name)0 386 y(de\002ned)i(in)i FK(m)p FN(')-5 b(s)25 b(symbol)e(table.)37 b(Module)23 b(attrib)n(utes)h(can)g (be)g(assigned)g(to.)37 b(\(Note)24 b(that)h(the)f FJ(import)g FN(statement)g(is)h(not,)f(strictly)0 485 y(speaking,)c(an)i(operation) d(on)i(a)h(module)e(object;)i FJ(import)49 b FK(foo)21 b FN(does)g(not)g(require)g(a)g(module)g(object)f(named)h FK(foo)g FN(to)h(e)o(xist,)f(rather)0 585 y(it)g(requires)e(an)h(\(e)o (xternal\))e FK(de\002nition)h FN(for)g(a)i(module)e(named)g FK(foo)h FN(some)n(where.\))0 732 y(A)32 b(special)f(member)g(of)g(e)n (v)o(ery)f(module)g(is)i FJ(__dict__)p FN(.)58 b(This)32 b(is)g(the)f(dictionary)f(containing)f(the)j(module')-5 b(s)30 b(symbol)h(table.)0 831 y(Modifying)20 b(this)j(dictionary)e (will)i(actually)f(change)g(the)g(module')-5 b(s)22 b(symbol)f(table,)i (b)n(ut)g(direct)f(assignment)f(to)i(the)g FJ(__dict__-)0 931 y FN(attrib)n(ute)g(is)g(not)g(possible)g(\(you)e(can)i(write)g FK(m)p FJ(.__dict__['a'])47 b(=)j(1)p FN(,)24 b(which)e(de\002nes)h FK(m)p FJ(.a)g FN(to)g(be)g FJ(1)p FN(,)g(b)n(ut)g(you)f(can')o(t)g (write)0 1031 y FK(m)p FJ(.__dict__)48 b(=)i({})p FN(\).)24 b(Modifying)18 b FJ(__dict__)i FN(directly)f(is)i(not)f(recommended.)0 1177 y(Modules)26 b(b)n(uilt)h(into)f(the)h(interpreter)e(are)i (written)f(lik)o(e)h(this:)39 b FJ()p FN(.)43 b(If)27 b(loaded)e(from)h(a)h(\002le,)0 1277 y(the)o(y)19 b(are)i(written)f(as)g FJ()p FN(.)0 1562 y Fv(3.11.2)101 b(Classes)28 b(and)g(Class)g(Instances)0 1765 y FN(See)21 b(chapters)e(3)h(and)g(7)g(of)g(the)g FK(Python)f(Refer)m(ence)h (Manual)f FN(for)g(these.)0 2050 y Fv(3.11.3)101 b(Functions)0 2253 y FN(Function)42 b(objects)h(are)h(created)e(by)h(function)f (de\002nitions.)94 b(The)43 b(only)f(operation)g(on)h(a)h(function)d (object)i(is)h(to)g(call)g(it:)0 2352 y FK(func)p FJ(\()p FK(ar)m(gument-list)q FJ(\))p FN(.)0 2499 y(There)21 b(are)h(really)f(tw)o(o)h(\003a)n(v)n(ors)g(of)g(function)e(objects:)28 b(b)n(uilt-in)21 b(functions)g(and)g(user)n(-de\002ned)f(functions.)28 b(Both)22 b(support)f(the)g(same)0 2599 y(operation)d(\(to)i(call)h (the)f(function\),)e(b)n(ut)i(the)g(implementation)e(is)k(dif)n (ferent,)c(hence)h(the)h(dif)n(ferent)f(object)h(types.)0 2746 y(See)h(the)f FK(Python)f(Refer)m(ence)g(Manual)g FN(for)h(more)f(information.)0 3031 y Fv(3.11.4)101 b(Methods)0 3233 y FN(Methods)26 b(are)g(functions)f(that)i(are)f(called)g(using)g (the)h(attrib)n(ute)f(notation.)42 b(There)26 b(are)g(tw)o(o)h(\003a)n (v)n(ors:)38 b(b)n(uilt-in)26 b(methods)f(\(such)h(as)0 3333 y FJ(append\(\))19 b FN(on)h(lists\))h(and)f(class)h(instance)f (methods.)k(Built-in)c(methods)f(are)h(described)f(with)h(the)h(types)f (that)g(support)f(them.)0 3480 y(The)26 b(implementation)e(adds)i(tw)o (o)h(special)f(read-only)e(attrib)n(utes)i(to)h(class)g(instance)f (methods:)36 b FK(m)p FJ(.im_self)26 b FN(is)h(the)f(object)g(on)0 3580 y(which)e(the)g(method)f(operates,)i(and)e FK(m)p FJ(.im_func)h FN(is)h(the)f(function)f(implementing)f(the)j(method.)36 b(Calling)24 b FK(m)p FJ(\()p FK(ar)m(g-1)p FJ(,)48 b FK(ar)m(g-2)p FJ(,)0 3679 y FN(.)12 b(.)g(.)g FJ(,)50 b FK(ar)m(g-n)p FJ(\))19 b FN(is)i(completely)e(equi)n(v)n(alent)g(to)h (calling)g FK(m)p FJ(.im_func\()p FK(m)p FJ(.im_self,)46 b FK(ar)m(g-1)p FJ(,)i FK(ar)m(g-2)p FJ(,)g FN(.)12 b(.)g(.)g FJ(,)50 b FK(ar)m(g-n)p FJ(\))p FN(.)0 3826 y(Class)18 b(instance)e(methods)f(are)h(either)g FK(bound)f FN(or)h FK(unbound)p FN(,)e(referring)g(to)i(whether)g(the)g(method)f(w)o(as)i (accessed)g(through)d(an)i(instance)0 3926 y(or)26 b(a)g(class,)i (respecti)n(v)o(ely)-5 b(.)40 b(When)26 b(a)g(method)e(is)j(unbound,)d (its)j FJ(im_self)e FN(attrib)n(ute)h(will)h(be)e FJ(None)h FN(and)f(if)i(called,)f(an)g(e)o(xplicit)0 4025 y FJ(self)d FN(object)h(must)f(be)h(passed)f(as)i(the)e(\002rst)i(ar)o(gument.)32 b(In)24 b(this)g(case,)g FJ(self)g FN(must)g(be)f(an)h(instance)f(of)g (the)h(unbound)d(method')-5 b(s)0 4125 y(class)21 b(\(or)f(a)g (subclass)h(of)f(that)g(class\),)h(otherwise)e(a)i FJ(TypeError)e FN(is)i(raised.)0 4272 y(Lik)o(e)32 b(function)f(objects,)j(methods)d (objects)h(support)f(getting)h(arbitrary)e(attrib)n(utes.)61 b(Ho)n(we)n(v)o(er)m(,)33 b(since)g(method)e(attrib)n(utes)h(are)0 4371 y(actually)c(stored)g(on)g(the)h(underlying)d(function)g(object)j (\()p FJ(meth.im_func)p FN(\),)f(setting)g(method)f(attrib)n(utes)i(on) f(either)g(bound)f(or)0 4471 y(unbound)18 b(methods)i(is)j(disallo)n (wed.)k(Attempting)20 b(to)h(set)h(a)g(method)e(attrib)n(ute)g(results) i(in)f(a)h FJ(TypeError)e FN(being)g(raised.)28 b(In)21 b(order)0 4571 y(to)f(set)h(a)g(method)e(attrib)n(ute,)g(you)h(need)f (to)h(e)o(xplicitly)g(set)h(it)g(on)e(the)i(underlying)c(function)h (object:)236 4809 y FA(class)44 b(C:)416 4900 y(def)g(method\(self\):) 595 4992 y(pass)236 5174 y(c)h(=)g(C\(\))236 5266 y (c.method.im_func.whoami)c(=)k('my)f(name)g(is)h(c')p 0 5549 3901 4 v 0 5649 a FI(3.11.)52 b(Other)23 b(Built-in)i(T)-10 b(ypes)2847 b(43)p eop end %%Page: 44 56 TeXDict begin 44 55 bop 0 83 a FN(See)21 b(the)f FK(Python)f(Refer)m (ence)g(Manual)g FN(for)h(more)f(information.)0 368 y Fv(3.11.5)101 b(Code)28 b(Objects)0 571 y FN(Code)20 b(objects)h(are)f(used)g(by)h(the)f(implementation)f(to)h(represent)g (\223pseudo-compiled\224)c(e)o(x)o(ecutable)j(Python)g(code)h(such)h (as)g(a)g(func-)0 670 y(tion)27 b(body)-5 b(.)43 b(The)o(y)25 b(dif)n(fer)h(from)g(function)f(objects)i(because)f(the)o(y)g(don')o(t) f(contain)h(a)h(reference)e(to)i(their)g(global)f(e)o(x)o(ecution)f(en) m(vi-)0 770 y(ronment.)k(Code)22 b(objects)g(are)g(returned)e(by)i(the) g(b)n(uilt-in)g FJ(compile\(\))f FN(function)f(and)i(can)g(be)g(e)o (xtracted)e(from)h(function)g(objects)0 870 y(through)d(their)i FJ(func_code)f FN(attrib)n(ute.)0 1017 y(A)27 b(code)g(object)f(can)h (be)f(e)o(x)o(ecuted)f(or)i(e)n(v)n(aluated)e(by)i(passing)f(it)i (\(instead)e(of)h(a)g(source)f(string\))h(to)g(the)g FJ(exec)f FN(statement)h(or)g(the)0 1116 y(b)n(uilt-in)20 b FJ(eval\(\))f FN(function.)0 1263 y(See)i(the)f FK(Python)f(Refer)m (ence)g(Manual)g FN(for)h(more)f(information.)0 1548 y Fv(3.11.6)101 b(T)-12 b(ype)28 b(Objects)0 1751 y FN(T)-7 b(ype)21 b(objects)g(represent)f(the)i(v)n(arious)e(object)h(types.)28 b(An)22 b(object')-5 b(s)21 b(type)g(is)h(accessed)g(by)f(the)g(b)n (uilt-in)g(function)e FJ(type\(\))p FN(.)28 b(There)0 1851 y(are)20 b(no)g(special)g(operations)f(on)h(types.)k(The)c (standard)f(module)g FJ(types)h FN(de\002nes)g(names)g(for)f(all)i (standard)e(b)n(uilt-in)h(types.)0 1997 y(T)-7 b(ypes)20 b(are)g(written)g(lik)o(e)h(this:)k FJ()p FN(.)0 2282 y Fv(3.11.7)101 b(The)28 b(Null)g(Object)0 2485 y FN(This)f(object)e(is)j(returned)c(by)i(functions)f(that)i(don') o(t)d(e)o(xplicitly)i(return)f(a)i(v)n(alue.)43 b(It)26 b(supports)g(no)g(special)g(operations.)42 b(There)26 b(is)0 2585 y(e)o(xactly)19 b(one)h(null)g(object,)f(named)g FJ(None)h FN(\(a)h(b)n(uilt-in)e(name\).)0 2732 y(It)h(is)i(written)e (as)g FJ(None)p FN(.)0 3017 y Fv(3.11.8)101 b(The)28 b(Ellipsis)h(Object)0 3219 y FN(This)24 b(object)e(is)j(used)e(by)g(e)o (xtended)e(slice)j(notation)e(\(see)i(the)f FK(Python)f(Refer)m(ence)h (Manual)p FN(\).)33 b(It)24 b(supports)e(no)h(special)g(operations.)0 3319 y(There)c(is)i(e)o(xactly)f(one)f(ellipsis)i(object,)f(named)f FJ(Ellipsis)g FN(\(a)h(b)n(uilt-in)g(name\).)0 3466 y(It)g(is)i (written)e(as)g FJ(Ellipsis)p FN(.)0 3751 y Fv(3.11.9)101 b(Boolean)30 b(V)-7 b(alues)0 3954 y FN(Boolean)27 b(v)n(alues)h(are)g (the)g(tw)o(o)h(constant)e(objects)h FJ(False)g FN(and)g FJ(True)p FN(.)48 b(The)o(y)27 b(are)h(used)g(to)h(represent)d(truth)i (v)n(alues)g(\(although)0 4053 y(other)21 b(v)n(alues)g(can)g(also)h (be)g(considered)e(f)o(alse)i(or)f(true\).)28 b(In)22 b(numeric)e(conte)o(xts)h(\(for)f(e)o(xample)g(when)h(used)h(as)g(the)g (ar)o(gument)d(to)j(an)0 4153 y(arithmetic)e(operator\),)e(the)o(y)h (beha)n(v)o(e)h(lik)o(e)g(the)h(inte)o(gers)e(0)i(and)e(1,)i(respecti)n (v)o(ely)-5 b(.)23 b(The)d(b)n(uilt-in)g(function)f FJ(bool\(\))h FN(can)g(be)g(used)g(to)0 4253 y(cast)h(an)o(y)e(v)n(alue)h(to)g(a)h (Boolean,)e(if)h(the)h(v)n(alue)e(can)h(be)g(interpreted)f(as)i(a)f (truth)g(v)n(alue)f(\(see)i(section)f(T)m(ruth)f(V)-9 b(alue)20 b(T)-6 b(esting)20 b(abo)o(v)o(e\).)0 4400 y(The)o(y)f(are)h(written)g(as)h FJ(False)f FN(and)g FJ(True)p FN(,)f(respecti)n(v)o(ely)-5 b(.)0 4684 y Fv(3.11.10)101 b(Inter)r(nal)29 b(Objects)0 4887 y FN(See)24 b(the)g FK(Python)e(Refer)m(ence)h(Manual)g FN(for)g(this)h(information.)33 b(It)24 b(describes)f(stack)h(frame)e(objects,)i(traceback)f(objects,)h (and)f(slice)0 4987 y(objects.)p 0 5549 3901 4 v 0 5649 a FI(44)2853 b(Chapter)23 b(3.)52 b(Built-in)25 b(T)-10 b(ypes)p eop end %%Page: 45 57 TeXDict begin 45 56 bop 0 88 a FE(3.12)121 b(Special)33 b(Attr)r(ib)n(utes)0 321 y FN(The)22 b(implementation)e(adds)i(a)h(fe)n (w)f(special)h(read-only)d(attrib)n(utes)i(to)g(se)n(v)o(eral)g(object) g(types,)g(where)g(the)o(y)f(are)i(rele)n(v)n(ant.)30 b(Some)22 b(of)0 421 y(these)e(are)g(not)g(reported)f(by)h(the)g FJ(dir\(\))g FN(b)n(uilt-in)f(function.)0 567 y FD(__dict__)208 667 y FN(A)h(dictionary)f(or)h(other)f(mapping)f(object)i(used)g(to)g (store)g(an)g(object')-5 b(s)21 b(\(writable\))e(attrib)n(utes.)0 814 y FD(__methods__)208 914 y FL(Depr)o(ecated)28 b(since)i(r)o (elease)f(2.2.)53 b FN(Use)30 b(the)g(b)n(uilt-in)f(function)f FJ(dir\(\))h FN(to)h(get)f(a)h(list)h(of)e(an)h(object')-5 b(s)29 b(attrib)n(utes.)53 b(This)208 1013 y(attrib)n(ute)19 b(is)i(no)f(longer)f(a)n(v)n(ailable.)0 1160 y FD(__members__)208 1260 y FL(Depr)o(ecated)28 b(since)i(r)o(elease)f(2.2.)53 b FN(Use)30 b(the)g(b)n(uilt-in)f(function)f FJ(dir\(\))h FN(to)h(get)f(a)h(list)h(of)e(an)h(object')-5 b(s)29 b(attrib)n(utes.)53 b(This)208 1359 y(attrib)n(ute)19 b(is)i(no)f(longer)f(a)n(v)n(ailable.)0 1506 y FD(__class__)208 1606 y FN(The)g(class)j(to)e(which)g(a)g(class)h(instance)f(belongs.)0 1753 y FD(__bases__)208 1852 y FN(The)f(tuple)h(of)g(base)g(classes)i (of)e(a)g(class)h(object.)k(If)20 b(there)g(are)g(no)f(base)i(classes,) g(this)g(will)f(be)h(an)f(empty)f(tuple.)0 1999 y FD(__name__)208 2099 y FN(The)g(name)h(of)g(the)g(class)h(or)f(type.)p 0 5549 3901 4 v 0 5649 a FI(3.12.)52 b(Special)25 b(Attr)q(ib)n(utes) 2927 b(45)p eop end %%Page: 46 58 TeXDict begin 46 57 bop 0 5549 3901 4 v 0 5649 a FI(46)p eop end %%Page: 47 59 TeXDict begin 47 58 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3561 427 y FG(FOUR)p 0 515 V 2502 978 a FT(Str)s(ing)57 b(Ser)6 b(vices)0 1468 y FN(The)20 b(modules)f(described)g(in)h(this)h(chapter) e(pro)o(vide)f(a)j(wide)f(range)f(of)h(string)g(manipulation)e (operations.)23 b(Here')-5 b(s)21 b(an)f(o)o(v)o(ervie)n(w:)50 1611 y FD(string)746 b FN(Common)19 b(string)h(operations.)50 1711 y FD(re)946 b FN(Re)o(gular)19 b(e)o(xpression)g(search)h(and)f (match)h(operations)f(with)h(a)h(Perl-style)f(e)o(xpression)e(syntax.) 50 1810 y FD(struct)746 b FN(Interpret)18 b(strings)j(as)g(pack)o(ed)e (binary)f(data.)50 1910 y FD(difflib)696 b FN(Helpers)20 b(for)f(computing)f(dif)n(ferences)h(between)g(objects.)50 2010 y FD(StringIO)646 b FN(Read)20 b(and)g(write)g(strings)g(as)h(if)g (the)o(y)e(were)h(\002les.)50 2109 y FD(cStringIO)596 b FN(F)o(aster)20 b(v)o(ersion)f(of)h FJ(StringIO)p FN(,)f(b)n(ut)h (not)g(subclassable.)50 2209 y FD(textwrap)646 b FN(T)-6 b(e)o(xt)20 b(wrapping)e(and)i(\002lling)50 2309 y FD (encodings.utf-8-sig)96 b FN(UTF-8)20 b(codec)f(with)h(BOM)h(signature) 50 2408 y FD(unicodedata)496 b FN(Access)21 b(the)f(Unicode)f (Database.)50 2508 y FD(stringprep)546 b FN(String)20 b(preparation,)d(as)k(per)f(RFC)i(3453)50 2607 y FD(fpformat)646 b FN(General)19 b(\003oating)h(point)f(formatting)g(functions.)0 2792 y(Information)e(on)j(the)g(methods)f(of)h(string)g(objects)g(can)g (be)g(found)f(in)h(section)g(3.6.1,)f(\223String)g(Methods.)-6 b(\224)0 3120 y FE(4.1)121 b Fx(string)31 b FE(\227)i(Common)h(str)r (ing)g(oper)o(ations)0 3353 y FN(The)21 b FJ(string)f FN(module)f(contains)i(a)g(number)e(of)h(useful)h(constants)f(and)h (classes,)g(as)h(well)f(as)h(some)f(deprecated)e(le)o(gac)o(y)g (functions)0 3452 y(that)h(are)g(also)h(a)n(v)n(ailable)f(as)h(methods) e(on)g(strings.)25 b(See)c(the)f(module)f FJ(re)h FN(for)g(string)g (functions)f(based)g(on)h(re)o(gular)f(e)o(xpressions.)0 3737 y Fv(4.1.1)100 b(Str)q(ing)30 b(constants)0 3940 y FN(The)20 b(constants)g(de\002ned)f(in)h(this)h(module)e(are:)0 4087 y FD(ascii_letters)208 4187 y FN(The)29 b(concatenation)e(of)j (the)f FJ(ascii_lowercase)f FN(and)h FJ(ascii_uppercase)e FN(constants)j(described)e(belo)n(w)-5 b(.)52 b(This)208 4286 y(v)n(alue)19 b(is)i(not)f(locale-dependent.)0 4433 y FD(ascii_lowercase)208 4533 y FN(The)d(lo)n(wercase)g(letters)h FJ('abcdefghijklmnopqrstuvwxyz')p FN(.)h(This)f(v)n(alue)f(is)h(not)f (locale-dependent)e(and)i(will)h(not)208 4632 y(change.)0 4779 y FD(ascii_uppercase)208 4879 y FN(The)f(uppercase)g(letters)h FJ('ABCDEFGHIJKLMNOPQRSTUVWXYZ')p FN(.)13 b(This)18 b(v)n(alue)g(is)g (not)g(locale-dependent)d(and)i(will)i(not)208 4979 y(change.)0 5125 y FD(digits)208 5225 y FN(The)g(string)h FJ('0123456789')p FN(.)0 5372 y FD(hexdigits)p 0 5549 3901 4 v 3808 5649 a FI(47)p eop end %%Page: 48 60 TeXDict begin 48 59 bop 208 83 a FN(The)19 b(string)h FJ('0123456789abcdefABCDEF')p FN(.)0 230 y FD(letters)208 330 y FN(The)h(concatenation)e(of)i(the)h(strings)f FJ(lowercase)g FN(and)g FJ(uppercase)f FN(described)h(belo)n(w)-5 b(.)28 b(The)21 b(speci\002c)h(v)n(alue)f(is)h(locale-)208 429 y(dependent,)17 b(and)j(will)h(be)f(updated)f(when)g FJ(locale.setlocale\(\))f FN(is)j(called.)0 576 y FD(lowercase)208 676 y FN(A)37 b(string)f(containing)e(all)j(the)g(characters)e(that)i (are)f(considered)f(lo)n(wercase)h(letters.)74 b(On)37 b(most)f(systems)h(this)g(is)h(the)208 775 y(string)32 b FJ('abcdefghijklmnopqrstuvwxyz')p FN(.)57 b(Do)32 b(not)g(change)f (its)j(de\002nition)d(\227)i(the)f(ef)n(fect)g(on)g(the)h(routines)208 875 y FJ(upper\(\))22 b FN(and)h FJ(swapcase\(\))f FN(is)j (unde\002ned.)32 b(The)23 b(speci\002c)h(v)n(alue)f(is)h (locale-dependent,)d(and)i(will)h(be)f(updated)f(when)208 975 y FJ(locale.setlocale\(\))17 b FN(is)k(called.)0 1121 y FD(octdigits)208 1221 y FN(The)e(string)h FJ('01234567')p FN(.)0 1368 y FD(punctuation)208 1468 y FN(String)f(of)j FH(A)t(S)t(C)t(I)t(I)i FN(characters)19 b(which)h(are)g(considered)e (punctuation)g(characters)h(in)i(the)f(`)p FJ(C)p FN(')g(locale.)0 1614 y FD(printable)208 1714 y FN(String)47 b(of)g(characters)f(which)h (are)h(considered)d(printable.)106 b(This)47 b(is)i(a)f(combination)d (of)i FJ(digits)p FN(,)54 b FJ(letters)p FN(,)208 1814 y FJ(punctuation)p FN(,)18 b(and)i FJ(whitespace)p FN(.)0 1961 y FD(uppercase)208 2060 y FN(A)36 b(string)g(containing)f(all)i (the)f(characters)g(that)g(are)g(considered)f(uppercase)g(letters.)74 b(On)36 b(most)h(systems)f(this)h(is)h(the)208 2160 y(string)c FJ('ABCDEFGHIJKLMNOPQRSTUVWXYZ')p FN(.)c(Do)35 b(not)f(change)g(its)i (de\002nition)e(\227)h(the)g(ef)n(fect)f(on)h(the)g(routines)208 2259 y FJ(lower\(\))22 b FN(and)h FJ(swapcase\(\))f FN(is)j (unde\002ned.)32 b(The)23 b(speci\002c)h(v)n(alue)f(is)h (locale-dependent,)d(and)i(will)h(be)f(updated)f(when)208 2359 y FJ(locale.setlocale\(\))17 b FN(is)k(called.)0 2506 y FD(whitespace)208 2606 y FN(A)h(string)f(containing)e(all)j (characters)f(that)g(are)h(considered)d(whitespace.)28 b(On)22 b(most)f(systems)h(this)g(includes)f(the)h(characters)208 2705 y(space,)e(tab,)g(linefeed,)f(return,)g(formfeed,)f(and)i(v)o (ertical)g(tab)m(.)25 b(Do)c(not)f(change)f(its)i(de\002nition)f(\227)h (the)f(ef)n(fect)g(on)g(the)h(routines)208 2805 y FJ(strip\(\))e FN(and)h FJ(split\(\))f FN(is)i(unde\002ned.)0 3090 y Fv(4.1.2)100 b(T)-12 b(emplate)29 b(str)q(ings)0 3293 y FN(T)-6 b(emplates)19 b(pro)o(vide)e(simpler)i(string)f (substitutions)h(as)h(described)e(in)h(PEP)h(292.)j(Instead)c(of)g(the) g(normal)f(`)p FJ(\045)p FN('-based)f(substitutions,)0 3392 y(T)-6 b(emplates)20 b(support)f(`)p FJ($)p FN('-based)f (substitutions,)i(using)f(the)h(follo)n(wing)f(rules:)125 3622 y FM(\017)41 b FN(`)p FJ($$)p FN(')19 b(is)i(an)f(escape;)h(it)f (is)i(replaced)d(with)h(a)h(single)f(`)p FJ($)p FN('.)125 3788 y FM(\017)41 b FN(`)p FJ($identifier)p FN(')19 b(names)i(a)h (substitution)e(placeholder)f(matching)h(a)i(mapping)e(k)o(e)o(y)g(of)h (\224identi\002er\224.)28 b(By)22 b(def)o(ault,)f(\224iden-)208 3888 y(ti\002er\224)28 b(must)g(spell)g(a)h(Python)e(identi\002er)-5 b(.)48 b(The)27 b(\002rst)i(non-identi\002er)d(character)g(after)i(the) g(`)p FJ($)p FN(')g(character)f(terminates)g(this)208 3987 y(placeholder)18 b(speci\002cation.)125 4153 y FM(\017)41 b FN(`)p FJ(${identifier})p FN(')22 b(is)27 b(equi)n(v)n(alent)c(to)j (`)p FJ($identifier)p FN('.)38 b(It)26 b(is)g(required)e(when)g(v)n (alid)h(identi\002er)g(characters)f(follo)n(w)208 4253 y(the)c(placeholder)e(b)n(ut)i(are)g(not)g(part)g(of)g(the)g (placeholder)m(,)d(such)j(as)h(\224$)p FM(f)p FN(noun)p FM(g)p FN(i\002cation\224.)0 4483 y(An)o(y)e(other)h(appearance)e(of)i (`)p FJ($)p FN(')g(in)g(the)g(string)g(will)h(result)f(in)h(a)f FJ(ValueError)f FN(being)g(raised.)0 4630 y(Ne)n(w)h(in)h(v)o(ersion)e (2.4.)0 4777 y(The)h FJ(string)f FN(module)g(pro)o(vides)g(a)h FJ(Template)g FN(class)h(that)f(implements)f(these)i(rules.)k(The)19 b(methods)g(of)h FJ(Template)g FN(are:)0 4924 y FL(class)h FD(Template)p FJ(\()p FK(template)p FJ(\))208 5023 y FN(The)e(constructor)g(tak)o(es)h(a)h(single)f(ar)o(gument)e(which)h (is)j(the)e(template)f(string.)0 5170 y FD(substitute)p FJ(\()p FK(mapping)p FC([)p FK(,)d(**kws)c FC(])p FJ(\))208 5270 y FN(Performs)19 b(the)i(template)f(substitution,)g(returning)f(a) i(ne)n(w)g(string.)26 b FK(mapping)19 b FN(is)j(an)o(y)e (dictionary-lik)o(e)f(object)h(with)h(k)o(e)o(ys)f(that)208 5369 y(match)e(the)g(placeholders)f(in)i(the)g(template.)24 b(Alternati)n(v)o(ely)-5 b(,)17 b(you)g(can)i(pro)o(vide)e(k)o(e)o(yw)o (ord)g(ar)o(guments,)f(where)i(the)h(k)o(e)o(yw)o(ords)p 0 5549 3901 4 v 0 5649 a FI(48)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 49 61 TeXDict begin 49 60 bop 208 83 a FN(are)18 b(the)h(placeholders.)k (When)18 b(both)g FK(mapping)f FN(and)h FK(kws)i FN(are)f(gi)n(v)o(en)e (and)h(there)g(are)h(duplicates,)f(the)h(placeholders)e(from)g FK(kws)208 183 y FN(tak)o(e)j(precedence.)0 330 y FD(safe_substitute)p FJ(\()p FK(mapping)p FC([)p FK(,)15 b(**kws)d FC(])p FJ(\))208 429 y FN(Lik)o(e)30 b FJ(substitute\(\))p FN(,)h(e)o(xcept)e (that)h(if)h(placeholders)e(are)h(missing)g(from)f FK(mapping)g FN(and)g FK(kws)p FN(,)34 b(instead)c(of)g(raising)g(a)208 529 y FJ(KeyError)f FN(e)o(xception,)j(the)f(original)e(placeholder)g (will)j(appear)d(in)i(the)g(resulting)f(string)h(intact.)57 b(Also,)33 b(unlik)o(e)d(with)208 628 y FJ(substitute\(\))p FN(,)18 b(an)o(y)h(other)h(appearances)e(of)i(the)g(`)p FJ($)p FN(')g(will)h(simply)f(return)f(`)p FJ($)p FN(')h(instead)g(of)f (raising)h FJ(ValueError)p FN(.)208 757 y(While)e(other)f(e)o (xceptions)f(may)h(still)i(occur)m(,)e(this)h(method)e(is)j(called)e (\223safe\224)h(because)f(substitutions)g(al)o(w)o(ays)h(tries)h(to)f (return)e(a)208 857 y(usable)j(string)h(instead)g(of)g(raising)f(an)h (e)o(xception.)j(In)d(another)e(sense,)j FJ(safe_substitute\(\))c FN(may)j(be)f(an)o(ything)f(other)208 956 y(than)23 b(safe,)i(since)f (it)g(will)h(silently)f(ignore)e(malformed)g(templates)h(containing)f (dangling)g(delimiters,)j(unmatched)c(braces,)208 1056 y(or)e(placeholders)g(that)h(are)g(not)g(v)n(alid)g(Python)f (identi\002ers.)0 1203 y FJ(Template)g FN(instances)h(also)h(pro)o (vide)d(one)i(public)f(data)h(attrib)n(ute:)0 1350 y FD(template)208 1449 y FN(This)i(is)i(the)e(object)g(passed)g(to)h(the) f(constructor')-5 b(s)21 b FK(template)h FN(ar)o(gument.)30 b(In)22 b(general,)g(you)f(shouldn')o(t)f(change)h(it,)j(b)n(ut)e (read-)208 1549 y(only)d(access)i(is)g(not)f(enforced.)0 1696 y(Here)g(is)h(an)f(e)o(xample)f(of)h(ho)n(w)g(to)g(use)g(a)h(T)-6 b(emplate:)236 1934 y FA(>>>)45 b(from)f(string)g(import)f(Template)236 2025 y(>>>)i(s)f(=)h(Template\('$who)d(likes)i($what'\))236 2117 y(>>>)h(s.substitute\(who='tim',)c(what='kung)i(pao'\))236 2208 y('tim)h(likes)g(kung)h(pao')236 2299 y(>>>)g(d)f(=)h (dict\(who='tim'\))236 2391 y(>>>)g(Template\('Give)d($who)i ($100'\).substitute\(d\))236 2482 y(Traceback)g(\(most)g(recent)f(call) i(last\):)236 2573 y([...])236 2665 y(ValueError:)e(Invalid)h (placeholder)f(in)h(string:)g(line)g(1,)h(col)f(10)236 2756 y(>>>)h(Template\('$who)d(likes)i($what'\).substitute\(d\))236 2847 y(Traceback)g(\(most)g(recent)f(call)i(last\):)236 2939 y([...])236 3030 y(KeyError:)f('what')236 3121 y(>>>)h (Template\('$who)d(likes)i($what'\).safe_substitute\(d\))236 3213 y('tim)g(likes)g($what')0 3499 y FN(Adv)n(anced)22 b(usage:)31 b(you)23 b(can)g(deri)n(v)o(e)g(subclasses)h(of)f FJ(Template)f FN(to)i(customize)f(the)h(placeholder)d(syntax,)i (delimiter)g(character)m(,)0 3599 y(or)d(the)g(entire)g(re)o(gular)f(e) o(xpression)f(used)i(to)g(parse)g(template)g(strings.)25 b(T)-7 b(o)20 b(do)g(this,)h(you)e(can)h(o)o(v)o(erride)e(these)i (class)h(attrib)n(utes:)125 3809 y FM(\017)41 b FK(delimiter)23 b FN(\226)f(This)g(is)g(the)g(literal)g(string)f(describing)f(a)i (placeholder)d(introducing)g(delimiter)-5 b(.)29 b(The)21 b(def)o(ault)g(v)n(alue)g(`)p FJ($)p FN('.)29 b(Note)208 3908 y(that)c(this)h(should)f FK(not)g FN(be)h(a)g(re)o(gular)e(e)o (xpression,)h(as)i(the)e(implementation)f(will)i(call)g FJ(re.escape\(\))e FN(on)h(this)i(string)e(as)208 4008 y(needed.)125 4166 y FM(\017)41 b FK(idpattern)19 b FN(\226)i(This)f (is)i(the)f(re)o(gular)e(e)o(xpression)g(describing)g(the)h(pattern)g (for)g(non-braced)d(placeholders)i(\(the)h(braces)g(will)i(be)208 4266 y(added)d(automatically)f(as)j(appropriate\).)h(The)e(def)o(ault)g (v)n(alue)f(is)i(the)g(re)o(gular)d(e)o(xpression)h(`)p FJ([_a-z][_a-z0-9])3646 4281 y(*)3696 4266 y FN('.)0 4476 y(Alternati)n(v)o(ely)-5 b(,)18 b(you)i(can)g(pro)o(vide)e(the)i (entire)g(re)o(gular)f(e)o(xpression)g(pattern)g(by)h(o)o(v)o(erriding) e(the)i(class)h(attrib)n(ute)f FK(pattern)p FN(.)25 b(If)c(you)e(do)0 4575 y(this,)f(the)f(v)n(alue)f(must)i(be)f(a)g(re)o(gular)f(e)o (xpression)f(object)i(with)g(four)f(named)g(capturing)f(groups.)23 b(The)16 b(capturing)g(groups)f(correspond)0 4675 y(to)20 b(the)h(rules)f(gi)n(v)o(en)f(abo)o(v)o(e,)f(along)h(with)h(the)h(in)m (v)n(alid)e(placeholder)f(rule:)125 4885 y FM(\017)41 b FK(escaped)21 b FN(\226)f(This)h(group)d(matches)i(the)g(escape)g (sequence,)f(e.g.)24 b(`)p FJ($$)p FN(',)c(in)g(the)g(def)o(ault)g (pattern.)125 5043 y FM(\017)41 b FK(named)26 b FN(\226)g(This)g(group) d(matches)j(the)f(unbraced)f(placeholder)f(name;)28 b(it)e(should)e (not)i(include)e(the)i(delimiter)f(in)g(capturing)208 5142 y(group.)125 5300 y FM(\017)41 b FK(br)o(aced)22 b FN(\226)f(This)g(group)e(matches)i(the)g(brace)f(enclosed)g (placeholder)f(name;)i(it)g(should)f(not)h(include)f(either)h(the)g (delimiter)f(or)208 5400 y(braces)f(in)i(the)f(capturing)e(group.)p 0 5549 3901 4 v 0 5649 a FI(4.1.)52 b FJ(string)22 b FI(\227)h(Common)h(str)q(ing)f(oper)o(ations)2217 b(49)p eop end %%Page: 50 62 TeXDict begin 50 61 bop 125 83 a FM(\017)41 b FK(in)m(valid)19 b FN(\226)g(This)g(group)e(matches)i(an)o(y)f(other)g(delimiter)g (pattern)g(\(usually)g(a)h(single)g(delimiter\),)f(and)g(it)h(should)f (appear)g(last)h(in)208 183 y(the)h(re)o(gular)e(e)o(xpression.)0 462 y Fv(4.1.3)100 b(Str)q(ing)30 b(functions)0 665 y FN(The)h(follo)n(wing)f(functions)g(are)i(a)n(v)n(ailable)f(to)h (operate)e(on)h(string)h(and)f(Unicode)f(objects.)59 b(The)o(y)31 b(are)g(not)g(a)n(v)n(ailable)h(as)g(string)0 765 y(methods.)0 912 y FD(capwords)p FJ(\()p FK(s)p FJ(\))208 1011 y FN(Split)f(the)h(ar)o(gument)d(into)i(w)o(ords)g(using)g FJ(split\(\))p FN(,)i(capitalize)e(each)g(w)o(ord)g(using)f FJ(capitalize\(\))p FN(,)j(and)d(join)i(the)208 1111 y(capitalized)22 b(w)o(ords)h(using)g FJ(join\(\))p FN(.)33 b(Note)23 b(that)h(this)f(replaces)g(runs)g(of)g(whitespace)g (characters)f(by)h(a)g(single)g(space,)h(and)208 1210 y(remo)o(v)o(es)18 b(leading)h(and)h(trailing)g(whitespace.)0 1357 y FD(maketrans)p FJ(\()p FK(fr)l(om,)f(to)p FJ(\))208 1457 y FN(Return)i(a)h(translation)f(table)g(suitable)h(for)f(passing)g (to)h FJ(translate\(\))p FN(,)f(that)g(will)i(map)e(each)g(character)g (in)h FK(fr)l(om)g FN(into)g(the)208 1557 y(character)c(at)j(the)f (same)h(position)e(in)h FK(to)p FN(;)h FK(fr)l(om)g FN(and)e FK(to)i FN(must)f(ha)n(v)o(e)g(the)g(same)g(length.)208 1683 y FL(W)-5 b(ar)o(ning:)25 b FN(Don')o(t)20 b(use)h(strings)g(deri) n(v)o(ed)e(from)h FJ(lowercase)g FN(and)g FJ(uppercase)g FN(as)h(ar)o(guments;)f(in)h(some)f(locales,)h(these)208 1783 y(don')o(t)d(ha)n(v)o(e)i(the)g(same)g(length.)k(F)o(or)c(case)h (con)m(v)o(ersions,)c(al)o(w)o(ays)k(use)f FJ(lower\(\))g FN(and)f FJ(upper\(\))p FN(.)0 2063 y Fv(4.1.4)100 b(Deprecated)30 b(str)q(ing)f(functions)0 2265 y FN(The)i(follo)n(wing)f(list)i(of)g (functions)e(are)h(also)h(de\002ned)e(as)i(methods)e(of)i(string)f(and) g(Unicode)f(objects;)37 b(see)32 b(\223String)f(Methods\224)0 2365 y(\(section)22 b(3.6.1\))f(for)g(more)h(information)e(on)i(those.) 31 b(Y)-9 b(ou)22 b(should)g(consider)f(these)i(functions)e(as)i (deprecated,)e(although)f(the)o(y)i(will)0 2465 y(not)e(be)g(remo)o(v)o (ed)e(until)i(Python)f(3.0.)24 b(The)c(functions)f(de\002ned)g(in)h (this)h(module)e(are:)0 2612 y FD(atof)p FJ(\()p FK(s)p FJ(\))208 2711 y FL(Depr)o(ecated)g(since)i(r)o(elease)e(2.0.)24 b FN(Use)d(the)f FJ(float\(\))g FN(b)n(uilt-in)g(function.)208 2838 y(Con)m(v)o(ert)f(a)j(string)f(to)h(a)f(\003oating)g(point)g (number)-5 b(.)26 b(The)21 b(string)g(must)h(ha)n(v)o(e)f(the)g (standard)f(syntax)h(for)f(a)i(\003oating)f(point)f(literal)208 2938 y(in)25 b(Python,)g(optionally)e(preceded)h(by)h(a)g(sign)g(\(`)p FJ(+)p FN(')g(or)g(`)p FJ(-)p FN('\).)39 b(Note)25 b(that)g(this)h (beha)n(v)o(es)e(identical)h(to)g(the)h(b)n(uilt-in)e(function)208 3037 y FJ(float\(\))19 b FN(when)h(passed)g(a)g(string.)208 3164 y FL(Note:)31 b FN(When)24 b(passing)f(in)h(a)g(string,)g(v)n (alues)g(for)f(NaN)h(and)f(In\002nity)g(may)g(be)h(returned,)e (depending)f(on)j(the)g(underlying)d(C)208 3264 y(library)-5 b(.)33 b(The)23 b(speci\002c)h(set)h(of)e(strings)h(accepted)e(which)h (cause)h(these)g(v)n(alues)f(to)g(be)h(returned)e(depends)g(entirely)h (on)g(the)h(C)208 3363 y(library)19 b(and)g(is)i(kno)n(wn)e(to)h(v)n (ary)-5 b(.)0 3510 y FD(atoi)p FJ(\()p FK(s)p FC([)p FK(,)20 b(base)12 b FC(])p FJ(\))208 3610 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(2.0.)24 b FN(Use)d(the)f FJ(int\(\))g FN(b)n(uilt-in)g(function.)208 3737 y(Con)m(v)o(ert)29 b(string)i FK(s)h FN(to)g(an)f(inte)o(ger)f(in)i(the)f(gi)n(v)o(en)f FK(base)p FN(.)58 b(The)31 b(string)g(must)g(consist)g(of)g(one)g(or)g (more)f(digits,)k(optionally)208 3836 y(preceded)23 b(by)h(a)i(sign)f (\(`)p FJ(+)p FN(')f(or)h(`)p FJ(-)p FN('\).)38 b(The)25 b FK(base)g FN(def)o(aults)f(to)h(10.)39 b(If)25 b(it)h(is)g(0,)g(a)f (def)o(ault)f(base)i(is)f(chosen)g(depending)d(on)j(the)208 3936 y(leading)g(characters)g(of)h(the)g(string)f(\(after)h(stripping)f (the)h(sign\):)36 b(`)p FJ(0x)p FN(')26 b(or)g(`)p FJ(0X)p FN(')f(means)h(16,)h(`)p FJ(0)p FN(')f(means)g(8,)h(an)o(ything)d(else) 208 4036 y(means)17 b(10.)23 b(If)18 b FK(base)f FN(is)h(16,)g(a)g (leading)e(`)p FJ(0x)p FN(')h(or)g(`)p FJ(0X)p FN(')g(is)i(al)o(w)o (ays)e(accepted,)g(though)f(not)h(required.)22 b(This)c(beha)n(v)o(es)e (identically)208 4135 y(to)23 b(the)g(b)n(uilt-in)f(function)f FJ(int\(\))i FN(when)f(passed)h(a)h(string.)33 b(\(Also)23 b(note:)30 b(for)22 b(a)i(more)e(\003e)o(xible)g(interpretation)f(of)i (numeric)208 4235 y(literals,)d(use)g(the)h(b)n(uilt-in)e(function)g FJ(eval\(\))p FN(.\))0 4382 y FD(atol)p FJ(\()p FK(s)p FC([)p FK(,)h(base)12 b FC(])p FJ(\))208 4481 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(2.0.)24 b FN(Use)d(the)f FJ(long\(\))g FN(b)n(uilt-in)g(function.)208 4608 y(Con)m(v)o(ert)j(string)i FK(s)h FN(to)f(a)g(long)g(inte)o(ger)f(in)h(the)g(gi)n(v)o(en)f FK(base)p FN(.)39 b(The)25 b(string)f(must)i(consist)f(of)g(one)f(or)h (more)f(digits,)i(optionally)208 4708 y(preceded)18 b(by)i(a)h(sign)g (\(`)p FJ(+)p FN(')e(or)h(`)p FJ(-)p FN('\).)25 b(The)c FK(base)f FN(ar)o(gument)e(has)j(the)f(same)h(meaning)e(as)i(for)f FJ(atoi\(\))p FN(.)25 b(A)c(trailing)f(`)p FJ(l)p FN(')g(or)g(`)p FJ(L)p FN(')208 4807 y(is)h(not)f(allo)n(wed,)g(e)o(xcept)f(if)i(the)g (base)f(is)i(0.)k(Note)20 b(that)h(when)f(in)m(v)n(ok)o(ed)e(without)i FK(base)g FN(or)h(with)f FK(base)h FN(set)g(to)g(10,)e(this)i(beha)n(v) o(es)208 4907 y(identical)e(to)i(the)f(b)n(uilt-in)f(function)g FJ(long\(\))g FN(when)h(passed)g(a)h(string.)0 5054 y FD(capitalize)p FJ(\()p FK(wor)m(d)r FJ(\))208 5154 y FN(Return)e(a)i(cop)o(y)e(of)h FK(wor)m(d)j FN(with)d(only)f(its)j (\002rst)f(character)e(capitalized.)0 5300 y FD(expandtabs)p FJ(\()p FK(s)p FC([)p FK(,)g(tabsize)12 b FC(])p FJ(\))208 5400 y FN(Expand)20 b(tabs)j(in)g(a)g(string)g(replacing)e(them)h(by)h (one)f(or)g(more)g(spaces,)h(depending)d(on)j(the)f(current)g(column)f (and)h(the)h(gi)n(v)o(en)p 0 5549 3901 4 v 0 5649 a FI(50)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 51 63 TeXDict begin 51 62 bop 208 83 a FN(tab)19 b(size.)26 b(The)19 b(column)f(number)g(is)j(reset)f(to)g(zero)f(after)h(each)f (ne)n(wline)g(occurring)e(in)j(the)g(string.)25 b(This)19 b(doesn')o(t)g(understand)208 183 y(other)g(non-printing)e(characters)i (or)h(escape)g(sequences.)k(The)c(tab)g(size)h(def)o(aults)f(to)g(8.)0 330 y FD(find)p FJ(\()p FK(s,)g(sub)p FC([)p FK(,)g(start)q FC([)p FK(,end)13 b FC(])f(])p FJ(\))208 429 y FN(Return)17 b(the)h(lo)n(west)g(inde)o(x)f(in)h FK(s)h FN(where)f(the)g(substring)f FK(sub)h FN(is)h(found)d(such)i(that)g FK(sub)g FN(is)h(wholly)e (contained)f(in)j FK(s)p FJ([)p FK(start)q FJ(:)p FK(end)r FJ(])p FN(.)208 529 y(Return)g FJ(-1)i FN(on)e(f)o(ailure.)25 b(Def)o(aults)20 b(for)g FK(start)i FN(and)e FK(end)i FN(and)d(interpretation)f(of)i(ne)o(gati)n(v)o(e)e(v)n(alues)i(is)h (the)f(same)h(as)g(for)e(slices.)0 676 y FD(rfind)p FJ(\()p FK(s,)h(sub)p FC([)p FK(,)f(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 775 y FN(Lik)o(e)20 b FJ(find\(\))f FN(b)n(ut)h(\002nd)g(the)h(highest)e(inde)o(x.)0 922 y FD(index)p FJ(\()p FK(s,)h(sub)p FC([)p FK(,)f(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 1022 y FN(Lik)o(e)20 b FJ(find\(\))f FN(b)n(ut)h(raise)h FJ(ValueError)e FN(when)g(the)i (substring)e(is)i(not)f(found.)0 1169 y FD(rindex)p FJ(\()p FK(s,)f(sub)p FC([)p FK(,)h(start)q FC([)p FK(,)h(end)13 b FC(])f(])p FJ(\))208 1268 y FN(Lik)o(e)20 b FJ(rfind\(\))f FN(b)n(ut)h(raise)h FJ(ValueError)e FN(when)g(the)h(substring)g(is)h (not)f(found.)0 1415 y FD(count)p FJ(\()p FK(s,)g(sub)p FC([)p FK(,)f(start)q FC([)p FK(,)i(end)13 b FC(])f(])p FJ(\))208 1515 y FN(Return)19 b(the)h(number)e(of)i(\(non-o)o(v)o (erlapping\))14 b(occurrences)k(of)i(substring)f FK(sub)h FN(in)g(string)g FK(s)p FJ([)p FK(start)q FJ(:)p FK(end)r FJ(])p FN(.)25 b(Def)o(aults)20 b(for)g FK(start)208 1614 y FN(and)f FK(end)j FN(and)e(interpretation)e(of)i(ne)o(gati)n(v)o (e)e(v)n(alues)i(are)g(the)g(same)g(as)h(for)f(slices.)0 1761 y FD(lower)p FJ(\()p FK(s)p FJ(\))208 1861 y FN(Return)f(a)i(cop)o (y)e(of)h FK(s)p FN(,)h(b)n(ut)f(with)h(upper)d(case)j(letters)g(con)m (v)o(erted)c(to)j(lo)n(wer)g(case.)0 2008 y FD(split)p FJ(\()p FK(s)p FC([)p FK(,)f(sep)p FC([)p FK(,)h(maxsplit)13 b FC(])f(])p FJ(\))208 2107 y FN(Return)26 b(a)i(list)g(of)f(the)g(w)o (ords)f(of)h(the)g(string)g FK(s)p FN(.)46 b(If)27 b(the)g(optional)f (second)g(ar)o(gument)f FK(sep)i FN(is)h(absent)f(or)g FJ(None)p FN(,)h(the)f(w)o(ords)208 2207 y(are)20 b(separated)f(by)h (arbitrary)f(strings)h(of)g(whitespace)f(characters)h(\(space,)f(tab,)h (ne)n(wline,)g(return,)f(formfeed\).)j(If)e(the)g(second)208 2307 y(ar)o(gument)h FK(sep)k FN(is)g(present)e(and)h(not)f FJ(None)p FN(,)i(it)g(speci\002es)g(a)f(string)g(to)g(be)g(used)g(as)h (the)f(w)o(ord)f(separator)-5 b(.)36 b(The)24 b(returned)e(list)208 2406 y(will)27 b(then)g(ha)n(v)o(e)f(one)g(more)h(item)g(than)f(the)h (number)e(of)i(non-o)o(v)o(erlapping)22 b(occurrences)j(of)h(the)h (separator)f(in)h(the)g(string.)208 2506 y(The)18 b(optional)g(third)h (ar)o(gument)e FK(maxsplit)j FN(def)o(aults)f(to)g(0.)25 b(If)19 b(it)h(is)g(nonzero,)d(at)j(most)f FK(maxsplit)i FN(number)c(of)i(splits)h(occur)m(,)e(and)208 2606 y(the)i(remainder)e (of)i(the)g(string)f(is)i(returned)e(as)h(the)g(\002nal)h(element)e(of) h(the)g(list)h(\(thus,)e(the)i(list)g(will)f(ha)n(v)o(e)g(at)g(most)h FK(maxsplit)q FJ(+1)208 2705 y FN(elements\).)208 2838 y(The)26 b(beha)n(vior)f(of)h(split)i(on)e(an)h(empty)f(string)g (depends)f(on)i(the)f(v)n(alue)g(of)h FK(sep)p FN(.)45 b(If)26 b FK(sep)h FN(is)h(not)e(speci\002ed,)i(or)e(speci\002ed)h(as) 208 2938 y FJ(None)p FN(,)d(the)g(result)g(will)h(be)f(an)g(empty)f (list.)37 b(If)24 b FK(sep)g FN(is)h(speci\002ed)f(as)g(an)o(y)g (string,)g(the)g(result)g(will)h(be)f(a)g(list)h(containing)d(one)208 3037 y(element)d(which)h(is)h(an)f(empty)f(string.)0 3184 y FD(rsplit)p FJ(\()p FK(s)p FC([)p FK(,)g(sep)p FC([)p FK(,)h(maxsplit)13 b FC(])f(])p FJ(\))208 3284 y FN(Return)21 b(a)g(list)i(of)e(the)h(w)o(ords)f(of)g(the)g(string)g FK(s)p FN(,)i(scanning)d FK(s)i FN(from)f(the)g(end.)28 b(T)-7 b(o)22 b(all)g(intents)f(and)g(purposes,)f(the)i(resulting)e (list)208 3383 y(of)j(w)o(ords)g(is)h(the)f(same)h(as)g(returned)d(by)i FJ(split\(\))p FN(,)g(e)o(xcept)g(when)f(the)i(optional)e(third)h(ar)o (gument)e FK(maxsplit)j FN(is)h(e)o(xplicitly)208 3483 y(speci\002ed)i(and)h(nonzero.)46 b(When)28 b FK(maxsplit)h FN(is)g(nonzero,)e(at)i(most)f FK(maxsplit)h FN(number)d(of)i(splits)h (\226)f(the)g FK(rightmost)g FN(ones)f(\226)208 3583 y(occur)m(,)21 b(and)h(the)h(remainder)e(of)h(the)h(string)f(is)i (returned)d(as)i(the)g(\002rst)g(element)f(of)g(the)h(list)h(\(thus,)e (the)h(list)h(will)f(ha)n(v)o(e)f(at)i(most)208 3682 y FK(maxsplit)q FJ(+1)c FN(elements\).)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 3829 y FD(splitfields)p FJ(\()p FK(s)p FC([)p FK(,)g(sep)p FC([)p FK(,)i(maxsplit)13 b FC(])f(])p FJ(\))208 3929 y FN(This)18 b(function)e(beha)n(v)o(es)h (identically)g(to)h FJ(split\(\))p FN(.)24 b(\(In)17 b(the)h(past,)h FJ(split\(\))e FN(w)o(as)i(only)e(used)h(with)g(one)g (ar)o(gument,)e(while)208 4028 y FJ(splitfields\(\))i FN(w)o(as)j(only)e(used)h(with)h(tw)o(o)f(ar)o(guments.\))0 4175 y FD(join)p FJ(\()p FK(wor)m(ds)p FC([)p FK(,)f(sep)12 b FC(])p FJ(\))208 4275 y FN(Concatenate)23 b(a)h(list)h(or)f(tuple)g (of)g(w)o(ords)f(with)i(interv)o(ening)c(occurrences)h(of)i FK(sep)p FN(.)37 b(The)24 b(def)o(ault)f(v)n(alue)g(for)h FK(sep)g FN(is)h(a)g(single)208 4374 y(space)20 b(character)-5 b(.)24 b(It)c(is)h(al)o(w)o(ays)g(true)f(that)g(`)p FJ (string.join\(string.split\()p FK(s)p FJ(,)45 b FK(sep)p FJ(\),)k FK(sep)p FJ(\))p FN(')20 b(equals)g FK(s)p FN(.)0 4521 y FD(joinfields)p FJ(\()p FK(wor)m(ds)p FC([)p FK(,)e(sep)12 b FC(])p FJ(\))208 4621 y FN(This)24 b(function)e(beha)n(v)o(es)h (identically)f(to)i FJ(join\(\))p FN(.)36 b(\(In)23 b(the)h(past,)h FJ(join\(\))e FN(w)o(as)i(only)e(used)g(with)h(one)f(ar)o(gument,)g (while)208 4721 y FJ(joinfields\(\))16 b FN(w)o(as)k(only)e(used)g (with)h(tw)o(o)g(ar)o(guments.\))j(Note)c(that)h(there)f(is)h(no)g FJ(joinfields\(\))d FN(method)i(on)g(string)208 4820 y(objects;)i(use)g(the)g FJ(join\(\))g FN(method)f(instead.)0 4967 y FD(lstrip)p FJ(\()p FK(s)p FC([)p FK(,)g(c)o(har)o(s)12 b FC(])p FJ(\))208 5067 y FN(Return)18 b(a)h(cop)o(y)e(of)h(the)h (string)f(with)h(leading)e(characters)h(remo)o(v)o(ed.)k(If)c FK(c)o(har)o(s)h FN(is)g(omitted)f(or)g FJ(None)p FN(,)h(whitespace)f (characters)208 5166 y(are)23 b(remo)o(v)o(ed.)33 b(If)24 b(gi)n(v)o(en)e(and)h(not)g FJ(None)p FN(,)h FK(c)o(har)o(s)g FN(must)g(be)f(a)h(string;)i(the)d(characters)g(in)h(the)g(string)f (will)h(be)g(stripped)f(from)208 5266 y(the)c(be)o(ginning)e(of)i(the)h (string)f(this)h(method)e(is)i(called)f(on.)50 b(Changed)18 b(in)i(v)o(ersion)e(2.2.3:)g(The)h FK(c)o(har)o(s)h FN(parameter)e(w)o (as)i(added.)208 5366 y(The)f FK(c)o(har)o(s)i FN(parameter)d(cannot)h (be)h(passed)h(in)f(earlier)g(2.2)f(v)o(ersions.)p 0 5549 3901 4 v 0 5649 a FI(4.1.)52 b FJ(string)22 b FI(\227)h(Common)h (str)q(ing)f(oper)o(ations)2217 b(51)p eop end %%Page: 52 64 TeXDict begin 52 63 bop 0 83 a FD(rstrip)p FJ(\()p FK(s)p FC([)p FK(,)19 b(c)o(har)o(s)12 b FC(])p FJ(\))208 183 y FN(Return)18 b(a)h(cop)o(y)f(of)h(the)f(string)h(with)g(trailing)f (characters)g(remo)o(v)o(ed.)k(If)d FK(c)o(har)o(s)f FN(is)i(omitted)e(or)h FJ(None)p FN(,)f(whitespace)h(characters)208 282 y(are)k(remo)o(v)o(ed.)33 b(If)24 b(gi)n(v)o(en)e(and)h(not)g FJ(None)p FN(,)h FK(c)o(har)o(s)g FN(must)g(be)f(a)h(string;)i(the)d (characters)g(in)h(the)g(string)f(will)h(be)g(stripped)f(from)208 382 y(the)e(end)h(of)f(the)h(string)g(this)g(method)f(is)h(called)g (on.)60 b(Changed)21 b(in)h(v)o(ersion)e(2.2.3:)h(The)g FK(c)o(har)o(s)h FN(parameter)f(w)o(as)h(added.)29 b(The)208 482 y FK(c)o(har)o(s)20 b FN(parameter)e(cannot)h(be)i(passed)f(in)g (earlier)g(2.2)f(v)o(ersions.)0 628 y FD(strip)p FJ(\()p FK(s)p FC([)p FK(,)g(c)o(har)o(s)12 b FC(])p FJ(\))208 728 y FN(Return)j(a)i(cop)o(y)e(of)h(the)g(string)f(with)i(leading)e (and)g(trailing)h(characters)f(remo)o(v)o(ed.)21 b(If)16 b FK(c)o(har)o(s)g FN(is)h(omitted)e(or)h FJ(None)p FN(,)g(whitespace) 208 828 y(characters)28 b(are)h(remo)o(v)o(ed.)49 b(If)28 b(gi)n(v)o(en)g(and)h(not)f FJ(None)p FN(,)j FK(c)o(har)o(s)e FN(must)g(be)g(a)h(string;)j(the)c(characters)f(in)h(the)g(string)g (will)h(be)208 927 y(stripped)g(from)h(the)h(both)f(ends)h(of)f(the)h (string)g(this)g(method)f(is)h(called)g(on.)120 b(Changed)31 b(in)h(v)o(ersion)f(2.2.3:)f(The)i FK(c)o(har)o(s)208 1027 y FN(parameter)18 b(w)o(as)j(added.)j(The)c FK(c)o(har)o(s)g FN(parameter)f(cannot)g(be)h(passed)g(in)g(earlier)g(2.2)g(v)o (ersions.)0 1174 y FD(swapcase)p FJ(\()p FK(s)p FJ(\))208 1273 y FN(Return)f(a)i(cop)o(y)e(of)h FK(s)p FN(,)h(b)n(ut)f(with)h(lo) n(wer)e(case)i(letters)g(con)m(v)o(erted)c(to)j(upper)f(case)i(and)e (vice)i(v)o(ersa.)0 1420 y FD(translate)p FJ(\()p FK(s,)e(table)p FC([)p FK(,)g(deletec)o(har)o(s)12 b FC(])p FJ(\))208 1520 y FN(Delete)27 b(all)h(characters)e(from)h FK(s)h FN(that)f(are)h(in)f FK(deletec)o(har)o(s)g FN(\(if)g(present\),)h(and) f(then)f(translate)i(the)f(characters)f(using)h FK(table)p FN(,)208 1620 y(which)19 b(must)h(be)h(a)f(256-character)d(string)j(gi) n(ving)f(the)h(translation)g(for)f(each)h(character)f(v)n(alue,)g(inde) o(x)o(ed)f(by)i(its)h(ordinal.)0 1766 y FD(upper)p FJ(\()p FK(s)p FJ(\))208 1866 y FN(Return)e(a)i(cop)o(y)e(of)h FK(s)p FN(,)h(b)n(ut)f(with)h(lo)n(wer)e(case)i(letters)g(con)m(v)o (erted)c(to)j(upper)f(case.)0 2013 y FD(ljust)p FJ(\()p FK(s,)h(width)p FJ(\))0 2113 y FD(rjust)p FJ(\()p FK(s,)g(width)p FJ(\))0 2212 y FD(center)p FJ(\()p FK(s,)f(width)p FJ(\))208 2312 y FN(These)h(functions)f(respecti)n(v)o(ely)g(left-justify)-5 b(,)19 b(right-justify)f(and)i(center)g(a)h(string)f(in)g(a)h(\002eld)g (of)f(gi)n(v)o(en)f(width.)26 b(The)o(y)19 b(return)g(a)208 2411 y(string)h(that)h(is)g(at)g(least)h FK(width)e FN(characters)g (wide,)g(created)g(by)h(padding)d(the)j(string)f FK(s)i FN(with)e(spaces)h(until)g(the)f(gi)n(v)o(en)g(width)g(on)208 2511 y(the)g(right,)f(left)i(or)e(both)h(sides.)25 b(The)20 b(string)g(is)h(ne)n(v)o(er)e(truncated.)0 2658 y FD(zfill)p FJ(\()p FK(s,)h(width)p FJ(\))208 2758 y FN(P)o(ad)f(a)i(numeric)d (string)i(on)f(the)h(left)g(with)g(zero)f(digits)h(until)g(the)g(gi)n (v)o(en)e(width)i(is)h(reached.)i(Strings)d(starting)f(with)i(a)f(sign) g(are)208 2857 y(handled)e(correctly)-5 b(.)0 3004 y FD(replace)p FJ(\()p FK(str)c(,)19 b(old,)h(ne)o(w)p FC([)p FK(,)g(maxr)m(eplace)12 b FC(])p FJ(\))208 3104 y FN(Return)28 b(a)h(cop)o(y)g(of)f(string)h FK(str)j FN(with)d(all)h(occurrences)d(of)h(substring)g FK(old)j FN(replaced)d(by)g FK(ne)o(w)p FN(.)51 b(If)29 b(the)g(optional)f(ar)o (gument)208 3203 y FK(maxr)m(eplace)19 b FN(is)i(gi)n(v)o(en,)d(the)j (\002rst)f FK(maxr)m(eplace)f FN(occurrences)g(are)h(replaced.)0 3531 y FE(4.2)121 b Fx(re)32 b FE(\227)h(Regular)i(e)l(xpression)g (oper)o(ations)0 3764 y FN(This)d(module)e(pro)o(vides)g(re)o(gular)g (e)o(xpression)g(matching)g(operations)g(similar)i(to)f(those)h(found)d (in)j(Perl.)59 b(Re)o(gular)31 b(e)o(xpression)0 3863 y(pattern)18 b(strings)h(may)f(not)g(contain)g(null)g(bytes,)h(b)n(ut)g (can)f(specify)g(the)h(null)f(byte)h(using)f(the)g FJ(\\)p FK(number)i FN(notation.)j(Both)c(patterns)f(and)0 3963 y(strings)i(to)h(be)f(searched)f(can)h(be)g(Unicode)f(strings)h(as)h (well)g(as)g(8-bit)e(strings.)25 b(The)20 b FJ(re)g FN(module)f(is)i (al)o(w)o(ays)g(a)n(v)n(ailable.)0 4110 y(Re)o(gular)27 b(e)o(xpressions)f(use)h(the)h(backslash)e(character)g(\(`)p FJ(\\)p FN('\))h(to)g(indicate)g(special)h(forms)e(or)h(to)h(allo)n(w)f (special)h(characters)e(to)i(be)0 4209 y(used)e(without)f(in)m(v)n (oking)f(their)h(special)h(meaning.)41 b(This)26 b(collides)g(with)g (Python')-5 b(s)25 b(usage)h(of)f(the)h(same)g(character)f(for)g(the)h (same)0 4309 y(purpose)e(in)h(string)g(literals;)j(for)c(e)o(xample,)h (to)g(match)g(a)g(literal)h(backslash,)f(one)g(might)f(ha)n(v)o(e)g(to) i(write)f FJ('\\\\\\\\')g FN(as)g(the)g(pattern)0 4409 y(string,)h(because)f(the)g(re)o(gular)f(e)o(xpression)g(must)h(be)g(`) p FJ(\\\\)p FN(',)h(and)f(each)g(backslash)g(must)g(be)g(e)o(xpressed)f (as)i(`)p FJ(\\\\)p FN(')f(inside)g(a)h(re)o(gular)0 4508 y(Python)19 b(string)h(literal.)0 4655 y(The)g(solution)g(is)i(to) e(use)h(Python')-5 b(s)20 b(ra)o(w)h(string)f(notation)f(for)h(re)o (gular)f(e)o(xpression)g(patterns;)i(backslashes)f(are)g(not)h(handled) e(in)h(an)o(y)0 4755 y(special)27 b(w)o(ay)g(in)g(a)h(string)e(literal) i(pre\002x)o(ed)d(with)i(`)p FJ(r)p FN('.)45 b(So)27 b FJ(r"\\n")g FN(is)h(a)f(tw)o(o-character)f(string)g(containing)f(`)p FJ(\\)p FN(')i(and)f(`)p FJ(n)p FN(',)j(while)0 4854 y FJ("\\n")19 b FN(is)h(a)g(one-character)d(string)i(containing)e(a)j (ne)n(wline.)k(Usually)19 b(patterns)g(will)h(be)g(e)o(xpressed)e(in)h (Python)f(code)h(using)g(this)h(ra)o(w)0 4954 y(string)g(notation.)0 5101 y FL(See)h(Also:)0 5248 y FK(Mastering)f(Re)m(gular)f(Expr)m (essions)208 5347 y FN(Book)g(on)g(re)o(gular)e(e)o(xpressions)i(by)g (Jef)n(fre)o(y)f(Friedl,)h(published)f(by)h(O'Reilly)-5 b(.)25 b(The)19 b(second)f(edition)h(of)g(the)h(book)e(no)h(longer)p 0 5549 3901 4 v 0 5649 a FI(52)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 53 65 TeXDict begin 53 64 bop 208 83 a FN(co)o(v)o(ers)19 b(Python)g(at)h (all,)h(b)n(ut)f(the)g(\002rst)h(edition)e(co)o(v)o(ered)g(writing)g (good)g(re)o(gular)g(e)o(xpression)f(patterns)i(in)g(great)g(detail.)0 362 y Fv(4.2.1)100 b(Regular)30 b(Expression)f(Syntax)0 565 y FN(A)23 b(re)o(gular)f(e)o(xpression)f(\(or)h(RE\))i(speci\002es) f(a)g(set)h(of)f(strings)f(that)h(matches)g(it;)i(the)e(functions)e(in) i(this)h(module)d(let)j(you)e(check)g(if)h(a)0 665 y(particular)17 b(string)h(matches)g(a)h(gi)n(v)o(en)e(re)o(gular)g(e)o(xpression)f (\(or)i(if)h(a)g(gi)n(v)o(en)e(re)o(gular)f(e)o(xpression)h(matches)h (a)h(particular)e(string,)h(which)0 764 y(comes)i(do)n(wn)f(to)h(the)h (same)f(thing\).)0 911 y(Re)o(gular)25 b(e)o(xpressions)g(can)h(be)g (concatenated)f(to)h(form)f(ne)n(w)h(re)o(gular)f(e)o(xpressions;)j(if) e FK(A)h FN(and)e FK(B)i FN(are)f(both)f(re)o(gular)g(e)o(xpressions,)0 1011 y(then)h FK(AB)g FN(is)i(also)e(a)h(re)o(gular)e(e)o(xpression.)42 b(In)26 b(general,)h(if)f(a)h(string)f FK(p)h FN(matches)f FK(A)h FN(and)e(another)g(string)h FK(q)h FN(matches)f FK(B)p FN(,)g(the)h(string)0 1110 y FK(pq)c FN(will)h(match)e(AB.)i (This)f(holds)g(unless)g FK(A)g FN(or)g FK(B)g FN(contain)f(lo)n(w)i (precedence)d(operations;)i(boundary)d(conditions)h(between)i FK(A)g FN(and)0 1210 y FK(B)p FN(;)h(or)f(ha)n(v)o(e)h(numbered)d (group)h(references.)34 b(Thus,)24 b(comple)o(x)e(e)o(xpressions)g(can) h(easily)h(be)g(constructed)e(from)h(simpler)g(primiti)n(v)o(e)0 1310 y(e)o(xpressions)d(lik)o(e)h(the)g(ones)f(described)g(here.)27 b(F)o(or)20 b(details)h(of)g(the)g(theory)f(and)g(implementation)f(of)h (re)o(gular)g(e)o(xpressions,)f(consult)0 1409 y(the)h(Friedl)g(book)f (referenced)f(abo)o(v)o(e,)g(or)i(almost)g(an)o(y)g(te)o(xtbook)e (about)h(compiler)g(construction.)0 1556 y(A)24 b(brief)f(e)o (xplanation)f(of)i(the)f(format)g(of)h(re)o(gular)e(e)o(xpressions)g (follo)n(ws.)36 b(F)o(or)23 b(further)g(information)e(and)i(a)h (gentler)f(presentation,)0 1656 y(consult)d(the)g(Re)o(gular)f (Expression)g(HO)m(WT)o(O,)h(accessible)g(from)f FO(http://www)l(.p)n (ython.org/do)o(c/ho)n(wto)o(/)-6 b FN(.)0 1803 y(Re)o(gular)30 b(e)o(xpressions)f(can)i(contain)f(both)g(special)h(and)f(ordinary)f (characters.)56 b(Most)31 b(ordinary)d(characters,)33 b(lik)o(e)e(`)p FJ(A)p FN(',)f(`)p FJ(a)p FN(',)j(or)0 1902 y(`)p FJ(0)p FN(',)28 b(are)f(the)h(simplest)f(re)o(gular)f(e)o (xpressions;)j(the)o(y)e(simply)g(match)f(themselv)o(es.)46 b(Y)-9 b(ou)26 b(can)h(concatenate)f(ordinary)f(characters,)0 2002 y(so)101 1968 y Fp(d)116 2002 y FJ(last)-10 b Fp(c)16 b FN(matches)26 b(the)h(string)f FJ('last')p FN(.)43 b(\(In)26 b(the)g(rest)h(of)g(this)g(section,)g(we')o(ll)g(write)g(RE') -5 b(s)27 b(in)2960 1968 y Fp(d)2975 2002 y FJ(this)49 b(special)g(style)-10 b Fp(c)g FN(,)0 2101 y(usually)20 b(without)f(quotes,)g(and)h(strings)g(to)h(be)f(matched)f FJ('in)49 b(single)g(quotes')p FN(.\))0 2248 y(Some)18 b(characters,)f(lik)o(e)h(`)p FJ(|)p FN(')g(or)f(`)p FJ(\()p FN(',)h(are)g(special.)24 b(Special)18 b(characters)f(either)h (stand)f(for)h(classes)h(of)e(ordinary)f(characters,)h(or)h(af)n(fect)0 2348 y(ho)n(w)i(the)g(re)o(gular)e(e)o(xpressions)h(around)g(them)g (are)i(interpreted.)0 2495 y(The)f(special)g(characters)f(are:)0 2682 y FL(`)p FD(.)p FL(')41 b FN(\(Dot.\))31 b(In)22 b(the)h(def)o(ault)e(mode,)h(this)h(matches)f(an)o(y)g(character)f(e)o (xcept)h(a)h(ne)n(wline.)31 b(If)22 b(the)h FJ(DOTALL)f FN(\003ag)h(has)f(been)g(speci\002ed,)208 2782 y(this)e(matches)g(an)o (y)f(character)g(including)g(a)h(ne)n(wline.)0 2935 y FL(`)p FD(\210)p FL(')41 b FN(\(Caret.\))24 b(Matches)c(the)g(start)h (of)f(the)g(string,)g(and)g(in)g FJ(MULTILINE)f FN(mode)g(also)i (matches)f(immediately)e(after)i(each)g(ne)n(wline.)0 3087 y FL(`)p FD($)p FL(')41 b FN(Matches)23 b(the)h(end)g(of)f(the)h (string)g(or)f(just)i(before)d(the)i(ne)n(wline)g(at)g(the)g(end)f(of)h (the)g(string,)g(and)f(in)i FJ(MULTILINE)d FN(mode)h(also)208 3187 y(matches)e(before)g(a)i(ne)n(wline.)1110 3154 y Fp(d)1126 3187 y FJ(foo)-10 b Fp(c)11 b FN(matches)22 b(both)g('foo')e(and)i('foobar',)e(while)i(the)h(re)o(gular)d(e)o (xpression)3383 3154 y Fp(d)3399 3187 y FJ(foo$)-10 b Fp(c)11 b FN(matches)208 3287 y(only)19 b('foo'.)24 b(More)c (interestingly)-5 b(,)19 b(searching)g(for)1699 3253 y Fp(d)1714 3287 y FJ(foo.$)-10 b Fp(c)10 b FN(in)20 b('foo1)p FM(n)p FN(nfoo2)p FM(n)p FN(n')15 b(matches)20 b('foo2')e(normally)-5 b(,)19 b(b)n(ut)h('foo1')e(in)208 3386 y FJ(MULTILINE)h FN(mode.)0 3539 y FL(`)28 3552 y FD(*)78 3539 y FL(')41 b FN(Causes)22 b(the)g(resulting)g(RE)g(to)h (match)e(0)h(or)g(more)f(repetitions)g(of)h(the)g(preceding)e(RE,)j(as) f(man)o(y)f(repetitions)g(as)i(are)f(possible.)208 3605 y Fp(d)223 3639 y FJ(ab)323 3654 y(*)363 3639 y Fp(c)10 b FN(will)21 b(match)e('a',)h('ab',)f(or)h('a')g(follo)n(wed)f(by)h(an) o(y)f(number)f(of)i('b')-5 b(s.)0 3792 y FL(`)p FD(+)p FL(')41 b FN(Causes)20 b(the)g(resulting)f(RE)h(to)g(match)f(1)h(or)f (more)g(repetitions)g(of)g(the)h(preceding)d(RE.)2687 3758 y Fp(d)2703 3792 y FJ(ab+)-10 b Fp(c)9 b FN(will)20 b(match)f('a')h(follo)n(wed)e(by)h(an)o(y)208 3892 y(non-zero)e(number) i(of)h('b')-5 b(s;)20 b(it)h(will)g(not)f(match)f(just)i('a'.)0 4044 y FL(`)p FD(?)p FL(')41 b FN(Causes)21 b(the)f(resulting)f(RE)i (to)f(match)g(0)g(or)g(1)g(repetitions)g(of)g(the)g(preceding)e(RE.) 2566 4011 y Fp(d)2581 4044 y FJ(ab?)-10 b Fp(c)10 b FN(will)21 b(match)e(either)h('a')g(or)g('ab'.)0 4210 y FD(*)50 4197 y(?)p FL(,)g FD(+?)p FL(,)g FD(??)41 b FN(The)29 b(`)610 4212 y FJ(*)660 4197 y FN(',)i(`)p FJ(+)p FN(',)g(and)d(`)p FJ(?)p FN(')52 b(quali\002ers)29 b(are)g(all)g FK(gr)m(eedy)p FN(;)k(the)o(y)c(match)f(as)i(much)e(te)o(xt)h(as)h(possible.)51 b(Sometimes)29 b(this)208 4297 y(beha)n(viour)24 b(isn')o(t)j(desired;) i(if)e(the)g(RE)1372 4264 y Fp(d)1388 4297 y FJ(<.)1488 4312 y(*)1538 4297 y(>)-10 b Fp(c)16 b FN(is)28 b(matched)d(against)h FJ('

title

')p FN(,)g(it)h(will)h(match)e(the)h(entire)208 4397 y(string,)33 b(and)d(not)h(just)h FJ('

')p FN(.)57 b(Adding)30 b(`)p FJ(?)p FN(')57 b(after)31 b(the)g(quali\002er)f(mak)o (es)h(it)h(perform)d(the)i(match)g(in)g FK(non-gr)m(eedy)e FN(or)208 4496 y FK(minimal)e FN(f)o(ashion;)k(as)e FK(fe)o(w)f FN(characters)f(as)i(possible)e(will)i(be)f(matched.)47 b(Using)2652 4463 y Fp(d)2668 4496 y FJ(.)2718 4511 y(*)2768 4496 y(?)-10 b Fp(c)17 b FN(in)28 b(the)g(pre)n(vious)f(e)o(xpression)f (will)208 4596 y(match)19 b(only)h FJ('

')p FN(.)0 4749 y FD({)p Fo(m)p FD(})41 b FN(Speci\002es)20 b(that)f(e)o(xactly)g FK(m)h FN(copies)g(of)f(the)h(pre)n(vious)e(RE)i(should)f(be)g (matched;)g(fe)n(wer)g(matches)g(cause)h(the)g(entire)f(RE)h(not)f(to) 208 4849 y(match.)24 b(F)o(or)c(e)o(xample,)913 4815 y Fp(d)929 4849 y FJ(a{6})-10 b Fp(c)9 b FN(will)21 b(match)f(e)o (xactly)f(six)i(`)p FJ(a)p FN(')f(characters,)f(b)n(ut)h(not)g(\002)n (v)o(e.)0 5001 y FD({)p Fo(m)p FD(,)p Fo(n)p FD(})41 b FN(Causes)22 b(the)g(resulting)e(RE)i(to)g(match)f(from)g FK(m)h FN(to)f FK(n)h FN(repetitions)e(of)i(the)f(preceding)f(RE,)i (attempting)e(to)i(match)f(as)h(man)o(y)208 5101 y(repetitions)h(as)j (possible.)38 b(F)o(or)24 b(e)o(xample,)1476 5068 y Fp(d)1492 5101 y FJ(a{3,5})-10 b Fp(c)13 b FN(will)25 b(match)f(from)g(3)h(to)f (5)h(`)p FJ(a)p FN(')g(characters.)37 b(Omitting)24 b FK(m)h FN(speci\002es)g(a)208 5201 y(lo)n(wer)h(bound)e(of)i(zero,)i (and)d(omitting)h FK(n)g FN(speci\002es)h(an)g(in\002nite)f(upper)f (bound.)42 b(As)27 b(an)g(e)o(xample,)3192 5167 y Fp(d)3208 5201 y FJ(a{4,}b)-10 b Fp(c)15 b FN(will)27 b(match)208 5300 y FJ(aaaab)f FN(or)g(a)g(thousand)f(`)p FJ(a)p FN(')h(characters)f (follo)n(wed)g(by)h(a)h FJ(b)p FN(,)h(b)n(ut)e(not)g FJ(aaab)p FN(.)43 b(The)26 b(comma)g(may)g(not)g(be)g(omitted)f(or)i (the)208 5400 y(modi\002er)19 b(w)o(ould)g(be)h(confused)f(with)h(the)g (pre)n(viously)f(described)f(form.)p 0 5549 3901 4 v 0 5649 a FI(4.2.)52 b FJ(re)23 b FI(\227)g(Regular)h(e)n(xpression)e (oper)o(ations)2267 b(53)p eop end %%Page: 54 66 TeXDict begin 54 65 bop 0 83 a FD({)p Fo(m)p FD(,)p Fo(n)p FD(}?)41 b FN(Causes)23 b(the)f(resulting)g(RE)h(to)g(match)f(from)f FK(m)j FN(to)e FK(n)h FN(repetitions)e(of)i(the)f(preceding)f(RE,)i (attempting)e(to)i(match)f(as)h FK(fe)o(w)208 183 y FN(repetitions)18 b(as)j(possible.)j(This)c(is)h(the)e(non-greedy)d(v)o(ersion)j(of)g (the)h(pre)n(vious)e(quali\002er)-5 b(.)24 b(F)o(or)c(e)o(xample,)e(on) h(the)h(6-character)208 282 y(string)f FJ('aaaaaa')p FN(,)857 249 y Fp(d)873 282 y FJ(a{3,5})-10 b Fp(c)9 b FN(will)21 b(match)f(5)g(`)p FJ(a)p FN(')g(characters,)f(while)2345 249 y Fp(d)2361 282 y FJ(a{3,5}?)-10 b Fp(c)8 b FN(will)21 b(only)f(match)f(3)i(characters.)0 435 y FL(`)p FD(\\)p FL(')41 b FN(Either)28 b(escapes)i(special)f(characters)f(\(permitting) f(you)i(to)g(match)g(characters)f(lik)o(e)h(`)2721 450 y FJ(*)2771 435 y FN(',)i(`)p FJ(?)p FN(',)g(and)e(so)g(forth\),)h(or)f (signals)g(a)208 535 y(special)20 b(sequence;)f(special)h(sequences)g (are)g(discussed)g(belo)n(w)-5 b(.)208 661 y(If)29 b(you')l(re)f(not)i (using)f(a)h(ra)o(w)g(string)f(to)h(e)o(xpress)f(the)h(pattern,)h (remember)d(that)i(Python)f(also)h(uses)g(the)g(backslash)f(as)i(an)208 761 y(escape)20 b(sequence)f(in)i(string)f(literals;)i(if)e(the)h (escape)f(sequence)g(isn')o(t)g(recognized)e(by)i(Python')-5 b(s)20 b(parser)m(,)g(the)g(backslash)g(and)208 861 y(subsequent)27 b(character)h(are)h(included)f(in)h(the)h(resulting)e(string.)51 b(Ho)n(we)n(v)o(er)m(,)30 b(if)f(Python)f(w)o(ould)h(recognize)e(the)i (resulting)208 960 y(sequence,)d(the)g(backslash)g(should)f(be)h (repeated)f(twice.)43 b(This)27 b(is)g(complicated)d(and)i(hard)f(to)i (understand,)e(so)h(it')-5 b(s)28 b(highly)208 1060 y(recommended)17 b(that)j(you)f(use)i(ra)o(w)f(strings)g(for)f(all)i(b)n(ut)f(the)g (simplest)h(e)o(xpressions.)0 1213 y FD([])41 b FN(Used)19 b(to)f(indicate)g(a)h(set)g(of)g(characters.)k(Characters)18 b(can)g(be)h(listed)g(indi)n(vidually)-5 b(,)16 b(or)i(a)h(range)e(of)h (characters)g(can)g(be)h(indicated)208 1313 y(by)i(gi)n(ving)f(tw)o(o)j (characters)d(and)i(separating)e(them)i(by)f(a)h(`)p FJ(-)p FN('.)30 b(Special)21 b(characters)g(are)h(not)f(acti)n(v)o(e)h (inside)f(sets.)31 b(F)o(or)22 b(e)o(xam-)208 1412 y(ple,)357 1379 y Fp(d)373 1412 y FJ([akm$])-10 b Fp(c)14 b FN(will)26 b(match)f(an)o(y)f(of)i(the)f(characters)f(`)p FJ(a)p FN(',)i(`)p FJ(k)p FN(',)h(`)p FJ(m)p FN(',)f(or)f(`)p FJ($)p FN(';)2530 1379 y Fp(d)2545 1412 y FJ([a-z])-10 b Fp(c)15 b FN(will)26 b(match)f(an)o(y)f(lo)n(wercase)h(letter)m(,)208 1512 y(and)f FJ([a-zA-Z0-9])f FN(matches)h(an)o(y)g(letter)h(or)f (digit.)38 b(Character)24 b(classes)i(such)e(as)i FJ(\\w)f FN(or)f FJ(\\S)h FN(\(de\002ned)e(belo)n(w\))h(are)g(also)208 1612 y(acceptable)18 b(inside)i(a)g(range.)k(If)c(you)f(w)o(ant)h(to)g (include)e(a)j(`)p FJ(])p FN(')e(or)h(a)g(`)p FJ(-)p FN(')f(inside)h(a)g(set,)h(precede)d(it)j(with)f(a)g(backslash,)f(or)h (place)208 1711 y(it)g(as)h(the)g(\002rst)g(character)-5 b(.)24 b(The)19 b(pattern)1384 1678 y Fp(d)1399 1711 y FJ([]])-10 b Fp(c)10 b FN(will)21 b(match)e FJ(']')p FN(,)h(for)g(e)o(xample.)208 1838 y(Y)-9 b(ou)20 b(can)g(match)h(the)f (characters)g(not)h(within)f(a)i(range)d(by)i FK(complementing)d FN(the)j(set.)28 b(This)21 b(is)h(indicated)d(by)i(including)e(a)i(`)p FJ(\210)p FN(')208 1937 y(as)27 b(the)g(\002rst)h(character)d(of)i(the) g(set;)k(`)p FJ(\210)p FN(')26 b(else)n(where)g(will)i(simply)e(match)h (the)f(`)p FJ(\210)p FN(')h(character)-5 b(.)44 b(F)o(or)26 b(e)o(xample,)3521 1904 y Fp(d)3537 1937 y FJ([\2105])-10 b Fp(c)16 b FN(will)208 2037 y(match)j(an)o(y)h(character)f(e)o(xcept)g (`)p FJ(5)p FN(',)g(and)1419 2003 y Fp(d)1435 2037 y FJ([\210\210])-10 b Fp(c)9 b FN(will)21 b(match)f(an)o(y)f(character)g (e)o(xcept)g(`)p FJ(\210)p FN('.)0 2190 y FL(`)p FD(|)p FL(')41 b FJ(A|B)p FN(,)18 b(where)h(A)h(and)e(B)i(can)f(be)g (arbitrary)f(REs,)i(creates)f(a)g(re)o(gular)f(e)o(xpression)f(that)j (will)f(match)g(either)g(A)g(or)g(B.)h(An)f(arbitrary)208 2290 y(number)24 b(of)i(REs)i(can)e(be)g(separated)g(by)g(the)g(`)p FJ(|)p FN(')g(in)h(this)g(w)o(ay)-5 b(.)43 b(This)27 b(can)f(be)g(used)h(inside)f(groups)f(\(see)i(belo)n(w\))e(as)i(well.) 208 2389 y(As)c(the)g(tar)o(get)f(string)g(is)i(scanned,)e(REs)h (separated)f(by)h(`)p FJ(|)p FN(')f(are)h(tried)f(from)g(left)h(to)g (right.)32 b(When)22 b(one)g(pattern)g(completely)208 2489 y(matches,)e(that)i(branch)d(is)j(accepted.)27 b(This)21 b(means)g(that)g(once)g FJ(A)g FN(matches,)g FJ(B)g FN(will)h(not)f(be) g(tested)h(further)m(,)d(e)n(v)o(en)h(if)h(it)h(w)o(ould)208 2588 y(produce)16 b(a)k(longer)d(o)o(v)o(erall)h(match.)24 b(In)19 b(other)f(w)o(ords,)g(the)h(`)p FJ(|)p FN(')g(operator)e(is)j (ne)n(v)o(er)d(greedy)-5 b(.)23 b(T)-7 b(o)19 b(match)f(a)i(literal)f (`)p FJ(|)p FN(',)g(use)3757 2555 y Fp(d)3772 2588 y FJ(\\|)-10 b Fp(c)g FN(,)208 2688 y(or)19 b(enclose)h(it)h(inside)f(a)h (character)e(class,)i(as)g(in)1614 2655 y Fp(d)1630 2688 y FJ([|])-10 b Fp(c)g FN(.)0 2841 y FD(\(...\))41 b FN(Matches)20 b(whate)n(v)o(er)e(re)o(gular)h(e)o(xpression)g(is)i(inside)f(the)g (parentheses,)f(and)g(indicates)h(the)h(start)f(and)g(end)f(of)h(a)h (group;)e(the)208 2941 y(contents)24 b(of)g(a)h(group)e(can)i(be)f (retrie)n(v)o(ed)g(after)g(a)h(match)f(has)h(been)f(performed,)f(and)i (can)f(be)h(matched)e(later)i(in)g(the)g(string)208 3040 y(with)17 b(the)492 3007 y Fp(d)508 3040 y FJ(\\)p FK(number)-8 b Fp(c)5 b FN(special)17 b(sequence,)g(described)e(belo)n(w)-5 b(.)23 b(T)-7 b(o)18 b(match)e(the)h(literals)h(`)p FJ(\()p FN(')f(or)g(`)p FJ(\))p FN(',)g(use)3175 3007 y Fp(d)3191 3040 y FJ(\\\()-10 b Fp(c)7 b FN(or)3403 3007 y Fp(d)3418 3040 y FJ(\\\))-10 b Fp(c)g FN(,)17 b(or)g(enclose)208 3140 y(them)i(inside)h(a)h(character)e(class:)1206 3107 y Fp(d)1222 3140 y FJ([\(])49 b([\)])-10 b Fp(c)g FN(.)0 3293 y FD(\(?...\))40 b FN(This)18 b(is)f(an)g(e)o(xtension)f(notation) g(\(a)h(`)p FJ(?)p FN(')23 b(follo)n(wing)16 b(a)h(`)p FJ(\()p FN(')g(is)h(not)e(meaningful)f(otherwise\).)23 b(The)16 b(\002rst)i(character)e(after)h(the)208 3393 y(`)p FJ(?)p FN(')26 b(determines)20 b(what)g(the)h(meaning)e(and)i (further)e(syntax)h(of)g(the)h(construct)f(is.)27 b(Extensions)20 b(usually)g(do)h(not)f(create)h(a)g(ne)n(w)208 3492 y(group;)445 3459 y Fp(d)461 3492 y FJ(\(?P<)p FK(name)p FJ(>...\))-10 b Fp(c)7 b FN(is)21 b(the)f(only)g(e)o(xception)e(to)i(this)h(rule.)k (F)o(ollo)n(wing)18 b(are)i(the)h(currently)d(supported)g(e)o (xtensions.)0 3646 y FD(\(?iLmsux\))40 b FN(\(One)22 b(or)g(more)f(letters)i(from)e(the)h(set)h(`)p FJ(i)p FN(',)g(`)p FJ(L)p FN(',)e(`)p FJ(m)p FN(',)i(`)p FJ(s)p FN(',)f(`)p FJ(u)p FN(',)g(`)p FJ(x)p FN('.\))30 b(The)22 b(group)f(matches)h(the)g(empty)f(string;)j(the)208 3745 y(letters)c(set)i(the)e(corresponding)d(\003ags)k(\()p FJ(re.I)p FN(,)e FJ(re.L)p FN(,)h FJ(re.M)p FN(,)g FJ(re.S)p FN(,)g FJ(re.U)p FN(,)g FJ(re.X)p FN(\))g(for)f(the)i(entire)f(re)o (gular)e(e)o(xpression.)208 3845 y(This)f(is)i(useful)e(if)h(you)f (wish)h(to)g(include)f(the)g(\003ags)h(as)h(part)e(of)h(the)f(re)o (gular)f(e)o(xpression,)h(instead)g(of)h(passing)f(a)h FK(\003a)o(g)f FN(ar)o(gument)208 3944 y(to)j(the)g FJ(compile\(\))f FN(function.)208 4071 y(Note)j(that)g(the)663 4037 y Fp(d)679 4071 y FJ(\(?x\))-10 b Fp(c)11 b FN(\003ag)22 b(changes)f(ho)n(w)h(the)g(e)o(xpression)f(is)i(parsed.)30 b(It)22 b(should)f(be)h(used)g(\002rst)h(in)f(the)h(e)o(xpression)d (string,)208 4170 y(or)e(after)f(one)h(or)g(more)g(whitespace)f (characters.)24 b(If)18 b(there)g(are)g(non-whitespace)e(characters)h (before)g(the)h(\003ag,)h(the)f(results)h(are)208 4270 y(unde\002ned.)0 4423 y FD(\(?:...\))40 b FN(A)23 b(non-grouping)18 b(v)o(ersion)j(of)h(re)o(gular)f(parentheses.)30 b(Matches)22 b(whate)n(v)o(er)f(re)o(gular)f(e)o(xpression)h(is)i(inside)g(the)f (paren-)208 4523 y(theses,)f(b)n(ut)g(the)h(substring)e(matched)g(by)h (the)g(group)f FK(cannot)f FN(be)i(retrie)n(v)o(ed)f(after)h (performing)d(a)k(match)e(or)h(referenced)e(later)208 4622 y(in)h(the)g(pattern.)0 4775 y FD(\(?P<)p Fo(name)p FD(>...\))39 b FN(Similar)22 b(to)g(re)o(gular)f(parentheses,)g(b)n(ut) h(the)g(substring)f(matched)g(by)g(the)h(group)f(is)i(accessible)f(via) g(the)g(sym-)208 4875 y(bolic)g(group)f(name)h FK(name)p FN(.)32 b(Group)21 b(names)i(must)f(be)h(v)n(alid)f(Python)g (identi\002ers,)h(and)f(each)g(group)f(name)h(must)h(be)g(de\002ned)208 4975 y(only)18 b(once)g(within)h(a)g(re)o(gular)f(e)o(xpression.)23 b(A)c(symbolic)f(group)g(is)h(also)h(a)f(numbered)e(group,)g(just)j(as) f(if)h(the)f(group)e(were)i(not)208 5074 y(named.)k(So)e(the)f(group)e (named)i('id')f(in)i(the)f(e)o(xample)f(abo)o(v)o(e)f(can)i(also)h(be)f (referenced)e(as)j(the)f(numbered)e(group)g(1.)208 5201 y(F)o(or)k(e)o(xample,)h(if)g(the)g(pattern)f(is)1204 5167 y Fp(d)1219 5201 y FJ(\(?P[a-zA-Z_]\\w)2119 5216 y(*)2169 5201 y(\))-10 b Fp(c)g FN(,)20 b(the)j(group)f(can)g(be)i (referenced)d(by)h(its)i(name)f(in)g(ar)o(gu-)208 5300 y(ments)18 b(to)g(methods)f(of)h(match)g(objects,)g(such)g(as)h FJ(m.group\('id'\))d FN(or)i FJ(m.end\('id'\))p FN(,)f(and)h(also)h(by) e(name)h(in)g(pattern)208 5400 y(te)o(xt)i(\(for)f(e)o(xample,)818 5366 y Fp(d)834 5400 y FJ(\(?P=id\))-10 b Fp(c)g FN(\))18 b(and)i(replacement)e(te)o(xt)j(\(such)e(as)i FJ(\\g)p FN(\).)p 0 5549 3901 4 v 0 5649 a FI(54)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 55 67 TeXDict begin 55 66 bop 0 83 a FD(\(?P=)p Fo(name)p FD(\))40 b FN(Matches)20 b(whate)n(v)o(er)e(te)o(xt)i(w)o(as)i(matched)d(by)g (the)i(earlier)e(group)g(named)g FK(name)p FN(.)0 245 y FD(\(?#...\))40 b FN(A)21 b(comment;)e(the)h(contents)f(of)h(the)h (parentheses)e(are)h(simply)g(ignored.)0 407 y FD(\(?=...\))40 b FN(Matches)19 b(if)761 374 y Fp(d)776 407 y FJ(...)-10 b Fp(c)8 b FN(matches)19 b(ne)o(xt,)f(b)n(ut)h(doesn')o(t)e(consume)g (an)o(y)h(of)h(the)f(string.)24 b(This)19 b(is)h(called)e(a)i (lookahead)c(assertion.)208 507 y(F)o(or)j(e)o(xample,)664 473 y Fp(d)680 507 y FJ(Isaac)48 b(\(?=Asimov\))-10 b Fp(c)9 b FN(will)21 b(match)e FJ('Isaac)49 b(')20 b FN(only)g(if)g(it') -5 b(s)22 b(follo)n(wed)c(by)i FJ('Asimov')p FN(.)0 669 y FD(\(?!...\))40 b FN(Matches)34 b(if)790 635 y Fp(d)806 669 y FJ(...)-10 b Fp(c)23 b FN(doesn')o(t)32 b(match)h(ne)o(xt.)64 b(This)34 b(is)g(a)g(ne)o(gati)n(v)o(e)e(lookahead)f(assertion.)65 b(F)o(or)33 b(e)o(xample,)3635 635 y Fp(d)3651 669 y FJ(Isaac)208 768 y(\(?!Asimov\))-10 b Fp(c)8 b FN(will)21 b(match)e FJ('Isaac)49 b(')21 b FN(only)e(if)h(it')-5 b(s)22 b FK(not)e FN(follo)n(wed)e(by)i FJ('Asimov')p FN(.)0 930 y FD(\(?<=...\))40 b FN(Matches)28 b(if)h(the)f(current)f (position)h(in)g(the)g(string)g(is)i(preceded)c(by)i(a)h(match)e(for) 2910 897 y Fp(d)2926 930 y FJ(...)-10 b Fp(c)17 b FN(that)29 b(ends)f(at)h(the)f(current)208 1030 y(position.)e(This)21 b(is)h(called)e(a)i FK(positive)e(lookbehind)f(assertion)p FN(.)2071 996 y Fp(d)2086 1030 y FJ(\(?<=abc\)def)-10 b Fp(c)9 b FN(will)22 b(\002nd)e(a)h(match)g(in)g(`)p FJ(abcdef)p FN(',)e(since)208 1130 y(the)e(lookbehind)e(will)j(back)f (up)g(3)h(characters)e(and)h(check)g(if)h(the)f(contained)f(pattern)h (matches.)24 b(The)17 b(contained)f(pattern)h(must)208 1229 y(only)h(match)h(strings)g(of)g(some)h(\002x)o(ed)e(length,)h (meaning)f(that)2007 1196 y Fp(d)2023 1229 y FJ(abc)-10 b Fp(c)8 b FN(or)2288 1196 y Fp(d)2304 1229 y FJ(a|b)-10 b Fp(c)9 b FN(are)19 b(allo)n(wed,)f(b)n(ut)3028 1196 y Fp(d)3043 1229 y FJ(a)3093 1244 y(*)3133 1229 y Fp(c)9 b FN(and)3310 1196 y Fp(d)3326 1229 y FJ(a{3,4})-10 b Fp(c)8 b FN(are)19 b(not.)208 1329 y(Note)f(that)h(patterns)f(which)g (start)h(with)f(positi)n(v)o(e)g(lookbehind)e(assertions)i(will)h(ne)n (v)o(er)f(match)g(at)h(the)f(be)o(ginning)e(of)i(the)h(string)208 1428 y(being)g(searched;)g(you)g(will)i(most)f(lik)o(ely)h(w)o(ant)f (to)g(use)h(the)f FJ(search\(\))f FN(function)g(rather)g(than)h(the)g FJ(match\(\))f FN(function:)444 1651 y FA(>>>)44 b(import)g(re)444 1742 y(>>>)g(m)h(=)f(re.search\('\(?<=abc\)def',)d('abcdef'\))444 1833 y(>>>)j(m.group\(0\))444 1925 y('def')208 2195 y FN(This)20 b(e)o(xample)f(looks)g(for)h(a)h(w)o(ord)e(follo)n(wing)g(a) h(hyphen:)444 2417 y FA(>>>)44 b(m)h(=)f(re.search\('\(?<=-\)\\w+',)e ('spam-egg'\))444 2508 y(>>>)i(m.group\(0\))444 2600 y('egg')0 2909 y FD(\(?\))-10 b Fp(c)r FN(is)18 b(a)h(poor)d(email)i(matching)e(pattern,)h(which)h (will)g(match)f(with)208 3669 y FJ('')28 b FN(as)j(well)h(as)f FJ('user@host.com')p FN(,)g(b)n(ut)g(not)g(with)g FJ('>>)44 b(re.split\('\\W+',)e ('Words,)i(words,)g(words.'\))444 2466 y(['Words',)f('words',)h ('words',)f(''])444 2558 y(>>>)h(re.split\('\(\\W+\)',)e('Words,)i (words,)g(words.'\))444 2649 y(['Words',)f(',)i(',)f('words',)g(',)g (',)h('words',)e('.',)h(''])444 2740 y(>>>)g(re.split\('\\W+',)e ('Words,)i(words,)g(words.',)f(1\))444 2832 y(['Words',)g('words,)h (words.'])0 3058 y FD(findall)p FJ(\()p FK(pattern,)18 b(string)p FC([)p FK(,)i(\003a)o(gs)12 b FC(])p FJ(\))208 3158 y FN(Return)17 b(a)h(list)g(of)g(all)g(non-o)o(v)o(erlapping)12 b(matches)18 b(of)f FK(pattern)g FN(in)h FK(string)p FN(.)24 b(If)18 b(one)f(or)g(more)g(groups)f(are)h(present)g(in)h(the)g (pattern,)208 3258 y(return)23 b(a)i(list)h(of)e(groups;)h(this)g(will) g(be)g(a)g(list)h(of)e(tuples)g(if)h(the)g(pattern)e(has)i(more)f(than) g(one)g(group.)36 b(Empty)23 b(matches)i(are)208 3357 y(included)d(in)h(the)h(result)f(unless)h(the)o(y)f(touch)f(the)i(be)o (ginning)d(of)i(another)f(match.)70 b(Ne)n(w)24 b(in)f(v)o(ersion)f (1.5.2.)105 b(Changed)22 b(in)208 3457 y(v)o(ersion)c(2.4:)i(Added)f (the)h(optional)f(\003ags)i(ar)o(gument.)0 3604 y FD(finditer)p FJ(\()p FK(pattern,)d(string)p FC([)p FK(,)i(\003a)o(gs)12 b FC(])p FJ(\))208 3703 y FN(Return)24 b(an)h(iterator)f(o)o(v)o(er)f (all)j(non-o)o(v)o(erlapping)20 b(matches)k(for)g(the)h(RE)h FK(pattern)e FN(in)h FK(string)p FN(.)39 b(F)o(or)25 b(each)f(match,)h(the)g(iterator)208 3803 y(returns)g(a)j(match)e (object.)44 b(Empty)26 b(matches)g(are)h(included)e(in)i(the)g(result)g (unless)g(the)o(y)f(touch)g(the)g(be)o(ginning)f(of)h(another)208 3903 y(match.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.4:)h(Added)f(the)h(optional)f (\003ags)i(ar)o(gument.)0 4050 y FD(sub)p FJ(\()p FK(pattern,)e(r)m (epl,)h(string)p FC([)p FK(,)g(count)13 b FC(])p FJ(\))208 4149 y FN(Return)27 b(the)h(string)g(obtained)f(by)g(replacing)g(the)h (leftmost)g(non-o)o(v)o(erlapping)23 b(occurrences)j(of)i FK(pattern)f FN(in)h FK(string)h FN(by)f(the)208 4249 y(replacement)21 b FK(r)m(epl)p FN(.)34 b(If)23 b(the)g(pattern)f(isn') o(t)h(found,)f FK(string)i FN(is)g(returned)d(unchanged.)31 b FK(r)m(epl)23 b FN(can)g(be)h(a)f(string)g(or)g(a)g(function;)g(if) 208 4348 y(it)f(is)g(a)g(string,)f(an)o(y)f(backslash)h(escapes)g(in)h (it)g(are)f(processed.)27 b(That)21 b(is,)i(`)p FJ(\\n)p FN(')d(is)j(con)m(v)o(erted)18 b(to)k(a)g(single)f(ne)n(wline)f (character)m(,)208 4448 y(`)p FJ(\\r)p FN(')25 b(is)j(con)m(v)o(erted) 23 b(to)k(a)g(linefeed,)f(and)g(so)h(forth.)42 b(Unkno)n(wn)24 b(escapes)j(such)f(as)h(`)p FJ(\\j)p FN(')f(are)g(left)h(alone.)43 b(Backreferences,)208 4548 y(such)19 b(as)i(`)p FJ(\\6)p FN(',)f(are)g(replaced)f(with)h(the)g(substring)g(matched)f(by)g(group) g(6)h(in)h(the)f(pattern.)k(F)o(or)c(e)o(xample:)444 4772 y FA(>>>)44 b(re.sub\(r'def\\s+\([a-zA-Z_][a-zA-Z_0-9])2288 4785 y(*)2333 4772 y(\)\\)o(s)2467 4785 y(*)2512 4772 y(\\\(\\s)2691 4785 y(*)2736 4772 y(\\\):',)444 4863 y(...)358 b(r'static)43 b(PyObject)1700 4876 y(*)1745 4863 y(\\npy_\\1\(void\)\\n{',)444 4954 y(...)358 b('def)44 b(myfunc\(\):'\))444 5046 y('static)f(PyObject)1162 5059 y(*)1207 5046 y(\\npy_myfunc\(void\)\\n{')208 5235 y FN(If)25 b FK(r)m(epl)h FN(is)g(a)g(function,)f(it)i(is)f(called)g(for) f(e)n(v)o(ery)f(non-o)o(v)o(erlapping)c(occurrence)k(of)h FK(pattern)p FN(.)41 b(The)25 b(function)f(tak)o(es)i(a)g(single)208 5335 y(match)19 b(object)h(ar)o(gument,)d(and)j(returns)f(the)i (replacement)d(string.)25 b(F)o(or)20 b(e)o(xample:)p 0 5549 3901 4 v 0 5649 a FI(58)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 59 71 TeXDict begin 59 70 bop 444 174 a FA(>>>)44 b(def)g (dashrepl\(matchobj\):)444 266 y(...)223 b(if)45 b(matchobj.group\(0\)) d(==)i('-':)h(return)e(')i(')444 357 y(...)223 b(else:)44 b(return)g('-')444 448 y(>>>)g(re.sub\('-{1,2}',)e(dashrepl,)i ('pro----gram-files'\))444 540 y('pro--gram)f(files')208 729 y FN(The)20 b(pattern)f(may)h(be)h(a)g(string)f(or)g(an)h(RE)g (object;)f(if)h(you)f(need)g(to)g(specify)g(re)o(gular)f(e)o(xpression) g(\003ags,)i(you)f(must)g(use)h(a)g(RE)208 829 y(object,)27 b(or)g(use)g(embedded)e(modi\002ers)h(in)h(a)h(pattern;)h(for)e(e)o (xample,)f(`)p FJ(sub\("\(?i\)b+",)48 b("x",)h("bbbb)f(BBBB"\))p FN(')208 928 y(returns)19 b FJ('x)49 b(x')p FN(.)208 1061 y(The)24 b(optional)g(ar)o(gument)f FK(count)j FN(is)g(the)f (maximum)f(number)f(of)i(pattern)f(occurrences)f(to)j(be)f(replaced;)h FK(count)g FN(must)f(be)g(a)208 1161 y(non-ne)o(gati)n(v)o(e)d(inte)o (ger)-5 b(.)42 b(If)26 b(omitted)g(or)g(zero,)h(all)f(occurrences)f (will)i(be)f(replaced.)41 b(Empty)26 b(matches)f(for)h(the)g(pattern)g (are)208 1260 y(replaced)16 b(only)g(when)h(not)h(adjacent)e(to)i(a)g (pre)n(vious)e(match,)h(so)h(`)p FJ(sub\('x)2391 1275 y(*)2441 1260 y(',)48 b('-',)h('abc'\))p FN(')16 b(returns)h FJ('-a-b-c-')p FN(.)208 1393 y(In)28 b(addition)f(to)h(character)g (escapes)g(and)g(backreferences)e(as)j(described)e(abo)o(v)o(e,)i(`)p FJ(\\g)p FN(')d(will)j(use)g(the)g(substring)208 1493 y(matched)21 b(by)h(the)g(group)f(named)g(`)p FJ(name)p FN(',)h(as)i(de\002ned)d(by)h(the)2093 1459 y Fp(d)2108 1493 y FJ(\(?P...\))-10 b Fp(c)10 b FN(syntax.)31 b(`)p FJ(\\g)p FN(')21 b(uses)i(the)208 1593 y(corresponding)g(group)h(number;)k(`)p FJ(\\g<2>)p FN(')e(is)h (therefore)e(equi)n(v)n(alent)g(to)h(`)p FJ(\\2)p FN(',)i(b)n(ut)e (isn')o(t)g(ambiguous)f(in)h(a)h(replacement)208 1692 y(such)21 b(as)h(`)p FJ(\\g<2>0)p FN('.)27 b(`)p FJ(\\20)p FN(')21 b(w)o(ould)g(be)g(interpreted)f(as)i(a)g(reference)d(to)j (group)d(20,)j(not)f(a)g(reference)f(to)i(group)d(2)j(follo)n(wed)208 1792 y(by)d(the)i(literal)f(character)f(`)p FJ(0)p FN('.)25 b(The)19 b(backreference)f(`)p FJ(\\g<0>)p FN(')h(substitutes)h(in)g (the)h(entire)e(substring)h(matched)f(by)g(the)i(RE.)0 1939 y FD(subn)p FJ(\()p FK(pattern,)d(r)m(epl,)j(string)p FC([)p FK(,)f(count)13 b FC(])p FJ(\))208 2038 y FN(Perform)18 b(the)j(same)f(operation)e(as)j FJ(sub\(\))p FN(,)f(b)n(ut)g(return)f (a)i(tuple)e FJ(\()p FK(ne)o(w)p 2305 2038 25 4 v 30 w(string)p FJ(,)49 b FK(number)p 2883 2038 V 28 w(of)p 2976 2038 V 30 w(subs)p 3154 2038 V 29 w(made)p FJ(\))p FN(.)0 2185 y FD(escape)p FJ(\()p FK(string)p FJ(\))208 2285 y FN(Return)26 b FK(string)h FN(with)g(all)h(non-alphanumerics)22 b(backslashed;)29 b(this)f(is)g(useful)e(if)h(you)f(w)o(ant)h(to)g (match)f(an)h(arbitrary)e(literal)208 2384 y(string)19 b(that)i(may)e(ha)n(v)o(e)h(re)o(gular)f(e)o(xpression)f (metacharacters)h(in)h(it.)0 2531 y FL(exception)f FD(error)208 2631 y FN(Exception)d(raised)h(when)g(a)h(string)g(passed)g(to)f(one)h (of)f(the)h(functions)e(here)h(is)i(not)f(a)g(v)n(alid)f(re)o(gular)f (e)o(xpression)g(\(for)h(e)o(xample,)208 2731 y(it)j(might)g(contain)f (unmatched)f(parentheses\))h(or)h(when)g(some)g(other)f(error)g(occurs) h(during)e(compilation)h(or)h(matching.)j(It)e(is)208 2830 y(ne)n(v)o(er)d(an)j(error)e(if)h(a)h(string)f(contains)f(no)h (match)f(for)h(a)h(pattern.)0 3115 y Fv(4.2.4)100 b(Regular)30 b(Expression)f(Objects)0 3318 y FN(Compiled)19 b(re)o(gular)g(e)o (xpression)f(objects)i(support)f(the)h(follo)n(wing)f(methods)g(and)h (attrib)n(utes:)0 3465 y FD(match)p FJ(\()p FK(string)p FC([)p FK(,)f(pos)p FC([)p FK(,)h(endpos)12 b FC(])g(])p FJ(\))208 3564 y FN(If)31 b(zero)h(or)f(more)g(characters)g(at)h(the)g (be)o(ginning)d(of)j FK(string)g FN(match)g(this)g(re)o(gular)e(e)o (xpression,)j(return)e(a)h(corresponding)208 3664 y FJ(MatchObject)19 b FN(instance.)29 b(Return)20 b FJ(None)i FN(if)f(the)h(string)f(does)g (not)g(match)g(the)g(pattern;)g(note)g(that)h(this)g(is)g(dif)n(ferent) e(from)208 3764 y(a)g(zero-length)e(match.)208 3897 y FL(Note:)24 b FN(If)c(you)f(w)o(ant)i(to)f(locate)g(a)h(match)e(an)o (ywhere)f(in)j FK(string)p FN(,)f(use)g FJ(search\(\))g FN(instead.)208 4029 y(The)f(optional)f(second)h(parameter)f FK(pos)i FN(gi)n(v)o(es)f(an)h(inde)o(x)e(in)i(the)g(string)f(where)h (the)f(search)h(is)g(to)g(start;)h(it)f(def)o(aults)f(to)h FJ(0)p FN(.)25 b(This)208 4129 y(is)c(not)f(completely)f(equi)n(v)n (alent)f(to)j(slicing)f(the)g(string;)g(the)h FJ('\210')f FN(pattern)f(character)g(matches)h(at)h(the)f(real)h(be)o(ginning)d(of) i(the)208 4229 y(string)f(and)h(at)h(positions)e(just)i(after)f(a)h(ne) n(wline,)e(b)n(ut)h(not)g(necessarily)g(at)g(the)g(inde)o(x)f(where)h (the)g(search)g(is)h(to)f(start.)208 4361 y(The)25 b(optional)g (parameter)g FK(endpos)g FN(limits)h(ho)n(w)g(f)o(ar)g(the)g(string)g (will)h(be)f(searched;)i(it)f(will)g(be)f(as)g(if)h(the)f(string)g(is)h FK(endpos)208 4461 y FN(characters)20 b(long,)h(so)h(only)e(the)i (characters)e(from)h FK(pos)g FN(to)h FK(endpos)48 b FJ(-)h(1)22 b FN(will)h(be)e(searched)f(for)h(a)h(match.)28 b(If)22 b FK(endpos)e FN(is)i(less)208 4561 y(than)f FK(pos)p FN(,)i(no)f(match)f(will)i(be)g(found,)d(otherwise,)i(if)h FK(rx)g FN(is)g(a)g(compiled)e(re)o(gular)g(e)o(xpression)f(object,)i FK(rx)p FJ(.match\()p FK(string)p FJ(,)208 4660 y(0,)49 b(50\))20 b FN(is)h(equi)n(v)n(alent)e(to)h FK(rx)p FJ(.match\()p FK(string)p FJ([:50],)48 b(0\))p FN(.)0 4807 y FD(search)p FJ(\()p FK(string)p FC([)p FK(,)19 b(pos)p FC([)p FK(,)g(endpos)12 b FC(])g(])p FJ(\))208 4907 y FN(Scan)22 b(through)f FK(string)j FN(looking)d(for)h(a)h(location)f(where)h(this)g(re)o (gular)f(e)o(xpression)f(produces)g(a)i(match,)g(and)g(return)e(a)j (corre-)208 5006 y(sponding)18 b FJ(MatchObject)i FN(instance.)27 b(Return)20 b FJ(None)h FN(if)g(no)g(position)f(in)h(the)g(string)g (matches)f(the)h(pattern;)g(note)f(that)h(this)208 5106 y(is)g(dif)n(ferent)d(from)h(\002nding)g(a)i(zero-length)d(match)i(at)g (some)g(point)g(in)g(the)g(string.)208 5239 y(The)f(optional)g FK(pos)h FN(and)g FK(endpos)f FN(parameters)g(ha)n(v)o(e)h(the)g(same)g (meaning)f(as)i(for)e(the)h FJ(match\(\))g FN(method.)p 0 5549 3901 4 v 0 5649 a FI(4.2.)52 b FJ(re)23 b FI(\227)g(Regular)h(e) n(xpression)e(oper)o(ations)2267 b(59)p eop end %%Page: 60 72 TeXDict begin 60 71 bop 0 83 a FD(split)p FJ(\()p FK(string)p FC([)p FK(,)19 b(maxsplit)49 b Fn(=)h(0)12 b FC(])p FJ(\))208 183 y FN(Identical)19 b(to)h(the)g FJ(split\(\))g FN(function,)e(using) i(the)g(compiled)f(pattern.)0 330 y FD(findall)p FJ(\()p FK(string)p FC([)p FK(,)g(pos)p FC([)p FK(,)g(endpos)12 b FC(])g(])p FJ(\))208 429 y FN(Identical)19 b(to)h(the)g FJ(findall\(\))f FN(function,)g(using)g(the)i(compiled)d(pattern.)0 576 y FD(finditer)p FJ(\()p FK(string)p FC([)p FK(,)g(pos)p FC([)p FK(,)i(endpos)12 b FC(])g(])p FJ(\))208 676 y FN(Identical)19 b(to)h(the)g FJ(finditer\(\))f FN(function,)f(using)i (the)g(compiled)f(pattern.)0 823 y FD(sub)p FJ(\()p FK(r)m(epl,)g (string)p FC([)p FK(,)i(count)48 b Fn(=)h(0)12 b FC(])p FJ(\))208 922 y FN(Identical)19 b(to)h(the)g FJ(sub\(\))g FN(function,)e(using)i(the)g(compiled)f(pattern.)0 1069 y FD(subn)p FJ(\()p FK(r)m(epl,)g(string)p FC([)p FK(,)h(count)49 b Fn(=)g(0)12 b FC(])p FJ(\))208 1169 y FN(Identical)19 b(to)h(the)g FJ(subn\(\))g FN(function,)e(using)i(the)g(compiled)f (pattern.)0 1316 y FD(flags)208 1415 y FN(The)g(\003ags)i(ar)o(gument)d (used)i(when)f(the)i(RE)f(object)g(w)o(as)h(compiled,)e(or)h FJ(0)g FN(if)h(no)e(\003ags)i(were)f(pro)o(vided.)0 1562 y FD(groupindex)208 1662 y FN(A)k(dictionary)d(mapping)h(an)o(y)h (symbolic)g(group)e(names)j(de\002ned)e(by)2269 1628 y Fp(d)2284 1662 y FJ(\(?P<)p FK(id)r FJ(>\))-10 b Fp(c)12 b FN(to)24 b(group)e(numbers.)34 b(The)23 b(dictionary)f(is)208 1761 y(empty)d(if)h(no)g(symbolic)f(groups)g(were)h(used)g(in)g(the)h (pattern.)0 1908 y FD(pattern)208 2008 y FN(The)e(pattern)h(string)g (from)f(which)g(the)i(RE)f(object)g(w)o(as)h(compiled.)0 2291 y Fv(4.2.5)100 b(Match)28 b(Objects)0 2494 y FJ(MatchObject)19 b FN(instances)h(support)f(the)h(follo)n(wing)e(methods)h(and)h(attrib) n(utes:)0 2641 y FD(expand)p FJ(\()p FK(template)p FJ(\))208 2740 y FN(Return)15 b(the)g(string)h(obtained)e(by)h(doing)g(backslash) g(substitution)g(on)g(the)h(template)f(string)g FK(template)p FN(,)h(as)g(done)f(by)g(the)h FJ(sub\(\))208 2840 y FN(method.)35 b(Escapes)24 b(such)g(as)h(`)p FJ(\\n)p FN(')f(are)g(con)m(v)o(erted)d (to)k(the)f(appropriate)e(characters,)i(and)f(numeric)g(backreferences) f(\(`)p FJ(\\1)p FN(',)208 2940 y(`)p FJ(\\2)p FN('\))j(and)g(named)g (backreferences)f(\(`)p FJ(\\g<1>)p FN(',)h(`)p FJ(\\g)p FN('\))f(are)i(replaced)f(by)h(the)g(contents)f(of)h(the)g (corresponding)208 3039 y(group.)0 3186 y FD(group)p FJ(\()p FC([)p FK(gr)l(oup1,)17 b(...)12 b FC(])p FJ(\))208 3286 y FN(Returns)30 b(one)g(or)g(more)g(subgroups)e(of)i(the)h(match.) 55 b(If)31 b(there)f(is)h(a)g(single)f(ar)o(gument,)h(the)f(result)h (is)g(a)g(single)g(string;)k(if)208 3385 y(there)29 b(are)h(multiple)f (ar)o(guments,)h(the)g(result)f(is)i(a)f(tuple)g(with)g(one)f(item)h (per)f(ar)o(gument.)52 b(W)m(ithout)29 b(ar)o(guments,)h FK(gr)l(oup1)208 3485 y FN(def)o(aults)c(to)g(zero)g(\(the)g(whole)g (match)g(is)h(returned\).)41 b(If)27 b(a)f FK(gr)l(oupN)31 b FN(ar)o(gument)24 b(is)k(zero,)f(the)f(corresponding)d(return)i(v)n (alue)208 3585 y(is)h(the)g(entire)g(matching)e(string;)29 b(if)d(it)g(is)h(in)f(the)g(inclusi)n(v)o(e)f(range)g([1..99],)g(it)h (is)h(the)f(string)g(matching)e(the)i(corresponding)208 3684 y(parenthesized)21 b(group.)31 b(If)23 b(a)g(group)f(number)f(is)j (ne)o(gati)n(v)o(e)c(or)j(lar)o(ger)f(than)g(the)h(number)e(of)i (groups)f(de\002ned)g(in)h(the)g(pattern,)208 3784 y(an)j FJ(IndexError)f FN(e)o(xception)g(is)j(raised.)44 b(If)26 b(a)h(group)e(is)i(contained)e(in)i(a)g(part)f(of)h(the)f(pattern)g (that)h(did)f(not)g(match,)i(the)208 3884 y(corresponding)20 b(result)k(is)h FJ(None)p FN(.)35 b(If)24 b(a)g(group)e(is)j(contained) d(in)i(a)h(part)e(of)h(the)g(pattern)f(that)h(matched)e(multiple)i (times,)h(the)208 3983 y(last)c(match)e(is)i(returned.)208 4114 y(If)16 b(the)g(re)o(gular)e(e)o(xpression)h(uses)i(the)1297 4081 y Fp(d)1312 4114 y FJ(\(?P<)p FK(name)p FJ(>...\))-10 b Fp(c)7 b FN(syntax,)13 b(the)j FK(gr)l(oupN)21 b FN(ar)o(guments)14 b(may)h(also)i(be)f(strings)g(identify-)208 4214 y(ing)f(groups)f(by)h (their)h(group)e(name.)23 b(If)15 b(a)h(string)g(ar)o(gument)d(is)k (not)e(used)h(as)g(a)g(group)e(name)h(in)h(the)g(pattern,)f(an)h FJ(IndexError)208 4314 y FN(e)o(xception)i(is)j(raised.)208 4445 y(A)f(moderately)f(complicated)f(e)o(xample:)444 4667 y FA(m)44 b(=)h(re.match\(r"\(?P\\d+\)\\.\(\\d)1883 4680 y(*)1928 4667 y(\)",)40 b('3.14'\))208 4855 y FN(After)19 b(performing)f(this)i(match,)g FJ(m.group\(1\))f FN(is)i FJ('3')p FN(,)f(as)h(is)g FJ(m.group\('int'\))p FN(,)d(and)h FJ(m.group\(2\))g FN(is)i FJ('14')p FN(.)0 5001 y FD(groups)p FJ(\()p FC([)p FK(default)13 b FC(])p FJ(\))208 5101 y FN(Return)20 b(a)i(tuple)f(containing)e(all)i(the)h(subgroups)d(of)h (the)i(match,)e(from)g(1)h(up)g(to)g(ho)n(we)n(v)o(er)f(man)o(y)g (groups)f(are)i(in)h(the)f(pattern.)208 5201 y(The)i FK(default)h FN(ar)o(gument)d(is)k(used)e(for)g(groups)f(that)i(did)f (not)g(participate)g(in)h(the)f(match;)i(it)f(def)o(aults)g(to)f FJ(None)p FN(.)35 b(\(Incompat-)208 5300 y(ibility)26 b(note:)37 b(in)27 b(the)f(original)g(Python)f(1.5)h(release,)i(if)f (the)f(tuple)g(w)o(as)h(one)f(element)g(long,)h(a)g(string)f(w)o(ould)g (be)g(returned)208 5400 y(instead.)e(In)c(later)g(v)o(ersions)g(\(from) e(1.5.1)h(on\),)g(a)i(singleton)e(tuple)h(is)h(returned)e(in)h(such)g (cases.\))p 0 5549 3901 4 v 0 5649 a FI(60)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 61 73 TeXDict begin 61 72 bop 0 83 a FD(groupdict)p FJ(\()p FC([)p FK(default)13 b FC(])p FJ(\))208 183 y FN(Return)19 b(a)h(dictionary)e(containing)g(all)i(the)g FK(named)f FN(subgroups)e(of)j(the)g(match,)f(k)o(e)o(yed)f(by)i(the)f(subgroup)f (name.)24 b(The)19 b FK(default)208 282 y FN(ar)o(gument)e(is)22 b(used)d(for)h(groups)f(that)h(did)g(not)g(participate)f(in)h(the)g (match;)g(it)h(def)o(aults)f(to)g FJ(None)p FN(.)0 429 y FD(start)p FJ(\()p FC([)p FK(gr)l(oup)12 b FC(])p FJ(\))0 529 y FD(end)p FJ(\()p FC([)p FK(gr)l(oup)g FC(])p FJ(\))208 628 y FN(Return)22 b(the)g(indices)h(of)f(the)g(start)h(and)f(end)g(of) h(the)f(substring)g(matched)f(by)h FK(gr)l(oup)p FN(;)h FK(gr)l(oup)f FN(def)o(aults)g(to)h(zero)f(\(meaning)f(the)208 728 y(whole)f(matched)f(substring\).)26 b(Return)20 b FJ(-1)h FN(if)g FK(gr)l(oup)f FN(e)o(xists)h(b)n(ut)g(did)g(not)f (contrib)n(ute)f(to)i(the)g(match.)26 b(F)o(or)21 b(a)g(match)f(object) g FK(m)p FN(,)208 828 y(and)f(a)i(group)e FK(g)i FN(that)f(did)g (contrib)n(ute)f(to)i(the)f(match,)g(the)g(substring)g(matched)f(by)h (group)f FK(g)h FN(\(equi)n(v)n(alent)f(to)h FK(m)p FJ(.group\()p FK(g)p FJ(\))p FN(\))208 927 y(is)444 1151 y FA (m.string[m.start\(g\):m.end\(g\)])208 1341 y FN(Note)d(that)h FJ(m.start\()p FK(gr)l(oup)p FJ(\))d FN(will)k(equal)e FJ(m.end\()p FK(gr)l(oup)p FJ(\))f FN(if)i FK(gr)l(oup)f FN(matched)f(a)j(null)e(string.)24 b(F)o(or)17 b(e)o(xample,)g(after)g FK(m)50 b FJ(=)208 1441 y(re.search\('b\(c?\)',)c('cba'\))p FN(,)26 b FK(m)p FJ(.start\(0\))e FN(is)i(1,)h FK(m)p FJ(.end\(0\))e FN(is)h(2,)g FK(m)p FJ(.start\(1\))f FN(and)f FK(m)p FJ(.end\(1\))208 1540 y FN(are)c(both)f(2,)h(and)g FK(m)p FJ(.start\(2\))f FN(raises)i(an)f FJ(IndexError)f FN(e)o(xception.)0 1687 y FD(span)p FJ(\()p FC([)p FK(gr)l(oup)12 b FC(])p FJ(\))208 1787 y FN(F)o(or)19 b FJ(MatchObject)e FK(m)p FN(,)j(return)e(the)i(2-tuple)e FJ(\()p FK(m)p FJ(.start\()p FK(gr)l(oup)p FJ(\),)46 b FK(m)p FJ(.end\()p FK(gr)l(oup)p FJ(\)\))p FN(.)23 b(Note)c(that)h(if)f FK(gr)l(oup)g FN(did)g(not)208 1886 y(contrib)n(ute)f(to)j(the)f (match,)f(this)i(is)g FJ(\(-1,)49 b(-1\))p FN(.)25 b(Again,)19 b FK(gr)l(oup)g FN(def)o(aults)h(to)h(zero.)0 2033 y FD(pos)208 2133 y FN(The)e(v)n(alue)g(of)h FK(pos)g FN(which)f(w)o(as)i (passed)f(to)g(the)g FJ(search\(\))f FN(or)g FJ(match\(\))g FN(method)g(of)g(the)h FJ(RegexObject)p FN(.)k(This)c(is)h(the)208 2232 y(inde)o(x)e(into)g(the)i(string)f(at)g(which)g(the)g(RE)h(engine) e(started)h(looking)f(for)g(a)i(match.)0 2379 y FD(endpos)208 2479 y FN(The)e(v)n(alue)h(of)f FK(endpos)g FN(which)h(w)o(as)g(passed) g(to)h(the)f FJ(search\(\))f FN(or)g FJ(match\(\))h FN(method)e(of)i (the)g FJ(RegexObject)p FN(.)j(This)e(is)208 2579 y(the)f(inde)o(x)f (into)h(the)g(string)g(be)o(yond)e(which)h(the)i(RE)f(engine)g(will)g (not)g(go.)0 2725 y FD(lastindex)208 2825 y FN(The)d(inte)o(ger)f(inde) o(x)h(of)g(the)g(last)i(matched)d(capturing)g(group,)g(or)h FJ(None)h FN(if)f(no)h(group)d(w)o(as)k(matched)d(at)i(all.)25 b(F)o(or)17 b(e)o(xample,)g(the)208 2925 y(e)o(xpressions)619 2891 y Fp(d)634 2925 y FJ(\(a\)b)-10 b Fp(c)g FN(,)888 2891 y Fp(d)904 2925 y FJ(\(\(a\)\(b\)\))g Fp(c)g FN(,)23 b(and)1501 2891 y Fp(d)1517 2925 y FJ(\(\(ab\)\))-10 b Fp(c)13 b FN(will)26 b(ha)n(v)o(e)e FJ(lastindex)48 b(==)h(1)25 b FN(if)g(applied)e(to)i(the)g(string)f FJ('ab')p FN(,)208 3024 y(while)c(the)g(e)o(xpression)910 2991 y Fp(d)925 3024 y FJ(\(a\)\(b\))-10 b Fp(c)9 b FN(will)21 b(ha)n(v)o(e)f FJ(lastindex)48 b(==)h(2)p FN(,)21 b(if)f(applied)f(to)i (the)f(same)g(string.)0 3171 y FD(lastgroup)208 3271 y FN(The)25 b(name)h(of)f(the)h(last)h(matched)e(capturing)f(group,)i (or)g FJ(None)f FN(if)i(the)f(group)e(didn')o(t)g(ha)n(v)o(e)i(a)g (name,)h(or)f(if)g(no)f(group)g(w)o(as)208 3370 y(matched)19 b(at)h(all.)0 3517 y FD(re)208 3617 y FN(The)d(re)o(gular)g(e)o (xpression)g(object)g(whose)h FJ(match\(\))g FN(or)g FJ(search\(\))f FN(method)g(produced)f(this)i FJ(MatchObject)f FN(instance.)0 3764 y FD(string)208 3863 y FN(The)i(string)h(passed)g (to)h FJ(match\(\))e FN(or)h FJ(search\(\))p FN(.)0 4148 y Fv(4.2.6)100 b(Examples)0 4304 y FL(Simulating)20 b FD(scanf\(\))0 4451 y FN(Python)f(does)i(not)f(currently)e(ha)n(v)o(e)i (an)h(equi)n(v)n(alent)d(to)j FJ(scanf\(\))p FN(.)k(Re)o(gular)20 b(e)o(xpressions)f(are)h(generally)f(more)h(po)n(werful,)e(though)0 4550 y(also)28 b(more)f(v)o(erbose,)i(than)e FJ(scanf\(\))g FN(format)g(strings.)49 b(The)27 b(table)h(belo)n(w)g(of)n(fers)f(some) g(more-or)n(-less)g(equi)n(v)n(alent)f(mappings)0 4650 y(between)19 b FJ(scanf\(\))h FN(format)f(tok)o(ens)h(and)f(re)o(gular) g(e)o(xpressions.)p 0 5549 3901 4 v 0 5649 a FI(4.2.)52 b FJ(re)23 b FI(\227)g(Regular)h(e)n(xpression)e(oper)o(ations)2267 b(61)p eop end %%Page: 62 74 TeXDict begin 62 73 bop 624 70 a FD(scanf\(\))19 b FL(T)-8 b(ok)o(en)p 1259 100 4 100 v 101 w(Regular)19 b(Expr)o(ession)p 574 103 2752 4 v 624 173 a FJ(\045c)p 1259 203 4 100 v 1311 139 a Fp(d)1326 173 y FJ(.)-10 b Fp(c)624 272 y FJ(\0455c)p 1259 302 V 1311 239 a Fp(d)1326 272 y FJ(.{5})g Fp(c)624 372 y FJ(\045d)p 1259 402 V 1311 338 a Fp(d)1326 372 y FJ([-+]?\\d+)g Fp(c)624 472 y FJ(\045e)p FN(,)20 b FJ(\045E)p FN(,)g FJ(\045f)p FN(,)g FJ(\045g)p 1259 501 V 1311 438 a Fp(d)1326 472 y FJ([-+]?\(\\d+\(\\.\\d)2026 487 y(*)2076 472 y(\)?|\\.\\d+\)\([eE][-+]?\\d)o(+\)?)-10 b Fp(c)624 571 y FJ(\045i)p 1259 601 V 1311 538 a Fp(d)1326 571 y FJ([-+]?\(0[xX][\\dA-Fa-f]+|0[0-7])2776 586 y(*)2826 571 y(|\\d+\))f Fp(c)624 671 y FJ(\045o)p 1259 701 V 1311 637 a Fp(d)1326 671 y FJ(0[0-7])1626 686 y(*)1666 671 y Fp(c)624 770 y FJ(\045s)p 1259 800 V 1311 737 a Fp(d)1326 770 y FJ(\\S+)h Fp(c)624 870 y FJ(\045u)p 1259 900 V 1311 837 a Fp(d)1326 870 y FJ(\\d+)g Fp(c)624 970 y FJ(\045x)p FN(,)20 b FJ(\045X)p 1259 1000 V 1311 936 a Fp(d)1326 970 y FJ(0[xX][\\dA-Fa-f]+)-10 b Fp(c)0 1195 y FN(T)j(o)20 b(e)o(xtract)g(the)g(\002lename)g(and)f(numbers)g(from)g (a)i(string)f(lik)o(e)416 1433 y FA(/usr/sbin/sendmail)41 b(-)k(0)g(errors,)e(4)i(warnings)0 1719 y FN(you)19 b(w)o(ould)h(use)g (a)h FJ(scanf\(\))e FN(format)g(lik)o(e)416 1958 y FA(\045s)44 b(-)h(\045d)f(errors,)g(\045d)g(warnings)0 2244 y FN(The)20 b(equi)n(v)n(alent)e(re)o(gular)h(e)o(xpression)g(w)o(ould)g(be)416 2482 y FA(\(\\S+\))44 b(-)g(\(\\d+\))g(errors,)g(\(\\d+\))g(warnings)0 2722 y FL(A)-8 b(v)o(oiding)20 b(r)o(ecursion)0 2869 y FN(If)40 b(you)f(create)g(re)o(gular)g(e)o(xpressions)f(that)i (require)f(the)g(engine)g(to)h(perform)e(a)i(lot)g(of)g(recursion,)j (you)c(may)g(encounter)f(a)0 2969 y FJ(RuntimeError)19 b FN(e)o(xception)f(with)i(the)g(message)g FJ(maximum)49 b(recursion)f(limit)20 b FN(e)o(xceeded.)j(F)o(or)d(e)o(xample,)236 3207 y FA(>>>)45 b(import)e(re)236 3298 y(>>>)i(s)f(=)h('Begin)f(')g(+) h(1000)1268 3311 y(*)1313 3298 y('a)f(very)g(long)g(string)g(')g(+)h ('end')236 3390 y(>>>)g(re.match\('Begin)d(\(\\w|)i(\))1402 3403 y(*)1447 3390 y(?)g(end',)g(s\).end\(\))236 3481 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 3572 y(File)f("",)f(line)h(1,)h(in)f(?)326 3664 y(File)g ("/usr/local/lib/python2.5/re.py",)39 b(line)44 b(132,)h(in)f(match)416 3755 y(return)f(_compile\(pattern,)f(flags\).match\(string\))236 3846 y(RuntimeError:)h(maximum)h(recursion)f(limit)h(exceeded)0 4133 y FN(Y)-9 b(ou)20 b(can)g(often)f(restructure)g(your)g(re)o(gular) f(e)o(xpression)h(to)h(a)n(v)n(oid)g(recursion.)0 4280 y(Starting)h(with)h(Python)e(2.3,)h(simple)g(uses)h(of)f(the)1482 4246 y Fp(d)1497 4295 y FJ(*)1547 4280 y(?)-10 b Fp(c)11 b FN(pattern)21 b(are)g(special-cased)g(to)g(a)n(v)n(oid)h(recursion.) 27 b(Thus,)21 b(the)g(abo)o(v)o(e)f(re)o(gular)0 4379 y(e)o(xpression)28 b(can)h(a)n(v)n(oid)h(recursion)e(by)h(being)f (recast)i(as)1730 4346 y Fp(d)1746 4379 y FJ(Begin)49 b([a-zA-Z0-9_)f(])2693 4394 y(*)2743 4379 y(?end)-10 b Fp(c)g FN(.)51 b(As)31 b(a)f(further)e(bene\002t,)j(such)0 4479 y(re)o(gular)19 b(e)o(xpressions)g(will)h(run)g(f)o(aster)g(than)g (their)g(recursi)n(v)o(e)f(equi)n(v)n(alents.)0 4806 y FE(4.3)121 b Fx(struct)31 b FE(\227)i(Inter)t(pret)i(str)r(ings)e(as) h(pac)n(k)n(ed)g(binar)t(y)f(data)0 5039 y FN(This)21 b(module)f(performs)f(con)m(v)o(ersions)g(between)h(Python)g(v)n(alues) h(and)f(C)j(structs)e(represented)e(as)j(Python)e(strings.)28 b(It)21 b(uses)h FK(format)0 5139 y(strings)g FN(\(e)o(xplained)e(belo) n(w\))h(as)h(compact)f(descriptions)g(of)g(the)h(lay-out)e(of)i(the)g (C)g(structs)h(and)e(the)h(intended)e(con)m(v)o(ersion)f(to/from)0 5238 y(Python)26 b(v)n(alues.)44 b(This)27 b(can)g(be)g(used)f(in)h (handling)e(binary)h(data)g(stored)h(in)g(\002les)h(or)e(from)g(netw)o (ork)g(connections,)g(among)f(other)0 5338 y(sources.)p 0 5549 3901 4 v 0 5649 a FI(62)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 63 75 TeXDict begin 63 74 bop 0 83 a FN(The)20 b(module)f(de\002nes)h(the)g (follo)n(wing)e(e)o(xception)h(and)g(functions:)0 230 y FL(exception)g FD(error)208 330 y FN(Exception)f(raised)i(on)g(v)n (arious)f(occasions;)g(ar)o(gument)f(is)j(a)g(string)f(describing)f (what)h(is)h(wrong.)0 476 y FD(pack)p FJ(\()p FK(fmt,)f(v1,)g(v2,)f(.) 12 b(.)g(.)g FJ(\))208 576 y FN(Return)20 b(a)i(string)e(containing)f (the)i(v)n(alues)g FK(v1)p FJ(,)49 b FK(v2)p FJ(,)g FN(.)12 b(.)g(.)41 b(pack)o(ed)20 b(according)f(to)i(the)g(gi)n(v)o(en)f (format.)26 b(The)21 b(ar)o(guments)e(must)208 676 y(match)g(the)h(v)n (alues)g(required)f(by)g(the)i(format)e(e)o(xactly)-5 b(.)0 823 y FD(pack_into)p FJ(\()p FK(fmt,)19 b(b)n(uf)o(fer)-9 b(,)19 b(of)o(fset,)h(v1,)g(v2,)g(...)p FJ(\))208 922 y FN(P)o(ack)27 b(the)g(v)n(alues)g FK(v1)p FJ(,)49 b FK(v2)p FJ(,)g FN(.)12 b(.)g(.)60 b(according)26 b(to)h(the)h(gi)n(v)o (en)e(format,)i(write)f(the)h(pack)o(ed)e(bytes)h(into)g(the)h (writable)f FK(b)n(uf)o(fer)208 1022 y FN(starting)19 b(at)i FK(of)o(fset)q FN(.)k(Note)c(that)f(the)g(of)n(fset)g(is)h(not)f (an)g(optional)f(ar)o(gument.)208 1151 y(Ne)n(w)h(in)g(v)o(ersion)f (2.5.)0 1298 y FD(unpack)p FJ(\()p FK(fmt,)g(string)p FJ(\))208 1398 y FN(Unpack)26 b(the)h(string)g(\(presumably)e(pack)o (ed)h(by)h FJ(pack\()p FK(fmt)q FJ(,)49 b FN(.)12 b(.)g(.)g FJ(\))p FN(\))47 b(according)25 b(to)i(the)h(gi)n(v)o(en)e(format.)45 b(The)27 b(result)g(is)h(a)208 1497 y(tuple)c(e)n(v)o(en)f(if)i(it)g (contains)f(e)o(xactly)g(one)g(item.)38 b(The)24 b(string)g(must)h (contain)f(e)o(xactly)f(the)i(amount)e(of)h(data)h(required)d(by)j(the) 208 1597 y(format)19 b(\()p FJ(len\()p FK(string)p FJ(\))g FN(must)h(equal)g FJ(calcsize\()p FK(fmt)q FJ(\))p FN(\).)0 1744 y FD(unpack_from)p FJ(\()p FK(fmt,)e(b)n(uf)o(fer)r FC([)p FK(,of)o(fset)h Fn(=)50 b(0)12 b FC(])p FJ(\))208 1843 y FN(Unpack)19 b(the)i FK(b)n(uf)o(fer)i FN(according)18 b(to)j(tthe)g(gi)n(v)o(en)f(format.)26 b(The)20 b(result)h(is)h(a)f (tuple)g(e)n(v)o(en)f(if)h(it)g(contains)g(e)o(xactly)e(one)i(item.)27 b(The)208 1943 y FK(b)n(uf)o(fer)e FN(must)f(contain)e(at)j(least)f (the)g(amount)e(of)i(data)f(required)f(by)i(the)f(format)g(\()p FJ(len\(buffer[offset:]\))29 b FN(must)24 b(be)208 2043 y(at)c(least)h FJ(calcsize\()p FK(fmt)q FJ(\))p FN(\).)208 2172 y(Ne)n(w)f(in)g(v)o(ersion)f(2.5.)0 2319 y FD(calcsize)p FJ(\()p FK(fmt)q FJ(\))208 2418 y FN(Return)g(the)i(size)f(of)g(the)g (struct)h(\(and)e(hence)g(of)h(the)g(string\))g(corresponding)d(to)j (the)g(gi)n(v)o(en)f(format.)0 2565 y(F)o(ormat)h(characters)f(ha)n(v)o (e)h(the)h(follo)n(wing)e(meaning;)g(the)i(con)m(v)o(ersion)d(between)i (C)h(and)f(Python)g(v)n(alues)g(should)f(be)i(ob)o(vious)e(gi)n(v)o(en) 0 2665 y(their)h(types:)836 2873 y FL(F)n(ormat)p 1149 2903 4 100 v 98 w(C)g(T)-6 b(ype)p 2145 2903 V 742 w(Python)p 2815 2903 V 414 w(Notes)p 786 2907 2329 4 v 916 2976 a FN(`)p FJ(x)p FN(')p 1149 3006 4 100 v 179 w(pad)19 b(byte)p 2145 3006 V 712 w(no)h(v)n(alue)p 2815 3006 V 916 3076 a(`)p FJ(c)p FN(')p 1149 3106 V 179 w FJ(char)p 2145 3106 V 796 w FN(string)g(of)g(length)f(1)p 2815 3106 V 916 3176 a(`)p FJ(b)p FN(')p 1149 3205 V 179 w FJ(signed)48 b(char)p 2145 3205 V 448 w FN(inte)o(ger)p 2815 3205 V 916 3275 a(`)p FJ(B)p FN(')p 1149 3305 V 179 w FJ(unsigned)g(char)p 2145 3305 V 348 w FN(inte)o(ger)p 2815 3305 V 916 3375 a(`)p FJ(h)p FN(')p 1149 3405 V 179 w FJ(short)p 2145 3405 V 746 w FN(inte)o(ger)p 2815 3405 V 916 3474 a(`)p FJ(H)p FN(')p 1149 3504 V 179 w FJ(unsigned)g(short)p 2145 3504 V 298 w FN(inte)o(ger)p 2815 3504 V 916 3574 a(`)p FJ(i)p FN(')p 1149 3604 V 179 w FJ(int)p 2145 3604 V 846 w FN(inte)o(ger)p 2815 3604 V 916 3674 a(`)p FJ(I)p FN(')p 1149 3704 V 179 w FJ(unsigned)g(int)p 2145 3704 V 398 w FN(long)p 2815 3704 V 916 3773 a(`)p FJ(l)p FN(')p 1149 3803 V 179 w FJ(long)p 2145 3803 V 796 w FN(inte)o(ger)p 2815 3803 V 916 3873 a(`)p FJ(L)p FN(')p 1149 3903 V 179 w FJ(unsigned)g(long)p 2145 3903 V 348 w FN(long)p 2815 3903 V 916 3973 a(`)p FJ(q)p FN(')p 1149 4002 V 179 w FJ(long)h(long)p 2145 4002 V 547 w FN(long)p 2815 4002 V 571 w(\(1\))916 4072 y(`)p FJ(Q)p FN(')p 1149 4102 V 179 w FJ(unsigned)f(long)h(long)p 2145 4102 V 99 w FN(long)p 2815 4102 V 571 w(\(1\))916 4172 y(`)p FJ(f)p FN(')p 1149 4202 V 179 w FJ(float)p 2145 4202 V 746 w FN(\003oat)p 2815 4202 V 916 4271 a(`)p FJ(d)p FN(')p 1149 4301 V 179 w FJ(double)p 2145 4301 V 696 w FN(\003oat)p 2815 4301 V 916 4371 a(`)p FJ(s)p FN(')p 1149 4401 V 179 w FJ(char[])p 2145 4401 V 696 w FN(string)p 2815 4401 V 916 4471 a(`)p FJ(p)p FN(')p 1149 4501 V 179 w FJ(char[])p 2145 4501 V 696 w FN(string)p 2815 4501 V 916 4570 a(`)p FJ(P)p FN(')p 1149 4600 V 179 w FJ(void)1450 4585 y(*)p 2145 4600 V 2197 4570 a FN(inte)o(ger)p 2815 4600 V 0 4776 a(Notes:)0 4989 y FL(\(1\))40 b FN(The)22 b(`)p FJ(q)p FN(')g(and)g(`)p FJ(Q)p FN(')g(con)m(v)o(ersion)e(codes)i(are)g(a)n(v)n(ailable)g(in)h (nati)n(v)o(e)e(mode)g(only)h(if)h(the)f(platform)f(C)i(compiler)e (supports)g(C)j FJ(long)208 5088 y(long)p FN(,)19 b(or)m(,)h(on)f(W)m (indo)n(ws,)h FJ(__int64)p FN(.)k(The)o(y)19 b(are)h(al)o(w)o(ays)h(a)n (v)n(ailable)f(in)g(standard)f(modes.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 5300 y(A)j(format)d(character)h(may)h(be)g (preceded)e(by)h(an)h(inte)o(gral)f(repeat)h(count.)26 b(F)o(or)21 b(e)o(xample,)e(the)i(format)f(string)h FJ('4h')g FN(means)f(e)o(xactly)0 5400 y(the)g(same)h(as)f FJ('hhhh')p FN(.)p 0 5549 3901 4 v 0 5649 a FI(4.3.)52 b FJ(struct)22 b FI(\227)h(Inter)r(pret)h(str)q(ings)f(as)f(pac)n(k)n(ed)i(binar)r(y)g (data)1775 b(63)p eop end %%Page: 64 76 TeXDict begin 64 75 bop 0 83 a FN(Whitespace)20 b(characters)f(between) h(formats)f(are)h(ignored;)f(a)h(count)f(and)h(its)h(format)e(must)i (not)f(contain)f(whitespace)g(though.)0 230 y(F)o(or)e(the)g(`)p FJ(s)p FN(')g(format)f(character)m(,)g(the)i(count)e(is)i(interpreted)e (as)i(the)f(size)h(of)f(the)g(string,)g(not)g(a)h(repeat)f(count)f(lik) o(e)h(for)g(the)g(other)g(format)0 330 y(characters;)24 b(for)f(e)o(xample,)f FJ('10s')h FN(means)g(a)h(single)f(10-byte)f (string,)h(while)h FJ('10c')f FN(means)g(10)g(characters.)33 b(F)o(or)23 b(packing,)g(the)0 429 y(string)g(is)h(truncated)e(or)i (padded)d(with)j(null)f(bytes)g(as)h(appropriate)d(to)j(mak)o(e)f(it)h (\002t.)36 b(F)o(or)23 b(unpacking,)e(the)i(resulting)g(string)g(al)o (w)o(ays)0 529 y(has)f(e)o(xactly)e(the)h(speci\002ed)h(number)d(of)i (bytes.)28 b(As)23 b(a)e(special)h(case,)g FJ('0s')f FN(means)g(a)h(single,)f(empty)g(string)g(\(while)g FJ('0c')g FN(means)0 628 y(0)f(characters\).)0 775 y(The)g(`)p FJ(p)p FN(')f(format)g(character)g(encodes)g(a)i(\224P)o(ascal)f (string\224,)f(meaning)g(a)h(short)g(v)n(ariable-length)d(string)j (stored)g(in)g(a)g(\002x)o(ed)g(number)e(of)0 875 y(bytes.)25 b(The)19 b(count)g(is)i(the)e(total)h(number)e(of)i(bytes)f(stored.)25 b(The)19 b(\002rst)i(byte)e(stored)g(is)i(the)f(length)f(of)g(the)h (string,)f(or)h(255,)f(whiche)n(v)o(er)0 975 y(is)k(smaller)-5 b(.)31 b(The)21 b(bytes)h(of)g(the)g(string)g(follo)n(w)-5 b(.)29 b(If)22 b(the)g(string)g(passed)f(in)i(to)f FJ(pack\(\))f FN(is)i(too)f(long)f(\(longer)f(than)i(the)g(count)f(minus)0 1074 y(1\),)i(only)g(the)g(leading)f(count-1)g(bytes)h(of)g(the)g (string)g(are)g(stored.)33 b(If)23 b(the)h(string)f(is)h(shorter)e (than)h(count-1,)f(it)i(is)g(padded)d(with)j(null)0 1174 y(bytes)f(so)g(that)g(e)o(xactly)g(count)f(bytes)h(in)g(all)g(are)g (used.)34 b(Note)23 b(that)g(for)f FJ(unpack\(\))p FN(,)h(the)g(`)p FJ(p)p FN(')g(format)f(character)f(consumes)i(count)0 1273 y(bytes,)d(b)n(ut)g(that)g(the)g(string)g(returned)f(can)h(ne)n(v) o(er)f(contain)g(more)g(than)h(255)f(characters.)0 1420 y(F)o(or)h(the)g(`)p FJ(I)p FN(',)g(`)p FJ(L)p FN(',)f(`)p FJ(q)p FN(')h(and)g(`)p FJ(Q)p FN(')g(format)f(characters,)g(the)h (return)f(v)n(alue)g(is)j(a)e(Python)f(long)h(inte)o(ger)-5 b(.)0 1567 y(F)o(or)20 b(the)g(`)p FJ(P)p FN(')f(format)g(character)m (,)f(the)i(return)f(v)n(alue)h(is)h(a)f(Python)f(inte)o(ger)g(or)g (long)h(inte)o(ger)m(,)e(depending)f(on)j(the)g(size)h(needed)d(to)i (hold)0 1667 y(a)25 b(pointer)d(when)i(it)h(has)f(been)g(cast)g(to)h (an)f(inte)o(ger)f(type.)36 b(A)25 b FJ(NULL)f FN(pointer)f(will)h(al)o (w)o(ays)h(be)f(returned)e(as)j(the)f(Python)f(inte)o(ger)g FJ(0)p FN(.)0 1766 y(When)f(packing)f(pointer)n(-sized)f(v)n(alues,)i (Python)f(inte)o(ger)g(or)h(long)g(inte)o(ger)f(objects)h(may)f(be)i (used.)30 b(F)o(or)22 b(e)o(xample,)f(the)h(Alpha)g(and)0 1866 y(Merced)j(processors)g(use)i(64-bit)e(pointer)f(v)n(alues,)j (meaning)e(a)h(Python)f(long)g(inte)o(ger)g(will)i(be)f(used)g(to)g (hold)f(the)i(pointer;)g(other)0 1966 y(platforms)19 b(use)h(32-bit)f(pointers)h(and)f(will)i(use)g(a)f(Python)f(inte)o(ger) -5 b(.)0 2113 y(By)18 b(def)o(ault,)g(C)h(numbers)d(are)i(represented)e (in)i(the)g(machine')-5 b(s)17 b(nati)n(v)o(e)g(format)g(and)g(byte)h (order)m(,)e(and)i(properly)e(aligned)g(by)i(skipping)0 2212 y(pad)i(bytes)g(if)g(necessary)g(\(according)d(to)k(the)f(rules)g (used)g(by)g(the)g(C)h(compiler\).)0 2359 y(Alternati)n(v)o(ely)-5 b(,)21 b(the)i(\002rst)h(character)e(of)g(the)h(format)f(string)h(can)g (be)g(used)f(to)h(indicate)g(the)g(byte)f(order)m(,)g(size)i(and)e (alignment)g(of)h(the)0 2459 y(pack)o(ed)c(data,)h(according)e(to)i (the)h(follo)n(wing)d(table:)947 2685 y FL(Character)p 1359 2715 4 100 v 97 w(Byte)j(order)p 2228 2715 V 488 w(Size)g(and)f(alignment)p 897 2718 2107 4 v 1076 2788 a FN(`)p FJ(@)p FN(')p 1359 2818 4 100 v 228 w(nati)n(v)o(e)p 2228 2818 V 669 w(nati)n(v)o(e)1076 2887 y(`)p FJ(=)p FN(')p 1359 2917 V 228 w(nati)n(v)o(e)p 2228 2917 V 669 w(standard)1076 2987 y(`)p FJ(<)p FN(')p 1359 3017 V 228 w(little-endian)p 2228 3017 V 467 w(standard)1076 3087 y(`)p FJ(>)p FN(')p 1359 3117 V 228 w(big-endian)p 2228 3117 V 512 w(standard)1076 3186 y(`)p FJ(!)p FN(')p 1359 3216 V 228 w(netw)o(ork)f(\(=)i(big-endian\))p 2228 3216 V 96 w(standard)0 3411 y(If)f(the)g(\002rst)h(character)e(is)i (not)f(one)g(of)g(these,)g(`)p FJ(@)p FN(')g(is)h(assumed.)0 3558 y(Nati)n(v)o(e)j(byte)f(order)g(is)i(big-endian)c(or)j (little-endian,)f(depending)f(on)h(the)h(host)g(system.)36 b(F)o(or)24 b(e)o(xample,)f(Motorola)g(and)g(Sun)h(pro-)0 3658 y(cessors)d(are)f(big-endian;)e(Intel)h(and)h(DEC)h(processors)e (are)h(little-endian.)0 3805 y(Nati)n(v)o(e)h(size)h(and)f(alignment)f (are)h(determined)f(using)g(the)i(C)g(compiler')-5 b(s)21 b FJ(sizeof)f FN(e)o(xpression.)27 b(This)22 b(is)g(al)o(w)o(ays)g (combined)d(with)0 3904 y(nati)n(v)o(e)g(byte)h(order)-5 b(.)0 4051 y(Standard)26 b(size)j(and)e(alignment)f(are)i(as)g(follo)n (ws:)40 b(no)27 b(alignment)f(is)j(required)d(for)h(an)o(y)g(type)g (\(so)g(you)g(ha)n(v)o(e)g(to)h(use)g(pad)f(bytes\);)0 4151 y FJ(short)17 b FN(is)g(2)g(bytes;)h FJ(int)f FN(and)f FJ(long)h FN(are)g(4)g(bytes;)h FJ(long)49 b(long)16 b FN(\()p FJ(__int64)g FN(on)h(W)m(indo)n(ws\))f(is)h(8)g(bytes;)h FJ(float)f FN(and)f FJ(double)0 4251 y FN(are)k(32-bit)f(and)h(64-bit)f (IEEE)h(\003oating)f(point)g(numbers,)g(respecti)n(v)o(ely)-5 b(.)0 4397 y(Note)24 b(the)h(dif)n(ference)d(between)i(`)p FJ(@)p FN(')g(and)g(`)p FJ(=)p FN(':)33 b(both)24 b(use)g(nati)n(v)o(e) g(byte)g(order)m(,)f(b)n(ut)i(the)f(size)h(and)f(alignment)f(of)h(the)h (latter)f(is)i(stan-)0 4497 y(dardized.)0 4644 y(The)16 b(form)e(`)p FJ(!)p FN(')24 b(is)17 b(a)n(v)n(ailable)e(for)g(those)h (poor)f(souls)h(who)f(claim)h(the)o(y)f(can')o(t)g(remember)f(whether)h (netw)o(ork)g(byte)g(order)g(is)i(big-endian)0 4744 y(or)j (little-endian.)0 4890 y(There)f(is)i(no)f(w)o(ay)h(to)f(indicate)f (non-nati)n(v)o(e)f(byte)i(order)f(\(force)g(byte-sw)o(apping\);)e(use) j(the)h(appropriate)c(choice)j(of)g(`)p FJ(<)p FN(')g(or)g(`)p FJ(>)p FN('.)0 5037 y(The)d(`)p FJ(P)p FN(')h(format)e(character)h(is)h (only)f(a)n(v)n(ailable)g(for)g(the)h(nati)n(v)o(e)f(byte)g(ordering)e (\(selected)j(as)g(the)g(def)o(ault)e(or)i(with)g(the)f(`)p FJ(@)p FN(')h(byte)f(order)0 5137 y(character\).)36 b(The)24 b(byte)g(order)f(character)g(`)p FJ(=)p FN(')h(chooses)g(to)g(use)h (little-)g(or)f(big-endian)e(ordering)g(based)i(on)g(the)g(host)g (system.)38 b(The)0 5237 y(struct)20 b(module)f(does)h(not)g(interpret) f(this)i(as)f(nati)n(v)o(e)g(ordering,)e(so)i(the)g(`)p FJ(P)p FN(')g(format)f(is)i(not)f(a)n(v)n(ailable.)0 5383 y(Examples)f(\(all)i(using)e(nati)n(v)o(e)h(byte)f(order)m(,)g (size)i(and)e(alignment,)g(on)h(a)g(big-endian)e(machine\):)p 0 5549 3901 4 v 0 5649 a FI(64)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 65 77 TeXDict begin 65 76 bop 236 174 a FA(>>>)45 b(from)f(struct)g(import) 1267 187 y(*)236 266 y(>>>)h(pack\('hhl',)e(1,)h(2,)h(3\))236 357 y('\\x00\\x01\\x00\\x02\\x00\\x00\\x00\\x03')236 448 y(>>>)g(unpack\('hhl',)d ('\\x00\\x01\\x00\\x02\\x00\\x00\\x00\\x03'\))236 540 y(\(1,)j(2,)f(3\))236 631 y(>>>)h(calcsize\('hhl'\))236 722 y(8)0 1009 y FN(Hint:)25 b(to)20 b(align)f(the)h(end)f(of)g(a)h (structure)f(to)g(the)h(alignment)e(requirement)f(of)j(a)g(particular)e (type,)h(end)g(the)h(format)e(with)i(the)f(code)g(for)0 1108 y(that)h(type)g(with)h(a)f(repeat)g(count)f(of)h(zero.)25 b(F)o(or)19 b(e)o(xample,)g(the)h(format)f FJ('llh0l')h FN(speci\002es)h(tw)o(o)f(pad)g(bytes)g(at)h(the)f(end,)f(assuming)0 1208 y(longs)k(are)h(aligned)e(on)i(4-byte)e(boundaries.)33 b(This)24 b(only)f(w)o(orks)g(when)g(nati)n(v)o(e)g(size)i(and)e (alignment)f(are)i(in)f(ef)n(fect;)i(standard)e(size)0 1308 y(and)d(alignment)e(does)i(not)g(enforce)f(an)o(y)g(alignment.)0 1455 y FL(See)i(Also:)0 1601 y FN(Module)e FJ(array)h FN(\(section)f(5.6\):)208 1701 y(P)o(ack)o(ed)g(binary)g(storage)g(of)h (homogeneous)d(data.)0 1848 y(Module)i FJ(xdrlib)h FN(\(section)f (9.5\):)208 1948 y(P)o(acking)g(and)g(unpacking)f(of)i(XDR)h(data.)0 2232 y Fv(4.3.1)100 b(Str)q(uct)29 b(Objects)0 2435 y FN(The)20 b FJ(struct)f FN(module)g(also)i(de\002nes)f(the)g(follo)n (wing)f(type:)0 2582 y FL(class)i FD(Struct)p FJ(\()p FK(format)q FJ(\))208 2682 y FN(Return)h(a)h(ne)n(w)g(Struct)f(object)h (which)f(writes)h(and)f(reads)h(binary)f(data)g(according)f(to)i(the)g (format)e(string)i FK(format)q FN(.)33 b(Creating)208 2781 y(a)22 b(Struct)f(object)g(once)g(and)g(calling)g(its)h(methods)f (is)h(more)f(ef)n(\002cient)g(than)g(calling)g(the)h FJ(struct)f FN(functions)f(with)i(the)f(same)208 2881 y(format)e(since)h(the)g(format)f(string)h(only)g(needs)f(to)i(be)f (compiled)f(once.)208 3014 y(Ne)n(w)h(in)g(v)o(ersion)f(2.5.)0 3161 y(Compiled)g(Struct)h(objects)g(support)f(the)h(follo)n(wing)f (methods)g(and)h(attrib)n(utes:)0 3308 y FD(pack)p FJ(\()p FK(v1,)f(v2,)h(...)p FJ(\))208 3407 y FN(Identical)f(to)h(the)g FJ(pack\(\))g FN(function,)e(using)i(the)g(compiled)f(format.)24 b(\()p FJ(len\(result\))18 b FN(will)j(equal)f FJ(self.size)p FN(.\))0 3554 y FD(pack_into)p FJ(\()p FK(b)n(uf)o(fer)-9 b(,)18 b(of)o(fset,)i(v1,)f(v2,)h(...)p FJ(\))208 3654 y FN(Identical)f(to)h(the)g FJ(pack_into\(\))f FN(function,)f(using)i (the)g(compiled)f(format.)0 3801 y FD(unpack)p FJ(\()p FK(string)p FJ(\))208 3900 y FN(Identical)g(to)h(the)g FJ(unpack\(\))g FN(function,)e(using)h(the)i(compiled)d(format.)24 b(\()p FJ(len\(string\))19 b FN(must)h(equal)f FJ(self.size)p FN(\).)0 4047 y FD(unpack_from)p FJ(\()p FK(b)n(uf)o(fer)r FC([)p FK(,of)o(fset)e Fn(=)49 b(0)12 b FC(])p FJ(\))208 4147 y FN(Identical)23 b(to)i(the)f FJ(unpack_from\(\))e FN(function,)i(using)g(the)g(compiled)f(format.)36 b(\()p FJ(len\(buffer[offset:]\))31 b FN(must)208 4246 y(be)20 b(at)g(least)h FJ(self.size)p FN(\).)0 4393 y FD(format)208 4493 y FN(The)e(format)g(string)h(used)g(to)h(construct)e(this)h (Struct)h(object.)0 4820 y FE(4.4)121 b Fx(difflib)31 b FE(\227)i(Helpers)h(f)l(or)g(computing)h(deltas)0 5053 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 5200 y FL(class)i FD(SequenceMatcher)208 5300 y FN(This)30 b(is)g(a)h(\003e)o(xible)e (class)i(for)e(comparing)e(pairs)j(of)g(sequences)f(of)g(an)o(y)g (type,)j(so)e(long)f(as)i(the)e(sequence)g(elements)h(are)208 5399 y(hashable.)25 b(The)20 b(basic)h(algorithm)e(predates,)h(and)g (is)i(a)f(little)h(f)o(ancier)e(than,)g(an)g(algorithm)f(published)h (in)g(the)h(late)g(1980')-5 b(s)20 b(by)p 0 5549 3901 4 v 0 5649 a FI(4.4.)52 b FJ(difflib)22 b FI(\227)h(Helpers)g(f)n(or)g (computing)h(deltas)2086 b(65)p eop end %%Page: 66 78 TeXDict begin 66 77 bop 208 83 a FN(Ratclif)n(f)17 b(and)f(Obershelp)g (under)f(the)i(hyperbolic)d(name)j(\223gestalt)g(pattern)f(matching.)-6 b(\224)22 b(The)17 b(idea)g(is)g(to)h(\002nd)e(the)h(longest)f(con-)208 183 y(tiguous)22 b(matching)g(subsequence)f(that)j(contains)f(no)f (\223junk\224)h(elements)g(\(the)g(Ratclif)n(f)g(and)g(Obershelp)f (algorithm)g(doesn')o(t)208 282 y(address)17 b(junk\).)23 b(The)18 b(same)h(idea)f(is)h(then)f(applied)f(recursi)n(v)o(ely)f(to)j (the)f(pieces)g(of)g(the)g(sequences)g(to)g(the)g(left)h(and)f(to)g (the)g(right)208 382 y(of)k(the)i(matching)d(subsequence.)32 b(This)24 b(does)f(not)f(yield)h(minimal)g(edit)g(sequences,)g(b)n(ut)g (does)g(tend)g(to)g(yield)g(matches)f(that)208 482 y(\223look)d (right\224)g(to)i(people.)208 614 y FL(T)o(iming:)50 b FN(The)32 b(basic)g(Ratclif)n(f-Obershelp)f(algorithm)g(is)i(cubic)f (time)h(in)g(the)f(w)o(orst)h(case)g(and)f(quadratic)f(time)i(in)g(the) 208 714 y(e)o(xpected)22 b(case.)38 b FJ(SequenceMatcher)22 b FN(is)j(quadratic)e(time)i(for)e(the)i(w)o(orst)f(case)h(and)f(has)g (e)o(xpected-case)e(beha)n(vior)h(de-)208 814 y(pendent)18 b(in)j(a)f(complicated)f(w)o(ay)h(on)g(ho)n(w)f(man)o(y)g(elements)h (the)g(sequences)g(ha)n(v)o(e)f(in)i(common;)d(best)j(case)f(time)h(is) g(linear)-5 b(.)0 960 y FL(class)21 b FD(Differ)208 1060 y FN(This)k(is)i(a)f(class)h(for)e(comparing)e(sequences)i(of)h(lines)g (of)f(te)o(xt,)i(and)e(producing)e(human-readable)f(dif)n(ferences)i (or)i(deltas.)208 1160 y(Dif)n(fer)20 b(uses)i FJ(SequenceMatcher)d FN(both)i(to)g(compare)f(sequences)h(of)g(lines,)h(and)f(to)g(compare)f (sequences)g(of)i(characters)208 1259 y(within)e(similar)g(\(near)n (-matching\))d(lines.)208 1392 y(Each)i(line)i(of)e(a)i FJ(Differ)f FN(delta)g(be)o(gins)f(with)i(a)f(tw)o(o-letter)g(code:) 1218 1521 y FL(Code)p 1515 1551 4 100 v 163 w(Meaning)p 1168 1555 1772 4 v 1218 1624 a FJ('-)49 b(')p 1515 1654 4 100 v 149 w FN(line)21 b(unique)d(to)j(sequence)e(1)1218 1724 y FJ('+)49 b(')p 1515 1754 V 149 w FN(line)21 b(unique)d(to)j (sequence)e(2)1218 1824 y FJ(')49 b(')p 1515 1854 V 199 w FN(line)21 b(common)d(to)i(both)g(sequences)1218 1923 y FJ('?)99 b(')p 1515 1953 V 99 w FN(line)21 b(not)f(present)f(in)h (either)g(input)g(sequence)208 2051 y(Lines)g(be)o(ginning)e(with)i(`)p FJ(?)49 b FN(')26 b(attempt)20 b(to)g(guide)g(the)g(e)o(ye)g(to)g (intraline)g(dif)n(ferences,)e(and)i(were)g(not)g(present)g(in)g (either)g(input)208 2151 y(sequence.)j(These)d(lines)h(can)f(be)g (confusing)e(if)j(the)f(sequences)f(contain)g(tab)i(characters.)0 2298 y FL(class)g FD(HtmlDiff)208 2397 y FN(This)29 b(class)h(can)f(be) g(used)g(to)g(create)g(an)g(HTML)g(table)g(\(or)f(a)i(complete)e(HTML)g (\002le)i(containing)d(the)j(table\))e(sho)n(wing)g(a)208 2497 y(side)c(by)g(side,)i(line)e(by)g(line)g(comparison)f(of)h(te)o (xt)g(with)g(inter)n(-line)g(and)g(intra-line)f(change)g(highlights.)36 b(The)24 b(table)g(can)h(be)208 2597 y(generated)18 b(in)i(either)g (full)g(or)g(conte)o(xtual)f(dif)n(ference)f(mode.)208 2729 y(The)h(constructor)g(for)g(this)i(class)g(is:)208 2862 y FD(__init__)p FJ(\()p FC([)p FK(tabsize)12 b FC(][)p FK(,)17 b(wr)o(apcolumn)12 b FC(][)p FK(,)18 b(linejunk)13 b FC(][)p FK(,)19 b(c)o(harjunk)13 b FC(])p FJ(\))390 2962 y FN(Initializes)20 b(instance)g(of)g FJ(HtmlDiff)p FN(.)390 3078 y FK(tabsize)h FN(is)g(an)f(optional)f(k)o(e)o(yw)o(ord)f (ar)o(gument)g(to)i(specify)g(tab)g(stop)g(spacing)g(and)f(def)o(aults) h(to)g FJ(8)p FN(.)390 3194 y FK(wr)o(apcolumn)j FN(is)i(an)f(optional) f(k)o(e)o(yw)o(ord)f(to)j(specify)e(column)g(number)f(where)i(lines)g (are)h(brok)o(en)d(and)i(wrapped,)f(de-)390 3294 y(f)o(aults)e(to)f FJ(None)g FN(where)g(lines)g(are)g(not)g(wrapped.)390 3410 y FK(linejunk)30 b FN(and)g FK(c)o(harjunk)f FN(are)h(optional)f (k)o(e)o(yw)o(ord)f(ar)o(guments)g(passed)h(into)h FJ(ndiff\(\))f FN(\(used)g(by)h FJ(HtmlDiff)e FN(to)390 3510 y(generate)22 b(the)h(side)g(by)g(side)g(HTML)f(dif)n(ferences\).)31 b(See)24 b FJ(ndiff\(\))e FN(documentation)e(for)i(ar)o(gument)f(def)o (ault)h(v)n(alues)390 3610 y(and)e(descriptions.)208 3742 y(The)f(follo)n(wing)g(methods)g(are)h(public:)208 3875 y FD(make_file)p FJ(\()p FK(fr)l(omlines,)e(tolines)i FC([)p FK(,)h(fr)l(omdesc)12 b FC(][)p FK(,)19 b(todesc)12 b FC(][)p FK(,)19 b(conte)n(xt)13 b FC(][)p FK(,)20 b(numlines)12 b FC(])p FJ(\))390 3975 y FN(Compares)32 b FK(fr)l(omlines)g FN(and)g FK(tolines)g FN(\(lists)i(of)e(strings\))f(and)h(returns)g(a)g (string)g(which)g(is)h(a)g(complete)e(HTML)h(\002le)390 4074 y(containing)18 b(a)j(table)f(sho)n(wing)f(line)i(by)e(line)i(dif) n(ferences)d(with)i(inter)n(-line)g(and)g(intra-line)f(changes)g (highlighted.)390 4191 y FK(fr)l(omdesc)24 b FN(and)g FK(todesc)g FN(are)g(optional)f(k)o(e)o(yw)o(ord)f(ar)o(guments)g(to)i (specify)g(from/to)e(\002le)j(column)e(header)g(strings)h(\(both)390 4290 y(def)o(ault)c(to)g(an)g(empty)f(string\).)390 4407 y FK(conte)n(xt)24 b FN(and)e FK(numlines)g FN(are)h(both)e(optional)h (k)o(e)o(yw)o(ord)e(ar)o(guments.)31 b(Set)23 b FK(conte)n(xt)h FN(to)e FJ(True)h FN(when)f(conte)o(xtual)f(dif)n(fer)n(-)390 4506 y(ences)28 b(are)f(to)g(be)h(sho)n(wn,)g(else)g(the)g(def)o(ault)e (is)j FJ(False)e FN(to)g(sho)n(w)g(the)h(full)f(\002les.)48 b FK(numlines)26 b FN(def)o(aults)h(to)h FJ(5)p FN(.)47 b(When)390 4606 y FK(conte)n(xt)25 b FN(is)f FJ(True)g FK(numlines)f FN(controls)f(the)i(number)d(of)j(conte)o(xt)e(lines)i (which)f(surround)e(the)j(dif)n(ference)d(highlights.)390 4705 y(When)g FK(conte)n(xt)h FN(is)f FJ(False)g FK(numlines)f FN(controls)g(the)h(number)e(of)h(lines)h(which)g(are)f(sho)n(wn)g (before)g(a)h(dif)n(ference)e(high-)390 4805 y(light)g(when)f(using)h (the)g(\224ne)o(xt\224)f(hyperlinks)f(\(setting)h(to)i(zero)e(w)o(ould) g(cause)h(the)h(\224ne)o(xt\224)e(hyperlinks)e(to)j(place)g(the)g(ne)o (xt)390 4905 y(dif)n(ference)f(highlight)h(at)i(the)f(top)g(of)g(the)g (bro)n(wser)f(without)g(an)o(y)h(leading)f(conte)o(xt\).)208 5037 y FD(make_table)p FJ(\()p FK(fr)l(omlines,)f(tolines)i FC([)p FK(,)g(fr)l(omdesc)12 b FC(][)p FK(,)20 b(todesc)12 b FC(][)p FK(,)19 b(conte)n(xt)13 b FC(][)p FK(,)20 b(numlines)12 b FC(])p FJ(\))390 5137 y FN(Compares)28 b FK(fr)l(omlines)h FN(and)g FK(tolines)g FN(\(lists)g(of)g(strings\))f(and)h(returns)e(a)j (string)e(which)g(is)i(a)f(complete)f(HTML)h(table)390 5237 y(sho)n(wing)19 b(line)i(by)e(line)i(dif)n(ferences)d(with)i (inter)n(-line)g(and)g(intra-line)f(changes)g(highlighted.)390 5353 y(The)h(ar)o(guments)e(for)i(this)g(method)f(are)h(the)h(same)f (as)h(those)f(for)f(the)i FJ(make_file\(\))d FN(method.)p 0 5549 3901 4 v 0 5649 a FI(66)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 67 79 TeXDict begin 67 78 bop 208 83 a FN(`)p FO(T)-9 b(ools/scr)q(ipts/diff) n(.p)n(y)p FN(')16 b(is)21 b(a)f(command-line)e(front-end)g(to)i(this)h (class)g(and)e(contains)h(a)g(good)f(e)o(xample)g(of)h(its)h(use.)208 216 y(Ne)n(w)f(in)g(v)o(ersion)f(2.4.)0 363 y FD(context_diff)p FJ(\()p FK(a,)f(b)p FC([)p FK(,)h(fr)l(om\002le)12 b FC(][)p FK(,)20 b(to\002le)12 b FC(][)p FK(,)19 b(fr)l(om\002ledate)12 b FC(][)p FK(,)18 b(to\002ledate)12 b FC(][)p FK(,)18 b(n)12 b FC(][)p FK(,)20 b(lineterm)12 b FC(])p FJ(\))208 462 y FN(Compare)19 b FK(a)h FN(and)g FK(b)g FN(\(lists)h(of)f (strings\);)g(return)f(a)i(delta)f(\(a)g(generator)e(generating)g(the)j (delta)f(lines\))g(in)g(conte)o(xt)f(dif)n(f)h(format.)208 595 y(Conte)o(xt)k(dif)n(fs)g(are)h(a)h(compact)e(w)o(ay)h(of)f(sho)n (wing)g(just)i(the)f(lines)g(that)g(ha)n(v)o(e)f(changed)g(plus)h(a)g (fe)n(w)g(lines)g(of)g(conte)o(xt.)38 b(The)208 695 y(changes)19 b(are)h(sho)n(wn)f(in)i(a)f(before/after)e(style.)26 b(The)19 b(number)g(of)h(conte)o(xt)f(lines)h(is)h(set)g(by)f FK(n)g FN(which)g(def)o(aults)g(to)g(three.)208 828 y(By)38 b(def)o(ault,)j(the)d(dif)n(f)g(control)e(lines)j(\(those)e(with)1829 843 y FJ(***)2017 828 y FN(or)h FJ(---)p FN(\))f(are)h(created)f(with)h (a)h(trailing)e(ne)n(wline.)78 b(This)38 b(is)208 927 y(helpful)h(so)i(that)g(inputs)f(created)g(from)g FJ (file.readlines\(\))e FN(result)j(in)g(dif)n(fs)f(that)h(are)g (suitable)f(for)g(use)h(with)208 1027 y FJ(file.writelines\(\))17 b FN(since)j(both)g(the)g(inputs)g(and)f(outputs)h(ha)n(v)o(e)f (trailing)h(ne)n(wlines.)208 1160 y(F)o(or)c(inputs)h(that)g(do)g(not)g (ha)n(v)o(e)g(trailing)f(ne)n(wlines,)h(set)h(the)g FK(lineterm)f FN(ar)o(gument)e(to)i FJ("")h FN(so)f(that)h(the)f(output)f(will)i(be)f (uniformly)208 1259 y(ne)n(wline)i(free.)208 1392 y(The)25 b(conte)o(xt)f(dif)n(f)g(format)g(normally)g(has)i(a)f(header)f(for)h (\002lenames)g(and)g(modi\002cation)e(times.)41 b(An)o(y)25 b(or)g(all)h(of)f(these)g(may)208 1492 y(be)f(speci\002ed)f(using)h (strings)g(for)f FK(fr)l(om\002le)p FN(,)i FK(to\002le)p FN(,)g FK(fr)l(om\002ledate)p FN(,)f(and)f FK(to\002ledate)p FN(.)35 b(The)24 b(modi\002cation)f(times)h(are)g(normally)208 1591 y(e)o(xpressed)18 b(in)j(the)f(format)f(returned)f(by)i FJ(time.ctime\(\))p FN(.)j(If)e(not)e(speci\002ed,)h(the)g(strings)g (def)o(ault)g(to)g(blanks.)208 1724 y(`)p FO(T)-9 b(ools/scr)q (ipts/diff)n(.p)n(y)p FN(')16 b(is)21 b(a)f(command-line)e(front-end)g (for)h(this)i(function.)208 1857 y(Ne)n(w)f(in)g(v)o(ersion)f(2.3.)0 2004 y FD(get_close_matches)p FJ(\()p FK(wor)m(d,)e(possibilities)p FC([)p FK(,)j(n)12 b FC(][)p FK(,)19 b(cutof)o(f)k FC(])p FJ(\))208 2104 y FN(Return)30 b(a)i(list)g(of)f(the)g(best)g(\223good)f (enough\224)f(matches.)57 b FK(wor)m(d)34 b FN(is)e(a)f(sequence)f(for) h(which)f(close)h(matches)g(are)g(desired)208 2203 y(\(typically)f(a)i (string\),)i(and)d FK(possibilities)h FN(is)g(a)g(list)h(of)f (sequences)e(against)h(which)h(to)f(match)g FK(wor)m(d)k FN(\(typically)30 b(a)i(list)h(of)208 2303 y(strings\).)208 2436 y(Optional)19 b(ar)o(gument)f FK(n)i FN(\(def)o(ault)f FJ(3)p FN(\))h(is)h(the)g(maximum)d(number)h(of)g(close)i(matches)f(to) g(return;)f FK(n)h FN(must)h(be)f(greater)f(than)h FJ(0)p FN(.)208 2569 y(Optional)i(ar)o(gument)g FK(cutof)o(f)35 b FN(\(def)o(ault)22 b FJ(0.6)p FN(\))i(is)g(a)h(\003oat)e(in)h(the)g (range)f([0,)h(1].)35 b(Possibilities)25 b(that)e(don')o(t)f(score)i (at)g(least)g(that)208 2668 y(similar)c(to)g FK(wor)m(d)j FN(are)d(ignored.)208 2801 y(The)e(best)i(\(no)e(more)h(than)g FK(n)p FN(\))g(matches)f(among)g(the)h(possibilities)h(are)f(returned)f (in)h(a)h(list,)g(sorted)f(by)g(similarity)g(score,)g(most)208 2901 y(similar)h(\002rst.)444 3125 y FA(>>>)44 b (get_close_matches\('appel',)d(['ape',)i('apple',)h('peach',)f ('puppy']\))444 3216 y(['apple',)g('ape'])444 3307 y(>>>)h(import)g (keyword)444 3399 y(>>>)g(get_close_matches\('wheel',)d (keyword.kwlist\))444 3490 y(['while'])444 3581 y(>>>)j (get_close_matches\('apple',)d(keyword.kwlist\))444 3673 y([])444 3764 y(>>>)j(get_close_matches\('accept',)c(keyword.kwlist\)) 444 3855 y(['except'])0 4082 y FD(ndiff)p FJ(\()p FK(a,)19 b(b)p FC([)p FK(,)h(linejunk)13 b FC(][)p FK(,)19 b(c)o(harjunk)13 b FC(])p FJ(\))208 4182 y FN(Compare)19 b FK(a)h FN(and)g FK(b)g FN(\(lists)h(of)f(strings\);)g(return)f(a)i FJ(Differ)p FN(-style)e(delta)h(\(a)g(generator)e(generating)g(the)j(delta)f (lines\).)208 4315 y(Optional)f(k)o(e)o(yw)o(ord)f(parameters)h FK(linejunk)i FN(and)e FK(c)o(harjunk)i FN(are)f(for)f(\002lter)i (functions)e(\(or)g FJ(None)p FN(\):)208 4447 y FK(linejunk)q FN(:)31 b(A)24 b(function)e(that)h(accepts)g(a)h(single)g(string)f(ar)o (gument,)f(and)h(returns)f(true)h(if)h(the)f(string)h(is)g(junk,)f(or)g (f)o(alse)h(if)g(not.)208 4547 y(The)e(def)o(ault)g(is)i(\()p FJ(None)p FN(\),)e(starting)h(with)g(Python)e(2.3.)32 b(Before)22 b(then,)h(the)g(def)o(ault)f(w)o(as)i(the)f(module-le)n(v)o (el)d(function)h FJ(IS_-)208 4647 y(LINE_JUNK\(\))p FN(,)c(which)h (\002lters)h(out)g(lines)g(without)f(visible)h(characters,)f(e)o(xcept) f(for)h(at)i(most)e(one)h(pound)d(character)i(\(`)p FJ(#)p FN('\).)208 4746 y(As)28 b(of)g(Python)e(2.3,)j(the)f(underlying)d FJ(SequenceMatcher)g FN(class)k(does)e(a)i(dynamic)d(analysis)i(of)f (which)g(lines)i(are)e(so)208 4846 y(frequent)18 b(as)j(to)f (constitute)g(noise,)g(and)f(this)i(usually)f(w)o(orks)f(better)h(than) g(the)g(pre-2.3)e(def)o(ault.)208 4979 y FK(c)o(harjunk)q FN(:)23 b(A)18 b(function)f(that)h(accepts)g(a)h(character)e(\(a)h (string)g(of)g(length)f(1\),)h(and)g(returns)f(if)i(the)f(character)f (is)i(junk,)f(or)g(f)o(alse)g(if)208 5078 y(not.)32 b(The)23 b(def)o(ault)f(is)i(module-le)n(v)o(el)c(function)h FJ (IS_CHARACTER_JUNK\(\))p FN(,)g(which)h(\002lters)i(out)e(whitespace)h (characters)208 5178 y(\(a)d(blank)f(or)h(tab;)g(note:)25 b(bad)20 b(idea)g(to)g(include)f(ne)n(wline)h(in)g(this!\).)208 5311 y(`)p FO(T)-9 b(ools/scr)q(ipts/ndiff)n(.p)n(y)p FN(')15 b(is)21 b(a)g(command-line)c(front-end)h(to)i(this)h(function.) p 0 5549 3901 4 v 0 5649 a FI(4.4.)52 b FJ(difflib)22 b FI(\227)h(Helpers)g(f)n(or)g(computing)h(deltas)2086 b(67)p eop end %%Page: 68 80 TeXDict begin 68 79 bop 444 83 a FA(>>>)44 b(diff)g(=)h (ndiff\('one\\ntwo\\nthree\\n'.splitlines\(1\))o(,)444 174 y(...)627 b('ore\\ntree\\nemu\\n'.splitlines\(1\)\))444 266 y(>>>)44 b(print)g(''.join\(diff\),)444 357 y(-)g(one)444 448 y(?)89 b(\210)444 540 y(+)44 b(ore)444 631 y(?)89 b(\210)444 722 y(-)44 b(two)444 814 y(-)g(three)444 905 y(?)89 b(-)444 996 y(+)44 b(tree)444 1088 y(+)g(emu)0 1291 y FD(restore)p FJ(\()p FK(sequence)o(,)17 b(whic)o(h)p FJ(\))208 1391 y FN(Return)i(one)h(of)g(the)g(tw)o(o)h(sequences)e (that)h(generated)f(a)h(delta.)208 1523 y(Gi)n(v)o(en)i(a)i FK(sequence)e FN(produced)f(by)i FJ(Differ.compare\(\))d FN(or)j FJ(ndiff\(\))p FN(,)g(e)o(xtract)g(lines)h(originating)d(from)h (\002le)i(1)f(or)g(2)208 1623 y(\(parameter)18 b FK(whic)o(h)p FN(\),)h(stripping)g(of)n(f)h(line)g(pre\002x)o(es.)208 1755 y(Example:)444 1978 y FA(>>>)44 b(diff)g(=)h (ndiff\('one\\ntwo\\nthree\\n'.splitlines\(1\))o(,)444 2069 y(...)627 b('ore\\ntree\\nemu\\n'.splitlines\(1\)\))444 2161 y(>>>)44 b(diff)g(=)h(list\(diff\))e(#)i(materialize)e(the)h (generated)f(delta)h(into)h(a)f(list)444 2252 y(>>>)g(print)g (''.join\(restore\(diff,)d(1\)\),)444 2343 y(one)444 2435 y(two)444 2526 y(three)444 2617 y(>>>)j(print)g (''.join\(restore\(diff,)d(2\)\),)444 2709 y(ore)444 2800 y(tree)444 2891 y(emu)0 3118 y FD(unified_diff)p FJ(\()p FK(a,)18 b(b)p FC([)p FK(,)h(fr)l(om\002le)12 b FC(][)p FK(,)20 b(to\002le)12 b FC(][)p FK(,)19 b(fr)l(om\002ledate) 12 b FC(][)p FK(,)18 b(to\002ledate)12 b FC(][)p FK(,)18 b(n)12 b FC(][)p FK(,)20 b(lineterm)12 b FC(])p FJ(\))208 3218 y FN(Compare)19 b FK(a)h FN(and)g FK(b)g FN(\(lists)h(of)f (strings\);)g(return)f(a)i(delta)f(\(a)g(generator)e(generating)g(the)j (delta)f(lines\))g(in)g(uni\002ed)g(dif)n(f)f(format.)208 3350 y(Uni\002ed)25 b(dif)n(fs)g(are)g(a)h(compact)f(w)o(ay)g(of)h(sho) n(wing)e(just)i(the)g(lines)g(that)f(ha)n(v)o(e)g(changed)f(plus)h(a)h (fe)n(w)g(lines)g(of)f(conte)o(xt.)40 b(The)208 3449 y(changes)20 b(are)i(sho)n(wn)e(in)i(a)g(inline)f(style)h(\(instead)f (of)g(separate)h(before/after)d(blocks\).)28 b(The)21 b(number)f(of)h(conte)o(xt)f(lines)i(is)h(set)208 3549 y(by)c FK(n)i FN(which)e(def)o(aults)h(to)g(three.)208 3681 y(By)33 b(def)o(ault,)j(the)d(dif)n(f)g(control)f(lines)i(\(those) f(with)g FJ(---)p FN(,)k FJ(+++)p FN(,)f(or)d FJ(@@)p FN(\))h(are)f(created)f(with)i(a)g(trailing)f(ne)n(wline.)63 b(This)208 3781 y(is)35 b(helpful)f(so)h(that)f(inputs)h(created)f (from)f FJ(file.readlines\(\))g FN(result)h(in)h(dif)n(fs)f(that)h(are) g(suitable)f(for)g(use)h(with)208 3880 y FJ(file.writelines\(\))17 b FN(since)j(both)g(the)g(inputs)g(and)f(outputs)h(ha)n(v)o(e)f (trailing)h(ne)n(wlines.)208 4013 y(F)o(or)c(inputs)h(that)g(do)g(not)g (ha)n(v)o(e)g(trailing)f(ne)n(wlines,)h(set)h(the)g FK(lineterm)f FN(ar)o(gument)e(to)i FJ("")h FN(so)f(that)h(the)f(output)f(will)i(be)f (uniformly)208 4112 y(ne)n(wline)i(free.)208 4244 y(The)25 b(conte)o(xt)f(dif)n(f)g(format)g(normally)g(has)i(a)f(header)f(for)h (\002lenames)g(and)g(modi\002cation)e(times.)41 b(An)o(y)25 b(or)g(all)h(of)f(these)g(may)208 4344 y(be)f(speci\002ed)f(using)h (strings)g(for)f FK(fr)l(om\002le)p FN(,)i FK(to\002le)p FN(,)g FK(fr)l(om\002ledate)p FN(,)f(and)f FK(to\002ledate)p FN(.)35 b(The)24 b(modi\002cation)f(times)h(are)g(normally)208 4444 y(e)o(xpressed)18 b(in)j(the)f(format)f(returned)f(by)i FJ(time.ctime\(\))p FN(.)j(If)e(not)e(speci\002ed,)h(the)g(strings)g (def)o(ault)g(to)g(blanks.)208 4576 y(`)p FO(T)-9 b(ools/scr)q (ipts/diff)n(.p)n(y)p FN(')16 b(is)21 b(a)f(command-line)e(front-end)g (for)h(this)i(function.)208 4708 y(Ne)n(w)f(in)g(v)o(ersion)f(2.3.)0 4855 y FD(IS_LINE_JUNK)p FJ(\()p FK(line)p FJ(\))208 4954 y FN(Return)h(true)g(for)h(ignorable)e(lines.)27 b(The)20 b(line)h FK(line)g FN(is)h(ignorable)d(if)i FK(line)g FN(is)h(blank)e(or)g(contains)g(a)i(single)e(`)p FJ(#)p FN(',)h(otherwise)f(it)i(is)208 5054 y(not)d(ignorable.)k(Used)e (as)g(a)f(def)o(ault)g(for)f(parameter)g FK(linejunk)i FN(in)f FJ(ndiff\(\))g FN(before)e(Python)h(2.3.)0 5201 y FD(IS_CHARACTER_JUNK)p FJ(\()p FK(c)o(h)p FJ(\))208 5300 y FN(Return)26 b(true)g(for)g(ignorable)f(characters.)43 b(The)27 b(character)e FK(c)o(h)h FN(is)i(ignorable)d(if)i FK(c)o(h)f FN(is)i(a)f(space)f(or)h(tab,)h(otherwise)e(it)h(is)h(not) 208 5400 y(ignorable.)23 b(Used)d(as)h(a)g(def)o(ault)e(for)h (parameter)e FK(c)o(harjunk)i FN(in)h FJ(ndiff\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(68)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 69 81 TeXDict begin 69 80 bop 0 83 a FL(See)21 b(Also:)0 230 y FK(P)-7 b(attern)20 b(Matc)o(hing:)k(The)c(Gestalt)g(Appr)l(oac)o(h)0 330 y Fy(\()p FO(http://www)l(.ddj.com/1844)o(079)o(70)o(?p)o(gn)o(o=5) -7 b Fy(\))208 429 y FN(Discussion)24 b(of)g(a)h(similar)f(algorithm)f (by)h(John)g(W)-8 b(.)25 b(Ratclif)n(f)g(and)f(D.)g(E.)h(Metzener)-5 b(.)37 b(This)24 b(w)o(as)h(published)e(in)i FK(Dr)-9 b(.)38 b(Dobb')m(s)208 529 y(J)n(ournal)19 b FN(in)h(July)-5 b(,)19 b(1988.)0 814 y Fv(4.4.1)100 b(SequenceMatcher)31 b(Objects)0 1017 y FN(The)20 b FJ(SequenceMatcher)e FN(class)j(has)f (this)h(constructor:)0 1163 y FL(class)g FD(SequenceMatcher)p FJ(\()p FC([)p FK(isjunk)q FC([)p FK(,)c(a)p FC([)p FK(,)j(b)12 b FC(])g(])g(])p FJ(\))208 1263 y FN(Optional)18 b(ar)o(gument)g FK(isjunk)j FN(must)e(be)h FJ(None)g FN(\(the)f(def)o(ault\))f(or)i(a)g (one-ar)o(gument)c(function)i(that)i(tak)o(es)g(a)g(sequence)e(element) 208 1363 y(and)e(returns)h(true)g(if)g(and)g(only)f(if)i(the)f(element) g(is)h(\223junk\224)e(and)h(should)f(be)h(ignored.)22 b(P)o(assing)c FJ(None)f FN(for)g FK(isjunk)h FN(is)g(equi)n(v)n(alent) 208 1462 y(to)i(passing)g FJ(lambda)48 b(x:)100 b(0)p FN(;)20 b(in)h(other)e(w)o(ords,)h(no)f(elements)h(are)g(ignored.)k(F)o (or)19 b(e)o(xample,)g(pass:)444 1686 y FA(lambda)44 b(x:)g(x)h(in)f(")h(\\t")208 1876 y FN(if)20 b(you')l(re)e(comparing)g (lines)j(as)g(sequences)e(of)h(characters,)f(and)h(don')o(t)e(w)o(ant)i (to)h(synch)e(up)h(on)g(blanks)f(or)h(hard)f(tabs.)208 2009 y(The)j(optional)f(ar)o(guments)g FK(a)h FN(and)g FK(b)h FN(are)f(sequences)g(to)h(be)f(compared;)g(both)g(def)o(ault)g (to)h(empty)e(strings.)32 b(The)23 b(elements)f(of)208 2108 y(both)d(sequences)g(must)h(be)h(hashable.)0 2255 y FJ(SequenceMatcher)d FN(objects)i(ha)n(v)o(e)g(the)g(follo)n(wing)e (methods:)0 2402 y FD(set_seqs)p FJ(\()p FK(a,)g(b)p FJ(\))208 2502 y FN(Set)i(the)h(tw)o(o)f(sequences)f(to)i(be)f (compared.)0 2649 y FJ(SequenceMatcher)h FN(computes)g(and)i(caches)f (detailed)h(information)d(about)i(the)h(second)f(sequence,)g(so)h(if)g (you)f(w)o(ant)h(to)g(com-)0 2748 y(pare)29 b(one)g(sequence)f(against) h(man)o(y)f(sequences,)j(use)e FJ(set_seq2\(\))g FN(to)g(set)h(the)g (commonly)d(used)i(sequence)f(once)h(and)g(call)0 2848 y FJ(set_seq1\(\))19 b FN(repeatedly)-5 b(,)18 b(once)h(for)h(each)g (of)g(the)g(other)f(sequences.)0 2995 y FD(set_seq1)p FJ(\()p FK(a)p FJ(\))208 3094 y FN(Set)h(the)h(\002rst)g(sequence)e(to) h(be)g(compared.)j(The)d(second)f(sequence)g(to)h(be)h(compared)d(is)j (not)f(changed.)0 3241 y FD(set_seq2)p FJ(\()p FK(b)p FJ(\))208 3341 y FN(Set)g(the)h(second)e(sequence)g(to)h(be)g (compared.)j(The)d(\002rst)h(sequence)e(to)h(be)h(compared)d(is)j(not)f (changed.)0 3488 y FD(find_longest_match)p FJ(\()p FK(alo,)c(ahi,)k (blo,)f(bhi)p FJ(\))208 3587 y FN(Find)h(longest)f(matching)g(block)g (in)i FK(a)p FJ([)p FK(alo)p FJ(:)p FK(ahi)p FJ(])c FN(and)j FK(b)p FJ([)p FK(blo)p FJ(:)p FK(bhi)p FJ(])p FN(.)208 3720 y(If)h FK(isjunk)h FN(w)o(as)g(omitted)e(or)h FJ(None)p FN(,)g FJ(get_longest_match\(\))d FN(returns)j FJ(\()p FK(i)p FJ(,)49 b FK(j)p FJ(,)h FK(k)q FJ(\))22 b FN(such)f(that)g FK(a)p FJ([)p FK(i)p FJ(:)p FK(i)p FJ(+)p FK(k)q FJ(])g FN(is)h(equal)e(to)208 3820 y FK(b)p FJ([)p FK(j)p FJ(:)p FK(j)p FJ(+)p FK(k)q FJ(])p FN(,)h(where)g FK(alo)49 b FJ(<=)g FK(i)h FJ(<=)g FK(i)p FJ(+)p FK(k)h FJ(<=)e FK(ahi)21 b FN(and)g FK(blo)49 b FJ(<=)h FK(j)g FJ(<=)f FK(j)p FJ(+)p FK(k)i FJ(<=)e FK(bhi)p FN(.)29 b(F)o(or)21 b(all)i FJ(\()p FK(i')p FJ(,)49 b FK(j')p FJ(,)g FK(k')p FJ(\))22 b FN(meeting)208 3919 y(those)i(conditions,)g(the)h (additional)e(conditions)g FK(k)51 b FJ(>=)f FK(k')p FN(,)25 b FK(i)50 b FJ(<=)g FK(i')p FN(,)26 b(and)e(if)h FK(i)49 b FJ(==)h FK(i')p FN(,)26 b FK(j)50 b FJ(<=)f FK(j')25 b FN(are)g(also)g(met.)38 b(In)24 b(other)208 4019 y(w)o(ords,)g(of)g(all)h(maximal)e(matching)g(blocks,)h(return)f (one)h(that)g(starts)h(earliest)g(in)f FK(a)p FN(,)h(and)f(of)g(all)h (those)f(maximal)f(matching)208 4119 y(blocks)c(that)h(start)h (earliest)g(in)f FK(a)p FN(,)g(return)f(the)h(one)g(that)g(starts)h (earliest)g(in)f FK(b)p FN(.)444 4343 y FA(>>>)44 b(s)h(=)f (SequenceMatcher\(None,)e(")i(abcd",)g("abcd)g(abcd"\))444 4434 y(>>>)g(s.find_longest_match\(0,)d(5,)k(0,)f(9\))444 4526 y(\(0,)g(4,)h(5\))208 4715 y FN(If)16 b FK(isjunk)i FN(w)o(as)f(pro)o(vided,)e(\002rst)i(the)g(longest)f(matching)f(block)h (is)i(determined)c(as)k(abo)o(v)o(e,)d(b)n(ut)i(with)f(the)h (additional)e(restriction)208 4815 y(that)26 b(no)f(junk)g(element)g (appears)g(in)i(the)e(block.)42 b(Then)25 b(that)h(block)f(is)h(e)o (xtended)e(as)j(f)o(ar)f(as)h(possible)e(by)h(matching)e(\(only\))208 4914 y(junk)d(elements)i(on)f(both)g(sides.)33 b(So)23 b(the)g(resulting)f(block)g(ne)n(v)o(er)f(matches)h(on)h(junk)f(e)o (xcept)f(as)j(identical)e(junk)g(happens)f(to)208 5014 y(be)f(adjacent)f(to)h(an)h(interesting)e(match.)208 5147 y(Here')-5 b(s)21 b(the)g(same)g(e)o(xample)f(as)i(before,)d(b)n (ut)i(considering)e(blanks)i(to)g(be)g(junk.)26 b(That)21 b(pre)n(v)o(ents)f FJ(')49 b(abcd')21 b FN(from)f(matching)208 5247 y(the)f FJ(')49 b(abcd')19 b FN(at)h(the)f(tail)h(end)f(of)g(the)g (second)f(sequence)g(directly)-5 b(.)24 b(Instead)18 b(only)h(the)g FJ('abcd')g FN(can)g(match,)f(and)h(matches)208 5346 y(the)h(leftmost)g FJ('abcd')f FN(in)i(the)f(second)f(sequence:)p 0 5549 3901 4 v 0 5649 a FI(4.4.)52 b FJ(difflib)22 b FI(\227)h(Helpers)g(f)n(or)g(computing)h(deltas)2086 b(69)p eop end %%Page: 70 82 TeXDict begin 70 81 bop 444 174 a FA(>>>)44 b(s)h(=)f (SequenceMatcher\(lambda)e(x:)i(x==")g(",)h(")f(abcd",)g("abcd)g (abcd"\))444 266 y(>>>)g(s.find_longest_match\(0,)d(5,)k(0,)f(9\))444 357 y(\(1,)g(0,)h(4\))208 547 y FN(If)20 b(no)f(blocks)h(match,)f(this) i(returns)e FJ(\()p FK(alo)p FJ(,)49 b FK(blo)p FJ(,)g(0\))p FN(.)0 694 y FD(get_matching_blocks)p FJ(\(\))208 793 y FN(Return)21 b(list)i(of)f(triples)g(describing)e(matching)g (subsequences.)29 b(Each)21 b(triple)h(is)h(of)f(the)f(form)g FJ(\()p FK(i)p FJ(,)50 b FK(j)p FJ(,)g FK(n)p FJ(\))p FN(,)22 b(and)f(means)g(that)208 893 y FK(a)p FJ([)p FK(i)p FJ(:)p FK(i)p FJ(+)p FK(n)p FJ(])48 b(==)h FK(b)p FJ([)p FK(j)p FJ(:)p FK(j)p FJ(+)p FK(n)p FJ(])p FN(.)24 b(The)c(triples)g(are)g(monotonically)e(increasing)h(in)h FK(i)h FN(and)f FK(j)p FN(.)208 1026 y(The)f(last)i(triple)f(is)i(a)e (dummy)-5 b(,)18 b(and)i(has)g(the)g(v)n(alue)g FJ(\(len\()p FK(a)p FJ(\),)48 b(len\()p FK(b)p FJ(\),)g(0\))p FN(.)25 b(It)c(is)g(the)f(only)f(triple)h(with)h FK(n)49 b FJ(==)h(0)p FN(.)208 1158 y(If)15 b FJ(\()p FK(i)p FJ(,)50 b FK(j)p FJ(,)g FK(n)p FJ(\))16 b FN(and)f FJ(\()p FK(i')p FJ(,)49 b FK(j')p FJ(,)h FK(n')p FJ(\))15 b FN(are)h(adjacent)f(triples)i(in)f (the)g(list,)i(and)d(the)h(second)f(is)i(not)f(the)g(last)h(triple)f (in)g(the)g(list,)i(then)208 1258 y FK(i)p FJ(+)p FK(n)49 b FJ(!=)g FK(i')19 b FN(or)g FK(j)p FJ(+)p FK(n)49 b FJ(!=)g FK(j')p FN(;)20 b(in)f(other)f(w)o(ords,)g(adjacent)g(triples)h (al)o(w)o(ays)g(describe)f(non-adjacent)e(equal)i(blocks.)49 b(Changed)208 1358 y(in)20 b(v)o(ersion)f(2.5:)g(The)h(guarantee)f (that)h(adjacent)f(triples)i(al)o(w)o(ays)f(describe)g(non-adjacent)d (blocks)j(w)o(as)h(implemented.)444 1582 y FA(>>>)44 b(s)h(=)f(SequenceMatcher\(None,)e("abxcd",)h("abcd"\))444 1673 y(>>>)h(s.get_matching_blocks\(\))444 1765 y([\(0,)g(0,)g(2\),)h (\(3,)f(2,)h(2\),)f(\(5,)g(4,)h(0\)])0 1964 y FD(get_opcodes)p FJ(\(\))208 2063 y FN(Return)19 b(list)i(of)f(5-tuples)f(describing)f (ho)n(w)h(to)i(turn)e FK(a)h FN(into)f FK(b)p FN(.)25 b(Each)20 b(tuple)f(is)i(of)f(the)g(form)f FJ(\()p FK(ta)o(g)p FJ(,)48 b FK(i1)p FJ(,)i FK(i2)p FJ(,)f FK(j1)p FJ(,)g FK(j2)p FJ(\))p FN(.)25 b(The)208 2163 y(\002rst)j(tuple)g(has)g FK(i1)49 b FJ(==)h FK(j1)f FJ(==)g(0)p FN(,)30 b(and)e(remaining)e (tuples)h(ha)n(v)o(e)h FK(i1)g FN(equal)f(to)h(the)g FK(i2)g FN(from)f(the)g(preceding)f(tuple,)j(and,)208 2263 y(lik)o(e)n(wise,)20 b FK(j1)g FN(equal)g(to)g(the)g(pre)n(vious)f FK(j2)p FN(.)208 2395 y(The)g FK(ta)o(g)h FN(v)n(alues)g(are)g (strings,)g(with)h(these)f(meanings:)540 2525 y FL(V)-8 b(alue)p 1037 2555 4 100 v 348 w(Meaning)p 490 2558 3128 4 v 540 2628 a FJ('replace')p 1037 2657 4 100 v 98 w FK(a)p FJ([)p FK(i1)p FJ(:)p FK(i2)p FJ(])19 b FN(should)g(be)h (replaced)f(by)h FK(b)p FJ([)p FK(j1)p FJ(:)p FK(j2)p FJ(])p FN(.)540 2727 y FJ('delete')p 1037 2757 V 148 w FK(a)p FJ([)p FK(i1)p FJ(:)p FK(i2)p FJ(])f FN(should)g(be)h (deleted.)k(Note)d(that)f FK(j1)49 b FJ(==)h FK(j2)20 b FN(in)g(this)h(case.)540 2827 y FJ('insert')p 1037 2857 V 148 w FK(b)p FJ([)p FK(j1)p FJ(:)p FK(j2)p FJ(])e FN(should)g(be)h(inserted)g(at)h FK(a)p FJ([)p FK(i1)p FJ(:)p FK(i1)p FJ(])p FN(.)i(Note)d(that)h FK(i1)49 b FJ(==)g FK(i2)21 b FN(in)f(this)h(case.)540 2926 y FJ('equal')p 1037 2956 V 198 w FK(a)p FJ([)p FK(i1)p FJ(:)p FK(i2)p FJ(])48 b(==)h FK(b)p FJ([)p FK(j1)p FJ(:)p FK(j2)p FJ(])19 b FN(\(the)h(sub-sequences)e(are)j(equal\).)208 3055 y(F)o(or)e(e)o(xample:)444 3279 y FA(>>>)44 b(a)h(=)f("qabxcd")444 3370 y(>>>)g(b)h(=)f("abycdf")444 3461 y(>>>)g(s)h(=)f (SequenceMatcher\(None,)e(a,)i(b\))444 3553 y(>>>)g(for)g(tag,)h(i1,)f (i2,)g(j1,)h(j2)f(in)h(s.get_opcodes\(\):)444 3644 y(...)179 b(print)44 b(\("\0457s)g(a[\045d:\045d])f(\(\045s\))h(b[\045d:\045d])g (\(\045s\)")g(\045)444 3735 y(...)492 b(\(tag,)44 b(i1,)h(i2,)f (a[i1:i2],)f(j1,)i(j2,)f(b[j1:j2]\)\))489 3827 y(delete)f(a[0:1])h (\(q\))h(b[0:0])e(\(\))533 3918 y(equal)h(a[1:3])g(\(ab\))g(b[0:2])g (\(ab\))444 4009 y(replace)f(a[3:4])h(\(x\))h(b[2:3])e(\(y\))533 4101 y(equal)h(a[4:6])g(\(cd\))g(b[3:5])g(\(cd\))489 4192 y(insert)f(a[6:6])h(\(\))h(b[5:6])f(\(f\))0 4419 y FD(get_grouped_opcodes)p FJ(\()p FC([)p FK(n)12 b FC(])p FJ(\))208 4518 y FN(Return)19 b(a)i(generator)d(of)i(groups)f(with)h (up)g(to)g FK(n)h FN(lines)f(of)g(conte)o(xt.)208 4651 y(Starting)29 b(with)g(the)h(groups)e(returned)f(by)i FJ(get_opcodes\(\))p FN(,)h(this)g(method)e(splits)j(out)e(smaller)g (change)f(clusters)i(and)208 4751 y(eliminates)20 b(interv)o(ening)d (ranges)j(which)f(ha)n(v)o(e)h(no)g(changes.)208 4884 y(The)f(groups)g(are)h(returned)f(in)h(the)g(same)h(format)e(as)i FJ(get_opcodes\(\))p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 5030 y FD(ratio)p FJ(\(\))208 5130 y FN(Return)g(a)i(measure)e(of)h (the)g(sequences')f(similarity)h(as)h(a)g(\003oat)f(in)h(the)f(range)f ([0,)h(1].)208 5263 y(Where)h(T)g(is)h(the)f(total)h(number)d(of)i (elements)g(in)g(both)g(sequences,)f(and)h(M)g(is)i(the)e(number)e(of)i (matches,)g(this)h(is)g(2.0*M)e(/)i(T)-6 b(.)208 5363 y(Note)20 b(that)g(this)h(is)g FJ(1.0)f FN(if)h(the)f(sequences)f(are)h (identical,)g(and)f FJ(0.0)h FN(if)h(the)o(y)e(ha)n(v)o(e)h(nothing)e (in)j(common.)p 0 5549 3901 4 v 0 5649 a FI(70)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 71 83 TeXDict begin 71 82 bop 208 83 a FN(This)35 b(is)h(e)o(xpensi)n(v)o(e)e (to)h(compute)f(if)i FJ(get_matching_blocks\(\))c FN(or)j FJ(get_opcodes\(\))f FN(hasn')o(t)g(already)g(been)208 183 y(called,)g(in)e(which)g(case)g(you)f(may)h(w)o(ant)g(to)g(try)g FJ(quick_ratio\(\))e FN(or)i FJ(real_quick_ratio\(\))d FN(\002rst)j(to)h(get)f(an)208 282 y(upper)18 b(bound.)0 429 y FD(quick_ratio)p FJ(\(\))208 529 y FN(Return)h(an)h(upper)f (bound)g(on)g FJ(ratio\(\))h FN(relati)n(v)o(ely)f(quickly)-5 b(.)208 662 y(This)20 b(isn')o(t)g(de\002ned)f(be)o(yond)f(that)i(it)h (is)g(an)f(upper)f(bound)f(on)i FJ(ratio\(\))p FN(,)f(and)h(is)h(f)o (aster)g(to)f(compute.)0 808 y FD(real_quick_ratio)p FJ(\(\))208 908 y FN(Return)f(an)h(upper)f(bound)g(on)g FJ(ratio\(\))h FN(v)o(ery)f(quickly)-5 b(.)208 1041 y(This)18 b(isn')o(t)h(de\002ned)f(be)o(yond)e(that)j(it)h(is)f(an)g(upper)e (bound)g(on)i FJ(ratio\(\))p FN(,)f(and)g(is)i(f)o(aster)e(to)h (compute)f(than)g(either)g FJ(ratio\(\))208 1141 y FN(or)h FJ(quick_ratio\(\))p FN(.)0 1287 y(The)d(three)f(methods)g(that)h (return)f(the)h(ratio)g(of)g(matching)f(to)h(total)g(characters)f(can)h (gi)n(v)o(e)f(dif)n(ferent)g(results)h(due)g(to)g(dif)n(fering)e(le)n (v)o(els)i(of)0 1387 y(approximation,)f(although)h FJ(quick_ratio\(\))g FN(and)i FJ(real_quick_ratio\(\))d FN(are)j(al)o(w)o(ays)g(at)h(least)g (as)f(lar)o(ge)f(as)i FJ(ratio\(\))p FN(:)236 1625 y FA(>>>)45 b(s)f(=)h(SequenceMatcher\(None,)c("abcd",)j("bcde"\))236 1717 y(>>>)h(s.ratio\(\))236 1808 y(0.75)236 1899 y(>>>)g (s.quick_ratio\(\))236 1991 y(0.75)236 2082 y(>>>)g (s.real_quick_ratio\(\))236 2173 y(1.0)0 2598 y Fv(4.4.2)100 b(SequenceMatcher)31 b(Examples)0 2801 y FN(This)20 b(e)o(xample)f (compares)g(tw)o(o)i(strings,)e(considering)g(blanks)g(to)h(be)h (\223junk:\224)236 3039 y FA(>>>)45 b(s)f(=)h(SequenceMatcher\(lambda)c (x:)k(x)f(==)h(")f(",)236 3130 y(...)941 b("private)44 b(Thread)f(currentThread;",)236 3222 y(...)941 b("private)44 b(volatile)f(Thread)h(currentThread;"\))0 3508 y FJ(ratio\(\))22 b FN(returns)g(a)h(\003oat)f(in)h([0,)g(1],)f(measuring)f(the)i (similarity)g(of)f(the)g(sequences.)32 b(As)23 b(a)g(rule)f(of)h (thumb,)e(a)i FJ(ratio\(\))f FN(v)n(alue)0 3608 y(o)o(v)o(er)d(0.6)g (means)h(the)g(sequences)g(are)g(close)g(matches:)236 3846 y FA(>>>)45 b(print)f(round\(s.ratio\(\),)e(3\))236 3937 y(0.866)0 4224 y FN(If)20 b(you')l(re)e(only)i(interested)f(in)i (where)e(the)h(sequences)g(match,)f FJ(get_matching_blocks\(\))e FN(is)k(handy:)236 4462 y FA(>>>)45 b(for)f(block)g(in)g (s.get_matching_blocks\(\):)236 4553 y(...)224 b(print)44 b("a[\045d])g(and)g(b[\045d])g(match)g(for)g(\045d)h(elements")e(\045)i (block)236 4645 y(a[0])f(and)h(b[0])f(match)g(for)g(8)h(elements)236 4736 y(a[8])f(and)h(b[17])f(match)g(for)g(6)h(elements)236 4827 y(a[14])f(and)h(b[23])f(match)g(for)g(15)g(elements)236 4919 y(a[29])g(and)h(b[38])f(match)g(for)g(0)h(elements)0 5205 y FN(Note)23 b(that)g(the)g(last)h(tuple)f(returned)e(by)i FJ(get_matching_blocks\(\))d FN(is)k(al)o(w)o(ays)f(a)h(dummy)-5 b(,)21 b FJ(\(len\()p FK(a)p FJ(\),)48 b(len\()p FK(b)p FJ(\),)h(0\))p FN(,)0 5305 y(and)20 b(this)g(is)h(the)g(only)e(case)i (in)f(which)g(the)g(last)h(tuple)f(element)f(\(number)f(of)i(elements)g (matched\))f(is)i FJ(0)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(4.4.)52 b FJ(difflib)22 b FI(\227)h(Helpers)g(f)n(or)g(computing)h (deltas)2086 b(71)p eop end %%Page: 72 84 TeXDict begin 72 83 bop 0 83 a FN(If)20 b(you)f(w)o(ant)i(to)f(kno)n(w) f(ho)n(w)h(to)g(change)f(the)h(\002rst)h(sequence)e(into)h(the)g (second,)f(use)i FJ(get_opcodes\(\))p FN(:)236 321 y FA(>>>)45 b(for)f(opcode)g(in)g(s.get_opcodes\(\):)236 413 y(...)224 b(print)44 b("\0456s)g(a[\045d:\045d])g(b[\045d:\045d]")f (\045)h(opcode)281 504 y(equal)g(a[0:8])g(b[0:8])236 595 y(insert)g(a[8:8])g(b[8:17])281 687 y(equal)g(a[8:14])g(b[17:23]) 281 778 y(equal)g(a[14:29])g(b[23:38])0 1064 y FN(See)d(also)g(the)g (function)e FJ(get_close_matches\(\))e FN(in)k(this)g(module,)j(which)c (sho)n(ws)h(ho)n(w)f(simple)h(code)f(b)n(uilding)f(on)0 1164 y FJ(SequenceMatcher)18 b FN(can)i(be)g(used)g(to)g(do)g(useful)g (w)o(ork.)0 1449 y Fv(4.4.3)100 b(Diff)m(er)28 b(Objects)0 1652 y FN(Note)h(that)h FJ(Differ)p FN(-generated)c(deltas)k(mak)o(e)f (no)g(claim)h(to)g(be)f FL(minimal)i FN(dif)n(fs.)52 b(T)-7 b(o)30 b(the)f(contrary)-5 b(,)30 b(minimal)f(dif)n(fs)g(are)g (often)0 1751 y(counter)n(-intuiti)n(v)o(e,)18 b(because)i(the)o(y)g (synch)g(up)h(an)o(ywhere)e(possible,)h(sometimes)h(accidental)f (matches)g(100)g(pages)h(apart.)26 b(Restrict-)0 1851 y(ing)19 b(synch)g(points)g(to)h(contiguous)d(matches)j(preserv)o(es)e (some)h(notion)g(of)g(locality)-5 b(,)19 b(at)h(the)f(occasional)g (cost)h(of)f(producing)e(a)j(longer)0 1951 y(dif)n(f.)0 2098 y(The)g FJ(Differ)f FN(class)j(has)e(this)h(constructor:)0 2244 y FL(class)g FD(Differ)p FJ(\()p FC([)p FK(linejunk)q FC([)p FK(,)d(c)o(harjunk)13 b FC(])f(])p FJ(\))208 2344 y FN(Optional)19 b(k)o(e)o(yw)o(ord)f(parameters)h FK(linejunk)i FN(and)e FK(c)o(harjunk)i FN(are)f(for)f(\002lter)i(functions)e(\(or)g FJ(None)p FN(\):)208 2477 y FK(linejunk)q FN(:)31 b(A)24 b(function)e(that)i(accepts)f(a)h(single)f(string)h(ar)o(gument,)d(and) i(returns)g(true)g(if)h(the)g(string)f(is)h(junk.)35 b(The)23 b(def)o(ault)g(is)208 2576 y FJ(None)p FN(,)c(meaning)g(that)h (no)g(line)g(is)h(considered)e(junk.)208 2709 y FK(c)o(harjunk)q FN(:)43 b(A)30 b(function)f(that)h(accepts)f(a)i(single)e(character)g (ar)o(gument)f(\(a)i(string)f(of)h(length)f(1\),)j(and)d(returns)g (true)g(if)i(the)208 2809 y(character)18 b(is)k(junk.)i(The)c(def)o (ault)f(is)i FJ(None)p FN(,)f(meaning)f(that)h(no)g(character)f(is)i (considered)d(junk.)0 2956 y FJ(Differ)i FN(objects)g(are)g(used)g (\(deltas)g(generated\))e(via)i(a)h(single)f(method:)0 3103 y FD(compare)p FJ(\()p FK(a,)f(b)p FJ(\))208 3202 y FN(Compare)g(tw)o(o)h(sequences)f(of)h(lines,)h(and)e(generate)g(the) h(delta)h(\(a)f(sequence)f(of)h(lines\).)208 3335 y(Each)15 b(sequence)g(must)h(contain)f(indi)n(vidual)f(single-line)h(strings)h (ending)f(with)h(ne)n(wlines.)23 b(Such)16 b(sequences)f(can)h(be)g (obtained)208 3435 y(from)22 b(the)i FJ(readlines\(\))e FN(method)g(of)i(\002le-lik)o(e)g(objects.)35 b(The)23 b(delta)h(generated)e(also)i(consists)g(of)g(ne)n(wline-terminated)208 3534 y(strings,)19 b(ready)h(to)g(be)g(printed)f(as-is)i(via)f(the)g FJ(writelines\(\))f FN(method)g(of)h(a)g(\002le-lik)o(e)g(object.)0 3819 y Fv(4.4.4)100 b(Diff)m(er)28 b(Example)0 4022 y FN(This)e(e)o(xample)e(compares)h(tw)o(o)h(te)o(xts.)42 b(First)27 b(we)f(set)g(up)g(the)g(te)o(xts,)h(sequences)e(of)g(indi)n (vidual)f(single-line)h(strings)h(ending)e(with)0 4122 y(ne)n(wlines)c(\(such)f(sequences)h(can)g(also)g(be)g(obtained)f(from) g(the)h FJ(readlines\(\))f FN(method)g(of)h(\002le-lik)o(e)g (objects\):)p 0 5549 3901 4 v 0 5649 a FI(72)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 73 85 TeXDict begin 73 84 bop 236 174 a FA(>>>)45 b(text1)f(=)g(''')89 b(1.)45 b(Beautiful)e(is)i(better)e(than)i(ugly.)236 266 y(...)134 b(2.)45 b(Explicit)e(is)i(better)f(than)g(implicit.)236 357 y(...)134 b(3.)45 b(Simple)f(is)g(better)g(than)g(complex.)236 448 y(...)134 b(4.)45 b(Complex)e(is)i(better)f(than)g(complicated.)236 540 y(...)h('''.splitlines\(1\))236 631 y(>>>)g(len\(text1\))236 722 y(4)236 814 y(>>>)g(text1[0][-1])236 905 y('\\n')236 996 y(>>>)g(text2)f(=)g(''')89 b(1.)45 b(Beautiful)e(is)i(better)e (than)i(ugly.)236 1088 y(...)134 b(3.)g(Simple)44 b(is)h(better)f(than) g(complex.)236 1179 y(...)134 b(4.)45 b(Complicated)e(is)h(better)g (than)g(complex.)236 1270 y(...)134 b(5.)45 b(Flat)f(is)g(better)g (than)g(nested.)236 1362 y(...)h('''.splitlines\(1\))0 1648 y FN(Ne)o(xt)20 b(we)g(instantiate)h(a)f(Dif)n(fer)g(object:)236 1886 y FA(>>>)45 b(d)f(=)h(Differ\(\))0 2173 y FN(Note)23 b(that)g(when)g(instantiating)f(a)h FJ(Differ)g FN(object)f(we)i(may)e (pass)i(functions)e(to)h(\002lter)g(out)g(line)g(and)g(character)e (\223junk.)-6 b(\224)33 b(See)24 b(the)0 2272 y FJ(Differ\(\))19 b FN(constructor)g(for)g(details.)0 2419 y(Finally)-5 b(,)19 b(we)i(compare)e(the)h(tw)o(o:)236 2657 y FA(>>>)45 b(result)e(=)i(list\(d.compare\(text1,)c(text2\)\))0 2944 y FJ(result)20 b FN(is)h(a)f(list)i(of)e(strings,)g(so)g(let')-5 b(s)21 b(pretty-print)d(it:)236 3182 y FA(>>>)45 b(from)f(pprint)g (import)f(pprint)236 3274 y(>>>)i(pprint\(result\))236 3365 y([')179 b(1.)45 b(Beautiful)e(is)i(better)e(than)i(ugly.\\n',)281 3456 y('-)134 b(2.)45 b(Explicit)e(is)i(better)f(than)g(implicit.\\n',) 281 3547 y('-)134 b(3.)45 b(Simple)f(is)g(better)g(than)g (complex.\\n',)281 3639 y('+)134 b(3.)g(Simple)44 b(is)h(better)f(than) g(complex.\\n',)281 3730 y('?)224 b(++)1434 b(\\n',)281 3821 y('-)134 b(4.)45 b(Complex)e(is)i(better)f(than)g (complicated.\\n',)281 3913 y('?)538 b(\210)941 b(----)44 b(\210)90 b(\\n',)281 4004 y('+)134 b(4.)45 b(Complicated)e(is)h (better)g(than)g(complex.\\n',)281 4095 y('?)493 b(++++)44 b(\210)986 b(\210)90 b(\\n',)281 4187 y('+)134 b(5.)45 b(Flat)f(is)g(better)g(than)g(nested.\\n'])0 4473 y FN(As)21 b(a)g(single)f(multi-line)f(string)h(it)h(looks)e(lik)o(e)i(this:)p 0 5549 3901 4 v 0 5649 a FI(4.4.)52 b FJ(difflib)22 b FI(\227)h(Helpers)g(f)n(or)g(computing)h(deltas)2086 b(73)p eop end %%Page: 74 86 TeXDict begin 74 85 bop 236 174 a FA(>>>)45 b(import)e(sys)236 266 y(>>>)i(sys.stdout.writelines\(result\))416 357 y(1.)f(Beautiful)f (is)i(better)f(than)g(ugly.)236 448 y(-)135 b(2.)44 b(Explicit)g(is)g (better)g(than)g(implicit.)236 540 y(-)135 b(3.)44 b(Simple)g(is)g (better)g(than)g(complex.)236 631 y(+)135 b(3.)f(Simple)44 b(is)g(better)g(than)g(complex.)236 722 y(?)224 b(++)236 814 y(-)135 b(4.)44 b(Complex)g(is)g(better)g(than)g(complicated.)236 905 y(?)538 b(\210)941 b(----)44 b(\210)236 996 y(+)135 b(4.)44 b(Complicated)f(is)i(better)e(than)i(complex.)236 1088 y(?)493 b(++++)44 b(\210)986 b(\210)236 1179 y(+)135 b(5.)44 b(Flat)g(is)h(better)f(than)g(nested.)0 1689 y FE(4.5)121 b Fx(StringIO)31 b FE(\227)i(Read)i(and)f(wr)r(ite)g(str)r (ings)f(as)g(\002les)0 1922 y FN(This)26 b(module)f(implements)f(a)j (\002le-lik)o(e)f(class,)i FJ(StringIO)p FN(,)c(that)i(reads)g(and)f (writes)h(a)h(string)e(b)n(uf)n(fer)g(\(also)h(kno)n(wn)e(as)j FK(memory)0 2021 y(\002les)p FN(\).)e(See)c(the)f(description)e(of)i (\002le)h(objects)f(for)g(operations)e(\(section)i(3.9\).)0 2168 y FL(class)h FD(StringIO)p FJ(\()p FC([)p FK(b)n(uf)o(fer)14 b FC(])p FJ(\))208 2268 y FN(When)30 b(a)g FJ(StringIO)f FN(object)h(is)h(created,)h(it)e(can)g(be)g(initialized)g(to)h(an)f(e)o (xisting)f(string)h(by)g(passing)f(the)h(string)g(to)h(the)208 2368 y(constructor)-5 b(.)23 b(If)d(no)g(string)g(is)h(gi)n(v)o(en,)e (the)h FJ(StringIO)g FN(will)h(start)g(empty)-5 b(.)23 b(In)d(both)g(cases,)h(the)f(initial)h(\002le)g(position)e(starts)i(at) 208 2467 y(zero.)208 2600 y(The)15 b FJ(StringIO)f FN(object)h(can)g (accept)h(either)f(Unicode)f(or)h(8-bit)g(strings,)h(b)n(ut)g(mixing)e (the)h(tw)o(o)h(may)f(tak)o(e)h(some)f(care.)23 b(If)15 b(both)208 2700 y(are)g(used,)h(8-bit)e(strings)h(that)h(cannot)e(be)h (interpreted)f(as)i(7-bit)g FH(A)t(S)t(C)t(I)t(I)j FN(\(that)c(use)h (the)f(8th)g(bit\))g(will)h(cause)g(a)f FJ(UnicodeError)208 2799 y FN(to)20 b(be)g(raised)g(when)g FJ(getvalue\(\))f FN(is)i(called.)0 2946 y(The)f(follo)n(wing)e(methods)i(of)f FJ(StringIO)h FN(objects)g(require)f(special)h(mention:)0 3093 y FD(getvalue)p FJ(\(\))208 3193 y FN(Retrie)n(v)o(e)e(the)h (entire)f(contents)g(of)g(the)h(\223\002le\224)g(at)h(an)o(y)e(time)g (before)g(the)h FJ(StringIO)e FN(object')-5 b(s)19 b FJ(close\(\))f FN(method)f(is)j(called.)208 3292 y(See)h(the)g(note)f (abo)o(v)o(e)f(for)i(information)d(about)i(mixing)g(Unicode)g(and)g (8-bit)g(strings;)i(such)e(mixing)g(can)h(cause)g(this)g(method)208 3392 y(to)f(raise)g FJ(UnicodeError)p FN(.)0 3539 y FD(close)p FJ(\(\))208 3638 y FN(Free)g(the)g(memory)f(b)n(uf)n(fer)-5 b(.)0 3785 y(Example)19 b(usage:)236 4023 y FA(import)44 b(StringIO)236 4206 y(output)g(=)h(StringIO.StringIO\(\))236 4297 y(output.write\('First)d(line.\\n'\))236 4389 y(print)i(>>output,) g('Second)f(line.')236 4571 y(#)i(Retrieve)e(file)i(contents)e(--)i (this)f(will)g(be)236 4663 y(#)h('First)f(line.\\nSecond)e(line.\\n') 236 4754 y(contents)i(=)g(output.getvalue\(\))236 4937 y(#)h(Close)f(object)g(and)g(discard)g(memory)g(buffer)f(--)236 5028 y(#)i(.getvalue\(\))e(will)h(now)g(raise)g(an)h(exception.)236 5119 y(output.close\(\))p 0 5549 3901 4 v 0 5649 a FI(74)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 75 87 TeXDict begin 75 86 bop 0 87 a FE(4.6)121 b Fx(cStringIO)31 b FE(\227)h(F)-6 b(aster)34 b(v)m(ersion)g(of)g Fx(StringIO)0 320 y FN(The)46 b(module)g FJ(cStringIO)f FN(pro)o(vides)g(an)i(interf) o(ace)f(similar)h(to)g(that)f(of)h(the)g FJ(StringIO)e FN(module.)104 b(Hea)n(vy)46 b(use)h(of)0 420 y FJ(StringIO.StringIO)26 b FN(objects)i(can)h(be)f(made)g(more)g(ef)n(\002cient)g(by)g(using)g (the)h(function)e FJ(StringIO\(\))g FN(from)h(this)h(mod-)0 519 y(ule)20 b(instead.)0 666 y(Since)f(this)g(module)f(pro)o(vides)f (a)i(f)o(actory)f(function)f(which)h(returns)g(objects)h(of)f(b)n (uilt-in)g(types,)h(there')-5 b(s)19 b(no)f(w)o(ay)h(to)g(b)n(uild)g (your)e(o)n(wn)0 766 y(v)o(ersion)i(using)h(subclassing.)k(Use)d(the)f (original)f FJ(StringIO)g FN(module)g(in)h(that)h(case.)0 913 y(Unlik)o(e)c(the)h(memory)e(\002les)j(implemented)c(by)j(the)f FJ(StringIO)g FN(module,)f(those)i(pro)o(vided)d(by)i(this)h(module)f (are)g(not)h(able)f(to)h(accept)0 1012 y(Unicode)h(strings)h(that)g (cannot)g(be)g(encoded)e(as)j(plain)h FH(A)t(S)t(C)t(I)t(I)h FN(strings.)0 1159 y(Calling)30 b FJ(StringIO\(\))f FN(with)h(a)g (Unicode)f(string)h(parameter)f(populates)f(the)i(object)g(with)g(the)g (b)n(uf)n(fer)f(representation)f(of)i(the)0 1259 y(Unicode)19 b(string,)h(instead)g(of)g(encoding)e(the)i(string.)0 1406 y(Another)f(dif)n(ference)f(from)i(the)g FJ(StringIO)g FN(module)f(is)i(that)g(calling)f FJ(StringIO\(\))f FN(with)h(a)h (string)f(parameter)f(creates)i(a)f(read-)0 1505 y(only)e(object.)24 b(Unlik)o(e)19 b(an)f(object)h(created)f(without)g(a)h(string)g (parameter)m(,)e(it)j(does)e(not)h(ha)n(v)o(e)f(write)h(methods.)24 b(These)18 b(objects)h(are)g(not)0 1605 y(generally)g(visible.)25 b(The)o(y)19 b(turn)g(up)h(in)g(tracebacks)f(as)i FJ(StringI)f FN(and)f FJ(StringO)p FN(.)0 1752 y(The)h(follo)n(wing)e(data)i (objects)g(are)h(pro)o(vided)c(as)k(well:)0 1899 y FD(InputType)208 1998 y FN(The)e(type)h(object)g(of)g(the)g(objects)g(created)f(by)h (calling)g FJ(StringIO)f FN(with)h(a)h(string)f(parameter)-5 b(.)0 2145 y FD(OutputType)208 2245 y FN(The)19 b(type)h(object)g(of)g (the)g(objects)g(returned)e(by)i(calling)g FJ(StringIO)f FN(with)h(no)g(parameters.)0 2392 y(There)f(is)i(a)g(C)g(API)g(to)f (the)g(module)f(as)i(well;)g(refer)e(to)i(the)f(module)f(source)g(for)h (more)f(information.)0 2539 y(Example)g(usage:)236 2685 y FA(import)44 b(cStringIO)236 2868 y(output)g(=)h (cStringIO.StringIO\(\))236 2959 y(output.write\('First)d(line.\\n'\)) 236 3051 y(print)i(>>output,)g('Second)f(line.')236 3233 y(#)i(Retrieve)e(file)i(contents)e(--)i(this)f(will)g(be)236 3325 y(#)h('First)f(line.\\nSecond)e(line.\\n')236 3416 y(contents)i(=)g(output.getvalue\(\))236 3599 y(#)h(Close)f(object)g (and)g(discard)g(memory)g(buffer)f(--)236 3690 y(#)i(.getvalue\(\))e (will)h(now)g(raise)g(an)h(exception.)236 3781 y(output.close\(\))0 4229 y FE(4.7)121 b Fx(textwrap)31 b FE(\227)i(T)-14 b(e)l(xt)33 b(wr)o(apping)i(and)g(\002lling)0 4462 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4609 y(The)28 b FJ(textwrap)g FN(module)g(pro)o(vides)f(tw)o(o)i(con)m(v)o(enience)d (functions,)j FJ(wrap\(\))f FN(and)h FJ(fill\(\))p FN(,)h(as)f(well)h (as)f FJ(TextWrapper)p FN(,)0 4709 y(the)24 b(class)h(that)f(does)g (all)g(the)g(w)o(ork,)g(and)g(a)g(utility)g(function)f FJ(dedent\(\))p FN(.)35 b(If)24 b(you')l(re)e(just)i(wrapping)f(or)g (\002lling)h(one)g(or)f(tw)o(o)i(te)o(xt)0 4808 y(strings,)d(the)g(con) m(v)o(enience)c(functions)j(should)f(be)i(good)e(enough;)h(otherwise,)g (you)g(should)g(use)h(an)f(instance)h(of)f FJ(TextWrapper)0 4908 y FN(for)f(ef)n(\002cienc)o(y)-5 b(.)0 5055 y FD(wrap)p FJ(\()p FK(te)n(xt)q FC([)p FK(,)20 b(width)p FC([)p FK(,)g(...)12 b FC(])g(])p FJ(\))208 5154 y FN(Wraps)27 b(the)g(single)f(paragraph)f(in)i FK(te)n(xt)i FN(\(a)e(string\))f(so)h (e)n(v)o(ery)f(line)h(is)h(at)f(most)g FK(width)g FN(characters)f (long.)44 b(Returns)27 b(a)g(list)h(of)208 5254 y(output)19 b(lines,)h(without)f(\002nal)i(ne)n(wlines.)208 5387 y(Optional)15 b(k)o(e)o(yw)o(ord)g(ar)o(guments)f(correspond)g(to)i (the)g(instance)g(attrib)n(utes)h(of)f FJ(TextWrapper)p FN(,)f(documented)f(belo)n(w)-5 b(.)22 b FK(width)p 0 5549 3901 4 v 0 5649 a FI(4.6.)52 b FJ(cStringIO)22 b FI(\227)h(F)l(aster)f(v)n(ersion)g(of)i FJ(StringIO)2005 b FI(75)p eop end %%Page: 76 88 TeXDict begin 76 87 bop 208 83 a FN(def)o(aults)19 b(to)i FJ(70)p FN(.)0 230 y FD(fill)p FJ(\()p FK(te)n(xt)q FC([)p FK(,)f(width)p FC([)p FK(,)g(...)12 b FC(])g(])p FJ(\))208 330 y FN(Wraps)25 b(the)f(single)h(paragraph)d(in)j FK(te)n(xt)q FN(,)i(and)d(returns)g(a)h(single)f(string)h(containing)e(the)h (wrapped)g(paragraph.)35 b FJ(fill\(\))25 b FN(is)208 429 y(shorthand)18 b(for)444 646 y FA("\\n".join\(wrap\(text,)41 b(...\)\))208 827 y FN(In)19 b(particular)m(,)g FJ(fill\(\))g FN(accepts)i(e)o(xactly)e(the)h(same)g(k)o(e)o(yw)o(ord)f(ar)o(guments) f(as)j FJ(wrap\(\))p FN(.)0 974 y(Both)28 b FJ(wrap\(\))g FN(and)g FJ(fill\(\))g FN(w)o(ork)f(by)h(creating)f(a)i FJ(TextWrapper)e FN(instance)h(and)f(calling)h(a)h(single)f(method)f (on)h(it.)50 b(That)0 1074 y(instance)25 b(is)i(not)e(reused,)h(so)f (for)g(applications)g(that)g(wrap/\002ll)h(man)o(y)e(te)o(xt)h (strings,)i(it)f(will)g(be)g(more)f(ef)n(\002cient)g(for)g(you)f(to)i (create)0 1174 y(your)19 b(o)n(wn)h FJ(TextWrapper)e FN(object.)0 1320 y(An)h(additional)e(utility)i(function,)e FJ(dedent\(\))p FN(,)h(is)h(pro)o(vided)e(to)h(remo)o(v)o(e)f (indentation)g(from)h(strings)g(that)h(ha)n(v)o(e)f(unw)o(anted)g (whites-)0 1420 y(pace)i(to)g(the)g(left)h(of)f(the)g(te)o(xt.)0 1567 y FD(dedent)p FJ(\()p FK(te)n(xt)q FJ(\))208 1667 y FN(Remo)o(v)o(e)f(an)o(y)g(common)f(leading)h(whitespace)h(from)f(e)n (v)o(ery)g(line)h(in)h FK(te)n(xt)q FN(.)208 1792 y(This)k(can)h(be)g (used)f(to)h(mak)o(e)f(triple-quoted)e(strings)j(line)g(up)f(with)h (the)g(left)g(edge)f(of)g(the)h(display)-5 b(,)26 b(while)f(still)i (presenting)208 1891 y(them)19 b(in)i(the)f(source)f(code)h(in)g (indented)f(form.)208 2017 y(Note)27 b(that)h(tabs)f(and)g(spaces)h (are)g(both)e(treated)h(as)i(whitespace,)f(b)n(ut)g(the)o(y)e(are)i (not)f(equal:)39 b(the)28 b(lines)g FJ(")99 b(hello")27 b FN(and)208 2116 y FJ(")p FM(n)p FJ(thello")f FN(are)h(considered)f (to)i(ha)n(v)o(e)f(no)g(common)e(leading)i(whitespace.)46 b(\(This)28 b(beha)n(viour)d(is)k(ne)n(w)e(in)h(Python)e(2.5;)208 2216 y(older)19 b(v)o(ersions)g(of)h(this)h(module)e(incorrectly)f(e)o (xpanded)g(tabs)i(before)f(searching)g(for)g(common)g(leading)g (whitespace.\))208 2341 y(F)o(or)g(e)o(xample:)444 2558 y FA(def)44 b(test\(\):)623 2649 y(#)h(end)f(first)g(line)g(with)g(\\)h (to)g(avoid)f(the)g(empty)g(line!)623 2740 y(s)h(=)f('''\\)623 2832 y(hello)713 2923 y(world)623 3014 y(''')623 3106 y(print)g(repr\(s\))447 b(#)45 b(prints)f(')179 b(hello\\n)268 b(world\\n)178 b(')623 3197 y(print)44 b(repr\(dedent\(s\)\))87 b(#)45 b(prints)f('hello\\n)88 b(world\\n')0 3400 y FL(class)21 b FD(TextWrapper)p FJ(\()p FK(...)p FJ(\))208 3499 y FN(The)d FJ(TextWrapper)f FN(constructor)f(accepts)i(a)h(number)e(of)h (optional)f(k)o(e)o(yw)o(ord)g(ar)o(guments.)22 b(Each)c(ar)o(gument)e (corresponds)208 3599 y(to)k(one)g(instance)f(attrib)n(ute,)h(so)g(for) g(e)o(xample)444 3815 y FA(wrapper)43 b(=)i (TextWrapper\(initial_indent=")2152 3828 y(*)2237 3815 y("\))208 3972 y FN(is)21 b(the)f(same)g(as)444 4188 y FA(wrapper)43 b(=)i(TextWrapper\(\))444 4279 y (wrapper.initial_indent)c(=)k(")1610 4292 y(*)1699 4279 y(")208 4461 y FN(Y)-9 b(ou)26 b(can)h(re-use)f(the)h(same)g FJ(TextWrapper)f FN(object)g(man)o(y)g(times,)j(and)d(you)g(can)h (change)f(an)o(y)g(of)h(its)h(options)e(through)208 4561 y(direct)19 b(assignment)h(to)g(instance)g(attrib)n(utes)g(between)f (uses.)0 4708 y(The)h FJ(TextWrapper)f FN(instance)g(attrib)n(utes)h (\(and)g(k)o(e)o(yw)o(ord)e(ar)o(guments)g(to)j(the)f(constructor\))e (are)i(as)h(follo)n(ws:)0 4855 y FD(width)208 4954 y FN(\(def)o(ault:)k FJ(70)p FN(\))c(The)g(maximum)e(length)h(of)h (wrapped)f(lines.)27 b(As)22 b(long)e(as)i(there)f(are)g(no)f(indi)n (vidual)g(w)o(ords)g(in)h(the)g(input)g(te)o(xt)208 5054 y(longer)d(than)i FJ(width)p FN(,)g FJ(TextWrapper)e FN(guarantees)h(that)h(no)g(output)f(line)h(will)h(be)g(longer)d(than)i FJ(width)g FN(characters.)0 5201 y FD(expand_tabs)208 5300 y FN(\(def)o(ault:)33 b FJ(True)p FN(\))25 b(If)g(true,)h(then)e (all)i(tab)f(characters)f(in)h FK(te)n(xt)j FN(will)e(be)f(e)o(xpanded) d(to)j(spaces)h(using)e(the)h FJ(expandtabs\(\))208 5400 y FN(method)18 b(of)i FK(te)n(xt)q FN(.)p 0 5549 3901 4 v 0 5649 a FI(76)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 77 89 TeXDict begin 77 88 bop 0 83 a FD(replace_whitespace)208 183 y FN(\(def)o(ault:)23 b FJ(True)p FN(\))c(If)h(true,)f(each)g (whitespace)g(character)f(\(as)i(de\002ned)e(by)h FJ(string.whitespace) p FN(\))e(remaining)g(after)j(tab)208 282 y(e)o(xpansion)f(will)j(be)f (replaced)f(by)h(a)h(single)f(space.)29 b FL(Note:)d FN(If)c FJ(expand_tabs)d FN(is)k(f)o(alse)f(and)e FJ (replace_whitespace)208 382 y FN(is)h(true,)e(each)h(tab)g(character)f (will)i(be)f(replaced)f(by)h(a)h(single)f(space,)g(which)f(is)i FK(not)f FN(the)h(same)f(as)h(tab)f(e)o(xpansion.)0 529 y FD(initial_indent)208 628 y FN(\(def)o(ault:)25 b FJ('')p FN(\))h(String)20 b(that)h(will)g(be)g(prepended)d(to)j(the)g(\002rst)g (line)g(of)f(wrapped)g(output.)25 b(Counts)20 b(to)n(w)o(ards)h(the)f (length)g(of)h(the)208 728 y(\002rst)f(line.)0 875 y FD(subsequent_indent)208 975 y FN(\(def)o(ault:)31 b FJ('')p FN(\))h(String)24 b(that)g(will)g(be)g(prepended)d(to)j(all)h (lines)f(of)f(wrapped)g(output)f(e)o(xcept)h(the)h(\002rst.)37 b(Counts)23 b(to)n(w)o(ards)h(the)208 1074 y(length)19 b(of)h(each)g(line)g(e)o(xcept)f(the)h(\002rst.)0 1221 y FD(fix_sentence_endings)208 1321 y FN(\(def)o(ault:)39 b FJ(False)p FN(\))27 b(If)h(true,)h FJ(TextWrapper)e FN(attempts)h(to)g(detect)f(sentence)h(endings)e(and)i(ensure)f(that)h (sentences)g(are)208 1420 y(al)o(w)o(ays)h(separated)e(by)h(e)o(xactly) g(tw)o(o)h(spaces.)50 b(This)28 b(is)i(generally)d(desired)h(for)f(te)o (xt)i(in)f(a)h(monospaced)e(font.)49 b(Ho)n(we)n(v)o(er)m(,)208 1520 y(the)24 b(sentence)h(detection)e(algorithm)h(is)h(imperfect:)34 b(it)25 b(assumes)g(that)g(a)g(sentence)g(ending)e(consists)i(of)g(a)g (lo)n(wercase)f(letter)208 1620 y(follo)n(wed)d(by)i(one)f(of)g(`)p FJ(.)p FN(',)h(`)p FJ(!)p FN(',)g(or)g(`)p FJ(?)p FN(',)g(possibly)f (follo)n(wed)g(by)g(one)h(of)f(`)p FJ(")p FN(')h(or)f(`)p FJ(')p FN(',)h(follo)n(wed)f(by)g(a)i(space.)33 b(One)22 b(problem)208 1719 y(with)e(this)h(is)g(algorithm)d(is)k(that)e(it)h (is)g(unable)e(to)h(detect)g(the)h(dif)n(ference)d(between)h(\223Dr)-5 b(.)f(\224)25 b(in)444 1943 y FA([...])44 b(Dr.)g(Frankenstein's)f (monster)g([...])208 2133 y FN(and)19 b(\223Spot.)-6 b(\224)25 b(in)444 2357 y FA([...])44 b(See)g(Spot.)g(See)g(Spot)h(run) f([...])208 2546 y FJ(fix_sentence_endings)17 b FN(is)k(f)o(alse)f(by)g (def)o(ault.)208 2679 y(Since)f(the)h(sentence)f(detection)f(algorithm) g(relies)i(on)g FJ(string.lowercase)d FN(for)i(the)g(de\002nition)g(of) g(\223lo)n(wercase)g(letter)m(,)-6 b(\224)208 2779 y(and)29 b(a)h(con)m(v)o(ention)c(of)k(using)f(tw)o(o)h(spaces)f(after)h(a)g (period)e(to)i(separate)f(sentences)g(on)g(the)h(same)g(line,)i(it)e (is)h(speci\002c)e(to)208 2878 y(English-language)16 b(te)o(xts.)0 3025 y FD(break_long_words)208 3125 y FN(\(def)o(ault:)23 b FJ(True)p FN(\))18 b(If)h(true,)g(then)f(w)o(ords)h(longer)e(than)i FJ(width)f FN(will)i(be)e(brok)o(en)g(in)h(order)e(to)i(ensure)f(that)h (no)g(lines)g(are)g(longer)208 3225 y(than)24 b FJ(width)p FN(.)37 b(If)25 b(it)g(is)g(f)o(alse,)h(long)e(w)o(ords)g(will)h(not)f (be)h(brok)o(en,)f(and)g(some)g(lines)h(may)f(be)g(longer)f(than)i FJ(width)p FN(.)37 b(\(Long)208 3324 y(w)o(ords)19 b(will)i(be)f(put)g (on)g(a)h(line)f(by)g(themselv)o(es,)f(in)h(order)f(to)i(minimize)e (the)h(amount)f(by)h(which)f FJ(width)h FN(is)h(e)o(xceeded.\))0 3471 y FJ(TextWrapper)e FN(also)h(pro)o(vides)f(tw)o(o)h(public)f (methods,)g(analogous)g(to)h(the)g(module-le)n(v)o(el)e(con)m(v)o (enience)f(functions:)0 3618 y FD(wrap)p FJ(\()p FK(te)n(xt)q FJ(\))208 3718 y FN(Wraps)29 b(the)f(single)h(paragraph)d(in)j FK(te)n(xt)i FN(\(a)e(string\))f(so)h(e)n(v)o(ery)e(line)i(is)g(at)h (most)e FJ(width)h FN(characters)e(long.)50 b(All)29 b(wrapping)208 3817 y(options)17 b(are)h(tak)o(en)g(from)f(instance)g (attrib)n(utes)h(of)g(the)g FJ(TextWrapper)f FN(instance.)24 b(Returns)18 b(a)h(list)g(of)f(output)f(lines,)h(without)208 3917 y(\002nal)i(ne)n(wlines.)0 4064 y FD(fill)p FJ(\()p FK(te)n(xt)q FJ(\))208 4163 y FN(Wraps)g(the)g(single)g(paragraph)e(in) i FK(te)n(xt)q FN(,)i(and)d(returns)g(a)i(single)f(string)g(containing) e(the)j(wrapped)d(paragraph.)0 4491 y FE(4.8)121 b Fx(codecs)31 b FE(\227)i(Codec)i(registr)t(y)e(and)h(base)h(classes)0 4724 y FN(This)c(module)f(de\002nes)g(base)h(classes)h(for)e(standard)g (Python)g(codecs)g(\(encoders)f(and)i(decoders\))e(and)h(pro)o(vides)f (access)j(to)f(the)0 4823 y(internal)19 b(Python)g(codec)h(re)o(gistry) f(which)h(manages)f(the)h(codec)f(and)h(error)f(handling)f(lookup)h (process.)0 4970 y(It)h(de\002nes)g(the)h(follo)n(wing)d(functions:)0 5117 y FD(register)p FJ(\()p FK(sear)m(c)o(h)p 673 5117 25 4 v 27 w(function)p FJ(\))208 5217 y FN(Re)o(gister)i(a)h(codec)e (search)h(function.)j(Search)d(functions)f(are)h(e)o(xpected)e(to)j (tak)o(e)f(one)g(ar)o(gument,)e(the)i(encoding)e(name)i(in)g(all)208 5316 y(lo)n(wer)f(case)i(letters,)f(and)g(return)f(a)i FJ(CodecInfo)e FN(object)g(ha)n(ving)g(the)i(follo)n(wing)d(attrib)n (utes:)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and)g(base)h(classes)1986 b(77)p eop end %%Page: 78 90 TeXDict begin 78 89 bop 349 83 a FM(\017)o FJ(name)20 b FN(The)g(name)g(of)g(the)g(encoding;)349 216 y FM(\017)o FJ(encoder)g FN(The)g(stateless)h(encoding)d(function;)349 349 y FM(\017)o FJ(decoder)i FN(The)g(stateless)h(decoding)d(function;) 349 482 y FM(\017)o FJ(incrementalencoder)g FN(An)i(incremental)f (encoder)f(class)j(or)f(f)o(actory)f(function;)349 614 y FM(\017)o FJ(incrementaldecoder)f FN(An)i(incremental)f(decoder)f (class)j(or)f(f)o(actory)f(function;)349 747 y FM(\017)o FJ(streamwriter)g FN(A)h(stream)h(writer)f(class)h(or)f(f)o(actory)f (function;)349 880 y FM(\017)o FJ(streamreader)g FN(A)h(stream)h (reader)e(class)i(or)f(f)o(actory)f(function.)208 1093 y(The)g(v)n(arious)h(functions)e(or)i(classes)h(tak)o(e)g(the)f(follo)n (wing)e(ar)o(guments:)208 1226 y FK(encoder)52 b FN(and)g FK(decoder)r FN(:)87 b(These)52 b(must)g(be)g(functions)e(or)i(methods) f(which)g(ha)n(v)o(e)h(the)g(same)g(interf)o(ace)f(as)i(the)208 1326 y FJ(encode\(\))p FN(/)p FJ(decode\(\))28 b FN(methods)h(of)i (Codec)f(instances)g(\(see)h(Codec)f(Interf)o(ace\).)55 b(The)30 b(functions/methods)e(are)i(e)o(x-)208 1425 y(pected)19 b(to)h(w)o(ork)g(in)g(a)h(stateless)g(mode.)208 1558 y FK(incr)m(ementalencoder)f FN(and)g FK(incr)m(ementalencoder)r FN(:)k(These)d(ha)n(v)o(e)f(to)h(be)g(f)o(actory)f(functions)g(pro)o (viding)e(the)j(follo)n(wing)e(inter)n(-)208 1658 y(f)o(ace:)208 1791 y FJ(factory\()p FK(err)l(or)o(s)p FJ(='strict'\))208 1924 y FN(The)66 b(f)o(actory)f(functions)g(must)i(return)f(objects)g (pro)o(viding)e(the)i(interf)o(aces)g(de\002ned)g(by)g(the)h(base)f (classes)208 2023 y FJ(IncrementalEncoder)13 b FN(and)j FJ(IncrementalEncoder)p FN(,)e(respecti)n(v)o(ely)-5 b(.)22 b(Incremental)14 b(codecs)i(can)h(maintain)e(state.)208 2156 y FK(str)m(eamr)m(eader)21 b FN(and)f FK(str)m(eamwriter)r FN(:)27 b(These)20 b(ha)n(v)o(e)f(to)i(be)f(f)o(actory)f(functions)g (pro)o(viding)e(the)j(follo)n(wing)f(interf)o(ace:)208 2289 y FJ(factory\()p FK(str)m(eam)p FJ(,)48 b FK(err)l(or)o(s)p FJ(='strict'\))208 2422 y FN(The)18 b(f)o(actory)g(functions)g(must)h (return)f(objects)h(pro)o(viding)d(the)j(interf)o(aces)g(de\002ned)f (by)h(the)g(base)g(classes)h FJ(StreamWriter)208 2521 y FN(and)f FJ(StreamReader)p FN(,)f(respecti)n(v)o(ely)-5 b(.)23 b(Stream)d(codecs)g(can)g(maintain)f(state.)208 2654 y(Possible)24 b(v)n(alues)g(for)f(errors)g(are)h FJ('strict')f FN(\(raise)h(an)g(e)o(xception)e(in)i(case)h(of)e(an)h (encoding)e(error\),)h FJ('replace')g FN(\(re-)208 2754 y(place)k(malformed)e(data)j(with)g(a)g(suitable)f(replacement)f(mark)o (er)m(,)i(such)g(as)g(`)p FJ(?)p FN('\),)g FJ('ignore')f FN(\(ignore)f(malformed)g(data)208 2853 y(and)19 b(continue)f(without)i (further)e(notice\),)h FJ('xmlcharrefreplace')e FN(\(replace)i(with)h (the)g(appropriate)e(XML)i(character)208 2953 y(reference)f(\(for)h (encoding)f(only\)\))g(and)i FJ('backslashreplace')d FN(\(replace)i(with)h(backslashed)f(escape)g(sequences)h(\(for)208 3053 y(encoding)d(only\)\))g(as)j(well)g(as)g(an)o(y)e(other)h(error)f (handling)f(name)i(de\002ned)f(via)h FJ(register_error\(\))p FN(.)208 3185 y(In)f(case)i(a)g(search)f(function)e(cannot)h(\002nd)h (a)h(gi)n(v)o(en)e(encoding,)e(it)k(should)e(return)g FJ(None)p FN(.)0 3332 y FD(lookup)p FJ(\()p FK(encoding)p FJ(\))208 3432 y FN(Looks)g(up)h(the)g(codec)f(info)h(in)g(the)g (Python)f(codec)h(re)o(gistry)f(and)g(returns)h(a)g FJ(CodecInfo)f FN(object)h(as)h(de\002ned)e(abo)o(v)o(e.)208 3565 y(Encodings)27 b(are)j(\002rst)g(look)o(ed)e(up)i(in)f(the)h(re)o(gistry')-5 b(s)29 b(cache.)53 b(If)29 b(not)g(found,)h(the)g(list)h(of)e(re)o (gistered)f(search)h(functions)g(is)208 3664 y(scanned.)23 b(If)d(no)f FJ(CodecInfo)g FN(object)g(is)i(found,)d(a)i FJ(LookupError)e FN(is)j(raised.)k(Otherwise,)19 b(the)h FJ(CodecInfo)e FN(object)i(is)208 3764 y(stored)f(in)i(the)f(cache)f (and)h(returned)e(to)j(the)f(caller)-5 b(.)0 3911 y(T)e(o)25 b(simplify)g(access)h(to)f(the)h(v)n(arious)e(codecs,)i(the)f(module)f (pro)o(vides)f(these)j(additional)e(functions)g(which)g(use)i FJ(lookup\(\))e FN(for)0 4011 y(the)c(codec)g(lookup:)0 4157 y FD(getencoder)p FJ(\()p FK(encoding)p FJ(\))208 4257 y FN(Look)f(up)g(the)i(codec)e(for)g(the)i(gi)n(v)o(en)e(encoding) f(and)h(return)g(its)j(encoder)c(function.)208 4390 y(Raises)j(a)g FJ(LookupError)d FN(in)j(case)f(the)h(encoding)d(cannot)h(be)h(found.)0 4537 y FD(getdecoder)p FJ(\()p FK(encoding)p FJ(\))208 4636 y FN(Look)f(up)g(the)i(codec)e(for)g(the)i(gi)n(v)o(en)e(encoding) f(and)h(return)g(its)j(decoder)c(function.)208 4769 y(Raises)j(a)g FJ(LookupError)d FN(in)j(case)f(the)h(encoding)d(cannot)h(be)h(found.)0 4916 y FD(getincrementalencoder)p FJ(\()p FK(encoding)o FJ(\))208 5016 y FN(Look)f(up)g(the)i(codec)e(for)g(the)i(gi)n(v)o(en)e (encoding)f(and)h(return)g(its)j(incremental)c(encoder)h(class)i(or)f (f)o(actory)f(function.)208 5149 y(Raises)29 b(a)f FJ(LookupError)f FN(in)h(case)h(the)f(encoding)e(cannot)h(be)h(found)e(or)i(the)g(codec) f(doesn')o(t)f(support)h(an)h(incremental)208 5248 y(encoder)-5 b(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)p 0 5549 3901 4 v 0 5649 a FI(78)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 79 91 TeXDict begin 79 90 bop 0 83 a FD(getincrementaldecoder)p FJ(\()p FK(encoding)o FJ(\))208 183 y FN(Look)19 b(up)g(the)i(codec)e (for)g(the)i(gi)n(v)o(en)e(encoding)f(and)h(return)g(its)j(incremental) c(decoder)h(class)i(or)f(f)o(actory)f(function.)208 315 y(Raises)29 b(a)f FJ(LookupError)f FN(in)h(case)h(the)f(encoding)e (cannot)h(be)h(found)e(or)i(the)g(codec)f(doesn')o(t)f(support)h(an)h (incremental)208 415 y(decoder)-5 b(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 562 y FD(getreader)p FJ(\()p FK(encoding)p FJ(\))208 662 y FN(Look)g(up)g(the)i(codec)e(for)g(the)i (gi)n(v)o(en)e(encoding)f(and)h(return)g(its)j(StreamReader)d(class)i (or)f(f)o(actory)f(function.)208 794 y(Raises)i(a)g FJ(LookupError)d FN(in)j(case)f(the)h(encoding)d(cannot)h(be)h(found.)0 941 y FD(getwriter)p FJ(\()p FK(encoding)p FJ(\))208 1041 y FN(Look)f(up)g(the)i(codec)e(for)g(the)i(gi)n(v)o(en)e(encoding) f(and)h(return)g(its)j(StreamWriter)d(class)i(or)f(f)o(actory)f (function.)208 1174 y(Raises)i(a)g FJ(LookupError)d FN(in)j(case)f(the) h(encoding)d(cannot)h(be)h(found.)0 1321 y FD(register_error)p FJ(\()p FK(name)o(,)d(err)l(or)p 1144 1321 25 4 v 30 w(handler)r FJ(\))208 1420 y FN(Re)o(gister)24 b(the)h(error)f (handling)f(function)g FK(err)l(or)p 1616 1420 V 31 w(handler)i FN(under)f(the)h(name)f FK(name)p FN(.)38 b FK(err)l(or)p 2890 1420 V 31 w(handler)25 b FN(will)h(be)f(called)f(during)208 1520 y(encoding)18 b(and)h(decoding)f(in)j(case)f(of)g(an)g(error)m(,)f (when)h FK(name)f FN(is)i(speci\002ed)f(as)h(the)f(errors)g(parameter) -5 b(.)208 1653 y(F)o(or)20 b(encoding)g FK(err)l(or)p 846 1653 V 30 w(handler)i FN(will)g(be)f(called)h(with)f(a)h FJ(UnicodeEncodeError)c FN(instance,)j(which)g(contains)g(informa-)208 1752 y(tion)h(about)g(the)h(location)f(of)h(the)g(error)-5 b(.)32 b(The)22 b(error)g(handler)g(must)h(either)f(raise)h(this)h(or)e (a)i(dif)n(ferent)d(e)o(xception)g(or)h(return)g(a)208 1852 y(tuple)f(with)i(a)g(replacement)d(for)i(the)g(unencodable)e(part) h(of)h(the)h(input)e(and)h(a)h(position)e(where)h(encoding)e(should)h (continue.)208 1952 y(The)28 b(encoder)g(will)h(encode)f(the)h (replacement)e(and)i(continue)e(encoding)g(the)i(original)f(input)g(at) i(the)f(speci\002ed)g(position.)208 2051 y(Ne)o(gati)n(v)o(e)20 b(position)h(v)n(alues)g(will)i(be)f(treated)f(as)i(being)e(relati)n(v) o(e)g(to)h(the)g(end)f(of)h(the)g(input)f(string.)30 b(If)21 b(the)h(resulting)f(position)208 2151 y(is)g(out)f(of)f(bound)g (an)h FJ(IndexError)f FN(will)i(be)f(raised.)208 2284 y(Decoding)25 b(and)h(translating)g(w)o(orks)h(similar)m(,)h(e)o(xcept) e FJ(UnicodeDecodeError)e FN(or)j FJ(UnicodeTranslateError)208 2383 y FN(will)20 b(be)f(passed)g(to)h(the)f(handler)f(and)h(that)g (the)h(replacement)d(from)i(the)g(error)f(handler)g(will)i(be)f(put)g (into)h(the)f(output)f(directly)-5 b(.)0 2530 y FD(lookup_error)p FJ(\()p FK(name)p FJ(\))208 2630 y FN(Return)19 b(the)i(error)e (handler)f(pre)n(viously)g(re)o(gistered)h(under)g(the)h(name)g FK(name)p FN(.)208 2763 y(Raises)h(a)g FJ(LookupError)d FN(in)j(case)f(the)h(handler)d(cannot)h(be)i(found.)0 2910 y FD(strict_errors)p FJ(\()p FK(e)n(xception)p FJ(\))208 3009 y FN(Implements)d(the)j FJ(strict)e FN(error)g(handling.)0 3156 y FD(replace_errors)p FJ(\()p FK(e)n(xception)p FJ(\))208 3256 y FN(Implements)f(the)j FJ(replace)e FN(error)g (handling.)0 3403 y FD(ignore_errors)p FJ(\()p FK(e)n(xception)p FJ(\))208 3502 y FN(Implements)f(the)j FJ(ignore)e FN(error)g (handling.)0 3649 y FD(xmlcharrefreplace_errors_errors)p FJ(\()p FK(e)n(xcep)o(tion)o FJ(\))208 3749 y FN(Implements)f(the)j FJ(xmlcharrefreplace)c FN(error)i(handling.)0 3896 y FD(backslashreplace_errors_errors)p FJ(\()p FK(e)n(xceptio)o(n)p FJ(\))208 3995 y FN(Implements)f(the)j FJ(backslashreplace)c FN(error)i(handling.)0 4142 y(T)-7 b(o)20 b(simplify)g(w)o(orking)f (with)h(encoded)e(\002les)j(or)f(stream,)g(the)g(module)f(also)i (de\002nes)f(these)g(utility)g(functions:)0 4289 y FD(open)p FJ(\()p FK(\002lename)o(,)e(mode)p FC([)p FK(,)h(encoding)p FC([)p FK(,)f(err)l(or)o(s)p FC([)p FK(,)j(b)n(uf)o(fering)12 b FC(])g(])g(])p FJ(\))208 4389 y FN(Open)39 b(an)h(encoded)e(\002le)j (using)e(the)h(gi)n(v)o(en)f FK(mode)h FN(and)f(return)g(a)h(wrapped)f (v)o(ersion)f(pro)o(viding)g(transparent)g(encod-)208 4488 y(ing/decoding.)208 4621 y FL(Note:)32 b FN(The)25 b(wrapped)d(v)o(ersion)i(will)h(only)f(accept)g(the)g(object)g(format)f (de\002ned)h(by)g(the)g(codecs,)h(i.e.)g(Unicode)e(objects)h(for)208 4721 y(most)c(b)n(uilt-in)f(codecs.)25 b(Output)19 b(is)i(also)g (codec-dependent)16 b(and)k(will)h(usually)e(be)h(Unicode)f(as)i(well.) 208 4853 y FK(encoding)d FN(speci\002es)i(the)h(encoding)d(which)h(is)i (to)g(be)f(used)g(for)f(the)i(\002le.)208 4986 y FK(err)l(or)o(s)g FN(may)e(be)h(gi)n(v)o(en)f(to)g(de\002ne)h(the)g(error)e(handling.)23 b(It)d(def)o(aults)g(to)g FJ('strict')f FN(which)g(causes)h(a)g FJ(ValueError)f FN(to)h(be)208 5086 y(raised)g(in)g(case)h(an)f (encoding)e(error)h(occurs.)208 5219 y FK(b)n(uf)o(fering)g FN(has)h(the)g(same)h(meaning)d(as)j(for)f(the)g(b)n(uilt-in)g FJ(open\(\))f FN(function.)k(It)e(def)o(aults)f(to)g(line)g(b)n(uf)n (fered.)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and)g(base)h(classes)1986 b(79)p eop end %%Page: 80 92 TeXDict begin 80 91 bop 0 83 a FD(EncodedFile)p FJ(\()p FK(\002le)o(,)18 b(input)q FC([)p FK(,)h(output)q FC([)p FK(,)g(err)l(or)o(s)12 b FC(])g(])p FJ(\))208 183 y FN(Return)19 b(a)i(wrapped)e(v)o(ersion)f(of)i(\002le)h(which)f(pro)o(vides)e (transparent)h(encoding)f(translation.)208 315 y(Strings)28 b(written)g(to)g(the)g(wrapped)f(\002le)i(are)f(interpreted)e (according)g(to)j(the)f(gi)n(v)o(en)f FK(input)i FN(encoding)d(and)i (then)f(written)h(to)208 415 y(the)d(original)g(\002le)h(as)g(strings)g (using)f(the)g FK(output)h FN(encoding.)39 b(The)26 b(intermediate)e (encoding)f(will)k(usually)e(be)g(Unicode)g(b)n(ut)208 515 y(depends)18 b(on)i(the)g(speci\002ed)g(codecs.)208 648 y(If)g FK(output)g FN(is)h(not)f(gi)n(v)o(en,)f(it)i(def)o(aults)e (to)i FK(input)q FN(.)208 780 y FK(err)l(or)o(s)i FN(may)e(be)h(gi)n(v) o(en)e(to)i(de\002ne)f(the)h(error)f(handling.)28 b(It)22 b(def)o(aults)f(to)h FJ('strict')p FN(,)f(which)g(causes)h FJ(ValueError)f FN(to)h(be)208 880 y(raised)e(in)g(case)h(an)f (encoding)e(error)h(occurs.)0 1027 y FD(iterencode)p FJ(\()p FK(iter)o(able)o(,)f(encoding)p FC([)p FK(,)f(err)l(or)o(s)12 b FC(])p FJ(\))208 1127 y FN(Uses)24 b(an)f(incremental)f(encoder)f(to) j(iterati)n(v)o(ely)e(encode)g(the)h(input)f(pro)o(vided)f(by)i FK(iter)o(able)p FN(.)34 b(This)23 b(function)e(is)k(a)e(generator)-5 b(.)208 1226 y FK(err)l(or)o(s)23 b FN(\(as)g(well)g(as)g(an)o(y)e (other)h(k)o(e)o(yw)o(ord)e(ar)o(gument\))g(is)j(passed)f(through)e(to) j(the)f(incremental)f(encoder)-5 b(.)62 b(Ne)n(w)22 b(in)h(v)o(ersion) 208 1326 y(2.5.)0 1473 y FD(iterdecode)p FJ(\()p FK(iter)o(able)o(,)18 b(encoding)p FC([)p FK(,)f(err)l(or)o(s)12 b FC(])p FJ(\))208 1572 y FN(Uses)24 b(an)f(incremental)f(decoder)f(to)j(iterati)n(v)o (ely)e(decode)g(the)h(input)f(pro)o(vided)f(by)i FK(iter)o(able)p FN(.)34 b(This)23 b(function)e(is)k(a)e(generator)-5 b(.)208 1672 y FK(err)l(or)o(s)23 b FN(\(as)g(well)g(as)g(an)o(y)e (other)h(k)o(e)o(yw)o(ord)e(ar)o(gument\))g(is)j(passed)f(through)e(to) j(the)f(incremental)f(encoder)-5 b(.)62 b(Ne)n(w)22 b(in)h(v)o(ersion) 208 1772 y(2.5.)0 1918 y(The)17 b(module)f(also)i(pro)o(vides)e(the)h (follo)n(wing)f(constants)h(which)g(are)g(useful)g(for)g(reading)f(and) h(writing)g(to)g(platform)f(dependent)g(\002les:)0 2065 y FD(BOM)0 2165 y(BOM_BE)0 2265 y(BOM_LE)0 2364 y(BOM_UTF8)0 2464 y(BOM_UTF16)0 2563 y(BOM_UTF16_BE)0 2663 y(BOM_UTF16_LE)0 2763 y(BOM_UTF32)0 2862 y(BOM_UTF32_BE)0 2962 y(BOM_UTF32_LE)208 3062 y FN(These)k(constants)h(de\002ne)g(v)n(arious)f(encodings)f(of)i (the)g(Unicode)f(byte)h(order)e(mark)i(\(BOM\))g(used)g(in)g(UTF-16)f (and)h(UTF-32)208 3161 y(data)h(streams)g(to)h(indicate)e(the)i(byte)f (order)f(used)h(in)g(the)g(stream)h(or)f(\002le)h(and)e(in)i(UTF-8)f (as)h(a)g(Unicode)e(signature.)30 b FJ(BOM_-)208 3261 y(UTF16)e FN(is)h(either)f FJ(BOM_UTF16_BE)e FN(or)j FJ(BOM_UTF16_LE)d FN(depending)g(on)i(the)g(platform')-5 b(s)28 b(nati)n(v)o(e)f(byte)h(order)m(,)h FJ(BOM)208 3360 y FN(is)g(an)g(alias)g(for)f FJ(BOM_UTF16)p FN(,)h FJ(BOM_LE)f FN(for)g FJ(BOM_UTF16_LE)f FN(and)h FJ(BOM_BE)g FN(for)g FJ(BOM_UTF16_BE)p FN(.)f(The)h(others)208 3460 y(represent)19 b(the)h(BOM)h(in)f(UTF-8)g(and)f(UTF-32)h(encodings.)0 3745 y Fv(4.8.1)100 b(Codec)29 b(Base)g(Classes)0 3948 y FN(The)21 b FJ(codecs)g FN(module)f(de\002nes)h(a)h(set)g(of)f(base)h (classes)g(which)f(de\002ne)g(the)h(interf)o(ace)e(and)h(can)g(also)h (be)f(used)h(to)f(easily)h(write)f(you)0 4047 y(o)n(wn)f(codecs)f(for)h (use)g(in)h(Python.)0 4194 y(Each)26 b(codec)g(has)h(to)f(de\002ne)g (four)g(interf)o(aces)g(to)g(mak)o(e)g(it)i(usable)e(as)h(codec)f(in)h (Python:)36 b(stateless)28 b(encoder)m(,)e(stateless)i(decoder)m(,)0 4294 y(stream)20 b(reader)f(and)g(stream)h(writer)-5 b(.)25 b(The)20 b(stream)g(reader)f(and)g(writers)h(typically)f(reuse)h (the)g(stateless)h(encoder/decoder)16 b(to)k(imple-)0 4394 y(ment)g(the)g(\002le)h(protocols.)0 4540 y(The)f FJ(Codec)g FN(class)h(de\002nes)f(the)g(interf)o(ace)f(for)h(stateless) h(encoders/decoders.)0 4687 y(T)-7 b(o)23 b(simplify)f(and)g (standardize)f(error)g(handling,)g(the)i FJ(encode\(\))e FN(and)h FJ(decode\(\))g FN(methods)f(may)i(implement)e(dif)n(ferent)g (error)0 4787 y(handling)f(schemes)i(by)g(pro)o(viding)d(the)j FK(err)l(or)o(s)i FN(string)e(ar)o(gument.)28 b(The)22 b(follo)n(wing)e(string)i(v)n(alues)g(are)g(de\002ned)f(and)g (implemented)0 4887 y(by)f(all)h(standard)e(Python)g(codecs:)p 0 5549 3901 4 v 0 5649 a FI(80)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 81 93 TeXDict begin 81 92 bop 50 70 a FL(V)-8 b(alue)p 1044 100 4 100 v 846 w(Meaning)p 0 103 7264 4 v 50 173 a FJ('strict')p 1044 203 4 100 v 646 w FN(Raise)21 b FJ(UnicodeError)e FN(\(or)g(a)i(subclass\);)f(this)h(is)g(the)f(def)o(ault.)50 272 y FJ('ignore')p 1044 302 V 646 w FN(Ignore)e(the)j(character)d(and) i(continue)f(with)h(the)g(ne)o(xt.)50 372 y FJ('replace')p 1044 402 V 596 w FN(Replace)g(with)g(a)h(suitable)f(replacement)f (character;)g(Python)g(will)i(use)f(the)g(of)n(\002cial)g(U+FFFD)h (REPLA)m(CEMENT)f(CHARA)m(CTER)h(for)e(the)i(b)n(uilt-in)e(Unicode)g (codecs)h(on)g(decoding)e(and)h('?')25 b(on)20 b(encoding.)50 472 y FJ('xmlcharrefreplace')p 1044 501 V 96 w FN(Replace)g(with)g(the) h(appropriate)c(XML)k(character)e(reference)f(\(only)h(for)h (encoding\).)50 571 y FJ('backslashreplace')p 1044 601 V 146 w FN(Replace)g(with)g(backslashed)f(escape)h(sequences)g(\(only)f (for)g(encoding\).)0 796 y(The)h(set)h(of)f(allo)n(wed)f(v)n(alues)h (can)g(be)g(e)o(xtended)e(via)j FJ(register_error)p FN(.)0 1065 y FI(Codec)i(Objects)0 1267 y FN(The)18 b FJ(Codec)g FN(class)h(de\002nes)f(these)g(methods)f(which)h(also)g(de\002ne)g(the) g(function)e(interf)o(aces)i(of)g(the)g(stateless)h(encoder)e(and)g (decoder:)0 1414 y FD(encode)p FJ(\()p FK(input)q FC([)p FK(,)h(err)l(or)o(s)12 b FC(])p FJ(\))208 1514 y FN(Encodes)k(the)i (object)f FK(input)h FN(and)f(returns)g(a)h(tuple)f(\(output)f(object,) h(length)g(consumed\).)22 b(While)c(codecs)f(are)g(not)g(restricted)g (to)208 1614 y(use)k(with)g(Unicode,)f(in)i(a)f(Unicode)f(conte)o(xt,)g (encoding)f(con)m(v)o(erts)h(a)h(Unicode)f(object)h(to)g(a)h(plain)f (string)g(using)f(a)i(particular)208 1713 y(character)c(set)j(encoding) e(\(e.g.,)g FJ(cp1252)g FN(or)h FJ(iso-8859-1)p FN(\).)208 1846 y FK(err)l(or)o(s)h FN(de\002nes)f(the)g(error)g(handling)e(to)i (apply)-5 b(.)24 b(It)c(def)o(aults)g(to)g FJ('strict')g FN(handling.)208 1979 y(The)25 b(method)g(may)g(not)h(store)g(state)g (in)g(the)g FJ(Codec)g FN(instance.)42 b(Use)26 b FJ(StreamCodec)f FN(for)g(codecs)g(which)h(ha)n(v)o(e)f(to)h(k)o(eep)208 2079 y(state)20 b(in)h(order)e(to)h(mak)o(e)g(encoding/decoding)15 b(ef)n(\002cient.)208 2211 y(The)i(encoder)g(must)h(be)h(able)f(to)g (handle)f(zero)h(length)f(input)h(and)g(return)f(an)h(empty)f(object)h (of)g(the)g(output)f(object)h(type)g(in)g(this)208 2311 y(situation.)0 2458 y FD(decode)p FJ(\()p FK(input)q FC([)p FK(,)g(err)l(or)o(s)12 b FC(])p FJ(\))208 2557 y FN(Decodes)21 b(the)g(object)h FK(input)g FN(and)f(returns)g(a)h (tuple)f(\(output)g(object,)g(length)g(consumed\).)27 b(In)21 b(a)i(Unicode)d(conte)o(xt,)h(decoding)208 2657 y(con)m(v)o(erts)d(a)j(plain)e(string)h(encoded)f(using)g(a)i (particular)e(character)g(set)i(encoding)d(to)i(a)h(Unicode)e(object.) 208 2790 y FK(input)25 b FN(must)f(be)h(an)f(object)g(which)g(pro)o (vides)f(the)i FJ(bf_getreadbuf)d FN(b)n(uf)n(fer)h(slot.)39 b(Python)23 b(strings,)j(b)n(uf)n(fer)d(objects)h(and)208 2890 y(memory)18 b(mapped)h(\002les)i(are)f(e)o(xamples)f(of)h(objects) g(pro)o(viding)d(this)k(slot.)208 3022 y FK(err)l(or)o(s)g FN(de\002nes)f(the)g(error)g(handling)e(to)i(apply)-5 b(.)24 b(It)c(def)o(aults)g(to)g FJ('strict')g FN(handling.)208 3155 y(The)25 b(method)g(may)g(not)h(store)g(state)g(in)g(the)g FJ(Codec)g FN(instance.)42 b(Use)26 b FJ(StreamCodec)f FN(for)g(codecs)g(which)h(ha)n(v)o(e)f(to)h(k)o(eep)208 3255 y(state)20 b(in)h(order)e(to)h(mak)o(e)g(encoding/decoding)15 b(ef)n(\002cient.)208 3388 y(The)i(decoder)g(must)h(be)h(able)f(to)g (handle)f(zero)h(length)f(input)h(and)g(return)f(an)h(empty)f(object)h (of)g(the)g(output)f(object)h(type)g(in)g(this)208 3487 y(situation.)0 3634 y(The)32 b FJ(IncrementalEncoder)d FN(and)i FJ(IncrementalDecoder)e FN(classes)k(pro)o(vide)d(the)i(basic) g(interf)o(ace)f(for)g(incremental)0 3734 y(encoding)21 b(and)i(decoding.)33 b(Encoding/decoding)18 b(the)24 b(input)f(isn')o(t)g(done)f(with)i(one)f(call)g(to)h(the)g(stateless)g (encoder/decoder)c(func-)0 3833 y(tion,)27 b(b)n(ut)e(with)h(multiple)f (calls)i(to)e(the)h FJ(encode)p FN(/)p FJ(decode)e FN(method)g(of)i (the)g(incremental)e(encoder/decoder)-5 b(.)38 b(The)25 b(incremental)0 3933 y(encoder/decoder)16 b(k)o(eeps)k(track)g(of)g (the)g(encoding/decoding)c(process)j(during)g(method)g(calls.)0 4080 y(The)g(joined)g(output)f(of)h(calls)i(to)e(the)h FJ(encode)p FN(/)p FJ(decode)e FN(method)g(is)i(the)g(same)g(as)g(if)g (all)g(the)f(single)h(inputs)f(were)g(joined)g(into)g(one,)0 4180 y(and)h(this)g(input)g(w)o(as)h(encoded/decoded)16 b(with)k(the)g(stateless)i(encoder/decoder)-5 b(.)0 4448 y FI(IncrementalEncoder)24 b(Objects)0 4651 y FN(Ne)n(w)c(in)h(v)o (ersion)e(2.5.)0 4798 y(The)h FJ(IncrementalEncoder)d FN(class)k(is)h(used)e(for)f(encoding)f(an)i(input)g(in)g(multiple)g (steps.)25 b(It)c(de\002nes)f(the)g(follo)n(wing)f(methods)0 4897 y(which)h(e)n(v)o(ery)e(incremental)h(encoder)g(must)h(de\002ne)g (in)g(order)f(to)h(be)g(compatible)f(with)h(the)h(Python)e(codec)g(re)o (gistry)-5 b(.)0 5044 y FL(class)21 b FD(IncrementalEncoder)p FJ(\()p FC([)p FK(err)l(or)o(s)12 b FC(])p FJ(\))208 5144 y FN(Constructor)18 b(for)i(an)g FJ(IncrementalEncoder)d FN(instance.)208 5277 y(All)32 b(incremental)e(encoders)g(must)i(pro)o (vide)d(this)j(constructor)e(interf)o(ace.)58 b(The)o(y)31 b(are)g(free)g(to)h(add)f(additional)f(k)o(e)o(yw)o(ord)208 5376 y(ar)o(guments,)17 b(b)n(ut)k(only)e(the)h(ones)g(de\002ned)f (here)h(are)g(used)g(by)g(the)g(Python)f(codec)g(re)o(gistry)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and)g(base)h(classes)1986 b(81)p eop end %%Page: 82 94 TeXDict begin 82 93 bop 208 83 a FN(The)23 b FJ(IncrementalEncoder)f FN(may)i(implement)e(dif)n(ferent)h(error)g(handling)f(schemes)i(by)g (pro)o(viding)e(the)i FK(err)l(or)o(s)i FN(k)o(e)o(y-)208 183 y(w)o(ord)19 b(ar)o(gument.)k(These)d(parameters)f(are)h (prede\002ned:)349 395 y FM(\017)o FJ('strict')f FN(Raise)j FJ(ValueError)d FN(\(or)g(a)i(subclass\);)f(this)h(is)g(the)f(def)o (ault.)349 527 y FM(\017)o FJ('ignore')f FN(Ignore)g(the)h(character)f (and)h(continue)e(with)j(the)f(ne)o(xt.)349 659 y FM(\017)o FJ('replace')f FN(Replace)h(with)h(a)f(suitable)g(replacement)f (character)349 791 y FM(\017)o FJ('xmlcharrefreplace')e FN(Replace)k(with)f(the)g(appropriate)e(XML)i(character)f(reference)349 923 y FM(\017)o FJ('backslashreplace')f FN(Replace)i(with)g (backslashed)f(escape)h(sequences.)208 1136 y(The)f FK(err)l(or)o(s)j FN(ar)o(gument)c(will)j(be)f(assigned)f(to)i(an)f(attrib)n(ute)f(of)h (the)g(same)h(name.)j(Assigning)c(to)g(this)g(attrib)n(ute)g(mak)o(es)g (it)h(pos-)208 1235 y(sible)g(to)h(switch)g(between)e(dif)n(ferent)g (error)g(handling)g(strate)o(gies)h(during)f(the)h(lifetime)h(of)f(the) g FJ(IncrementalEncoder)208 1335 y FN(object.)208 1467 y(The)e(set)i(of)f(allo)n(wed)g(v)n(alues)g(for)f(the)h FK(err)l(or)o(s)i FN(ar)o(gument)c(can)i(be)g(e)o(xtended)e(with)j FJ(register_error\(\))p FN(.)0 1614 y FD(encode)p FJ(\()p FK(object)q FC([)p FK(,)d(\002nal)12 b FC(])p FJ(\))208 1714 y FN(Encodes)17 b FK(object)j FN(\(taking)e(the)h(current)e(state) j(of)e(the)h(encoder)f(into)g(account\))f(and)i(returns)f(the)h (resulting)f(encoded)f(object.)24 b(If)208 1813 y(this)c(is)h(the)g (last)g(call)f(to)h FJ(encode)e FK(\002nal)h FN(must)g(be)g(true)g (\(the)g(def)o(ault)f(is)i(f)o(alse\).)0 1960 y FD(reset)p FJ(\(\))208 2060 y FN(Reset)g(the)f(encoder)f(to)h(the)g(initial)h (state.)0 2328 y FI(IncrementalDecoder)j(Objects)0 2531 y FN(The)c FJ(IncrementalDecoder)d FN(class)k(is)h(used)e(for)f (decoding)f(an)i(input)g(in)g(multiple)g(steps.)25 b(It)c(de\002nes)f (the)g(follo)n(wing)f(methods)0 2630 y(which)h(e)n(v)o(ery)e (incremental)h(decoder)g(must)h(de\002ne)g(in)g(order)f(to)h(be)g (compatible)f(with)h(the)h(Python)e(codec)g(re)o(gistry)-5 b(.)0 2777 y FL(class)21 b FD(IncrementalDecoder)p FJ(\()p FC([)p FK(err)l(or)o(s)12 b FC(])p FJ(\))208 2877 y FN(Constructor)18 b(for)i(an)g FJ(IncrementalDecoder)d FN(instance.)208 3009 y(All)32 b(incremental)e(decoders)g(must)i(pro)o(vide)d(this)j (constructor)e(interf)o(ace.)58 b(The)o(y)31 b(are)g(free)g(to)h(add)f (additional)f(k)o(e)o(yw)o(ord)208 3109 y(ar)o(guments,)17 b(b)n(ut)k(only)e(the)h(ones)g(de\002ned)f(here)h(are)g(used)g(by)g (the)g(Python)f(codec)g(re)o(gistry)-5 b(.)208 3241 y(The)23 b FJ(IncrementalDecoder)f FN(may)i(implement)e(dif)n(ferent)h(error)g (handling)f(schemes)i(by)g(pro)o(viding)e(the)i FK(err)l(or)o(s)i FN(k)o(e)o(y-)208 3341 y(w)o(ord)19 b(ar)o(gument.)k(These)d (parameters)f(are)h(prede\002ned:)349 3553 y FM(\017)o FJ('strict')f FN(Raise)j FJ(ValueError)d FN(\(or)g(a)i(subclass\);)f (this)h(is)g(the)f(def)o(ault.)349 3685 y FM(\017)o FJ('ignore')f FN(Ignore)g(the)h(character)f(and)h(continue)e(with)j(the)f(ne)o(xt.) 349 3817 y FM(\017)o FJ('replace')f FN(Replace)h(with)h(a)f(suitable)g (replacement)f(character)-5 b(.)208 4030 y(The)19 b FK(err)l(or)o(s)j FN(ar)o(gument)c(will)j(be)f(assigned)f(to)i(an)f(attrib)n(ute)f(of)h (the)g(same)h(name.)j(Assigning)c(to)g(this)g(attrib)n(ute)g(mak)o(es)g (it)h(pos-)208 4130 y(sible)g(to)h(switch)g(between)e(dif)n(ferent)g (error)g(handling)g(strate)o(gies)h(during)f(the)h(lifetime)h(of)f(the) g FJ(IncrementalEncoder)208 4229 y FN(object.)208 4362 y(The)e(set)i(of)f(allo)n(wed)g(v)n(alues)g(for)f(the)h FK(err)l(or)o(s)i FN(ar)o(gument)c(can)i(be)g(e)o(xtended)e(with)j FJ(register_error\(\))p FN(.)0 4509 y FD(decode)p FJ(\()p FK(object)q FC([)p FK(,)d(\002nal)12 b FC(])p FJ(\))208 4608 y FN(Decodes)18 b FK(object)h FN(\(taking)e(the)i(current)e(state) j(of)e(the)h(decoder)e(into)h(account\))f(and)h(returns)g(the)g (resulting)g(decoded)f(object.)24 b(If)208 4708 y(this)18 b(is)h(the)f(last)h(call)f(to)g FJ(decode)g FK(\002nal)f FN(must)h(be)g(true)f(\(the)h(def)o(ault)f(is)i(f)o(alse\).)24 b(If)18 b FK(\002nal)f FN(is)i(true)f(the)g(decoder)e(must)i(decode)f (the)208 4807 y(input)j(completely)h(and)g(must)g(\003ush)h(all)g(b)n (uf)n(fers.)29 b(If)21 b(this)h(isn')o(t)g(possible)f(\(e.g.)29 b(because)21 b(of)g(incomplete)f(byte)h(sequences)g(at)208 4907 y(the)c(end)f(of)h(the)g(input\))f(it)i(must)f(initiate)g(error)f (handling)g(just)h(lik)o(e)h(in)f(the)g(stateless)h(case)g(\(which)e (might)h(raise)g(an)g(e)o(xception\).)0 5054 y FD(reset)p FJ(\(\))208 5154 y FN(Reset)k(the)f(decoder)f(to)h(the)g(initial)h (state.)0 5300 y(The)g FJ(StreamWriter)e FN(and)h FJ(StreamReader)f FN(classes)j(pro)o(vide)d(generic)h(w)o(orking)f(interf)o(aces)i(which) f(can)h(be)g(used)f(to)h(imple-)0 5400 y(ment)f(ne)n(w)g(encoding)e (submodules)g(v)o(ery)h(easily)-5 b(.)25 b(See)c FJ(encodings.utf_8)d FN(for)h(an)h(e)o(xample)f(of)h(ho)n(w)g(this)g(is)i(done.)p 0 5549 3901 4 v 0 5649 a FI(82)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 83 95 TeXDict begin 83 94 bop 0 83 a FI(StreamWr)q(iter)24 b(Objects)0 286 y FN(The)17 b FJ(StreamWriter)e FN(class)j(is)g(a)g (subclass)f(of)g FJ(Codec)g FN(and)g(de\002nes)f(the)i(follo)n(wing)d (methods)h(which)h(e)n(v)o(ery)f(stream)h(writer)g(must)0 386 y(de\002ne)j(in)g(order)f(to)h(be)g(compatible)f(with)h(the)h (Python)e(codec)g(re)o(gistry)-5 b(.)0 532 y FL(class)21 b FD(StreamWriter)p FJ(\()p FK(str)m(eam)p FC([)p FK(,)d(err)l(or)o(s) 12 b FC(])p FJ(\))208 632 y FN(Constructor)18 b(for)i(a)h FJ(StreamWriter)d FN(instance.)208 765 y(All)k(stream)g(writers)g(must) g(pro)o(vide)e(this)j(constructor)d(interf)o(ace.)30 b(The)o(y)21 b(are)h(free)f(to)h(add)g(additional)f(k)o(e)o(yw)o(ord)f (ar)o(guments,)208 865 y(b)n(ut)g(only)f(the)h(ones)g(de\002ned)f(here) h(are)g(used)g(by)g(the)g(Python)f(codec)h(re)o(gistry)-5 b(.)208 997 y FK(str)m(eam)20 b FN(must)g(be)h(a)f(\002le-lik)o(e)g (object)g(open)f(for)h(writing)f(binary)g(data.)208 1130 y(The)h FJ(StreamWriter)g FN(may)g(implement)g(dif)n(ferent)f(error)h (handling)f(schemes)i(by)f(pro)o(viding)f(the)i FK(err)l(or)o(s)h FN(k)o(e)o(yw)o(ord)d(ar)o(gu-)208 1230 y(ment.)24 b(These)c (parameters)f(are)h(prede\002ned:)349 1443 y FM(\017)o FJ('strict')f FN(Raise)j FJ(ValueError)d FN(\(or)g(a)i(subclass\);)f (this)h(is)g(the)f(def)o(ault.)349 1576 y FM(\017)o FJ('ignore')f FN(Ignore)g(the)h(character)f(and)h(continue)e(with)j(the)f(ne)o(xt.) 349 1709 y FM(\017)o FJ('replace')f FN(Replace)h(with)h(a)f(suitable)g (replacement)f(character)349 1842 y FM(\017)o FJ('xmlcharrefreplace')e FN(Replace)k(with)f(the)g(appropriate)e(XML)i(character)f(reference)349 1974 y FM(\017)o FJ('backslashreplace')f FN(Replace)i(with)g (backslashed)f(escape)h(sequences.)208 2188 y(The)28 b FK(err)l(or)o(s)h FN(ar)o(gument)d(will)j(be)g(assigned)f(to)g(an)g (attrib)n(ute)g(of)g(the)h(same)f(name.)49 b(Assigning)27 b(to)i(this)g(attrib)n(ute)f(mak)o(es)g(it)208 2287 y(possible)16 b(to)h(switch)h(between)e(dif)n(ferent)f(error)h(handling)f(strate)o (gies)i(during)e(the)i(lifetime)g(of)g(the)g FJ(StreamWriter)e FN(object.)208 2420 y(The)k(set)i(of)f(allo)n(wed)g(v)n(alues)g(for)f (the)h FK(err)l(or)o(s)i FN(ar)o(gument)c(can)i(be)g(e)o(xtended)e (with)j FJ(register_error\(\))p FN(.)0 2567 y FD(write)p FJ(\()p FK(object)q FJ(\))208 2667 y FN(Writes)g(the)f(object')-5 b(s)20 b(contents)f(encoded)g(to)h(the)g(stream.)0 2814 y FD(writelines)p FJ(\()p FK(list)q FJ(\))208 2913 y FN(Writes)h(the)f(concatenated)e(list)j(of)f(strings)g(to)h(the)f (stream)g(\(possibly)f(by)h(reusing)f(the)h FJ(write\(\))g FN(method\).)0 3060 y FD(reset)p FJ(\(\))208 3160 y FN(Flushes)g(and)g (resets)g(the)h(codec)e(b)n(uf)n(fers)g(used)h(for)g(k)o(eeping)e (state.)208 3293 y(Calling)23 b(this)g(method)f(should)g(ensure)g(that) h(the)g(data)g(on)f(the)h(output)f(is)i(put)f(into)f(a)i(clean)e(state) i(that)f(allo)n(ws)g(appending)e(of)208 3392 y(ne)n(w)f(fresh)f(data)h (without)g(ha)n(ving)f(to)h(rescan)g(the)g(whole)g(stream)g(to)g(reco)o (v)o(er)e(state.)0 3539 y(In)26 b(addition)f(to)i(the)f(abo)o(v)o(e)f (methods,)h(the)g FJ(StreamWriter)f FN(must)h(also)h(inherit)f(all)h (other)e(methods)g(and)h(attrib)n(utes)g(from)g(the)0 3639 y(underlying)17 b(stream.)0 3907 y FI(StreamReader)24 b(Objects)0 4110 y FN(The)j FJ(StreamReader)g FN(class)h(is)h(a)f (subclass)g(of)g FJ(Codec)f FN(and)g(de\002nes)h(the)g(follo)n(wing)e (methods)g(which)i(e)n(v)o(ery)e(stream)i(reader)0 4209 y(must)20 b(de\002ne)g(in)g(order)f(to)i(be)f(compatible)e(with)j(the)f (Python)f(codec)g(re)o(gistry)-5 b(.)0 4356 y FL(class)21 b FD(StreamReader)p FJ(\()p FK(str)m(eam)p FC([)p FK(,)d(err)l(or)o(s) 12 b FC(])p FJ(\))208 4456 y FN(Constructor)18 b(for)i(a)h FJ(StreamReader)d FN(instance.)208 4589 y(All)k(stream)f(readers)g (must)g(pro)o(vide)f(this)i(constructor)d(interf)o(ace.)28 b(The)o(y)21 b(are)g(free)g(to)h(add)f(additional)f(k)o(e)o(yw)o(ord)g (ar)o(guments,)208 4688 y(b)n(ut)g(only)f(the)h(ones)g(de\002ned)f (here)h(are)g(used)g(by)g(the)g(Python)f(codec)h(re)o(gistry)-5 b(.)208 4821 y FK(str)m(eam)20 b FN(must)g(be)h(a)f(\002le-lik)o(e)g (object)g(open)f(for)h(reading)f(\(binary\))f(data.)208 4954 y(The)i FJ(StreamReader)g FN(may)g(implement)g(dif)n(ferent)f (error)h(handling)f(schemes)i(by)f(pro)o(viding)f(the)i FK(err)l(or)o(s)h FN(k)o(e)o(yw)o(ord)d(ar)o(gu-)208 5054 y(ment.)24 b(These)c(parameters)f(are)h(de\002ned:)349 5267 y FM(\017)o FJ('strict')f FN(Raise)j FJ(ValueError)d FN(\(or)g(a)i(subclass\);)f(this)h(is)g(the)f(def)o(ault.)349 5400 y FM(\017)o FJ('ignore')f FN(Ignore)g(the)h(character)f(and)h (continue)e(with)j(the)f(ne)o(xt.)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and) g(base)h(classes)1986 b(83)p eop end %%Page: 84 96 TeXDict begin 84 95 bop 349 83 a FM(\017)o FJ('replace')19 b FN(Replace)h(with)h(a)f(suitable)g(replacement)f(character)-5 b(.)208 286 y(The)28 b FK(err)l(or)o(s)h FN(ar)o(gument)d(will)j(be)g (assigned)f(to)g(an)g(attrib)n(ute)g(of)g(the)h(same)f(name.)49 b(Assigning)27 b(to)i(this)g(attrib)n(ute)f(mak)o(es)g(it)208 386 y(possible)16 b(to)h(switch)h(between)e(dif)n(ferent)f(error)h (handling)f(strate)o(gies)i(during)e(the)i(lifetime)g(of)g(the)g FJ(StreamReader)e FN(object.)208 513 y(The)k(set)i(of)f(allo)n(wed)g(v) n(alues)g(for)f(the)h FK(err)l(or)o(s)i FN(ar)o(gument)c(can)i(be)g(e)o (xtended)e(with)j FJ(register_error\(\))p FN(.)0 660 y FD(read)p FJ(\()p FC([)p FK(size)p FC([)p FK(,)f(c)o(har)o(s,)g FC([)p FK(\002r)o(stline)12 b FC(])g(])g(])p FJ(\))208 760 y FN(Decodes)19 b(data)h(from)f(the)i(stream)f(and)f(returns)h(the) g(resulting)f(object.)208 888 y FK(c)o(har)o(s)24 b FN(indicates)g(the) h(number)d(of)i(characters)g(to)g(read)g(from)g(the)g(stream.)38 b FJ(read\(\))24 b FN(will)h(ne)n(v)o(er)e(return)g(more)h(than)g FK(c)o(har)o(s)208 987 y FN(characters,)19 b(b)n(ut)h(it)h(might)e (return)g(less,)i(if)g(there)e(are)i(not)e(enough)g(characters)g(a)n(v) n(ailable.)208 1115 y FK(size)k FN(indicates)g(the)g(approximate)d (maximum)h(number)g(of)i(bytes)f(to)h(read)f(from)g(the)h(stream)g(for) f(decoding)e(purposes.)32 b(The)208 1214 y(decoder)23 b(can)i(modify)f(this)h(setting)h(as)g(appropriate.)37 b(The)25 b(def)o(ault)g(v)n(alue)f(-1)h(indicates)g(to)g(read)g(and)g (decode)f(as)i(much)e(as)208 1314 y(possible.)g FK(size)d FN(is)h(intended)c(to)j(pre)n(v)o(ent)d(ha)n(ving)h(to)h(decode)f(huge) g(\002les)j(in)e(one)g(step.)208 1442 y FK(\002r)o(stline)e FN(indicates)g(that)g(it)g(w)o(ould)g(be)g(suf)n(\002cient)f(to)h(only) f(return)g(the)h(\002rst)h(line,)f(if)g(there)g(are)g(decoding)e (errors)h(on)g(later)h(lines.)208 1569 y(The)h(method)f(should)h(use)g (a)h(greedy)f(read)g(strate)o(gy)f(meaning)g(that)i(it)g(should)f(read) g(as)h(much)f(data)g(as)i(is)f(allo)n(wed)f(within)h(the)208 1669 y(de\002nition)e(of)i(the)g(encoding)e(and)h(the)h(gi)n(v)o(en)e (size,)j(e.g.)j(if)c(optional)f(encoding)f(endings)h(or)g(state)i(mark) o(ers)e(are)h(a)n(v)n(ailable)f(on)208 1769 y(the)h(stream,)g(these)g (should)f(be)h(read)g(too.)208 1896 y(Changed)e(in)j(v)o(ersion)e(2.4:) g FK(c)o(har)o(s)h FN(ar)o(gument)e(added.)76 b(Changed)18 b(in)j(v)o(ersion)e(2.4.2:)g FK(\002r)o(stline)h FN(ar)o(gument)e (added.)0 2043 y FD(readline)p FJ(\()p FC([)p FK(size)p FC([)p FK(,)h(k)o(eepends)12 b FC(])g(])p FJ(\))208 2143 y FN(Read)20 b(one)g(line)g(from)f(the)h(input)g(stream)g(and)f(return) g(the)i(decoded)d(data.)208 2271 y FK(size)p FN(,)j(if)f(gi)n(v)o(en,)f (is)i(passed)f(as)h(size)g(ar)o(gument)d(to)i(the)g(stream')-5 b(s)21 b FJ(readline\(\))d FN(method.)208 2398 y(If)i FK(k)o(eepends)f FN(is)i(f)o(alse)g(line-endings)d(will)j(be)f (stripped)f(from)g(the)h(lines)h(returned.)208 2526 y(Changed)d(in)j(v) o(ersion)e(2.4:)g FK(k)o(eepends)h FN(ar)o(gument)d(added.)0 2673 y FD(readlines)p FJ(\()p FC([)p FK(sizehint)q FC([)p FK(,)h(k)o(eepends)12 b FC(])g(])p FJ(\))208 2772 y FN(Read)20 b(all)h(lines)f(a)n(v)n(ailable)g(on)g(the)g(input)f(stream)i(and)e (return)g(them)h(as)h(a)f(list)i(of)e(lines.)208 2900 y(Line-endings)d(are)j(implemented)e(using)h(the)h(codec')-5 b(s)20 b(decoder)e(method)g(and)i(are)f(included)g(in)h(the)g(list)h (entries)e(if)i FK(k)o(eepends)208 3000 y FN(is)g(true.)208 3128 y FK(sizehint)q FN(,)f(if)h(gi)n(v)o(en,)d(is)k(passed)e(as)h(the) f FK(size)h FN(ar)o(gument)d(to)i(the)g(stream')-5 b(s)21 b FJ(read\(\))f FN(method.)0 3274 y FD(reset)p FJ(\(\))208 3374 y FN(Resets)h(the)f(codec)g(b)n(uf)n(fers)f(used)h(for)f(k)o (eeping)g(state.)208 3502 y(Note)26 b(that)g(no)f(stream)h (repositioning)e(should)h(tak)o(e)h(place.)43 b(This)26 b(method)f(is)i(primarily)e(intended)f(to)i(be)g(able)g(to)h(reco)o(v)o (er)208 3601 y(from)19 b(decoding)f(errors.)0 3748 y(In)26 b(addition)f(to)i(the)f(abo)o(v)o(e)f(methods,)h(the)g FJ(StreamReader)f FN(must)h(also)h(inherit)f(all)h(other)e(methods)g (and)h(attrib)n(utes)g(from)g(the)0 3848 y(underlying)17 b(stream.)0 3995 y(The)22 b(ne)o(xt)h(tw)o(o)g(base)f(classes)i(are)f (included)e(for)i(con)m(v)o(enience.)29 b(The)o(y)22 b(are)h(not)f(needed)g(by)g(the)h(codec)f(re)o(gistry)-5 b(,)21 b(b)n(ut)i(may)g(pro)o(vide)0 4094 y(useful)d(in)g(practice.)0 4358 y FI(StreamReaderWr)q(iter)k(Objects)0 4561 y FN(The)c FJ(StreamReaderWriter)d FN(allo)n(ws)k(wrapping)d(streams)i(which)g(w)o (ork)g(in)g(both)f(read)h(and)g(write)g(modes.)0 4708 y(The)d(design)f(is)i(such)e(that)h(one)g(can)f(use)i(the)e(f)o(actory) g(functions)g(returned)f(by)h(the)h FJ(lookup\(\))f FN(function)f(to)i (construct)f(the)h(instance.)0 4855 y FL(class)k FD(StreamReaderWriter) p FJ(\()p FK(str)m(eam,)c(Reader)-9 b(,)19 b(Writer)-9 b(,)21 b(err)l(or)o(s)p FJ(\))208 4954 y FN(Creates)d(a)g FJ(StreamReaderWriter)d FN(instance.)24 b FK(str)m(eam)18 b FN(must)g(be)g(a)g(\002le-lik)o(e)f(object.)24 b FK(Reader)19 b FN(and)e FK(Writer)k FN(must)d(be)g(f)o(ac-)208 5054 y(tory)k(functions)g(or)h(classes)h(pro)o(viding)d(the)i FJ(StreamReader)f FN(and)g FJ(StreamWriter)g FN(interf)o(ace)g(resp.)34 b(Error)22 b(handling)208 5154 y(is)f(done)e(in)h(the)g(same)h(w)o(ay)f (as)h(de\002ned)e(for)h(the)g(stream)g(readers)f(and)h(writers.)0 5300 y FJ(StreamReaderWriter)37 b FN(instances)i(de\002ne)g(the)h (combined)d(interf)o(aces)i(of)g FJ(StreamReader)f FN(and)h FJ(StreamWriter)0 5400 y FN(classes.)26 b(The)o(y)19 b(inherit)h(all)g(other)g(methods)f(and)h(attrib)n(utes)g(from)f(the)h (underlying)e(stream.)p 0 5549 3901 4 v 0 5649 a FI(84)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 85 97 TeXDict begin 85 96 bop 0 83 a FI(StreamRecoder)23 b(Objects)0 286 y FN(The)d FJ(StreamRecoder)f FN(pro)o(vide)f(a)j(frontend)e(-)h (back)o(end)f(vie)n(w)i(of)f(encoding)e(data)j(which)f(is)h(sometimes)g (useful)f(when)g(dealing)0 386 y(with)g(dif)n(ferent)f(encoding)f(en)m (vironments.)0 532 y(The)f(design)f(is)i(such)e(that)h(one)g(can)f(use) i(the)e(f)o(actory)g(functions)g(returned)f(by)h(the)h FJ(lookup\(\))f FN(function)f(to)i(construct)f(the)h(instance.)0 679 y FL(class)k FD(StreamRecoder)p FJ(\()p FK(str)m(eam,)d(encode)o(,) g(decode)o(,)h(Reader)-9 b(,)19 b(Writer)-9 b(,)21 b(err)l(or)o(s)p FJ(\))208 779 y FN(Creates)k(a)h FJ(StreamRecoder)d FN(instance)i (which)g(implements)f(a)i(tw)o(o-w)o(ay)e(con)m(v)o(ersion:)33 b FK(encode)24 b FN(and)h FK(decode)e FN(w)o(ork)i(on)208 879 y(the)i(frontend)e(\(the)i(input)g(to)g FJ(read\(\))g FN(and)g(output)f(of)h FJ(write\(\))p FN(\))f(while)h FK(Reader)i FN(and)e FK(Writer)j FN(w)o(ork)d(on)g(the)g(back)o(end)208 978 y(\(reading)18 b(and)i(writing)f(to)i(the)f(stream\).)208 1111 y(Y)-9 b(ou)19 b(can)h(use)h(these)f(objects)g(to)g(do)g (transparent)f(direct)g(recodings)g(from)g(e.g.)h(Latin-1)f(to)h(UTF-8) g(and)g(back.)208 1244 y FK(str)m(eam)g FN(must)g(be)h(a)f(\002le-lik)o (e)g(object.)208 1377 y FK(encode)p FN(,)33 b FK(decode)e FN(must)i(adhere)e(to)i(the)f FJ(Codec)g FN(interf)o(ace.)61 b FK(Reader)r FN(,)34 b FK(Writer)i FN(must)c(be)g(f)o(actory)f (functions)g(or)h(classes)208 1476 y(pro)o(viding)17 b(objects)j(of)g(the)g FJ(StreamReader)f FN(and)g FJ(StreamWriter)g FN(interf)o(ace)g(respecti)n(v)o(ely)-5 b(.)208 1609 y FK(encode)20 b FN(and)h FK(decode)f FN(are)h(needed)f(for)h(the)h (frontend)d(translation,)i FK(Reader)h FN(and)f FK(Writer)k FN(for)c(the)g(back)o(end)f(translation.)28 b(The)208 1709 y(intermediate)20 b(format)g(used)i(is)g(determined)e(by)h(the)h (tw)o(o)g(sets)g(of)g(codecs,)f(e.g.)29 b(the)22 b(Unicode)e(codecs)h (will)i(use)e(Unicode)g(as)208 1808 y(the)f(intermediate)f(encoding.) 208 1941 y(Error)f(handling)h(is)i(done)e(in)h(the)h(same)f(w)o(ay)g (as)h(de\002ned)e(for)h(the)g(stream)g(readers)g(and)f(writers.)0 2088 y FJ(StreamRecoder)14 b FN(instances)i(de\002ne)f(the)h(combined)e (interf)o(aces)i(of)f FJ(StreamReader)f FN(and)i FJ(StreamWriter)e FN(classes.)25 b(The)o(y)0 2188 y(inherit)20 b(all)g(other)g(methods)f (and)g(attrib)n(utes)i(from)e(the)h(underlying)d(stream.)0 2473 y Fv(4.8.2)100 b(Encodings)30 b(and)f(Unicode)0 2676 y FN(Unicode)d(strings)h(are)f(stored)h(internally)e(as)j (sequences)e(of)h(codepoints)e(\(to)i(be)f(precise)h(as)h FJ(Py_UNICODE)d FN(arrays\).)44 b(Depend-)0 2775 y(ing)35 b(on)f(the)i(w)o(ay)f(Python)f(is)i(compiled)e(\(either)g(via)h FL(--enable-unicode=ucs2)f FN(or)h FL(--enable-unicode=ucs4)p FN(,)j(with)d(the)g(for)n(-)0 2875 y(mer)c(being)g(the)h(def)o(ault\))f FJ(Py_UNICODE)f FN(is)j(either)e(a)i(16-bit)d(or)i(32-bit)e(data)i (type.)59 b(Once)32 b(a)g(Unicode)f(object)g(is)i(used)e(out-)0 2974 y(side)k(of)g(CPU)h(and)e(memory)-5 b(,)37 b(CPU)f(endianness)e (and)g(ho)n(w)g(these)i(arrays)e(are)h(stored)f(as)i(bytes)f(become)e (an)i(issue.)70 b(T)m(rans-)0 3074 y(forming)29 b(a)j(unicode)e(object) h(into)g(a)h(sequence)e(of)h(bytes)h(is)g(called)f(encoding)e(and)i (recreating)f(the)i(unicode)d(object)i(from)g(the)0 3174 y(sequence)38 b(of)g(bytes)h(is)h(kno)n(wn)d(as)j(decoding.)78 b(There)38 b(are)h(man)o(y)f(dif)n(ferent)f(methods)h(for)g(ho)n(w)g (this)i(transformation)c(can)0 3273 y(be)j(done)g(\(these)g(methods)g (are)g(also)h(called)f(encodings\).)81 b(The)39 b(simplest)h(method)e (is)j(to)e(map)g(the)h(codepoints)e(0-255)f(to)0 3373 y(the)g(bytes)f FJ(0x0)p FN(-)p FJ(0xff)p FN(.)74 b(This)37 b(means)f(that)h(a)g(unicode)e(object)h(that)h(contains)f(codepoints)f (abo)o(v)o(e)g FJ(U+00FF)i FN(can')o(t)e(be)i(en-)0 3473 y(coded)c(with)i(this)g(method)e(\(which)h(is)h(called)g FJ('latin-1')e FN(or)h FJ('iso-8859-1')p FN(\).)66 b FJ(unicode.encode\(\))32 b FN(will)j(raise)0 3572 y(a)41 b FJ(UnicodeEncodeError)e FN(that)i(looks)f(lik)o(e)i(this:)67 b(`)p FJ(UnicodeEncodeError:)96 b('latin-1')48 b(codec)h(can't)0 3672 y(encode)g(character)f(u'\\u1234')g(in)h(position)g(3:)99 b(ordinal)48 b(not)i(in)f(range\(256\))p FN('.)0 3819 y(There')-5 b(s)26 b(another)e(group)h(of)g(encodings)g(\(the)g(so)i (called)f(charmap)e(encodings\))g(that)i(choose)g(a)g(dif)n(ferent)e (subset)j(of)e(all)i(unicode)0 3918 y(code)20 b(points)h(and)g(ho)n(w)f (these)i(codepoints)d(are)i(mapped)f(to)h(the)g(bytes)g FJ(0x0)p FN(-)p FJ(0xff.)27 b FN(T)-7 b(o)21 b(see)h(ho)n(w)e(this)i (is)g(done)e(simply)h(open)f(e.g.)0 4018 y(`)p FO(encodings/cp1252.p)n (y)p FN(')c(\(which)21 b(is)i(an)e(encoding)f(that)i(is)g(used)f (primarily)g(on)g(W)m(indo)n(ws\).)28 b(There')-5 b(s)21 b(a)h(string)g(constant)f(with)g(256)0 4118 y(characters)e(that)i(sho)n (ws)f(you)f(which)h(character)f(is)i(mapped)d(to)j(which)e(byte)h(v)n (alue.)0 4264 y(All)30 b(of)g(these)g(encodings)d(can)j(only)f(encode)f (256)h(of)g(the)h(65536)e(\(or)h(1114111\))d(codepoints)i(de\002ned)h (in)h(unicode.)51 b(A)31 b(simple)0 4364 y(and)22 b(straightforw)o(ard) d(w)o(ay)k(that)f(can)g(store)g(each)g(Unicode)f(code)h(point,)f(is)j (to)e(store)g(each)g(codepoint)e(as)j(tw)o(o)g(consecuti)n(v)o(e)d (bytes.)0 4464 y(There)26 b(are)i(tw)o(o)f(possibilities:)40 b(Store)27 b(the)g(bytes)h(in)f(big)g(endian)f(or)h(in)h(little)g (endian)e(order)-5 b(.)45 b(These)27 b(tw)o(o)h(encodings)e(are)h (called)0 4563 y(UTF-16-BE)f(and)g(UTF-16-LE)f(respecti)n(v)o(ely)-5 b(.)44 b(Their)26 b(disadv)n(antage)f(is)j(that)f(if)g(e.g.)45 b(you)26 b(use)h(UTF-16-BE)f(on)g(a)i(little)g(endian)0 4663 y(machine)f(you)g(will)i(al)o(w)o(ays)g(ha)n(v)o(e)e(to)h(sw)o(ap) h(bytes)f(on)f(encoding)g(and)g(decoding.)47 b(UTF-16)27 b(a)n(v)n(oids)h(this)h(problem:)39 b(Bytes)29 b(will)0 4763 y(al)o(w)o(ays)d(be)g(in)g(natural)f(endianness.)40 b(When)26 b(these)g(bytes)f(are)h(read)f(by)g(a)i(CPU)f(with)g(a)g(dif) n(ferent)f(endianness,)g(then)h(bytes)f(ha)n(v)o(e)0 4862 y(to)i(be)f(sw)o(apped)g(though.)42 b(T)-7 b(o)26 b(be)h(able)f(to)h(detect)f(the)g(endianness)g(of)g(a)h(UTF-16)e(byte)h (sequence,)h(there')-5 b(s)26 b(the)h(so)g(called)f(BOM)0 4962 y(\(the)c(\224Byte)g(Order)f(Mark\224\).)29 b(This)22 b(is)h(the)f(Unicode)f(character)f FJ(U+FEFF)p FN(.)h(This)h(character) f(will)i(be)f(prepended)d(to)j(e)n(v)o(ery)f(UTF-16)0 5061 y(byte)k(sequence.)38 b(The)25 b(byte)f(sw)o(apped)h(v)o(ersion)f (of)g(this)i(character)e(\()p FJ(0xFFFE)p FN(\))g(is)i(an)f(ille)o(gal) f(character)g(that)h(may)g(not)g(appear)e(in)0 5161 y(a)i(Unicode)f(te) o(xt.)39 b(So)25 b(when)g(the)g(\002rst)g(character)f(in)h(an)g(UTF-16) f(byte)h(sequence)e(appears)i(to)g(be)g(a)g FJ(U+FFFE)f FN(the)h(bytes)g(ha)n(v)o(e)f(to)0 5261 y(be)g(sw)o(apped)g(on)g (decoding.)35 b(Unfortunately)22 b(upto)i(Unicode)f(4.0)h(the)g (character)f FJ(U+FEFF)h FN(had)g(a)h(second)e(purpose)g(as)i(a)g(`)p FJ(ZERO)0 5360 y(WIDTH)49 b(NO-BREAK)f(SPACE)p FN(':)20 b(A)h(character)e(that)h(has)h(no)e(width)h(and)g(doesn')o(t)f(allo)n (w)h(a)h(w)o(ord)f(to)g(be)g(split.)26 b(It)21 b(can)f(e.g.)25 b(be)20 b(used)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and)g(base)h(classes) 1986 b(85)p eop end %%Page: 86 98 TeXDict begin 86 97 bop 0 83 a FN(to)19 b(gi)n(v)o(e)e(hints)i(to)g(a)g (ligature)e(algorithm.)23 b(W)m(ith)18 b(Unicode)g(4.0)g(using)g FJ(U+FEFF)f FN(as)j(a)f(`)p FJ(ZERO)48 b(WIDTH)h(NO-BREAK)g(SPACE)p FN(')17 b(has)0 183 y(been)j(deprecated)f(\(with)i FJ(U+2060)f FN(\(`)p FJ(WORD)48 b(JOINER)p FN('\))20 b(assuming)g(this)h(role\).)26 b(Ne)n(v)o(ertheless)20 b(Unicode)f(softw)o(are)i(still)h(must)f(be)0 282 y(able)c(to)h(handle)e FJ(U+FEFF)h FN(in)g(both)g(roles:)23 b(As)c(a)e(BOM)h(it')-5 b(s)19 b(a)e(de)n(vice)g(to)g(determine)f(the)i (storage)e(layout)h(of)g(the)g(encoded)f(bytes,)h(and)0 382 y(v)n(anishes)j(once)g(the)h(byte)g(sequence)e(has)j(been)e (decoded)f(into)h(a)i(Unicode)d(string;)i(as)h(a)f(`)p FJ(ZERO)49 b(WIDTH)g(NO-BREAK)f(SPACE)p FN(')0 482 y(it')-5 b(s)21 b(a)g(normal)e(character)g(that)h(will)h(be)f(decoded)f(lik)o(e) h(an)o(y)f(other)-5 b(.)0 628 y(There')g(s)27 b(another)f(encoding)f (that)j(is)g(able)g(to)f(encoding)f(the)h(full)g(range)g(of)g(Unicode)f (characters:)39 b(UTF-8.)46 b(UTF-8)27 b(is)i(an)e(8-bit)0 728 y(encoding,)18 b(which)h(means)h(there)g(are)g(no)g(issues)h(with)f (byte)f(order)g(in)i(UTF-8.)j(Each)c(byte)f(in)h(a)h(UTF-8)f(byte)f (sequence)g(consists)i(of)0 828 y(tw)o(o)f(parts:)25 b(Mark)o(er)19 b(bits)i(\(the)e(most)h(signi\002cant)f(bits\))h(and)g (payload)e(bits.)25 b(The)20 b(mark)o(er)f(bits)h(are)g(a)g(sequence)f (of)g(zero)h(to)g(six)g(1)g(bits)0 927 y(follo)n(wed)k(by)g(a)i(0)f (bit.)40 b(Unicode)23 b(characters)i(are)g(encoded)e(lik)o(e)i(this)h (\(with)f(x)g(being)f(payload)f(bits,)k(which)d(when)h(concatenated)0 1027 y(gi)n(v)o(e)19 b(the)i(Unicode)e(character\):)300 1253 y FL(Range)p 1453 1283 4 100 v 977 w(Encoding)p 250 1286 3401 4 v 300 1356 a FJ(U-00000000)f FN(...)25 b FJ(U-0000007F)p 1453 1386 4 100 v 98 w FN(0xxxxxxx)300 1456 y FJ(U-00000080)18 b FN(...)25 b FJ(U-000007FF)p 1453 1486 V 98 w FN(110xxxxx)17 b(10xxxxxx)300 1555 y FJ(U-00000800)h FN(...)25 b FJ(U-0000FFFF)p 1453 1585 V 98 w FN(1110xxxx)17 b(10xxxxxx)g(10xxxxxx)300 1655 y FJ(U-00010000)h FN(...)25 b FJ(U-001FFFFF)p 1453 1685 V 98 w FN(11110xxx)17 b(10xxxxxx)g(10xxxxxx)g(10xxxxxx)300 1755 y FJ(U-00200000)h FN(...)25 b FJ(U-03FFFFFF)p 1453 1785 V 98 w FN(111110xx)17 b(10xxxxxx)g(10xxxxxx)g(10xxxxxx)g(10xxxxxx) 300 1854 y FJ(U-04000000)h FN(...)25 b FJ(U-7FFFFFFF)p 1453 1884 V 98 w FN(1111110x)17 b(10xxxxxx)g(10xxxxxx)g(10xxxxxx)g (10xxxxxx)f(10xxxxxx)0 2079 y(The)k(least)h(signi\002cant)e(bit)i(of)f (the)g(Unicode)f(character)g(is)i(the)f(rightmost)f(x)i(bit.)0 2226 y(As)f(UTF-8)f(is)h(an)f(8-bit)g(encoding)e(no)i(BOM)h(is)g (required)d(and)i(an)o(y)g FJ(U+FEFF)f FN(character)g(in)i(the)f (decoded)e(Unicode)h(string)h(\(e)n(v)o(en)f(if)0 2326 y(it')-5 b(s)21 b(the)f(\002rst)h(character\))e(is)i(treated)f(as)h(a)f (`)p FJ(ZERO)49 b(WIDTH)g(NO-BREAK)f(SPACE)p FN('.)0 2473 y(W)m(ithout)22 b(e)o(xternal)g(information)f(it')-5 b(s)24 b(impossible)e(to)i(reliably)e(determine)g(which)g(encoding)f(w) o(as)j(used)f(for)f(encoding)f(a)j(Unicode)0 2572 y(string.)37 b(Each)23 b(charmap)g(encoding)f(can)i(decode)f(an)o(y)g(random)g(byte) g(sequence.)36 b(Ho)n(we)n(v)o(er)23 b(that')-5 b(s)24 b(not)g(possible)g(with)g(UTF-8,)h(as)0 2672 y(UTF-8)15 b(byte)g(sequences)f(ha)n(v)o(e)h(a)g(structure)g(that)g(doesn')o(t)f (allo)n(w)h(arbitrary)f(byte)g(sequence.)22 b(T)-7 b(o)16 b(increase)f(the)g(reliability)g(with)g(which)0 2772 y(a)21 b(UTF-8)f(encoding)e(can)i(be)h(detected,)e(Microsoft)h(in)m(v)o (ented)e(a)j(v)n(ariant)e(of)h(UTF-8)g(\(that)g(Python)g(2.5)f(calls)j FJ("utf-8-sig")p FN(\))c(for)0 2871 y(its)i(Notepad)e(program:)23 b(Before)18 b(an)o(y)h(of)g(the)g(Unicode)f(characters)g(is)i(written)f (to)g(the)h(\002le,)f(a)h(UTF-8)f(encoded)e(BOM)j(\(which)e(looks)0 2971 y(lik)o(e)j(this)h(as)g(a)f(byte)g(sequence:)26 b FJ(0xef)p FN(,)21 b FJ(0xbb)p FN(,)g FJ(0xbf)p FN(\))f(is)i(written.) 28 b(As)21 b(it')-5 b(s)23 b(rather)d(improbable)f(that)i(an)o(y)f (charmap)g(encoded)f(\002le)0 3070 y(starts)i(with)f(these)h(byte)e(v)n (alues)h(\(which)g(w)o(ould)f(e.g.)25 b(map)19 b(to)0 3217 y(LA)-9 b(TIN)20 b(SMALL)g(LETTER)f(I)i(WITH)f(DIAERESIS)0 3317 y(RIGHT)-8 b(-POINTING)19 b(DOUBLE)i(ANGLE)f(Q)o(UO)m(T)-8 b(A)f(TION)19 b(MARK)0 3417 y(INVER)-5 b(TED)20 b(Q)o(UESTION)g(MARK)0 3563 y(in)d(iso-8859-1\),)e(this)j(increases)f(the)g(probability)e (that)j(a)f(utf-8-sig)f(encoding)f(can)i(be)g(correctly)f(guessed)h (from)f(the)h(byte)g(sequence.)0 3663 y(So)25 b(here)g(the)g(BOM)g(is)h (not)f(used)g(to)g(be)g(able)f(to)i(determine)d(the)i(byte)g(order)e (used)i(for)f(generating)f(the)i(byte)g(sequence,)f(b)n(ut)h(as)h(a)0 3763 y(signature)21 b(that)h(helps)g(in)g(guessing)g(the)g(encoding.)28 b(On)22 b(encoding)e(the)j(utf-8-sig)d(codec)h(will)i(write)g FJ(0xef)p FN(,)f FJ(0xbb)p FN(,)g FJ(0xbf)g FN(as)h(the)0 3862 y(\002rst)h(three)f(bytes)h(to)f(the)h(\002le.)35 b(On)24 b(decoding)d(utf-8-sig)h(will)j(skip)e(those)h(three)f(bytes)g (if)h(the)o(y)f(appear)f(as)i(the)g(\002rst)g(three)f(bytes)g(in)0 3962 y(the)d(\002le.)0 4247 y Fv(4.8.3)100 b(Standard)30 b(Encodings)0 4450 y FN(Python)24 b(comes)h(with)g(a)g(number)e(of)i (codecs)g(b)n(uilt-in,)g(either)g(implemented)e(as)i(C)h(functions)e (or)h(with)g(dictionaries)f(as)h(mapping)0 4549 y(tables.)g(The)17 b(follo)n(wing)g(table)h(lists)i(the)e(codecs)g(by)g(name,)g(together)f (with)h(a)h(fe)n(w)f(common)e(aliases,)k(and)d(the)i(languages)d(for)i (which)0 4649 y(the)k(encoding)f(is)i(lik)o(ely)f(used.)32 b(Neither)22 b(the)g(list)i(of)e(aliases)h(nor)f(the)g(list)i(of)e (languages)f(is)j(meant)d(to)i(be)f(e)o(xhausti)n(v)o(e.)30 b(Notice)22 b(that)0 4749 y(spelling)e(alternati)n(v)o(es)f(that)h (only)f(dif)n(fer)h(in)g(case)h(or)e(use)i(a)f(hyphen)e(instead)i(of)g (an)g(underscore)e(are)i(also)h(v)n(alid)f(aliases.)0 4896 y(Man)o(y)j(of)h(the)g(character)f(sets)i(support)e(the)h(same)g (languages.)35 b(The)o(y)23 b(v)n(ary)g(in)i(indi)n(vidual)d (characters)h(\(e.g.)36 b(whether)23 b(the)h(EUR)m(O)0 4995 y(SIGN)30 b(is)g(supported)d(or)i(not\),)i(and)d(in)i(the)f (assignment)f(of)h(characters)g(to)g(code)g(positions.)51 b(F)o(or)29 b(the)h(European)d(languages)g(in)0 5095 y(particular)m(,)18 b(the)j(follo)n(wing)d(v)n(ariants)i(typically)f(e) o(xist:)125 5325 y FM(\017)41 b FN(an)20 b(ISO)g(8859)f(codeset)p 0 5549 3901 4 v 0 5649 a FI(86)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 87 99 TeXDict begin 87 98 bop 125 83 a FM(\017)41 b FN(a)18 b(Microsoft)g(W)m(indo)n(ws)g(code)f(page,)h(which)g(is)h(typically)f (deri)n(v)o(ed)f(from)g(a)i(8859)e(codeset,)h(b)n(ut)g(replaces)g (control)g(characters)208 183 y(with)i(additional)f(graphic)f (characters)125 349 y FM(\017)41 b FN(an)20 b(IBM)g(EBCDIC)h(code)f (page)125 515 y FM(\017)41 b FN(an)20 b(IBM)g(PC)i(code)d(page,)g (which)h(is)j FH(A)t(S)t(C)t(I)t(I)h FN(compatible)50 785 y FL(Codec)p 651 815 4 100 v 431 w(Aliases)p 3844 815 V 2943 w(Languages)p 0 818 6015 4 v 0 818 V 50 888 a FN(ascii)p 651 918 4 100 v 501 w(646,)19 b(us-ascii)p 3844 918 V 2772 w(English)50 988 y(big5)p 651 1018 V 504 w(big5-tw)-5 b(,)18 b(csbig5)p 3844 1018 V 2680 w(T)m(raditional)h (Chinese)50 1087 y(big5hkscs)p 651 1117 V 319 w(big5-hkscs,)f(hkscs)p 3844 1117 V 2606 w(T)m(raditional)h(Chinese)50 1187 y(cp037)p 651 1217 V 448 w(IBM037,)g(IBM039)p 3844 1217 V 2586 w(English)50 1287 y(cp424)p 651 1316 V 448 w(EBCDIC-CP-HE,)h(IBM424)p 3844 1316 V 2296 w(Hebre)n(w)50 1386 y(cp437)p 651 1416 V 448 w(437,)f(IBM437)p 3844 1416 V 2743 w(English)50 1486 y(cp500)p 651 1516 V 448 w(EBCDIC-CP-BE,)i(EBCDIC-CP-CH,)g(IBM500) p 3844 1516 V 1682 w(W)-7 b(estern)21 b(Europe)50 1585 y(cp737)p 651 1615 V 3844 1615 V 3640 w(Greek)50 1685 y(cp775)p 651 1715 V 448 w(IBM775)p 3844 1715 V 2909 w(Baltic)g(languages)50 1785 y(cp850)p 651 1815 V 448 w(850,)e(IBM850)p 3844 1815 V 2743 w(W)-7 b(estern)21 b(Europe)50 1884 y(cp852)p 651 1914 V 448 w(852,)e(IBM852)p 3844 1914 V 2743 w(Central)h(and)g(Eastern)g(Europe)50 1984 y(cp855)p 651 2014 V 448 w(855,)f(IBM855)p 3844 2014 V 2743 w(Bulgarian,)g(Byelorussian,)g(Macedonian,)f(Russian,)i (Serbian)50 2084 y(cp856)p 651 2113 V 3844 2113 V 3640 w(Hebre)n(w)50 2183 y(cp857)p 651 2213 V 448 w(857,)f(IBM857)p 3844 2213 V 2743 w(T)l(urkish)50 2283 y(cp860)p 651 2313 V 448 w(860,)g(IBM860)p 3844 2313 V 2743 w(Portuguese)50 2382 y(cp861)p 651 2412 V 448 w(861,)g(CP-IS,)h(IBM861)p 3844 2412 V 2499 w(Icelandic)50 2482 y(cp862)p 651 2512 V 448 w(862,)f(IBM862)p 3844 2512 V 2743 w(Hebre)n(w)50 2582 y(cp863)p 651 2612 V 448 w(863,)g(IBM863)p 3844 2612 V 2743 w(Canadian)50 2681 y(cp864)p 651 2711 V 448 w(IBM864)p 3844 2711 V 2909 w(Arabic)50 2781 y(cp865)p 651 2811 V 448 w(865,)g(IBM865)p 3844 2811 V 2743 w(Danish,)h(Norwe)o (gian)50 2881 y(cp866)p 651 2910 V 448 w(866,)f(IBM866)p 3844 2910 V 2743 w(Russian)50 2980 y(cp869)p 651 3010 V 448 w(869,)g(CP-GR,)i(IBM869)p 3844 3010 V 2457 w(Greek)50 3080 y(cp874)p 651 3110 V 3844 3110 V 3640 w(Thai)50 3179 y(cp875)p 651 3209 V 3844 3209 V 3640 w(Greek)50 3279 y(cp932)p 651 3309 V 448 w(932,)e(ms932,)g(mskanji,)g(ms-kanji)p 3844 3309 V 2167 w(Japanese)50 3379 y(cp949)p 651 3409 V 448 w(949,)g(ms949,)g(uhc)p 3844 3409 V 2642 w(K)m(orean)50 3478 y(cp950)p 651 3508 V 448 w(950,)g(ms950)p 3844 3508 V 2803 w(T)m(raditional)g(Chinese)50 3578 y(cp1006)p 651 3608 V 3844 3608 V 3598 w(Urdu)50 3678 y(cp1026)p 651 3707 V 406 w(ibm1026)p 3844 3707 V 2894 w(T)l(urkish)50 3777 y(cp1140)p 651 3807 V 406 w(ibm1140)p 3844 3807 V 2894 w(W)-7 b(estern)21 b(Europe)50 3877 y(cp1250)p 651 3907 V 406 w(windo)n(ws-1250)p 3844 3907 V 2697 w(Central)f(and)g (Eastern)g(Europe)50 3976 y(cp1251)p 651 4006 V 406 w(windo)n(ws-1251)p 3844 4006 V 2697 w(Bulgarian,)f(Byelorussian,)g(Macedonian,)f(Russian,) i(Serbian)50 4076 y(cp1252)p 651 4106 V 406 w(windo)n(ws-1252)p 3844 4106 V 2697 w(W)-7 b(estern)21 b(Europe)50 4176 y(cp1253)p 651 4206 V 406 w(windo)n(ws-1253)p 3844 4206 V 2697 w(Greek)50 4275 y(cp1254)p 651 4305 V 406 w(windo)n(ws-1254)p 3844 4305 V 2697 w(T)l(urkish)50 4375 y(cp1255)p 651 4405 V 406 w(windo)n(ws-1255)p 3844 4405 V 2697 w(Hebre)n(w)50 4475 y(cp1256)p 651 4504 V 406 w(windo)n(ws1256)p 3844 4504 V 2725 w(Arabic)50 4574 y(cp1257)p 651 4604 V 406 w(windo)n(ws-1257)p 3844 4604 V 2697 w(Baltic)g(languages)50 4674 y(cp1258)p 651 4704 V 406 w(windo)n(ws-1258)p 3844 4704 V 2697 w(V)-5 b(ietnamese)50 4773 y(euc)p 171 4773 25 4 v 29 w(jp)p 651 4803 4 100 v 443 w(eucjp,)19 b(ujis,)i(u-jis)p 3844 4803 V 2661 w(Japanese)50 4873 y(euc)p 171 4873 25 4 v 29 w(jis)p 278 4873 V 30 w(2004)p 651 4903 4 100 v 232 w(jisx0213,)d(eucjis2004)p 3844 4903 V 2503 w(Japanese)50 4973 y(euc)p 171 4973 25 4 v 29 w(jisx0213)p 651 5003 4 100 v 220 w(eucjisx0213)p 3844 5003 V 2788 w(Japanese)50 5072 y(euc)p 171 5072 25 4 v 29 w(kr)p 651 5102 4 100 v 438 w(euckr)m(,)g(k)o(orean,)h(ksc5601,)f(ks)p 1589 5072 25 4 v 30 w(c-5601,)g(ks)p 1965 5072 V 30 w(c-5601-1987,)d (ksx1001,)j(ks)p 2857 5072 V 30 w(x-1001)p 3844 5102 4 100 v 775 w(K)m(orean)50 5172 y(gb2312)p 651 5202 V 401 w(chinese,)h(csiso58gb231280,)d(euc-cn,)j(euccn,)g(eucgb2312-cn,)d (gb2312-1980,)f(gb2312-80,)h(iso-ir)n(-58)p 3844 5202 V 98 w(Simpli\002ed)k(Chinese)50 5272 y(gbk)p 651 5301 V 527 w(936,)f(cp936,)f(ms936)p 3844 5301 V 2559 w(Uni\002ed)i(Chinese) 50 5371 y(gb18030)p 651 5401 V 359 w(gb18030-2000)p 3844 5401 V 2702 w(Uni\002ed)g(Chinese)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and) g(base)h(classes)1986 b(87)p eop end %%Page: 88 100 TeXDict begin 88 99 bop 50 70 a FL(Codec)p 651 100 4 100 v 431 w(Aliases)p 3844 100 V 2943 w(Languages)p 0 103 6015 4 v 0 103 V 50 173 a FN(hz)p 651 203 4 100 v 574 w(hzgb,)19 b(hz-gb,)f(hz-gb-2312)p 3844 203 V 2372 w(Simpli\002ed)i(Chinese)50 272 y(iso2022)p 320 272 25 4 v 28 w(jp)p 651 302 4 100 v 295 w(csiso2022jp,)e(iso2022jp,)g (iso-2022-jp)p 3844 302 V 1999 w(Japanese)50 372 y(iso2022)p 320 372 25 4 v 28 w(jp)p 413 372 V 29 w(1)p 651 402 4 100 v 224 w(iso2022jp-1,)f(iso-2022-jp-1)p 3844 402 V 2298 w(Japanese)50 472 y(iso2022)p 320 472 25 4 v 28 w(jp)p 413 472 V 29 w(2)p 651 501 4 100 v 224 w(iso2022jp-2,)g (iso-2022-jp-2)p 3844 501 V 2298 w(Japanese,)j(K)m(orean,)f (Simpli\002ed)g(Chinese,)h(W)-7 b(estern)21 b(Europe,)d(Greek)50 571 y(iso2022)p 320 571 25 4 v 28 w(jp)p 413 571 V 29 w(2004)p 651 601 4 100 v 98 w(iso2022jp-2004,)d(iso-2022-jp-2004)p 3844 601 V 2048 w(Japanese)50 671 y(iso2022)p 320 671 25 4 v 28 w(jp)p 413 671 V 29 w(3)p 651 701 4 100 v 224 w(iso2022jp-3,)i(iso-2022-jp-3)p 3844 701 V 2298 w(Japanese)50 770 y(iso2022)p 320 770 25 4 v 28 w(jp)p 413 770 V 29 w(e)o(xt)p 651 800 4 100 v 165 w(iso2022jp-e)o(xt,)g(iso-2022-jp-e)o (xt)p 3844 800 V 2180 w(Japanese)50 870 y(iso2022)p 320 870 25 4 v 28 w(kr)p 651 900 4 100 v 290 w(csiso2022kr)m(,)g(iso2022kr) m(,)g(iso-2022-kr)p 3844 900 V 1992 w(K)m(orean)50 970 y(latin)p 203 970 25 4 v 29 w(1)p 651 1000 4 100 v 434 w(iso-8859-1,)g(iso8859-1,)h(8859,)g(cp819,)h(latin,)h(latin1,)f(L1)p 3844 1000 V 1453 w(W)-7 b(est)22 b(Europe)50 1069 y(iso8859)p 320 1069 25 4 v 28 w(2)p 651 1099 4 100 v 318 w(iso-8859-2,)17 b(latin2,)j(L2)p 3844 1099 V 2467 w(Central)g(and)g(Eastern)g(Europe)50 1169 y(iso8859)p 320 1169 25 4 v 28 w(3)p 651 1199 4 100 v 318 w(iso-8859-3,)d(latin3,)j(L3)p 3844 1199 V 2467 w(Esperanto,)f(Maltese)50 1269 y(iso8859)p 320 1269 25 4 v 28 w(4)p 651 1298 4 100 v 318 w(iso-8859-4,)e(latin4,)j(L4)p 3844 1298 V 2467 w(Baltic)h(languagues)50 1368 y(iso8859)p 320 1368 25 4 v 28 w(5)p 651 1398 4 100 v 318 w(iso-8859-5,)c(c)o (yrillic)p 3844 1398 V 2556 w(Bulgarian,)i(Byelorussian,)g(Macedonian,) f(Russian,)i(Serbian)50 1468 y(iso8859)p 320 1468 25 4 v 28 w(6)p 651 1498 4 100 v 318 w(iso-8859-6,)d(arabic)p 3844 1498 V 2587 w(Arabic)50 1567 y(iso8859)p 320 1567 25 4 v 28 w(7)p 651 1597 4 100 v 318 w(iso-8859-7,)g(greek,)i(greek8)p 3844 1597 V 2337 w(Greek)50 1667 y(iso8859)p 320 1667 25 4 v 28 w(8)p 651 1697 4 100 v 318 w(iso-8859-8,)e(hebre)n(w)p 3844 1697 V 2547 w(Hebre)n(w)50 1767 y(iso8859)p 320 1767 25 4 v 28 w(9)p 651 1797 4 100 v 318 w(iso-8859-9,)g(latin5,)j(L5) p 3844 1797 V 2467 w(T)l(urkish)50 1866 y(iso8859)p 320 1866 25 4 v 28 w(10)p 651 1896 4 100 v 276 w(iso-8859-10,)d(latin6,)i (L6)p 3844 1896 V 2426 w(Nordic)g(languages)50 1966 y(iso8859)p 320 1966 25 4 v 28 w(13)p 651 1996 4 100 v 276 w(iso-8859-13)p 3844 1996 V 2787 w(Baltic)i(languages)50 2066 y(iso8859)p 320 2066 25 4 v 28 w(14)p 651 2095 4 100 v 276 w(iso-8859-14,)c (latin8,)i(L8)p 3844 2095 V 2426 w(Celtic)i(languages)50 2165 y(iso8859)p 320 2165 25 4 v 28 w(15)p 651 2195 4 100 v 276 w(iso-8859-15)p 3844 2195 V 2787 w(W)-7 b(estern)21 b(Europe)50 2265 y(johab)p 651 2295 V 467 w(cp1361,)d(ms1361)p 3844 2295 V 2641 w(K)m(orean)50 2364 y(k)o(oi8)p 203 2364 25 4 v 28 w(r)p 651 2394 4 100 v 3844 2394 V 3641 w(Russian)50 2464 y(k)o(oi8)p 203 2464 25 4 v 28 w(u)p 651 2494 4 100 v 3844 2494 V 3627 w(Ukrainian)50 2564 y(mac)p 194 2564 25 4 v 29 w(c)o(yrillic)p 651 2594 4 100 v 250 w(macc)o(yrillic)p 3844 2594 V 2818 w(Bulgarian,)h (Byelorussian,)g(Macedonian,)f(Russian,)i(Serbian)50 2663 y(mac)p 194 2663 25 4 v 29 w(greek)p 651 2693 4 100 v 299 w(macgreek)p 3844 2693 V 2867 w(Greek)50 2763 y(mac)p 194 2763 25 4 v 29 w(iceland)p 651 2793 4 100 v 244 w(maciceland)p 3844 2793 V 2812 w(Icelandic)50 2863 y(mac)p 194 2863 25 4 v 29 w(latin2)p 651 2892 4 100 v 295 w(maclatin2,)f(maccentraleurope)p 3844 2892 V 2229 w(Central)h(and)g(Eastern)g(Europe)50 2962 y(mac)p 194 2962 25 4 v 29 w(roman)p 651 2992 4 100 v 271 w(macroman)p 3844 2992 V 2839 w(W)-7 b(estern)21 b(Europe)50 3062 y(mac)p 194 3062 25 4 v 29 w(turkish)p 651 3092 4 100 v 253 w(macturkish)p 3844 3092 V 2821 w(T)l(urkish)50 3161 y(ptcp154)p 651 3191 V 383 w(csptcp154,)d(pt154,)h(cp154,)f(c)o (yrillic-asian)p 3844 3191 V 1905 w(Kazakh)50 3261 y(shift)p 203 3261 25 4 v 29 w(jis)p 651 3291 4 100 v 398 w(csshiftjis,)j (shiftjis,)f(sjis,)h(s)p 1496 3261 25 4 v 31 w(jis)p 3844 3291 4 100 v 2295 w(Japanese)50 3361 y(shift)p 203 3361 25 4 v 29 w(jis)p 310 3361 V 31 w(2004)p 651 3391 4 100 v 199 w(shiftjis2004,)d(sjis)p 1251 3361 25 4 v 31 w(2004,)h(sjis2004)p 3844 3391 4 100 v 2132 w(Japanese)50 3460 y(shift)p 203 3460 25 4 v 29 w(jisx0213)p 651 3490 4 100 v 188 w(shiftjisx0213,)f(sjisx0213,)h(s)p 1575 3460 25 4 v 30 w(jisx0213)p 3844 3490 4 100 v 2007 w(Japanese)50 3560 y(utf)p 148 3560 25 4 v 29 w(16)p 651 3590 4 100 v 447 w(U16,)g(utf16)p 3844 3590 V 2831 w(all)i(languages)50 3660 y(utf)p 148 3660 25 4 v 29 w(16)p 261 3660 V 29 w(be)p 651 3689 4 100 v 339 w(UTF-16BE)p 3844 3689 V 2817 w(all)g(languages)e(\(BMP)h(only\))50 3759 y(utf)p 148 3759 25 4 v 29 w(16)p 261 3759 V 29 w(le)p 651 3789 4 100 v 358 w(UTF-16LE)p 3844 3789 V 2821 w(all)h(languages)e(\(BMP)h (only\))50 3859 y(utf)p 148 3859 25 4 v 29 w(7)p 651 3889 4 100 v 489 w(U7,)g(unicode-1-1-utf-7)p 3844 3889 V 2453 w(all)h(languages)50 3958 y(utf)p 148 3958 25 4 v 29 w(8)p 651 3988 4 100 v 489 w(U8,)f(UTF)-7 b(,)20 b(utf8)p 3844 3988 V 2723 w(all)h(languages)50 4058 y(utf)p 148 4058 25 4 v 29 w(8)p 219 4058 V 29 w(sig)p 651 4088 4 100 v 3844 4088 V 3555 w(all)g(languages)0 4564 y(A)27 b(number)e(of)i(codecs)f(are)h(speci\002c)g(to)g(Python,)g(so)h(their)e (codec)g(names)h(ha)n(v)o(e)f(no)g(meaning)g(outside)g(Python.)44 b(Some)26 b(of)h(them)0 4664 y(don')o(t)22 b(con)m(v)o(ert)f(from)h (Unicode)g(strings)h(to)g(byte)g(strings,)h(b)n(ut)f(instead)g(use)g (the)g(property)f(of)g(the)i(Python)e(codecs)g(machinery)f(that)0 4764 y(an)o(y)e(bijecti)n(v)o(e)h(function)e(with)j(one)e(ar)o(gument)f (can)i(be)g(considered)f(as)h(an)h(encoding.)0 4911 y(F)o(or)e(the)g (codecs)g(listed)g(belo)n(w)-5 b(,)19 b(the)g(result)g(in)g(the)h (\223encoding\224)c(direction)i(is)i(al)o(w)o(ays)g(a)g(byte)e(string.) 25 b(The)19 b(result)g(of)g(the)g(\223decoding\224)0 5010 y(direction)g(is)i(listed)g(as)g(operand)d(type)h(in)i(the)f (table.)p 0 5549 3901 4 v 0 5649 a FI(88)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 89 101 TeXDict begin 89 100 bop 50 70 a FL(Codec)p 765 100 4 100 v 545 w(Aliases)p 2234 100 V 1220 w(Operand)20 b(type)p 2825 100 V 99 w(Pur)o(pose)p 0 103 7761 4 v 50 173 a FN(base64)p 287 173 25 4 v 28 w(codec)p 765 203 4 100 v 312 w(base64,)f(base-64)p 2234 203 V 937 w(byte)h(string)p 2825 203 V 237 w(Con)m(v)o(ert)e(operand)h(to)h(MIME)g(base64)50 272 y(bz2)p 176 272 25 4 v 29 w(codec)p 765 302 4 100 v 422 w(bz2)p 2234 302 V 1348 w(byte)g(string)p 2825 302 V 237 w(Compress)g(the)g(operand)e(using)i(bz2)50 372 y(he)o(x)p 175 372 25 4 v 28 w(codec)p 765 402 4 100 v 424 w(he)o(x)p 2234 402 V 1349 w(byte)g(string)p 2825 402 V 237 w(Con)m(v)o(ert)e(operand)h(to)h(he)o(xadecimal)e (representation,)g(with)i(tw)o(o)h(digits)f(per)g(byte)50 472 y(idna)p 765 501 V 2234 501 V 2092 w(Unicode)f(string)p 2825 501 V 99 w(Implements)f(RFC)k(3490.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)50 b(See)21 b(also)f FJ(encodings.idna)50 571 y FN(mbcs)p 765 601 V 591 w(dbcs)p 2234 601 V 1316 w(Unicode)f(string)p 2825 601 V 99 w(W)m(indo)n(ws)g(only:)25 b(Encode)18 b(operand)h(according)f(to)i(the)g(ANSI)h(codepage)d(\(CP)p 5203 571 25 4 v 30 w(A)m(CP\))50 671 y(palmos)p 765 701 4 100 v 2234 701 V 1995 w(Unicode)h(string)p 2825 701 V 99 w(Encoding)f(of)i(P)o(almOS)g(3.5)50 770 y(pun)o(ycode)p 765 800 V 2234 800 V 1911 w(Unicode)f(string)p 2825 800 V 99 w(Implements)f(RFC)k(3492.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.3.)50 870 y(quopri)p 274 870 25 4 v 27 w(codec)p 765 900 4 100 v 326 w(quopri,)f(quoted-printable,)e(quotedprintable)p 2234 900 V 96 w(byte)k(string)p 2825 900 V 237 w(Con)m(v)o(ert)e (operand)h(to)h(MIME)g(quoted)e(printable)50 970 y(ra)o(w)p 179 970 25 4 v 29 w(unicode)p 473 970 V 28 w(escape)p 765 1000 4 100 v 2234 1000 V 1568 w(Unicode)h(string)p 2825 1000 V 99 w(Produce)g(a)h(string)g(that)g(is)h(suitable)f(as)h(ra) o(w)f(Unicode)f(literal)i(in)f(Python)f(source)h(code)50 1069 y(rot)p 148 1069 25 4 v 29 w(13)p 765 1099 4 100 v 561 w(rot13)p 2234 1099 V 1292 w(Unicode)f(string)p 2825 1099 V 99 w(Returns)h(the)g(Caesar)n(-c)o(ypher)e(encryption)g(of) i(the)g(operand)50 1169 y(string)p 245 1169 25 4 v 29 w(escape)p 765 1199 4 100 v 2234 1199 V 1795 w(byte)g(string)p 2825 1199 V 237 w(Produce)f(a)h(string)g(that)g(is)h(suitable)f(as)h (string)f(literal)h(in)f(Python)f(source)h(code)50 1269 y(unde\002ned)p 765 1298 V 2234 1298 V 1906 w(an)o(y)p 2825 1298 V 471 w(Raise)h(an)f(e)o(xception)e(for)i(all)h(con)m(v)o (ersions.)h(Can)f(be)f(used)g(as)h(the)f(system)g(encoding)e(if)j(no)f (automatic)f(coercion)f(between)i(byte)g(and)f(Unicode)g(strings)h(is)h (desired.)50 1368 y(unicode)p 320 1368 25 4 v 28 w(escape)p 765 1398 4 100 v 2234 1398 V 1721 w(Unicode)e(string)p 2825 1398 V 99 w(Produce)g(a)h(string)g(that)g(is)h(suitable)f(as)h (Unicode)e(literal)i(in)f(Python)f(source)h(code)50 1468 y(unicode)p 320 1468 25 4 v 28 w(internal)p 765 1498 4 100 v 2234 1498 V 1688 w(Unicode)f(string)p 2825 1498 V 99 w(Return)g(the)i(internal)e(representation)f(of)i(the)g(operand)50 1567 y(uu)p 139 1567 25 4 v 29 w(codec)p 765 1597 4 100 v 459 w(uu)p 2234 1597 V 1385 w(byte)g(string)p 2825 1597 V 237 w(Con)m(v)o(ert)e(the)j(operand)d(using)h(uuencode)50 1667 y(zlib)p 180 1667 25 4 v 29 w(codec)p 765 1697 4 100 v 418 w(zip,)g(zlib)p 2234 1697 V 1202 w(byte)h(string)p 2825 1697 V 237 w(Compress)g(the)g(operand)e(using)i(gzip)0 1946 y Fv(4.8.4)100 b Fm(encodings.idna)25 b Fv(\227)i(Inter)r (nationaliz)o(ed)k(Domain)e(Names)f(in)g(Applications)0 2149 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 2296 y(This)26 b(module)f(implements)h(RFC)h(3490)e(\(Internationalized)e(Domain)j (Names)g(in)g(Applications\))f(and)h(RFC)i(3492)c(\(Nameprep:)0 2395 y(A)37 b(Stringprep)d(Pro\002le)j(for)e(Internationalized)f (Domain)h(Names)i(\(IDN\)\).)e(It)i(b)n(uilds)f(upon)f(the)h FJ(punycode)g FN(encoding)e(and)0 2495 y FJ(stringprep)p FN(.)0 2642 y(These)20 b(RFCs)j(together)c(de\002ne)h(a)g(protocol)f (to)i(support)e(non-)r FH(A)t(S)t(C)t(I)t(I)j FN(characters)d(in)i (domain)e(names.)26 b(A)21 b(domain)e(name)g(containing)0 2741 y(non-)r FH(A)t(S)t(C)t(I)t(I)28 b FN(characters)d(\(such)h(as)h (\223www)-5 b(.Alliancefranc)-32 b(\270)q(aise.nu\224\))25 b(is)i(con)m(v)o(erted)d(into)i(an)i FH(A)t(S)t(C)t(I)t(I)r FN(-compatible)e(encoding)e(\(A)m(CE,)0 2841 y(such)29 b(as)h(\223www)-5 b(.xn\226alliancefranaise-npb)m(.)o(nu)o(\224\).)47 b(The)29 b(A)m(CE)h(form)e(of)h(the)g(domain)f(name)h(is)h(then)f(used) g(in)h(all)g(places)f(where)0 2941 y(arbitrary)i(characters)h(are)g (not)g(allo)n(wed)g(by)g(the)h(protocol,)g(such)g(as)g(DNS)g(queries,)i (HTTP)d FO(Host:)50 b FN(\002elds,)36 b(and)c(so)h(on.)61 b(This)0 3040 y(con)m(v)o(ersion)27 b(is)k(carried)e(out)g(in)h(the)g (application;)j(if)d(possible)f(in)m(visible)g(to)h(the)g(user:)44 b(The)30 b(application)e(should)h(transparently)0 3140 y(con)m(v)o(ert)18 b(Unicode)g(domain)g(labels)i(to)g(IDN)m(A)f(on)g (the)h(wire,)g(and)f(con)m(v)o(ert)e(back)i(A)m(CE)h(labels)g(to)f (Unicode)g(before)f(presenting)g(them)0 3240 y(to)i(the)h(user)-5 b(.)0 3386 y(Python)22 b(supports)g(this)h(con)m(v)o(ersion)d(in)j(se)n (v)o(eral)f(w)o(ays:)31 b(The)23 b FJ(idna)g FN(codec)f(allo)n(ws)h(to) g(con)m(v)o(ert)e(between)h(Unicode)f(and)i(the)g(A)m(CE.)0 3486 y(Furthermore,)f(the)h FJ(socket)g FN(module)f(transparently)g (con)m(v)o(erts)g(Unicode)g(host)i(names)f(to)h(A)m(CE,)f(so)h(that)g (applications)e(need)h(not)0 3586 y(be)28 b(concerned)d(about)i(con)m (v)o(erting)d(host)k(names)f(themselv)o(es)g(when)g(the)o(y)g(pass)h (them)g(to)f(the)h(sock)o(et)f(module.)46 b(On)28 b(top)f(of)h(that,)0 3685 y(modules)c(that)g(ha)n(v)o(e)g(host)h(names)f(as)i(function)d (parameters,)h(such)g(as)i FJ(httplib)e FN(and)g FJ(ftplib)p FN(,)h(accept)f(Unicode)f(host)i(names)0 3785 y(\()p FJ(httplib)19 b FN(then)h(also)g(transparently)f(sends)h(an)g(IDN)m(A)g (hostname)f(in)i(the)f FO(Host:)25 b FN(\002eld)20 b(if)h(it)g(sends)f (that)g(\002eld)g(at)h(all\).)0 3932 y(When)j(recei)n(ving)f(host)i (names)f(from)g(the)g(wire)h(\(such)f(as)h(in)g(re)n(v)o(erse)f(name)g (lookup\),)f(no)h(automatic)g(con)m(v)o(ersion)d(to)k(Unicode)f(is)0 4031 y(performed:)f(Applications)c(wishing)g(to)i(present)e(such)h (host)g(names)g(to)h(the)f(user)g(should)f(decode)g(them)h(to)g (Unicode.)0 4178 y(The)d(module)f FJ(encodings.idna)g FN(also)h(implements)g(the)g(nameprep)f(procedure,)f(which)i(performs)f (certain)g(normalizations)g(on)0 4278 y(host)g(names,)h(to)g(achie)n(v) o(e)e(case-insensiti)n(vity)g(of)i(international)d(domain)i(names,)g (and)g(to)h(unify)e(similar)i(characters.)22 b(The)17 b(nameprep)0 4378 y(functions)i(can)h(be)g(used)g(directly)f(if)i (desired.)0 4524 y FD(nameprep)p FJ(\()p FK(label)p FJ(\))208 4624 y FN(Return)50 b(the)g(nameprepped)e(v)o(ersion)h(of)h FK(label)p FN(.)116 b(The)50 b(implementation)e(currently)h(assumes)i (query)e(strings,)58 b(so)208 4724 y FJ(AllowUnassigned)18 b FN(is)j(true.)0 4871 y FD(ToASCII)p FJ(\()p FK(label)p FJ(\))208 4970 y FN(Con)m(v)o(ert)d(a)j(label)f(to)i FH(A)t(S)t(C)t(I)t(I)r FN(,)g(as)f(speci\002ed)f(in)g(RFC)i(3490.)h FJ(UseSTD3ASCIIRules)18 b FN(is)j(assumed)f(to)g(be)g(f)o(alse.)0 5117 y FD(ToUnicode)p FJ(\()p FK(label)p FJ(\))208 5217 y FN(Con)m(v)o(ert)e(a)j(label)f(to)g(Unicode,)f(as)i(speci\002ed)f(in) g(RFC)i(3490.)p 0 5549 3901 4 v 0 5649 a FI(4.8.)52 b FJ(codecs)22 b FI(\227)h(Codec)g(registr)r(y)g(and)g(base)h(classes) 1986 b(89)p eop end %%Page: 90 102 TeXDict begin 90 101 bop 0 83 a Fv(4.8.5)100 b Fm(encodings.utf_8_sig) 24 b Fv(\227)j(UTF-8)h(codec)g(with)g(BOM)g(signature)0 286 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 433 y(This)26 b(module)e(implements)h(a)h(v)n(ariant)f(of)h(the)g(UTF-8)f(codec:)35 b(On)26 b(encoding)e(a)i(UTF-8)g(encoded)e(BOM)i(will)h(be)e(prepended) e(to)0 532 y(the)h(UTF-8)f(encoded)f(bytes.)35 b(F)o(or)23 b(the)h(stateful)f(encoder)f(this)i(is)h(only)e(done)f(once)h(\(on)g (the)g(\002rst)i(write)f(to)f(the)h(byte)f(stream\).)35 b(F)o(or)0 632 y(decoding)18 b(an)i(optional)f(UTF-8)h(encoded)e(BOM)j (at)g(the)f(start)h(of)f(the)g(data)g(will)h(be)f(skipped.)0 959 y FE(4.9)121 b Fx(unicodedata)30 b FE(\227)j(Unicode)i(Database)0 1192 y FN(This)26 b(module)f(pro)o(vides)f(access)i(to)g(the)g(Unicode) f(Character)g(Database)h(which)f(de\002nes)h(character)f(properties)f (for)h(all)i(Unicode)0 1292 y(characters.)38 b(The)25 b(data)g(in)g(this)g(database)f(is)i(based)f(on)f(the)h(`)p FO(UnicodeData.txt)p FN(')c(\002le)26 b(v)o(ersion)e(4.1.0)f(which)i (is)g(publicly)f(a)n(v)n(ailable)0 1392 y(from)19 b FO(ftp://ftp)m (.unicode)o(.org/)-6 b FN(.)0 1538 y(The)55 b(module)f(uses)i(the)f (same)h(names)f(and)g(symbols)f(as)i(de\002ned)f(by)g(the)g (UnicodeData)f(File)i(F)o(ormat)e(4.1.0)g(\(see)0 1638 y FO(http://www)l(.unicode)o(.org)o(/Pub)n(l)o(ic/4)o(.1.)o(0/u)o (cd/UCD)-5 b(.)o(html)f FN(\).)25 b(It)20 b(de\002nes)g(the)g(follo)n (wing)f(functions:)0 1785 y FD(lookup)p FJ(\()p FK(name)p FJ(\))208 1885 y FN(Look)27 b(up)h(character)f(by)h(name.)48 b(If)28 b(a)h(character)e(with)i(the)f(gi)n(v)o(en)f(name)h(is)h (found,)f(return)g(the)g(corresponding)d(Unicode)208 1984 y(character)-5 b(.)24 b(If)c(not)g(found,)e FJ(KeyError)h FN(is)i(raised.)0 2131 y FD(name)p FJ(\()p FK(unic)o(hr)r FC([)p FK(,)d(default)13 b FC(])p FJ(\))208 2231 y FN(Returns)k(the)h (name)g(assigned)f(to)h(the)g(Unicode)f(character)g FK(unic)o(hr)i FN(as)f(a)h(string.)k(If)18 b(no)g(name)f(is)i(de\002ned,)e FK(default)i FN(is)g(returned,)208 2330 y(or)m(,)g(if)h(not)g(gi)n(v)o (en,)f FJ(ValueError)g FN(is)i(raised.)0 2477 y FD(decimal)p FJ(\()p FK(unic)o(hr)r FC([)p FK(,)c(default)c FC(])p FJ(\))208 2577 y FN(Returns)29 b(the)g(decimal)g(v)n(alue)g(assigned)g (to)h(the)f(Unicode)f(character)g FK(unic)o(hr)j FN(as)f(inte)o(ger)-5 b(.)52 b(If)29 b(no)g(such)h(v)n(alue)e(is)j(de\002ned,)208 2676 y FK(default)20 b FN(is)i(returned,)c(or)m(,)h(if)i(not)e(gi)n(v)o (en,)g FJ(ValueError)g FN(is)i(raised.)0 2823 y FD(digit)p FJ(\()p FK(unic)o(hr)r FC([)p FK(,)d(default)13 b FC(])p FJ(\))208 2923 y FN(Returns)21 b(the)h(digit)g(v)n(alue)f(assigned)h (to)g(the)g(Unicode)e(character)h FK(unic)o(hr)i FN(as)g(inte)o(ger)-5 b(.)29 b(If)22 b(no)f(such)h(v)n(alue)f(is)i(de\002ned,)e FK(default)208 3023 y FN(is)g(returned,)d(or)m(,)h(if)i(not)f(gi)n(v)o (en,)e FJ(ValueError)h FN(is)i(raised.)0 3169 y FD(numeric)p FJ(\()p FK(unic)o(hr)r FC([)p FK(,)c(default)c FC(])p FJ(\))208 3269 y FN(Returns)19 b(the)h(numeric)e(v)n(alue)h(assigned)h (to)g(the)f(Unicode)g(character)f FK(unic)o(hr)j FN(as)g(\003oat.)k(If) 19 b(no)h(such)f(v)n(alue)g(is)i(de\002ned,)d FK(default)208 3369 y FN(is)j(returned,)d(or)m(,)h(if)i(not)f(gi)n(v)o(en,)e FJ(ValueError)h FN(is)i(raised.)0 3516 y FD(category)p FJ(\()p FK(unic)o(hr)r FJ(\))208 3615 y FN(Returns)f(the)g(general)f (cate)o(gory)f(assigned)i(to)g(the)g(Unicode)f(character)g FK(unic)o(hr)j FN(as)f(string.)0 3762 y FD(bidirectional)p FJ(\()p FK(unic)o(hr)r FJ(\))208 3862 y FN(Returns)16 b(the)h(bidirectional)f(cate)o(gory)f(assigned)h(to)h(the)g(Unicode)f (character)g FK(unic)o(hr)i FN(as)g(string.)23 b(If)17 b(no)g(such)g(v)n(alue)f(is)i(de\002ned,)208 3961 y(an)i(empty)f (string)h(is)h(returned.)0 4108 y FD(combining)p FJ(\()p FK(unic)o(hr)r FJ(\))208 4208 y FN(Returns)28 b(the)g(canonical)g (combining)e(class)j(assigned)f(to)h(the)f(Unicode)g(character)f FK(unic)o(hr)j FN(as)f(inte)o(ger)-5 b(.)49 b(Returns)28 b FJ(0)h FN(if)g(no)208 4307 y(combining)17 b(class)22 b(is)f(de\002ned.)0 4454 y FD(east_asian_width)p FJ(\()p FK(unic)o(hr)r FJ(\))208 4554 y FN(Returns)f(the)g(east)h(asian)f (width)g(assigned)g(to)g(the)g(Unicode)f(character)g FK(unic)o(hr)i FN(as)g(string.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.) 0 4701 y FD(mirrored)p FJ(\()p FK(unic)o(hr)r FJ(\))208 4800 y FN(Returns)25 b(the)g(mirrored)e(property)g(assigned)i(to)g(the) g(Unicode)f(character)g FK(unic)o(hr)i FN(as)g(inte)o(ger)-5 b(.)40 b(Returns)25 b FJ(1)g FN(if)h(the)f(character)208 4900 y(has)20 b(been)f(identi\002ed)h(as)h(a)f(\223mirrored\224)e (character)h(in)i(bidirectional)d(te)o(xt,)i FJ(0)g FN(otherwise.)0 5047 y FD(decomposition)p FJ(\()p FK(unic)o(hr)r FJ(\))208 5147 y FN(Returns)27 b(the)g(character)e(decomposition)g(mapping)g (assigned)i(to)g(the)g(Unicode)f(character)g FK(unic)o(hr)i FN(as)g(string.)45 b(An)27 b(empty)208 5246 y(string)19 b(is)j(returned)c(in)i(case)h(no)f(such)g(mapping)e(is)j(de\002ned.)0 5393 y FD(normalize)p FJ(\()p FK(form,)d(unistr)r FJ(\))p 0 5549 3901 4 v 0 5649 a FI(90)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 91 103 TeXDict begin 91 102 bop 208 83 a FN(Return)22 b(the)h(normal)f(form)f FK(form)j FN(for)e(the)h(Unicode)f(string)g FK(unistr)r FN(.)33 b(V)-9 b(alid)23 b(v)n(alues)g(for)f FK(form)h FN(are)g('NFC',)g('NFKC',)g('NFD',)208 183 y(and)c('NFKD'.)208 314 y(The)d(Unicode)g(standard)g(de\002nes)h(v)n(arious)f (normalization)f(forms)i(of)g(a)g(Unicode)f(string,)h(based)g(on)g(the) g(de\002nition)f(of)h(canon-)208 414 y(ical)i(equi)n(v)n(alence)f(and)h (compatibility)e(equi)n(v)n(alence.)23 b(In)c(Unicode,)f(se)n(v)o(eral) h(characters)g(can)g(be)g(e)o(xpressed)f(in)i(v)n(arious)e(w)o(ay)-5 b(.)208 513 y(F)o(or)18 b(e)o(xample,)f(the)i(character)e(U+00C7)h (\(LA)-9 b(TIN)18 b(CAPIT)-8 b(AL)19 b(LETTER)f(C)i(WITH)f(CEDILLA\))e (can)i(also)g(be)g(e)o(xpressed)e(as)208 613 y(the)j(sequence)f(U+0043) f(\(LA)-9 b(TIN)20 b(CAPIT)-8 b(AL)20 b(LETTER)g(C\))h(U+0327)d (\(COMBINING)i(CEDILLA\).)208 745 y(F)o(or)i(each)h(character)m(,)f (there)h(are)g(tw)o(o)h(normal)e(forms:)30 b(normal)22 b(form)h(C)h(and)e(normal)g(form)h(D.)g(Normal)g(form)f(D)i(\(NFD\))f (is)208 844 y(also)f(kno)n(wn)f(as)i(canonical)e(decomposition,)f(and)h (translates)i(each)e(character)g(into)h(its)h(decomposed)d(form.)30 b(Normal)22 b(form)208 944 y(C)f(\(NFC\))f(\002rst)h(applies)f(a)h (canonical)e(decomposition,)e(then)j(composes)f(pre-combined)e (characters)i(again.)208 1076 y(In)24 b(addition)g(to)i(these)f(tw)o(o) h(forms,)f(there)g(are)g(tw)o(o)g(additional)f(normal)g(forms)h(based)g (on)f(compatibility)g(equi)n(v)n(alence.)38 b(In)208 1175 y(Unicode,)18 b(certain)h(characters)g(are)h(supported)e(which)h (normally)f(w)o(ould)h(be)h(uni\002ed)f(with)h(other)f(characters.)24 b(F)o(or)19 b(e)o(xample,)208 1275 y(U+2160)30 b(\(R)m(OMAN)h(NUMERAL)h (ONE\))g(is)h(really)e(the)h(same)g(thing)f(as)h(U+0049)f(\(LA)-9 b(TIN)30 b(CAPIT)-8 b(AL)33 b(LETTER)e(I\).)208 1374 y(Ho)n(we)n(v)o(er)m(,)18 b(it)j(is)g(supported)d(in)i(Unicode)f(for)h (compatibility)e(with)j(e)o(xisting)e(character)g(sets)i(\(e.g.)k (gb2312\).)208 1506 y(The)19 b(normal)f(form)h(KD)g(\(NFKD\))h(will)g (apply)f(the)g(compatibility)f(decomposition,)f(i.e.)25 b(replace)19 b(all)h(compatibility)e(charac-)208 1606 y(ters)f(with)f(their)h(equi)n(v)n(alents.)22 b(The)16 b(normal)g(form)f(KC)j(\(NFKC\))f(\002rst)g(applies)g(the)f (compatibility)f(decomposition,)g(follo)n(wed)208 1705 y(by)k(the)i(canonical)d(composition.)208 1837 y(Ne)n(w)i(in)g(v)o (ersion)f(2.3.)0 1984 y(In)h(addition,)f(the)h(module)f(e)o(xposes)g (the)h(follo)n(wing)f(constant:)0 2131 y FD(unidata_version)208 2230 y FN(The)g(v)o(ersion)g(of)h(the)g(Unicode)f(database)h(used)g(in) g(this)h(module.)208 2362 y(Ne)n(w)f(in)g(v)o(ersion)f(2.3.)0 2509 y FD(ucd_3_2_0)208 2608 y FN(This)27 b(is)h(an)f(object)f(that)i (has)f(the)g(same)g(methods)f(as)i(the)f(entire)g(module,)g(b)n(ut)g (uses)h(the)f(Unicode)f(database)g(v)o(ersion)g(3.2)208 2708 y(instead,)19 b(for)h(applications)f(that)h(require)f(this)i (speci\002c)f(v)o(ersion)f(of)h(the)g(Unicode)f(database)h(\(such)f(as) i(IDN)m(A\).)208 2839 y(Ne)n(w)f(in)g(v)o(ersion)f(2.5.)0 2986 y(Examples:)236 3225 y FA(>>>)45 b(unicodedata.lookup\('LEFT)40 b(CURLY)k(BRACKET'\))236 3316 y(u'{')236 3407 y(>>>)h (unicodedata.name\(u'/'\))236 3499 y('SOLIDUS')236 3590 y(>>>)g(unicodedata.decimal\(u'9'\))236 3681 y(9)236 3772 y(>>>)g(unicodedata.decimal\(u'a'\))236 3864 y(Traceback)f(\(most) g(recent)f(call)i(last\):)326 3955 y(File)f("",)f(line)h(1,)h (in)f(?)236 4046 y(ValueError:)f(not)i(a)f(decimal)236 4138 y(>>>)h(unicodedata.category\(u'A'\))85 b(#)45 b('L'etter,)e ('u'ppercase)236 4229 y('Lu')236 4320 y(>>>)i (unicodedata.bidirectional\(u'\\u0660'\))38 b(#)45 b('A'rabic,)e ('N'umber)236 4412 y('AN')0 4921 y FE(4.10)121 b Fx(stringprep)31 b FE(\227)i(Inter)s(net)i(Str)r(ing)e(Prepar)o(ation)0 5154 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 5300 y(When)j (identifying)d(things)j(\(such)f(as)h(host)g(names\))f(in)h(the)g (internet,)f(it)h(is)h(often)e(necessary)g(to)h(compare)e(such)h (identi\002cations)g(for)0 5400 y(\223equality\224.)36 b(Exactly)24 b(ho)n(w)g(this)h(comparison)d(is)j(e)o(x)o(ecuted)e(may)h (depend)f(on)h(the)g(application)f(domain,)h(e.g.)37 b(whether)23 b(it)j(should)p 0 5549 3901 4 v 0 5649 a FI(4.10.)52 b FJ(stringprep)21 b FI(\227)j(Inter)r(net)f(Str)q(ing)h (Prepar)o(ation)1970 b(91)p eop end %%Page: 92 104 TeXDict begin 92 103 bop 0 83 a FN(be)20 b(case-insensiti)n(v)o(e)e(or) i(not.)k(It)c(may)f(be)h(also)g(necessary)f(to)h(restrict)f(the)h (possible)g(identi\002cations,)e(to)i(allo)n(w)g(only)f (identi\002cations)0 183 y(consisting)g(of)h(\223printable\224)f (characters.)0 330 y(RFC)25 b(3454)c(de\002nes)i(a)g(procedure)e(for)h (\223preparing\224)f(Unicode)h(strings)h(in)g(internet)f(protocols.)32 b(Before)23 b(passing)f(strings)h(onto)g(the)0 429 y(wire,)h(the)o(y)f (are)h(processed)f(with)h(the)f(preparation)f(procedure,)g(after)h (which)g(the)o(y)g(ha)n(v)o(e)g(a)h(certain)f(normalized)f(form.)35 b(The)23 b(RFC)0 529 y(de\002nes)g(a)h(set)g(of)g(tables,)g(which)f (can)g(be)h(combined)d(into)i(pro\002les.)35 b(Each)23 b(pro\002le)g(must)g(de\002ne)g(which)g(tables)h(it)g(uses,)h(and)e (what)0 628 y(other)18 b(optional)g(parts)i(of)e(the)i FJ(stringprep)e FN(procedure)e(are)k(part)e(of)h(the)h(pro\002le.)k (One)19 b(e)o(xample)f(of)g(a)i FJ(stringprep)e FN(pro\002le)h(is)0 728 y FJ(nameprep)p FN(,)g(which)h(is)h(used)f(for)f(internationalized) f(domain)h(names.)0 875 y(The)i(module)e FJ(stringprep)h FN(only)g(e)o(xposes)g(the)h(tables)g(from)f(RFC)i(3454.)k(As)c(these)f (tables)g(w)o(ould)f(be)h(v)o(ery)f(lar)o(ge)g(to)h(represent)0 975 y(them)d(as)i(dictionaries)e(or)g(lists,)j(the)e(module)e(uses)i (the)g(Unicode)f(character)g(database)g(internally)-5 b(.)23 b(The)18 b(module)g(source)g(code)g(itself)0 1074 y(w)o(as)j(generated)d(using)i(the)g FJ(mkstringprep.py)e FN(utility)-5 b(.)0 1221 y(As)20 b(a)g(result,)f(these)g(tables)h(are)f (e)o(xposed)e(as)j(functions,)e(not)h(as)h(data)f(structures.)24 b(There)18 b(are)i(tw)o(o)f(kinds)g(of)g(tables)g(in)g(the)h(RFC:)g (sets)0 1321 y(and)i(mappings.)32 b(F)o(or)23 b(a)g(set,)i FJ(stringprep)c FN(pro)o(vides)g(the)i(\223characteristic)f (function\224,)g(i.e.)34 b(a)23 b(function)e(that)i(returns)g(true)f (if)i(the)0 1420 y(parameter)e(is)j(part)e(of)h(the)g(set.)36 b(F)o(or)23 b(mappings,)g(it)i(pro)o(vides)d(the)h(mapping)f(function:) 31 b(gi)n(v)o(en)23 b(the)g(k)o(e)o(y)-5 b(,)24 b(it)g(returns)f(the)h (associated)0 1520 y(v)n(alue.)g(Belo)n(w)d(is)g(a)f(list)i(of)e(all)g (functions)f(a)n(v)n(ailable)h(in)g(the)g(module.)0 1667 y FD(in_table_a1)p FJ(\()p FK(code)p FJ(\))208 1766 y FN(Determine)f(whether)g FK(code)g FN(is)j(in)e(tableA.1)f (\(Unassigned)g(code)h(points)f(in)i(Unicode)e(3.2\).)0 1913 y FD(in_table_b1)p FJ(\()p FK(code)p FJ(\))208 2013 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e(tableB.1)g (\(Commonly)e(mapped)g(to)j(nothing\).)0 2160 y FD(map_table_b2)p FJ(\()p FK(code)p FJ(\))208 2259 y FN(Return)e(the)i(mapped)d(v)n(alue) i(for)f FK(code)h FN(according)e(to)i(tableB.2)g(\(Mapping)e(for)i (case-folding)e(used)i(with)g(NFKC\).)0 2406 y FD(map_table_b3)p FJ(\()p FK(code)p FJ(\))208 2506 y FN(Return)d(the)g(mapped)f(v)n(alue) h(for)g FK(code)g FN(according)f(to)i(tableB.3)f(\(Mapping)e(for)i (case-folding)f(used)h(with)h(no)f(normalization\).)0 2653 y FD(in_table_c11)p FJ(\()p FK(code)p FJ(\))208 2752 y FN(Determine)i(whether)g FK(code)g FN(is)j(in)e(tableC.1.1)f (\(ASCII)h(space)g(characters\).)0 2899 y FD(in_table_c12)p FJ(\()p FK(code)p FJ(\))208 2999 y FN(Determine)f(whether)g FK(code)g FN(is)j(in)e(tableC.1.2)f(\(Non-ASCII)g(space)h (characters\).)0 3146 y FD(in_table_c11_c12)p FJ(\()p FK(code)p FJ(\))208 3245 y FN(Determine)f(whether)g FK(code)g FN(is)j(in)e(tableC.1)g(\(Space)f(characters,)g(union)g(of)h(C.1.1)g (and)f(C.1.2\).)0 3392 y FD(in_table_c21)p FJ(\()p FK(code)p FJ(\))208 3492 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e (tableC.2.1)f(\(ASCII)h(control)f(characters\).)0 3639 y FD(in_table_c22)p FJ(\()p FK(code)p FJ(\))208 3738 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e(tableC.2.2)f (\(Non-ASCII)g(control)g(characters\).)0 3885 y FD(in_table_c21_c22)p FJ(\()p FK(code)p FJ(\))208 3985 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e(tableC.2)g(\(Control)f(characters,)g(union)g(of) h(C.2.1)f(and)h(C.2.2\).)0 4132 y FD(in_table_c3)p FJ(\()p FK(code)p FJ(\))208 4231 y FN(Determine)f(whether)g FK(code)g FN(is)j(in)e(tableC.3)g(\(Pri)n(v)n(ate)f(use\).)0 4378 y FD(in_table_c4)p FJ(\()p FK(code)p FJ(\))208 4478 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e(tableC.4)g (\(Non-character)d(code)i(points\).)0 4625 y FD(in_table_c5)p FJ(\()p FK(code)p FJ(\))208 4724 y FN(Determine)g(whether)g FK(code)g FN(is)j(in)e(tableC.5)g(\(Surrogate)d(codes\).)0 4871 y FD(in_table_c6)p FJ(\()p FK(code)p FJ(\))208 4971 y FN(Determine)i(whether)g FK(code)g FN(is)j(in)e(tableC.6)g (\(Inappropriate)c(for)k(plain)g(te)o(xt\).)0 5118 y FD(in_table_c7)p FJ(\()p FK(code)p FJ(\))208 5217 y FN(Determine)f (whether)g FK(code)g FN(is)j(in)e(tableC.7)g(\(Inappropriate)c(for)k (canonical)f(representation\).)0 5364 y FD(in_table_c8)p FJ(\()p FK(code)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(92)2807 b(Chapter)23 b(4.)52 b(Str)q(ing)24 b(Ser)r(vices)p eop end %%Page: 93 105 TeXDict begin 93 104 bop 208 83 a FN(Determine)19 b(whether)g FK(code)g FN(is)j(in)e(tableC.8)g(\(Change)f(display)g(properties)g(or) h(are)g(deprecated\).)0 230 y FD(in_table_c9)p FJ(\()p FK(code)p FJ(\))208 330 y FN(Determine)f(whether)g FK(code)g FN(is)j(in)e(tableC.9)g(\(T)-7 b(agging)18 b(characters\).)0 476 y FD(in_table_d1)p FJ(\()p FK(code)p FJ(\))208 576 y FN(Determine)h(whether)g FK(code)g FN(is)j(in)e(tableD.1)f (\(Characters)h(with)g(bidirectional)e(property)g(\223R\224)j(or)f (\223)-7 b(AL)f(\224\).)0 723 y FD(in_table_d2)p FJ(\()p FK(code)p FJ(\))208 823 y FN(Determine)19 b(whether)g FK(code)g FN(is)j(in)e(tableD.2)f(\(Characters)h(with)g(bidirectional)e (property)g(\223L)-8 b(\224\).)0 1150 y FE(4.11)121 b Fx(fpformat)31 b FE(\227)i(Floating)i(point)f(con)n(v)m(ersions)0 1383 y FN(The)f FJ(fpformat)f FN(module)g(de\002nes)h(functions)e(for)i (dealing)f(with)h(\003oating)g(point)f(numbers)g(representations)f(in)i (100\045)f(pure)0 1482 y(Python.)24 b FL(Note:)g FN(This)c(module)f(is) i(unneeded:)i(e)n(v)o(erything)18 b(here)i(could)f(be)h(done)f(via)h (the)g FJ(\045)h FN(string)f(interpolation)e(operator)-5 b(.)0 1629 y(The)20 b FJ(fpformat)f FN(module)g(de\002nes)h(the)g (follo)n(wing)f(functions)f(and)i(an)g(e)o(xception:)0 1776 y FD(fix)p FJ(\()p FK(x,)g(digs)p FJ(\))208 1876 y FN(F)o(ormat)28 b FK(x)h FN(as)g FJ([-]ddd.ddd)f FN(with)h FK(digs)g FN(digits)g(after)f(the)h(point)f(and)g(at)h(least)h(one)e (digit)h(before.)49 b(If)29 b FK(digs)49 b FJ(<=)g(0)p FN(,)32 b(the)208 1975 y(decimal)19 b(point)h(is)h(suppressed.)208 2108 y FK(x)f FN(can)g(be)h(either)e(a)i(number)d(or)i(a)h(string)f (that)g(looks)g(lik)o(e)g(one.)25 b FK(digs)20 b FN(is)h(an)f(inte)o (ger)-5 b(.)208 2241 y(Return)19 b(v)n(alue)h(is)h(a)g(string.)0 2388 y FD(sci)p FJ(\()p FK(x,)f(digs)p FJ(\))208 2488 y FN(F)o(ormat)e FK(x)j FN(as)f FJ([-]d.dddE[+-]ddd)d FN(with)j FK(digs)g FN(digits)g(after)f(the)h(point)e(and)i(e)o(xactly) e(one)h(digit)h(before.)j(If)d FK(digs)49 b FJ(<=)g(0)p FN(,)208 2587 y(one)19 b(digit)h(is)h(k)o(ept)f(and)g(the)g(point)g(is) h(suppressed.)208 2720 y FK(x)f FN(can)g(be)h(either)e(a)i(real)f (number)m(,)e(or)i(a)h(string)e(that)i(looks)e(lik)o(e)i(one.)j FK(digs)c FN(is)h(an)g(inte)o(ger)-5 b(.)208 2853 y(Return)19 b(v)n(alue)h(is)h(a)g(string.)0 3000 y FL(exception)e FD(NotANumber)208 3099 y FN(Exception)d(raised)h(when)h(a)g(string)f (passed)h(to)g FJ(fix\(\))g FN(or)f FJ(sci\(\))h FN(as)g(the)g FK(x)h FN(parameter)d(does)i(not)f(look)g(lik)o(e)h(a)h(number)-5 b(.)22 b(This)208 3199 y(is)f(a)g(subclass)g(of)f FJ(ValueError)f FN(when)h(the)g(standard)g(e)o(xceptions)f(are)h(strings.)26 b(The)20 b(e)o(xception)e(v)n(alue)i(is)i(the)e(improperly)208 3299 y(formatted)e(string)i(that)g(caused)g(the)g(e)o(xception)e(to)j (be)f(raised.)0 3445 y(Example:)236 3684 y FA(>>>)45 b(import)e(fpformat)236 3775 y(>>>)i(fpformat.fix\(1.23,)c(1\))236 3866 y('1.2')p 0 5549 3901 4 v 0 5649 a FI(4.11.)52 b FJ(fpformat)22 b FI(\227)h(Floating)h(point)g(con)n(v)n(ersions)2083 b(93)p eop end %%Page: 94 106 TeXDict begin 94 105 bop 0 5549 3901 4 v 0 5649 a FI(94)p eop end %%Page: 95 107 TeXDict begin 95 106 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3634 427 y FG(FIVE)p 0 515 V 2869 978 a FT(Data)57 b(T)-25 b(ypes)0 1466 y FN(The)23 b(modules)f(described)f(in)j(this)f(chapter)f (pro)o(vide)f(a)i(v)n(ariety)g(of)f(specialized)h(data)g(types)f(such)h (as)h(dates)f(and)g(times,)h(\002x)o(ed-type)0 1566 y(arrays,)19 b(heap)h(queues,)f(synchronized)e(queues,)i(and)h(sets.)0 1713 y(The)g(follo)n(wing)e(modules)i(are)g(documented)d(in)k(this)f (chapter:)50 1856 y FD(datetime)247 b FN(Basic)22 b(date)e(and)f(time)i (types.)50 1956 y FD(calendar)247 b FN(Functions)20 b(for)f(w)o(orking) g(with)h(calendars,)f(including)g(some)h(emulation)e(of)i(the)j(U)t FH(N)t(I)t(X)g FL(cal)d FN(program.)50 2055 y FD(collections)97 b FN(High-performance)16 b(datatypes)50 2155 y FD(heapq)397 b FN(Heap)20 b(queue)f(algorithm)g(\(a.k.a.)24 b(priority)19 b(queue\).)50 2254 y FD(bisect)347 b FN(Array)20 b(bisection)f (algorithms)g(for)h(binary)f(searching.)50 2354 y FD(array)397 b FN(Ef)n(\002cient)20 b(arrays)g(of)f(uniformly)f(typed)i(numeric)e(v) n(alues.)50 2454 y FD(sets)447 b FN(Implementation)18 b(of)i(sets)h(of)f(unique)f(elements.)50 2553 y FD(sched)397 b FN(General)20 b(purpose)f(e)n(v)o(ent)g(scheduler)-5 b(.)50 2653 y FD(mutex)397 b FN(Lock)20 b(and)f(queue)g(for)h(mutual)f (e)o(xclusion.)50 2753 y FD(Queue)397 b FN(A)21 b(synchronized)d(queue) h(class.)50 2852 y FD(weakref)297 b FN(Support)19 b(for)h(weak)g (references)e(and)i(weak)g(dictionaries.)50 2952 y FD(UserDict)247 b FN(Class)22 b(wrapper)d(for)g(dictionary)g(objects.)50 3051 y FD(UserList)247 b FN(Class)22 b(wrapper)d(for)g(list)j(objects.) 50 3151 y FD(UserString)147 b FN(Class)22 b(wrapper)d(for)g(string)h (objects.)50 3251 y FD(types)397 b FN(Names)21 b(for)e(b)n(uilt-in)h (types.)50 3350 y FD(new)497 b FN(Interf)o(ace)19 b(to)i(the)f (creation)f(of)h(runtime)f(implementation)f(objects.)50 3450 y FD(copy)447 b FN(Shallo)n(w)20 b(and)g(deep)f(cop)o(y)h (operations.)50 3550 y FD(pprint)347 b FN(Data)21 b(pretty)e(printer)-5 b(.)50 3649 y FD(repr)447 b FN(Alternate)20 b FJ(repr\(\))g FN(implementation)e(with)i(size)h(limits.)0 3952 y FE(5.1)121 b Fx(datetime)31 b FE(\227)i(Basic)f(date)j(and)g(time)e(types)0 4185 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4331 y(The)j FJ(datetime)g FN(module)g(supplies)g(classes)i(for)e(manipulating)f (dates)i(and)f(times)h(in)g(both)f(simple)h(and)f(comple)o(x)f(w)o (ays.)33 b(While)0 4431 y(date)26 b(and)g(time)h(arithmetic)e(is)j (supported,)e(the)g(focus)g(of)g(the)h(implementation)d(is)j(on)f(ef)n (\002cient)g(member)f(e)o(xtraction)g(for)h(output)0 4531 y(formatting)18 b(and)i(manipulation.)0 4678 y(There)i(are)i(tw)o (o)f(kinds)g(of)g(date)g(and)g(time)h(objects:)31 b(\223nai)n(v)o (e\224)22 b(and)h(\223a)o(w)o(are\224.)34 b(This)23 b(distinction)g (refers)f(to)i(whether)e(the)i(object)e(has)0 4777 y(an)o(y)i(notion)h (of)g(time)g(zone,)h(daylight)e(sa)n(ving)h(time,)h(or)f(other)g(kind)f (of)h(algorithmic)f(or)h(political)g(time)g(adjustment.)39 b(Whether)25 b(a)0 4877 y(nai)n(v)o(e)f FJ(datetime)g FN(object)g(represents)f(Coordinated)g(Uni)n(v)o(ersal)h(T)m(ime)g (\(UTC\),)h(local)f(time,)i(or)f(time)f(in)h(some)g(other)f(timezone)0 4976 y(is)g(purely)e(up)h(to)h(the)f(program,)f(just)i(lik)o(e)g(it')-5 b(s)24 b(up)f(to)h(the)f(program)e(whether)i(a)g(particular)g(number)e (represents)i(metres,)g(miles,)i(or)0 5076 y(mass.)47 b(Nai)n(v)o(e)27 b FJ(datetime)g FN(objects)g(are)h(easy)f(to)h (understand)d(and)i(to)h(w)o(ork)f(with,)i(at)f(the)f(cost)h(of)f (ignoring)f(some)h(aspects)h(of)0 5176 y(reality)-5 b(.)0 5323 y(F)o(or)31 b(applications)f(requiring)f(more,)j FJ(datetime)f FN(and)f FJ(time)h FN(objects)g(ha)n(v)o(e)f(an)h (optional)f(time)h(zone)g(information)e(member)m(,)p 0 5549 3901 4 v 3808 5649 a FI(95)p eop end %%Page: 96 108 TeXDict begin 96 107 bop 0 83 a FJ(tzinfo)p FN(,)27 b(that)g(can)f (contain)f(an)h(instance)g(of)g(a)h(subclass)g(of)f(the)g(abstract)g FJ(tzinfo)g FN(class.)45 b(These)26 b FJ(tzinfo)g FN(objects)g(capture) 0 183 y(information)16 b(about)h(the)h(of)n(fset)g(from)f(UTC)i(time,)g (the)f(time)h(zone)e(name,)h(and)g(whether)f(Daylight)g(Sa)n(ving)h(T)m (ime)g(is)h(in)g(ef)n(fect.)24 b(Note)0 282 y(that)i(no)g(concrete)g FJ(tzinfo)f FN(classes)j(are)e(supplied)g(by)g(the)g FJ(datetime)f FN(module.)43 b(Supporting)24 b(timezones)h(at)i(whate)n (v)o(er)e(le)n(v)o(el)0 382 y(of)g(detail)g(is)i(required)c(is)j(up)f (to)h(the)f(application.)39 b(The)24 b(rules)i(for)e(time)i(adjustment) e(across)h(the)h(w)o(orld)e(are)i(more)e(political)h(than)0 482 y(rational,)19 b(and)h(there)f(is)j(no)d(standard)g(suitable)h(for) g(e)n(v)o(ery)f(application.)0 628 y(The)h FJ(datetime)f FN(module)g(e)o(xports)g(the)h(follo)n(wing)f(constants:)0 775 y FD(MINYEAR)208 875 y FN(The)g(smallest)i(year)f(number)e(allo)n (wed)i(in)g(a)h FJ(date)f FN(or)g FJ(datetime)f FN(object.)24 b FJ(MINYEAR)c FN(is)h FJ(1)p FN(.)0 1022 y FD(MAXYEAR)208 1121 y FN(The)e(lar)o(gest)h(year)g(number)e(allo)n(wed)i(in)g(a)h FJ(date)f FN(or)f FJ(datetime)h FN(object.)k FJ(MAXYEAR)c FN(is)h FJ(9999)p FN(.)0 1268 y FL(See)g(Also:)0 1415 y FN(Module)e FJ(calendar)g FN(\(section)h(5.2\):)208 1515 y(General)f(calendar)g(related)h(functions.)0 1662 y(Module)f FJ(time)h FN(\(section)g(14.2\):)208 1761 y(T)m(ime)g(access)g(and)g(con)m(v)o(ersions.)0 2046 y Fv(5.1.1)100 b(A)l(v)n(ailab)n(le)30 b(T)-12 b(ypes)0 2235 y FL(class)21 b FD(date)208 2335 y FN(An)28 b(idealized)f(nai)n(v) o(e)g(date,)i(assuming)e(the)h(current)f(Gre)o(gorian)f(calendar)g(al)o (w)o(ays)j(w)o(as,)h(and)e(al)o(w)o(ays)g(will)h(be,)g(in)f(ef)n(fect.) 208 2434 y(Attrib)n(utes:)d FJ(year)p FN(,)20 b FJ(month)p FN(,)f(and)h FJ(day)p FN(.)0 2581 y FL(class)h FD(time)208 2681 y FN(An)33 b(idealized)g(time,)k(independent)32 b(of)h(an)o(y)g(particular)g(day)-5 b(,)36 b(assuming)d(that)g(e)n(v)o (ery)g(day)g(has)h(e)o(xactly)f(24*60*60)d(sec-)208 2780 y(onds)h(\(there)g(is)i(no)e(notion)g(of)g(\224leap)h(seconds\224)f (here\).)59 b(Attrib)n(utes:)48 b FJ(hour)p FN(,)34 b FJ(minute)p FN(,)g FJ(second)p FN(,)g FJ(microsecond)p FN(,)208 2880 y(and)19 b FJ(tzinfo)p FN(.)0 3027 y FL(class)i FD(datetime)208 3127 y FN(A)46 b(combination)e(of)i(a)h(date)f(and)f(a) i(time.)103 b(Attrib)n(utes:)77 b FJ(year)p FN(,)53 b FJ(month)p FN(,)f FJ(day)p FN(,)g FJ(hour)p FN(,)g FJ(minute)p FN(,)g FJ(second)p FN(,)208 3226 y FJ(microsecond)p FN(,)18 b(and)i FJ(tzinfo)p FN(.)0 3373 y FL(class)h FD(timedelta)208 3473 y FN(A)g(duration)e(e)o(xpressing)g(the)i(dif)n(ference)e(between) h(tw)o(o)h FJ(date)p FN(,)f FJ(time)p FN(,)h(or)f FJ(datetime)g FN(instances)h(to)f(microsecond)f(reso-)208 3572 y(lution.)0 3719 y FL(class)i FD(tzinfo)208 3819 y FN(An)c(abstract)g(base)g(class) h(for)e(time)i(zone)e(information)f(objects.)24 b(These)17 b(are)g(used)g(by)f(the)h FJ(datetime)g FN(and)f FJ(time)h FN(classes)h(to)208 3918 y(pro)o(vide)f(a)j(customizable)e(notion)h(of) g(time)h(adjustment)f(\(for)f(e)o(xample,)g(to)i(account)f(for)g(time)g (zone)g(and/or)g(daylight)f(sa)n(ving)208 4018 y(time\).)0 4165 y(Objects)i(of)g(these)h(types)f(are)g(immutable.)0 4312 y(Objects)g(of)g(the)h FJ(date)f FN(type)f(are)h(al)o(w)o(ays)h (nai)n(v)o(e.)0 4459 y(An)35 b(object)e FK(d)k FN(of)e(type)f FJ(time)g FN(or)g FJ(datetime)g FN(may)g(be)g(nai)n(v)o(e)g(or)g(a)o(w) o(are.)67 b FK(d)37 b FN(is)f(a)o(w)o(are)e(if)h FK(d)r FJ(.tzinfo)e FN(is)j(not)e FJ(None)g FN(and)0 4558 y FK(d)r FJ(.tzinfo.utcoffset\()p FK(d)r FJ(\))27 b FN(does)j(not)g (return)f FJ(None)p FN(.)54 b(If)30 b FK(d)r FJ(.tzinfo)g FN(is)h FJ(None)p FN(,)h(or)e(if)g FK(d)r FJ(.tzinfo)g FN(is)h(not)f FJ(None)g FN(b)n(ut)0 4658 y FK(d)r FJ (.tzinfo.utcoffset\()p FK(d)r FJ(\))17 b FN(returns)i FJ(None)p FN(,)h FK(d)i FN(is)f(nai)n(v)o(e.)0 4805 y(The)f (distinction)f(between)h(nai)n(v)o(e)f(and)g(a)o(w)o(are)h(doesn')o(t)f (apply)g(to)i FJ(timedelta)e FN(objects.)0 4952 y(Subclass)h (relationships:)p 0 5549 3901 4 v 0 5649 a FI(96)2954 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 97 109 TeXDict begin 97 108 bop 236 174 a FA(object)416 266 y(timedelta)416 357 y(tzinfo)416 448 y(time)416 540 y(date)595 631 y(datetime)0 1056 y Fv(5.1.2)100 b Fm(timedelta)26 b Fv(Objects)0 1259 y FN(A)21 b FJ(timedelta)e FN(object)g(represents)h (a)g(duration,)f(the)h(dif)n(ference)e(between)h(tw)o(o)i(dates)f(or)g (times.)0 1405 y FL(class)h FD(timedelta)p FJ(\()p FC([)p FK(days)p FC([)p FK(,)c(seconds)p FC([)p FK(,)i(micr)l(oseconds)p FC([)p FK(,)h(milliseconds)p FC([)p FK(,)f(minutes)p FC([)p FK(,)h(hour)o(s)p FC([)p FK(,)f(weeks)12 b FC(])g(])g(])g(])g(]) g(])g(])p FJ(\))208 1505 y FN(All)26 b(ar)o(guments)d(are)i(optional)g (and)f(def)o(ault)h(to)h FJ(0)p FN(.)41 b(Ar)o(guments)23 b(may)i(be)h(ints,)h(longs,)f(or)f(\003oats,)i(and)e(may)g(be)g(positi) n(v)o(e)g(or)208 1605 y(ne)o(gati)n(v)o(e.)208 1738 y(Only)19 b FK(days)p FN(,)h FK(seconds)g FN(and)f FK(micr)l(oseconds)h FN(are)g(stored)g(internally)-5 b(.)23 b(Ar)o(guments)18 b(are)i(con)m(v)o(erted)e(to)i(those)g(units:)349 1951 y FM(\017)o FN(A)h(millisecond)e(is)i(con)m(v)o(erted)d(to)i(1000)f (microseconds.)349 2084 y FM(\017)o FN(A)i(minute)e(is)i(con)m(v)o (erted)d(to)i(60)g(seconds.)349 2217 y FM(\017)o FN(An)g(hour)f(is)i (con)m(v)o(erted)d(to)i(3600)f(seconds.)349 2349 y FM(\017)o FN(A)i(week)f(is)h(con)m(v)o(erted)d(to)i(7)g(days.)208 2563 y(and)f(days,)h(seconds)f(and)h(microseconds)e(are)j(then)e (normalized)g(so)h(that)g(the)h(representation)d(is)j(unique,)d(with) 349 2776 y FM(\017)o FJ(0)50 b(<=)f FK(micr)l(oseconds)g FJ(<)h(1000000)349 2909 y FM(\017)o FJ(0)g(<=)f FK(seconds)g FJ(<)h(3600)1252 2924 y(*)1302 2909 y(24)19 b FN(\(the)h(number)e(of)i (seconds)g(in)g(one)g(day\))349 3042 y FM(\017)o FJ(-999999999)48 b(<=)i FK(days)f FJ(<=)g(999999999)208 3255 y FN(If)23 b(an)o(y)f(ar)o(gument)f(is)k(a)e(\003oat)h(and)f(there)g(are)g (fractional)f(microseconds,)g(the)i(fractional)e(microseconds)f(left)j (o)o(v)o(er)e(from)g(all)208 3355 y(ar)o(guments)j(are)i(combined)e (and)i(their)g(sum)g(is)i(rounded)c(to)i(the)g(nearest)g(microsecond.) 45 b(If)27 b(no)g(ar)o(gument)e(is)j(a)g(\003oat,)h(the)208 3454 y(con)m(v)o(ersion)17 b(and)j(normalization)e(processes)i(are)g(e) o(xact)f(\(no)h(information)e(is)j(lost\).)208 3587 y(If)f(the)g (normalized)e(v)n(alue)i(of)f(days)h(lies)h(outside)f(the)g(indicated)f (range,)g FJ(OverflowError)g FN(is)i(raised.)208 3720 y(Note)f(that)g(normalization)e(of)i(ne)o(gati)n(v)o(e)e(v)n(alues)i (may)f(be)i(surprising)d(at)j(\002rst.)26 b(F)o(or)20 b(e)o(xample,)444 3944 y FA(>>>)44 b(d)h(=)f (timedelta\(microseconds=-1\))444 4035 y(>>>)g(\(d.days,)g(d.seconds,)f (d.microseconds\))444 4127 y(\(-1,)h(86399,)g(999999\))0 4330 y FN(Class)22 b(attrib)n(utes)e(are:)0 4477 y FD(min)208 4577 y FN(The)f(most)i(ne)o(gati)n(v)o(e)d FJ(timedelta)h FN(object,)g FJ(timedelta\(-999999999\))p FN(.)0 4723 y FD(max)208 4823 y FN(The)24 b(most)h(positi)n(v)o(e)f FJ(timedelta)g FN(object,)i FJ(timedelta\(days=999999999,)45 b(hours=23,)j(minutes=59,)208 4923 y(seconds=59,)f (microseconds=999999\))p FN(.)0 5070 y FD(resolution)208 5169 y FN(The)195 b(smallest)h(possible)f(dif)n(ference)e(between)i (non-equal)e FJ(timedelta)h FN(objects,)208 5269 y FJ (timedelta\(microseconds=1\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f (time)h(types)2139 b(97)p eop end %%Page: 98 110 TeXDict begin 98 109 bop 0 83 a FN(Note)27 b(that,)h(because)d(of)i (normalization,)e FJ(timedelta.max)g Ft(>)p FJ(-timedelta.min)p FN(.)42 b FJ(-timedelta.max)24 b FN(is)k(not)e(repre-)0 183 y(sentable)20 b(as)h(a)f FJ(timedelta)f FN(object.)0 330 y(Instance)g(attrib)n(utes)h(\(read-only\):)953 542 y FL(Attrib)n(ute)p 1465 571 4 100 v 232 w(V)-8 b(alue)p 769 575 2362 4 v 1018 644 a FJ(days)p 1465 674 4 100 v 298 w FN(Between)21 b(-999999999)16 b(and)j(999999999)e(inclusi)n(v)o (e)943 744 y FJ(seconds)p 1465 774 V 223 w FN(Between)k(0)f(and)f (86399)g(inclusi)n(v)o(e)819 844 y FJ(microseconds)p 1465 874 V 97 w FN(Between)i(0)f(and)f(999999)f(inclusi)n(v)o(e)0 1055 y(Supported)g(operations:)418 1348 y FL(Operation)p 1199 1378 V 467 w(Result)p 0 1381 4271 4 v 354 1451 a FK(t1)50 b FJ(=)f FK(t2)h FJ(+)f FK(t3)p 1199 1481 4 100 v 404 w FN(Sum)20 b(of)g FK(t2)g FN(and)g FK(t3)p FN(.)25 b(Afterw)o(ards)19 b FK(t1)p FN(-)p FK(t2)h FN(==)g FK(t3)h FN(and)e FK(t1)p FN(-)p FK(t3)h FN(==)g FK(t2)h FN(are)f(true.)k(\(1\))354 1551 y FK(t1)50 b FJ(=)f FK(t2)h FJ(-)f FK(t3)p 1199 1581 V 404 w FN(Dif)n(ference)19 b(of)g FK(t2)i FN(and)e FK(t3)p FN(.)26 b(Afterw)o(ards)19 b FK(t1)h FN(==)h FK(t2)f FN(-)g FK(t3)h FN(and)e FK(t2)i FN(==)f FK(t1)g FN(+)h FK(t3)f FN(are)h(true.)j(\(1\))50 1650 y FK(t1)49 b FJ(=)h FK(t2)378 1665 y FJ(*)478 1650 y FK(i)g FJ(or)f FK(t1)h FJ(=)f FK(i)987 1665 y FJ(*)1087 1650 y FK(t2)p 1199 1680 V 99 w FN(Delta)21 b(multiplied)e(by)g(an)i (inte)o(ger)e(or)h(long.)k(Afterw)o(ards)19 b FK(t1)h FN(//)h(i)g(==)g FK(t2)f FN(is)h(true,)f(pro)o(vided)d FJ(i)50 b(!=)f(0)p FN(.)p 1199 1780 V 1251 1750 a(In)20 b(general,)f FK(t1)h FN(*)g(i)h(==)g FK(t1)f FN(*)g(\(i-1\))f(+)i FK(t1)f FN(is)i(true.)i(\(1\))350 1850 y FK(t1)50 b FJ(=)f FK(t2)h FJ(//)f FK(i)p 1199 1879 V 400 w FN(The)20 b(\003oor)f(is)j (computed)c(and)h(the)i(remainder)d(\(if)i(an)o(y\))f(is)i(thro)n(wn)e (a)o(w)o(ay)-5 b(.)24 b(\(3\))543 1949 y FJ(+)p FK(t1)p 1199 1979 V 593 w FN(Returns)c(a)h FJ(timedelta)e FN(object)g(with)i (the)f(same)g(v)n(alue.)25 b(\(2\))543 2049 y FJ(-)p FK(t1)p 1199 2079 V 593 w FN(equi)n(v)n(alent)18 b(to)j FJ(timedelta)p FN(\(-)p FK(t1.days)p FN(,)16 b(-)p FK(t1.seconds)p FN(,)j(-)p FK(t1.micr)l(oseconds)p FN(\),)f(and)h(to)i FK(t1)p FN(*)f(-1.)k(\(1\)\(4\))464 2148 y FJ(abs\()p FK(t)q FJ(\))p 1199 2178 V 513 w FN(equi)n(v)n(alent)18 b(to)j(+)p FK(t)h FN(when)e FJ(t.days)48 b(>=)i(0)p FN(,)20 b(and)g(to)g(-)p FK(t)i FN(when)e FJ(t.days)48 b(<)i(0)p FN(.)25 b(\(2\))0 2358 y(Notes:)0 2574 y FL(\(1\))40 b FN(This)21 b(is)g(e)o(xact,)e(b)n(ut)h(may)g(o)o(v)o(er\003o)n(w)-5 b(.)0 2734 y FL(\(2\))40 b FN(This)21 b(is)g(e)o(xact,)e(and)h(cannot)f (o)o(v)o(er\003o)n(w)-5 b(.)0 2894 y FL(\(3\))40 b FN(Di)n(vision)20 b(by)g(0)g(raises)h FJ(ZeroDivisionError)p FN(.)0 3055 y FL(\(4\))40 b FN(-)p FK(timedelta.max)19 b FN(is)i(not)f (representable)e(as)j(a)g FJ(timedelta)e FN(object.)0 3270 y(In)j(addition)f(to)h(the)g(operations)f(listed)h(abo)o(v)o(e)f FJ(timedelta)g FN(objects)h(support)e(certain)i(additions)f(and)h (subtractions)e(with)j FJ(date)0 3370 y FN(and)d FJ(datetime)f FN(objects)h(\(see)g(belo)n(w\).)0 3517 y(Comparisons)25 b(of)h FJ(timedelta)f FN(objects)h(are)g(supported)e(with)i(the)g FJ(timedelta)f FN(object)h(representing)e(the)i(smaller)g(duration)0 3616 y(considered)i(to)j(be)f(the)g(smaller)g(timedelta.)55 b(In)30 b(order)f(to)h(stop)g(mix)o(ed-type)e(comparisons)g(from)h(f)o (alling)h(back)g(to)g(the)g(def)o(ault)0 3716 y(comparison)18 b(by)j(object)f(address,)f(when)h(a)h FJ(timedelta)f FN(object)g(is)h(compared)e(to)h(an)h(object)f(of)g(a)h(dif)n(ferent)e (type,)h FJ(TypeError)0 3816 y FN(is)h(raised)f(unless)g(the)h (comparison)d(is)j FJ(==)f FN(or)g FJ(!=)p FN(.)25 b(The)20 b(latter)h(cases)f(return)f FJ(False)h FN(or)g FJ(True)p FN(,)g(respecti)n(v)o(ely)-5 b(.)0 3963 y FJ(timedelta)23 b FN(objects)h(are)g(hashable)f(\(usable)h(as)h(dictionary)d(k)o(e)o (ys\),)i(support)f(ef)n(\002cient)h(pickling,)g(and)f(in)i(Boolean)e (conte)o(xts,)h(a)0 4062 y FJ(timedelta)19 b FN(object)h(is)h (considered)d(to)j(be)f(true)g(if)g(and)g(only)f(if)i(it)f(isn')o(t)g (equal)g(to)g FJ(timedelta\(0\))p FN(.)0 4345 y Fv(5.1.3)100 b Fm(date)27 b Fv(Objects)0 4547 y FN(A)33 b FJ(date)f FN(object)g(represents)f(a)i(date)f(\(year)m(,)i(month)d(and)g(day\))h (in)g(an)g(idealized)g(calendar)m(,)h(the)g(current)e(Gre)o(gorian)f (calendar)0 4647 y(inde\002nitely)20 b(e)o(xtended)g(in)i(both)e (directions.)28 b(January)20 b(1)i(of)f(year)g(1)h(is)g(called)f(day)g (number)f(1,)i(January)e(2)i(of)f(year)g(1)g(is)i(called)e(day)0 4747 y(number)e(2,)h(and)g(so)h(on.)26 b(This)21 b(matches)f(the)h (de\002nition)f(of)g(the)h(\224proleptic)e(Gre)o(gorian\224)f(calendar) h(in)i(Dersho)n(witz)f(and)g(Reingold')-5 b(s)0 4846 y(book)26 b FK(Calendrical)h(Calculations)p FN(,)h(where)f(it')-5 b(s)29 b(the)f(base)g(calendar)e(for)h(all)h(computations.)46 b(See)28 b(the)f(book)g(for)g(algorithms)f(for)0 4946 y(con)m(v)o(erting)17 b(between)j(proleptic)f(Gre)o(gorian)f(ordinals)h (and)h(man)o(y)f(other)g(calendar)g(systems.)0 5093 y FL(class)i FD(date)p FJ(\()p FK(year)-9 b(,)19 b(month,)g(day)p FJ(\))208 5192 y FN(All)h(ar)o(guments)f(are)h(required.)j(Ar)o (guments)18 b(may)i(be)g(ints)h(or)e(longs,)h(in)g(the)g(follo)n(wing)f (ranges:)349 5400 y FM(\017)o FJ(MINYEAR)49 b(<=)g FK(year)i FJ(<=)f(MAXYEAR)p 0 5549 3901 4 v 0 5649 a FI(98)2954 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 99 111 TeXDict begin 99 110 bop 349 83 a FM(\017)o FJ(1)50 b(<=)f FK(month)g FJ(<=)g(12)349 204 y FM(\017)o FJ(1)h(<=)f FK(day)g FJ(<=)g(number)g(of)h(days)f(in)g(the)g(given)g(month)g(and)g (year)208 406 y FN(If)20 b(an)g(ar)o(gument)e(outside)h(those)h(ranges) g(is)h(gi)n(v)o(en,)d FJ(ValueError)h FN(is)i(raised.)0 553 y(Other)f(constructors,)e(all)j(class)g(methods:)0 699 y FD(today)p FJ(\(\))208 799 y FN(Return)e(the)i(current)d(local)j (date.)j(This)d(is)g(equi)n(v)n(alent)d(to)j FJ (date.fromtimestamp\(time.time\(\)\))p FN(.)0 946 y FD(fromtimestamp)p FJ(\()p FK(timestamp)p FJ(\))208 1046 y FN(Return)d(the)i(local)f(date) g(corresponding)c(to)20 b(the)f(POSIX)h(timestamp,)e(such)h(as)h(is)g (returned)e(by)h FJ(time.time\(\))p FN(.)k(This)c(may)208 1145 y(raise)f FJ(ValueError)p FN(,)f(if)i(the)f(timestamp)g(is)i(out)e (of)g(the)g(range)f(of)h(v)n(alues)g(supported)f(by)h(the)g(platform)f (C)i FJ(localtime\(\))208 1245 y FN(function.)28 b(It')-5 b(s)23 b(common)d(for)h(this)i(to)f(be)g(restricted)f(to)h(years)g (from)f(1970)f(through)g(2038.)29 b(Note)22 b(that)g(on)g(non-POSIX)e (sys-)208 1344 y(tems)15 b(that)h(include)e(leap)i(seconds)e(in)i (their)f(notion)f(of)h(a)h(timestamp,)g(leap)f(seconds)g(are)g(ignored) f(by)h FJ(fromtimestamp\(\))p FN(.)0 1491 y FD(fromordinal)p FJ(\()p FK(or)m(dinal)p FJ(\))208 1591 y FN(Return)40 b(the)h(date)g(corresponding)d(to)j(the)g(proleptic)f(Gre)o(gorian)f (ordinal,)45 b(where)40 b(January)g(1)h(of)g(year)f(1)h(has)h(ordi-)208 1691 y(nal)35 b(1.)70 b FJ(ValueError)33 b FN(is)k(raised)e(unless)g FJ(1)49 b(<=)h FK(or)m(dinal)e FJ(<=)i(date.max.toordinal\(\))p FN(.)66 b(F)o(or)35 b(an)o(y)f(date)h FK(d)r FN(,)208 1790 y FJ(date.fromordinal\()p FK(d)r FJ(.toordinal\(\)\))44 b(==)49 b FK(d)r FN(.)0 1937 y(Class)22 b(attrib)n(utes:)0 2084 y FD(min)208 2184 y FN(The)d(earliest)i(representable)d(date,)i FJ(date\(MINYEAR,)47 b(1,)j(1\))p FN(.)0 2330 y FD(max)208 2430 y FN(The)19 b(latest)i(representable)e(date,)h FJ(date\(MAXYEAR,) 47 b(12,)i(31\))p FN(.)0 2577 y FD(resolution)208 2677 y FN(The)19 b(smallest)i(possible)f(dif)n(ference)e(between)i (non-equal)e(date)i(objects,)f FJ(timedelta\(days=1\))p FN(.)0 2823 y(Instance)g(attrib)n(utes)h(\(read-only\):)0 2970 y FD(year)208 3070 y FN(Between)g FJ(MINYEAR)f FN(and)h FJ(MAXYEAR)f FN(inclusi)n(v)o(e.)0 3217 y FD(month)208 3316 y FN(Between)h(1)g(and)g(12)f(inclusi)n(v)o(e.)0 3463 y FD(day)208 3563 y FN(Between)h(1)g(and)g(the)g(number)e(of)i (days)g(in)g(the)h(gi)n(v)o(en)e(month)g(of)g(the)i(gi)n(v)o(en)e(year) -5 b(.)0 3710 y(Supported)18 b(operations:)481 3907 y FL(Operation)p 1200 3937 4 100 v 404 w(Result)p 125 3940 3651 4 v 175 4010 a FK(date2)48 b FJ(=)h FK(date1)g FJ(+)g FK(timedelta)p 1200 4040 4 100 v 99 w(date2)19 b FN(is)i FK(timedelta)p FJ(.days)e FN(days)h(remo)o(v)o(ed)e(from)h FK(date1)p FN(.)24 b(\(1\))175 4109 y FK(date2)48 b FJ(=)h FK(date1)g FJ(-)g FK(timedelta)p 1200 4139 V 99 w FN(Computes)19 b FK(date2)h FN(such)g(that)g FK(date2)48 b FJ(+)i FK(timedelta)f FJ(==)g FK(date1)p FN(.)24 b(\(2\))175 4209 y FK(timedelta)48 b FJ(=)i FK(date1)e FJ(-)i FK(date2)p 1200 4239 V 98 w FN(\(3\))404 4309 y FK(date1)e FJ(<)i FK(date2)p 1200 4338 V 327 w(date1)19 b FN(is)i(considered)e(less)i(than)f FK(date2)f FN(when)h FK(date1)f FN(precedes)g FK(date2)g FN(in)i(time.)k(\(4\))0 4503 y(Notes:)0 4693 y FL(\(1\))40 b FK(date2)32 b FN(is)i(mo)o(v)o(ed)d(forw)o(ard)g(in)j(time)f(if)g FK(timedelta)p FJ(.days)48 b(>)h(0)p FN(,)37 b(or)32 b(backw)o(ard)g(if)h FK(timedelta)p FJ(.days)48 b(<)h(0)p FN(.)64 b(Afterw)o(ard)208 4793 y FK(date2)48 b FJ(-)h FK(date1)g FJ(==)g FK(timedelta)p FJ(.days)p FN(.)78 b FK(timedelta)p FJ(.seconds)37 b FN(and)h FK(timedelta)p FJ(.microseconds)d FN(are)k(ignored.)208 4892 y FJ(OverflowError)18 b FN(is)j(raised)f(if)h FK(date2)p FJ(.year)d FN(w)o(ould)h(be)h (smaller)h(than)e FJ(MINYEAR)h FN(or)g(lar)o(ger)f(than)g FJ(MAXYEAR)p FN(.)0 5046 y FL(\(2\))40 b FN(This)28 b(isn')o(t)g(quite) g(equi)n(v)n(alent)e(to)i(date1)f(+)i(\(-timedelta\),)f(because)f (-timedelta)g(in)h(isolation)g(can)f(o)o(v)o(er\003o)n(w)f(in)j(cases)f (where)208 5146 y(date1)19 b(-)i(timedelta)e(does)h(not.)25 b FK(timedelta)p FJ(.seconds)18 b FN(and)i FK(timedelta)p FJ(.microseconds)d FN(are)j(ignored.)0 5300 y FL(\(3\))40 b FN(This)20 b(is)g(e)o(xact,)f(and)g(cannot)f(o)o(v)o(er\003o)n(w)-5 b(.)23 b(timedelta.seconds)17 b(and)i(timedelta.microseconds)d(are)k (0,)f(and)g(date2)g(+)g(timedelta)g(==)208 5400 y(date1)g(after)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2139 b(99)p eop end %%Page: 100 112 TeXDict begin 100 111 bop 0 83 a FL(\(4\))40 b FN(In)28 b(other)e(w)o(ords,)j FJ(date1)49 b(<)h(date2)27 b FN(if)h(and)f(only)g (if)h FK(date1)p FJ(.toordinal\(\))46 b(<)j FK(date2)p FJ(.toordinal\(\))p FN(.)44 b(In)28 b(order)208 183 y(to)g(stop)g (comparison)e(from)h(f)o(alling)g(back)h(to)g(the)g(def)o(ault)f (scheme)h(of)g(comparing)e(object)h(addresses,)j(date)e(comparison)208 282 y(normally)20 b(raises)k FJ(TypeError)d FN(if)i(the)f(other)g (comparand)e(isn')o(t)i(also)h(a)g FJ(date)f FN(object.)32 b(Ho)n(we)n(v)o(er)m(,)21 b FJ(NotImplemented)208 382 y FN(is)28 b(returned)e(instead)h(if)h(the)g(other)e(comparand)f(has)j (a)g FJ(timetuple)f FN(attrib)n(ute.)47 b(This)27 b(hook)f(gi)n(v)o(es) i(other)e(kinds)h(of)h(date)208 482 y(objects)19 b(a)i(chance)e(at)h (implementing)e(mix)o(ed-type)f(comparison.)23 b(If)d(not,)f(when)h(a)g FJ(date)g FN(object)f(is)i(compared)d(to)i(an)g(object)208 581 y(of)g(a)h(dif)n(ferent)d(type,)i FJ(TypeError)f FN(is)j(raised)e(unless)h(the)f(comparison)f(is)i FJ(==)g FN(or)f FJ(!=)p FN(.)26 b(The)20 b(latter)g(cases)i(return)d FJ(False)h FN(or)208 681 y FJ(True)p FN(,)f(respecti)n(v)o(ely)-5 b(.)0 894 y(Dates)21 b(can)f(be)g(used)g(as)h(dictionary)d(k)o(e)o(ys.) 25 b(In)20 b(Boolean)f(conte)o(xts,)g(all)i FJ(date)f FN(objects)g(are)g(considered)e(to)j(be)f(true.)0 1041 y(Instance)f(methods:)0 1188 y FD(replace)p FJ(\()p FK(year)-9 b(,)18 b(month,)h(day)p FJ(\))208 1287 y FN(Return)31 b(a)h(date)f(with)h(the)g(same)g(v)n(alue,)h(e)o(xcept)e(for)g(those)g (members)g(gi)n(v)o(en)f(ne)n(w)i(v)n(alues)f(by)g(whiche)n(v)o(er)f(k) o(e)o(yw)o(ord)g(ar)n(-)208 1387 y(guments)24 b(are)h(speci\002ed.)39 b(F)o(or)25 b(e)o(xample,)f(if)i FJ(d)49 b(==)h(date\(2002,)e(12,)h (31\))p FN(,)26 b(then)f FJ(d.replace\(day=26\))46 b(==)208 1487 y(date\(2002,)i(12,)h(26\))p FN(.)0 1634 y FD(timetuple)p FJ(\(\))208 1733 y FN(Return)19 b(a)i FJ(time.struct_time)d FN(such)i(as)g(returned)f(by)h FJ(time.localtime\(\))p FN(.)i(The)e(hours,)f(minutes)h(and)f(seconds)208 1833 y(are)40 b(0,)45 b(and)39 b(the)h(DST)h(\003ag)f(is)h(-1.)85 b FK(d)r FJ(.timetuple\(\))38 b FN(is)j(equi)n(v)n(alent)d(to)j FJ(time.struct_time\(\()p FK(d)r FJ(.year,)208 1932 y FK(d)r FJ(.month,)48 b FK(d)r FJ(.day,)g(0,)i(0,)f(0,)h FK(d)r FJ(.weekday\(\),)d FK(d)r FJ(.toordinal\(\))h(-)h(date\()p FK(d)r FJ(.year,)f(1,)208 2032 y(1\).toordinal\(\))f(+)i(1,)h(-1\)\))0 2179 y FD(toordinal)p FJ(\(\))208 2279 y FN(Return)17 b(the)g(proleptic)g(Gre)o(gorian)e(ordinal)h(of)i(the)f(date,)h(where)f (January)g(1)g(of)h(year)f(1)g(has)h(ordinal)e(1.)25 b(F)o(or)17 b(an)o(y)g FJ(date)g FN(object)208 2378 y FK(d)r FN(,)j FJ(date.fromordinal\()p FK(d)r FJ(.toordinal\(\)\))44 b(==)49 b FK(d)r FN(.)0 2525 y FD(weekday)p FJ(\(\))208 2625 y FN(Return)25 b(the)i(day)e(of)h(the)g(week)g(as)h(an)g(inte)o (ger)m(,)f(where)f(Monday)g(is)i(0)f(and)g(Sunday)f(is)i(6.)43 b(F)o(or)26 b(e)o(xample,)g FJ(date\(2002,)208 2724 y(12,)49 b(4\).weekday\(\))e(==)j(2)p FN(,)20 b(a)h(W)-7 b(ednesday)i(.)24 b(See)c(also)h FJ(isoweekday\(\))p FN(.)0 2871 y FD(isoweekday)p FJ(\(\))208 2971 y FN(Return)k(the)i(day)e(of)h(the)g(week)g(as)h(an)g (inte)o(ger)m(,)f(where)f(Monday)g(is)i(1)f(and)g(Sunday)f(is)i(7.)43 b(F)o(or)26 b(e)o(xample,)g FJ(date\(2002,)208 3070 y(12,)49 b(4\).isoweekday\(\))e(==)i(3)p FN(,)21 b(a)f(W)-7 b(ednesday)i(.)24 b(See)d(also)f FJ(weekday\(\))p FN(,)f FJ(isocalendar\(\))p FN(.)0 3217 y FD(isocalendar)p FJ(\(\))208 3317 y FN(Return)g(a)i (3-tuple,)e(\(ISO)h(year)m(,)f(ISO)h(week)g(number)m(,)e(ISO)j (weekday\).)208 3450 y(The)110 b(ISO)i(calendar)d(is)j(a)g(widely)f (used)f(v)n(ariant)g(of)h(the)g(Gre)o(gorian)e(calendar)-5 b(.)297 b(See)208 3549 y FO(http://www)l(.ph)n(ys)o(.uu.nl/)14 b(vgent/calendar/isocalenda)o(r)l(.htm)h FN(for)k(a)i(good)e(e)o (xplanation.)208 3682 y(The)g(ISO)i(year)f(consists)g(of)g(52)g(or)g (53)g(full)g(weeks,)g(and)g(where)g(a)g(week)g(starts)h(on)f(a)h (Monday)d(and)i(ends)g(on)g(a)h(Sunday)-5 b(.)23 b(The)208 3782 y(\002rst)g(week)e(of)h(an)h(ISO)f(year)g(is)h(the)f(\002rst)h (\(Gre)o(gorian\))c(calendar)i(week)h(of)g(a)h(year)f(containing)e(a)i (Thursday)-5 b(.)29 b(This)23 b(is)g(called)208 3881 y(week)c(number)g(1,)h(and)g(the)g(ISO)g(year)g(of)g(that)g(Thursday)e (is)k(the)e(same)g(as)h(its)g(Gre)o(gorian)d(year)-5 b(.)208 4014 y(F)o(or)23 b(e)o(xample,)f(2004)g(be)o(gins)h(on)g(a)h (Thursday)-5 b(,)21 b(so)j(the)g(\002rst)g(week)f(of)g(ISO)h(year)f (2004)f(be)o(gins)g(on)h(Monday)-5 b(,)22 b(29)h(Dec)h(2003)208 4114 y(and)30 b(ends)i(on)f(Sunday)-5 b(,)32 b(4)g(Jan)f(2004,)i(so)f (that)f FJ(date\(2003,)48 b(12,)i(29\).isocalendar\(\))c(==)k(\(2004,)e (1,)208 4214 y(1\))20 b FN(and)g FJ(date\(2004,)48 b(1,)h (4\).isocalendar\(\))e(==)i(\(2004,)g(1,)g(7\))p FN(.)0 4360 y FD(isoformat)p FJ(\(\))208 4460 y FN(Return)17 b(a)i(string)e(representing)f(the)i(date)g(in)g(ISO)h(8601)d(format,)h ('YYYY)-9 b(-MM-DD'.)16 b(F)o(or)i(e)o(xample,)f FJ(date\(2002,)48 b(12,)208 4560 y(4\).isoformat\(\))f(==)i('2002-12-04')p FN(.)0 4707 y FD(__str__)p FJ(\(\))208 4806 y FN(F)o(or)19 b(a)i(date)f FK(d)r FN(,)g FJ(str\()p FK(d)r FJ(\))g FN(is)h(equi)n(v)n(alent)e(to)h FK(d)r FJ(.isoformat\(\))p FN(.)0 4953 y FD(ctime)p FJ(\(\))208 5053 y FN(Return)26 b(a)i(string)f(representing)e(the)i(date,)i(for)e(e)o(xample)f (date\(2002,)g(12,)i(4\).ctime\(\))e(==)h('W)-7 b(ed)28 b(Dec)f(4)h(00:00:00)d(2002'.)208 5152 y FK(d)r FJ(.ctime\(\))d FN(is)j(equi)n(v)n(alent)d(to)j FJ(time.ctime\(time.mktime\()p FK(d)r FJ(.timetupl)o(e\(\)\)\))18 b FN(on)23 b(platforms)g(where)h (the)208 5252 y(nati)n(v)o(e)f(C)i FJ(ctime\(\))f FN(function)e (\(which)i FJ(time.ctime\(\))e FN(in)m(v)n(ok)o(es,)i(b)n(ut)h(which)f FJ(date.ctime\(\))e FN(does)i(not)g(in)m(v)n(ok)o(e\))208 5352 y(conforms)18 b(to)i(the)g(C)i(standard.)p 0 5549 3901 4 v 0 5649 a FI(100)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 101 113 TeXDict begin 101 112 bop 0 83 a FD(strftime)p FJ(\()p FK(format)q FJ(\))208 183 y FN(Return)23 b(a)h(string)g(representing)e (the)i(date,)g(controlled)e(by)i(an)g(e)o(xplicit)f(format)g(string.)35 b(F)o(ormat)23 b(codes)h(referring)e(to)i(hours,)208 282 y(minutes)19 b(or)h(seconds)g(will)h(see)f(0)h(v)n(alues.)j(See)d (section)f(5.1.7)f(\226)h FJ(strftime\(\))f FN(beha)n(vior)-5 b(.)0 567 y Fv(5.1.4)100 b Fm(datetime)26 b Fv(Objects)0 770 y FN(A)f FJ(datetime)e FN(object)h(is)h(a)g(single)f(object)g (containing)f(all)i(the)f(information)e(from)h(a)i FJ(date)f FN(object)g(and)g(a)h FJ(time)f FN(object.)37 b(Lik)o(e)0 869 y(a)26 b FJ(date)f FN(object,)h FJ(datetime)e FN(assumes)i(the)f (current)f(Gre)o(gorian)g(calendar)g(e)o(xtended)f(in)j(both)e (directions;)j(lik)o(e)f(a)g(time)f(object,)0 969 y FJ(datetime)19 b FN(assumes)i(there)e(are)i(e)o(xactly)e(3600*24)e(seconds)j(in)g(e)n (v)o(ery)f(day)-5 b(.)0 1116 y(Constructor:)0 1262 y FL(class)21 b FD(datetime)p FJ(\()p FK(year)-9 b(,)18 b(month,)h(day)p FC([)p FK(,)g(hour)r FC([)p FK(,)g(minute)p FC([)p FK(,)h(second)r FC([)p FK(,)f(micr)l(osecond)r FC([)p FK(,)g(tzinfo)12 b FC(])g(])g(])g(])g(])p FJ(\))208 1362 y FN(The)23 b(year)m(,)h(month)f(and)h(day)g(ar)o(guments)e(are)i (required.)35 b FK(tzinfo)24 b FN(may)g(be)g FJ(None)p FN(,)h(or)f(an)g(instance)f(of)h(a)h FJ(tzinfo)f FN(subclass.)208 1462 y(The)19 b(remaining)g(ar)o(guments)f(may)i(be)g(ints)h(or)e (longs,)h(in)g(the)g(follo)n(wing)f(ranges:)349 1674 y FM(\017)o FJ(MINYEAR)49 b(<=)g FK(year)i FJ(<=)f(MAXYEAR)349 1805 y FM(\017)o FJ(1)g(<=)f FK(month)g FJ(<=)g(12)349 1937 y FM(\017)o FJ(1)h(<=)f FK(day)g FJ(<=)g(number)g(of)h(days)f(in)g (the)g(given)g(month)g(and)g(year)349 2068 y FM(\017)o FJ(0)h(<=)f FK(hour)i FJ(<)e(24)349 2200 y FM(\017)o FJ(0)h(<=)f FK(minute)g FJ(<)h(60)349 2331 y FM(\017)o FJ(0)g(<=)f FK(second)i FJ(<)f(60)349 2463 y FM(\017)o FJ(0)g(<=)f FK(micr)l(osecond)i FJ(<)e(1000000)208 2675 y FN(If)20 b(an)g(ar)o(gument)e(outside)h(those)h(ranges)g(is)h(gi)n(v) o(en,)d FJ(ValueError)h FN(is)i(raised.)0 2822 y(Other)f(constructors,) e(all)j(class)g(methods:)0 2969 y FD(today)p FJ(\(\))208 3068 y FN(Return)106 b(the)i(current)d(local)j(datetime,)128 b(with)107 b FJ(tzinfo)g(None)p FN(.)285 b(This)108 b(is)g(equi)n(v)n (alent)d(to)208 3168 y FJ(datetime.fromtimestamp\(time.time\()o(\)\))p FN(.)20 b(See)g(also)h FJ(now\(\))p FN(,)e FJ(fromtimestamp\(\))p FN(.)0 3315 y FD(now)p FJ(\()p FC([)p FK(tz)12 b FC(])p FJ(\))208 3415 y FN(Return)21 b(the)h(current)e(local)i(date)f(and)h (time.)29 b(If)22 b(optional)f(ar)o(gument)e FK(tz)k FN(is)f FJ(None)g FN(or)f(not)h(speci\002ed,)g(this)g(is)h(lik)o(e)f FJ(today\(\))p FN(,)208 3514 y(b)n(ut,)k(if)g(possible,)g(supplies)f (more)g(precision)f(than)h(can)g(be)h(gotten)e(from)h(going)f(through)f (a)j FJ(time.time\(\))e FN(timestamp)208 3614 y(\(for)19 b(e)o(xample,)f(this)j(may)f(be)g(possible)g(on)g(platforms)f (supplying)f(the)i(C)h FJ(gettimeofday\(\))d FN(function\).)208 3746 y(Else)101 b FK(tz)h FN(must)g(be)f(an)g(instance)g(of)g(a)h (class)g FJ(tzinfo)e FN(subclass,)122 b(and)101 b(the)g(current)f(date) 208 3846 y(and)84 b(time)h(are)h(con)m(v)o(erted)c(to)j FK(tz)p FN(')-5 b(s)87 b(time)e(zone.)219 b(In)85 b(this)h(case)g(the)f (result)g(is)h(equi)n(v)n(alent)d(to)208 3945 y FK(tz)p FJ(.fromutc\(datetime.utcnow\(\).replace\()o(tzinf)o(o=)p FK(tz)p FJ(\)\))p FN(.)20 b(See)g(also)h FJ(today\(\))p FN(,)e FJ(utcnow\(\))p FN(.)0 4092 y FD(utcnow)p FJ(\(\))208 4192 y FN(Return)j(the)h(current)f(UTC)i(date)e(and)h(time,)h(with)f FJ(tzinfo)f(None)p FN(.)33 b(This)24 b(is)g(lik)o(e)f FJ(now\(\))p FN(,)g(b)n(ut)g(returns)f(the)h(current)f(UTC)208 4291 y(date)e(and)f(time,)h(as)h(a)g(nai)n(v)o(e)e FJ(datetime)g FN(object.)25 b(See)20 b(also)h FJ(now\(\))p FN(.)0 4438 y FD(fromtimestamp)p FJ(\()p FK(timestamp)p FC([)p FK(,)c(tz)12 b FC(])p FJ(\))208 4538 y FN(Return)20 b(the)h(local)g(date)g(and)f (time)i(corresponding)17 b(to)k(the)g(POSIX)h(timestamp,)e(such)h(as)h (is)g(returned)d(by)h FJ(time.time\(\))p FN(.)208 4637 y(If)26 b(optional)g(ar)o(gument)f FK(tz)j FN(is)g FJ(None)f FN(or)g(not)f(speci\002ed,)j(the)e(timestamp)f(is)i(con)m(v)o(erted)d (to)i(the)g(platform')-5 b(s)26 b(local)h(date)g(and)208 4737 y(time,)20 b(and)f(the)i(returned)d FJ(datetime)h FN(object)h(is)h(nai)n(v)o(e.)208 4869 y(Else)122 b FK(tz)g FN(must)f(be)h(an)f(instance)g(of)g(a)h(class)g FJ(tzinfo)f FN(subclass,)147 b(and)121 b(the)g(times-)208 4969 y(tamp)99 b(is)i(con)m(v)o(erted)c(to)j FK(tz)p FN(')-5 b(s)101 b(time)e(zone.)263 b(In)100 b(this)g(case)g(the)g(result)g(is)g(equi)n (v)n(alent)e(to)208 5069 y FK(tz)p FJ (.fromutc\(datetime.utcfromtimestamp\()o FK(timestamp)p FJ(\).)o(repla)o(ce\(tz)o(info=)p FK(tz)p FJ(\)\))p FN(.)208 5201 y FJ(fromtimestamp\(\))25 b FN(may)i(raise)h FJ(ValueError)p FN(,)f(if)h(the)g(timestamp)f(is)h(out)f(of)g(the)h(range)e(of)h(v)n (alues)h(supported)d(by)208 5300 y(the)20 b(platform)g(C)h FJ(localtime\(\))f FN(or)g FJ(gmtime\(\))g FN(functions.)25 b(It')-5 b(s)21 b(common)e(for)h(this)i(to)f(be)f(restricted)h(to)g (years)f(in)h(1970)208 5400 y(through)f(2038.)33 b(Note)23 b(that)g(on)g(non-POSIX)e(systems)j(that)f(include)f(leap)h(seconds)f (in)i(their)e(notion)g(of)h(a)h(timestamp,)f(leap)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2093 b(101)p eop end %%Page: 102 114 TeXDict begin 102 113 bop 208 83 a FN(seconds)29 b(are)h(ignored)e(by)h FJ(fromtimestamp\(\))p FN(,)h(and)f(then)g(it')-5 b(s)31 b(possible)f(to)g(ha)n(v)o(e)f(tw)o(o)h(timestamps)g(dif)n(fering)e(by) h(a)208 183 y(second)19 b(that)h(yield)g(identical)g FJ(datetime)f FN(objects.)25 b(See)20 b(also)h FJ(utcfromtimestamp\(\)) p FN(.)0 330 y FD(utcfromtimestamp)p FJ(\()p FK(timestamp)p FJ(\))208 429 y FN(Return)28 b(the)h(UTC)h FJ(datetime)e FN(corresponding)d(to)30 b(the)f(POSIX)g(timestamp,)i(with)e FJ(tzinfo)f(None)p FN(.)52 b(This)29 b(may)f(raise)208 529 y FJ(ValueError)p FN(,)17 b(if)i(the)g(timestamp)g(is)g(out)g(of)f (the)h(range)f(of)h(v)n(alues)f(supported)f(by)i(the)f(platform)g(C)i FJ(gmtime\(\))e FN(function.)208 628 y(It')-5 b(s)20 b(common)f(for)g(this)i(to)f(be)g(restricted)g(to)h(years)e(in)i(1970)e (through)f(2038.)23 b(See)e(also)f FJ(fromtimestamp\(\))p FN(.)0 775 y FD(fromordinal)p FJ(\()p FK(or)m(dinal)p FJ(\))208 875 y FN(Return)15 b(the)g FJ(datetime)g FN(corresponding)d (to)k(the)f(proleptic)f(Gre)o(gorian)g(ordinal,)h(where)g(January)f(1)i (of)f(year)g(1)h(has)f(ordinal)g(1.)208 975 y FJ(ValueError)21 b FN(is)i(raised)f(unless)g FJ(1)50 b(<=)f(ordinal)g(<=)g (datetime.max.toordinal\(\))p FN(.)28 b(The)22 b(hour)m(,)f(minute,)208 1074 y(second)e(and)g(microsecond)f(of)i(the)h(result)f(are)g(all)h(0,) f(and)f FJ(tzinfo)h FN(is)h FJ(None)p FN(.)0 1221 y FD(combine)p FJ(\()p FK(date)o(,)d(time)p FJ(\))208 1321 y FN(Return)36 b(a)h(ne)n(w)f FJ(datetime)g FN(object)g(whose)g(date)h(members)e(are)i (equal)f(to)g(the)h(gi)n(v)o(en)e FJ(date)i FN(object')-5 b(s,)40 b(and)c(whose)208 1420 y(time)g(and)f FJ(tzinfo)g FN(members)g(are)h(equal)f(to)h(the)g(gi)n(v)o(en)f FJ(time)g FN(object')-5 b(s.)72 b(F)o(or)36 b(an)o(y)f FJ(datetime)g FN(object)g FK(d)r FN(,)40 b FK(d)51 b FJ(==)208 1520 y(datetime.combine\()p FK(d)r FJ(.date\(\),)44 b FK(d)r FJ(.timetz\(\)\))p FN(.)30 b(If)22 b(date)g(is)i(a)e FJ(datetime)g FN(object,)g(its)h(time)f(and)g FJ(tzinfo)208 1620 y FN(members)d(are)h(ignored.)0 1766 y FD(strptime)p FJ(\()p FK(date)p 599 1766 25 4 v 27 w(string)o(,)h(format)q FJ(\))208 1866 y FN(Return)43 b(a)i FJ(datetime)f FN(corresponding)c (to)45 b FK(date)p 1782 1866 V 29 w(string)p FN(,)50 b(parsed)44 b(according)e(to)i FK(format)q FN(.)98 b(This)45 b(is)g(equi)n(v)n(alent)d(to)208 1966 y FJ(datetime\()658 1981 y(*)708 1966 y(\(time.strptime\(date_str)o(ing,)h (format\)[0:6]\)\))p FN(.)53 b FJ(ValueError)28 b FN(is)j(raised)f(if)h (the)208 2065 y(date)p 352 2065 V 29 w(string)20 b(and)f(format)g(can') o(t)g(be)h(parsed)g(by)g FJ(time.strptime\(\))d FN(or)j(if)h(it)g (returns)e(a)h(v)n(alue)g(which)g(isn')o(t)f(a)i(time)f(tuple.)208 2198 y(Ne)n(w)g(in)g(v)o(ersion)f(2.5.)0 2345 y(Class)j(attrib)n(utes:) 0 2492 y FD(min)208 2591 y FN(The)d(earliest)i(representable)d FJ(datetime)p FN(,)h FJ(datetime\(MINYEAR,)47 b(1,)i(1,)h (tzinfo=None\))p FN(.)0 2738 y FD(max)208 2838 y FN(The)67 b(latest)h(representable)e FJ(datetime)p FN(,)78 b FJ (datetime\(MAXYEAR,)47 b(12,)i(31,)h(23,)f(59,)g(59,)g(999999,)208 2938 y(tzinfo=None\))p FN(.)0 3084 y FD(resolution)208 3184 y FN(The)18 b(smallest)i(possible)e(dif)n(ference)f(between)h (non-equal)e FJ(datetime)i FN(objects,)h FJ (timedelta\(microseconds=1\))p FN(.)0 3331 y(Instance)g(attrib)n(utes)h (\(read-only\):)0 3478 y FD(year)208 3577 y FN(Between)g FJ(MINYEAR)f FN(and)h FJ(MAXYEAR)f FN(inclusi)n(v)o(e.)0 3724 y FD(month)208 3824 y FN(Between)h(1)g(and)g(12)f(inclusi)n(v)o (e.)0 3971 y FD(day)208 4070 y FN(Between)h(1)g(and)g(the)g(number)e (of)i(days)g(in)g(the)h(gi)n(v)o(en)e(month)g(of)g(the)i(gi)n(v)o(en)e (year)-5 b(.)0 4217 y FD(hour)208 4317 y FN(In)19 b FJ(range\(24\))p FN(.)0 4464 y FD(minute)208 4563 y FN(In)g FJ(range\(60\))p FN(.)0 4710 y FD(second)208 4810 y FN(In)g FJ(range\(60\))p FN(.)0 4957 y FD(microsecond)208 5056 y FN(In)g FJ(range\(1000000\))p FN(.)0 5203 y FD(tzinfo)208 5303 y FN(The)g(object)h(passed)g(as)h(the) f FK(tzinfo)h FN(ar)o(gument)c(to)k(the)f FJ(datetime)f FN(constructor)m(,)f(or)i FJ(None)g FN(if)g(none)f(w)o(as)j(passed.)p 0 5549 3901 4 v 0 5649 a FI(102)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 103 115 TeXDict begin 103 114 bop 0 83 a FN(Supported)18 b(operations:)1016 309 y FL(Operation)p 1878 339 4 100 v 547 w(Result)p 517 343 2866 4 v 567 412 a FK(datetime2)48 b FJ(=)i FK(datetime1)e FJ(+)i FK(timedelta)p 1878 442 4 100 v 98 w FN(\(1\))567 512 y FK(datetime2)e FJ(=)i FK(datetime1)e FJ(-)i FK(timedelta)p 1878 542 V 98 w FN(\(2\))567 612 y FK(timedelta)f FJ(=)g FK(datetime1)g FJ(-)g FK(datetime2)p 1878 641 V 98 w FN(\(3\))796 711 y FK(datetime1)f FJ(<)i FK(datetime2)p 1878 741 V 327 w FN(Compares)20 b FJ(datetime)f FN(to)h FJ(datetime)p FN(.)k(\(4\))0 937 y FL(\(1\))40 b FN(datetime2)21 b(is)i(a)g(duration)d(of)i(timedelta)g(remo)o(v)o(ed)d(from)i (datetime1,)h(mo)o(ving)e(forw)o(ard)g(in)j(time)f(if)g FK(timedelta)p FJ(.days)f FN(\277)h(0,)h(or)208 1036 y(backw)o(ard)15 b(if)j FK(timedelta)p FJ(.days)d FN(\241)j(0.)24 b(The)17 b(result)g(has)g(the)h(same)f FJ(tzinfo)g FN(member)e(as)j (the)f(input)g(datetime,)g(and)g(datetime2)208 1136 y(-)j(datetime1)g (==)h(timedelta)f(after)-5 b(.)26 b FJ(OverflowError)19 b FN(is)j(raised)e(if)h(datetime2.year)d(w)o(ould)i(be)h(smaller)f (than)g FJ(MINYEAR)208 1236 y FN(or)f(lar)o(ger)g(than)h FJ(MAXYEAR)p FN(.)f(Note)h(that)h(no)e(time)i(zone)e(adjustments)h(are) g(done)f(e)n(v)o(en)g(if)i(the)f(input)f(is)i(an)g(a)o(w)o(are)e (object.)0 1402 y FL(\(2\))40 b FN(Computes)24 b(the)h(datetime2)f (such)g(that)h(datetime2)e(+)i(timedelta)g(==)f(datetime1.)38 b(As)25 b(for)f(addition,)g(the)h(result)g(has)g(the)f(same)208 1501 y FJ(tzinfo)c FN(member)f(as)j(the)e(input)g(datetime,)g(and)h(no) f(time)h(zone)f(adjustments)g(are)g(done)g(e)n(v)o(en)g(if)h(the)g (input)f(is)h(a)o(w)o(are.)26 b(This)208 1601 y(isn')o(t)e(quite)h (equi)n(v)n(alent)f(to)h(datetime1)g(+)g(\(-timedelta\),)g(because)g (-timedelta)f(in)h(isolation)g(can)g(o)o(v)o(er\003o)n(w)f(in)h(cases)h (where)208 1701 y(datetime1)19 b(-)h(timedelta)g(does)g(not.)0 1867 y FL(\(3\))40 b FN(Subtraction)22 b(of)g(a)i FJ(datetime)e FN(from)g(a)h FJ(datetime)f FN(is)i(de\002ned)e(only)g(if)h(both)g (operands)e(are)i(nai)n(v)o(e,)f(or)h(if)g(both)f(are)h(a)o(w)o(are.) 208 1966 y(If)d(one)f(is)i(a)o(w)o(are)f(and)g(the)g(other)f(is)j(nai)n (v)o(e,)d FJ(TypeError)g FN(is)i(raised.)208 2099 y(If)j(both)h(are)f (nai)n(v)o(e,)h(or)g(both)f(are)h(a)o(w)o(are)g(and)f(ha)n(v)o(e)h(the) g(same)g FJ(tzinfo)f FN(member)m(,)g(the)h FJ(tzinfo)g FN(members)f(are)h(ignored,)208 2199 y(and)17 b(the)i(result)f(is)h(a)g FJ(timedelta)e FN(object)h FK(t)i FN(such)e(that)h FK(datetime2)48 b FJ(+)i FK(t)h FJ(==)e FK(datetime1)p FN(.)24 b(No)18 b(time)g(zone)g(adjustments)g(are)208 2298 y(done)h(in)h(this)h(case.) 208 2431 y(If)43 b(both)f(are)i(a)o(w)o(are)f(and)f(ha)n(v)o(e)h(dif)n (ferent)f FJ(tzinfo)g FN(members,)48 b FJ(a-b)c FN(acts)g(as)g(if)f FK(a)h FN(and)f FK(b)g FN(were)g(\002rst)h(con)m(v)o(erted)208 2531 y(to)c(nai)n(v)o(e)f(UTC)i(datetimes)g(\002rst.)86 b(The)40 b(result)g(is)h FJ(\()p FK(a)p FJ(.replace\(tzinfo=None\))46 b(-)j FK(a)p FJ(.utcoffset\(\)\))e(-)208 2630 y(\()p FK(b)p FJ(.replace\(tzinfo=None\))e(-)k FK(b)p FJ(.utcoffset\(\)\))18 b FN(e)o(xcept)h(that)i(the)f(implementation)e(ne)n(v)o(er)h(o)o(v)o (er\003o)n(ws.)0 2796 y FL(\(4\))40 b FK(datetime1)20 b FN(is)h(considered)d(less)j(than)f FK(datetime2)f FN(when)h FK(datetime1)f FN(precedes)g FK(datetime2)g FN(in)i(time.)208 2929 y(If)k(one)g(comparand)e(is)j(nai)n(v)o(e)f(and)g(the)g(other)g (is)h(a)o(w)o(are,)h FJ(TypeError)d FN(is)i(raised.)41 b(If)26 b(both)e(comparands)f(are)j(a)o(w)o(are,)g(and)208 3029 y(ha)n(v)o(e)g(the)i(same)f FJ(tzinfo)g FN(member)m(,)g(the)g (common)e FJ(tzinfo)i FN(member)f(is)i(ignored)e(and)g(the)i(base)f (datetimes)g(are)g(com-)208 3129 y(pared.)37 b(If)25 b(both)e(comparands)g(are)i(a)o(w)o(are)f(and)g(ha)n(v)o(e)g(dif)n (ferent)f FJ(tzinfo)h FN(members,)h(the)g(comparands)d(are)j(\002rst)g (adjusted)208 3228 y(by)f(subtracting)f(their)i(UTC)g(of)n(fsets)g (\(obtained)e(from)h FJ(self.utcoffset\(\))p FN(\).)36 b FL(Note:)e FN(In)24 b(order)g(to)h(stop)g(comparison)208 3328 y(from)g(f)o(alling)i(back)f(to)h(the)g(def)o(ault)f(scheme)g(of)h (comparing)d(object)j(addresses,)h(datetime)e(comparison)f(normally)g (raises)208 3427 y FJ(TypeError)18 b FN(if)i(the)g(other)e(comparand)f (isn')o(t)j(also)g(a)g FJ(datetime)e FN(object.)25 b(Ho)n(we)n(v)o(er)m (,)17 b FJ(NotImplemented)h FN(is)i(returned)208 3527 y(instead)d(if)g(the)g(other)g(comparand)e(has)i(a)h FJ(timetuple)e FN(attrib)n(ute.)23 b(This)18 b(hook)e(gi)n(v)o(es)h (other)f(kinds)h(of)g(date)g(objects)g(a)h(chance)208 3627 y(at)24 b(implementing)e(mix)o(ed-type)f(comparison.)35 b(If)24 b(not,)g(when)f(a)i FJ(datetime)e FN(object)g(is)i(compared)d (to)j(an)e(object)h(of)g(a)g(dif-)208 3726 y(ferent)19 b(type,)h FJ(TypeError)f FN(is)i(raised)f(unless)h(the)f(comparison)e (is)j FJ(==)g FN(or)f FJ(!=)p FN(.)25 b(The)20 b(latter)h(cases)g (return)e FJ(False)h FN(or)g FJ(True)p FN(,)208 3826 y(respecti)n(v)o(ely)-5 b(.)0 4056 y FJ(datetime)20 b FN(objects)i(can)f(be)g(used)g(as)h(dictionary)e(k)o(e)o(ys.)28 b(In)21 b(Boolean)g(conte)o(xts,)g(all)h FJ(datetime)e FN(objects)h(are)g(considered)f(to)i(be)0 4155 y(true.)0 4302 y(Instance)d(methods:)0 4449 y FD(date)p FJ(\(\))208 4549 y FN(Return)g FJ(date)h FN(object)g(with)g(same)h(year)m(,)e (month)g(and)g(day)-5 b(.)0 4696 y FD(time)p FJ(\(\))208 4795 y FN(Return)26 b FJ(time)h FN(object)f(with)h(same)g(hour)m(,)g (minute,)h(second)e(and)g(microsecond.)43 b FJ(tzinfo)26 b FN(is)i FJ(None)p FN(.)45 b(See)28 b(also)f(method)208 4895 y FJ(timetz\(\))p FN(.)0 5042 y FD(timetz)p FJ(\(\))208 5141 y FN(Return)k FJ(time)g FN(object)g(with)g(same)h(hour)m(,)h (minute,)g(second,)g(microsecond,)f(and)f(tzinfo)g(members.)57 b(See)32 b(also)g(method)208 5241 y FJ(time\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2093 b(103)p eop end %%Page: 104 116 TeXDict begin 104 115 bop 0 83 a FD(replace)p FJ(\()p FC([)p FK(year)r FC([)p FK(,)18 b(month)p FC([)p FK(,)h(day)p FC([)p FK(,)g(hour)r FC([)p FK(,)g(minute)p FC([)p FK(,)h(second)r FC([)p FK(,)f(micr)l(osecond)r FC([)p FK(,)g(tzinfo)12 b FC(])g(])g(])g(])g(])g(])g(])g(])p FJ(\))208 183 y FN(Return)21 b(a)i(datetime)f(with)g(the)h(same)f(members,)g(e)o(xcept) f(for)h(those)g(members)f(gi)n(v)o(en)g(ne)n(w)h(v)n(alues)g(by)g (whiche)n(v)o(er)e(k)o(e)o(yw)o(ord)208 282 y(ar)o(guments)i(are)i (speci\002ed.)37 b(Note)24 b(that)g FJ(tzinfo=None)f FN(can)h(be)g(speci\002ed)g(to)h(create)f(a)g(nai)n(v)o(e)g(datetime)f (from)h(an)g(a)o(w)o(are)208 382 y(datetime)19 b(with)i(no)e(con)m(v)o (ersion)f(of)i(date)g(and)f(time)i(members.)0 529 y FD(astimezone)p FJ(\()p FK(tz)p FJ(\))208 628 y FN(Return)e(a)h FJ(datetime)f FN(object)g(with)h(ne)n(w)g FJ(tzinfo)f FN(member)f FK(tz)p FN(,)j(adjusting)e(the)g(date)h(and)f(time)h(members)f(so)h(the)g (result)g(is)208 728 y(the)g(same)g(UTC)h(time)f(as)h FK(self)12 b FN(,)21 b(b)n(ut)f(in)h FK(tz)p FN(')-5 b(s)21 b(local)f(time.)208 861 y FK(tz)28 b FN(must)g(be)g(an)f (instance)g(of)h(a)g FJ(tzinfo)f FN(subclass,)j(and)d(its)h FJ(utcoffset\(\))f FN(and)g FJ(dst\(\))g FN(methods)g(must)g(not)h (return)208 960 y FJ(None)p FN(.)23 b FK(self)31 b FN(must)18 b(be)f(a)o(w)o(are)h(\()p FK(self)12 b FJ(.tzinfo)17 b FN(must)h(not)f(be)g FJ(None)p FN(,)h(and)f FK(self)12 b FJ(.utcoffset\(\))17 b FN(must)h(not)f(return)f FJ(None)p FN(\).)208 1093 y(If)30 b FK(self)12 b FJ(.tzinfo)30 b FN(is)i FK(tz)p FN(,)i FK(self)12 b FJ(.astimezone\()p FK(tz)p FJ(\))30 b FN(is)h(equal)f(to)h FK(self)12 b FN(:)47 b(no)30 b(adjustment)g(of)g(date)h(or)f(time)h(members)f(is)208 1193 y(performed.)k(Else)24 b(the)g(result)g(is)h(local)f(time)h(in)f (time)g(zone)g FK(tz)p FN(,)h(representing)d(the)i(same)h(UTC)f(time)h (as)f FK(self)12 b FN(:)34 b(after)24 b FK(astz)50 b FJ(=)208 1293 y FK(dt)q FJ(.astimezone\()p FK(tz)p FJ(\))p FN(,)19 b FK(astz)50 b FJ(-)g FK(astz)p FJ(.utcoffset\(\))19 b FN(will)j(usually)e(ha)n(v)o(e)g(the)h(same)h(date)e(and)h(time)g (members)f(as)h FK(dt)208 1392 y FJ(-)49 b FK(dt)q FJ(.utcoffset\(\))p FN(.)26 b(The)20 b(discussion)h(of)g(class)g FJ(tzinfo)g FN(e)o(xplains)f(the)h(cases)g(at)h(Daylight)e(Sa)n(ving)g(T)m(ime)h (transition)208 1492 y(boundaries)d(where)h(this)i(cannot)e(be)h(achie) n(v)o(ed)f(\(an)g(issue)i(only)f(if)g FK(tz)h FN(models)f(both)f (standard)g(and)h(daylight)f(time\).)208 1625 y(If)e(you)g(merely)g(w)o (ant)h(to)g(attach)g(a)g(time)g(zone)g(object)f FK(tz)i FN(to)f(a)g(datetime)g FK(dt)h FN(without)e(adjustment)g(of)h(date)f (and)h(time)g(members,)208 1724 y(use)h FK(dt)q FJ(.replace\(tzinfo=)p FK(tz)p FJ(\))p FN(.)j(If)d(you)e(merely)h(w)o(ant)h(to)g(remo)o(v)o(e) e(the)i(time)g(zone)f(object)g(from)g(an)h(a)o(w)o(are)f(datetime)g FK(dt)208 1824 y FN(without)h(con)m(v)o(ersion)f(of)h(date)h(and)g (time)g(members,)f(use)i FK(dt)q FJ(.replace\(tzinfo=None\))p FN(.)208 1957 y(Note)29 b(that)g(the)h(def)o(ault)e FJ (tzinfo.fromutc\(\))f FN(method)h(can)h(be)h(o)o(v)o(erridden)c(in)j(a) h FJ(tzinfo)f FN(subclass)g(to)h(af)n(fect)f(the)208 2056 y(result)20 b(returned)e(by)i FJ(astimezone\(\))p FN(.)j(Ignoring)18 b(error)h(cases,)i FJ(astimezone\(\))d FN(acts)j(lik)o(e:)533 2281 y FA(def)45 b(astimezone\(self,)d(tz\):)713 2372 y(if)i(self.tzinfo)f(is)i(tz:)892 2463 y(return)f(self)713 2555 y(#)g(Convert)g(self)g(to)h(UTC,)f(and)g(attach)g(the)g(new)h (time)f(zone)g(object.)713 2646 y(utc)g(=)h(\(self)f(-)g (self.utcoffset\(\)\).replace\(tzinfo=tz\))713 2737 y(#)g(Convert)g (from)g(UTC)h(to)f(tz's)g(local)g(time.)713 2828 y(return)g (tz.fromutc\(utc\))0 3119 y FD(utcoffset)p FJ(\(\))208 3219 y FN(If)20 b FJ(tzinfo)f FN(is)j FJ(None)p FN(,)e(returns)f FJ(None)p FN(,)h(else)h(returns)e FK(self)12 b FJ(.tzinfo.utcoffset\()p FK(self)g FJ(\))p FN(,)18 b(and)i(raises)h(an)f(e)o(xception)e(if)208 3318 y(the)e(latter)g(doesn')o(t)f(return)g FJ(None)p FN(,)h(or)g(a)h FJ(timedelta)e FN(object)g(representing)f(a)j(whole)e (number)g(of)h(minutes)f(with)h(magnitude)208 3418 y(less)21 b(than)f(one)f(day)-5 b(.)0 3565 y FD(dst)p FJ(\(\))208 3664 y FN(If)19 b FJ(tzinfo)f FN(is)j FJ(None)p FN(,)e(returns)f FJ(None)p FN(,)h(else)h(returns)e FK(self)12 b FJ(.tzinfo.dst\()p FK(self)g FJ(\))p FN(,)18 b(and)h(raises)h(an)f(e)o(xception)f(if)h (the)g(latter)208 3764 y(doesn')o(t)25 b(return)h FJ(None)p FN(,)i(or)f(a)g FJ(timedelta)f FN(object)h(representing)e(a)i(whole)g (number)e(of)i(minutes)f(with)h(magnitude)e(less)208 3864 y(than)19 b(one)h(day)-5 b(.)0 4011 y FD(tzname)p FJ(\(\))208 4110 y FN(If)18 b FJ(tzinfo)g FN(is)h FJ(None)p FN(,)g(returns)e FJ(None)p FN(,)i(else)g(returns)f FK(self)12 b FJ(.tzinfo.tzname\()p FK(self)g FJ(\))p FN(,)17 b(raises)i(an)f(e)o (xception)f(if)i(the)f(latter)208 4210 y(doesn')o(t)g(return)h FJ(None)h FN(or)g(a)h(string)f(object,)0 4357 y FD(timetuple)p FJ(\(\))208 4456 y FN(Return)26 b(a)h FJ(time.struct_time)e FN(such)h(as)i(returned)d(by)h FJ(time.localtime\(\))p FN(.)43 b FK(d)r FJ(.timetuple\(\))24 b FN(is)k(equi)n(v)n(a-)208 4556 y(lent)50 b(to)h FJ(time.struct_time\(\()p FK(d)r FJ(.year,)45 b FK(d)r FJ(.month,)k FK(d)r FJ(.day,)f FK(d)r FJ(.hour,)h FK(d)r FJ(.minute,)f FK(d)r FJ(.second,)208 4656 y FK(d)r FJ(.weekday\(\),)f FK(d)r FJ(.toordinal\(\))g(-)j(date\() p FK(d)r FJ(.year,)e(1,)h(1\).toordinal\(\))e(+)j(1,)f(dst\)\))94 b FN(The)208 4755 y FJ(tm_isdst)16 b FN(\003ag)i(of)f(the)g(result)h (is)g(set)g(according)d(to)j(the)f FJ(dst\(\))g FN(method:)23 b FJ(tzinfo)17 b FN(is)h FJ(None)f FN(or)g FJ(dst\(\))g FN(returns)g FJ(None)p FN(,)208 4855 y FJ(tm_isdst)i FN(is)h(set)h(to)f FJ(-1)p FN(;)h(else)f(if)g FJ(dst\(\))g FN(returns)f(a)h(non-zero)e(v)n(alue,)h FJ(tm_isdst)g FN(is)i(set)g(to)f FJ(1)p FN(;)g(else)h FJ(tm_isdst)e FN(is)i(set)208 4954 y(to)f FJ(0)p FN(.)0 5101 y FD(utctimetuple)p FJ(\(\))208 5201 y FN(If)h FJ(datetime)g FN(instance)g FK(d)j FN(is)f(nai)n(v)o(e,)d(this)j(is)f(the)g(same)g(as)g FK(d)r FJ(.timetuple\(\))e FN(e)o(xcept)g(that)i FJ(tm_isdst)f FN(is)h(forced)f(to)g(0)208 5301 y(re)o(gardless)d(of)i(what)g FJ(d.dst\(\))g FN(returns.)k(DST)c(is)h(ne)n(v)o(er)e(in)i(ef)n(fect)e (for)h(a)g(UTC)h(time.)p 0 5549 3901 4 v 0 5649 a FI(104)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 105 117 TeXDict begin 105 116 bop 208 83 a FN(If)24 b FK(d)j FN(is)f(a)o(w)o(are,)f FK(d)i FN(is)e(normalized)e(to)i(UTC)g(time,)h (by)e(subtracting)f FK(d)r FJ(.utcoffset\(\))p FN(,)h(and)g(a)h FJ(time.struct_time)208 183 y FN(for)e(the)g(normalized)f(time)i(is)h (returned.)33 b FJ(tm_isdst)23 b FN(is)i(forced)d(to)i(0.)35 b(Note)24 b(that)g(the)g(result')-5 b(s)24 b FJ(tm_year)f FN(member)f(may)208 282 y(be)g FJ(MINYEAR)p FN(-1)e(or)i FJ(MAXYEAR)p FN(+1,)g(if)g FK(d)r FN(.year)f(w)o(as)i FJ(MINYEAR)f FN(or)g FJ(MAXYEAR)g FN(and)f(UTC)i(adjustment)e(spills)j (o)o(v)o(er)c(a)j(year)208 382 y(boundary)-5 b(.)0 529 y FD(toordinal)p FJ(\(\))208 628 y FN(Return)19 b(the)i(proleptic)d (Gre)o(gorian)g(ordinal)h(of)h(the)h(date.)j(The)c(same)h(as)f FJ(self.date\(\).toordinal\(\))p FN(.)0 775 y FD(weekday)p FJ(\(\))208 875 y FN(Return)51 b(the)h(day)f(of)h(the)g(week)f(as)i(an) f(inte)o(ger)m(,)58 b(where)51 b(Monday)g(is)h(0)g(and)g(Sunday)e(is)j (6.)120 b(The)52 b(same)g(as)208 975 y FJ(self.date\(\).weekday\(\))p FN(.)21 b(See)g(also)f FJ(isoweekday\(\))p FN(.)0 1121 y FD(isoweekday)p FJ(\(\))208 1221 y FN(Return)51 b(the)h(day)f(of)h (the)g(week)f(as)i(an)f(inte)o(ger)m(,)58 b(where)51 b(Monday)g(is)h(1)g(and)g(Sunday)e(is)j(7.)120 b(The)52 b(same)g(as)208 1321 y FJ(self.date\(\).isoweekday\(\))p FN(.)21 b(See)f(also)h FJ(weekday\(\))p FN(,)e FJ(isocalendar\(\))p FN(.)0 1468 y FD(isocalendar)p FJ(\(\))208 1567 y FN(Return)99 b(a)h(3-tuple,)118 b(\(ISO)99 b(year)m(,)119 b(ISO)100 b(week)f(number)m(,)117 b(ISO)100 b(weekday\).)262 b(The)99 b(same)h(as)208 1667 y FJ(self.date\(\).isocalendar\(\))p FN(.)0 1814 y FD(isoformat)p FJ(\()p FC([)p FK(sep)12 b FC(])p FJ(\))208 1913 y FN(Return)23 b(a)i(string)f(representing)e (the)i(date)g(and)g(time)g(in)h(ISO)f(8601)f(format,)h(YYYY)-9 b(-MM-DDTHH:MM:SS.mmmmmm)208 2013 y(or)m(,)19 b(if)h FJ(microsecond)f FN(is)i(0,)f(YYYY)-9 b(-MM-DDTHH:MM:SS)208 2146 y(If)25 b FJ(utcoffset\(\))f FN(does)h(not)g(return)f FJ(None)p FN(,)i(a)g(6-character)d(string)j(is)g(appended,)e(gi)n(ving) g(the)h(UTC)h(of)n(fset)f(in)h(\(signed\))208 2245 y(hours)k(and)h (minutes:)47 b(YYYY)-9 b(-MM-DDTHH:MM:SS.mmmmmm+HH:MM)26 b(or)m(,)34 b(if)d FJ(microsecond)f FN(is)i(0)g(YYYY)-9 b(-)208 2345 y(MM-DDTHH:MM:SS+HH:MM)208 2478 y(The)17 b(optional)g(ar)o(gument)e FK(sep)j FN(\(def)o(ault)f FJ('T')p FN(\))h(is)h(a)f(one-character)d(separator)m(,)i(placed)g (between)g(the)h(date)f(and)h(time)g(portions)208 2577 y(of)h(the)i(result.)k(F)o(or)19 b(e)o(xample,)444 2802 y FA(>>>)44 b(from)g(datetime)g(import)g(tzinfo,)f(timedelta,)g (datetime)444 2893 y(>>>)h(class)g(TZ\(tzinfo\):)444 2984 y(...)223 b(def)45 b(utcoffset\(self,)d(dt\):)i(return)g (timedelta\(minutes=-399\))444 3076 y(...)444 3167 y(>>>)g (datetime\(2002,)f(12,)h(25,)g(tzinfo=TZ\(\)\).isoformat\(')d('\))444 3258 y('2002-12-25)i(00:00:00-06:39')0 3456 y FD(__str__)p FJ(\(\))208 3556 y FN(F)o(or)19 b(a)i FJ(datetime)e FN(instance)h FK(d)r FN(,)g FJ(str\()p FK(d)r FJ(\))g FN(is)h(equi)n(v)n(alent)e(to)h FK(d)r FJ(.isoformat\(')47 b('\))p FN(.)0 3703 y FD(ctime)p FJ(\(\))208 3802 y FN(Return)65 b(a)i(string)f(representing)e(the)j (date)f(and)f(time,)78 b(for)66 b(e)o(xample)f FJ(datetime\(2002,)47 b(12,)i(4,)h(20,)208 3902 y(30,)f(40\).ctime\(\))f(==)h('Wed)g(Dec)g(4) h(20:30:40)e(2002')p FN(.)266 b FJ(d.ctime\(\))99 b FN(is)j(equi)n(v)n (alent)c(to)208 4001 y FJ(time.ctime\(time.mktime\(d.timetupl)o (e\(\)\)\))20 b FN(on)26 b(platforms)f(where)g(the)i(nati)n(v)o(e)e(C)i FJ(ctime\(\))e FN(function)208 4101 y(\(which)35 b FJ(time.ctime\(\))f FN(in)m(v)n(ok)o(es,)39 b(b)n(ut)e(which)e FJ(datetime.ctime\(\))f FN(does)i(not)g(in)m(v)n(ok)o(e\))f(conforms)f(to)i(the)h(C)208 4201 y(standard.)0 4348 y FD(strftime)p FJ(\()p FK(format)q FJ(\))208 4447 y FN(Return)30 b(a)h(string)g(representing)d(the)j(date) g(and)f(time,)k(controlled)29 b(by)h(an)h(e)o(xplicit)f(format)g (string.)56 b(See)31 b(section)g(5.1.7)e(\226)208 4547 y FJ(strftime\(\))18 b FN(beha)n(vior)-5 b(.)0 4832 y Fv(5.1.5)100 b Fm(time)27 b Fv(Objects)0 5035 y FN(A)j(time)g(object)f (represents)g(a)h(\(local\))f(time)g(of)h(day)-5 b(,)31 b(independent)c(of)i(an)o(y)g(particular)f(day)-5 b(,)31 b(and)e(subject)g(to)h(adjustment)f(via)g(a)0 5134 y FJ(tzinfo)20 b FN(object.)0 5281 y FL(class)h FD(time)p FJ(\()p FK(hour)r FC([)p FK(,)d(minute)p FC([)p FK(,)h(second)r FC([)p FK(,)g(micr)l(osecond)r FC([)p FK(,)g(tzinfo)12 b FC(])g(])g(])g(])p FJ(\))208 5381 y FN(All)k(ar)o(guments)d(are)i (optional.)23 b FK(tzinfo)15 b FN(may)g(be)h FJ(None)p FN(,)g(or)f(an)g(instance)g(of)g(a)h FJ(tzinfo)f FN(subclass.)24 b(The)15 b(remaining)f(ar)o(guments)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f (time)h(types)2093 b(105)p eop end %%Page: 106 118 TeXDict begin 106 117 bop 208 83 a FN(may)19 b(be)h(ints)h(or)f(longs,) f(in)i(the)f(follo)n(wing)f(ranges:)349 296 y FM(\017)o FJ(0)50 b(<=)f FK(hour)i FJ(<)e(24)349 429 y FM(\017)o FJ(0)h(<=)f FK(minute)g FJ(<)h(60)349 562 y FM(\017)o FJ(0)g(<=)f FK(second)i FJ(<)f(60)349 695 y FM(\017)o FJ(0)g(<=)f FK(micr)l(osecond)i FJ(<)e(1000000)p FN(.)208 908 y(If)27 b(an)h(ar)o(gument)e(outside)i(those)g(ranges)f(is)i(gi)n (v)o(en,)f FJ(ValueError)f FN(is)i(raised.)48 b(All)29 b(def)o(ault)e(to)i FJ(0)f FN(e)o(xcept)f FK(tzinfo)p FN(,)j(which)208 1008 y(def)o(aults)19 b(to)i FJ(None)p FN(.)0 1155 y(Class)h(attrib)n(utes:)0 1301 y FD(min)208 1401 y FN(The)d(earliest)i(representable)d FJ(time)p FN(,)i FJ(time\(0,)49 b(0,)g(0,)g(0\))p FN(.)0 1548 y FD(max)208 1648 y FN(The)19 b(latest)i(representable)e FJ(time)p FN(,)h FJ(time\(23,)48 b(59,)h(59,)g(999999\))p FN(.)0 1794 y FD(resolution)208 1894 y FN(The)28 b(smallest)h(possible) g(dif)n(ference)d(between)i(non-equal)e FJ(time)j FN(objects,)h FJ(timedelta\(microseconds=1\))p FN(,)c(al-)208 1994 y(though)18 b(note)i(that)g(arithmetic)f(on)h FJ(time)g FN(objects)g(is)h(not)f(supported.)0 2141 y(Instance)f(attrib)n(utes)h (\(read-only\):)0 2287 y FD(hour)208 2387 y FN(In)f FJ(range\(24\))p FN(.)0 2534 y FD(minute)208 2634 y FN(In)g FJ(range\(60\))p FN(.)0 2780 y FD(second)208 2880 y FN(In)g FJ(range\(60\))p FN(.)0 3027 y FD(microsecond)208 3127 y FN(In)g FJ(range\(1000000\))p FN(.)0 3273 y FD(tzinfo)208 3373 y FN(The)g(object)h(passed)g(as)h(the) f(tzinfo)g(ar)o(gument)e(to)i(the)g FJ(time)g FN(constructor)m(,)e(or)i FJ(None)g FN(if)g(none)f(w)o(as)i(passed.)0 3520 y(Supported)d (operations:)125 3750 y FM(\017)41 b FN(comparison)16 b(of)h FJ(time)h FN(to)g FJ(time)p FN(,)h(where)e FK(a)h FN(is)h(considered)d(less)k(than)d FK(b)h FN(when)g FK(a)g FN(precedes)f FK(b)h FN(in)g(time.)25 b(If)18 b(one)f(comparand)f(is) 208 3849 y(nai)n(v)o(e)i(and)h(the)g(other)f(is)i(a)o(w)o(are,)f FJ(TypeError)f FN(is)i(raised.)25 b(If)19 b(both)f(comparands)f(are)i (a)o(w)o(are,)g(and)g(ha)n(v)o(e)f(the)i(same)f FJ(tzinfo)208 3949 y FN(member)m(,)33 b(the)g(common)d FJ(tzinfo)i FN(member)f(is)j(ignored)d(and)h(the)g(base)h(times)g(are)f(compared.) 60 b(If)32 b(both)g(comparands)208 4049 y(are)c(a)o(w)o(are)g(and)f(ha) n(v)o(e)h(dif)n(ferent)e FJ(tzinfo)i FN(members,)h(the)f(comparands)e (are)i(\002rst)h(adjusted)f(by)f(subtracting)g(their)h(UTC)208 4148 y(of)n(fsets)22 b(\(obtained)f(from)g FJ(self.utcoffset\(\))p FN(\).)29 b(In)23 b(order)e(to)i(stop)f(mix)o(ed-type)e(comparisons)h (from)g(f)o(alling)i(back)e(to)208 4248 y(the)28 b(def)o(ault)f (comparison)f(by)i(object)f(address,)j(when)d(a)h FJ(time)g FN(object)g(is)h(compared)d(to)i(an)g(object)g(of)f(a)i(dif)n(ferent)d (type,)208 4348 y FJ(TypeError)17 b FN(is)i(raised)f(unless)g(the)g (comparison)e(is)j FJ(==)g FN(or)f FJ(!=)p FN(.)24 b(The)18 b(latter)g(cases)h(return)e FJ(False)h FN(or)g FJ(True)p FN(,)g(respecti)n(v)o(ely)-5 b(.)125 4514 y FM(\017)41 b FN(hash,)19 b(use)i(as)g(dict)f(k)o(e)o(y)125 4680 y FM(\017)41 b FN(ef)n(\002cient)19 b(pickling)125 4846 y FM(\017)41 b FN(in)26 b(Boolean)g(conte)o(xts,)h(a)f FJ(time)h FN(object)f(is)h(considered)e(to)h(be)h(true)f(if)g(and)g (only)g(if,)i(after)e(con)m(v)o(erting)d(it)28 b(to)e(minutes)g(and)208 4945 y(subtracting)18 b FJ(utcoffset\(\))h FN(\(or)h FJ(0)g FN(if)h(that')-5 b(s)20 b FJ(None)p FN(\),)g(the)g(result)g(is)h (non-zero.)0 5175 y(Instance)e(methods:)p 0 5549 3901 4 v 0 5649 a FI(106)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 107 119 TeXDict begin 107 118 bop 0 83 a FD(replace)p FJ(\()p FC([)p FK(hour)r FC([)p FK(,)17 b(minute)p FC([)p FK(,)j(second)r FC([)p FK(,)f(micr)l(osecond)r FC([)p FK(,)g(tzinfo)12 b FC(])g(])g(])g(])g(])p FJ(\))208 183 y FN(Return)22 b(a)i FJ(time)f FN(with)h(the)f(same)g(v)n(alue,)h(e)o(xcept)e(for)g (those)i(members)e(gi)n(v)o(en)g(ne)n(w)h(v)n(alues)g(by)g(whiche)n(v)o (er)e(k)o(e)o(yw)o(ord)g(ar)o(gu-)208 282 y(ments)i(are)h(speci\002ed.) 35 b(Note)23 b(that)h FJ(tzinfo=None)e FN(can)h(be)h(speci\002ed)f(to)h (create)f(a)h(nai)n(v)o(e)f FJ(time)h FN(from)e(an)i(a)o(w)o(are)f FJ(time)p FN(,)208 382 y(without)c(con)m(v)o(ersion)f(of)h(the)i(time)f (members.)0 529 y FD(isoformat)p FJ(\(\))208 628 y FN(Return)33 b(a)i(string)f(representing)e(the)i(time)g(in)g(ISO)h(8601)e(format,)j (HH:MM:SS.mmmmmm)c(or)m(,)37 b(if)d(self.microsecond)208 728 y(is)k(0,)k(HH:MM:SS)c(If)f FJ(utcoffset\(\))f FN(does)h(not)g (return)g FJ(None)p FN(,)k(a)d(6-character)d(string)j(is)g(appended,)h (gi)n(ving)e(the)208 828 y(UTC)d(of)n(fset)g(in)h(\(signed\))e(hours)g (and)h(minutes:)53 b(HH:MM:SS.mmmmmm+HH:MM)31 b(or)m(,)37 b(if)e(self.microsecond)c(is)36 b(0,)208 927 y(HH:MM:SS+HH:MM)0 1074 y FD(__str__)p FJ(\(\))208 1174 y FN(F)o(or)19 b(a)i(time)f FK(t)q FN(,)h FJ(str\()p FK(t)q FJ(\))g FN(is)g(equi)n(v)n(alent)d(to)j FK(t)q FJ(.isoformat\(\))p FN(.)0 1321 y FD(strftime)p FJ(\()p FK(format)q FJ(\))208 1420 y FN(Return)d(a)i(string)f (representing)e(the)i(time,)h(controlled)d(by)i(an)g(e)o(xplicit)g (format)f(string.)24 b(See)c(section)f(5.1.7)f(\226)h FJ(strftime\(\))208 1520 y FN(beha)n(vior)-5 b(.)0 1667 y FD(utcoffset)p FJ(\(\))208 1766 y FN(If)28 b FJ(tzinfo)f FN(is)i FJ(None)p FN(,)h(returns)e FJ(None)p FN(,)h(else)g(returns)f FK(self)12 b FJ(.tzinfo.utcoffset\(None\))p FN(,)26 b(and)i(raises)h (an)f(e)o(xcep-)208 1866 y(tion)e(if)h(the)f(latter)h(doesn')o(t)e (return)g FJ(None)h FN(or)g(a)h FJ(timedelta)e FN(object)h (representing)f(a)i(whole)f(number)e(of)i(minutes)g(with)208 1966 y(magnitude)18 b(less)j(than)f(one)f(day)-5 b(.)0 2113 y FD(dst)p FJ(\(\))208 2212 y FN(If)27 b FJ(tzinfo)g FN(is)h FJ(None)p FN(,)h(returns)d FJ(None)p FN(,)j(else)f(returns)e FK(self)12 b FJ(.tzinfo.dst\(None\))p FN(,)27 b(and)g(raises)h(an)f(e)o (xception)f(if)i(the)208 2312 y(latter)c(doesn')o(t)e(return)h FJ(None)p FN(,)i(or)e(a)i FJ(timedelta)e FN(object)g(representing)f(a)i (whole)g(number)e(of)i(minutes)f(with)h(magnitude)208 2411 y(less)d(than)f(one)f(day)-5 b(.)0 2558 y FD(tzname)p FJ(\(\))208 2658 y FN(If)20 b FJ(tzinfo)g FN(is)i FJ(None)p FN(,)e(returns)g FJ(None)p FN(,)g(else)i(returns)e FK(self)12 b FJ(.tzinfo.tzname\(None\))p FN(,)17 b(or)k(raises)g(an)g(e)o (xception)e(if)i(the)208 2758 y(latter)f(doesn')o(t)f(return)g FJ(None)h FN(or)g(a)g(string)g(object.)0 3042 y Fv(5.1.6)100 b Fm(tzinfo)27 b Fv(Objects)0 3245 y FJ(tzinfo)f FN(is)h(an)f(abstract) g(base)h(clase,)h(meaning)d(that)h(this)h(class)g(should)e(not)h(be)h (instantiated)e(directly)-5 b(.)42 b(Y)-9 b(ou)26 b(need)g(to)g(deri)n (v)o(e)f(a)0 3345 y(concrete)19 b(subclass,)h(and)f(\(at)i(least\))f (supply)f(implementations)f(of)i(the)g(standard)f FJ(tzinfo)g FN(methods)g(needed)g(by)g(the)h FJ(datetime)0 3445 y FN(methods)f(you)g(use.)26 b(The)19 b FJ(datetime)h FN(module)e(does)i (not)g(supply)f(an)o(y)h(concrete)f(subclasses)h(of)g FJ(tzinfo)p FN(.)0 3591 y(An)h(instance)f(of)g(\(a)h(concrete)e (subclass)i(of\))f FJ(tzinfo)h FN(can)f(be)h(passed)f(to)h(the)g (constructors)e(for)h FJ(datetime)f FN(and)i FJ(time)f FN(objects.)0 3691 y(The)d(latter)h(objects)f(vie)n(w)g(their)g (members)f(as)i(being)f(in)g(local)g(time,)h(and)f(the)g FJ(tzinfo)g FN(object)g(supports)f(methods)h(re)n(v)o(ealing)e(of)n (fset)0 3791 y(of)j(local)g(time)g(from)g(UTC,)g(the)g(name)g(of)g(the) g(time)h(zone,)e(and)h(DST)h(of)n(fset,)e(all)i(relati)n(v)o(e)f(to)g (a)h(date)f(or)g(time)g(object)g(passed)g(to)g(them.)0 3938 y(Special)25 b(requirement)d(for)i(pickling:)33 b(A)25 b FJ(tzinfo)f FN(subclass)h(must)g(ha)n(v)o(e)f(an)h FJ(__init__)e FN(method)h(that)h(can)f(be)h(called)f(with)h(no)0 4037 y(ar)o(guments,)17 b(else)j(it)f(can)g(be)g(pickled)f(b)n(ut)h (possibly)f(not)h(unpickled)e(again.)23 b(This)c(is)h(a)g(technical)e (requirement)e(that)k(may)e(be)h(relax)o(ed)0 4137 y(in)h(the)h (future.)0 4284 y(A)j(concrete)e(subclass)i(of)f FJ(tzinfo)g FN(may)g(need)g(to)g(implement)g(the)g(follo)n(wing)f(methods.)34 b(Exactly)22 b(which)h(methods)f(are)i(needed)0 4383 y(depends)19 b(on)h(the)g(uses)h(made)e(of)h(a)o(w)o(are)g FJ(datetime)f FN(objects.)25 b(If)20 b(in)g(doubt,)f(simply)h (implement)f(all)h(of)g(them.)0 4530 y FD(utcoffset)p FJ(\()p FK(self)o(,)f(dt)q FJ(\))208 4630 y FN(Return)27 b(of)n(fset)g(of)g(local)h(time)g(from)e(UTC,)j(in)e(minutes)h(east)g (of)f(UTC.)h(If)g(local)f(time)h(is)h(west)f(of)g(UTC,)g(this)g(should) f(be)208 4729 y(ne)o(gati)n(v)o(e.)22 b(Note)e(that)g(this)h(is)g (intended)d(to)i(be)g(the)g(total)g(of)n(fset)g(from)f(UTC;)h(for)g(e)o (xample,)e(if)i(a)h FJ(tzinfo)e FN(object)g(represents)208 4829 y(both)i(time)h(zone)f(and)g(DST)h(adjustments,)f FJ(utcoffset\(\))g FN(should)g(return)f(their)i(sum.)30 b(If)21 b(the)h(UTC)g(of)n(fset)g(isn')o(t)f(kno)n(wn,)208 4929 y(return)g FJ(None)p FN(.)34 b(Else)23 b(the)g(v)n(alue)g (returned)e(must)i(be)g(a)g FJ(timedelta)f FN(object)h(specifying)e(a)i (whole)g(number)e(of)i(minutes)f(in)208 5028 y(the)f(range)f(-1439)f (to)i(1439)f(inclusi)n(v)o(e)g(\(1440)f(=)i(24*60;)f(the)h(magnitude)e (of)i(the)g(of)n(fset)g(must)g(be)g(less)h(than)e(one)h(day\).)26 b(Most)208 5128 y(implementations)18 b(of)i FJ(utcoffset\(\))e FN(will)j(probably)d(look)i(lik)o(e)g(one)g(of)g(these)g(tw)o(o:)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2093 b(107)p eop end %%Page: 108 120 TeXDict begin 108 119 bop 623 174 a FA(return)44 b(CONSTANT)761 b(#)44 b(fixed-offset)f(class)623 266 y(return)h(CONSTANT)f(+)i (self.dst\(dt\))88 b(#)44 b(daylight-aware)f(class)208 454 y FN(If)20 b FJ(utcoffset\(\))e FN(does)i(not)g(return)f FJ(None)p FN(,)h FJ(dst\(\))g FN(should)f(not)h(return)f FJ(None)h FN(either)-5 b(.)208 587 y(The)19 b(def)o(ault)h (implementation)e(of)i FJ(utcoffset\(\))e FN(raises)j FJ(NotImplementedError)p FN(.)0 734 y FD(dst)p FJ(\()p FK(self)o(,)f(dt)q FJ(\))208 833 y FN(Return)i(the)i(daylight)e(sa)n (ving)h(time)g(\(DST\))g(adjustment,)g(in)g(minutes)g(east)h(of)f(UTC,) h(or)f FJ(None)g FN(if)g(DST)h(information)d(isn')o(t)208 933 y(kno)n(wn.)i(Return)d FJ(timedelta\(0\))e FN(if)i(DST)h(is)g(not)e (in)i(ef)n(fect.)j(If)c(DST)g(is)h(in)g(ef)n(fect,)e(return)g(the)h(of) n(fset)f(as)i(a)g FJ(timedelta)208 1032 y FN(object)d(\(see)h FJ(utcoffset\(\))f FN(for)h(details\).)24 b(Note)19 b(that)g(DST)h(of)n (fset,)f(if)g(applicable,)f(has)h(already)f(been)h(added)f(to)h(the)g (UTC)208 1132 y(of)n(fset)k(returned)f(by)i FJ(utcoffset\(\))p FN(,)f(so)h(there')-5 b(s)24 b(no)f(need)g(to)h(consult)g FJ(dst\(\))f FN(unless)h(you')l(re)e(interested)h(in)h(obtaining)208 1232 y(DST)g(info)f(separately)-5 b(.)35 b(F)o(or)24 b(e)o(xample,)f FJ(datetime.timetuple\(\))e FN(calls)k(its)g FJ(tzinfo)e FN(member')-5 b(s)23 b FJ(dst\(\))h FN(method)208 1331 y(to)g(determine)g(ho)n(w)g(the)h FJ(tm_isdst)e FN(\003ag)i(should)f(be)g(set,)j(and)d FJ(tzinfo.fromutc\(\))e FN(calls)k FJ(dst\(\))e FN(to)h(account)e(for)208 1431 y(DST)d(changes)f(when)h(crossing)f(time)i(zones.)208 1563 y(An)k(instance)f FK(tz)i FN(of)f(a)g FJ(tzinfo)g FN(subclass)g(that)g(models)g(both)f(standard)g(and)g(daylight)g(times) h(must)g(be)g(consistent)g(in)g(this)208 1663 y(sense:)208 1795 y FK(tz)p FJ(.utcoffset\()p FK(dt)q FJ(\))48 b(-)h FK(tz)p FJ(.dst\()p FK(dt)q FJ(\))208 1927 y FN(must)27 b(return)f(the)h(same)h(result)f(for)g(e)n(v)o(ery)e FJ(datetime)i FK(dt)i FN(with)e FK(dt)q FJ(.tzinfo)49 b(==)g FK(tz)28 b FN(F)o(or)f(sane)h FJ(tzinfo)e FN(subclasses,)208 2027 y(this)f(e)o(xpression)e(yields)i(the)g(time)g(zone')-5 b(s)24 b(\224standard)g(of)n(fset\224,)h(which)g(should)e(not)i(depend) e(on)i(the)f(date)h(or)g(the)g(time,)h(b)n(ut)208 2126 y(only)d(on)h(geographic)d(location.)36 b(The)24 b(implementation)d(of) j FJ(datetime.astimezone\(\))d FN(relies)j(on)g(this,)i(b)n(ut)e (cannot)208 2226 y(detect)30 b(violations;)k(it')-5 b(s)32 b(the)e(programmer')-5 b(s)28 b(responsibility)h(to)h(ensure)g(it.)56 b(If)30 b(a)h FJ(tzinfo)e FN(subclass)i(cannot)e(guarantee)208 2326 y(this,)f(it)g(may)e(be)h(able)f(to)h(o)o(v)o(erride)e(the)i(def)o (ault)f(implementation)e(of)j FJ(tzinfo.fromutc\(\))d FN(to)j(w)o(ork)f(correctly)f(with)208 2425 y FJ(astimezone\(\))18 b FN(re)o(gardless.)208 2558 y(Most)i(implementations)e(of)i FJ(dst\(\))g FN(will)h(probably)d(look)h(lik)o(e)i(one)e(of)h(these)h (tw)o(o:)623 2781 y FA(def)44 b(dst\(self\):)802 2872 y(#)h(a)g(fixed-offset)e(class:)88 b(doesn't)44 b(account)g(for)g(DST) 802 2964 y(return)g(timedelta\(0\))208 3134 y FN(or)623 3357 y FA(def)g(dst\(self\):)802 3449 y(#)h(Code)f(to)h(set)f(dston)g (and)g(dstoff)g(to)h(the)f(time)g(zone's)g(DST)802 3540 y(#)h(transition)e(times)h(based)g(on)h(the)f(input)g(dt.year,)g(and)g (expressed)802 3631 y(#)h(in)g(standard)e(local)h(time.)89 b(Then)802 3814 y(if)45 b(dston)f(<=)g(dt.replace\(tzinfo=None\))d(<)k (dstoff:)982 3905 y(return)f(timedelta\(hours=1\))802 3997 y(else:)982 4088 y(return)g(timedelta\(0\))208 4277 y FN(The)19 b(def)o(ault)h(implementation)e(of)i FJ(dst\(\))g FN(raises)g FJ(NotImplementedError)p FN(.)0 4424 y FD(tzname)p FJ(\()p FK(self)o(,)g(dt)q FJ(\))208 4523 y FN(Return)c(the)h(time)g (zone)f(name)h(corresponding)c(to)k(the)g FJ(datetime)f FN(object)g FK(dt)q FN(,)i(as)g(a)f(string.)24 b(Nothing)15 b(about)h(string)h(names)g(is)208 4623 y(de\002ned)g(by)i(the)g FJ(datetime)e FN(module,)h(and)g(there')-5 b(s)19 b(no)f(requirement)f (that)i(it)g(mean)f(an)o(ything)f(in)i(particular)-5 b(.)24 b(F)o(or)18 b(e)o(xample,)208 4722 y(\224GMT\224,)30 b(\224UTC\224,)i(\224-500\224,)e(\224-5:00\224,)f(\224EDT\224,)i (\224US/Eastern\224,)g(\224America/Ne)n(w)d(Y)-9 b(ork\224)28 b(are)h(all)h(v)n(alid)e(replies.)52 b(Return)208 4822 y FJ(None)20 b FN(if)g(a)h(string)f(name)g(isn')o(t)g(kno)n(wn.)k(Note) c(that)h(this)g(is)g(a)g(method)e(rather)h(than)f(a)i(\002x)o(ed)f (string)g(primarily)f(because)h(some)208 4922 y FJ(tzinfo)f FN(subclasses)i(will)g(wish)f(to)h(return)e(dif)n(ferent)f(names)i (depending)e(on)h(the)i(speci\002c)f(v)n(alue)f(of)h FK(dt)i FN(passed,)e(especially)208 5021 y(if)g(the)g FJ(tzinfo)g FN(class)h(is)g(accounting)d(for)i(daylight)f(time.)208 5154 y(The)g(def)o(ault)h(implementation)e(of)i FJ(tzname\(\))f FN(raises)i FJ(NotImplementedError)p FN(.)0 5300 y(These)31 b(methods)e(are)i(called)f(by)h(a)g FJ(datetime)f FN(or)g FJ(time)h FN(object,)h(in)f(response)f(to)h(their)f(methods)g(of)g(the) h(same)g(names.)56 b(A)0 5400 y FJ(datetime)31 b FN(object)g(passes)i (itself)g(as)f(the)g(ar)o(gument,)h(and)e(a)h FJ(time)g FN(object)g(passes)g FJ(None)g FN(as)h(the)f(ar)o(gument.)58 b(A)32 b FJ(tzinfo)p 0 5549 3901 4 v 0 5649 a FI(108)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 109 121 TeXDict begin 109 120 bop 0 83 a FN(subclass')-5 b(s)21 b(methods)e(should)g(therefore)g(be)h(prepared)e(to)i(accept)g(a)h FK(dt)g FN(ar)o(gument)d(of)i FJ(None)p FN(,)g(or)g(of)g(class)h FJ(datetime)p FN(.)0 230 y(When)30 b FJ(None)g FN(is)h(passed,)h(it')-5 b(s)31 b(up)e(to)i(the)f(class)g(designer)f(to)h(decide)g(the)g(best)g (response.)53 b(F)o(or)30 b(e)o(xample,)h(returning)d FJ(None)i FN(is)0 330 y(appropriate)24 b(if)k(the)e(class)i(wishes)f (to)g(say)g(that)g(time)g(objects)g(don')o(t)e(participate)h(in)h(the)g FJ(tzinfo)f FN(protocols.)43 b(It)27 b(may)g(be)f(more)0 429 y(useful)19 b(for)g FJ(utcoffset\(None\))e FN(to)j(return)e(the)i (standard)e(UTC)i(of)n(fset,)f(as)i(there)e(is)h(no)f(other)g(con)m(v)o (ention)e(for)i(disco)o(v)o(ering)e(the)0 529 y(standard)i(of)n(fset.)0 676 y(When)25 b(a)h FJ(datetime)e FN(object)h(is)h(passed)f(in)h (response)e(to)h(a)h FJ(datetime)e FN(method,)h FJ(dt.tzinfo)f FN(is)i(the)g(same)f(object)g(as)h FK(self)12 b FN(.)0 775 y FJ(tzinfo)23 b FN(methods)g(can)g(rely)h(on)f(this,)i(unless)e (user)h(code)f(calls)h FJ(tzinfo)g FN(methods)e(directly)-5 b(.)34 b(The)24 b(intent)f(is)i(that)e(the)h FJ(tzinfo)0 875 y FN(methods)19 b(interpret)g FK(dt)j FN(as)f(being)e(in)h(local)h (time,)f(and)f(not)h(need)g(w)o(orry)f(about)g(objects)h(in)g(other)g (timezones.)0 1022 y(There)f(is)i(one)f(more)f FJ(tzinfo)h FN(method)f(that)h(a)h(subclass)f(may)g(wish)h(to)f(o)o(v)o(erride:)0 1169 y FD(fromutc)p FJ(\()p FK(self)o(,)g(dt)q FJ(\))208 1268 y FN(This)41 b(is)h(called)f(from)g(the)g(def)o(ault)f FJ(datetime.astimezone\(\))e FN(implementation.)86 b(When)41 b(called)g(from)g(that,)208 1368 y FK(dt)q FJ(.tzinfo)28 b FN(is)h FK(self)12 b FN(,)32 b(and)c FK(dt)q FN(')-5 b(s)30 b(date)e(and)h(time)f(members)g(are)h(to)g(be)f(vie)n(wed)g(as)i (e)o(xpressing)d(a)i(UTC)g(time.)51 b(The)28 b(pur)n(-)208 1468 y(pose)d(of)h FJ(fromutc\(\))f FN(is)i(to)f(adjust)g(the)g(date)g (and)f(time)h(members,)g(returning)e(an)i(equi)n(v)n(alent)f(datetime)g (in)h FK(self)12 b FN(')-5 b(s)28 b(local)208 1567 y(time.)208 1696 y(Most)20 b FJ(tzinfo)g FN(subclasses)h(should)f(be)g(able)g(to)h (inherit)f(the)g(def)o(ault)g FJ(fromutc\(\))f FN(implementation)f (without)i(problems.)208 1796 y(It')-5 b(s)23 b(strong)f(enough)e(to)j (handle)f(\002x)o(ed-of)n(fset)f(time)i(zones,)f(and)g(time)h(zones)g (accounting)d(for)i(both)g(standard)g(and)g(daylight)208 1896 y(time,)27 b(and)f(the)g(latter)h(e)n(v)o(en)e(if)i(the)f(DST)h (transition)e(times)i(dif)n(fer)e(in)i(dif)n(ferent)d(years.)43 b(An)27 b(e)o(xample)e(of)h(a)g(time)h(zone)f(the)208 1995 y(def)o(ault)j FJ(fromutc\(\))g FN(implementation)e(may)j(not)f (handle)g(correctly)g(in)h(all)g(cases)h(is)g(one)e(where)g(the)h (standard)f(of)n(fset)208 2095 y(\(from)20 b(UTC\))j(depends)e(on)g (the)i(speci\002c)f(date)g(and)g(time)g(passed,)g(which)g(can)g(happen) f(for)g(political)h(reasons.)30 b(The)22 b(def)o(ault)208 2195 y(implementations)16 b(of)i FJ(astimezone\(\))f FN(and)h FJ(fromutc\(\))f FN(may)h(not)g(produce)f(the)h(result)h(you)e (w)o(ant)i(if)g(the)f(result)h(is)g(one)208 2294 y(of)g(the)i(hours)e (straddling)g(the)h(moment)f(the)h(standard)f(of)n(fset)h(changes.)208 2424 y(Skipping)e(code)i(for)f(error)g(cases,)i(the)f(def)o(ault)g FJ(fromutc\(\))f FN(implementation)f(acts)j(lik)o(e:)533 2644 y FA(def)45 b(fromutc\(self,)d(dt\):)713 2736 y(#)i(raise)g (ValueError)g(error)g(if)g(dt.tzinfo)f(is)i(not)f(self)713 2827 y(dtoff)g(=)g(dt.utcoffset\(\))713 2918 y(dtdst)g(=)g(dt.dst\(\)) 713 3010 y(#)g(raise)g(ValueError)g(if)g(dtoff)g(is)h(None)f(or)g (dtdst)g(is)h(None)713 3101 y(delta)f(=)g(dtoff)g(-)h(dtdst)89 b(#)45 b(this)f(is)g(self's)g(standard)g(offset)713 3192 y(if)g(delta:)892 3283 y(dt)h(+=)f(delta)134 b(#)44 b(convert)g(to)h (standard)e(local)h(time)892 3375 y(dtdst)g(=)h(dt.dst\(\))892 3466 y(#)g(raise)f(ValueError)f(if)h(dtdst)g(is)h(None)713 3557 y(if)f(dtdst:)892 3649 y(return)g(dt)g(+)h(dtdst)713 3740 y(else:)892 3831 y(return)f(dt)0 4126 y FN(Example)19 b FJ(tzinfo)h FN(classes:)236 4304 y FA(from)44 b(datetime)g(import)g (tzinfo,)f(timedelta,)g(datetime)236 4487 y(ZERO)h(=)h(timedelta\(0\)) 236 4578 y(HOUR)f(=)h(timedelta\(hours=1\))236 4761 y(#)g(A)g(UTC)f (class.)236 4943 y(class)g(UTC\(tzinfo\):)416 5035 y("""UTC""")416 5217 y(def)g(utcoffset\(self,)e(dt\):)595 5309 y(return)i(ZERO)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2093 b(109)p eop end %%Page: 110 122 TeXDict begin 110 121 bop 416 83 a FA(def)44 b(tzname\(self,)f(dt\):) 595 174 y(return)h("UTC")416 357 y(def)g(dst\(self,)f(dt\):)595 448 y(return)h(ZERO)236 631 y(utc)h(=)f(UTC\(\))236 814 y(#)h(A)g(class)f(building)f(tzinfo)h(objects)g(for)g(fixed-offset)f (time)h(zones.)236 905 y(#)h(Note)f(that)g(FixedOffset\(0,)f("UTC"\))h (is)g(a)h(different)e(way)h(to)h(build)f(a)236 996 y(#)h(UTC)f(tzinfo)g (object.)236 1179 y(class)g(FixedOffset\(tzinfo\):)416 1270 y("""Fixed)f(offset)h(in)g(minutes)g(east)g(from)g(UTC.""")416 1453 y(def)g(__init__\(self,)e(offset,)i(name\):)595 1544 y(self.__offset)f(=)h(timedelta\(minutes)e(=)j(offset\))595 1636 y(self.__name)e(=)i(name)416 1818 y(def)f(utcoffset\(self,)e (dt\):)595 1910 y(return)i(self.__offset)416 2092 y(def)g (tzname\(self,)f(dt\):)595 2183 y(return)h(self.__name)416 2366 y(def)g(dst\(self,)f(dt\):)595 2457 y(return)h(ZERO)236 2640 y(#)h(A)g(class)f(capturing)f(the)h(platform's)f(idea)h(of)h (local)f(time.)236 2823 y(import)g(time)g(as)h(_time)236 3005 y(STDOFFSET)f(=)g(timedelta\(seconds)e(=)j(-_time.timezone\))236 3097 y(if)g(_time.daylight:)416 3188 y(DSTOFFSET)e(=)i (timedelta\(seconds)d(=)i(-_time.altzone\))236 3279 y(else:)416 3371 y(DSTOFFSET)f(=)i(STDOFFSET)236 3553 y(DSTDIFF)f(=)h(DSTOFFSET)e (-)i(STDOFFSET)236 3736 y(class)f(LocalTimezone\(tzinfo\):)416 3919 y(def)g(utcoffset\(self,)e(dt\):)595 4010 y(if)i (self._isdst\(dt\):)774 4101 y(return)g(DSTOFFSET)595 4193 y(else:)774 4284 y(return)g(STDOFFSET)416 4467 y(def)g(dst\(self,) f(dt\):)595 4558 y(if)h(self._isdst\(dt\):)774 4649 y(return)g(DSTDIFF) 595 4741 y(else:)774 4832 y(return)g(ZERO)416 5015 y(def)g (tzname\(self,)f(dt\):)595 5106 y(return)h (_time.tzname[self._isdst\(dt\)])416 5289 y(def)g(_isdst\(self,)f (dt\):)595 5380 y(tt)h(=)h(\(dt.year,)e(dt.month,)h(dt.day,)p 0 5549 3901 4 v 0 5649 a FI(110)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 111 123 TeXDict begin 111 122 bop 864 83 a FA(dt.hour,)43 b(dt.minute,)h (dt.second,)864 174 y(dt.weekday\(\),)f(0,)h(-1\))595 266 y(stamp)g(=)h(_time.mktime\(tt\))595 357 y(tt)f(=)h (_time.localtime\(stamp\))595 448 y(return)f(tt.tm_isdst)f(>)h(0)236 631 y(Local)g(=)h(LocalTimezone\(\))236 905 y(#)g(A)g(complete)e (implementation)g(of)h(current)g(DST)g(rules)g(for)g(major)g(US)h(time) f(zones.)236 1088 y(def)h(first_sunday_on_or_after\(dt\):)416 1179 y(days_to_go)e(=)h(6)h(-)g(dt.weekday\(\))416 1270 y(if)f(days_to_go:)595 1362 y(dt)g(+=)h(timedelta\(days_to_go\))416 1453 y(return)e(dt)236 1727 y(#)i(US)f(DST)h(Rules)236 1818 y(#)236 1910 y(#)g(This)f(is)h(a)f(simplified)f(\(i.e.,)h(wrong)g (for)g(a)h(few)f(cases\))g(set)h(of)f(rules)g(for)g(US)236 2001 y(#)h(DST)f(start)g(and)h(end)f(times.)g(For)g(a)h(complete)e(and) h(up-to-date)g(set)g(of)g(DST)h(rules)236 2092 y(#)g(and)f(timezone)g (definitions,)f(visit)h(the)g(Olson)g(Database)f(\(or)i(try)f(pytz\):) 236 2183 y(#)h(http://www.twinsun.com/tz/tz-link.htm)236 2275 y(#)g(http://sourceforge.net/projects/pytz/)38 b(\(might)44 b(not)h(be)f(up-to-date\))236 2366 y(#)236 2457 y(#)h(In)f(the)h(US,)f (since)g(2007,)g(DST)g(starts)g(at)h(2am)f(\(standard)f(time\))h(on)h (the)f(second)236 2549 y(#)h(Sunday)f(in)g(March,)g(which)g(is)h(the)f (first)g(Sunday)g(on)g(or)h(after)f(Mar)g(8.)236 2640 y(DSTSTART_2007)f(=)i(datetime\(1,)e(3,)h(8,)h(2\))236 2731 y(#)g(and)f(ends)g(at)h(2am)f(\(DST)g(time;)g(1am)h(standard)e (time\))h(on)h(the)f(first)g(Sunday)g(of)g(Nov.)236 2823 y(DSTEND_2007)f(=)i(datetime\(1,)e(11,)h(1,)h(1\))236 2914 y(#)g(From)f(1987)g(to)h(2006,)f(DST)g(used)g(to)h(start)f(at)g (2am)g(\(standard)g(time\))g(on)g(the)h(first)236 3005 y(#)g(Sunday)f(in)g(April)g(and)h(to)f(end)g(at)h(2am)f(\(DST)g(time;)g (1am)h(standard)e(time\))h(on)h(the)f(last)236 3097 y(#)h(Sunday)f(of)g (October,)g(which)g(is)g(the)h(first)e(Sunday)h(on)h(or)f(after)g(Oct)h (25.)236 3188 y(DSTSTART_1987_2006)d(=)j(datetime\(1,)e(4,)h(1,)h(2\)) 236 3279 y(DSTEND_1987_2006)d(=)j(datetime\(1,)e(10,)h(25,)h(1\))236 3371 y(#)g(From)f(1967)g(to)h(1986,)f(DST)g(used)g(to)h(start)f(at)g (2am)g(\(standard)g(time\))g(on)g(the)h(last)236 3462 y(#)g(Sunday)f(in)g(April)g(\(the)g(one)h(on)f(or)h(after)f(April)g (24\))g(and)g(to)h(end)f(at)h(2am)f(\(DST)g(time;)236 3553 y(#)h(1am)f(standard)g(time\))g(on)g(the)h(last)f(Sunday)f(of)i (October,)e(which)h(is)h(the)f(first)g(Sunday)236 3645 y(#)h(on)f(or)h(after)f(Oct)g(25.)236 3736 y(DSTSTART_1967_1986)e(=)j (datetime\(1,)e(4,)h(24,)g(2\))236 3827 y(DSTEND_1967_1986)e(=)j (DSTEND_1987_2006)236 4010 y(class)f(USTimeZone\(tzinfo\):)416 4193 y(def)g(__init__\(self,)e(hours,)i(reprname,)f(stdname,)h (dstname\):)595 4284 y(self.stdoffset)e(=)j(timedelta\(hours=hours\)) 595 4375 y(self.reprname)e(=)h(reprname)595 4467 y(self.stdname)f(=)h (stdname)595 4558 y(self.dstname)f(=)h(dstname)416 4741 y(def)g(__repr__\(self\):)595 4832 y(return)g(self.reprname)416 5015 y(def)g(tzname\(self,)f(dt\):)595 5106 y(if)h(self.dst\(dt\):)774 5197 y(return)g(self.dstname)595 5289 y(else:)774 5380 y(return)g(self.stdname)p 0 5549 3901 4 v 0 5649 a FI(5.1.)52 b FJ(datetime)22 b FI(\227)h(Basic)g(date)h(and)f(time)h(types)2093 b(111)p eop end %%Page: 112 124 TeXDict begin 112 123 bop 416 174 a FA(def)44 b(utcoffset\(self,)e (dt\):)595 266 y(return)i(self.stdoffset)e(+)j(self.dst\(dt\))416 448 y(def)f(dst\(self,)f(dt\):)595 540 y(if)h(dt)h(is)f(None)h(or)f (dt.tzinfo)f(is)i(None:)774 631 y(#)g(An)f(exception)g(may)g(be)h (sensible)e(here,)h(in)g(one)h(or)f(both)g(cases.)774 722 y(#)h(It)f(depends)g(on)h(how)f(you)g(want)g(to)h(treat)f(them.)89 b(The)44 b(default)774 814 y(#)h(fromutc\(\))e(implementation)g (\(called)g(by)i(the)f(default)g(astimezone\(\))774 905 y(#)h(implementation\))d(passes)i(a)h(datetime)e(with)h(dt.tzinfo)g(is) g(self.)774 996 y(return)g(ZERO)595 1088 y(assert)g(dt.tzinfo)f(is)i (self)595 1270 y(#)g(Find)f(start)g(and)g(end)g(times)g(for)h(US)f (DST.)g(For)h(years)f(before)f(1967,)h(return)595 1362 y(#)h(ZERO)f(for)g(no)h(DST.)595 1453 y(if)f(2006)h(<)f(dt.year:)774 1544 y(dststart,)g(dstend)f(=)i(DSTSTART_2007,)d(DSTEND_2007)595 1636 y(elif)i(1986)g(<)h(dt.year)f(<)g(2007:)774 1727 y(dststart,)g(dstend)f(=)i(DSTSTART_1987_2006,)d(DSTEND_1987_2006)595 1818 y(elif)i(1966)g(<)h(dt.year)f(<)g(1987:)774 1910 y(dststart,)g(dstend)f(=)i(DSTSTART_1967_1986,)d(DSTEND_1967_1986)595 2001 y(else:)774 2092 y(return)i(ZERO)595 2275 y(start)g(=)h (first_sunday_on_or_after\(dststart.re)o(place\()o(year=d)o(t.year)o (\)\))595 2366 y(end)f(=)h(first_sunday_on_or_after\(dstend.replac)o (e\(year)o(=dt.ye)o(ar\)\))595 2549 y(#)g(Can't)f(compare)f(naive)h(to) h(aware)f(objects,)f(so)i(strip)f(the)g(timezone)f(from)595 2640 y(#)i(dt)f(first.)595 2731 y(if)g(start)g(<=)h (dt.replace\(tzinfo=None\))c(<)j(end:)774 2823 y(return)g(HOUR)595 2914 y(else:)774 3005 y(return)g(ZERO)236 3188 y(Eastern)89 b(=)44 b(USTimeZone\(-5,)f("Eastern",)88 b("EST",)44 b("EDT"\))236 3279 y(Central)89 b(=)44 b(USTimeZone\(-6,)f("Central",) 88 b("CST",)44 b("CDT"\))236 3371 y(Mountain)g(=)g(USTimeZone\(-7,)f ("Mountain",)g("MST",)h("MDT"\))236 3462 y(Pacific)89 b(=)44 b(USTimeZone\(-8,)f("Pacific",)88 b("PST",)44 b("PDT"\))0 3659 y FN(Note)30 b(that)g(there)f(are)g(una)n(v)n(oidable) f(subtleties)i(twice)g(per)g(year)f(in)h(a)g FJ(tzinfo)f FN(subclass)h(accounting)e(for)h(both)g(standard)f(and)0 3758 y(daylight)22 b(time,)i(at)f(the)h(DST)f(transition)g(points.)33 b(F)o(or)23 b(concreteness,)f(consider)g(US)i(Eastern)f(\(UTC)g (-0500\),)f(where)g(EDT)h(be)o(gins)0 3858 y(the)g(minute)e(after)h (1:59)g(\(EST\))g(on)g(the)h(\002rst)g(Sunday)e(in)i(April,)f(and)g (ends)g(the)h(minute)f(after)g(1:59)g(\(EDT\))f(on)h(the)h(last)g (Sunday)e(in)0 3958 y(October:)416 4196 y FA(UTC)134 b(3:MM)89 b(4:MM)g(5:MM)g(6:MM)g(7:MM)f(8:MM)416 4287 y(EST)h(22:MM)44 b(23:MM)89 b(0:MM)g(1:MM)g(2:MM)f(3:MM)416 4378 y(EDT)h(23:MM)g(0:MM)g(1:MM)g(2:MM)g(3:MM)f(4:MM)326 4561 y(start)h(22:MM)44 b(23:MM)89 b(0:MM)g(1:MM)g(3:MM)f(4:MM)416 4744 y(end)h(23:MM)g(0:MM)g(1:MM)g(1:MM)g(2:MM)f(3:MM)0 5030 y FN(When)18 b(DST)g(starts)h(\(the)f(\224start\224)g(line\),)g (the)g(local)g(w)o(all)h(clock)f(leaps)g(from)f(1:59)g(to)h(3:00.)24 b(A)18 b(w)o(all)h(time)f(of)g(the)g(form)f(2:MM)h(doesn')o(t)0 5130 y(really)27 b(mak)o(e)g(sense)h(on)f(that)g(day)-5 b(,)28 b(so)g FJ(astimezone\(Eastern\))c FN(w)o(on')o(t)j(deli)n(v)o (er)f(a)i(result)f(with)g FJ(hour)50 b(==)f(2)28 b FN(on)f(the)g(day)0 5229 y(DST)19 b(be)o(gins.)k(In)18 b(order)f(for)h FJ(astimezone\(\))f FN(to)h(mak)o(e)g(this)h(guarantee,)e(the)h FJ(rzinfo.dst\(\))f FN(method)g(must)h(consider)f(times)0 5329 y(in)j(the)h(\224missing)f (hour\224)e(\(2:MM)i(for)f(Eastern\))h(to)g(be)g(in)h(daylight)e(time.) p 0 5549 3901 4 v 0 5649 a FI(112)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 113 125 TeXDict begin 113 124 bop 0 83 a FN(When)20 b(DST)g(ends)f(\(the)h (\224end\224)f(line\),)g(there')-5 b(s)20 b(a)g(potentially)f(w)o(orse) h(problem:)j(there')-5 b(s)20 b(an)g(hour)e(that)i(can')o(t)f(be)h (spelled)f(unambigu-)0 183 y(ously)25 b(in)g(local)g(w)o(all)g(time:)36 b(the)25 b(last)h(hour)d(of)i(daylight)f(time.)40 b(In)24 b(Eastern,)i(that')-5 b(s)26 b(times)f(of)g(the)g(form)f(5:MM)h(UTC)g (on)g(the)g(day)0 282 y(daylight)f(time)i(ends.)40 b(The)25 b(local)g(w)o(all)h(clock)f(leaps)h(from)e(1:59)h(\(daylight)e(time\))j (back)e(to)i(1:00)e(\(standard)g(time\))h(again.)40 b(Local)0 382 y(times)17 b(of)g(the)g(form)f(1:MM)g(are)h(ambiguous.)22 b FJ(astimezone\(\))15 b FN(mimics)i(the)g(local)g(clock')-5 b(s)16 b(beha)n(vior)g(by)g(mapping)f(tw)o(o)i(adjacent)0 482 y(UTC)k(hours)e(into)h(the)g(same)g(local)g(hour)f(then.)24 b(In)c(the)g(Eastern)f(e)o(xample,)g(UTC)h(times)h(of)f(the)g(form)f (5:MM)h(and)f(6:MM)h(both)f(map)0 581 y(to)28 b(1:MM)f(when)g(con)m(v)o (erted)d(to)k(Eastern.)46 b(In)27 b(order)f(for)h FJ(astimezone\(\))f FN(to)i(mak)o(e)f(this)h(guarantee,)f(the)g FJ(tzinfo.dst\(\))0 681 y FN(method)20 b(must)i(consider)f(times)h(in)g(the)f(\224repeated) g(hour\224)f(to)i(be)g(in)g(standard)e(time.)30 b(This)22 b(is)g(easily)g(arranged,)e(as)j(in)e(the)h(e)o(xample,)0 780 y(by)e(e)o(xpressing)e(DST)j(switch)f(times)h(in)f(the)h(time)f (zone')-5 b(s)20 b(standard)f(local)h(time.)0 927 y(Applications)e (that)i(can')o(t)e(bear)h(such)g(ambiguities)g(should)f(a)n(v)n(oid)h (using)g(hybrid)e FJ(tzinfo)i FN(subclasses;)h(there)f(are)h(no)f (ambiguities)0 1027 y(when)k(using)g(UTC,)i(or)e(an)o(y)g(other)g (\002x)o(ed-of)n(fset)f FJ(tzinfo)h FN(subclass)h(\(such)f(as)i(a)f (class)h(representing)d(only)h(EST)h(\(\002x)o(ed)f(of)n(fset)g(-5)0 1127 y(hours\),)c(or)h(only)f(EDT)h(\(\002x)o(ed)f(of)n(fset)h(-4)g (hours\)\).)0 1407 y Fv(5.1.7)100 b Fm(strftime\(\))26 b Fv(Beha)n(vior)0 1609 y FJ(date)p FN(,)d FJ(datetime)p FN(,)e(and)h FJ(time)g FN(objects)g(all)h(support)e(a)i FJ(strftime\()p FK(format)q FJ(\))e FN(method,)h(to)g(create)g(a)h (string)f(representing)f(the)0 1709 y(time)g(under)e(the)h(control)f (of)h(an)h(e)o(xplicit)e(format)h(string.)25 b(Broadly)19 b(speaking,)g FJ(d.strftime\(fmt\))f FN(acts)j(lik)o(e)g(the)g FJ(time)f FN(mod-)0 1809 y(ule')-5 b(s)21 b FJ(time.strftime\(fmt,)46 b(d.timetuple\(\)\))18 b FN(although)h(not)g(all)i(objects)f(support)f (a)i FJ(timetuple\(\))d FN(method.)0 1956 y(F)o(or)i FJ(time)g FN(objects,)g(the)g(format)f(codes)h(for)g(year)m(,)f(month,) g(and)h(day)g(should)f(not)h(be)g(used,)g(as)h(time)f(objects)h(ha)n(v) o(e)e(no)h(such)g(v)n(alues.)0 2055 y(If)g(the)o(y')l(re)f(used)g(an)o (yw)o(ay)-5 b(,)19 b FJ(1900)h FN(is)h(substituted)e(for)h(the)g(year)m (,)f(and)h FJ(0)g FN(for)g(the)g(month)f(and)h(day)-5 b(.)0 2202 y(F)o(or)18 b FJ(date)g FN(objects,)g(the)h(format)e(codes)h (for)f(hours,)h(minutes,)g(and)g(seconds)f(should)h(not)g(be)g(used,)g (as)h FJ(date)f FN(objects)g(ha)n(v)o(e)g(no)g(such)0 2302 y(v)n(alues.)25 b(If)20 b(the)o(y')l(re)e(used)i(an)o(yw)o(ay)-5 b(,)18 b FJ(0)j FN(is)g(substituted)e(for)h(them.)0 2449 y(F)o(or)g(a)g(nai)n(v)o(e)g(object,)f(the)h FJ(\045z)h FN(and)e FJ(\045Z)i FN(format)e(codes)h(are)g(replaced)f(by)g(empty)h (strings.)0 2595 y(F)o(or)g(an)g(a)o(w)o(are)g(object:)66 2798 y FJ(\045z)42 b(utcoffset\(\))24 b FN(is)i(transformed)d(into)j(a) g(5-character)d(string)i(of)h(the)f(form)g(+HHMM)g(or)g(-HHMM,)g(where) g(HH)h(is)h(a)f(2-)208 2898 y(digit)k(string)g(gi)n(ving)e(the)j (number)d(of)i(UTC)h(of)n(fset)f(hours,)h(and)f(MM)g(is)i(a)e(2-digit)f (string)h(gi)n(ving)f(the)i(number)d(of)i(UTC)208 2997 y(of)n(fset)21 b(minutes.)28 b(F)o(or)22 b(e)o(xample,)e(if)i FJ(utcoffset\(\))e FN(returns)h FJ(timedelta\(hours=-3,)46 b(minutes=-30\))p FN(,)20 b FJ(\045z)i FN(is)208 3097 y(replaced)d(with)h(the)g(string)g FJ('-0330')p FN(.)66 3252 y FJ(\045Z)42 b FN(If)17 b FJ(tzname\(\))g FN(returns)g FJ(None)p FN(,)h FJ(\045Z)f FN(is)i(replaced)e(by)g(an)g(empty)g (string.)24 b(Otherwise)18 b FJ(\045Z)f FN(is)i(replaced)e(by)g(the)h (returned)d(v)n(alue,)208 3352 y(which)k(must)h(be)h(a)f(string.)0 3555 y(The)39 b(full)g(set)i(of)e(format)f(codes)h(supported)e(v)n (aries)i(across)h(platforms,)j(because)38 b(Python)h(calls)h(the)f (platform)f(C)i(library')-5 b(s)0 3654 y FJ(strftime\(\))25 b FN(function,)h(and)g(platform)e(v)n(ariations)i(are)g(common.)41 b(The)26 b(documentation)e(for)i(Python')-5 b(s)25 b FJ(time)h FN(module)f(lists)0 3754 y(the)31 b(format)f(codes)h(that)g (the)g(C)h(standard)d(\(1989)h(v)o(ersion\))f(requires,)k(and)d(those)h (w)o(ork)f(on)h(all)g(platforms)f(with)h(a)h(standard)e(C)0 3854 y(implementation.)23 b(Note)d(that)g(the)g(1999)f(v)o(ersion)g(of) h(the)g(C)h(standard)e(added)g(additional)g(format)g(codes.)0 4000 y(The)j(e)o(xact)g(range)f(of)i(years)f(for)g(which)g FJ(strftime\(\))f FN(w)o(orks)h(also)h(v)n(aries)f(across)g(platforms.) 31 b(Re)o(gardless)21 b(of)i(platform,)e(years)0 4100 y(before)e(1900)g(cannot)g(be)h(used.)0 4423 y FE(5.2)121 b Fx(calendar)31 b FE(\227)i(Gener)o(al)h(calendar-related)i(functions) 0 4655 y FN(This)31 b(module)e(allo)n(ws)i(you)f(to)h(output)e (calendars)h(lik)o(e)h(the)h(U)t FH(N)t(I)t(X)i FL(cal)d FN(program,)g(and)f(pro)o(vides)f(additional)g(useful)h(functions)0 4755 y(related)22 b(to)i(the)f(calendar)-5 b(.)32 b(By)24 b(def)o(ault,)f(these)g(calendars)f(ha)n(v)o(e)g(Monday)g(as)h(the)g (\002rst)h(day)f(of)f(the)i(week,)f(and)f(Sunday)g(as)i(the)f(last)0 4855 y(\(the)c(European)d(con)m(v)o(ention\).)21 b(Use)f FJ(setfirstweekday\(\))d FN(to)i(set)g(the)h(\002rst)f(day)g(of)f(the)h (week)g(to)g(Sunday)f(\(6\))g(or)h(to)g(an)o(y)f(other)0 4954 y(weekday)-5 b(.)23 b(P)o(arameters)d(that)g(specify)f(dates)i (are)f(gi)n(v)o(en)f(as)i(inte)o(gers.)0 5101 y(Most)28 b(of)f(these)g(functions)f(and)h(classses)i(rely)e(on)g(the)h FJ(datetime)e FN(module)g(which)h(uses)h(an)f(idealized)g(calendar)m(,) g(the)h(current)0 5201 y(Gre)o(gorian)20 b(calendar)i(inde\002nitely)f (e)o(xtended)f(in)j(both)f(directions.)30 b(This)23 b(matches)f(the)h (de\002nition)e(of)h(the)h(\224proleptic)e(Gre)o(gorian\224)0 5300 y(calendar)e(in)h(Dersho)n(witz)f(and)g(Reingold')-5 b(s)20 b(book)e(\224Calendrical)h(Calculations\224,)h(where)f(it')-5 b(s)21 b(the)f(base)g(calendar)f(for)g(all)h(computa-)0 5400 y(tions.)p 0 5549 3901 4 v 0 5649 a FI(5.2.)52 b FJ(calendar)22 b FI(\227)h(Gener)o(al)g(calendar-related)h(functions) 1772 b(113)p eop end %%Page: 114 126 TeXDict begin 114 125 bop 0 83 a FL(class)21 b FD(Calendar)p FJ(\()p FC([)p FK(\002r)o(stweekday)12 b FC(])p FJ(\))208 183 y FN(Creates)23 b(a)f FJ(Calendar)g FN(object.)31 b FK(\002r)o(stweekday)22 b FN(is)i(an)e(inte)o(ger)f(specifying)g(the) i(\002rst)g(day)f(of)g(the)h(week.)31 b FJ(0)23 b FN(is)g(Monday)e (\(the)208 282 y(def)o(ault\),)d FJ(6)j FN(is)g(Sunday)-5 b(.)208 415 y(A)22 b FJ(Calendar)f FN(object)g(pro)o(vides)f(se)n(v)o (eral)i(methods)e(that)i(can)g(be)g(used)f(for)h(preparing)d(the)j (calendar)f(data)g(for)h(formatting.)208 515 y(This)e(class)h(doesn')o (t)e(do)h(an)o(y)f(formatting)f(itself.)26 b(This)20 b(is)h(the)f(job)g(of)g(subclasses.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.5.)0 662 y FJ(Calendar)g FN(instances)h(ha)n(v)o(e)g(the)g(follo)n (wing)f(methods:)0 808 y FD(iterweekdays)p FJ(\()p FK(weekday)p FJ(\))208 908 y FN(Return)f(an)g(iterator)g(for)f(the)i(week)f(day)g (numbers)f(that)h(will)h(be)g(used)f(for)f(one)h(week.)24 b(The)18 b(\002rst)i(v)n(alue)d(from)h(the)g(iterator)g(will)208 1008 y(be)i(the)g(same)g(as)h(the)f(v)n(alue)g(of)g(the)g FJ(firstweekday)f FN(property)-5 b(.)0 1155 y FD(itermonthdates)p FJ(\()p FK(year)c(,)17 b(month)p FJ(\))208 1254 y FN(Return)40 b(an)h(iterator)g(for)f(the)h(month)f FK(month)g FN(\(1-12\))g(in)h (the)g(year)f FK(year)r FN(.)88 b(This)41 b(iterator)g(will)h(return)e (all)h(days)g(\(as)208 1354 y FJ(datetime.date)27 b FN(objects\))h(for) h(the)g(month)f(and)g(all)i(days)f(before)f(the)h(start)h(of)e(the)h (month)f(or)h(after)g(the)g(end)g(of)g(the)208 1453 y(month)19 b(that)h(are)g(required)e(to)j(get)f(a)g(complete)g(week.)0 1600 y FD(itermonthdays2)p FJ(\()p FK(year)-9 b(,)17 b(month)p FJ(\))208 1700 y FN(Return)22 b(an)g(iterator)h(for)f(the)g (month)g FK(month)g FN(in)h(the)f(year)g FK(year)j FN(similar)e(to)g FJ(itermonthdates\(\))p FN(.)30 b(Days)23 b(returned)e(will)208 1800 y(be)f(tuples)g(consisting)f(of)h(a)h(day)e(number)g(and)g(a)i (week)f(day)g(number)-5 b(.)0 1946 y FD(itermonthdays)p FJ(\()p FK(year)c(,)17 b(month)p FJ(\))208 2046 y FN(Return)22 b(an)g(iterator)h(for)f(the)g(month)g FK(month)g FN(in)h(the)f(year)g FK(year)j FN(similar)e(to)g FJ(itermonthdates\(\))p FN(.)30 b(Days)23 b(returned)e(will)208 2146 y(simply)e(be)i(day)e(numbers.)0 2293 y FD(monthdatescalendar)p FJ(\()p FK(year)-9 b(,)16 b(month)p FJ(\))208 2392 y FN(Return)42 b(a)i(list)g(of)e(the)h(weeks)g (in)h(the)f(month)e FK(month)i FN(of)f(the)h FK(year)i FN(as)f(full)f(weeks.)93 b(W)-7 b(eeks)44 b(are)f(lists)i(of)d(se)n(v)o (en)208 2492 y FJ(datetime.date)18 b FN(objects.)0 2639 y FD(monthdays2calendar)p FJ(\()p FK(year)-9 b(,)16 b(month)p FJ(\))208 2738 y FN(Return)21 b(a)i(list)g(of)f(the)h(weeks)f(in)h(the) f(month)f FK(month)g FN(of)h(the)h FK(year)h FN(as)f(full)f(weeks.)31 b(W)-7 b(eeks)23 b(are)g(lists)g(of)f(se)n(v)o(en)g(tuples)g(of)g(day) 208 2838 y(numbers)c(and)i(weekday)f(numbers.)0 2985 y FD(monthdayscalendar)p FJ(\()p FK(year)-9 b(,)16 b(month)p FJ(\))208 3084 y FN(Return)j(a)i(list)g(of)f(the)g(weeks)h(in)f(the)g (month)f FK(month)g FN(of)h(the)g FK(year)j FN(as)e(full)f(weeks.)25 b(W)-7 b(eeks)21 b(are)f(lists)h(of)f(se)n(v)o(en)g(day)f(numbers.)0 3231 y FD(yeardatescalendar)p FJ(\()p FK(year)r FC([)p FK(,)d(width)c FC(])p FJ(\))208 3331 y FN(Return)18 b(the)h(data)f(for) h(the)f(speci\002ed)h(year)f(ready)g(for)g(formatting.)23 b(The)18 b(return)g(v)n(alue)g(is)i(a)f(list)h(of)f(month)e(ro)n(ws.)24 b(Each)19 b(month)208 3431 y(ro)n(w)h(contains)f(up)h(to)h FK(width)g FN(months)e(\(def)o(aulting)g(to)h(3\).)26 b(Each)20 b(month)f(contains)h(between)f(4)i(and)f(6)g(weeks)h(and)f (each)g(week)208 3530 y(contains)f(1\2267)g(days.)25 b(Days)20 b(are)g FJ(datetime.date)f FN(objects.)0 3677 y FD(yeardays2calendar)p FJ(\()p FK(year)r FC([)p FK(,)d(width)c FC(])p FJ(\))208 3777 y FN(Return)22 b(the)h(data)g(for)g(the)g (speci\002ed)f(year)h(ready)f(for)g(formatting)f(\(similar)i(to)g FJ(yeardatescalendar\(\))p FN(\).)31 b(Entries)22 b(in)208 3876 y(the)e(week)g(lists)h(are)f(tuples)g(of)g(day)g(numbers)f(and)g (weekday)g(numbers.)24 b(Day)c(numbers)e(outside)i(this)h(month)e(are)h (zero.)0 4023 y FD(yeardayscalendar)p FJ(\()p FK(year)r FC([)p FK(,)d(width)12 b FC(])p FJ(\))208 4123 y FN(Return)22 b(the)h(data)g(for)g(the)g(speci\002ed)f(year)h(ready)f(for)g (formatting)f(\(similar)i(to)g FJ(yeardatescalendar\(\))p FN(\).)31 b(Entries)22 b(in)208 4222 y(the)e(week)g(lists)h(are)f(day)g (numbers.)j(Day)e(numbers)d(outside)i(this)h(month)d(are)j(zero.)0 4369 y FL(class)g FD(TextCalendar)p FJ(\()p FC([)p FK(\002r)o (stweekday)12 b FC(])p FJ(\))208 4469 y FN(This)20 b(class)h(can)f(be)g (used)g(to)g(generate)f(plain)h(te)o(xt)g(calendars.)208 4602 y(Ne)n(w)g(in)g(v)o(ersion)f(2.5.)0 4749 y FJ(TextCalendar)g FN(instances)h(ha)n(v)o(e)f(the)h(follo)n(wing)f(methods:)0 4896 y FD(formatmonth)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)h(w)p FC([)p FK(,)j(l)12 b FC(])g(])p FJ(\))208 4995 y FN(Return)25 b(a)i(month')-5 b(s)25 b(calendar)g(in)i(a)f(multi-line)g(string.)42 b(If)26 b FK(w)i FN(is)f(pro)o(vided,)e(it)i(speci\002es)f(the)h(width)f(of)g (the)g(date)g(columns,)208 5095 y(which)c(are)h(centered.)33 b(If)23 b FK(l)h FN(is)g(gi)n(v)o(en,)e(it)i(speci\002es)g(the)f (number)e(of)i(lines)h(that)f(each)g(week)g(will)h(use.)34 b(Depends)22 b(on)h(the)g(\002rst)208 5194 y(weekday)18 b(as)j(speci\002ed)f(in)h(the)f(constructor)e(or)i(set)h(by)f(the)g FJ(setfirstweekday\(\))d FN(method.)0 5341 y FD(prmonth)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)i(w)p FC([)p FK(,)h(l)12 b FC(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(114)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 115 127 TeXDict begin 115 126 bop 208 83 a FN(Print)20 b(a)g(month')-5 b(s)20 b(calendar)f(as)i(returned)d(by)i FJ(formatmonth\(\))p FN(.)0 230 y FD(formatyear)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)h(w)p FC([)p FK(,)j(l)p FC([)p FK(,)f(c)p FC([)p FK(,)g(m)12 b FC(])g(])g(])g(])p FJ(\))208 330 y FN(Return)18 b(a)h FK(m)p FN(-column)e(calendar)h(for)g (an)g(entire)h(year)f(as)i(a)f(multi-line)f(string.)24 b(Optional)18 b(parameters)f FK(w)p FN(,)j FK(l)p FN(,)f(and)g FK(c)g FN(are)g(for)f(date)208 429 y(column)e(width,)i(lines)h(per)f (week,)g(and)f(number)g(of)h(spaces)g(between)f(month)g(columns,)g (respecti)n(v)o(ely)-5 b(.)23 b(Depends)17 b(on)h(the)g(\002rst)208 529 y(weekday)25 b(as)i(speci\002ed)f(in)h(the)f(constructor)e(or)j (set)g(by)f(the)g FJ(setfirstweekday\(\))e FN(method.)42 b(The)27 b(earliest)f(year)g(for)208 628 y(which)19 b(a)i(calendar)e (can)h(be)g(generated)e(is)j(platform-dependent.)0 775 y FD(pryear)p FJ(\()p FK(the)n(year)r FC([)p FK(,)c(w)p FC([)p FK(,)k(l)p FC([)p FK(,)g(c)p FC([)p FK(,)f(m)12 b FC(])g(])g(])g(])p FJ(\))208 875 y FN(Print)20 b(the)g(calendar)f (for)g(an)i(entire)e(year)h(as)h(returned)d(by)i FJ(formatyear\(\))p FN(.)0 1022 y FL(class)h FD(HTMLCalendar)p FJ(\()p FC([)p FK(\002r)o(stweekday)12 b FC(])p FJ(\))208 1121 y FN(This)20 b(class)h(can)f(be)g(used)g(to)g(generate)f(HTML)h(calendars.)208 1254 y(Ne)n(w)g(in)g(v)o(ersion)f(2.5.)0 1401 y FJ(HTMLCalendar)g FN(instances)h(ha)n(v)o(e)f(the)h(follo)n(wing)f(methods:)0 1548 y FD(formatmonth)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)h(withyear)c FC(])p FJ(\))208 1648 y FN(Return)31 b(a)h(month')-5 b(s)31 b(calendar)f(as)j(an)e(HTML) h(table.)59 b(If)32 b FK(withyear)i FN(is)e(true)g(the)f(year)g(will)i (be)f(included)e(in)i(the)f(header)m(,)208 1747 y(otherwise)19 b(just)i(the)f(month)f(name)h(will)g(be)h(used.)0 1894 y FD(formatyear)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)h(width)12 b FC(])p FJ(\))208 1994 y FN(Return)19 b(a)i(year')-5 b(s)20 b(calendar)f(as)i(an)f(HTML)g(table.)25 b FK(width)20 b FN(\(def)o(aulting)e(to)j(3\))f(speci\002es)g(the)g (number)f(of)h(months)f(per)h(ro)n(w)-5 b(.)0 2141 y FD(formatyearpage)p FJ(\()p FK(the)n(year)c(,)16 b(themonth)p FC([)p FK(,)i(width)p FC([)p FK(,)i(css)p FC([)p FK(,)h(encoding)12 b FC(])g(])g(])p FJ(\))208 2240 y FN(Return)20 b(a)h(year')-5 b(s)20 b(calendar)f(as)i(a)g(complete)f(HTML)g(page.)25 b FK(width)c FN(\(def)o(aulting)d(to)j(3\))f(speci\002es)h(the)g (number)d(of)i(months)g(per)208 2340 y(ro)n(w)-5 b(.)35 b FK(css)25 b FN(is)g(the)g(name)e(for)h(the)g(cascading)f(style)h (sheet)g(to)h(be)f(used.)36 b FJ(None)24 b FN(can)g(be)g(passed)g(if)g (no)g(style)g(sheet)h(should)e(be)208 2439 y(used.)h FK(encoding)18 b FN(speci\002es)j(the)f(encoding)e(to)j(be)f(used)g (for)f(the)i(output)d(\(def)o(aulting)h(to)h(the)g(system)h(def)o(ault) e(encoding\).)0 2586 y FL(class)i FD(LocaleTextCalendar)p FJ(\()p FC([)p FK(\002r)o(stweekday)p FC([)p FK(,)16 b(locale)c FC(])g(])p FJ(\))208 2686 y FN(This)26 b(subclass)g(of)g FJ(TextCalendar)e FN(can)i(be)g(passed)g(a)g(locale)g(name)g(in)g(the)g (constructor)e(and)i(will)g(return)f(month)g(and)208 2786 y(weekday)i(names)h(in)g(the)h(speci\002ed)f(locale.)49 b(If)28 b(this)h(locale)g(includes)e(an)i(encoding)d(all)j(strings)f (containing)f(month)g(and)208 2885 y(weekday)18 b(names)i(will)h(be)f (returned)f(as)i(unicode.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 3032 y FL(class)i FD(LocaleHTMLCalendar)p FJ(\()p FC([)p FK(\002r)o(stweekday)p FC([)p FK(,)16 b(locale)c FC(])g(])p FJ(\))208 3132 y FN(This)26 b(subclass)g(of)g FJ(HTMLCalendar)e FN(can)i(be)g(passed)g(a)g(locale)g(name)g(in)g(the)g(constructor)e (and)i(will)g(return)f(month)g(and)208 3231 y(weekday)i(names)h(in)g (the)h(speci\002ed)f(locale.)49 b(If)28 b(this)h(locale)g(includes)e (an)i(encoding)d(all)j(strings)f(containing)f(month)g(and)208 3331 y(weekday)18 b(names)i(will)h(be)f(returned)f(as)i(unicode.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 3478 y(F)o(or)h(simple)g(te)o (xt)g(calendars)f(this)i(module)e(pro)o(vides)f(the)i(follo)n(wing)f (functions.)0 3625 y FD(setfirstweekday)p FJ(\()p FK(weekday)p FJ(\))208 3724 y FN(Sets)e(the)f(weekday)g(\()p FJ(0)g FN(is)h(Monday)-5 b(,)15 b FJ(6)i FN(is)h(Sunday\))c(to)j(start)g(each) f(week.)24 b(The)16 b(v)n(alues)g FJ(MONDAY)p FN(,)f FJ(TUESDAY)p FN(,)h FJ(WEDNESDAY)p FN(,)208 3824 y FJ(THURSDAY)p FN(,)24 b FJ(FRIDAY)p FN(,)i FJ(SATURDAY)p FN(,)e(and)i FJ(SUNDAY)f FN(are)h(pro)o(vided)e(for)h(con)m(v)o(enience.)39 b(F)o(or)26 b(e)o(xample,)g(to)g(set)h(the)f(\002rst)208 3924 y(weekday)18 b(to)j(Sunday:)444 4148 y FA(import)44 b(calendar)444 4239 y(calendar.setfirstweekday\(calendar.SUND)o(AY\)) 208 4395 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 4542 y FD(firstweekday)p FJ(\(\))208 4642 y FN(Returns)h(the)g(current)f (setting)h(for)f(the)i(weekday)d(to)j(start)f(each)g(week.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.0.)0 4789 y FD(isleap)p FJ(\()p FK(year)r FJ(\))208 4888 y FN(Returns)i FJ(True)g FN(if)g FK(year)i FN(is)f(a)g(leap)f(year)m(,)f(otherwise)h FJ(False)p FN(.)0 5035 y FD(leapdays)p FJ(\()p FK(y1,)e(y2)p FJ(\))208 5135 y FN(Returns)23 b(the)h(number)d(of)j(leap)f(years)g(in) h(the)g(range)e([)p FK(y1)p FN(.)12 b(.)g(.)g FK(y2)p FN(\),)24 b(where)f FK(y1)g FN(and)g FK(y2)h FN(are)f(years.)71 b(Changed)22 b(in)i(v)o(ersion)e(2.0:)208 5234 y(This)e(function)e (didn')o(t)h(w)o(ork)h(for)f(ranges)h(spanning)e(a)j(century)d(change)h (in)i(Python)e(1.5.2.)0 5381 y FD(weekday)p FJ(\()p FK(year)-9 b(,)18 b(month,)h(day)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(5.2.)52 b FJ(calendar)22 b FI(\227)h(Gener)o(al)g (calendar-related)h(functions)1772 b(115)p eop end %%Page: 116 128 TeXDict begin 116 127 bop 208 83 a FN(Returns)20 b(the)g(day)f(of)h (the)h(week)e(\()p FJ(0)i FN(is)g(Monday\))d(for)h FK(year)k FN(\()p FJ(1970)p FN(\226.)12 b(.)g(.)g(\),)19 b FK(month)g FN(\()p FJ(1)p FN(\226)p FJ(12)p FN(\),)g FK(day)h FN(\()p FJ(1)p FN(\226)p FJ(31)p FN(\).)0 230 y FD(weekheader)p FJ(\()p FK(n)p FJ(\))208 330 y FN(Return)f(a)i(header)e(containing)f (abbre)n(viated)g(weekday)h(names.)25 b FK(n)20 b FN(speci\002es)h(the) f(width)g(in)g(characters)f(for)h(one)f(weekday)-5 b(.)0 476 y FD(monthrange)p FJ(\()p FK(year)c(,)18 b(month)p FJ(\))208 576 y FN(Returns)i(weekday)e(of)i(\002rst)h(day)f(of)g(the)g (month)f(and)h(number)e(of)i(days)g(in)g(month,)f(for)g(the)i (speci\002ed)f FK(year)i FN(and)d FK(month)p FN(.)0 723 y FD(monthcalendar)p FJ(\()p FK(year)-9 b(,)17 b(month)p FJ(\))208 823 y FN(Returns)26 b(a)i(matrix)e(representing)f(a)j(month') -5 b(s)26 b(calendar)-5 b(.)45 b(Each)26 b(ro)n(w)h(represents)f(a)i (week;)i(days)d(outside)f(of)h(the)g(month)f(a)208 922 y(represented)18 b(by)i(zeros.)k(Each)c(week)g(be)o(gins)f(with)i (Monday)d(unless)i(set)h(by)f FJ(setfirstweekday\(\))p FN(.)0 1069 y FD(prmonth)p FJ(\()p FK(the)n(year)-9 b(,)17 b(themonth)p FC([)p FK(,)i(w)p FC([)p FK(,)h(l)12 b FC(])g(])p FJ(\))208 1169 y FN(Prints)20 b(a)h(month')-5 b(s)19 b(calendar)g(as)i(returned)d(by)i FJ(month\(\))p FN(.)0 1316 y FD(month)p FJ(\()p FK(the)n(year)-9 b(,)18 b(themonth)p FC([)p FK(,)g(w)p FC([)p FK(,)j(l)12 b FC(])g(])p FJ(\))208 1415 y FN(Returns)k(a)i(month')-5 b(s)16 b(calendar)g(in)h(a)h (multi-line)e(string)g(using)h(the)g FJ(formatmonth)f FN(of)g(the)h FJ(TextCalendar)f FN(class.)49 b(Ne)n(w)208 1515 y(in)20 b(v)o(ersion)f(2.0.)0 1662 y FD(prcal)p FJ(\()p FK(year)r FC([)p FK(,)g(w)p FC([)p FK(,)h(l)p FC([)p FK(c)12 b FC(])g(])g(])p FJ(\))208 1761 y FN(Prints)20 b(the)g(calendar)f(for)h(an)g(entire)g(year)f(as)i(returned)e(by)g FJ(calendar\(\))p FN(.)0 1908 y FD(calendar)p FJ(\()p FK(year)r FC([)p FK(,)f(w)p FC([)p FK(,)j(l)p FC([)p FK(c)12 b FC(])g(])g(])p FJ(\))208 2008 y FN(Returns)44 b(a)g(3-column)f(calendar)g(for)g(an)i(entire)e(year)h(as)h(a)g (multi-line)e(string)h(using)g(the)h FJ(formatyear)e FN(of)h(the)208 2107 y FJ(TextCalendar)18 b FN(class.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 2254 y FD(timegm)p FJ(\()p FK(tuple)p FJ(\))208 2354 y FN(An)28 b(unrelated)g(b)n(ut)h (handy)e(function)g(that)i(tak)o(es)g(a)g(time)h(tuple)e(such)h(as)g (returned)e(by)i(the)f FJ(gmtime\(\))g FN(function)g(in)h(the)208 2454 y FJ(time)i FN(module,)i(and)e(returns)f(the)i(corresponding)e(U)t FH(N)t(I)t(X)k FN(timestamp)e(v)n(alue,)h(assuming)e(an)g(epoch)g(of)g (1970,)i(and)e(the)208 2553 y(POSIX)20 b(encoding.)j(In)d(f)o(act,)g FJ(time.gmtime\(\))e FN(and)i FJ(timegm\(\))f FN(are)h(each)g(others')g (in)m(v)o(erse.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 2700 y(The)h FJ(calendar)f FN(module)g(e)o(xports)g(the)h(follo)n(wing) f(data)h(attrib)n(utes:)0 2847 y FD(day_name)208 2946 y FN(An)g(array)f(that)h(represents)g(the)g(days)g(of)g(the)g(week)g (in)g(the)g(current)f(locale.)0 3093 y FD(day_abbr)208 3193 y FN(An)h(array)f(that)h(represents)g(the)g(abbre)n(viated)e(days) i(of)g(the)g(week)g(in)g(the)g(current)f(locale.)0 3340 y FD(month_name)208 3439 y FN(An)g(array)f(that)h(represents)f(the)h (months)f(of)h(the)g(year)f(in)h(the)h(current)d(locale.)25 b(This)19 b(follo)n(ws)f(normal)g(con)m(v)o(ention)e(of)j(January)208 3539 y(being)g(month)g(number)f(1,)i(so)h(it)g(has)f(a)h(length)e(of)h (13)g(and)f FJ(month_name[0])g FN(is)i(the)f(empty)f(string.)0 3686 y FD(month_abbr)208 3786 y FN(An)d(array)g(that)h(represents)f (the)g(abbre)n(viated)f(months)g(of)i(the)g(year)f(in)g(the)h(current)f (locale.)23 b(This)17 b(follo)n(ws)f(normal)g(con)m(v)o(ention)208 3885 y(of)j(January)g(being)h(month)f(number)f(1,)i(so)h(it)f(has)h(a)g (length)e(of)h(13)g(and)f FJ(month_abbr[0])f FN(is)k(the)e(empty)f (string.)0 4032 y FL(See)i(Also:)0 4179 y FN(Module)e FJ(datetime)g FN(\(section)h(5.1\):)208 4279 y(Object-oriented)d (interf)o(ace)j(to)g(dates)g(and)g(times)h(with)f(similar)g (functionality)f(to)h(the)g FJ(time)g FN(module.)0 4425 y(Module)f FJ(time)h FN(\(section)g(14.2\):)208 4525 y(Lo)n(w-le)n(v)o(el)e(time)i(related)g(functions.)0 4853 y FE(5.3)121 b Fx(collections)30 b FE(\227)j(High-perf)l(or)s (mance)j(container)f(datatypes)0 5085 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 5232 y(This)28 b(module)f(implements)g (high-performance)c(container)j(datatypes.)48 b(Currently)-5 b(,)28 b(there)f(are)h(tw)o(o)g(datatypes,)h(deque)e(and)g(de-)0 5332 y(f)o(aultdict.)51 b(Future)28 b(additions)g(may)g(include)g (balanced)g(trees)h(and)g(ordered)e(dictionaries.)102 b(Changed)27 b(in)j(v)o(ersion)d(2.5:)i(Added)p 0 5549 3901 4 v 0 5649 a FI(116)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 117 129 TeXDict begin 117 128 bop 0 83 a FN(def)o(aultdict.)0 368 y Fv(5.3.1)100 b Fm(deque)27 b Fv(objects)0 566 y FD(deque)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 666 y FN(Returns)18 b(a)g(ne)n(w)g(deque)g(object)f (initialized)h(left-to-right)e(\(using)i FJ(append\(\))p FN(\))f(with)h(data)h(from)e FK(iter)o(able)p FN(.)24 b(If)18 b FK(iter)o(able)g FN(is)h(not)208 765 y(speci\002ed,)g(the)h (ne)n(w)g(deque)f(is)j(empty)-5 b(.)208 898 y(Deques)28 b(are)g(a)h(generalization)e(of)h(stacks)i(and)e(queues)g(\(the)g(name) g(is)i(pronounced)25 b(\223deck\224)i(and)i(is)g(short)f(for)h (\223double-)208 998 y(ended)22 b(queue\224\).)33 b(Deques)23 b(support)g(thread-safe,)f(memory)g(ef)n(\002cient)h(appends)f(and)h (pops)g(from)g(either)g(side)h(of)f(the)h(deque)208 1097 y(with)c(approximately)d(the)j(same)h FJ(O\(1\))f FN(performance)d(in)j (either)g(direction.)208 1230 y(Though)g FJ(list)j FN(objects)f (support)f(similar)i(operations,)f(the)o(y)g(are)g(optimized)g(for)g(f) o(ast)h(\002x)o(ed-length)d(operations)h(and)h(incur)208 1330 y FJ(O\(n\))h FN(memory)f(mo)o(v)o(ement)g(costs)i(for)f(`)p FJ(pop\(0\))p FN(')g(and)g(`)p FJ(insert\(0,)48 b(v\))p FN(')23 b(operations)f(which)i(change)e(both)h(the)h(size)208 1430 y(and)19 b(position)h(of)f(the)i(underlying)c(data)j (representation.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 1576 y(Deque)h(objects)h(support)f(the)h(follo)n(wing)f(methods:)0 1723 y FD(append)p FJ(\()p FK(x)p FJ(\))208 1823 y FN(Add)g FK(x)i FN(to)f(the)h(right)e(side)i(of)f(the)g(deque.)0 1970 y FD(appendleft)p FJ(\()p FK(x)p FJ(\))208 2069 y FN(Add)f FK(x)i FN(to)f(the)h(left)f(side)h(of)f(the)g(deque.)0 2216 y FD(clear)p FJ(\(\))208 2316 y FN(Remo)o(v)o(e)f(all)h(elements)g (from)f(the)i(deque)e(lea)n(ving)g(it)i(with)f(length)g(0.)0 2463 y FD(extend)p FJ(\()p FK(iter)o(able)p FJ(\))208 2562 y FN(Extend)f(the)h(right)f(side)i(of)f(the)g(deque)f(by)h (appending)d(elements)j(from)f(the)i(iterable)e(ar)o(gument.)0 2709 y FD(extendleft)p FJ(\()p FK(iter)o(able)p FJ(\))208 2809 y FN(Extend)i(the)j(left)f(side)g(of)g(the)g(deque)f(by)h (appending)e(elements)h(from)h FK(iter)o(able)p FN(.)33 b(Note,)23 b(the)h(series)f(of)g(left)g(appends)f(results)208 2909 y(in)e(re)n(v)o(ersing)e(the)i(order)f(of)h(elements)g(in)h(the)f (iterable)f(ar)o(gument.)0 3055 y FD(pop)p FJ(\(\))208 3155 y FN(Remo)o(v)o(e)37 b(and)h(return)g(an)g(element)g(from)g(the)h (right)f(side)h(of)f(the)h(deque.)79 b(If)39 b(no)f(elements)g(are)h (present,)j(raises)e(an)208 3255 y FJ(IndexError)p FN(.)0 3402 y FD(popleft)p FJ(\(\))208 3501 y FN(Remo)o(v)o(e)f(and)i(return)f (an)g(element)h(from)f(the)h(left)g(side)g(of)g(the)g(deque.)86 b(If)41 b(no)f(elements)h(are)g(present,)k(raises)d(an)208 3601 y FJ(IndexError)p FN(.)0 3748 y FD(remove)p FJ(\()p FK(value)p FJ(\))208 3847 y FN(Remo)o(v)o(ed)18 b(the)i(\002rst)h (occurrence)d(of)i FK(value)p FN(.)k(If)c(not)g(found,)e(raises)j(a)g FJ(ValueError)p FN(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 3994 y FD(rotate)p FJ(\()p FK(n)p FJ(\))208 4094 y FN(Rotate)e(the)h (deque)e FK(n)i FN(steps)g(to)g(the)f(right.)23 b(If)18 b FK(n)f FN(is)i(ne)o(gati)n(v)o(e,)c(rotate)j(to)f(the)h(left.)24 b(Rotating)17 b(one)g(step)h(to)f(the)h(right)f(is)h(equi)n(v)n(alent) 208 4193 y(to:)25 b(`)p FJ(d.appendleft\(d.pop\(\)\))p FN('.)0 4340 y(In)37 b(addition)e(to)i(the)g(abo)o(v)o(e,)j(deques)c (support)f(iteration,)40 b(pickling,)g(`)p FJ(len\(d\))p FN(',)g(`)p FJ(reversed\(d\))p FN(',)e(`)p FJ(copy.copy\(d\))p FN(',)0 4440 y(`)p FJ(copy.deepcopy\(d\))p FN(',)17 b(membership)h (testing)i(with)h(the)f FJ(in)g FN(operator)m(,)e(and)i(subscript)f (references)g(such)h(as)h(`)p FJ(d[-1])p FN('.)0 4587 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(5.3.)52 b FJ(collections)21 b FI(\227)i(High-perf)n(or)r(mance)g(container)h(datatypes)1483 b(117)p eop end %%Page: 118 130 TeXDict begin 118 129 bop 236 174 a FA(>>>)45 b(from)f(collections)f (import)h(deque)236 266 y(>>>)h(d)f(=)h(deque\('ghi'\))760 b(#)45 b(make)f(a)g(new)h(deque)f(with)g(three)g(items)236 357 y(>>>)h(for)f(elem)g(in)h(d:)851 b(#)45 b(iterate)e(over)h(the)h (deque's)e(elements)236 448 y(...)224 b(print)44 b(elem.upper\(\))236 540 y(G)236 631 y(H)236 722 y(I)236 905 y(>>>)h(d.append\('j'\))894 b(#)45 b(add)f(a)h(new)f(entry)g(to)g(the)h(right)f(side)236 996 y(>>>)h(d.appendleft\('f'\))714 b(#)45 b(add)f(a)h(new)f(entry)g (to)g(the)h(left)f(side)236 1088 y(>>>)h(d)1434 b(#)45 b(show)f(the)g(representation)f(of)h(the)g(deque)236 1179 y(deque\(['f',)f('g',)h('h',)h('i',)f('j']\))236 1362 y(>>>)h(d.pop\(\))1164 b(#)45 b(return)e(and)i(remove)f(the)g (rightmost)f(item)236 1453 y('j')236 1544 y(>>>)i(d.popleft\(\))984 b(#)45 b(return)e(and)i(remove)f(the)g(leftmost)f(item)236 1636 y('f')236 1727 y(>>>)i(list\(d\))1164 b(#)45 b(list)f(the)g (contents)g(of)g(the)g(deque)236 1818 y(['g',)g('h',)g('i'])236 1910 y(>>>)h(d[0])1299 b(#)45 b(peek)f(at)g(leftmost)g(item)236 2001 y('g')236 2092 y(>>>)h(d[-1])1254 b(#)45 b(peek)f(at)g(rightmost)g (item)236 2183 y('i')236 2366 y(>>>)h(list\(reversed\(d\)\))714 b(#)45 b(list)f(the)g(contents)g(of)g(a)h(deque)f(in)g(reverse)236 2457 y(['i',)g('h',)g('g'])236 2549 y(>>>)h('h')f(in)g(d)1121 b(#)45 b(search)e(the)i(deque)236 2640 y(True)236 2731 y(>>>)g(d.extend\('jkl'\))804 b(#)45 b(add)f(multiple)f(elements)h(at)g (once)236 2823 y(>>>)h(d)236 2914 y(deque\(['g',)e('h',)h('i',)h('j',)f ('k',)g('l']\))236 3005 y(>>>)h(d.rotate\(1\))984 b(#)45 b(right)f(rotation)236 3097 y(>>>)h(d)236 3188 y(deque\(['l',)e('g',)h ('h',)h('i',)f('j',)g('k']\))236 3279 y(>>>)h(d.rotate\(-1\))939 b(#)45 b(left)f(rotation)236 3371 y(>>>)h(d)236 3462 y(deque\(['g',)e('h',)h('i',)h('j',)f('k',)g('l']\))236 3645 y(>>>)h(deque\(reversed\(d\)\))669 b(#)45 b(make)f(a)g(new)h (deque)f(in)g(reverse)g(order)236 3736 y(deque\(['l',)f('k',)h('j',)h ('i',)f('h',)g('g']\))236 3827 y(>>>)h(d.clear\(\))1074 b(#)45 b(empty)f(the)g(deque)236 3919 y(>>>)h(d.pop\(\))1164 b(#)45 b(cannot)e(pop)i(from)f(an)g(empty)g(deque)236 4010 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 4101 y(File)f("",)f(line)h(1,)g(in)h(-toplevel-)416 4193 y(d.pop\(\))236 4284 y(IndexError:)e(pop)i(from)f(an)g(empty)g (deque)236 4467 y(>>>)h(d.extendleft\('abc'\))624 b(#)45 b(extendleft\(\))d(reverses)i(the)g(input)g(order)236 4558 y(>>>)h(d)236 4649 y(deque\(['c',)e('b',)h('a']\))0 5061 y FI(Recipes)0 5263 y FN(This)20 b(section)g(sho)n(ws)h(v)n (arious)e(approaches)f(to)i(w)o(orking)f(with)h(deques.)p 0 5549 3901 4 v 0 5649 a FI(118)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 119 131 TeXDict begin 119 130 bop 0 83 a FN(The)31 b FJ(rotate\(\))f FN(method)g(pro)o(vides)f(a)j(w)o(ay)f(to)g(implement)f FJ(deque)h FN(slicing)g(and)g(deletion.)56 b(F)o(or)31 b(e)o(xample,)h(a)g(pure)e(p)o(ython)0 183 y(implementation)18 b(of)i FJ(del)49 b(d[n])20 b FN(relies)h(on)e(the)i FJ(rotate\(\))e FN(method)g(to)h(position)f(elements)h(to)h(be)f(popped:)236 421 y FA(def)45 b(delete_nth\(d,)d(n\):)416 512 y(d.rotate\(-n\))416 603 y(d.popleft\(\))416 695 y(d.rotate\(n\))0 981 y FN(T)-7 b(o)20 b(implement)f FJ(deque)g FN(slicing,)h(use)g(a)h(similar)f (approach)e(applying)g FJ(rotate\(\))h FN(to)h(bring)f(a)h(tar)o(get)f (element)g(to)h(the)g(left)h(side)f(of)0 1081 y(the)g(deque.)k(Remo)o (v)o(e)19 b(old)h(entries)g(with)g FJ(popleft\(\))p FN(,)f(add)h(ne)n (w)g(entries)g(with)g FJ(extend\(\))p FN(,)f(and)h(then)g(re)n(v)o (erse)f(the)h(rotation.)0 1228 y(W)m(ith)j(minor)f(v)n(ariations)g(on)g (that)h(approach,)f(it)h(is)h(easy)f(to)g(implement)f(F)o(orth)g(style) h(stack)g(manipulations)e(such)i(as)h FJ(dup)p FN(,)f FJ(drop)p FN(,)0 1327 y FJ(swap)p FN(,)d FJ(over)p FN(,)g FJ(pick)p FN(,)f FJ(rot)p FN(,)h(and)g FJ(roll)p FN(.)0 1474 y(A)h(roundrobin)d(task)j(serv)o(er)f(can)h(be)g(b)n(uilt)g(from)f (a)h FJ(deque)g FN(using)g FJ(popleft\(\))e FN(to)i(select)h(the)f (current)f(task)h(and)f FJ(append\(\))g FN(to)0 1574 y(add)g(it)h(back)e(to)h(the)h(tasklist)g(if)f(the)g(input)g(stream)g (is)h(not)f(e)o(xhausted:)236 1812 y FA(def)45 b(roundrobin\()911 1825 y(*)956 1812 y(iterables\):)416 1903 y(pending)e(=)i (deque\(iter\(i\))e(for)h(i)h(in)f(iterables\))416 1995 y(while)g(pending:)595 2086 y(task)g(=)h(pending.popleft\(\))595 2177 y(try:)774 2269 y(yield)f(task.next\(\))595 2360 y(except)g(StopIteration:)774 2451 y(continue)595 2543 y(pending.append\(task\))236 2725 y(>>>)h(for)f(value)g(in)g (roundrobin\('abc',)e('d',)i('efgh'\):)236 2817 y(...)224 b(print)44 b(value)236 2999 y(a)236 3091 y(d)236 3182 y(e)236 3273 y(b)236 3365 y(f)236 3456 y(c)236 3547 y(g)236 3639 y(h)0 4016 y FN(Multi-pass)26 b(data)g(reduction)e(algorithms)h (can)g(be)h(succinctly)g(e)o(xpressed)e(and)i(ef)n(\002ciently)f(coded) g(by)g(e)o(xtracting)g(elements)g(with)0 4116 y(multiple)d(calls)h(to)g FJ(popleft\(\))p FN(,)f(applying)f(the)i(reduction)e(function,)g(and)h (calling)g FJ(append\(\))g FN(to)h(add)f(the)h(result)g(back)f(to)h (the)0 4216 y(queue.)0 4363 y(F)o(or)e(e)o(xample,)f(b)n(uilding)g(a)h (balanced)f(binary)g(tree)i(of)f(nested)g(lists)h(entails)g(reducing)d (tw)o(o)j(adjacent)e(nodes)h(into)g(one)f(by)h(grouping)0 4462 y(them)f(in)g(a)h(list:)p 0 5549 3901 4 v 0 5649 a FI(5.3.)52 b FJ(collections)21 b FI(\227)i(High-perf)n(or)r(mance)g (container)h(datatypes)1483 b(119)p eop end %%Page: 120 132 TeXDict begin 120 131 bop 236 174 a FA(def)45 b(maketree\(iterable\):) 416 266 y(d)f(=)h(deque\(iterable\))416 357 y(while)f(len\(d\))f(>)i (1:)595 448 y(pair)f(=)h([d.popleft\(\),)d(d.popleft\(\)])595 540 y(d.append\(pair\))416 631 y(return)h(list\(d\))236 814 y(>>>)i(print)f(maketree\('abcdefgh'\))236 905 y([[[['a',)g('b'],)g (['c',)g('d']],)g([['e',)f('f'],)h(['g',)g('h']]]])0 1417 y Fv(5.3.2)100 b Fm(defaultdict)25 b Fv(objects)0 1613 y FD(defaultdict)p FJ(\()p FC([)p FK(default)p 877 1613 25 4 v 26 w(factory)p FC([)p FK(,)20 b(...)12 b FC(])g(])p FJ(\))208 1713 y FN(Returns)22 b(a)h(ne)n(w)f (dictionary-lik)o(e)e(object.)32 b FJ(defaultdict)21 b FN(is)i(a)g(subclass)g(of)f(the)g(b)n(uiltin)h FJ(dict)f FN(class.)33 b(It)23 b(o)o(v)o(errides)d(one)208 1813 y(method)f(and)i(adds)g(one)f(writable)h(instance)g(v)n(ariable.)26 b(The)21 b(remaining)f(functionality)f(is)j(the)f(same)g(as)h(for)f (the)g FJ(dict)g FN(class)208 1912 y(and)e(is)i(not)f(documented)e (here.)208 2043 y(The)25 b(\002rst)i(ar)o(gument)d(pro)o(vides)h(the)h (initial)h(v)n(alue)e(for)h(the)g FJ(default_factory)e FN(attrib)n(ute;)29 b(it)e(def)o(aults)f(to)g FJ(None)p FN(.)43 b(All)208 2142 y(remaining)23 b(ar)o(guments)g(are)i(treated)f (the)h(same)g(as)h(if)f(the)o(y)g(were)g(passed)f(to)i(the)f FJ(dict)f FN(constructor)m(,)g(including)f(k)o(e)o(yw)o(ord)208 2242 y(ar)o(guments.)208 2373 y(Ne)n(w)d(in)g(v)o(ersion)f(2.5.)0 2520 y FJ(defaultdict)g FN(objects)h(support)e(the)j(follo)n(wing)d (method)h(in)h(addition)f(to)i(the)f(standard)f FJ(dict)h FN(operations:)0 2666 y FD(__missing__)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 2766 y FN(If)g(the)g FJ(default_factory)e FN(attrib)n(ute)i (is)h FJ(None)p FN(,)e(this)i(raises)g(an)f FJ(KeyError)f FN(e)o(xception)g(with)h(the)g FK(k)o(e)n(y)g FN(as)h(ar)o(gument.)208 2897 y(If)d FJ(default_factory)e FN(is)j(not)f FJ(None)p FN(,)h(it)g(is)g(called)f(without)g(ar)o(guments)e(to)j(pro)o(vide)d(a) j(def)o(ault)f(v)n(alue)g(for)f(the)i(gi)n(v)o(en)e FK(k)o(e)n(y)p FN(,)208 2996 y(this)j(v)n(alue)g(is)h(inserted)f(in)g(the)g (dictionary)e(for)i(the)g FK(k)o(e)n(y)p FN(,)g(and)g(returned.)208 3127 y(If)g(calling)f FJ(default_factory)f FN(raises)j(an)f(e)o (xception)f(this)h(e)o(xception)f(is)i(propagated)c(unchanged.)208 3257 y(This)23 b(method)f(is)j(called)e(by)g(the)h FJ(__getitem__)e FN(method)g(of)h(the)h FJ(dict)f FN(class)i(when)e(the)g(requested)g(k) o(e)o(y)g(is)h(not)f(found;)208 3357 y(whate)n(v)o(er)18 b(it)j(returns)e(or)h(raises)h(is)g(then)f(returned)e(or)i(raised)g(by) g FJ(__getitem__)p FN(.)0 3504 y FJ(defaultdict)f FN(objects)h(support) e(the)j(follo)n(wing)d(instance)i(v)n(ariable:)0 3651 y FD(default_factory)208 3750 y FN(This)h(attrib)n(ute)f(is)i(used)e (by)g(the)h FJ(__missing__)f FN(method;)f(it)j(is)f(initialized)g(from) f(the)g(\002rst)i(ar)o(gument)c(to)j(the)g(constructor)m(,)208 3850 y(if)f(present,)f(or)h(to)h FJ(None)p FN(,)e(if)i(absent.)0 4116 y FJ(defaultdict)g FI(Examples)0 4319 y FN(Using)f FJ(list)g FN(as)h(the)f FJ(default_factory)p FN(,)e(it)j(is)g(easy)f (to)h(group)d(a)j(sequence)e(of)h(k)o(e)o(y-v)n(alue)e(pairs)i(into)g (a)g(dictionary)f(of)h(lists:)236 4466 y FA(>>>)45 b(s)f(=)h ([\('yellow',)e(1\),)h(\('blue',)g(2\),)g(\('yellow',)f(3\),)h (\('blue',)g(4\),)g(\('red',)g(1\)])236 4557 y(>>>)h(d)f(=)h (defaultdict\(list\))236 4649 y(>>>)g(for)f(k,)g(v)h(in)g(s:)595 4740 y(d[k].append\(v\))236 4923 y(>>>)g(d.items\(\))236 5014 y([\('blue',)f([2,)g(4]\),)g(\('red',)g([1]\),)g(\('yellow',)f ([1,)h(3]\)])0 5300 y FN(When)22 b(each)f(k)o(e)o(y)h(is)g(encountered) e(for)h(the)h(\002rst)h(time,)f(it)g(is)h(not)f(already)f(in)h(the)g (mapping;)f(so)h(an)g(entry)f(is)i(automatically)d(created)0 5400 y(using)32 b(the)g FJ(default_factory)e FN(function)g(which)i (returns)f(an)h(empty)g FJ(list)p FN(.)61 b(The)31 b FJ(list.append\(\))g FN(operation)f(then)p 0 5549 3901 4 v 0 5649 a FI(120)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 121 133 TeXDict begin 121 132 bop 0 83 a FN(attaches)20 b(the)h(v)n(alue)f(to)g (the)h(ne)n(w)f(list.)27 b(When)20 b(k)o(e)o(ys)g(are)g(encountered)e (again,)h(the)i(look-up)d(proceeds)h(normally)g(\(returning)f(the)i (list)0 183 y(for)h(that)h(k)o(e)o(y\))e(and)h(the)h FJ(list.append\(\))d FN(operation)h(adds)h(another)f(v)n(alue)h(to)h (the)f(list.)30 b(This)22 b(technique)e(is)i(simpler)f(and)g(f)o(aster) 0 282 y(than)f(an)g(equi)n(v)n(alent)e(technique)h(using)h FJ(dict.setdefault\(\))p FN(:)236 520 y FA(>>>)45 b(d)f(=)h({})236 612 y(>>>)g(for)f(k,)g(v)h(in)g(s:)236 703 y(d.setdefault\(k,)e ([]\).append\(v\))236 886 y(>>>)i(d.items\(\))236 977 y([\('blue',)f([2,)g(4]\),)g(\('red',)g([1]\),)g(\('yellow',)f([1,)h (3]\)])0 1264 y FN(Setting)27 b(the)g FJ(default_factory)e FN(to)i FJ(int)g FN(mak)o(es)g(the)g FJ(defaultdict)e FN(useful)i(for)f(counting)g(\(lik)o(e)h(a)g(bag)f(or)h(multiset)g(in)0 1363 y(other)19 b(languages\):)236 1601 y FA(>>>)45 b(s)f(=)h ('mississippi')236 1693 y(>>>)g(d)f(=)h(defaultdict\(int\))236 1784 y(>>>)g(for)f(k)h(in)f(s:)595 1875 y(d[k])g(+=)h(1)236 2058 y(>>>)g(d.items\(\))236 2149 y([\('i',)f(4\),)g(\('p',)g(2\),)h (\('s',)f(4\),)g(\('m',)g(1\)])0 2436 y FN(When)20 b(a)g(letter)g(is)h (\002rst)g(encountered,)c(it)k(is)f(missing)g(from)f(the)h(mapping,)e (so)i(the)g FJ(default_factory)e FN(function)g(calls)j FJ(int\(\))0 2536 y FN(to)f(supply)g(a)g(def)o(ault)g(count)f(of)h (zero.)k(The)c(increment)f(operation)f(then)i(b)n(uilds)g(up)g(the)g (count)f(for)h(each)f(letter)-5 b(.)0 2682 y(The)20 b(function)e FJ(int\(\))i FN(which)f(al)o(w)o(ays)i(returns)e(zero)g(is)i(just)g(a)f (special)h(case)f(of)g(constant)f(functions.)24 b(A)c(f)o(aster)g(and)g (more)f(\003e)o(xible)0 2782 y(w)o(ay)26 b(to)g(create)f(constant)g (functions)f(is)j(to)f(use)g FJ(itertools.repeat\(\))d FN(which)i(can)g(supply)g(an)o(y)g(constant)g(v)n(alue)g(\(not)g(just)0 2882 y(zero\):)236 3120 y FA(>>>)45 b(def)f(constant_factory\(value\):) 236 3211 y(...)224 b(return)44 b(itertools.repeat\(value\).next)236 3302 y(>>>)h(d)f(=)h(defaultdict\(constant_factory\(''\)\)) 236 3394 y(>>>)g(d.update\(name='John',)c(action='ran'\))236 3485 y(>>>)k('\045\(name\)s)e(\045\(action\)s)g(to)i(\045\(object\)s')d (\045)j(d)236 3576 y('John)f(ran)h(to)f(')0 3863 y FN(Setting)20 b(the)g FJ(default_factory)e FN(to)j FJ(set)f FN(mak)o(es)g(the)g FJ(defaultdict)f FN(useful)g(for)h(b)n (uilding)f(a)h(dictionary)f(of)h(sets:)236 4101 y FA(>>>)45 b(s)f(=)h([\('red',)e(1\),)i(\('blue',)e(2\),)i(\('red',)e(3\),)h (\('blue',)g(4\),)g(\('red',)g(1\),)g(\('blue',)g(4\)])236 4192 y(>>>)h(d)f(=)h(defaultdict\(set\))236 4284 y(>>>)g(for)f(k,)g(v)h (in)g(s:)595 4375 y(d[k].add\(v\))236 4558 y(>>>)g(d.items\(\))236 4649 y([\('blue',)f(set\([2,)f(4]\)\),)h(\('red',)g(set\([1,)f(3]\)\)]) 0 5159 y FE(5.4)121 b Fx(heapq)32 b FE(\227)g(Heap)j(queue)h(algor)r (ithm)0 5392 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)p 0 5549 3901 4 v 0 5649 a FI(5.4.)52 b FJ(heapq)22 b FI(\227)h(Heap)h (queue)g(algor)q(ithm)2377 b(121)p eop end %%Page: 122 134 TeXDict begin 122 133 bop 0 83 a FN(This)20 b(module)f(pro)o(vides)g (an)h(implementation)e(of)i(the)g(heap)f(queue)g(algorithm,)g(also)h (kno)n(wn)f(as)i(the)f(priority)f(queue)g(algorithm.)0 230 y(Heaps)26 b(are)g(arrays)f(for)h(which)f FK(heap)p FJ([)p FK(k)q FJ(])48 b(<=)i FK(heap)p FJ([2)1706 245 y(*)1756 230 y FK(k)q FJ(+1])24 b FN(and)i FK(heap)p FJ([)p FK(k)q FJ(])48 b(<=)h FK(heap)p FJ([2)2876 245 y(*)2926 230 y FK(k)q FJ(+2])24 b FN(for)i(all)g FK(k)q FN(,)i(counting)d(ele-)0 330 y(ments)i(from)g(zero.)46 b(F)o(or)27 b(the)g(sak)o(e)h(of)f(comparison,)g(non-e)o(xisting)e (elements)i(are)g(considered)f(to)i(be)f(in\002nite.)46 b(The)27 b(interesting)0 429 y(property)18 b(of)i(a)h(heap)e(is)i(that) f FK(heap)p FJ([0])f FN(is)i(al)o(w)o(ays)g(its)g(smallest)g(element.)0 576 y(The)e(API)g(belo)n(w)g(dif)n(fers)f(from)g(te)o(xtbook)f(heap)i (algorithms)f(in)h(tw)o(o)h(aspects:)25 b(\(a\))19 b(W)-7 b(e)20 b(use)f(zero-based)f(inde)o(xing.)k(This)e(mak)o(es)f(the)0 676 y(relationship)24 b(between)g(the)h(inde)o(x)f(for)g(a)h(node)f (and)h(the)g(inde)o(x)o(es)f(for)g(its)i(children)e(slightly)g(less)i (ob)o(vious,)f(b)n(ut)g(is)h(more)e(suitable)0 775 y(since)g(Python)f (uses)h(zero-based)e(inde)o(xing.)34 b(\(b\))23 b(Our)h(pop)f(method)f (returns)h(the)h(smallest)h(item,)g(not)e(the)h(lar)o(gest)f(\(called)h (a)g(\224min)0 875 y(heap\224)19 b(in)i(te)o(xtbooks;)d(a)j(\224max)e (heap\224)h(is)h(more)e(common)g(in)h(te)o(xts)g(because)g(of)g(its)h (suitability)f(for)f(in-place)h(sorting\).)0 1022 y(These)h(tw)o(o)h (mak)o(e)e(it)i(possible)f(to)h(vie)n(w)f(the)g(heap)f(as)i(a)g(re)o (gular)e(Python)g(list)i(without)f(surprises:)27 b FK(heap)p FJ([0])19 b FN(is)j(the)g(smallest)g(item,)0 1121 y(and)e FK(heap)p FJ(.sort\(\))d FN(maintains)j(the)g(heap)g(in)m(v)n(ariant!)0 1268 y(T)-7 b(o)16 b(create)g(a)h(heap,)f(use)g(a)g(list)i(initialized) d(to)i FJ([])p FN(,)f(or)g(you)g(can)f(transform)g(a)h(populated)e (list)k(into)e(a)g(heap)f(via)i(function)d FJ(heapify\(\))p FN(.)0 1415 y(The)20 b(follo)n(wing)e(functions)h(are)h(pro)o(vided:)0 1562 y FD(heappush)p FJ(\()p FK(heap,)d(item)p FJ(\))208 1662 y FN(Push)j(the)g(v)n(alue)f FK(item)i FN(onto)f(the)g FK(heap)p FN(,)f(maintaining)f(the)i(heap)g(in)m(v)n(ariant.)0 1808 y FD(heappop)p FJ(\()p FK(heap)p FJ(\))208 1908 y FN(Pop)38 b(and)h(return)f(the)h(smallest)h(item)f(from)f(the)h FK(heap)p FN(,)k(maintaining)37 b(the)i(heap)g(in)m(v)n(ariant.)80 b(If)39 b(the)g(heap)f(is)i(empty)-5 b(,)208 2008 y FJ(IndexError)18 b FN(is)k(raised.)0 2155 y FD(heapify)p FJ(\()p FK(x)p FJ(\))208 2254 y FN(T)m(ransform)c(list)j FK(x)g FN(into)f(a)h(heap,)e (in-place,)g(in)h(linear)g(time.)0 2401 y FD(heapreplace)p FJ(\()p FK(heap,)d(item)p FJ(\))208 2501 y FN(Pop)g(and)g(return)g(the) g(smallest)i(item)e(from)g(the)h FK(heap)p FN(,)f(and)g(also)h(push)f (the)g(ne)n(w)h FK(item)p FN(.)24 b(The)18 b(heap)f(size)h(doesn')o(t)e (change.)23 b(If)18 b(the)208 2600 y(heap)23 b(is)i(empty)-5 b(,)23 b FJ(IndexError)f FN(is)j(raised.)36 b(This)24 b(is)h(more)e(ef)n(\002cient)g(than)g FJ(heappop\(\))g FN(follo)n(wed)g(by)g FJ(heappush\(\))p FN(,)208 2700 y(and)17 b(can)i(be)f(more)f(appropriate)f(when)i(using)g(a)h(\002x)o (ed-size)e(heap.)24 b(Note)18 b(that)h(the)f(v)n(alue)g(returned)e(may) i(be)g(lar)o(ger)g(than)f FK(item)p FN(!)208 2800 y(That)i(constrains)h (reasonable)f(uses)h(of)g(this)h(routine)e(unless)h(written)g(as)h (part)f(of)g(a)h(conditional)d(replacement:)802 3024 y FA(if)45 b(item)f(>)h(heap[0]:)982 3115 y(item)f(=)h (heapreplace\(heap,)d(item\))0 3319 y FN(Example)19 b(of)h(use:)236 3465 y FA(>>>)45 b(from)f(heapq)g(import)g(heappush,)f(heappop)236 3557 y(>>>)i(heap)f(=)g([])236 3648 y(>>>)h(data)f(=)g([1,)h(3,)f(5,)h (7,)f(9,)h(2,)f(4,)h(6,)f(8,)h(0])236 3739 y(>>>)g(for)f(item)g(in)h (data:)236 3831 y(...)224 b(heappush\(heap,)42 b(item\))236 3922 y(...)236 4013 y(>>>)j(ordered)e(=)i([])236 4105 y(>>>)g(while)f(heap:)236 4196 y(...)224 b (ordered.append\(heappop\(heap\)\))236 4287 y(...)236 4379 y(>>>)45 b(print)f(ordered)236 4470 y([0,)h(1,)f(2,)h(3,)f(4,)h (5,)f(6,)h(7,)f(8,)h(9])236 4561 y(>>>)g(data.sort\(\))236 4653 y(>>>)g(print)f(data)g(==)g(ordered)236 4744 y(True)236 4835 y(>>>)0 5122 y FN(The)20 b(module)f(also)h(of)n(fers)f(tw)o(o)i (general)e(purpose)g(functions)f(based)i(on)g(heaps.)0 5269 y FD(nlargest)p FJ(\()p FK(n,)e(iter)o(able)p FC([)p FK(,)i(k)o(e)n(y)12 b FC(])p FJ(\))208 5368 y FN(Return)34 b(a)h(list)h(with)f(the)g FK(n)g FN(lar)o(gest)g(elements)f(from)g(the) h(dataset)g(de\002ned)f(by)g FK(iter)o(able)p FN(.)69 b FK(k)o(e)n(y)p FN(,)38 b(if)d(pro)o(vided,)h(speci\002es)p 0 5549 3901 4 v 0 5649 a FI(122)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 123 135 TeXDict begin 123 134 bop 208 83 a FN(a)38 b(function)f(of)h(one)g(ar)o (gument)e(that)i(is)h(used)f(to)h(e)o(xtract)e(a)i(comparison)d(k)o(e)o (y)i(from)f(each)h(element)g(in)h(the)f(iterable:)208 183 y(`)p FK(k)o(e)n(y)p FJ(=str.lower)p FN(')23 b(Equi)n(v)n(alent)h (to:)38 b(`)p FJ(sorted\(iterable,)46 b(key=key,)j(reverse=True\)[:n])p FN(')h(Ne)n(w)26 b(in)208 282 y(v)o(ersion)18 b(2.4.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.5:)h(Added)f(the)h(optional)f FK(k)o(e)n(y)h FN(ar)o(gument.)0 429 y FD(nsmallest)p FJ(\()p FK(n,)e(iter)o(able)p FC([)p FK(,)i(k)o(e)n(y)12 b FC(])p FJ(\))208 529 y FN(Return)36 b(a)h(list)h(with)f(the)f FK(n)h FN(smallest)h(elements)e(from)g(the)g(dataset)h(de\002ned)f(by)g FK(iter)o(able)p FN(.)74 b FK(k)o(e)n(y)p FN(,)41 b(if)c(pro)o(vided,)h (speci-)208 628 y(\002es)31 b(a)f(function)f(of)h(one)f(ar)o(gument)f (that)i(is)i(used)e(to)g(e)o(xtract)f(a)i(comparison)d(k)o(e)o(y)i (from)f(each)h(element)f(in)i(the)f(iterable:)208 728 y(`)p FK(k)o(e)n(y)p FJ(=str.lower)p FN(')12 b(Equi)n(v)n(alent)i(to:) 22 b(`)p FJ(sorted\(iterable,)47 b(key=key\)[:n])p FN(')29 b(Ne)n(w)16 b(in)f(v)o(ersion)f(2.4.)71 b(Changed)208 828 y(in)20 b(v)o(ersion)f(2.5:)g(Added)h(the)g(optional)f FK(k)o(e)n(y)h FN(ar)o(gument.)0 975 y(Both)29 b(functions)f(perform)f (best)j(for)e(smaller)i(v)n(alues)e(of)h FK(n)p FN(.)53 b(F)o(or)28 b(lar)o(ger)g(v)n(alues,)j(it)f(is)g(more)f(ef)n(\002cient) f(to)i(use)f(the)g FJ(sorted\(\))0 1074 y FN(function.)23 b(Also,)e(when)e FJ(n==1)p FN(,)h(it)h(is)g(more)e(ef)n(\002cient)h(to) g(use)h(the)f(b)n(uiltin)g FJ(min\(\))g FN(and)f FJ(max\(\))h FN(functions.)0 1359 y Fv(5.4.1)100 b(Theor)s(y)0 1562 y FN(\(This)20 b(e)o(xplanation)e(is)j(due)f(to)g(Franois)g(Pinard.)k (The)c(Python)f(code)g(for)h(this)h(module)e(w)o(as)i(contrib)n(uted)d (by)i(K)n(e)n(vin)f(O'Connor)-5 b(.\))0 1709 y(Heaps)26 b(are)g(arrays)f(for)h(which)f FJ(a[)p FK(k)q FJ(])49 b(<=)h(a[2)1481 1724 y(*)1531 1709 y FK(k)q FJ(+1])25 b FN(and)h FJ(a[)p FK(k)q FJ(])49 b(<=)h(a[2)2428 1724 y(*)2478 1709 y FK(k)q FJ(+2])25 b FN(for)h(all)g FK(k)q FN(,)i(counting)c(elements)i(from)f(0.)0 1808 y(F)o(or)d(the)f(sak)o(e) i(of)e(comparison,)f(non-e)o(xisting)f(elements)j(are)g(considered)e (to)i(be)g(in\002nite.)29 b(The)22 b(interesting)f(property)f(of)h(a)h (heap)g(is)0 1908 y(that)e FJ(a[0])g FN(is)h(al)o(w)o(ays)g(its)g (smallest)g(element.)0 2055 y(The)h(strange)g(in)m(v)n(ariant)f(abo)o (v)o(e)f(is)k(meant)e(to)g(be)h(an)f(ef)n(\002cient)g(memory)f (representation)f(for)i(a)h(tournament.)29 b(The)22 b(numbers)f(belo)n (w)0 2155 y(are)f FK(k)q FN(,)h(not)f FJ(a[)p FK(k)q FJ(])p FN(:)1805 2393 y FA(0)1043 2575 y(1)1479 b(2)685 2758 y(3)672 b(4)717 b(5)672 b(6)505 2941 y(7)314 b(8)g(9)f(10)269 b(11)f(12)h(13)g(14)416 3123 y(15)44 b(16)134 b(17)45 b(18)134 b(19)44 b(20)135 b(21)44 b(22)134 b(23)45 b(24)134 b(25)44 b(26)134 b(27)45 b(28)134 b(29)45 b(30)0 3410 y FN(In)27 b(the)g(tree)g(abo)o(v)o(e,)g(each)f(cell)i FK(k)h FN(is)f(topping)d FJ(2)1431 3425 y(*)1481 3410 y FK(k)q FJ(+1)i FN(and)g FJ(2)1844 3425 y(*)1894 3410 y FK(k)q FJ(+2)p FN(.)45 b(In)27 b(an)g(usual)g(binary)f(tournament)e (we)k(see)f(in)g(sports,)i(each)0 3510 y(cell)23 b(is)h(the)f(winner)f (o)o(v)o(er)f(the)i(tw)o(o)g(cells)h(it)f(tops,)h(and)e(we)h(can)g (trace)f(the)h(winner)f(do)n(wn)g(the)h(tree)g(to)g(see)g(all)h (opponents)c(s/he)j(had.)0 3609 y(Ho)n(we)n(v)o(er)m(,)d(in)i(man)o(y)e (computer)g(applications)g(of)h(such)h(tournaments,)d(we)j(do)f(not)h (need)e(to)i(trace)g(the)f(history)g(of)g(a)h(winner)-5 b(.)29 b(T)-7 b(o)22 b(be)0 3709 y(more)17 b(memory)f(ef)n(\002cient,)i (when)g(a)g(winner)f(is)i(promoted,)d(we)i(try)g(to)g(replace)g(it)g (by)g(something)e(else)j(at)g(a)f(lo)n(wer)g(le)n(v)o(el,)f(and)h(the)g (rule)0 3809 y(becomes)j(that)h(a)g(cell)g(and)g(the)f(tw)o(o)i(cells)f (it)h(tops)e(contain)g(three)h(dif)n(ferent)e(items,)i(b)n(ut)g(the)g (top)f(cell)i(\224wins\224)f(o)o(v)o(er)e(the)i(tw)o(o)g(topped)0 3908 y(cells.)0 4055 y(If)j(this)h(heap)e(in)m(v)n(ariant)f(is)k (protected)c(at)j(all)f(time,)i(inde)o(x)d(0)h(is)h(clearly)e(the)i(o)o (v)o(erall)d(winner)-5 b(.)40 b(The)24 b(simplest)i(algorithmic)d(w)o (ay)i(to)0 4155 y(remo)o(v)o(e)18 b(it)j(and)e(\002nd)h(the)f(\224ne)o (xt\224)g(winner)g(is)i(to)f(mo)o(v)o(e)f(some)g(loser)h(\(let')-5 b(s)21 b(say)f(cell)g(30)g(in)g(the)g(diagram)e(abo)o(v)o(e\))g(into)i (the)g(0)g(position,)0 4254 y(and)25 b(then)g(percolate)f(this)i(ne)n (w)f(0)g(do)n(wn)g(the)g(tree,)h(e)o(xchanging)d(v)n(alues,)j(until)f (the)g(in)m(v)n(ariant)f(is)i(re-established.)39 b(This)26 b(is)g(clearly)0 4354 y(logarithmic)18 b(on)i(the)g(total)g(number)f (of)h(items)g(in)h(the)f(tree.)25 b(By)c(iterating)e(o)o(v)o(er)g(all)i (items,)f(you)f(get)i(an)f(O\(n)g(log)f(n\))h(sort.)0 4501 y(A)28 b(nice)g(feature)f(of)g(this)h(sort)g(is)h(that)f(you)e (can)i(ef)n(\002ciently)f(insert)h(ne)n(w)f(items)h(while)g(the)g(sort) g(is)g(going)f(on,)i(pro)o(vided)c(that)j(the)0 4600 y(inserted)17 b(items)h(are)g(not)f(\224better\224)g(than)g(the)h(last) g(0')o(th)f(element)g(you)g(e)o(xtracted.)22 b(This)c(is)h(especially)e (useful)g(in)h(simulation)f(conte)o(xts,)0 4700 y(where)j(the)h(tree)g (holds)f(all)i(incoming)d(e)n(v)o(ents,)h(and)h(the)f(\224win\224)h (condition)e(means)i(the)g(smallest)g(scheduled)f(time.)27 b(When)21 b(an)f(e)n(v)o(ent)0 4800 y(schedule)g(other)f(e)n(v)o(ents)h (for)g(e)o(x)o(ecution,)f(the)o(y)g(are)i(scheduled)e(into)h(the)h (future,)e(so)i(the)o(y)f(can)g(easily)h(go)f(into)h(the)f(heap.)26 b(So,)20 b(a)h(heap)0 4899 y(is)g(a)g(good)e(structure)g(for)g (implementing)f(schedulers)i(\(this)g(is)h(what)f(I)h(used)f(for)f(my)h (MIDI)g(sequencer)e(:-\).)0 5046 y(V)-9 b(arious)26 b(structures)h(for) f(implementing)f(schedulers)h(ha)n(v)o(e)h(been)f(e)o(xtensi)n(v)o(ely) f(studied,)j(and)f(heaps)f(are)h(good)f(for)g(this,)j(as)f(the)o(y)0 5146 y(are)d(reasonably)e(speedy)-5 b(,)25 b(the)g(speed)f(is)i(almost) f(constant,)g(and)g(the)g(w)o(orst)g(case)g(is)h(not)f(much)f(dif)n (ferent)f(than)i(the)g(a)n(v)o(erage)e(case.)0 5245 y(Ho)n(we)n(v)o(er) m(,)18 b(there)i(are)g(other)f(representations)g(which)g(are)h(more)g (ef)n(\002cient)g(o)o(v)o(erall,)e(yet)i(the)h(w)o(orst)f(cases)h (might)e(be)h(terrible.)0 5392 y(Heaps)27 b(are)h(also)f(v)o(ery)f (useful)h(in)g(big)g(disk)h(sorts.)46 b(Y)-9 b(ou)27 b(most)g(probably)e(all)j(kno)n(w)e(that)i(a)f(big)g(sort)g(implies)h (producing)c(\224runs\224)p 0 5549 3901 4 v 0 5649 a FI(5.4.)52 b FJ(heapq)22 b FI(\227)h(Heap)h(queue)g(algor)q(ithm)2377 b(123)p eop end %%Page: 124 136 TeXDict begin 124 135 bop 0 83 a FN(\(which)19 b(are)g(pre-sorted)f (sequences,)g(which)h(size)i(is)f(usually)f(related)g(to)h(the)f (amount)f(of)i(CPU)g(memory\),)e(follo)n(wed)g(by)h(a)h(mer)o(ging)0 183 y(passes)e(for)f(these)g(runs,)h(which)e(mer)o(ging)g(is)i(often)e (v)o(ery)h(cle)n(v)o(erly)f(or)o(ganised)2262 153 y FF(1)2292 183 y FN(.)24 b(It)18 b(is)g(v)o(ery)e(important)g(that)i(the)f (initial)h(sort)f(produces)0 282 y(the)h(longest)f(runs)g(possible.)24 b(T)-7 b(ournaments)15 b(are)j(a)g(good)e(w)o(ay)i(to)g(that.)24 b(If,)18 b(using)f(all)h(the)g(memory)e(a)n(v)n(ailable)h(to)h(hold)f (a)h(tournament,)0 382 y(you)j(replace)g(and)h(percolate)e(items)j (that)f(happen)e(to)i(\002t)h(the)f(current)e(run,)i(you')o(ll)f (produce)e(runs)j(which)f(are)h(twice)g(the)g(size)h(of)f(the)0 482 y(memory)c(for)i(random)e(input,)i(and)f(much)g(better)h(for)g (input)f(fuzzily)h(ordered.)0 628 y(Moreo)o(v)o(er)m(,)15 b(if)j(you)f(output)g(the)h(0')o(th)e(item)i(on)g(disk)f(and)h(get)f (an)h(input)f(which)h(may)f(not)g(\002t)i(in)f(the)g(current)e (tournament)g(\(because)h(the)0 728 y(v)n(alue)j(\224wins\224)g(o)o(v)o (er)f(the)h(last)h(output)f(v)n(alue\),)f(it)i(cannot)e(\002t)i(in)f (the)h(heap,)e(so)i(the)f(size)h(of)f(the)g(heap)g(decreases.)25 b(The)20 b(freed)f(memory)0 828 y(could)i(be)h(cle)n(v)o(erly)e(reused) h(immediately)g(for)g(progressi)n(v)o(ely)f(b)n(uilding)g(a)i(second)f (heap,)h(which)f(gro)n(ws)g(at)i(e)o(xactly)e(the)h(same)g(rate)0 927 y(the)h(\002rst)g(heap)f(is)i(melting.)32 b(When)23 b(the)g(\002rst)g(heap)f(completely)f(v)n(anishes,)i(you)f(switch)h (heaps)f(and)h(start)g(a)g(ne)n(w)g(run.)32 b(Cle)n(v)o(er)22 b(and)0 1027 y(quite)e(ef)n(fecti)n(v)o(e!)0 1174 y(In)f(a)i(w)o(ord,)d (heaps)i(are)f(useful)h(memory)e(structures)h(to)g(kno)n(w)-5 b(.)24 b(I)c(use)g(them)f(in)h(a)g(fe)n(w)g(applications,)e(and)h(I)h (think)f(it)h(is)h(good)d(to)i(k)o(eep)0 1273 y(a)h(`heap')d(module)h (around.)k(:-\))0 1600 y FE(5.5)121 b Fx(bisect)31 b FE(\227)i(Arr)o(a)l(y)g(bisection)h(algor)r(ithm)0 1833 y FN(This)21 b(module)f(pro)o(vides)f(support)h(for)g(maintaining)f(a)j (list)g(in)f(sorted)f(order)g(without)g(ha)n(ving)g(to)h(sort)g(the)g (list)h(after)f(each)g(insertion.)0 1933 y(F)o(or)28 b(long)f(lists)i(of)f(items)g(with)g(e)o(xpensi)n(v)o(e)e(comparison)g (operations,)i(this)h(can)e(be)h(an)g(impro)o(v)o(ement)d(o)o(v)o(er)h (the)i(more)f(common)0 2032 y(approach.)h(The)21 b(module)g(is)i (called)e FJ(bisect)h FN(because)f(it)i(uses)f(a)g(basic)g(bisection)g (algorithm)e(to)i(do)f(its)i(w)o(ork.)30 b(The)21 b(source)g(code)0 2132 y(may)f(be)g(most)g(useful)g(as)h(a)f(w)o(orking)f(e)o(xample)g (of)h(the)g(algorithm)e(\(the)i(boundary)e(conditions)g(are)i(already)g (right!\).)0 2279 y(The)g(follo)n(wing)e(functions)h(are)h(pro)o (vided:)0 2426 y FD(bisect_left)p FJ(\()p FK(list,)f(item)p FC([)p FK(,)h(lo)p FC([)p FK(,)g(hi)12 b FC(])g(])p FJ(\))208 2525 y FN(Locate)19 b(the)h(proper)e(insertion)h(point)g(for)g FK(item)i FN(in)f FK(list)i FN(to)e(maintain)f(sorted)h(order)-5 b(.)24 b(The)19 b(parameters)g FK(lo)h FN(and)g FK(hi)g FN(may)f(be)h(used)208 2625 y(to)25 b(specify)f(a)i(subset)f(of)g(the)g (list)h(which)e(should)g(be)h(considered;)h(by)f(def)o(ault)f(the)h (entire)g(list)h(is)g(used.)39 b(If)25 b FK(item)h FN(is)g(already)208 2724 y(present)20 b(in)h FK(list)q FN(,)i(the)e(insertion)f(point)g (will)i(be)f(before)f(\(to)h(the)g(left)g(of\))g(an)o(y)f(e)o(xisting)g (entries.)28 b(The)20 b(return)g(v)n(alue)h(is)h(suitable)208 2824 y(for)d(use)i(as)f(the)h(\002rst)g(parameter)d(to)j FK(list)q FJ(.insert\(\))p FN(.)j(This)d(assumes)f(that)h FK(list)h FN(is)f(already)f(sorted.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.1.)0 2971 y FD(bisect_right)p FJ(\()p FK(list,)g(item)p FC([)p FK(,)h(lo)p FC([)p FK(,)g(hi)12 b FC(])g(])p FJ(\))208 3071 y FN(Similar)27 b(to)g FJ(bisect_left\(\))p FN(,)g(b)n(ut)g (returns)f(an)i(insertion)e(point)g(which)h(comes)g(after)g(\(to)g(the) g(right)f(of\))h(an)o(y)f(e)o(xisting)208 3170 y(entries)20 b(of)g FK(item)g FN(in)h FK(list)q FN(.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 3317 y FD(bisect)p FJ(\()p FK(...)p FJ(\))208 3417 y FN(Alias)i(for)e FJ(bisect_right\(\))p FN(.)0 3564 y FD(insort_left)p FJ(\()p FK(list,)g(item)p FC([)p FK(,)h(lo)p FC([)p FK(,)g(hi)12 b FC(])g(])p FJ(\))208 3663 y FN(Insert)23 b FK(item)h FN(in)g FK(list)j FN(in)d(sorted)f (order)-5 b(.)36 b(This)24 b(is)g(equi)n(v)n(alent)f(to)h FK(list)q FJ(.insert\(bisect.bisect_left\()p FK(list)q FJ(,)46 b FK(item)p FJ(,)208 3763 y FK(lo)p FJ(,)j FK(hi)p FJ(\),)g FK(item)p FJ(\))p FN(.)25 b(This)20 b(assumes)h(that)f FK(list)j FN(is)e(already)e(sorted.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.1.)0 3910 y FD(insort_right)p FJ(\()p FK(list,)g(item)p FC([)p FK(,)h(lo)p FC([)p FK(,)g(hi)12 b FC(])g(])p FJ(\))208 4009 y FN(Similar)20 b(to)g FJ(insort_left\(\))p FN(,)e(b)n(ut)i (inserting)g FK(item)g FN(in)h FK(list)i FN(after)c(an)o(y)h(e)o (xisting)f(entries)h(of)g FK(item)p FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 4156 y FD(insort)p FJ(\()p FK(...)p FJ(\))208 4256 y FN(Alias)i(for)e FJ(insort_right\(\))p FN(.)0 4540 y Fv(5.5.1)100 b(Examples)0 4743 y FN(The)19 b FJ(bisect\(\))g FN(function)f(is)i(generally)e(useful)h(for)g(cate)o (gorizing)e(numeric)h(data.)25 b(This)20 b(e)o(xample)e(uses)i FJ(bisect\(\))f FN(to)g(look)g(up)0 4843 y(a)24 b(letter)g(grade)f(for) g(an)h(e)o(xam)f(total)h(\(say\))g(based)f(on)g(a)i(set)f(of)g(ordered) e(numeric)g(breakpoints:)31 b(85)23 b(and)h(up)f(is)i(an)f(`)-7 b(A)e(',)23 b(75..84)f(is)j(a)0 4942 y(`B',)20 b(etc.)p 0 5006 1560 4 v 90 5061 a FB(1)120 5085 y FH(The)14 b(disk)h(balancing) i(algorithms)f(which)g(are)f(current,)h(no)n(w)o(adays,)h(are)e(more)f (anno)o(ying)j(than)e(cle)n(v)o(er)m(,)i(and)e(this)h(is)e(a)g (consequence)k(of)c(the)h(seeking)h(capabilities)0 5163 y(of)f(the)g(disks.)20 b(On)14 b(de)n(vices)j(which)f(cannot)g(seek,)f (lik)o(e)h(big)f(tape)h(dri)n(v)o(es,)g(the)g(story)f(w)o(as)g(quite)h (dif)n(ferent,)h(and)e(one)g(had)g(to)g(be)g(v)o(ery)g(cle)n(v)o(er)i (to)e(ensure)h(\(f)o(ar)f(in)g(adv)n(ance\))0 5242 y(that)20 b(each)h(tape)f(mo)o(v)o(ement)h(will)f(be)f(the)h(most)g(ef)n(fecti)n (v)o(e)i(possible)f(\(that)g(is,)e(will)h(best)g(participate)j(at)d (\224progressing\224)i(the)e(mer)o(ge\).)27 b(Some)20 b(tapes)g(were)g(e)n(v)o(en)g(able)0 5321 y(to)f(read)g(backw)o(ards,)h (and)f(this)g(w)o(as)f(also)h(used)g(to)f(a)o(v)o(oid)h(the)g(re)n (winding)i(time.)k(Belie)n(v)o(e)c(me,)d(real)i(good)e(tape)i(sorts)e (were)h(quite)h(spectacular)i(to)c(w)o(atch!)27 b(From)18 b(all)0 5400 y(times,)f(sorting)h(has)f(al)o(w)o(ays)i(been)f(a)f (Great)h(Art!)k(:-\))p 0 5549 3901 4 v 0 5649 a FI(124)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 125 137 TeXDict begin 125 136 bop 236 174 a FA(>>>)45 b(grades)e(=)i("FEDCBA") 236 266 y(>>>)g(breakpoints)e(=)h([30,)g(44,)h(66,)f(75,)g(85])236 357 y(>>>)h(from)f(bisect)g(import)f(bisect)236 448 y(>>>)i(def)f (grade\(total\):)236 540 y(...)493 b(return)44 b (grades[bisect\(breakpoints,)c(total\)])236 631 y(...)236 722 y(>>>)45 b(grade\(66\))236 814 y('C')236 905 y(>>>)g(map\(grade,)e ([33,)h(99,)g(77,)h(44,)f(12,)g(88]\))236 996 y(['E',)g('A',)g('B',)h ('D',)f('F',)g('A'])0 1598 y FE(5.6)121 b Fx(array)32 b FE(\227)g(Ef\002cient)i(arr)o(a)l(ys)f(of)h(n)o(umer)r(ic)f(v)m (alues)0 1830 y FN(This)e(module)f(de\002nes)h(an)g(object)g(type)f (which)h(can)g(ef)n(\002ciently)f(represent)g(an)h(array)f(of)h(basic)g (v)n(alues:)47 b(characters,)33 b(inte)o(gers,)0 1930 y(\003oating)26 b(point)g(numbers.)43 b(Arrays)27 b(are)f(sequence)g (types)h(and)f(beha)n(v)o(e)f(v)o(ery)h(much)g(lik)o(e)h(lists,)i(e)o (xcept)d(that)h(the)g(type)f(of)h(objects)0 2030 y(stored)f(in)i(them)e (is)i(constrained.)43 b(The)27 b(type)g(is)g(speci\002ed)g(at)h(object) e(creation)g(time)h(by)g(using)f(a)h FK(type)g(code)p FN(,)h(which)e(is)i(a)g(single)0 2129 y(character)-5 b(.)24 b(The)c(follo)n(wing)f(type)g(codes)h(are)g(de\002ned:)674 2356 y FL(T)-6 b(ype)20 b(code)p 1078 2386 4 100 v 99 w(C)h(T)-6 b(ype)p 1669 2386 V 336 w(Python)20 b(T)-6 b(ype)p 2374 2386 V 257 w(Minimum)22 b(size)f(in)g(bytes)p 624 2389 2652 4 v 777 2459 a FJ('c')p 1078 2488 4 100 v 202 w FN(char)p 1669 2488 V 447 w(character)p 2374 2488 V 779 w(1)777 2558 y FJ('b')p 1078 2588 V 202 w FN(signed)f(char)p 1669 2588 V 209 w(int)p 2374 2588 V 997 w(1)777 2658 y FJ('B')p 1078 2688 V 202 w FN(unsigned)f(char)p 1669 2688 V 126 w(int)p 2374 2688 V 997 w(1)777 2757 y FJ('u')p 1078 2787 V 202 w FN(Py)p 1222 2757 25 4 v 30 w(UNICODE)p 1669 2787 4 100 v 99 w(Unicode)g(character)p 2374 2787 V 477 w(2)777 2857 y FJ('h')p 1078 2887 V 202 w FN(signed)h(short)p 1669 2887 V 186 w(int)p 2374 2887 V 997 w(2)777 2957 y FJ('H')p 1078 2987 V 202 w FN(unsigned)f(short)p 1669 2987 V 103 w(int)p 2374 2987 V 997 w(2)777 3056 y FJ('i')p 1078 3086 V 202 w FN(signed)h(int)p 1669 3086 V 265 w(int)p 2374 3086 V 997 w(2)777 3156 y FJ('I')p 1078 3186 V 202 w FN(unsigned)f(int)p 1669 3186 V 182 w(long)p 2374 3186 V 936 w(2)777 3256 y FJ('l')p 1078 3285 V 202 w FN(signed)h(long)p 1669 3285 V 204 w(int)p 2374 3285 V 997 w(4)777 3355 y FJ('L')p 1078 3385 V 202 w FN(unsigned)f(long)p 1669 3385 V 121 w(long)p 2374 3385 V 936 w(4)777 3455 y FJ('f')p 1078 3485 V 202 w FN(\003oat)p 1669 3485 V 443 w(\003oat)p 2374 3485 V 937 w(4)777 3554 y FJ('d')p 1078 3584 V 202 w FN(double)p 1669 3584 V 363 w(\003oat)p 2374 3584 V 937 w(8)0 3780 y(The)j(actual)g(representation)e(of)h(v)n(alues)h(is)h(determined)d (by)i(the)g(machine)f(architecture)g(\(strictly)g(speaking,)g(by)h(the) g(C)h(implemen-)0 3879 y(tation\).)31 b(The)22 b(actual)g(size)h(can)f (be)g(accessed)g(through)f(the)h FJ(itemsize)f FN(attrib)n(ute.)31 b(The)22 b(v)n(alues)g(stored)g(for)g FJ('L')g FN(and)g FJ('I')g FN(items)0 3979 y(will)i(be)g(represented)d(as)j(Python)f (long)f(inte)o(gers)h(when)g(retrie)n(v)o(ed,)f(because)h(Python')-5 b(s)23 b(plain)g(inte)o(ger)f(type)h(cannot)f(represent)h(the)0 4078 y(full)d(range)f(of)h(C')-5 b(s)22 b(unsigned)c(\(long\))h(inte)o (gers.)0 4225 y(The)h(module)f(de\002nes)h(the)g(follo)n(wing)e(type:)0 4372 y FD(array)p FJ(\()p FK(typecode)p FC([)p FK(,)f(initializer)d FC(])p FJ(\))208 4472 y FN(Return)24 b(a)i(ne)n(w)f(array)f(whose)g (items)i(are)f(restricted)g(by)f FK(typecode)p FN(,)h(and)f (initialized)h(from)f(the)h(optional)f FK(initializer)j FN(v)n(alue,)208 4571 y(which)e(must)h(be)g(a)g(list,)j(string,)d(or)g (iterable)g(o)o(v)o(er)e(elements)i(of)g(the)g(appropriate)d(type.)85 b(Changed)25 b(in)h(v)o(ersion)f(2.4:)g(F)o(or)n(-)208 4671 y(merly)-5 b(,)24 b(only)g(lists)i(or)e(strings)h(were)g (accepted.)76 b(If)25 b(gi)n(v)o(en)e(a)i(list)h(or)e(string,)i(the)e (initializer)h(is)g(passed)g(to)g(the)g(ne)n(w)f(array')-5 b(s)208 4771 y FJ(fromlist\(\))p FN(,)23 b FJ(fromstring\(\))p FN(,)f(or)i FJ(fromunicode\(\))d FN(method)i(\(see)h(belo)n(w\))e(to)i (add)f(initial)h(items)h(to)e(the)h(array)-5 b(.)208 4870 y(Otherwise,)19 b(the)h(iterable)g(initializer)g(is)h(passed)f(to) h(the)f FJ(extend\(\))f FN(method.)0 5017 y FD(ArrayType)208 5117 y FN(Obsolete)g(alias)i(for)f FJ(array)p FN(.)0 5264 y(Array)g(objects)g(support)f(the)i(ordinary)d(sequence)i (operations)f(of)h(inde)o(xing,)f(slicing,)h(concatenation,)e(and)i (multiplication.)25 b(When)0 5363 y(using)33 b(slice)i(assignment,)g (the)f(assigned)f(v)n(alue)g(must)h(be)f(an)h(array)f(object)g(with)h (the)f(same)h(type)f(code;)40 b(in)34 b(all)g(other)f(cases,)p 0 5549 3901 4 v 0 5649 a FI(5.6.)52 b FJ(array)22 b FI(\227)h (Ef\002cient)h(arr)o(a)n(ys)d(of)i(n)o(umer)q(ic)h(v)n(alues)1976 b(125)p eop end %%Page: 126 138 TeXDict begin 126 137 bop 0 83 a FJ(TypeError)23 b FN(is)j(raised.)37 b(Array)24 b(objects)g(also)h(implement)e(the)i(b)n(uf)n(fer)e(interf)o (ace,)h(and)g(may)g(be)h(used)f(where)n(v)o(er)f(b)n(uf)n(fer)g (objects)0 183 y(are)d(supported.)0 330 y(The)g(follo)n(wing)e(data)i (items)h(and)f(methods)f(are)h(also)h(supported:)0 476 y FD(typecode)208 576 y FN(The)e(typecode)g(character)g(used)h(to)g (create)g(the)g(array)-5 b(.)0 723 y FD(itemsize)208 823 y FN(The)19 b(length)h(in)g(bytes)g(of)g(one)g(array)f(item)h(in)h (the)f(internal)f(representation.)0 969 y FD(append)p FJ(\()p FK(x)p FJ(\))208 1069 y FN(Append)f(a)j(ne)n(w)f(item)g(with)h (v)n(alue)e FK(x)i FN(to)f(the)g(end)g(of)g(the)g(array)-5 b(.)0 1216 y FD(buffer_info)p FJ(\(\))208 1316 y FN(Return)22 b(a)h(tuple)f FJ(\()p FK(addr)m(ess)p FJ(,)49 b FK(length)p FJ(\))21 b FN(gi)n(ving)g(the)i(current)e(memory)g(address)h(and)h(the) f(length)g(in)h(elements)f(of)g(the)h(b)n(uf)n(fer)208 1415 y(used)h(to)g(hold)g(array')-5 b(s)24 b(contents.)37 b(The)24 b(size)h(of)f(the)h(memory)d(b)n(uf)n(fer)h(in)i(bytes)f(can)g (be)h(computed)d(as)j FK(arr)o(ay)p FJ(.buffer_-)208 1515 y(info\(\)[1])706 1530 y(*)805 1515 y FK(arr)o(ay)p FJ(.itemsize)p FN(.)i(This)21 b(is)h(occasionally)e(useful)h(when)g(w)o (orking)e(with)j(lo)n(w-le)n(v)o(el)e(\(and)g(inherently)208 1614 y(unsafe\))f(I/O)h(interf)o(aces)g(that)g(require)f(memory)g (addresses,)h(such)g(as)h(certain)e FJ(ioctl\(\))h FN(operations.)j (The)d(returned)f(num-)208 1714 y(bers)h(are)g(v)n(alid)f(as)i(long)f (as)h(the)f(array)f(e)o(xists)i(and)e(no)h(length-changing)d (operations)h(are)i(applied)f(to)i(it.)208 1847 y FL(Note:)48 b FN(When)31 b(using)h(array)f(objects)h(from)f(code)g(written)h(in)g (C)h(or)f(C)2358 1840 y(++)2485 1847 y(\(the)f(only)g(w)o(ay)i(to)f(ef) n(fecti)n(v)o(ely)e(mak)o(e)i(use)g(of)208 1946 y(this)26 b(information\),)f(it)h(mak)o(es)g(more)f(sense)i(to)f(use)g(the)g(b)n (uf)n(fer)f(interf)o(ace)g(supported)f(by)i(array)f(objects.)42 b(This)26 b(method)f(is)208 2046 y(maintained)19 b(for)h(backw)o(ard)f (compatibility)g(and)h(should)g(be)h(a)n(v)n(oided)f(in)g(ne)n(w)h (code.)26 b(The)20 b(b)n(uf)n(fer)g(interf)o(ace)g(is)h(documented)208 2146 y(in)f(the)g FK(Python/C)g(API)f(Refer)m(ence)h(Manual)p FN(.)0 2293 y FD(byteswap)p FJ(\(\))208 2392 y FN(\223Bytesw)o(ap\224)d (all)h(items)g(of)g(the)f(array)-5 b(.)23 b(This)18 b(is)g(only)f (supported)f(for)h(v)n(alues)g(which)g(are)g(1,)h(2,)g(4,)g(or)f(8)h (bytes)f(in)h(size;)h(for)e(other)208 2492 y(types)i(of)f(v)n(alues,)h FJ(RuntimeError)f FN(is)i(raised.)k(It)c(is)g(useful)e(when)h(reading)f (data)h(from)f(a)h(\002le)h(written)f(on)g(a)g(machine)f(with)208 2591 y(a)i(dif)n(ferent)f(byte)g(order)-5 b(.)0 2738 y FD(count)p FJ(\()p FK(x)p FJ(\))208 2838 y FN(Return)19 b(the)i(number)d(of)i(occurrences)e(of)i FK(x)h FN(in)f(the)g(array)-5 b(.)0 2985 y FD(extend)p FJ(\()p FK(iter)o(able)p FJ(\))208 3084 y FN(Append)23 b(items)i(from)e FK(iter)o(able)i FN(to)f(the)h(end)f(of)h(the)f(array)-5 b(.)37 b(If)25 b FK(iter)o(able)f FN(is)i(another)d(array)-5 b(,)24 b(it)h(must)g(ha)n(v)o(e)f FK(e)n(xactly)h FN(the)f(same)208 3184 y(type)h(code;)j(if)e(not,)h FJ(TypeError)e FN(will)h(be)g (raised.)42 b(If)26 b FK(iter)o(able)f FN(is)i(not)e(an)h(array)-5 b(,)26 b(it)h(must)e(be)h(iterable)g(and)f(its)i(elements)208 3284 y(must)20 b(be)h(the)g(right)f(type)g(to)h(be)g(appended)e(to)i (the)f(array)-5 b(.)53 b(Changed)20 b(in)h(v)o(ersion)e(2.4:)i(F)o (ormerly)-5 b(,)18 b(the)j(ar)o(gument)e(could)g(only)208 3383 y(be)h(another)e(array)-5 b(.)0 3530 y FD(fromfile)p FJ(\()p FK(f)o(,)19 b(n)p FJ(\))208 3630 y FN(Read)25 b FK(n)h FN(items)f(\(as)h(machine)e(v)n(alues\))h(from)g(the)g(\002le) h(object)f FK(f)38 b FN(and)25 b(append)f(them)h(to)g(the)h(end)e(of)i (the)f(array)-5 b(.)39 b(If)26 b(less)g(than)208 3729 y FK(n)e FN(items)g(are)g(a)n(v)n(ailable,)h FJ(EOFError)e FN(is)i(raised,)g(b)n(ut)f(the)g(items)h(that)f(were)g(a)n(v)n(ailable) g(are)g(still)h(inserted)e(into)h(the)g(array)-5 b(.)36 b FK(f)208 3829 y FN(must)20 b(be)g(a)h(real)f(b)n(uilt-in)f(\002le)i (object;)f(something)f(else)h(with)h(a)f FJ(read\(\))g FN(method)f(w)o(on')o(t)g(do.)0 3976 y FD(fromlist)p FJ(\()p FK(list)q FJ(\))208 4076 y FN(Append)h(items)j(from)e(the)i (list.)32 b(This)22 b(is)i(equi)n(v)n(alent)c(to)j(`)p FJ(for)49 b(x)g(in)h FK(list)q FJ(:)g(a.append\(x\))p FN(')21 b(e)o(xcept)g(that)h(if)h(there)f(is)h(a)208 4175 y(type)c(error)m(,)g(the)h(array)f(is)i(unchanged.)0 4322 y FD(fromstring)p FJ(\()p FK(s)p FJ(\))208 4422 y FN(Appends)d(items)j(from)e(the)h(string,)g(interpreting)e(the)i (string)g(as)h(an)f(array)f(of)h(machine)f(v)n(alues)g(\(as)i(if)f(it)h (had)f(been)f(read)h(from)208 4521 y(a)g(\002le)h(using)f(the)g FJ(fromfile\(\))f FN(method\).)0 4668 y FD(fromunicode)p FJ(\()p FK(s)p FJ(\))208 4768 y FN(Extends)24 b(this)i(array)e(with)i (data)f(from)f(the)i(gi)n(v)o(en)e(unicode)f(string.)40 b(The)25 b(array)g(must)g(be)g(a)h(type)f FJ('u')g FN(array;)i (otherwise)e(a)208 4867 y FJ(ValueError)f FN(is)j(raised.)41 b(Use)27 b(`)p FJ(array.fromstring\(ustr.decode\(enc)o(\)\))p FN(')20 b(to)26 b(append)e(Unicode)h(data)g(to)208 4967 y(an)20 b(array)f(of)h(some)g(other)f(type.)0 5114 y FD(index)p FJ(\()p FK(x)p FJ(\))208 5214 y FN(Return)g(the)i(smallest)f FK(i)h FN(such)f(that)g FK(i)h FN(is)g(the)g(inde)o(x)e(of)h(the)g (\002rst)h(occurrence)d(of)h FK(x)i FN(in)g(the)f(array)-5 b(.)0 5360 y FD(insert)p FJ(\()p FK(i,)19 b(x)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(126)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 127 139 TeXDict begin 127 138 bop 208 83 a FN(Insert)20 b(a)i(ne)n(w)f(item)g (with)g(v)n(alue)g FK(x)h FN(in)f(the)g(array)f(before)g(position)g FK(i)p FN(.)29 b(Ne)o(gati)n(v)o(e)19 b(v)n(alues)i(are)g(treated)g(as) h(being)e(relati)n(v)o(e)g(to)i(the)208 183 y(end)d(of)h(the)g(array)-5 b(.)0 330 y FD(pop)p FJ(\()p FC([)p FK(i)12 b FC(])p FJ(\))208 429 y FN(Remo)o(v)o(es)21 b(the)i(item)f(with)h(the)g(inde)o (x)e FK(i)i FN(from)f(the)g(array)g(and)g(returns)f(it.)33 b(The)22 b(optional)g(ar)o(gument)e(def)o(aults)i(to)h FJ(-1)p FN(,)g(so)f(that)208 529 y(by)d(def)o(ault)h(the)g(last)h(item) f(is)i(remo)o(v)o(ed)17 b(and)j(returned.)0 676 y FD(read)p FJ(\()p FK(f)o(,)g(n)p FJ(\))208 775 y FL(Depr)o(ecated)f(since)i(r)o (elease)e(1.5.1.)24 b FN(Use)d(the)f FJ(fromfile\(\))f FN(method.)208 908 y(Read)25 b FK(n)h FN(items)f(\(as)h(machine)e(v)n (alues\))h(from)g(the)g(\002le)h(object)f FK(f)38 b FN(and)25 b(append)f(them)h(to)g(the)h(end)e(of)i(the)f(array)-5 b(.)39 b(If)26 b(less)g(than)208 1008 y FK(n)e FN(items)g(are)g(a)n(v)n (ailable,)h FJ(EOFError)e FN(is)i(raised,)g(b)n(ut)f(the)g(items)h (that)f(were)g(a)n(v)n(ailable)g(are)g(still)h(inserted)e(into)h(the)g (array)-5 b(.)36 b FK(f)208 1107 y FN(must)20 b(be)g(a)h(real)f(b)n (uilt-in)f(\002le)i(object;)f(something)f(else)h(with)h(a)f FJ(read\(\))g FN(method)f(w)o(on')o(t)g(do.)0 1254 y FD(remove)p FJ(\()p FK(x)p FJ(\))208 1354 y FN(Remo)o(v)o(e)g(the)h (\002rst)h(occurrence)d(of)h FK(x)i FN(from)e(the)i(array)-5 b(.)0 1501 y FD(reverse)p FJ(\(\))208 1600 y FN(Re)n(v)o(erse)19 b(the)i(order)e(of)g(the)i(items)f(in)h(the)f(array)-5 b(.)0 1747 y FD(tofile)p FJ(\()p FK(f)12 b FJ(\))208 1847 y FN(Write)20 b(all)h(items)g(\(as)f(machine)f(v)n(alues\))h(to)g (the)g(\002le)h(object)f FK(f)12 b FN(.)0 1994 y FD(tolist)p FJ(\(\))208 2093 y FN(Con)m(v)o(ert)18 b(the)i(array)g(to)g(an)g (ordinary)e(list)k(with)e(the)g(same)g(items.)0 2240 y FD(tostring)p FJ(\(\))208 2340 y FN(Con)m(v)o(ert)d(the)j(array)e(to) h(an)g(array)g(of)g(machine)f(v)n(alues)h(and)f(return)g(the)h(string)g (representation)e(\(the)i(same)h(sequence)e(of)h(bytes)208 2439 y(that)h(w)o(ould)f(be)h(written)g(to)h(a)f(\002le)h(by)f(the)g FJ(tofile\(\))f FN(method.\))0 2586 y FD(tounicode)p FJ(\(\))208 2686 y FN(Con)m(v)o(ert)f(the)h(array)g(to)h(a)g(unicode)e (string.)24 b(The)19 b(array)g(must)h(be)f(a)h(type)g FJ('u')f FN(array;)g(otherwise)g(a)h FJ(ValueError)e FN(is)j(raised.)208 2786 y(Use)f(`)p FJ (array.tostring\(\).decode\(enc\))p FN(')15 b(to)21 b(obtain)e(a)h (unicode)f(string)h(from)f(an)h(array)g(of)f(some)h(other)g(type.)0 2932 y FD(write)p FJ(\()p FK(f)12 b FJ(\))208 3032 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(1.5.1.)24 b FN(Use)d(the)f FJ(tofile\(\))f FN(method.)208 3165 y(Write)h(all)h(items)g(\(as)f(machine)f(v)n(alues\))h(to)g(the)g (\002le)h(object)f FK(f)12 b FN(.)0 3312 y(When)28 b(an)g(array)g (object)f(is)j(printed)d(or)h(con)m(v)o(erted)d(to)k(a)f(string,)i(it)f (is)g(represented)e(as)i FJ(array\()p FK(typecode)p FJ(,)46 b FK(initializer)r FJ(\))p FN(.)k(The)0 3411 y FK(initializer)33 b FN(is)e(omitted)e(if)h(the)g(array)g(is)h(empty)-5 b(,)31 b(otherwise)e(it)i(is)g(a)f(string)g(if)h(the)f FK(typecode)e FN(is)k FJ('c')p FN(,)g(otherwise)d(it)i(is)g(a)g(list)g (of)0 3511 y(numbers.)44 b(The)27 b(string)f(is)i(guaranteed)d(to)i(be) g(able)g(to)g(be)g(con)m(v)o(erted)e(back)h(to)h(an)g(array)f(with)h (the)h(same)f(type)f(and)h(v)n(alue)f(using)0 3611 y(re)n(v)o(erse)e (quotes)h(\()p FJ(``)p FN(\),)h(so)g(long)f(as)h(the)g FJ(array\(\))e FN(function)g(has)i(been)f(imported)f(using)h FJ(from)49 b(array)f(import)h(array)p FN(.)0 3710 y(Examples:)236 3857 y FA(array\('l'\))236 3948 y(array\('c',)43 b('hello)h(world'\)) 236 4040 y(array\('u',)f(u'hello)h(\\textbackslash)f(u2641'\))236 4131 y(array\('l',)g([1,)i(2,)f(3,)h(4,)f(5]\))236 4222 y(array\('d',)f([1.0,)h(2.0,)h(3.14]\))0 4510 y FL(See)21 b(Also:)0 4656 y FN(Module)e FJ(struct)h FN(\(section)f(4.3\):)208 4756 y(P)o(acking)g(and)g(unpacking)f(of)i(heterogeneous)d(binary)i (data.)0 4903 y(Module)g FJ(xdrlib)h FN(\(section)f(9.5\):)208 5003 y(P)o(acking)27 b(and)i(unpacking)d(of)j(External)f(Data)h (Representation)e(\(XDR\))i(data)g(as)h(used)f(in)g(some)g(remote)f (procedure)e(call)208 5102 y(systems.)0 5249 y FK(The)20 b(Numerical)h(Python)e(Manual)0 5349 y Fy(\()p FO(http://n)o(ump)n(y)-7 b(.sourcef)n(orge)o(.)o(ne)o(t/n)n(umdoc/HT)o(ML/n)n(umdoc.h)o(tm)h Fy(\))p 0 5549 3901 4 v 0 5649 a FI(5.6.)52 b FJ(array)22 b FI(\227)h(Ef\002cient)h(arr)o(a)n(ys)d(of)i(n)o(umer)q(ic)h(v)n (alues)1976 b(127)p eop end %%Page: 128 140 TeXDict begin 128 139 bop 208 83 a FN(The)37 b(Numeric)g(Python)f(e)o (xtension)h(\(NumPy\))f(de\002nes)h(another)g(array)f(type;)47 b(see)38 b FO(http://n)o(ump)n(y)-7 b(.sourcef)n(orge)o(.)o(ne)o(t/)32 b FN(for)208 183 y(further)45 b(information)f(about)i(Numerical)g (Python.)103 b(\(A)47 b(PDF)h(v)o(ersion)d(of)i(the)f(NumPy)g(manual)g (is)i(a)n(v)n(ailable)e(at)208 282 y FO(http://n)o(ump)n(y)-7 b(.sourcef)n(orge)n(.ne)o(t/n)n(umdo)o(c/n)o(umdo)o(c.pd)o(f)h FN(\).)0 610 y FE(5.7)121 b Fx(sets)32 b FE(\227)h(Unordered)j (collections)d(of)h(unique)h(elements)0 843 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 989 y(The)d FJ(sets)g FN(module)f(pro)o (vides)g(classes)j(for)d(constructing)g(and)h(manipulating)e(unordered) g(collections)h(of)i(unique)d(elements.)24 b(Com-)0 1089 y(mon)18 b(uses)h(include)e(membership)g(testing,)h(remo)o(ving)e (duplicates)i(from)f(a)i(sequence,)f(and)g(computing)e(standard)h(math) h(operations)0 1189 y(on)i(sets)h(such)f(as)h(intersection,)e(union,)f (dif)n(ference,)g(and)i(symmetric)f(dif)n(ference.)0 1336 y(Lik)o(e)25 b(other)f(collections,)i(sets)g(support)e FK(x)50 b FJ(in)f FK(set)q FN(,)27 b FJ(len\()p FK(set)q FJ(\))p FN(,)g(and)d FJ(for)50 b FK(x)g FJ(in)f FK(set)q FN(.)41 b(Being)25 b(an)g(unordered)d(collection,)j(sets)0 1435 y(do)30 b(not)g(record)f(element)h(position)f(or)h(order)f(of)h (insertion.)55 b(Accordingly)-5 b(,)30 b(sets)h(do)f(not)g(support)f (inde)o(xing,)i(slicing,)h(or)e(other)0 1535 y(sequence-lik)o(e)18 b(beha)n(vior)-5 b(.)0 1682 y(Most)27 b(set)g(applications)e(use)h(the) g FJ(Set)h FN(class)g(which)f(pro)o(vides)e(e)n(v)o(ery)h(set)i(method) e(e)o(xcept)g(for)h FJ(__hash__\(\))p FN(.)42 b(F)o(or)26 b(adv)n(anced)0 1781 y(applications)e(requiring)g(a)i(hash)f(method,)h (the)g FJ(ImmutableSet)e FN(class)i(adds)g(a)g FJ(__hash__\(\))e FN(method)g(b)n(ut)i(omits)g(methods)0 1881 y(which)d(alter)h(the)f (contents)g(of)h(the)f(set.)36 b(Both)24 b FJ(Set)f FN(and)g FJ(ImmutableSet)f FN(deri)n(v)o(e)h(from)f FJ(BaseSet)p FN(,)i(an)f(abstract)h(class)g(useful)0 1981 y(for)c(determining)e (whether)h(something)f(is)k(a)e(set:)26 b FJ(isinstance\()p FK(obj)p FJ(,)47 b(BaseSet\))p FN(.)0 2127 y(The)31 b(set)g(classes)h (are)f(implemented)e(using)i(dictionaries.)56 b(Accordingly)-5 b(,)31 b(the)g(requirements)e(for)h(set)i(elements)e(are)h(the)g(same)0 2227 y(as)43 b(those)e(for)h(dictionary)e(k)o(e)o(ys;)53 b(namely)-5 b(,)45 b(that)d(the)g(element)g(de\002nes)f(both)h FJ(__eq__)f FN(and)g FJ(__hash__)p FN(.)90 b(As)42 b(a)h(result,)0 2327 y(sets)38 b(cannot)f(contain)f(mutable)h(elements)g(such)g(as)h (lists)h(or)e(dictionaries.)75 b(Ho)n(we)n(v)o(er)m(,)40 b(the)o(y)c(can)h(contain)g(immutable)f(col-)0 2426 y(lections)h(such)f (as)h(tuples)g(or)f(instances)h(of)f FJ(ImmutableSet)p FN(.)73 b(F)o(or)37 b(con)m(v)o(enience)c(in)k(implementing)e(sets)i (of)g(sets,)k(inner)0 2526 y(sets)36 b(are)f(automatically)e(con)m(v)o (erted)f(to)j(immutable)f(form,)j(for)d(e)o(xample,)j FJ(Set\([Set\(['dog']\)]\))32 b FN(is)k(transformed)c(to)0 2626 y FJ(Set\([ImmutableSet\(['dog']\)]\))p FN(.)0 2772 y FL(class)21 b FD(Set)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 2872 y FN(Constructs)17 b(a)h(ne)n(w)g(empty)f FJ(Set)g FN(object.)24 b(If)17 b(the)h(optional)f FK(iter)o(able)g FN(parameter)f(is)j(supplied,)e(updates)g(the)g(set)i(with)f(elements) 208 2972 y(obtained)c(from)h(iteration.)23 b(All)17 b(of)f(the)g (elements)g(in)g FK(iter)o(able)g FN(should)f(be)i(immutable)d(or)i(be) h(transformable)c(to)k(an)f(immutable)208 3071 y(using)j(the)h (protocol)f(described)g(in)h(section)g(5.7.3.)0 3218 y FL(class)h FD(ImmutableSet)p FJ(\()p FC([)p FK(iter)o(able)12 b FC(])p FJ(\))208 3318 y FN(Constructs)19 b(a)i(ne)n(w)e(empty)g FJ(ImmutableSet)g FN(object.)24 b(If)c(the)g(optional)e FK(iter)o(able)i FN(parameter)e(is)j(supplied,)e(updates)g(the)h(set) 208 3417 y(with)h(elements)f(obtained)f(from)h(iteration.)26 b(All)21 b(of)g(the)g(elements)f(in)h FK(iter)o(able)g FN(should)e(be)i(immutable)f(or)g(be)h(transformable)208 3517 y(to)f(an)g(immutable)f(using)h(the)g(protocol)e(described)h(in)i (section)e(5.7.3.)208 3650 y(Because)29 b FJ(ImmutableSet)e FN(objects)h(pro)o(vide)f(a)i FJ(__hash__\(\))f FN(method,)h(the)o(y)g (can)f(be)h(used)g(as)g(set)h(elements)e(or)h(as)208 3749 y(dictionary)20 b(k)o(e)o(ys.)31 b FJ(ImmutableSet)21 b FN(objects)h(do)g(not)f(ha)n(v)o(e)h(methods)f(for)h(adding)f(or)h (remo)o(ving)e(elements,)i(so)h(all)g(of)f(the)208 3849 y(elements)d(must)i(be)f(kno)n(wn)e(when)i(the)g(constructor)f(is)i (called.)0 4134 y Fv(5.7.1)100 b(Set)28 b(Objects)0 4337 y FN(Instances)20 b(of)g FJ(Set)g FN(and)f FJ(ImmutableSet)g FN(both)g(pro)o(vide)f(the)j(follo)n(wing)d(operations:)p 0 5549 3901 4 v 0 5649 a FI(128)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 129 141 TeXDict begin 129 140 bop 657 70 a FL(Operation)p 1488 100 4 100 v 517 w(Equi)o(v)o(alent)p 1974 100 V 99 w(Result)p 188 103 3525 4 v 698 173 a FJ(len\()p FK(s)p FJ(\))p 1488 203 4 100 v 1974 203 V 1045 w FN(cardinality)19 b(of)h(set)h FK(s)p 188 206 3525 4 v 704 276 a(x)50 b FJ(in)g FK(s)p 1488 306 4 100 v 1974 306 V 1052 w FN(test)21 b FK(x)g FN(for)f(membership)e(in)i FK(s)605 375 y(x)50 b FJ(not)f(in)g FK(s)p 1488 405 V 1974 405 V 953 w FN(test)21 b FK(x)g FN(for)f(non-membership)c(in)k FK(s)536 475 y(s)p FJ(.issubset\()p FK(t)q FJ(\))p 1488 505 V 463 w FK(s)50 b FJ(<=)f FK(t)p 1974 505 V 166 w FN(test)21 b(whether)e(e)n(v)o(ery)g(element)h(in)g FK(s)h FN(is)g(in)g FK(t)487 575 y(s)p FJ(.issuperset\()p FK(t)q FJ(\))p 1488 604 V 412 w FK(s)50 b FJ(>=)f FK(t)p 1974 604 V 166 w FN(test)21 b(whether)e(e)n(v)o(ery)g(element)h(in)g FK(t)j FN(is)e(in)f FK(s)p 188 608 3525 4 v 611 677 a(s)p FJ(.union\()p FK(t)q FJ(\))p 1488 707 4 100 v 605 w FK(s)h FM(j)g FK(t)p 1974 707 V 233 w FN(ne)n(w)f(set)h(with)g(elements)e (from)h(both)f FK(s)i FN(and)f FK(t)437 777 y(s)p FJ(.intersection\()p FK(t)q FJ(\))p 1488 807 V 408 w FK(s)h FN(&)g FK(t)p 1974 807 V 212 w FN(ne)n(w)f(set)h(with)g(elements)e(common)g(to)h FK(s)h FN(and)f FK(t)487 877 y(s)p FJ(.difference\()p FK(t)q FJ(\))p 1488 907 V 477 w FK(s)h FN(-)f FK(t)p 1974 907 V 231 w FN(ne)n(w)g(set)h(with)g(elements)e(in)i FK(s)g FN(b)n(ut)f(not)g(in)g FK(t)237 976 y(s)p FJ (.symmetric_difference\()p FK(t)q FJ(\))p 1488 1006 V 227 w FK(s)h FN(\210)f FK(t)p 1974 1006 V 231 w FN(ne)n(w)g(set)h(with) g(elements)e(in)i(either)f FK(s)h FN(or)f FK(t)i FN(b)n(ut)e(not)g (both)648 1076 y FK(s)p FJ(.copy\(\))p 1488 1106 V 1974 1106 V 995 w FN(ne)n(w)g(set)h(with)g(a)f(shallo)n(w)g(cop)o(y)f(of)h FK(s)0 1297 y FN(Note,)55 b(the)49 b(non-operator)44 b(v)o(ersions)k(of)g FJ(union\(\))p FN(,)54 b FJ(intersection\(\))p FN(,)g FJ(difference\(\))p FN(,)f(and)48 b FJ(symmetric_-)0 1397 y(difference\(\))31 b FN(will)i(accept)f(an)o(y)g(iterable)g(as)i (an)e(ar)o(gument.)60 b(In)32 b(contrast,)j(their)d(operator)f(based)h (counterparts)f(require)0 1496 y(their)c(ar)o(guments)e(to)i(be)g (sets.)46 b(This)27 b(precludes)f(error)n(-prone)e(constructions)h(lik) o(e)i FJ(Set\('abc'\))48 b(&)i('cbs')26 b FN(in)h(f)o(a)n(v)n(or)g(of)g (the)0 1596 y(more)20 b(readable)f FJ (Set\('abc'\).intersection\('cbs'\))p FN(.)48 b(Changed)20 b(in)g(v)o(ersion)g(2.3.1:)f(F)o(ormerly)g(all)i(ar)o(guments)e(were)0 1695 y(required)f(to)j(be)f(sets.)0 1842 y(In)k(addition,)g(both)f FJ(Set)h FN(and)g FJ(ImmutableSet)e FN(support)h(set)i(to)f(set)h (comparisons.)36 b(T)-7 b(w)o(o)24 b(sets)h(are)f(equal)g(if)g(and)g (only)f(if)i(e)n(v)o(ery)0 1942 y(element)20 b(of)g(each)g(set)i(is)f (contained)e(in)i(the)f(other)g(\(each)g(is)h(a)g(subset)g(of)f(the)h (other\).)k(A)c(set)g(is)h(less)f(than)f(another)f(set)j(if)f(and)f (only)f(if)0 2042 y(the)k(\002rst)h(set)g(is)h(a)e(proper)f(subset)h (of)g(the)h(second)e(set)i(\(is)g(a)g(subset,)g(b)n(ut)f(is)h(not)f (equal\).)33 b(A)24 b(set)g(is)g(greater)f(than)g(another)e(set)k(if)e (and)0 2141 y(only)c(if)i(the)f(\002rst)h(set)g(is)g(a)g(proper)d (superset)i(of)g(the)g(second)f(set)i(\(is)g(a)g(superset,)e(b)n(ut)i (is)g(not)f(equal\).)0 2288 y(The)e(subset)h(and)g(equality)e (comparisons)g(do)i(not)f(generalize)g(to)h(a)g(complete)f(ordering)e (function.)23 b(F)o(or)18 b(e)o(xample,)g(an)o(y)g(tw)o(o)h(disjoint)0 2388 y(sets)33 b(are)f(not)g(equal)f(and)g(are)h(not)g(subsets)g(of)g (each)g(other)m(,)h(so)f FK(all)h FN(of)e(the)h(follo)n(wing)f(return)f FJ(False)p FN(:)49 b FK(a)p FJ(<)p FK(b)p FN(,)34 b FK(a)p FJ(==)p FK(b)p FN(,)g(or)d FK(a)p FJ(>)p FK(b)p FN(.)0 2487 y(Accordingly)-5 b(,)17 b(sets)k(do)f(not)g(implement)f(the)h FJ(__cmp__)g FN(method.)0 2634 y(Since)k(sets)i(only)d(de\002ne)h (partial)g(ordering)f(\(subset)h(relationships\),)f(the)i(output)e(of)h (the)g FJ(list.sort\(\))f FN(method)g(is)j(unde\002ned)0 2734 y(for)20 b(lists)h(of)f(sets.)0 2881 y(The)g(follo)n(wing)e(table) j(lists)g(operations)e(a)n(v)n(ailable)g(in)i FJ(ImmutableSet)d FN(b)n(ut)j(not)e(found)g(in)h FJ(Set)p FN(:)1303 3103 y FL(Operation)p 1715 3133 V 98 w(Result)p 1253 3136 1394 4 v 1319 3206 a FJ(hash\()p FK(s)p FJ(\))p 1715 3236 4 100 v 116 w FN(returns)f(a)i(hash)f(v)n(alue)f(for)h FK(s)0 3427 y FN(The)g(follo)n(wing)e(table)j(lists)g(operations)e(a)n (v)n(ailable)g(in)i FJ(Set)f FN(b)n(ut)g(not)g(found)f(in)h FJ(ImmutableSet)p FN(:)643 3730 y FL(Operation)p 1649 3760 V 692 w(Equi)o(v)o(alent)p 2135 3760 V 99 w(Result)p 0 3764 4719 4 v 573 3833 a FK(s)p FJ(.update\()p FK(t)q FJ(\))p 1649 3863 4 100 v 731 w FK(s)h FM(j)p FN(=)f FK(t)p 2135 3863 V 210 w FN(return)f(set)i FK(s)g FN(with)g(elements)f (added)f(from)g FK(t)249 3933 y(s)p FJ(.intersection_update\()p FK(t)q FJ(\))p 1649 3963 V 384 w FK(s)i FN(&=)f FK(t)p 2135 3963 V 189 w FN(return)f(set)i FK(s)g FN(k)o(eeping)e(only)g (elements)h(also)h(found)d(in)j FK(t)299 4033 y(s)p FJ (.difference_update\()p FK(t)q FJ(\))p 1649 4063 V 452 w FK(s)g FN(-=)f FK(t)p 2135 4063 V 208 w FN(return)f(set)i FK(s)g FN(after)f(remo)o(ving)e(elements)i(found)e(in)j FK(t)50 4132 y(s)p FJ(.symmetric_difference_update\()p FK(t)q FJ(\))p 1649 4162 V 201 w FK(s)g FN(\210=)f FK(t)p 2135 4162 V 208 w FN(return)f(set)i FK(s)g FN(with)g(elements)f(from)f FK(s)i FN(or)f FK(t)i FN(b)n(ut)e(not)g(both)p 0 4165 4719 4 v 641 4235 a FK(s)p FJ(.add\()p FK(x)p FJ(\))p 1649 4265 4 100 v 2135 4265 V 1176 w FN(add)g(element)f FK(x)i FN(to)g(set)g FK(s)567 4335 y(s)p FJ(.remove\()p FK(x)p FJ(\))p 1649 4365 V 2135 4365 V 1100 w FN(remo)o(v)o(e)d FK(x)j FN(from)e(set)i FK(s)p FN(;)h(raises)e FJ(KeyError)g FN(if)g(not)g(present)542 4434 y FK(s)p FJ(.discard\()p FK(x)p FJ(\))p 1649 4464 V 2135 4464 V 1075 w FN(remo)o(v)o(es)f FK(x)i FN(from)e(set)i FK(s)g FN(if)f(present)660 4534 y FK(s)p FJ(.pop\(\))p 1649 4564 V 2135 4564 V 1194 w FN(remo)o(v)o(e)e(and)i(return)f(an)h(arbitrary)f(element)g(from)h FK(s)p FN(;)h(raises)g FJ(KeyError)e FN(if)h(empty)610 4634 y FK(s)p FJ(.clear\(\))p 1649 4664 V 2135 4664 V 1144 w FN(remo)o(v)o(e)e(all)j(elements)f(from)f(set)i FK(s)0 4855 y FN(Note,)34 b(the)e(non-operator)c(v)o(ersions)j(of)g FJ(update\(\))p FN(,)j FJ(intersection_update\(\))p FN(,)d FJ(difference_update\(\))p FN(,)g(and)0 4954 y FJ (symmetric_difference_update\(\))19 b FN(will)24 b(accept)f(an)o(y)f (iterable)h(as)h(an)g(ar)o(gument.)67 b(Changed)22 b(in)i(v)o(ersion)e (2.3.1:)g(F)o(or)n(-)0 5054 y(merly)d(all)i(ar)o(guments)d(were)i (required)f(to)h(be)g(sets.)0 5201 y(Also)j(note,)f(the)g(module)f (also)h(includes)g(a)g FJ(union_update\(\))e FN(method)h(which)h(is)h (an)f(alias)h(for)f FJ(update\(\))p FN(.)30 b(The)22 b(method)f(is)0 5300 y(included)f(for)h(backw)o(ards)f(compatibility)-5 b(.)26 b(Programmers)19 b(should)i(prefer)f(the)h FJ(update\(\))g FN(method)f(because)g(it)i(is)h(supported)c(by)0 5400 y(the)h(b)n(uiltin)g FJ(set\(\))g FN(and)g FJ(frozenset\(\))e FN(types.)p 0 5549 3901 4 v 0 5649 a FI(5.7.)52 b FJ(sets)22 b FI(\227)i(Unordered)f(collections)g(of)h(unique)g(elements)1717 b(129)p eop end %%Page: 130 142 TeXDict begin 130 141 bop 0 83 a Fv(5.7.2)100 b(Example)0 377 y FA(>>>)44 b(from)g(sets)h(import)e(Set)0 469 y(>>>)h(engineers)g (=)g(Set\(['John',)f('Jane',)h('Jack',)f('Janice']\))0 560 y(>>>)h(programmers)f(=)i(Set\(['Jack',)e('Sam',)h('Susan',)f ('Janice']\))0 651 y(>>>)h(managers)g(=)g(Set\(['Jane',)f('Jack',)h ('Susan',)f('Zack']\))0 743 y(>>>)h(employees)g(=)g(engineers)g(|)g (programmers)f(|)i(managers)492 b(#)44 b(union)0 834 y(>>>)g(engineering_management)d(=)k(engineers)e(&)i(managers)537 b(#)44 b(intersection)0 925 y(>>>)g(fulltime_management)e(=)j(managers) e(-)i(engineers)e(-)i(programmers)e(#)h(difference)0 1017 y(>>>)g(engineers.add\('Marvin'\))1521 b(#)44 b(add)h(element)0 1108 y(>>>)f(print)g(engineers)0 1199 y(Set\(['Jane',)f('Marvin',)g ('Janice',)g('John',)h('Jack']\))0 1290 y(>>>)g (employees.issuperset\(engineers\))219 b(#)45 b(superset)e(test)0 1382 y(False)0 1473 y(>>>)h(employees.update\(engineers\))399 b(#)45 b(update)f(from)g(another)g(set)0 1564 y(>>>)g (employees.issuperset\(engineers\))0 1656 y(True)0 1747 y(>>>)g(for)h(group)f(in)g([engineers,)f(programmers,)g(managers,)g (employees]:)0 1838 y(...)224 b(group.discard\('Susan'\))444 b(#)45 b(unconditionally)d(remove)i(element)0 1930 y(...)224 b(print)44 b(group)0 2021 y(...)0 2112 y(Set\(['Jane',)f('Marvin',)g ('Janice',)g('John',)h('Jack']\))0 2204 y(Set\(['Janice',)e('Jack',)i ('Sam']\))0 2295 y(Set\(['Jane',)f('Zack',)g('Jack']\))0 2386 y(Set\(['Jack',)g('Sam',)h('Jane',)f('Marvin',)h('Janice',)f ('John',)h('Zack']\))0 2810 y Fv(5.7.3)100 b(Protocol)29 b(f)m(or)f(automatic)h(con)n(v)n(ersion)g(to)f(imm)o(utab)n(le)0 3013 y FN(Sets)i(can)f(only)f(contain)g(immutable)g(elements.)51 b(F)o(or)28 b(con)m(v)o(enience,)g(mutable)g FJ(Set)h FN(objects)g(are)g(automatically)f(copied)f(to)j(an)0 3113 y FJ(ImmutableSet)19 b FN(before)f(being)i(added)f(as)h(a)h(set)g (element.)0 3260 y(The)g(mechanism)f(is)i(to)g(al)o(w)o(ays)g(add)f(a)g (hashable)g(element,)g(or)g(if)g(it)h(is)h(not)e(hashable,)f(the)i (element)e(is)j(check)o(ed)d(to)h(see)h(if)g(it)g(has)g(an)0 3360 y FJ(__as_immutable__\(\))17 b FN(method)i(which)h(returns)f(an)h (immutable)f(equi)n(v)n(alent.)0 3506 y(Since)g FJ(Set)h FN(objects)f(ha)n(v)o(e)f(a)i FJ(__as_immutable__\(\))d FN(method)h(returning)f(an)i(instance)g(of)g FJ(ImmutableSet)p FN(,)f(it)i(is)g(possible)0 3606 y(to)g(construct)f(sets)j(of)e(sets.)0 3753 y(A)h(similar)g(mechanism)f(is)h(needed)f(by)g(the)h FJ(__contains__\(\))e FN(and)h FJ(remove\(\))g FN(methods)g(which)g (need)g(to)h(hash)f(an)h(element)0 3853 y(to)j(check)e(for)h (membership)f(in)i(a)g(set.)35 b(Those)23 b(methods)g(check)g(an)g (element)g(for)g(hashability)f(and,)i(if)g(not,)g(check)e(for)h(a)h FJ(__as_-)0 3952 y(temporarily_immutable__\(\))c FN(method)i(which)h (returns)g(the)g(element)g(wrapped)f(by)i(a)g(class)g(that)g(pro)o (vides)e(temporary)0 4052 y(methods)d(for)h FJ(__hash__\(\))p FN(,)e FJ(__eq__\(\))p FN(,)h(and)h FJ(__ne__\(\))p FN(.)0 4199 y(The)g(alternate)f(mechanism)g(spares)i(the)f(need)f(to)i(b)n (uild)e(a)i(separate)f(cop)o(y)f(of)h(the)g(original)f(mutable)g (object.)0 4345 y FJ(Set)42 b FN(objects)g(implement)f(the)h FJ(__as_temporarily_immutable__\(\))c FN(method)j(which)g(returns)h (the)g FJ(Set)g FN(object)0 4445 y(wrapped)19 b(by)g(a)i(ne)n(w)f (class)h FJ(_TemporarilyImmutableSet)p FN(.)0 4592 y(The)31 b(tw)o(o)g(mechanisms)g(for)f(adding)g(hashability)g(are)i(normally)d (in)m(visible)i(to)g(the)g(user;)37 b(ho)n(we)n(v)o(er)m(,)32 b(a)f(con\003ict)g(can)g(arise)h(in)f(a)0 4692 y(multi-threaded)h(en)m (vironment)f(where)j(one)g(thread)g(is)h(updating)e(a)i(set)g(while)g (another)e(has)i(temporarily)d(wrapped)h(it)j(in)e FJ(_-)0 4791 y(TemporarilyImmutableSet)p FN(.)21 b(In)f(other)f(w)o(ords,)h (sets)h(of)f(mutable)g(sets)h(are)f(not)g(thread-safe.)0 5076 y Fv(5.7.4)100 b(Compar)q(ison)30 b(to)e(the)g(b)n(uilt-in)h Fm(set)e Fv(types)0 5279 y FN(The)d(b)n(uilt-in)g FJ(set)h FN(and)f FJ(frozenset)g FN(types)g(were)h(designed)e(based)i(on)f (lessons)h(learned)f(from)f(the)i FJ(sets)g FN(module.)37 b(The)24 b(k)o(e)o(y)0 5379 y(dif)n(ferences)18 b(are:)p 0 5549 3901 4 v 0 5649 a FI(130)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 131 143 TeXDict begin 131 142 bop 125 83 a FM(\017)41 b FJ(Set)20 b FN(and)f FJ(ImmutableSet)g FN(were)h(renamed)f(to)h FJ(set)g FN(and)g FJ(frozenset)p FN(.)125 249 y FM(\017)41 b FN(There)19 b(is)i(no)f(equi)n(v)n(alent)e(to)j FJ(BaseSet)p FN(.)j(Instead,)19 b(use)i FJ(isinstance\(x,)47 b(\(set,)i (frozenset\)\))p FN(.)125 415 y FM(\017)41 b FN(The)19 b(hash)h(algorithm)f(for)h(the)g(b)n(uilt-ins)g(performs)e (signi\002cantly)h(better)h(\(fe)n(wer)f(collisions\))h(for)g(most)g (datasets.)125 581 y FM(\017)41 b FN(The)19 b(b)n(uilt-in)h(v)o (ersions)f(ha)n(v)o(e)h(more)f(space)h(ef)n(\002cient)g(pickles.)125 747 y FM(\017)41 b FN(The)20 b(b)n(uilt-in)f(v)o(ersions)h(do)g(not)g (ha)n(v)o(e)g(a)g FJ(union_update\(\))f FN(method.)24 b(Instead,)19 b(use)i(the)f FJ(update\(\))g FN(method)f(which)h(is)208 847 y(equi)n(v)n(alent.)125 1013 y FM(\017)41 b FN(The)24 b(b)n(uilt-in)f(v)o(ersions)h(do)g(not)g(ha)n(v)o(e)g(a)h FJ(_repr\(sorted=True\))c FN(method.)37 b(Instead,)24 b(use)h(the)f(b)n(uilt-in)g FJ(repr\(\))g FN(and)208 1112 y FJ(sorted\(\))19 b FN(functions:)24 b FJ(repr\(sorted\(s\)\))p FN(.)125 1279 y FM(\017)41 b FN(The)22 b(b)n(uilt-in)h(v)o(ersion)f (does)h(not)g(ha)n(v)o(e)f(a)i(protocol)d(for)i(automatic)f(con)m(v)o (ersion)e(to)k(immutable.)32 b(Man)o(y)22 b(found)g(this)i(feature)208 1378 y(to)c(be)g(confusing)e(and)i(no)g(one)f(in)i(the)f(community)e (reported)g(ha)n(ving)h(found)g(real)h(uses)h(for)e(it.)0 1789 y FE(5.8)121 b Fx(sched)32 b FE(\227)g(Ev)m(ent)i(scheduler)0 2021 y FN(The)20 b FJ(sched)g FN(module)e(de\002nes)i(a)h(class)g (which)f(implements)f(a)i(general)e(purpose)f(e)n(v)o(ent)i(scheduler:) 0 2168 y FL(class)h FD(scheduler)p FJ(\()p FK(timefunc,)c(delayfunc)p FJ(\))208 2268 y FN(The)j FJ(scheduler)h FN(class)h(de\002nes)f(a)g (generic)f(interf)o(ace)h(to)g(scheduling)f(e)n(v)o(ents.)27 b(It)22 b(needs)e(tw)o(o)i(functions)e(to)h(actually)g(deal)208 2368 y(with)k(the)g(\223outside)f(w)o(orld\224)h(\227)g FK(timefunc)g FN(should)f(be)h(callable)g(without)f(ar)o(guments,)g (and)h(return)e(a)j(number)d(\(the)i(\223time\224,)208 2467 y(in)h(an)o(y)f(units)i(whatsoe)n(v)o(er\).)40 b(The)26 b FK(delayfunc)f FN(function)f(should)h(be)h(callable)g(with)h(one)e (ar)o(gument,)g(compatible)g(with)i(the)208 2567 y(output)c(of)i FK(timefunc)p FN(,)g(and)f(should)g(delay)g(that)h(man)o(y)f(time)h (units.)39 b FK(delayfunc)23 b FN(will)i(also)g(be)g(called)g(with)g (the)g(ar)o(gument)d FJ(0)208 2666 y FN(after)d(each)h(e)n(v)o(ent)g (is)h(run)e(to)h(allo)n(w)h(other)e(threads)g(an)i(opportunity)c(to)j (run)g(in)g(multi-threaded)d(applications.)0 2813 y(Example:)236 3051 y FA(>>>)45 b(import)e(sched,)h(time)236 3143 y(>>>)h (s=sched.scheduler\(time.time,)40 b(time.sleep\))236 3234 y(>>>)45 b(def)f(print_time\(\):)f(print)h("From)g(print_time",)e (time.time\(\))236 3325 y(...)236 3417 y(>>>)j(def)f (print_some_times\(\):)236 3508 y(...)224 b(print)44 b(time.time\(\))236 3599 y(...)224 b(s.enter\(5,)43 b(1,)i(print_time,) e(\(\)\))236 3691 y(...)224 b(s.enter\(10,)43 b(1,)h(print_time,)f (\(\)\))236 3782 y(...)224 b(s.run\(\))236 3873 y(...)g(print)44 b(time.time\(\))236 3965 y(...)236 4056 y(>>>)h(print_some_times\(\)) 236 4147 y(930343690.257)236 4239 y(From)f(print_time)g(930343695.274) 236 4330 y(From)g(print_time)g(930343700.273)236 4421 y(930343700.276)0 4846 y Fv(5.8.1)100 b(Scheduler)30 b(Objects)0 5049 y FJ(scheduler)19 b FN(instances)h(ha)n(v)o(e)g(the)g (follo)n(wing)f(methods:)0 5196 y FD(enterabs)p FJ(\()p FK(time)o(,)g(priority)-5 b(,)21 b(action,)e(ar)m(gument)q FJ(\))208 5296 y FN(Schedule)26 b(a)h(ne)n(w)g(e)n(v)o(ent.)45 b(The)27 b FK(time)g FN(ar)o(gument)e(should)h(be)h(a)h(numeric)e(type) g(compatible)g(with)h(the)g(return)f(v)n(alue)h(of)g(the)p 0 5549 3901 4 v 0 5649 a FI(5.8.)52 b FJ(sched)22 b FI(\227)h(Ev)n(ent) h(scheduler)2600 b(131)p eop end %%Page: 132 144 TeXDict begin 132 143 bop 208 83 a FK(timefunc)19 b FN(function)f (passed)i(to)g(the)g(constructor)-5 b(.)23 b(Ev)o(ents)c(scheduled)g (for)g(the)h(same)g FK(time)h FN(will)f(be)g(e)o(x)o(ecuted)e(in)i(the) g(order)f(of)208 183 y(their)g FK(priority)p FN(.)208 315 y(Ex)o(ecuting)c(the)i(e)n(v)o(ent)f(means)g(e)o(x)o(ecuting)f FK(action)p FJ(\()1700 330 y(*)1750 315 y FK(ar)m(gument)q FJ(\))p FN(.)21 b FK(ar)m(gument)c FN(must)g(be)g(a)h(sequence)e (holding)f(the)i(parameters)208 415 y(for)i FK(action)p FN(.)208 548 y(Return)g(v)n(alue)h(is)h(an)f(e)n(v)o(ent)f(which)h(may) g(be)g(used)g(for)f(later)i(cancellation)e(of)g(the)i(e)n(v)o(ent)e (\(see)h FJ(cancel\(\))p FN(\).)0 695 y FD(enter)p FJ(\()p FK(delay)-5 b(,)19 b(priority)-5 b(,)20 b(action,)f(ar)m(gument)q FJ(\))208 794 y FN(Schedule)k(an)h(e)n(v)o(ent)f(for)h FK(delay)g FN(more)f(time)i(units.)37 b(Other)24 b(then)g(the)g(relati) n(v)o(e)g(time,)h(the)f(other)g(ar)o(guments,)f(the)h(ef)n(fect)g(and) 208 894 y(the)c(return)f(v)n(alue)g(are)h(the)h(same)f(as)h(those)f (for)f FJ(enterabs\(\))p FN(.)0 1041 y FD(cancel)p FJ(\()p FK(e)o(vent)q FJ(\))208 1141 y FN(Remo)o(v)o(e)28 b(the)i(e)n(v)o(ent)f (from)g(the)h(queue.)52 b(If)30 b FK(e)o(vent)h FN(is)g(not)e(an)h(e)n (v)o(ent)f(currently)f(in)i(the)g(queue,)h(this)f(method)e(will)j (raise)f(a)208 1240 y FJ(RuntimeError)p FN(.)0 1387 y FD(empty)p FJ(\(\))208 1487 y FN(Return)19 b(true)h(if)h(the)f(e)n(v)o (ent)f(queue)g(is)i(empty)-5 b(.)0 1634 y FD(run)p FJ(\(\))208 1733 y FN(Run)24 b(all)h(scheduled)e(e)n(v)o(ents.)38 b(This)25 b(function)e(will)i(w)o(ait)g(\(using)f(the)h FJ(delayfunc)e FN(function)g(passed)h(to)h(the)g(constructor\))208 1833 y(for)19 b(the)h(ne)o(xt)g(e)n(v)o(ent,)f(then)h(e)o(x)o(ecute)e (it)j(and)f(so)g(on)g(until)g(there)g(are)g(no)g(more)f(scheduled)g(e)n (v)o(ents.)208 1966 y(Either)j FK(action)g FN(or)h FK(delayfunc)f FN(can)h(raise)g(an)g(e)o(xception.)32 b(In)23 b(either)g(case,)h(the)f (scheduler)f(will)i(maintain)e(a)i(consistent)f(state)208 2065 y(and)e(propagate)f(the)j(e)o(xception.)30 b(If)22 b(an)g(e)o(xception)f(is)i(raised)g(by)f FK(action)p FN(,)g(the)g(e)n(v)o(ent)g(will)h(not)f(be)g(attempted)g(in)h(future)e (calls)208 2165 y(to)f FJ(run\(\))p FN(.)208 2298 y(If)c(a)h(sequence)f (of)g(e)n(v)o(ents)g(tak)o(es)h(longer)f(to)g(run)g(than)h(the)f(time)h (a)n(v)n(ailable)f(before)g(the)g(ne)o(xt)g(e)n(v)o(ent,)g(the)h (scheduler)f(will)h(simply)208 2397 y(f)o(all)j(behind.)k(No)d(e)n(v)o (ents)e(will)j(be)e(dropped;)e(the)i(calling)g(code)g(is)h(responsible) e(for)h(canceling)f(e)n(v)o(ents)h(which)g(are)g(no)g(longer)208 2497 y(pertinent.)0 2824 y FE(5.9)121 b Fx(mutex)32 b FE(\227)g(Mutual)i(e)l(xclusion)g(suppor)5 b(t)0 3057 y FN(The)19 b FJ(mutex)h FN(module)e(de\002nes)i(a)g(class)g(that)g (allo)n(ws)g(mutual-e)o(xclusion)d(via)i(acquiring)f(and)h(releasing)g (locks.)25 b(It)20 b(does)g(not)f(require)0 3157 y(\(or)h(imply\))f (threading)f(or)i(multi-tasking,)e(though)h(it)i(could)e(be)h(useful)g (for)f(those)h(purposes.)0 3304 y(The)g FJ(mutex)g FN(module)e (de\002nes)i(the)h(follo)n(wing)d(class:)0 3451 y FL(class)j FD(mutex)p FJ(\(\))208 3550 y FN(Create)f(a)h(ne)n(w)f(\(unlock)o(ed\)) d(mute)o(x.)208 3683 y(A)27 b(mute)o(x)f(has)h(tw)o(o)g(pieces)f(of)h (state)g(\227)h(a)f(\223lock)o(ed\224)f(bit)h(and)f(a)h(queue.)44 b(When)26 b(the)h(mute)o(x)f(is)h(not)g(lock)o(ed,)g(the)g(queue)f(is) 208 3783 y(empty)-5 b(.)50 b(Otherwise,)31 b(the)f(queue)e(contains)g (zero)h(or)g(more)f FJ(\()p FK(function)p FJ(,)48 b FK(ar)m(gument)q FJ(\))28 b FN(pairs)h(representing)e(functions)h(\(or)208 3882 y(methods\))18 b(w)o(aiting)i(to)h(acquire)e(the)h(lock.)k(When)c (the)g(mute)o(x)f(is)j(unlock)o(ed)c(while)i(the)g(queue)f(is)i(not)f (empty)-5 b(,)19 b(the)h(\002rst)h(queue)208 3982 y(entry)e(is)i(remo)o (v)o(ed)d(and)h(its)j FK(function)p FJ(\()p FK(ar)m(gument)q FJ(\))17 b FN(pair)j(called,)f(implying)g(it)i(no)n(w)f(has)g(the)g (lock.)208 4115 y(Of)26 b(course,)g(no)g(multi-threading)d(is)k (implied)e(\226)h(hence)f(the)h(funn)o(y)e(interf)o(ace)h(for)g FJ(lock\(\))p FN(,)i(where)e(a)i(function)d(is)j(called)208 4214 y(once)19 b(the)h(lock)g(is)h(acquired.)0 4499 y Fv(5.9.1)100 b(Mute)m(x)28 b(Objects)0 4702 y FJ(mutex)20 b FN(objects)g(ha)n(v)o(e)f(follo)n(wing)g(methods:)0 4849 y FD(test)p FJ(\(\))208 4949 y FN(Check)g(whether)h(the)g(mute)o (x)f(is)i(lock)o(ed.)0 5096 y FD(testandset)p FJ(\(\))208 5195 y FN(\223)-7 b(Atomic\224)19 b(test-and-set,)h(grab)f(the)h(lock)g (if)g(it)h(is)g(not)f(set,)h(and)f(return)f FJ(True)p FN(,)g(otherwise,)h(return)f FJ(False)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(132)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 133 145 TeXDict begin 133 144 bop 0 83 a FD(lock)p FJ(\()p FK(function,)18 b(ar)m(gument)q FJ(\))208 183 y FN(Ex)o(ecute)j FK(function)p FJ(\()p FK(ar)m(gument)q FJ(\))p FN(,)e(unless)k(the)g(mute)o(x)e(is)i (lock)o(ed.)31 b(In)22 b(the)h(case)g(it)g(is)g(lock)o(ed,)f(place)g (the)h(function)d(and)i(ar)o(gu-)208 282 y(ment)d(on)h(the)g(queue.)k (See)d FJ(unlock)e FN(for)h(e)o(xplanation)e(of)i(when)f FK(function)p FJ(\()p FK(ar)m(gument)q FJ(\))e FN(is)22 b(e)o(x)o(ecuted)c(in)i(that)h(case.)0 429 y FD(unlock)p FJ(\(\))208 529 y FN(Unlock)e(the)h(mute)o(x)f(if)h(queue)f(is)j(empty) -5 b(,)18 b(otherwise)i(e)o(x)o(ecute)f(the)h(\002rst)h(element)e(in)i (the)f(queue.)0 855 y FE(5.10)121 b Fx(Queue)32 b FE(\227)h(A)g (synchroniz)n(ed)i(queue)g(class)0 1088 y FN(The)30 b FJ(Queue)g FN(module)f(implements)h(a)h(multi-producer)m(,)e (multi-consumer)f(FIFO)j(queue.)54 b(It)31 b(is)h(especially)e(useful)g (in)g(threads)0 1188 y(programming)15 b(when)k(information)d(must)j(be) g(e)o(xchanged)d(safely)j(between)f(multiple)g(threads.)24 b(The)18 b FJ(Queue)h FN(class)h(in)f(this)g(module)0 1287 y(implements)g(all)i(the)f(required)f(locking)f(semantics.)25 b(It)c(depends)e(on)g(the)i(a)n(v)n(ailability)e(of)h(thread)f(support) g(in)i(Python.)0 1434 y(The)f FJ(Queue)g FN(module)e(de\002nes)i(the)h (follo)n(wing)d(class)j(and)f(e)o(xception:)0 1581 y FL(class)h FD(Queue)p FJ(\()p FK(maxsize)p FJ(\))208 1681 y FN(Constructor)g(for)i(the)g(class.)35 b FK(maxsize)24 b FN(is)g(an)f(inte)o(ger)f(that)i(sets)g(the)f(upperbound)d(limit)j (on)g(the)g(number)f(of)h(items)g(that)h(can)208 1780 y(be)c(placed)f(in)i(the)f(queue.)k(Insertion)19 b(will)i(block)f(once) f(this)i(size)g(has)g(been)e(reached,)g(until)h(queue)f(items)i(are)f (consumed.)k(If)208 1880 y FK(maxsize)c FN(is)h(less)h(than)d(or)h (equal)g(to)g(zero,)g(the)g(queue)f(size)i(is)g(in\002nite.)0 2027 y FL(exception)e FD(Empty)208 2127 y FN(Exception)14 b(raised)j(when)f(non-blocking)d FJ(get\(\))j FN(\(or)g FJ(get_nowait\(\))p FN(\))e(is)k(called)e(on)g(a)h FJ(Queue)g FN(object)f(which)g(is)h(empty)-5 b(.)0 2273 y FL(exception)19 b FD(Full)208 2373 y FN(Exception)f(raised)i(when)g(non-blocking)c FJ(put\(\))k FN(\(or)f FJ(put_nowait\(\))p FN(\))g(is)i(called)f(on)g (a)g FJ(Queue)g FN(object)g(which)f(is)i(full.)0 2657 y Fv(5.10.1)101 b(Queue)28 b(Objects)0 2860 y FN(Class)20 b FJ(Queue)f FN(implements)e(queue)h(objects)g(and)g(has)h(the)g (methods)f(described)f(belo)n(w)-5 b(.)24 b(This)19 b(class)g(can)g(be) f(deri)n(v)o(ed)f(from)h(in)h(order)0 2960 y(to)j(implement)e(other)g (queue)h(or)o(ganizations)d(\(e.g.)28 b(stack\))21 b(b)n(ut)g(the)h (inheritable)e(interf)o(ace)g(is)j(not)e(described)f(here.)28 b(See)22 b(the)f(source)0 3059 y(code)f(for)f(details.)25 b(The)20 b(public)f(methods)h(are:)0 3206 y FD(qsize)p FJ(\(\))208 3306 y FN(Return)f(the)i(approximate)c(size)k(of)f(the)g (queue.)k(Because)c(of)g(multithreading)e(semantics,)i(this)h(number)d (is)j(not)f(reliable.)0 3453 y FD(empty)p FJ(\(\))208 3552 y FN(Return)e FJ(True)g FN(if)h(the)f(queue)g(is)h(empty)-5 b(,)17 b FJ(False)h FN(otherwise.)24 b(Because)19 b(of)f (multithreading)e(semantics,)j(this)g(is)g(not)f(reliable.)0 3699 y FD(full)p FJ(\(\))208 3799 y FN(Return)h FJ(True)h FN(if)h(the)f(queue)f(is)i(full,)f FJ(False)g FN(otherwise.)k(Because)c (of)g(multithreading)e(semantics,)i(this)h(is)g(not)f(reliable.)0 3946 y FD(put)p FJ(\()p FK(item)p FC([)p FK(,)g(bloc)n(k)q FC([)p FK(,)f(timeout)13 b FC(])f(])p FJ(\))208 4045 y FN(Put)21 b FK(item)g FN(into)g(the)g(queue.)26 b(If)21 b(optional)f(ar)o(gs)g FK(bloc)n(k)i FN(is)g(true)f(and)f FK(timeout)i FN(is)g(None)f(\(the)f(def)o(ault\),)g(block)g(if)h (necessary)g(until)208 4145 y(a)j(free)f(slot)h(is)h(a)n(v)n(ailable.) 35 b(If)23 b FK(timeout)i FN(is)g(a)f(positi)n(v)o(e)f(number)m(,)f(it) j(blocks)e(at)h(most)g FK(timeout)g FN(seconds)g(and)f(raises)h(the)g FJ(Full)208 4245 y FN(e)o(xception)18 b(if)j(no)f(free)g(slot)h(w)o(as) h(a)n(v)n(ailable)e(within)g(that)g(time.)27 b(Otherwise)20 b(\()p FK(bloc)n(k)h FN(is)h(f)o(alse\),)e(put)g(an)h(item)f(on)g(the)h (queue)e(if)i(a)208 4344 y(free)e(slot)i(is)g(immediately)e(a)n(v)n (ailable,)h(else)g(raise)h(the)f FJ(Full)g FN(e)o(xception)e(\()p FK(timeout)j FN(is)g(ignored)e(in)h(that)g(case\).)208 4476 y(Ne)n(w)g(in)g(v)o(ersion)f(2.3:)h(the)g(timeout)g(parameter)-5 b(.)0 4623 y FD(put_nowait)p FJ(\()p FK(item)p FJ(\))208 4723 y FN(Equi)n(v)n(alent)18 b(to)i FJ(put\()p FK(item)p FJ(,)49 b(False\))p FN(.)0 4870 y FD(get)p FJ(\()p FC([)p FK(bloc)n(k)q FC([)p FK(,)19 b(timeout)13 b FC(])f(])p FJ(\))208 4969 y FN(Remo)o(v)o(e)26 b(and)h(return)f(an)h(item)h(from)e (the)i(queue.)45 b(If)27 b(optional)f(ar)o(gs)h FK(bloc)n(k)i FN(is)f(true)f(and)g FK(timeout)i FN(is)f(None)f(\(the)g(def)o(ault\),) 208 5069 y(block)22 b(if)h(necessary)f(until)h(an)g(item)g(is)h(a)n(v)n (ailable.)32 b(If)23 b FK(timeout)h FN(is)g(a)f(positi)n(v)o(e)f (number)m(,)g(it)h(blocks)g(at)g(most)g FK(timeout)h FN(seconds)208 5168 y(and)d(raises)i(the)f FJ(Empty)f FN(e)o(xception)g(if)h(no)g(item)g(w)o(as)h(a)n(v)n(ailable)e(within)h (that)g(time.)31 b(Otherwise)22 b(\()p FK(bloc)n(k)g FN(is)h(f)o(alse\),)g(return)e(an)208 5268 y(item)f(if)g(one)g(is)h (immediately)e(a)n(v)n(ailable,)h(else)g(raise)h(the)f FJ(Empty)g FN(e)o(xception)e(\()p FK(timeout)j FN(is)g(ignored)e(in)h (that)g(case\).)208 5400 y(Ne)n(w)g(in)g(v)o(ersion)f(2.3:)h(the)g (timeout)g(parameter)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(5.10.)52 b FJ(Queue)22 b FI(\227)i(A)f(synchroniz)o(ed)f(queue)i (class)2114 b(133)p eop end %%Page: 134 146 TeXDict begin 134 145 bop 0 83 a FD(get_nowait)p FJ(\(\))208 183 y FN(Equi)n(v)n(alent)18 b(to)i FJ(get\(False\))p FN(.)0 330 y(T)-7 b(w)o(o)21 b(methods)e(are)h(of)n(fered)f(to)h (support)f(tracking)g(whether)g(enqueued)f(tasks)j(ha)n(v)o(e)f(been)g (fully)f(processed)h(by)f(daemon)g(consumer)0 429 y(threads.)0 576 y FD(task_done)p FJ(\(\))208 676 y FN(Indicate)g(that)i(a)g (formerly)e(enqueued)f(task)j(is)h(complete.)j(Used)c(by)g(queue)e (consumer)g(threads.)26 b(F)o(or)20 b(each)h FJ(get\(\))f FN(used)g(to)208 775 y(fetch)f(a)i(task,)f(a)h(subsequent)d(call)j(to)f FJ(task_done\(\))f FN(tells)i(the)g(queue)e(that)h(the)g(processing)f (on)h(the)g(task)g(is)h(complete.)208 908 y(If)e(a)h FJ(join\(\))f FN(is)i(currently)d(blocking,)g(it)i(will)h(resume)e (when)g(all)h(items)g(ha)n(v)o(e)g(been)f(processed)f(\(meaning)g(that) i(a)g FJ(task_-)208 1008 y(done\(\))f FN(call)i(w)o(as)g(recei)n(v)o (ed)d(for)i(e)n(v)o(ery)f(item)h(that)h(had)e(been)h FJ(put\(\))f FN(into)h(the)h(queue\).)208 1141 y(Raises)g(a)g FJ(ValueError)e FN(if)h(called)g(more)f(times)i(than)f(there)g(were)g (items)g(placed)g(in)g(the)g(queue.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d (2.5.)0 1287 y FD(join)p FJ(\(\))208 1387 y FN(Blocks)i(until)g(all)h (items)f(in)h(the)f(queue)f(ha)n(v)o(e)h(been)f(gotten)g(and)h (processed.)208 1520 y(The)g(count)g(of)g(un\002nished)f(tasks)j(goes)e (up)h(whene)n(v)o(er)d(an)j(item)g(is)h(added)d(to)i(the)g(queue.)k (The)c(count)e(goes)i(do)n(wn)f(whene)n(v)o(er)208 1620 y(a)j(consumer)e(thread)h(calls)i FJ(task_done\(\))d FN(to)i(indicate)f(that)h(the)g(item)g(w)o(as)h(retrie)n(v)o(ed)d(and)h (all)i(w)o(ork)e(on)g(it)i(is)g(complete.)208 1719 y(When)c(the)g (count)f(of)h(un\002nished)f(tasks)h(drops)g(to)g(zero,)f(join\(\))h (unblocks.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 1866 y(Example)g(of)h(ho)n(w)f(to)i(w)o(ait)g(for)e(enqueued)f(tasks)j (to)f(be)g(completed:)416 2104 y FA(def)44 b(worker\(\):)595 2196 y(while)g(True:)774 2287 y(item)g(=)h(q.get\(\))774 2378 y(do_work\(item\))774 2470 y(q.task_done\(\))416 2652 y(q)f(=)h(Queue\(\))416 2743 y(for)f(i)h(in)f (range\(num_worker_threads\):)640 2835 y(t)g(=)h (Thread\(target=worker\))640 2926 y(t.setDaemon\(True\))640 3017 y(t.start\(\))416 3200 y(for)f(item)g(in)h(source\(\):)595 3291 y(q.put\(item\))416 3474 y(q.join\(\))312 b(#)45 b(block)f(until)g(all)g(tasks)g(are)g(done)0 3984 y FE(5.11)121 b Fx(weakref)32 b FE(\227)g(W)l(eak)j(ref)l(erences)0 4217 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 4364 y(The)h FJ(weakref)f FN(module)g(allo)n(ws)i(the)f(Python)f(programmer)e(to)j (create)g FK(weak)h(r)m(efer)m(ences)f FN(to)g(objects.)0 4511 y(In)g(the)g(follo)n(wing,)e(the)j(term)f FK(r)m(efer)m(ent)g FN(means)g(the)g(object)g(which)f(is)j(referred)c(to)i(by)g(a)h(weak)f (reference.)0 4658 y(A)g(weak)g(reference)e(to)i(an)g(object)f(is)h (not)g(enough)e(to)i(k)o(eep)f(the)h(object)f(ali)n(v)o(e:)25 b(when)19 b(the)g(only)g(remaining)f(references)h(to)h(a)g(referent)0 4757 y(are)27 b(weak)g(references,)g(garbage)e(collection)h(is)i(free)e (to)i(destro)o(y)e(the)h(referent)e(and)i(reuse)g(its)h(memory)d(for)h (something)g(else.)46 b(A)0 4857 y(primary)23 b(use)h(for)f(weak)h (references)f(is)i(to)f(implement)f(caches)h(or)g(mappings)f(holding)f (lar)o(ge)h(objects,)i(where)e(it')-5 b(s)25 b(desired)f(that)g(a)0 4956 y(lar)o(ge)d(object)h(not)g(be)g(k)o(ept)g(ali)n(v)o(e)g(solely)g (because)g(it)h(appears)e(in)i(a)g(cache)e(or)h(mapping.)30 b(F)o(or)22 b(e)o(xample,)f(if)i(you)e(ha)n(v)o(e)h(a)g(number)f(of)0 5056 y(lar)o(ge)16 b(binary)g(image)g(objects,)i(you)e(may)g(wish)i(to) f(associate)h(a)f(name)g(with)g(each.)23 b(If)17 b(you)f(used)h(a)h (Python)e(dictionary)f(to)i(map)g(names)0 5156 y(to)22 b(images,)h(or)e(images)h(to)h(names,)f(the)g(image)g(objects)f(w)o (ould)h(remain)f(ali)n(v)o(e)h(just)h(because)e(the)o(y)h(appeared)e (as)j(v)n(alues)f(or)g(k)o(e)o(ys)f(in)0 5255 y(the)28 b(dictionaries.)46 b(The)28 b FJ(WeakKeyDictionary)d FN(and)i FJ(WeakValueDictionary)e FN(classes)k(supplied)d(by)i(the)f FJ(weakref)0 5355 y FN(module)c(are)i(an)g(alternati)n(v)o(e,)f(using)g (weak)h(references)e(to)i(construct)f(mappings)f(that)i(don')o(t)e(k)o (eep)i(objects)f(ali)n(v)o(e)h(solely)f(because)p 0 5549 3901 4 v 0 5649 a FI(134)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 135 147 TeXDict begin 135 146 bop 0 83 a FN(the)o(y)28 b(appear)g(in)h(the)g (mapping)e(objects.)51 b(If,)31 b(for)d(e)o(xample,)h(an)g(image)g (object)f(is)i(a)f(v)n(alue)f(in)h(a)h FJ(WeakValueDictionary)p FN(,)0 183 y(then)19 b(when)g(the)g(last)i(remaining)d(references)g(to) h(that)h(image)f(object)g(are)g(the)h(weak)f(references)f(held)h(by)h (weak)f(mappings,)f(garbage)0 282 y(collection)h(can)h(reclaim)g(the)g (object,)g(and)f(its)i(corresponding)c(entries)j(in)h(weak)e(mappings)g (are)h(simply)g(deleted.)0 429 y FJ(WeakKeyDictionary)26 b FN(and)j FJ(WeakValueDictionary)d FN(use)j(weak)f(references)g(in)h (their)g(implementation,)f(setting)h(up)0 529 y(callback)18 b(functions)f(on)i(the)f(weak)h(references)e(that)i(notify)f(the)h (weak)f(dictionaries)g(when)g(a)h(k)o(e)o(y)g(or)f(v)n(alue)g(has)h (been)f(reclaimed)g(by)0 628 y(garbage)g(collection.)24 b(Most)c(programs)e(should)h(\002nd)h(that)g(using)g(one)f(of)h(these)g (weak)g(dictionary)e(types)i(is)h(all)g(the)o(y)e(need)h(\226)g(it')-5 b(s)21 b(not)0 728 y(usually)g(necessary)g(to)g(create)g(your)g(o)n(wn) g(weak)g(references)f(directly)-5 b(.)28 b(The)21 b(lo)n(w-le)n(v)o(el) f(machinery)f(used)j(by)f(the)g(weak)g(dictionary)0 828 y(implementations)d(is)j(e)o(xposed)e(by)h(the)g FJ(weakref)f FN(module)g(for)h(the)g(bene\002t)g(of)g(adv)n(anced)e(uses.)0 975 y(Not)i(all)g(objects)g(can)g(be)f(weakly)h(referenced;)d(those)j (objects)g(which)f(can)h(include)e(class)j(instances,)f(functions)e (written)i(in)g(Python)0 1074 y(\(b)n(ut)25 b(not)f(in)i(C\),)f (methods)f(\(both)g(bound)f(and)i(unbound\),)e(sets,)k(frozensets,)e (\002le)h(objects,)f(generators,)g(type)f(objects,)i(DBcursor)0 1174 y(objects)20 b(from)g(the)g FJ(bsddb)g FN(module,)f(sock)o(ets,)h (arrays,)g(deques,)f(and)h(re)o(gular)f(e)o(xpression)g(pattern)g (objects.)52 b(Changed)19 b(in)i(v)o(ersion)0 1273 y(2.4:)f(Added)f (support)g(for)g(\002les,)i(sock)o(ets,)f(arrays,)f(and)h(patterns.)0 1420 y(Se)n(v)o(eral)25 b(b)n(uiltin)g(types)g(such)h(as)g FJ(list)f FN(and)g FJ(dict)g FN(do)g(not)h(directly)e(support)g(weak)i (references)e(b)n(ut)h(can)h(add)f(support)f(through)0 1520 y(subclassing:)236 1758 y FA(class)44 b(Dict\(dict\):)416 1849 y(pass)236 2032 y(obj)h(=)f(Dict\(red=1,)f(green=2,)h(blue=3\))133 b(#)45 b(this)f(object)g(is)g(weak)g(referencable)0 2319 y FN(Extension)28 b(types)h(can)g(easily)g(be)g(made)g(to)g(support)f (weak)h(references;)k(see)c(\223W)-7 b(eak)30 b(Reference)e (Support\224)g(in)h FK(Extending)e(and)0 2418 y(Embedding)18 b(the)i(Python)f(Interpr)m(eter)p FN(.)0 2565 y FL(class)i FD(ref)p FJ(\()p FK(object)q FC([)p FK(,)e(callbac)n(k)13 b FC(])p FJ(\))208 2665 y FN(Return)26 b(a)h(weak)f(reference)f(to)i FK(object)q FN(.)44 b(The)26 b(original)f(object)h(can)h(be)f(retrie)n (v)o(ed)f(by)h(calling)g(the)h(reference)e(object)h(if)h(the)208 2765 y(referent)k(is)i(still)h(ali)n(v)o(e;)k(if)33 b(the)g(referent)e (is)j(no)e(longer)f(ali)n(v)o(e,)k(calling)d(the)h(reference)e(object)h (will)h(cause)g FJ(None)f FN(to)h(be)208 2864 y(returned.)d(If)23 b FK(callbac)n(k)g FN(is)g(pro)o(vided)e(and)h(not)g FJ(None)p FN(,)h(and)f(the)h(returned)e(weakref)g(object)h(is)i(still)g (ali)n(v)o(e,)e(the)h(callback)f(will)208 2964 y(be)c(called)f(when)h (the)g(object)f(is)i(about)e(to)i(be)e(\002nalized;)i(the)f(weak)g (reference)e(object)h(will)i(be)f(passed)g(as)h(the)f(only)f(parameter) 208 3063 y(to)j(the)g(callback;)g(the)g(referent)f(will)i(no)e(longer)g (be)h(a)n(v)n(ailable.)208 3196 y(It)25 b(is)h(allo)n(w)o(able)e(for)h (man)o(y)e(weak)i(references)f(to)h(be)g(constructed)e(for)i(the)g (same)g(object.)39 b(Callbacks)25 b(re)o(gistered)f(for)g(each)208 3296 y(weak)19 b(reference)g(will)i(be)f(called)g(from)f(the)h(most)h (recently)e(re)o(gistered)g(callback)g(to)h(the)h(oldest)f(re)o (gistered)f(callback.)208 3429 y(Exceptions)f(raised)i(by)g(the)g (callback)g(will)g(be)h(noted)e(on)h(the)g(standard)f(error)g(output,)g (b)n(ut)h(cannot)f(be)h(propagated;)d(the)o(y)j(are)208 3528 y(handled)e(in)j(e)o(xactly)e(the)h(same)g(w)o(ay)h(as)f(e)o (xceptions)f(raised)h(from)f(an)h(object')-5 b(s)20 b FJ(__del__\(\))f FN(method.)208 3661 y(W)-7 b(eak)20 b(references)e(are)h(hashable)g(if)h(the)g FK(object)g FN(is)h(hashable.)i(The)o(y)c(will)h(maintain)f(their)g(hash)h(v)n (alue)f(e)n(v)o(en)f(after)h(the)h FK(object)208 3761 y FN(w)o(as)e(deleted.)23 b(If)17 b FJ(hash\(\))g FN(is)h(called)f(the) h(\002rst)g(time)f(only)g(after)g(the)g FK(object)h FN(w)o(as)g (deleted,)f(the)h(call)f(will)h(raise)g FJ(TypeError)p FN(.)208 3894 y(W)-7 b(eak)23 b(references)e(support)g(tests)j(for)e (equality)-5 b(,)22 b(b)n(ut)g(not)g(ordering.)30 b(If)23 b(the)g(referents)e(are)i(still)g(ali)n(v)o(e,)g(tw)o(o)g(references)e (ha)n(v)o(e)208 3993 y(the)g(same)g(equality)g(relationship)e(as)j (their)f(referents)g(\(re)o(gardless)e(of)i(the)g FK(callbac)n(k)q FN(\).)28 b(If)21 b(either)g(referent)e(has)j(been)e(deleted,)208 4093 y(the)g(references)f(are)h(equal)f(only)h(if)g(the)g(reference)f (objects)h(are)g(the)g(same)g(object.)208 4226 y(Changed)d(in)i(v)o (ersion)f(2.4:)h(This)g(is)h(no)n(w)e(a)i(subclassable)e(type)h(rather) f(than)h(a)g(f)o(actory)f(function;)g(it)h(deri)n(v)o(es)f(from)g FJ(object)p FN(.)0 4373 y FD(proxy)p FJ(\()p FK(object)q FC([)p FK(,)h(callbac)n(k)13 b FC(])p FJ(\))208 4472 y FN(Return)21 b(a)i(proxy)d(to)i FK(object)h FN(which)f(uses)g(a)h (weak)f(reference.)29 b(This)22 b(supports)f(use)h(of)g(the)g(proxy)e (in)j(most)f(conte)o(xts)f(instead)208 4572 y(of)i(requiring)f(the)i(e) o(xplicit)f(dereferencing)e(used)i(with)h(weak)g(reference)e(objects.) 35 b(The)24 b(returned)e(object)h(will)i(ha)n(v)o(e)e(a)h(type)208 4671 y(of)c(either)g FJ(ProxyType)f FN(or)h FJ(CallableProxyType)p FN(,)e(depending)g(on)i(whether)g FK(object)h FN(is)g(callable.)26 b(Proxy)19 b(objects)i(are)208 4771 y(not)d(hashable)h(re)o(gardless)e (of)i(the)h(referent;)e(this)i(a)n(v)n(oids)f(a)h(number)d(of)i (problems)f(related)h(to)g(their)g(fundamentally)e(mutable)208 4871 y(nature,)k(and)g(pre)n(v)o(ent)g(their)g(use)i(as)f(dictionary)f (k)o(e)o(ys.)30 b FK(callbac)n(k)22 b FN(is)h(the)f(same)h(as)f(the)g (parameter)f(of)h(the)g(same)g(name)f(to)i(the)208 4970 y FJ(ref\(\))c FN(function.)0 5117 y FD(getweakrefcount)p FJ(\()p FK(object)q FJ(\))208 5217 y FN(Return)g(the)i(number)d(of)i (weak)g(references)f(and)g(proxies)g(which)h(refer)f(to)i FK(object)q FN(.)0 5364 y FD(getweakrefs)p FJ(\()p FK(object)q FJ(\))p 0 5549 3901 4 v 0 5649 a FI(5.11.)52 b FJ(weakref)22 b FI(\227)h(W)n(eak)g(ref)n(erences)2424 b(135)p eop end %%Page: 136 148 TeXDict begin 136 147 bop 208 83 a FN(Return)19 b(a)i(list)g(of)f(all)h (weak)f(reference)e(and)i(proxy)e(objects)i(which)g(refer)f(to)i FK(object)q FN(.)0 230 y FL(class)g FD(WeakKeyDictionary)p FJ(\()p FC([)p FK(dict)13 b FC(])p FJ(\))208 330 y FN(Mapping)k(class)k (that)e(references)f(k)o(e)o(ys)h(weakly)-5 b(.)23 b(Entries)d(in)f (the)g(dictionary)f(will)i(be)f(discarded)f(when)h(there)g(is)h(no)f (longer)f(a)208 429 y(strong)h(reference)f(to)i(the)g(k)o(e)o(y)-5 b(.)24 b(This)c(can)g(be)g(used)g(to)g(associate)g(additional)f(data)h (with)g(an)g(object)f(o)n(wned)g(by)h(other)f(parts)h(of)208 529 y(an)e(application)e(without)i(adding)e(attrib)n(utes)i(to)g(those) g(objects.)24 b(This)19 b(can)e(be)h(especially)g(useful)g(with)g (objects)g(that)g(o)o(v)o(erride)208 628 y(attrib)n(ute)h(accesses.)208 761 y FL(Note:)i FN(Caution:)i(Because)15 b(a)h FJ(WeakKeyDictionary)d FN(is)j(b)n(uilt)g(on)f(top)g(of)g(a)g(Python)g(dictionary)-5 b(,)13 b(it)j(must)g(not)f(change)f(size)208 861 y(when)19 b(iterating)h(o)o(v)o(er)e(it.)26 b(This)20 b(can)g(be)h(dif)n (\002cult)e(to)i(ensure)e(for)h(a)g FJ(WeakKeyDictionary)e FN(because)h(actions)h(performed)208 960 y(by)28 b(the)h(program)e (during)g(iteration)h(may)h(cause)g(items)g(in)g(the)g(dictionary)e(to) j(v)n(anish)e(\224by)g(magic\224)g(\(as)i(a)f(side)g(ef)n(fect)g(of)208 1060 y(garbage)18 b(collection\).)0 1207 y FJ(WeakKeyDictionary)c FN(objects)j(ha)n(v)o(e)f(the)h(follo)n(wing)e(additional)g(methods.)23 b(These)16 b(e)o(xpose)g(the)h(internal)f(references)f(directly)-5 b(.)0 1307 y(The)23 b(references)g(are)g(not)g(guaranteed)f(to)i(be)f (\223li)n(v)o(e\224)g(at)h(the)g(time)g(the)o(y)f(are)g(used,)h(so)g (the)g(result)g(of)f(calling)g(the)h(references)e(needs)0 1406 y(to)e(be)g(check)o(ed)e(before)g(being)h(used.)25 b(This)20 b(can)f(be)h(used)g(to)f(a)n(v)n(oid)h(creating)f(references) f(that)i(will)g(cause)g(the)g(garbage)e(collector)g(to)0 1506 y(k)o(eep)i(the)g(k)o(e)o(ys)g(around)e(longer)h(than)h(needed.)0 1653 y FD(iterkeyrefs)p FJ(\(\))208 1752 y FN(Return)f(an)h(iterator)g (that)g(yields)g(the)h(weak)e(references)g(to)i(the)f(k)o(e)o(ys.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1899 y FD(keyrefs)p FJ(\(\))208 1999 y FN(Return)g(a)i(list)g(of)f(weak)g(references)f(to)h (the)g(k)o(e)o(ys.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 2146 y FL(class)j FD(WeakValueDictionary)p FJ(\()p FC([)p FK(dict)13 b FC(])p FJ(\))208 2245 y FN(Mapping)21 b(class)i(that)g (references)f(v)n(alues)g(weakly)-5 b(.)32 b(Entries)22 b(in)h(the)g(dictionary)e(will)j(be)e(discarded)g(when)g(no)g(strong)g (refer)n(-)208 2345 y(ence)d(to)i(the)f(v)n(alue)f(e)o(xists)i(an)o(y)e (more.)208 2478 y FL(Note:)k FN(Caution:)h(Because)18 b(a)h FJ(WeakValueDictionary)d FN(is)j(b)n(uilt)g(on)f(top)g(of)g(a)h (Python)e(dictionary)-5 b(,)16 b(it)j(must)g(not)f(change)208 2577 y(size)27 b(when)g(iterating)f(o)o(v)o(er)g(it.)46 b(This)27 b(can)g(be)g(dif)n(\002cult)g(to)g(ensure)f(for)h(a)g FJ(WeakValueDictionary)d FN(because)j(actions)208 2677 y(performed)c(by)i(the)g(program)f(during)g(iteration)h(may)g(cause)g (items)h(in)g(the)g(dictionary)e(to)h(v)n(anish)g(\224by)g(magic\224)g (\(as)h(a)g(side)208 2777 y(ef)n(fect)19 b(of)h(garbage)e (collection\).)0 2924 y FJ(WeakValueDictionary)d FN(objects)j(ha)n(v)o (e)f(the)h(follo)n(wing)e(additional)h(methods.)23 b(These)18 b(method)e(ha)n(v)o(e)i(the)g(same)g(issues)h(as)g(the)0 3023 y FJ(iterkeyrefs\(\))f FN(and)i FJ(keyrefs\(\))f FN(methods)g(of)h FJ(WeakKeyDictionary)e FN(objects.)0 3170 y FD(itervaluerefs)p FJ(\(\))208 3270 y FN(Return)h(an)h(iterator) g(that)g(yields)g(the)h(weak)e(references)g(to)i(the)f(v)n(alues.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 3417 y FD(valuerefs)p FJ(\(\))208 3516 y FN(Return)g(a)i(list)g(of)f(weak)g(references)f(to)h (the)g(v)n(alues.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 3663 y FD(ReferenceType)208 3763 y FN(The)g(type)h(object)g(for)f(weak) h(references)f(objects.)0 3910 y FD(ProxyType)208 4009 y FN(The)g(type)h(object)g(for)f(proxies)h(of)f(objects)h(which)g(are)g (not)g(callable.)0 4156 y FD(CallableProxyType)208 4256 y FN(The)f(type)h(object)g(for)f(proxies)h(of)f(callable)h(objects.)0 4403 y FD(ProxyTypes)208 4502 y FN(Sequence)25 b(containing)g(all)i (the)g(type)f(objects)h(for)f(proxies.)43 b(This)27 b(can)g(mak)o(e)f (it)i(simpler)e(to)h(test)h(if)f(an)f(object)g(is)i(a)f(proxy)208 4602 y(without)19 b(being)g(dependent)f(on)i(naming)f(both)g(proxy)g (types.)0 4749 y FL(exception)g FD(ReferenceError)208 4848 y FN(Exception)h(raised)h(when)h(a)g(proxy)e(object)i(is)h(used)e (b)n(ut)h(the)g(underlying)d(object)j(has)g(been)f(collected.)30 b(This)22 b(is)h(the)f(same)g(as)208 4948 y(the)e(standard)f FJ(ReferenceError)f FN(e)o(xception.)0 5095 y FL(See)j(Also:)0 5242 y FN(PEP)g(0205,)d(\223)p FK(W)-8 b(eak)21 b(Refer)m(ences)p FN(\224)208 5341 y(The)27 b(proposal)f(and)h(rationale)g(for)g(this)h (feature,)h(including)c(links)j(to)g(earlier)f(implementations)f(and)h (information)f(about)p 0 5549 3901 4 v 0 5649 a FI(136)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 137 149 TeXDict begin 137 148 bop 208 83 a FN(similar)20 b(features)f(in)i (other)e(languages.)0 368 y Fv(5.11.1)101 b(W)m(eak)28 b(Ref)m(erence)h(Objects)0 571 y FN(W)-7 b(eak)28 b(reference)d (objects)i(ha)n(v)o(e)g(no)g(attrib)n(utes)g(or)g(methods,)h(b)n(ut)f (do)g(allo)n(w)g(the)g(referent)f(to)h(be)h(obtained,)f(if)g(it)h (still)h(e)o(xists,)g(by)0 670 y(calling)20 b(it:)236 909 y FA(>>>)45 b(import)e(weakref)236 1000 y(>>>)i(class)f(Object:)236 1091 y(...)224 b(pass)236 1183 y(...)236 1274 y(>>>)45 b(o)f(=)h(Object\(\))236 1365 y(>>>)g(r)f(=)h(weakref.ref\(o\))236 1457 y(>>>)g(o2)f(=)h(r\(\))236 1548 y(>>>)g(o)f(is)h(o2)236 1639 y(True)0 1926 y FN(If)20 b(the)g(referent)f(no)h(longer)f(e)o (xists,)h(calling)g(the)g(reference)f(object)g(returns)h FJ(None)p FN(:)236 2164 y FA(>>>)45 b(del)f(o,)g(o2)236 2255 y(>>>)h(print)f(r\(\))236 2347 y(None)0 2633 y FN(T)-6 b(esting)26 b(that)f(a)h(weak)g(reference)e(object)h(is)i(still)g(li)n (v)o(e)e(should)g(be)g(done)g(using)g(the)h(e)o(xpression)e FK(r)m(ef)12 b FJ(\(\))50 b(is)f(not)h(None)p FN(.)41 b(Nor)n(-)0 2733 y(mally)-5 b(,)19 b(application)g(code)g(that)i(needs) f(to)g(use)g(a)h(reference)d(object)i(should)f(follo)n(w)h(this)g (pattern:)236 2880 y FA(#)45 b(r)g(is)f(a)h(weak)f(reference)f(object) 236 2971 y(o)i(=)g(r\(\))236 3062 y(if)g(o)f(is)h(None:)416 3154 y(#)f(referent)g(has)g(been)g(garbage)g(collected)416 3245 y(print)g("Object)f(has)i(been)f(deallocated;)e(can't)i (frobnicate.")236 3336 y(else:)416 3428 y(print)g("Object)f(is)i(still) f(live!")416 3519 y(o.do_something_useful\(\))0 3806 y FN(Using)22 b(a)g(separate)g(test)h(for)e(\223li)n(v)o(eness\224)h (creates)g(race)g(conditions)e(in)j(threaded)d(applications;)i(another) e(thread)i(can)f(cause)h(a)h(weak)0 3905 y(reference)d(to)h(become)f (in)m(v)n(alidated)f(before)h(the)h(weak)g(reference)e(is)k(called;)e (the)g(idiom)g(sho)n(wn)f(abo)o(v)o(e)g(is)i(safe)f(in)h(threaded)d (appli-)0 4005 y(cations)h(as)h(well)g(as)f(single-threaded)e (applications.)0 4152 y(Specialized)26 b(v)o(ersions)g(of)g FJ(ref)h FN(objects)f(can)g(be)h(created)f(through)e(subclassing.)44 b(This)27 b(is)g(used)f(in)h(the)g(implementation)d(of)j(the)0 4251 y FJ(WeakValueDictionary)18 b FN(to)k(reduce)e(the)h(memory)f(o)o (v)o(erhead)f(for)h(each)h(entry)g(in)g(the)h(mapping.)k(This)c(may)e (be)i(most)f(useful)0 4351 y(to)h(associate)h(additional)d(information) g(with)i(a)h(reference,)d(b)n(ut)j(could)e(also)h(be)g(used)g(to)g (insert)g(additional)f(processing)g(on)h(calls)g(to)0 4451 y(retrie)n(v)o(e)d(the)h(referent.)0 4597 y(This)h(e)o(xample)e (sho)n(ws)i(ho)n(w)f(a)h(subclass)g(of)f FJ(ref)h FN(can)f(be)h(used)f (to)h(store)g(additional)e(information)f(about)i(an)g(object)g(and)g (af)n(fect)h(the)0 4697 y(v)n(alue)f(that')-5 b(s)20 b(returned)f(when)g(the)h(referent)f(is)i(accessed:)p 0 5549 3901 4 v 0 5649 a FI(5.11.)52 b FJ(weakref)22 b FI(\227)h(W)n(eak)g(ref)n(erences)2424 b(137)p eop end %%Page: 138 150 TeXDict begin 138 149 bop 236 174 a FA(import)44 b(weakref)236 357 y(class)g(ExtendedRef\(weakref.ref\):)416 448 y(def)g (__init__\(self,)e(ob,)j(callback=None,)2119 461 y(**)2209 448 y(annotations\):)595 540 y(super\(ExtendedRef,)d (self\).__init__\(ob,)f(callback\))595 631 y(self.__counter)h(=)j(0)595 722 y(for)f(k,)h(v)f(in)h(annotations.iteritems\(\):)774 814 y(setattr\(self,)e(k,)h(v\))416 996 y(def)g(__call__\(self\):)595 1088 y("""Return)f(a)i(pair)f(containing)f(the)h(referent)g(and)g(the)h (number)e(of)595 1179 y(times)h(the)g(reference)g(has)g(been)g(called.) 595 1270 y(""")595 1362 y(ob)g(=)h(super\(ExtendedRef,)d (self\).__call__\(\))595 1453 y(if)i(ob)h(is)f(not)h(None:)774 1544 y(self.__counter)e(+=)h(1)774 1636 y(ob)h(=)f(\(ob,)h (self.__counter\))595 1727 y(return)f(ob)0 2150 y Fv(5.11.2)101 b(Example)0 2353 y FN(This)20 b(simple)g(e)o(xample)f(sho)n(ws)h(ho)n (w)f(an)h(application)e(can)i(use)g(objects)g(IDs)g(to)h(retrie)n(v)o (e)d(objects)i(that)g(it)h(has)f(seen)g(before.)j(The)d(IDs)0 2453 y(of)h(the)f(objects)h(can)f(then)h(be)g(used)f(in)h(other)f(data) h(structures)f(without)g(forcing)f(the)i(objects)f(to)h(remain)f(ali)n (v)o(e,)h(b)n(ut)f(the)h(objects)g(can)0 2552 y(still)g(be)f(retrie)n (v)o(ed)f(by)h(ID)g(if)h(the)o(y)e(do.)236 2791 y FA(import)44 b(weakref)236 2973 y(_id2obj_dict)f(=)i (weakref.WeakValueDictionary\(\))236 3156 y(def)g(remember\(obj\):)416 3247 y(oid)f(=)h(id\(obj\))416 3338 y(_id2obj_dict[oid])d(=)i(obj)416 3430 y(return)f(oid)236 3612 y(def)i(id2obj\(oid\):)416 3704 y(return)e(_id2obj_dict[oid])0 4214 y FE(5.12)121 b Fx(UserDict)31 b FE(\227)i(Class)g(wr)o(apper)i(f)l(or)f(dictionar)t (y)g(objects)0 4447 y FN(The)23 b(module)f(de\002nes)h(a)h(mixin,)f FJ(DictMixin)p FN(,)f(de\002ning)g(all)i(dictionary)e(methods)g(for)h (classes)h(that)f(already)g(ha)n(v)o(e)f(a)i(minimum)0 4546 y(mapping)h(interf)o(ace.)42 b(This)27 b(greatly)e(simpli\002es)i (writing)f(classes)i(that)e(need)g(to)g(be)h(substitutable)e(for)h (dictionaries)g(\(such)f(as)j(the)0 4646 y(shelv)o(e)20 b(module\).)0 4793 y(This)f(module)f(also)h(de\002nes)g(a)g(class,)h FJ(UserDict)p FN(,)e(that)h(acts)h(as)f(a)h(wrapper)d(around)g (dictionary)h(objects.)24 b(The)19 b(need)f(for)g(this)i(class)0 4892 y(has)28 b(been)e(lar)o(gely)g(supplanted)g(by)g(the)i(ability)f (to)g(subclass)h(directly)e(from)h FJ(dict)g FN(\(a)g(feature)f(that)i (became)e(a)n(v)n(ailable)h(starting)0 4992 y(with)c(Python)e(v)o (ersion)g(2.2\).)31 b(Prior)22 b(to)h(the)f(introduction)e(of)i FJ(dict)p FN(,)h(the)g FJ(UserDict)e FN(class)j(w)o(as)f(used)f(to)h (create)f(dictionary-lik)o(e)0 5092 y(sub-classes)e(that)h(obtained)d (ne)n(w)i(beha)n(viors)f(by)h(o)o(v)o(erriding)d(e)o(xisting)i(methods) h(or)f(adding)g(ne)n(w)h(ones.)0 5239 y(The)g FJ(UserDict)f FN(module)g(de\002nes)h(the)g FJ(UserDict)f FN(class)j(and)d FJ(DictMixin)p FN(:)0 5385 y FL(class)i FD(UserDict)p FJ(\()p FC([)p FK(initialdata)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(138)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 139 151 TeXDict begin 139 150 bop 208 83 a FN(Class)26 b(that)f(simulates)h(a)f (dictionary)-5 b(.)38 b(The)24 b(instance')-5 b(s)25 b(contents)g(are)g(k)o(ept)g(in)g(a)g(re)o(gular)f(dictionary)-5 b(,)24 b(which)g(is)i(accessible)208 183 y(via)20 b(the)g FJ(data)g FN(attrib)n(ute)g(of)g FJ(UserDict)f FN(instances.)26 b(If)20 b FK(initialdata)f FN(is)i(pro)o(vided,)c FJ(data)j FN(is)i(initialized)d(with)i(its)g(contents;)208 282 y(note)f(that)g(a)h(reference)e(to)i FK(initialdata)e FN(will)j(not)e(be)h(k)o(ept,)f(allo)n(wing)g(it)h(be)g(used)f(for)g (other)g(purposes.)25 b FL(Note:)g FN(F)o(or)20 b(backw)o(ard)208 382 y(compatibility)-5 b(,)18 b(instances)i(of)g FJ(UserDict)f FN(are)h(not)g(iterable.)0 529 y FL(class)h FD(IterableUserDict)p FJ(\()p FC([)p FK(initialdata)12 b FC(])p FJ(\))208 628 y FN(Subclass)20 b(of)g FJ(UserDict)f FN(that)h(supports)f(direct)h (iteration)g(\(e.g.)k FJ(for)49 b(key)g(in)h(myDict)p FN(\).)0 775 y(In)60 b(addition)f(to)h(supporting)e(the)i(methods)f (and)g(operations)g(of)h(mappings)e(\(see)i(section)g(3.8\),)69 b FJ(UserDict)59 b FN(and)0 875 y FJ(IterableUserDict)18 b FN(instances)i(pro)o(vide)e(the)i(follo)n(wing)f(attrib)n(ute:)0 1022 y FD(data)208 1121 y FN(A)h(real)g(dictionary)f(used)h(to)g(store) g(the)g(contents)g(of)g(the)g FJ(UserDict)f FN(class.)0 1268 y FL(class)i FD(DictMixin)p FJ(\(\))208 1368 y FN(Mixin)k (de\002ning)f(all)i(dictionary)e(methods)h(for)g(classes)h(that)g (already)f(ha)n(v)o(e)g(a)h(minimum)e(dictionary)g(interf)o(ace)g (including)208 1468 y FJ(__getitem__\(\))p FN(,)18 b FJ(__setitem__\(\))p FN(,)g FJ(__delitem__\(\))p FN(,)g(and)h FJ(keys\(\))p FN(.)208 1600 y(This)24 b(mixin)g(should)g(be)g(used)g (as)i(a)f(superclass.)37 b(Adding)23 b(each)i(of)f(the)g(abo)o(v)o(e)f (methods)h(adds)g(progressi)n(v)o(ely)e(more)i(func-)208 1700 y(tionality)-5 b(.)43 b(F)o(or)26 b(instance,)i(de\002ning)d(all)i (b)n(ut)g FJ(__delitem__)e FN(will)i(preclude)e(only)h FJ(pop)h FN(and)f FJ(popitem)f FN(from)h(the)h(full)208 1800 y(interf)o(ace.)208 1932 y(In)22 b(addition)g(to)h(the)h(four)e (base)h(methods,)f(progressi)n(v)o(ely)f(more)h(ef)n(\002cienc)o(y)g (comes)h(with)g(de\002ning)f FJ(__contains__\(\))p FN(,)208 2032 y FJ(__iter__\(\))p FN(,)c(and)i FJ(iteritems\(\))p FN(.)208 2165 y(Since)g(the)g(mixin)g(has)g(no)g(kno)n(wledge)e(of)i (the)g(subclass)g(constructor)m(,)e(it)j(does)f(not)g(de\002ne)f FJ(__init__\(\))g FN(or)h FJ(copy\(\))p FN(.)0 2492 y FE(5.13)121 b Fx(UserList)31 b FE(\227)i(Class)g(wr)o(apper)i(f)l(or)f (list)f(objects)0 2725 y FL(Note:)e FN(This)24 b(module)f(is)h(a)n(v)n (ailable)g(for)f(backw)o(ard)f(compatibility)g(only)-5 b(.)34 b(If)24 b(you)f(are)g(writing)h(code)f(that)g(does)h(not)f(need) g(to)h(w)o(ork)0 2825 y(with)c(v)o(ersions)g(of)f(Python)h(earlier)f (than)h(Python)f(2.2,)g(please)i(consider)e(subclassing)g(directly)h (from)f(the)h(b)n(uilt-in)g FJ(list)g FN(type.)0 2972 y(This)k(module)f(de\002nes)h(a)g(class)h(that)f(acts)h(as)f(a)h (wrapper)d(around)g(list)j(objects.)37 b(It)24 b(is)h(a)f(useful)g (base)g(class)h(for)e(your)g(o)n(wn)g(list-lik)o(e)0 3071 y(classes,)k(which)e(can)g(inherit)g(from)f(them)h(and)g(o)o(v)o (erride)e(e)o(xisting)h(methods)g(or)h(add)g(ne)n(w)g(ones.)40 b(In)25 b(this)h(w)o(ay)f(one)g(can)g(add)g(ne)n(w)0 3171 y(beha)n(viors)19 b(to)h(lists.)0 3318 y(The)g FJ(UserList)f FN(module)g(de\002nes)h(the)g FJ(UserList)f FN(class:)0 3465 y FL(class)i FD(UserList)p FJ(\()p FC([)p FK(list)13 b FC(])p FJ(\))208 3564 y FN(Class)25 b(that)f(simulates)h(a)f(list.)38 b(The)24 b(instance')-5 b(s)24 b(contents)g(are)g(k)o(ept)g(in)g(a)h (re)o(gular)d(list,)k(which)e(is)h(accessible)f(via)h(the)f FJ(data)208 3664 y FN(attrib)n(ute)i(of)g FJ(UserList)g FN(instances.)44 b(The)27 b(instance')-5 b(s)26 b(contents)g(are)h (initially)f(set)i(to)f(a)g(cop)o(y)f(of)g FK(list)q FN(,)k(def)o(aulting)25 b(to)i(the)208 3764 y(empty)19 b(list)i FJ([])p FN(.)k FK(list)e FN(can)d(be)g(either)g(a)h(re)o (gular)d(Python)h(list,)i(or)f(an)g(instance)g(of)g FJ(UserList)f FN(\(or)h(a)g(subclass\).)0 3910 y(In)25 b(addition)g(to)g(supporting)f (the)h(methods)g(and)g(operations)f(of)h(mutable)g(sequences)f(\(see)i (section)f(3.6\),)h FJ(UserList)f FN(instances)0 4010 y(pro)o(vide)18 b(the)i(follo)n(wing)f(attrib)n(ute:)0 4157 y FD(data)208 4257 y FN(A)h(real)g(Python)f(list)j(object)d(used)h (to)h(store)f(the)g(contents)g(of)f(the)i FJ(UserList)e FN(class.)0 4403 y FL(Subclassing)30 b(r)o(equir)o(ements:)43 b FN(Subclasses)30 b(of)f FJ(UserList)g FN(are)g(e)o(xpect)f(to)i(of)n (fer)e(a)i(constructor)e(which)h(can)g(be)g(called)g(with)0 4503 y(either)18 b(no)h(ar)o(guments)e(or)h(one)h(ar)o(gument.)j(List)d (operations)f(which)g(return)g(a)h(ne)n(w)g(sequence)e(attempt)i(to)g (create)g(an)f(instance)h(of)g(the)0 4603 y(actual)i(implementation)f (class.)30 b(T)-7 b(o)22 b(do)f(so,)h(it)h(assumes)f(that)f(the)h (constructor)e(can)h(be)h(called)f(with)h(a)g(single)g(parameter)m(,)e (which)h(is)0 4702 y(a)g(sequence)e(object)g(used)h(as)h(a)g(data)f (source.)0 4849 y(If)e(a)h(deri)n(v)o(ed)d(class)k(does)e(not)g(wish)g (to)h(comply)e(with)h(this)h(requirement,)d(all)j(of)f(the)g(special)g (methods)g(supported)e(by)i(this)h(class)g(will)0 4949 y(need)g(to)g(be)h(o)o(v)o(erridden;)c(please)k(consult)f(the)g (sources)g(for)g(information)e(about)h(the)i(methods)e(which)h(need)g (to)h(be)f(pro)o(vided)e(in)i(that)0 5048 y(case.)0 5195 y(Changed)c(in)i(v)o(ersion)e(2.0:)h(Python)g(v)o(ersions)f(1.5.2)g (and)h(1.6)g(also)h(required)e(that)h(the)h(constructor)d(be)j (callable)f(with)h(no)f(parameters,)0 5295 y(and)i(of)n(fer)f(a)h (mutable)g FJ(data)g FN(attrib)n(ute.)24 b(Earlier)17 b(v)o(ersions)h(of)g(Python)f(did)h(not)g(attempt)f(to)i(create)f (instances)g(of)g(the)g(deri)n(v)o(ed)f(class.)p 0 5549 3901 4 v 0 5649 a FI(5.13.)52 b FJ(UserList)22 b FI(\227)h(Class)g(wr)o (apper)g(f)n(or)f(list)i(objects)1940 b(139)p eop end %%Page: 140 152 TeXDict begin 140 151 bop 0 88 a FE(5.14)121 b Fx(UserString)31 b FE(\227)i(Class)g(wr)o(apper)h(f)l(or)h(str)r(ing)e(objects)0 321 y FL(Note:)38 b FN(This)27 b FJ(UserString)f FN(class)i(from)e (this)h(module)f(is)i(a)n(v)n(ailable)f(for)f(backw)o(ard)g (compatibility)f(only)-5 b(.)44 b(If)27 b(you)f(are)h(writing)0 421 y(code)21 b(that)h(does)f(not)h(need)f(to)h(w)o(ork)f(with)h(v)o (ersions)e(of)i(Python)f(earlier)g(than)g(Python)g(2.2,)g(please)h (consider)e(subclassing)h(directly)0 520 y(from)e(the)h(b)n(uilt-in)g FJ(str)g FN(type)g(instead)g(of)g(using)f FJ(UserString)g FN(\(there)h(is)h(no)f(b)n(uilt-in)f(equi)n(v)n(alent)g(to)h FJ(MutableString)p FN(\).)0 667 y(This)i(module)e(de\002nes)i(a)g (class)h(that)f(acts)h(as)f(a)g(wrapper)f(around)f(string)h(objects.)30 b(It)22 b(is)h(a)f(useful)f(base)h(class)h(for)e(your)g(o)n(wn)g (string-)0 767 y(lik)o(e)e(classes,)h(which)e(can)g(inherit)g(from)g (them)g(and)g(o)o(v)o(erride)e(e)o(xisting)i(methods)g(or)g(add)g(ne)n (w)h(ones.)24 b(In)18 b(this)h(w)o(ay)g(one)f(can)h(add)f(ne)n(w)0 866 y(beha)n(viors)h(to)h(strings.)0 1013 y(It)f(should)f(be)h(noted)f (that)h(these)g(classes)h(are)e(highly)g(inef)n(\002cient)g(compared)f (to)i(real)g(string)f(or)h(Unicode)f(objects;)h(this)g(is)h(especially) 0 1113 y(the)g(case)h(for)e FJ(MutableString)p FN(.)0 1260 y(The)h FJ(UserString)f FN(module)g(de\002nes)h(the)g(follo)n (wing)e(classes:)0 1407 y FL(class)j FD(UserString)p FJ(\()p FC([)p FK(sequence)12 b FC(])p FJ(\))208 1506 y FN(Class)29 b(that)e(simulates)h(a)g(string)g(or)f(a)h(Unicode)f (string)g(object.)47 b(The)27 b(instance')-5 b(s)28 b(content)f(is)h(k) o(ept)f(in)h(a)g(re)o(gular)e(string)i(or)208 1606 y(Unicode)c(string)h (object,)g(which)g(is)h(accessible)f(via)h(the)f FJ(data)g FN(attrib)n(ute)g(of)g FJ(UserString)f FN(instances.)40 b(The)25 b(instance')-5 b(s)208 1705 y(contents)17 b(are)h(initially)h (set)g(to)f(a)h(cop)o(y)f(of)g FK(sequence)p FN(.)23 b FK(sequence)17 b FN(can)h(be)g(either)g(a)h(re)o(gular)e(Python)g (string)h(or)g(Unicode)f(string,)208 1805 y(an)h(instance)g(of)h FJ(UserString)e FN(\(or)h(a)h(subclass\))f(or)h(an)f(arbitrary)f (sequence)h(which)g(can)g(be)h(con)m(v)o(erted)c(into)k(a)g(string)f (using)208 1905 y(the)i(b)n(uilt-in)f FJ(str\(\))h FN(function.)0 2052 y FL(class)h FD(MutableString)p FJ(\()p FC([)p FK(sequence)12 b FC(])p FJ(\))208 2151 y FN(This)23 b(class)h(is)g(deri)n(v)o(ed)e (from)g(the)h FJ(UserString)f FN(abo)o(v)o(e)f(and)i(rede\002nes)f (strings)i(to)f(be)g FK(mutable)p FN(.)33 b(Mutable)22 b(strings)i(can')o(t)208 2251 y(be)f(used)g(as)h(dictionary)e(k)o(e)o (ys,)h(because)g(dictionaries)f(require)g FK(immutable)h FN(objects)g(as)h(k)o(e)o(ys.)34 b(The)23 b(main)g(intention)f(of)h (this)208 2350 y(class)c(is)f(to)h(serv)o(e)e(as)i(an)f(educational)e (e)o(xample)h(for)g(inheritance)f(and)i(necessity)g(to)g(remo)o(v)o(e)e (\(o)o(v)o(erride\))f(the)j FJ(__hash__\(\))208 2450 y FN(method)g(in)i(order)f(to)h(trap)f(attempts)h(to)g(use)g(a)h (mutable)e(object)g(as)i(dictionary)d(k)o(e)o(y)-5 b(,)18 b(which)i(w)o(ould)f(be)h(otherwise)f(v)o(ery)g(error)208 2550 y(prone)f(and)i(hard)f(to)i(track)e(do)n(wn.)0 2697 y(In)j(addition)g(to)h(supporting)d(the)j(methods)f(and)g(operations)f (of)i(string)f(and)g(Unicode)g(objects)h(\(see)g(section)f(3.6.1,)g (\223String)g(Meth-)0 2796 y(ods\224\),)d FJ(UserString)g FN(instances)h(pro)o(vide)e(the)j(follo)n(wing)d(attrib)n(ute:)0 2943 y FD(data)208 3043 y FN(A)i(real)g(Python)f(string)h(or)g(Unicode) f(object)h(used)g(to)g(store)g(the)h(content)e(of)h(the)g FJ(UserString)f FN(class.)0 3370 y FE(5.15)121 b Fx(types)32 b FE(\227)h(Names)h(f)l(or)g(b)n(uilt-in)f(types)0 3603 y FN(This)19 b(module)e(de\002nes)h(names)g(for)g(some)g(object)g (types)g(that)g(are)h(used)f(by)g(the)g(standard)f(Python)h (interpreter)m(,)e(b)n(ut)j(not)f(for)f(the)i(types)0 3703 y(de\002ned)g(by)g(v)n(arious)f(e)o(xtension)h(modules.)k(Also,)d (it)g(does)g(not)f(include)g(some)g(of)g(the)h(types)g(that)f(arise)h (during)e(processing)g(such)i(as)0 3802 y(the)j FJ(listiterator)e FN(type.)33 b(It)23 b(is)h(safe)f(to)g(use)h(`)p FJ(from)48 b(types)h(import)2401 3817 y(*)2451 3802 y FN(')23 b(\227)g(the)g (module)f(does)h(not)f(e)o(xport)g(an)o(y)g(names)0 3902 y(besides)e(the)g(ones)g(listed)h(here.)j(Ne)n(w)d(names)f(e)o(xported) e(by)h(future)g(v)o(ersions)h(of)g(this)g(module)f(will)i(all)g(end)e (in)i(`)p FJ(Type)p FN('.)0 4049 y(T)-7 b(ypical)20 b(use)g(is)h(for)f (functions)f(that)h(do)g(dif)n(ferent)e(things)i(depending)e(on)h (their)h(ar)o(gument)e(types,)i(lik)o(e)g(the)h(follo)n(wing:)236 4287 y FA(from)44 b(types)g(import)1043 4300 y(*)236 4378 y(def)h(delete\(mylist,)d(item\):)416 4469 y(if)i(type\(item\))f (is)i(IntType:)550 4561 y(del)f(mylist[item])416 4652 y(else:)550 4743 y(mylist.remove\(item\))0 5030 y FN(Starting)26 b(in)h(Python)f(2.2,)h(b)n(uilt-in)g(f)o(actory)e(functions)h(such)g (as)i FJ(int\(\))e FN(and)g FJ(str\(\))h FN(are)f(also)i(names)e(for)g (the)h(corresponding)0 5130 y(types.)d(This)19 b(is)h(no)n(w)e(the)h (preferred)d(w)o(ay)j(to)g(access)h(the)e(type)h(instead)f(of)h(using)f (the)h FJ(types)f FN(module.)23 b(Accordingly)-5 b(,)16 b(the)j(e)o(xample)0 5229 y(abo)o(v)o(e)g(should)g(be)h(written)g(as)h (follo)n(ws:)p 0 5549 3901 4 v 0 5649 a FI(140)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 141 153 TeXDict begin 141 152 bop 236 174 a FA(def)45 b(delete\(mylist,)d (item\):)416 266 y(if)i(isinstance\(item,)e(int\):)550 357 y(del)i(mylist[item])416 448 y(else:)550 540 y (mylist.remove\(item\))0 826 y FN(The)20 b(module)f(de\002nes)h(the)g (follo)n(wing)e(names:)0 973 y FD(NoneType)208 1073 y FN(The)h(type)h(of)g FJ(None)p FN(.)0 1220 y FD(TypeType)208 1319 y FN(The)f(type)h(of)g(type)g(objects)g(\(such)f(as)i(returned)e (by)g FJ(type\(\))p FN(\).)0 1466 y FD(BooleanType)208 1566 y FN(The)27 b(type)h(of)f(the)h FJ(bool)g FN(v)n(alues)f FJ(True)h FN(and)f FJ(False)p FN(;)32 b(this)c(is)h(an)f(alias)h(of)e (the)h(b)n(uilt-in)g FJ(bool\(\))f FN(function.)95 b(Ne)n(w)28 b(in)208 1665 y(v)o(ersion)18 b(2.3.)0 1812 y FD(IntType)208 1912 y FN(The)h(type)h(of)g(inte)o(gers)f(\(e.g.)25 b FJ(1)p FN(\).)0 2059 y FD(LongType)208 2158 y FN(The)19 b(type)h(of)g(long)f(inte)o(gers)h(\(e.g.)k FJ(1L)p FN(\).)0 2305 y FD(FloatType)208 2405 y FN(The)19 b(type)h(of)g(\003oating)g (point)f(numbers)g(\(e.g.)24 b FJ(1.0)p FN(\).)0 2552 y FD(ComplexType)208 2651 y FN(The)h(type)g(of)g(comple)o(x)f(numbers)g (\(e.g.)40 b FJ(1.0j)p FN(\).)h(This)25 b(is)i(not)e(de\002ned)g(if)g (Python)g(w)o(as)h(b)n(uilt)g(without)f(comple)o(x)e(number)208 2751 y(support.)0 2898 y FD(StringType)208 2997 y FN(The)c(type)h(of)g (character)f(strings)h(\(e.g.)k FJ('Spam')p FN(\).)0 3144 y FD(UnicodeType)208 3244 y FN(The)18 b(type)h(of)g(Unicode)f (character)g(strings)h(\(e.g.)24 b FJ(u'Spam')p FN(\).)f(This)d(is)g (not)e(de\002ned)h(if)g(Python)f(w)o(as)i(b)n(uilt)f(without)g(Unicode) 208 3344 y(support.)0 3490 y FD(TupleType)208 3590 y FN(The)g(type)h(of)g(tuples)g(\(e.g.)k FJ(\(1,)50 b(2,)f(3,)h('Spam'\)) p FN(\).)0 3737 y FD(ListType)208 3836 y FN(The)19 b(type)h(of)g(lists) i(\(e.g.)i FJ([0,)49 b(1,)h(2,)f(3])p FN(\).)0 3983 y FD(DictType)208 4083 y FN(The)19 b(type)h(of)g(dictionaries)f(\(e.g.)24 b FJ({'Bacon':)98 b(1,)50 b('Ham':)98 b(0})p FN(\).)0 4230 y FD(DictionaryType)208 4329 y FN(An)20 b(alternate)f(name)h(for)f FJ(DictType)p FN(.)0 4476 y FD(FunctionType)208 4576 y FN(The)g(type)h(of)g(user)n(-de\002ned)f(functions)f(and)i(lambdas.)0 4723 y FD(LambdaType)208 4822 y FN(An)g(alternate)f(name)h(for)f FJ(FunctionType)p FN(.)0 4969 y FD(GeneratorType)208 5069 y FN(The)g(type)h(of)g(generator)n(-iterator)d(objects,)j (produced)d(by)j(calling)g(a)h(generator)d(function.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.2.)0 5216 y FD(CodeType)208 5315 y FN(The)h(type)h(for)g(code)f(objects)h(such)g(as)h(returned)d (by)i FJ(compile\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(5.15.)52 b FJ(types)22 b FI(\227)i(Names)f(f)n(or)f(b)n(uilt-in)j (types)2279 b(141)p eop end %%Page: 142 154 TeXDict begin 142 153 bop 0 83 a FD(ClassType)208 183 y FN(The)19 b(type)h(of)g(user)n(-de\002ned)f(classes.)0 330 y FD(InstanceType)208 429 y FN(The)g(type)h(of)g(instances)g(of)g (user)n(-de\002ned)f(classes.)0 576 y FD(MethodType)208 676 y FN(The)g(type)h(of)g(methods)f(of)h(user)n(-de\002ned)f(class)i (instances.)0 823 y FD(UnboundMethodType)208 922 y FN(An)f(alternate)f (name)h(for)f FJ(MethodType)p FN(.)0 1069 y FD(BuiltinFunctionType)208 1169 y FN(The)g(type)h(of)g(b)n(uilt-in)g(functions)e(lik)o(e)j FJ(len\(\))f FN(or)g FJ(sys.exit\(\))p FN(.)0 1316 y FD(BuiltinMethodType)208 1415 y FN(An)g(alternate)f(name)h(for)f FJ(BuiltinFunction)p FN(.)0 1562 y FD(ModuleType)208 1662 y FN(The)g(type)h(of)g(modules.)0 1808 y FD(FileType)208 1908 y FN(The)f(type)h(of)g(open)f(\002le)i(objects)f(such)g(as)h FJ(sys.stdout)p FN(.)0 2055 y FD(XRangeType)208 2155 y FN(The)e(type)h(of)g(range)f(objects)h(returned)f(by)g FJ(xrange\(\))p FN(.)0 2301 y FD(SliceType)208 2401 y FN(The)g(type)h(of)g(objects)g(returned)e(by)i FJ(slice\(\))p FN(.)0 2548 y FD(EllipsisType)208 2648 y FN(The)f(type)h(of)g FJ(Ellipsis)p FN(.)0 2794 y FD(TracebackType)208 2894 y FN(The)f(type)h(of)g(traceback)f(objects)h(such)g(as)h(found)d(in)i FJ(sys.exc_traceback)p FN(.)0 3041 y FD(FrameType)208 3141 y FN(The)f(type)h(of)g(frame)f(objects)h(such)g(as)h(found)e(in)h FJ(tb.tb_frame)f FN(if)h FJ(tb)h FN(is)g(a)f(traceback)f(object.)0 3287 y FD(BufferType)208 3387 y FN(The)g(type)h(of)g(b)n(uf)n(fer)f (objects)h(created)f(by)h(the)g FJ(buffer\(\))g FN(function.)0 3534 y FD(DictProxyType)208 3634 y FN(The)f(type)h(of)g(dict)g (proxies,)f(such)h(as)h FJ(TypeType.__dict__)p FN(.)0 3780 y FD(NotImplementedType)208 3880 y FN(The)e(type)h(of)g FJ(NotImplemented)0 4027 y FD(GetSetDescriptorType)208 4127 y FN(The)i(type)g(of)h(objects)g(de\002ned)f(in)h(e)o(xtension)e (modules)h(with)h FJ(PyGetSetDef)p FN(,)f(such)g(as)i FJ(FrameType.f_locals)c FN(or)208 4226 y FJ(array.array.typecode)p FN(.)j(This)e(constant)e(is)j(not)e(de\002ned)g(in)h(implementations)e (of)h(Python)f(that)i(do)f(not)h(ha)n(v)o(e)f(such)208 4326 y(e)o(xtension)27 b(types,)j(so)f(for)f(portable)f(code)h(use)g FJ(hasattr\(types,)48 b('GetSetDescriptorType'\))p FN(.)97 b(Ne)n(w)28 b(in)208 4425 y(v)o(ersion)18 b(2.5.)0 4572 y FD(MemberDescriptorType)208 4672 y FN(The)112 b(type)h(of)f(objects)h (de\002ned)f(in)h(e)o(xtension)e(modules)h(with)h FJ(PyMemberDef)p FN(,)134 b(such)113 b(as)208 4772 y FJ(datetime.timedelta.days)p FN(.)27 b(This)22 b(constant)g(is)h(not)f(de\002ned)f(in)i (implementations)d(of)i(Python)f(that)h(do)g(not)g(ha)n(v)o(e)208 4871 y(such)g(e)o(xtension)f(types,)h(so)h(for)f(portable)f(code)g(use) i FJ(hasattr\(types,)47 b('MemberDescriptorType'\))p FN(.)60 b(Ne)n(w)208 4971 y(in)20 b(v)o(ersion)f(2.5.)0 5118 y FD(StringTypes)208 5217 y FN(A)i(sequence)e(containing)g FJ(StringType)g FN(and)h FJ(UnicodeType)f FN(used)i(to)g(f)o(acilitate) f(easier)h(checking)e(for)h(an)o(y)g(string)g(ob-)208 5317 y(ject.)k(Using)16 b(this)i(is)f(more)f(portable)g(than)g(using)g (a)h(sequence)f(of)g(the)h(tw)o(o)g(string)f(types)h(constructed)e (else)n(where)h(since)h(it)g(only)p 0 5549 3901 4 v 0 5649 a FI(142)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 143 155 TeXDict begin 143 154 bop 208 83 a FN(contains)17 b FJ(UnicodeType)g FN(if)i(it)g(has)f(been)g(b)n(uilt)g(in)h(the)f(running)e(v)o(ersion)h (of)h(Python.)24 b(F)o(or)18 b(e)o(xample:)k FJ(isinstance\(s,)208 183 y(types.StringTypes\))p FN(.)47 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.2.)0 510 y FE(5.16)121 b Fx(new)33 b FE(\227)f(Creation)j(of)f(r)r (untime)g(inter)s(nal)g(objects)0 743 y FN(The)21 b FJ(new)h FN(module)e(allo)n(ws)h(an)h(interf)o(ace)e(to)i(the)f(interpreter)f (object)h(creation)f(functions.)28 b(This)21 b(is)h(for)f(use)h (primarily)e(in)i(marshal-)0 843 y(type)j(functions,)h(when)f(a)i(ne)n (w)e(object)h(needs)f(to)h(be)g(created)f(\223magically\224)g(and)g (not)g(by)h(using)f(the)h(re)o(gular)e(creation)h(functions.)0 942 y(This)d(module)f(pro)o(vides)f(a)i(lo)n(w-le)n(v)o(el)f(interf)o (ace)g(to)h(the)g(interpreter)m(,)e(so)i(care)g(must)g(be)g(e)o(x)o (ercised)e(when)i(using)f(this)i(module.)28 b(It)23 b(is)0 1042 y(possible)d(to)g(supply)f(non-sensical)g(ar)o(guments)f(which)i (crash)g(the)g(interpreter)f(when)g(the)h(object)g(is)h(used.)0 1189 y(The)f FJ(new)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (functions:)0 1336 y FD(instance)p FJ(\()p FK(class)p FC([)p FK(,)g(dict)13 b FC(])p FJ(\))208 1435 y FN(This)26 b(function)e(creates)i(an)g(instance)g(of)g FK(class)g FN(with)h(dictionary)d FK(dict)k FN(without)d(calling)g(the)i FJ(__init__\(\))d FN(constructor)-5 b(.)208 1535 y(If)29 b FK(dict)h FN(is)g(omitted)f(or)g FJ(None)p FN(,)i(a)e(ne)n(w)-5 b(,)31 b(empty)d(dictionary)f(is)j(created)f(for)f(the)i(ne)n(w)e (instance.)52 b(Note)29 b(that)g(there)g(are)g(no)208 1634 y(guarantees)18 b(that)j(the)f(object)f(will)i(be)g(in)f(a)g (consistent)g(state.)0 1781 y FD(instancemethod)p FJ(\()p FK(function,)c(instance)o(,)j(class)p FJ(\))208 1881 y FN(This)h(function)f(will)j(return)d(a)i(method)e(object,)h(bound)f (to)i FK(instance)p FN(,)e(or)i(unbound)c(if)k FK(instance)f FN(is)i FJ(None)p FN(.)k FK(function)19 b FN(must)i(be)208 1981 y(callable.)0 2127 y FD(function)p FJ(\()p FK(code)o(,)d(globals)p FC([)p FK(,)h(name)p FC([)p FK(,)g(ar)m(gdefs)p FC([)p FK(,)g(closur)m(e)12 b FC(])g(])g(])p FJ(\))208 2227 y FN(Returns)20 b(a)g(\(Python\))f(function)f(with)j(the)f(gi)n(v)o(en) f(code)g(and)h(globals.)k(If)c FK(name)g FN(is)h(gi)n(v)o(en,)e(it)i (must)f(be)g(a)h(string)f(or)g FJ(None)p FN(.)25 b(If)20 b(it)208 2327 y(is)j(a)f(string,)h(the)f(function)e(will)j(ha)n(v)o(e)f (the)g(gi)n(v)o(en)f(name,)h(otherwise)g(the)g(function)e(name)i(will)h (be)f(tak)o(en)g(from)f FK(code)p FJ(.co_-)208 2426 y(name)p FN(.)31 b(If)22 b FK(ar)m(gdefs)f FN(is)j(gi)n(v)o(en,)d(it)i(must)f (be)g(a)h(tuple)f(and)g(will)h(be)f(used)g(to)g(determine)f(the)h(def)o (ault)g(v)n(alues)g(of)g(parameters.)30 b(If)208 2526 y FK(closur)m(e)16 b FN(is)i(gi)n(v)o(en,)e(it)i(must)e(be)h FJ(None)g FN(or)f(a)i(tuple)e(of)h(cell)g(objects)f(containing)f (objects)i(to)g(bind)f(to)h(the)g(names)f(in)h FK(code)p FJ(.co_-)208 2626 y(freevars)p FN(.)0 2772 y FD(code)p FJ(\()p FK(ar)m(gcount,)25 b(nlocals,)i(stac)n(ksize)o(,)h(\003a)o(gs,) f(codestring)o(,)g(constants,)f(names,)h(varnames,)g(\002lename)o(,)f (name)o(,)h(\002r)o(stlineno,)g(lno-)250 2872 y(tab)p FJ(\))208 2946 y FN(This)20 b(function)e(is)k(an)e(interf)o(ace)f(to)h (the)h FJ(PyCode_New\(\))d FN(C)j(function.)0 3093 y FD(module)p FJ(\()p FK(name[,)d(doc])p FJ(\))208 3193 y FN(This)i(function)f(returns)g(a)i(ne)n(w)f(module)e(object)i(with)h (name)e FK(name)p FN(.)25 b FK(name)19 b FN(must)i(be)f(a)h(string.)j (The)c(optional)f FK(doc)h FN(ar)o(gument)208 3292 y(can)g(ha)n(v)o(e)f (an)o(y)h(type.)0 3439 y FD(classobj)p FJ(\()p FK(name)o(,)e (baseclasses,)i(dict)q FJ(\))208 3539 y FN(This)f(function)e(returns)h (a)i(ne)n(w)f(class)h(object,)f(with)g(name)f FK(name)p FN(,)h(deri)n(v)o(ed)e(from)h FK(baseclasses)h FN(\(which)f(should)h (be)g(a)g(tuple)g(of)208 3638 y(classes\))i(and)e(with)i(namespace)d FK(dict)q FN(.)0 3966 y FE(5.17)121 b Fx(copy)32 b FE(\227)h(Shallo)n (w)h(and)h(deep)g(cop)l(y)f(oper)o(ations)0 4199 y FN(This)20 b(module)f(pro)o(vides)g(generic)g(\(shallo)n(w)g(and)h(deep\))f(cop)o (ying)g(operations.)0 4345 y(Interf)o(ace)g(summary:)236 4584 y FA(import)44 b(copy)236 4766 y(x)h(=)g(copy.copy\(y\))356 b(#)45 b(make)f(a)h(shallow)e(copy)h(of)h(y)236 4858 y(x)g(=)g(copy.deepcopy\(y\))176 b(#)45 b(make)f(a)h(deep)f(copy)g(of)g (y)0 5097 y FN(F)o(or)20 b(module)f(speci\002c)h(errors,)f FJ(copy.error)g FN(is)i(raised.)0 5244 y(The)k(dif)n(ference)e(between) h(shallo)n(w)h(and)f(deep)g(cop)o(ying)g(is)i(only)e(rele)n(v)n(ant)g (for)g(compound)e(objects)j(\(objects)f(that)h(contain)f(other)0 5343 y(objects,)c(lik)o(e)g(lists)i(or)e(class)h(instances\):)p 0 5549 3901 4 v 0 5649 a FI(5.16.)52 b FJ(new)23 b FI(\227)g(Creation)h (of)f(r)q(untime)h(inter)r(nal)h(objects)1956 b(143)p eop end %%Page: 144 156 TeXDict begin 144 155 bop 125 83 a FM(\017)41 b FN(A)22 b FK(shallow)f(copy)g FN(constructs)g(a)h(ne)n(w)g(compound)c(object)k (and)f(then)g(\(to)g(the)h(e)o(xtent)f(possible\))g(inserts)h FK(r)m(efer)m(ences)g FN(into)f(it)h(to)208 183 y(the)e(objects)g (found)e(in)j(the)f(original.)125 349 y FM(\017)41 b FN(A)21 b FK(deep)f(copy)h FN(constructs)f(a)h(ne)n(w)g(compound)d (object)i(and)h(then,)f(recursi)n(v)o(ely)-5 b(,)19 b(inserts)i FK(copies)g FN(into)f(it)i(of)f(the)g(objects)f(found)208 448 y(in)g(the)g(original.)0 678 y(T)-7 b(w)o(o)20 b(problems)f(often)h (e)o(xist)g(with)g(deep)g(cop)o(y)f(operations)g(that)h(don')o(t)f(e)o (xist)h(with)g(shallo)n(w)g(cop)o(y)g(operations:)125 908 y FM(\017)41 b FN(Recursi)n(v)o(e)18 b(objects)h(\(compound)d (objects)k(that,)f(directly)f(or)i(indirectly)-5 b(,)17 b(contain)i(a)g(reference)f(to)i(themselv)o(es\))e(may)h(cause)g(a)208 1008 y(recursi)n(v)o(e)f(loop.)125 1174 y FM(\017)41 b FN(Because)23 b(deep)f(cop)o(y)g(copies)h FK(e)o(verything)f FN(it)h(may)g(cop)o(y)f(too)h(much,)f(e.g.,)h(administrati)n(v)o(e)e (data)i(structures)g(that)g(should)f(be)208 1273 y(shared)d(e)n(v)o(en) g(between)h(copies.)0 1503 y(The)g FJ(deepcopy\(\))f FN(function)f(a)n(v)n(oids)i(these)h(problems)e(by:)125 1733 y FM(\017)41 b FN(k)o(eeping)18 b(a)j(\223memo\224)e(dictionary)f (of)i(objects)g(already)f(copied)g(during)g(the)h(current)f(cop)o(ying) f(pass;)j(and)125 1899 y FM(\017)41 b FN(letting)20 b(user)n (-de\002ned)e(classes)j(o)o(v)o(erride)d(the)i(cop)o(ying)f(operation)f (or)i(the)g(set)h(of)f(components)e(copied.)0 2129 y(This)26 b(module)f(does)h(not)g(cop)o(y)g(types)g(lik)o(e)g(module,)g(method,)h (stack)f(trace,)h(stack)g(frame,)f(\002le,)j(sock)o(et,)e(windo)n(w)-5 b(,)26 b(array)-5 b(,)26 b(or)g(an)o(y)0 2229 y(similar)c(types.)30 b(It)23 b(does)f(\223cop)o(y\224)e(functions)h(and)g(classes)j (\(shallo)n(w)d(and)h(deeply\),)e(by)i(returning)e(the)i(original)f (object)g(unchanged;)0 2328 y(this)k(is)g(compatible)e(with)i(the)f(w)o (ay)g(these)h(are)f(treated)g(by)g(the)g FJ(pickle)g FN(module.)75 b(Changed)23 b(in)h(v)o(ersion)f(2.5:)h(Added)f(cop)o (ying)0 2428 y(functions.)0 2575 y(Classes)e(can)e(use)h(the)g(same)f (interf)o(aces)g(to)h(control)e(cop)o(ying)g(that)h(the)o(y)g(use)h(to) g(control)e(pickling.)23 b(See)d(the)g(description)e(of)h(module)0 2674 y FJ(pickle)h FN(for)f(information)f(on)i(these)g(methods.)k(The)c FJ(copy)g FN(module)f(does)h(not)f(use)i(the)f FJ(copy_reg)f FN(re)o(gistration)g(module.)0 2821 y(In)28 b(order)g(for)g(a)h(class)g (to)g(de\002ne)f(its)i(o)n(wn)e(cop)o(y)g(implementation,)g(it)h(can)g (de\002ne)f(special)h(methods)e FJ(__copy__\(\))g FN(and)i FJ(__-)0 2921 y(deepcopy__\(\))p FN(.)23 b(The)18 b(former)f(is)j (called)e(to)h(implement)f(the)g(shallo)n(w)h(cop)o(y)f(operation;)f (no)h(additional)g(ar)o(guments)e(are)j(passed.)0 3021 y(The)28 b(latter)h(is)g(called)f(to)h(implement)e(the)h(deep)g(cop)o (y)g(operation;)i(it)g(is)f(passed)f(one)g(ar)o(gument,)g(the)g(memo)g (dictionary)-5 b(.)47 b(If)29 b(the)0 3120 y FJ(__deepcopy__\(\))c FN(implementation)f(needs)j(to)g(mak)o(e)f(a)h(deep)f(cop)o(y)g(of)h(a) g(component,)f(it)h(should)f(call)h(the)g FJ(deepcopy\(\))0 3220 y FN(function)18 b(with)j(the)f(component)e(as)j(\002rst)g(ar)o (gument)c(and)j(the)g(memo)g(dictionary)e(as)j(second)e(ar)o(gument.)0 3367 y FL(See)i(Also:)0 3514 y FN(Module)e FJ(pickle)h FN(\(section)f(13.1\):)208 3613 y(Discussion)h(of)g(the)g(special)g (methods)f(used)h(to)h(support)d(object)i(state)h(retrie)n(v)n(al)e (and)h(restoration.)0 3941 y FE(5.18)121 b Fx(pprint)32 b FE(\227)h(Data)h(pretty)h(pr)r(inter)0 4173 y FN(The)24 b FJ(pprint)f FN(module)f(pro)o(vides)h(a)h(capability)f(to)h (\223pretty-print\224)d(arbitrary)i(Python)f(data)i(structures)f(in)h (a)h(form)e(which)g(can)h(be)0 4273 y(used)g(as)i(input)d(to)i(the)g (interpreter)-5 b(.)37 b(If)24 b(the)h(formatted)e(structures)h (include)f(objects)i(which)f(are)g(not)g(fundamental)f(Python)g(types,) 0 4373 y(the)e(representation)d(may)i(not)g(be)h(loadable.)k(This)20 b(may)h(be)f(the)h(case)g(if)f(objects)h(such)f(as)h(\002les,)h(sock)o (ets,)e(classes,)i(or)e(instances)h(are)0 4472 y(included,)d(as)j(well) g(as)g(man)o(y)e(other)g(b)n(uiltin)h(objects)g(which)g(are)g(not)g (representable)e(as)j(Python)e(constants.)0 4619 y(The)i(formatted)e (representation)f(k)o(eeps)j(objects)g(on)f(a)h(single)g(line)g(if)g (it)h(can,)f(and)f(breaks)g(them)g(onto)g(multiple)h(lines)g(if)g(the)o (y)f(don')o(t)0 4719 y(\002t)e(within)f(the)h(allo)n(wed)f(width.)23 b(Construct)17 b FJ(PrettyPrinter)f FN(objects)h(e)o(xplicitly)f(if)i (you)f(need)f(to)i(adjust)f(the)h(width)f(constraint.)0 4866 y(Changed)24 b(in)h(v)o(ersion)e(2.5:)i(Dictionaries)f(are)h (sorted)f(by)h(k)o(e)o(y)f(before)f(the)i(display)f(is)i(computed;)g (before)d(2.5,)i(a)h(dictionary)d(w)o(as)0 4965 y(sorted)d(only)f(if)i (its)g(display)e(required)g(more)g(than)h(one)f(line,)h(although)f (that)h(w)o(asn')o(t)g(documented.)0 5112 y(The)g FJ(pprint)f FN(module)g(de\002nes)h(one)g(class:)0 5259 y FL(class)h FD(PrettyPrinter)p FJ(\()p FK(...)p FJ(\))208 5359 y FN(Construct)f(a)i FJ(PrettyPrinter)e FN(instance.)28 b(This)22 b(constructor)d(understands)h(se)n(v)o(eral)g(k)o(e)o(yw)o (ord)g(parameters.)27 b(An)22 b(output)p 0 5549 3901 4 v 0 5649 a FI(144)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 145 157 TeXDict begin 145 156 bop 208 83 a FN(stream)24 b(may)h(be)g(set)h (using)e(the)h FK(str)m(eam)h FN(k)o(e)o(yw)o(ord;)g(the)f(only)f (method)f(used)i(on)g(the)g(stream)g(object)f(is)i(the)f(\002le)h (protocol')-5 b(s)208 183 y FJ(write\(\))17 b FN(method.)23 b(If)c(not)f(speci\002ed,)g(the)h FJ(PrettyPrinter)d FN(adopts)i FJ(sys.stdout)p FN(.)23 b(Three)18 b(additional)f (parameters)208 282 y(may)23 b(be)h(used)f(to)h(control)e(the)i (formatted)e(representation.)34 b(The)23 b(k)o(e)o(yw)o(ords)f(are)i FK(indent)q FN(,)g FK(depth)p FN(,)g(and)f FK(width)p FN(.)36 b(The)23 b(amount)208 382 y(of)g(indentation)f(added)h(for)g (each)g(recursi)n(v)o(e)f(le)n(v)o(el)i(is)h(speci\002ed)e(by)g FK(indent)q FN(;)j(the)d(def)o(ault)g(is)i(one.)35 b(Other)24 b(v)n(alues)f(can)h(cause)208 482 y(output)i(to)h(look)f(a)i(little)g (odd,)g(b)n(ut)f(can)g(mak)o(e)g(nesting)f(easier)i(to)f(spot.)46 b(The)27 b(number)e(of)i(le)n(v)o(els)g(which)g(may)g(be)g(printed)208 581 y(is)g(controlled)e(by)i FK(depth)p FN(;)i(if)e(the)g(data)g (structure)f(being)g(printed)g(is)h(too)g(deep,)h(the)f(ne)o(xt)f (contained)f(le)n(v)o(el)i(is)g(replaced)f(by)208 681 y(`)p FJ(...)p FN('.)i(By)22 b(def)o(ault,)f(there)g(is)i(no)e (constraint)f(on)i(the)f(depth)g(of)g(the)h(objects)f(being)g (formatted.)27 b(The)22 b(desired)f(output)f(width)208 780 y(is)28 b(constrained)e(using)i(the)f FK(width)h FN(parameter;)i(the)e(def)o(ault)f(is)i(eighty)e(characters.)46 b(If)28 b(a)g(structure)f(cannot)g(be)g(formatted)208 880 y(within)20 b(the)g(constrained)e(width,)i(a)g(best)h(ef)n(fort)e (will)i(be)f(made.)444 1104 y FA(>>>)44 b(import)g(pprint,)g(sys)444 1196 y(>>>)g(stuff)g(=)h(sys.path[:])444 1287 y(>>>)f(stuff.insert\(0,) e(stuff[:]\))444 1378 y(>>>)i(pp)h(=)f (pprint.PrettyPrinter\(indent=4\))444 1469 y(>>>)g(pp.pprint\(stuff\)) 444 1561 y([)134 b([)g('',)802 1652 y('/usr/local/lib/python1.5',)802 1743 y('/usr/local/lib/python1.5/test',)802 1835 y ('/usr/local/lib/python1.5/sunos5',)802 1926 y ('/usr/local/lib/python1.5/sharedmodules',)802 2017 y ('/usr/local/lib/python1.5/tkinter'],)623 2109 y('',)623 2200 y('/usr/local/lib/python1.5',)623 2291 y ('/usr/local/lib/python1.5/test',)623 2383 y ('/usr/local/lib/python1.5/sunos5',)623 2474 y ('/usr/local/lib/python1.5/sharedmodules')o(,)623 2565 y('/usr/local/lib/python1.5/tkinter'])444 2657 y(>>>)444 2748 y(>>>)44 b(import)g(parser)444 2839 y(>>>)g(tup)g(=)h (parser.ast2tuple\()444 2931 y(...)223 b (parser.suite\(open\('pprint.py'\).read\(\)\)\)[1])o([1][1])444 3022 y(>>>)44 b(pp)h(=)f(pprint.PrettyPrinter\(depth=6\))444 3113 y(>>>)g(pp.pprint\(tup\))444 3205 y(\(266,)g(\(267,)g(\(307,)g (\(287,)g(\(288,)g(\(...\)\)\)\)\)\))0 3408 y FN(The)20 b FJ(PrettyPrinter)e FN(class)j(supports)e(se)n(v)o(eral)h(deri)n(v)n (ati)n(v)o(e)e(functions:)0 3555 y FD(pformat)p FJ(\()p FK(object)q FC([)p FK(,)g(indent)q FC([)p FK(,)i(width)p FC([)p FK(,)f(depth)12 b FC(])g(])g(])p FJ(\))208 3655 y FN(Return)35 b(the)i(formatted)e(representation)f(of)i FK(object)h FN(as)g(a)g(string.)73 b FK(indent)q FN(,)40 b FK(width)c FN(and)g FK(depth)f FN(will)j(be)e(passed)g(to)h(the)208 3754 y FJ(PrettyPrinter)28 b FN(constructor)g(as)i(formatting)e (parameters.)108 b(Changed)28 b(in)i(v)o(ersion)f(2.4:)g(The)h (parameters)e FK(indent)q FN(,)208 3854 y FK(width)20 b FN(and)g FK(depth)f FN(were)h(added.)0 4001 y FD(pprint)p FJ(\()p FK(object)q FC([)p FK(,)e(str)m(eam)p FC([)p FK(,)j(indent)q FC([)p FK(,)e(width)p FC([)p FK(,)h(depth)12 b FC(])g(])g(])g(])p FJ(\))208 4100 y FN(Prints)42 b(the)h(formatted)e (representation)f(of)i FK(object)i FN(on)e FK(str)m(eam)p FN(,)48 b(follo)n(wed)41 b(by)i(a)f(ne)n(wline.)92 b(If)42 b FK(str)m(eam)h FN(is)h(omitted,)208 4200 y FJ(sys.stdout)25 b FN(is)j(used.)46 b(This)27 b(may)f(be)h(used)g(in)g(the)h(interacti)n (v)o(e)d(interpreter)h(instead)h(of)f(a)i FJ(print)e FN(statement)h(for)g(in-)208 4300 y(specting)g(v)n(alues.)50 b FK(indent)q FN(,)30 b FK(width)e FN(and)g FK(depth)g FN(will)h(be)f(passed)h(to)g(the)f FJ(PrettyPrinter)f FN(constructor)f(as)j(formatting)208 4399 y(parameters.)p 0 5549 3901 4 v 0 5649 a FI(5.18.)52 b FJ(pprint)22 b FI(\227)h(Data)h(pretty)e(pr)q(inter)2433 b(145)p eop end %%Page: 146 158 TeXDict begin 146 157 bop 444 174 a FA(>>>)44 b(stuff)g(=)h (sys.path[:])444 266 y(>>>)f(stuff.insert\(0,)e(stuff\))444 357 y(>>>)i(pprint.pprint\(stuff\))444 448 y([,)489 540 y('',)489 631 y ('/usr/local/lib/python1.5',)489 722 y ('/usr/local/lib/python1.5/test',)489 814 y ('/usr/local/lib/python1.5/sunos5',)489 905 y ('/usr/local/lib/python1.5/sharedmodul)o(es',)489 996 y('/usr/local/lib/python1.5/tkinter'])208 1153 y FN(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(The)h(parameters)f FK(indent)q FN(,)h FK(width)g FN(and)g FK(depth)f FN(were)h(added.)0 1300 y FD(isreadable)p FJ(\()p FK(object)q FJ(\))208 1399 y FN(Determine)h(if)i(the)f(formatted)f(representation)f(of)i FK(object)h FN(is)h(\223readable,)-6 b(\224)21 b(or)h(can)g(be)h(used)f (to)g(reconstruct)f(the)h(v)n(alue)g(using)208 1499 y FJ(eval\(\))p FN(.)i(This)c(al)o(w)o(ays)h(returns)e FJ(False)h FN(for)g(recursi)n(v)o(e)e(objects.)444 1723 y FA(>>>)44 b(pprint.isreadable\(stuff\))444 1814 y(False)0 2018 y FD(isrecursive)p FJ(\()p FK(object)q FJ(\))208 2118 y FN(Determine)19 b(if)h FK(object)h FN(requires)f(a)g(recursi)n (v)o(e)f(representation.)0 2265 y(One)h(more)f(support)g(function)g(is) i(also)f(de\002ned:)0 2411 y FD(saferepr)p FJ(\()p FK(object)q FJ(\))208 2511 y FN(Return)29 b(a)h(string)g(representation)e(of)h FK(object)q FN(,)j(protected)d(against)g(recursi)n(v)o(e)f(data)i (structures.)53 b(If)30 b(the)g(representation)e(of)208 2611 y FK(object)c FN(e)o(xposes)f(a)g(recursi)n(v)o(e)f(entry)-5 b(,)23 b(the)h(recursi)n(v)o(e)e(reference)f(will)k(be)e(represented)f (as)i(`)p FJ()p FN('.)23 b(The)c(representation)f (is)k(not)d(otherwise)h(formatted.)236 2948 y FA(>>>)45 b(pprint.saferepr\(stuff\))236 3040 y("[,)f('',)h('/usr/local/lib/python1.5',)c('/usr/loca)236 3131 y(l/lib/python1.5/test',)h('/usr/local/lib/python1.5/sunos5',)e ('/usr/local/lib/python)236 3222 y(1.5/sharedmodules',)j ('/usr/local/lib/python1.5/tkinter']")0 3647 y Fv(5.18.1)101 b(PrettyPr)q(inter)29 b(Objects)0 3850 y FJ(PrettyPrinter)18 b FN(instances)i(ha)n(v)o(e)g(the)g(follo)n(wing)f(methods:)0 3997 y FD(pformat)p FJ(\()p FK(object)q FJ(\))208 4097 y FN(Return)53 b(the)h(formatted)f(representation)f(of)i FK(object)q FN(.)127 b(This)54 b(tak)o(es)h(into)f(account)f(the)h (options)f(passed)h(to)h(the)208 4196 y FJ(PrettyPrinter)18 b FN(constructor)-5 b(.)0 4343 y FD(pprint)p FJ(\()p FK(object)q FJ(\))208 4443 y FN(Print)20 b(the)g(formatted)f (representation)f(of)i FK(object)h FN(on)e(the)i(con\002gured)c (stream,)j(follo)n(wed)f(by)h(a)h(ne)n(wline.)0 4590 y(The)g(follo)n(wing)f(methods)g(pro)o(vide)f(the)j(implementations)d (for)i(the)g(corresponding)d(functions)i(of)h(the)g(same)h(names.)28 b(Using)21 b(these)0 4689 y(methods)e(on)h(an)g(instance)g(is)h (slightly)f(more)f(ef)n(\002cient)h(since)g(ne)n(w)g FJ(PrettyPrinter)f FN(objects)h(don')o(t)e(need)i(to)g(be)g(created.)0 4836 y FD(isreadable)p FJ(\()p FK(object)q FJ(\))208 4936 y FN(Determine)14 b(if)i(the)f(formatted)f(representation)g(of)h (the)g(object)g(is)i(\223readable,)-6 b(\224)15 b(or)g(can)g(be)h(used) f(to)h(reconstruct)e(the)h(v)n(alue)g(using)208 5035 y FJ(eval\(\))p FN(.)27 b(Note)21 b(that)h(this)g(returns)e FJ(False)h FN(for)g(recursi)n(v)o(e)f(objects.)28 b(If)21 b(the)g FK(depth)f FN(parameter)g(of)h(the)g FJ(PrettyPrinter)208 5135 y FN(is)g(set)g(and)e(the)i(object)e(is)i(deeper)e(than)h(allo)n (wed,)f(this)i(returns)e FJ(False)p FN(.)0 5282 y FD(isrecursive)p FJ(\()p FK(object)q FJ(\))208 5381 y FN(Determine)g(if)h(the)g(object)g (requires)f(a)i(recursi)n(v)o(e)e(representation.)p 0 5549 3901 4 v 0 5649 a FI(146)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 147 159 TeXDict begin 147 158 bop 0 83 a FN(This)20 b(method)f(is)i(pro)o (vided)d(as)j(a)g(hook)e(to)h(allo)n(w)g(subclasses)h(to)f(modify)f (the)h(w)o(ay)g(objects)g(are)g(con)m(v)o(erted)e(to)i(strings.)25 b(The)20 b(def)o(ault)0 183 y(implementation)e(uses)j(the)f(internals)g (of)f(the)i FJ(saferepr\(\))e FN(implementation.)0 330 y FD(format)p FJ(\()p FK(object,)f(conte)n(xt,)i(maxle)o(vels,)f(le)o (vel)p FJ(\))208 429 y FN(Returns)g(three)h(v)n(alues:)25 b(the)19 b(formatted)g(v)o(ersion)f(of)i FK(object)h FN(as)g(a)f(string,)f(a)i(\003ag)f(indicating)e(whether)h(the)h(result) g(is)h(readable,)208 529 y(and)27 b(a)i(\003ag)g(indicating)e(whether)g (recursion)g(w)o(as)j(detected.)48 b(The)29 b(\002rst)g(ar)o(gument)d (is)j(the)g(object)f(to)g(be)h(presented.)48 b(The)208 628 y(second)30 b(is)i(a)f(dictionary)f(which)g(contains)h(the)g FJ(id\(\))g FN(of)g(objects)g(that)g(are)g(part)g(of)f(the)i(current)d (presentation)h(conte)o(xt)208 728 y(\(direct)25 b(and)g(indirect)g (containers)f(for)h FK(object)i FN(that)f(are)g(af)n(fecting)e(the)i (presentation\))e(as)i(the)g(k)o(e)o(ys;)i(if)e(an)g(object)f(needs)g (to)208 828 y(be)h(presented)f(which)h(is)h(already)f(represented)e(in) j FK(conte)n(xt)q FN(,)h(the)e(third)g(return)f(v)n(alue)h(should)f(be) i FJ(True)p FN(.)43 b(Recursi)n(v)o(e)26 b(calls)208 927 y(to)e(the)h FJ(format\(\))f FN(method)f(should)g(add)h(additional) g(entries)g(for)g(containers)f(to)i(this)g(dictionary)-5 b(.)36 b(The)24 b(third)g(ar)o(gument,)208 1027 y FK(maxle)o(vels)p FN(,)j(gi)n(v)o(es)f(the)h(requested)e(limit)j(to)e(recursion;)j(this)e (will)g(be)g FJ(0)g FN(if)g(there)f(is)i(no)e(requested)f(limit.)45 b(This)27 b(ar)o(gument)208 1127 y(should)e(be)h(passed)g(unmodi\002ed) e(to)i(recursi)n(v)o(e)f(calls.)43 b(The)26 b(fourth)e(ar)o(gument,)h FK(le)o(vel)p FN(,)j(gi)n(v)o(es)d(the)h(current)f(le)n(v)o(el;)k (recursi)n(v)o(e)208 1226 y(calls)20 b(should)g(be)g(passed)g(a)g(v)n (alue)g(less)h(than)f(that)g(of)g(the)g(current)f(call.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1554 y FE(5.19)121 b Fx(repr)32 b FE(\227)h(Alter)s(nate)i Fx(repr\(\))c FE(implementation)0 1786 y FN(The)16 b FJ(repr)f FN(module)g(pro)o (vides)f(a)i(means)g(for)f(producing)e(object)j(representations)e(with) i(limits)g(on)g(the)g(size)g(of)g(the)g(resulting)f(strings.)0 1886 y(This)20 b(is)h(used)f(in)h(the)f(Python)f(deb)n(ugger)f(and)i (may)f(be)i(useful)e(in)i(other)e(conte)o(xts)g(as)i(well.)0 2033 y(This)f(module)f(pro)o(vides)g(a)h(class,)h(an)f(instance,)g(and) f(a)i(function:)0 2180 y FL(class)g FD(Repr)p FJ(\(\))208 2279 y FN(Class)f(which)f(pro)o(vides)f(formatting)f(services)i(useful) g(in)h(implementing)d(functions)h(similar)h(to)h(the)f(b)n(uilt-in)g FJ(repr\(\))p FN(;)g(size)208 2379 y(limits)h(for)f(dif)n(ferent)f (object)h(types)h(are)g(added)e(to)i(a)n(v)n(oid)f(the)h(generation)e (of)h(representations)f(which)i(are)f(e)o(xcessi)n(v)o(ely)g(long.)0 2526 y FD(aRepr)208 2626 y FN(This)28 b(is)h(an)f(instance)g(of)f FJ(Repr)h FN(which)g(is)h(used)f(to)g(pro)o(vide)e(the)i FJ(repr\(\))f FN(function)g(described)f(belo)n(w)-5 b(.)48 b(Changing)27 b(the)208 2725 y(attrib)n(utes)20 b(of)g(this)g(object)g (will)h(af)n(fect)f(the)g(size)h(limits)g(used)e(by)h FJ(repr\(\))g FN(and)g(the)g(Python)f(deb)n(ugger)-5 b(.)0 2872 y FD(repr)p FJ(\()p FK(obj)p FJ(\))208 2972 y FN(This)20 b(is)h(the)g FJ(repr\(\))e FN(method)g(of)h FJ(aRepr)p FN(.)25 b(It)c(returns)e(a)i(string)f(similar)h(to)f(that)g (returned)f(by)h(the)g(b)n(uilt-in)g(function)f(of)h(the)208 3071 y(same)g(name,)f(b)n(ut)h(with)h(limits)g(on)f(most)g(sizes.)0 3356 y Fv(5.19.1)101 b(Repr)28 b(Objects)0 3559 y FJ(Repr)21 b FN(instances)g(pro)o(vide)e(se)n(v)o(eral)i(members)f(which)h(can)g (be)g(used)g(to)g(pro)o(vide)e(size)j(limits)g(for)f(the)g (representations)e(of)i(dif)n(ferent)0 3659 y(object)f(types,)f(and)h (methods)f(which)h(format)f(speci\002c)h(object)g(types.)0 3806 y FD(maxlevel)208 3905 y FN(Depth)f(limit)i(on)f(the)g(creation)f (of)h(recursi)n(v)o(e)f(representations.)k(The)d(def)o(ault)f(is)i FJ(6)p FN(.)0 4052 y FD(maxdict)0 4152 y(maxlist)0 4251 y(maxtuple)0 4351 y(maxset)0 4451 y(maxfrozenset)0 4550 y(maxdeque)0 4650 y(maxarray)208 4749 y FN(Limits)k(on)g(the)g(number)e (of)h(entries)h(represented)f(for)g(the)h(named)f(object)g(type.)39 b(The)25 b(def)o(ault)f(is)i FJ(4)f FN(for)g FJ(maxdict)p FN(,)g FJ(5)g FN(for)208 4849 y FJ(maxarray)p FN(,)19 b(and)g FJ(6)i FN(for)e(the)i(others.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4:)h FJ(maxset)p FN(,)f FJ(maxfrozenset)p FN(,)g(and)g FJ(set)p FN(.)25 b(.)0 4996 y FD(maxlong)208 5096 y FN(Maximum)f(number)f(of)j(characters)e(in)i(the)f (representation)f(for)h(a)h(long)f(inte)o(ger)-5 b(.)40 b(Digits)26 b(are)f(dropped)f(from)g(the)i(middle.)208 5195 y(The)19 b(def)o(ault)h(is)h FJ(40)p FN(.)0 5342 y FD(maxstring)p 0 5549 3901 4 v 0 5649 a FI(5.19.)52 b FJ(repr)23 b FI(\227)g(Alter)r(nate)h FJ(repr\(\))e FI(implementation)1958 b(147)p eop end %%Page: 148 160 TeXDict begin 148 159 bop 208 83 a FN(Limit)23 b(on)f(the)h(number)f (of)g(characters)g(in)i(the)f(representation)d(of)j(the)g(string.)33 b(Note)23 b(that)g(the)g(\223normal\224)f(representation)f(of)208 183 y(the)k(string)h(is)g(used)g(as)g(the)g(character)f(source:)35 b(if)26 b(escape)g(sequences)f(are)h(needed)e(in)i(the)g (representation,)e(these)i(may)g(be)208 282 y(mangled)18 b(when)i(the)g(representation)e(is)j(shortened.)i(The)d(def)o(ault)g (is)h FJ(30)p FN(.)0 429 y FD(maxother)208 529 y FN(This)g(limit)g(is)h (used)f(to)g(control)f(the)h(size)g(of)g(object)g(types)f(for)h(which)f (no)h(speci\002c)g(formatting)e(method)h(is)h(a)n(v)n(ailable)g(on)g (the)208 628 y FJ(Repr)f FN(object.)k(It)c(is)i(applied)d(in)h(a)h (similar)f(manner)f(as)i FJ(maxstring)p FN(.)j(The)19 b(def)o(ault)h(is)h FJ(20)p FN(.)0 775 y FD(repr)p FJ(\()p FK(obj)p FJ(\))208 875 y FN(The)e(equi)n(v)n(alent)g(to)h(the)g(b)n (uilt-in)g FJ(repr\(\))g FN(that)g(uses)h(the)f(formatting)e(imposed)h (by)h(the)g(instance.)0 1022 y FD(repr1)p FJ(\()p FK(obj,)e(le)o(vel)p FJ(\))208 1121 y FN(Recursi)n(v)o(e)f(implementation)g(used)h(by)h FJ(repr\(\))p FN(.)k(This)c(uses)h(the)e(type)g(of)h FK(obj)f FN(to)h(determine)e(which)h(formatting)f(method)g(to)208 1221 y(call,)k(passing)f(it)h FK(obj)g FN(and)f FK(le)o(vel)p FN(.)27 b(The)20 b(type-speci\002c)f(methods)h(should)g(call)h FJ(repr1\(\))f FN(to)h(perform)d(recursi)n(v)o(e)i(formatting,)208 1321 y(with)g FK(le)o(vel)49 b FJ(-)h(1)21 b FN(for)e(the)h(v)n(alue)g (of)g FK(le)o(vel)g FN(in)g(the)h(recursi)n(v)o(e)d(call.)0 1468 y FD(repr_)p Fo(type)p FJ(\()p FK(obj,)g(le)o(vel)p FJ(\))208 1567 y FN(F)o(ormatting)25 b(methods)g(for)h(speci\002c)h (types)g(are)f(implemented)f(as)j(methods)d(with)i(a)g(name)f(based)h (on)f(the)h(type)f(name.)44 b(In)208 1667 y(the)32 b(method)g(name,)i FK(type)f FN(is)h(replaced)d(by)h FJ(string.join\(string.split\(type\() p FK(obj)p FJ(\).)o(__nam)o(e__,)44 b('_-)208 1766 y('\)\))p FN(.)h(Dispatch)27 b(to)g(these)g(methods)f(is)i(handled)d(by)i FJ(repr1\(\))p FN(.)45 b(T)-7 b(ype-speci\002c)26 b(methods)f(which)i (need)f(to)h(recursi)n(v)o(ely)208 1866 y(format)19 b(a)h(v)n(alue)g (should)f(call)i(`)p FJ(self.repr1\()p FK(subobj)p FJ(,)45 b FK(le)o(vel)50 b FJ(-)f(1\))p FN('.)0 2151 y Fv(5.19.2)101 b(Subclassing)29 b(Repr)g(Objects)0 2354 y FN(The)18 b(use)h(of)g(dynamic)e(dispatching)g(by)h FJ(Repr.repr1\(\))f FN(allo)n(ws)i(subclasses)g(of)f FJ(Repr)h FN(to)f(add)h(support)e(for) h(additional)f(b)n(uilt-in)0 2453 y(object)24 b(types)g(or)g(to)h (modify)e(the)h(handling)f(of)h(types)g(already)f(supported.)36 b(This)24 b(e)o(xample)f(sho)n(ws)i(ho)n(w)f(special)g(support)f(for)h (\002le)0 2553 y(objects)c(could)f(be)h(added:)236 2791 y FA(import)44 b(repr)236 2883 y(import)g(sys)236 3065 y(class)g(MyRepr\(repr.Repr\):)416 3157 y(def)g(repr_file\(self,)e (obj,)i(level\):)595 3248 y(if)g(obj.name)g(in)g(['',)f ('',)g('']:)774 3339 y(return)h(obj.name)595 3431 y(else:)774 3522 y(return)g(`obj`)236 3705 y(aRepr)g(=)h (MyRepr\(\))236 3796 y(print)f(aRepr.repr\(sys.stdin\))445 b(#)45 b(prints)e('')p 0 5549 3901 4 v 0 5649 a FI(148)2908 b(Chapter)24 b(5.)51 b(Data)24 b(T)-10 b(ypes)p eop end %%Page: 149 161 TeXDict begin 149 160 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3707 427 y FG(SIX)p 0 515 V 603 978 a FT(Numer)s(ic)57 b(and)g(Mathematical) g(Modules)0 1457 y FN(The)27 b(modules)f(described)h(in)g(this)h (chapter)e(pro)o(vide)g(numeric)g(and)h(math-related)e(functions)h(and) h(data)g(types.)47 b(The)27 b FJ(math)g FN(and)0 1556 y FJ(cmath)20 b FN(contain)g(v)n(arious)g(mathematical)g(functions)f (for)h(\003oating-point)e(and)j(comple)o(x)e(numbers.)25 b(F)o(or)20 b(users)h(more)f(interested)g(in)0 1656 y(decimal)g (accurac)o(y)e(than)i(in)g(speed,)g(the)g FJ(decimal)f FN(module)g(supports)g(e)o(xact)h(representations)e(of)i(decimal)g (numbers.)0 1803 y(The)g(follo)n(wing)e(modules)i(are)g(documented)d (in)k(this)f(chapter:)50 1946 y FD(math)348 b FN(Mathematical)19 b(functions)g(\()p FJ(sin\(\))g FN(etc.\).)50 2046 y FD(cmath)298 b FN(Mathematical)19 b(functions)g(for)g(comple)o(x)g (numbers.)50 2145 y FD(decimal)198 b FN(Implementation)17 b(of)j(the)g(General)g(Decimal)g(Arithmetic)f(Speci\002cation.)50 2245 y FD(random)248 b FN(Generate)19 b(pseudo-random)d(numbers)j(with) h(v)n(arious)g(common)e(distrib)n(utions.)50 2345 y FD(itertools)98 b FN(Functions)19 b(creating)g(iterators)h(for)g(ef)n(\002cient)f (looping.)50 2444 y FD(functools)98 b FN(Higher)n(-order)17 b(functions)i(and)h(operations)e(on)i(callable)g(objects.)50 2544 y FD(operator)148 b FN(All)21 b(Python')-5 b(s)19 b(standard)g(operators)g(as)i(b)n(uilt-in)e(functions.)0 2844 y FE(6.1)121 b Fx(math)32 b FE(\227)h(Mathematical)h(functions)0 3077 y FN(This)20 b(module)f(is)i(al)o(w)o(ays)g(a)n(v)n(ailable.)j(It) d(pro)o(vides)d(access)j(to)f(the)h(mathematical)e(functions)g (de\002ned)g(by)g(the)i(C)g(standard.)0 3224 y(These)g(functions)f (cannot)h(be)g(used)g(with)h(comple)o(x)d(numbers;)i(use)h(the)f (functions)f(of)h(the)h(same)f(name)g(from)f(the)i FJ(cmath)f FN(module)0 3323 y(if)h(you)f(require)g(support)f(for)h(comple)o(x)f (numbers.)29 b(The)21 b(distinction)g(between)g(functions)g(which)g (support)g(comple)o(x)f(numbers)g(and)0 3423 y(those)g(which)g(don')o (t)e(is)j(made)f(since)h(most)f(users)g(do)g(not)g(w)o(ant)g(to)h (learn)e(quite)h(as)h(much)e(mathematics)h(as)h(required)d(to)j (understand)0 3523 y(comple)o(x)28 b(numbers.)54 b(Recei)n(ving)29 b(an)h(e)o(xception)e(instead)i(of)g(a)g(comple)o(x)f(result)h(allo)n (ws)g(earlier)g(detection)f(of)h(the)g(une)o(xpected)0 3622 y(comple)o(x)18 b(number)f(used)j(as)g(a)g(parameter)m(,)d(so)j (that)g(the)f(programmer)e(can)i(determine)f(ho)n(w)h(and)g(why)f(it)j (w)o(as)f(generated)e(in)h(the)h(\002rst)0 3722 y(place.)0 3869 y(The)25 b(follo)n(wing)f(functions)f(are)j(pro)o(vided)c(by)j (this)h(module.)39 b(Except)24 b(when)h(e)o(xplicitly)f(noted)g (otherwise,)i(all)g(return)e(v)n(alues)h(are)0 3968 y(\003oats.)0 4115 y(Number)n(-theoretic)17 b(and)j(representation)e(functions:)0 4262 y FD(ceil)p FJ(\()p FK(x)p FJ(\))208 4362 y FN(Return)h(the)i (ceiling)e(of)h FK(x)h FN(as)g(a)g(\003oat,)f(the)g(smallest)h(inte)o (ger)e(v)n(alue)g(greater)h(than)f(or)h(equal)g(to)g FK(x)p FN(.)0 4509 y FD(fabs)p FJ(\()p FK(x)p FJ(\))208 4608 y FN(Return)f(the)i(absolute)e(v)n(alue)g(of)h FK(x)p FN(.)0 4755 y FD(floor)p FJ(\()p FK(x)p FJ(\))208 4855 y FN(Return)f(the)i(\003oor)e(of)h FK(x)h FN(as)g(a)f(\003oat,)h(the)f (lar)o(gest)f(inte)o(ger)g(v)n(alue)h(less)h(than)f(or)g(equal)f(to)i FK(x)p FN(.)0 5001 y FD(fmod)p FJ(\()p FK(x,)e(y)p FJ(\))208 5101 y FN(Return)25 b FJ(fmod\()p FK(x)p FJ(,)49 b FK(y)p FJ(\))p FN(,)28 b(as)f(de\002ned)e(by)h(the)g(platform)f(C)i(library)-5 b(.)42 b(Note)26 b(that)h(the)f(Python)f(e)o(xpression)g FK(x)50 b FJ(\045)f FK(y)27 b FN(may)f(not)208 5201 y(return)19 b(the)h(same)g(result.)26 b(The)20 b(intent)g(of)g(the)g(C)h(standard)e (is)i(that)g FJ(fmod\()p FK(x)p FJ(,)49 b FK(y)p FJ(\))20 b FN(be)g(e)o(xactly)g(\(mathematically;)e(to)j(in\002nite)208 5300 y(precision\))g(equal)i(to)g FK(x)50 b FJ(-)g FK(n)1084 5315 y FJ(*)1134 5300 y FK(y)22 b FN(for)h(some)g(inte)o(ger)f FK(n)h FN(such)g(that)g(the)g(result)g(has)h(the)f(same)g(sign)g(as)h FK(x)g FN(and)e(magnitude)f(less)208 5400 y(than)c FJ(abs\()p FK(y)p FJ(\))p FN(.)24 b(Python')-5 b(s)17 b FK(x)50 b FJ(\045)f FK(y)19 b FN(returns)e(a)h(result)g(with)g(the)g(sign)g(of) f FK(y)h FN(instead,)g(and)g(may)f(not)h(be)f(e)o(xactly)g(computable)f (for)p 0 5549 3901 4 v 3762 5649 a FI(149)p eop end %%Page: 150 162 TeXDict begin 150 161 bop 208 83 a FN(\003oat)19 b(ar)o(guments.)k(F)o (or)c(e)o(xample,)f FJ(fmod\(-1e-100,)47 b(1e100\))19 b FN(is)h FJ(-1e-100)p FN(,)f(b)n(ut)g(the)g(result)h(of)f(Python')-5 b(s)18 b FJ(-1e-100)208 183 y(\045)49 b(1e100)28 b FN(is)g FJ(1e100-1e-100)p FN(,)g(which)f(cannot)g(be)g(represented)f(e)o (xactly)h(as)h(a)g(\003oat,)i(and)d(rounds)f(to)i(the)g(surprising)208 282 y FJ(1e100)p FN(.)37 b(F)o(or)24 b(this)h(reason,)g(function)d FJ(fmod\(\))i FN(is)i(generally)d(preferred)f(when)i(w)o(orking)f(with) h(\003oats,)i(while)e(Python')-5 b(s)24 b FK(x)208 382 y FJ(\045)49 b FK(y)21 b FN(is)g(preferred)d(when)h(w)o(orking)g(with)h (inte)o(gers.)0 529 y FD(frexp)p FJ(\()p FK(x)p FJ(\))208 628 y FN(Return)i(the)i(mantissa)f(and)g(e)o(xponent)e(of)i FK(x)h FN(as)g(the)f(pair)g FJ(\()p FK(m)p FJ(,)49 b FK(e)p FJ(\))p FN(.)35 b FK(m)24 b FN(is)g(a)g(\003oat)f(and)g FK(e)h FN(is)g(an)f(inte)o(ger)f(such)h(that)h FK(x)50 b FJ(==)f FK(m)208 743 y FJ(*)307 728 y(2)357 743 y(**)457 728 y FK(e)25 b FN(e)o(xactly)-5 b(.)38 b(If)25 b FK(x)h FN(is)g(zero,)g(returns)e FJ(\(0.0,)49 b(0\))p FN(,)26 b(otherwise)f FJ(0.5)49 b(<=)g(abs\()p FK(m)p FJ(\))g(<)h(1)p FN(.)40 b(This)25 b(is)h(used)f(to)g(\224pick)208 828 y(apart\224)19 b(the)h(internal)g(representation)e(of)i(a)g(\003oat)h (in)f(a)h(portable)d(w)o(ay)-5 b(.)0 975 y FD(ldexp)p FJ(\()p FK(x,)19 b(i)p FJ(\))208 1074 y FN(Return)g FK(x)541 1089 y FJ(*)641 1074 y(\(2)741 1089 y(**)841 1074 y FK(i)p FJ(\))p FN(.)24 b(This)d(is)g(essentially)f(the)g(in)m(v)o(erse)f(of)h (function)f FJ(frexp\(\))p FN(.)0 1221 y FD(modf)p FJ(\()p FK(x)p FJ(\))208 1321 y FN(Return)g(the)i(fractional)d(and)i(inte)o (ger)f(parts)h(of)g FK(x)p FN(.)26 b(Both)20 b(results)h(carry)e(the)h (sign)g(of)g FK(x)p FN(,)h(and)e(both)h(are)g(\003oats.)0 1468 y(Note)30 b(that)g FJ(frexp\(\))g FN(and)g FJ(modf\(\))f FN(ha)n(v)o(e)h(a)h(dif)n(ferent)d(call/return)h(pattern)g(than)h (their)g(C)h(equi)n(v)n(alents:)44 b(the)o(y)30 b(tak)o(e)g(a)h(single) 0 1567 y(ar)o(gument)25 b(and)h(return)g(a)h(pair)f(of)h(v)n(alues,)h (rather)e(than)g(returning)f(their)i(second)f(return)f(v)n(alue)i (through)d(an)j(`output)e(parameter')0 1667 y(\(there)19 b(is)i(no)f(such)g(thing)g(in)g(Python\).)0 1814 y(F)o(or)k(the)g FJ(ceil\(\))p FN(,)h FJ(floor\(\))p FN(,)g(and)f FJ(modf\(\))f FN(functions,)h(note)g(that)h FK(all)f FN(\003oating-point)e(numbers)h (of)h(suf)n(\002ciently)g(lar)o(ge)f(mag-)0 1913 y(nitude)f(are)g(e)o (xact)g(inte)o(gers.)32 b(Python)21 b(\003oats)i(typically)f(carry)g (no)g(more)g(than)g(53)g(bits)h(of)g(precision)e(\(the)i(same)g(as)g (the)g(platform)e(C)0 2013 y(double)e(type\),)g(in)h(which)g(case)g(an) o(y)g(\003oat)g FK(x)h FN(with)f FJ(abs\()p FK(x)p FJ(\))49 b(>=)h(2)2001 2028 y(**)2101 2013 y(52)20 b FN(necessarily)f(has)i(no)f (fractional)e(bits.)0 2160 y(Po)n(wer)i(and)f(logarithmic)g(functions:) 0 2307 y FD(exp)p FJ(\()p FK(x)p FJ(\))208 2406 y FN(Return)g FJ(e)504 2421 y(**)604 2406 y FK(x)p FN(.)0 2553 y FD(log)p FJ(\()p FK(x)p FC([)p FK(,)h(base)12 b FC(])p FJ(\))208 2653 y FN(Return)18 b(the)i(logarithm)d(of)i FK(x)h FN(to)f(the)h(gi)n (v)o(en)e FK(base)p FN(.)24 b(If)19 b(the)h FK(base)f FN(is)h(not)f(speci\002ed,)g(return)f(the)h(natural)g(logarithm)e(of)i FK(x)h FN(\(that)f(is,)208 2752 y(the)h(logarithm)e(to)i(base)h FK(e)p FN(\).)50 b(Changed)19 b(in)i(v)o(ersion)e(2.3:)g FK(base)h FN(ar)o(gument)e(added.)0 2899 y FD(log10)p FJ(\()p FK(x)p FJ(\))208 2999 y FN(Return)h(the)i(base-10)d(logarithm)h (of)h FK(x)p FN(.)0 3146 y FD(pow)p FJ(\()p FK(x,)g(y)p FJ(\))208 3245 y FN(Return)f FK(x)491 3260 y FJ(**)591 3245 y FK(y)p FN(.)0 3392 y FD(sqrt)p FJ(\()p FK(x)p FJ(\))208 3492 y FN(Return)g(the)i(square)e(root)g(of)h FK(x)p FN(.)0 3639 y(T)m(rigonometric)d(functions:)0 3786 y FD(acos)p FJ(\()p FK(x)p FJ(\))208 3885 y FN(Return)i(the)i(arc) f(cosine)f(of)h FK(x)p FN(,)h(in)f(radians.)0 4032 y FD(asin)p FJ(\()p FK(x)p FJ(\))208 4132 y FN(Return)f(the)i(arc)f(sine) g(of)g FK(x)p FN(,)h(in)f(radians.)0 4279 y FD(atan)p FJ(\()p FK(x)p FJ(\))208 4378 y FN(Return)f(the)i(arc)f(tangent)f(of)h FK(x)p FN(,)g(in)h(radians.)0 4525 y FD(atan2)p FJ(\()p FK(y)-5 b(,)20 b(x)p FJ(\))208 4625 y FN(Return)d FJ(atan\()p FK(y)48 b FJ(/)i FK(x)p FJ(\))p FN(,)18 b(in)g(radians.)23 b(The)17 b(result)h(is)g(between)f FJ(-pi)g FN(and)g FJ(pi)p FN(.)24 b(The)17 b(v)o(ector)f(in)i(the)f(plane)g(from)g(the)g (origin)f(to)208 4724 y(point)j FJ(\()p FK(x)p FJ(,)50 b FK(y)p FJ(\))20 b FN(mak)o(es)h(this)g(angle)e(with)i(the)f(positi)n (v)o(e)g(X)h(axis.)26 b(The)20 b(point)g(of)g FJ(atan2\(\))f FN(is)j(that)e(the)h(signs)f(of)g(both)g(inputs)208 4824 y(are)i(kno)n(wn)g(to)h(it,)h(so)f(it)h(can)e(compute)g(the)h(correct)e (quadrant)g(for)i(the)f(angle.)33 b(F)o(or)22 b(e)o(xample,)g FJ(atan\(1)p FN(\))g(and)g FJ(atan2\(1,)208 4924 y(1\))e FN(are)g(both)f FJ(pi/4)p FN(,)h(b)n(ut)g FJ(atan2\(-1,)49 b(-1\))20 b FN(is)h FJ(-3)1829 4939 y(*)1879 4924 y(pi/4)p FN(.)0 5070 y FD(cos)p FJ(\()p FK(x)p FJ(\))208 5170 y FN(Return)e(the)i(cosine)e(of)h FK(x)h FN(radians.)0 5317 y FD(hypot)p FJ(\()p FK(x,)e(y)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(150)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 151 163 TeXDict begin 151 162 bop 208 83 a FN(Return)21 b(the)i(Euclidean)e (norm,)g FJ(sqrt\()p FK(x)1442 98 y FJ(*)1492 83 y FK(x)49 b FJ(+)h FK(y)1715 98 y FJ(*)1765 83 y FK(y)p FJ(\))p FN(.)31 b(This)22 b(is)h(the)g(length)e(of)h(the)g(v)o(ector)g(from)f (the)h(origin)f(to)i(point)e FJ(\()p FK(x)p FJ(,)208 183 y FK(y)p FJ(\))p FN(.)0 330 y FD(sin)p FJ(\()p FK(x)p FJ(\))208 429 y FN(Return)e(the)i(sine)f(of)g FK(x)h FN(radians.)0 576 y FD(tan)p FJ(\()p FK(x)p FJ(\))208 676 y FN(Return)e(the)i(tangent)e(of)h FK(x)g FN(radians.)0 823 y(Angular)f(con)m(v)o(ersion:)0 969 y FD(degrees)p FJ(\()p FK(x)p FJ(\))208 1069 y FN(Con)m(v)o(erts)g(angle)g FK(x)i FN(from)e(radians)h(to)g(de)o(grees.)0 1216 y FD(radians)p FJ(\()p FK(x)p FJ(\))208 1316 y FN(Con)m(v)o(erts)f(angle) g FK(x)i FN(from)e(de)o(grees)g(to)i(radians.)0 1462 y(Hyperbolic)d(functions:)0 1609 y FD(cosh)p FJ(\()p FK(x)p FJ(\))208 1709 y FN(Return)h(the)i(hyperbolic)c(cosine)j(of)g FK(x)p FN(.)0 1856 y FD(sinh)p FJ(\()p FK(x)p FJ(\))208 1955 y FN(Return)f(the)i(hyperbolic)c(sine)j(of)g FK(x)p FN(.)0 2102 y FD(tanh)p FJ(\()p FK(x)p FJ(\))208 2202 y FN(Return)f(the)i(hyperbolic)c(tangent)i(of)h FK(x)p FN(.)0 2349 y(The)g(module)f(also)h(de\002nes)g(tw)o(o)h(mathematical)e (constants:)0 2496 y FD(pi)208 2595 y FN(The)g(mathematical)g(constant) h FK(pi)p FN(.)0 2742 y FD(e)208 2842 y FN(The)f(mathematical)g (constant)h FK(e)p FN(.)0 2989 y FL(Note:)26 b FN(The)21 b FJ(math)g FN(module)e(consists)j(mostly)e(of)h(thin)g(wrappers)f (around)f(the)i(platform)f(C)i(math)e(library)g(functions.)26 b(Beha)n(vior)20 b(in)0 3088 y(e)o(xceptional)15 b(cases)j(is)f (loosely)g(speci\002ed)f(by)h(the)g(C)h(standards,)e(and)h(Python)e (inherits)i(much)f(of)h(its)g(math-function)d(error)n(-reporting)0 3188 y(beha)n(vior)27 b(from)h(the)g(platform)g(C)h(implementation.)48 b(As)30 b(a)f(result,)i(the)d(speci\002c)h(e)o(xceptions)e(raised)i(in) g(error)e(cases)j(\(and)e(e)n(v)o(en)0 3287 y(whether)19 b(some)g(ar)o(guments)f(are)i(considered)e(to)i(be)g(e)o(xceptional)e (at)i(all\))g(are)g(not)f(de\002ned)g(in)h(an)o(y)f(useful)h (cross-platform)d(or)j(cross-)0 3387 y(release)d(w)o(ay)-5 b(.)24 b(F)o(or)16 b(e)o(xample,)h(whether)f FJ(math.log\(0\))f FN(returns)h FJ(-Inf)h FN(or)g(raises)h FJ(ValueError)e FN(or)h FJ(OverflowError)e FN(isn')o(t)0 3487 y(de\002ned,)24 b(and)f(in)h(cases)h(where)e FJ(math.log\(0\))g FN(raises)h FJ(OverflowError)p FN(,)f FJ(math.log\(0L\))f FN(may)i(raise)g FJ(ValueError)0 3586 y FN(instead.)0 3733 y FL(See)d(Also:)0 3880 y FN(Module)e FJ(cmath)h FN(\(section)f(6.2\):)208 3980 y(Comple)o(x)g(number)f(v)o(ersions)h(of)h(man)o(y)f(of)h(these)g (functions.)0 4307 y FE(6.2)121 b Fx(cmath)32 b FE(\227)g(Mathematical) i(functions)h(f)l(or)f(comple)l(x)g(n)o(umbers)0 4540 y FN(This)25 b(module)e(is)j(al)o(w)o(ays)f(a)n(v)n(ailable.)38 b(It)25 b(pro)o(vides)e(access)j(to)f(mathematical)e(functions)g(for)i (comple)o(x)e(numbers.)37 b(The)24 b(functions)0 4640 y(are:)0 4786 y FD(acos)p FJ(\()p FK(x)p FJ(\))208 4886 y FN(Return)k(the)h(arc)g(cosine)g(of)g FK(x)p FN(.)52 b(There)29 b(are)g(tw)o(o)g(branch)f(cuts:)43 b(One)29 b(e)o(xtends)f(right)h(from)f(1)h(along)f(the)h(real)h(axis)f(to)g FM(1)p FN(,)208 4986 y(continuous)18 b(from)h(belo)n(w)-5 b(.)24 b(The)c(other)f(e)o(xtends)g(left)i(from)e(-1)h(along)f(the)h (real)g(axis)h(to)f(-)p FM(1)p FN(,)g(continuous)e(from)i(abo)o(v)o(e.) 0 5133 y FD(acosh)p FJ(\()p FK(x)p FJ(\))208 5232 y FN(Return)h(the)g (hyperbolic)e(arc)j(cosine)f(of)g FK(x)p FN(.)30 b(There)21 b(is)h(one)f(branch)f(cut,)i(e)o(xtending)d(left)j(from)f(1)g(along)g (the)g(real)h(axis)g(to)g(-)p FM(1)p FN(,)208 5332 y(continuous)c(from) h(abo)o(v)o(e.)p 0 5549 3901 4 v 0 5649 a FI(6.2.)52 b FJ(cmath)22 b FI(\227)h(Mathematical)i(functions)e(f)n(or)g(comple)n (x)g(n)o(umbers)1552 b(151)p eop end %%Page: 152 164 TeXDict begin 152 163 bop 0 83 a FD(asin)p FJ(\()p FK(x)p FJ(\))208 183 y FN(Return)19 b(the)i(arc)f(sine)g(of)g FK(x)p FN(.)26 b(This)20 b(has)g(the)h(same)f(branch)f(cuts)h(as)h FJ(acos\(\))p FN(.)0 330 y FD(asinh)p FJ(\()p FK(x)p FJ(\))208 429 y FN(Return)31 b(the)i(hyperbolic)d(arc)i(sine)h(of)f FK(x)p FN(.)62 b(There)31 b(are)i(tw)o(o)f(branch)f(cuts,)36 b(e)o(xtending)30 b(left)j(from)e FM(\006)p FJ(1j)h FN(to)h FM(\006)p FN(-)p FM(1)p FJ(j)p FN(,)h(both)208 529 y(continuous)20 b(from)i(abo)o(v)o(e.)31 b(These)23 b(branch)e(cuts)i(should)f(be)h (considered)e(a)i(b)n(ug)f(to)h(be)g(corrected)e(in)i(a)g(future)f (release.)33 b(The)208 628 y(correct)24 b(branch)h(cuts)h(should)e(e)o (xtend)h(along)g(the)g(imaginary)f(axis,)k(one)d(from)g FJ(1j)g FN(up)h(to)g FM(1)p FJ(j)g FN(and)f(continuous)f(from)h(the)208 728 y(right,)19 b(and)h(one)f(from)g(-)p FJ(1j)h FN(do)n(wn)g(to)g(-)p FM(1)p FJ(j)g FN(and)g(continuous)e(from)h(the)h(left.)0 875 y FD(atan)p FJ(\()p FK(x)p FJ(\))208 975 y FN(Return)h(the)h(arc)g (tangent)f(of)g FK(x)p FN(.)31 b(There)21 b(are)h(tw)o(o)g(branch)f (cuts:)29 b(One)21 b(e)o(xtends)g(from)g FJ(1j)h FN(along)f(the)h (imaginary)e(axis)i(to)g FM(1)p FJ(j)p FN(,)208 1074 y(continuous)h(from)i(the)h(left.)41 b(The)26 b(other)e(e)o(xtends)h (from)g(-)p FJ(1j)g FN(along)g(the)h(imaginary)e(axis)i(to)f(-)p FM(1)p FJ(j)p FN(,)i(continuous)d(from)h(the)208 1174 y(left.)g(\(This)20 b(should)f(probably)f(be)i(changed)e(so)j(the)f (upper)f(cut)h(becomes)f(continuous)f(from)i(the)g(other)f(side.\))0 1321 y FD(atanh)p FJ(\()p FK(x)p FJ(\))208 1420 y FN(Return)24 b(the)h(hyperbolic)d(arc)j(tangent)f(of)g FK(x)p FN(.)40 b(There)24 b(are)h(tw)o(o)g(branch)f(cuts:)35 b(One)25 b(e)o(xtends)e(from)h(1)h(along)f(the)h(real)g(axis)g(to)208 1520 y FM(1)p FN(,)c(continuous)e(from)i(abo)o(v)o(e.)26 b(The)21 b(other)f(e)o(xtends)g(from)g(-1)h(along)g(the)g(real)g(axis)g (to)h(-)p FM(1)p FN(,)f(continuous)e(from)h(abo)o(v)o(e.)27 b(\(This)208 1620 y(should)19 b(probably)f(be)i(changed)e(so)j(the)f (right)f(cut)i(becomes)e(continuous)f(from)h(the)h(other)g(side.\))0 1766 y FD(cos)p FJ(\()p FK(x)p FJ(\))208 1866 y FN(Return)f(the)i (cosine)e(of)h FK(x)p FN(.)0 2013 y FD(cosh)p FJ(\()p FK(x)p FJ(\))208 2113 y FN(Return)f(the)i(hyperbolic)c(cosine)j(of)g FK(x)p FN(.)0 2259 y FD(exp)p FJ(\()p FK(x)p FJ(\))208 2359 y FN(Return)f(the)i(e)o(xponential)c(v)n(alue)j FJ(e)1232 2374 y(**)1332 2359 y FK(x)p FN(.)0 2506 y FD(log)p FJ(\()p FK(x)p FC([)p FK(,)g(base)12 b FC(])p FJ(\))208 2606 y FN(Returns)17 b(the)g(logarithm)f(of)h FK(x)h FN(to)g(the)f(gi)n(v)o(en)f FK(base)p FN(.)24 b(If)17 b(the)h FK(base)f FN(is)h(not)f(speci\002ed,)h(returns)e(the)i (natural)e(logarithm)g(of)h FK(x)p FN(.)24 b(There)208 2705 y(is)f(one)f(branch)e(cut,)j(from)e(0)i(along)e(the)i(ne)o(gati)n (v)o(e)d(real)i(axis)h(to)f(-)p FM(1)p FN(,)h(continuous)d(from)i(abo)o (v)o(e.)62 b(Changed)21 b(in)h(v)o(ersion)f(2.4:)208 2805 y FK(base)e FN(ar)o(gument)f(added.)0 2952 y FD(log10)p FJ(\()p FK(x)p FJ(\))208 3051 y FN(Return)h(the)i(base-10)d(logarithm)h (of)h FK(x)p FN(.)25 b(This)c(has)f(the)g(same)h(branch)d(cut)i(as)h FJ(log\(\))p FN(.)0 3198 y FD(sin)p FJ(\()p FK(x)p FJ(\))208 3298 y FN(Return)e(the)i(sine)f(of)g FK(x)p FN(.)0 3445 y FD(sinh)p FJ(\()p FK(x)p FJ(\))208 3544 y FN(Return)f(the)i (hyperbolic)c(sine)j(of)g FK(x)p FN(.)0 3691 y FD(sqrt)p FJ(\()p FK(x)p FJ(\))208 3791 y FN(Return)f(the)i(square)e(root)g(of)h FK(x)p FN(.)26 b(This)20 b(has)h(the)f(same)g(branch)f(cut)h(as)h FJ(log\(\))p FN(.)0 3938 y FD(tan)p FJ(\()p FK(x)p FJ(\))208 4037 y FN(Return)e(the)i(tangent)e(of)h FK(x)p FN(.)0 4184 y FD(tanh)p FJ(\()p FK(x)p FJ(\))208 4284 y FN(Return)f(the)i (hyperbolic)c(tangent)i(of)h FK(x)p FN(.)0 4431 y(The)g(module)f(also)h (de\002nes)g(tw)o(o)h(mathematical)e(constants:)0 4577 y FD(pi)208 4677 y FN(The)g(mathematical)g(constant)h FK(pi)p FN(,)g(as)h(a)g(real.)0 4824 y FD(e)208 4924 y FN(The)e(mathematical)g(constant)h FK(e)p FN(,)g(as)h(a)g(real.)0 5070 y(Note)j(that)g(the)g(selection)g(of)f(functions)g(is)i(similar)m (,)f(b)n(ut)g(not)g(identical,)g(to)g(that)g(in)h(module)d FJ(math)p FN(.)36 b(The)24 b(reason)f(for)g(ha)n(ving)g(tw)o(o)0 5170 y(modules)f(is)i(that)g(some)f(users)g(aren')o(t)f(interested)g (in)i(comple)o(x)d(numbers,)h(and)h(perhaps)f(don')o(t)g(e)n(v)o(en)g (kno)n(w)g(what)h(the)o(y)g(are.)34 b(The)o(y)0 5270 y(w)o(ould)22 b(rather)f(ha)n(v)o(e)h FJ(math.sqrt\(-1\))e FN(raise)j(an)f(e)o(xception)e(than)i(return)f(a)i(comple)o(x)d(number) -5 b(.)30 b(Also)23 b(note)e(that)i(the)f(functions)0 5369 y(de\002ned)g(in)i FJ(cmath)f FN(al)o(w)o(ays)h(return)f(a)h (comple)o(x)d(number)m(,)h(e)n(v)o(en)h(if)h(the)f(answer)g(can)h(be)f (e)o(xpressed)f(as)j(a)f(real)f(number)f(\(in)h(which)p 0 5549 3901 4 v 0 5649 a FI(152)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 153 165 TeXDict begin 153 164 bop 0 83 a FN(case)21 b(the)f(comple)o(x)e (number)h(has)h(an)g(imaginary)f(part)g(of)h(zero\).)0 230 y(A)k(note)f(on)g(branch)f(cuts:)31 b(The)o(y)23 b(are)g(curv)o(es)f(along)h(which)g(the)g(gi)n(v)o(en)f(function)g(f)o (ails)i(to)f(be)h(continuous.)32 b(The)o(y)22 b(are)i(a)f(necessary)0 330 y(feature)30 b(of)g(man)o(y)f(comple)o(x)g(functions.)54 b(It)31 b(is)h(assumed)e(that)g(if)h(you)f(need)g(to)g(compute)f(with)i (comple)o(x)e(functions,)i(you)f(will)0 429 y(understand)18 b(about)h(branch)f(cuts.)25 b(Consult)20 b(almost)g(an)o(y)f(\(not)g (too)h(elementary\))e(book)g(on)i(comple)o(x)e(v)n(ariables)h(for)g (enlightenment.)0 529 y(F)o(or)g(information)e(of)i(the)h(proper)d (choice)i(of)g(branch)f(cuts)i(for)e(numerical)g(purposes,)g(a)i(good)e (reference)g(should)g(be)i(the)f(follo)n(wing:)0 676 y FL(See)i(Also:)0 823 y FN(Kahan,)i(W)m(:)h(Branch)e(cuts)h(for)g (comple)o(x)e(elementary)h(functions;)h(or)m(,)g(Much)f(ado)g(about)g (nothing')-5 b(s)22 b(sign)h(bit.)34 b(In)23 b(Iserles,)g(A.,)h(and)0 922 y(Po)n(well,)c(M.)g(\(eds.\),)g FK(The)g(state)g(of)h(the)f(art)h (in)f(numerical)f(analysis)p FN(.)25 b(Clarendon)19 b(Press)i(\(1987\)) d(pp165-211.)0 1246 y FE(6.3)121 b Fx(decimal)31 b FE(\227)i(Decimal)g (\003oating)h(point)h(ar)r(ithmetic)0 1479 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 1626 y(The)25 b FJ(decimal)g FN(module)g(pro)o(vides)f(support)g(for)h(decimal)g(\003oating)g(point) g(arithmetic.)41 b(It)26 b(of)n(fers)f(se)n(v)o(eral)g(adv)n(antages)f (o)o(v)o(er)h(the)0 1726 y FJ(float\(\))19 b FN(datatype:)125 1938 y FM(\017)41 b FN(Decimal)18 b(numbers)g(can)g(be)h(represented)e (e)o(xactly)-5 b(.)24 b(In)18 b(contrast,)h(numbers)e(lik)o(e)i FJ(1.1)g FN(do)g(not)f(ha)n(v)o(e)g(an)h(e)o(xact)g(representation)208 2038 y(in)j(binary)g(\003oating)g(point.)31 b(End)22 b(users)h(typically)f(w)o(ould)g(not)g(e)o(xpect)g FJ(1.1)h FN(to)f(display)h(as)g FJ(1.1000000000000001)d FN(as)208 2137 y(it)g(does)g(with)h(binary)e(\003oating)g(point.)125 2296 y FM(\017)41 b FN(The)16 b(e)o(xactness)h(carries)g(o)o(v)o(er)f (into)h(arithmetic.)23 b(In)17 b(decimal)g(\003oating)f(point,)h(`)p FJ(0.1)49 b(+)h(0.1)f(+)h(0.1)f(-)g(0.3)p FN(')17 b(is)h(e)o(xactly)208 2396 y(equal)29 b(to)g(zero.)53 b(In)30 b(binary)e(\003oating)h(point,) i(result)f(is)g FJ(5.5511151231257827e-017)p FN(.)50 b(While)30 b(near)f(to)h(zero,)i(the)208 2496 y(dif)n(ferences)20 b(pre)n(v)o(ent)g(reliable)h(equality)g(testing)h(and)f(dif)n(ferences) f(can)i(accumulate.)28 b(F)o(or)22 b(this)g(reason,)f(decimal)h(w)o (ould)f(be)208 2595 y(preferred)d(in)i(accounting)e(applications)h (which)h(ha)n(v)o(e)f(strict)i(equality)e(in)m(v)n(ariants.)125 2754 y FM(\017)41 b FN(The)20 b(decimal)g(module)f(incorporates)g(a)i (notion)e(of)h(signi\002cant)h(places)f(so)h(that)g(`)p FJ(1.30)49 b(+)g(1.20)p FN(')20 b(is)i FJ(2.50)p FN(.)k(The)20 b(trailing)208 2854 y(zero)f(is)h(k)o(ept)g(to)f(indicate)h (signi\002cance.)j(This)d(is)h(the)f(customary)e(presentation)g(for)h (monetary)e(applications.)24 b(F)o(or)19 b(multipli-)208 2954 y(cation,)j(the)g(\223schoolbook\224)e(approach)g(uses)j(all)g (the)f(\002gures)g(in)h(the)f(multiplicands.)30 b(F)o(or)22 b(instance,)g(`)p FJ(1.3)3428 2969 y(*)3528 2954 y(1.2)p FN(')g(gi)n(v)o(es)208 3053 y FJ(1.56)e FN(while)g(`)p FJ(1.30)910 3068 y(*)1009 3053 y(1.20)p FN(')g(gi)n(v)o(es)f FJ(1.5600)p FN(.)125 3212 y FM(\017)41 b FN(Unlik)o(e)20 b(hardw)o(are)g(based)g(binary)g(\003oating)g(point,)g(the)h(decimal)g (module)e(has)j(a)f(user)g(settable)g(precision)f(\(def)o(aulting)f(to) i(28)208 3312 y(places\))e(which)h(can)g(be)g(as)h(lar)o(ge)e(as)i (needed)e(for)h(a)g(gi)n(v)o(en)f(problem:)444 3441 y FA(>>>)44 b(getcontext\(\).prec)e(=)j(6)444 3533 y(>>>)f(Decimal\(1\))f (/)i(Decimal\(7\))444 3624 y(Decimal\("0.142857"\))444 3715 y(>>>)f(getcontext\(\).prec)e(=)j(28)444 3806 y(>>>)f (Decimal\(1\))f(/)i(Decimal\(7\))444 3898 y (Decimal\("0.142857142857142857142857142)o(9"\))125 4196 y FM(\017)c FN(Both)28 b(binary)f(and)h(decimal)f(\003oating)h(point)f (are)i(implemented)d(in)j(terms)f(of)g(published)f(standards.)48 b(While)29 b(the)f(b)n(uilt-in)208 4296 y(\003oat)19 b(type)g(e)o(xposes)g(only)g(a)h(modest)f(portion)f(of)h(its)i (capabilities,)e(the)h(decimal)f(module)f(e)o(xposes)h(all)h(required)e (parts)h(of)h(the)208 4396 y(standard.)j(When)d(needed,)f(the)h (programmer)d(has)k(full)f(control)f(o)o(v)o(er)g(rounding)e(and)j (signal)g(handling.)0 4608 y(The)g(module)f(design)g(is)i(centered)e (around)g(three)g(concepts:)25 b(the)20 b(decimal)f(number)m(,)f(the)i (conte)o(xt)f(for)h(arithmetic,)f(and)h(signals.)0 4755 y(A)i(decimal)e(number)f(is)j(immutable.)27 b(It)21 b(has)h(a)f(sign,)g (coef)n(\002cient)f(digits,)h(and)g(an)g(e)o(xponent.)k(T)-7 b(o)22 b(preserv)o(e)d(signi\002cance,)h(the)h(coef-)0 4855 y(\002cient)g(digits)h(do)f(not)g(truncate)f(trailing)h(zeroes.)28 b(Decimals)22 b(also)f(include)g(special)g(v)n(alues)g(such)g(as)h FJ(Infinity)p FN(,)f FJ(-Infinity)p FN(,)0 4954 y(and)f FJ(NaN)p FN(.)g(The)f(standard)g(also)i(dif)n(ferentiates)e FJ(-0)h FN(from)f FJ(+0)p FN(.)0 5101 y(The)e(conte)o(xt)g(for)g (arithmetic)f(is)j(an)e(en)m(vironment)e(specifying)h(precision,)h (rounding)e(rules,)j(limits)g(on)f(e)o(xponents,)f(\003ags)i (indicating)0 5201 y(the)30 b(results)h(of)f(operations,)h(and)e(trap)h (enablers)f(which)h(determine)f(whether)g(signals)h(are)h(treated)e(as) i(e)o(xceptions.)53 b(Rounding)0 5300 y(options)18 b(include)h FJ(ROUND_CEILING)p FN(,)e FJ(ROUND_DOWN)p FN(,)h FJ(ROUND_FLOOR)p FN(,)f FJ(ROUND_HALF_DOWN)p FN(,)g FJ(ROUND_HALF_EVEN)p FN(,)0 5400 y FJ(ROUND_HALF_UP)p FN(,)h(and)i FJ(ROUND_UP)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q(ithmetic)1917 b(153)p eop end %%Page: 154 166 TeXDict begin 154 165 bop 0 83 a FN(Signals)33 b(are)f(groups)f(of)i(e) o(xceptional)d(conditions)i(arising)g(during)f(the)h(course)g(of)h (computation.)60 b(Depending)30 b(on)i(the)h(needs)0 183 y(of)24 b(the)h(application,)f(signals)h(may)f(be)h(ignored,)f (considered)f(as)i(informational,)e(or)i(treated)f(as)h(e)o(xceptions.) 37 b(The)25 b(signals)g(in)g(the)0 282 y(decimal)16 b(module)g(are:)24 b FJ(Clamped)p FN(,)16 b FJ(InvalidOperation)p FN(,)f FJ(DivisionByZero)p FN(,)h FJ(Inexact)p FN(,)g FJ(Rounded)p FN(,)h FJ(Subnormal)p FN(,)0 382 y FJ(Overflow)p FN(,)i(and)h FJ(Underflow)p FN(.)0 529 y(F)o(or)g(each)h(signal)g(there)f(is)i(a)f (\003ag)g(and)f(a)i(trap)e(enabler)-5 b(.)26 b(When)21 b(a)g(signal)g(is)h(encountered,)c(its)k(\003ag)f(is)g(incremented)e (from)h(zero)g(and,)0 628 y(then,)25 b(if)f(the)g(trap)g(enabler)g(is)h (set)g(to)f(one,)h(an)f(e)o(xception)e(is)k(raised.)37 b(Flags)24 b(are)h(stick)o(y)-5 b(,)24 b(so)h(the)f(user)g(needs)g(to)g (reset)h(them)f(before)0 728 y(monitoring)18 b(a)i(calculation.)0 875 y FL(See)h(Also:)0 1022 y FN(IBM')-5 b(s)21 b(General)e(Decimal)i (Arithmetic)e(Speci\002cation,)g FK(The)h(Gener)o(al)g(Decimal)g (Arithmetic)g(Speci\002cation)p FN(.)0 1169 y(IEEE)g(standard)f (854-1987,)d FK(Unof)o(\002cial)j(IEEE)g(854)h(T)-8 b(e)n(xt)p FN(.)0 1454 y Fv(6.3.1)100 b(Quic)n(k-star)t(t)27 b(T)-12 b(utor)q(ial)0 1656 y FN(The)21 b(usual)h(start)g(to)f(using)g (decimals)h(is)g(importing)e(the)i(module,)e(vie)n(wing)g(the)i (current)e(conte)o(xt)h(with)g FJ(getcontext\(\))f FN(and,)h(if)0 1756 y(necessary)-5 b(,)19 b(setting)h(ne)n(w)g(v)n(alues)g(for)f (precision,)g(rounding,)f(or)h(enabled)g(traps:)236 1994 y FA(>>>)45 b(from)f(decimal)f(import)1312 2007 y(*)236 2086 y(>>>)i(getcontext\(\))236 2177 y(Context\(prec=28,)d (rounding=ROUND_HALF_EVEN,)f(Emin=-999999999,)h(Emax=999999999,)595 2268 y(capitals=1,)h(flags=[],)g(traps=[Overflow,)f(InvalidOperation,) 595 2360 y(DivisionByZero]\))236 2542 y(>>>)j(getcontext\(\).prec)d(=)i (7)314 b(#)45 b(Set)f(a)g(new)h(precision)0 2829 y FN(Decimal)31 b(instances)f(can)h(be)f(constructed)f(from)h(inte)o(gers,)i(strings,)h (or)d(tuples.)57 b(T)-7 b(o)30 b(create)h(a)g(Decimal)f(from)g(a)h FJ(float)p FN(,)i(\002rst)0 2928 y(con)m(v)o(ert)25 b(it)j(to)g(a)f (string.)46 b(This)28 b(serv)o(es)f(as)h(an)f(e)o(xplicit)f(reminder)g (of)h(the)g(details)h(of)f(the)g(con)m(v)o(ersion)e(\(including)g (representation)0 3028 y(error\).)k(Decimal)22 b(numbers)f(include)g (special)h(v)n(alues)g(such)g(as)g FJ(NaN)h FN(which)e(stands)h(for)g (\223Not)g(a)g(number\224,)f(positi)n(v)o(e)g(and)h(ne)o(gati)n(v)o(e)0 3128 y FJ(Infinity)p FN(,)d(and)h FJ(-0)p FN(.)236 3274 y FA(>>>)45 b(Decimal\(10\))236 3366 y(Decimal\("10"\))236 3457 y(>>>)g(Decimal\("3.14"\))236 3548 y(Decimal\("3.14"\))236 3640 y(>>>)g(Decimal\(\(0,)e(\(3,)h(1,)g(4\),)h(-2\)\))236 3731 y(Decimal\("3.14"\))236 3822 y(>>>)g(Decimal\(str\(2.0)1133 3835 y(**)1267 3822 y(0.5\)\))236 3914 y(Decimal\("1.41421356237"\))236 4005 y(>>>)g(Decimal\("NaN"\))236 4096 y(Decimal\("NaN"\))236 4188 y(>>>)g(Decimal\("-Infinity"\))236 4279 y(Decimal\("-Infinity"\))0 4566 y FN(The)18 b(signi\002cance)g(of)h(a)g(ne)n(w)g(Decimal)f(is)i (determined)d(solely)i(by)f(the)h(number)e(of)i(digits)f(input.)24 b(Conte)o(xt)18 b(precision)g(and)g(rounding)0 4665 y(only)h(come)h (into)g(play)g(during)e(arithmetic)i(operations.)p 0 5549 3901 4 v 0 5649 a FI(154)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 155 167 TeXDict begin 155 166 bop 236 83 a FA(>>>)45 b(getcontext\(\).prec)d(=) i(6)236 174 y(>>>)h(Decimal\('3.0'\))236 266 y(Decimal\("3.0"\))236 357 y(>>>)g(Decimal\('3.1415926535'\))236 448 y (Decimal\("3.1415926535"\))236 540 y(>>>)g(Decimal\('3.1415926535'\))c (+)j(Decimal\('2.7182818285'\))236 631 y(Decimal\("5.85987"\))236 722 y(>>>)h(getcontext\(\).rounding)c(=)k(ROUND_UP)236 814 y(>>>)g(Decimal\('3.1415926535'\))c(+)j(Decimal\('2.7182818285'\)) 236 905 y(Decimal\("5.85988"\))0 1191 y FN(Decimals)20 b(interact)g(well)h(with)f(much)f(of)h(the)g(rest)h(of)f(Python.)k (Here)c(is)h(a)g(small)f(decimal)g(\003oating)f(point)h(\003ying)f (circus:)236 1338 y FA(>>>)45 b(data)f(=)g(map\(Decimal,)f('1.34)h (1.87)g(3.45)g(2.35)h(1.00)f(0.03)g(9.25'.split\(\)\))236 1430 y(>>>)h(max\(data\))236 1521 y(Decimal\("9.25"\))236 1612 y(>>>)g(min\(data\))236 1704 y(Decimal\("0.03"\))236 1795 y(>>>)g(sorted\(data\))236 1886 y([Decimal\("0.03"\),)d (Decimal\("1.00"\),)g(Decimal\("1.34"\),)g(Decimal\("1.87"\),)281 1978 y(Decimal\("2.35"\),)g(Decimal\("3.45"\),)g(Decimal\("9.25"\)])236 2069 y(>>>)j(sum\(data\))236 2160 y(Decimal\("19.29"\))236 2252 y(>>>)g(a,b,c)f(=)g(data[:3])236 2343 y(>>>)h(str\(a\))236 2434 y('1.34')236 2526 y(>>>)g(float\(a\))236 2617 y (1.3400000000000001)236 2708 y(>>>)g(round\(a,)e(1\))224 b(#)45 b(round\(\))e(first)h(converts)g(to)g(binary)g(floating)f(point) 236 2800 y(1.3)236 2891 y(>>>)i(int\(a\))236 2982 y(1)236 3073 y(>>>)g(a)505 3086 y(*)595 3073 y(5)236 3165 y(Decimal\("6.70"\)) 236 3256 y(>>>)g(a)505 3269 y(*)595 3256 y(b)236 3347 y(Decimal\("2.5058"\))236 3439 y(>>>)g(c)f(\045)h(a)236 3530 y(Decimal\("0.77"\))0 3817 y FN(The)18 b FJ(quantize\(\))f FN(method)g(rounds)g(a)h(number)f(to)h(a)h(\002x)o(ed)e(e)o(xponent.)22 b(This)d(method)e(is)i(useful)e(for)h(monetary)e(applications)h(that)0 3916 y(often)i(round)g(results)h(to)h(a)f(\002x)o(ed)g(number)e(of)i (places:)236 4154 y FA(>>>)45 b (Decimal\('7.325'\).quantize\(Decimal\('.)o(01'\),)38 b(rounding=ROUND_DOWN\))236 4246 y(Decimal\("7.32"\))236 4337 y(>>>)45 b(Decimal\('7.325'\).quantize\(Decimal\('1)o(.'\),)39 b(rounding=ROUND_UP\))236 4428 y(Decimal\("8"\))0 4715 y FN(As)26 b(sho)n(wn)e(abo)o(v)o(e,)g(the)h FJ(getcontext\(\))e FN(function)h(accesses)h(the)g(current)f(conte)o(xt)g(and)g(allo)n(ws)h (the)g(settings)h(to)f(be)g(changed.)0 4815 y(This)20 b(approach)e(meets)j(the)f(needs)g(of)g(most)g(applications.)0 4961 y(F)o(or)25 b(more)g(adv)n(anced)f(w)o(ork,)i(it)g(may)f(be)h (useful)f(to)g(create)h(alternate)f(conte)o(xts)f(using)h(the)h(Conte)o (xt\(\))e(constructor)-5 b(.)40 b(T)-7 b(o)25 b(mak)o(e)h(an)0 5061 y(alternate)20 b(acti)n(v)o(e,)f(use)h(the)h FJ(setcontext\(\))d FN(function.)0 5208 y(In)f(accordance)e(with)i(the)g(standard,)f(the)h FJ(Decimal)f FN(module)g(pro)o(vides)f(tw)o(o)i(ready)f(to)h(use)g (standard)f(conte)o(xts,)g FJ(BasicContext)0 5308 y FN(and)k FJ(ExtendedContext)p FN(.)i(The)e(former)f(is)i(especially)f(useful)f (for)h(deb)n(ugging)e(because)h(man)o(y)g(of)h(the)g(traps)g(are)g (enabled:)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q(ithmetic)1917 b(155)p eop end %%Page: 156 168 TeXDict begin 156 167 bop 236 83 a FA(>>>)45 b(myothercontext)d(=)j (Context\(prec=60,)d(rounding=ROUND_HALF_DOWN\))236 174 y(>>>)j(setcontext\(myothercontext\))236 266 y(>>>)g(Decimal\(1\))e(/)h (Decimal\(7\))236 357 y(Decimal\("0.14285714285714285714285714285)o (714285)o(714285)o(714285)o(714285)o(714285)o(7"\))236 540 y(>>>)h(ExtendedContext)236 631 y(Context\(prec=9,)e (rounding=ROUND_HALF_EVEN,)d(Emin=-999999999,)i(Emax=999999999,)595 722 y(capitals=1,)h(flags=[],)g(traps=[]\))236 814 y(>>>)i (setcontext\(ExtendedContext\))236 905 y(>>>)g(Decimal\(1\))e(/)h (Decimal\(7\))236 996 y(Decimal\("0.142857143"\))236 1088 y(>>>)h(Decimal\(42\))e(/)h(Decimal\(0\))236 1179 y(Decimal\("Infinity"\))236 1362 y(>>>)h(setcontext\(BasicContext\))236 1453 y(>>>)g(Decimal\(42\))e(/)h(Decimal\(0\))236 1544 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 1636 y(File)f("",)e(line)i(1,)h(in)f(-toplevel-)416 1727 y(Decimal\(42\))f(/)h(Decimal\(0\))236 1818 y(DivisionByZero:)f(x) h(/)h(0)0 2105 y FN(Conte)o(xts)28 b(also)g(ha)n(v)o(e)g(signal)g (\003ags)g(for)g(monitoring)d(e)o(xceptional)h(conditions)h (encountered)e(during)i(computations.)46 b(The)28 b(\003ags)0 2204 y(remain)23 b(set)h(until)f(e)o(xplicitly)g(cleared,)g(so)h(it)g (is)g(best)g(to)g(clear)f(the)h(\003ags)g(before)e(each)h(set)h(of)f (monitored)f(computations)f(by)i(using)0 2304 y(the)d FJ(clear_flags\(\))f FN(method.)236 2542 y FA(>>>)45 b(setcontext\(ExtendedContext\))236 2633 y(>>>)g (getcontext\(\).clear_flags\(\))236 2725 y(>>>)g(Decimal\(355\))d(/)j (Decimal\(113\))236 2816 y(Decimal\("3.14159292"\))236 2907 y(>>>)g(getcontext\(\))236 2999 y(Context\(prec=9,)e (rounding=ROUND_HALF_EVEN,)d(Emin=-999999999,)i(Emax=999999999,)595 3090 y(capitals=1,)h(flags=[Inexact,)f(Rounded],)h(traps=[]\))0 3377 y FN(The)25 b FK(\003a)o(gs)g FN(entry)g(sho)n(ws)h(that)g(the)f (rational)g(approximation)d(to)k FJ(Pi)g FN(w)o(as)g(rounded)e (\(digits)h(be)o(yond)e(the)j(conte)o(xt)e(precision)h(were)0 3476 y(thro)n(wn)19 b(a)o(w)o(ay\))g(and)h(that)g(the)h(result)f(is)h (ine)o(xact)e(\(some)h(of)g(the)g(discarded)f(digits)h(were)g (non-zero\).)0 3623 y(Indi)n(vidual)e(traps)i(are)g(set)h(using)f(the)g (dictionary)f(in)h(the)g FJ(traps)g FN(\002eld)g(of)g(a)h(conte)o(xt:) 236 3861 y FA(>>>)45 b(Decimal\(1\))e(/)h(Decimal\(0\))236 3953 y(Decimal\("Infinity"\))236 4044 y(>>>)h (getcontext\(\).traps[DivisionByZero])39 b(=)44 b(1)236 4135 y(>>>)h(Decimal\(1\))e(/)h(Decimal\(0\))236 4227 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 4318 y(File)f("",)e(line)i(1,)h(in)f(-toplevel-)416 4409 y(Decimal\(1\))f(/)h(Decimal\(0\))236 4501 y(DivisionByZero:)f(x)h (/)h(0)0 4787 y FN(Most)28 b(programs)f(adjust)h(the)g(current)f(conte) o(xt)g(only)g(once,)j(at)e(the)h(be)o(ginning)c(of)j(the)g(program.)47 b(And,)30 b(in)e(man)o(y)f(applications,)0 4887 y(data)21 b(is)h(con)m(v)o(erted)d(to)i FJ(Decimal)f FN(with)i(a)f(single)g(cast) h(inside)f(a)h(loop.)27 b(W)m(ith)21 b(conte)o(xt)f(set)i(and)f (decimals)f(created,)h(the)g(b)n(ulk)g(of)g(the)0 4987 y(program)d(manipulates)h(the)h(data)g(no)g(dif)n(ferently)e(than)i (with)g(other)g(Python)f(numeric)f(types.)p 0 5549 3901 4 v 0 5649 a FI(156)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 157 169 TeXDict begin 157 168 bop 0 83 a Fv(6.3.2)100 b(Decimal)29 b(objects)0 281 y FL(class)21 b FD(Decimal)p FJ(\()p FC([)p FK(value)d FC([)p FK(,)i(conte)n(xt)13 b FC(])f(])p FJ(\))208 381 y FN(Constructs)19 b(a)i(ne)n(w)f FJ(Decimal)g FN(object)f(based)h(from)f FK(value)p FN(.)208 514 y FK(value)14 b FN(can)h(be)h(an)f(inte)o(ger)m(,)g(string,)g(tuple,)h (or)f(another)f FJ(Decimal)g FN(object.)23 b(If)15 b(no)g FK(value)g FN(is)h(gi)n(v)o(en,)f(returns)f FJ(Decimal\("0"\))p FN(.)208 613 y(If)20 b FK(value)f FN(is)i(a)g(string,)f(it)g(should)g (conform)e(to)i(the)g(decimal)g(numeric)f(string)h(syntax:)623 837 y FA(sign)493 b(::=)89 b('+')44 b(|)h('-')623 929 y(digit)448 b(::=)89 b('0')44 b(|)h('1')f(|)h('2')f(|)h('3')f(|)h('4')f (|)h('5')f(|)h('6')f(|)h('7')f(|)h('8')f(|)h('9')623 1020 y(indicator)268 b(::=)89 b('e')44 b(|)h('E')623 1111 y(digits)403 b(::=)89 b(digit)44 b([digit]...)623 1203 y(decimal-part)133 b(::=)89 b(digits)44 b('.')g([digits])f(|)i (['.'])f(digits)623 1294 y(exponent-part)88 b(::=)h(indicator)43 b([sign])h(digits)623 1385 y(infinity)313 b(::=)89 b('Infinity')43 b(|)i('Inf')623 1477 y(nan)538 b(::=)89 b('NaN')44 b([digits])f(|)i ('sNaN')f([digits])623 1568 y(numeric-value)88 b(::=)h(decimal-part)43 b([exponent-part])f(|)j(infinity)623 1659 y(numeric-string)e(::=)89 b([sign])44 b(numeric-value)e(|)j([sign])f(nan)208 1940 y FN(If)31 b FK(value)g FN(is)h(a)g FJ(tuple)p FN(,)i(it)e(should)f(ha) n(v)o(e)g(three)g(components,)h(a)g(sign)f(\()p FJ(0)h FN(for)f(positi)n(v)o(e)f(or)i FJ(1)f FN(for)g(ne)o(gati)n(v)o(e\),)h (a)g FJ(tuple)208 2040 y FN(of)44 b(digits,)50 b(and)44 b(an)h(inte)o(ger)e(e)o(xponent.)96 b(F)o(or)44 b(e)o(xample,)49 b(`)p FJ(Decimal\(\(0,)e(\(1,)i(4,)h(1,)f(4\),)g(-3\)\))p FN(')44 b(returns)208 2140 y FJ(Decimal\("1.414"\))p FN(.)208 2272 y(The)19 b FK(conte)n(xt)i FN(precision)d(does)h(not)h (af)n(fect)f(ho)n(w)g(man)o(y)f(digits)i(are)f(stored.)24 b(That)c(is)g(determined)e(e)o(xclusi)n(v)o(ely)g(by)h(the)g(number)208 2372 y(of)f(digits)g(in)h FK(value)p FN(.)24 b(F)o(or)18 b(e)o(xample,)f(`)p FJ(Decimal\("3.00000"\))p FN(')e(records)j(all)h (\002)n(v)o(e)f(zeroes)g(e)n(v)o(en)g(if)h(the)f(conte)o(xt)g (precision)208 2472 y(is)j(only)e(three.)208 2605 y(The)25 b(purpose)f(of)i(the)f FK(conte)n(xt)i FN(ar)o(gument)d(is)i (determining)e(what)h(to)h(do)g(if)g FK(value)f FN(is)h(a)h(malformed)c (string.)41 b(If)26 b(the)g(conte)o(xt)208 2704 y(traps)19 b FJ(InvalidOperation)p FN(,)e(an)j(e)o(xception)e(is)i(raised;)g (otherwise,)f(the)h(constructor)e(returns)g(a)j(ne)n(w)e(Decimal)h (with)g(the)208 2804 y(v)n(alue)f(of)h FJ(NaN)p FN(.)208 2937 y(Once)f(constructed,)g FJ(Decimal)g FN(objects)h(are)g (immutable.)0 3083 y(Decimal)k(\003oating)g(point)g(objects)g(share)g (man)o(y)g(properties)f(with)h(the)h(other)f(b)n(uiltin)g(numeric)f (types)h(such)h(as)g FJ(float)f FN(and)g FJ(int)p FN(.)0 3183 y(All)19 b(of)f(the)g(usual)g(math)g(operations)f(and)h(special)g (methods)f(apply)-5 b(.)23 b(Lik)o(e)n(wise,)18 b(decimal)g(objects)g (can)g(be)g(copied,)g(pickled,)f(printed,)0 3283 y(used)f(as)h (dictionary)d(k)o(e)o(ys,)i(used)g(as)h(set)g(elements,)g(compared,)d (sorted,)i(and)g(coerced)f(to)h(another)f(type)g(\(such)h(as)h FJ(float)e FN(or)h FJ(long)p FN(\).)0 3430 y(In)k(addition)f(to)h(the)h (standard)e(numeric)g(properties,)f(decimal)i(\003oating)g(point)f (objects)h(also)h(ha)n(v)o(e)e(a)i(number)e(of)h(specialized)f(meth-)0 3529 y(ods:)0 3676 y FD(adjusted)p FJ(\(\))208 3776 y FN(Return)29 b(the)g(adjusted)g(e)o(xponent)e(after)i(shifting)g(out)g (the)h(coef)n(\002cient')-5 b(s)29 b(rightmost)f(digits)i(until)f(only) g(the)g(lead)h(digit)f(re-)208 3875 y(mains:)g FJ (Decimal\("321e+5"\).adjusted\(\))18 b FN(returns)j(se)n(v)o(en.)31 b(Used)23 b(for)f(determining)e(the)i(position)g(of)g(the)h(most)208 3975 y(signi\002cant)c(digit)h(with)h(respect)f(to)g(the)g(decimal)g (point.)0 4122 y FD(as_tuple)p FJ(\(\))208 4221 y FN(Returns)g(a)g (tuple)g(representation)e(of)i(the)g(number:)k(`)p FJ(\(sign,)48 b(digittuple,)g(exponent\))p FN('.)0 4368 y FD(compare)p FJ(\()p FK(other)r FC([)p FK(,)18 b(conte)n(xt)13 b FC(])p FJ(\))208 4468 y FN(Compares)19 b(lik)o(e)h FJ(__cmp__\(\))f FN(b)n(ut)i(returns)e(a)i(decimal)e(instance:)802 4692 y FA(a)45 b(or)g(b)f(is)h(a)f(NaN)h(==>)f(Decimal\("NaN"\))802 4783 y(a)h(<)g(b)493 b(==>)44 b(Decimal\("-1"\))802 4875 y(a)h(==)g(b)448 b(==>)44 b(Decimal\("0"\))802 4966 y(a)h(>)g(b)493 b(==>)44 b(Decimal\("1"\))0 5284 y FD(max)p FJ(\()p FK(other)r FC([)p FK(,)19 b(conte)n(xt)13 b FC(])p FJ(\))208 5384 y FN(Lik)o(e)25 b(`)p FJ(max\(self,)48 b(other\))p FN(')24 b(e)o(xcept)h(that)h(the)f(conte)o(xt)f(rounding)f(rule)i(is)i(applied) d(before)h(returning)e(and)i(that)h FJ(NaN)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h (\003oating)g(point)g(ar)q(ithmetic)1917 b(157)p eop end %%Page: 158 170 TeXDict begin 158 169 bop 208 83 a FN(v)n(alues)19 b(are)h(either)g (signalled)g(or)g(ignored)e(\(depending)f(on)j(the)g(conte)o(xt)f(and)h (whether)f(the)o(y)h(are)g(signaling)f(or)h(quiet\).)0 230 y FD(min)p FJ(\()p FK(other)r FC([)p FK(,)f(conte)n(xt)13 b FC(])p FJ(\))208 330 y FN(Lik)o(e)25 b(`)p FJ(min\(self,)48 b(other\))p FN(')24 b(e)o(xcept)h(that)h(the)f(conte)o(xt)f(rounding)f (rule)i(is)i(applied)d(before)h(returning)e(and)i(that)h FJ(NaN)208 429 y FN(v)n(alues)19 b(are)h(either)g(signalled)g(or)g (ignored)e(\(depending)f(on)j(the)g(conte)o(xt)f(and)h(whether)f(the)o (y)h(are)g(signaling)f(or)h(quiet\).)0 576 y FD(normalize)p FJ(\()p FC([)p FK(conte)n(xt)13 b FC(])p FJ(\))208 676 y FN(Normalize)49 b(the)i(number)e(by)i(stripping)e(the)i(rightmost)f (trailing)g(zeroes)g(and)g(con)m(v)o(erting)e(an)o(y)i(result)h(equal)f (to)208 775 y FJ(Decimal\("0"\))28 b FN(to)h FJ(Decimal\("0e0"\))p FN(.)51 b(Used)30 b(for)f(producing)e(canonical)h(v)n(alues)i(for)f (members)f(of)i(an)f(equi)n(v)n(a-)208 875 y(lence)19 b(class.)26 b(F)o(or)20 b(e)o(xample,)f FJ(Decimal\("32.100"\))e FN(and)j FJ(Decimal\("0.321000e+2"\))c FN(both)k(normalize)e(to)j(the) 208 975 y(equi)n(v)n(alent)d(v)n(alue)i FJ(Decimal\("32.1"\))p FN(.)0 1121 y FD(quantize)p FJ(\()p FK(e)n(xp)f FC([)p FK(,)h(r)l(ounding)p FC([)p FK(,)e(conte)n(xt)q FC([)p FK(,)i(watc)o(he)n(xp)12 b FC(])g(])g(])p FJ(\))208 1221 y FN(Quantize)17 b(mak)o(es)i(the)f(e)o(xponent)e(the)j(same)g(as)g FK(e)n(xp)p FN(.)24 b(Searches)18 b(for)g(a)h(rounding)d(method)h(in)i FK(r)l(ounding)p FN(,)e(then)h(in)g FK(conte)n(xt)q FN(,)h(and)208 1321 y(then)g(in)i(the)f(current)f(conte)o(xt.)208 1453 y(If)24 b FK(watc)o(he)n(xp)f FN(is)i(set)g(\(def)o(ault\),)f(then)f (an)i(error)e(is)i(returned)d(whene)n(v)o(er)g(the)j(resulting)e(e)o (xponent)f(is)j(greater)e(than)h FJ(Emax)g FN(or)208 1553 y(less)d(than)f FJ(Etiny)p FN(.)0 1700 y FD(remainder_near)p FJ(\()p FK(other)r FC([)p FK(,)d(conte)n(xt)c FC(])p FJ(\))208 1800 y FN(Computes)29 b(the)h(modulo)e(as)j(either)f(a)g (positi)n(v)o(e)f(or)h(ne)o(gati)n(v)o(e)e(v)n(alue)h(depending)f(on)h (which)h(is)h(closest)f(to)g(zero.)54 b(F)o(or)30 b(in-)208 1899 y(stance,)i(`)p FJ(Decimal\(10\).remainder_near\(6\))p FN(')25 b(returns)k FJ(Decimal\("-2"\))f FN(which)i(is)h(closer)f(to)g (zero)g(than)208 1999 y FJ(Decimal\("4"\))p FN(.)208 2132 y(If)20 b(both)f(are)h(equally)f(close,)h(the)h(one)e(chosen)h (will)g(ha)n(v)o(e)g(the)g(same)h(sign)f(as)h FK(self)12 b FN(.)0 2279 y FD(same_quantum)p FJ(\()p FK(other)r FC([)p FK(,)17 b(conte)n(xt)c FC(])p FJ(\))208 2378 y FN(T)-6 b(est)20 b(whether)g(self)g(and)g(other)f(ha)n(v)o(e)h(the)g (same)g(e)o(xponent)e(or)i(whether)f(both)h(are)g FJ(NaN)p FN(.)0 2525 y FD(sqrt)p FJ(\()p FC([)p FK(conte)n(xt)13 b FC(])p FJ(\))208 2625 y FN(Return)19 b(the)i(square)e(root)g(to)i (full)f(precision.)0 2772 y FD(to_eng_string)p FJ(\()p FC([)p FK(conte)n(xt)13 b FC(])p FJ(\))208 2871 y FN(Con)m(v)o(ert)18 b(to)j(an)f(engineering-type)c(string.)208 3004 y(Engineering)23 b(notation)i(has)h(an)g(e)o(xponent)e(which)h(is)i(a)g(multiple)e(of)h (3,)h(so)f(there)g(are)g(up)g(to)g(3)g(digits)g(left)g(of)g(the)g (decimal)208 3104 y(place.)e(F)o(or)c(e)o(xample,)f(con)m(v)o(erts)f FJ(Decimal\('123E+1'\))g FN(to)i FJ(Decimal\("1.23E+3"\))0 3251 y FD(to_integral)p FJ(\()p FC([)p FK(r)l(ounding)p FC([)p FK(,)c(conte)n(xt)d FC(])f(])p FJ(\))208 3350 y FN(Rounds)19 b(to)i(the)g(nearest)f(inte)o(ger)g(without)g(signaling) f FJ(Inexact)h FN(or)h FJ(Rounded)p FN(.)k(If)c(gi)n(v)o(en,)e(applies) h FK(r)l(ounding)p FN(;)f(otherwise,)208 3450 y(uses)h(the)g(rounding)e (method)h(in)h(either)g(the)g(supplied)f FK(conte)n(xt)j FN(or)e(the)g(current)f(conte)o(xt.)0 3735 y Fv(6.3.3)100 b(Conte)m(xt)28 b(objects)0 3938 y FN(Conte)o(xts)22 b(are)g(en)m(vironments)d(for)j(arithmetic)f(operations.)29 b(The)o(y)21 b(go)o(v)o(ern)f(precision,)h(set)i(rules)f(for)g (rounding,)d(determine)i(which)0 4037 y(signals)f(are)h(treated)e(as)i (e)o(xceptions,)d(and)i(limit)h(the)f(range)f(for)h(e)o(xponents.)0 4184 y(Each)54 b(thread)f(has)i(its)g(o)n(wn)f(current)f(conte)o(xt)h (which)g(is)h(accessed)f(or)g(changed)f(using)h(the)g FJ(getcontext\(\))f FN(and)0 4284 y FJ(setcontext\(\))19 b FN(functions:)0 4431 y FD(getcontext)p FJ(\(\))208 4530 y FN(Return)g(the)i(current)d(conte)o(xt)h(for)h(the)g(acti)n(v)o (e)g(thread.)0 4677 y FD(setcontext)p FJ(\()p FK(c)p FJ(\))208 4777 y FN(Set)g(the)h(current)d(conte)o(xt)h(for)h(the)g (acti)n(v)o(e)g(thread)f(to)h FK(c)p FN(.)0 4924 y(Be)o(ginning)c(with) i(Python)f(2.5,)h(you)f(can)h(also)g(use)g(the)g FJ(with)g FN(statement)g(and)f(the)h FJ(localcontext\(\))e FN(function)g(to)j (temporarily)0 5023 y(change)g(the)h(acti)n(v)o(e)g(conte)o(xt.)0 5170 y FD(localcontext)p FJ(\()p FC([)p FK(c)12 b FC(])p FJ(\))208 5270 y FN(Return)25 b(a)i(conte)o(xt)e(manager)f(that)i(will) h(set)g(the)f(current)f(conte)o(xt)g(for)g(the)h(acti)n(v)o(e)g(thread) f(to)h(a)h(cop)o(y)e(of)h FK(c)g FN(on)g(entry)f(to)i(the)208 5369 y(with-statement)d(and)h(restore)g(the)h(pre)n(vious)e(conte)o(xt) g(when)h(e)o(xiting)g(the)h(with-statement.)40 b(If)26 b(no)f(conte)o(xt)f(is)j(speci\002ed,)f(a)p 0 5549 3901 4 v 0 5649 a FI(158)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 159 171 TeXDict begin 159 170 bop 208 83 a FN(cop)o(y)19 b(of)h(the)g(current)f (conte)o(xt)g(is)i(used.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)208 216 y(F)o(or)e(e)o(xample,)f(the)i(follo)n(wing)e(code)h(sets)h(the)g (current)e(decimal)h(precision)g(to)g(42)h(places,)f(performs)f(a)i (calculation,)f(and)g(then)208 315 y(automatically)h(restores)i(the)g (pre)n(vious)f(conte)o(xt:)623 540 y FA(from)44 b(__future__)f(import)h (with_statement)623 631 y(from)g(decimal)g(import)g(localcontext)623 814 y(with)g(localcontext\(\))f(as)h(ctx:)802 905 y(ctx.prec)g(=)h(42) 134 b(#)44 b(Perform)g(a)h(high)f(precision)f(calculation)802 996 y(s)i(=)g(calculate_something\(\))623 1088 y(s)g(=)f(+s)90 b(#)44 b(Round)g(the)h(final)f(result)g(back)g(to)g(the)h(default)e (precision)0 1291 y FN(Ne)n(w)22 b(conte)o(xts)f(can)h(also)g(be)g (created)f(using)g(the)h FJ(Context)f FN(constructor)f(described)h (belo)n(w)-5 b(.)29 b(In)21 b(addition,)g(the)h(module)e(pro)o(vides)0 1391 y(three)g(pre-made)e(conte)o(xts:)0 1538 y FL(class)j FD(BasicContext)208 1637 y FN(This)27 b(is)g(a)h(standard)d(conte)o(xt) h(de\002ned)g(by)g(the)h(General)f(Decimal)h(Arithmetic)f (Speci\002cation.)44 b(Precision)26 b(is)i(set)f(to)g(nine.)208 1737 y(Rounding)16 b(is)k(set)f(to)g FJ(ROUND_HALF_UP)p FN(.)e(All)i(\003ags)g(are)f(cleared.)24 b(All)19 b(traps)g(are)f (enabled)g(\(treated)g(as)h(e)o(xceptions\))e(e)o(xcept)208 1836 y FJ(Inexact)p FN(,)i FJ(Rounded)p FN(,)g(and)h FJ(Subnormal)p FN(.)208 1969 y(Because)g(man)o(y)f(of)h(the)g(traps)g (are)g(enabled,)f(this)i(conte)o(xt)e(is)i(useful)e(for)h(deb)n (ugging.)0 2116 y FL(class)h FD(ExtendedContext)208 2216 y FN(This)27 b(is)g(a)h(standard)d(conte)o(xt)h(de\002ned)g(by)g(the)h (General)f(Decimal)h(Arithmetic)f(Speci\002cation.)44 b(Precision)26 b(is)i(set)f(to)g(nine.)208 2315 y(Rounding)17 b(is)k(set)g(to)e FJ(ROUND_HALF_EVEN)p FN(.)f(All)i(\003ags)g(are)g (cleared.)k(No)c(traps)f(are)h(enabled)f(\(so)g(that)h(e)o(xceptions)e (are)i(not)208 2415 y(raised)g(during)e(computations\).)208 2548 y(Because)23 b(the)g(trapped)e(are)i(disabled,)g(this)h(conte)o (xt)d(is)j(useful)f(for)f(applications)g(that)h(prefer)f(to)h(ha)n(v)o (e)f(result)h(v)n(alue)g(of)g FJ(NaN)208 2648 y FN(or)i FJ(Infinity)g FN(instead)h(of)g(raising)f(e)o(xceptions.)41 b(This)26 b(allo)n(ws)h(an)e(application)g(to)h(complete)f(a)h(run)g (in)g(the)g(presence)f(of)208 2747 y(conditions)18 b(that)j(w)o(ould)e (otherwise)h(halt)g(the)g(program.)0 2894 y FL(class)h FD(DefaultContext)208 2994 y FN(This)26 b(conte)o(xt)g(is)i(used)e(by)h (the)f FJ(Context)g FN(constructor)f(as)j(a)f(prototype)d(for)i(ne)n(w) h(conte)o(xts.)44 b(Changing)25 b(a)i(\002eld)g(\(such)f(a)208 3093 y(precision\))18 b(has)j(the)f(ef)n(fect)g(of)f(changing)g(the)h (def)o(ault)f(for)h(ne)n(w)g(conte)o(xts)f(creating)g(by)h(the)g FJ(Context)g FN(constructor)-5 b(.)208 3226 y(This)17 b(conte)o(xt)f(is)i(most)f(useful)g(in)g(multi-threaded)e(en)m (vironments.)21 b(Changing)16 b(one)g(of)h(the)h(\002elds)f(before)f (threads)h(are)g(started)208 3326 y(has)g(the)h(ef)n(fect)f(of)g (setting)h(system-wide)f(def)o(aults.)23 b(Changing)16 b(the)i(\002elds)g(after)f(threads)g(ha)n(v)o(e)g(started)h(is)g(not)g (recommended)208 3425 y(as)i(it)h(w)o(ould)f(require)f(thread)g (synchronization)e(to)j(pre)n(v)o(ent)f(race)h(conditions.)208 3558 y(In)25 b(single)g(threaded)f(en)m(vironments,)g(it)j(is)f (preferable)e(to)i(not)f(use)h(this)g(conte)o(xt)e(at)i(all.)42 b(Instead,)26 b(simply)f(create)h(conte)o(xts)208 3658 y(e)o(xplicitly)19 b(as)i(described)e(belo)n(w)-5 b(.)208 3791 y(The)20 b(def)o(ault)g(v)n(alues)g(are)g(precision=28,)e (rounding=R)m(OUND)p 2085 3791 25 4 v 27 w(HALF)p 2329 3791 V 29 w(EVEN,)j(and)f(enabled)f(traps)h(for)g(Ov)o(er\003o)n(w)-5 b(,)19 b(In)m(v)n(ali-)208 3890 y(dOperation,)f(and)h(Di)n (visionByZero.)0 4037 y(In)h(addition)f(to)h(the)g(three)g(supplied)f (conte)o(xts,)g(ne)n(w)h(conte)o(xts)f(can)h(be)g(created)g(with)g(the) h FJ(Context)e FN(constructor)-5 b(.)0 4184 y FL(class)21 b FD(Context)p FJ(\()p FK(pr)m(ec=None)o(,)d(r)l(ounding=None)o(,)f(tr) o(aps=None)o(,)j(\003a)o(gs=None)o(,)f(Emin=None)o(,)g(Emax=None)o(,)g (capitals=1)p FJ(\))208 4284 y FN(Creates)41 b(a)g(ne)n(w)g(conte)o (xt.)86 b(If)40 b(a)i(\002eld)f(is)h(not)e(speci\002ed)h(or)f(is)i FJ(None)p FN(,)k(the)41 b(def)o(ault)f(v)n(alues)g(are)h(copied)f(from) g(the)208 4383 y FJ(DefaultContext)p FN(.)22 b(If)e(the)h FK(\003a)o(gs)e FN(\002eld)i(is)g(not)f(speci\002ed)g(or)g(is)h FJ(None)p FN(,)e(all)i(\003ags)g(are)f(cleared.)208 4516 y(The)f FK(pr)m(ec)i FN(\002eld)f(is)h(a)g(positi)n(v)o(e)e(inte)o(ger) g(that)h(sets)i(the)e(precision)f(for)h(arithmetic)f(operations)g(in)h (the)g(conte)o(xt.)208 4649 y(The)f FK(r)l(ounding)g FN(option)g(is)i(one)f(of:)349 4815 y FM(\017)o FJ(ROUND_CEILING)f FN(\(to)n(w)o(ards)g FJ(Infinity)p FN(\),)349 4948 y FM(\017)o FJ(ROUND_DOWN)g FN(\(to)n(w)o(ards)g(zero\),)349 5081 y FM(\017)o FJ(ROUND_FLOOR)g FN(\(to)n(w)o(ards)g FJ(-Infinity)p FN(\),)349 5213 y FM(\017)o FJ(ROUND_HALF_DOWN)f FN(\(to)i(nearest)g(with)g(ties)h(going)e(to)n(w)o(ards)h(zero\),)349 5346 y FM(\017)o FJ(ROUND_HALF_EVEN)e FN(\(to)i(nearest)g(with)g(ties)h (going)e(to)i(nearest)f(e)n(v)o(en)f(inte)o(ger\),)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q(ithmetic)1917 b(159)p eop end %%Page: 160 172 TeXDict begin 160 171 bop 349 83 a FM(\017)o FJ(ROUND_HALF_UP)19 b FN(\(to)h(nearest)f(with)i(ties)g(going)e(a)o(w)o(ay)h(from)f (zero\),)g(or)349 216 y FM(\017)o FJ(ROUND_UP)g FN(\(a)o(w)o(ay)h(from) f(zero\).)208 382 y(The)i FK(tr)o(aps)h FN(and)g FK(\003a)o(gs)f FN(\002elds)i(list)g(an)o(y)e(signals)h(to)g(be)g(set.)32 b(Generally)-5 b(,)20 b(ne)n(w)i(conte)o(xts)f(should)g(only)g(set)i (traps)f(and)g(lea)n(v)o(e)g(the)208 482 y(\003ags)e(clear)-5 b(.)208 614 y(The)19 b FK(Emin)h FN(and)g FK(Emax)g FN(\002elds)h(are)f (inte)o(gers)f(specifying)g(the)h(outer)f(limits)i(allo)n(w)o(able)f (for)g(e)o(xponents.)208 747 y(The)i FK(capitals)g FN(\002eld)g(is)i (either)e FJ(0)h FN(or)f FJ(1)h FN(\(the)f(def)o(ault\).)31 b(If)22 b(set)i(to)e FJ(1)p FN(,)i(e)o(xponents)c(are)j(printed)e(with) i(a)g(capital)f FJ(E)p FN(;)h(otherwise,)f(a)208 847 y(lo)n(wercase)d FJ(e)i FN(is)g(used:)k FJ(Decimal\('6.02e+23'\))p FN(.)0 994 y(The)16 b FJ(Context)f FN(class)i(de\002nes)e(se)n(v)o (eral)g(general)g(purpose)f(methods)h(as)i(well)f(as)h(a)f(lar)o(ge)f (number)f(of)i(methods)f(for)g(doing)f(arithmetic)0 1093 y(directly)19 b(in)i(a)f(gi)n(v)o(en)f(conte)o(xt.)0 1240 y FD(clear_flags)p FJ(\(\))208 1340 y FN(Resets)i(all)g(of)f(the)g (\003ags)h(to)f FJ(0)p FN(.)0 1487 y FD(copy)p FJ(\(\))208 1586 y FN(Return)f(a)i(duplicate)e(of)h(the)g(conte)o(xt.)0 1733 y FD(create_decimal)p FJ(\()p FK(num)p FJ(\))208 1833 y FN(Creates)29 b(a)h(ne)n(w)f(Decimal)g(instance)f(from)g FK(num)h FN(b)n(ut)g(using)g FK(self)42 b FN(as)30 b(conte)o(xt.)50 b(Unlik)o(e)29 b(the)g FJ(Decimal)g FN(constructor)m(,)g(the)208 1932 y(conte)o(xt)18 b(precision,)h(rounding)f(method,)g(\003ags,)j (and)e(traps)i(are)f(applied)f(to)h(the)g(con)m(v)o(ersion.)208 2065 y(This)e(is)h(useful)f(because)g(constants)g(are)g(often)f(gi)n(v) o(en)g(to)i(a)f(greater)g(precision)f(than)h(is)h(needed)e(by)h(the)g (application.)23 b(Another)208 2165 y(bene\002t)e(is)i(that)f(rounding) d(immediately)h(eliminates)i(unintended)e(ef)n(fects)h(from)g(digits)h (be)o(yond)e(the)h(current)g(precision.)29 b(In)208 2265 y(the)20 b(follo)n(wing)e(e)o(xample,)h(using)h(unrounded)c(inputs)k (means)g(that)g(adding)f(zero)h(to)g(a)h(sum)f(can)g(change)f(the)h (result:)623 2489 y FA(>>>)44 b(getcontext\(\).prec)e(=)j(3)623 2580 y(>>>)f(Decimal\("3.4445"\))e(+)j(Decimal\("1.0023"\))623 2671 y(Decimal\("4.45"\))623 2763 y(>>>)f(Decimal\("3.4445"\))e(+)j (Decimal\(0\))e(+)i(Decimal\("1.0023"\))623 2854 y(Decimal\("4.44"\))0 3147 y FD(Etiny)p FJ(\(\))208 3247 y FN(Returns)22 b(a)h(v)n(alue)f (equal)g(to)h(`)p FJ(Emin)48 b(-)i(prec)f(+)h(1)p FN(')22 b(which)g(is)i(the)f(minimum)e(e)o(xponent)f(v)n(alue)i(for)g (subnormal)e(results.)208 3346 y(When)g(under\003o)n(w)e(occurs,)h(the) h(e)o(xponent)e(is)j(set)g(to)g FJ(Etiny)p FN(.)0 3493 y FD(Etop)p FJ(\(\))208 3593 y FN(Returns)f(a)g(v)n(alue)g(equal)f(to)i (`)p FJ(Emax)48 b(-)i(prec)f(+)h(1)p FN('.)0 3740 y(The)25 b(usual)f(approach)f(to)i(w)o(orking)e(with)i(decimals)g(is)h(to)f (create)f FJ(Decimal)h FN(instances)f(and)h(then)f(apply)g(arithmetic)g (operations)0 3839 y(which)d(tak)o(e)h(place)f(within)g(the)h(current)e (conte)o(xt)g(for)h(the)h(acti)n(v)o(e)f(thread.)28 b(An)21 b(alternate)g(approach)f(is)i(to)g(use)f(conte)o(xt)g(methods)f(for)0 3939 y(calculating)25 b(within)g(a)i(speci\002c)f(conte)o(xt.)41 b(The)25 b(methods)g(are)h(similar)g(to)g(those)g(for)f(the)h FJ(Decimal)f FN(class)i(and)e(are)h(only)f(brie\003y)0 4038 y(recounted)18 b(here.)0 4185 y FD(abs)p FJ(\()p FK(x)p FJ(\))208 4285 y FN(Returns)i(the)g(absolute)f(v)n(alue)h(of)g FK(x)p FN(.)0 4432 y FD(add)p FJ(\()p FK(x,)g(y)p FJ(\))208 4531 y FN(Return)f(the)i(sum)f(of)g FK(x)g FN(and)g FK(y)p FN(.)0 4678 y FD(compare)p FJ(\()p FK(x,)f(y)p FJ(\))208 4778 y FN(Compares)g(v)n(alues)h(numerically)-5 b(.)208 4911 y(Lik)o(e)20 b FJ(__cmp__\(\))f FN(b)n(ut)h(returns)f(a)i(decimal) e(instance:)p 0 5549 3901 4 v 0 5649 a FI(160)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 161 173 TeXDict begin 161 172 bop 802 174 a FA(a)45 b(or)g(b)f(is)h(a)f(NaN)h (==>)f(Decimal\("NaN"\))802 266 y(a)h(<)g(b)493 b(==>)44 b(Decimal\("-1"\))802 357 y(a)h(==)g(b)448 b(==>)44 b(Decimal\("0"\)) 802 448 y(a)h(>)g(b)493 b(==>)44 b(Decimal\("1"\))0 741 y FD(divide)p FJ(\()p FK(x,)19 b(y)p FJ(\))208 841 y FN(Return)g FK(x)i FN(di)n(vided)e(by)h FK(y)p FN(.)0 988 y FD(divmod)p FJ(\()p FK(x,)f(y)p FJ(\))208 1087 y FN(Di)n(vides)h(tw)o(o)g(numbers)f(and)g(returns)h(the)g(inte)o(ger)f (part)h(of)g(the)g(result.)0 1234 y FD(max)p FJ(\()p FK(x,)g(y)p FJ(\))208 1334 y FN(Compare)f(tw)o(o)h(v)n(alues)g (numerically)e(and)i(return)f(the)h(maximum.)208 1467 y(If)g(the)o(y)f(are)h(numerically)f(equal)g(then)h(the)g(left-hand)f (operand)f(is)j(chosen)e(as)i(the)f(result.)0 1614 y FD(min)p FJ(\()p FK(x,)g(y)p FJ(\))208 1713 y FN(Compare)f(tw)o(o)h(v)n (alues)g(numerically)e(and)i(return)f(the)h(minimum.)208 1846 y(If)g(the)o(y)f(are)h(numerically)f(equal)g(then)h(the)g (left-hand)f(operand)f(is)j(chosen)e(as)i(the)f(result.)0 1993 y FD(minus)p FJ(\()p FK(x)p FJ(\))208 2093 y FN(Minus)g (corresponds)d(to)k(the)f(unary)f(pre\002x)g(minus)h(operator)e(in)j (Python.)0 2239 y FD(multiply)p FJ(\()p FK(x,)e(y)p FJ(\))208 2339 y FN(Return)g(the)i(product)d(of)i FK(x)h FN(and)e FK(y)p FN(.)0 2486 y FD(normalize)p FJ(\()p FK(x)p FJ(\))208 2586 y FN(Normalize)g(reduces)g(an)h(operand)e(to)j(its)g(simplest)f (form.)208 2718 y(Essentially)g(a)g FJ(plus)g FN(operation)f(with)h (all)h(trailing)e(zeros)h(remo)o(v)o(ed)e(from)h(the)h(result.)0 2865 y FD(plus)p FJ(\()p FK(x)p FJ(\))208 2965 y FN(Plus)k(corresponds) d(to)j(the)f(unary)g(pre\002x)g(plus)g(operator)f(in)i(Python.)34 b(This)24 b(operation)d(applies)j(the)f(conte)o(xt)g(precision)f(and) 208 3064 y(rounding,)17 b(so)j(it)h(is)g FK(not)f FN(an)g(identity)g (operation.)0 3211 y FD(power)p FJ(\()p FK(x,)f(y)p FC([)p FK(,)h(modulo)12 b FC(])p FJ(\))208 3311 y FN(Return)19 b(`)p FJ(x)582 3326 y(**)731 3311 y(y)p FN(')h(to)h(the)f FK(modulo)f FN(if)h(gi)n(v)o(en.)208 3444 y(The)i(right-hand)e(operand) h(must)h(be)h(a)g(whole)f(number)f(whose)h(inte)o(ger)g(part)g(\(after) g(an)o(y)g(e)o(xponent)e(has)j(been)f(applied\))f(has)208 3543 y(no)27 b(more)g(than)h(9)g(digits)g(and)f(whose)h(fractional)e (part)i(\(if)g(an)o(y\))e(is)j(all)g(zeros)e(before)g(an)o(y)g (rounding.)46 b(The)27 b(operand)f(may)208 3643 y(be)c(positi)n(v)o(e,) h(ne)o(gati)n(v)o(e,)e(or)i(zero;)g(if)h(ne)o(gati)n(v)o(e,)d(the)i (absolute)f(v)n(alue)g(of)h(the)g(po)n(wer)e(is)j(used,)f(and)g(the)g (left-hand)e(operand)g(is)208 3743 y(in)m(v)o(erted)d(\(di)n(vided)g (into)i(1\))g(before)f(use.)208 3876 y(If)d(the)h(increased)e (precision)h(needed)f(for)h(the)g(intermediate)g(calculations)f(e)o (xceeds)h(the)h(capabilities)f(of)g(the)h(implementation)208 3975 y(then)i(an)h FJ(InvalidOperation)e FN(condition)h(is)i(signaled.) 208 4108 y(If,)g(when)h(raising)f(to)h(a)g(ne)o(gati)n(v)o(e)e(po)n (wer)m(,)g(an)i(under\003o)n(w)e(occurs)h(during)f(the)i(di)n(vision)f (into)g(1,)h(the)g(operation)e(is)j(not)e(halted)208 4208 y(at)f(that)h(point)e(b)n(ut)h(continues.)0 4354 y FD(quantize)p FJ(\()p FK(x,)f(y)p FJ(\))208 4454 y FN(Returns)h(a)g(v)n(alue)g(equal)f(to)i FK(x)f FN(after)g(rounding)e (and)i(ha)n(ving)f(the)h(e)o(xponent)e(of)i FK(y)p FN(.)208 4587 y(Unlik)o(e)j(other)g(operations,)f(if)i(the)g(length)e(of)h(the)h (coef)n(\002cient)f(after)g(the)g(quantize)g(operation)e(w)o(ould)i(be) h(greater)e(than)h(pre-)208 4687 y(cision,)f(then)f(an)h FJ(InvalidOperation)e FN(is)j(signaled.)30 b(This)22 b(guarantees)f(that,)h(unless)g(there)g(is)h(an)f(error)f(condition,)g (the)208 4786 y(quantized)d(e)o(xponent)g(is)j(al)o(w)o(ays)g(equal)e (to)i(that)f(of)g(the)g(right-hand)e(operand.)208 4919 y(Also)i(unlik)o(e)g(other)f(operations,)f(quantize)h(ne)n(v)o(er)g (signals)i(Under\003o)n(w)-5 b(,)18 b(e)n(v)o(en)h(if)h(the)h(result)f (is)h(subnormal)d(and)i(ine)o(xact.)0 5066 y FD(remainder)p FJ(\()p FK(x,)f(y)p FJ(\))208 5166 y FN(Returns)h(the)g(remainder)e (from)h(inte)o(ger)g(di)n(vision.)208 5298 y(The)g(sign)i(of)e(the)i (result,)f(if)g(non-zero,)e(is)j(the)f(same)g(as)h(that)g(of)f(the)g (original)f(di)n(vidend.)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q (ithmetic)1917 b(161)p eop end %%Page: 162 174 TeXDict begin 162 173 bop 0 83 a FD(remainder_near)p FJ(\()p FK(x,)18 b(y)p FJ(\))208 183 y FN(Computed)28 b(the)h(modulo)f(as)i(either)f(a)h(positi)n(v)o(e)f(or)g(ne)o(gati)n(v) o(e)f(v)n(alue)h(depending)e(on)i(which)g(is)h(closest)g(to)g(zero.)53 b(F)o(or)29 b(in-)208 282 y(stance,)j(`)p FJ (Decimal\(10\).remainder_near\(6\))p FN(')25 b(returns)k FJ(Decimal\("-2"\))f FN(which)i(is)h(closer)f(to)g(zero)g(than)208 382 y FJ(Decimal\("4"\))p FN(.)208 515 y(If)20 b(both)f(are)h(equally)f (close,)h(the)h(one)e(chosen)h(will)g(ha)n(v)o(e)g(the)g(same)h(sign)f (as)h FK(self)12 b FN(.)0 662 y FD(same_quantum)p FJ(\()p FK(x,)18 b(y)p FJ(\))208 761 y FN(T)-6 b(est)20 b(whether)g FK(x)g FN(and)g FK(y)h FN(ha)n(v)o(e)e(the)i(same)f(e)o(xponent)e(or)i (whether)f(both)g(are)h FJ(NaN)p FN(.)0 908 y FD(sqrt)p FJ(\()p FK(x)p FJ(\))208 1008 y FN(Return)f(the)i(square)e(root)g(of)h FK(x)h FN(to)g(full)f(precision.)0 1155 y FD(subtract)p FJ(\()p FK(x,)f(y)p FJ(\))208 1254 y FN(Return)g(the)i(dif)n(ference)d (between)h FK(x)i FN(and)f FK(y)p FN(.)0 1401 y FD(to_eng_string)p FJ(\(\))208 1501 y FN(Con)m(v)o(ert)e(to)j(engineering-type)16 b(string.)208 1634 y(Engineering)23 b(notation)i(has)h(an)g(e)o (xponent)e(which)h(is)i(a)g(multiple)e(of)h(3,)h(so)f(there)g(are)g(up) g(to)g(3)g(digits)g(left)g(of)g(the)g(decimal)208 1733 y(place.)e(F)o(or)c(e)o(xample,)f(con)m(v)o(erts)f FJ (Decimal\('123E+1'\))g FN(to)i FJ(Decimal\("1.23E+3"\))0 1880 y FD(to_integral)p FJ(\()p FK(x)p FJ(\))208 1980 y FN(Rounds)f(to)h(the)h(nearest)e(inte)o(ger)h(without)f(signaling)g FJ(Inexact)h FN(or)g FJ(Rounded)p FN(.)0 2127 y FD(to_sci_string)p FJ(\()p FK(x)p FJ(\))208 2226 y FN(Con)m(v)o(erts)f(a)h(number)f(to)h (a)h(string)e(using)h(scienti\002c)h(notation.)0 2511 y Fv(6.3.4)100 b(Signals)0 2714 y FN(Signals)20 b(represent)g (conditions)e(that)j(arise)g(during)d(computation.)23 b(Each)d(corresponds)e(to)j(one)f(conte)o(xt)f(\003ag)h(and)g(one)g (conte)o(xt)f(trap)0 2814 y(enabler)-5 b(.)0 2960 y(The)21 b(conte)o(xt)f(\003ag)i(is)g(incremented)d(whene)n(v)o(er)h(the)h (condition)f(is)i(encountered.)k(After)21 b(the)h(computation,)d (\003ags)j(may)f(be)g(check)o(ed)0 3060 y(for)f(informational)e (purposes)h(\(for)g(instance,)h(to)g(determine)f(whether)h(a)g (computation)e(w)o(as)j(e)o(xact\).)k(After)20 b(checking)f(the)h (\003ags,)h(be)0 3160 y(sure)f(to)g(clear)g(all)h(\003ags)g(before)e (starting)g(the)i(ne)o(xt)e(computation.)0 3307 y(If)d(the)g(conte)o (xt')-5 b(s)16 b(trap)g(enabler)f(is)i(set)g(for)e(the)i(signal,)f (then)g(the)g(condition)f(causes)h(a)h(Python)e(e)o(xception)f(to)j(be) f(raised.)23 b(F)o(or)16 b(e)o(xample,)0 3406 y(if)h(the)g FJ(DivisionByZero)e FN(trap)i(is)h(set,)g(then)f(a)h FJ(DivisionByZero)d FN(e)o(xception)g(is)j(raised)f(upon)e (encountering)f(the)k(condition.)0 3553 y FL(class)j FD(Clamped)208 3653 y FN(Altered)e(an)h(e)o(xponent)e(to)j(\002t)g (representation)d(constraints.)208 3786 y(T)-7 b(ypically)i(,)17 b(clamping)h(occurs)g(when)g(an)h(e)o(xponent)e(f)o(alls)i(outside)g (the)g(conte)o(xt')-5 b(s)18 b FJ(Emin)h FN(and)f FJ(Emax)h FN(limits.)25 b(If)19 b(possible,)g(the)208 3885 y(e)o(xponent)e(is)22 b(reduced)c(to)i(\002t)h(by)f(adding)f(zeroes)h(to)g(the)g(coef)n (\002cient.)0 4032 y FL(class)h FD(DecimalException)208 4132 y FN(Base)g(class)g(for)e(other)h(signals)g(and)g(a)g(subclass)h (of)f FJ(ArithmeticError)p FN(.)0 4279 y FL(class)h FD(DivisionByZero) 208 4378 y FN(Signals)f(the)g(di)n(vision)f(of)h(a)h(non-in\002nite)d (number)g(by)i(zero.)208 4511 y(Can)25 b(occur)f(with)h(di)n(vision,)g (modulo)e(di)n(vision,)i(or)f(when)h(raising)f(a)h(number)e(to)j(a)f (ne)o(gati)n(v)o(e)e(po)n(wer)-5 b(.)38 b(If)25 b(this)g(signal)g(is)h (not)208 4611 y(trapped,)18 b(returns)h FJ(Infinity)h FN(or)g FJ(-Infinity)f FN(with)h(the)g(sign)g(determined)f(by)g(the)i (inputs)e(to)i(the)f(calculation.)0 4758 y FL(class)h FD(Inexact)208 4857 y FN(Indicates)e(that)h(rounding)e(occurred)g(and)i (the)g(result)g(is)h(not)f(e)o(xact.)208 4990 y(Signals)j(when)g (non-zero)e(digits)i(were)g(discarded)f(during)g(rounding.)32 b(The)23 b(rounded)e(result)i(is)i(returned.)32 b(The)23 b(signal)g(\003ag)208 5090 y(or)c(trap)h(is)h(used)f(to)h(detect)f (when)f(results)i(are)f(ine)o(xact.)0 5236 y FL(class)h FD(InvalidOperation)208 5336 y FN(An)f(in)m(v)n(alid)f(operation)f(w)o (as)j(performed.)p 0 5549 3901 4 v 0 5649 a FI(162)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 163 175 TeXDict begin 163 174 bop 208 83 a FN(Indicates)18 b(that)h(an)h (operation)d(w)o(as)j(requested)e(that)h(does)g(not)g(mak)o(e)g(sense.) 25 b(If)19 b(not)g(trapped,)e(returns)i FJ(NaN)p FN(.)g(Possible)g (causes)208 183 y(include:)802 315 y FA(Infinity)44 b(-)h(Infinity)802 407 y(0)892 420 y(*)982 407 y(Infinity)802 498 y(Infinity)f(/)h (Infinity)802 589 y(x)g(\045)g(0)802 681 y(Infinity)f(\045)h(x)802 772 y(x._rescale\()e(non-integer)g(\))802 863 y(sqrt\(-x\))h(and)g(x)h (>)g(0)802 955 y(0)892 968 y(**)1027 955 y(0)802 1046 y(x)892 1059 y(**)1027 1046 y(\(non-integer\))802 1137 y(x)892 1150 y(**)1027 1137 y(Infinity)0 1431 y FL(class)21 b FD(Overflow)208 1531 y FN(Numerical)e(o)o(v)o(er\003o)n(w)-5 b(.)208 1664 y(Indicates)24 b(the)h(e)o(xponent)e(is)j(lar)o(ger)e (than)g FJ(Emax)h FN(after)g(rounding)e(has)i(occurred.)38 b(If)25 b(not)f(trapped,)h(the)g(result)g(depends)f(on)208 1764 y(the)30 b(rounding)f(mode,)j(either)f(pulling)e(inw)o(ard)h(to)h (the)g(lar)o(gest)g(representable)e(\002nite)i(number)e(or)h(rounding)f (outw)o(ard)g(to)208 1863 y FJ(Infinity)p FN(.)24 b(In)19 b(either)h(case,)h FJ(Inexact)e FN(and)h FJ(Rounded)f FN(are)h(also)h(signaled.)0 2010 y FL(class)g FD(Rounded)208 2110 y FN(Rounding)d(occurred)g(though)g(possibly)i(no)g(information)d (w)o(as)22 b(lost.)208 2242 y(Signaled)h(whene)n(v)o(er)e(rounding)h (discards)h(digits;)j(e)n(v)o(en)d(if)h(those)f(digits)h(are)g(zero)g (\(such)f(as)h(rounding)e FJ(5.00)h FN(to)h FJ(5.0)p FN(\).)36 b(If)208 2342 y(not)19 b(trapped,)g(returns)g(the)h(result)h (unchanged.)h(This)e(signal)g(is)h(used)f(to)h(detect)f(loss)h(of)f (signi\002cant)f(digits.)0 2489 y FL(class)i FD(Subnormal)208 2589 y FN(Exponent)d(w)o(as)j(lo)n(wer)e(than)h FJ(Emin)g FN(prior)f(to)h(rounding.)208 2721 y(Occurs)28 b(when)g(an)h(operation) e(result)i(is)h(subnormal)d(\(the)i(e)o(xponent)d(is)k(too)f(small\).) 51 b(If)29 b(not)f(trapped,)i(returns)e(the)h(result)208 2821 y(unchanged.)0 2968 y FL(class)21 b FD(Underflow)208 3068 y FN(Numerical)e(under\003o)n(w)f(with)i(result)h(rounded)c(to)k (zero.)208 3200 y(Occurs)e(when)h(a)h(subnormal)d(result)i(is)h(pushed) e(to)i(zero)e(by)h(rounding.)i FJ(Inexact)e FN(and)f FJ(Subnormal)g FN(are)i(also)f(signaled.)0 3347 y(The)g(follo)n(wing)e (table)j(summarizes)e(the)h(hierarchy)e(of)i(signals:)416 3585 y FA(exceptions.ArithmeticError\(exception)o(s.Stan)o(dardEr)o (ror\))595 3677 y(DecimalException)774 3768 y(Clamped)774 3859 y(DivisionByZero\(DecimalException,)40 b (exceptions.ZeroDivisionError\))774 3951 y(Inexact)954 4042 y(Overflow\(Inexact,)i(Rounded\))954 4133 y(Underflow\(Inexact,)f (Rounded,)j(Subnormal\))774 4225 y(InvalidOperation)774 4316 y(Rounded)774 4407 y(Subnormal)0 4831 y Fv(6.3.5)100 b(Floating)29 b(P)-5 b(oint)29 b(Notes)0 5034 y FI(Mitigating)c (round-off)f(error)e(with)i(increased)f(precision)0 5236 y FN(The)16 b(use)g(of)g(decimal)f(\003oating)g(point)h(eliminates)g (decimal)f(representation)f(error)h(\(making)f(it)j(possible)f(to)g (represent)f FJ(0.1)h FN(e)o(xactly\);)0 5336 y(ho)n(we)n(v)o(er)m(,)i (some)i(operations)e(can)i(still)i(incur)d(round-of)n(f)e(error)i(when) g(non-zero)f(digits)j(e)o(xceed)e(the)h(\002x)o(ed)f(precision.)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q(ithmetic)1917 b(163)p eop end %%Page: 164 176 TeXDict begin 164 175 bop 0 83 a FN(The)18 b(ef)n(fects)f(of)h (round-of)n(f)c(error)j(can)h(be)g(ampli\002ed)f(by)g(the)h(addition)f (or)g(subtraction)g(of)g(nearly)g(of)n(fsetting)g(quantities)g (resulting)g(in)0 183 y(loss)h(of)f(signi\002cance.)23 b(Knuth)16 b(pro)o(vides)f(tw)o(o)i(instructi)n(v)o(e)f(e)o(xamples)g (where)h(rounded)d(\003oating)j(point)f(arithmetic)g(with)h(insuf)n (\002cient)0 282 y(precision)i(causes)i(the)f(breakdo)n(wn)d(of)j(the)g (associati)n(v)o(e)g(and)g(distrib)n(uti)n(v)o(e)f(properties)g(of)g (addition:)236 520 y FA(#)45 b(Examples)e(from)i(Seminumerical)d (Algorithms,)h(Section)h(4.2.2.)236 612 y(>>>)h(from)f(decimal)f (import)h(Decimal,)g(getcontext)236 703 y(>>>)h(getcontext\(\).prec)d (=)i(8)236 886 y(>>>)h(u,)f(v,)h(w)f(=)h(Decimal\(11111113\),)d (Decimal\(-11111111\),)f(Decimal\('7.51111111'\))236 977 y(>>>)k(\(u)f(+)h(v\))f(+)h(w)236 1068 y(Decimal\("9.5111111"\))236 1160 y(>>>)g(u)f(+)h(\(v)f(+)h(w\))236 1251 y(Decimal\("10"\))236 1434 y(>>>)g(u,)f(v,)h(w)f(=)h(Decimal\(20000\),)d(Decimal\(-6\),)h (Decimal\('6.0000003'\))236 1525 y(>>>)i(\(u)506 1538 y(*)551 1525 y(v\))f(+)g(\(u)864 1538 y(*)909 1525 y(w\))236 1616 y(Decimal\("0.01"\))236 1708 y(>>>)h(u)505 1721 y(*)595 1708 y(\(v+w\))236 1799 y(Decimal\("0.0060000"\))0 2086 y FN(The)21 b FJ(decimal)f FN(module)g(mak)o(es)h(it)g(possible)g (to)g(restore)g(the)g(identities)g(by)f(e)o(xpanding)f(the)i(precision) f(suf)n(\002ciently)g(to)h(a)n(v)n(oid)g(loss)0 2185 y(of)f(signi\002cance:)236 2423 y FA(>>>)45 b(getcontext\(\).prec)d(=)i (20)236 2515 y(>>>)h(u,)f(v,)h(w)f(=)h(Decimal\(11111113\),)d (Decimal\(-11111111\),)f(Decimal\('7.51111111'\))236 2606 y(>>>)k(\(u)f(+)h(v\))f(+)h(w)236 2697 y(Decimal\("9.51111111"\)) 236 2789 y(>>>)g(u)f(+)h(\(v)f(+)h(w\))236 2880 y (Decimal\("9.51111111"\))236 2971 y(>>>)236 3063 y(>>>)g(u,)f(v,)h(w)f (=)h(Decimal\(20000\),)d(Decimal\(-6\),)h(Decimal\('6.0000003'\))236 3154 y(>>>)i(\(u)506 3167 y(*)551 3154 y(v\))f(+)g(\(u)864 3167 y(*)909 3154 y(w\))236 3245 y(Decimal\("0.0060000"\))236 3337 y(>>>)h(u)505 3350 y(*)595 3337 y(\(v+w\))236 3428 y(Decimal\("0.0060000"\))0 3840 y FI(Special)24 b(v)n(alues)0 4043 y FN(The)45 b(number)e(system)i(for)f(the)h FJ(decimal)g FN(module)e(pro)o(vides)h(special)h(v)n(alues)f(including)g FJ(NaN)p FN(,)g FJ(sNaN)p FN(,)h FJ(-Infinity)p FN(,)0 4143 y FJ(Infinity)p FN(,)19 b(and)h(tw)o(o)g(zeroes,)g FJ(+0)g FN(and)g FJ(-0)p FN(.)0 4290 y(In\002nities)25 b(can)g(be)g(constructed)e(directly)h(with:)35 b FJ (Decimal\('Infinity'\))p FN(.)i(Also,)26 b(the)o(y)e(can)h(arise)g (from)f(di)n(viding)g(by)g(zero)0 4389 y(when)17 b(the)i FJ(DivisionByZero)d FN(signal)h(is)i(not)f(trapped.)23 b(Lik)o(e)n(wise,)18 b(when)g(the)g FJ(Overflow)f FN(signal)h(is)h(not) e(trapped,)g(in\002nity)h(can)0 4489 y(result)i(from)f(rounding)f(be)o (yond)g(the)i(limits)h(of)f(the)g(lar)o(gest)g(representable)e(number) -5 b(.)0 4636 y(The)19 b(in\002nities)h(are)f(signed)f(\(af)n(\002ne\)) h(and)f(can)h(be)h(used)f(in)g(arithmetic)g(operations)f(where)g(the)o (y)h(get)g(treated)g(as)h(v)o(ery)e(lar)o(ge,)g(indeter)n(-)0 4736 y(minate)i(numbers.)j(F)o(or)d(instance,)g(adding)e(a)j(constant)e (to)i(in\002nity)e(gi)n(v)o(es)h(another)f(in\002nite)h(result.)0 4882 y(Some)f(operations)f(are)i(indeterminate)d(and)i(return)g FJ(NaN)p FN(,)g(or)g(if)h(the)g FJ(InvalidOperation)d FN(signal)i(is)i(trapped,)d(raise)i(an)f(e)o(xcep-)0 4982 y(tion.)24 b(F)o(or)18 b(e)o(xample,)g FJ(0/0)g FN(returns)g FJ(NaN)h FN(which)f(means)g(\223not)g(a)h(number\224.)k (This)18 b(v)n(ariety)g(of)g FJ(NaN)h FN(is)h(quiet)e(and,)g(once)g (created,)g(will)0 5082 y(\003o)n(w)k(through)d(other)i(computations)e (al)o(w)o(ays)j(resulting)e(in)i(another)e FJ(NaN)p FN(.)h(This)h(beha) n(vior)e(can)h(be)g(useful)g(for)g(a)h(series)g(of)f(compu-)0 5181 y(tations)h(that)h(occasionally)e(ha)n(v)o(e)h(missing)g(inputs)g (\227)h(it)g(allo)n(ws)g(the)f(calculation)g(to)g(proceed)f(while)h (\003agging)f(speci\002c)i(results)g(as)0 5281 y(in)m(v)n(alid.)p 0 5549 3901 4 v 0 5649 a FI(164)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 165 177 TeXDict begin 165 176 bop 0 83 a FN(A)22 b(v)n(ariant)e(is)i FJ(sNaN)f FN(which)f(signals)h(rather)g(than)f(remaining)g(quiet)g (after)h(e)n(v)o(ery)f(operation.)26 b(This)21 b(is)h(a)f(useful)g (return)f(v)n(alue)g(when)0 183 y(an)g(in)m(v)n(alid)f(result)h(needs)g (to)g(interrupt)f(a)i(calculation)e(for)g(special)i(handling.)0 330 y(The)30 b(signed)g(zeros)g(can)g(result)g(from)g(calculations)f (that)h(under\003o)n(w)-5 b(.)54 b(The)o(y)29 b(k)o(eep)h(the)g(sign)g (that)h(w)o(ould)e(ha)n(v)o(e)h(resulted)g(if)h(the)0 429 y(calculation)22 b(had)h(been)g(carried)f(out)h(to)g(greater)g (precision.)33 b(Since)23 b(their)g(magnitude)e(is)k(zero,)e(both)f (positi)n(v)o(e)h(and)g(ne)o(gati)n(v)o(e)e(zeros)0 529 y(are)f(treated)g(as)h(equal)e(and)h(their)g(sign)g(is)h (informational.)0 676 y(In)d(addition)g(to)h(the)f(tw)o(o)h(signed)f (zeros)h(which)f(are)g(distinct)h(yet)g(equal,)f(there)g(are)h(v)n (arious)e(representations)g(of)i(zero)f(with)h(dif)n(fering)0 775 y(precisions)k(yet)h(equi)n(v)n(alent)e(in)i(v)n(alue.)35 b(This)24 b(tak)o(es)g(a)g(bit)g(of)g(getting)f(used)h(to.)36 b(F)o(or)23 b(an)h(e)o(ye)f(accustomed)f(to)i(normalized)e(\003oating)0 875 y(point)d(representations,)g(it)h(is)i(not)d(immediately)g(ob)o (vious)g(that)h(the)g(follo)n(wing)f(calculation)g(returns)g(a)i(v)n (alue)e(equal)h(to)g(zero:)236 1113 y FA(>>>)45 b(1)f(/)h (Decimal\('Infinity'\))236 1204 y(Decimal\("0E-1000000026"\))0 1628 y Fv(6.3.6)100 b(W)m(or)q(king)30 b(with)e(threads)0 1831 y FN(The)18 b FJ(getcontext\(\))e FN(function)h(accesses)i(a)f (dif)n(ferent)f FJ(Context)g FN(object)h(for)f(each)h(thread.)23 b(Ha)n(ving)18 b(separate)f(thread)h(conte)o(xts)0 1930 y(means)i(that)g(threads)g(may)f(mak)o(e)h(changes)f(\(such)h(as)h FJ(getcontext.prec=10)p FN(\))c(without)i(interfering)f(with)j(other)e (threads.)0 2077 y(Lik)o(e)n(wise,)h(the)g FJ(setcontext\(\))f FN(function)f(automatically)h(assigns)h(its)i(tar)o(get)d(to)h(the)h (current)d(thread.)0 2224 y(If)j FJ(setcontext\(\))f FN(has)i(not)f(been)g(called)g(before)g FJ(getcontext\(\))p FN(,)f(then)h FJ(getcontext\(\))f FN(will)i(automatically)e(create)h(a) 0 2324 y(ne)n(w)f(conte)o(xt)f(for)g(use)i(in)f(the)g(current)f (thread.)0 2470 y(The)h(ne)n(w)h(conte)o(xt)e(is)j(copied)d(from)h(a)h (prototype)d(conte)o(xt)h(called)i FK(DefaultConte)n(xt)q FN(.)26 b(T)-7 b(o)20 b(control)g(the)g(def)o(aults)h(so)g(that)f(each) h(thread)0 2570 y(will)j(use)f(the)g(same)g(v)n(alues)g(throughout)d (the)j(application,)f(directly)g(modify)f(the)i FK(DefaultConte)n(xt)h FN(object.)33 b(This)23 b(should)f(be)h(done)0 2670 y FK(befor)m(e)g FN(an)o(y)f(threads)g(are)h(started)g(so)h(that)f(there) f(w)o(on')o(t)g(be)h(a)h(race)f(condition)e(between)h(threads)h (calling)f FJ(getcontext\(\))p FN(.)32 b(F)o(or)0 2769 y(e)o(xample:)236 2916 y FA(#)45 b(Set)f(applicationwide)f(defaults)g (for)h(all)h(threads)e(about)h(to)h(be)f(launched)236 3008 y(DefaultContext.prec)e(=)j(12)236 3099 y(DefaultContext.rounding) c(=)k(ROUND_DOWN)236 3190 y(DefaultContext.traps)d(=)i (ExtendedContext.traps.copy\(\))236 3282 y (DefaultContext.traps[InvalidOperation])39 b(=)44 b(1)236 3373 y(setcontext\(DefaultContext\))236 3555 y(#)h(Afterwards,)e(the)h (threads)g(can)g(be)h(started)236 3647 y(t1.start\(\))236 3738 y(t2.start\(\))236 3829 y(t3.start\(\))281 3921 y(.)g(.)f(.)0 4344 y Fv(6.3.7)100 b(Recipes)0 4547 y FN(Here)20 b(are)g(a)h(fe)n(w)f(recipes)g(that)g(serv)o(e)g(as)h (utility)f(functions)f(and)g(that)i(demonstrate)d(w)o(ays)j(to)f(w)o (ork)g(with)g(the)g FJ(Decimal)g FN(class:)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h (\003oating)g(point)g(ar)q(ithmetic)1917 b(165)p eop end %%Page: 166 178 TeXDict begin 166 177 bop 236 174 a FA(def)45 b(moneyfmt\(value,)d (places=2,)h(curr='',)h(sep=',',)f(dp='.',)819 266 y(pos='',)h (neg='-',)f(trailneg=''\):)416 357 y("""Convert)g(Decimal)g(to)i(a)g (money)f(formatted)f(string.)416 540 y(places:)88 b(required)44 b(number)f(of)i(places)f(after)g(the)g(decimal)g(point)416 631 y(curr:)178 b(optional)44 b(currency)f(symbol)h(before)g(the)g (sign)g(\(may)g(be)h(blank\))416 722 y(sep:)223 b(optional)44 b(grouping)f(separator)g(\(comma,)h(period,)g(space,)f(or)i(blank\))416 814 y(dp:)268 b(decimal)44 b(point)g(indicator)f(\(comma)h(or)g (period\))819 905 y(only)g(specify)g(as)g(blank)g(when)g(places)g(is)h (zero)416 996 y(pos:)223 b(optional)44 b(sign)g(for)g(positive)f (numbers:)h('+',)g(space)g(or)h(blank)416 1088 y(neg:)223 b(optional)44 b(sign)g(for)g(negative)f(numbers:)h('-',)g('\(',)g (space)g(or)h(blank)416 1179 y(trailneg:optional)d(trailing)h(minus)h (indicator:)88 b('-',)44 b('\)',)g(space)g(or)h(blank)416 1362 y(>>>)f(d)h(=)f(Decimal\('-1234567.8901'\))416 1453 y(>>>)g(moneyfmt\(d,)f(curr='$'\))416 1544 y('-$1,234,567.89')416 1636 y(>>>)h(moneyfmt\(d,)f(places=0,)g(sep='.',)h(dp='',)f(neg='',)h (trailneg='-'\))416 1727 y('1.234.568-')416 1818 y(>>>)g(moneyfmt\(d,)f (curr='$',)g(neg='\(',)h(trailneg='\)'\))416 1910 y ('\($1,234,567.89\)')416 2001 y(>>>)g(moneyfmt\(Decimal\(123456789\),)c (sep=')k('\))416 2092 y('123)g(456)g(789.00')416 2183 y(>>>)g(moneyfmt\(Decimal\('-0.02'\),)c(neg='<',)k(trailneg='>'\))416 2275 y('<.02>')416 2457 y(""")416 2549 y(q)g(=)h(Decimal\(\(0,)e (\(1,\),)h(-places\)\))178 b(#)44 b(2)h(places)f(-->)g('0.01')416 2640 y(sign,)g(digits,)f(exp)i(=)f(value.quantize\(q\).as_tuple\(\))416 2731 y(assert)f(exp)i(==)f(-places)416 2823 y(result)f(=)i([])416 2914 y(digits)e(=)i(map\(str,)f(digits\))416 3005 y(build,)f(next)i(=)f (result.append,)f(digits.pop)416 3097 y(if)h(sign:)595 3188 y(build\(trailneg\))416 3279 y(for)g(i)h(in)f(range\(places\):)595 3371 y(if)g(digits:)774 3462 y(build\(next\(\)\))595 3553 y(else:)774 3645 y(build\('0'\))416 3736 y(build\(dp\))416 3827 y(i)g(=)h(0)416 3919 y(while)f(digits:)595 4010 y(build\(next\(\)\))595 4101 y(i)h(+=)f(1)595 4193 y(if)g(i)h(==)g(3)f (and)h(digits:)774 4284 y(i)g(=)g(0)774 4375 y(build\(sep\))416 4467 y(build\(curr\))416 4558 y(if)f(sign:)595 4649 y(build\(neg\))416 4741 y(else:)595 4832 y(build\(pos\))416 4923 y(result.reverse\(\))416 5015 y(return)f(''.join\(result\))236 5197 y(def)i(pi\(\):)416 5289 y("""Compute)e(Pi)h(to)h(the)f(current)g(precision.)416 5471 y(>>>)g(print)g(pi\(\))416 5562 y(3.141592653589793238462643383) 416 5745 y(""")416 5836 y(getcontext\(\).prec)e(+=)i(2)90 b(#)44 b(extra)g(digits)g(for)g(intermediate)f(steps)416 5928 y(three)h(=)g(Decimal\(3\))268 b(#)44 b(substitute)f("three=3.0")g (for)i(regular)e(floats)416 6019 y(lasts,)g(t,)i(s,)f(n,)h(na,)f(d,)h (da)f(=)h(0,)f(three,)g(3,)h(1,)f(0,)h(0,)f(24)416 6110 y(while)g(s)g(!=)h(lasts:)595 6202 y(lasts)f(=)h(s)595 6293 y(n,)f(na)h(=)g(n+na,)f(na+8)595 6384 y(d,)g(da)h(=)g(d+da,)f (da+32)595 6476 y(t)h(=)f(\(t)909 6489 y(*)998 6476 y(n\))h(/)g(d)595 6567 y(s)g(+=)f(t)416 6658 y(getcontext\(\).prec)e(-=)i(2)416 6750 y(return)f(+s)673 b(#)44 b(unary)g(plus)g(applies)g(the)g(new)h (precision)236 6932 y(def)g(exp\(x\):)416 7024 y("""Return)e(e)i (raised)e(to)i(the)f(power)g(of)h(x.)89 b(Result)44 b(type)g(matches)g (input)g(type.)416 7206 y(>>>)g(print)g(exp\(Decimal\(1\)\))416 7298 y(2.718281828459045235360287471)416 7389 y(>>>)g(print)g (exp\(Decimal\(2\)\))416 7480 y(7.389056098930650227230427461)416 7572 y(>>>)g(print)g(exp\(2.0\))416 7663 y(7.38905609893)416 7754 y(>>>)g(print)g(exp\(2+0j\))416 7846 y(\(7.38905609893+0j\))416 8028 y(""")416 8120 y(getcontext\(\).prec)e(+=)i(2)416 8211 y(i,)g(lasts,)g(s,)g(fact,)g(num)h(=)f(0,)h(0,)f(1,)h(1,)f(1)416 8302 y(while)g(s)g(!=)h(lasts:)595 8394 y(lasts)f(=)h(s)595 8485 y(i)g(+=)f(1)595 8576 y(fact)819 8589 y(*)864 8576 y(=)h(i)595 8667 y(num)774 8680 y(*)819 8667 y(=)g(x)595 8759 y(s)g(+=)f(num)g(/)h(fact)416 8850 y(getcontext\(\).prec)d(-=)i(2) 416 8941 y(return)f(+s)236 9124 y(def)i(cos\(x\):)416 9215 y("""Return)e(the)h(cosine)g(of)h(x)f(as)h(measured)e(in)i (radians.)416 9398 y(>>>)f(print)g(cos\(Decimal\('0.5'\)\))416 9489 y(0.8775825618903727161162815826)416 9581 y(>>>)g(print)g (cos\(0.5\))416 9672 y(0.87758256189)416 9763 y(>>>)g(print)g (cos\(0.5+0j\))416 9855 y(\(0.87758256189+0j\))416 10037 y(""")416 10129 y(getcontext\(\).prec)e(+=)i(2)416 10220 y(i,)g(lasts,)g(s,)g(fact,)g(num,)h(sign)f(=)g(0,)h(0,)f(1,)h(1,)f(1,)h (1)416 10311 y(while)f(s)g(!=)h(lasts:)595 10403 y(lasts)f(=)h(s)595 10494 y(i)g(+=)f(2)595 10585 y(fact)819 10598 y(*)864 10585 y(=)h(i)1043 10598 y(*)1133 10585 y(\(i-1\))595 10677 y(num)774 10690 y(*)819 10677 y(=)g(x)998 10690 y(*)1088 10677 y(x)595 10768 y(sign)819 10781 y(*)864 10768 y(=)g(-1)595 10859 y(s)g(+=)f(num)g(/)h(fact)1312 10872 y(*)1402 10859 y(sign)416 10951 y(getcontext\(\).prec)d(-=)i(2) 416 11042 y(return)f(+s)236 11225 y(def)i(sin\(x\):)416 11316 y("""Return)e(the)h(sine)g(of)h(x)g(as)f(measured)f(in)i (radians.)416 11499 y(>>>)f(print)g(sin\(Decimal\('0.5'\)\))416 11590 y(0.4794255386042030002732879352)416 11681 y(>>>)g(print)g (sin\(0.5\))416 11773 y(0.479425538604)416 11864 y(>>>)g(print)g (sin\(0.5+0j\))416 11955 y(\(0.479425538604+0j\))416 12138 y(""")416 12229 y(getcontext\(\).prec)e(+=)i(2)416 12320 y(i,)g(lasts,)g(s,)g(fact,)g(num,)h(sign)f(=)g(1,)h(0,)f(x,)h(1,) f(x,)h(1)416 12412 y(while)f(s)g(!=)h(lasts:)595 12503 y(lasts)f(=)h(s)595 12594 y(i)g(+=)f(2)595 12686 y(fact)819 12699 y(*)864 12686 y(=)h(i)1043 12699 y(*)1133 12686 y(\(i-1\))595 12777 y(num)774 12790 y(*)819 12777 y(=)g(x)998 12790 y(*)1088 12777 y(x)595 12868 y(sign)819 12881 y(*)864 12868 y(=)g(-1)595 12960 y(s)g(+=)f(num)g(/)h(fact)1312 12973 y(*)1402 12960 y(sign)416 13051 y(getcontext\(\).prec)d(-=)i(2) 416 13142 y(return)f(+s)p 0 5549 3901 4 v 0 5649 a FI(166)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 167 179 TeXDict begin 167 178 bop 0 83 a Fv(6.3.8)100 b(Decimal)29 b(F)-8 b(A)m(Q)0 286 y FN(Q.)22 b(It)g(is)g(cumbersome)e(to)i(type)f FJ(decimal.Decimal\('1234.5'\))p FN(.)k(Is)d(there)f(a)i(w)o(ay)e(to)h (minimize)f(typing)f(when)h(using)h(the)0 386 y(interacti)n(v)o(e)d (interpreter?)0 532 y(A.)h(Some)g(users)h(abbre)n(viate)d(the)i (constructor)f(to)h(just)h(a)f(single)g(letter:)236 679 y FA(>>>)45 b(D)f(=)h(decimal.Decimal)236 771 y(>>>)g(D\('1.23'\))e(+)i (D\('3.45'\))236 862 y(Decimal\("4.68"\))0 1148 y FN(Q.)18 b(In)g(a)h(\002x)o(ed-point)d(application)g(with)j(tw)o(o)f(decimal)g (places,)g(some)g(inputs)g(ha)n(v)o(e)f(man)o(y)g(places)h(and)g(need)f (to)i(be)f(rounded.)k(Others)0 1248 y(are)e(not)g(supposed)f(to)h(ha)n (v)o(e)g(e)o(xcess)g(digits)g(and)g(need)f(to)i(be)f(v)n(alidated.)k (What)c(methods)f(should)g(be)i(used?)0 1395 y(A.)d(The)g FJ(quantize\(\))e FN(method)h(rounds)g(to)h(a)g(\002x)o(ed)f(number)g (of)g(decimal)h(places.)24 b(If)18 b(the)g FJ(Inexact)f FN(trap)g(is)i(set,)g(it)g(is)g(also)f(useful)0 1495 y(for)i(v)n(alidation:)236 1733 y FA(>>>)45 b(TWOPLACES)e(=)i (Decimal\(10\))1492 1746 y(**)1626 1733 y(-2)313 b(#)45 b(same)f(as)h(Decimal\('0.01'\))236 1915 y(>>>)g(#)f(Round)g(to)h(two)f (places)236 2007 y(>>>)h(Decimal\("3.214"\).quantize\(TWOPLACES\))236 2098 y(Decimal\("3.21"\))236 2281 y(>>>)g(#)f(Validate)g(that)g(a)h (number)e(does)i(not)f(exceed)g(two)g(places)236 2372 y(>>>)h(Decimal\("3.21"\).quantize\(TWOPLACES,)38 b (context=Context\(traps=[Inexact]\)\))236 2463 y(Decimal\("3.21"\))236 2646 y(>>>)45 b(Decimal\("3.214"\).quantize\(TWOPLACES,)38 b(context=Context\(traps=[Inexact]\)\))236 2737 y(Traceback)44 b(\(most)g(recent)f(call)i(last\):)371 2829 y(...)236 2920 y(Inexact:)f(Changed)f(in)i(rounding)0 3207 y FN(Q.)20 b(Once)g(I)h(ha)n(v)o(e)e(v)n(alid)h(tw)o(o)h(place)e(inputs,)h(ho)n(w) g(do)f(I)i(maintain)e(that)h(in)m(v)n(ariant)f(throughout)e(an)j (application?)0 3353 y(A.)k(Some)g(operations)f(lik)o(e)h(addition)f (and)h(subtraction)e(automatically)h(preserv)o(e)g(\002x)o(ed)g(point.) 36 b(Others,)25 b(lik)o(e)f(multiplication)f(and)0 3453 y(di)n(vision,)c(change)g(the)h(number)e(of)i(decimal)g(places)g(and)g (need)f(to)i(be)f(follo)n(wed-up)d(with)k(a)f FJ(quantize\(\))f FN(step.)0 3600 y(Q.)25 b(There)g(are)g(man)o(y)f(w)o(ays)h(to)g(e)o (xpress)g(the)g(same)g(v)n(alue.)39 b(The)25 b(numbers)f FJ(200)p FN(,)i FJ(200.000)p FN(,)f FJ(2E2)p FN(,)h(and)f FJ(.02E+4)f FN(all)i(ha)n(v)o(e)f(the)0 3699 y(same)20 b(v)n(alue)g(at)h(v)n(arious)e(precisions.)24 b(Is)c(there)g(a)h(w)o (ay)f(to)g(transform)f(them)h(to)g(a)h(single)f(recognizable)e (canonical)h(v)n(alue?)0 3846 y(A.)h(The)g FJ(normalize\(\))f FN(method)g(maps)h(all)h(equi)n(v)n(alent)d(v)n(alues)i(to)g(a)h (single)f(representati)n(v)o(e:)236 4085 y FA(>>>)45 b(values)e(=)i(map\(Decimal,)e('200)h(200.000)g(2E2)g (.02E+4'.split\(\)\))236 4176 y(>>>)h([v.normalize\(\))d(for)i(v)h(in)g (values])236 4267 y([Decimal\("2E+2"\),)d(Decimal\("2E+2"\),)g (Decimal\("2E+2"\),)g(Decimal\("2E+2"\)])0 4554 y FN(Q.)17 b(Some)f(decimal)g(v)n(alues)g(al)o(w)o(ays)h(print)e(with)i(e)o (xponential)d(notation.)22 b(Is)17 b(there)f(a)h(w)o(ay)g(to)f(get)h(a) g(non-e)o(xponential)12 b(representation?)0 4701 y(A.)27 b(F)o(or)g(some)g(v)n(alues,)h(e)o(xponential)d(notation)h(is)i(the)f (only)g(w)o(ay)g(to)g(e)o(xpress)g(the)g(number)e(of)i(signi\002cant)g (places)g(in)g(the)g(coef)n(\002-)0 4800 y(cient.)35 b(F)o(or)23 b(e)o(xample,)g(e)o(xpressing)e FJ(5.0E+3)i FN(as)i FJ(5000)e FN(k)o(eeps)g(the)h(v)n(alue)e(constant)h(b)n(ut)h (cannot)e(sho)n(w)h(the)h(original')-5 b(s)22 b(tw)o(o-place)0 4900 y(signi\002cance.)0 5047 y(Q.)e(Is)h(there)f(a)g(w)o(ay)h(to)f (con)m(v)o(ert)e(a)j(re)o(gular)d(\003oat)j(to)f(a)h FJ(Decimal)p FN(?)0 5194 y(A.)g(Y)-8 b(es,)22 b(all)g(binary)e (\003oating)g(point)g(numbers)g(can)h(be)g(e)o(xactly)f(e)o(xpressed)g (as)i(a)g(Decimal.)27 b(An)21 b(e)o(xact)g(con)m(v)o(ersion)e(may)h (tak)o(e)h(more)0 5293 y(precision)e(than)h(intuition)f(w)o(ould)h (suggest,)f(so)i(trapping)d FJ(Inexact)i FN(will)g(signal)h(a)f(need)g (for)f(more)h(precision:)p 0 5549 3901 4 v 0 5649 a FI(6.3.)52 b FJ(decimal)22 b FI(\227)h(Decimal)h(\003oating)g(point)g(ar)q (ithmetic)1917 b(167)p eop end %%Page: 168 180 TeXDict begin 168 179 bop 236 174 a FA(def)45 b(floatToDecimal\(f\):) 416 266 y("Convert)e(a)i(floating)e(point)h(number)g(to)g(a)h(Decimal)f (with)g(no)g(loss)h(of)f(information")416 357 y(#)g(Transform)g (\(exactly\))f(a)i(float)f(to)g(a)h(mantissa)e(\(0.5)h(<=)h(abs\(m\))f (<)g(1.0\))g(and)h(an)416 448 y(#)f(exponent.)88 b(Double)44 b(the)h(mantissa)e(until)h(it)g(is)h(an)f(integer.)89 b(Use)44 b(the)g(integer)416 540 y(#)g(mantissa)g(and)g(exponent)g(to)g (compute)g(an)g(equivalent)f(Decimal.)89 b(If)44 b(this)g(cannot)416 631 y(#)g(be)h(done)f(exactly,)f(then)i(retry)f(with)g(more)g (precision.)416 814 y(mantissa,)f(exponent)g(=)i(math.frexp\(f\))416 905 y(while)f(mantissa)f(!=)i(int\(mantissa\):)595 996 y(mantissa)998 1009 y(*)1043 996 y(=)g(2.0)595 1088 y(exponent)e(-=)i (1)416 1179 y(mantissa)e(=)i(int\(mantissa\))416 1362 y(oldcontext)e(=)h(getcontext\(\))416 1453 y (setcontext\(Context\(traps=[Inexact]\)\))416 1544 y(try:)595 1636 y(while)g(True:)774 1727 y(try:)909 1818 y(return)g(mantissa)1626 1831 y(*)1716 1818 y(Decimal\(2\))2209 1831 y(**)2343 1818 y(exponent)774 1910 y(except)g(Inexact:)954 2001 y(getcontext\(\).prec)e(+=)i(1)416 2092 y(finally:)595 2183 y(setcontext\(oldcontext\))0 2470 y FN(Q.)20 b(Why)g(isn')o(t)g (the)g FJ(floatToDecimal\(\))e FN(routine)h(included)g(in)h(the)g (module?)0 2617 y(A.)e(There)g(is)g(some)g(question)f(about)g(whether)g (it)i(is)g(advisable)e(to)h(mix)g(binary)f(and)g(decimal)h(\003oating)f (point.)24 b(Also,)18 b(its)h(use)g(requires)0 2716 y(some)h(care)g(to) g(a)n(v)n(oid)g(the)g(representation)f(issues)i(associated)f(with)g (binary)f(\003oating)g(point:)236 2955 y FA(>>>)45 b (floatToDecimal\(1.1\))236 3046 y (Decimal\("1.10000000000000008881784197001)o(252323)o(389053)o(344726)o (5625"\))0 3333 y FN(Q.)25 b(W)m(ithin)f(a)h(comple)o(x)d(calculation,) i(ho)n(w)g(can)g(I)g(mak)o(e)g(sure)h(that)f(I)h(ha)n(v)o(en')o(t)d (gotten)h(a)i(spurious)e(result)i(because)e(of)h(insuf)n(\002cient)0 3432 y(precision)19 b(or)h(rounding)e(anomalies.)0 3579 y(A.)24 b(The)f(decimal)f(module)g(mak)o(es)h(it)i(easy)e(to)g(test)i (results.)34 b(A)24 b(best)g(practice)f(is)h(to)f(re-run)f (calculations)g(using)h(greater)g(precision)0 3679 y(and)31 b(with)g(v)n(arious)f(rounding)f(modes.)57 b(W)m(idely)31 b(dif)n(fering)f(results)h(indicate)g(insuf)n(\002cient)f(precision,)j (rounding)c(mode)h(issues,)0 3778 y(ill-conditioned)18 b(inputs,)h(or)h(a)h(numerically)d(unstable)i(algorithm.)0 3925 y(Q.)27 b(I)g(noticed)f(that)i(conte)o(xt)d(precision)h(is)i (applied)e(to)h(the)g(results)h(of)e(operations)g(b)n(ut)h(not)f(to)i (the)f(inputs.)44 b(Is)28 b(there)f(an)o(ything)d(to)0 4025 y(w)o(atch)c(out)g(for)g(when)f(mixing)g(v)n(alues)h(of)g(dif)n (ferent)e(precisions?)0 4172 y(A.)24 b(Y)-8 b(es.)36 b(The)23 b(principle)g(is)h(that)g(all)h(v)n(alues)e(are)h(considered)e (to)i(be)f(e)o(xact)g(and)h(so)g(is)g(the)g(arithmetic)f(on)g(those)h (v)n(alues.)35 b(Only)24 b(the)0 4271 y(results)18 b(are)f(rounded.)22 b(The)17 b(adv)n(antage)e(for)i(inputs)g(is)h(that)f(\223what)h(you)e (type)h(is)h(what)g(you)e(get\224.)24 b(A)18 b(disadv)n(antage)d(is)j (that)g(the)f(results)0 4371 y(can)j(look)f(odd)h(if)g(you)f(for)o(get) g(that)h(the)g(inputs)g(ha)n(v)o(en')o(t)f(been)g(rounded:)236 4609 y FA(>>>)45 b(getcontext\(\).prec)d(=)i(3)236 4700 y(>>>)h(Decimal\('3.104'\))d(+)i(D\('2.104'\))236 4792 y(Decimal\("5.21"\))236 4883 y(>>>)h(Decimal\('3.104'\))d(+)i (D\('0.000'\))g(+)g(D\('2.104'\))236 4974 y(Decimal\("5.20"\))0 5261 y FN(The)20 b(solution)f(is)i(either)f(to)g(increase)g(precision)f (or)h(to)h(force)e(rounding)e(of)j(inputs)g(using)g(the)g(unary)f(plus) h(operation:)p 0 5549 3901 4 v 0 5649 a FI(168)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 169 181 TeXDict begin 169 180 bop 236 174 a FA(>>>)45 b(getcontext\(\).prec)d (=)i(3)236 266 y(>>>)h(+Decimal\('1.23456789'\))265 b(#)45 b(unary)e(plus)i(triggers)e(rounding)236 357 y(Decimal\("1.23"\))0 644 y FN(Alternati)n(v)o(ely)-5 b(,)18 b(inputs)i(can)g(be)g(rounded)e (upon)g(creation)i(using)f(the)h FJ(Context.create_decimal\(\))d FN(method:)236 882 y FA(>>>)45 b(Context\(prec=5,)d (rounding=ROUND_DOWN\).create_decimal\('1)o(.23456)o(78'\))236 973 y(Decimal\("1.2345"\))0 1483 y FE(6.4)121 b Fx(random)31 b FE(\227)i(Gener)o(ate)j(pseudo-r)o(andom)g(n)o(umbers)0 1716 y FN(This)20 b(module)f(implements)g(pseudo-random)e(number)h (generators)h(for)g(v)n(arious)g(distrib)n(utions.)0 1863 y(F)o(or)26 b(inte)o(gers,)h(uniform)e(selection)h(from)f(a)i (range.)43 b(F)o(or)26 b(sequences,)h(uniform)e(selection)h(of)g(a)h (random)e(element,)i(a)g(function)d(to)0 1962 y(generate)19 b(a)i(random)d(permutation)g(of)i(a)g(list)i(in-place,)d(and)g(a)i (function)d(for)i(random)e(sampling)i(without)f(replacement.)0 2109 y(On)f(the)h(real)f(line,)h(there)f(are)g(functions)f(to)i (compute)e(uniform,)f(normal)i(\(Gaussian\),)f(lognormal,)g(ne)o(gati)n (v)o(e)f(e)o(xponential,)g(gamma,)0 2209 y(and)k(beta)g(distrib)n (utions.)k(F)o(or)c(generating)e(distrib)n(utions)h(of)h(angles,)g(the) g(v)n(on)f(Mises)i(distrib)n(ution)e(is)j(a)n(v)n(ailable.)0 2356 y(Almost)h(all)g(module)e(functions)h(depend)f(on)h(the)g(basic)h (function)e FJ(random\(\))p FN(,)h(which)h(generates)e(a)i(random)e (\003oat)i(uniformly)d(in)0 2455 y(the)j(semi-open)e(range)g([0.0,)h (1.0\).)31 b(Python)22 b(uses)h(the)f(Mersenne)g(T)-7 b(wister)23 b(as)g(the)g(core)f(generator)-5 b(.)30 b(It)23 b(produces)e(53-bit)h(precision)0 2555 y(\003oats)d(and)f(has)h(a)g (period)f(of)g(2**19937-1.)j(The)d(underlying)e(implementation)g(in)j (C)h(is)g(both)e(f)o(ast)h(and)f(threadsafe.)23 b(The)c(Mersenne)0 2655 y(T)-7 b(wister)29 b(is)h(one)e(of)g(the)h(most)g(e)o(xtensi)n(v)o (ely)e(tested)h(random)f(number)g(generators)g(in)i(e)o(xistence.)50 b(Ho)n(we)n(v)o(er)m(,)28 b(being)g(completely)0 2754 y(deterministic,)19 b(it)i(is)g(not)f(suitable)g(for)g(all)g(purposes,) f(and)h(is)h(completely)d(unsuitable)h(for)h(cryptographic)d(purposes.) 0 2901 y(The)e(functions)f(supplied)g(by)h(this)h(module)e(are)h (actually)g(bound)f(methods)g(of)h(a)h(hidden)e(instance)h(of)g(the)g FJ(random.Random)f FN(class.)0 3001 y(Y)-9 b(ou)23 b(can)h(instantiate) f(your)f(o)n(wn)i(instances)f(of)h FJ(Random)f FN(to)g(get)h (generators)e(that)i(don')o(t)e(share)h(state.)36 b(This)24 b(is)h(especially)e(useful)0 3100 y(for)d(multi-threaded)f(programs,)g (creating)h(a)i(dif)n(ferent)d(instance)i(of)g FJ(Random)f FN(for)h(each)g(thread,)f(and)g(using)h(the)g FJ(jumpahead\(\))0 3200 y FN(method)e(to)h(mak)o(e)g(it)h(lik)o(ely)f(that)g(the)g (generated)f(sequences)g(seen)h(by)g(each)g(thread)f(don')o(t)g(o)o(v)o (erlap.)0 3347 y(Class)h FJ(Random)e FN(can)g(also)h(be)f(subclassed)g (if)h(you)f(w)o(ant)g(to)h(use)g(a)g(dif)n(ferent)d(basic)j(generator)e (of)h(your)f(o)n(wn)h(de)n(vising:)23 b(in)c(that)f(case,)0 3447 y(o)o(v)o(erride)h(the)j FJ(random\(\))p FN(,)f FJ(seed\(\))p FN(,)g FJ(getstate\(\))p FN(,)g FJ(setstate\(\))f FN(and)i FJ(jumpahead\(\))e FN(methods.)28 b(Optionally)-5 b(,)21 b(a)h(ne)n(w)0 3546 y(generator)i(can)h(supply)g(a)h FJ(getrandombits\(\))e FN(method)g(\227)i(this)h(allo)n(ws)f FJ(randrange\(\))e FN(to)i(produce)e(selections)h(o)o(v)o(er)g(an)0 3646 y(arbitrarily)19 b(lar)o(ge)g(range.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4:)h(the)g FJ(getrandombits\(\))e FN(method.)0 3793 y(As)e(an)g(e)o(xample)e(of)i(subclassing,)f(the)h FJ(random)f FN(module)g(pro)o(vides)e(the)j FJ(WichmannHill)e FN(class)j(that)f(implements)e(an)i(alternati)n(v)o(e)0 3892 y(generator)i(in)h(pure)g(Python.)k(The)d(class)g(pro)o(vides)e(a) i(backw)o(ard)e(compatible)g(w)o(ay)h(to)h(reproduce)d(results)j(from)e (earlier)h(v)o(ersions)g(of)0 3992 y(Python,)i(which)h(used)g(the)g(W)m (ichmann-Hill)f(algorithm)f(as)j(the)g(core)e(generator)-5 b(.)30 b(Note)22 b(that)g(this)h(W)m(ichmann-Hill)e(generator)f(can)0 4092 y(no)e(longer)f(be)h(recommended:)j(its)e(period)e(is)i(too)f (short)g(by)g(contemporary)d(standards,)i(and)h(the)g(sequence)f (generated)g(is)i(kno)n(wn)d(to)0 4191 y(f)o(ail)22 b(some)f(stringent) g(randomness)f(tests.)30 b(See)22 b(the)f(references)f(belo)n(w)h(for)g (a)h(recent)f(v)n(ariant)f(that)i(repairs)f(these)h(\003a)o(ws.)59 b(Changed)0 4291 y(in)20 b(v)o(ersion)f(2.3:)h(Substituted)f(MersenneT) -7 b(wister)19 b(for)h(W)m(ichmann-Hill.)0 4438 y(Bookk)o(eeping)e (functions:)0 4585 y FD(seed)p FJ(\()p FC([)p FK(x)12 b FC(])p FJ(\))208 4684 y FN(Initialize)18 b(the)g(basic)g(random)f (number)f(generator)-5 b(.)23 b(Optional)17 b(ar)o(gument)f FK(x)j FN(can)f(be)g(an)o(y)g(hashable)f(object.)24 b(If)18 b FK(x)h FN(is)g(omitted)f(or)208 4784 y FJ(None)p FN(,)h(current)g (system)i(time)f(is)h(used;)f(current)f(system)h(time)h(is)g(also)f (used)g(to)g(initialize)h(the)f(generator)e(when)i(the)g(module)208 4883 y(is)30 b(\002rst)h(imported.)51 b(If)30 b(randomness)e(sources)h (are)h(pro)o(vided)d(by)i(the)h(operating)e(system,)k(the)o(y)d(are)g (used)h(instead)f(of)h(the)208 4983 y(system)22 b(time)g(\(see)g(the)g FJ(os.urandom\(\))e FN(function)g(for)i(details)g(on)f(a)n(v)n (ailability\).)60 b(Changed)21 b(in)h(v)o(ersion)f(2.4:)g(formerly)-5 b(,)208 5083 y(operating)19 b(system)i(resources)f(were)i(not)e(used.) 57 b(If)21 b FK(x)h FN(is)g(not)f FJ(None)g FN(or)f(an)i(int)f(or)g (long,)f FJ(hash\()p FK(x)p FJ(\))h FN(is)h(used)f(instead.)28 b(If)21 b FK(x)h FN(is)208 5182 y(an)e(int)g(or)g(long,)f FK(x)i FN(is)g(used)f(directly)-5 b(.)0 5329 y FD(getstate)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(6.4.)52 b FJ(random)22 b FI(\227)h(Gener)o(ate)h(pseudo-r)o(andom)f(n)o(umbers)1850 b(169)p eop end %%Page: 170 182 TeXDict begin 170 181 bop 208 83 a FN(Return)16 b(an)g(object)h (capturing)d(the)j(current)f(internal)f(state)j(of)e(the)h(generator)-5 b(.)22 b(This)17 b(object)f(can)h(be)f(passed)h(to)g FJ(setstate\(\))208 183 y FN(to)j(restore)g(the)g(state.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 330 y FD(setstate)p FJ(\()p FK(state)p FJ(\))208 429 y FK(state)g FN(should)g(ha)n(v)o(e)g (been)g(obtained)f(from)g(a)i(pre)n(vious)e(call)i(to)f FJ(getstate\(\))p FN(,)f(and)h FJ(setstate\(\))g FN(restores)g(the)g (internal)208 529 y(state)h(of)g(the)h(generator)d(to)i(what)g(it)h(w)o (as)g(at)g(the)f(time)h FJ(setstate\(\))d FN(w)o(as)j(called.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 676 y FD(jumpahead)p FJ(\()p FK(n)p FJ(\))208 775 y FN(Change)24 b(the)g(internal)g(state)i (to)f(one)f(dif)n(ferent)f(from)h(and)g(lik)o(ely)h(f)o(ar)g(a)o(w)o (ay)f(from)g(the)h(current)e(state.)40 b FK(n)25 b FN(is)g(a)h(non-ne)o (gati)n(v)o(e)208 875 y(inte)o(ger)e(which)h(is)h(used)f(to)h(scramble) e(the)i(current)e(state)i(v)o(ector)-5 b(.)39 b(This)26 b(is)g(most)g(useful)f(in)g(multi-threaded)e(programs,)h(in)208 975 y(conjuction)f(with)j(multiple)f(instances)h(of)f(the)g FJ(Random)h FN(class:)37 b FJ(setstate\(\))24 b FN(or)h FJ(seed\(\))g FN(can)h(be)f(used)h(to)f(force)g(all)208 1074 y(instances)h(into)g(the)g(same)h(internal)e(state,)k(and)d(then)g FJ(jumpahead\(\))e FN(can)j(be)f(used)g(to)h(force)e(the)h(instances')g (states)i(f)o(ar)208 1174 y(apart.)87 b(Ne)n(w)26 b(in)h(v)o(ersion)e (2.1.)131 b(Changed)25 b(in)i(v)o(ersion)e(2.3:)h(Instead)f(of)h (jumping)f(to)i(a)f(speci\002c)h(state,)h FK(n)f FN(steps)g(ahead,)208 1273 y FJ(jumpahead\()p FK(n)p FJ(\))18 b FN(jumps)i(to)g(another)f (state)i(lik)o(ely)f(to)g(be)g(separated)f(by)h(man)o(y)f(steps.)0 1420 y FD(getrandbits)p FJ(\()p FK(k)q FJ(\))208 1520 y FN(Returns)e(a)g(p)o(ython)f FJ(long)h FN(int)h(with)f FK(k)i FN(random)d(bits.)24 b(This)18 b(method)d(is)k(supplied)d(with)h (the)h(MersenneT)-7 b(wister)16 b(generator)f(and)208 1620 y(some)23 b(other)g(generators)f(may)h(also)h(pro)o(vide)e(it)i (as)h(an)e(optional)g(part)g(of)h(the)f(API.)h(When)g(a)n(v)n(ailable,) f FJ(getrandbits\(\))208 1719 y FN(enables)c FJ(randrange\(\))g FN(to)h(handle)f(arbitrarily)g(lar)o(ge)g(ranges.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 1866 y(Functions)g(for)h(inte)o (gers:)0 2013 y FD(randrange)p FJ(\()p FC([)p FK(start,)12 b FC(])18 b FK(stop)p FC([)p FK(,)i(step)12 b FC(])p FJ(\))208 2113 y FN(Return)70 b(a)g(randomly)f(selected)h(element)g (from)f FJ(range\()p FK(start)q FJ(,)50 b FK(stop)p FJ(,)f FK(step)p FJ(\))p FN(.)176 b(This)70 b(is)i(equi)n(v)n(alent)c(to)208 2212 y FJ(choice\(range\()p FK(start)q FJ(,)48 b FK(stop)p FJ(,)h FK(step)p FJ(\)\))p FN(,)19 b(b)n(ut)i(doesn')o(t)d(actually)i (b)n(uild)g(a)g(range)f(object.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f (1.5.2.)0 2359 y FD(randint)p FJ(\()p FK(a,)g(b)p FJ(\))208 2459 y FN(Return)g(a)i(random)d(inte)o(ger)h FK(N)26 b FN(such)20 b(that)h FK(a)49 b FJ(<=)g FK(N)56 b FJ(<=)49 b FK(b)p FN(.)0 2606 y(Functions)19 b(for)h(sequences:)0 2752 y FD(choice)p FJ(\()p FK(seq)p FJ(\))208 2852 y FN(Return)f(a)i(random)d(element)i(from)f(the)h(non-empty)e(sequence)h FK(seq)p FN(.)25 b(If)20 b FK(seq)g FN(is)i(empty)-5 b(,)18 b(raises)j FJ(IndexError)p FN(.)0 2999 y FD(shuffle)p FJ(\()p FK(x)p FC([)p FK(,)e(r)o(andom)12 b FC(])p FJ(\))208 3099 y FN(Shuf)n(\003e)25 b(the)g(sequence)g FK(x)h FN(in)g(place.)41 b(The)25 b(optional)g(ar)o(gument)e FK(r)o(andom)h FN(is)j(a)f(0-ar)o (gument)d(function)h(returning)f(a)j(random)208 3198 y(\003oat)20 b(in)g([0.0,)f(1.0\);)g(by)h(def)o(ault,)f(this)i(is)g (the)g(function)d FJ(random\(\))p FN(.)208 3328 y(Note)i(that)h(for)g (e)n(v)o(en)f(rather)g(small)h FJ(len\()p FK(x)p FJ(\))p FN(,)g(the)g(total)g(number)e(of)h(permutations)f(of)i FK(x)h FN(is)f(lar)o(ger)f(than)g(the)h(period)f(of)h(most)208 3427 y(random)d(number)g(generators;)h(this)i(implies)f(that)g(most)g (permutations)f(of)h(a)g(long)g(sequence)f(can)h(ne)n(v)o(er)e(be)j (generated.)0 3574 y FD(sample)p FJ(\()p FK(population,)16 b(k)q FJ(\))208 3674 y FN(Return)28 b(a)h FK(k)i FN(length)d(list)i(of) e(unique)g(elements)g(chosen)g(from)g(the)h(population)e(sequence.)49 b(Used)29 b(for)g(random)e(sampling)208 3774 y(without)19 b(replacement.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)208 3903 y(Returns)26 b(a)g(ne)n(w)g(list)h(containing)d(elements)i(from)f (the)h(population)e(while)i(lea)n(ving)g(the)g(original)f(population)f (unchanged.)208 4003 y(The)19 b(resulting)g(list)h(is)h(in)f(selection) f(order)g(so)h(that)f(all)i(sub-slices)e(will)i(also)f(be)f(v)n(alid)g (random)f(samples.)25 b(This)20 b(allo)n(ws)g(raf)n(\003e)208 4102 y(winners)f(\(the)h(sample\))g(to)g(be)g(partitioned)f(into)h (grand)e(prize)i(and)g(second)f(place)h(winners)f(\(the)h(subslices\).) 208 4232 y(Members)f(of)h(the)g(population)d(need)j(not)f(be)h (hashable)g(or)f(unique.)24 b(If)c(the)g(population)d(contains)j (repeats,)f(then)h(each)g(occur)n(-)208 4332 y(rence)f(is)i(a)g (possible)f(selection)g(in)g(the)g(sample.)208 4461 y(T)-7 b(o)22 b(choose)g(a)g(sample)g(from)g(a)h(range)e(of)h(inte)o(gers,)g (use)g(an)h FJ(xrange\(\))e FN(object)h(as)h(an)f(ar)o(gument.)29 b(This)23 b(is)g(especially)f(f)o(ast)208 4561 y(and)d(space)h(ef)n (\002cient)g(for)g(sampling)f(from)g(a)i(lar)o(ge)e(population:)k FJ(sample\(xrange\(10000000\),)45 b(60\))p FN(.)0 4708 y(The)26 b(follo)n(wing)f(functions)g(generate)g(speci\002c)h(real-v)n (alued)e(distrib)n(utions.)43 b(Function)25 b(parameters)g(are)h(named) g(after)f(the)i(corre-)0 4807 y(sponding)21 b(v)n(ariables)i(in)g(the)g (distrib)n(ution')-5 b(s)23 b(equation,)f(as)i(used)f(in)g(common)f (mathematical)g(practice;)i(most)f(of)g(these)h(equations)0 4907 y(can)c(be)g(found)f(in)h(an)o(y)f(statistics)j(te)o(xt.)0 5054 y FD(random)p FJ(\(\))208 5154 y FN(Return)d(the)i(ne)o(xt)e (random)f(\003oating)i(point)f(number)g(in)h(the)g(range)f([0.0,)g (1.0\).)0 5300 y FD(uniform)p FJ(\()p FK(a,)g(b)p FJ(\))208 5400 y FN(Return)g(a)i(random)d(real)j(number)d FK(N)26 b FN(such)20 b(that)g FK(a)50 b FJ(<=)f FK(N)55 b FJ(<)50 b FK(b)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(170)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 171 183 TeXDict begin 171 182 bop 0 83 a FD(betavariate)p FJ(\()p FK(alpha,)16 b(beta)p FJ(\))208 183 y FN(Beta)k(distrib)n(ution.)k (Conditions)19 b(on)g(the)h(parameters)f(are)h FK(alpha)48 b FJ(>)i(0)20 b FN(and)f FK(beta)49 b FJ(>)h(0)p FN(.)25 b(Returned)19 b(v)n(alues)g(range)g(between)208 282 y(0)h(and)f(1.)0 429 y FD(expovariate)p FJ(\()p FK(lambd)r FJ(\))208 529 y FN(Exponential)f(distrib)n(ution.)27 b FK(lambd)22 b FN(is)g(1.0)e(di)n(vided)g(by)h(the)g(desired)f(mean.)27 b(\(The)20 b(parameter)g(w)o(ould)g(be)h(called)g(\223lambda\224,)208 628 y(b)n(ut)f(that)g(is)h(a)g(reserv)o(ed)d(w)o(ord)i(in)g(Python.\))k (Returned)19 b(v)n(alues)h(range)f(from)g(0)h(to)h(positi)n(v)o(e)e (in\002nity)-5 b(.)0 775 y FD(gammavariate)p FJ(\()p FK(alpha,)16 b(beta)p FJ(\))208 875 y FN(Gamma)j(distrib)n(ution.)24 b(\()p FK(Not)c FN(the)g(gamma)f(function!\))k(Conditions)c(on)h(the)g (parameters)f(are)h FK(alpha)48 b FJ(>)i(0)20 b FN(and)g FK(beta)49 b FJ(>)g(0)p FN(.)0 1022 y FD(gauss)p FJ(\()p FK(mu,)19 b(sigma)p FJ(\))208 1121 y FN(Gaussian)29 b(distrib)n(ution.) 52 b FK(mu)30 b FN(is)g(the)g(mean,)h(and)e FK(sigma)h FN(is)g(the)g(standard)e(de)n(viation.)52 b(This)30 b(is)g(slightly)g (f)o(aster)f(than)h(the)208 1221 y FJ(normalvariate\(\))18 b FN(function)g(de\002ned)h(belo)n(w)-5 b(.)0 1368 y FD(lognormvariate)p FJ(\()p FK(mu,)17 b(sigma)p FJ(\))208 1468 y FN(Log)23 b(normal)g(distrib)n(ution.)35 b(If)24 b(you)f(tak)o(e)h(the)g(natural)f(logarithm)f(of)i(this)g(distrib)n (ution,)g(you')o(ll)f(get)h(a)g(normal)f(distrib)n(ution)208 1567 y(with)d(mean)g FK(mu)g FN(and)f(standard)g(de)n(viation)g FK(sigma)p FN(.)25 b FK(mu)20 b FN(can)g(ha)n(v)o(e)g(an)o(y)f(v)n (alue,)g(and)h FK(sigma)g FN(must)g(be)g(greater)g(than)f(zero.)0 1714 y FD(normalvariate)p FJ(\()p FK(mu,)e(sigma)p FJ(\))208 1814 y FN(Normal)i(distrib)n(ution.)24 b FK(mu)c FN(is)h(the)f(mean,)g (and)f FK(sigma)h FN(is)h(the)g(standard)e(de)n(viation.)0 1961 y FD(vonmisesvariate)p FJ(\()p FK(mu,)e(kappa)p FJ(\))208 2060 y FK(mu)g FN(is)i(the)f(mean)f(angle,)h(e)o(xpressed)e (in)i(radians)g(between)f(0)h(and)f(2*)p FK(pi)p FN(,)g(and)h FK(kappa)e FN(is)j(the)f(concentration)d(parameter)m(,)h(which)208 2160 y(must)24 b(be)f(greater)g(than)h(or)f(equal)h(to)g(zero.)35 b(If)24 b FK(kappa)e FN(is)j(equal)f(to)g(zero,)g(this)g(distrib)n (ution)f(reduces)g(to)h(a)g(uniform)e(random)208 2259 y(angle)d(o)o(v)o(er)g(the)h(range)f(0)i(to)f(2*)p FK(pi)p FN(.)0 2406 y FD(paretovariate)p FJ(\()p FK(alpha)p FJ(\))208 2506 y FN(P)o(areto)f(distrib)n(ution.)24 b FK(alpha)19 b FN(is)i(the)f(shape)g(parameter)-5 b(.)0 2653 y FD(weibullvariate)p FJ(\()p FK(alpha,)16 b(beta)p FJ(\))208 2752 y FN(W)-7 b(eib)n(ull)21 b(distrib)n(ution.)i FK(alpha)c FN(is)i(the)f(scale)h (parameter)e(and)g FK(beta)h FN(is)h(the)g(shape)e(parameter)-5 b(.)0 2899 y(Alternati)n(v)o(e)19 b(Generators:)0 3046 y FL(class)i FD(WichmannHill)p FJ(\()p FC([)p FK(seed)11 b FC(])p FJ(\))208 3146 y FN(Class)31 b(that)f(implements)f(the)h(W)m (ichmann-Hill)e(algorithm)g(as)j(the)f(core)f(generator)-5 b(.)53 b(Has)30 b(all)h(of)e(the)h(same)g(methods)f(as)208 3245 y FJ(Random)20 b FN(plus)h(the)h FJ(whseed\(\))e FN(method)g(described)f(belo)n(w)-5 b(.)27 b(Because)22 b(this)g(class)g(is)g(implemented)d(in)i(pure)g(Python,)f(it)i(is)208 3345 y(not)f(threadsafe)f(and)h(may)g(require)f(locks)h(between)g (calls.)30 b(The)21 b(period)f(of)h(the)h(generator)d(is)k (6,953,607,871,64)o(4)16 b(which)21 b(is)208 3445 y(small)f(enough)e (to)j(require)e(care)h(that)g(tw)o(o)g(independent)e(random)g (sequences)i(do)f(not)h(o)o(v)o(erlap.)0 3591 y FD(whseed)p FJ(\()p FC([)p FK(x)12 b FC(])p FJ(\))208 3691 y FN(This)29 b(is)h(obsolete,)h(supplied)d(for)h(bit-le)n(v)o(el)f(compatibility)g (with)i(v)o(ersions)e(of)h(Python)f(prior)g(to)i(2.1.)52 b(See)29 b FJ(seed\(\))g FN(for)208 3791 y(details.)49 b FJ(whseed\(\))28 b FN(does)g(not)g(guarantee)e(that)j(distinct)f (inte)o(ger)g(ar)o(guments)e(yield)i(distinct)g(internal)g(states,)j (and)d(can)208 3890 y(yield)19 b(no)h(more)f(than)h(about)f(2**24)g (distinct)h(internal)f(states)j(in)e(all.)0 4037 y FL(class)h FD(SystemRandom)p FJ(\()p FC([)p FK(seed)11 b FC(])p FJ(\))208 4137 y FN(Class)19 b(that)g(uses)g(the)f FJ(os.urandom\(\))e FN(function)h(for)h(generating)e(random)g(numbers)h(from)h(sources)f (pro)o(vided)f(by)i(the)g(op-)208 4237 y(erating)d(system.)24 b(Not)17 b(a)n(v)n(ailable)g(on)f(all)i(systems.)24 b(Does)17 b(not)f(rely)h(on)f(softw)o(are)h(state)g(and)f(sequences)g(are)h(not)g (reproducible.)208 4336 y(Accordingly)-5 b(,)24 b(the)i FJ(seed\(\))g FN(and)g FJ(jumpahead\(\))e FN(methods)h(ha)n(v)o(e)h(no) g(ef)n(fect)f(and)h(are)g(ignored.)41 b(The)26 b FJ(getstate\(\))208 4436 y FN(and)19 b FJ(setstate\(\))g FN(methods)g(raise)i FJ(NotImplementedError)c FN(if)j(called.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 4583 y(Examples)g(of)h(basic)g(usage:)p 0 5549 3901 4 v 0 5649 a FI(6.4.)52 b FJ(random)22 b FI(\227)h(Gener)o(ate)h(pseudo-r)o(andom)f(n)o(umbers)1850 b(171)p eop end %%Page: 172 184 TeXDict begin 172 183 bop 236 174 a FA(>>>)45 b(random.random\(\))356 b(#)44 b(Random)g(float)g(x,)h(0.0)f(<=)g(x)h(<)g(1.0)236 266 y(0.37444887175646646)236 357 y(>>>)g(random.uniform\(1,)d(10\))89 b(#)44 b(Random)g(float)g(x,)h(1.0)f(<=)g(x)h(<)g(10.0)236 448 y(1.1800146073117523)236 540 y(>>>)g(random.randint\(1,)d(10\))89 b(#)44 b(Integer)g(from)g(1)h(to)f(10,)h(endpoints)e(included)236 631 y(7)236 722 y(>>>)i(random.randrange\(0,)c(101,)j(2\))90 b(#)44 b(Even)g(integer)g(from)g(0)h(to)f(100)236 814 y(26)236 905 y(>>>)h(random.choice\('abcdefghij'\))85 b(#)44 b(Choose)g(a)h(random)f(element)236 996 y('c')236 1179 y(>>>)h(items)f(=)g([1,)h(2,)f(3,)h(4,)f(5,)h(6,)f(7])236 1270 y(>>>)h(random.shuffle\(items\))236 1362 y(>>>)g(items)236 1453 y([7,)g(3,)f(2,)h(5,)f(6,)h(4,)f(1])236 1636 y(>>>)h (random.sample\([1,)d(2,)i(3,)h(4,)f(5],)89 b(3\))g(#)45 b(Choose)f(3)h(elements)236 1727 y([4,)g(1,)f(5])0 2105 y FL(See)21 b(Also:)0 2252 y FN(M.)26 b(Matsumoto)e(and)i(T)-6 b(.)25 b(Nishimura,)h(\223Mersenne)f(T)-7 b(wister:)36 b(A)27 b(623-dimensionally)22 b(equidistrib)n(uted)h(uniform)h (pseudorandom)0 2352 y(number)18 b(generator\224,)g FK(A)n(CM)j(T)-5 b(r)o(ansactions)19 b(on)h(Modeling)f(and)g(Computer)h(Simulation)f FN(V)-11 b(ol.)25 b(8,)20 b(No.)25 b(1,)20 b(January)f(pp.3-30)f(1998.) 0 2499 y(W)m(ichmann,)27 b(B.)h(A.)g(&)f(Hill,)j(I.)d(D.,)i(\223)-7 b(Algorithm)26 b(AS)i(183:)38 b(An)28 b(ef)n(\002cient)f(and)f (portable)g(pseudo-random)d(number)j(generator\224,)0 2598 y FK(Applied)19 b(Statistics)i FN(31)e(\(1982\))g(188-190.)0 2745 y FO(http://www)l(.npl.co)m(.uk/ssfm/do)o(wnl)o(oad)o(/a)o(bstr)o (acts)o(.h)o(tml#1)o(96)208 2845 y FN(A)j(modern)d(v)n(ariation)h(of)h (the)h(W)m(ichmann-Hill)e(generator)f(that)j(greatly)e(increases)i(the) f(period,)f(and)h(passes)h(no)n(w-standard)208 2944 y(statistical)f (tests)g(that)g(the)f(original)f(generator)f(f)o(ailed.)0 3272 y FE(6.5)121 b Fx(itertools)31 b FE(\227)h(Functions)j(creating)f (iter)o(ators)g(f)l(or)g(ef\002cient)h(looping)0 3505 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3652 y(This)33 b(module)e(implements)h(a)h(number)e(of)h(iterator)g(b)n(uilding)f (blocks)h(inspired)g(by)g(constructs)g(from)g(the)g(Hask)o(ell)h(and)f (SML)0 3751 y(programming)17 b(languages.)23 b(Each)d(has)g(been)g (recast)g(in)h(a)f(form)f(suitable)h(for)g(Python.)0 3898 y(The)25 b(module)g(standardizes)f(a)i(core)f(set)i(of)e(f)o(ast,) j(memory)23 b(ef)n(\002cient)j(tools)f(that)h(are)g(useful)f(by)g (themselv)o(es)g(or)g(in)h(combination.)0 3998 y(Standardization)14 b(helps)j(a)n(v)n(oid)g(the)f(readability)g(and)g(reliability)g (problems)f(which)i(arise)g(when)f(man)o(y)f(dif)n(ferent)h(indi)n (viduals)f(create)0 4097 y(their)20 b(o)n(wn)g(slightly)f(v)n(arying)g (implementations,)f(each)i(with)g(their)g(o)n(wn)g(quirks)f(and)h (naming)e(con)m(v)o(entions.)0 4244 y(The)25 b(tools)g(are)g(designed)f (to)h(combine)f(readily)g(with)h(one)g(another)-5 b(.)38 b(This)26 b(mak)o(es)e(it)i(easy)f(to)h(construct)e(more)g(specialized) h(tools)0 4344 y(succinctly)19 b(and)h(ef)n(\002ciently)f(in)i(pure)e (Python.)0 4491 y(F)o(or)28 b(instance,)h(SML)f(pro)o(vides)f(a)h(tab)n (ulation)f(tool:)41 b FJ(tabulate\(f\))27 b FN(which)g(produces)g(a)h (sequence)f FJ(f\(0\),)49 b(f\(1\),)g(...)p FN(.)0 4590 y(This)22 b(toolbox)e(pro)o(vides)g FJ(imap\(\))h FN(and)g FJ(count\(\))g FN(which)h(can)f(be)h(combined)d(to)j(form)f FJ(imap\(f,)49 b(count\(\)\))20 b FN(and)i(produce)0 4690 y(an)e(equi)n(v)n(alent)f(result.)0 4837 y(Lik)o(e)n(wise,)26 b(the)e(functional)f(tools)i(are)g(designed)e(to)i(w)o(ork)f(well)h (with)g(the)g(high-speed)d(functions)h(pro)o(vided)g(by)h(the)g FJ(operator)0 4936 y FN(module.)0 5083 y(The)18 b(module)f(author)g (welcomes)h(suggestions)f(for)h(other)g(basic)g(b)n(uilding)f(blocks)h (to)g(be)h(added)e(to)h(future)f(v)o(ersions)h(of)g(the)g(module.)0 5230 y(Whether)25 b(cast)i(in)f(pure)f(p)o(ython)g(form)g(or)g (compiled)g(code,)i(tools)f(that)g(use)g(iterators)g(are)g(more)f (memory)f(ef)n(\002cient)i(\(and)f(f)o(aster\))0 5330 y(than)g(their)g(list)h(based)f(counterparts.)37 b(Adopting)24 b(the)h(principles)f(of)h(just-in-time)f(manuf)o(acturing,)f(the)o(y)i (create)g(data)g(when)f(and)p 0 5549 3901 4 v 0 5649 a FI(172)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h (Mathematical)g(Modules)p eop end %%Page: 173 185 TeXDict begin 173 184 bop 0 83 a FN(where)20 b(needed)e(instead)i(of)g (consuming)e(memory)h(with)h(the)g(computer)f(equi)n(v)n(alent)f(of)i (\223in)m(v)o(entory\224.)0 230 y(The)e(performance)e(adv)n(antage)g (of)j(iterators)f(becomes)g(more)f(acute)i(as)g(the)f(number)f(of)i (elements)f(increases)g(\226)h(at)g(some)f(point,)g(lists)0 330 y(gro)n(w)h(lar)o(ge)h(enough)e(to)i(se)n(v)o(erely)f(impact)h (memory)e(cache)i(performance)d(and)j(start)h(running)d(slo)n(wly)-5 b(.)0 476 y FL(See)21 b(Also:)0 623 y FN(The)f(Standard)f(ML)h(Basis)i (Library)-5 b(,)18 b FK(The)i(Standar)m(d)e(ML)j(Basis)g(Libr)o(ary)p FN(.)0 770 y(Hask)o(ell,)f(A)h(Purely)f(Functional)e(Language,)g FK(De\002nition)h(of)i(Hask)o(ell)f(and)f(the)i(Standar)m(d)d(Libr)o (aries)p FN(.)0 1051 y Fv(6.5.1)100 b(Iter)t(tool)28 b(functions)0 1254 y FN(The)e(follo)n(wing)f(module)g(functions)g(all)i (construct)e(and)h(return)f(iterators.)43 b(Some)26 b(pro)o(vide)f (streams)h(of)g(in\002nite)h(length,)g(so)f(the)o(y)0 1354 y(should)19 b(only)h(be)g(accessed)g(by)g(functions)e(or)i(loops)g (that)g(truncate)f(the)i(stream.)0 1500 y FD(chain)p FJ(\()p FK(*iter)o(ables)p FJ(\))208 1600 y FN(Mak)o(e)29 b(an)g(iterator)g(that)h(returns)e(elements)i(from)e(the)i(\002rst)g (iterable)f(until)g(it)i(is)f(e)o(xhausted,)g(then)f(proceeds)f(to)i (the)f(ne)o(xt)208 1700 y(iterable,)24 b(until)g(all)g(of)g(the)g (iterables)g(are)g(e)o(xhausted.)35 b(Used)24 b(for)f(treating)g (consecuti)n(v)o(e)g(sequences)g(as)i(a)f(single)g(sequence.)208 1799 y(Equi)n(v)n(alent)18 b(to:)668 2019 y FA(def)44 b(chain\()1117 2032 y(*)1162 2019 y(iterables\):)847 2110 y(#)h(chain\('ABC',)e('DEF'\))h(-->)g(A)h(B)f(C)h(D)g(E)f(F)847 2202 y(for)h(it)f(in)h(iterables:)1027 2293 y(for)f(element)g(in)g(it:) 1206 2384 y(yield)g(element)0 2702 y FD(count)p FJ(\()p FC([)p FK(n)12 b FC(])p FJ(\))208 2802 y FN(Mak)o(e)23 b(an)g(iterator)g(that)h(returns)e(consecuti)n(v)o(e)g(inte)o(gers)h (starting)g(with)h FK(n)p FN(.)35 b(If)23 b(not)g(speci\002ed)g FK(n)h FN(def)o(aults)f(to)h(zero.)34 b(Does)24 b(not)208 2902 y(currently)i(support)g(p)o(ython)g(long)h(inte)o(gers.)48 b(Often)27 b(used)h(as)g(an)g(ar)o(gument)e(to)i FJ(imap\(\))f FN(to)h(generate)f(consecuti)n(v)o(e)f(data)208 3001 y(points.)e(Also,)c(used)g(with)h FJ(izip\(\))e FN(to)i(add)e(sequence) g(numbers.)24 b(Equi)n(v)n(alent)18 b(to:)668 3221 y FA(def)44 b(count\(n=0\):)847 3312 y(#)h(count\(10\))e(-->)i(10)f(11)h (12)f(13)h(14)f(...)847 3404 y(while)g(True:)1027 3495 y(yield)g(n)1027 3586 y(n)g(+=)h(1)208 3863 y FN(Note,)21 b FJ(count\(\))f FN(does)h(not)g(check)g(for)g(o)o(v)o(er\003o)n(w)e (and)i(will)h(return)e(ne)o(gati)n(v)o(e)f(numbers)h(after)h(e)o (xceeding)e FJ(sys.maxint)p FN(.)208 3962 y(This)h(beha)n(vior)f(may)g (change)g(in)h(the)h(future.)0 4109 y FD(cycle)p FJ(\()p FK(iter)o(able)p FJ(\))208 4209 y FN(Mak)o(e)d(an)g(iterator)f (returning)f(elements)i(from)g(the)g(iterable)g(and)f(sa)n(ving)h(a)h (cop)o(y)e(of)h(each.)24 b(When)18 b(the)h(iterable)e(is)i(e)o (xhausted,)208 4309 y(return)g(elements)g(from)h(the)g(sa)n(v)o(ed)g (cop)o(y)-5 b(.)23 b(Repeats)e(inde\002nitely)-5 b(.)23 b(Equi)n(v)n(alent)c(to:)668 4528 y FA(def)44 b(cycle\(iterable\):)847 4620 y(#)h(cycle\('ABCD'\))e(-->)h(A)h(B)f(C)h(D)g(A)f(B)h(C)g(D)f(A)h (B)g(C)f(D)h(...)847 4711 y(saved)f(=)h([])847 4802 y(for)g(element)e (in)i(iterable:)1027 4894 y(yield)f(element)1027 4985 y(saved.append\(element\))847 5076 y(while)g(saved:)1027 5168 y(for)g(element)g(in)g(saved:)1296 5259 y(yield)g(element)p 0 5549 3901 4 v 0 5649 a FI(6.5.)52 b FJ(itertools)22 b FI(\227)h(Functions)g(creating)g(iter)o(ators)g(f)n(or)g(ef\002cient) g(looping)1278 b(173)p eop end %%Page: 174 186 TeXDict begin 174 185 bop 208 83 a FN(Note,)23 b(this)g(member)f(of)g (the)h(toolkit)f(may)h(require)e(signi\002cant)i(auxiliary)e(storage)i (\(depending)d(on)i(the)h(length)f(of)g(the)h(iter)n(-)208 183 y(able\).)0 330 y FD(dropwhile)p FJ(\()p FK(pr)m(edicate)o(,)17 b(iter)o(able)p FJ(\))208 429 y FN(Mak)o(e)j(an)h(iterator)g(that)g (drops)f(elements)h(from)e(the)j(iterable)e(as)i(long)e(as)i(the)f (predicate)f(is)i(true;)f(afterw)o(ards,)f(returns)g(e)n(v)o(ery)208 529 y(element.)27 b(Note,)21 b(the)g(iterator)f(does)h(not)g(produce)e FK(any)i FN(output)f(until)h(the)g(predicate)f(\002rst)i(becomes)e(f)o (alse,)i(so)f(it)h(may)f(ha)n(v)o(e)f(a)208 628 y(lengthy)e(start-up)h (time.)25 b(Equi)n(v)n(alent)19 b(to:)668 853 y FA(def)44 b(dropwhile\(predicate,)e(iterable\):)847 944 y(#)j(dropwhile\(lambda)d (x:)j(x<5,)f([1,4,6,4,1]\))f(-->)h(6)h(4)f(1)847 1035 y(iterable)g(=)g(iter\(iterable\))847 1127 y(for)h(x)f(in)h(iterable:) 1027 1218 y(if)f(not)g(predicate\(x\):)1206 1309 y(yield)g(x)1206 1401 y(break)847 1492 y(for)h(x)f(in)h(iterable:)1027 1583 y(yield)f(x)0 1901 y FD(groupby)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)18 b(k)o(e)n(y)12 b FC(])p FJ(\))208 2001 y FN(Mak)o(e)24 b(an)h(iterator)f(that)h(returns)f(consecuti)n(v)o(e)f (k)o(e)o(ys)h(and)g(groups)g(from)g(the)g FK(iter)o(able)p FN(.)39 b(The)24 b FK(k)o(e)n(y)h FN(is)h(a)f(function)e(computing)208 2100 y(a)i(k)o(e)o(y)g(v)n(alue)f(for)h(each)g(element.)39 b(If)25 b(not)g(speci\002ed)g(or)g(is)h FJ(None)p FN(,)g FK(k)o(e)n(y)f FN(def)o(aults)g(to)g(an)h(identity)e(function)g(and)g (returns)h(the)208 2200 y(element)19 b(unchanged.)j(Generally)-5 b(,)19 b(the)h(iterable)g(needs)f(to)i(already)e(be)h(sorted)g(on)f (the)i(same)f(k)o(e)o(y)g(function.)208 2333 y(The)d(returned)f(group)g (is)j(itself)f(an)g(iterator)f(that)h(shares)f(the)h(underlying)d (iterable)j(with)g FJ(groupby\(\))p FN(.)23 b(Because)18 b(the)f(source)208 2433 y(is)27 b(shared,)f(when)g(the)g FJ(groupby)g FN(object)f(is)j(adv)n(anced,)d(the)h(pre)n(vious)f(group) f(is)j(no)f(longer)f(visible.)43 b(So,)28 b(if)e(that)h(data)f(is)208 2532 y(needed)18 b(later)m(,)i(it)h(should)e(be)h(stored)g(as)h(a)g (list:)623 2756 y FA(groups)44 b(=)h([])623 2848 y(uniquekeys)e(=)i([]) 623 2939 y(for)f(k,)h(g)g(in)f(groupby\(data,)f(keyfunc\):)802 3030 y(groups.append\(list\(g\)\))266 b(#)44 b(Store)g(group)g (iterator)g(as)g(a)h(list)802 3122 y(uniquekeys.append\(k\))208 3402 y FJ(groupby\(\))19 b FN(is)i(equi)n(v)n(alent)d(to:)p 0 5549 3901 4 v 0 5649 a FI(174)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 175 187 TeXDict begin 175 186 bop 623 174 a FA(class)44 b(groupby\(object\):) 802 266 y(#)h([k)g(for)f(k,)g(g)h(in)g(groupby\('AAAABBBCCDAABBB'\)])40 b(-->)k(A)h(B)g(C)f(D)h(A)g(B)802 357 y(#)g([\(list\(g\)\))e(for)i(k,)f (g)h(in)f(groupby\('AAAABBBCCD'\)])d(-->)k(AAAA)f(BBB)g(CC)h(D)802 448 y(def)g(__init__\(self,)d(iterable,)i(key=None\):)982 540 y(if)g(key)h(is)f(None:)1161 631 y(key)g(=)h(lambda)f(x:)g(x)982 722 y(self.keyfunc)f(=)h(key)982 814 y(self.it)f(=)i(iter\(iterable\)) 982 905 y(self.tgtkey)e(=)h(self.currkey)f(=)i(self.currvalue)d(=)j (xrange\(0\))802 996 y(def)g(__iter__\(self\):)982 1088 y(return)f(self)802 1179 y(def)h(next\(self\):)982 1270 y(while)f(self.currkey)f(==)h(self.tgtkey:)1161 1362 y(self.currvalue)f(=)h(self.it.next\(\))f(#)h(Exit)h(on)f (StopIteration)1161 1453 y(self.currkey)f(=)i (self.keyfunc\(self.currvalue\))982 1544 y(self.tgtkey)e(=)h (self.currkey)982 1636 y(return)g(\(self.currkey,)e (self._grouper\(self.tgtkey\)\))802 1727 y(def)j(_grouper\(self,)d (tgtkey\):)982 1818 y(while)i(self.currkey)f(==)h(tgtkey:)1161 1910 y(yield)g(self.currvalue)1161 2001 y(self.currvalue)f(=)h (self.it.next\(\))f(#)h(Exit)h(on)f(StopIteration)1161 2092 y(self.currkey)f(=)i(self.keyfunc\(self.currvalue\))208 2340 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)0 2487 y FD(ifilter)p FJ(\()p FK(pr)m(edicate)o(,)f(iter)o(able)p FJ(\))208 2586 y FN(Mak)o(e)27 b(an)h(iterator)f(that)h(\002lters)h (elements)e(from)g(iterable)g(returning)f(only)h(those)h(for)f(which)h (the)f(predicate)g(is)i FJ(True)p FN(.)48 b(If)208 2686 y FK(pr)m(edicate)19 b FN(is)i FJ(None)p FN(,)f(return)f(the)h(items)h (that)f(are)g(true.)25 b(Equi)n(v)n(alent)18 b(to:)668 2819 y FA(def)44 b(ifilter\(predicate,)e(iterable\):)847 2910 y(#)j(ifilter\(lambda)d(x:)j(x\0452,)f(range\(10\)\))f(-->)i(1)f (3)h(5)g(7)f(9)847 3001 y(if)h(predicate)e(is)i(None:)1027 3093 y(predicate)e(=)i(bool)847 3184 y(for)g(x)f(in)h(iterable:)1027 3275 y(if)f(predicate\(x\):)1206 3367 y(yield)g(x)0 3662 y FD(ifilterfalse)p FJ(\()p FK(pr)m(edicate)o(,)17 b(iter)o(able)p FJ(\))208 3761 y FN(Mak)o(e)25 b(an)g(iterator)f(that)i(\002lters)g (elements)f(from)f(iterable)h(returning)e(only)h(those)h(for)g(which)f (the)i(predicate)e(is)i FJ(False)p FN(.)40 b(If)208 3861 y FK(pr)m(edicate)19 b FN(is)i FJ(None)p FN(,)f(return)f(the)h(items)h (that)f(are)g(f)o(alse.)25 b(Equi)n(v)n(alent)19 b(to:)668 3994 y FA(def)44 b(ifilterfalse\(predicate,)d(iterable\):)847 4085 y(#)k(ifilterfalse\(lambda)d(x:)i(x\0452,)g(range\(10\)\))f(-->)i (0)f(2)h(4)g(6)f(8)847 4176 y(if)h(predicate)e(is)i(None:)1027 4268 y(predicate)e(=)i(bool)847 4359 y(for)g(x)f(in)h(iterable:)1027 4450 y(if)f(not)g(predicate\(x\):)1206 4542 y(yield)g(x)0 4837 y FD(imap)p FJ(\()p FK(function,)18 b(*iter)o(ables)p FJ(\))208 4936 y FN(Mak)o(e)26 b(an)h(iterator)g(that)g(computes)f(the) h(function)e(using)h(ar)o(guments)f(from)h(each)h(of)g(the)g (iterables.)45 b(If)27 b FK(function)f FN(is)i(set)f(to)208 5036 y FJ(None)p FN(,)k(then)f FJ(imap\(\))f FN(returns)g(the)g(ar)o (guments)f(as)j(a)f(tuple.)53 b(Lik)o(e)30 b FJ(map\(\))f FN(b)n(ut)h(stops)g(when)f(the)h(shortest)f(iterable)h(is)208 5136 y(e)o(xhausted)22 b(instead)i(of)g(\002lling)g(in)g FJ(None)g FN(for)f(shorter)h(iterables.)36 b(The)24 b(reason)f(for)h (the)g(dif)n(ference)e(is)j(that)f(in\002nite)g(iterator)208 5235 y(ar)o(guments)18 b(are)i(typically)g(an)g(error)f(for)h FJ(map\(\))g FN(\(because)g(the)g(output)f(is)j(fully)d(e)n(v)n (aluated\))g(b)n(ut)h(represent)g(a)h(common)d(and)208 5335 y(useful)h(w)o(ay)h(of)g(supplying)f(ar)o(guments)f(to)i FJ(imap\(\))p FN(.)k(Equi)n(v)n(alent)19 b(to:)p 0 5549 3901 4 v 0 5649 a FI(6.5.)52 b FJ(itertools)22 b FI(\227)h(Functions)g (creating)g(iter)o(ators)g(f)n(or)g(ef\002cient)g(looping)1278 b(175)p eop end %%Page: 176 188 TeXDict begin 176 187 bop 668 83 a FA(def)44 b(imap\(function,)1520 96 y(*)1565 83 y(iterables\):)847 174 y(#)h(imap\(pow,)e(\(2,3,10\),)h (\(5,2,3\)\))f(-->)h(32)h(9)g(1000)847 266 y(iterables)f(=)g (map\(iter,)g(iterables\))847 357 y(while)g(True:)1027 448 y(args)g(=)g([i.next\(\))g(for)g(i)h(in)f(iterables])1027 540 y(if)g(function)g(is)g(None:)1206 631 y(yield)g(tuple\(args\))1027 722 y(else:)1206 814 y(yield)g(function\()1880 827 y(*)1925 814 y(args\))0 1132 y FD(islice)p FJ(\()p FK(iter)o(able)o(,)18 b FC([)p FK(start,)12 b FC(])21 b FK(stop)f FC([)p FK(,)g(step)12 b FC(])p FJ(\))208 1231 y FN(Mak)o(e)25 b(an)g(iterator)f(that)i (returns)e(selected)h(elements)g(from)f(the)h(iterable.)40 b(If)25 b FK(start)j FN(is)e(non-zero,)e(then)g(elements)h(from)g(the) 208 1331 y(iterable)k(are)g(skipped)g(until)g(start)h(is)h(reached.)51 b(Afterw)o(ard,)31 b(elements)e(are)h(returned)d(consecuti)n(v)o(ely)h (unless)h FK(step)h FN(is)h(set)208 1431 y(higher)19 b(than)h(one)g(which)h(results)g(in)g(items)g(being)e(skipped.)26 b(If)20 b FK(stop)h FN(is)h FJ(None)p FN(,)e(then)g(iteration)g (continues)g(until)g(the)h(iterator)208 1530 y(is)30 b(e)o(xhausted,)f(if)h(at)g(all;)k(otherwise,)d(it)f(stops)f(at)h(the)f (speci\002ed)g(position.)52 b(Unlik)o(e)29 b(re)o(gular)e(slicing,)k FJ(islice\(\))e FN(does)208 1630 y(not)d(support)f(ne)o(gati)n(v)o(e)f (v)n(alues)i(for)g FK(start)q FN(,)j FK(stop)p FN(,)f(or)e FK(step)p FN(.)44 b(Can)26 b(be)h(used)f(to)h(e)o(xtract)e(related)h (\002elds)h(from)e(data)i(where)f(the)208 1729 y(internal)21 b(structure)g(has)h(been)f(\003attened)g(\(for)g(e)o(xample,)g(a)h (multi-line)f(report)g(may)g(list)i(a)f(name)g(\002eld)g(on)f(e)n(v)o (ery)g(third)g(line\).)208 1829 y(Equi)n(v)n(alent)d(to:)668 2052 y FA(def)44 b(islice\(iterable,)1609 2065 y(*)1654 2052 y(args\):)847 2143 y(#)h(islice\('ABCDEFG',)d(2\))i(-->)h(A)f(B) 847 2234 y(#)h(islice\('ABCDEFG',)d(2,)i(4\))h(-->)f(C)h(D)847 2326 y(#)g(islice\('ABCDEFG',)d(2,)i(None\))g(-->)h(C)f(D)h(E)g(F)f(G) 847 2417 y(#)h(islice\('ABCDEFG',)d(0,)i(None,)g(2\))h(-->)f(A)h(C)g(E) f(G)847 2508 y(s)h(=)g(slice\()1297 2521 y(*)1342 2508 y(args\))847 2599 y(it)g(=)f(iter\(xrange\(s.start)e(or)j(0,)f(s.stop)g (or)g(sys.maxint,)f(s.step)h(or)h(1\)\))847 2691 y(nexti)f(=)h (it.next\(\))847 2782 y(for)g(i,)f(element)g(in)g (enumerate\(iterable\):)1027 2873 y(if)g(i)h(==)f(nexti:)1206 2965 y(yield)g(element)1206 3056 y(nexti)g(=)h(it.next\(\))208 3335 y FN(If)20 b FK(start)i FN(is)g FJ(None)p FN(,)e(then)g(iteration) f(starts)j(at)e(zero.)25 b(If)c FK(step)f FN(is)i FJ(None)p FN(,)e(then)f(the)i(step)g(def)o(aults)e(to)i(one.)51 b(Changed)19 b(in)i(v)o(ersion)208 3435 y(2.5:)e(accept)h FJ(None)g FN(v)n(alues)g(for)f(def)o(ault)h FK(start)i FN(and)e FK(step)p FN(.)0 3582 y FD(izip)p FJ(\()p FK(*iter)o(ables)p FJ(\))208 3681 y FN(Mak)o(e)29 b(an)g(iterator)g(that)g(aggre)o(gates)e (elements)i(from)g(each)g(of)g(the)g(iterables.)52 b(Lik)o(e)29 b FJ(zip\(\))g FN(e)o(xcept)g(that)g(it)h(returns)f(an)208 3781 y(iterator)19 b(instead)h(of)g(a)h(list.)26 b(Used)20 b(for)g(lock-step)f(iteration)g(o)o(v)o(er)g(se)n(v)o(eral)g(iterables) h(at)h(a)g(time.)k(Equi)n(v)n(alent)18 b(to:)668 4003 y FA(def)44 b(izip\()1072 4016 y(*)1117 4003 y(iterables\):)847 4095 y(#)h(izip\('ABCD',)e('xy'\))h(-->)g(Ax)h(By)847 4186 y(iterables)f(=)g(map\(iter,)g(iterables\))847 4277 y(while)g(iterables:)1027 4369 y(result)f(=)i([it.next\(\))e(for)i(it)f (in)h(iterables])1027 4460 y(yield)f(tuple\(result\))208 4739 y FN(Changed)30 b(in)j(v)o(ersion)d(2.4:)i(When)g(no)g(iterables)f (are)h(speci\002ed,)j(returns)c(a)i(zero)e(length)g(iterator)h(instead) g(of)g(raising)f(a)208 4839 y FJ(TypeError)19 b FN(e)o(xception.)208 4970 y(Note,)e(the)f(left-to-right)f(e)n(v)n(aluation)g(order)h(of)g (the)h(iterables)f(is)i(guaranteed.)k(This)17 b(mak)o(es)f(possible)h (an)f(idiom)g(for)h(clustering)208 5070 y(a)e(data)h(series)g(into)f (n-length)e(groups)h(using)h(`)p FJ(izip\()1773 5085 y(*)1823 5070 y([iter\(s\)])2273 5085 y(*)2323 5070 y(n\))p FN('.)20 b(F)o(or)15 b(data)g(that)h(doesn')o(t)d(\002t)k(n-length)c (groups)h(e)o(x-)208 5169 y(actly)-5 b(,)18 b(the)h(last)h(tuple)f(can) g(be)g(pre-padded)d(with)j(\002ll)h(v)n(alues)f(using)f(`)p FJ(izip\()2458 5184 y(*)2508 5169 y([chain\(s,)47 b([None])3305 5184 y(*)3355 5169 y(\(n-1\)\)])3705 5184 y(*)3755 5169 y(n\))p FN('.)208 5300 y(Note,)25 b(when)e FJ(izip\(\))h FN(is)h(used)f(with)h(unequal)e(length)g(inputs,)i(subsequent)e (iteration)g(o)o(v)o(er)g(the)h(longer)g(iterables)g(cannot)208 5400 y(reliably)g(be)h(continued)e(after)i FJ(izip\(\))f FN(terminates.)39 b(Potentially)-5 b(,)25 b(up)g(to)g(one)g(entry)f (will)i(be)f(missing)g(from)f(each)h(of)g(the)p 0 5549 3901 4 v 0 5649 a FI(176)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 177 189 TeXDict begin 177 188 bop 208 83 a FN(left-o)o(v)o(er)19 b(iterables.)28 b(This)21 b(occurs)g(because)f(a)i(v)n(alue)f(is)h (fetched)e(from)g(each)h(iterator)g(in-turn,)f(b)n(ut)h(the)g(process)g (ends)g(when)208 183 y(one)h(of)h(the)h(iterators)f(terminates.)34 b(This)23 b(lea)n(v)o(es)h(the)f(last)h(fetched)f(v)n(alues)g(in)g (limbo)g(\(the)o(y)f(cannot)g(be)i(returned)d(in)j(a)g(\002nal,)208 282 y(incomplete)14 b(tuple)h(and)g(the)o(y)g(are)h(cannot)e(be)i (pushed)f(back)g(into)g(the)h(iterator)f(for)g(retrie)n(v)n(al)g(with)h FJ(it.next\(\))p FN(\).)21 b(In)16 b(general,)208 382 y FJ(izip\(\))k FN(should)f(only)h(be)g(used)g(with)h(unequal)e(length) h(inputs)g(when)g(you)f(don')o(t)g(care)h(about)g(trailing,)g (unmatched)e(v)n(alues)208 482 y(from)h(the)h(longer)f(iterables.)0 628 y FD(repeat)p FJ(\()p FK(object)q FC([)p FK(,)f(times)12 b FC(])p FJ(\))208 728 y FN(Mak)o(e)k(an)h(iterator)f(that)g(returns)g FK(object)i FN(o)o(v)o(er)d(and)h(o)o(v)o(er)f(again.)23 b(Runs)17 b(inde\002nitely)e(unless)i(the)g FK(times)g FN(ar)o(gument)e(is)i(speci\002ed.)208 828 y(Used)i(as)h(ar)o(gument)e (to)h FJ(imap\(\))g FN(for)g(in)m(v)n(ariant)f(parameters)g(to)i(the)f (called)h(function.)i(Also)e(used)g(with)f FJ(izip\(\))g FN(to)h(create)208 927 y(an)g(in)m(v)n(ariant)e(part)i(of)g(a)h(tuple)e (record.)24 b(Equi)n(v)n(alent)18 b(to:)668 1151 y FA(def)44 b(repeat\(object,)f(times=None\):)847 1243 y(#)i(repeat\(10,)e(3\))i (-->)f(10)g(10)h(10)847 1334 y(if)g(times)f(is)g(None:)1027 1425 y(while)g(True:)1206 1517 y(yield)g(object)847 1608 y(else:)1027 1699 y(for)g(i)h(in)f(xrange\(times\):)1206 1791 y(yield)g(object)0 2086 y FD(starmap)p FJ(\()p FK(function,)17 b(iter)o(able)p FJ(\))208 2185 y FN(Mak)o(e)34 b(an)g(iterator)g(that)h (computes)e(the)i(function)e(using)h(ar)o(guments)f(tuples)h(obtained)f (from)h(the)g(iterable.)68 b(Used)35 b(in-)208 2285 y(stead)c(of)f FJ(imap\(\))h FN(when)f(ar)o(gument)f(parameters)g(are)i(already)f (grouped)f(in)i(tuples)g(from)e(a)j(single)f(iterable)f(\(the)h(data) 208 2385 y(has)25 b(been)g(\223pre-zipped\224\).)39 b(The)25 b(dif)n(ference)f(between)h FJ(imap\(\))g FN(and)g FJ(starmap\(\))f FN(parallels)i(the)g(distinction)e(between)208 2484 y FJ(function\(a,b\))18 b FN(and)i FJ(function\()1467 2499 y(*)1517 2484 y(c\))p FN(.)j(Equi)n(v)n(alent)18 b(to:)668 2617 y FA(def)44 b(starmap\(function,)e(iterable\):)847 2708 y(#)j(starmap\(pow,)e([\(2,5\),)g(\(3,2\),)h(\(10,3\)]\))g(-->)g (32)h(9)f(1000)847 2800 y(iterable)g(=)g(iter\(iterable\))847 2891 y(while)g(True:)1027 2982 y(yield)g(function\()1701 2995 y(*)1746 2982 y(iterable.next\(\)\))0 3277 y FD(takewhile)p FJ(\()p FK(pr)m(edicate)o(,)17 b(iter)o(able)p FJ(\))208 3377 y FN(Mak)o(e)j(an)g(iterator)f(that)h(returns)g(elements)g(from)f (the)h(iterable)g(as)h(long)e(as)i(the)f(predicate)f(is)i(true.)k(Equi) n(v)n(alent)18 b(to:)668 3601 y FA(def)44 b(takewhile\(predicate,)e (iterable\):)847 3692 y(#)j(takewhile\(lambda)d(x:)j(x<5,)f ([1,4,6,4,1]\))f(-->)h(1)h(4)847 3784 y(for)g(x)f(in)h(iterable:)1027 3875 y(if)f(predicate\(x\):)1206 3966 y(yield)g(x)1027 4058 y(else:)1206 4149 y(break)0 4467 y FD(tee)p FJ(\()p FK(iter)o(able)p FC([)p FK(,)19 b(n=2)12 b FC(])p FJ(\))208 4567 y FN(Return)19 b FK(n)i FN(independent)c(iterators)j(from)f(a)i (single)f(iterable.)k(The)c(case)h(where)e FJ(n==2)h FN(is)h(equi)n(v)n(alent)e(to:)p 0 5549 3901 4 v 0 5649 a FI(6.5.)52 b FJ(itertools)22 b FI(\227)h(Functions)g(creating)g(iter) o(ators)g(f)n(or)g(ef\002cient)g(looping)1278 b(177)p eop end %%Page: 178 190 TeXDict begin 178 189 bop 668 174 a FA(def)44 b(tee\(iterable\):)847 266 y(def)h(gen\(next,)e(data={},)g(cnt=[0]\):)1027 357 y(for)h(i)h(in)f(count\(\):)1206 448 y(if)g(i)h(==)g(cnt[0]:)1385 540 y(item)f(=)h(data[i])f(=)g(next\(\))1385 631 y(cnt[0])g(+=)h(1)1206 722 y(else:)1385 814 y(item)f(=)h(data.pop\(i\))1206 905 y(yield)f(item)847 996 y(it)h(=)f(iter\(iterable\))847 1088 y(return)g(\(gen\(it.next\),)f(gen\(it.next\)\))208 1369 y FN(Note,)31 b(once)e FJ(tee\(\))g FN(has)g(made)g(a)h(split,)i (the)d(original)f FK(iter)o(able)h FN(should)f(not)h(be)h(used)f(an)o (ywhere)e(else;)35 b(otherwise,)c(the)208 1468 y FK(iter)o(able)19 b FN(could)h(get)g(adv)n(anced)e(without)h(the)i(tee)f(objects)g(being) f(informed.)208 1601 y(Note,)k(this)g(member)e(of)h(the)h(toolkit)f (may)g(require)g(signi\002cant)g(auxiliary)f(storage)h(\(depending)e (on)i(ho)n(w)g(much)g(temporary)208 1701 y(data)c(needs)g(to)g(be)h (stored\).)k(In)18 b(general,)g(if)g(one)g(iterator)g(is)h(going)e(to)i (use)g(most)f(or)g(all)h(of)f(the)h(data)f(before)f(the)h(other)g (iterator)m(,)208 1800 y(it)i(is)i(f)o(aster)e(to)g(use)h FJ(list\(\))e FN(instead)h(of)g FJ(tee\(\))p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 2085 y Fv(6.5.2)100 b(Examples)0 2288 y FN(The)20 b(follo)n(wing)e(e)o(xamples)h(sho)n(w)h (common)f(uses)h(for)g(each)g(tool)g(and)f(demonstrate)g(w)o(ays)i(the) o(y)e(can)h(be)g(combined.)236 2618 y FA(#)45 b(Show)f(a)h(dictionary)e (sorted)h(and)g(grouped)g(by)g(value)236 2709 y(>>>)h(from)f(operator)f (import)h(itemgetter)236 2800 y(>>>)h(d)f(=)h(dict\(a=1,)e(b=2,)h(c=1,) h(d=2,)f(e=1,)g(f=2,)g(g=3\))236 2892 y(>>>)h(di)f(=)h (sorted\(d.iteritems\(\),)c(key=itemgetter\(1\)\))236 2983 y(>>>)k(for)f(k,)g(g)h(in)g(groupby\(di,)e(key=itemgetter\(1\)\):) 236 3074 y(...)224 b(print)44 b(k,)g(map\(itemgetter\(0\),)e(g\))236 3166 y(...)236 3257 y(1)j(['a',)f('c',)g('e'])236 3348 y(2)h(['b',)f('d',)g('f'])236 3440 y(3)h(['g'])236 3622 y(#)g(Find)f(runs)g(of)h(consecutive)e(numbers)g(using)h(groupby.)89 b(The)44 b(key)g(to)h(the)f(solution)236 3714 y(#)h(is)f(differencing)f (with)h(a)h(range)f(so)h(that)f(consecutive)f(numbers)g(all)i(appear)e (in)236 3805 y(#)i(same)f(group.)236 3896 y(>>>)h(data)f(=)g([)h(1,)89 b(4,5,6,)44 b(10,)h(15,16,17,18,)d(22,)j(25,26,27,28])236 3987 y(>>>)g(for)f(k,)g(g)h(in)g(groupby\(enumerate\(data\),)40 b(lambda)k(\(i,x\):i-x\):)236 4079 y(...)224 b(print)44 b(map\(operator.itemgetter\(1\),)c(g\))236 4170 y(...)236 4261 y([1])236 4353 y([4,)45 b(5,)f(6])236 4444 y([10])236 4535 y([15,)g(16,)h(17,)f(18])236 4627 y([22])236 4718 y([25,)g(26,)h(27,)f(28])p 0 5549 3901 4 v 0 5649 a FI(178)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 179 191 TeXDict begin 179 190 bop 0 83 a Fv(6.5.3)100 b(Recipes)0 286 y FN(This)20 b(section)g(sho)n(ws)h(recipes)e(for)h(creating)f(an)h (e)o(xtended)e(toolset)j(using)e(the)i(e)o(xisting)e(itertools)h(as)h (b)n(uilding)e(blocks.)0 433 y(The)27 b(e)o(xtended)f(tools)i(of)n(fer) e(the)i(same)f(high)g(performance)e(as)j(the)g(underlying)d(toolset.)47 b(The)27 b(superior)g(memory)e(performance)0 532 y(is)h(k)o(ept)f(by)g (processing)f(elements)h(one)g(at)g(a)h(time)g(rather)e(than)h (bringing)e(the)i(whole)g(iterable)g(into)g(memory)f(all)h(at)h(once.) 40 b(Code)0 632 y(v)n(olume)27 b(is)h(k)o(ept)g(small)g(by)f(linking)g (the)g(tools)h(together)e(in)i(a)g(functional)e(style)i(which)f(helps)h (eliminate)f(temporary)f(v)n(ariables.)0 732 y(High)18 b(speed)h(is)g(retained)f(by)h(preferring)d(\223v)o(ectorized\224)g(b)n (uilding)i(blocks)g(o)o(v)o(er)f(the)i(use)g(of)g(for)n(-loops)e(and)h (generators)f(which)h(incur)0 831 y(interpreter)h(o)o(v)o(erhead.)p 0 5549 3901 4 v 0 5649 a FI(6.5.)52 b FJ(itertools)22 b FI(\227)h(Functions)g(creating)g(iter)o(ators)g(f)n(or)g(ef\002cient) g(looping)1278 b(179)p eop end %%Page: 180 192 TeXDict begin 180 191 bop 236 174 a FA(def)45 b(take\(n,)e(seq\):)416 266 y(return)g(list\(islice\(seq,)g(n\)\))236 448 y(def)i (enumerate\(iterable\):)416 540 y(return)e(izip\(count\(\),)g (iterable\))236 722 y(def)i(tabulate\(function\):)416 814 y("Return)e(function\(0\),)g(function\(1\),)g(...")416 905 y(return)g(imap\(function,)g(count\(\)\))236 1088 y(def)i(iteritems\(mapping\):)416 1179 y(return)e (izip\(mapping.iterkeys\(\),)e(mapping.itervalues\(\)\))236 1362 y(def)k(nth\(iterable,)d(n\):)416 1453 y("Returns)h(the)h(nth)h (item)f(or)g(raise)g(StopIteration")416 1544 y(return)f (islice\(iterable,)g(n,)h(None\).next\(\))236 1727 y(def)h(all\(seq,)e (pred=None\):)416 1818 y("Returns)g(True)h(if)h(pred\(x\))e(is)i(true)f (for)g(every)g(element)g(in)g(the)h(iterable")416 1910 y(for)f(elem)g(in)h(ifilterfalse\(pred,)c(seq\):)595 2001 y(return)j(False)416 2092 y(return)f(True)236 2275 y(def)i(any\(seq,)e(pred=None\):)416 2366 y("Returns)g(True)h(if)h (pred\(x\))e(is)i(true)f(for)g(at)h(least)f(one)g(element)g(in)g(the)h (iterable")416 2457 y(for)f(elem)g(in)h(ifilter\(pred,)d(seq\):)595 2549 y(return)i(True)416 2640 y(return)f(False)236 2823 y(def)i(no\(seq,)e(pred=None\):)416 2914 y("Returns)g(True)h(if)h (pred\(x\))e(is)i(false)f(for)g(every)g(element)g(in)g(the)h(iterable") 416 3005 y(for)f(elem)g(in)h(ifilter\(pred,)d(seq\):)595 3097 y(return)i(False)416 3188 y(return)f(True)236 3371 y(def)i(quantify\(seq,)d(pred=None\):)416 3462 y("Count)h(how)i(many)f (times)g(the)g(predicate)f(is)i(true)f(in)h(the)f(sequence")416 3553 y(return)f(sum\(imap\(pred,)g(seq\)\))236 3736 y(def)i (padnone\(seq\):)416 3827 y("""Returns)e(the)h(sequence)g(elements)f (and)h(then)g(returns)g(None)g(indefinitely.)416 4010 y(Useful)f(for)i(emulating)e(the)h(behavior)g(of)g(the)h(built-in)e (map\(\))h(function.)416 4101 y(""")416 4193 y(return)f(chain\(seq,)h (repeat\(None\)\))236 4375 y(def)h(ncycles\(seq,)d(n\):)416 4467 y("Returns)h(the)h(sequence)g(elements)f(n)i(times")416 4558 y(return)e(chain\()999 4571 y(*)1044 4558 y(repeat\(seq,)f(n\)\)) 236 4741 y(def)j(dotproduct\(vec1,)d(vec2\):)416 4832 y(return)h(sum\(imap\(operator.mul,)f(vec1,)h(vec2\)\))236 5015 y(def)i(flatten\(listOfLists\):)416 5106 y(return)e(list\(chain\() 1224 5119 y(*)1269 5106 y(listOfLists\)\))236 5289 y(def)i (repeatfunc\(func,)d(times=None,)1716 5302 y(*)1761 5289 y(args\):)416 5380 y("""Repeat)h(calls)h(to)g(func)h(with)f(specified)f (arguments.)416 5562 y(Example:)88 b(repeatfunc\(random.random\))416 5654 y(""")416 5745 y(if)44 b(times)g(is)h(None:)595 5836 y(return)f(starmap\(func,)e(repeat\(args\)\))416 5928 y(else:)595 6019 y(return)i(starmap\(func,)e(repeat\(args,)h (times\)\))236 6202 y(def)i(pairwise\(iterable\):)416 6293 y("s)f(->)h(\(s0,s1\),)e(\(s1,s2\),)h(\(s2,)g(s3\),)g(...")416 6384 y(a,)g(b)h(=)f(tee\(iterable\))416 6476 y(for)g(elem)g(in)h(b:)595 6567 y(break)416 6658 y(return)e(izip\(a,)h(b\))236 6841 y(def)h(grouper\(n,)e(iterable,)g(padvalue=None\):)416 6932 y("grouper\(3,)g('abcdefg',)g('x'\))h(-->)g(\('a','b','c'\),)f (\('d','e','f'\),)f(\('g','x','x'\)")416 7024 y(return)h(izip\()954 7037 y(*)999 7024 y([chain\(iterable,)f(repeat\(padvalue,)g(n-1\)\)]) 2793 7037 y(*)2838 7024 y(n\))236 7206 y(def)j(reverse_map\(d\):)416 7298 y("Return)e(a)i(new)f(dict)g(with)h(swapped)e(keys)h(and)h (values")416 7389 y(return)e(dict\(izip\(d.itervalues\(\),)e(d\)\))236 7572 y(def)k(roundrobin\()911 7585 y(*)956 7572 y(iterables\):)416 7663 y("roundrobin\('abc',)c('d',)k('ef'\))f(-->)g('a',)g('d',)g('e',)g ('b',)g('f',)h('c'")416 7754 y(#)f(Recipe)g(credited)g(to)g(George)g (Sakkis)416 7846 y(pending)f(=)i(len\(iterables\))416 7937 y(nexts)f(=)g(cycle\(iter\(it\).next)e(for)i(it)h(in)f (iterables\))416 8028 y(while)g(pending:)595 8120 y(try:)774 8211 y(for)h(next)f(in)g(nexts:)954 8302 y(yield)g(next\(\))595 8394 y(except)g(StopIteration:)774 8485 y(pending)g(-=)g(1)774 8576 y(nexts)g(=)h(cycle\(islice\(nexts,)c(pending\)\))236 8759 y(def)k(powerset\(iterable\):)416 8850 y("powerset\('ab'\))d(-->)i (set\([]\),)g(set\(['a']\),)f(set\(['b']\),)g(set\(['a',)g('b']\)")416 8941 y(#)h(Recipe)g(credited)g(to)g(Eric)g(Raymond)416 9033 y(pairs)g(=)g([\(2)909 9046 y(**)999 9033 y(i,)g(x\))g(for)h(i,)f (x)h(in)f(enumerate\(iterable\)])416 9124 y(for)g(n)h(in)f(xrange\(2) 1179 9137 y(**)1269 9124 y(len\(pairs\)\):)595 9215 y(yield)g(set\(x)g (for)g(m,)h(x)f(in)h(pairs)f(if)g(m&n\))p 0 5549 3901 4 v 0 5649 a FI(180)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 181 193 TeXDict begin 181 192 bop 0 410 a FE(6.6)121 b Fx(functools)28 b FE(\227)i(Higher)h(order)h(functions)g(and)g(oper)o(ations)g(on)g (callab)n(le)e(ob-)286 560 y(jects)n(.)0 793 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 940 y(The)g FJ(functools)e FN(module)h(is)i(for)e(higher)n(-order)d(functions:)24 b(functions)17 b(that)i(act)g(on)g(or)f(return)g(other)g(functions.)23 b(In)c(general,)e(an)o(y)0 1039 y(callable)j(object)g(can)g(be)g (treated)f(as)i(a)g(function)d(for)i(the)g(purposes)f(of)h(this)h (module.)0 1186 y(The)f FJ(functools)f FN(module)g(de\002nes)h(the)g (follo)n(wing)e(function:)0 1333 y FD(partial)p FJ(\()p FK(func)p FC([)p FK(,*ar)m(gs)12 b FC(][)p FK(,)k(**k)o(e)n(ywor)m(ds)c FC(])p FJ(\))208 1433 y FN(Return)24 b(a)i(ne)n(w)f FJ(partial)g FN(object)f(which)h(when)g(called)g(will)h(beha)n(v)o(e)e(lik)o(e)i FK(func)e FN(called)i(with)f(the)g(positional)g(ar)o(guments)208 1532 y FK(ar)m(gs)e FN(and)g(k)o(e)o(yw)o(ord)e(ar)o(guments)g FK(k)o(e)n(ywor)m(ds)p FN(.)34 b(If)23 b(more)g(ar)o(guments)e(are)i (supplied)g(to)g(the)g(call,)i(the)o(y)d(are)h(appended)e(to)j FK(ar)m(gs)p FN(.)208 1632 y(If)c(additional)e(k)o(e)o(yw)o(ord)h(ar)o (guments)f(are)i(supplied,)f(the)o(y)g(e)o(xtend)g(and)h(o)o(v)o (erride)e FK(k)o(e)n(ywor)m(ds)p FN(.)24 b(Roughly)19 b(equi)n(v)n(alent)g(to:)802 1856 y FA(def)45 b(partial\(func,)1609 1869 y(*)1654 1856 y(args,)1923 1869 y(**)2013 1856 y(keywords\):)982 1947 y(def)f(newfunc\()1521 1960 y(*)1566 1947 y(fargs,)1878 1960 y(**)1968 1947 y(fkeywords\):)1161 2039 y(newkeywords)f(=)i (keywords.copy\(\))1161 2130 y(newkeywords.update\(fkeywords\))1161 2221 y(return)f(func\()1700 2234 y(*)1745 2221 y(\(args)f(+)i(fargs\),) 2461 2234 y(**)2551 2221 y(newkeywords\))982 2313 y(newfunc.func)e(=)h (func)982 2404 y(newfunc.args)f(=)h(args)982 2495 y(newfunc.keywords)e (=)j(keywords)982 2587 y(return)f(newfunc)208 2867 y FN(The)22 b FJ(partial)f FN(is)i(used)f(for)g(partial)g(function)f (application)g(which)g(\223freezes\224)h(some)g(portion)f(of)h(a)h (function')-5 b(s)21 b(ar)o(guments)208 2967 y(and/or)g(k)o(e)o(yw)o (ords)h(resulting)g(in)h(a)h(ne)n(w)f(object)f(with)i(a)f(simpli\002ed) g(signature.)32 b(F)o(or)23 b(e)o(xample,)f FJ(partial)h FN(can)g(be)g(used)f(to)208 3067 y(create)d(a)i(callable)f(that)g(beha) n(v)o(es)g(lik)o(e)g(the)g FJ(int)g FN(function)f(where)g(the)i FK(base)f FN(ar)o(gument)d(def)o(aults)j(to)h(tw)o(o:)802 3291 y FA(>>>)45 b(basetwo)e(=)i(partial\(int,)e(base=2\))802 3382 y(>>>)i(basetwo.__doc__)d(=)j('Convert)e(base)h(2)h(string)f(to)g (an)h(int.')802 3473 y(>>>)g(basetwo\('10010'\))802 3565 y(18)0 3883 y FD(update_wrapper)p FJ(\()p FK(wr)o(apper)-9 b(,)17 b(wr)o(apped)r FC([)p FK(,)i(assigned)12 b FC(][)p FK(,)20 b(updated)12 b FC(])p FJ(\))208 3982 y FN(Update)31 b(a)h FK(wr)o(apper)h FN(function)d(to)i(look)f(lik)o(e)h(the)g FK(wr)o(apped)h FN(function.)58 b(The)31 b(optional)g(ar)o(guments)f (are)h(tuples)h(to)g(spec-)208 4082 y(ify)e(which)h(attrib)n(utes)g(of) f(the)h(original)f(function)f(are)i(assigned)g(directly)f(to)h(the)g (matching)f(attrib)n(utes)g(on)h(the)g(wrapper)208 4182 y(function)24 b(and)j(which)f(attrib)n(utes)g(of)h(the)f(wrapper)f (function)g(are)i(updated)e(with)i(the)f(corresponding)d(attrib)n(utes) k(from)f(the)208 4281 y(original)c(function.)34 b(The)24 b(def)o(ault)f(v)n(alues)g(for)h(these)g(ar)o(guments)d(are)j(the)g (module)e(le)n(v)o(el)i(constants)f FK(WRAPPER)p 3572 4281 25 4 v 29 w(ASSIGN-)208 4381 y(MENTS)h FN(\(which)f(assigns)g(to)h (the)f(wrapper)f(function')-5 b(s)p 1884 4381 V 1914 4381 V 82 w FK(name)p 2125 4381 V 2154 4381 V 58 w FN(,)p 2229 4381 V 2259 4381 V 85 w FK(module)p 2535 4381 V 2563 4381 V 82 w FN(and)p 2761 4381 V 2790 4381 V 82 w FK(doc)p 2941 4381 V 2970 4381 V 59 w FN(,)24 b(the)g(documentation)c (string\))208 4481 y(and)f FK(WRAPPER)p 728 4481 V 29 w(UPD)m(A)m(TES)h FN(\(which)f(updates)g(the)i(wrapper)d(function')-5 b(s)p 2425 4481 V 2455 4481 V 79 w FK(dict)p 2610 4481 V 2639 4481 V 59 w FN(,)21 b(i.e.)k(the)20 b(instance)g(dictionary\).) 208 4613 y(The)h(main)g(intended)f(use)i(for)f(this)h(function)e(is)j (in)e(decorator)f(functions)g(which)h(wrap)g(the)h(decorated)e (function)g(and)h(return)208 4713 y(the)16 b(wrapper)-5 b(.)23 b(If)16 b(the)h(wrapper)e(function)g(is)j(not)e(updated,)f(the)i (metadata)f(of)g(the)h(returned)e(function)f(will)k(re\003ect)e(the)h (wrapper)208 4813 y(de\002nition)i(rather)g(than)h(the)g(original)f (function)f(de\002nition,)h(which)h(is)h(typically)e(less)j(than)d (helpful.)0 4960 y FD(wraps)p FJ(\()p FK(wr)o(apped)r FC([)p FK(,)f(assigned)12 b FC(][)p FK(,)21 b(updated)11 b FC(])p FJ(\))208 5059 y FN(This)54 b(is)i(a)f(con)m(v)o(enience)c (function)i(for)h(in)m(v)n(oking)e FJ(partial\(update_wrapper,)46 b(wrapped=wrapped,)208 5159 y(assigned=assigned,)g(updated=updated\))19 b FN(as)i(a)h(function)d(decorator)g(when)i(de\002ning)e(a)j(wrapper)e (function.)208 5258 y(F)o(or)f(e)o(xample:)p 0 5549 3901 4 v 0 5649 a FI(6.6.)52 b FJ(functools)22 b FI(\227)h(Higher)g(order)g (functions)g(and)h(oper)o(ations)g(on)f(callab)n(le)i(objects)o(.)880 b(181)p eop end %%Page: 182 194 TeXDict begin 182 193 bop 802 174 a FA(>>>)45 b(def)f (my_decorator\(f\):)802 266 y(...)224 b(@wraps\(f\))802 357 y(...)g(def)44 b(wrapper\()1700 370 y(*)1745 357 y(args,)2013 370 y(**)2103 357 y(kwds\):)802 448 y(...)403 b(print)44 b('Calling)g(decorated)f(function')802 540 y(...)403 b(return)44 b(f\()1744 553 y(*)1789 540 y(args,)2058 553 y(**)2148 540 y(kwds\))802 631 y(...)224 b(return)44 b(wrapper)802 722 y(...)802 814 y(>>>)h(@my_decorator)802 905 y(...)g(def)f(example\(\):)444 996 y(...)223 b("""Docstring""")802 1088 y(...)h(print)44 b('Called)g(example)f(function')802 1179 y(...)802 1270 y(>>>)i(example\(\))802 1362 y(Calling)f(decorated) f(function)802 1453 y(Called)h(example)g(function)802 1544 y(>>>)h(example.__name__)802 1636 y('example')444 1727 y(>>>)f(example.__doc__)444 1818 y('Docstring')208 2066 y FN(W)m(ithout)19 b(the)g(use)h(of)g(this)g(decorator)e(f)o (actory)-5 b(,)18 b(the)h(name)g(of)h(the)f(e)o(xample)g(function)f(w)o (ould)h(ha)n(v)o(e)g(been)g FJ('wrapper')p FN(,)f(and)208 2165 y(the)i(docstring)f(of)g(the)i(original)e FJ(example\(\))g FN(w)o(ould)g(ha)n(v)o(e)h(been)f(lost.)0 2450 y Fv(6.6.1)100 b Fm(partial)26 b Fv(Objects)0 2653 y FJ(partial)19 b FN(objects)h(are)h(callable)e(objects)h(created)g(by)g FJ(partial\(\))p FN(.)j(The)o(y)d(ha)n(v)o(e)f(three)h(read-only)e (attrib)n(utes:)0 2800 y FD(func)208 2900 y FN(A)h(callable)g(object)f (or)h(function.)j(Calls)f(to)e(the)g FJ(partial)f FN(object)g(will)i (be)f(forw)o(arded)e(to)i FJ(func)f FN(with)i(ne)n(w)e(ar)o(guments)f (and)208 2999 y(k)o(e)o(yw)o(ords.)0 3146 y FD(args)208 3246 y FN(The)23 b(leftmost)g(positional)f(ar)o(guments)g(that)h(will)h (be)g(prepended)c(to)k(the)f(positional)g(ar)o(guments)e(pro)o(vided)g (to)i(a)h FJ(partial)208 3345 y FN(object)19 b(call.)0 3492 y FD(keywords)208 3592 y FN(The)g(k)o(e)o(yw)o(ord)g(ar)o(guments) f(that)i(will)h(be)f(supplied)f(when)h(the)g FJ(partial)g FN(object)f(is)i(called.)0 3739 y FJ(partial)k FN(objects)g(are)h(lik)o (e)g FJ(function)f FN(objects)g(in)h(that)g(the)o(y)f(are)h(callable,)g (weak)g(referencable,)e(and)h(can)h(ha)n(v)o(e)f(attrib)n(utes.)0 3838 y(There)18 b(are)g(some)h(important)e(dif)n(ferences.)23 b(F)o(or)18 b(instance,)g(the)h FJ(__name__)f FN(and)g FJ(__doc__)g FN(attrib)n(utes)g(are)h(not)f(created)g(automat-)0 3938 y(ically)-5 b(.)24 b(Also,)19 b FJ(partial)g FN(objects)f (de\002ned)g(in)h(classes)h(beha)n(v)o(e)e(lik)o(e)h(static)h(methods)d (and)i(do)f(not)h(transform)e(into)i(bound)e(methods)0 4038 y(during)i(instance)g(attrib)n(ute)h(look-up.)0 4365 y FE(6.7)121 b Fx(operator)31 b FE(\227)i(Standard)i(oper)o(ators) g(as)e(functions)n(.)0 4598 y FN(The)15 b FJ(operator)g FN(module)f(e)o(xports)g(a)i(set)g(of)f(functions)f(implemented)g(in)h (C)i(corresponding)12 b(to)j(the)h(intrinsic)f(operators)f(of)h (Python.)0 4698 y(F)o(or)22 b(e)o(xample,)g FJ(operator.add\(x,)47 b(y\))23 b FN(is)g(equi)n(v)n(alent)e(to)i(the)f(e)o(xpression)f FJ(x+y)p FN(.)33 b(The)22 b(function)f(names)h(are)g(those)h(used)f (for)0 4797 y(special)e(class)h(methods;)f(v)n(ariants)f(without)h (leading)f(and)g(trailing)h(`)p FJ(__)p FN(')g(are)g(also)g(pro)o (vided)e(for)i(con)m(v)o(enience.)0 4944 y(The)26 b(functions)e(f)o (all)i(into)g(cate)o(gories)f(that)h(perform)e(object)h(comparisons,)h (logical)f(operations,)h(mathematical)f(operations,)g(se-)0 5044 y(quence)19 b(operations,)f(and)i(abstract)g(type)g(tests.)0 5191 y(The)27 b(object)f(comparison)f(functions)g(are)i(useful)f(for)h (all)g(objects,)h(and)e(are)h(named)f(after)h(the)g(rich)f(comparison)f (operators)g(the)o(y)0 5290 y(support:)p 0 5549 3901 4 v 0 5649 a FI(182)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 183 195 TeXDict begin 183 194 bop 0 83 a FD(lt)p FJ(\()p FK(a,)19 b(b)p FJ(\))0 183 y FD(le)p FJ(\()p FK(a,)g(b)p FJ(\))0 282 y FD(eq)p FJ(\()p FK(a,)g(b)p FJ(\))0 382 y FD(ne)p FJ(\()p FK(a,)g(b)p FJ(\))0 482 y FD(ge)p FJ(\()p FK(a,)g(b)p FJ(\))0 581 y FD(gt)p FJ(\()p FK(a,)g(b)p FJ(\))0 681 y FD(__lt__)p FJ(\()p FK(a,)g(b)p FJ(\))0 780 y FD(__le__)p FJ(\()p FK(a,)g(b)p FJ(\))0 880 y FD(__eq__)p FJ(\()p FK(a,)g(b)p FJ(\))0 980 y FD(__ne__)p FJ(\()p FK(a,)g(b)p FJ(\))0 1079 y FD(__ge__)p FJ(\()p FK(a,)g(b)p FJ(\))0 1179 y FD(__gt__)p FJ(\()p FK(a,)g(b)p FJ(\))208 1279 y FN(Perform)j(\223rich)h(comparisons\224)f(between)h FK(a)h FN(and)g FK(b)p FN(.)36 b(Speci\002cally)-5 b(,)23 b FJ(lt\()p FK(a)p FJ(,)49 b FK(b)p FJ(\))24 b FN(is)h(equi)n(v)n (alent)d(to)i FK(a)49 b FJ(<)h FK(b)p FN(,)24 b FJ(le\()p FK(a)p FJ(,)49 b FK(b)p FJ(\))24 b FN(is)208 1378 y(equi)n(v)n(alent)d (to)i FK(a)49 b FJ(<=)h FK(b)p FN(,)23 b FJ(eq\()p FK(a)p FJ(,)49 b FK(b)p FJ(\))23 b FN(is)h(equi)n(v)n(alent)d(to)i FK(a)49 b FJ(==)h FK(b)p FN(,)23 b FJ(ne\()p FK(a)p FJ(,)49 b FK(b)p FJ(\))23 b FN(is)g(equi)n(v)n(alent)f(to)h FK(a)49 b FJ(!=)h FK(b)p FN(,)23 b FJ(gt\()p FK(a)p FJ(,)49 b FK(b)p FJ(\))208 1478 y FN(is)27 b(equi)n(v)n(alent)e(to)i FK(a)49 b FJ(>)h FK(b)26 b FN(and)h FJ(ge\()p FK(a)p FJ(,)48 b FK(b)p FJ(\))27 b FN(is)g(equi)n(v)n(alent)e(to)i FK(a)49 b FJ(>=)h FK(b)p FN(.)44 b(Note)26 b(that)h(unlik)o(e)f(the)h (b)n(uilt-in)f FJ(cmp\(\))p FN(,)h(these)208 1577 y(functions)g(can)i (return)e(an)o(y)h(v)n(alue,)i(which)e(may)h(or)f(may)h(not)f(be)h (interpretable)e(as)i(a)h(Boolean)e(v)n(alue.)50 b(See)29 b(the)g FK(Python)208 1677 y(Refer)m(ence)19 b(Manual)g FN(for)h(more)f(information)f(about)h(rich)h(comparisons.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 1824 y(The)k(logical)g (operations)f(are)i(also)f(generally)f(applicable)h(to)g(all)h (objects,)g(and)f(support)f(truth)h(tests,)i(identity)e(tests,)i(and)e (boolean)0 1924 y(operations:)0 2070 y FD(not_)p FJ(\()p FK(o)p FJ(\))0 2170 y FD(__not__)p FJ(\()p FK(o)p FJ(\))208 2270 y FN(Return)f(the)g(outcome)f(of)i FJ(not)f FK(o)p FN(.)33 b(\(Note)22 b(that)h(there)f(is)h(no)g FJ(__not__\(\))e FN(method)g(for)h(object)h(instances;)g(only)f(the)h(inter)n(-)208 2369 y(preter)c(core)h(de\002nes)g(this)g(operation.)j(The)d(result)g (is)h(af)n(fected)f(by)f(the)h FJ(__nonzero__\(\))f FN(and)g FJ(__len__\(\))h FN(methods.\))0 2516 y FD(truth)p FJ(\()p FK(o)p FJ(\))208 2616 y FN(Return)f FJ(True)h FN(if)h FK(o)f FN(is)h(true,)f(and)f FJ(False)h FN(otherwise.)25 b(This)20 b(is)h(equi)n(v)n(alent)d(to)j(using)e(the)i FJ(bool)f FN(constructor)-5 b(.)0 2763 y FD(is_)p FJ(\()p FK(a,)19 b(b)p FJ(\))208 2862 y FN(Return)g FK(a)50 b FJ(is)f FK(b)p FN(.)25 b(T)-6 b(ests)21 b(object)f(identity)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3009 y FD(is_not)p FJ(\()p FK(a,)g(b)p FJ(\))208 3109 y FN(Return)g FK(a)50 b FJ(is)f(not)g FK(b)p FN(.)25 b(T)-6 b(ests)22 b(object)d(identity)-5 b(.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3256 y(The)h(mathematical)f(and)h(bitwise)g(operations)f(are)h(the)g (most)g(numerous:)0 3403 y FD(abs)p FJ(\()p FK(o)p FJ(\))0 3502 y FD(__abs__)p FJ(\()p FK(o)p FJ(\))208 3602 y FN(Return)f(the)i (absolute)e(v)n(alue)g(of)h FK(o)p FN(.)0 3749 y FD(add)p FJ(\()p FK(a,)f(b)p FJ(\))0 3848 y FD(__add__)p FJ(\()p FK(a,)g(b)p FJ(\))208 3948 y FN(Return)g FK(a)i FJ(+)f FK(b)p FN(,)g(for)g FK(a)g FN(and)g FK(b)g FN(numbers.)0 4095 y FD(and_)p FJ(\()p FK(a,)f(b)p FJ(\))0 4194 y FD(__and__)p FJ(\()p FK(a,)g(b)p FJ(\))208 4294 y FN(Return)g(the)i(bitwise)f(and)g (of)g FK(a)g FN(and)g FK(b)p FN(.)0 4441 y FD(div)p FJ(\()p FK(a,)f(b)p FJ(\))0 4541 y FD(__div__)p FJ(\()p FK(a,)g(b)p FJ(\))208 4640 y FN(Return)g FK(a)i FJ(/)f FK(b)g FN(when)g FJ(__future__.division)d FN(is)k(not)f(in)h(ef)n(fect.)j(This)c(is)h (also)g(kno)n(wn)e(as)h(\223classic\224)h(di)n(vision.)0 4787 y FD(floordiv)p FJ(\()p FK(a,)d(b)p FJ(\))0 4887 y FD(__floordiv__)p FJ(\()p FK(a,)g(b)p FJ(\))208 4986 y FN(Return)h FK(a)i FJ(//)f FK(b)p FN(.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 5133 y FD(inv)p FJ(\()p FK(o)p FJ(\))0 5233 y FD(invert)p FJ(\()p FK(o)p FJ(\))0 5332 y FD(__inv__)p FJ(\()p FK(o)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(6.7.)52 b FJ(operator)22 b FI(\227)h(Standard)h(oper)o (ators)f(as)f(functions)o(.)1847 b(183)p eop end %%Page: 184 196 TeXDict begin 184 195 bop 0 83 a FD(__invert__)p FJ(\()p FK(o)p FJ(\))208 183 y FN(Return)17 b(the)h(bitwise)g(in)m(v)o(erse)e (of)i(the)f(number)f FK(o)p FN(.)25 b(This)17 b(is)i(equi)n(v)n(alent)d (to)i FJ(\230)p FK(o)p FN(.)24 b(The)17 b(names)h FJ(invert\(\))f FN(and)g FJ(__invert_-)208 282 y(_\(\))j FN(were)g(added)f(in)h(Python) f(2.0.)0 429 y FD(lshift)p FJ(\()p FK(a,)g(b)p FJ(\))0 529 y FD(__lshift__)p FJ(\()p FK(a,)f(b)p FJ(\))208 628 y FN(Return)h FK(a)i FN(shifted)e(left)i(by)e FK(b)p FN(.)0 775 y FD(mod)p FJ(\()p FK(a,)g(b)p FJ(\))0 875 y FD(__mod__)p FJ(\()p FK(a,)g(b)p FJ(\))208 975 y FN(Return)g FK(a)i FJ(\045)f FK(b)p FN(.)0 1121 y FD(mul)p FJ(\()p FK(a,)f(b)p FJ(\))0 1221 y FD(__mul__)p FJ(\()p FK(a,)g(b)p FJ(\))208 1321 y FN(Return)g FK(a)517 1336 y FJ(*)587 1321 y FK(b)p FN(,)h(for)g FK(a)g FN(and)g FK(b)g FN(numbers.)0 1468 y FD(neg)p FJ(\()p FK(o)p FJ(\))0 1567 y FD(__neg__)p FJ(\()p FK(o)p FJ(\))208 1667 y FN(Return)f FK(o)i FN(ne)o(gated.)0 1814 y FD(or_)p FJ(\()p FK(a,)e(b)p FJ(\))0 1913 y FD(__or__)p FJ(\()p FK(a,)g(b)p FJ(\))208 2013 y FN(Return)g(the)i(bitwise)f(or)g (of)g FK(a)g FN(and)g FK(b)p FN(.)0 2160 y FD(pos)p FJ(\()p FK(o)p FJ(\))0 2259 y FD(__pos__)p FJ(\()p FK(o)p FJ(\))208 2359 y FN(Return)f FK(o)i FN(positi)n(v)o(e.)0 2506 y FD(pow)p FJ(\()p FK(a,)e(b)p FJ(\))0 2606 y FD(__pow__)p FJ(\()p FK(a,)g(b)p FJ(\))208 2705 y FN(Return)g FK(a)517 2720 y FJ(**)637 2705 y FK(b)p FN(,)h(for)g FK(a)g FN(and)f FK(b)i FN(numbers.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 2852 y FD(rshift)p FJ(\()p FK(a,)g(b)p FJ(\))0 2952 y FD(__rshift__)p FJ(\()p FK(a,)f(b)p FJ(\))208 3051 y FN(Return)h FK(a)i FN(shifted)e(right)h(by)g FK(b)p FN(.)0 3198 y FD(sub)p FJ(\()p FK(a,)f(b)p FJ(\))0 3298 y FD(__sub__)p FJ(\()p FK(a,)g(b)p FJ(\))208 3397 y FN(Return)g FK(a)i FJ(-)f FK(b)p FN(.)0 3544 y FD(truediv)p FJ(\()p FK(a,)f(b)p FJ(\))0 3644 y FD(__truediv__)p FJ(\()p FK(a,)f(b)p FJ(\))208 3744 y FN(Return)26 b FK(a)g FJ(/)h FK(b)g FN(when)f FJ(__future__.division)d FN(is)28 b(in)f(ef)n(fect.)43 b(This)27 b(is)g(also)g(kno)n(wn)e(as)j(\223true\224)e(di)n(vision.)88 b(Ne)n(w)26 b(in)208 3843 y(v)o(ersion)18 b(2.2.)0 3990 y FD(xor)p FJ(\()p FK(a,)h(b)p FJ(\))0 4090 y FD(__xor__)p FJ(\()p FK(a,)g(b)p FJ(\))208 4189 y FN(Return)g(the)i(bitwise)f(e)o (xclusi)n(v)o(e)f(or)h(of)g FK(a)g FN(and)g FK(b)p FN(.)0 4336 y FD(index)p FJ(\()p FK(a)p FJ(\))0 4436 y FD(__index__)p FJ(\()p FK(a)p FJ(\))208 4535 y FN(Return)f FK(a)i FN(con)m(v)o(erted)c (to)j(an)h(inte)o(ger)-5 b(.)24 b(Equi)n(v)n(alent)18 b(to)i FK(a)p FJ(.__index__\(\))p FN(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 4682 y(Operations)g(which)h(w)o(ork)f(with)i (sequences)e(include:)0 4829 y FD(concat)p FJ(\()p FK(a,)g(b)p FJ(\))0 4929 y FD(__concat__)p FJ(\()p FK(a,)f(b)p FJ(\))208 5028 y FN(Return)h FK(a)i FJ(+)f FK(b)g FN(for)g FK(a)g FN(and)g FK(b)g FN(sequences.)0 5175 y FD(contains)p FJ(\()p FK(a,)e(b)p FJ(\))0 5275 y FD(__contains__)p FJ(\()p FK(a,)g(b)p FJ(\))208 5374 y FN(Return)j(the)h(outcome)e(of)h (the)h(test)h FK(b)f FJ(in)g FK(a)p FN(.)29 b(Note)22 b(the)g(re)n(v)o(ersed)e(operands.)28 b(The)21 b(name)g FJ(__contains__\(\))f FN(w)o(as)j(added)p 0 5549 3901 4 v 0 5649 a FI(184)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 185 197 TeXDict begin 185 196 bop 208 83 a FN(in)20 b(Python)f(2.0.)0 230 y FD(countOf)p FJ(\()p FK(a,)g(b)p FJ(\))208 330 y FN(Return)g(the)i(number)d(of)i(occurrences)e(of)i FK(b)g FN(in)h FK(a)p FN(.)0 476 y FD(delitem)p FJ(\()p FK(a,)e(b)p FJ(\))0 576 y FD(__delitem__)p FJ(\()p FK(a,)f(b)p FJ(\))208 676 y FN(Remo)o(v)o(e)h(the)h(v)n(alue)f(of)h FK(a)g FN(at)h(inde)o(x)e FK(b)p FN(.)0 823 y FD(delslice)p FJ(\()p FK(a,)f(b,)i(c)p FJ(\))0 922 y FD(__delslice__)p FJ(\()p FK(a,)e(b,)i(c)p FJ(\))208 1022 y FN(Delete)g(the)g(slice)h(of) f FK(a)g FN(from)f(inde)o(x)g FK(b)i FN(to)f(inde)o(x)f FK(c)p FJ(-1)p FN(.)0 1169 y FD(getitem)p FJ(\()p FK(a,)g(b)p FJ(\))0 1268 y FD(__getitem__)p FJ(\()p FK(a,)f(b)p FJ(\))208 1368 y FN(Return)h(the)i(v)n(alue)e(of)h FK(a)g FN(at)h(inde)o(x)e FK(b)p FN(.)0 1515 y FD(getslice)p FJ(\()p FK(a,)f(b,)i(c)p FJ(\))0 1614 y FD(__getslice__)p FJ(\()p FK(a,)e(b,)i(c)p FJ(\))208 1714 y FN(Return)f(the)i(slice)f(of)g FK(a)h FN(from)e(inde)o(x)g FK(b)h FN(to)g(inde)o(x)f FK(c)p FJ(-1)p FN(.)0 1861 y FD(indexOf)p FJ(\()p FK(a,)g(b)p FJ(\))208 1961 y FN(Return)g(the)i(inde)o(x)d(of)i(the)h(\002rst)g(of)e (occurrence)f(of)i FK(b)h FN(in)f FK(a)p FN(.)0 2107 y FD(repeat)p FJ(\()p FK(a,)f(b)p FJ(\))0 2207 y FD(__repeat__)p FJ(\()p FK(a,)f(b)p FJ(\))208 2307 y FN(Return)h FK(a)517 2322 y FJ(*)587 2307 y FK(b)h FN(where)g FK(a)g FN(is)h(a)g(sequence)e (and)h FK(b)g FN(is)h(an)f(inte)o(ger)-5 b(.)0 2454 y FD(sequenceIncludes)p FJ(\()p FK(...)p FJ(\))208 2553 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(2.0.)24 b FN(Use)d FJ(contains\(\))e FN(instead.)208 2686 y(Alias)i(for)e FJ(contains\(\))p FN(.)0 2833 y FD(setitem)p FJ(\()p FK(a,)g(b,)h(c)p FJ(\))0 2932 y FD(__setitem__)p FJ(\()p FK(a,)e(b,)i(c)p FJ(\))208 3032 y FN(Set)g(the)h(v)n(alue)e(of)h FK(a)g FN(at)h(inde)o(x)e FK(b)h FN(to)h FK(c)p FN(.)0 3179 y FD(setslice)p FJ(\()p FK(a,)d(b,)i(c,)h(v)p FJ(\))0 3279 y FD(__setslice__)p FJ(\()p FK(a,)d(b,)i(c,)g(v)p FJ(\))208 3378 y FN(Set)g(the)h(slice)g(of)e FK(a)i FN(from)e(inde)o(x) g FK(b)h FN(to)g(inde)o(x)f FK(c)p FJ(-1)i FN(to)f(the)g(sequence)f FK(v)p FN(.)0 3525 y(Man)o(y)h(operations)f(ha)n(v)o(e)i(an)f (\223in-place\224)g(v)o(ersion.)26 b(The)20 b(follo)n(wing)g(functions) f(pro)o(vide)g(a)i(more)f(primiti)n(v)o(e)g(access)h(to)g(in-place)f (op-)0 3625 y(erators)f(than)h(the)g(usual)g(syntax)f(does;)h(for)g(e)o (xample,)e(the)i(statement)g FJ(x)49 b(+=)h(y)20 b FN(is)h(equi)n(v)n (alent)e(to)h FJ(x)49 b(=)h(operator.iadd\(x,)0 3724 y(y\))p FN(.)27 b(Another)20 b(w)o(ay)h(to)g(put)f(it)i(is)g(to)f(say)g (that)g FJ(z)49 b(=)h(operator.iadd\(x,)d(y\))21 b FN(is)h(equi)n(v)n (alent)d(to)i(the)g(compound)d(statement)i FJ(z)0 3824 y(=)50 b(x;)f(z)h(+=)f(y)p FN(.)0 3971 y FD(iadd)p FJ(\()p FK(a,)19 b(b)p FJ(\))0 4070 y FD(__iadd__)p FJ(\()p FK(a,)f(b)p FJ(\))208 4170 y(a)49 b(=)h(iadd\(a,)e(b\))21 b FN(is)g(equi)n(v)n (alent)d(to)j FJ(a)49 b(+=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d (2.5.)0 4317 y FD(iand)p FJ(\()p FK(a,)h(b)p FJ(\))0 4417 y FD(__iand__)p FJ(\()p FK(a,)f(b)p FJ(\))208 4516 y(a)49 b(=)h(iand\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)49 b(&=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 4663 y FD(iconcat)p FJ(\()p FK(a,)h(b)p FJ(\))0 4763 y FD(__iconcat__)p FJ(\()p FK(a,)f(b)p FJ(\))208 4862 y(a)49 b(=)h(iconcat\(a,)e(b\))20 b FN(is)h(equi)n(v)n(alent)e(to)h FJ(a)50 b(+=)f(b)21 b FN(for)e FK(a)i FN(and)e FK(b)h FN(sequences.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 5009 y FD(idiv)p FJ(\()p FK(a,)g(b)p FJ(\))0 5109 y FD(__idiv__)p FJ(\()p FK(a,)f(b)p FJ(\))208 5208 y(a)49 b(=)h(idiv\(a,)e(b\))31 b FN(is)g(equi)n(v)n(alent)e(to)i FJ(a)50 b(/=)f(b)31 b FN(when)f FJ(__future__.division)d FN(is)32 b(not)e(in)h(ef)n(fect.) 112 b(Ne)n(w)30 b(in)208 5308 y(v)o(ersion)18 b(2.5.)p 0 5549 3901 4 v 0 5649 a FI(6.7.)52 b FJ(operator)22 b FI(\227)h(Standard)h(oper)o(ators)f(as)f(functions)o(.)1847 b(185)p eop end %%Page: 186 198 TeXDict begin 186 197 bop 0 83 a FD(ifloordiv)p FJ(\()p FK(a,)18 b(b)p FJ(\))0 183 y FD(__ifloordiv__)p FJ(\()p FK(a,)f(b)p FJ(\))208 282 y(a)49 b(=)h(ifloordiv\(a,)d(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)49 b(//=)h(b)p FN(.)h(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 429 y FD(ilshift)p FJ(\()p FK(a,)g(b)p FJ(\))0 529 y FD(__ilshift__)p FJ(\()p FK(a,)f(b)p FJ(\))208 628 y(a)49 b(=)h(ilshift\(a,)e(b\))20 b FN(is)h(equi)n(v)n(alent)e(to)h FJ(a)50 b(<<=)f(b)p FN(.)i(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 775 y FD(imod)p FJ(\()p FK(a,)g(b)p FJ(\))0 875 y FD(__imod__)p FJ(\()p FK(a,)f(b)p FJ(\))208 975 y(a)49 b(=)h(imod\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)49 b(\045=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 1121 y FD(imul)p FJ(\()p FK(a,)h(b)p FJ(\))0 1221 y FD(__imul__)p FJ(\()p FK(a,)f(b)p FJ(\))208 1321 y(a)49 b(=)h(imul\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)1549 1336 y(*)1599 1321 y(=)50 b(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 1468 y FD(ior)p FJ(\()p FK(a,)h(b)p FJ(\))0 1567 y FD(__ior__)p FJ(\()p FK(a,)g(b)p FJ(\))208 1667 y(a)49 b(=)h(ior\(a,)f(b\))20 b FN(is)h(equi)n(v)n(alent)d(to)j FJ(a)49 b(|=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 1814 y FD(ipow)p FJ(\()p FK(a,)g(b)p FJ(\))0 1913 y FD(__ipow__)p FJ(\()p FK(a,)f(b)p FJ(\))208 2013 y(a)49 b(=)h(ipow\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)1549 2028 y(**)1649 2013 y(=)50 b(b)p FN(.)h(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 2160 y FD(irepeat)p FJ(\()p FK(a,)g(b)p FJ(\))0 2259 y FD(__irepeat__)p FJ(\()p FK(a,)f(b)p FJ(\))208 2359 y(a)49 b(=)h(irepeat\(a,)e(b\))23 b FN(is)h(equi)n(v)n(alent)d(to)i FJ(a)1709 2374 y(*)1759 2359 y(=)50 b(b)23 b FN(where)f FK(a)h FN(is)h(a)f(sequence)f(and)g FK(b)h FN(is)g(an)g(inte)o(ger)-5 b(.)66 b(Ne)n(w)23 b(in)g(v)o(ersion)208 2459 y(2.5.)0 2606 y FD(irshift)p FJ(\()p FK(a,)c(b)p FJ(\))0 2705 y FD(__irshift__)p FJ(\()p FK(a,)f(b)p FJ(\))208 2805 y(a)49 b(=)h(irshift\(a,)e(b\))20 b FN(is)h(equi)n(v)n(alent)e(to)h FJ(a)50 b(>>=)f(b)p FN(.)i(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2952 y FD(isub)p FJ(\()p FK(a,)g(b)p FJ(\))0 3051 y FD(__isub__)p FJ(\()p FK(a,)f(b)p FJ(\))208 3151 y(a)49 b(=)h(isub\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)49 b(-=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 3298 y FD(itruediv)p FJ(\()p FK(a,)g(b)p FJ(\))0 3397 y FD(__itruediv__)p FJ(\()p FK(a,)g(b)p FJ(\))208 3497 y(a)49 b(=)h(itruediv\(a,)e(b\))26 b FN(is)i(equi)n(v)n(alent)d(to)i FJ(a)49 b(/=)h(b)27 b FN(when)f FJ(__future__.division)d FN(is)28 b(in)f(ef)n(fect.)89 b(Ne)n(w)26 b(in)208 3597 y(v)o(ersion)18 b(2.5.)0 3744 y FD(ixor)p FJ(\()p FK(a,)h(b)p FJ(\))0 3843 y FD(__ixor__)p FJ(\()p FK(a,)f(b)p FJ(\))208 3943 y(a)49 b(=)h(ixor\(a,)e(b\))21 b FN(is)g(equi)n(v)n(alent)d(to)j FJ(a)49 b(\210=)h(b)p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 4090 y(The)j FJ(operator)f FN(module)f(also)i(de\002nes)g(a)h(fe)n(w)e(predicates)g (to)i(test)f(the)g(type)g(of)g(objects.)26 b FL(Note:)g FN(Be)c(careful)e(not)h(to)g(misinterpret)0 4189 y(the)16 b(results)g(of)g(these)g(functions;)g(only)f FJ(isCallable\(\))g FN(has)h(an)o(y)f(measure)g(of)h(reliability)f(with)h(instance)g (objects.)23 b(F)o(or)16 b(e)o(xample:)236 4427 y FA(>>>)45 b(class)f(C:)236 4519 y(...)224 b(pass)236 4610 y(...)236 4701 y(>>>)45 b(import)e(operator)236 4793 y(>>>)i(o)f(=)h(C\(\))236 4884 y(>>>)g(operator.isMappingType\(o\))236 4975 y(True)0 5260 y FD(isCallable)p FJ(\()p FK(o)p FJ(\))208 5360 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(2.0.)24 b FN(Use)d(the)f FJ(callable\(\))f FN(b)n(uilt-in)h(function)e (instead.)p 0 5549 3901 4 v 0 5649 a FI(186)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 187 199 TeXDict begin 187 198 bop 208 83 a FN(Returns)17 b(true)g(if)h(the)g (object)f FK(o)g FN(can)h(be)f(called)h(lik)o(e)f(a)h(function,)f (otherwise)g(it)h(returns)f(f)o(alse.)24 b(T)m(rue)17 b(is)i(returned)c(for)i(functions,)208 183 y(bound)h(and)i(unbound)d (methods,)i(class)i(objects,)f(and)f(instance)h(objects)g(which)g (support)e(the)j FJ(__call__\(\))e FN(method.)0 330 y FD(isMappingType)p FJ(\()p FK(o)p FJ(\))208 429 y FN(Returns)i(true)f (if)i(the)f(object)g FK(o)g FN(supports)f(the)h(mapping)f(interf)o (ace.)27 b(This)21 b(is)h(true)f(for)f(dictionaries)h(and)f(all)i (instance)f(objects)208 529 y(de\002ning)30 b FJ(__getitem__)p FN(.)57 b FL(W)-5 b(ar)o(ning:)47 b FN(There)31 b(is)h(no)f(reliable)g (w)o(ay)h(to)g(test)g(if)g(an)f(instance)h(supports)e(the)i(complete) 208 628 y(mapping)18 b(protocol)g(since)i(the)g(interf)o(ace)f(itself)h (is)h(ill-de\002ned.)j(This)c(mak)o(es)f(this)i(test)g(less)g(useful)e (than)g(it)i(otherwise)e(might)208 728 y(be.)0 875 y FD(isNumberType)p FJ(\()p FK(o)p FJ(\))208 975 y FN(Returns)g(true)h (if)g(the)g(object)f FK(o)h FN(represents)f(a)h(number)-5 b(.)23 b(This)d(is)h(true)f(for)f(all)h(numeric)f(types)g(implemented)f (in)i(C.)h FL(W)-5 b(ar)o(ning:)208 1074 y FN(There)21 b(is)j(no)e(reliable)g(w)o(ay)h(to)f(test)i(if)f(an)f(instance)g (supports)g(the)h(complete)e(numeric)g(interf)o(ace)h(since)h(the)f (interf)o(ace)g(itself)208 1174 y(is)f(ill-de\002ned.)i(This)e(mak)o (es)f(this)h(test)g(less)g(useful)f(than)f(it)i(otherwise)f(might)f (be.)0 1321 y FD(isSequenceType)p FJ(\()p FK(o)p FJ(\))208 1420 y FN(Returns)26 b(true)f(if)i(the)f(object)g FK(o)g FN(supports)f(the)i(sequence)e(protocol.)41 b(This)26 b(returns)g(true)f(for)h(all)h(objects)f(which)g(de\002ne)f(se-)208 1520 y(quence)18 b(methods)g(in)h(C,)h(and)f(for)g(all)h(instance)f (objects)g(de\002ning)f FJ(__getitem__)p FN(.)23 b FL(W)-5 b(ar)o(ning:)24 b FN(There)18 b(is)j(no)e(reliable)g(w)o(ay)208 1620 y(to)f(test)h(if)g(an)f(instance)g(supports)f(the)h(complete)f (sequence)h(interf)o(ace)f(since)h(the)h(interf)o(ace)e(itself)i(is)g (ill-de\002ned.)k(This)c(mak)o(es)208 1719 y(this)h(test)h(less)h (useful)d(than)h(it)h(otherwise)e(might)h(be.)0 1866 y(Example:)k(Build)c(a)h(dictionary)d(that)j(maps)f(the)g(ordinals)f (from)g FJ(0)i FN(to)f FJ(255)g FN(to)h(their)f(character)f(equi)n(v)n (alents.)236 2104 y FA(>>>)45 b(import)e(operator)236 2196 y(>>>)i(d)f(=)h({})236 2287 y(>>>)g(keys)f(=)g(range\(256\))236 2378 y(>>>)h(vals)f(=)g(map\(chr,)g(keys\))236 2470 y(>>>)h (map\(operator.setitem,)c([d])1537 2483 y(*)1582 2470 y(len\(keys\),)h(keys,)i(vals\))0 2756 y FN(The)26 b FJ(operator)e FN(module)h(also)h(de\002nes)g(tools)g(for)f(generalized) f(attrib)n(ute)h(and)h(item)g(lookups.)40 b(These)26 b(are)f(useful)h(for)f(making)0 2856 y(f)o(ast)19 b(\002eld)g(e)o (xtractors)f(as)h(ar)o(guments)e(for)h FJ(map\(\))p FN(,)g FJ(sorted\(\))p FN(,)g FJ(itertools.groupby\(\))p FN(,)e(or)i(other)g (functions)g(that)h(e)o(xpect)0 2955 y(a)i(function)d(ar)o(gument.)0 3102 y FD(attrgetter)p FJ(\()p FK(attr)r FC([)p FK(,)g(ar)m(gs...)12 b FC(])p FJ(\))208 3202 y FN(Return)38 b(a)g(callable)h(object)e(that)i (fetches)f FK(attr)j FN(from)c(its)j(operand.)77 b(If)39 b(more)e(than)h(one)g(attrib)n(ute)g(is)h(requested,)j(re-)208 3301 y(turns)27 b(a)i(tuple)e(of)h(attrib)n(utes.)48 b(After)m(,)29 b(`)p FJ(f=attrgetter\('name'\))p FN(',)d(the)i(call)g (`)p FJ(f\(b\))p FN(')f(returns)g(`)p FJ(b.name)p FN('.)47 b(After)m(,)208 3401 y(`)p FJ(f=attrgetter\('name',)e('date'\))p FN(',)17 b(the)h(call)h(`)p FJ(f\(b\))p FN(')e(returns)g(`)p FJ(\(b.name,)48 b(b.date\))p FN('.)g(Ne)n(w)18 b(in)g(v)o(ersion)208 3501 y(2.4.)75 b(Changed)19 b(in)i(v)o(ersion)d(2.5:)i(Added)f(support) g(for)h(multiple)f(attrib)n(utes.)0 3648 y FD(itemgetter)p FJ(\()p FK(item)p FC([)p FK(,)f(ar)m(gs...)12 b FC(])p FJ(\))208 3747 y FN(Return)23 b(a)h(callable)f(object)h(that)f(fetches) h FK(item)g FN(from)f(its)h(operand.)34 b(If)23 b(more)g(than)g(one)g (item)h(is)h(requested,)e(returns)g(a)h(tuple)208 3847 y(of)19 b(items.)25 b(After)m(,)18 b(`)p FJ(f=itemgetter\(2\))p FN(',)e(the)k(call)f(`)p FJ(f\(b\))p FN(')g(returns)f(`)p FJ(b[2])p FN('.)24 b(After)m(,)19 b(`)p FJ(f=itemgetter\(2,5,3\))p FN(',)208 3946 y(the)24 b(call)h(`)p FJ(f\(b\))p FN(')f(returns)g(`)p FJ(\(b[2],)49 b(b[5],)f(b[3]\))p FN('.)78 b(Ne)n(w)25 b(in)g(v)o(ersion)e(2.4.)117 b(Changed)23 b(in)i(v)o(ersion)f(2.5:)g (Added)208 4046 y(support)18 b(for)i(multiple)f(item)i(e)o(xtraction.)0 4193 y(Examples:)236 4340 y FA(>>>)45 b(from)f(operator)f(import)h (itemgetter)236 4431 y(>>>)h(inventory)e(=)i([\('apple',)e(3\),)h (\('banana',)f(2\),)h(\('pear',)g(5\),)g(\('orange',)f(1\)])236 4522 y(>>>)i(getcount)e(=)i(itemgetter\(1\))236 4614 y(>>>)g(map\(getcount,)d(inventory\))236 4705 y([3,)j(2,)f(5,)h(1])236 4796 y(>>>)g(sorted\(inventory,)d(key=getcount\))236 4888 y([\('orange',)h(1\),)i(\('banana',)e(2\),)h(\('apple',)f(3\),)i (\('pear',)e(5\)])p 0 5549 3901 4 v 0 5649 a FI(6.7.)52 b FJ(operator)22 b FI(\227)h(Standard)h(oper)o(ators)f(as)f(functions)o (.)1847 b(187)p eop end %%Page: 188 200 TeXDict begin 188 199 bop 0 83 a Fv(6.7.1)100 b(Mapping)30 b(Oper)o(ators)f(to)e(Functions)0 286 y FN(This)18 b(table)h(sho)n(ws)f (ho)n(w)g(abstract)g(operations)f(correspond)e(to)k(operator)d(symbols) i(in)g(the)g(Python)g(syntax)f(and)h(the)g(functions)f(in)i(the)0 386 y FJ(operator)g FN(module.)245 607 y FL(Operation)p 1031 637 4 100 v 653 w(Syntax)p 1738 637 V 279 w(Function)p 195 640 3511 4 v 245 710 a FN(Addition)p 1031 740 4 100 v 728 w FK(a)49 b FJ(+)h FK(b)p 1738 740 V 286 w FJ(add\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 809 y FN(Concatenation)p 1031 839 V 432 w FK(seq1)g FJ(+)h FK(seq2)p 1738 839 V 175 w FJ(concat\()p FK(seq1)p FJ(,)e FK(seq2)p FJ(\))245 909 y FN(Containment)18 b(T)-6 b(est)p 1031 939 V 379 w FK(o)50 b FJ(in)f FK(seq)p 1738 939 V 227 w FJ(contains\()p FK(seq)p FJ(,)f FK(o)p FJ(\))245 1009 y FN(Di)n(vision)p 1031 1039 V 740 w FK(a)h FJ(/)h FK(b)p 1738 1039 V 286 w FJ(div\()p FK(a)p FJ(,)f FK(b)p FJ(\))g(#)20 b FN(without)g FJ(__future__.division)245 1108 y FN(Di)n(vision)p 1031 1138 V 740 w FK(a)49 b FJ(/)h FK(b)p 1738 1138 V 286 w FJ(truediv\()p FK(a)p FJ(,)e FK(b)p FJ(\))h(#)20 b FN(with)h FJ(__future__.division)245 1208 y FN(Di)n(vision)p 1031 1238 V 715 w FK(a)49 b FJ(//)h FK(b)p 1738 1238 V 261 w FJ(floordiv\()p FK(a)p FJ(,)e FK(b)p FJ(\))245 1308 y FN(Bitwise)21 b(And)p 1031 1337 V 607 w FK(a)49 b FJ(&)h FK(b)p 1738 1337 V 286 w FJ(and_\()p FK(a)p FJ(,)e FK(b)p FJ(\))245 1407 y FN(Bitwise)21 b(Exclusi)n(v)o(e)e(Or)p 1031 1437 V 318 w FK(a)49 b FJ(\210)h FK(b)p 1738 1437 V 286 w FJ(xor\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 1507 y FN(Bitwise)21 b(In)m(v)o(ersion)p 1031 1537 V 485 w FJ(\230)49 b FK(a)p 1738 1537 V 332 w FJ(invert\()p FK(a)p FJ(\))245 1606 y FN(Bitwise)21 b(Or)p 1031 1636 V 663 w FK(a)49 b FJ(|)h FK(b)p 1738 1636 V 286 w FJ(or_\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 1706 y FN(Exponentiation)p 1031 1736 V 489 w FK(a)1336 1721 y FJ(**)1486 1706 y FK(b)p 1738 1736 V 261 w FJ(pow\()p FK(a)p FJ(,)g FK(b)p FJ(\))245 1806 y FN(Identity)p 1031 1836 V 740 w FK(a)g FJ(is)h FK(b)p 1738 1836 V 261 w FJ(is_\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 1905 y FN(Identity)p 1031 1935 V 640 w FK(a)h FJ(is)f(not)g FK(b)p 1738 1935 V 162 w FJ(is_not\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 2005 y FN(Inde)o(x)o(ed)17 b(Assignment)p 1031 2035 V 275 w FK(o)p FJ([)p FK(k)q FJ(])50 b(=)f FK(v)p 1738 2035 V 220 w FJ(setitem\()p FK(o)p FJ(,)f FK(k)q FJ(,)i FK(v)p FJ(\))245 2105 y FN(Inde)o(x)o(ed)17 b(Deletion)p 1031 2135 V 380 w FJ(del)49 b FK(o)p FJ([)p FK(k)q FJ(])p 1738 2135 V 213 w(delitem\()p FK(o)p FJ(,)f FK(k)q FJ(\))245 2204 y FN(Inde)o(xing)p 1031 2234 V 754 w FK(o)p FJ([)p FK(k)q FJ(])p 1738 2234 V 313 w(getitem\()p FK(o)p FJ(,)g FK(k)q FJ(\))245 2304 y FN(Left)20 b(Shift)p 1031 2334 V 679 w FK(a)49 b FJ(<<)h FK(b)p 1738 2334 V 261 w FJ(lshift\()p FK(a)p FJ(,)e FK(b)p FJ(\))245 2403 y FN(Modulo)p 1031 2433 V 760 w FK(a)h FJ(\045)h FK(b)p 1738 2433 V 286 w FJ(mod\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 2503 y FN(Multiplication)p 1031 2533 V 548 w FK(a)1361 2518 y FJ(*)1461 2503 y FK(b)p 1738 2533 V 286 w FJ(mul\()p FK(a)p FJ(,)g FK(b)p FJ(\))245 2603 y FN(Ne)o(gation)18 b(\(Arithmetic\))p 1031 2633 V 331 w FJ(-)49 b FK(a)p 1738 2633 V 332 w FJ(neg\()p FK(a)p FJ(\))245 2702 y FN(Ne)o(gation)18 b(\(Logical\))p 1031 2732 V 387 w FJ(not)49 b FK(a)p 1738 2732 V 282 w FJ(not_\()p FK(a)p FJ(\))245 2802 y FN(Right)20 b(Shift)p 1031 2832 V 633 w FK(a)49 b FJ(>>)h FK(b)p 1738 2832 V 261 w FJ(rshift\()p FK(a)p FJ(,)e FK(b)p FJ(\))245 2902 y FN(Sequence)19 b(Repitition)p 1031 2932 V 328 w FK(seq)1405 2917 y FJ(*)1505 2902 y FK(i)p 1738 2932 V 261 w FJ(repeat\()p FK(seq)p FJ(,)48 b FK(i)p FJ(\))245 3001 y FN(Slice)20 b(Assignment)p 1031 3031 V 254 w FK(seq)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])g FN(=)g FK(values)p 1738 3031 V 99 w FJ(setslice\()p FK(seq)p FJ(,)48 b FK(i)p FJ(,)h FK(j)p FJ(,)h FK(values)p FJ(\))245 3101 y FN(Slice)20 b(Deletion)p 1031 3131 V 415 w FJ(del)50 b FK(seq)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])p 1738 3131 V 149 w(delslice\()p FK(seq)p FJ(,)e FK(i)p FJ(,)h FK(j)p FJ(\))245 3201 y FN(Slicing)p 1031 3230 V 752 w FK(seq)p FJ([)p FK(i)p FJ(:)p FK(j)p FJ(])p 1738 3230 V 249 w(getslice\()p FK(seq)p FJ(,)f FK(i)p FJ(,)h FK(j)p FJ(\))245 3300 y FN(String)19 b(F)o(ormatting)p 1031 3330 V 437 w FK(s)50 b FJ(\045)f FK(o)p 1738 3330 V 291 w FJ(mod\()p FK(s)p FJ(,)g FK(o)p FJ(\))245 3400 y FN(Subtraction)p 1031 3430 V 640 w FK(a)g FJ(-)h FK(b)p 1738 3430 V 286 w FJ(sub\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 3499 y FN(T)m(ruth)19 b(T)-6 b(est)p 1031 3529 V 781 w FK(o)p 1738 3529 V 382 w FJ(truth\()p FK(o)p FJ(\))245 3599 y FN(Ordering)p 1031 3629 V 723 w FK(a)49 b FJ(<)h FK(b)p 1738 3629 V 286 w FJ(lt\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 3699 y FN(Ordering)p 1031 3729 V 698 w FK(a)g FJ(<=)h FK(b)p 1738 3729 V 261 w FJ(le\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 3798 y FN(Equality)p 1031 3828 V 717 w FK(a)g FJ(==)h FK(b)p 1738 3828 V 261 w FJ(eq\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 3898 y FN(Dif)n(ference)p 1031 3928 V 645 w FK(a)g FJ(!=)h FK(b)p 1738 3928 V 261 w FJ(ne\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 3998 y FN(Ordering)p 1031 4027 V 698 w FK(a)g FJ(>=)h FK(b)p 1738 4027 V 261 w FJ(ge\()p FK(a)p FJ(,)f FK(b)p FJ(\))245 4097 y FN(Ordering)p 1031 4127 V 723 w FK(a)g FJ(>)h FK(b)p 1738 4127 V 286 w FJ(gt\()p FK(a)p FJ(,)f FK(b)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(188)1997 b(Chapter)24 b(6.)52 b(Numer)q(ic)23 b(and)h(Mathematical)g(Modules)p eop end %%Page: 189 201 TeXDict begin 189 200 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3495 427 y FG(SEVEN)p 0 515 V 1771 978 a FT(Inter)5 b(net)58 b(Data)g(Handling)0 1468 y FN(This)20 b(chapter)f(describes)h(modules)f (which)h(support)f(handling)f(data)i(formats)g(commonly)d(used)j(on)g (the)g(Internet.)50 1611 y FD(email.iterators)97 b FN(Iterate)19 b(o)o(v)o(er)g(a)i(message)f(object)g(tree.)50 1711 y FD(mailcap)497 b FN(Mailcap)19 b(\002le)i(handling.)50 1810 y FD(mailbox)497 b FN(Manipulate)19 b(mailbox)o(es)f(in)j(v)n (arious)e(formats)50 1910 y FD(mhlib)597 b FN(Manipulate)19 b(MH)h(mailbox)o(es)f(from)g(Python.)50 2010 y FD(mimetools)397 b FN(T)-7 b(ools)20 b(for)f(parsing)h(MIME-style)f(message)h(bodies.)50 2109 y FD(mimetypes)397 b FN(Mapping)18 b(of)i(\002lename)g(e)o (xtensions)f(to)h(MIME)g(types.)50 2209 y FD(MimeWriter)347 b FN(Generic)19 b(MIME)h(\002le)h(writer)-5 b(.)50 2309 y FD(mimify)547 b FN(Mimi\002cation)19 b(and)h(unmimi\002cation)e(of)i (mail)g(messages.)50 2408 y FD(multifile)397 b FN(Support)18 b(for)i(reading)f(\002les)i(which)e(contain)h(distinct)g(parts,)g(such) g(as)h(some)f(MIME)f(data.)50 2508 y FD(rfc822)547 b FN(P)o(arse)20 b(RFC)i(2822)c(style)j(mail)f(messages.)50 2607 y FD(base64)547 b FN(RFC)21 b(3548:)j(Base16,)c(Base32,)g(Base64)g (Data)h(Encodings)50 2707 y FD(binhex)547 b FN(Encode)18 b(and)i(decode)f(\002les)i(in)f(binhe)o(x4)e(format.)50 2807 y FD(binascii)447 b FN(T)-7 b(ools)20 b(for)f(con)m(v)o(erting)f (between)h(binary)g(and)h(v)n(arious)h FH(A)t(S)t(C)t(I)t(I)r FN(-encoded)e(binary)g(representations.)50 2906 y FD(quopri)547 b FN(Encode)18 b(and)i(decode)f(\002les)i(using)f(the)g(MIME)g (quoted-printable)c(encoding.)50 3006 y FD(uu)747 b FN(Encode)18 b(and)i(decode)f(\002les)i(in)f(uuencode)e(format.)0 3308 y FE(7.1)121 b Fx(email)32 b FE(\227)g(An)i(email)f(and)h(MIME)f (handling)i(pac)n(kage)0 3541 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 3688 y(The)h FJ(email)h FN(package)e(is)j(a)f(library)f(for)g(managing) f(email)i(messages,)g(including)e(MIME)h(and)g(other)g(RFC)j (2822-based)18 b(message)0 3788 y(documents.)29 b(It)22 b(subsumes)g(most)g(of)g(the)g(functionality)e(in)j(se)n(v)o(eral)e (older)g(standard)g(modules)g(such)h(as)h FJ(rfc822)p FN(,)f FJ(mimetools)p FN(,)0 3887 y FJ(multifile)p FN(,)e(and)g(other)h (non-standard)d(packages)h(such)i(as)h FJ(mimecntl)p FN(.)k(It)c(is)g(speci\002cally)e FK(not)h FN(designed)f(to)h(do)g(an)o (y)f(sending)0 3987 y(of)i(email)h(messages)g(to)g(SMTP)g(\(RFC)h (2821\),)d(NNTP)-9 b(,)23 b(or)f(other)g(serv)o(ers;)i(those)e(are)h (functions)e(of)i(modules)e(such)i(as)g FJ(smtplib)0 4087 y FN(and)k FJ(nntplib)p FN(.)47 b(The)27 b FJ(email)h FN(package)e(attempts)i(to)g(be)f(as)i(RFC-compliant)e(as)h(possible,)h (supporting)d(in)i(addition)e(to)i(RFC)0 4186 y(2822,)19 b(such)g(MIME-related)g(RFCs)j(as)f(RFC)g(2045,)e(RFC)j(2046,)c(RFC)k (2047,)c(and)i(RFC)i(2231.)0 4333 y(The)17 b(primary)g(distinguishing)f (feature)g(of)i(the)g FJ(email)f FN(package)g(is)h(that)g(it)h(splits)f (the)g(parsing)f(and)g(generating)f(of)i(email)f(messages)0 4433 y(from)25 b(the)h(internal)f FK(object)g(model)g FN(representation)f(of)h(email.)42 b(Applications)25 b(using)g(the)h FJ(email)f FN(package)f(deal)i(primarily)e(with)0 4532 y(objects;)19 b(you)f(can)h(add)g(sub-objects)f(to)h(messages,)g (remo)o(v)o(e)e(sub-objects)h(from)g(messages,)h(completely)f (re-arrange)e(the)k(contents,)0 4632 y(etc.)36 b(There)23 b(is)h(a)g(separate)g(parser)f(and)g(a)h(separate)f(generator)f(which)h (handles)g(the)h(transformation)d(from)i(\003at)h(te)o(xt)g(to)f(the)h (object)0 4732 y(model,)c(and)g(then)h(back)f(to)h(\003at)h(te)o(xt)e (again.)26 b(There)20 b(are)h(also)h(handy)d(subclasses)i(for)g(some)f (common)f(MIME)i(object)f(types,)h(and)f(a)0 4831 y(fe)n(w)h (miscellaneous)f(utilities)h(that)g(help)g(with)g(such)f(common)f (tasks)j(as)f(e)o(xtracting)e(and)i(parsing)e(message)i(\002eld)g(v)n (alues,)g(creating)0 4931 y(RFC-compliant)e(dates,)i(etc.)0 5078 y(The)28 b(follo)n(wing)g(sections)g(describe)g(the)h (functionality)e(of)h(the)h FJ(email)f FN(package.)49 b(The)29 b(ordering)d(follo)n(ws)j(a)g(progression)d(that)0 5177 y(should)17 b(be)h(common)f(in)h(applications:)23 b(an)18 b(email)g(message)g(is)h(read)f(as)h(\003at)f(te)o(xt)g(from)g (a)g(\002le)h(or)f(other)f(source,)h(the)g(te)o(xt)g(is)h(parsed)e(to)0 5277 y(produce)g(the)j(object)f(structure)g(of)g(the)g(email)h (message,)f(this)h(structure)f(is)h(manipulated,)d(and)i(\002nally)-5 b(,)19 b(the)h(object)f(tree)g(is)i(rendered)0 5377 y(back)f(into)f (\003at)i(te)o(xt.)p 0 5549 3901 4 v 3762 5649 a FI(189)p eop end %%Page: 190 202 TeXDict begin 190 201 bop 0 83 a FN(It)22 b(is)h(perfectly)d(feasible)i (to)g(create)f(the)h(object)g(structure)e(out)i(of)f(whole)h(cloth)f (\227)i(i.e.)30 b(completely)20 b(from)h(scratch.)29 b(From)22 b(there,)f(a)0 183 y(similar)f(progression)f(can)h(be)g(tak)o (en)f(as)i(abo)o(v)o(e.)0 330 y(Also)16 b(included)f(are)g(detailed)h (speci\002cations)f(of)h(all)g(the)g(classes)h(and)e(modules)g(that)h (the)g FJ(email)f FN(package)g(pro)o(vides,)g(the)g(e)o(xception)0 429 y(classes)22 b(you)f(might)f(encounter)g(while)h(using)g(the)g FJ(email)g FN(package,)f(some)h(auxiliary)f(utilities,)i(and)e(a)i(fe)n (w)f(e)o(xamples.)27 b(F)o(or)21 b(users)0 529 y(of)i(the)h(older)f FJ(mimelib)g FN(package,)g(or)h(pre)n(vious)e(v)o(ersions)h(of)g(the)h FJ(email)f FN(package,)g(a)h(section)g(on)f(dif)n(ferences)f(and)h (porting)g(is)0 628 y(pro)o(vided.)0 775 y FL(See)e(Also:)0 922 y FN(Module)e FJ(smtplib)g FN(\(section)h(18.13\):)208 1022 y(SMTP)g(protocol)f(client)0 1169 y(Module)g FJ(nntplib)g FN(\(section)h(18.12\):)208 1268 y(NNTP)g(protocol)f(client)0 1553 y Fv(7.1.1)100 b(Representing)30 b(an)f(email)g(message)0 1756 y FN(The)23 b(central)g(class)i(in)e(the)h FJ(email)f FN(package)f(is)j(the)e FJ(Message)g FN(class,)i(imported)d(from)h(the) g FJ(email.message)f FN(module.)34 b(It)24 b(is)0 1856 y(the)c(base)g(class)h(for)e(the)h FJ(email)g FN(object)f(model.)24 b FJ(Message)c FN(pro)o(vides)e(the)i(core)f(functionality)f(for)i (setting)g(and)f(querying)f(header)0 1955 y(\002elds,)i(and)g(for)g (accessing)g(message)g(bodies.)0 2102 y(Conceptually)-5 b(,)28 b(a)h FJ(Message)e FN(object)h(consists)h(of)f FK(header)o(s)g FN(and)g FK(payloads)p FN(.)48 b(Headers)28 b(are)g(RFC)i(2822)d(style)i(\002eld)f(names)g(and)0 2202 y(v)n(alues)23 b(where)f(the)i(\002eld)f(name)g(and)g(v)n(alue)f (are)h(separated)g(by)f(a)i(colon.)33 b(The)23 b(colon)f(is)j(not)e (part)f(of)h(either)g(the)h(\002eld)f(name)g(or)g(the)0 2301 y(\002eld)d(v)n(alue.)0 2448 y(Headers)29 b(are)h(stored)f(and)g (returned)e(in)j(case-preserving)d(form)i(b)n(ut)g(are)h(matched)e (case-insensiti)n(v)o(ely)-5 b(.)51 b(There)29 b(may)g(also)h(be)f(a)0 2548 y(single)23 b(en)m(v)o(elope)f(header)m(,)g(also)i(kno)n(wn)e(as)i (the)g FK(Unix-F)-5 b(r)l(om)23 b FN(header)f(or)h(the)h FJ(From_)f FN(header)-5 b(.)34 b(The)23 b(payload)f(is)i(either)f(a)h (string)f(in)0 2648 y(the)e(case)g(of)g(simple)f(message)h(objects)g (or)f(a)h(list)h(of)f FJ(Message)f FN(objects)g(for)g(MIME)h(container) e(documents)g(\(e.g.)26 b FO(m)o(ultipar)s(t/*)19 b FN(and)0 2747 y FO(message/rfc822)p FN(\).)0 2894 y FJ(Message)k FN(objects)g(pro)o(vide)e(a)j(mapping)e(style)i(interf)o(ace)e(for)h (accessing)g(the)h(message)f(headers,)g(and)g(an)h(e)o(xplicit)f (interf)o(ace)f(for)0 2994 y(accessing)f(both)g(the)h(headers)f(and)g (the)g(payload.)28 b(It)22 b(pro)o(vides)e(con)m(v)o(enience)f(methods) h(for)h(generating)f(a)i(\003at)g(te)o(xt)g(representation)0 3093 y(of)29 b(the)g(message)f(object)h(tree,)i(for)d(accessing)h (commonly)d(used)j(header)f(parameters,)h(and)g(for)f(recursi)n(v)o (ely)f(w)o(alking)h(o)o(v)o(er)g(the)0 3193 y(object)20 b(tree.)0 3340 y(Here)g(are)g(the)g(methods)g(of)f(the)i FJ(Message)e FN(class:)0 3487 y FL(class)i FD(Message)p FJ(\(\))208 3586 y FN(The)e(constructor)g(tak)o(es)h(no)g(ar)o (guments.)0 3733 y FD(as_string)p FJ(\()p FC([)p FK(unixfr)l(om)12 b FC(])p FJ(\))208 3833 y FN(Return)j(the)h(entire)g(message)g (\003attened)g(as)g(a)h(string.)23 b(When)16 b(optional)f FK(unixfr)l(om)h FN(is)h FJ(True)p FN(,)f(the)g(en)m(v)o(elope)e (header)h(is)i(included)208 3932 y(in)j(the)g(returned)e(string.)25 b FK(unixfr)l(om)20 b FN(def)o(aults)g(to)g FJ(False)p FN(.)208 4065 y(Note)h(that)h(this)h(method)d(is)j(pro)o(vided)c(as)k (a)f(con)m(v)o(enience)d(and)i(may)g(not)h(al)o(w)o(ays)g(format)f(the) g(message)h(the)g(w)o(ay)g(you)f(w)o(ant.)208 4165 y(F)o(or)d(e)o (xample,)f(by)h(def)o(ault)g(it)h(mangles)f(lines)h(that)f(be)o(gin)f (with)i FJ(From)49 b FN(.)25 b(F)o(or)18 b(more)g(\003e)o(xibility)-5 b(,)17 b(instantiate)i(a)g FJ(Generator)208 4265 y FN(instance)g(and)h (use)g(its)i FJ(flatten\(\))d FN(method)g(directly)-5 b(.)23 b(F)o(or)d(e)o(xample:)444 4489 y FA(from)44 b(cStringIO)f (import)h(StringIO)444 4580 y(from)g(email.generator)e(import)i (Generator)444 4671 y(fp)g(=)h(StringIO\(\))444 4763 y(g)f(=)h(Generator\(fp,)e(mangle_from_=False,)e(maxheaderlen=60\))444 4854 y(g.flatten\(msg\))444 4945 y(text)j(=)h(fp.getvalue\(\))0 5143 y FD(__str__)p FJ(\(\))208 5243 y FN(Equi)n(v)n(alent)18 b(to)i FJ(as_string\(unixfrom=True\))p FN(.)0 5390 y FD(is_multipart)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(190)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 191 203 TeXDict begin 191 202 bop 208 83 a FN(Return)18 b FJ(True)h FN(if)g(the)g(message')-5 b(s)19 b(payload)e(is)j(a)f(list)h(of)e(sub-) p FJ(Message)g FN(objects,)g(otherwise)g(return)g FJ(False)p FN(.)24 b(When)19 b FJ(is_-)208 183 y(multipart\(\))f FN(returns)i(F)o(alse,)g(the)g(payload)f(should)g(be)h(a)h(string)f (object.)0 330 y FD(set_unixfrom)p FJ(\()p FK(unixfr)l(om)p FJ(\))208 429 y FN(Set)g(the)h(message')-5 b(s)20 b(en)m(v)o(elope)e (header)h(to)h FK(unixfr)l(om)p FN(,)g(which)f(should)h(be)g(a)g (string.)0 576 y FD(get_unixfrom)p FJ(\(\))208 676 y FN(Return)f(the)i(message')-5 b(s)20 b(en)m(v)o(elope)e(header)-5 b(.)24 b(Def)o(aults)c(to)h FJ(None)f FN(if)g(the)g(en)m(v)o(elope)e (header)h(w)o(as)i(ne)n(v)o(er)e(set.)0 823 y FD(attach)p FJ(\()p FK(payload)r FJ(\))208 922 y FN(Add)25 b(the)g(gi)n(v)o(en)f FK(payload)i FN(to)g(the)f(current)f(payload,)h(which)g(must)h(be)f FJ(None)h FN(or)f(a)h(list)g(of)f FJ(Message)g FN(objects)g(before)g (the)208 1022 y(call.)35 b(After)24 b(the)g(call,)g(the)g(payload)e (will)j(al)o(w)o(ays)f(be)f(a)i(list)f(of)g FJ(Message)f FN(objects.)35 b(If)23 b(you)g(w)o(ant)h(to)g(set)g(the)g(payload)e(to) i(a)208 1121 y(scalar)c(object)g(\(e.g.)k(a)c(string\),)g(use)g FJ(set_payload\(\))e FN(instead.)0 1268 y FD(get_payload)p FJ(\()p FC([)p FK(i)p FC([)p FK(,)g(decode)12 b FC(])g(])p FJ(\))208 1368 y FN(Return)21 b(a)i(reference)e(the)h(current)f (payload,)g(which)h(will)h(be)f(a)h(list)g(of)f FJ(Message)g FN(objects)g(when)f FJ(is_multipart\(\))g FN(is)208 1468 y FJ(True)p FN(,)i(or)g(a)h(string)f(when)f FJ(is_multipart\(\))g FN(is)i FJ(False)p FN(.)34 b(If)23 b(the)g(payload)f(is)i(a)f(list)i (and)e(you)f(mutate)h(the)g(list)h(object,)208 1567 y(you)19 b(modify)f(the)j(message')-5 b(s)20 b(payload)f(in)h(place.)208 1700 y(W)m(ith)g(optional)e(ar)o(gument)g FK(i)p FN(,)i FJ(get_payload\(\))e FN(will)j(return)d(the)i FK(i)p FN(-th)g(element)f(of)h(the)f(payload,)f(counting)g(from)h(zero,)g(if) 208 1800 y FJ(is_multipart\(\))f FN(is)j FJ(True)p FN(.)j(An)d FJ(IndexError)d FN(will)j(be)f(raised)g(if)h FK(i)f FN(is)h(less)h (than)d(0)h(or)g(greater)f(than)h(or)g(equal)f(to)i(the)208 1899 y(number)e(of)h(items)i(in)f(the)g(payload.)k(If)c(the)g(payload)f (is)i(a)f(string)g(\(i.e.)27 b FJ(is_multipart\(\))19 b FN(is)i FJ(False)p FN(\))g(and)f FK(i)i FN(is)g(gi)n(v)o(en,)d(a)208 1999 y FJ(TypeError)g FN(is)i(raised.)208 2132 y(Optional)j FK(decode)f FN(is)j(a)f(\003ag)g(indicating)f(whether)g(the)h(payload)e (should)h(be)h(decoded)e(or)h(not,)i(according)d(to)i(the)f FO(Content-)208 2231 y(T)-9 b(r)o(ansf)n(er-Encoding:)23 b FN(header)-5 b(.)28 b(When)22 b FJ(True)f FN(and)g(the)g(message)h (is)g(not)f(a)h(multipart,)f(the)g(payload)f(will)i(be)g(decoded)d(if)j (this)208 2331 y(header')-5 b(s)21 b(v)n(alue)g(is)j(`)p FJ(quoted-printable)p FN(')19 b(or)j(`)p FJ(base64)p FN('.)29 b(If)22 b(some)h(other)e(encoding)f(is)j(used,)f(or)g FO(Content-T)-9 b(r)o(ansf)n(er-)208 2431 y(Encoding:)22 b FN(header)c(is)i(missing,)e(or)h(if)g(the)g(payload)f(has)h(bogus)f (base64)g(data,)g(the)h(payload)f(is)i(returned)d(as-is)i (\(undecoded\).)208 2530 y(If)26 b(the)g(message)h(is)g(a)g(multipart)f (and)g(the)g FK(decode)f FN(\003ag)i(is)g FJ(True)p FN(,)h(then)e FJ(None)g FN(is)i(returned.)42 b(The)26 b(def)o(ault)g(for)f FK(decode)h FN(is)208 2630 y FJ(False)p FN(.)0 2777 y FD(set_payload)p FJ(\()p FK(payload)r FC([)p FK(,)16 b(c)o(har)o(set)d FC(])p FJ(\))208 2876 y FN(Set)21 b(the)h(entire)f (message)g(object')-5 b(s)21 b(payload)e(to)j FK(payload)r FN(.)k(It)21 b(is)i(the)e(client')-5 b(s)22 b(responsibility)d(to)j (ensure)e(the)h(payload)f(in)m(v)n(ari-)208 2976 y(ants.)25 b(Optional)19 b FK(c)o(har)o(set)j FN(sets)f(the)f(message')-5 b(s)21 b(def)o(ault)e(character)g(set;)i(see)g FJ(set_charset\(\))d FN(for)i(details.)208 3109 y(Changed)e(in)j(v)o(ersion)e(2.2.2:)g FK(c)o(har)o(set)i FN(ar)o(gument)d(added.)0 3256 y FD(set_charset)p FJ(\()p FK(c)o(har)o(set)q FJ(\))208 3355 y FN(Set)58 b(the)h(character)d(set)j(of)f(the)g(payload)f(to)h FK(c)o(har)o(set)q FN(,)68 b(which)58 b(can)g(either)f(be)i(a)f FJ(Charset)g FN(instance)f(\(see)208 3455 y FJ(email.charset)p FN(\),)14 b(a)j(string)f(naming)f(a)i(character)e(set,)j(or)e FJ(None)p FN(.)23 b(If)16 b(it)h(is)h(a)e(string,)h(it)g(will)g(be)f(con)m(v)o (erted)e(to)j(a)f FJ(Charset)208 3555 y FN(instance.)23 b(If)15 b FK(c)o(har)o(set)j FN(is)e FJ(None)p FN(,)h(the)f FJ(charset)f FN(parameter)f(will)j(be)f(remo)o(v)o(ed)d(from)i(the)h FO(Content-T)-9 b(ype:)20 b FN(header)-5 b(.)23 b(An)o(ything)208 3654 y(else)d(will)h(generate)e(a)i FJ(TypeError)p FN(.)208 3787 y(The)k(message)h(will)h(be)f(assumed)f(to)h(be)g(of)g(type)f FO(te)n(xt/*)h FN(encoded)e(with)i FK(c)o(har)o(set.input)p 2818 3787 25 4 v 28 w(c)o(har)o(set)q FN(.)42 b(It)27 b(will)f(be)g(con)m(v)o(erted)d(to)208 3887 y FK(c)o(har)o(set.output)p 691 3887 V 27 w(c)o(har)o(set)30 b FN(and)e(encoded)e(properly)-5 b(,)28 b(if)h(needed,)g(when)f(generating)e(the)j(plain)f(te)o(xt)g (representation)e(of)j(the)208 3986 y(message.)24 b(MIME)c(headers)f (\()p FO(MIME-V)-6 b(ersion:)p FN(,)19 b FO(Content-T)-9 b(ype:)p FN(,)17 b FO(Content-T)-9 b(r)o(ansf)n(er-Encodin)o(g:)o FN(\))20 b(will)h(be)f(added)f(as)i(needed.)208 4119 y(Ne)n(w)f(in)g(v)o(ersion)f(2.2.2.)0 4266 y FD(get_charset)p FJ(\(\))208 4366 y FN(Return)g(the)i FJ(Charset)e FN(instance)h (associated)g(with)g(the)g(message')-5 b(s)21 b(payload.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.2.2.)0 4512 y(The)28 b(follo)n(wing)g(methods)f(implement)h(a)h(mapping-lik)o(e)d(interf)o (ace)i(for)h(accessing)f(the)h(message')-5 b(s)29 b(RFC)h(2822)e (headers.)50 b(Note)0 4612 y(that)29 b(there)e(are)i(some)f(semantic)g (dif)n(ferences)f(between)g(these)i(methods)e(and)h(a)h(normal)e (mapping)g(\(i.e.)49 b(dictionary\))27 b(interf)o(ace.)0 4712 y(F)o(or)h(e)o(xample,)h(in)g(a)g(dictionary)d(there)j(are)f(no)g (duplicate)g(k)o(e)o(ys,)i(b)n(ut)e(here)g(there)g(may)g(be)h (duplicate)e(message)h(headers.)49 b(Also,)0 4811 y(in)25 b(dictionaries)e(there)h(is)h(no)f(guaranteed)e(order)h(to)i(the)f(k)o (e)o(ys)g(returned)f(by)h FJ(keys\(\))p FN(,)g(b)n(ut)h(in)f(a)h FJ(Message)f FN(object,)g(headers)g(are)0 4911 y(al)o(w)o(ays)h (returned)d(in)i(the)g(order)f(the)o(y)h(appeared)e(in)i(the)g (original)f(message,)i(or)f(were)g(added)f(to)h(the)g(message)g(later) -5 b(.)37 b(An)o(y)24 b(header)0 5011 y(deleted)c(and)f(then)h (re-added)e(are)i(al)o(w)o(ays)h(appended)d(to)i(the)g(end)g(of)g(the)g (header)f(list.)0 5157 y(These)h(semantic)g(dif)n(ferences)e(are)i (intentional)f(and)h(are)g(biased)g(to)n(w)o(ard)f(maximal)h(con)m(v)o (enience.)0 5304 y(Note)g(that)g(in)h(all)g(cases,)f(an)o(y)g(en)m(v)o (elope)e(header)h(present)g(in)h(the)h(message)f(is)h(not)f(included)e (in)j(the)f(mapping)e(interf)o(ace.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g (handling)h(pac)n(kage)1797 b(191)p eop end %%Page: 192 204 TeXDict begin 192 203 bop 0 83 a FD(__len__)p FJ(\(\))208 183 y FN(Return)19 b(the)i(total)f(number)e(of)i(headers,)f(including)g (duplicates.)0 330 y FD(__contains__)p FJ(\()p FK(name)p FJ(\))208 429 y FN(Return)f(true)h(if)h(the)f(message)g(object)f(has)i (a)f(\002eld)h(named)e FK(name)p FN(.)24 b(Matching)18 b(is)i(done)e(case-insensiti)n(v)o(ely)f(and)i FK(name)g FN(should)208 529 y(not)g(include)h(the)g(trailing)f(colon.)24 b(Used)d(for)e(the)h FJ(in)h FN(operator)m(,)d(e.g.:)444 753 y FA(if)44 b('message-id')f(in)i(myMessage:)623 844 y(print)f('Message-ID:',)f(myMessage['message-id'])0 1046 y FD(__getitem__)p FJ(\()p FK(name)p FJ(\))208 1145 y FN(Return)22 b(the)h(v)n(alue)f(of)h(the)g(named)e(header)h(\002eld.) 33 b FK(name)23 b FN(should)f(not)g(include)g(the)h(colon)f(\002eld)h (separator)-5 b(.)32 b(If)23 b(the)g(header)f(is)208 1245 y(missing,)d FJ(None)h FN(is)i(returned;)c(a)j FJ(KeyError)e FN(is)i(ne)n(v)o(er)e(raised.)208 1378 y(Note)e(that)g(if)h(the)f (named)g(\002eld)g(appears)g(more)f(than)h(once)g(in)g(the)h(message') -5 b(s)17 b(headers,)g(e)o(xactly)f(which)h(of)g(those)g(\002eld)h(v)n (alues)208 1478 y(will)i(be)h(returned)d(is)j(unde\002ned.)i(Use)e(the) f FJ(get_all\(\))f FN(method)g(to)h(get)h(the)f(v)n(alues)g(of)f(all)i (the)f(e)o(xtant)g(named)f(headers.)0 1624 y FD(__setitem__)p FJ(\()p FK(name)o(,)e(val)p FJ(\))208 1724 y FN(Add)29 b(a)h(header)f(to)h(the)g(message)f(with)h(\002eld)g(name)g FK(name)f FN(and)g(v)n(alue)g FK(val)p FN(.)54 b(The)30 b(\002eld)g(is)g(appended)e(to)i(the)g(end)f(of)h(the)208 1824 y(message')-5 b(s)20 b(e)o(xisting)f(\002elds.)208 1957 y(Note)j(that)h(this)g(does)g FK(not)f FN(o)o(v)o(erwrite)f(or)i (delete)g(an)o(y)f(e)o(xisting)g(header)f(with)i(the)g(same)g(name.)32 b(If)23 b(you)f(w)o(ant)g(to)h(ensure)f(that)208 2056 y(the)e(ne)n(w)g(header)f(is)i(the)f(only)f(one)h(present)g(in)g(the)g (message)g(with)h(\002eld)f(name)g FK(name)p FN(,)f(delete)h(the)g (\002eld)g(\002rst,)h(e.g.:)444 2280 y FA(del)44 b(msg['subject'])444 2372 y(msg['subject'])e(=)j('Python)f(roolz!')0 2573 y FD(__delitem__)p FJ(\()p FK(name)p FJ(\))208 2673 y FN(Delete)24 b(all)i(occurrences)c(of)j(the)f(\002eld)h(with)g(name)f FK(name)g FN(from)g(the)h(message')-5 b(s)25 b(headers.)37 b(No)25 b(e)o(xception)d(is)k(raised)f(if)g(the)208 2772 y(named)19 b(\002eld)h(isn')o(t)g(present)f(in)i(the)f(headers.)0 2919 y FD(has_key)p FJ(\()p FK(name)p FJ(\))208 3019 y FN(Return)f(true)h(if)h(the)f(message)g(contains)f(a)i(header)e (\002eld)h(named)f FK(name)p FN(,)h(otherwise)f(return)g(f)o(alse.)0 3166 y FD(keys)p FJ(\(\))208 3265 y FN(Return)g(a)i(list)g(of)f(all)h (the)f(message')-5 b(s)20 b(header)g(\002eld)g(names.)0 3412 y FD(values)p FJ(\(\))208 3512 y FN(Return)f(a)i(list)g(of)f(all)h (the)f(message')-5 b(s)20 b(\002eld)h(v)n(alues.)0 3659 y FD(items)p FJ(\(\))208 3758 y FN(Return)e(a)i(list)g(of)f(2-tuples)f (containing)g(all)h(the)h(message')-5 b(s)20 b(\002eld)g(headers)g(and) f(v)n(alues.)0 3905 y FD(get)p FJ(\()p FK(name)p FC([)p FK(,)f(failobj)12 b FC(])p FJ(\))208 4005 y FN(Return)21 b(the)i(v)n(alue)e(of)h(the)h(named)e(header)g(\002eld.)32 b(This)22 b(is)i(identical)d(to)i FJ(__getitem__\(\))d FN(e)o(xcept)i(that)g(optional)f FK(failobj)208 4105 y FN(is)g(returned)d(if)j(the)f(named)f(header)g(is)i(missing)f(\(def)o (aults)g(to)g FJ(None)p FN(\).)0 4251 y(Here)g(are)g(some)g(additional) f(useful)h(methods:)0 4398 y FD(get_all)p FJ(\()p FK(name)p FC([)p FK(,)e(failobj)12 b FC(])p FJ(\))208 4498 y FN(Return)26 b(a)h(list)h(of)f(all)h(the)f(v)n(alues)f(for)g(the)h(\002eld)g(named)f FK(name)p FN(.)45 b(If)27 b(there)f(are)h(no)f(such)h(named)f(headers)g (in)h(the)g(message,)208 4598 y FK(failobj)19 b FN(is)i(returned)e (\(def)o(aults)g(to)h FJ(None)p FN(\).)0 4744 y FD(add_header)p FJ(\()p 555 4744 25 4 v 28 w FK(name)o(,)p 803 4744 V 49 w(value)o(,)g(**)p 1138 4744 V 29 w(par)o(ams)p FJ(\))208 4844 y FN(Extended)d(header)h(setting.)25 b(This)19 b(method)f(is)i (similar)f(to)h FJ(__setitem__\(\))d FN(e)o(xcept)i(that)g(additional)f (header)g(parameters)208 4944 y(can)i(be)h(pro)o(vided)d(as)k(k)o(e)o (yw)o(ord)d(ar)o(guments.)p 1556 4944 V 54 w FK(name)h FN(is)i(the)f(header)e(\002eld)i(to)g(add)g(and)p 2767 4944 V 50 w FK(value)f FN(is)i(the)e FK(primary)h FN(v)n(alue)f(for)h (the)208 5043 y(header)-5 b(.)208 5176 y(F)o(or)24 b(each)h(item)g(in)g (the)g(k)o(e)o(yw)o(ord)e(ar)o(gument)g(dictionary)p 1933 5176 V 53 w FK(par)o(ams)p FN(,)j(the)f(k)o(e)o(y)f(is)i(tak)o(en) f(as)g(the)g(parameter)f(name,)h(with)g(un-)208 5276 y(derscores)e(con)m(v)o(erted)f(to)i(dashes)h(\(since)f(dashes)g(are)g (ille)o(gal)g(in)h(Python)e(identi\002ers\).)37 b(Normally)-5 b(,)23 b(the)i(parameter)e(will)i(be)208 5375 y(added)19 b(as)h FJ(key="value")f FN(unless)h(the)h(v)n(alue)e(is)i FJ(None)p FN(,)f(in)g(which)g(case)h(only)e(the)h(k)o(e)o(y)g(will)h (be)f(added.)p 0 5549 3901 4 v 0 5649 a FI(192)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 193 205 TeXDict begin 193 204 bop 208 83 a FN(Here')-5 b(s)20 b(an)g(e)o(xample:)444 216 y FA(msg.add_header\('Content-Disposition',) 38 b('attachment',)43 b(filename='bud.gif'\))208 405 y FN(This)20 b(will)h(add)e(a)i(header)e(that)h(looks)g(lik)o(e)444 538 y FA(Content-Disposition:)41 b(attachment;)i(filename="bud.gif")0 742 y FD(replace_header)p FJ(\()p 755 742 25 4 v 27 w FK(name)o(,)p 1003 742 V 49 w(value)p FJ(\))208 841 y FN(Replace)19 b(a)i(header)-5 b(.)24 b(Replace)19 b(the)h(\002rst)h (header)e(found)f(in)i(the)f(message)h(that)g(matches)p 2781 841 V 49 w FK(name)p FN(,)f(retaining)g(header)g(order)f(and)208 941 y(\002eld)i(name)g(case.)25 b(If)20 b(no)g(matching)e(header)h(w)o (as)i(found,)e(a)h FJ(KeyError)g FN(is)h(raised.)208 1074 y(Ne)n(w)f(in)g(v)o(ersion)f(2.2.2.)0 1221 y FD(get_content_type)p FJ(\(\))208 1320 y FN(Return)e(the)h(message')-5 b(s)17 b(content)g(type.)24 b(The)17 b(returned)f(string)h(is)i(coerced)d(to)i (lo)n(wer)g(case)g(of)f(the)h(form)e FO(maintype/subtype)p FN(.)22 b(If)208 1420 y(there)f(w)o(as)i(no)f FO(Content-T)-9 b(ype:)26 b FN(header)21 b(in)i(the)f(message)g(the)g(def)o(ault)g (type)g(as)h(gi)n(v)o(en)e(by)g FJ(get_default_type\(\))f FN(will)208 1520 y(be)26 b(returned.)42 b(Since)27 b(according)d(to)j (RFC)h(2045,)f(messages)f(al)o(w)o(ays)h(ha)n(v)o(e)f(a)h(def)o(ault)f (type,)h FJ(get_content_type\(\))208 1619 y FN(will)20 b(al)o(w)o(ays)h(return)e(a)i(v)n(alue.)208 1752 y(RFC)j(2045)d (de\002nes)h(a)h(message')-5 b(s)23 b(def)o(ault)f(type)g(to)h(be)f FO(te)n(xt/plain)e FN(unless)j(it)g(appears)f(inside)h(a)g FO(m)o(ultipar)s(t/digest)c FN(container)m(,)208 1852 y(in)k(which)g(case)g(it)h(w)o(ould)f(be)g FO(message/rfc822)p FN(.)33 b(If)23 b(the)g FO(Content-T)-9 b(ype:)28 b FN(header)22 b(has)i(an)f(in)m(v)n(alid)f(type)h(speci\002cation,)g(RFC)208 1951 y(2045)18 b(mandates)i(that)g(the)g(def)o(ault)g(type)f(be)h FO(te)n(xt/plain)p FN(.)208 2084 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.2.)0 2231 y FD(get_content_maintype)p FJ(\(\))208 2331 y FN(Return)h(the)h (message')-5 b(s)21 b(main)g(content)f(type.)26 b(This)21 b(is)h(the)f FO(maintype)f FN(part)h(of)f(the)h(string)g(returned)e(by) h FJ(get_content_-)208 2430 y(type\(\))p FN(.)208 2563 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.2.)0 2710 y FD(get_content_subtype)p FJ(\(\))208 2810 y FN(Return)25 b(the)h(message')-5 b(s)26 b(sub-content)e(type.)42 b(This)26 b(is)h(the)f FO(subtype)g FN(part)f(of)h(the)g(string)g(returned)e(by)h FJ(get_content_-)208 2909 y(type\(\))p FN(.)208 3042 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.2.) 0 3189 y FD(get_default_type)p FJ(\(\))208 3289 y FN(Return)24 b(the)h(def)o(ault)f(content)g(type.)38 b(Most)26 b(messages)f(ha)n(v)o (e)f(a)h(def)o(ault)f(content)g(type)h(of)f FO(te)n(xt/plain)p FN(,)f(e)o(xcept)h(for)g(messages)208 3388 y(that)c(are)g(subparts)f (of)h FO(m)o(ultipar)s(t/digest)d FN(containers.)24 b(Such)19 b(subparts)h(ha)n(v)o(e)f(a)i(def)o(ault)f(content)f(type)g(of)h FO(message/rfc822)p FN(.)208 3521 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.2.)0 3668 y FD(set_default_type)p FJ(\()p FK(ctype)p FJ(\))208 3768 y FN(Set)k(the)f(def)o(ault)g(content)g(type.)32 b FK(ctype)22 b FN(should)g(either)g(be)h FO(te)n(xt/plain)d FN(or)i FO(message/rfc822)p FN(,)f(although)g(this)i(is)h(not)e (enforced.)208 3867 y(The)d(def)o(ault)h(content)f(type)h(is)h(not)f (stored)f(in)i(the)f FO(Content-T)-9 b(ype:)22 b FN(header)-5 b(.)208 4000 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.2.)0 4147 y FD(get_params)p FJ(\()p FC([)p FK(failobj)p FC([)p FK(,)e(header)r FC([)p FK(,)i(unquote)12 b FC(])g(])g(])p FJ(\))208 4247 y FN(Return)30 b(the)g(message')-5 b(s)31 b FO(Content-T)-9 b(ype:)42 b FN(parameters,)32 b(as)f(a)g(list.)57 b(The)30 b(elements)g(of)g(the)h(returned)d(list)k(are)e(2-tuples)g(of) 208 4346 y(k)o(e)o(y/v)n(alue)19 b(pairs,)j(as)g(split)g(on)f(the)g(`)p FJ(=)p FN(')g(sign.)29 b(The)21 b(left)g(hand)g(side)h(of)f(the)g(`)p FJ(=)p FN(')g(is)i(the)e(k)o(e)o(y)-5 b(,)20 b(while)i(the)f(right)g (hand)f(side)i(is)h(the)208 4446 y(v)n(alue.)31 b(If)22 b(there)g(is)i(no)e(`)p FJ(=)p FN(')g(sign)g(in)h(the)g(parameter)e (the)h(v)n(alue)g(is)h(the)g(empty)e(string,)i(otherwise)f(the)g(v)n (alue)g(is)i(as)f(described)208 4545 y(in)d FJ(get_param\(\))f FN(and)g(is)i(unquoted)d(if)j(optional)e FK(unquote)f FN(is)j FJ(True)f FN(\(the)g(def)o(ault\).)208 4678 y(Optional)26 b FK(failobj)h FN(is)i(the)f(object)f(to)g(return)g(if)h(there)f(is)i (no)e FO(Content-T)-9 b(ype:)37 b FN(header)-5 b(.)46 b(Optional)27 b FK(header)i FN(is)f(the)g(header)e(to)208 4778 y(search)19 b(instead)h(of)g FO(Content-T)-9 b(ype:)p FN(.)208 4911 y(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g FK(unquote)f FN(ar)o(gument)g(added.)0 5058 y FD(get_param)p FJ(\()p FK(par)o(am)p FC([)p FK(,)f(failobj)p FC([)p FK(,)i(header)r FC([)p FK(,)g(unquote)12 b FC(])g(])g(])p FJ(\))208 5157 y FN(Return)k(the)i(v)n(alue)e(of)h(the)g FO(Content-T)-9 b(ype:)21 b FN(header')-5 b(s)17 b(parameter)e FK(par)o(am)i FN(as)h(a)f(string.)24 b(If)17 b(the)g(message)g(has)h (no)f FO(Content-T)-9 b(ype:)208 5257 y FN(header)19 b(or)g(if)i(there)f(is)h(no)f(such)g(parameter)m(,)e(then)h FK(failobj)h FN(is)h(returned)d(\(def)o(aults)i(to)g FJ(None)p FN(\).)208 5390 y(Optional)f FK(header)i FN(if)g(gi)n(v)o (en,)d(speci\002es)j(the)f(message)g(header)f(to)i(use)f(instead)g(of)g FO(Content-T)-9 b(ype:)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g (handling)h(pac)n(kage)1797 b(193)p eop end %%Page: 194 206 TeXDict begin 194 205 bop 208 83 a FN(P)o(arameter)16 b(k)o(e)o(ys)h(are)g(al)o(w)o(ays)h(compared)d(case)j(insensiti)n(v)o (ely)-5 b(.)22 b(The)17 b(return)f(v)n(alue)h(can)g(either)g(be)g(a)h (string,)f(or)g(a)h(3-tuple)e(if)i(the)208 183 y(parameter)h(w)o(as)j (RFC)g(2231)e(encoded.)25 b(When)20 b(it')-5 b(s)22 b(a)g(3-tuple,)d (the)i(elements)g(of)f(the)h(v)n(alue)g(are)f(of)h(the)g(form)f FJ(\(CHARSET,)208 282 y(LANGUAGE,)48 b(VALUE\))p FN(.)27 b(Note)h(that)g(both)g FJ(CHARSET)f FN(and)h FJ(LANGUAGE)f FN(can)h(be)g FJ(None)p FN(,)i(in)e(which)g(case)g(you)g(should)208 382 y(consider)19 b FJ(VALUE)g FN(to)i(be)f(encoded)e(in)j(the)f FJ(us-ascii)f FN(charset.)25 b(Y)-9 b(ou)19 b(can)h(usually)g(ignore)f FJ(LANGUAGE)p FN(.)208 515 y(If)30 b(your)g(application)g(doesn')o(t)f (care)i(whether)f(the)h(parameter)e(w)o(as)j(encoded)d(as)j(in)f(RFC)h (2231,)g(you)e(can)h(collapse)g(the)208 614 y(parameter)c(v)n(alue)h (by)h(calling)g FJ(email.Utils.collapse_rfc2231_valu)o(e\(\))p FN(,)c(passing)k(in)g(the)g(return)f(v)n(alue)208 714 y(from)i FJ(get_param\(\))p FN(.)56 b(This)31 b(will)h(return)e(a)i (suitably)e(decoded)g(Unicode)g(string)g(whn)h(the)g(v)n(alue)g(is)h(a) f(tuple,)j(or)d(the)208 814 y(original)19 b(string)g(unquoted)f(if)j (it)g(isn')o(t.)j(F)o(or)c(e)o(xample:)444 946 y FA(rawparam)43 b(=)i(msg.get_param\('foo'\))444 1038 y(param)f(=)g (email.Utils.collapse_rfc2231_value\(rawpara)o(m\))208 1227 y FN(In)15 b(an)o(y)g(case,)i(the)f(parameter)f(v)n(alue)g (\(either)g(the)h(returned)e(string,)i(or)g(the)g FJ(VALUE)g FN(item)g(in)g(the)g(3-tuple\))e(is)j(al)o(w)o(ays)f(unquoted,)208 1327 y(unless)k FK(unquote)e FN(is)j(set)g(to)g FJ(False)p FN(.)208 1460 y(Changed)d(in)j(v)o(ersion)e(2.2.2:)g FK(unquote)f FN(ar)o(gument)g(added,)g(and)i(3-tuple)f(return)g(v)n (alue)h(possible.)0 1607 y FD(set_param)p FJ(\()p FK(par)o(am,)d(value) p FC([)p FK(,)i(header)r FC([)p FK(,)g(r)m(equote)p FC([)p FK(,)g(c)o(har)o(set)q FC([)p FK(,)h(langua)o(g)o(e)12 b FC(])g(])g(])g(])p FJ(\))208 1706 y FN(Set)29 b(a)g(parameter)e(in)h (the)h FO(Content-T)-9 b(ype:)39 b FN(header)-5 b(.)49 b(If)28 b(the)h(parameter)e(already)g(e)o(xists)i(in)g(the)f(header)m (,)h(its)h(v)n(alue)d(will)j(be)208 1806 y(replaced)e(with)i FK(value)p FN(.)52 b(If)30 b(the)f FO(Content-T)-9 b(ype:)41 b FN(header)29 b(as)h(not)f(yet)h(been)f(de\002ned)f(for)h(this)h (message,)i(it)e(will)g(be)g(set)g(to)208 1905 y FO(te)n(xt/plain)17 b FN(and)j(the)g(ne)n(w)g(parameter)f(v)n(alue)g(will)i(be)f(appended)e (as)j(per)f(RFC)h(2045.)208 2038 y(Optional)d FK(header)i FN(speci\002es)f(an)g(alternati)n(v)o(e)f(header)g(to)h FO(Content-T)-9 b(ype:)p FN(,)16 b(and)j(all)g(parameters)f(will)i(be)f (quoted)f(as)h(necessary)208 2138 y(unless)h(optional)f FK(r)m(equote)g FN(is)i FJ(False)f FN(\(the)g(def)o(ault)f(is)i FJ(True)p FN(\).)208 2271 y(If)30 b(optional)g FK(c)o(har)o(set)i FN(is)g(speci\002ed,)g(the)f(parameter)e(will)j(be)f(encoded)e (according)f(to)j(RFC)h(2231.)56 b(Optional)30 b FK(langua)o(g)o(e)208 2370 y FN(speci\002es)20 b(the)g(RFC)i(2231)d(language,)f(def)o (aulting)h(to)h(the)g(empty)g(string.)k(Both)c FK(c)o(har)o(set)i FN(and)e FK(langua)o(g)o(e)e FN(should)h(be)h(strings.)208 2503 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.2.)0 2650 y FD(del_param)p FJ(\()p FK(par)o(am)p FC([)p FK(,)e(header)r FC([)p FK(,)i(r)m(equote) 12 b FC(])g(])p FJ(\))208 2750 y FN(Remo)o(v)o(e)20 b(the)h(gi)n(v)o (en)g(parameter)f(completely)g(from)g(the)i FO(Content-T)-9 b(ype:)24 b FN(header)-5 b(.)29 b(The)21 b(header)f(will)i(be)g (re-written)e(in)i(place)208 2849 y(without)e(the)h(parameter)f(or)g (its)i(v)n(alue.)27 b(All)22 b(v)n(alues)f(will)h(be)f(quoted)e(as)j (necessary)e(unless)i FK(r)m(equote)e FN(is)i FJ(False)f FN(\(the)f(def)o(ault)208 2949 y(is)h FJ(True)p FN(\).)j(Optional)19 b FK(header)j FN(speci\002es)e(an)g(alternati)n(v)o(e)f(to)i FO(Content-T)-9 b(ype:)p FN(.)208 3082 y(Ne)n(w)20 b(in)g(v)o(ersion)f (2.2.2.)0 3229 y FD(set_type)p FJ(\()p FK(type)p FC([)p FK(,)f(header)c FC(][)p FK(,)k(r)m(equote)12 b FC(])p FJ(\))208 3328 y FN(Set)19 b(the)g(main)f(type)g(and)h(subtype)e(for)h (the)h FO(Content-T)-9 b(ype:)22 b FN(header)-5 b(.)23 b FK(type)c FN(must)g(be)g(a)g(string)f(in)h(the)g(form)f FO(maintype/subtype)p FN(,)208 3428 y(otherwise)h(a)i FJ(ValueError)e FN(is)i(raised.)208 3561 y(This)i(method)e(replaces)i (the)g FO(Content-T)-9 b(ype:)28 b FN(header)m(,)22 b(k)o(eeping)f(all) j(the)f(parameters)f(in)h(place.)33 b(If)23 b FK(r)m(equote)f FN(is)i FJ(False)p FN(,)f(this)208 3660 y(lea)n(v)o(es)d(the)g(e)o (xisting)g(header')-5 b(s)19 b(quoting)f(as)j(is,)g(otherwise)f(the)g (parameters)f(will)i(be)f(quoted)f(\(the)h(def)o(ault\).)208 3793 y(An)i(alternati)n(v)o(e)g(header)f(can)i(be)f(speci\002ed)h(in)f (the)h FK(header)h FN(ar)o(gument.)30 b(When)22 b(the)h FO(Content-T)-9 b(ype:)27 b FN(header)22 b(is)h(set)h(a)f FO(MIME-)208 3893 y(V)-6 b(ersion:)23 b FN(header)c(is)j(also)e(added.) 208 4026 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.2.)0 4173 y FD(get_filename)p FJ(\()p FC([)p FK(failobj)12 b FC(])p FJ(\))208 4272 y FN(Return)21 b(the)h(v)n(alue)f(of)g(the)h FJ(filename)f FN(parameter)f(of)h(the)h FO(Content-Disposition:)h FN(header)e(of)g(the)h(message.)29 b(If)22 b(the)g(header)208 4372 y(does)k(not)g(ha)n(v)o(e)g(a)h FJ(filename)e FN(parameter)m(,)h (this)h(method)e(f)o(alls)i(back)f(to)g(looking)f(for)h(the)g FJ(name)h FN(parameter)-5 b(.)42 b(If)26 b(neither)208 4471 y(is)e(found,)e(or)h(the)h(header)e(is)i(missing,)g(then)f FK(failobj)g FN(is)h(returned.)33 b(The)23 b(returned)e(string)j(will)g (al)o(w)o(ays)g(be)f(unquoted)e(as)j(per)208 4571 y FJ (Utils.unquote\(\))p FN(.)0 4718 y FD(get_boundary)p FJ(\()p FC([)p FK(failobj)12 b FC(])p FJ(\))208 4818 y FN(Return)23 b(the)i(v)n(alue)e(of)h(the)g FJ(boundary)g FN(parameter)e(of)i(the)h FO(Content-T)-9 b(ype:)30 b FN(header)23 b(of)h(the)g(message,)h(or)f FK(failobj)f FN(if)i(either)208 4917 y(the)j(header)f(is)i(missing,)g(or)f(has)h(no) e FJ(boundary)h FN(parameter)-5 b(.)47 b(The)28 b(returned)e(string)i (will)h(al)o(w)o(ays)f(be)g(unquoted)e(as)j(per)208 5017 y FJ(Utils.unquote\(\))p FN(.)0 5164 y FD(set_boundary)p FJ(\()p FK(boundary)p FJ(\))208 5263 y FN(Set)18 b(the)g FJ(boundary)g FN(parameter)e(of)i(the)g FO(Content-T)-9 b(ype:)21 b FN(header)c(to)h FK(boundary)p FN(.)k FJ(set_boundary\(\)) 16 b FN(will)j(al)o(w)o(ays)g(quote)208 5363 y FK(boundary)f FN(if)i(necessary)-5 b(.)24 b(A)d FJ(HeaderParseError)c FN(is)k(raised)f(if)h(the)f(message)g(object)g(has)g(no)g FO(Content-T)-9 b(ype:)22 b FN(header)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(194)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 195 207 TeXDict begin 195 206 bop 208 83 a FN(Note)19 b(that)h(using)g(this)g (method)f(is)h(subtly)g(dif)n(ferent)e(than)h(deleting)g(the)h(old)g FO(Content-T)-9 b(ype:)22 b FN(header)c(and)i(adding)e(a)i(ne)n(w)g (one)208 183 y(with)g(the)g(ne)n(w)g(boundary)d(via)j FJ(add_header\(\))p FN(,)e(because)h FJ(set_boundary\(\))f FN(preserv)o(es)h(the)h(order)f(of)g(the)h FO(Content-)208 282 y(T)-9 b(ype:)29 b FN(header)21 b(in)i(the)g(list)g(of)g(headers.) 31 b(Ho)n(we)n(v)o(er)m(,)21 b(it)i(does)g FK(not)f FN(preserv)o(e)f (an)o(y)h(continuation)e(lines)j(which)f(may)g(ha)n(v)o(e)g(been)208 382 y(present)d(in)h(the)h(original)e FO(Content-T)-9 b(ype:)22 b FN(header)-5 b(.)0 529 y FD(get_content_charset)p FJ(\()p FC([)p FK(failobj)12 b FC(])p FJ(\))208 628 y FN(Return)17 b(the)i FJ(charset)e FN(parameter)g(of)h(the)g FO(Content-T)-9 b(ype:)21 b FN(header)m(,)c(coerced)g(to)h(lo)n(wer)g (case.)25 b(If)18 b(there)g(is)h(no)f FO(Content-T)-9 b(ype:)208 728 y FN(header)m(,)18 b(or)i(if)g(that)h(header)e(has)h(no) g FJ(charset)f FN(parameter)m(,)f FK(failobj)i FN(is)h(returned.)208 861 y(Note)30 b(that)g(this)h(method)d(dif)n(fers)i(from)f FJ(get_charset\(\))f FN(which)i(returns)f(the)h FJ(Charset)g FN(instance)g(for)f(the)h(def)o(ault)208 960 y(encoding)18 b(of)i(the)g(message)g(body)-5 b(.)208 1093 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.2.)0 1240 y FD(get_charsets)p FJ(\()p FC([)p FK(failobj)12 b FC(])p FJ(\))208 1340 y FN(Return)22 b(a)i(list)g(containing)d(the)i(character)f(set)i(names) f(in)g(the)g(message.)34 b(If)22 b(the)i(message)f(is)h(a)f FO(m)o(ultipar)s(t)p FN(,)f(then)h(the)g(list)h(will)208 1439 y(contain)19 b(one)g(element)h(for)g(each)f(subpart)h(in)g(the)g (payload,)e(otherwise,)i(it)h(will)g(be)f(a)g(list)i(of)e(length)f(1.) 208 1572 y(Each)h(item)h(in)g(the)g(list)i(will)e(be)g(a)h(string)e (which)h(is)h(the)f(v)n(alue)f(of)h(the)g FJ(charset)f FN(parameter)g(in)h(the)g FO(Content-T)-9 b(ype:)24 b FN(header)208 1672 y(for)18 b(the)i(represented)d(subpart.)24 b(Ho)n(we)n(v)o(er)m(,)17 b(if)j(the)g(subpart)e(has)i(no)f FO(Content-T)-9 b(ype:)21 b FN(header)m(,)d(no)h FJ(charset)g FN(parameter)m(,)e(or)j(is)208 1772 y(not)f(of)h(the)h FO(te)n(xt)e FN(main)h(MIME)g(type,)g(then)f(that)i(item)f(in)g(the)g (returned)f(list)i(will)g(be)f FK(failobj)p FN(.)0 1918 y FD(walk)p FJ(\(\))208 2018 y FN(The)e FJ(walk\(\))g FN(method)f(is)i(an)f(all-purpose)f(generator)f(which)i(can)h(be)f (used)g(to)h(iterate)f(o)o(v)o(er)f(all)i(the)g(parts)f(and)g(subparts) g(of)g(a)208 2118 y(message)i(object)g(tree,)h(in)f(depth-\002rst)g (tra)n(v)o(ersal)g(order)-5 b(.)26 b(Y)-9 b(ou)20 b(will)h(typically)f (use)h FJ(walk\(\))f FN(as)h(the)g(iterator)f(in)h(a)g FJ(for)f FN(loop;)208 2217 y(each)f(iteration)h(returns)f(the)h(ne)o (xt)g(subpart.)208 2350 y(Here')-5 b(s)20 b(an)g(e)o(xample)f(that)h (prints)g(the)g(MIME)g(type)g(of)g(e)n(v)o(ery)e(part)i(of)g(a)h (multipart)e(message)h(structure:)444 2574 y FA(>>>)44 b(for)g(part)h(in)f(msg.walk\(\):)444 2666 y(...)223 b(print)44 b(part.get_content_type\(\))444 2757 y(multipart/report)444 2848 y(text/plain)444 2940 y(message/delivery-status)444 3031 y(text/plain)444 3122 y(text/plain)444 3214 y(message/rfc822)0 3417 y FN(Changed)33 b(in)i(v)o(ersion)f(2.5:)g(The)h(pre)n(viously)d (deprecated)h(methods)h FJ(get_type\(\))p FN(,)j FJ(get_main_type\(\))p FN(,)f(and)e FJ(get_-)0 3517 y(subtype\(\))19 b FN(were)h(remo)o(v)o (ed.)0 3664 y FJ(Message)25 b FN(objects)g(can)g(also)g(optionally)f (contain)g(tw)o(o)i(instance)f(attrib)n(utes,)h(which)f(can)g(be)g (used)h(when)e(generating)g(the)h(plain)0 3763 y(te)o(xt)20 b(of)g(a)h(MIME)e(message.)0 3910 y FD(preamble)208 4010 y FN(The)25 b(format)f(of)h(a)h(MIME)f(document)e(allo)n(ws)i(for)g (some)g(te)o(xt)h(between)e(the)h(blank)g(line)g(follo)n(wing)f(the)h (headers,)h(and)f(the)208 4109 y(\002rst)20 b(multipart)e(boundary)e (string.)25 b(Normally)-5 b(,)17 b(this)j(te)o(xt)f(is)i(ne)n(v)o(er)c (visible)j(in)f(a)h(MIME-a)o(w)o(are)d(mail)j(reader)e(because)h(it)h (f)o(alls)208 4209 y(outside)j(the)h(standard)f(MIME)g(armor)-5 b(.)36 b(Ho)n(we)n(v)o(er)m(,)23 b(when)g(vie)n(wing)g(the)h(ra)o(w)g (te)o(xt)f(of)h(the)g(message,)h(or)e(when)h(vie)n(wing)f(the)208 4309 y(message)d(in)g(a)h(non-MIME)c(a)o(w)o(are)j(reader)m(,)f(this)i (te)o(xt)f(can)g(become)f(visible.)208 4441 y(The)f FK(pr)m(eamble)g FN(attrib)n(ute)g(contains)h(this)g(leading)f(e)o(xtra-armor)e(te)o(xt) j(for)f(MIME)g(documents.)23 b(When)c(the)g FJ(Parser)f FN(disco)o(v-)208 4541 y(ers)h(some)g(te)o(xt)g(after)g(the)h(headers)e (b)n(ut)h(before)f(the)h(\002rst)h(boundary)d(string,)i(it)h(assigns)f (this)h(te)o(xt)f(to)h(the)f(message')-5 b(s)20 b FK(pr)m(eamble)208 4641 y FN(attrib)n(ute.)j(When)17 b(the)g FJ(Generator)f FN(is)i(writing)e(out)h(the)f(plain)h(te)o(xt)g(representation)e(of)h (a)i(MIME)e(message,)h(and)g(it)h(\002nds)f(the)208 4740 y(message)23 b(has)g(a)h FK(pr)m(eamble)e FN(attrib)n(ute,)h(it)h(will) g(write)g(this)f(te)o(xt)h(in)f(the)g(area)g(between)g(the)g(headers)f (and)h(the)g(\002rst)h(boundary)-5 b(.)208 4840 y(See)20 b FJ(email.parser)f FN(and)g FJ(email.generator)f FN(for)i(details.)208 4973 y(Note)g(that)g(if)g(the)h(message)f(object)f(has)i(no)f (preamble,)e(the)i FK(pr)m(eamble)f FN(attrib)n(ute)h(will)h(be)f FJ(None)p FN(.)0 5120 y FD(epilogue)208 5219 y FN(The)29 b FK(epilo)o(gue)g FN(attrib)n(ute)h(acts)g(the)h(same)f(w)o(ay)g(as)h (the)f FK(pr)m(eamble)f FN(attrib)n(ute,)j(e)o(xcept)d(that)h(it)h (contains)e(te)o(xt)h(that)g(appears)208 5319 y(between)19 b(the)h(last)h(boundary)d(and)h(the)h(end)g(of)g(the)g(message.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h (email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(195)p eop end %%Page: 196 208 TeXDict begin 196 207 bop 208 83 a FN(Changed)18 b(in)i(v)o(ersion)e (2.5:)h(Y)-9 b(ou)19 b(do)h(not)f(need)g(to)h(set)g(the)g(epilogue)e (to)i(the)g(empty)e(string)i(in)g(order)e(for)h(the)h FJ(Generator)e FN(to)208 183 y(print)h(a)i(ne)n(wline)e(at)i(the)f(end) g(of)g(the)g(\002le.)0 330 y FD(defects)208 429 y FN(The)e FK(defects)i FN(attrib)n(ute)f(contains)f(a)i(list)g(of)f(all)h(the)f (problems)f(found)f(when)i(parsing)f(this)i(message.)25 b(See)19 b FJ(email.errors)208 529 y FN(for)g(a)i(detailed)e (description)g(of)h(the)g(possible)g(parsing)f(defects.)208 658 y(Ne)n(w)h(in)g(v)o(ersion)f(2.4.)0 940 y Fv(7.1.2)100 b(P)l(arsing)30 b(email)e(messages)0 1143 y FN(Message)c(object)g (structures)g(can)g(be)g(created)g(in)g(one)g(of)g(tw)o(o)g(w)o(ays:)34 b(the)o(y)24 b(can)g(be)g(created)g(from)f(whole)h(cloth)g(by)f (instantiating)0 1243 y FJ(Message)h FN(objects)g(and)g(stringing)g (them)g(together)f(via)i FJ(attach\(\))e FN(and)h FJ(set_payload\(\))f FN(calls,)j(or)f(the)o(y)e(can)i(be)f(created)0 1342 y(by)c(parsing)f(a)i(\003at)f(te)o(xt)g(representation)f(of)g(the)i (email)f(message.)0 1489 y(The)25 b FJ(email)g FN(package)f(pro)o (vides)g(a)i(standard)e(parser)h(that)h(understands)e(most)h(email)h (document)d(structures,)j(including)e(MIME)0 1589 y(documents.)49 b(Y)-9 b(ou)28 b(can)g(pass)h(the)g(parser)f(a)h(string)f(or)g(a)h (\002le)h(object,)g(and)e(the)g(parser)g(will)i(return)d(to)i(you)f (the)g(root)g FJ(Message)0 1689 y FN(instance)h(of)h(the)g(object)f (structure.)53 b(F)o(or)29 b(simple,)j(non-MIME)27 b(messages)j(the)g (payload)e(of)i(this)g(root)f(object)g(will)i(lik)o(ely)e(be)h(a)0 1788 y(string)g(containing)f(the)h(te)o(xt)g(of)g(the)h(message.)55 b(F)o(or)30 b(MIME)g(messages,)j(the)d(root)g(object)g(will)h(return)e FJ(True)h FN(from)f(its)j FJ(is_-)0 1888 y(multipart\(\))19 b FN(method,)f(and)i(the)g(subparts)g(can)g(be)g(accessed)g(via)g(the)g FJ(get_payload\(\))f FN(and)g FJ(walk\(\))h FN(methods.)0 2035 y(There)e(are)g(actually)g(tw)o(o)g(parser)g(interf)o(aces)g(a)n (v)n(ailable)f(for)h(use,)h(the)f(classic)h FJ(Parser)f FN(API)h(and)f(the)g(incremental)f FJ(FeedParser)0 2134 y FN(API.)k(The)g(classic)h FJ(Parser)e FN(API)i(is)g(\002ne)f(if)h (you)e(ha)n(v)o(e)g(the)h(entire)g(te)o(xt)g(of)g(the)g(message)g(in)g (memory)f(as)h(a)h(string,)f(or)f(if)i(the)f(entire)0 2234 y(message)16 b(li)n(v)o(es)h(in)f(a)h(\002le)h(on)e(the)g(\002le)h (system.)24 b FJ(FeedParser)15 b FN(is)j(more)d(appropriate)f(for)i (when)g(you')l(re)f(reading)g(the)h(message)h(from)0 2334 y(a)i(stream)e(which)h(might)f(block)h(w)o(aiting)f(for)h(more)f (input)h(\(e.g.)23 b(reading)17 b(an)h(email)g(message)g(from)f(a)h (sock)o(et\).)24 b(The)18 b FJ(FeedParser)0 2433 y FN(can)i(consume)f (and)h(parse)f(the)i(message)f(incrementally)-5 b(,)17 b(and)j(only)f(returns)h(the)g(root)f(object)h(when)g(you)f(close)h (the)g(parser)3629 2403 y FF(1)3661 2433 y FN(.)0 2580 y(Note)k(that)f(the)h(parser)f(can)h(be)f(e)o(xtended)f(in)i(limited)f (w)o(ays,)i(and)e(of)h(course)f(you)f(can)i(implement)e(your)h(o)n(wn)g (parser)g(completely)0 2680 y(from)d(scratch.)26 b(There)20 b(is)i(no)e(magical)h(connection)d(between)i(the)h FJ(email)g FN(package')-5 b(s)19 b(b)n(undled)g(parser)i(and)f(the)h FJ(Message)f FN(class,)0 2779 y(so)h(your)d(custom)i(parser)g(can)g (create)g(message)g(object)f(trees)i(an)o(y)e(w)o(ay)h(it)h(\002nds)g (necessary)-5 b(.)0 3045 y FI(F)n(eedP)m(arser)22 b(API)0 3248 y FN(Ne)n(w)e(in)h(v)o(ersion)e(2.4.)0 3395 y(The)24 b FJ(FeedParser)p FN(,)g(imported)e(from)i(the)g FJ(email.feedparser)e FN(module,)h(pro)o(vides)g(an)h(API)h(that)f(is)h(conduci)n(v)o(e)d(to) i(incre-)0 3494 y(mental)k(parsing)f(of)h(email)g(messages,)i(such)e (as)h(w)o(ould)e(be)h(necessary)g(when)f(reading)g(the)h(te)o(xt)g(of)g (an)g(email)g(message)g(from)f(a)0 3594 y(source)i(that)g(can)g(block)g (\(e.g.)51 b(a)30 b(sock)o(et\).)52 b(The)29 b FJ(FeedParser)f FN(can)h(of)h(course)e(be)i(used)f(to)g(parse)g(an)h(email)f(message)g (fully)0 3693 y(contained)18 b(in)i(a)g(string)f(or)h(a)g(\002le,)g(b)n (ut)g(the)f(classic)i FJ(Parser)e FN(API)h(may)f(be)h(more)e(con)m(v)o (enient)f(for)i(such)h(use)g(cases.)25 b(The)20 b(semantics)0 3793 y(and)g(results)g(of)g(the)g(tw)o(o)h(parser)e(APIs)i(are)f (identical.)0 3940 y(The)e FJ(FeedParser)p FN(')-5 b(s)18 b(API)h(is)h(simple;)f(you)f(create)h(an)f(instance,)h(feed)f(it)h(a)g (b)n(unch)f(of)g(te)o(xt)h(until)g(there')-5 b(s)18 b(no)h(more)e(to)i (feed)g(it,)g(then)0 4040 y(close)g(the)g(parser)f(to)h(retrie)n(v)o(e) e(the)i(root)f(message)h(object.)24 b(The)18 b FJ(FeedParser)f FN(is)j(e)o(xtremely)d(accurate)h(when)g(parsing)g(standards-)0 4139 y(compliant)e(messages,)i(and)f(it)h(does)f(a)h(v)o(ery)e(good)g (job)h(of)h(parsing)e(non-compliant)e(messages,)k(pro)o(viding)d (information)g(about)h(ho)n(w)0 4239 y(a)i(message)g(w)o(as)h(deemed)d (brok)o(en.)23 b(It)18 b(will)g(populate)f(a)h(message)g(object')-5 b(s)17 b FK(defects)h FN(attrib)n(ute)g(with)g(a)g(list)h(of)e(an)o(y)g (problems)g(it)h(found)0 4338 y(in)i(a)h(message.)k(See)20 b(the)h FJ(email.errors)d FN(module)h(for)g(the)i(list)g(of)f(defects)g (that)g(it)h(can)f(\002nd.)0 4485 y(Here)g(is)h(the)f(API)h(for)e(the)i FJ(FeedParser)p FN(:)0 4632 y FL(class)g FD(FeedParser)p FJ(\()p FC([)p 782 4632 25 4 v 27 w FK(factory)12 b FC(])p FJ(\))208 4732 y FN(Create)17 b(a)h FJ(FeedParser)f FN(instance.)23 b(Optional)p 1645 4732 V 47 w FK(factory)17 b FN(is)i(a)e(no-ar)o (gument)d(callable)k(that)f(will)i(be)e(called)g(whene)n(v)o(er)f(a)i (ne)n(w)208 4831 y(message)i(object)f(is)i(needed.)j(It)c(def)o(aults)g (to)h(the)f FJ(email.message.Message)d FN(class.)0 4978 y FD(feed)p FJ(\()p FK(data)p FJ(\))208 5078 y FN(Feed)23 b(the)h FJ(FeedParser)f FN(some)g(more)h(data.)35 b FK(data)23 b FN(should)g(be)h(a)g(string)g(containing)e(one)h(or)h(more)f(lines.) 36 b(The)24 b(lines)g(can)208 5178 y(be)19 b(partial)h(and)f(the)h FJ(FeedParser)f FN(will)h(stitch)h(such)e(partial)h(lines)g(together)f (properly)-5 b(.)22 b(The)e(lines)g(in)g(the)g(string)f(can)h(ha)n(v)o (e)p 0 5242 1560 4 v 90 5298 a FB(1)120 5321 y FH(As)h(of)h(email)h (package)h(v)o(ersion)f(3.0,)g(introduced)h(in)f(Python)f(2.4,)h(the)g (classic)g Fz(Parser)e FH(w)o(as)h(re-implemented)j(in)d(terms)h(of)f (the)g Fz(FeedParser)p FH(,)f(so)h(the)0 5400 y(semantics)d(and)e (results)h(are)g(identical)i(between)f(the)f(tw)o(o)f(parsers.)p 0 5549 3901 4 v 0 5649 a FI(196)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 197 209 TeXDict begin 197 208 bop 208 83 a FN(an)o(y)23 b(of)h(the)g(common)e (three)i(line)g(endings,)f(carriage)g(return,)h(ne)n(wline,)g(or)g (carriage)f(return)g(and)g(ne)n(wline)h(\(the)o(y)f(can)h(e)n(v)o(en) 208 183 y(be)c(mix)o(ed\).)0 330 y FD(close)p FJ(\(\))208 429 y FN(Closing)h(a)i FJ(FeedParser)d FN(completes)i(the)f(parsing)g (of)h(all)h(pre)n(viously)c(fed)j(data,)g(and)f(returns)g(the)h(root)g (message)f(object.)208 529 y(It)f(is)h(unde\002ned)d(what)j(happens)d (if)j(you)e(feed)h(more)f(data)h(to)h(a)f(closed)g FJ(FeedParser)p FN(.)0 796 y FI(P)m(arser)i(class)g(API)0 999 y FN(The)c FJ(Parser)f FN(class,)i(imported)e(from)f(the)i FJ(email.parser)f FN(module,)g(pro)o(vides)f(an)i(API)g(that)g(can)g(be)g(used)f(to)i (parse)e(a)i(message)0 1098 y(when)c(the)i(complete)e(contents)g(of)h (the)g(message)g(are)g(a)n(v)n(ailable)f(in)i(a)f(string)g(or)g (\002le.)24 b(The)16 b FJ(email.parser)e FN(module)h(also)h(pro)o (vides)0 1198 y(a)26 b(second)g(class,)i(called)e FJ(HeaderParser)e FN(which)h(can)h(be)g(used)g(if)g(you')l(re)e(only)i(interested)f(in)h (the)g(headers)f(of)h(the)g(message.)0 1297 y FJ(HeaderParser)20 b FN(can)i(be)f(much)g(f)o(aster)h(in)g(these)g(situations,)g(since)g (it)g(does)g(not)f(attempt)h(to)g(parse)f(the)h(message)g(body)-5 b(,)20 b(instead)0 1397 y(setting)g(the)g(payload)f(to)h(the)h(ra)o(w)e (body)g(as)i(a)g(string.)j FJ(HeaderParser)19 b FN(has)h(the)h(same)f (API)g(as)h(the)g FJ(Parser)e FN(class.)0 1544 y FL(class)i FD(Parser)p FJ(\()p FC([)p 582 1544 25 4 v 28 w FK(class)12 b FC(])p FJ(\))208 1644 y FN(The)k(constructor)f(for)g(the)i FJ(Parser)f FN(class)i(tak)o(es)f(an)f(optional)g(ar)o(gument)p 2378 1644 V 44 w FK(class)p FN(.)24 b(This)17 b(must)f(be)h(a)g (callable)f(f)o(actory)g(\(such)g(as)208 1743 y(a)i(function)f(or)h(a)h (class\),)h(and)e(it)h(is)g(used)f(whene)n(v)o(er)f(a)i(sub-message)e (object)h(needs)g(to)h(be)f(created.)24 b(It)19 b(def)o(aults)f(to)g FJ(Message)208 1843 y FN(\(see)i FJ(email.message)p FN(\).)j(The)d(f)o (actory)f(will)i(be)f(called)g(without)f(ar)o(guments.)208 1974 y(The)26 b(optional)f FK(strict)k FN(\003ag)d(is)i(ignored.)41 b FL(Depr)o(ecated)25 b(since)i(r)o(elease)f(2.4.)43 b FN(Because)27 b(the)f FJ(Parser)g FN(class)h(is)g(a)g(backw)o(ard)208 2074 y(compatible)17 b(API)j(wrapper)d(around)h(the)h(ne)n(w-in-Python) d(2.4)i FJ(FeedParser)p FN(,)g FK(all)h FN(parsing)f(is)j(ef)n(fecti)n (v)o(ely)c(non-strict.)23 b(Y)-9 b(ou)208 2173 y(should)19 b(simply)h(stop)g(passing)g(a)g FK(strict)j FN(\003ag)d(to)h(the)f FJ(Parser)g FN(constructor)-5 b(.)208 2305 y(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g(The)g FK(strict)k FN(\003ag)e(w)o(as)g (added.)75 b(Changed)19 b(in)h(v)o(ersion)f(2.4:)h(The)g FK(strict)i FN(\003ag)f(w)o(as)g(deprecated.)0 2452 y(The)f(other)f (public)h FJ(Parser)f FN(methods)g(are:)0 2598 y FD(parse)p FJ(\()p FK(fp)p FC([)p FK(,)g(header)o(sonly)12 b FC(])p FJ(\))208 2698 y FN(Read)19 b(all)g(the)g(data)g(from)e(the)i (\002le-lik)o(e)g(object)g FK(fp)p FN(,)g(parse)f(the)h(resulting)f(te) o(xt,)h(and)f(return)g(the)h(root)f(message)h(object.)24 b FK(fp)19 b FN(must)208 2798 y(support)f(both)i(the)g FJ(readline\(\))f FN(and)g(the)i FJ(read\(\))e FN(methods)g(on)h (\002le-lik)o(e)g(objects.)208 2929 y(The)g(te)o(xt)g(contained)f(in)h FK(fp)h FN(must)f(be)h(formatted)d(as)k(a)e(block)g(of)g(RFC)i(2822)d (style)i(headers)e(and)h(header)f(continuation)f(lines,)208 3029 y(optionally)28 b(preceded)h(by)h(a)h(en)m(v)o(elope)e(header)-5 b(.)55 b(The)30 b(header)g(block)g(is)h(terminated)e(either)i(by)f(the) g(end)g(of)h(the)f(data)h(or)208 3128 y(by)25 b(a)i(blank)f(line.)43 b(F)o(ollo)n(wing)25 b(the)h(header)g(block)f(is)i(the)g(body)e(of)h (the)g(message)g(\(which)g(may)f(contain)h(MIME-encoded)208 3228 y(subparts\).)208 3359 y(Optional)19 b FK(header)o(sonly)g FN(is)i(as)g(with)f(the)g FJ(parse\(\))g FN(method.)208 3490 y(Changed)e(in)j(v)o(ersion)e(2.2.2:)g(The)g FK(header)o(sonly)g FN(\003ag)h(w)o(as)h(added.)0 3637 y FD(parsestr)p FJ(\()p FK(te)n(xt)q FC([)p FK(,)e(header)o(sonly)12 b FC(])p FJ(\))208 3737 y FN(Similar)19 b(to)h(the)f FJ(parse\(\))g FN(method,)f(e)o(xcept)h(it)h(tak)o(es)g(a)g(string)f(object)g(instead) g(of)h(a)g(\002le-lik)o(e)f(object.)24 b(Calling)c(this)g(method)208 3836 y(on)f(a)i(string)f(is)h(e)o(xactly)e(equi)n(v)n(alent)g(to)h (wrapping)e FK(te)n(xt)23 b FN(in)d(a)h FJ(StringIO)e FN(instance)h(\002rst)h(and)e(calling)h FJ(parse\(\))p FN(.)208 3968 y(Optional)i FK(header)o(sonly)f FN(is)j(a)f(\003ag)g (specifying)e(whether)h(to)h(stop)g(parsing)f(after)g(reading)g(the)h (headers)f(or)g(not.)33 b(The)22 b(def)o(ault)208 4067 y(is)f FJ(False)p FN(,)e(meaning)g(it)i(parses)f(the)g(entire)g (contents)g(of)f(the)i(\002le.)208 4199 y(Changed)d(in)j(v)o(ersion)e (2.2.2:)g(The)g FK(header)o(sonly)g FN(\003ag)h(w)o(as)h(added.)0 4346 y(Since)30 b(creating)f(a)h(message)g(object)f(structure)g(from)g (a)h(string)f(or)h(a)g(\002le)h(object)e(is)i(such)f(a)g(common)e (task,)k(tw)o(o)e(functions)f(are)0 4445 y(pro)o(vided)18 b(as)j(a)f(con)m(v)o(enience.)i(The)o(y)d(are)h(a)n(v)n(ailable)g(in)g (the)h(top-le)n(v)o(el)d FJ(email)i FN(package)f(namespace.)0 4592 y FD(message_from_string)p FJ(\()p FK(s)p FC([)p FK(,)p 1115 4592 V 47 w(class)p FC([)p FK(,)h(strict)13 b FC(])f(])p FJ(\))208 4692 y FN(Return)26 b(a)i(message)f(object)g (structure)g(from)f(a)i(string.)46 b(This)27 b(is)h(e)o(xactly)f(equi)n (v)n(alent)e(to)j FJ(Parser\(\).parsestr\(s\))p FN(.)208 4791 y(Optional)p 524 4791 V 49 w FK(class)21 b FN(and)e FK(strict)k FN(are)d(interpreted)f(as)i(with)f(the)g FJ(Parser)g FN(class)h(constructor)-5 b(.)208 4923 y(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g(The)g FK(strict)k FN(\003ag)e(w)o(as)g (added.)0 5069 y FD(message_from_file)p FJ(\()p FK(fp)p FC([)p FK(,)p 1048 5069 V 46 w(class)p FC([)p FK(,)g(strict)13 b FC(])f(])p FJ(\))208 5169 y FN(Return)57 b(a)h(message)f(object)g (structure)g(tree)g(from)g(an)g(open)g(\002le)h(object.)137 b(This)57 b(is)i(e)o(xactly)e(equi)n(v)n(alent)e(to)208 5269 y FJ(Parser\(\).parse\(fp\))p FN(.)22 b(Optional)p 1467 5269 V 49 w FK(class)f FN(and)e FK(strict)k FN(are)d(interpreted)f (as)i(with)f(the)g FJ(Parser)g FN(class)h(constructor)-5 b(.)208 5400 y(Changed)18 b(in)j(v)o(ersion)e(2.2.2:)g(The)g FK(strict)k FN(\003ag)e(w)o(as)g(added.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g (MIME)g(handling)h(pac)n(kage)1797 b(197)p eop end %%Page: 198 210 TeXDict begin 198 209 bop 0 83 a FN(Here')-5 b(s)20 b(an)h(e)o(xample)d (of)i(ho)n(w)g(you)f(might)h(use)g(this)h(at)g(an)f(interacti)n(v)o(e)f (Python)g(prompt:)236 321 y FA(>>>)45 b(import)e(email)236 413 y(>>>)i(msg)f(=)h(email.message_from_string\(myString\))0 821 y FI(Additional)26 b(notes)0 1024 y FN(Here)20 b(are)g(some)g (notes)g(on)g(the)g(parsing)f(semantics:)125 1241 y FM(\017)41 b FN(Most)25 b(non-)p FO(m)o(ultipar)s(t)d FN(type)i(messages)i(are)f (parsed)f(as)i(a)g(single)f(message)g(object)g(with)g(a)h(string)e (payload.)39 b(These)25 b(objects)208 1341 y(will)20 b(return)f FJ(False)h FN(for)g FJ(is_multipart\(\))p FN(.)j(Their)c FJ(get_payload\(\))g FN(method)f(will)j(return)e(a)i (string)f(object.)125 1501 y FM(\017)41 b FN(All)29 b FO(m)o(ultipar)s(t)f FN(type)g(messages)h(will)h(be)f(parsed)f(as)i(a)g (container)d(message)i(object)f(with)i(a)f(list)h(of)f(sub-message)f (objects)208 1601 y(for)f(their)i(payload.)48 b(The)28 b(outer)g(container)e(message)j(will)g(return)e FJ(True)i FN(for)e FJ(is_multipart\(\))g FN(and)h(their)g FJ(get_-)208 1700 y(payload\(\))19 b FN(method)f(will)j(return)e(the)i(list)g(of)f FJ(Message)f FN(subparts.)125 1861 y FM(\017)41 b FN(Most)23 b(messages)g(with)g(a)h(content)e(type)h(of)g FO(message/*)f FN(\(e.g.)33 b FO(message/deliv)n(er)r(y-status)21 b FN(and)i FO(message/rfc822)p FN(\))d(will)k(also)208 1961 y(be)29 b(parsed)f(as)i(container)e(object)h(containing)e(a)j (list)g(payload)e(of)h(length)f(1.)52 b(Their)29 b FJ(is_multipart\(\)) e FN(method)h(will)208 2060 y(return)19 b FJ(True)p FN(.)24 b(The)c(single)g(element)g(in)g(the)g(list)i(payload)c(will)j(be)f(a)h (sub-message)e(object.)125 2221 y FM(\017)41 b FN(Some)27 b(non-standards)d(compliant)i(messages)h(may)g(not)g(be)g(internally)f (consistent)h(about)g(their)g FO(m)o(ultipar)s(t)p FN(-edness.)43 b(Such)208 2321 y(messages)35 b(may)g(ha)n(v)o(e)g(a)h FO(Content-T)-9 b(ype:)52 b FN(header)35 b(of)g(type)g FO(m)o(ultipar)s(t)p FN(,)i(b)n(ut)e(their)h FJ(is_multipart\(\))d FN(method)h(may)208 2420 y(return)g FJ(False)p FN(.)69 b(If)35 b(such)g(messages)h(were)f(parsed)f(with)i(the)f FJ(FeedParser)p FN(,)i(the)o(y)e(will)h(ha)n(v)o(e)f(an)g(instance)g (of)g(the)208 2520 y FJ(MultipartInvariantViolationDefect)17 b FN(class)25 b(in)f(their)f FK(defects)g FN(attrib)n(ute)h(list.)35 b(See)24 b FJ(email.errors)e FN(for)208 2620 y(details.)0 2902 y Fv(7.1.3)100 b(Gener)o(ating)30 b(MIME)e(documents)0 3105 y FN(One)i(of)g(the)h(most)f(common)e(tasks)j(is)h(to)e(generate)f (the)i(\003at)g(te)o(xt)f(of)g(the)g(email)h(message)f(represented)e (by)i(a)h(message)f(object)0 3205 y(structure.)48 b(Y)-9 b(ou)27 b(will)i(need)f(to)g(do)g(this)h(if)f(you)f(w)o(ant)i(to)f (send)g(your)f(message)h(via)g(the)g FJ(smtplib)f FN(module)g(or)h(the) g FJ(nntplib)0 3304 y FN(module,)20 b(or)g(print)h(the)g(message)g(on)f (the)h(console.)27 b(T)-7 b(aking)20 b(a)h(message)g(object)g (structure)f(and)g(producing)f(a)i(\003at)h(te)o(xt)f(document)e(is)0 3404 y(the)h(job)g(of)g(the)g FJ(Generator)f FN(class.)0 3551 y(Again,)28 b(as)g(with)f(the)g FJ(email.parser)f FN(module,)h(you)f(aren')o(t)g(limited)h(to)h(the)f(functionality)e(of) i(the)g(b)n(undled)f(generator;)i(you)0 3650 y(could)k(write)i(one)f (from)f(scratch)h(yourself.)63 b(Ho)n(we)n(v)o(er)32 b(the)h(b)n(undled)f(generator)f(kno)n(ws)i(ho)n(w)f(to)i(generate)e (most)h(email)h(in)f(a)0 3750 y(standards-compliant)28 b(w)o(ay)-5 b(,)32 b(should)e(handle)g(MIME)g(and)g(non-MIME)f(email)i (messages)f(just)i(\002ne,)h(and)d(is)i(designed)d(so)i(that)0 3850 y(the)19 b(transformation)d(from)i(\003at)i(te)o(xt,)f(to)g(a)g (message)g(structure)f(via)h(the)g FJ(Parser)g FN(class,)h(and)e(back)g (to)h(\003at)h(te)o(xt,)f(is)h(idempotent)d(\(the)0 3949 y(input)i(is)j(identical)d(to)i(the)f(output\).)0 4096 y(Here)g(are)g(the)g(public)g(methods)f(of)h(the)g FJ(Generator)f FN(class,)i(imported)d(from)i(the)g FJ(email.generator)e FN(module:)0 4243 y FL(class)j FD(Generator)p FJ(\()p FK(outfp)p FC([)p FK(,)c(mangle)p 1188 4243 25 4 v 28 w(fr)l(om)p 1369 4243 V 30 w FC([)p FK(,)k(maxheaderlen)12 b FC(])g(])p FJ(\))208 4343 y FN(The)29 b(constructor)e(for)i(the)h FJ(Generator)e FN(class)j(tak)o(es)f(a)g(\002le-lik)o(e)f(object)g (called)h FK(outfp)f FN(for)g(an)g(ar)o(gument.)51 b FK(outfp)29 b FN(must)208 4442 y(support)18 b(the)j FJ(write\(\))e FN(method)g(and)g(be)i(usable)e(as)i(the)g(output)e(\002le)h(in)h(a)f (Python)f(e)o(xtended)g(print)g(statement.)208 4572 y(Optional)g FK(mangle)p 770 4572 V 28 w(fr)l(om)p 951 4572 V 50 w FN(is)i(a)f(\003ag)g(that,)g(when)f FJ(True)p FN(,)g(puts)h(a)g(`)p FJ(>)p FN(')g(character)e(in)i(front)f(of)h(an)o(y)f(line)h(in)g(the)f (body)g(that)h(starts)208 4672 y(e)o(xactly)25 b(as)h(`)p FJ(From)49 b FN(',)27 b(i.e.)43 b FJ(From)25 b FN(follo)n(wed)g(by)g(a) i(space)e(at)i(the)f(be)o(ginning)d(of)j(the)g(line.)42 b(This)26 b(is)h(the)f(only)f(guaranteed)208 4772 y(portable)18 b(w)o(ay)i(to)h(a)n(v)n(oid)e(ha)n(ving)g(such)h(lines)h(be)f(mistak)o (en)f(for)h(a)i(U)t FH(N)t(I)t(X)h FN(mailbox)c(format)g(en)m(v)o (elope)f(header)g(separator)h(\(see)208 4871 y(WHY)30 b(THE)f(CONTENT)-8 b(-LENGTH)29 b(FORMA)-9 b(T)29 b(IS)h(B)m(AD)g(for)f (details\).)53 b FK(mangle)p 2766 4871 V 28 w(fr)l(om)p 2947 4871 V 60 w FN(def)o(aults)29 b(to)h FJ(True)p FN(,)h(b)n(ut)e (you)208 4971 y(might)19 b(w)o(ant)h(to)h(set)g(this)f(to)h FJ(False)f FN(if)g(you)f(are)i(not)e(writing)j(U)t FH(N)t(I)t(X)h FN(mailbox)c(format)g(\002les.)208 5101 y(Optional)24 b FK(maxheaderlen)f FN(speci\002es)i(the)g(longest)f(length)g(for)h(a)g (non-continued)c(header)-5 b(.)39 b(When)25 b(a)g(header)f(line)h(is)h (longer)208 5201 y(than)h FK(maxheaderlen)e FN(\(in)i(characters,)h (with)g(tabs)f(e)o(xpanded)e(to)j(8)f(spaces\),)i(the)f(header)e(will)i (be)f(split)h(as)h(de\002ned)d(in)i(the)208 5300 y FJ (email.header.Header)19 b FN(class.)32 b(Set)23 b(to)f(zero)g(to)g (disable)g(header)f(wrapping.)29 b(The)22 b(def)o(ault)g(is)h(78,)f(as) h(recommended)208 5400 y(\(b)n(ut)c(not)h(required\))e(by)i(RFC)i (2822.)p 0 5549 3901 4 v 0 5649 a FI(198)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 199 211 TeXDict begin 199 210 bop 0 83 a FN(The)20 b(other)f(public)h FJ(Generator)f FN(methods)g(are:)0 230 y FD(flatten)p FJ(\()p FK(msg)p FC([)p FK(,)g(unixfr)l(om)12 b FC(])p FJ(\))208 330 y FN(Print)24 b(the)g(te)o(xtual)g(representation)e(of)i (the)h(message)f(object)g(structure)f(rooted)g(at)i FK(msg)g FN(to)f(the)h(output)e(\002le)i(speci\002ed)f(when)208 429 y(the)h FJ(Generator)f FN(instance)h(w)o(as)h(created.)40 b(Subparts)24 b(are)h(visited)h(depth-\002rst)e(and)h(the)g(resulting)f (te)o(xt)h(will)h(be)g(properly)208 529 y(MIME)19 b(encoded.)208 658 y(Optional)k FK(unixfr)l(om)h FN(is)h(a)f(\003ag)h(that)f(forces)f (the)h(printing)f(of)h(the)g(en)m(v)o(elope)e(header)h(delimiter)h (before)e(the)i(\002rst)h(RFC)h(2822)208 758 y(header)h(of)h(the)h (root)f(message)g(object.)50 b(If)28 b(the)h(root)f(object)g(has)h(no)f (en)m(v)o(elope)e(header)m(,)j(a)g(standard)e(one)h(is)i(crafted.)49 b(By)208 858 y(def)o(ault,)19 b(this)i(is)g(set)g(to)f FJ(False)g FN(to)g(inhibit)g(the)g(printing)f(of)h(the)g(en)m(v)o (elope)e(delimiter)-5 b(.)208 987 y(Note)20 b(that)g(for)g(subparts,)f (no)h(en)m(v)o(elope)d(header)i(is)j(e)n(v)o(er)d(printed.)208 1117 y(Ne)n(w)h(in)g(v)o(ersion)f(2.2.2.)0 1264 y FD(clone)p FJ(\()p FK(fp)p FJ(\))208 1364 y FN(Return)g(an)h(independent)e(clone)i (of)f(this)i FJ(Generator)e FN(instance)h(with)g(the)h(e)o(xact)e(same) i(options.)208 1493 y(Ne)n(w)f(in)g(v)o(ersion)f(2.2.2.)0 1640 y FD(write)p FJ(\()p FK(s)p FJ(\))208 1740 y FN(Write)25 b(the)g(string)g FK(s)h FN(to)f(the)g(underlying)e(\002le)j(object,)f (i.e.)40 b FK(outfp)24 b FN(passed)h(to)h FJ(Generator)p FN(')-5 b(s)24 b(constructor)-5 b(.)38 b(This)25 b(pro)o(vides)208 1839 y(just)20 b(enough)e(\002le-lik)o(e)j(API)f(for)g FJ(Generator)f FN(instances)h(to)g(be)g(used)g(in)h(e)o(xtended)d (print)h(statements.)0 1986 y(As)g(a)f(con)m(v)o(enience,)d(see)j(the)g (methods)f FJ(Message.as_string\(\))e FN(and)i FJ(str\(aMessage\))p FN(,)f(a.k.a.)24 b FJ(Message.__str_-)0 2086 y(_\(\))p FN(,)29 b(which)e(simplify)g(the)h(generation)e(of)h(a)h(formatted)e (string)h(representation)f(of)h(a)h(message)g(object.)47 b(F)o(or)27 b(more)g(detail,)i(see)0 2185 y FJ(email.message)p FN(.)0 2332 y(The)i FJ(email.generator)d FN(module)i(also)h(pro)o (vides)f(a)h(deri)n(v)o(ed)e(class,)35 b(called)30 b FJ(DecodedGenerator)f FN(which)h(is)i(lik)o(e)g(the)0 2432 y FJ(Generator)19 b FN(base)h(class,)h(e)o(xcept)e(that)i(non-)p FO(te)n(xt)d FN(parts)i(are)g(substituted)g(with)g(a)h(format)e(string) h(representing)e(the)i(part.)0 2579 y FL(class)h FD(DecodedGenerator)p FJ(\()p FK(outfp)p FC([)p FK(,)16 b(mangle)p 1537 2579 25 4 v 28 w(fr)l(om)p 1718 2579 V 30 w FC([)p FK(,)k(maxheaderlen)p FC([)p FK(,)e(fmt)13 b FC(])f(])g(])p FJ(\))208 2678 y FN(This)26 b(class,)i(deri)n(v)o(ed)c(from)h FJ(Generator)g FN(w)o(alks)h(through)e(all)i(the)g(subparts)g(of)f(a)i(message.)42 b(If)26 b(the)f(subpart)g(is)i(of)f(main)208 2778 y(type)e FO(te)n(xt)p FN(,)h(then)f(it)h(prints)g(the)f(decoded)f(payload)g(of)h (the)h(subpart.)37 b(Optional)p 2557 2778 V 53 w FK(mangle)p 2832 2778 V 29 w(fr)l(om)p 3014 2778 V 55 w FN(and)24 b FK(maxheaderlen)e FN(are)j(as)208 2878 y(with)20 b(the)g FJ(Generator)f FN(base)h(class.)208 3007 y(If)e(the)h(subpart)f(is)i (not)e(of)h(main)f(type)h FO(te)n(xt)p FN(,)f(optional)g FK(fmt)j FN(is)f(a)f(format)f(string)g(that)h(is)h(used)f(instead)f(of) h(the)g(message)f(payload.)208 3107 y FK(fmt)k FN(is)f(e)o(xpanded)d (with)i(the)g(follo)n(wing)f(k)o(e)o(yw)o(ords,)f(`)p FJ(\045\(keyword\)s)p FN(')g(format:)349 3314 y FM(\017)o FJ(type)i FN(\226)g(Full)h(MIME)f(type)g(of)f(the)i(non-)p FO(te)n(xt)d FN(part)349 3440 y FM(\017)o FJ(maintype)h FN(\226)i(Main)f(MIME)f(type)h(of)g(the)g(non-)p FO(te)n(xt)e FN(part)349 3567 y FM(\017)o FJ(subtype)i FN(\226)g(Sub-MIME)e(type)i (of)g(the)g(non-)p FO(te)n(xt)e FN(part)349 3693 y FM(\017)o FJ(filename)h FN(\226)i(Filename)e(of)h(the)h(non-)p FO(te)n(xt)d FN(part)349 3820 y FM(\017)o FJ(description)h FN(\226)h(Description)f(associated)h(with)h(the)f(non-)p FO(te)n(xt)e FN(part)349 3946 y FM(\017)o FJ(encoding)h FN(\226)i(Content)e(transfer)h(encoding)e(of)i(the)g(non-)p FO(te)n(xt)e FN(part)208 4153 y(The)h(def)o(ault)h(v)n(alue)f(for)h FK(fmt)i FN(is)f FJ(None)p FN(,)f(meaning)444 4283 y FA([Non-text)43 b(\(\045\(type\)s\))g(part)h(of)h(message)f(omitted,)f (filename)h(\045\(filename\)s])208 4469 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.2.)0 4616 y(Changed)g(in)h(v)o(ersion)f(2.5:)h (The)g(pre)n(viously)e(deprecated)g(method)h FJ(__call__\(\))g FN(w)o(as)i(remo)o(v)o(ed.)0 4898 y Fv(7.1.4)100 b(Creating)29 b(email)g(and)g(MIME)f(objects)g(from)g(scr)o(atch)0 5101 y FN(Ordinarily)-5 b(,)26 b(you)h(get)g(a)g(message)g(object)f (structure)g(by)h(passing)f(a)i(\002le)f(or)g(some)g(te)o(xt)g(to)g(a)g (parser)m(,)h(which)e(parses)h(the)g(te)o(xt)g(and)0 5201 y(returns)i(the)g(root)g(message)g(object.)52 b(Ho)n(we)n(v)o(er) 28 b(you)g(can)h(also)h(b)n(uild)f(a)h(complete)e(message)i(structure)e (from)g(scratch,)j(or)f(e)n(v)o(en)0 5300 y(indi)n(vidual)19 b FJ(Message)g FN(objects)h(by)g(hand.)k(In)c(f)o(act,)g(you)g(can)g (also)g(tak)o(e)h(an)f(e)o(xisting)g(structure)f(and)h(add)f(ne)n(w)i FJ(Message)e FN(objects,)0 5400 y(mo)o(v)o(e)g(them)h(around,)e(etc.)25 b(This)20 b(mak)o(es)g(a)h(v)o(ery)e(con)m(v)o(enient)e(interf)o(ace)j (for)f(slicing-and-dicing)e(MIME)j(messages.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g (and)g(MIME)g(handling)h(pac)n(kage)1797 b(199)p eop end %%Page: 200 212 TeXDict begin 200 211 bop 0 83 a FN(Y)-9 b(ou)27 b(can)h(create)g(a)g (ne)n(w)g(object)f(structure)g(by)g(creating)g FJ(Message)g FN(instances,)j(adding)c(attachments)h(and)h(all)g(the)g(appropriate)0 183 y(headers)d(manually)-5 b(.)40 b(F)o(or)25 b(MIME)g(messages)h (though,)f(the)h FJ(email)f FN(package)f(pro)o(vides)g(some)i(con)m(v)o (enient)d(subclasses)j(to)g(mak)o(e)0 282 y(things)20 b(easier)-5 b(.)0 429 y(Here)20 b(are)g(the)g(classes:)0 576 y FL(class)h FD(MIMEBase)p FJ(\()p 642 576 25 4 v 28 w FK(maintype)o(,)p 1015 576 V 49 w(subtype)o(,)e(**)p 1423 576 V 29 w(par)o(ams)p FJ(\))208 676 y FN(Module:)24 b FJ(email.mime.base)208 808 y FN(This)c(is)i(the)e(base)h(class)g(for) f(all)h(the)f(MIME-speci\002c)g(subclasses)g(of)h FJ(Message)p FN(.)k(Ordinarily)19 b(you)g(w)o(on')o(t)g(create)i(instances)208 908 y(speci\002cally)j(of)h FJ(MIMEBase)p FN(,)g(although)e(you)h (could.)39 b FJ(MIMEBase)24 b FN(is)i(pro)o(vided)c(primarily)i(as)i(a) f(con)m(v)o(enient)d(base)k(class)208 1008 y(for)19 b(more)g (speci\002c)i(MIME-a)o(w)o(are)d(subclasses.)p 213 1141 V 237 1141 a FK(maintype)d FN(is)i(the)e FO(Content-T)-9 b(ype:)20 b FN(major)15 b(type)h(\(e.g.)22 b FO(te)n(xt)16 b FN(or)f FO(image)p FN(\),)g(and)p 2406 1141 V 45 w FK(subtype)g FN(is)i(the)f FO(Content-T)-9 b(ype:)20 b FN(minor)14 b(type)h(\(e.g.)208 1240 y FO(plain)g FN(or)h FO(gif)p FN(\).)p 626 1240 V 53 w FK(par)o(ams)g FN(is)i(a)f(parameter) e(k)o(e)o(y/v)n(alue)g(dictionary)g(and)h(is)i(passed)e(directly)g(to)h FJ(Message.add_header\(\))p FN(.)208 1373 y(The)k FJ(MIMEBase)f FN(class)j(al)o(w)o(ays)f(adds)f(a)h FO(Content-T)-9 b(ype:)25 b FN(header)20 b(\(based)h(on)p 2532 1373 V 51 w FK(maintype)p FN(,)p 2909 1373 V 50 w FK(subtype)p FN(,)g(and)p 3378 1373 V 51 w FK(par)o(ams)p FN(\),)f(and)h(a)208 1473 y FO(MIME-V)-6 b(ersion:)23 b FN(header)c(\(al)o(w)o(ays)i(set)g (to)f FJ(1.0)p FN(\).)0 1620 y FL(class)h FD(MIMENonMultipart)p FJ(\(\))208 1719 y FN(Module:)j FJ(email.mime.nonmultipart)208 1852 y FN(A)j(subclass)g(of)f FJ(MIMEBase)p FN(,)h(this)g(is)h(an)f (intermediate)e(base)i(class)g(for)f(MIME)h(messages)f(that)h(are)g (not)f FO(m)o(ultipar)s(t)p FN(.)43 b(The)208 1952 y(primary)28 b(purpose)h(of)h(this)h(class)h(is)f(to)g(pre)n(v)o(ent)e(the)h(use)h (of)f(the)g FJ(attach\(\))g FN(method,)h(which)f(only)g(mak)o(es)g (sense)h(for)208 2051 y FO(m)o(ultipar)s(t)18 b FN(messages.)25 b(If)20 b FJ(attach\(\))f FN(is)j(called,)d(a)i FJ (MultipartConversionError)16 b FN(e)o(xception)i(is)k(raised.)208 2184 y(Ne)n(w)e(in)g(v)o(ersion)f(2.2.2.)0 2331 y FL(class)i FD(MIMEMultipart)p FJ(\()p FC([)p FK(subtype)p FC([)p FK(,)16 b(boundary)p FC([)p FK(,)p 1663 2331 V 47 w(subparts)p FC([)p FK(,)p 2061 2331 V 50 w(par)o(ams)c FC(])g(])g(])g(])p FJ(\))208 2431 y FN(Module:)24 b FJ(email.mime.multipart)208 2563 y FN(A)h(subclass)h(of)e FJ(MIMEBase)p FN(,)i(this)f(is)h(an)g (intermediate)d(base)i(class)i(for)d(MIME)h(messages)g(that)g(are)g FO(m)o(ultipar)s(t)p FN(.)38 b(Optional)p 208 2663 V 232 2663 a FK(subtype)24 b FN(def)o(aults)g(to)g FO(mix)n(ed)p FN(,)g(b)n(ut)h(can)e(be)i(used)e(to)i(specify)e(the)h(subtype)f(of)h (the)g(message.)37 b(A)25 b FO(Content-T)-9 b(ype:)30 b FN(header)23 b(of)208 2763 y FO(m)o(ultipar)s(t/)p 525 2763 V 27 w FK(subtype)c FN(will)i(be)f(added)f(to)i(the)f(message) g(object.)k(A)d FO(MIME-V)-6 b(ersion:)24 b FN(header)19 b(will)i(also)f(be)g(added.)208 2895 y(Optional)e FK(boundary)g FN(is)i(the)g(multipart)e(boundary)f(string.)24 b(When)c FJ(None)f FN(\(the)g(def)o(ault\),)g(the)g(boundary)e(is)j(calculated)f (when)208 2995 y(needed.)p 213 3128 V 237 3128 a FK(subparts)i FN(is)h(a)g(sequence)d(of)i(initial)h(subparts)e(for)g(the)h(payload.) 26 b(It)c(must)f(be)g(possible)f(to)i(con)m(v)o(ert)d(this)i(sequence)f (to)h(a)h(list.)208 3228 y(Y)-9 b(ou)19 b(can)h(al)o(w)o(ays)h(attach)f (ne)n(w)g(subparts)f(to)i(the)f(message)g(by)g(using)f(the)h FJ(Message.attach\(\))e FN(method.)208 3360 y(Additional)k(parameters)g (for)h(the)h FO(Content-T)-9 b(ype:)29 b FN(header)22 b(are)i(tak)o(en)f(from)g(the)g(k)o(e)o(yw)o(ord)f(ar)o(guments,)g(or)i (passed)f(into)h(the)p 208 3460 V 232 3460 a FK(par)o(ams)c FN(ar)o(gument,)e(which)h(is)i(a)g(k)o(e)o(yw)o(ord)d(dictionary)-5 b(.)208 3593 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.2.)0 3740 y FL(class)i FD(MIMEApplication)p FJ(\()p 992 3740 V 27 w FK(data)p FC([)p FK(,)p 1248 3740 V 49 w(subtype)p FC([)p FK(,)p 1612 3740 V 48 w(encoder)r FC([)p FK(,)e(**)p 2077 3740 V 29 w(par)o(ams)12 b FC(])g(])g(])p FJ(\))208 3839 y FN(Module:)24 b FJ(email.mime.application)208 3972 y FN(A)31 b(subclass)f(of)h FJ(MIMENonMultipart)p FN(,)f(the)g FJ(MIMEApplication)f FN(class)i(is)h(used)e(to)g (represent)g(MIME)g(message)208 4072 y(objects)20 b(of)h(major)f(type)g FO(application)p FN(.)p 1345 4072 V 54 w FK(data)g FN(is)h(a)h(string)e (containing)f(the)i(ra)o(w)f(byte)h(data.)26 b(Optional)p 3191 4072 V 50 w FK(subtype)20 b FN(speci\002es)i(the)208 4171 y(MIME)d(subtype)g(and)h(def)o(aults)g(to)g FO(octet-stream)p FN(.)208 4304 y(Optional)p 532 4304 V 57 w FK(encoder)30 b FN(is)g(a)f(callable)f(\(i.e.)51 b(function\))27 b(which)h(will)h (perform)e(the)i(actual)f(encoding)f(of)h(the)h(data)g(for)f(trans-)208 4404 y(port.)53 b(This)30 b(callable)g(tak)o(es)g(one)f(ar)o(gument,)h (which)f(is)i(the)f FJ(MIMEApplication)e FN(instance.)54 b(It)30 b(should)f(use)h FJ(get_-)208 4504 y(payload\(\))21 b FN(and)h FJ(set_payload\(\))f FN(to)i(change)e(the)i(payload)e(to)i (encoded)e(form.)31 b(It)23 b(should)f(also)g(add)h(an)o(y)e FO(Content-)208 4603 y(T)-9 b(r)o(ansf)n(er-Encoding:)20 b FN(or)e(other)g(headers)g(to)h(the)g(message)g(object)f(as)h (necessary)-5 b(.)24 b(The)18 b(def)o(ault)g(encoding)f(is)j(base64.)j (See)d(the)208 4703 y FJ(email.encoders)e FN(module)h(for)g(a)i(list)g (of)f(the)g(b)n(uilt-in)g(encoders.)p 213 4836 V 237 4836 a FK(par)o(ams)g FN(are)g(passed)g(straight)g(through)e(to)i(the)h (base)f(class)h(constructor)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.5.)0 4983 y FL(class)i FD(MIMEAudio)p FJ(\()p 692 4983 V 28 w FK(audiodata)p FC([)p FK(,)p 1138 4983 V 47 w(subtype)p FC([)p FK(,)p 1503 4983 V 49 w(encoder)r FC([)p FK(,)d(**)p 1967 4983 V 29 w(par)o(ams)12 b FC(])g(])g(])p FJ(\))208 5082 y FN(Module:)24 b FJ(email.mime.audio)208 5215 y FN(A)18 b(subclass)h(of)f FJ(MIMENonMultipart)p FN(,)e(the)i FJ(MIMEAudio)f FN(class)i(is)g(used)f(to)h(create)f(MIME)f (message)h(objects)g(of)g(major)208 5315 y(type)25 b FO(audio)p FN(.)p 627 5315 V 69 w FK(audiodata)e FN(is)k(a)f(string)f (containing)f(the)i(ra)o(w)f(audio)g(data.)41 b(If)25 b(this)h(data)g(can)f(be)h(decoded)e(by)h(the)h(standard)p 0 5549 3901 4 v 0 5649 a FI(200)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 201 213 TeXDict begin 201 212 bop 208 83 a FN(Python)22 b(module)g FJ(sndhdr)p FN(,)i(then)f(the)g(subtype)f(will)j(be)e(automatically)f (included)g(in)i(the)f FO(Content-T)-9 b(ype:)29 b FN(header)-5 b(.)34 b(Other)n(-)208 183 y(wise)27 b(you)e(can)h(e)o(xplicitly)g (specify)f(the)i(audio)e(subtype)h(via)g(the)p 2173 183 25 4 v 56 w FK(subtype)g FN(parameter)-5 b(.)42 b(If)27 b(the)f(minor)f(type)h(could)g(not)g(be)208 282 y(guessed)19 b(and)p 637 282 V 50 w FK(subtype)g FN(w)o(as)i(not)f(gi)n(v)o(en,)f (then)g FJ(TypeError)g FN(is)j(raised.)208 415 y(Optional)p 521 415 V 46 w FK(encoder)d FN(is)g(a)f(callable)f(\(i.e.)24 b(function\))16 b(which)h(will)i(perform)c(the)j(actual)g(encoding)d (of)j(the)f(audio)g(data)h(for)f(trans-)208 515 y(port.)37 b(This)24 b(callable)g(tak)o(es)h(one)f(ar)o(gument,)f(which)h(is)h (the)g FJ(MIMEAudio)e FN(instance.)38 b(It)24 b(should)g(use)g FJ(get_payload\(\))208 614 y FN(and)33 b FJ(set_payload\(\))f FN(to)i(change)f(the)h(payload)e(to)i(encoded)e(form.)65 b(It)35 b(should)e(also)h(add)f(an)o(y)g FO(Content-T)-9 b(r)o(ansf)n(er-)208 714 y(Encoding:)48 b FN(or)33 b(other)g(headers)f (to)h(the)g(message)g(object)g(as)g(necessary)-5 b(.)63 b(The)33 b(def)o(ault)f(encoding)f(is)j(base64.)63 b(See)34 b(the)208 814 y FJ(email.encoders)18 b FN(module)h(for)g(a)i(list)g(of) f(the)g(b)n(uilt-in)g(encoders.)p 213 946 V 237 946 a FK(par)o(ams)g FN(are)g(passed)g(straight)g(through)e(to)i(the)h(base)f (class)h(constructor)-5 b(.)0 1093 y FL(class)21 b FD(MIMEImage)p FJ(\()p 692 1093 V 28 w FK(ima)o(g)o(edata)p FC([)p FK(,)p 1150 1093 V 48 w(subtype)p FC([)p FK(,)p 1515 1093 V 49 w(encoder)r FC([)p FK(,)d(**)p 1979 1093 V 29 w(par)o(ams)12 b FC(])g(])g(])p FJ(\))208 1193 y FN(Module:)24 b FJ(email.mime.image) 208 1326 y FN(A)18 b(subclass)h(of)f FJ(MIMENonMultipart)p FN(,)e(the)i FJ(MIMEImage)f FN(class)i(is)g(used)f(to)h(create)f(MIME)f (message)h(objects)g(of)g(major)208 1425 y(type)k FO(image)p FN(.)p 639 1425 V 64 w FK(ima)o(g)o(edata)g FN(is)i(a)g(string)f (containing)f(the)h(ra)o(w)g(image)g(data.)35 b(If)23 b(this)h(data)f(can)g(be)h(decoded)d(by)i(the)h(standard)208 1525 y(Python)e(module)g FJ(imghdr)p FN(,)i(then)f(the)g(subtype)f (will)j(be)e(automatically)f(included)g(in)i(the)f FO(Content-T)-9 b(ype:)29 b FN(header)-5 b(.)34 b(Other)n(-)208 1625 y(wise)26 b(you)e(can)i(e)o(xplicitly)e(specify)h(the)g(image)g (subtype)g(via)g(the)p 2183 1625 V 55 w FK(subtype)g FN(parameter)-5 b(.)40 b(If)25 b(the)h(minor)e(type)h(could)f(not)i(be) 208 1724 y(guessed)19 b(and)p 637 1724 V 50 w FK(subtype)g FN(w)o(as)i(not)f(gi)n(v)o(en,)f(then)g FJ(TypeError)g FN(is)j(raised.)208 1857 y(Optional)p 539 1857 V 64 w FK(encoder)35 b FN(is)h(a)g(callable)f(\(i.e.)69 b(function\))33 b(which)h(will)i(perform)d(the)i(actual)g(encoding)e(of)h(the)h(image)g (data)208 1957 y(for)29 b(transport.)55 b(This)30 b(callable)h(tak)o (es)f(one)g(ar)o(gument,)h(which)f(is)h(the)f FJ(MIMEImage)g FN(instance.)55 b(It)31 b(should)e(use)i FJ(get_-)208 2056 y(payload\(\))21 b FN(and)h FJ(set_payload\(\))f FN(to)i(change)e(the)i(payload)e(to)i(encoded)e(form.)31 b(It)23 b(should)f(also)g(add)h(an)o(y)e FO(Content-)208 2156 y(T)-9 b(r)o(ansf)n(er-Encoding:)20 b FN(or)e(other)g(headers)g (to)h(the)g(message)g(object)f(as)h(necessary)-5 b(.)24 b(The)18 b(def)o(ault)g(encoding)f(is)j(base64.)j(See)d(the)208 2256 y FJ(email.encoders)e FN(module)h(for)g(a)i(list)g(of)f(the)g(b)n (uilt-in)g(encoders.)p 213 2388 V 237 2388 a FK(par)o(ams)g FN(are)g(passed)g(straight)g(through)e(to)i(the)h FJ(MIMEBase)e FN(constructor)-5 b(.)0 2535 y FL(class)21 b FD(MIMEMessage)p FJ(\()p 792 2535 V 27 w FK(msg)p FC([)p FK(,)p 1034 2535 V 50 w(subtype)12 b FC(])p FJ(\))208 2635 y FN(Module:)24 b FJ(email.mime.message)208 2768 y FN(A)f(subclass)g(of)f FJ(MIMENonMultipart)p FN(,)e(the)j FJ(MIMEMessage)e FN(class)j(is)f (used)g(to)g(create)f(MIME)g(objects)g(of)h(main)f(type)208 2867 y FO(message)p FN(.)p 589 2867 V 81 w FK(msg)29 b FN(is)h(used)f(as)h(the)f(payload,)h(and)f(must)g(be)g(an)g(instance) g(of)f(class)j FJ(Message)d FN(\(or)g(a)i(subclass)f(thereof\),)208 2967 y(otherwise)19 b(a)i FJ(TypeError)e FN(is)i(raised.)208 3100 y(Optional)p 524 3100 V 49 w FK(subtype)e FN(sets)i(the)g(subtype) e(of)h(the)g(message;)g(it)h(def)o(aults)f(to)g FO(rfc822)p FN(.)0 3247 y FL(class)h FD(MIMEText)p FJ(\()p 642 3247 V 28 w FK(te)n(xt)q FC([)p FK(,)p 871 3247 V 51 w(subtype)p FC([)p FK(,)p 1236 3247 V 49 w(c)o(har)o(set)13 b FC(])f(])p FJ(\))208 3346 y FN(Module:)24 b FJ(email.mime.text)208 3479 y FN(A)c(subclass)h(of)e FJ(MIMENonMultipart)p FN(,)f(the)i FJ(MIMEText)f FN(class)i(is)g(used)f(to)h(create)f(MIME)f(objects)h(of) g(major)f(type)h FO(te)n(xt)p FN(.)p 208 3579 V 232 3579 a FK(te)n(xt)h FN(is)f(the)f(string)f(for)g(the)h(payload.)p 1326 3579 V 53 w FK(subtype)f FN(is)i(the)e(minor)g(type)g(and)g(def)o (aults)h(to)g FO(plain)p FN(.)p 2912 3579 V 52 w FK(c)o(har)o(set)h FN(is)g(the)f(character)e(set)j(of)208 3678 y(the)i(te)o(xt)g(and)g(is) i(passed)e(as)i(a)e(parameter)f(to)i(the)g FJ(MIMENonMultipart)d FN(constructor;)i(it)h(def)o(aults)f(to)h FJ(us-ascii)p FN(.)31 b(No)208 3778 y(guessing)19 b(or)h(encoding)e(is)j(performed)d (on)h(the)i(te)o(xt)f(data.)208 3911 y(Changed)h(in)i(v)o(ersion)e (2.4:)h(The)h(pre)n(viously)e(deprecated)p 1942 3911 V 50 w FK(encoding)g FN(ar)o(gument)f(has)j(been)f(remo)o(v)o(ed.)30 b(Encoding)21 b(happens)208 4011 y(implicitly)e(based)h(on)g(the)p 992 4011 V 50 w FK(c)o(har)o(set)i FN(ar)o(gument.)0 4295 y Fv(7.1.5)100 b(Inter)r(nationaliz)o(ed)31 b(headers)0 4498 y FN(RFC)19 b(2822)d(is)i(the)f(base)h(standard)e(that)h (describes)g(the)g(format)f(of)h(email)h(messages.)24 b(It)17 b(deri)n(v)o(es)g(from)f(the)h(older)g(RFC)h(822)f(standard)0 4598 y(which)23 b(came)g(into)g(widespread)f(use)i(at)g(a)g(time)f (when)g(most)h(email)f(w)o(as)h(composed)e(of)j FH(A)t(S)t(C)t(I)t(I)i FN(characters)22 b(only)-5 b(.)34 b(RFC)25 b(2822)d(is)i(a)0 4698 y(speci\002cation)19 b(written)h(assuming)g(email)g(contains)f (only)h(7-bit)h FH(A)t(S)t(C)t(I)t(I)j FN(characters.)0 4844 y(Of)f(course,)g(as)h(email)g(has)f(been)f(deplo)o(yed)g(w)o (orldwide,)g(it)i(has)g(become)e(internationalized,)f(such)i(that)g (language)f(speci\002c)h(char)n(-)0 4944 y(acter)e(sets)h(can)e(no)n(w) h(be)g(used)f(in)h(email)g(messages.)27 b(The)21 b(base)g(standard)e (still)j(requires)e(email)h(messages)g(to)g(be)g(transferred)e(using)0 5044 y(only)d(7-bit)i FH(A)t(S)t(C)t(I)t(I)i FN(characters,)c(so)i(a)f (sle)n(w)g(of)g(RFCs)h(ha)n(v)o(e)e(been)g(written)h(describing)e(ho)n (w)h(to)h(encode)e(email)i(containing)e(non-)r FH(A)t(S)t(C)t(I)t(I)0 5143 y FN(characters)22 b(into)g(RFC)i(2822-compliant)19 b(format.)31 b(These)23 b(RFCs)h(include)e(RFC)i(2045,)e(RFC)i(2046,)d (RFC)j(2047,)e(and)g(RFC)i(2231.)0 5243 y(The)c FJ(email)g FN(package)e(supports)i(these)g(standards)f(in)i(its)g FJ(email.header)d FN(and)i FJ(email.charset)e FN(modules.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h (email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(201)p eop end %%Page: 202 214 TeXDict begin 202 213 bop 0 83 a FN(If)19 b(you)f(w)o(ant)h(to)g (include)e(non-)r FH(A)t(S)t(C)t(I)t(I)k FN(characters)d(in)h(your)e (email)i(headers,)f(say)h(in)g(the)g FO(Subject:)k FN(or)18 b FO(T)-9 b(o:)24 b FN(\002elds,)c(you)e(should)f(use)j(the)0 183 y FJ(Header)h FN(class)h(and)e(assign)h(the)g(\002eld)g(in)h(the)f FJ(Message)f FN(object)h(to)g(an)g(instance)f(of)h FJ(Header)g FN(instead)g(of)f(using)h(a)g(string)g(for)g(the)0 282 y(header)e(v)n(alue.)24 b(Import)19 b(the)h FJ(Header)g FN(class)h(from)e(the)h FJ(email.header)f FN(module.)k(F)o(or)d(e)o (xample:)236 520 y FA(>>>)45 b(from)f(email.message)e(import)i(Message) 236 612 y(>>>)h(from)f(email.header)f(import)g(Header)236 703 y(>>>)i(msg)f(=)h(Message\(\))236 794 y(>>>)g(h)f(=)h (Header\('p\\xf6stal',)d('iso-8859-1'\))236 886 y(>>>)j(msg['Subject']) d(=)j(h)236 977 y(>>>)g(print)f(msg.as_string\(\))236 1068 y(Subject:)g(=?iso-8859-1?q?p=F6stal?=)0 1538 y FN(Notice)24 b(here)f(ho)n(w)h(we)g(w)o(anted)f(the)h FO(Subject:)31 b FN(\002eld)24 b(to)g(contain)f(a)i(non-)r FH(A)t(S)t(C)t(I)t(I)g FN(character?)35 b(W)-7 b(e)25 b(did)f(this)g(by)g(creating)f(a)h FJ(Header)0 1637 y FN(instance)19 b(and)f(passing)h(in)g(the)g(character)f(set)i(that)f (the)g(byte)g(string)f(w)o(as)i(encoded)d(in.)25 b(When)19 b(the)g(subsequent)f FJ(Message)g FN(instance)0 1737 y(w)o(as)k(\003attened,)e(the)h FO(Subject:)26 b FN(\002eld)21 b(w)o(as)h(properly)d(RFC)j(2047)e(encoded.)25 b(MIME-a)o(w)o(are)20 b(mail)h(readers)f(w)o(ould)g(sho)n(w)h(this)h(header)0 1836 y(using)e(the)g(embedded)e(ISO-8859-1)f(character)-5 b(.)0 1983 y(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.2.)0 2130 y(Here)h(is)h(the)f FJ(Header)g FN(class)h(description:)0 2277 y FL(class)g FD(Header)p FJ(\()p FC([)p FK(s)p FC([)p FK(,)e(c)o(har)o(set)q FC([)p FK(,)h(maxlinelen)p FC([)p FK(,)f(header)p 1697 2277 25 4 v 28 w(name)p FC([)p FK(,)g (continuation)p 2409 2277 V 27 w(ws)p FC([)p FK(,)i(err)l(or)o(s)12 b FC(])g(])g(])g(])g(])g(])p FJ(\))208 2377 y FN(Create)20 b(a)h(MIME-compliant)c(header)i(that)h(can)g(contain)g(strings)g(in)g (dif)n(ferent)f(character)g(sets.)208 2506 y(Optional)25 b FK(s)i FN(is)g(the)g(initial)f(header)f(v)n(alue.)43 b(If)26 b FJ(None)g FN(\(the)g(def)o(ault\),)g(the)g(initial)h(header)e (v)n(alue)h(is)h(not)f(set.)44 b(Y)-9 b(ou)25 b(can)h(later)208 2606 y(append)f(to)i(the)f(header)g(with)h FJ(append\(\))f FN(method)f(calls.)45 b FK(s)28 b FN(may)e(be)h(a)g(byte)f(string)h(or) f(a)h(Unicode)f(string,)h(b)n(ut)g(see)h(the)208 2705 y FJ(append\(\))19 b FN(documentation)e(for)j(semantics.)208 2835 y(Optional)29 b FK(c)o(har)o(set)i FN(serv)o(es)f(tw)o(o)g (purposes:)44 b(it)31 b(has)f(the)g(same)g(meaning)e(as)j(the)f FK(c)o(har)o(set)i FN(ar)o(gument)27 b(to)j(the)g FJ(append\(\))208 2935 y FN(method.)23 b(It)18 b(also)h(sets)h(the)f(def)o(ault)f (character)f(set)i(for)f(all)h(subsequent)e FJ(append\(\))h FN(calls)h(that)g(omit)g(the)f FK(c)o(har)o(set)i FN(ar)o(gument.)208 3034 y(If)f FK(c)o(har)o(set)j FN(is)e(not)g(pro)o(vided)d(in)j(the)g (constructor)e(\(the)i(def)o(ault\),)f(the)h FJ(us-ascii)f FN(character)f(set)j(is)g(used)e(both)g(as)i FK(s)p FN(')-5 b(s)21 b(initial)208 3134 y(charset)e(and)h(as)h(the)f(def)o(ault)g (for)f(subsequent)g FJ(append\(\))g FN(calls.)208 3263 y(The)i(maximum)g(line)h(length)g(can)g(be)g(speci\002ed)g(e)o(xplicit) g(via)g FK(maxlinelen)p FN(.)30 b(F)o(or)22 b(splitting)g(the)g (\002rst)h(line)g(to)f(a)h(shorter)e(v)n(alue)208 3363 y(\(to)f(account)e(for)i(the)g(\002eld)g(header)f(which)h(isn')o(t)g (included)f(in)h FK(s)p FN(,)h(e.g.)j FO(Subject:)p FN(\))g(pass)c(in)h (the)f(name)f(of)h(the)g(\002eld)h(in)f FK(header)p 3849 3363 V 28 w(-)208 3463 y(name)p FN(.)j(The)18 b(def)o(ault)g FK(maxlinelen)f FN(is)i(76,)g(and)e(the)i(def)o(ault)e(v)n(alue)h(for)g FK(header)p 2468 3463 V 28 w(name)g FN(is)h FJ(None)p FN(,)g(meaning)d(it)k(is)f(not)f(tak)o(en)g(into)208 3562 y(account)h(for)g(the)h(\002rst)h(line)f(of)g(a)h(long,)e(split)i (header)-5 b(.)208 3692 y(Optional)23 b FK(continuation)p 951 3692 V 27 w(ws)j FN(must)f(be)g(RFC)h(2822-compliant)21 b(folding)i(whitespace,)i(and)f(is)i(usually)e(either)h(a)g(space)g(or) f(a)208 3791 y(hard)19 b(tab)h(character)-5 b(.)24 b(This)d(character)d (will)j(be)g(prepended)c(to)j(continuation)e(lines.)0 3938 y(Optional)h FK(err)l(or)o(s)j FN(is)f(passed)f(straight)g (through)e(to)i(the)h FJ(append\(\))e FN(method.)0 4085 y FD(append)p FJ(\()p FK(s)p FC([)p FK(,)g(c)o(har)o(set)q FC([)p FK(,)h(err)l(or)o(s)12 b FC(])g(])p FJ(\))208 4185 y FN(Append)18 b(the)i(string)g FK(s)h FN(to)g(the)f(MIME)g (header)-5 b(.)208 4314 y(Optional)20 b FK(c)o(har)o(set)q FN(,)j(if)f(gi)n(v)o(en,)e(should)h(be)h(a)g FJ(Charset)f FN(instance)g(\(see)h FJ(email.charset)p FN(\))e(or)h(the)h(name)f(of)h (a)g(character)208 4414 y(set,)c(which)f(will)h(be)f(con)m(v)o(erted)e (to)i(a)h FJ(Charset)f FN(instance.)23 b(A)18 b(v)n(alue)f(of)g FJ(None)g FN(\(the)g(def)o(ault\))f(means)h(that)h(the)f FK(c)o(har)o(set)i FN(gi)n(v)o(en)208 4513 y(in)h(the)g(constructor)e (is)k(used.)208 4643 y FK(s)k FN(may)e(be)h(a)h(byte)f(string)f(or)h(a) h(Unicode)e(string.)39 b(If)25 b(it)h(is)g(a)g(byte)f(string)f(\(i.e.) 40 b FJ(isinstance\(s,)48 b(str\))24 b FN(is)j(true\),)e(then)208 4743 y FK(c)o(har)o(set)19 b FN(is)h(the)e(encoding)f(of)h(that)h(byte) f(string,)g(and)g(a)h FJ(UnicodeError)e FN(will)i(be)g(raised)f(if)h (the)f(string)g(cannot)g(be)g(decoded)208 4842 y(with)i(that)g (character)f(set.)208 4972 y(If)27 b FK(s)i FN(is)g(a)f(Unicode)e (string,)k(then)d FK(c)o(har)o(set)i FN(is)g(a)f(hint)f(specifying)g (the)g(character)g(set)i(of)e(the)h(characters)f(in)h(the)f(string.)48 b(In)208 5071 y(this)27 b(case,)i(when)e(producing)d(an)j(RFC)h (2822-compliant)c(header)i(using)g(RFC)j(2047)d(rules,)i(the)f(Unicode) f(string)h(will)h(be)208 5171 y(encoded)20 b(using)h(the)i(follo)n (wing)d(charsets)i(in)g(order:)28 b FJ(us-ascii)p FN(,)22 b(the)g FK(c)o(har)o(set)h FN(hint,)g FJ(utf-8)p FN(.)30 b(The)22 b(\002rst)h(character)d(set)j(to)208 5271 y(not)c(pro)o(v)n (ok)o(e)f(a)j FJ(UnicodeError)e FN(is)i(used.)208 5400 y(Optional)e FK(err)l(or)o(s)j FN(is)f(passed)f(through)e(to)i(an)o(y)g FJ(unicode\(\))f FN(or)h FJ(ustr.encode\(\))e FN(call,)i(and)g(def)o (aults)g(to)g(\223strict\224.)p 0 5549 3901 4 v 0 5649 a FI(202)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 203 215 TeXDict begin 203 214 bop 0 83 a FD(encode)p FJ(\()p FC([)p FK(splitc)o(har)o(s)12 b FC(])p FJ(\))208 183 y FN(Encode)20 b(a)i(message)g(header)f(into)g(an)h(RFC-compliant)f (format,)g(possibly)g(wrapping)f(long)h(lines)i(and)e(encapsulating)f (non-)210 282 y FH(A)t(S)t(C)t(I)t(I)g FN(parts)e(in)f(base64)f(or)h (quoted-printable)d(encodings.)22 b(Optional)17 b FK(splitc)o(har)o(s)g FN(is)h(a)g(string)f(containing)e(characters)i(to)g(split)208 382 y(long)24 b(ASCII)h(lines)g(on,)h(in)f(rough)e(support)g(of)i(RFC)h (2822')-5 b(s)24 b FK(highest)h(le)o(vel)g(syntactic)f(br)m(eaks)p FN(.)39 b(This)25 b(doesn')o(t)f(af)n(fect)g(RFC)208 482 y(2047)18 b(encoded)h(lines.)0 628 y(The)h FJ(Header)f FN(class)j(also)e(pro)o(vides)f(a)h(number)f(of)g(methods)h(to)g (support)f(standard)g(operators)f(and)i(b)n(uilt-in)g(functions.)0 775 y FD(__str__)p FJ(\(\))208 875 y FN(A)g(synon)o(ym)e(for)i FJ(Header.encode\(\))p FN(.)i(Useful)f(for)e FJ(str\(aHeader\))p FN(.)0 1022 y FD(__unicode__)p FJ(\(\))208 1121 y FN(A)h(helper)f(for)h (the)g(b)n(uilt-in)g FJ(unicode\(\))f FN(function.)k(Returns)d(the)g (header)f(as)i(a)g(Unicode)e(string.)0 1268 y FD(__eq__)p FJ(\()p FK(other)r FJ(\))208 1368 y FN(This)h(method)f(allo)n(ws)h(you) f(to)i(compare)d(tw)o(o)j FJ(Header)f FN(instances)g(for)f(equality)-5 b(.)0 1515 y FD(__ne__)p FJ(\()p FK(other)r FJ(\))208 1614 y FN(This)20 b(method)f(allo)n(ws)h(you)f(to)i(compare)d(tw)o(o)j FJ(Header)f FN(instances)g(for)f(inequality)-5 b(.)0 1761 y(The)20 b FJ(email.header)e FN(module)h(also)i(pro)o(vides)d(the) i(follo)n(wing)f(con)m(v)o(enient)e(functions.)0 1908 y FD(decode_header)p FJ(\()p FK(header)r FJ(\))208 2008 y FN(Decode)i(a)h(message)h(header)e(v)n(alue)g(without)g(con)m(v)o (erting)f(the)i(character)f(set.)26 b(The)19 b(header)g(v)n(alue)h(is)h (in)f FK(header)r FN(.)208 2141 y(This)j(function)f(returns)g(a)i(list) h(of)e FJ(\(decoded_string,)47 b(charset\))22 b FN(pairs)i(containing)d (each)i(of)h(the)f(decoded)f(parts)208 2240 y(of)c(the)h(header)-5 b(.)24 b FK(c)o(har)o(set)d FN(is)f FJ(None)f FN(for)f(non-encoded)d (parts)k(of)g(the)g(header)m(,)f(otherwise)g(a)i(lo)n(wer)e(case)i (string)e(containing)g(the)208 2340 y(name)h(of)h(the)g(character)f (set)i(speci\002ed)f(in)g(the)h(encoded)d(string.)208 2473 y(Here')-5 b(s)20 b(an)g(e)o(xample:)444 2697 y FA(>>>)44 b(from)g(email.header)f(import)h(decode_header)444 2788 y(>>>)g(decode_header\('=?iso-8859-1?q?p=F6stal?=)o('\))444 2879 y([\('p\\xf6stal',)e('iso-8859-1'\)])0 3106 y FD(make_header)p FJ(\()p FK(decoded)p 884 3106 25 4 v 25 w(seq)p FC([)p FK(,)20 b(maxlinelen)p FC([)p FK(,)f(header)p 1779 3106 V 28 w(name)p FC([)p FK(,)g(continuation)p 2491 3106 V 27 w(ws)12 b FC(])g(])g(])p FJ(\))208 3206 y FN(Create)20 b(a)h FJ(Header)e FN(instance)h(from)f(a)i(sequence)e(of)h(pairs)g(as)h (returned)d(by)i FJ(decode_header\(\))p FN(.)208 3339 y FJ(decode_header\(\))f FN(tak)o(es)k(a)f(header)f(v)n(alue)g(string)h (and)f(returns)g(a)i(sequence)e(of)g(pairs)h(of)g(the)g(format)f FJ(\(decoded_-)208 3438 y(string,)48 b(charset\))19 b FN(where)h FK(c)o(har)o(set)h FN(is)h(the)e(name)f(of)h(the)h (character)d(set.)208 3571 y(This)33 b(function)f(tak)o(es)i(one)f(of)h (those)f(sequence)g(of)g(pairs)g(and)h(returns)e(a)i FJ(Header)f FN(instance.)65 b(Optional)33 b FK(maxlinelen)p FN(,)208 3671 y FK(header)p 445 3671 V 28 w(name)p FN(,)19 b(and)h FK(continuation)p 1258 3671 V 27 w(ws)h FN(are)f(as)h(in)f(the) h FJ(Header)e FN(constructor)-5 b(.)0 3956 y Fv(7.1.6)100 b(Representing)30 b(char)o(acter)f(sets)0 4159 y FN(This)d(module)e (pro)o(vides)g(a)h(class)i FJ(Charset)e FN(for)g(representing)e (character)h(sets)j(and)e(character)f(set)i(con)m(v)o(ersions)d(in)j (email)g(mes-)0 4258 y(sages,)c(as)h(well)f(as)h(a)f(character)e(set)j (re)o(gistry)e(and)g(se)n(v)o(eral)g(con)m(v)o(enience)e(methods)h(for) i(manipulating)d(this)j(re)o(gistry)-5 b(.)29 b(Instances)21 b(of)0 4358 y FJ(Charset)e FN(are)i(used)f(in)g(se)n(v)o(eral)f(other)h (modules)f(within)h(the)g FJ(email)g FN(package.)0 4505 y(Import)f(this)h(class)i(from)d(the)h FJ(email.charset)e FN(module.)0 4652 y(Ne)n(w)i(in)h(v)o(ersion)e(2.2.2.)0 4798 y FL(class)i FD(Charset)p FJ(\()p FC([)p FK(input)p 804 4798 V 27 w(c)o(har)o(set)13 b FC(])p FJ(\))208 4898 y FN(Map)19 b(character)g(sets)j(to)e(their)g(email)g(properties.)208 5031 y(This)26 b(class)i(pro)o(vides)c(information)g(about)i(the)g (requirements)f(imposed)g(on)h(email)h(for)e(a)i(speci\002c)g (character)e(set.)45 b(It)26 b(also)208 5131 y(pro)o(vides)h(con)m(v)o (enience)g(routines)h(for)h(con)m(v)o(erting)d(between)j(character)f (sets,)33 b(gi)n(v)o(en)28 b(the)h(a)n(v)n(ailability)g(of)g(the)h (applicable)208 5230 y(codecs.)38 b(Gi)n(v)o(en)24 b(a)h(character)f (set,)i(it)g(will)g(do)e(its)i(best)f(to)g(pro)o(vide)e(information)f (on)j(ho)n(w)f(to)h(use)g(that)g(character)f(set)i(in)f(an)208 5330 y(email)20 b(message)g(in)g(an)g(RFC-compliant)g(w)o(ay)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(203)p eop end %%Page: 204 216 TeXDict begin 204 215 bop 208 83 a FN(Certain)22 b(character)f(sets)i (must)g(be)f(encoded)e(with)j(quoted-printable)18 b(or)k(base64)g(when) f(used)h(in)h(email)f(headers)f(or)h(bodies.)208 183 y(Certain)e(character)f(sets)i(must)f(be)g(con)m(v)o(erted)e(outright,) g(and)i(are)g(not)g(allo)n(wed)f(in)i(email.)208 315 y(Optional)h FK(input)p 699 315 25 4 v 29 w(c)o(har)o(set)j FN(is)g(as)f(described)e(belo)n(w;)j(it)g(is)f(al)o(w)o(ays)h(coerced)d (to)i(lo)n(wer)f(case.)36 b(After)23 b(being)g(alias)h(normalized)208 415 y(it)j(is)h(also)f(used)f(as)i(a)f(lookup)e(into)i(the)f(re)o (gistry)g(of)h(character)e(sets)j(to)f(\002nd)g(out)f(the)h(header)e (encoding,)h(body)g(encoding,)208 515 y(and)d(output)g(con)m(v)o (ersion)f(codec)h(to)i(be)f(used)g(for)g(the)g(character)f(set.)38 b(F)o(or)24 b(e)o(xample,)g(if)h FK(input)p 3009 515 V 28 w(c)o(har)o(set)h FN(is)f FJ(iso-8859-1)p FN(,)208 614 y(then)19 b(headers)g(and)g(bodies)g(will)h(be)g(encoded)e(using)h (quoted-printable)d(and)j(no)g(output)g(con)m(v)o(ersion)e(codec)h(is)j (necessary)-5 b(.)24 b(If)208 714 y FK(input)p 385 714 V 28 w(c)o(har)o(set)c FN(is)g FJ(euc-jp)p FN(,)e(then)g(headers)f (will)j(be)e(encoded)f(with)i(base64,)e(bodies)h(will)h(not)g(be)f (encoded,)f(b)n(ut)h(output)g(te)o(xt)208 814 y(will)i(be)h(con)m(v)o (erted)c(from)i(the)i FJ(euc-jp)e FN(character)g(set)i(to)f(the)h FJ(iso-2022-jp)d FN(character)h(set.)0 960 y FJ(Charset)g FN(instances)i(ha)n(v)o(e)e(the)h(follo)n(wing)f(data)h(attrib)n(utes:) 0 1107 y FD(input_charset)208 1207 y FN(The)i(initial)g(character)g (set)h(speci\002ed.)31 b(Common)21 b(aliases)j(are)e(con)m(v)o(erted)e (to)i(their)h FK(of)o(\002cial)e FN(email)h(names)g(\(e.g.)31 b FJ(latin_1)208 1307 y FN(is)21 b(con)m(v)o(erted)c(to)k FJ(iso-8859-1)p FN(\).)i(Def)o(aults)d(to)g(7-bit)g FJ(us-ascii)p FN(.)0 1453 y FD(header_encoding)208 1553 y FN(If)32 b(the)g(character)f(set)i(must)g(be)f(encoded)e(before)h(it)i(can)f(be) h(used)f(in)g(an)g(email)h(header)m(,)g(this)g(attrib)n(ute)f(will)h (be)f(set)h(to)208 1653 y FJ(Charset.QP)23 b FN(\(for)g (quoted-printable\),)e FJ(Charset.BASE64)h FN(\(for)i(base64)f (encoding\),)g(or)h FJ(Charset.SHORTEST)208 1752 y FN(for)19 b(the)h(shortest)g(of)g(QP)h(or)f(B)m(ASE64)g(encoding.)j(Otherwise,)d (it)h(will)g(be)f FJ(None)p FN(.)0 1899 y FD(body_encoding)208 1999 y FN(Same)f(as)h FK(header)p 738 1999 V 28 w(encoding)p FN(,)d(b)n(ut)i(describes)g(the)g(encoding)e(for)i(the)g(mail)g (message')-5 b(s)20 b(body)-5 b(,)17 b(which)i(indeed)f(may)h(be)g(dif) n(fer)n(-)208 2098 y(ent)h(than)f(the)i(header)e(encoding.)k FJ(Charset.SHORTEST)17 b FN(is)k(not)f(allo)n(wed)g(for)f FK(body)p 2796 2098 V 29 w(encoding)p FN(.)0 2245 y FD(output_charset) 208 2345 y FN(Some)i(character)f(sets)i(must)g(be)f(con)m(v)o(erted)e (before)h(the)o(y)h(can)g(be)g(used)h(in)f(email)h(headers)e(or)h (bodies.)28 b(If)22 b(the)f FK(input)p 3634 2345 V 29 w(c)o(har)o(set)208 2445 y FN(is)f(one)f(of)g(them,)g(this)i(attrib)n (ute)e(will)h(contain)f(the)g(name)g(of)g(the)h(character)e(set)j (output)d(will)i(be)g(con)m(v)o(erted)d(to.)25 b(Otherwise,)19 b(it)208 2544 y(will)h(be)h FJ(None)p FN(.)0 2691 y FD(input_codec)208 2791 y FN(The)16 b(name)h(of)g(the)g(Python)f(codec)g(used)h(to)g(con)m (v)o(ert)e(the)i FK(input)p 2032 2791 V 29 w(c)o(har)o(set)h FN(to)g(Unicode.)23 b(If)16 b(no)h(con)m(v)o(ersion)e(codec)h(is)i (necessary)-5 b(,)208 2890 y(this)20 b(attrib)n(ute)g(will)h(be)f FJ(None)p FN(.)0 3037 y FD(output_codec)208 3137 y FN(The)h(name)g(of)h (the)f(Python)g(codec)g(used)g(to)h(con)m(v)o(ert)e(Unicode)h(to)g(the) h FK(output)p 2511 3137 V 28 w(c)o(har)o(set)q FN(.)30 b(If)22 b(no)f(con)m(v)o(ersion)e(codec)i(is)i(neces-)208 3236 y(sary)-5 b(,)19 b(this)i(attrib)n(ute)f(will)g(ha)n(v)o(e)g(the)g (same)h(v)n(alue)e(as)i(the)f FK(input)p 2044 3236 V 29 w(codec)p FN(.)0 3383 y FJ(Charset)f FN(instances)i(also)f(ha)n(v)o (e)g(the)g(follo)n(wing)e(methods:)0 3530 y FD(get_body_encoding)p FJ(\(\))208 3630 y FN(Return)h(the)i(content)e(transfer)g(encoding)f (used)i(for)g(body)e(encoding.)208 3763 y(This)31 b(is)i(either)e(the)h (string)f(`)p FJ(quoted-printable)p FN(')e(or)i(`)p FJ(base64)p FN(')g(depending)e(on)i(the)h(encoding)e(used,)k(or)d(it)i(is)f(a)208 3862 y(function,)18 b(in)i(which)f(case)h(you)f(should)g(call)i(the)f (function)e(with)i(a)g(single)g(ar)o(gument,)d(the)j(Message)g(object)g (being)f(encoded.)208 3962 y(The)g(function)g(should)g(then)h(set)h (the)f FO(Content-T)-9 b(r)o(ansf)n(er-Encoding)o(:)20 b FN(header)f(itself)h(to)h(whate)n(v)o(er)d(is)k(appropriate.)208 4095 y(Returns)31 b(the)i(string)e(`)p FJ(quoted-printable)p FN(')e(if)k FK(body)p 1991 4095 V 28 w(encoding)d FN(is)j FJ(QP)p FN(,)f(returns)f(the)h(string)g(`)p FJ(base64)p FN(')f(if)h FK(body)p 3849 4095 V 28 w(-)208 4194 y(encoding)18 b FN(is)j FJ(BASE64)p FN(,)e(and)h(returns)f(the)h(string)g(`)p FJ(7bit)p FN(')g(otherwise.)0 4341 y FD(convert)p FJ(\()p FK(s)p FJ(\))208 4441 y FN(Con)m(v)o(ert)e(the)i(string)g FK(s)h FN(from)f(the)g FK(input)p 1358 4441 V 28 w(codec)g FN(to)g(the)g FK(output)p 2022 4441 V 28 w(codec)p FN(.)0 4588 y FD(to_splittable)p FJ(\()p FK(s)p FJ(\))208 4687 y FN(Con)m(v)o(ert)e(a)j(possibly)e(multibyte)g(string)h(to)h(a)f (safely)g(splittable)h(format.)i FK(s)e FN(is)h(the)e(string)g(to)g (split.)208 4820 y(Uses)k(the)f FK(input)p 695 4820 V 28 w(codec)g FN(to)g(try)g(and)f(con)m(v)o(ert)f(the)j(string)e(to)i (Unicode,)e(so)i(it)f(can)g(be)g(safely)g(split)h(on)f(character)f (boundaries)208 4920 y(\(e)n(v)o(en)c(for)i(multibyte)f(characters\).) 208 5053 y(Returns)h(the)g(string)g(as-is)h(if)f(it)h(isn')o(t)f(kno)n (wn)f(ho)n(w)g(to)i(con)m(v)o(ert)d FK(s)j FN(to)f(Unicode)f(with)h (the)h FK(input)p 2962 5053 V 28 w(c)o(har)o(set)q FN(.)208 5186 y(Characters)28 b(that)i(could)e(not)h(be)g(con)m(v)o(erted)d(to)k (Unicode)e(will)i(be)f(replaced)f(with)h(the)g(Unicode)f(replacement)g (character)208 5285 y(`)p FJ(U+FFFD)p FN('.)p 0 5549 3901 4 v 0 5649 a FI(204)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 205 217 TeXDict begin 205 216 bop 0 83 a FD(from_splittable)p FJ(\()p FK(ustr)r FC([)p FK(,)17 b(to)p 1079 83 25 4 v 30 w(output)c FC(])p FJ(\))208 183 y FN(Con)m(v)o(ert)18 b(a)j(splittable)f(string)g(back)f(into)h(an)g(encoded)f(string.)24 b FK(ustr)f FN(is)e(a)g(Unicode)e(string)h(to)g(\223unsplit\224.)208 315 y(This)27 b(method)f(uses)i(the)g(proper)d(codec)i(to)g(try)h(and)e (con)m(v)o(ert)g(the)h(string)g(from)g(Unicode)f(back)h(into)g(an)g (encoded)f(format.)208 415 y(Return)19 b(the)i(string)e(as-is)i(if)g (it)g(is)g(not)f(Unicode,)e(or)i(if)h(it)g(could)e(not)h(be)g(con)m(v)o (erted)e(from)h(Unicode.)208 548 y(Characters)26 b(that)h(could)f(not)h (be)g(con)m(v)o(erted)d(from)i(Unicode)g(will)i(be)f(replaced)f(with)h (an)g(appropriate)e(character)h(\(usually)208 648 y(`)p FJ(?)p FN('\).)208 780 y(If)20 b FK(to)p 354 780 V 29 w(output)h FN(is)g FJ(True)g FN(\(the)f(def)o(ault\),)f(uses)i FK(output)p 1742 780 V 28 w(codec)e FN(to)i(con)m(v)o(ert)d(to)j(an)f (encoded)f(format.)24 b(If)d FK(to)p 3228 780 V 29 w(output)g FN(is)g FJ(False)p FN(,)f(it)208 880 y(uses)g FK(input)p 548 880 V 29 w(codec)p FN(.)0 1027 y FD(get_output_charset)p FJ(\(\))208 1127 y FN(Return)f(the)i(output)d(character)h(set.)208 1259 y(This)h(is)h(the)f FK(output)p 793 1259 V 28 w(c)o(har)o(set)i FN(attrib)n(ute)e(if)g(that)h(is)g(not)e FJ(None)p FN(,)h(otherwise)g (it)h(is)g FK(input)p 2701 1259 V 28 w(c)o(har)o(set)q FN(.)0 1406 y FD(encoded_header_len)p FJ(\(\))208 1506 y FN(Return)e(the)i(length)e(of)h(the)g(encoded)e(header)h(string,)h (properly)e(calculating)h(for)h(quoted-printable)c(or)k(base64)f (encoding.)0 1653 y FD(header_encode)p FJ(\()p FK(s)p FC([)p FK(,)f(con)m(vert)13 b FC(])p FJ(\))208 1752 y FN(Header)n(-encode)k(the)j(string)g FK(s)p FN(.)208 1885 y(If)31 b FK(con)m(vert)h FN(is)g FJ(True)p FN(,)i(the)d(string)g (will)h(be)f(con)m(v)o(erted)e(from)h(the)h(input)g(charset)g(to)g(the) h(output)e(charset)h(automatically)-5 b(.)208 1985 y(This)31 b(is)h(not)e(useful)g(for)h(multibyte)f(character)f(sets,)35 b(which)30 b(ha)n(v)o(e)g(line)h(length)f(issues)i(\(multibyte)e (characters)g(must)h(be)208 2084 y(split)e(on)f(a)i(character)m(,)f (not)f(a)i(byte)e(boundary\);)i(use)f(the)g(higher)n(-le)n(v)o(el)e FJ(Header)h FN(class)i(to)f(deal)g(with)g(these)g(issues)g(\(see)208 2184 y FJ(email.header)p FN(\).)22 b FK(con)m(vert)f FN(def)o(aults)f(to)g FJ(False)p FN(.)208 2317 y(The)f(type)h(of)g (encoding)e(\(base64)h(or)h(quoted-printable\))c(will)21 b(be)f(based)g(on)g(the)g FK(header)p 2824 2317 V 28 w(encoding)f FN(attrib)n(ute.)0 2464 y FD(body_encode)p FJ(\()p FK(s)p FC([)p FK(,)f(con)m(vert)13 b FC(])p FJ(\))208 2563 y FN(Body-encode)k(the)j(string)g FK(s)p FN(.)208 2696 y(If)j FK(con)m(vert)h FN(is)g FJ(True)f FN(\(the)g(def)o(ault\),) g(the)h(string)f(will)h(be)f(con)m(v)o(erted)e(from)h(the)h(input)g (charset)g(to)h(output)e(charset)h(automat-)208 2796 y(ically)-5 b(.)33 b(Unlik)o(e)22 b FJ(header_encode\(\))p FN(,)g(there)g(are)h(no)g(issues)g(with)h(byte)e(boundaries)f(and)i (multibyte)e(charsets)i(in)h(email)208 2895 y(bodies,)19 b(so)h(this)h(is)g(usually)f(pretty)f(safe.)208 3028 y(The)g(type)h(of)g(encoding)e(\(base64)h(or)h(quoted-printable\))c (will)21 b(be)f(based)g(on)g(the)g FK(body)p 2755 3028 V 28 w(encoding)e FN(attrib)n(ute.)0 3175 y(The)i FJ(Charset)f FN(class)i(also)g(pro)o(vides)d(a)j(number)d(of)i(methods)f(to)i (support)e(standard)g(operations)f(and)i(b)n(uilt-in)f(functions.)0 3322 y FD(__str__)p FJ(\(\))208 3422 y FN(Returns)h FK(input)p 664 3422 V 28 w(c)o(har)o(set)i FN(as)f(a)f(string)g(coerced)f(to)h(lo) n(wer)g(case.)25 b FJ(__repr__\(\))19 b FN(is)i(an)g(alias)g(for)e FJ(__str__\(\))p FN(.)0 3569 y FD(__eq__)p FJ(\()p FK(other)r FJ(\))208 3668 y FN(This)h(method)f(allo)n(ws)h(you)f(to)i(compare)d (tw)o(o)j FJ(Charset)e FN(instances)h(for)g(equality)-5 b(.)0 3815 y FD(__ne__)p FJ(\()p FK(other)r FJ(\))208 3915 y FN(This)20 b(method)f(allo)n(ws)h(you)f(to)i(compare)d(tw)o(o)j FJ(Charset)e FN(instances)h(for)g(inequality)-5 b(.)0 4062 y(The)24 b FJ(email.charset)e FN(module)g(also)i(pro)o(vides)e (the)i(follo)n(wing)e(functions)h(for)g(adding)f(ne)n(w)i(entries)g(to) g(the)g(global)f(character)0 4161 y(set,)e(alias,)f(and)g(codec)f(re)o (gistries:)0 4308 y FD(add_charset)p FJ(\()p FK(c)o(har)o(set)q FC([)p FK(,)f(header)p 1160 4308 V 28 w(enc)p FC([)p FK(,)i(body)p 1548 4308 V 28 w(enc)p FC([)p FK(,)g(output)p 1987 4308 V 28 w(c)o(har)o(set)13 b FC(])f(])g(])p FJ(\))208 4408 y FN(Add)19 b(character)g(properties)g(to)h(the)h(global)e(re)o (gistry)-5 b(.)208 4541 y FK(c)o(har)o(set)21 b FN(is)g(the)f(input)g (character)f(set,)i(and)e(must)h(be)h(the)f(canonical)f(name)g(of)h(a)h (character)e(set.)208 4673 y(Optional)37 b FK(header)p 774 4673 V 29 w(enc)h FN(and)g FK(body)p 1279 4673 V 29 w(enc)g FN(is)i(either)e FJ(Charset.QP)f FN(for)h(quoted-printable,) i FJ(Charset.BASE64)c FN(for)208 4773 y(base64)29 b(encoding,)h FJ(Charset.SHORTEST)d FN(for)j(the)g(shortest)g(of)g(quoted-printable)c (or)k(base64)f(encoding,)h(or)g FJ(None)208 4873 y FN(for)19 b(no)h(encoding.)j FJ(SHORTEST)c FN(is)i(only)e(v)n(alid)h(for)g FK(header)p 1983 4873 V 28 w(enc)p FN(.)25 b(The)20 b(def)o(ault)f(is)i FJ(None)f FN(for)g(no)g(encoding.)208 5005 y(Optional)j FK(output)p 742 5005 V 28 w(c)o(har)o(set)i FN(is)g(the)f(character)f (set)h(that)g(the)g(output)f(should)g(be)h(in.)36 b(Con)m(v)o(ersions) 22 b(will)j(proceed)d(from)h(input)208 5105 y(charset,)c(to)g(Unicode,) f(to)i(the)g(output)e(charset)h(when)g(the)g(method)f FJ(Charset.convert\(\))f FN(is)k(called.)j(The)19 b(def)o(ault)g(is)h (to)208 5205 y(output)f(in)h(the)g(same)g(character)f(set)i(as)g(the)f (input.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(205)p eop end %%Page: 206 218 TeXDict begin 206 217 bop 208 83 a FN(Both)21 b FK(input)p 568 83 25 4 v 29 w(c)o(har)o(set)i FN(and)e FK(output)p 1219 83 V 28 w(c)o(har)o(set)i FN(must)f(ha)n(v)o(e)f(Unicode)f(codec)h (entries)h(in)g(the)f(module')-5 b(s)21 b(character)f(set-to-codec)208 183 y(mapping;)33 b(use)d FJ(add_codec\(\))f FN(to)h(add)f(codecs)h (the)g(module)e(does)i(not)g(kno)n(w)f(about.)54 b(See)30 b(the)g FJ(codecs)g FN(module')-5 b(s)208 282 y(documentation)17 b(for)i(more)h(information.)208 415 y(The)f(global)h(character)f(set)i (re)o(gistry)e(is)i(k)o(ept)f(in)g(the)g(module)f(global)g(dictionary)g FJ(CHARSETS)p FN(.)0 562 y FD(add_alias)p FJ(\()p FK(alias,)f (canonical)p FJ(\))208 662 y FN(Add)26 b(a)i(character)e(set)h(alias.) 47 b FK(alias)27 b FN(is)h(the)f(alias)h(name,)g(e.g.)45 b FJ(latin-1)p FN(.)g FK(canonical)26 b FN(is)i(the)f(character)f(set') -5 b(s)28 b(canonical)208 761 y(name,)19 b(e.g.)25 b FJ(iso-8859-1)p FN(.)208 894 y(The)19 b(global)h(charset)g(alias)h(re)o (gistry)e(is)i(k)o(ept)f(in)g(the)g(module)f(global)g(dictionary)g FJ(ALIASES)p FN(.)0 1041 y FD(add_codec)p FJ(\()p FK(c)o(har)o(set,)f (codecname)p FJ(\))208 1141 y FN(Add)h(a)i(codec)e(that)i(map)e (characters)g(in)i(the)f(gi)n(v)o(en)f(character)g(set)i(to)f(and)g (from)f(Unicode.)208 1273 y FK(c)o(har)o(set)24 b FN(is)g(the)f (canonical)f(name)g(of)h(a)h(character)e(set.)34 b FK(codecname)21 b FN(is)j(the)f(name)g(of)f(a)i(Python)e(codec,)h(as)g(appropriate)e (for)208 1373 y(the)f(second)f(ar)o(gument)f(to)i(the)g FJ(unicode\(\))g FN(b)n(uilt-in,)f(or)h(to)g(the)g FJ(encode\(\))g FN(method)e(of)i(a)h(Unicode)e(string.)0 1658 y Fv(7.1.7)100 b(Encoders)0 1861 y FN(When)18 b(creating)f FJ(Message)h FN(objects)g(from)f(scratch,)i(you)e(often)g(need)h(to)h(encode)e(the)h (payloads)f(for)h(transport)f(through)f(compliant)0 1960 y(mail)k(serv)o(ers.)25 b(This)20 b(is)h(especially)f(true)g(for)f FO(image/*)g FN(and)h FO(te)n(xt/*)g FN(type)g(messages)g(containing)e (binary)h(data.)0 2107 y(The)28 b FJ(email)g FN(package)f(pro)o(vides)f (some)i(con)m(v)o(enient)e(encodings)g(in)j(its)g FJ(encoders)e FN(module.)48 b(These)28 b(encoders)f(are)h(actually)0 2207 y(used)e(by)g(the)h FJ(MIMEAudio)f FN(and)g FJ(MIMEImage)f FN(class)j(constructors)c(to)j(pro)o(vide)e(def)o(ault)h(encodings.)42 b(All)27 b(encoder)e(functions)0 2307 y(tak)o(e)f(e)o(xactly)g(one)g (ar)o(gument,)f(the)h(message)g(object)g(to)h(encode.)36 b(The)o(y)23 b(usually)h(e)o(xtract)g(the)g(payload,)g(encode)f(it,)j (and)e(reset)h(the)0 2406 y(payload)19 b(to)h(this)h(ne)n(wly)e (encoded)g(v)n(alue.)24 b(The)o(y)19 b(should)g(also)i(set)g(the)f FO(Content-T)-9 b(r)o(ansf)n(er-Encodin)o(g:)20 b FN(header)f(as)h (appropriate.)0 2553 y(Here)g(are)g(the)g(encoding)f(functions)f(pro)o (vided:)0 2700 y FD(encode_quopri)p FJ(\()p FK(msg)p FJ(\))208 2800 y FN(Encodes)55 b(the)h(payload)f(into)h (quoted-printable)c(form)j(and)h(sets)h(the)g FO(Content-T)-9 b(r)o(ansf)n(er-Encodin)o(g:)91 b FN(header)55 b(to)208 2899 y FJ(quoted-printable)1008 2869 y FF(2)1038 2899 y FN(.)33 b(This)23 b(is)h(a)g(good)d(encoding)g(to)i(use)g(when)f (most)h(of)g(your)f(payload)f(is)j(normal)d(printable)h(data,)208 2999 y(b)n(ut)e(contains)f(a)i(fe)n(w)f(unprintable)e(characters.)0 3146 y FD(encode_base64)p FJ(\()p FK(msg)p FJ(\))208 3245 y FN(Encodes)28 b(the)i(payload)e(into)h(base64)g(form)g(and)g (sets)h(the)g FO(Content-T)-9 b(r)o(ansf)n(er-Encoding)o(:)39 b FN(header)28 b(to)i FJ(base64)p FN(.)53 b(This)30 b(is)208 3345 y(a)d(good)e(encoding)g(to)i(use)g(when)f(most)h(of)f(your)g (payload)f(is)j(unprintable)d(data)h(since)h(it)h(is)f(a)h(more)e (compact)f(form)h(than)208 3445 y(quoted-printable.)21 b(The)f(dra)o(wback)e(of)i(base64)f(encoding)f(is)j(that)g(it)g (renders)e(the)h(te)o(xt)g(non-human)d(readable.)0 3591 y FD(encode_7or8bit)p FJ(\()p FK(msg)p FJ(\))208 3691 y FN(This)26 b(doesn')o(t)e(actually)i(modify)e(the)i(message')-5 b(s)27 b(payload,)e(b)n(ut)i(it)f(does)g(set)h(the)f FO(Content-T)-9 b(r)o(ansf)n(er-Encoding)o(:)32 b FN(header)24 b(to)208 3791 y(either)19 b FJ(7bit)h FN(or)g FJ(8bit)g FN(as)h(appropriate,)d(based)i(on)f(the)i(payload)d(data.)0 3938 y FD(encode_noop)p FJ(\()p FK(msg)p FJ(\))208 4037 y FN(This)i(does)g(nothing;)e(it)j(doesn')o(t)e(e)n(v)o(en)g(set)i(the) f FO(Content-T)-9 b(r)o(ansf)n(er-Encoding:)19 b FN(header)-5 b(.)0 4322 y Fv(7.1.8)100 b(Exception)29 b(and)g(Def)m(ect)f(classes)0 4525 y FN(The)20 b(follo)n(wing)e(e)o(xception)h(classes)i(are)f (de\002ned)f(in)i(the)f FJ(email.errors)e FN(module:)0 4672 y FL(exception)h FD(MessageError)p FJ(\(\))208 4771 y FN(This)30 b(is)h(the)f(base)h(class)g(for)e(all)i(e)o(xceptions)e (that)h(the)g FJ(email)g FN(package)f(can)h(raise.)55 b(It)31 b(is)g(deri)n(v)o(ed)d(from)h(the)i(standard)208 4871 y FJ(Exception)19 b FN(class)i(and)e(de\002nes)h(no)g(additional)f (methods.)0 5018 y FL(exception)g FD(MessageParseError)p FJ(\(\))208 5118 y FN(This)h(is)h(the)f(base)h(class)g(for)e(e)o (xceptions)g(thro)n(wn)g(by)g(the)i FJ(Parser)e FN(class.)26 b(It)21 b(is)g(deri)n(v)o(ed)d(from)h FJ(MessageError)p FN(.)p 0 5189 1560 4 v 90 5244 a FB(2)120 5268 y FH(Note)e(that)i (encoding)g(with)e Fz(encode_quopri\(\))e FH(also)i(encodes)i(all)f (tabs)f(and)h(space)g(characters)i(in)d(the)h(data.)p 0 5549 3901 4 v 0 5649 a FI(206)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 207 219 TeXDict begin 207 218 bop 0 83 a FL(exception)19 b FD(HeaderParseError) p FJ(\(\))208 183 y FN(Raised)f(under)f(some)i(error)e(conditions)g (when)g(parsing)h(the)g(RFC)i(2822)d(headers)g(of)h(a)h(message,)g (this)f(class)i(is)f(deri)n(v)o(ed)e(from)208 282 y FJ (MessageParseError)p FN(.)22 b(It)d(can)g(be)g(raised)g(from)g(the)g FJ(Parser.parse\(\))e FN(or)i FJ(Parser.parsestr\(\))e FN(methods.)208 415 y(Situations)29 b(where)g(it)i(can)f(be)f(raised)h (include)f(\002nding)g(an)g(en)m(v)o(elope)f(header)h(after)g(the)h (\002rst)h(RFC)g(2822)d(header)h(of)h(the)208 515 y(message,)22 b(\002nding)f(a)i(continuation)d(line)i(before)f(the)i(\002rst)g(RFC)h (2822)d(header)g(is)i(found,)e(or)h(\002nding)f(a)i(line)g(in)f(the)g (headers)208 614 y(which)d(is)i(neither)f(a)g(header)f(or)h(a)h (continuation)d(line.)0 761 y FL(exception)h FD(BoundaryError)p FJ(\(\))208 861 y FN(Raised)f(under)f(some)i(error)e(conditions)g(when) g(parsing)h(the)g(RFC)i(2822)d(headers)g(of)h(a)h(message,)g(this)f (class)i(is)f(deri)n(v)o(ed)e(from)208 960 y FJ(MessageParseError)p FN(.)22 b(It)d(can)g(be)g(raised)g(from)g(the)g FJ(Parser.parse\(\))e FN(or)i FJ(Parser.parsestr\(\))e FN(methods.)208 1093 y(Situations)23 b(where)f(it)i(can)f(be)h(raised)f(include)f(not)h (being)f(able)h(to)h(\002nd)f(the)g(starting)g(or)g(terminating)f (boundary)e(in)j(a)h FO(m)o(ulti-)208 1193 y(par)s(t/*)19 b FN(message)h(when)f(strict)i(parsing)e(is)j(used.)0 1340 y FL(exception)d FD(MultipartConversionError)p FJ(\(\))208 1439 y FN(Raised)53 b(when)g(a)h(payload)e(is)i(added)e(to)i(a)g FJ(Message)e FN(object)h(using)g FJ(add_payload\(\))p FN(,)59 b(b)n(ut)54 b(the)f(payload)208 1539 y(is)h(already)e(a)h (scalar)h(and)e(the)h(message')-5 b(s)54 b FO(Content-T)-9 b(ype:)88 b FN(main)52 b(type)h(is)h(not)f(either)g FO(m)o(ultipar)s(t) e FN(or)i(missing.)208 1639 y FJ(MultipartConversionError)16 b FN(multiply)j(inherits)h(from)f FJ(MessageError)g FN(and)g(the)h(b)n (uilt-in)g FJ(TypeError)p FN(.)208 1772 y(Since)29 b FJ(Message.add_payload\(\))e FN(is)j(deprecated,)g(this)g(e)o(xception) e(is)j(rarely)d(raised)i(in)g(practice.)52 b(Ho)n(we)n(v)o(er)29 b(the)208 1871 y(e)o(xception)34 b(may)h(also)h(be)g(raised)g(if)g(the) g FJ(attach\(\))f FN(method)f(is)j(called)f(on)f(an)h(instance)g(of)f (a)i(class)f(deri)n(v)o(ed)f(from)208 1971 y FJ(MIMENonMultipart)17 b FN(\(e.g.)25 b FJ(MIMEImage)p FN(\).)0 2118 y(Here')-5 b(s)21 b(the)h(list)g(of)f(the)g(defects)g(that)g(the)h FJ(FeedParser)d FN(can)i(\002nd)g(while)h(parsing)e(messages.)28 b(Note)21 b(that)g(the)h(defects)f(are)g(added)0 2217 y(to)h(the)g(message)g(where)g(the)g(problem)e(w)o(as)j(found,)d(so)j (for)e(e)o(xample,)g(if)h(a)h(message)f(nested)f(inside)h(a)h FO(m)o(ultipar)s(t/alter)r(nativ)n(e)17 b FN(had)k(a)0 2317 y(malformed)d(header)m(,)g(that)j(nested)f(message)g(object)f(w)o (ould)h(ha)n(v)o(e)f(a)i(defect,)e(b)n(ut)i(the)f(containing)e (messages)i(w)o(ould)g(not.)0 2464 y(All)h(defect)e(classes)j(are)e (subclassed)g(from)f FJ(email.errors.MessageDefect)p FN(,)c(b)n(ut)21 b(this)f(class)i(is)f FK(not)f FN(an)g(e)o(xception!)0 2611 y(Ne)n(w)g(in)h(v)o(ersion)e(2.4:)g(All)i(the)f(defect)g(classes)h (were)f(added.)125 2841 y FM(\017)41 b FJ(NoBoundaryInMultipartDefect) 12 b FN(\226)17 b(A)g(message)g(claimed)f(to)h(be)g(a)h(multipart,)e(b) n(ut)h(had)f(no)h FO(boundar)r(y)e FN(parameter)-5 b(.)125 3007 y FM(\017)41 b FJ(StartBoundaryNotFoundDefect)21 b FN(\226)k(The)g(start)h(boundary)d(claimed)i(in)g(the)h FO(Content-T)-9 b(ype:)32 b FN(header)25 b(w)o(as)h(ne)n(v)o(er)208 3106 y(found.)125 3272 y FM(\017)41 b FJ (FirstHeaderLineIsContinuationDefe)o(ct)22 b FN(\226)27 b(The)f(message)h(had)f(a)i(continuation)c(line)j(as)h(its)g(\002rst)g (header)208 3372 y(line.)125 3538 y FM(\017)41 b FJ (MisplacedEnvelopeHeaderDefect)13 b FN(-)19 b(A)g(\223Unix)f(From\224)g (header)g(w)o(as)h(found)e(in)i(the)f(middle)g(of)g(a)h(header)f (block.)125 3704 y FM(\017)41 b FJ(MalformedHeaderDefect)16 b FN(\226)21 b(A)f(header)f(w)o(as)i(found)e(that)h(w)o(as)h(missing)f (a)h(colon,)e(or)h(w)o(as)h(otherwise)e(malformed.)125 3870 y FM(\017)41 b FJ(MultipartInvariantViolationDefect)17 b FN(\226)24 b(A)g(message)f(claimed)g(to)g(be)h(a)f FO(m)o(ultipar)s(t)p FN(,)g(b)n(ut)g(no)g(subparts)g(were)208 3970 y(found.)g(Note)d(that)g(when)f(a)h(message)g(has)g(this)h (defect,)e(its)i FJ(is_multipart\(\))d FN(method)h(may)g(return)g(f)o (alse)h(e)n(v)o(en)f(though)208 4069 y(its)i(content)e(type)h(claims)g (to)h(be)f FO(m)o(ultipar)s(t)p FN(.)0 4354 y Fv(7.1.9)100 b(Miscellaneous)30 b(utilities)0 4557 y FN(There)19 b(are)h(se)n(v)o (eral)g(useful)g(utilities)h(pro)o(vided)c(in)k(the)f FJ(email.utils)e FN(module:)0 4704 y FD(quote)p FJ(\()p FK(str)r FJ(\))208 4804 y FN(Return)35 b(a)h(ne)n(w)f(string)h(with)f (backslashes)h(in)f FK(str)k FN(replaced)34 b(by)i(tw)o(o)g (backslashes,)i(and)d(double)g(quotes)g(replaced)f(by)208 4903 y(backslash-double)17 b(quote.)0 5050 y FD(unquote)p FJ(\()p FK(str)r FJ(\))208 5150 y FN(Return)25 b(a)i(ne)n(w)e(string)h (which)f(is)i(an)f FK(unquoted)e FN(v)o(ersion)h(of)g FK(str)r FN(.)44 b(If)26 b FK(str)j FN(ends)d(and)f(be)o(gins)g(with)h (double)f(quotes,)h(the)o(y)g(are)208 5249 y(stripped)19 b(of)n(f.)24 b(Lik)o(e)n(wise)c(if)h FK(str)i FN(ends)d(and)g(be)o (gins)f(with)h(angle)g(brack)o(ets,)f(the)o(y)h(are)g(stripped)f(of)n (f.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(207)p eop end %%Page: 208 220 TeXDict begin 208 219 bop 0 83 a FD(parseaddr)p FJ(\()p FK(addr)m(ess)p FJ(\))208 183 y FN(P)o(arse)24 b(address)h(\226)f (which)h(should)e(be)i(the)g(v)n(alue)f(of)g(some)g(address-containing) e(\002eld)j(such)f(as)i FO(T)-9 b(o:)33 b FN(or)25 b FO(Cc:)35 b FN(\226)24 b(into)h(its)g(con-)208 282 y(stituent)e FK(r)m(ealname)f FN(and)g FK(email)h(addr)m(ess)g FN(parts.)34 b(Returns)23 b(a)g(tuple)g(of)f(that)i(information,)d(unless)i(the)g (parse)g(f)o(ails,)h(in)f(which)208 382 y(case)d(a)h(2-tuple)e(of)h FJ(\('',)49 b(''\))20 b FN(is)h(returned.)0 529 y FD(formataddr)p FJ(\()p FK(pair)r FJ(\))208 628 y FN(The)k(in)m(v)o(erse)f(of)h FJ(parseaddr\(\))p FN(,)g(this)h(tak)o(es)g(a)g(2-tuple)e(of)h(the)g (form)g FJ(\(realname,)48 b(email_address\))23 b FN(and)i(re-)208 728 y(turns)17 b(the)g(string)h(v)n(alue)f(suitable)g(for)g(a)h FO(T)-9 b(o:)24 b FN(or)17 b FO(Cc:)25 b FN(header)-5 b(.)23 b(If)18 b(the)f(\002rst)i(element)e(of)g FK(pair)j FN(is)e(f)o(alse,)h(then)e(the)g(second)g(element)208 828 y(is)k(returned)d(unmodi\002ed.)0 975 y FD(getaddresses)p FJ(\()p FK(\002eldvalues)p FJ(\))208 1074 y FN(This)28 b(method)f(returns)g(a)i(list)g(of)f(2-tuples)f(of)h(the)g(form)f (returned)f(by)i FJ(parseaddr\(\))p FN(.)47 b FK(\002eldvalues)27 b FN(is)i(a)g(sequence)e(of)208 1174 y(header)19 b(\002eld)i(v)n(alues) f(as)i(might)e(be)h(returned)e(by)h FJ(Message.get_all\(\))p FN(.)k(Here')-5 b(s)21 b(a)g(simple)g(e)o(xample)e(that)i(gets)g(all)h (the)208 1273 y(recipients)d(of)h(a)h(message:)444 1406 y FA(from)44 b(email.utils)f(import)h(getaddresses)444 1589 y(tos)g(=)h(msg.get_all\('to',)d([]\))444 1680 y(ccs)i(=)h (msg.get_all\('cc',)d([]\))444 1772 y(resent_tos)h(=)i (msg.get_all\('resent-to',)40 b([]\))444 1863 y(resent_ccs)j(=)i (msg.get_all\('resent-cc',)40 b([]\))444 1954 y(all_recipients)i(=)j (getaddresses\(tos)d(+)j(ccs)f(+)h(resent_tos)e(+)i(resent_ccs\))0 2158 y FD(parsedate)p FJ(\()p FK(date)p FJ(\))208 2258 y FN(Attempts)19 b(to)h(parse)f(a)h(date)g(according)d(to)j(the)g (rules)f(in)h(RFC)h(2822.)j(ho)n(we)n(v)o(er)m(,)17 b(some)i(mailers)h (don')o(t)e(follo)n(w)h(that)g(format)g(as)208 2357 y(speci\002ed,)d (so)i FJ(parsedate\(\))d FN(tries)i(to)g(guess)g(correctly)e(in)i(such) g(cases.)24 b FK(date)16 b FN(is)i(a)f(string)g(containing)e(an)h(RFC)j (2822)c(date,)208 2457 y(such)26 b(as)h FJ("Mon,)49 b(20)h(Nov)f(1995)g (19:12:08)f(-0500")p FN(.)c(If)27 b(it)g(succeeds)g(in)g(parsing)e(the) i(date,)h FJ(parsedate\(\))208 2556 y FN(returns)19 b(a)j(9-tuple)d (that)i(can)g(be)g(passed)f(directly)g(to)h FJ(time.mktime\(\))p FN(;)f(otherwise)g FJ(None)g FN(will)i(be)f(returned.)k(Note)20 b(that)208 2656 y(\002elds)g(6,)g(7,)g(and)g(8)g(of)g(the)g(result)h (tuple)e(are)h(not)g(usable.)0 2803 y FD(parsedate_tz)p FJ(\()p FK(date)p FJ(\))208 2903 y FN(Performs)d(the)i(same)f(function) f(as)i FJ(parsedate\(\))p FN(,)f(b)n(ut)g(returns)g(either)g FJ(None)g FN(or)h(a)g(10-tuple;)e(the)i(\002rst)g(9)g(elements)f(mak)o (e)208 3002 y(up)24 b(a)h(tuple)f(that)h(can)f(be)h(passed)g(directly)f (to)g FJ(time.mktime\(\))p FN(,)g(and)g(the)h(tenth)f(is)i(the)e(of)n (fset)h(of)f(the)h(date')-5 b(s)25 b(timezone)208 3102 y(from)20 b(UTC)j(\(which)e(is)i(the)f(of)n(\002cial)f(term)h(for)f (Greenwich)g(Mean)h(T)m(ime\))2384 3072 y FF(3)2416 3102 y FN(.)31 b(If)21 b(the)h(input)f(string)h(has)g(no)g(timezone,)f(the)h (last)208 3201 y(element)d(of)h(the)g(tuple)g(returned)e(is)k FJ(None)p FN(.)i(Note)c(that)h(\002elds)f(6,)g(7,)g(and)g(8)g(of)g(the) g(result)h(tuple)f(are)g(not)f(usable.)0 3348 y FD(mktime_tz)p FJ(\()p FK(tuple)p FJ(\))208 3448 y FN(T)l(urn)h(a)i(10-tuple)e(as)i (returned)e(by)h FJ(parsedate_tz\(\))e FN(into)j(a)g(UTC)g(timestamp.) 28 b(It)22 b(the)f(timezone)g(item)g(in)h(the)g(tuple)f(is)208 3548 y FJ(None)p FN(,)i(assume)g(local)g(time.)33 b(Minor)22 b(de\002cienc)o(y:)30 b FJ(mktime_tz\(\))21 b FN(interprets)i(the)g (\002rst)g(8)g(elements)g(of)g FK(tuple)f FN(as)i(a)g(local)208 3647 y(time)18 b(and)g(then)f(compensates)g(for)h(the)g(timezone)f(dif) n(ference.)23 b(This)18 b(may)g(yield)g(a)g(slight)h(error)e(around)f (changes)h(in)i(daylight)208 3747 y(sa)n(vings)h(time,)g(though)e(not)i (w)o(orth)g(w)o(orrying)e(about)h(for)h(common)e(use.)0 3894 y FD(formatdate)p FJ(\()p FC([)p FK(time)o(val)p FC([)p FK(,)f(localtime)12 b FC(][)p FK(,)19 b(use)m(gmt)13 b FC(])f(])p FJ(\))208 3993 y FN(Returns)20 b(a)g(date)g(string)g(as)h (per)f(RFC)i(2822,)c(e.g.:)444 4217 y FA(Fri,)44 b(09)g(Nov)h(2001)f (01:08:47)f(-0000)208 4407 y FN(Optional)61 b FK(time)o(val)g FN(if)i(gi)n(v)o(en)d(is)j(a)f(\003oating)g(point)f(time)h(v)n(alue)f (as)i(accepted)e(by)g FJ(time.gmtime\(\))f FN(and)208 4507 y FJ(time.localtime\(\))p FN(,)17 b(otherwise)j(the)g(current)f (time)h(is)h(used.)208 4640 y(Optional)e FK(localtime)g FN(is)i(a)g(\003ag)f(that)g(when)g FJ(True)p FN(,)f(interprets)g FK(time)o(val)p FN(,)h(and)g(returns)f(a)h(date)g(relati)n(v)o(e)f(to)i (the)f(local)g(timezone)208 4739 y(instead)27 b(of)g(UTC,)h(properly)d (taking)h(daylight)g(sa)n(vings)i(time)f(into)g(account.)46 b(The)27 b(def)o(ault)f(is)j FJ(False)e FN(meaning)f(UTC)i(is)208 4839 y(used.)208 4972 y(Optional)19 b FK(use)m(gmt)i FN(is)g(a)f(\003ag)g(that)h(when)e FJ(True)p FN(,)h(outputs)f(a)h(date) g(string)g(with)g(the)g(timezone)f(as)i(an)f(ascii)h(string)f FJ(GMT)p FN(,)f(rather)208 5071 y(than)g(a)h(numeric)f FJ(-0000)p FN(.)24 b(This)c(is)h(needed)d(for)h(some)h(protocols)e (\(such)i(as)g(HTTP\).)f(This)h(only)f(applies)h(when)f FK(localtime)h FN(is)208 5171 y FJ(False)p FN(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)p 0 5225 1560 4 v 90 5281 a FB(3)120 5304 y FH(Note)d(that)i(the)f(sign)f(of)g(the)h(timezone)i(of) n(fset)e(is)f(the)h(opposite)h(of)e(the)h(sign)f(of)g(the)h Fz(time.timezone)d FH(v)n(ariable)19 b(for)d(the)h(same)g(timezone;)i (the)d(latter)j(v)n(ariable)0 5383 y(follo)n(ws)f(the)g(POSIX)e (standard)j(while)f(this)g(module)g(follo)n(ws)g(RFC)f(2822.)p 0 5549 3901 4 v 0 5649 a FI(208)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 209 221 TeXDict begin 209 220 bop 0 83 a FD(make_msgid)p FJ(\()p FC([)p FK(idstring)12 b FC(])p FJ(\))208 183 y FN(Returns)20 b(a)h(string)g(suitable)g(for)f(an)g(RFC)j(2822-compliant)17 b FO(Message-ID:)j FN(header)-5 b(.)26 b(Optional)20 b FK(idstring)g FN(if)h(gi)n(v)o(en,)f(is)i(a)f(string)208 282 y(used)e(to)i(strengthen)d(the)j(uniqueness)d(of)i(the)g(message)h (id.)0 429 y FD(decode_rfc2231)p FJ(\()p FK(s)p FJ(\))208 529 y FN(Decode)e(the)h(string)g FK(s)h FN(according)d(to)i(RFC)i (2231.)0 676 y FD(encode_rfc2231)p FJ(\()p FK(s)p FC([)p FK(,)c(c)o(har)o(set)q FC([)p FK(,)i(langua)o(g)o(e)12 b FC(])g(])p FJ(\))208 775 y FN(Encode)21 b(the)i(string)g FK(s)h FN(according)d(to)i(RFC)i(2231.)32 b(Optional)22 b FK(c)o(har)o(set)j FN(and)e FK(langua)o(g)o(e)p FN(,)e(if)i(gi)n(v)o (en)f(is)i(the)f(character)f(set)i(name)208 875 y(and)h(language)f (name)h(to)g(use.)42 b(If)26 b(neither)e(is)j(gi)n(v)o(en,)f FK(s)g FN(is)h(returned)d(as-is.)42 b(If)25 b FK(c)o(har)o(set)i FN(is)g(gi)n(v)o(en)d(b)n(ut)i FK(langua)o(g)o(e)d FN(is)k(not,)g(the) 208 975 y(string)19 b(is)j(encoded)c(using)i(the)g(empty)f(string)h (for)g FK(langua)o(g)o(e)p FN(.)0 1121 y FD(collapse_rfc2231_value)p FJ(\()p FK(value)p FC([)p FK(,)15 b(err)l(or)o(s)p FC([)p FK(,)21 b(fallbac)n(k)p 1963 1121 25 4 v 29 w(c)o(har)o(set)13 b FC(])f(])p FJ(\))208 1221 y FN(When)26 b(a)h(header)f(parameter)f(is) i(encoded)e(in)i(RFC)h(2231)d(format,)i FJ(Message.get_param\(\))d FN(may)i(return)g(a)h(3-tuple)208 1321 y(containing)19 b(the)j(character)e(set,)j(language,)d(and)h(v)n(alue.)28 b FJ(collapse_rfc2231_value\(\))18 b FN(turns)j(this)h(into)f(a)h (unicode)208 1420 y(string.)50 b(Optional)28 b FK(err)l(or)o(s)i FN(is)g(passed)f(to)g(the)g FK(err)l(or)o(s)h FN(ar)o(gument)d(of)h (the)h(b)n(uilt-in)f FJ(unicode\(\))g FN(function;)j(it)f(def)o(aults)e (to)208 1520 y FJ(replace)p FN(.)d(Optional)20 b FK(fallbac)n(k)p 1188 1520 V 29 w(c)o(har)o(set)i FN(speci\002es)f(the)g(character)f (set)h(to)g(use)g(if)g(the)g(one)f(in)h(the)g(RFC)h(2231)e(header)f(is) j(not)208 1620 y(kno)n(wn)c(by)i(Python;)f(it)i(def)o(aults)f(to)g FJ(us-ascii)p FN(.)208 1752 y(F)o(or)i(con)m(v)o(enience,)e(if)k(the)e FK(value)h FN(passed)g(to)g FJ(collapse_rfc2231_value\(\))c FN(is)k(not)g(a)g(tuple,)g(it)h(should)e(be)h(a)g(string)208 1852 y(and)c(it)i(is)g(returned)e(unquoted.)0 1999 y FD(decode_params)p FJ(\()p FK(par)o(ams)p FJ(\))208 2098 y FN(Decode)25 b(parameters)f(list)j(according)d(to)i(RFC)i(2231.)40 b FK(par)o(ams)26 b FN(is)h(a)f(sequence)f(of)g(2-tuples)g(containing)f (elements)i(of)g(the)208 2198 y(form)19 b FJ(\(content-type,)47 b(string-value\))p FN(.)0 2345 y(Changed)19 b(in)h(v)o(ersion)f(2.4:)h (The)g FJ(dump_address_pair\(\))d FN(function)h(has)j(been)e(remo)o(v)o (ed;)f(use)i FJ(formataddr\(\))f FN(instead.)0 2492 y(Changed)d(in)h(v) o(ersion)f(2.4:)g(The)h FJ(decode\(\))f FN(function)g(has)h(been)f (remo)o(v)o(ed;)g(use)h(the)g FJ(Header.decode_header\(\))d FN(method)0 2591 y(instead.)0 2738 y(Changed)k(in)h(v)o(ersion)e(2.4:)h (The)h FJ(encode\(\))f FN(function)f(has)i(been)f(remo)o(v)o(ed;)f(use) i(the)g FJ(Header.encode\(\))e FN(method)g(instead.)0 3023 y Fv(7.1.10)101 b(Iter)o(ators)0 3226 y FN(Iterating)23 b(o)o(v)o(er)f(a)i(message)g(object)f(tree)h(is)h(f)o(airly)e(easy)h (with)g(the)g FJ(Message.walk\(\))e FN(method.)34 b(The)24 b FJ(email.iterators)0 3326 y FN(module)19 b(pro)o(vides)f(some)i (useful)g(higher)f(le)n(v)o(el)h(iterations)f(o)o(v)o(er)g(message)h (object)g(trees.)0 3473 y FD(body_line_iterator)p FJ(\()p FK(msg)p FC([)p FK(,)d(decode)12 b FC(])p FJ(\))208 3572 y FN(This)22 b(iterates)g(o)o(v)o(er)e(all)i(the)g(payloads)f(in)h(all) g(the)g(subparts)f(of)h FK(msg)p FN(,)g(returning)e(the)h(string)h (payloads)e(line-by-line.)28 b(It)22 b(skips)208 3672 y(o)o(v)o(er)k(all)j(the)f(subpart)f(headers,)i(and)f(it)h(skips)f(o)o (v)o(er)f(an)o(y)g(subpart)g(with)h(a)h(payload)d(that)j(isn')o(t)e(a)i (Python)e(string.)48 b(This)29 b(is)208 3772 y(some)n(what)f(equi)n(v)n (alent)f(to)j(reading)d(the)j(\003at)g(te)o(xt)f(representation)e(of)i (the)g(message)g(from)f(a)i(\002le)f(using)g FJ(readline\(\))p FN(,)208 3871 y(skipping)18 b(o)o(v)o(er)h(all)i(the)f(interv)o(ening)e (headers.)208 4004 y(Optional)h FK(decode)g FN(is)i(passed)f(through)e (to)i FJ(Message.get_payload\(\))p FN(.)0 4151 y FD (typed_subpart_iterator)p FJ(\()p FK(msg)p FC([)p FK(,)c(maintype)p FC([)p FK(,)i(subtype)12 b FC(])g(])p FJ(\))208 4250 y FN(This)21 b(iterates)h(o)o(v)o(er)e(all)i(the)f(subparts)g(of)g FK(msg)p FN(,)h(returning)d(only)i(those)g(subparts)f(that)i(match)f (the)g(MIME)g(type)g(speci\002ed)g(by)208 4350 y FK(maintype)e FN(and)g FK(subtype)p FN(.)208 4483 y(Note)25 b(that)g FK(subtype)g FN(is)h(optional;)g(if)g(omitted,)f(then)g(subpart)f(MIME) h(type)g(matching)f(is)i(done)e(only)h(with)g(the)g(main)g(type.)208 4583 y FK(maintype)19 b FN(is)i(optional)e(too;)h(it)h(def)o(aults)e (to)i FO(te)n(xt)p FN(.)208 4715 y(Thus,)e(by)h(def)o(ault)f FJ(typed_subpart_iterator\(\))e FN(returns)i(each)h(subpart)f(that)h (has)h(a)f(MIME)g(type)g(of)g FO(te)n(xt/*)p FN(.)0 4862 y(The)j(follo)n(wing)e(function)g(has)i(been)f(added)g(as)i(a)f(useful) g(deb)n(ugging)d(tool.)33 b(It)23 b(should)f FK(not)g FN(be)h(considered)e(part)i(of)g(the)g(supported)0 4962 y(public)c(interf)o(ace)h(for)f(the)h(package.)0 5109 y FD(_structure)p FJ(\()p FK(msg)p FC([)p FK(,)e(fp)p FC([)p FK(,)i(le)o(vel)12 b FC(])g(])p FJ(\))208 5208 y FN(Prints)20 b(an)g(indented)f(representation)f(of)i(the)g(content)f (types)h(of)g(the)g(message)g(object)g(structure.)k(F)o(or)c(e)o (xample:)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(209)p eop end %%Page: 210 222 TeXDict begin 210 221 bop 444 174 a FA(>>>)44 b(msg)g(=)h (email.message_from_file\(somefile\))444 266 y(>>>)f(_structure\(msg\)) 444 357 y(multipart/mixed)623 448 y(text/plain)623 540 y(text/plain)623 631 y(multipart/digest)802 722 y(message/rfc822)982 814 y(text/plain)802 905 y(message/rfc822)982 996 y(text/plain)802 1088 y(message/rfc822)982 1179 y(text/plain)802 1270 y(message/rfc822)982 1362 y(text/plain)802 1453 y(message/rfc822)982 1544 y(text/plain)623 1636 y(text/plain)208 1825 y FN(Optional)21 b FK(fp)h FN(is)g(a)h(\002le-lik)o(e)e(object)h(to)g(print)f(the)h (output)e(to.)30 b(It)22 b(must)g(be)g(suitable)g(for)f(Python')-5 b(s)21 b(e)o(xtended)f(print)h(statement.)208 1925 y FK(le)o(vel)f FN(is)h(used)f(internally)-5 b(.)0 2210 y Fv(7.1.11)101 b(P)l(ac)n(kage)29 b(Histor)s(y)0 2413 y FN(This)21 b(table)g(describes)f(the)h(release)g(history)f(of)g(the)h (email)g(package,)e(corresponding)f(to)j(the)f(v)o(ersion)g(of)h (Python)e(that)i(the)g(package)0 2512 y(w)o(as)k(released)f(with.)37 b(F)o(or)23 b(purposes)g(of)h(this)h(document,)e(when)g(you)g(see)i(a)g (note)e(about)g(change)g(or)h(added)f(v)o(ersions,)h(these)g(refer)0 2612 y(to)i(the)f(Python)f(v)o(ersion)g(the)i(change)e(w)o(as)i(made)f (in,)h FK(not)f FN(the)h(email)f(package)f(v)o(ersion.)39 b(This)26 b(table)f(also)g(describes)g(the)h(Python)0 2712 y(compatibility)19 b(of)h(each)f(v)o(ersion)g(of)h(the)g(package.) 783 2938 y FL(email)h(v)o(ersion)p 1303 2968 4 100 v 99 w(distrib)n(uted)g(with)p 2393 2968 V 521 w(compatible)f(with)p 733 2971 2434 4 v 783 3041 a FJ(1.x)p 1303 3071 4 100 v 422 w FN(Python)f(2.2.0)f(to)j(Python)e(2.2.1)p 2393 3071 V 137 w FK(no)h(long)o(er)g(supported)783 3140 y FJ(2.5)p 1303 3170 V 422 w FN(Python)f(2.2.2+)f(and)i(Python)f(2.3)p 2393 3170 V 98 w(Python)g(2.1)h(to)g(2.5)783 3240 y FJ(3.0)p 1303 3270 V 422 w FN(Python)f(2.4)p 2393 3270 V 728 w(Python)g(2.3)h (to)g(2.5)783 3340 y FJ(4.0)p 1303 3370 V 422 w FN(Python)f(2.5)p 2393 3370 V 728 w(Python)g(2.3)h(to)g(2.5)0 3565 y(Here)g(are)g(the)g (major)g(dif)n(ferences)e(between)i FJ(email)g FN(v)o(ersion)e(4)j(and) e(v)o(ersion)g(3:)125 3795 y FM(\017)41 b FN(All)k(modules)g(ha)n(v)o (e)f(been)h(renamed)e(according)g(to)j(PEP)g(8)f(standards.)99 b(F)o(or)45 b(e)o(xample,)50 b(the)45 b(v)o(ersion)f(3)h(module)208 3894 y FJ(email.Message)18 b FN(w)o(as)j(renamed)e(to)h FJ(email.message)e FN(in)j(v)o(ersion)d(4.)125 4060 y FM(\017)41 b FN(A)29 b(ne)n(w)h(subpackage)d FJ(email.mime)h FN(w)o(as)i(added)e(and)h(all)h(the)f(v)o(ersion)f(3)i FJ(email.MIME)3034 4075 y(*)3112 4060 y FN(modules)e(were)h(renamed)208 4160 y(and)21 b(situated)h(into)f(the)h FJ(email.mime)f FN(subpackage.)28 b(F)o(or)22 b(e)o(xample,)f(the)h(v)o(ersion)e(3)i (module)f FJ(email.MIMEText)f FN(w)o(as)208 4260 y(renamed)e(to)i FJ(email.mime.text)p FN(.)208 4392 y FK(Note)g(that)g(the)g(ver)o(sion) h(3)f(names)g(will)h(continue)e(to)h(work)h(until)f(Python)f(2.6)p FN(.)125 4558 y FM(\017)41 b FN(The)19 b FJ(email.mime.application)e FN(module)i(w)o(as)i(added,)e(which)g(contains)h(the)g FJ(MIMEApplication)e FN(class.)125 4724 y FM(\017)41 b FN(Methods)24 b(that)i(were)f(deprecated)f(in)h(v)o(ersion)g(3)g(ha)n (v)o(e)g(been)g(remo)o(v)o(ed.)38 b(These)26 b(include)e FJ(Generator.__call__\(\))p FN(,)208 4824 y FJ(Message.get_type\(\))p FN(,)17 b FJ(Message.get_main_type\(\))p FN(,)f FJ (Message.get_subtype\(\))p FN(.)125 4990 y FM(\017)41 b FN(Fix)o(es)18 b(ha)n(v)o(e)g(been)f(added)g(for)h(RFC)h(2231)e (support)g(which)h(can)g(change)f(some)h(of)g(the)g(return)f(types)h (for)f FJ(Message.get_-)208 5090 y(param\(\))26 b FN(and)h(friends.)45 b(Under)26 b(some)h(circumstances,)h(v)n(alues)f(which)g(used)g(to)g (return)f(a)i(3-tuple)e(no)n(w)h(return)f(simple)208 5189 y(strings)c(\(speci\002cally)-5 b(,)21 b(if)h(all)g(e)o(xtended)e (parameter)h(se)o(gments)g(were)h(unencoded,)d(there)j(is)h(no)e (language)g(and)g(charset)h(des-)208 5289 y(ignation)15 b(e)o(xpected,)h(so)h(the)g(return)f(type)g(is)i(no)n(w)f(a)g(simple)g (string\).)23 b(Also,)18 b(\045-decoding)c(used)j(to)g(be)g(done)f(for) g(both)g(encoded)208 5389 y(and)j(unencoded)f(se)o(gments;)h(this)i (decoding)d(is)j(no)n(w)f(done)f(only)g(for)h(encoded)e(se)o(gments.)p 0 5549 3901 4 v 0 5649 a FI(210)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 211 223 TeXDict begin 211 222 bop 0 83 a FN(Here)20 b(are)g(the)g(major)g(dif)n (ferences)e(between)i FJ(email)g FN(v)o(ersion)e(3)j(and)e(v)o(ersion)g (2:)125 277 y FM(\017)41 b FN(The)51 b FJ(FeedParser)f FN(class)i(w)o(as)h(introduced,)j(and)51 b(the)h FJ(Parser)f FN(class)h(w)o(as)h(implemented)c(in)j(terms)f(of)h(the)208 377 y FJ(FeedParser)p FN(.)c(All)29 b(parsing)f(therefore)f(is)i (non-strict,)g(and)f(parsing)g(will)h(mak)o(e)f(a)h(best)g(ef)n(fort)e (ne)n(v)o(er)g(to)i(raise)g(an)f(e)o(x-)208 477 y(ception.)23 b(Problems)d(found)e(while)j(parsing)e(messages)h(are)g(stored)g(in)g (the)g(message')-5 b(s)21 b FK(defect)g FN(attrib)n(ute.)125 628 y FM(\017)41 b FN(All)57 b(aspects)g(of)f(the)h(API)g(which)f (raised)g FJ(DeprecationWarning)p FN(s)e(in)j(v)o(ersion)f(2)g(ha)n(v)o (e)g(been)g(remo)o(v)o(ed.)208 728 y(These)42 b(include)f(the)p 885 728 25 4 v 72 w FK(encoder)i FN(ar)o(gument)d(to)j(the)f FJ(MIMEText)f FN(constructor)m(,)46 b(the)c FJ(Message.add_payload\(\)) 208 828 y FN(method,)57 b(the)51 b FJ(Utils.dump_address_pair\(\))d FN(function,)57 b(and)51 b(the)g(functions)f FJ(Utils.decode\(\))f FN(and)208 927 y FJ(Utils.encode\(\))p FN(.)125 1079 y FM(\017)41 b FN(Ne)n(w)j FJ(DeprecationWarning)p FN(s)e(ha)n(v)o(e)h (been)h(added)e(to:)74 b FJ(Generator.__call__\(\))p FN(,)46 b FJ(Message.get_-)208 1179 y(type\(\))p FN(,)33 b FJ(Message.get_main_type\(\))p FN(,)e FJ(Message.get_subtype\(\))p FN(,)g(and)h(the)g FK(strict)i FN(ar)o(gument)c(to)i(the)208 1278 y FJ(Parser)19 b FN(class.)26 b(These)20 b(are)g(e)o(xpected)f(to) h(be)g(remo)o(v)o(ed)e(in)i(future)f(v)o(ersions.)125 1430 y FM(\017)41 b FN(Support)18 b(for)i(Pythons)f(earlier)h(than)g (2.3)f(has)i(been)e(remo)o(v)o(ed.)0 1625 y(Here)h(are)g(the)g(dif)n (ferences)f(between)g FJ(email)h FN(v)o(ersion)f(2)h(and)g(v)o(ersion)f (1:)125 1819 y FM(\017)41 b FN(The)19 b FJ(email.Header)g FN(and)h FJ(email.Charset)e FN(modules)h(ha)n(v)o(e)h(been)f(added.)125 1971 y FM(\017)41 b FN(The)21 b(pickle)h(format)f(for)g FJ(Message)g FN(instances)h(has)h(changed.)28 b(Since)22 b(this)h(w)o(as)g(ne)n(v)o(er)e(\(and)g(still)i(isn')o(t\))e(formally)g (de\002ned,)208 2070 y(this)g(isn')o(t)h(considered)d(a)j(backw)o(ard)e (incompatibility)-5 b(.)26 b(Ho)n(we)n(v)o(er)20 b(if)h(your)f (application)g(pickles)h(and)g(unpickles)f FJ(Message)208 2170 y FN(instances,)33 b(be)f(a)o(w)o(are)f(that)g(in)g FJ(email)g FN(v)o(ersion)f(2,)k FJ(Message)d FN(instances)g(no)n(w)g (ha)n(v)o(e)g(pri)n(v)n(ate)f(v)n(ariables)p 3479 2170 V 60 w FK(c)o(har)o(set)j FN(and)p 208 2270 V 232 2270 a FK(default)p 469 2270 V 29 w(type)p FN(.)125 2422 y FM(\017)41 b FN(Se)n(v)o(eral)26 b(methods)h(in)h(the)f FJ(Message)g FN(class)i(ha)n(v)o(e)e(been)g(deprecated,)g(or)g(their)h (signatures)e(changed.)46 b(Also,)29 b(man)o(y)e(ne)n(w)208 2521 y(methods)c(ha)n(v)o(e)h(been)g(added.)36 b(See)25 b(the)g(documentation)c(for)j(the)g FJ(Message)g FN(class)i(for)d (details.)39 b(The)24 b(changes)f(should)h(be)208 2621 y(completely)18 b(backw)o(ard)h(compatible.)125 2773 y FM(\017)41 b FN(The)28 b(object)g(structure)g(has)i(changed)d(in)i (the)g(f)o(ace)f(of)h FO(message/rfc822)e FN(content)h(types.)51 b(In)28 b FJ(email)h FN(v)o(ersion)f(1,)j(such)d(a)208 2872 y(type)19 b(w)o(ould)f(be)i(represented)d(by)i(a)h(scalar)g (payload,)d(i.e.)25 b(the)20 b(container)e(message')-5 b(s)19 b FJ(is_multipart\(\))f FN(returned)f(f)o(alse,)208 2972 y FJ(get_payload\(\))h FN(w)o(as)j(not)f(a)g(list)i(object,)d(b)n (ut)h(a)h(single)f FJ(Message)f FN(instance.)208 3098 y(This)27 b(structure)f(w)o(as)j(inconsistent)d(with)i(the)f(rest)h(of) f(the)g(package,)h(so)f(the)h(object)f(representation)e(for)h FO(message/rfc822)208 3197 y FN(content)e(types)i(w)o(as)g(changed.)39 b(In)26 b FJ(email)f FN(v)o(ersion)f(2,)j(the)f(container)e FK(does)h FN(return)g FJ(True)g FN(from)g FJ(is_multipart\(\))p FN(,)208 3297 y(and)19 b FJ(get_payload\(\))g FN(returns)g(a)h(list)i (containing)c(a)j(single)f FJ(Message)f FN(item.)208 3423 y(Note)h(that)g(this)h(is)g(one)f(place)g(that)h(backw)o(ard)d (compatibility)h(could)h(not)g(be)g(completely)f(maintained.)24 b(Ho)n(we)n(v)o(er)m(,)18 b(if)i(you')l(re)208 3522 y(already)e (testing)i(the)g(return)f(type)h(of)g FJ(get_payload\(\))p FN(,)e(you)h(should)g(be)h(\002ne.)25 b(Y)-9 b(ou)19 b(just)i(need)e(to)h(mak)o(e)g(sure)f(your)g(code)208 3622 y(doesn')o(t)13 b(do)i(a)h FJ(set_payload\(\))e FN(with)h(a)h FJ(Message)f FN(instance)g(on)f(a)i(container)e(with)i(a) f(content)g(type)g(of)g FO(message/rfc822)p FN(.)125 3774 y FM(\017)41 b FN(The)24 b FJ(Parser)g FN(constructor')-5 b(s)24 b FK(strict)j FN(ar)o(gument)c(w)o(as)i(added,)g(and)f(its)i FJ(parse\(\))e FN(and)h FJ(parsestr\(\))e FN(methods)h(gre)n(w)g(a)208 3873 y FK(header)o(sonly)i FN(ar)o(gument.)45 b(The)27 b FK(strict)j FN(\003ag)e(w)o(as)g(also)g(added)f(to)g(functions)g FJ(email.message_from_file\(\))c FN(and)208 3973 y FJ (email.message_from_string\(\))p FN(.)125 4125 y FM(\017)41 b FJ(Generator.__call__\(\))20 b FN(is)k(deprecated;)g(use)g FJ(Generator.flatten\(\))c FN(instead.)35 b(The)23 b FJ(Generator)g FN(class)208 4224 y(has)d(also)g(gro)n(wn)f(the)h FJ(clone\(\))g FN(method.)125 4376 y FM(\017)41 b FN(The)19 b FJ(DecodedGenerator)f FN(class)j(in)g(the)f FJ(email.Generator)e FN(module)h(w)o(as)i(added.)125 4528 y FM(\017)41 b FN(The)18 b(intermediate)f(base)i(classes)g FJ(MIMENonMultipart)d FN(and)i FJ(MIMEMultipart)f FN(ha)n(v)o(e)h(been)g(added,)f(and)h (interposed)208 4628 y(in)i(the)g(class)h(hierarchy)d(for)i(most)g(of)g (the)g(other)f(MIME-related)g(deri)n(v)o(ed)f(classes.)125 4779 y FM(\017)41 b FN(The)p 365 4779 V 52 w FK(encoder)23 b FN(ar)o(gument)e(to)i(the)f FJ(MIMEText)g FN(constructor)f(has)i (been)f(deprecated.)30 b(Encoding)21 b(no)n(w)h(happens)f(implicitly) 208 4879 y(based)e(on)h(the)p 648 4879 V 50 w FK(c)o(har)o(set)i FN(ar)o(gument.)125 5031 y FM(\017)41 b FN(The)24 b(follo)n(wing)f (functions)g(in)h(the)h FJ(email.Utils)e FN(module)g(ha)n(v)o(e)h(been) g(deprecated:)32 b FJ(dump_address_pairs\(\))p FN(,)208 5131 y FJ(decode\(\))p FN(,)f(and)e FJ(encode\(\))p FN(.)54 b(The)30 b(follo)n(wing)e(functions)h(ha)n(v)o(e)g(been)h(added)f(to)h (the)g(module:)43 b FJ(make_msgid\(\))p FN(,)208 5230 y FJ(decode_rfc2231\(\))p FN(,)17 b FJ(encode_rfc2231\(\))p FN(,)h(and)h FJ(decode_params\(\))p FN(.)125 5382 y FM(\017)41 b FN(The)19 b(non-public)f(function)g FJ (email.Iterators._structure\(\))e FN(w)o(as)21 b(added.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h (email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(211)p eop end %%Page: 212 224 TeXDict begin 212 223 bop 0 83 a Fv(7.1.12)101 b(Diff)m(erences)28 b(from)g Fm(mimelib)0 286 y FN(The)16 b FJ(email)g FN(package)f(w)o(as) j(originally)d(prototyped)e(as)18 b(a)e(separate)g(library)g(called)g FJ(mimelib)p FN(.)23 b(Changes)16 b(ha)n(v)o(e)g(been)g(made)g(so)g (that)0 386 y(method)j(names)g(are)h(more)f(consistent,)h(and)f(some)h (methods)f(or)h(modules)f(ha)n(v)o(e)g(either)h(been)f(added)g(or)g (remo)o(v)o(ed.)k(The)d(semantics)0 485 y(of)e(some)g(of)g(the)g (methods)f(ha)n(v)o(e)h(also)g(changed.)23 b(F)o(or)18 b(the)g(most)g(part,)g(an)o(y)g(functionality)e(a)n(v)n(ailable)i(in)g FJ(mimelib)f FN(is)j(still)f(a)n(v)n(ailable)0 585 y(in)24 b(the)g FJ(email)f FN(package,)g(albeit)h(often)f(in)h(a)g(dif)n (ferent)e(w)o(ay)-5 b(.)35 b(Backw)o(ard)23 b(compatibility)f(between)h (the)h FJ(mimelib)f FN(package)f(and)0 684 y(the)e FJ(email)g FN(package)f(w)o(as)i(not)f(a)g(priority)-5 b(.)0 831 y(Here)26 b(is)h(a)g(brief)f(description)e(of)i(the)h(dif)n(ferences)d (between)i(the)g FJ(mimelib)g FN(and)f(the)i FJ(email)f FN(packages,)g(along)f(with)i(hints)f(on)0 931 y(ho)n(w)20 b(to)g(port)f(your)g(applications.)0 1078 y(Of)e(course,)g(the)g(most)h (visible)f(dif)n(ference)e(between)i(the)g(tw)o(o)g(packages)f(is)i (that)g(the)f(package)f(name)g(has)i(been)e(changed)g(to)h FJ(email)p FN(.)0 1177 y(In)j(addition,)f(the)h(top-le)n(v)o(el)e (package)h(has)i(the)f(follo)n(wing)e(dif)n(ferences:)125 1407 y FM(\017)41 b FJ(messageFromString\(\))17 b FN(has)j(been)g (renamed)e(to)j FJ(message_from_string\(\))p FN(.)125 1573 y FM(\017)41 b FJ(messageFromFile\(\))17 b FN(has)k(been)e (renamed)g(to)h FJ(message_from_file\(\))p FN(.)0 1803 y(The)g FJ(Message)f FN(class)i(has)g(the)f(follo)n(wing)f(dif)n (ferences:)125 2033 y FM(\017)41 b FN(The)19 b(method)g FJ(asString\(\))g FN(w)o(as)i(renamed)e(to)h FJ(as_string\(\))p FN(.)125 2199 y FM(\017)41 b FN(The)19 b(method)g FJ(ismultipart\(\))g FN(w)o(as)i(renamed)d(to)j FJ(is_multipart\(\))p FN(.)125 2365 y FM(\017)41 b FN(The)19 b FJ(get_payload\(\))g FN(method)g(has)h(gro)n(wn)f(a)h FK(decode)f FN(optional)g(ar)o (gument.)125 2531 y FM(\017)41 b FN(The)19 b(method)g FJ(getall\(\))g FN(w)o(as)j(renamed)c(to)i FJ(get_all\(\))p FN(.)125 2697 y FM(\017)41 b FN(The)19 b(method)g FJ(addheader\(\))g FN(w)o(as)i(renamed)e(to)h FJ(add_header\(\))p FN(.)125 2863 y FM(\017)41 b FN(The)19 b(method)g FJ(gettype\(\))g FN(w)o(as)i(renamed)e(to)h FJ(get_type\(\))p FN(.)125 3029 y FM(\017)41 b FN(The)19 b(method)g FJ(getmaintype\(\))g FN(w)o(as)i(renamed)d(to)j FJ(get_main_type\(\))p FN(.)125 3195 y FM(\017)41 b FN(The)19 b(method)g FJ(getsubtype\(\))g FN(w)o(as)i(renamed)d(to)j FJ(get_subtype\(\))p FN(.)125 3362 y FM(\017)41 b FN(The)20 b(method)f FJ(getparams\(\))f FN(w)o(as)k(renamed)c(to)j FJ(get_params\(\))p FN(.)j(Also,)c(whereas)g FJ(getparams\(\))f FN(returned)g(a)h(list)208 3461 y(of)g(strings,)h FJ(get_params\(\))e FN(returns)h(a)i(list)g(of)e(2-tuples,)g(ef)n (fecti)n(v)o(ely)f(the)i(k)o(e)o(y/v)n(alue)e(pairs)i(of)g(the)g (parameters,)e(split)j(on)208 3561 y(the)e(`)p FJ(=)p FN(')g(sign.)125 3727 y FM(\017)41 b FN(The)19 b(method)g FJ(getparam\(\))g FN(w)o(as)i(renamed)e(to)h FJ(get_param\(\))p FN(.)125 3893 y FM(\017)41 b FN(The)19 b(method)g FJ(getcharsets\(\))g FN(w)o(as)i(renamed)d(to)j FJ(get_charsets\(\))p FN(.)125 4059 y FM(\017)41 b FN(The)19 b(method)g FJ(getfilename\(\))g FN(w)o(as)i(renamed)d(to)j FJ(get_filename\(\))p FN(.)125 4225 y FM(\017)41 b FN(The)19 b(method)g FJ(getboundary\(\))g FN(w)o(as)i(renamed)d(to)j FJ(get_boundary\(\))p FN(.)125 4391 y FM(\017)41 b FN(The)19 b(method)g FJ(setboundary\(\))g FN(w)o(as)i(renamed)d(to)j FJ(set_boundary\(\))p FN(.)125 4557 y FM(\017)41 b FN(The)29 b(method)e FJ(getdecodedpayload\(\))g FN(w)o(as)j(remo)o(v)o(ed.)50 b(T)-7 b(o)29 b(get)h(similar)f (functionality)-5 b(,)29 b(pass)h(the)f(v)n(alue)g(1)g(to)h(the)208 4657 y FK(decode)18 b FN(\003ag)j(of)f(the)g(get)p 928 4657 25 4 v 29 w(payload\(\))e(method.)125 4823 y FM(\017)41 b FN(The)64 b(method)f FJ(getpayloadastext\(\))f FN(w)o(as)j(remo)o(v)o (ed.)155 b(Similar)65 b(functionality)d(is)k(supported)c(by)j(the)208 4922 y FJ(DecodedGenerator)17 b FN(class)k(in)g(the)f FJ(email.generator)e FN(module.)125 5088 y FM(\017)41 b FN(The)20 b(method)g FJ(getbodyastext\(\))f FN(w)o(as)i(remo)o(v)o (ed.)k(Y)-9 b(ou)21 b(can)g(get)g(similar)g(functionality)e(by)h (creating)g(an)h(iterator)f(with)208 5188 y FJ (typed_subpart_iterator\(\))c FN(in)k(the)g FJ(email.iterators)e FN(module.)p 0 5549 3901 4 v 0 5649 a FI(212)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 213 225 TeXDict begin 213 224 bop 0 83 a FN(The)34 b FJ(Parser)f FN(class)i(has)f(no)g(dif)n(ferences)e(in)j(its)g(public)e(interf)o (ace.)66 b(It)34 b(does)g(ha)n(v)o(e)f(some)h(additional)f(smarts)h(to) g(recognize)0 183 y FO(message/deliv)n(er)r(y-status)25 b FN(type)h(messages,)j(which)d(it)i(represents)e(as)i(a)g FJ(Message)e FN(instance)h(containing)e(separate)h FJ(Message)0 282 y FN(subparts)19 b(for)h(each)g(header)f(block)g(in)h(the)h(deli)n (v)o(ery)d(status)j(noti\002cation)2122 252 y FF(4)2153 282 y FN(.)0 429 y(The)j FJ(Generator)g FN(class)i(has)e(no)h(dif)n (ferences)e(in)i(its)g(public)f(interf)o(ace.)38 b(There)23 b(is)j(a)f(ne)n(w)g(class)g(in)g(the)g FJ(email.generator)0 529 y FN(module)g(though,)h(called)g FJ(DecodedGenerator)d FN(which)j(pro)o(vides)f(most)h(of)g(the)g(functionality)e(pre)n (viously)g(a)n(v)n(ailable)i(in)h(the)0 628 y FJ (Message.getpayloadastext\(\))16 b FN(method.)0 775 y(The)k(follo)n (wing)e(modules)i(and)f(classes)i(ha)n(v)o(e)f(been)g(changed:)125 1003 y FM(\017)41 b FN(The)26 b FJ(MIMEBase)g FN(class)h(constructor)e (ar)o(guments)p 1755 1003 25 4 v 54 w FK(major)k FN(and)p 2160 1003 V 56 w FK(minor)f FN(ha)n(v)o(e)e(changed)f(to)p 2994 1003 V 57 w FK(maintype)g FN(and)p 3502 1003 V 56 w FK(subtype)h FN(re-)208 1103 y(specti)n(v)o(ely)-5 b(.)125 1268 y FM(\017)41 b FN(The)27 b FJ(Image)h FN(class/module)f (has)h(been)f(renamed)f(to)i FJ(MIMEImage)p FN(.)47 b(The)p 2517 1268 V 58 w FK(minor)29 b FN(ar)o(gument)d(has)i(been)f(renamed)f (to)p 3847 1268 V 58 w FK(-)208 1368 y(subtype)p FN(.)125 1533 y FM(\017)41 b FN(The)18 b FJ(Text)h FN(class/module)f(has)i(been) e(renamed)f(to)j FJ(MIMEText)p FN(.)j(The)p 2323 1533 V 49 w FK(minor)e FN(ar)o(gument)16 b(has)k(been)e(renamed)g(to)p 3601 1533 V 49 w FK(subtype)p FN(.)125 1698 y FM(\017)41 b FN(The)28 b FJ(MessageRFC822)f FN(class/module)h(has)i(been)e (renamed)f(to)j FJ(MIMEMessage)p FN(.)49 b(Note)29 b(that)h(an)e (earlier)h(v)o(ersion)f(of)208 1798 y FJ(mimelib)17 b FN(called)h(this)g(class/module)f FJ(RFC822)p FN(,)h(b)n(ut)g(that)g (clashed)f(with)h(the)g(Python)f(standard)g(library)g(module)f FJ(rfc822)208 1898 y FN(on)j(some)h(case-insensiti)n(v)o(e)f(\002le)i (systems.)208 2030 y(Also,)i(the)g FJ(MIMEMessage)e FN(class)j(no)n(w)e (represents)g(an)o(y)g(kind)f(of)i(MIME)f(message)h(with)g(main)f(type) g FO(message)p FN(.)32 b(It)23 b(tak)o(es)208 2130 y(an)d(optional)f (ar)o(gument)p 937 2130 V 47 w FK(subtype)h FN(which)f(is)i(used)f(to)h (set)g(the)f(MIME)g(subtype.)p 2586 2130 V 53 w FK(subtype)g FN(def)o(aults)g(to)g FO(rfc822)p FN(.)0 2358 y FJ(mimelib)28 b FN(pro)o(vided)f(some)i(utility)g(functions)e(in)i(its)i FJ(address)d FN(and)g FJ(date)h FN(modules.)51 b(All)29 b(of)g(these)g(functions)f(ha)n(v)o(e)g(been)0 2457 y(mo)o(v)o(ed)18 b(to)j(the)f FJ(email.utils)f FN(module.)0 2604 y(The)i FJ(MsgReader)f FN(class/module)g(has)i(been)e(remo)o(v)o(ed.)26 b(Its)c(functionality)d(is)j(most)f(closely)g(supported)e(in)j(the)f FJ(body_line_-)0 2704 y(iterator\(\))e FN(function)f(in)j(the)f FJ(email.iterators)e FN(module.)0 2988 y Fv(7.1.13)101 b(Examples)0 3191 y FN(Here)20 b(are)f(a)h(fe)n(w)g(e)o(xamples)e(of)i (ho)n(w)f(to)h(use)f(the)h FJ(email)f FN(package)f(to)i(read,)f(write,) h(and)f(send)g(simple)h(email)g(messages,)f(as)i(well)f(as)0 3291 y(more)f(comple)o(x)g(MIME)h(messages.)0 3438 y(First,)h(let')-5 b(s)21 b(see)g(ho)n(w)e(to)i(create)f(and)f(send)h(a)h(simple)f(te)o (xt)g(message:)236 3625 y FA(#)45 b(Import)f(smtplib)f(for)i(the)f (actual)g(sending)f(function)236 3716 y(import)h(smtplib)236 3899 y(#)h(Import)f(the)g(email)g(modules)g(we'll)g(need)236 3990 y(from)g(email.mime.text)f(import)h(MIMEText)236 4173 y(#)h(Open)f(a)h(plain)f(text)g(file)g(for)g(reading.)89 b(For)44 b(this)g(example,)g(assume)f(that)236 4264 y(#)i(the)f(text)g (file)h(contains)e(only)h(ASCII)g(characters.)236 4355 y(fp)h(=)f(open\(textfile,)f('rb'\))236 4447 y(#)i(Create)f(a)g (text/plain)g(message)236 4538 y(msg)h(=)f(MIMEText\(fp.read\(\)\))236 4629 y(fp.close\(\))236 4812 y(#)h(me)f(==)h(the)f(sender's)g(email)g (address)236 4903 y(#)h(you)f(==)h(the)f(recipient's)f(email)h(address) 236 4995 y(msg['Subject'])f(=)h('The)h(contents)e(of)i(\045s')f(\045)g (textfile)236 5086 y(msg['From'])f(=)i(me)236 5177 y(msg['To'])f(=)g (you)p 0 5321 1560 4 v 90 5377 a FB(4)120 5400 y FH(Deli)n(v)o(ery)19 b(Status)f(Noti\002cations)i(\(DSN\))c(are)i(de\002ned)g(in)f(RFC)h (1894.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n(kage)1797 b(213)p eop end %%Page: 214 226 TeXDict begin 214 225 bop 236 83 a FA(#)45 b(Send)f(the)g(message)g (via)g(our)h(own)f(SMTP)g(server,)g(but)g(don't)g(include)g(the)236 174 y(#)h(envelope)e(header.)236 266 y(s)i(=)g(smtplib.SMTP\(\))236 357 y(s.connect\(\))236 448 y(s.sendmail\(me,)e([you],)h (msg.as_string\(\)\))236 540 y(s.close\(\))0 736 y FN(Here')-5 b(s)24 b(an)f(e)o(xample)f(of)h(ho)n(w)g(to)g(send)g(a)h(MIME)f (message)g(containing)f(a)i(b)n(unch)e(of)h(f)o(amily)g(pictures)g (that)g(may)g(be)g(residing)g(in)g(a)0 836 y(directory:)236 1024 y FA(#)45 b(Import)f(smtplib)f(for)i(the)f(actual)g(sending)f (function)236 1116 y(import)h(smtplib)236 1298 y(#)h(Here)f(are)g(the)h (email)f(package)f(modules)h(we'll)g(need)236 1390 y(from)g (email.mime.image)f(import)g(MIMEImage)236 1481 y(from)h (email.mime.multipart)e(import)i(MIMEMultipart)236 1664 y(COMMASPACE)f(=)i(',)g(')236 1846 y(#)g(Create)f(the)g(container)f (\(outer\))h(email)g(message.)236 1938 y(msg)h(=)f(MIMEMultipart\(\)) 236 2029 y(msg['Subject'])f(=)h('Our)h(family)e(reunion')236 2120 y(#)i(me)f(==)h(the)f(sender's)g(email)g(address)236 2212 y(#)h(family)f(=)g(the)h(list)f(of)g(all)h(recipients')e(email)h (addresses)236 2303 y(msg['From'])f(=)i(me)236 2394 y(msg['To'])f(=)g (COMMASPACE.join\(family\))236 2486 y(msg.preamble)f(=)i('Our)f(family) g(reunion')236 2668 y(#)h(Assume)f(we)g(know)g(that)h(the)f(image)g (files)g(are)g(all)g(in)h(PNG)f(format)236 2759 y(for)h(file)f(in)g (pngfiles:)416 2851 y(#)g(Open)g(the)h(files)f(in)g(binary)g(mode.)89 b(Let)44 b(the)g(MIMEImage)g(class)g(automatically)416 2942 y(#)g(guess)g(the)h(specific)e(image)h(type.)416 3033 y(fp)g(=)h(open\(file,)e('rb'\))416 3125 y(img)h(=)h (MIMEImage\(fp.read\(\)\))416 3216 y(fp.close\(\))416 3307 y(msg.attach\(img\))236 3490 y(#)g(Send)f(the)g(email)g(via)h(our) f(own)g(SMTP)h(server.)236 3581 y(s)g(=)g(smtplib.SMTP\(\))236 3673 y(s.connect\(\))236 3764 y(s.sendmail\(me,)e(family,)g (msg.as_string\(\)\))236 3855 y(s.close\(\))0 4052 y FN(Here')-5 b(s)20 b(an)h(e)o(xample)d(of)i(ho)n(w)g(to)g(send)g(the)g (entire)g(contents)g(of)g(a)g(directory)f(as)i(an)f(email)g(message:) 2969 4022 y FF(5)236 4240 y FA(#!/usr/bin/env)43 b(python)236 4423 y("""Send)h(the)g(contents)g(of)g(a)h(directory)e(as)i(a)f(MIME)g (message.""")236 4606 y(import)g(os)236 4697 y(import)g(sys)236 4788 y(import)g(smtplib)236 4880 y(#)h(For)f(guessing)g(MIME)g(type)g (based)g(on)h(file)f(name)g(extension)236 4971 y(import)g(mimetypes)236 5154 y(from)g(optparse)g(import)g(OptionParser)p 0 5298 1560 4 v 90 5354 a FB(5)120 5377 y FH(Thanks)17 b(to)g(Matthe)n(w)i (Dixon)f(Co)n(wles)g(for)f(the)h(original)h(inspiration)h(and)d(e)o (xamples.)p 0 5549 3901 4 v 0 5649 a FI(214)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 215 227 TeXDict begin 215 226 bop 236 83 a FA(from)44 b(email)g(import)g (encoders)236 174 y(from)g(email.message)f(import)h(Message)236 266 y(from)g(email.mime.audio)f(import)g(MIMEAudio)236 357 y(from)h(email.mime.base)f(import)h(MIMEBase)236 448 y(from)g(email.mime.image)f(import)g(MIMEImage)236 540 y(from)h(email.mime.multipart)e(import)i(MIMEMultipart)236 631 y(from)g(email.mime.text)f(import)h(MIMEText)236 814 y(COMMASPACE)f(=)i(',)g(')236 1088 y(def)g(main\(\):)416 1179 y(parser)e(=)i(OptionParser\(usage="""\\)236 1270 y(Send)f(the)h(contents)e(of)i(a)f(directory)g(as)g(a)h(MIME)f (message.)236 1453 y(Usage:)g(\045prog)g([options])236 1636 y(Unless)g(the)g(-o)h(option)f(is)g(given,)g(the)g(email)g(is)h (sent)f(by)g(forwarding)g(to)g(your)g(local)236 1727 y(SMTP)g(server,)g(which)g(then)g(does)g(the)h(normal)e(delivery)h (process.)88 b(Your)44 b(local)g(machine)236 1818 y(must)g(be)h (running)f(an)g(SMTP)g(server.)236 1910 y("""\))416 2001 y(parser.add_option\('-d',)d('--directory',)1223 2092 y(type='string',)h(action='store',)1223 2183 y(help="""Mail)g(the)j (contents)e(of)i(the)f(specified)f(directory,)1223 2275 y(otherwise)g(use)h(the)g(current)g(directory.)88 b(Only)44 b(the)h(regular)1223 2366 y(files)f(in)g(the)g(directory)g(are)g(sent,) g(and)g(we)h(don't)f(recurse)f(to)1223 2457 y(subdirectories."""\))416 2549 y(parser.add_option\('-o',)e('--output',)1223 2640 y(type='string',)h(action='store',)g(metavar='FILE',)1223 2731 y(help="""Print)g(the)i(composed)g(message)g(to)g(FILE)g(instead)g (of)1223 2823 y(sending)f(the)i(message)e(to)i(the)f(SMTP)g (server."""\))416 2914 y(parser.add_option\('-s',)d('--sender',)1223 3005 y(type='string',)h(action='store',)g(metavar='SENDER',)1223 3097 y(help='The)h(value)h(of)g(the)h(From:)f(header)f(\(required\)'\)) 416 3188 y(parser.add_option\('-r',)e('--recipient',)1223 3279 y(type='string',)h(action='append',)g(metavar='RECIPIENT',)1223 3371 y(default=[],)h(dest='recipients',)1223 3462 y(help='A)g(To:)i (header)e(value)h(\(at)h(least)f(one)g(required\)'\))416 3553 y(opts,)g(args)g(=)g(parser.parse_args\(\))416 3645 y(if)g(not)g(opts.sender)f(or)i(not)f(opts.recipients:)595 3736 y(parser.print_help\(\))595 3827 y(sys.exit\(1\))416 3919 y(directory)f(=)i(opts.directory)416 4010 y(if)f(not)g(directory:) 595 4101 y(directory)f(=)i('.')416 4193 y(#)f(Create)g(the)g(enclosing) g(\(outer\))f(message)416 4284 y(outer)h(=)g(MIMEMultipart\(\))416 4375 y(outer['Subject'])e(=)i('Contents)g(of)g(directory)f(\045s')i (\045)f(os.path.abspath\(directory\))416 4467 y(outer['To'])f(=)h (COMMASPACE.join\(opts.recipients\))416 4558 y(outer['From'])e(=)j (opts.sender)416 4649 y(outer.preamble)d(=)j('You)f(will)g(not)g(see)h (this)f(in)g(a)h(MIME-aware)e(mail)h(reader.\\n')416 4832 y(for)g(filename)f(in)i(os.listdir\(directory\):)595 4923 y(path)f(=)h(os.path.join\(directory,)c(filename\))595 5015 y(if)j(not)h(os.path.isfile\(path\):)774 5106 y(continue)595 5197 y(#)g(Guess)f(the)g(content)g(type)g(based)g(on)g(the)g(file's)g (extension.)88 b(Encoding)595 5289 y(#)45 b(will)f(be)g(ignored,)g (although)f(we)i(should)e(check)h(for)h(simple)f(things)f(like)595 5380 y(#)i(gzip'd)e(or)i(compressed)e(files.)p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g (and)g(MIME)g(handling)h(pac)n(kage)1797 b(215)p eop end %%Page: 216 228 TeXDict begin 216 227 bop 595 83 a FA(ctype,)44 b(encoding)f(=)i (mimetypes.guess_type\(path\))595 174 y(if)f(ctype)g(is)h(None)f(or)h (encoding)e(is)h(not)h(None:)774 266 y(#)g(No)f(guess)g(could)g(be)h (made,)f(or)g(the)h(file)f(is)g(encoded)g(\(compressed\),)f(so)774 357 y(#)i(use)f(a)h(generic)f(bag-of-bits)e(type.)774 448 y(ctype)i(=)h('application/octet-stream')595 540 y(maintype,)e(subtype)h(=)h(ctype.split\('/',)d(1\))595 631 y(if)i(maintype)g(==)g('text':)774 722 y(fp)h(=)f(open\(path\))774 814 y(#)h(Note:)f(we)g(should)g(handle)g(calculating)f(the)h(charset) 774 905 y(msg)h(=)f(MIMEText\(fp.read\(\),)e(_subtype=subtype\))774 996 y(fp.close\(\))595 1088 y(elif)i(maintype)g(==)g('image':)774 1179 y(fp)h(=)f(open\(path,)g('rb'\))774 1270 y(msg)h(=)f (MIMEImage\(fp.read\(\),)e(_subtype=subtype\))774 1362 y(fp.close\(\))595 1453 y(elif)i(maintype)g(==)g('audio':)774 1544 y(fp)h(=)f(open\(path,)g('rb'\))774 1636 y(msg)h(=)f (MIMEAudio\(fp.read\(\),)e(_subtype=subtype\))774 1727 y(fp.close\(\))595 1818 y(else:)774 1910 y(fp)j(=)f(open\(path,)g ('rb'\))774 2001 y(msg)h(=)f(MIMEBase\(maintype,)e(subtype\))774 2092 y(msg.set_payload\(fp.read\(\)\))774 2183 y(fp.close\(\))774 2275 y(#)j(Encode)f(the)g(payload)g(using)g(Base64)774 2366 y(encoders.encode_base64\(msg\))595 2457 y(#)h(Set)f(the)g (filename)g(parameter)595 2549 y (msg.add_header\('Content-Disposition',)38 b('attachment',)43 b(filename=filename\))595 2640 y(outer.attach\(msg\))416 2731 y(#)h(Now)h(send)f(or)g(store)g(the)h(message)416 2823 y(composed)e(=)i(outer.as_string\(\))416 2914 y(if)f(opts.output:) 595 3005 y(fp)g(=)h(open\(opts.output,)d('w'\))595 3097 y(fp.write\(composed\))595 3188 y(fp.close\(\))416 3279 y(else:)595 3371 y(s)j(=)f(smtplib.SMTP\(\))595 3462 y(s.connect\(\))595 3553 y(s.sendmail\(opts.sender,)d(opts.recipients,) h(composed\))595 3645 y(s.close\(\))236 3919 y(if)j(__name__)e(==)i ('__main__':)416 4010 y(main\(\))0 4207 y FN(And)20 b(\002nally)-5 b(,)19 b(here')-5 b(s)20 b(an)g(e)o(xample)f(of)h(ho)n(w)g(to)g(unpack) e(a)j(MIME)f(message)g(lik)o(e)g(the)g(one)g(abo)o(v)o(e,)e(into)i(a)h (directory)d(of)i(\002les:)236 4395 y FA(#!/usr/bin/env)43 b(python)236 4578 y("""Unpack)h(a)g(MIME)g(message)g(into)g(a)h (directory)e(of)i(files.""")236 4760 y(import)f(os)236 4852 y(import)g(sys)236 4943 y(import)g(email)236 5034 y(import)g(errno)236 5126 y(import)g(mimetypes)236 5308 y(from)g(optparse)g(import)g(OptionParser)p 0 5549 3901 4 v 0 5649 a FI(216)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 217 229 TeXDict begin 217 228 bop 236 174 a FA(def)45 b(main\(\):)416 266 y(parser)e(=)i(OptionParser\(usage="""\\)236 357 y(Unpack)f(a)h(MIME)f(message)g(into)g(a)g(directory)g(of)g(files.)236 540 y(Usage:)g(\045prog)g([options])f(msgfile)236 631 y("""\))416 722 y(parser.add_option\('-d',)e('--directory',)1223 814 y(type='string',)h(action='store',)1223 905 y(help="""Unpack)g(the) i(MIME)g(message)g(into)g(the)h(named)1223 996 y(directory,)e(which)h (will)g(be)g(created)g(if)g(it)h(doesn't)f(already)1223 1088 y(exist."""\))416 1179 y(opts,)g(args)g(=)g(parser.parse_args\(\)) 416 1270 y(if)g(not)g(opts.directory:)595 1362 y(parser.print_help\(\)) 595 1453 y(sys.exit\(1\))416 1636 y(try:)595 1727 y(msgfile)g(=)g (args[0])416 1818 y(except)f(IndexError:)595 1910 y (parser.print_help\(\))595 2001 y(sys.exit\(1\))416 2183 y(try:)595 2275 y(os.mkdir\(opts.directory\))416 2366 y(except)g(OSError,)h(e:)595 2457 y(#)h(Ignore)e(directory)h(exists)g (error)595 2549 y(if)g(e.errno)g(<>)h(errno.EEXIST:)774 2640 y(raise)416 2823 y(fp)f(=)h(open\(msgfile\))416 2914 y(msg)f(=)h(email.message_from_file\(fp\))416 3005 y(fp.close\(\))416 3188 y(counter)e(=)i(1)416 3279 y(for)f(part)g(in)h (msg.walk\(\):)595 3371 y(#)g(multipart/)1135 3384 y(*)1223 3371 y(are)f(just)g(containers)595 3462 y(if)g (part.get_content_maintype\(\))d(==)j('multipart':)774 3553 y(continue)595 3645 y(#)h(Applications)d(should)i(really)g (sanitize)f(the)i(given)f(filename)f(so)i(that)f(an)595 3736 y(#)h(email)f(message)f(can't)h(be)h(used)f(to)g(overwrite)g (important)f(files)595 3827 y(filename)g(=)i(part.get_filename\(\))595 3919 y(if)f(not)h(filename:)774 4010 y(ext)g(=)f (mimetypes.guess_extension\(part.get_conte)o(nt_typ)o(e\(\)\))774 4101 y(if)h(not)f(ext:)954 4193 y(#)g(Use)h(a)f(generic)g(bag-of-bits)f (extension)954 4284 y(ext)h(=)h('.bin')774 4375 y(filename)f(=)g ('part-\04503d\045s')f(\045)i(\(counter,)e(ext\))595 4467 y(counter)h(+=)g(1)595 4558 y(fp)g(=)h (open\(os.path.join\(opts.directory,)39 b(filename\),)k('wb'\))595 4649 y(fp.write\(part.get_payload\(decode=True\))o(\))595 4741 y(fp.close\(\))236 5015 y(if)i(__name__)e(==)i('__main__':)416 5106 y(main\(\))p 0 5549 3901 4 v 0 5649 a FI(7.1.)52 b FJ(email)22 b FI(\227)h(An)h(email)g(and)g(MIME)g(handling)h(pac)n (kage)1797 b(217)p eop end %%Page: 218 230 TeXDict begin 218 229 bop 0 87 a FE(7.2)121 b Fx(mailcap)31 b FE(\227)i(Mailcap)g(\002le)g(handling.)0 320 y FN(Mailcap)26 b(\002les)i(are)f(used)f(to)h(con\002gure)e(ho)n(w)h(MIME-a)o(w)o(are)f (applications)h(such)g(as)h(mail)g(readers)f(and)h(W)-7 b(eb)27 b(bro)n(wsers)f(react)g(to)0 420 y(\002les)d(with)g(dif)n (ferent)d(MIME)i(types.)31 b(\(The)21 b(name)h(\223mailcap\224)f(is)i (deri)n(v)o(ed)e(from)g(the)h(phrase)g(\223mail)g(capability\224.\))29 b(F)o(or)22 b(e)o(xample,)f(a)0 519 y(mailcap)h(\002le)g(might)g (contain)f(a)h(line)h(lik)o(e)f(`)p FJ(video/mpeg;)48 b(xmpeg)g(\045s)p FN('.)31 b(Then,)22 b(if)g(the)g(user)g(encounters)e (an)j(email)f(message)0 619 y(or)h(W)-7 b(eb)24 b(document)e(with)i (the)f(MIME)g(type)g FO(video/mpeg)p FN(,)f(`)p FJ(\045s)p FN(')h(will)h(be)g(replaced)e(by)h(a)h(\002lename)f(\(usually)f(one)h (belonging)e(to)j(a)0 719 y(temporary)18 b(\002le\))i(and)g(the)g FL(xmpeg)g FN(program)e(can)i(be)g(automatically)f(started)h(to)h(vie)n (w)f(the)g(\002le.)0 866 y(The)30 b(mailcap)f(format)g(is)i(documented) c(in)j(RFC)i(1524,)e(\223)-7 b(A)31 b(User)f(Agent)g(Con\002guration)e (Mechanism)h(F)o(or)g(Multimedia)g(Mail)0 965 y(F)o(ormat)19 b(Information,)-6 b(\224)18 b(b)n(ut)i(is)h(not)f(an)g(Internet)f (standard.)24 b(Ho)n(we)n(v)o(er)m(,)18 b(mailcap)h(\002les)i(are)f (supported)f(on)g(most)k(U)t FH(N)t(I)t(X)g FN(systems.)0 1112 y FD(findmatch)p FJ(\()p FK(caps,)18 b(MIMEtype)p FC([)p FK(,)h(k)o(e)n(y)p FC([)p FK(,)h(\002lename)p FC([)p FK(,)e(plist)13 b FC(])f(])g(])p FJ(\))208 1212 y FN(Return)20 b(a)i(2-tuple;)e(the)h(\002rst)h(element)e(is)i(a)g (string)f(containing)e(the)i(command)e(line)i(to)g(be)g(e)o(x)o(ecuted) f(\(which)g(can)h(be)g(passed)208 1311 y(to)d FJ(os.system\(\))p FN(\),)f(and)h(the)g(second)g(element)g(is)h(the)f(mailcap)g(entry)g (for)g(a)h(gi)n(v)o(en)e(MIME)h(type.)24 b(If)18 b(no)g(matching)f (MIME)208 1411 y(type)i(can)h(be)g(found,)f FJ(\(None,)48 b(None\))20 b FN(is)h(returned.)208 1544 y FK(k)o(e)n(y)27 b FN(is)i(the)f(name)g(of)g(the)g(\002eld)g(desired,)h(which)e (represents)h(the)g(type)f(of)h(acti)n(vity)f(to)i(be)f(performed;)h (the)f(def)o(ault)f(v)n(alue)208 1643 y(is)f(')l(vie)n(w',)g(since)g (in)f(the)h(most)g(common)e(case)i(you)e(simply)i(w)o(ant)f(to)h(vie)n (w)g(the)f(body)g(of)g(the)h(MIME-typed)d(data.)41 b(Other)208 1743 y(possible)22 b(v)n(alues)g(might)g(be)g('compose')e(and)i ('edit',)h(if)f(you)g(w)o(anted)g(to)h(create)f(a)h(ne)n(w)f(body)f(of) h(the)h(gi)n(v)o(en)e(MIME)h(type)g(or)208 1843 y(alter)e(the)g(e)o (xisting)f(body)g(data.)25 b(See)c(RFC)g(1524)e(for)h(a)g(complete)f (list)j(of)e(these)g(\002elds.)208 1975 y FK(\002lename)25 b FN(is)i(the)f(\002lename)g(to)h(be)f(substituted)g(for)f(`)p FJ(\045s)p FN(')h(in)h(the)f(command)f(line;)k(the)d(def)o(ault)g(v)n (alue)g(is)h FJ('/dev/null')208 2075 y FN(which)19 b(is)i(almost)g (certainly)e(not)h(what)g(you)f(w)o(ant,)h(so)h(usually)e(you')o(ll)h (o)o(v)o(erride)d(it)k(by)f(specifying)f(a)h(\002lename.)208 2208 y FK(plist)29 b FN(can)e(be)h(a)g(list)g(containing)e(named)g (parameters;)k(the)e(def)o(ault)e(v)n(alue)h(is)h(simply)g(an)f(empty)f (list.)48 b(Each)27 b(entry)g(in)h(the)208 2308 y(list)e(must)f(be)g(a) g(string)g(containing)e(the)i(parameter)e(name,)j(an)e(equals)h(sign)g (\(`)p FJ(=)p FN('\),)g(and)f(the)h(parameter')-5 b(s)24 b(v)n(alue.)39 b(Mailcap)208 2407 y(entries)32 b(can)g(contain)f(named) g(parameters)g(lik)o(e)h FJ(\045{foo})p FN(,)i(which)e(will)h(be)f (replaced)f(by)g(the)i(v)n(alue)e(of)h(the)g(parameter)208 2507 y(named)20 b('foo'.)26 b(F)o(or)21 b(e)o(xample,)e(if)j(the)f (command)e(line)i(`)p FJ(showpartial)48 b(\045{id})g(\045{number})h (\045{total})p FN(')19 b(w)o(as)j(in)208 2606 y(a)j(mailcap)f(\002le,)j (and)d FK(plist)j FN(w)o(as)f(set)f(to)g FJ(['id=1',)49 b('number=2',)e('total=3'])p FN(,)25 b(the)g(resulting)f(command)e (line)208 2706 y(w)o(ould)d(be)h FJ('showpartial)48 b(1)h(2)h(3')p FN(.)208 2839 y(In)18 b(a)h(mailcap)f(\002le,)i(the)e(\223test\224)i (\002eld)f(can)f(optionally)f(be)i(speci\002ed)f(to)h(test)h(some)e(e)o (xternal)g(condition)e(\(such)j(as)g(the)g(machine)208 2938 y(architecture,)c(or)h(the)g(windo)n(w)f(system)i(in)f(use\))h(to) f(determine)f(whether)g(or)h(not)g(the)h(mailcap)e(line)i(applies.)23 b FJ(findmatch\(\))208 3038 y FN(will)d(automatically)f(check)h(such)g (conditions)e(and)i(skip)g(the)g(entry)g(if)g(the)g(check)g(f)o(ails.)0 3185 y FD(getcaps)p FJ(\(\))208 3285 y FN(Returns)e(a)h(dictionary)e (mapping)g(MIME)i(types)f(to)h(a)h(list)g(of)e(mailcap)g(\002le)i (entries.)k(This)19 b(dictionary)e(must)i(be)g(passed)g(to)g(the)208 3384 y FJ(findmatch\(\))h FN(function.)30 b(An)22 b(entry)f(is)i (stored)f(as)h(a)g(list)g(of)f(dictionaries,)f(b)n(ut)h(it)h(shouldn')o (t)d(be)j(necessary)e(to)h(kno)n(w)g(the)208 3484 y(details)e(of)g (this)h(representation.)208 3617 y(The)27 b(information)f(is)j(deri)n (v)o(ed)d(from)h(all)h(of)g(the)g(mailcap)f(\002les)i(found)e(on)g(the) h(system.)49 b(Settings)28 b(in)g(the)g(user')-5 b(s)28 b(mailcap)208 3716 y(\002le)e(`)p FO($HOME/.mailcap)p FN(')d(will)k(o)o(v)o(erride)c(settings)j(in)g(the)f(system)h(mailcap)f (\002les)i(`)p FO(/etc/mailcap)p FN(',)d(`)p FO(/usr/etc/mailcap)p FN(',)g(and)208 3816 y(`)p FO(/usr/local/etc/mailcap)p FN('.)0 3963 y(An)c(e)o(xample)f(usage:)236 4201 y FA(>>>)45 b(import)e(mailcap)236 4292 y(>>>)i(d=mailcap.getcaps\(\))236 4384 y(>>>)g(mailcap.findmatch\(d,)c('video/mpeg',)i (filename='/tmp/tmp1223'\))236 4475 y(\('xmpeg)h(/tmp/tmp1223',)e ({'view':)i('xmpeg)g(\045s'}\))0 4985 y FE(7.3)121 b Fx(mailbox)31 b FE(\227)i(Manipulate)i(mailbo)l(x)l(es)f(in)f(v)m(ar)r (ious)h(f)l(or)s(mats)0 5218 y FN(This)26 b(module)f(de\002nes)g(tw)o (o)h(classes,)j FJ(Mailbox)c FN(and)g FJ(Message)p FN(,)h(for)g (accessing)f(and)g(manipulating)f(on-disk)h(mailbox)o(es)f(and)0 5318 y(the)19 b(messages)h(the)o(y)e(contain.)24 b FJ(Mailbox)19 b FN(of)n(fers)f(a)i(dictionary-lik)o(e)d(mapping)g(from)h(k)o(e)o(ys)h (to)h(messages.)25 b FJ(Message)18 b FN(e)o(xtends)h(the)p 0 5549 3901 4 v 0 5649 a FI(218)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 219 231 TeXDict begin 219 230 bop 0 83 a FJ(email.Message)17 b FN(module')-5 b(s)18 b FJ(Message)h FN(class)h(with)f (format-speci\002c)f(state)h(and)g(beha)n(vior)-5 b(.)23 b(Supported)17 b(mailbox)h(formats)h(are)0 183 y(Maildir)m(,)g(mbox,)g (MH,)h(Babyl,)g(and)g(MMDF)-7 b(.)0 330 y FL(See)21 b(Also:)0 476 y FN(Module)e FJ(email)h FN(\(section)f(7.1\):)208 576 y(Represent)g(and)h(manipulate)f(messages.)0 861 y Fv(7.3.1)100 b Fm(Mailbox)26 b Fv(objects)0 1063 y FL(class)21 b FD(Mailbox)208 1163 y FN(A)f(mailbox,)f(which)h(may)f(be) h(inspected)g(and)f(modi\002ed.)0 1310 y(The)27 b FJ(Mailbox)f FN(class)i(de\002nes)f(an)g(interf)o(ace)f(and)h(is)h(not)e(intended)g (to)h(be)g(instantiated.)45 b(Instead,)28 b(format-speci\002c)d (subclasses)0 1410 y(should)19 b(inherit)h(from)f FJ(Mailbox)g FN(and)h(your)f(code)g(should)h(instantiate)g(a)g(particular)f (subclass.)0 1556 y(The)34 b FJ(Mailbox)f FN(interf)o(ace)g(is)i (dictionary-lik)o(e,)g(with)g(small)f(k)o(e)o(ys)g(corresponding)d(to)j (messages.)67 b(K)n(e)o(ys)34 b(are)g(issued)g(by)g(the)0 1656 y FJ(Mailbox)27 b FN(instance)g(with)g(which)g(the)o(y)g(will)h (be)g(used)f(and)g(are)g(only)g(meaningful)e(to)j(that)f FJ(Mailbox)g FN(instance.)47 b(A)28 b(k)o(e)o(y)e(con-)0 1756 y(tinues)31 b(to)g(identify)f(a)h(message)g(e)n(v)o(en)f(if)i(the) f(corresponding)c(message)k(is)h(modi\002ed,)g(such)f(as)h(by)f (replacing)e(it)j(with)f(another)0 1855 y(message.)0 2002 y(Messages)18 b(may)e(be)h(added)f(to)i(a)g FJ(Mailbox)e FN(instance)h(using)g(the)g(set-lik)o(e)g(method)f FJ(add\(\))h FN(and)f(remo)o(v)o(ed)f(using)i(a)h FJ(del)f FN(statement)0 2102 y(or)j(the)g(set-lik)o(e)g(methods)g FJ(remove\(\))f FN(and)g FJ(discard\(\))p FN(.)0 2249 y FJ(Mailbox)26 b FN(interf)o(ace)h(semantics)g(dif)n(fer)f(from)g(dictionary)f (semantics)i(in)h(some)f(note)n(w)o(orthy)d(w)o(ays.)46 b(Each)27 b(time)g(a)h(message)f(is)0 2348 y(requested,)33 b(a)g(ne)n(w)e(representation)f(\(typically)h(a)h FJ(Message)f FN(instance\))g(is)i(generated)d(based)h(upon)g(the)h(current)e(state)j (of)f(the)0 2448 y(mailbox.)23 b(Similarly)-5 b(,)19 b(when)g(a)h(message)g(is)h(added)d(to)i(a)g FJ(Mailbox)f FN(instance,)g(the)h(pro)o(vided)d(message)i(representation')-5 b(s)18 b(contents)0 2548 y(are)i(copied.)k(In)c(neither)f(case)i(is)g (a)g(reference)d(to)i(the)h(message)f(representation)e(k)o(ept)i(by)f (the)i FJ(Mailbox)e FN(instance.)0 2694 y(The)k(def)o(ault)f FJ(Mailbox)h FN(iterator)f(iterates)i(o)o(v)o(er)e(message)h (representations,)f(not)h(k)o(e)o(ys)f(as)i(the)g(def)o(ault)e (dictionary)g(iterator)g(does.)0 2794 y(Moreo)o(v)o(er)m(,)16 b(modi\002cation)h(of)h(a)h(mailbox)e(during)g(iteration)h(is)i(safe)e (and)g(well-de\002ned.)23 b(Messages)c(added)f(to)g(the)h(mailbox)e (after)i(an)0 2894 y(iterator)h(is)h(created)e(will)i(not)f(be)g(seen)h (by)e(the)i(iterator)-5 b(.)24 b(Messages)d(remo)o(v)o(ed)d(from)h(the) h(mailbox)f(before)g(the)h(iterator)g(yields)g(them)0 2993 y(will)e(be)g(silently)g(skipped,)f(though)f(using)h(a)h(k)o(e)o (y)f(from)g(an)h(iterator)f(may)g(result)h(in)f(a)i FJ(KeyError)d FN(e)o(xception)g(if)i(the)g(corresponding)0 3093 y(message)i(is)h (subsequently)d(remo)o(v)o(ed.)p 0 3183 3901 17 v 0 3773 17 590 v 75 3298 a FL(W)-5 b(ar)o(ning:)74 b FN(Be)27 b(v)o(ery)e(cautious)h(when)f(modifying)f(mailbox)o(es)h(that)i(might)e (be)i(simultaneously)d(changed)h(by)h(some)g(other)75 3398 y(process.)41 b(The)26 b(safest)g(mailbox)f(format)g(to)h(use)g (for)f(such)h(tasks)g(is)h(Maildir;)i(try)c(to)h(a)n(v)n(oid)g(using)f (single-\002le)h(formats)f(such)75 3498 y(as)j(mbox)f(for)g(concurrent) f(writing.)48 b(If)28 b(you')l(re)e(modifying)f(a)k(mailbox,)f(you)f FK(must)i FN(lock)e(it)i(by)e(calling)h(the)g FJ(lock\(\))f FN(and)75 3597 y FJ(unlock\(\))i FN(methods)g FK(befor)m(e)h FN(reading)e(an)o(y)i(messages)g(in)g(the)g(\002le)h(or)f(making)f(an)o (y)g(changes)g(by)h(adding)e(or)i(deleting)f(a)75 3697 y(message.)24 b(F)o(ailing)c(to)h(lock)e(the)i(mailbox)d(runs)i(the)g (risk)h(of)f(losing)f(messages)i(or)f(corrupting)d(the)j(entire)g (mailbox.)p 3883 3773 V 0 3790 3901 17 v 0 3945 a FJ(Mailbox)f FN(instances)i(ha)n(v)o(e)e(the)h(follo)n(wing)f(methods:)0 4092 y FD(add)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 4191 y FN(Add)g FK(messa)o(g)o(e)i FN(to)f(the)g(mailbox)f(and)h (return)f(the)h(k)o(e)o(y)g(that)g(has)g(been)g(assigned)f(to)i(it.)208 4324 y(P)o(arameter)c FK(messa)o(g)o(e)j FN(may)e(be)h(a)g FJ(Message)g FN(instance,)f(an)h FJ(email.Message.Message)d FN(instance,)i(a)i(string,)e(or)h(a)g(\002le-)208 4423 y(lik)o(e)25 b(object)h(\(which)e(should)h(be)h(open)e(in)i(te)o(xt)f (mode\).)40 b(If)26 b FK(messa)o(g)o(e)g FN(is)g(an)g(instance)f(of)g (the)h(appropriate)d(format-speci\002c)208 4523 y FJ(Message)g FN(subclass)i(\(e.g.,)f(if)g(it')-5 b(s)25 b(an)g FJ(mboxMessage)d FN(instance)i(and)g(this)h(is)g(an)f FJ(mbox)g FN(instance\),)g(its)h (format-speci\002c)208 4623 y(information)17 b(is)k(used.)k(Otherwise,) 20 b(reasonable)f(def)o(aults)g(for)h(format-speci\002c)e(information)g (are)i(used.)0 4769 y FD(remove)p FJ(\()p FK(k)o(e)n(y)p FJ(\))0 4869 y FD(__delitem__)p FJ(\()p FK(k)o(e)n(y)p FJ(\))0 4969 y FD(discard)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 5068 y FN(Delete)g(the)g(message)g(corresponding)d(to)j FK(k)o(e)n(y)g FN(from)f(the)i(mailbox.)208 5201 y(If)29 b(no)f(such)h(message)g(e)o(xists,)j(a)d FJ(KeyError)g FN(e)o(xception)e(is)j(raised)f(if)g(the)h(method)d(w)o(as)j(called)f (as)h FJ(remove\(\))e FN(or)h FJ(_-)208 5300 y(_delitem__\(\))34 b FN(b)n(ut)h(no)g(e)o(xception)f(is)j(raised)e(if)h(the)g(method)e(w)o (as)j(called)e(as)h FJ(discard\(\))p FN(.)71 b(The)35 b(beha)n(vior)f(of)208 5400 y FJ(discard\(\))29 b FN(may)h(be)g (preferred)f(if)h(the)h(underlying)d(mailbox)h(format)g(supports)h (concurrent)e(modi\002cation)g(by)i(other)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i (mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r(mats)1619 b(219)p eop end %%Page: 220 232 TeXDict begin 220 231 bop 208 83 a FN(processes.)0 230 y FD(__setitem__)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(messa)o(g)o(e)p FJ(\))208 330 y FN(Replace)k(the)g(message)f(corresponding)e(to)j FK(k)o(e)n(y)g FN(with)g FK(messa)o(g)o(e)p FN(.)30 b(Raise)23 b(a)g FJ(KeyError)e FN(e)o(xception)f(if)i(no)g(message)g(already)208 429 y(corresponds)17 b(to)k FK(k)o(e)n(y)p FN(.)208 560 y(As)g(with)g FJ(add\(\))p FN(,)f(parameter)f FK(messa)o(g)o(e)i FN(may)f(be)g(a)h FJ(Message)f FN(instance,)g(an)h FJ (email.Message.Message)c FN(instance,)208 660 y(a)23 b(string,)g(or)f(a)h(\002le-lik)o(e)g(object)f(\(which)g(should)g(be)h (open)e(in)i(te)o(xt)g(mode\).)31 b(If)23 b FK(messa)o(g)o(e)g FN(is)h(an)e(instance)h(of)f(the)h(appropriate)208 759 y(format-speci\002c)f FJ(Message)h FN(subclass)i(\(e.g.,)f(if)g(it')-5 b(s)26 b(an)e FJ(mboxMessage)f FN(instance)h(and)f(this)i(is)g(an)f FJ(mbox)g FN(instance\),)h(its)208 859 y(format-speci\002c)f (information)f(is)k(used.)42 b(Otherwise,)27 b(the)e(format-speci\002c) g(information)e(of)j(the)g(message)f(that)h(currently)208 959 y(corresponds)17 b(to)k FK(k)o(e)n(y)f FN(is)h(left)f(unchanged.)0 1105 y FD(iterkeys)p FJ(\(\))0 1205 y FD(keys)p FJ(\(\))208 1305 y FN(Return)f(an)h(iterator)g(o)o(v)o(er)f(all)i(k)o(e)o(ys)e(if)i (called)f(as)h FJ(iterkeys\(\))e FN(or)h(return)f(a)h(list)h(of)f(k)o (e)o(ys)g(if)h(called)f(as)h FJ(keys\(\))p FN(.)0 1452 y FD(itervalues)p FJ(\(\))0 1551 y FD(__iter__)p FJ(\(\))0 1651 y FD(values)p FJ(\(\))208 1750 y FN(Return)c(an)i(iterator)f(o)o (v)o(er)f(representations)f(of)i(all)h(messages)g(if)f(called)h(as)g FJ(itervalues\(\))d FN(or)j FJ(__iter__\(\))e FN(or)h(return)208 1850 y(a)23 b(list)g(of)g(such)f(representations)f(if)i(called)g(as)g FJ(values\(\))p FN(.)32 b(The)22 b(messages)h(are)f(represented)f(as)j (instances)e(of)h(the)f(appro-)208 1950 y(priate)h(format-speci\002c)g FJ(Message)g FN(subclass)i(unless)f(a)h(custom)e(message)h(f)o(actory)f (w)o(as)j(speci\002ed)d(when)h(the)g FJ(Mailbox)208 2049 y FN(instance)c(w)o(as)j(initialized.)k FL(Note:)g FN(The)21 b(beha)n(vior)f(of)h FJ(__iter__\(\))f FN(is)i(unlik)o(e)e(that)i(of)f (dictionaries,)f(which)h(iterate)g(o)o(v)o(er)208 2149 y(k)o(e)o(ys.)0 2296 y FD(iteritems)p FJ(\(\))0 2395 y FD(items)p FJ(\(\))208 2495 y FN(Return)27 b(an)h(iterator)g(o)o(v)o (er)f(\()p FK(k)o(e)n(y)p FN(,)i FK(messa)o(g)o(e)p FN(\))f(pairs,)i (where)e FK(k)o(e)n(y)g FN(is)h(a)f(k)o(e)o(y)g(and)f FK(messa)o(g)o(e)i FN(is)g(a)f(message)g(representation,)g(if)208 2595 y(called)21 b(as)h FJ(iteritems\(\))e FN(or)h(return)g(a)h(list)g (of)g(such)f(pairs)g(if)h(called)f(as)i FJ(items\(\))p FN(.)28 b(The)21 b(messages)h(are)f(represented)f(as)208 2694 y(instances)h(of)g(the)h(appropriate)d(format-speci\002c)h FJ(Message)h FN(subclass)h(unless)f(a)i(custom)e(message)g(f)o(actory)f (w)o(as)j(speci\002ed)208 2794 y(when)c(the)h FJ(Mailbox)g FN(instance)g(w)o(as)h(initialized.)0 2941 y FD(get)p FJ(\()p FK(k)o(e)n(y)p FC([)p FK(,)e(default=None)12 b FC(])p FJ(\))0 3040 y FD(__getitem__)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 3140 y FN(Return)17 b(a)i(representation)d(of)i(the)g (message)g(corresponding)c(to)19 b FK(k)o(e)n(y)p FN(.)24 b(If)18 b(no)f(such)h(message)g(e)o(xists,)h FK(default)g FN(is)g(returned)d(if)j(the)208 3240 y(method)e(w)o(as)i(called)f(as)h FJ(get\(\))f FN(and)g(a)h FJ(KeyError)f FN(e)o(xception)e(is)k(raised)e (if)h(the)f(method)f(w)o(as)j(called)e(as)h FJ(__getitem_-)208 3339 y(_\(\))p FN(.)27 b(The)21 b(message)g(is)h(represented)e(as)i(an) f(instance)g(of)g(the)g(appropriate)e(format-speci\002c)g FJ(Message)h FN(subclass)i(unless)f(a)208 3439 y(custom)e(message)h(f)o (actory)f(w)o(as)i(speci\002ed)f(when)g(the)g FJ(Mailbox)f FN(instance)h(w)o(as)h(initialized.)0 3586 y FD(get_message)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 3685 y FN(Return)k(a)g(representation) f(of)h(the)g(message)g(corresponding)d(to)k FK(k)o(e)n(y)f FN(as)h(an)g(instance)f(of)g(the)g(appropriate)e(format-speci\002c)208 3785 y FJ(Message)c FN(subclass,)h(or)g(raise)h(a)f FJ(KeyError)g FN(e)o(xception)e(if)i(no)g(such)g(message)g(e)o(xists.)0 3932 y FD(get_string)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 4032 y FN(Return)h(a)h(string)g(representation)e(of)h(the)h(message)g (corresponding)c(to)k FK(k)o(e)n(y)p FN(,)g(or)g(raise)g(a)g FJ(KeyError)f FN(e)o(xception)f(if)i(no)g(such)208 4131 y(message)e(e)o(xists.)0 4278 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 4378 y FN(Return)d(a)h(\002le-lik)o(e)g (representation)e(of)h(the)h(message)g(corresponding)c(to)k FK(k)o(e)n(y)p FN(,)g(or)g(raise)g(a)g FJ(KeyError)f FN(e)o(xception)f(if)i(no)g(such)208 4477 y(message)k(e)o(xists.)32 b(The)22 b(\002le-lik)o(e)g(object)g(beha)n(v)o(es)g(as)h(if)g(open)e (in)i(binary)e(mode.)30 b(This)23 b(\002le)g(should)e(be)i(closed)f (once)f(it)j(is)f(no)208 4577 y(longer)18 b(needed.)208 4708 y FL(Note:)25 b FN(Unlik)o(e)c(other)f(representations)f(of)h (messages,)h(\002le-lik)o(e)g(representations)e(are)i(not)f (necessarily)h(independent)d(of)j(the)208 4807 y FJ(Mailbox)c FN(instance)h(that)h(created)e(them)h(or)g(of)g(the)h(underlying)c (mailbox.)23 b(More)18 b(speci\002c)h(documentation)c(is)k(pro)o(vided) d(by)208 4907 y(each)j(subclass.)0 5054 y FD(has_key)p FJ(\()p FK(k)o(e)n(y)p FJ(\))0 5154 y FD(__contains__)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 5253 y FN(Return)g FJ(True)h FN(if)h FK(k)o(e)n(y)f FN(corresponds)e(to)i(a)h(message,)e FJ(False)h FN(otherwise.)0 5400 y FD(__len__)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(220)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 221 233 TeXDict begin 221 232 bop 208 83 a FN(Return)19 b(a)i(count)e(of)h (messages)g(in)h(the)f(mailbox.)0 230 y FD(clear)p FJ(\(\))208 330 y FN(Delete)g(all)h(messages)f(from)f(the)h(mailbox.)0 476 y FD(pop)p FJ(\()p FK(k)o(e)n(y)p FC([)p FK(,)f(default)13 b FC(])p FJ(\))208 576 y FN(Return)19 b(a)i(representation)d(of)i(the)g (message)g(corresponding)d(to)k FK(k)o(e)n(y)f FN(and)f(delete)h(the)h (message.)j(If)d(no)e(such)h(message)g(e)o(xists,)208 676 y(return)d FK(default)j FN(if)f(it)g(w)o(as)h(supplied)e(or)g(else) i(raise)f(a)g FJ(KeyError)f FN(e)o(xception.)23 b(The)18 b(message)h(is)h(represented)d(as)i(an)g(instance)208 775 y(of)i(the)h(appropriate)d(format-speci\002c)h FJ(Message)h FN(subclass)h(unless)f(a)i(custom)e(message)g(f)o(actory)g(w)o(as)h (speci\002ed)f(when)h(the)208 875 y FJ(Mailbox)d FN(instance)h(w)o(as)h (initialized.)0 1022 y FD(popitem)p FJ(\(\))208 1121 y FN(Return)f(an)h(arbitrary)f(\()p FK(k)o(e)n(y)p FN(,)g FK(messa)o(g)o(e)p FN(\))h(pair)m(,)g(where)f FK(k)o(e)n(y)h FN(is)h(a)g(k)o(e)o(y)e(and)h FK(messa)o(g)o(e)g FN(is)h(a)f(message)g (representation,)e(and)i(delete)208 1221 y(the)29 b(corresponding)e (message.)54 b(If)30 b(the)g(mailbox)e(is)j(empty)-5 b(,)31 b(raise)f(a)g FJ(KeyError)f FN(e)o(xception.)53 b(The)29 b(message)h(is)h(repre-)208 1321 y(sented)26 b(as)i(an)f(instance)f(of)h(the)g(appropriate)d(format-speci\002c)h FJ(Message)h FN(subclass)h(unless)g(a)h(custom)e(message)h(f)o(actory) 208 1420 y(w)o(as)21 b(speci\002ed)e(when)h(the)g FJ(Mailbox)g FN(instance)g(w)o(as)h(initialized.)0 1567 y FD(update)p FJ(\()p FK(ar)m(g)p FJ(\))208 1667 y FN(P)o(arameter)f FK(ar)m(g)h FN(should)f(be)h(a)g FK(k)o(e)n(y)p FN(-to-)p FK(messa)o(g)o(e)f FN(mapping)f(or)i(an)g(iterable)g(of)g(\()p FK(k)o(e)n(y)p FN(,)f FK(messa)o(g)o(e)p FN(\))h(pairs.)28 b(Updates)21 b(the)g(mailbox)208 1766 y(so)j(that,)g(for)f(each)h(gi)n (v)o(en)e FK(k)o(e)n(y)i FN(and)f FK(messa)o(g)o(e)p FN(,)h(the)g(message)g(corresponding)c(to)k FK(k)o(e)n(y)f FN(is)i(set)g(to)e FK(messa)o(g)o(e)h FN(as)h(if)f(by)f(using)g FJ(_-)208 1866 y(_setitem__\(\))p FN(.)j(As)c(with)f FJ(__setitem__\(\))p FN(,)e(each)i FK(k)o(e)n(y)g FN(must)g(already)f (correspond)f(to)i(a)g(message)g(in)h(the)f(mailbox)208 1966 y(or)j(else)h(a)g FJ(KeyError)e FN(e)o(xception)g(will)i(be)f (raised,)h(so)g(in)g(general)e(it)i(is)h(incorrect)d(for)g FK(ar)m(g)i FN(to)f(be)h(a)f FJ(Mailbox)g FN(instance.)208 2065 y FL(Note:)g FN(Unlik)o(e)c(with)g(dictionaries,)f(k)o(e)o(yw)o (ord)f(ar)o(guments)h(are)h(not)g(supported.)0 2212 y FD(flush)p FJ(\(\))208 2312 y FN(Write)32 b(an)o(y)g(pending)e(changes) h(to)h(the)g(\002lesystem.)61 b(F)o(or)32 b(some)g FJ(Mailbox)f FN(subclasses,)k(changes)c(are)h(al)o(w)o(ays)h(written)208 2411 y(immediately)18 b(and)i FJ(flush\(\))g FN(does)f(nothing,)g(b)n (ut)h(you)f(should)g(still)j(mak)o(e)d(a)i(habit)f(of)g(calling)f(this) i(method.)0 2558 y FD(lock)p FJ(\(\))208 2658 y FN(Acquire)37 b(an)h(e)o(xclusi)n(v)o(e)f(advisory)g(lock)h(on)g(the)g(mailbox)g(so)g (that)h(other)e(processes)h(kno)n(w)g(not)g(to)g(modify)f(it.)81 b(An)208 2758 y FJ(ExternalClashError)24 b FN(is)k(raised)e(if)i(the)f (lock)f(is)i(not)f(a)n(v)n(ailable.)44 b(The)27 b(particular)f(locking) f(mechanisms)h(used)h(de-)208 2857 y(pend)f(upon)h(the)g(mailbox)g (format.)46 b(Y)-9 b(ou)27 b(should)g FK(always)h FN(lock)f(the)g (mailbox)g(before)f(making)h(an)o(y)f(modi\002cations)h(to)h(its)208 2957 y(contents.)0 3104 y FD(unlock)p FJ(\(\))208 3203 y FN(Release)21 b(the)f(lock)f(on)h(the)g(mailbox,)f(if)i(an)o(y)-5 b(.)0 3350 y FD(close)p FJ(\(\))208 3450 y FN(Flush)19 b(the)h(mailbox,)e(unlock)g(it)j(if)f(necessary)-5 b(,)18 b(and)h(close)h(an)o(y)f(open)f(\002les.)26 b(F)o(or)19 b(some)h FJ(Mailbox)f FN(subclasses,)h(this)g(method)208 3549 y(does)f(nothing.)0 3818 y FJ(Maildir)0 4021 y FL(class)i FD(Maildir)p FJ(\()p FK(dirname)p FC([)p FK(,)c(factory=rfc822.Messa)o (g)o(e)p FC([)p FK(,)h(cr)m(eate=T)-5 b(rue)12 b FC(])g(])p FJ(\))208 4120 y FN(A)23 b(subclass)h(of)f FJ(Mailbox)f FN(for)h(mailbox)o(es)f(in)h(Maildir)g(format.)33 b(P)o(arameter)22 b FK(factory)h FN(is)h(a)g(callable)f(object)g(that)g(accepts)g(a)208 4220 y(\002le-lik)o(e)f(message)g(representation)e(\(which)i(beha)n(v)o (es)f(as)i(if)g(opened)e(in)h(binary)f(mode\))g(and)h(returns)g(a)g (custom)g(representa-)208 4319 y(tion.)27 b(If)22 b FK(factory)f FN(is)h FJ(None)p FN(,)f FJ(MaildirMessage)e FN(is)j(used)f(as)h(the)g (def)o(ault)e(message)h(representation.)26 b(If)c FK(cr)m(eate)f FN(is)h FJ(True)p FN(,)208 4419 y(the)e(mailbox)f(is)i(created)e(if)i (it)g(does)f(not)f(e)o(xist.)208 4552 y(It)g(is)h(for)f(historical)f (reasons)h(that)g FK(factory)g FN(def)o(aults)g(to)g FJ(rfc822.Message)e FN(and)i(that)g FK(dirname)g FN(is)h(named)e(as)i (such)e(rather)208 4652 y(than)25 b FK(path)p FN(.)42 b(F)o(or)26 b(a)g FJ(Maildir)g FN(instance)g(that)g(beha)n(v)o(es)f (lik)o(e)h(instances)g(of)g(other)f FJ(Mailbox)h FN(subclasses,)i(set)f FK(factory)e FN(to)208 4751 y FJ(None)p FN(.)0 4898 y(Maildir)e(is)h(a) f(directory-based)d(mailbox)i(format)g(in)m(v)o(ented)f(for)h(the)i (qmail)e(mail)i(transfer)e(agent)g(and)h(no)n(w)f(widely)h(supported)e (by)0 4998 y(other)f(programs.)k(Messages)d(in)g(a)g(Maildir)f(mailbox) g(are)g(stored)g(in)h(separate)f(\002les)i(within)e(a)h(common)e (directory)g(structure.)25 b(This)0 5097 y(design)18 b(allo)n(ws)h(Maildir)g(mailbox)o(es)e(to)i(be)g(accessed)f(and)g (modi\002ed)g(by)g(multiple)h(unrelated)e(programs)g(without)h(data)g (corruption,)0 5197 y(so)j(\002le)f(locking)f(is)i(unnecessary)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or) r(mats)1619 b(221)p eop end %%Page: 222 234 TeXDict begin 222 233 bop 0 83 a FN(Maildir)24 b(mailbox)o(es)f (contain)g(three)g(subdirectories,)h(namely:)32 b(`)p FO(tmp)p FN(',)24 b(`)p FO(ne)o(w)p FN(',)g(and)f(`)p FO(cur)p FN('.)37 b(Messages)24 b(are)g(created)g(momentarily)0 183 y(in)32 b(the)h(`)p FO(tmp)p FN(')e(subdirectory)f(and)i(then)f(mo) o(v)o(ed)g(to)h(the)g(`)p FO(ne)o(w)p FN(')f(subdirectory)f(to)i (\002nalize)g(deli)n(v)o(ery)-5 b(.)59 b(A)33 b(mail)f(user)g(agent)g (may)0 282 y(subsequently)25 b(mo)o(v)o(e)h(the)h(message)g(to)g(the)g (`)p FO(cur)p FN(')g(subdirectory)d(and)j(store)g(information)d(about)i (the)h(state)h(of)f(the)g(message)g(in)g(a)0 382 y(special)20 b(\224info\224)g(section)f(appended)f(to)j(its)g(\002le)g(name.)0 529 y(F)o(olders)j(of)h(the)g(style)g(introduced)e(by)h(the)h(Courier)g (mail)g(transfer)f(agent)g(are)h(also)g(supported.)38 b(An)o(y)24 b(subdirectory)e(of)j(the)g(main)0 628 y(mailbox)g(is)i (considered)e(a)h(folder)g(if)g(`)p FJ(.)p FN(')43 b(is)28 b(the)e(\002rst)h(character)e(in)h(its)i(name.)42 b(F)o(older)26 b(names)g(are)g(represented)e(by)i FJ(Maildir)0 728 y FN(without)20 b(the)g(leading)f(`)p FJ(.)p FN('.)26 b(Each)20 b(folder)f(is)i(itself)g(a)g(Maildir)f(mailbox)f(b)n(ut)i(should)e(not) h(contain)f(other)h(folders.)25 b(Instead,)19 b(a)i(logical)0 828 y(nesting)f(is)h(indicated)e(using)h(`)p FJ(.)p FN(')k(to)d (delimit)f(le)n(v)o(els,)g(e.g.,)f(\224Archi)n(v)o(ed.2005.07\224.)0 975 y FL(Note:)44 b FN(The)30 b(Maildir)f(speci\002cation)g(requires)g (the)h(use)h(of)e(a)i(colon)e(\(`)p FJ(:)p FN('\))43 b(in)31 b(certain)e(message)h(\002le)g(names.)54 b(Ho)n(we)n(v)o(er)m (,)31 b(some)0 1074 y(operating)d(systems)i(do)f(not)h(permit)f(this)h (character)e(in)i(\002le)h(names,)g(If)f(you)e(wish)i(to)g(use)g(a)g (Maildir)n(-lik)o(e)f(format)g(on)g(such)h(an)0 1174 y(operating)f(system,)k(you)d(should)f(specify)h(another)g(character)f (to)i(use)g(instead.)56 b(The)30 b(e)o(xclamation)f(point)h(\(`)p FJ(!)p FN('\))56 b(is)31 b(a)g(popular)0 1273 y(choice.)24 b(F)o(or)c(e)o(xample:)236 1512 y FA(import)44 b(mailbox)236 1603 y(mailbox.Maildir.colon)e(=)i('!')0 1842 y FN(The)20 b FJ(colon)g FN(attrib)n(ute)f(may)h(also)h(be)f(set)h(on)f(a)g(per)n (-instance)f(basis.)0 1989 y FJ(Maildir)g FN(instances)i(ha)n(v)o(e)e (all)i(of)f(the)g(methods)f(of)h FJ(Mailbox)g FN(in)g(addition)f(to)h (the)g(follo)n(wing:)0 2136 y FD(list_folders)p FJ(\(\))208 2236 y FN(Return)f(a)i(list)g(of)f(the)g(names)g(of)g(all)h(folders.)0 2382 y FD(get_folder)p FJ(\()p FK(folder)r FJ(\))208 2482 y FN(Return)d(a)h FJ(Maildir)e FN(instance)h(representing)f(the)h (folder)g(whose)g(name)g(is)h FK(folder)r FN(.)24 b(A)19 b FJ(NoSuchMailboxError)d FN(e)o(xcep-)208 2582 y(tion)j(is)j(raised)e (if)g(the)g(folder)f(does)h(not)g(e)o(xist.)0 2729 y FD(add_folder)p FJ(\()p FK(folder)r FJ(\))208 2828 y FN(Create)g(a)h(folder)e(whose)g(name)h(is)h FK(folder)h FN(and)e(return)f(a)h FJ(Maildir)g FN(instance)g(representing)e(it.)0 2975 y FD(remove_folder)p FJ(\()p FK(folder)r FJ(\))208 3075 y FN(Delete)26 b(the)g(folder)f(whose)g(name)h(is)h FK(folder)r FN(.)42 b(If)26 b(the)g(folder)f(contains)g(an)o(y)g (messages,)j(a)e FJ(NotEmptyError)e FN(e)o(xception)208 3174 y(will)c(be)h(raised)f(and)f(the)h(folder)f(will)i(not)f(be)g (deleted.)0 3321 y FD(clean)p FJ(\(\))208 3421 y FN(Delete)f(temporary) e(\002les)k(from)d(the)h(mailbox)f(that)i(ha)n(v)o(e)e(not)h(been)g (accessed)g(in)h(the)f(last)h(36)f(hours.)24 b(The)19 b(Maildir)g(speci\002ca-)208 3520 y(tion)g(says)i(that)f(mail-reading)e (programs)h(should)g(do)h(this)g(occasionally)-5 b(.)0 3667 y(Some)20 b FJ(Mailbox)f FN(methods)g(implemented)g(by)h FJ(Maildir)f FN(deserv)o(e)g(special)h(remarks:)0 3814 y FD(add)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))0 3914 y FD(__setitem__)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(messa)o(g)o(e)p FJ(\))0 4013 y FD(update)p FJ(\()p FK(ar)m(g)p FJ(\))208 4113 y FL(W)-5 b(ar)o(ning:)27 b FN(These)22 b(methods)f(generate)f (unique)h(\002le)h(names)g(based)g(upon)e(the)i(current)f(process)g (ID.)h(When)g(using)f(multiple)208 4213 y(threads,)d(undetected)f(name) h(clashes)h(may)g(occur)f(and)g(cause)h(corruption)d(of)j(the)f (mailbox)g(unless)h(threads)f(are)h(coordinated)208 4312 y(to)h(a)n(v)n(oid)g(using)f(these)i(methods)e(to)h(manipulate)f(the)h (same)h(mailbox)d(simultaneously)-5 b(.)0 4459 y FD(flush)p FJ(\(\))208 4559 y FN(All)20 b(changes)g(to)g(Maildir)g(mailbox)o(es)f (are)h(immediately)f(applied,)f(so)j(this)g(method)e(does)g(nothing.)0 4706 y FD(lock)p FJ(\(\))0 4805 y FD(unlock)p FJ(\(\))208 4905 y FN(Maildir)g(mailbox)o(es)g(do)h(not)g(support)f(\(or)g (require\))g(locking,)f(so)j(these)f(methods)f(do)h(nothing.)0 5052 y FD(close)p FJ(\(\))208 5151 y(Maildir)25 b FN(instances)h(do)f (not)h(k)o(eep)f(an)o(y)h(open)f(\002les)i(and)e(the)h(underlying)d (mailbox)o(es)i(do)h(not)f(support)g(locking,)h(so)g(this)208 5251 y(method)18 b(does)i(nothing.)0 5398 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(222)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 223 235 TeXDict begin 223 234 bop 208 83 a FN(Depending)22 b(upon)h(the)h(host) g(platform,)f(it)i(may)f(not)g(be)g(possible)g(to)h(modify)d(or)i(remo) o(v)o(e)f(the)h(underlying)d(message)k(while)208 183 y(the)20 b(returned)e(\002le)j(remains)f(open.)0 330 y FL(See)h(Also:)0 476 y FN(maildir)f(man)f(page)h(from)f(qmail)208 576 y(The)g(original)g(speci\002cation)h(of)g(the)g(format.)0 723 y(Using)g(maildir)g(format)208 823 y(Notes)g(on)g(Maildir)g(by)f (its)j(in)m(v)o(entor)-5 b(.)23 b(Includes)c(an)h(updated)e (name-creation)g(scheme)i(and)f(details)i(on)f(\224info\224)f (semantics.)0 969 y(maildir)h(man)f(page)h(from)f(Courier)208 1069 y(Another)f(speci\002cation)i(of)g(the)g(format.)k(Describes)c(a)g (common)f(e)o(xtension)g(for)g(supporting)f(folders.)0 1337 y FJ(mbox)0 1540 y FL(class)j FD(mbox)p FJ(\()p FK(path)p FC([)p FK(,)d(factory=None)p FC([)p FK(,)h(cr)m(eate=T)-5 b(rue)12 b FC(])g(])p FJ(\))208 1640 y FN(A)18 b(subclass)g(of)g FJ(Mailbox)g FN(for)f(mailbox)o(es)g(in)h(mbox)f(format.)23 b(P)o(arameter)17 b FK(factory)h FN(is)h(a)f(callable)g(object)g(that)g (accepts)g(a)g(\002le-)208 1739 y(lik)o(e)g(message)f(representation)f (\(which)h(beha)n(v)o(es)g(as)h(if)g(opened)e(in)i(binary)f(mode\))f (and)h(returns)g(a)i(custom)e(representation.)22 b(If)208 1839 y FK(factory)e FN(is)h FJ(None)p FN(,)g FJ(mboxMessage)e FN(is)i(used)g(as)g(the)g(def)o(ault)f(message)g(representation.)k(If)d FK(cr)m(eate)f FN(is)i FJ(True)p FN(,)e(the)h(mailbox)208 1939 y(is)g(created)e(if)i(it)g(does)e(not)h(e)o(xist.)0 2086 y(The)f(mbox)e(format)h(is)i(the)f(classic)h(format)e(for)g (storing)g(mail)h(on)i(U)t FH(N)t(I)t(X)h FN(systems.)j(All)20 b(messages)f(in)g(an)g(mbox)f(mailbox)f(are)i(stored)0 2185 y(in)h(a)h(single)f(\002le)h(with)f(the)g(be)o(ginning)e(of)i (each)g(message)g(indicated)f(by)h(a)g(line)h(whose)f(\002rst)g(\002)n (v)o(e)g(characters)g(are)g(\224From)f(\224.)0 2332 y(Se)n(v)o(eral)31 b(v)n(ariations)g(of)h(the)g(mbox)f(format)g(e)o(xist)h(to)g(address)g (percei)n(v)o(ed)e(shortcomings)g(in)i(the)g(original.)59 b(In)32 b(the)g(interest)g(of)0 2432 y(compatibility)-5 b(,)23 b FJ(mbox)i FN(implements)e(the)h(original)g(format,)g(which)g (is)h(sometimes)f(referred)f(to)i(as)g FK(mboxo)p FN(.)36 b(This)25 b(means)f(that)h(the)0 2531 y FO(Content-Length:)44 b FN(header)m(,)32 b(if)g(present,)i(is)f(ignored)d(and)h(that)h(an)o (y)f(occurrences)e(of)j(\224From)f(\224)h(at)g(the)g(be)o(ginning)d(of) i(a)i(line)e(in)0 2631 y(a)e(message)e(body)g(are)h(transformed)e(to)i (\224\277From)g(\224)g(when)g(storing)f(the)h(message,)i(although)c (occurences)g(of)i(\224\277From)f(\224)i(are)f(not)0 2731 y(transformed)18 b(to)i(\224From)g(\224)g(when)g(reading)f(the)h (message.)0 2877 y(Some)g FJ(Mailbox)f FN(methods)g(implemented)g(by)h FJ(mbox)g FN(deserv)o(e)f(special)h(remarks:)0 3024 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 3124 y FN(Using)26 b(the)h(\002le)h(after)e(calling)h FJ(flush\(\))f FN(or)h FJ(close\(\))f FN(on)g(the)h FJ(mbox)g FN(instance)f(may)h (yield)f(unpredictable)f(results)i(or)208 3224 y(raise)20 b(an)g(e)o(xception.)0 3370 y FD(lock)p FJ(\(\))0 3470 y FD(unlock)p FJ(\(\))208 3570 y FN(Three)f(locking)g(mechanisms)g(are) h(used\227dot)f(locking)g(and,)g(if)i(a)n(v)n(ailable,)e(the)i FJ(flock\(\))e FN(and)h FJ(lockf\(\))f FN(system)h(calls.)0 3717 y FL(See)h(Also:)0 3863 y FN(mbox)e(man)h(page)f(from)g(qmail)208 3963 y(A)h(speci\002cation)g(of)g(the)g(format)f(and)h(its)h(v)n (ariations.)0 4110 y(mbox)e(man)h(page)f(from)g(tin)208 4210 y(Another)f(speci\002cation)i(of)g(the)g(format,)f(with)h(details) h(on)e(locking.)0 4356 y(Con\002guring)f(Netscape)i(Mail)h(on)g(U)t FH(N)t(I)t(X)r FN(:)27 b(Why)19 b(The)h(Content-Length)e(F)o(ormat)h (is)i(Bad)208 4456 y(An)f(ar)o(gument)e(for)h(using)h(the)g(original)f (mbox)g(format)g(rather)g(than)h(a)h(v)n(ariation.)0 4603 y(\224mbox\224)e(is)i(a)f(f)o(amily)g(of)g(se)n(v)o(eral)g (mutually)e(incompatible)h(mailbox)g(formats)208 4703 y(A)h(history)g(of)g(mbox)e(v)n(ariations.)0 4971 y FJ(MH)0 5174 y FL(class)j FD(MH)p FJ(\()p FK(path)p FC([)p FK(,)d(factory=None) p FC([)p FK(,)h(cr)m(eate=T)-5 b(rue)12 b FC(])g(])p FJ(\))208 5273 y FN(A)21 b(subclass)h(of)e FJ(Mailbox)h FN(for)f(mailbox)o(es)g(in)h(MH)h(format.)k(P)o(arameter)20 b FK(factory)h FN(is)h(a)g(callable)f(object)f(that)i(accepts)f(a)g (\002le-)208 5373 y(lik)o(e)i(message)g(representation)e(\(which)h (beha)n(v)o(es)g(as)i(if)g(opened)d(in)i(binary)f(mode\))g(and)h (returns)f(a)h(custom)g(representation.)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i (mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r(mats)1619 b(223)p eop end %%Page: 224 236 TeXDict begin 224 235 bop 208 83 a FN(If)21 b FK(factory)h FN(is)h FJ(None)p FN(,)e FJ(MHMessage)g FN(is)i(used)e(as)i(the)f(def)o (ault)f(message)g(representation.)28 b(If)22 b FK(cr)m(eate)f FN(is)i FJ(True)p FN(,)f(the)g(mailbox)208 183 y(is)f(created)e(if)i (it)g(does)e(not)h(e)o(xist.)0 330 y(MH)28 b(is)g(a)g(directory-based)c (mailbox)i(format)h(in)m(v)o(ented)e(for)i(the)g(MH)h(Message)f (Handling)f(System,)j(a)f(mail)g(user)f(agent.)46 b(Each)0 429 y(message)20 b(in)h(an)f(MH)h(mailbox)f(resides)g(in)h(its)g(o)n (wn)f(\002le.)27 b(An)20 b(MH)h(mailbox)e(may)h(contain)g(other)g(MH)g (mailbox)o(es)g(\(called)g FK(folder)o(s)p FN(\))0 529 y(in)h(addition)e(to)i(messages.)26 b(F)o(olders)20 b(may)g(be)h (nested)f(inde\002nitely)-5 b(.)24 b(MH)d(mailbox)o(es)e(also)i (support)f FK(sequences)p FN(,)f(which)h(are)h(named)0 628 y(lists)30 b(used)e(to)h(logically)f(group)f(messages)i(without)f (mo)o(ving)e(them)j(to)f(sub-folders.)49 b(Sequences)27 b(are)i(de\002ned)f(in)g(a)h(\002le)h(called)0 728 y(`)p FO(.mh)p 157 728 23 4 v 26 w(sequences)p FN(')19 b(in)h(each)g(folder) -5 b(.)0 875 y(The)25 b FJ(MH)h FN(class)g(manipulates)f(MH)g(mailbox)o (es,)h(b)n(ut)f(it)h(does)f(not)h(attempt)f(to)g(emulate)g(all)h(of)f FL(mh)p FN(')-5 b(s)27 b(beha)n(viors.)40 b(In)25 b(particular)m(,)g (it)0 975 y(does)i(not)f(modify)g(and)g(is)i(not)f(af)n(fected)f(by)g (the)h(`)p FO(conte)n(xt)p FN(')f(or)g(`)p FO(.mh)p 2052 975 V 27 w(pro\002le)p FN(')f(\002les)j(that)f(are)g(used)g(by)f FL(mh)i FN(to)f(store)g(its)h(state)g(and)0 1074 y(con\002guration.)0 1221 y FJ(MH)20 b FN(instances)g(ha)n(v)o(e)g(all)h(of)f(the)g(methods) f(of)h FJ(Mailbox)f FN(in)i(addition)e(to)h(the)g(follo)n(wing:)0 1368 y FD(list_folders)p FJ(\(\))208 1468 y FN(Return)f(a)i(list)g(of)f (the)g(names)g(of)g(all)h(folders.)0 1614 y FD(get_folder)p FJ(\()p FK(folder)r FJ(\))208 1714 y FN(Return)f(an)h FJ(MH)f FN(instance)h(representing)e(the)h(folder)g(whose)g(name)g(is)i FK(folder)r FN(.)27 b(A)21 b FJ(NoSuchMailboxError)d FN(e)o(xception)h(is)208 1814 y(raised)h(if)g(the)g(folder)f(does)h (not)g(e)o(xist.)0 1961 y FD(add_folder)p FJ(\()p FK(folder)r FJ(\))208 2060 y FN(Create)g(a)h(folder)e(whose)g(name)h(is)h FK(folder)h FN(and)e(return)f(an)h FJ(MH)g FN(instance)g(representing)e (it.)0 2207 y FD(remove_folder)p FJ(\()p FK(folder)r FJ(\))208 2307 y FN(Delete)26 b(the)g(folder)f(whose)g(name)h(is)h FK(folder)r FN(.)42 b(If)26 b(the)g(folder)f(contains)g(an)o(y)g (messages,)j(a)e FJ(NotEmptyError)e FN(e)o(xception)208 2406 y(will)c(be)h(raised)f(and)f(the)h(folder)f(will)i(not)f(be)g (deleted.)0 2553 y FD(get_sequences)p FJ(\(\))208 2653 y FN(Return)j(a)g(dictionary)f(of)h(sequence)f(names)h(mapped)f(to)i(k) o(e)o(y)f(lists.)35 b(If)24 b(there)f(are)g(no)g(sequences,)g(the)g (empty)g(dictionary)f(is)208 2752 y(returned.)0 2899 y FD(set_sequences)p FJ(\()p FK(sequences)p FJ(\))208 2999 y FN(Re-de\002ne)g(the)h(sequences)f(that)h(e)o(xist)g(in)g(the)g (mailbox)f(based)h(upon)e FK(sequences)p FN(,)i(a)g(dictionary)e(of)i (names)g(mapped)e(to)i(k)o(e)o(y)208 3099 y(lists,)e(lik)o(e)f (returned)f(by)h FJ(get_sequences\(\))p FN(.)0 3245 y FD(pack)p FJ(\(\))208 3345 y FN(Rename)27 b(messages)g(in)h(the)f (mailbox)f(as)i(necessary)f(to)h(eliminate)f(gaps)f(in)i(numbering.)44 b(Entries)27 b(in)h(the)f(sequences)f(list)208 3445 y(are)h(updated)e (correspondingly)-5 b(.)42 b FL(Note:)c FN(Already-issued)26 b(k)o(e)o(ys)h(are)g(in)m(v)n(alidated)e(by)i(this)h(operation)d(and)i (should)f(not)h(be)208 3544 y(subsequently)18 b(used.)0 3691 y(Some)i FJ(Mailbox)f FN(methods)g(implemented)g(by)h FJ(MH)g FN(deserv)o(e)f(special)h(remarks:)0 3838 y FD(remove)p FJ(\()p FK(k)o(e)n(y)p FJ(\))0 3938 y FD(__delitem__)p FJ(\()p FK(k)o(e)n(y)p FJ(\))0 4037 y FD(discard)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 4137 y FN(These)28 b(methods)f(immediately)g (delete)i(the)f(message.)50 b(The)28 b(MH)h(con)m(v)o(ention)c(of)k (marking)d(a)j(message)g(for)e(deletion)h(by)208 4237 y(prepending)17 b(a)j(comma)g(to)g(its)h(name)f(is)h(not)f(used.)0 4383 y FD(lock)p FJ(\(\))0 4483 y FD(unlock)p FJ(\(\))208 4583 y FN(Three)h(locking)f(mechanisms)h(are)h(used\227dot)f(locking)g (and,)h(if)g(a)n(v)n(ailable,)g(the)g FJ(flock\(\))f FN(and)h FJ(lockf\(\))f FN(system)h(calls.)208 4682 y(F)o(or)h(MH)h (mailbox)o(es,)f(locking)g(the)h(mailbox)e(means)i(locking)e(the)i(`)p FO(.mh)p 2379 4682 V 26 w(sequences)p FN(')e(\002le)j(and,)f(only)f (for)g(the)h(duration)e(of)208 4782 y(an)o(y)d(operations)g(that)h(af)n (fect)f(them,)h(locking)f(indi)n(vidual)f(message)i(\002les.)0 4929 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 5028 y FN(Depending)e(upon)h(the)h(host)g(platform,)e(it)j(may)f(not)g (be)g(possible)g(to)h(remo)o(v)o(e)d(the)i(underlying)e(message)i (while)g(the)g(returned)208 5128 y(\002le)g(remains)g(open.)0 5275 y FD(flush)p FJ(\(\))208 5374 y FN(All)g(changes)g(to)g(MH)g (mailbox)o(es)f(are)h(immediately)f(applied,)g(so)i(this)f(method)f (does)h(nothing.)p 0 5549 3901 4 v 0 5649 a FI(224)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 225 237 TeXDict begin 225 236 bop 0 83 a FD(close)p FJ(\(\))208 183 y(MH)20 b FN(instances)g(do)g(not)g(k)o(eep)f(an)o(y)h(open)f (\002les,)i(so)f(this)h(method)e(is)i(equi)n(v)o(elant)d(to)j FJ(unlock\(\))p FN(.)0 330 y FL(See)g(Also:)0 476 y FN(nmh)e(-)i (Message)f(Handling)f(System)208 576 y(Home)g(page)h(of)g FL(nmh)p FN(,)h(an)f(updated)e(v)o(ersion)h(of)h(the)g(original)f FL(mh)p FN(.)0 723 y(MH)i(&)f(nmh:)k(Email)c(for)g(Users)h(&)f (Programmers)208 823 y(A)g(GPL-licensed)g(book)e(on)i FL(mh)h FN(and)f FL(nmh)p FN(,)h(with)f(some)g(information)e(on)i(the)g (mailbox)f(format.)0 1091 y FJ(Babyl)0 1294 y FL(class)i FD(Babyl)p FJ(\()p FK(path)p FC([)p FK(,)d(factory=None)p FC([)p FK(,)g(cr)m(eate=T)-5 b(rue)12 b FC(])g(])p FJ(\))208 1393 y FN(A)18 b(subclass)f(of)h FJ(Mailbox)e FN(for)h(mailbox)o(es)g (in)g(Babyl)h(format.)23 b(P)o(arameter)16 b FK(factory)h FN(is)i(a)f(callable)f(object)g(that)h(accepts)f(a)h(\002le-)208 1493 y(lik)o(e)g(message)f(representation)f(\(which)h(beha)n(v)o(es)g (as)h(if)g(opened)e(in)i(binary)f(mode\))f(and)h(returns)g(a)i(custom)e (representation.)22 b(If)208 1593 y FK(factory)17 b FN(is)h FJ(None)p FN(,)g FJ(BabylMessage)d FN(is)k(used)e(as)h(the)f(def)o (ault)g(message)g(representation.)22 b(If)17 b FK(cr)m(eate)h FN(is)g FJ(True)p FN(,)f(the)h(mailbox)208 1692 y(is)j(created)e(if)i (it)g(does)e(not)h(e)o(xist.)0 1839 y(Babyl)27 b(is)g(a)g (single-\002le)g(mailbox)e(format)h(used)g(by)h(the)g(Rmail)g(mail)g (user)f(agent)g(included)g(with)h(Emacs.)44 b(The)27 b(be)o(ginning)d(of)i(a)0 1939 y(message)f(is)h(indicated)f(by)g(a)g (line)h(containing)d(the)j(tw)o(o)f(characters)g(Control-Underscore)d (\(`)p FM(n)p FJ(037)p FN('\))h(and)i(Control-L)f(\(`)p FM(n)p FJ(014)p FN('\).)0 2038 y(The)19 b(end)h(of)f(a)h(message)g(is)h (indicated)d(by)h(the)h(start)h(of)e(the)h(ne)o(xt)f(message)g(or)m(,)g (in)h(the)g(case)g(of)g(the)f(last)i(message,)e(a)i(line)e(containing)0 2138 y(a)i(Control-Underscore)16 b(\(`)p FM(n)p FJ(037)p FN('\))j(character)-5 b(.)0 2285 y(Messages)20 b(in)f(a)h(Babyl)f (mailbox)f(ha)n(v)o(e)h(tw)o(o)h(sets)g(of)f(headers,)g(original)f (headers)g(and)h(so-called)g(visible)g(headers.)24 b(V)-5 b(isible)19 b(headers)0 2384 y(are)31 b(typically)f(a)h(subset)g(of)g (the)g(original)f(headers)g(that)h(ha)n(v)o(e)f(been)g(reformatted)f (or)i(abridged)e(to)i(be)g(more)f(attracti)n(v)o(e.)56 b(Each)0 2484 y(message)27 b(in)g(a)h(Babyl)f(mailbox)f(also)h(has)h (an)f(accompan)o(ying)d(list)k(of)f FK(labels)p FN(,)i(or)d(short)h (strings)g(that)h(record)e(e)o(xtra)g(information)0 2584 y(about)19 b(the)h(message,)g(and)g(a)g(list)i(of)e(all)g(user)n (-de\002ned)f(labels)h(found)f(in)h(the)g(mailbox)f(is)i(k)o(ept)f(in)h (the)f(Babyl)g(options)f(section.)0 2731 y FJ(Babyl)h FN(instances)g(ha)n(v)o(e)g(all)g(of)g(the)g(methods)g(of)f FJ(Mailbox)h FN(in)g(addition)f(to)h(the)h(follo)n(wing:)0 2877 y FD(get_labels)p FJ(\(\))208 2977 y FN(Return)32 b(a)h(list)g(of)g(the)f(names)h(of)f(all)h(user)n(-de\002ned)e(labels)i (used)f(in)h(the)f(mailbox.)61 b FL(Note:)49 b FN(The)33 b(actual)f(messages)h(are)208 3077 y(inspected)25 b(to)h(determine)f (which)g(labels)h(e)o(xist)h(in)f(the)g(mailbox)f(rather)g(than)g (consulting)g(the)h(list)h(of)f(labels)g(in)h(the)f(Babyl)208 3176 y(options)19 b(section,)h(b)n(ut)g(the)g(Babyl)g(section)g(is)h (updated)e(whene)n(v)o(er)f(the)i(mailbox)f(is)i(modi\002ed.)0 3323 y(Some)f FJ(Mailbox)f FN(methods)g(implemented)g(by)h FJ(Babyl)f FN(deserv)o(e)g(special)i(remarks:)0 3470 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 3570 y FN(In)26 b(Babyl)g(mailbox)o(es,)h(the)g(headers)e(of)i(a)g(message)f (are)h(not)f(stored)g(contiguously)f(with)h(the)h(body)e(of)i(the)f (message.)44 b(T)-7 b(o)208 3669 y(generate)22 b(a)i(\002le-lik)o(e)g (representation,)e(the)i(headers)e(and)i(body)e(are)h(copied)g (together)f(into)i(a)g FJ(StringIO)f FN(instance)g(\(from)208 3769 y(the)j FJ(StringIO)f FN(module\),)g(which)h(has)g(an)g(API)h (identical)e(to)i(that)f(of)g(a)g(\002le.)44 b(As)26 b(a)h(result,)g(the)f(\002le-lik)o(e)h(object)e(is)i(truly)208 3869 y(independent)17 b(of)j(the)g(underlying)e(mailbox)h(b)n(ut)h (does)g(not)g(sa)n(v)o(e)g(memory)e(compared)h(to)h(a)h(string)e (representation.)0 4015 y FD(lock)p FJ(\(\))0 4115 y FD(unlock)p FJ(\(\))208 4215 y FN(Three)g(locking)g(mechanisms)g(are)h (used\227dot)f(locking)g(and,)g(if)i(a)n(v)n(ailable,)e(the)i FJ(flock\(\))e FN(and)h FJ(lockf\(\))f FN(system)h(calls.)0 4362 y FL(See)h(Also:)0 4508 y FN(F)o(ormat)e(of)h(V)-9 b(ersion)20 b(5)g(Babyl)g(Files)208 4608 y(A)g(speci\002cation)g(of)g (the)g(Babyl)g(format.)0 4755 y(Reading)f(Mail)i(with)f(Rmail)208 4855 y(The)f(Rmail)i(manual,)e(with)h(some)g(information)e(on)i(Babyl)g (semantics.)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or) r(mats)1619 b(225)p eop end %%Page: 226 238 TeXDict begin 226 237 bop 0 83 a FJ(MMDF)0 286 y FL(class)21 b FD(MMDF)p FJ(\()p FK(path)p FC([)p FK(,)d(factory=None)p FC([)p FK(,)h(cr)m(eate=T)-5 b(rue)12 b FC(])g(])p FJ(\))208 386 y FN(A)23 b(subclass)g(of)g FJ(Mailbox)f FN(for)h(mailbox)o(es)e (in)i(MMDF)h(format.)32 b(P)o(arameter)22 b FK(factory)h FN(is)h(a)f(callable)g(object)f(that)h(accepts)g(a)208 485 y(\002le-lik)o(e)f(message)g(representation)e(\(which)i(beha)n(v)o (es)f(as)i(if)g(opened)e(in)h(binary)f(mode\))g(and)h(returns)g(a)g (custom)g(representa-)208 585 y(tion.)31 b(If)22 b FK(factory)h FN(is)g FJ(None)p FN(,)g FJ(MMDFMessage)e FN(is)i(used)f(as)i(the)e (def)o(ault)g(message)g(representation.)30 b(If)22 b FK(cr)m(eate)h FN(is)g FJ(True)p FN(,)g(the)208 684 y(mailbox)18 b(is)k(created)d(if)i(it)f(does)g(not)g(e)o(xist.)0 831 y(MMDF)f(is)h(a)g(single-\002le)f(mailbox)e(format)h(in)m(v)o(ented)f (for)i(the)g(Multichannel)e(Memorandum)f(Distrib)n(ution)j(F)o(acility) -5 b(,)18 b(a)i(mail)f(trans-)0 931 y(fer)h(agent.)k(Each)19 b(message)h(is)g(in)g(the)g(same)g(form)f(as)h(an)g(mbox)f(message)g(b) n(ut)h(is)h(brack)o(eted)d(before)g(and)h(after)h(by)f(lines)h (containing)0 1031 y(four)30 b(Control-A)h(\(`)p FM(n)p FJ(001)p FN('\))e(characters.)58 b(As)32 b(with)g(the)f(mbox)f(format,) j(the)f(be)o(ginning)d(of)i(each)g(message)g(is)i(indicated)d(by)h(a)0 1130 y(line)25 b(whose)f(\002rst)i(\002)n(v)o(e)e(characters)g(are)h (\224From)f(\224,)i(b)n(ut)e(additional)g(occurrences)e(of)j(\224From)f (\224)h(are)g(not)f(transformed)e(to)j(\224\277From)f(\224)0 1230 y(when)c(storing)g(messages)h(because)f(the)h(e)o(xtra)f(message)g (separator)g(lines)h(pre)n(v)o(ent)e(mistaking)g(such)i(occurrences)e (for)h(the)g(starts)i(of)0 1329 y(subsequent)d(messages.)0 1476 y(Some)h FJ(Mailbox)f FN(methods)g(implemented)g(by)h FJ(MMDF)g FN(deserv)o(e)f(special)h(remarks:)0 1623 y FD(get_file)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 1723 y FN(Using)26 b(the)h(\002le)h(after)e(calling)h FJ(flush\(\))f FN(or)h FJ(close\(\))f FN(on)g(the)h FJ(MMDF)g FN(instance)f(may)h (yield)f(unpredictable)f(results)i(or)208 1822 y(raise)20 b(an)g(e)o(xception.)0 1969 y FD(lock)p FJ(\(\))0 2069 y FD(unlock)p FJ(\(\))208 2169 y FN(Three)f(locking)g(mechanisms)g(are) h(used\227dot)f(locking)g(and,)g(if)i(a)n(v)n(ailable,)e(the)i FJ(flock\(\))e FN(and)h FJ(lockf\(\))f FN(system)h(calls.)0 2315 y FL(See)h(Also:)0 2462 y FN(mmdf)e(man)h(page)f(from)g(tin)208 2562 y(A)h(speci\002cation)g(of)g(MMDF)g(format)f(from)g(the)i (documentation)c(of)j(tin,)g(a)g(ne)n(wsreader)-5 b(.)0 2709 y(MMDF)208 2808 y(A)20 b(W)m(ikipedia)g(article)g(describing)e (the)j(Multichannel)d(Memorandum)f(Distrib)n(ution)j(F)o(acility)-5 b(.)0 3093 y Fv(7.3.2)100 b Fm(Message)26 b Fv(objects)0 3306 y FL(class)21 b FD(Message)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 3405 y FN(A)23 b(subclass)g(of)g(the)g FJ(email.Message)d FN(module')-5 b(s)22 b FJ(Message)p FN(.)33 b(Subclasses)23 b(of)f FJ(mailbox.Message)f FN(add)h(mailbox-) 208 3505 y(format-speci\002c)c(state)j(and)e(beha)n(vior)-5 b(.)208 3638 y(If)54 b FK(messa)o(g)o(e)g FN(is)h(omitted,)62 b(the)54 b(ne)n(w)g(instance)g(is)h(created)f(in)g(a)h(def)o(ault,)62 b(empty)53 b(state.)128 b(If)54 b FK(messa)o(g)o(e)g FN(is)i(an)208 3737 y FJ(email.Message.Message)20 b FN(instance,)k(its) h(contents)e(are)g(copied;)i(furthermore,)c(an)o(y)i(format-speci\002c) f(information)208 3837 y(is)27 b(con)m(v)o(erted)d(insof)o(ar)i(as)h (possible)g(if)f FK(messa)o(g)o(e)h FN(is)h(a)f FJ(Message)f FN(instance.)43 b(If)27 b FK(messa)o(g)o(e)g FN(is)g(a)g(string)f(or)h (a)g(\002le,)h(it)g(should)208 3936 y(contain)19 b(an)h(RFC)i (2822-compliant)16 b(message,)k(which)f(is)j(read)d(and)h(parsed.)0 4083 y(The)28 b(format-speci\002c)f(state)i(and)f(beha)n(viors)f(of)n (fered)g(by)h(subclasses)h(v)n(ary)-5 b(,)29 b(b)n(ut)g(in)f(general)g (it)h(is)h(only)d(the)i(properties)e(that)i(are)0 4183 y(not)22 b(speci\002c)g(to)g(a)g(particular)f(mailbox)f(that)i(are)g (supported)e(\(although)f(presumably)h(the)i(properties)f(are)g (speci\002c)i(to)f(a)g(particular)0 4283 y(mailbox)e(format\).)28 b(F)o(or)21 b(e)o(xample,)f(\002le)i(of)n(fsets)g(for)f(single-\002le)g (mailbox)f(formats)h(and)g(\002le)h(names)f(for)g(directory-based)e (mailbox)0 4382 y(formats)e(are)h(not)g(retained,)f(because)g(the)o(y)h (are)g(only)f(applicable)g(to)h(the)g(original)f(mailbox.)23 b(But)18 b(state)h(such)f(as)g(whether)f(a)i(message)0 4482 y(has)h(been)g(read)g(by)f(the)i(user)f(or)g(mark)o(ed)e(as)j (important)e(is)i(retained,)e(because)h(it)g(applies)g(to)h(the)f (message)g(itself.)0 4629 y(There)h(is)h(no)f(requirement)e(that)j FJ(Message)f FN(instances)g(be)h(used)f(to)g(represent)g(messages)g (retrie)n(v)o(ed)f(using)h FJ(Mailbox)g FN(instances.)0 4728 y(In)d(some)g(situations,)g(the)g(time)g(and)g(memory)e(required)h (to)h(generate)f FJ(Message)g FN(representations)g(might)g(not)h(not)g (acceptable.)23 b(F)o(or)0 4828 y(such)d(situations,)h FJ(Mailbox)f FN(instances)g(also)h(of)n(fer)e(string)i(and)f (\002le-lik)o(e)g(representations,)f(and)h(a)h(custom)f(message)h(f)o (actory)e(may)0 4928 y(be)h(speci\002ed)g(when)g(a)g FJ(Mailbox)g FN(instance)f(is)j(initialized.)p 0 5549 3901 4 v 0 5649 a FI(226)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 227 239 TeXDict begin 227 238 bop 0 83 a FJ(MaildirMessage)0 286 y FL(class)21 b FD(MaildirMessage)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 386 y FN(A)26 b(message)f(with)h(Maildir)n(-speci\002c)f(beha)n(viors.)40 b(P)o(arameter)24 b FK(messa)o(g)o(e)i FN(has)g(the)g(same)f(meaning)g (as)h(with)g(the)f FJ(Message)208 485 y FN(constructor)-5 b(.)0 632 y(T)e(ypically)i(,)21 b(a)i(mail)f(user)g(agent)f (application)g(mo)o(v)o(es)g(all)h(of)g(the)g(messages)g(in)h(the)f(`)p FO(ne)o(w)p FN(')e(subdirectory)g(to)i(the)g(`)p FO(cur)p FN(')g(subdirectory)0 732 y(after)h(the)f(\002rst)i(time)f(the)g(user)g (opens)f(and)g(closes)h(the)g(mailbox,)f(recording)f(that)i(the)f (messages)h(are)g(old)g(whether)f(or)g(not)h(the)o(y')l(v)o(e)0 831 y(actually)h(been)f(read.)36 b(Each)24 b(message)g(in)g(`)p FO(cur)p FN(')g(has)g(an)g(\224info\224)f(section)h(added)f(to)h(its)h (\002le)g(name)e(to)i(store)f(information)d(about)j(its)0 931 y(state.)33 b(\(Some)22 b(mail)g(readers)g(may)g(also)h(add)f(an)h (\224info\224)e(section)i(to)f(messages)h(in)g(`)p FO(ne)o(w)p FN('.\))30 b(The)22 b(\224info\224)g(section)g(may)g(tak)o(e)h(one)f (of)0 1031 y(tw)o(o)h(forms:)30 b(it)23 b(may)g(contain)f(\2242,)-6 b(\224)22 b(follo)n(wed)g(by)g(a)h(list)h(of)f(standardized)e(\003ags)i (\(e.g.,)f(\2242,FR\224\))h(or)g(it)g(may)g(contain)e(\2241,)-6 b(\224)23 b(follo)n(wed)0 1130 y(by)d(so-called)f(e)o(xperimental)f (information.)23 b(Standard)c(\003ags)h(for)g(Maildir)g(messages)g(are) g(as)h(follo)n(ws:)1089 1356 y FL(Flag)p 1294 1386 4 100 v 98 w(Meaning)p 1707 1386 V 99 w(Explanation)p 1039 1390 1823 4 v 1089 1459 a FN(D)p 1294 1489 4 100 v 196 w(Draft)p 1707 1489 V 237 w(Under)f(composition)1089 1559 y(F)p 1294 1589 V 210 w(Flagged)p 1707 1589 V 144 w(Mark)o(ed)g(as)g(important)1089 1659 y(P)p 1294 1689 V 210 w(P)o(assed)p 1707 1689 V 188 w(F)o(orw)o(arded,)f(resent,)g(or)h (bounced)1089 1758 y(R)p 1294 1788 V 201 w(Replied)p 1707 1788 V 154 w(Replied)g(to)1089 1858 y(S)p 1294 1888 V 210 w(Seen)p 1707 1888 V 251 w(Read)1089 1958 y(T)p 1294 1987 V 205 w(T)m(rashed)p 1707 1987 V 147 w(Mark)o(ed)g(for)f (subsequent)g(deletion)0 2183 y FJ(MaildirMessage)f FN(instances)i(of)n (fer)f(the)h(follo)n(wing)f(methods:)0 2329 y FD(get_subdir)p FJ(\(\))208 2429 y FN(Return)g(either)h(\224ne)n(w\224)g(\(if)g(the)g (message)g(should)f(be)h(stored)g(in)g(the)g(`)p FO(ne)o(w)p FN(')f(subdirectory\))e(or)j(\224cur\224)f(\(if)h(the)h(message)f (should)208 2529 y(be)i(stored)h(in)g(the)g(`)p FO(cur)p FN(')f(subdirectory\).)30 b FL(Note:)g FN(A)23 b(message)g(is)h (typically)e(mo)o(v)o(ed)f(from)h(`)p FO(ne)o(w)p FN(')f(to)i(`)p FO(cur)p FN(')f(after)h(its)h(mailbox)208 2628 y(has)j(been)g (accessed,)i(whether)d(or)h(not)g(the)g(message)h(is)g(has)g(been)e (read.)46 b(A)28 b(message)f FJ(msg)g FN(has)h(been)f(read)f(if)i FJ("S")49 b(in)208 2728 y(msg.get_flags\(\))18 b FN(is)j FJ(True)p FN(.)0 2875 y FD(set_subdir)p FJ(\()p FK(subdir)r FJ(\))208 2974 y FN(Set)f(the)h(subdirectory)c(the)k(message)f(should)f (be)h(stored)g(in.)25 b(P)o(arameter)19 b FK(subdir)j FN(must)e(be)g(either)g(\224ne)n(w\224)f(or)h(\224cur\224.)0 3121 y FD(get_flags)p FJ(\(\))208 3221 y FN(Return)26 b(a)h(string)f(specifying)f(the)i(\003ags)g(that)g(are)f(currently)f (set.)45 b(If)27 b(the)f(message)h(complies)f(with)h(the)f(standard)g (Maildir)208 3321 y(format,)d(the)i(result)f(is)h(the)f(concatenation)e (in)j(alphabetical)e(order)g(of)h(zero)f(or)h(one)g(occurrence)e(of)i (each)g(of)g(`)p FJ(D)p FN(',)f(`)p FJ(F)p FN(',)h(`)p FJ(P)p FN(',)208 3420 y(`)p FJ(R)p FN(',)19 b(`)p FJ(S)p FN(',)h(and)f(`)p FJ(T)p FN('.)h(The)g(empty)f(string)h(is)h(returned)e (if)h(no)g(\003ags)g(are)h(set)g(or)e(if)i(\224info\224)e(contains)h(e) o(xperimental)e(semantics.)0 3567 y FD(set_flags)p FJ(\()p FK(\003a)o(gs)p FJ(\))208 3667 y FN(Set)i(the)h(\003ags)f(speci\002ed)g (by)g FK(\003a)o(gs)g FN(and)f(unset)h(all)h(others.)0 3814 y FD(add_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 3913 y FN(Set)i(the)f(\003ag\(s\))g(speci\002ed)g(by)g FK(\003a)o(g)g FN(without)f(changing)f(other)i(\003ags.)32 b(T)-7 b(o)22 b(add)g(more)g(than)f(one)h(\003ag)h(at)g(a)f(time,)h FK(\003a)o(g)f FN(may)g(be)208 4013 y(a)i(string)h(of)f(more)f(than)h (one)g(character)-5 b(.)37 b(The)24 b(current)f(\224info\224)h(is)h(o)o (v)o(erwritten)d(whether)i(or)g(not)g(it)h(contains)f(e)o(xperimental) 208 4112 y(information)17 b(rather)j(than)f(\003ags.)0 4259 y FD(remove_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 4359 y FN(Unset)25 b(the)g(\003ag\(s\))f(speci\002ed)h(by)f FK(\003a)o(g)g FN(without)g(changing)f(other)h(\003ags.)39 b(T)-7 b(o)25 b(remo)o(v)o(e)e(more)h(than)h(one)f(\003ag)h(at)g(a)g (time,)h FK(\003a)o(g)208 4459 y FN(maybe)e(a)j(string)f(of)f(more)g (than)h(one)f(character)-5 b(.)42 b(If)26 b(\224info\224)f(contains)g (e)o(xperimental)f(information)f(rather)i(than)h(\003ags,)i(the)208 4558 y(current)18 b(\224info\224)i(is)h(not)f(modi\002ed.)0 4705 y FD(get_date)p FJ(\(\))208 4805 y FN(Return)f(the)i(deli)n(v)o (ery)d(date)i(of)g(the)g(message)g(as)h(a)g(\003oating-point)d(number)g (representing)g(seconds)i(since)g(the)g(epoch.)0 4952 y FD(set_date)p FJ(\()p FK(date)p FJ(\))208 5051 y FN(Set)g(the)h(deli) n(v)o(ery)d(date)i(of)g(the)g(message)g(to)h FK(date)p FN(,)e(a)i(\003oating-point)d(number)g(representing)g(seconds)i(since)g (the)g(epoch.)0 5198 y FD(get_info)p FJ(\(\))208 5298 y FN(Return)k(a)h(string)g(containing)e(the)h(\224info\224)g(for)h(a)g (message.)38 b(This)25 b(is)h(useful)f(for)f(accessing)g(and)g (modifying)f(\224info\224)h(that)h(is)208 5397 y(e)o(xperimental)18 b(\(i.e.,)h(not)h(a)h(list)g(of)f(\003ags\).)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i (mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r(mats)1619 b(227)p eop end %%Page: 228 240 TeXDict begin 228 239 bop 0 83 a FD(set_info)p FJ(\()p FK(info)p FJ(\))208 183 y FN(Set)20 b(\224info\224)g(to)g FK(info)p FN(,)g(which)f(should)h(be)g(a)g(string.)0 330 y(When)30 b(a)h FJ(MaildirMessage)e FN(instance)h(is)i(created)e (based)g(upon)f(an)h FJ(mboxMessage)g FN(or)g FJ(MMDFMessage)f FN(instance,)k(the)0 429 y FO(Status:)24 b FN(and)c FO(X-Status:)k FN(headers)19 b(are)h(omitted)g(and)g(the)g(follo)n(wing)e(con)m(v)o (ersions)g(tak)o(e)i(place:)891 655 y FL(Resulting)h(state)p 1555 685 4 100 v 190 w FD(mboxMessage)e FL(or)h FD(MMDFMessage)f FL(state)p 841 689 2218 4 v 891 758 a FN(\224cur\224)h(subdirectory)p 1555 788 4 100 v 96 w(O)h(\003ag)891 858 y(F)g(\003ag)p 1555 888 V 523 w(F)g(\003ag)891 958 y(R)g(\003ag)p 1555 988 V 514 w(A)g(\003ag)891 1057 y(S)g(\003ag)p 1555 1087 V 523 w(R)g(\003ag)891 1157 y(T)g(\003ag)p 1555 1187 V 518 w(D)g(\003ag)0 1382 y(When)e(a)g FJ(MaildirMessage)e FN(instance)i(is)h(created)e(based)h(upon)e(an)i FJ(MHMessage)f FN(instance,)h(the)g(follo)n(wing)e(con)m(v)o(ersions)g(tak)o(e)0 1482 y(place:)1049 1708 y FL(Resulting)k(state)p 2066 1738 V 543 w FD(MHMessage)f FL(state)p 1000 1741 1901 4 v 1049 1811 a FN(\224cur\224)g(subdirectory)p 2066 1841 4 100 v 449 w(\224unseen\224)f(sequence)1049 1910 y(\224cur\224)h(subdirectory)e(and)h(S)i(\003ag)p 2066 1940 V 99 w(no)f(\224unseen\224)f(sequence)1049 2010 y(F)i(\003ag)p 2066 2040 V 876 w(\224\003agged\224)e(sequence)1049 2110 y(R)j(\003ag)p 2066 2140 V 866 w(\224replied\224)d(sequence)0 2335 y(When)k(a)g FJ(MaildirMessage)d FN(instance)j(is)g(created)f (based)h(upon)e(a)i FJ(BabylMessage)e FN(instance,)i(the)g(follo)n (wing)e(con)m(v)o(ersions)0 2434 y(tak)o(e)f(place:)927 2661 y FL(Resulting)g(state)p 1943 2691 V 544 w FD(BabylMessage)e FL(state)p 877 2694 2147 4 v 927 2764 a FN(\224cur\224)h(subdirectory)p 1943 2794 4 100 v 450 w(\224unseen\224)g(label)927 2863 y(\224cur\224)g(subdirectory)f(and)i(S)g(\003ag)p 1943 2893 V 100 w(no)f(\224unseen\224)g(label)927 2963 y(P)i(\003ag)p 1943 2993 V 876 w(\224forw)o(arded\224)c(or)j(\224resent\224)g(label) 927 3062 y(R)h(\003ag)p 1943 3092 V 867 w(\224answered\224)e(label)927 3162 y(T)h(\003ag)p 1943 3192 V 872 w(\224deleted\224)f(label)0 3422 y FJ(mboxMessage)0 3624 y FL(class)i FD(mboxMessage)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 3724 y FN(A)29 b(message)g(with)h(mbox-speci\002c)d(beha)n(viors.)51 b(P)o(arameter)28 b FK(messa)o(g)o(e)i FN(has)f(the)g(same)h(meaning)e (as)i(with)f(the)g FJ(Message)208 3824 y FN(constructor)-5 b(.)0 3971 y(Messages)29 b(in)h(an)f(mbox)f(mailbox)f(are)i(stored)g (together)f(in)h(a)h(single)f(\002le.)52 b(The)29 b(sender')-5 b(s)28 b(en)m(v)o(elope)f(address)i(and)f(the)i(time)f(of)0 4070 y(deli)n(v)o(ery)23 b(are)i(typically)f(stored)g(in)h(a)h(line)f (be)o(ginning)d(with)j(\224From)f(\224)i(that)f(is)g(used)g(to)g (indicate)f(the)h(start)h(of)e(a)i(message,)f(though)0 4170 y(there)e(is)h(considerable)e(v)n(ariation)g(in)h(the)h(e)o(xact)f (format)f(of)h(this)h(data)g(among)e(mbox)g(implementations.)32 b(Flags)24 b(that)g(indicate)f(the)0 4269 y(state)29 b(of)e(the)h(message,)i(such)e(as)g(whether)f(it)i(has)f(been)g(read)f (or)h(mark)o(ed)f(as)h(important,)g(are)g(typically)g(stored)f(in)h FO(Status:)40 b FN(and)0 4369 y FO(X-Status:)24 b FN(headers.)0 4516 y(Con)m(v)o(entional)18 b(\003ags)i(for)g(mbox)f(messages)h(are)g (as)h(follo)n(ws:)1077 4742 y FL(Flag)p 1282 4772 V 99 w(Meaning)p 1718 4772 V 122 w(Explanation)p 1027 4775 1846 4 v 1077 4845 a FN(R)p 1282 4875 4 100 v 202 w(Read)p 1718 4875 V 265 w(Read)1077 4945 y(O)p 1282 4975 V 197 w(Old)p 1718 4975 V 311 w(Pre)n(viously)e(detected)g(by)h(MU)m(A)1077 5044 y(D)p 1282 5074 V 197 w(Deleted)p 1718 5074 V 177 w(Mark)o(ed)f(for)h(subsequent)e(deletion)1077 5144 y(F)p 1282 5174 V 211 w(Flagged)p 1718 5174 V 167 w(Mark)o(ed)h(as)i (important)1077 5244 y(A)p 1282 5274 V 197 w(Answered)p 1718 5274 V 98 w(Replied)f(to)p 0 5549 3901 4 v 0 5649 a FI(228)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 229 241 TeXDict begin 229 240 bop 0 83 a FN(The)25 b(\224R\224)h(and)f (\224O\224)h(\003ags)f(are)h(stored)f(in)g(the)h FO(Status:)34 b FN(header)m(,)25 b(and)g(the)h(\224D\224,)g(\224F\224,)h(and)e (\224A\224)h(\003ags)f(are)h(stored)f(in)g(the)h FO(X-Status:)0 183 y FN(header)-5 b(.)24 b(The)c(\003ags)h(and)e(headers)h(typically)f (appear)g(in)h(the)g(order)f(mentioned.)0 330 y FJ(mboxMessage)g FN(instances)h(of)n(fer)f(the)h(follo)n(wing)f(methods:)0 476 y FD(get_from)p FJ(\(\))208 576 y FN(Return)28 b(a)g(string)h (representing)d(the)i(\224From)g(\224)h(line)g(that)f(marks)g(the)h (start)f(of)h(the)f(message)g(in)h(an)f(mbox)g(mailbox.)48 b(The)208 676 y(leading)19 b(\224From)g(\224)i(and)f(the)g(trailing)f (ne)n(wline)h(are)g(e)o(xcluded.)0 823 y FD(set_from)p FJ(\()p FK(fr)l(om)p 608 823 25 4 v 28 w FC([)p FK(,)h(time)p 861 823 V 29 w(=None)12 b FC(])p FJ(\))208 922 y FN(Set)27 b(the)h(\224From)e(\224)i(line)f(to)g FK(fr)l(om)p 1182 922 V 30 w FN(,)i(which)e(should)f(be)h(speci\002ed)g(without)g(a)g (leading)f(\224From)h(\224)g(or)g(trailing)g(ne)n(wline.)45 b(F)o(or)208 1022 y(con)m(v)o(enience,)27 b FK(time)p 818 1022 V 59 w FN(may)h(be)g(speci\002ed)h(and)f(will)h(be)f (formatted)f(appropriately)f(and)i(appended)e(to)j FK(fr)l(om)p 3462 1022 V 30 w FN(.)50 b(If)29 b FK(time)p 3791 1022 V 59 w FN(is)208 1121 y(speci\002ed,)j(it)g(should)d(be)i(a)g FJ(struct_time)e FN(instance,)j(a)f(tuple)g(suitable)f(for)g(passing)g (to)h FJ(time.strftime\(\))p FN(,)g(or)208 1221 y FJ(True)20 b FN(\(to)g(use)g FJ(time.gmtime\(\))p FN(\).)0 1368 y FD(get_flags)p FJ(\(\))208 1468 y FN(Return)e(a)i(string)f (specifying)f(the)i(\003ags)f(that)h(are)f(currently)f(set.)25 b(If)19 b(the)h(message)f(complies)g(with)g(the)h(con)m(v)o(entional)c (format,)208 1567 y(the)k(result)h(is)h(the)f(concatenation)d(in)j(the) g(follo)n(wing)e(order)g(of)i(zero)f(or)g(one)h(occurrence)d(of)j(each) f(of)g(`)p FJ(R)p FN(',)h(`)p FJ(O)p FN(',)f(`)p FJ(D)p FN(',)g(`)p FJ(F)p FN(',)g(and)208 1667 y(`)p FJ(A)p FN('.)0 1814 y FD(set_flags)p FJ(\()p FK(\003a)o(gs)p FJ(\))208 1913 y FN(Set)h(the)g(\003ags)g(speci\002ed)f(by)h FK(\003a)o(gs)f FN(and)g(unset)h(all)g(others.)26 b(P)o(arameter)20 b FK(\003a)o(gs)g FN(should)g(be)g(the)h(concatenation)e(in)h(an)o(y)g (order)g(of)208 2013 y(zero)f(or)h(more)f(occurrences)g(of)h(each)f(of) h(`)p FJ(R)p FN(',)g(`)p FJ(O)p FN(',)g(`)p FJ(D)p FN(',)f(`)p FJ(F)p FN(',)h(and)f(`)p FJ(A)p FN('.)0 2160 y FD(add_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2259 y FN(Set)h(the)g(\003ag\(s\))f (speci\002ed)h(by)f FK(\003a)o(g)g FN(without)h(changing)d(other)i (\003ags.)26 b(T)-7 b(o)20 b(add)f(more)g(than)g(one)h(\003ag)f(at)i(a) f(time,)g FK(\003a)o(g)f FN(may)g(be)h(a)208 2359 y(string)f(of)h(more) g(than)f(one)h(character)-5 b(.)0 2506 y FD(remove_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2606 y FN(Unset)25 b(the)g (\003ag\(s\))f(speci\002ed)h(by)f FK(\003a)o(g)g FN(without)g(changing) f(other)h(\003ags.)39 b(T)-7 b(o)25 b(remo)o(v)o(e)e(more)h(than)h(one) f(\003ag)h(at)g(a)g(time,)h FK(\003a)o(g)208 2705 y FN(maybe)19 b(a)h(string)g(of)g(more)f(than)h(one)g(character)-5 b(.)0 2852 y(When)20 b(an)g FJ(mboxMessage)f FN(instance)h(is)h (created)f(based)f(upon)g(a)i FJ(MaildirMessage)d FN(instance,)i(a)g (\224From)g(\224)h(line)f(is)h(generated)0 2952 y(based)f(upon)f(the)h FJ(MaildirMessage)e FN(instance')-5 b(s)20 b(deli)n(v)o(ery)f(date,)g (and)h(the)g(follo)n(wing)f(con)m(v)o(ersions)f(tak)o(e)i(place:)1196 3143 y FL(Resulting)h(state)p 1768 3173 4 100 v 98 w FD(MaildirMessage)e FL(state)p 1147 3176 1607 4 v 1196 3246 a FN(R)j(\003ag)p 1768 3276 4 100 v 421 w(S)f(\003ag)1196 3346 y(O)g(\003ag)p 1768 3376 V 417 w(\224cur\224)f(subdirectory)1196 3445 y(D)h(\003ag)p 1768 3475 V 417 w(T)g(\003ag)1196 3545 y(F)g(\003ag)p 1768 3575 V 431 w(F)g(\003ag)1196 3645 y(A)g(\003ag)p 1768 3675 V 417 w(R)h(\003ag)0 3835 y(When)k(an)h FJ(mboxMessage)e FN(instance)h(is)i(created)e(based)g (upon)f(an)i FJ(MHMessage)e FN(instance,)j(the)e(follo)n(wing)f(con)m (v)o(ersions)g(tak)o(e)0 3935 y(place:)1250 4126 y FL(Resulting)20 b(state)p 1865 4156 V 143 w FD(MHMessage)f FL(state)p 1200 4160 1500 4 v 1250 4229 a FN(R)i(\003ag)f(and)g(O)h(\003ag)p 1865 4259 4 100 v 99 w(no)f(\224unseen\224)f(sequence)1250 4329 y(O)i(\003ag)p 1865 4359 V 461 w(\224unseen\224)e(sequence)1250 4429 y(F)i(\003ag)p 1865 4458 V 475 w(\224\003agged\224)e(sequence)1250 4528 y(A)i(\003ag)p 1865 4558 V 461 w(\224replied\224)e(sequence)0 4719 y(When)g(an)g FJ(mboxMessage)e FN(instance)i(is)h(created)e(based) h(upon)e(a)j FJ(BabylMessage)d FN(instance,)i(the)g(follo)n(wing)e(con) m(v)o(ersions)g(tak)o(e)0 4818 y(place:)1224 5010 y FL(Resulting)k (state)p 1840 5040 V 142 w FD(BabylMessage)e FL(state)p 1174 5043 1552 4 v 1224 5113 a FN(R)i(\003ag)g(and)e(O)i(\003ag)p 1840 5143 4 100 v 99 w(no)f(\224unseen\224)f(label)1224 5212 y(O)i(\003ag)p 1840 5242 V 461 w(\224unseen\224)e(label)1224 5312 y(D)i(\003ag)p 1840 5342 V 461 w(\224deleted\224)e(label)1224 5412 y(A)i(\003ag)p 1840 5442 V 461 w(\224answered\224)e(label)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r (mats)1619 b(229)p eop end %%Page: 230 242 TeXDict begin 230 241 bop 0 83 a FN(When)18 b(a)h FJ(Message)e FN(instance)h(is)i(created)d(based)h(upon)f(an)h FJ(MMDFMessage)f FN(instance,)h(the)g(\224From)g(\224)h(line)f(is)h(copied)f(and)f(all)i (\003ags)0 183 y(directly)g(correspond:)1271 409 y FL(Resulting)i (state)p 1843 439 4 100 v 98 w FD(MMDFMessage)e FL(state)p 1221 442 1458 4 v 1271 512 a FN(R)i(\003ag)p 1843 542 4 100 v 422 w(R)g(\003ag)1271 612 y(O)g(\003ag)p 1843 641 V 417 w(O)g(\003ag)1271 711 y(D)g(\003ag)p 1843 741 V 417 w(D)g(\003ag)1271 811 y(F)g(\003ag)p 1843 841 V 431 w(F)g(\003ag)1271 910 y(A)g(\003ag)p 1843 940 V 417 w(A)g(\003ag)0 1164 y FJ(MHMessage)0 1367 y FL(class)g FD(MHMessage)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 1467 y FN(A)22 b(message)g(with)g(MH-speci\002c)g(beha)n (viors.)29 b(P)o(arameter)21 b FK(messa)o(g)o(e)i FN(has)f(the)g(same)g (meaning)f(as)i(with)f(the)g FJ(Message)f FN(con-)208 1566 y(structor)-5 b(.)0 1713 y(MH)21 b(messages)h(do)e(not)h(support)f (marks)g(or)h(\003ags)h(in)f(the)g(traditional)f(sense,)h(b)n(ut)g(the) o(y)g(do)g(support)e(sequences,)h(which)h(are)g(logical)0 1813 y(groupings)15 b(of)j(arbitrary)e(messages.)25 b(Some)17 b(mail)h(reading)e(programs)g(\(although)g(not)h(the)h(standard)f FL(mh)i FN(and)e FL(nmh)p FN(\))h(use)g(sequences)0 1913 y(in)i(much)g(the)g(same)g(w)o(ay)g(\003ags)h(are)f(used)g(with)g (other)g(formats,)f(as)i(follo)n(ws:)1026 2139 y FL(Sequence)p 1407 2169 V 100 w(Explanation)p 977 2172 1947 4 v 1026 2242 a FN(unseen)p 1407 2272 4 100 v 200 w(Not)f(read,)g(b)n(ut)g(pre)n (viously)e(detected)i(by)f(MU)m(A)1026 2341 y(replied)p 1407 2371 V 200 w(Replied)h(to)1026 2441 y(\003agged)p 1407 2471 V 186 w(Mark)o(ed)f(as)i(important)0 2666 y FJ(MHMessage)e FN(instances)h(of)n(fer)f(the)h(follo)n(wing)f(methods:) 0 2813 y FD(get_sequences)p FJ(\(\))208 2913 y FN(Return)g(a)i(list)g (of)f(the)g(names)g(of)g(sequences)f(that)i(include)e(this)i(message.)0 3059 y FD(set_sequences)p FJ(\()p FK(sequences)p FJ(\))208 3159 y FN(Set)f(the)h(list)g(of)f(sequences)f(that)h(include)g(this)g (message.)0 3306 y FD(add_sequence)p FJ(\()p FK(sequence)p FJ(\))208 3406 y FN(Add)f FK(sequence)g FN(to)i(the)f(list)h(of)f (sequences)f(that)i(include)e(this)i(message.)0 3552 y FD(remove_sequence)p FJ(\()p FK(sequence)p FJ(\))208 3652 y FN(Remo)o(v)o(e)e FK(sequence)g FN(from)g(the)h(list)h(of)f (sequences)f(that)i(include)e(this)i(message.)0 3799 y(When)e(an)g FJ(MHMessage)f FN(instance)g(is)i(created)e(based)h(upon) f(a)h FJ(MaildirMessage)e FN(instance,)i(the)g(follo)n(wing)e(con)m(v)o (ersions)g(tak)o(e)0 3899 y(place:)1137 4125 y FL(Resulting)j(state)p 1828 4155 V 218 w FD(MaildirMessage)e FL(state)p 1087 4158 1727 4 v 1137 4228 a FN(\224unseen\224)h(sequence)p 1828 4258 4 100 v 111 w(no)h(S)h(\003ag)1137 4327 y(\224replied\224)e (sequence)p 1828 4357 V 111 w(R)i(\003ag)1137 4427 y(\224\003agged\224) d(sequence)p 1828 4457 V 98 w(F)j(\003ag)0 4652 y(When)26 b(an)h FJ(MHMessage)f FN(instance)g(is)h(created)f(based)h(upon)e(an)h FJ(mboxMessage)g FN(or)g FJ(MMDFMessage)f FN(instance,)j(the)e FO(Status:)0 4752 y FN(and)20 b FO(X-Status:)k FN(headers)19 b(are)h(omitted)g(and)f(the)h(follo)n(wing)f(con)m(v)o(ersions)f(tak)o (e)i(place:)877 4978 y FL(Resulting)h(state)p 1569 5008 V 218 w FD(mboxMessage)e FL(or)h FD(MMDFMessage)f FL(state)p 828 5011 2245 4 v 877 5081 a FN(\224unseen\224)g(sequence)p 1569 5111 4 100 v 112 w(no)h(R)h(\003ag)877 5181 y(\224replied\224)e (sequence)p 1569 5211 V 112 w(A)i(\003ag)877 5280 y(\224\003agged\224)e (sequence)p 1569 5310 V 98 w(F)i(\003ag)p 0 5549 3901 4 v 0 5649 a FI(230)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 231 243 TeXDict begin 231 242 bop 0 83 a FN(When)26 b(an)g FJ(MHMessage)f FN(instance)g(is)i(created)f(based)f(upon)g(a)h FJ(BabylMessage)f FN(instance,)h(the)h(follo)n(wing)d(con)m(v)o(ersions)g(tak)o(e)0 183 y(place:)1193 387 y FL(Resulting)d(state)p 1871 416 4 100 v 204 w FD(BabylMessage)e FL(state)p 1143 420 1614 4 v 1193 490 a FN(\224unseen\224)g(sequence)p 1871 519 4 100 v 98 w(\224unseen\224)g(label)1193 589 y(\224replied\224)g (sequence)p 1871 619 V 98 w(\224answered\224)g(label)0 845 y FJ(BabylMessage)0 1047 y FL(class)i FD(BabylMessage)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 1147 y FN(A)29 b(message)f(with)h(Babyl-speci\002c)f(beha)n(viors.)49 b(P)o(arameter)28 b FK(messa)o(g)o(e)h FN(has)g(the)f(same)h(meaning)e (as)j(with)f(the)f FJ(Message)208 1247 y FN(constructor)-5 b(.)0 1394 y(Certain)26 b(message)f(labels,)i(called)e FK(attrib)n(utes)p FN(,)i(are)e(de\002ned)g(by)g(con)m(v)o(ention)e(to) i(ha)n(v)o(e)g(special)h(meanings.)40 b(The)25 b(attrib)n(utes)g(are)h (as)0 1493 y(follo)n(ws:)1022 1680 y FL(Label)p 1411 1710 V 237 w(Explanation)p 972 1714 1956 4 v 1022 1783 a FN(unseen)p 1411 1813 4 100 v 208 w(Not)20 b(read,)g(b)n(ut)g(pre)n (viously)e(detected)i(by)f(MU)m(A)1022 1883 y(deleted)p 1411 1913 V 199 w(Mark)o(ed)g(for)h(subsequent)f(deletion)1022 1983 y(\002led)p 1411 2012 V 292 w(Copied)h(to)g(another)f(\002le)i(or) f(mailbox)1022 2082 y(answered)p 1411 2112 V 125 w(Replied)g(to)1022 2182 y(forw)o(arded)p 1411 2212 V 97 w(F)o(orw)o(arded)1022 2281 y(edited)p 1411 2311 V 236 w(Modi\002ed)f(by)h(the)g(user)1022 2381 y(resent)p 1411 2411 V 241 w(Resent)0 2584 y(By)c(def)o(ault,)g (Rmail)g(displays)f(only)g(visible)h(headers.)23 b(The)15 b FJ(BabylMessage)f FN(class,)j(though,)e(uses)h(the)g(original)e (headers)h(because)0 2683 y(the)o(y)k(are)i(more)e(complete.)24 b(V)-5 b(isible)20 b(headers)g(may)f(be)i(accessed)f(e)o(xplicitly)f (if)h(desired.)0 2830 y FJ(BabylMessage)f FN(instances)h(of)n(fer)f (the)h(follo)n(wing)e(methods:)0 2977 y FD(get_labels)p FJ(\(\))208 3077 y FN(Return)h(a)i(list)g(of)f(labels)h(on)e(the)i (message.)0 3224 y FD(set_labels)p FJ(\()p FK(labels)p FJ(\))208 3323 y FN(Set)f(the)h(list)g(of)f(labels)g(on)g(the)g (message)g(to)h FK(labels)p FN(.)0 3470 y FD(add_label)p FJ(\()p FK(label)p FJ(\))208 3570 y FN(Add)e FK(label)h FN(to)g(the)h(list)g(of)f(labels)g(on)g(the)g(message.)0 3717 y FD(remove_label)p FJ(\()p FK(label)p FJ(\))208 3816 y FN(Remo)o(v)o(e)f FK(label)g FN(from)h(the)g(list)h(of)f(labels) g(on)g(the)g(message.)0 3963 y FD(get_visible)p FJ(\(\))208 4063 y FN(Return)f(an)h FJ(Message)g FN(instance)g(whose)g(headers)f (are)h(the)g(message')-5 b(s)21 b(visible)f(headers)f(and)h(whose)g (body)e(is)k(empty)-5 b(.)0 4210 y FD(set_visible)p FJ(\()p FK(visible)p FJ(\))208 4309 y FN(Set)31 b(the)f(message')-5 b(s)30 b(visible)h(headers)e(to)h(be)h(the)f(same)g(as)h(the)g(headers) e(in)h FK(messa)o(g)o(e)p FN(.)56 b(P)o(arameter)29 b FK(visible)i FN(should)e(be)h(a)208 4409 y FJ(Message)20 b FN(instance,)i(an)g FJ(email.Message.Message)c FN(instance,)j(a)h (string,)g(or)f(a)h(\002le-lik)o(e)g(object)f(\(which)g(should)g(be)208 4509 y(open)e(in)h(te)o(xt)g(mode\).)0 4655 y FD(update_visible)p FJ(\(\))208 4755 y FN(When)27 b(a)h FJ(BabylMessage)e FN(instance')-5 b(s)27 b(original)g(headers)f(are)i(modi\002ed,)g(the)f (visible)h(headers)e(are)i(not)f(automatically)208 4855 y(modi\002ed)22 b(to)h(correspond.)31 b(This)24 b(method)e(updates)g (the)h(visible)h(headers)e(as)i(follo)n(ws:)31 b(each)23 b(visible)g(header)f(with)h(a)h(corre-)208 4954 y(sponding)c(original)h (header)g(is)i(set)g(to)g(the)f(v)n(alue)g(of)g(the)g(original)f (header)m(,)g(each)h(visible)h(header)e(without)g(a)i(corresponding)208 5054 y(original)i(header)g(is)i(remo)o(v)o(ed,)e(and)h(an)o(y)f(of)h FO(Date:)p FN(,)h FO(F)m(rom:)p FN(,)g FO(Reply-T)-9 b(o:)p FN(,)26 b FO(T)-9 b(o:)p FN(,)27 b FO(CC:)p FN(,)g(and)f FO(Subject:)36 b FN(that)26 b(are)h(present)e(in)i(the)208 5154 y(original)19 b(headers)g(b)n(ut)h(not)g(the)g(visible)g(headers)g (are)g(added)f(to)h(the)g(visible)g(headers.)0 5300 y(When)j(a)g FJ(BabylMessage)e FN(instance)h(is)i(created)e(based)g(upon)g(a)h FJ(MaildirMessage)d FN(instance,)j(the)g(follo)n(wing)e(con)m(v)o (ersions)0 5400 y(tak)o(e)f(place:)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n (x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r(mats)1619 b(231)p eop end %%Page: 232 244 TeXDict begin 232 243 bop 1160 70 a FL(Resulting)21 b(state)p 1804 100 4 100 v 171 w FD(MaildirMessage)d FL(state)p 1110 103 1680 4 v 1160 173 a FN(\224unseen\224)h(label)p 1804 203 4 100 v 209 w(no)h(S)h(\003ag)1160 272 y(\224deleted\224)e (label)p 1804 302 V 200 w(T)h(\003ag)1160 372 y(\224answered\224)f (label)p 1804 402 V 126 w(R)i(\003ag)1160 472 y(\224forw)o(arded\224)d (label)p 1804 501 V 99 w(P)j(\003ag)0 697 y(When)e(a)g FJ(BabylMessage)f FN(instance)g(is)i(created)f(based)f(upon)g(an)h FJ(mboxMessage)e FN(or)i FJ(MMDFMessage)f FN(instance,)g(the)h FO(Status:)0 796 y FN(and)h FO(X-Status:)k FN(headers)19 b(are)h(omitted)g(and)f(the)h(follo)n(wing)f(con)m(v)o(ersions)f(tak)o (e)i(place:)914 1023 y FL(Resulting)h(state)p 1532 1052 V 144 w FD(mboxMessage)e FL(or)h FD(MMDFMessage)f FL(state)p 864 1056 2172 4 v 914 1125 a FN(\224unseen\224)g(label)p 1532 1155 4 100 v 182 w(no)h(R)h(\003ag)914 1225 y(\224deleted\224)f (label)p 1532 1255 V 172 w(D)h(\003ag)914 1325 y(\224answered\224)e (label)p 1532 1355 V 99 w(A)i(\003ag)0 1550 y(When)26 b(a)g FJ(BabylMessage)f FN(instance)g(is)i(created)f(based)f(upon)g(an) h FJ(MHMessage)f FN(instance,)h(the)h(follo)n(wing)d(con)m(v)o(ersions) g(tak)o(e)0 1649 y(place:)1298 1876 y FL(Resulting)c(state)p 1916 1906 V 145 w FD(MHMessage)f FL(state)p 1248 1909 1404 4 v 1298 1979 a FN(\224unseen\224)g(label)p 1916 2009 4 100 v 182 w(\224unseen\224)g(sequence)1298 2078 y(\224answered\224)g(label)p 1916 2108 V 99 w(\224replied\224)g (sequence)0 2332 y FJ(MMDFMessage)0 2535 y FL(class)i FD(MMDFMessage)p FJ(\()p FC([)p FK(messa)o(g)o(e)12 b FC(])p FJ(\))208 2635 y FN(A)25 b(message)g(with)h(MMDF-speci\002c)f (beha)n(viors.)38 b(P)o(arameter)24 b FK(messa)o(g)o(e)i FN(has)f(the)h(same)f(meaning)f(as)i(with)f(the)g FJ(Message)208 2734 y FN(constructor)-5 b(.)0 2881 y(As)22 b(with)g(message)f(in)h(an) f(mbox)g(mailbox,)f(MMDF)i(messages)f(are)h(stored)f(with)g(the)h (sender')-5 b(s)21 b(address)g(and)g(the)g(deli)n(v)o(ery)f(date)h(in)0 2981 y(an)26 b(initial)g(line)g(be)o(ginning)d(with)j(\224From)f(\224.) 43 b(Lik)o(e)n(wise,)27 b(\003ags)f(that)g(indicate)f(the)h(state)g(of) g(the)g(message)f(are)h(typically)f(stored)g(in)0 3080 y FO(Status:)f FN(and)c FO(X-Status:)k FN(headers.)0 3227 y(Con)m(v)o(entional)18 b(\003ags)i(for)g(MMDF)g(messages)h(are)f (identical)f(to)i(those)f(of)g(mbox)e(message)j(and)e(are)h(as)h(follo) n(ws:)1077 3454 y FL(Flag)p 1282 3484 V 99 w(Meaning)p 1718 3484 V 122 w(Explanation)p 1027 3487 1846 4 v 1077 3557 a FN(R)p 1282 3586 4 100 v 202 w(Read)p 1718 3586 V 265 w(Read)1077 3656 y(O)p 1282 3686 V 197 w(Old)p 1718 3686 V 311 w(Pre)n(viously)e(detected)g(by)h(MU)m(A)1077 3756 y(D)p 1282 3786 V 197 w(Deleted)p 1718 3786 V 177 w(Mark)o(ed)f(for)h(subsequent)e(deletion)1077 3855 y(F)p 1282 3885 V 211 w(Flagged)p 1718 3885 V 167 w(Mark)o(ed)h(as)i (important)1077 3955 y(A)p 1282 3985 V 197 w(Answered)p 1718 3985 V 98 w(Replied)f(to)0 4180 y(The)25 b(\224R\224)h(and)f (\224O\224)h(\003ags)f(are)h(stored)f(in)g(the)h FO(Status:)34 b FN(header)m(,)25 b(and)g(the)h(\224D\224,)g(\224F\224,)h(and)e (\224A\224)h(\003ags)f(are)h(stored)f(in)g(the)h FO(X-Status:)0 4280 y FN(header)-5 b(.)24 b(The)c(\003ags)h(and)e(headers)h(typically) f(appear)g(in)h(the)g(order)f(mentioned.)0 4427 y FJ(MMDFMessage)g FN(instances)h(of)n(fer)f(the)h(follo)n(wing)f(methods,)f(which)i(are)g (identical)g(to)g(those)g(of)n(fered)f(by)g FJ(mboxMessage)p FN(:)0 4574 y FD(get_from)p FJ(\(\))208 4673 y FN(Return)28 b(a)g(string)h(representing)d(the)i(\224From)g(\224)h(line)g(that)f (marks)g(the)h(start)f(of)h(the)f(message)g(in)h(an)f(mbox)g(mailbox.) 48 b(The)208 4773 y(leading)19 b(\224From)g(\224)i(and)f(the)g (trailing)f(ne)n(wline)h(are)g(e)o(xcluded.)0 4920 y FD(set_from)p FJ(\()p FK(fr)l(om)p 608 4920 25 4 v 28 w FC([)p FK(,)h(time)p 861 4920 V 29 w(=None)12 b FC(])p FJ(\))208 5019 y FN(Set)27 b(the)h(\224From)e(\224)i(line)f(to)g FK(fr)l(om)p 1182 5019 V 30 w FN(,)i(which)e(should)f(be)h(speci\002ed) g(without)g(a)g(leading)f(\224From)h(\224)g(or)g(trailing)g(ne)n (wline.)45 b(F)o(or)208 5119 y(con)m(v)o(enience,)27 b FK(time)p 818 5119 V 59 w FN(may)h(be)g(speci\002ed)h(and)f(will)h (be)f(formatted)f(appropriately)f(and)i(appended)e(to)j FK(fr)l(om)p 3462 5119 V 30 w FN(.)50 b(If)29 b FK(time)p 3791 5119 V 59 w FN(is)208 5219 y(speci\002ed,)j(it)g(should)d(be)i(a)g FJ(struct_time)e FN(instance,)j(a)f(tuple)g(suitable)f(for)g(passing)g (to)h FJ(time.strftime\(\))p FN(,)g(or)208 5318 y FJ(True)20 b FN(\(to)g(use)g FJ(time.gmtime\(\))p FN(\).)p 0 5549 3901 4 v 0 5649 a FI(232)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 233 245 TeXDict begin 233 244 bop 0 83 a FD(get_flags)p FJ(\(\))208 183 y FN(Return)18 b(a)i(string)f(specifying)f(the)i(\003ags)f(that)h (are)f(currently)f(set.)25 b(If)19 b(the)h(message)f(complies)g(with)g (the)h(con)m(v)o(entional)c(format,)208 282 y(the)k(result)h(is)h(the)f (concatenation)d(in)j(the)g(follo)n(wing)e(order)g(of)i(zero)f(or)g (one)h(occurrence)d(of)j(each)f(of)g(`)p FJ(R)p FN(',)h(`)p FJ(O)p FN(',)f(`)p FJ(D)p FN(',)g(`)p FJ(F)p FN(',)g(and)208 382 y(`)p FJ(A)p FN('.)0 529 y FD(set_flags)p FJ(\()p FK(\003a)o(gs)p FJ(\))208 628 y FN(Set)h(the)g(\003ags)g(speci\002ed)f (by)h FK(\003a)o(gs)f FN(and)g(unset)h(all)g(others.)26 b(P)o(arameter)20 b FK(\003a)o(gs)g FN(should)g(be)g(the)h (concatenation)e(in)h(an)o(y)g(order)g(of)208 728 y(zero)f(or)h(more)f (occurrences)g(of)h(each)f(of)h(`)p FJ(R)p FN(',)g(`)p FJ(O)p FN(',)g(`)p FJ(D)p FN(',)f(`)p FJ(F)p FN(',)h(and)f(`)p FJ(A)p FN('.)0 875 y FD(add_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 975 y FN(Set)h(the)g(\003ag\(s\))f(speci\002ed)h(by)f FK(\003a)o(g)g FN(without)h(changing)d(other)i(\003ags.)26 b(T)-7 b(o)20 b(add)f(more)g(than)g(one)h(\003ag)f(at)i(a)f(time,)g FK(\003a)o(g)f FN(may)g(be)h(a)208 1074 y(string)f(of)h(more)g(than)f (one)h(character)-5 b(.)0 1221 y FD(remove_flag)p FJ(\()p FK(\003a)o(g)p FJ(\))208 1321 y FN(Unset)25 b(the)g(\003ag\(s\))f (speci\002ed)h(by)f FK(\003a)o(g)g FN(without)g(changing)f(other)h (\003ags.)39 b(T)-7 b(o)25 b(remo)o(v)o(e)e(more)h(than)h(one)f(\003ag) h(at)g(a)g(time,)h FK(\003a)o(g)208 1420 y FN(maybe)19 b(a)h(string)g(of)g(more)f(than)h(one)g(character)-5 b(.)0 1567 y(When)20 b(an)g FJ(MMDFMessage)f FN(instance)h(is)h (created)f(based)f(upon)g(a)i FJ(MaildirMessage)d FN(instance,)i(a)g (\224From)g(\224)h(line)f(is)h(generated)0 1667 y(based)f(upon)f(the)h FJ(MaildirMessage)e FN(instance')-5 b(s)20 b(deli)n(v)o(ery)f(date,)g (and)h(the)g(follo)n(wing)f(con)m(v)o(ersions)f(tak)o(e)i(place:)1196 1893 y FL(Resulting)h(state)p 1768 1923 4 100 v 98 w FD(MaildirMessage)e FL(state)p 1147 1926 1607 4 v 1196 1996 a FN(R)j(\003ag)p 1768 2026 4 100 v 421 w(S)f(\003ag)1196 2096 y(O)g(\003ag)p 1768 2126 V 417 w(\224cur\224)f(subdirectory)1196 2195 y(D)h(\003ag)p 1768 2225 V 417 w(T)g(\003ag)1196 2295 y(F)g(\003ag)p 1768 2325 V 431 w(F)g(\003ag)1196 2395 y(A)g(\003ag)p 1768 2424 V 417 w(R)h(\003ag)0 2620 y(When)k(an)h FJ(MMDFMessage)e FN(instance)h(is)i(created)e(based)g (upon)f(an)i FJ(MHMessage)e FN(instance,)j(the)e(follo)n(wing)f(con)m (v)o(ersions)g(tak)o(e)0 2719 y(place:)1250 2945 y FL(Resulting)20 b(state)p 1865 2975 V 143 w FD(MHMessage)f FL(state)p 1200 2979 1500 4 v 1250 3048 a FN(R)i(\003ag)f(and)g(O)h(\003ag)p 1865 3078 4 100 v 99 w(no)f(\224unseen\224)f(sequence)1250 3148 y(O)i(\003ag)p 1865 3178 V 461 w(\224unseen\224)e(sequence)1250 3248 y(F)i(\003ag)p 1865 3278 V 475 w(\224\003agged\224)e(sequence)1250 3347 y(A)i(\003ag)p 1865 3377 V 461 w(\224replied\224)e(sequence)0 3572 y(When)g(an)g FJ(MMDFMessage)e FN(instance)i(is)h(created)e(based) h(upon)e(a)j FJ(BabylMessage)d FN(instance,)i(the)g(follo)n(wing)e(con) m(v)o(ersions)g(tak)o(e)0 3672 y(place:)1224 3898 y FL(Resulting)k (state)p 1840 3928 V 142 w FD(BabylMessage)e FL(state)p 1174 3932 1552 4 v 1224 4001 a FN(R)i(\003ag)g(and)e(O)i(\003ag)p 1840 4031 4 100 v 99 w(no)f(\224unseen\224)f(label)1224 4101 y(O)i(\003ag)p 1840 4131 V 461 w(\224unseen\224)e(label)1224 4200 y(D)i(\003ag)p 1840 4230 V 461 w(\224deleted\224)e(label)1224 4300 y(A)i(\003ag)p 1840 4330 V 461 w(\224answered\224)e(label)0 4525 y(When)h(an)h FJ(MMDFMessage)e FN(instance)h(is)h(created)f(based) g(upon)f(an)i FJ(mboxMessage)e FN(instance,)h(the)g(\224From)g(\224)h (line)f(is)i(copied)d(and)0 4625 y(all)i(\003ags)f(directly)g (correspond:)1271 4851 y FL(Resulting)h(state)p 1843 4881 V 98 w FD(mboxMessage)e FL(state)p 1221 4884 1458 4 v 1271 4954 a FN(R)i(\003ag)p 1843 4984 4 100 v 422 w(R)g(\003ag)1271 5054 y(O)g(\003ag)p 1843 5084 V 417 w(O)g(\003ag)1271 5153 y(D)g(\003ag)p 1843 5183 V 417 w(D)g(\003ag)1271 5253 y(F)g(\003ag)p 1843 5283 V 431 w(F)g(\003ag)1271 5353 y(A)g(\003ag)p 1843 5382 V 417 w(A)g(\003ag)p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n(x)n(es)e(in)h(v)n(ar)q (ious)e(f)n(or)r(mats)1619 b(233)p eop end %%Page: 234 246 TeXDict begin 234 245 bop 0 83 a Fv(7.3.3)100 b(Exceptions)0 286 y FN(The)20 b(follo)n(wing)e(e)o(xception)h(classes)i(are)f (de\002ned)f(in)i(the)f FJ(mailbox)f FN(module:)0 433 y FL(class)i FD(Error)p FJ(\(\))208 532 y FN(The)e(based)h(class)h(for) f(all)h(other)e(module-speci\002c)f(e)o(xceptions.)0 679 y FL(class)j FD(NoSuchMailboxError)p FJ(\(\))208 779 y FN(Raised)d(when)f(a)h(mailbox)e(is)j(e)o(xpected)d(b)n(ut)i(is)g (not)f(found,)g(such)g(as)h(when)f(instantiating)g(a)h FJ(Mailbox)f FN(subclass)h(with)g(a)g(path)208 879 y(that)i(does)g(not) g(e)o(xist)g(\(and)f(with)i(the)f FK(cr)m(eate)g FN(parameter)f(set)i (to)f FJ(False)p FN(\),)f(or)h(when)g(opening)e(a)j(folder)e(that)h (does)g(not)g(e)o(xist.)0 1025 y FL(class)h FD(NotEmptyErrorError)p FJ(\(\))208 1125 y FN(Raised)c(when)f(a)i(mailbox)e(is)i(not)e(empty)g (b)n(ut)h(is)h(e)o(xpected)e(to)h(be,)g(such)g(as)h(when)e(deleting)g (a)h(folder)f(that)h(contains)g(messages.)0 1272 y FL(class)k FD(ExternalClashError)p FJ(\(\))208 1372 y FN(Raised)j(when)f(some)g (mailbox-related)e(condition)h(be)o(yond)f(the)j(control)e(of)h(the)h (program)d(causes)j(it)g(to)g(be)f(unable)g(to)h(pro-)208 1471 y(ceed,)k(such)f(as)h(when)e(f)o(ailing)h(to)g(acquire)f(a)i(lock) e(that)i(another)d(program)g(already)h(holds)h(a)h(lock,)g(or)f(when)f (a)i(uniquely-)208 1571 y(generated)18 b(\002le)j(name)e(already)h(e)o (xists.)0 1718 y FL(class)h FD(FormatError)p FJ(\(\))208 1817 y FN(Raised)30 b(when)f(the)h(data)f(in)h(a)g(\002le)g(cannot)f (be)h(parsed,)h(such)e(as)h(when)f(an)h FJ(MH)g FN(instance)f(attempts) h(to)g(read)f(a)h(corrupted)208 1917 y(`)p FO(.mh)p 365 1917 23 4 v 26 w(sequences)p FN(')18 b(\002le.)0 2195 y Fv(7.3.4)100 b(Deprecated)30 b(classes)e(and)h(methods)0 2398 y FN(Older)22 b(v)o(ersions)f(of)g(the)h FJ(mailbox)g FN(module)e(do)i(not)g(support)e(modi\002cation)h(of)g(mailbox)o(es,)g (such)h(as)h(adding)d(or)i(remo)o(ving)e(mes-)0 2497 y(sage,)d(and)f(do)h(not)f(pro)o(vide)f(classes)j(to)f(represent)e (format-speci\002c)g(message)i(properties.)22 b(F)o(or)16 b(backw)o(ard)f(compatibility)-5 b(,)16 b(the)g(older)0 2597 y(mailbox)j(classes)i(are)f(still)i(a)n(v)n(ailable,)d(b)n(ut)h (the)h(ne)n(wer)e(classes)i(should)f(be)g(used)g(in)g(preference)e(to)i (them.)0 2744 y(Older)g(mailbox)f(objects)h(support)e(only)i(iteration) f(and)h(pro)o(vide)e(a)j(single)f(public)f(method:)0 2891 y FD(next)p FJ(\(\))208 2990 y FN(Return)27 b(the)g(ne)o(xt)g (message)g(in)h(the)f(mailbox,)h(created)f(with)h(the)f(optional)f FK(factory)i FN(ar)o(gument)d(passed)i(into)g(the)h(mailbox)208 3090 y(object')-5 b(s)18 b(constructor)-5 b(.)23 b(By)d(def)o(ault)e (this)i(is)f(an)g FJ(rfc822.Message)e FN(object)i(\(see)g(the)g FJ(rfc822)f FN(module\).)23 b(Depending)17 b(on)208 3190 y(the)i(mailbox)f(implementation)f(the)i FK(fp)h FN(attrib)n(ute)f(of)g (this)h(object)f(may)f(be)i(a)g(true)f(\002le)h(object)e(or)h(a)h (class)g(instance)f(simulating)208 3289 y(a)k(\002le)h(object,)f (taking)f(care)h(of)g(things)f(lik)o(e)i(message)e(boundaries)f(if)j (multiple)e(mail)h(messages)h(are)f(contained)e(in)i(a)h(single)208 3389 y(\002le,)c(etc.)25 b(If)c(no)e(more)h(messages)g(are)g(a)n(v)n (ailable,)g(this)g(method)f(returns)g FJ(None)p FN(.)0 3536 y(Most)h(of)g(the)f(older)g(mailbox)g(classes)i(ha)n(v)o(e)e (names)g(that)h(dif)n(fer)f(from)g(the)h(current)e(mailbox)h(class)h (names,)g(e)o(xcept)e(for)i FJ(Maildir)p FN(.)0 3635 y(F)o(or)i(this)i(reason,)e(the)h(ne)n(w)f FJ(Maildir)g FN(class)i(de\002nes)e(a)h FJ(next\(\))f FN(method)g(and)g(its)i (constructor)c(dif)n(fers)i(slightly)h(from)e(those)i(of)0 3735 y(the)d(other)g(ne)n(w)g(mailbox)e(classes.)0 3882 y(The)i(older)f(mailbox)g(classes)i(whose)f(names)g(are)g(not)g(the)g (same)h(as)g(their)f(ne)n(wer)f(counterparts)f(are)i(as)h(follo)n(ws:)0 4029 y FL(class)g FD(UnixMailbox)p FJ(\()p FK(fp)p FC([)p FK(,)c(factory)12 b FC(])p FJ(\))208 4128 y FN(Access)30 b(to)g(a)g(classic)j(U)t FH(N)t(I)t(X)r FN(-style)d(mailbox,)g(where)f (all)i(messages)e(are)h(contained)e(in)i(a)g(single)g(\002le)g(and)f (separated)g(by)208 4228 y(`)p FJ(From)48 b FN(')25 b(\(a.k.a.)f(`)p FJ(From_)p FN('\))f(lines.)39 b(The)25 b(\002le)g(object)g FK(fp)f FN(points)h(to)g(the)g(mailbox)e(\002le.)40 b(The)24 b(optional)g FK(factory)g FN(parameter)208 4328 y(is)i(a)g(callable)f (that)h(should)f(create)g(ne)n(w)g(message)h(objects.)40 b FK(factory)26 b FN(is)g(called)g(with)f(one)g(ar)o(gument,)g FK(fp)g FN(by)h(the)f FJ(next\(\))208 4427 y FN(method)18 b(of)i(the)g(mailbox)f(object.)24 b(The)c(def)o(ault)g(is)h(the)f FJ(rfc822.Message)e FN(class)j(\(see)f(the)g FJ(rfc822)g FN(module)f(\226)h(and)g(the)208 4527 y(note)f(belo)n(w\).)208 4652 y FL(Note:)37 b FN(F)o(or)26 b(reasons)h(of)f(this)i(module')-5 b(s)25 b(internal)h(implementation,)g(you)g(will)i(probably)c(w)o(ant)j (to)g(open)e(the)i FK(fp)g FN(object)f(in)208 4751 y(binary)18 b(mode.)24 b(This)d(is)g(especially)f(important)e(on)i(W)m(indo)n(ws.) 208 4876 y(F)o(or)g(maximum)g(portability)-5 b(,)19 b(messages)i(in)g (a)j(U)t FH(N)t(I)t(X)r FN(-style)e(mailbox)d(are)i(separated)g(by)f (an)o(y)h(line)g(that)g(be)o(gins)f(e)o(xactly)g(with)208 4976 y(the)e(string)g FJ('From)49 b(')19 b FN(\(note)f(the)g(trailing)g (space\))g(if)h(preceded)e(by)h(e)o(xactly)f(tw)o(o)i(ne)n(wlines.)24 b(Because)19 b(of)f(the)g(wide-range)f(of)208 5076 y(v)n(ariations)e (in)h(practice,)h(nothing)d(else)j(on)f(the)h(From)p 1754 5076 25 4 v 45 w(line)g(should)e(be)h(considered.)22 b(Ho)n(we)n(v)o(er)m(,)15 b(the)i(current)e(implementation)208 5175 y(doesn')o(t)j(check)i(for)f(the)h(leading)g(tw)o(o)g(ne)n (wlines.)25 b(This)20 b(is)h(usually)f(\002ne)g(for)f(most)i (applications.)208 5300 y(The)f FJ(UnixMailbox)f FN(class)j(implements) e(a)h(more)f(strict)i(v)o(ersion)d(of)i(From)p 2498 5300 V 50 w(line)g(checking,)e(using)i(a)g(re)o(gular)e(e)o(xpression)208 5400 y(that)27 b(usually)f(correctly)g(matched)g(From)p 1445 5400 V 56 w(delimiters.)45 b(It)27 b(considers)f(delimiter)h(line) g(to)g(be)g(separated)f(by)g(`)p FJ(From)49 b FK(name)p 0 5549 3901 4 v 0 5649 a FI(234)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 235 247 TeXDict begin 235 246 bop 208 83 a FK(time)p FN(')21 b(lines.)30 b(F)o(or)22 b(maximum)e(portability)-5 b(,)20 b(use)i(the)f FJ(PortableUnixMailbox)e FN(class)k(instead.)29 b(This)22 b(class)g(is)h(identical)208 183 y(to)d FJ(UnixMailbox)f FN(e)o(xcept)g(that)h(indi)n(vidual)e(messages)j(are)f(separated)f(by)h (only)f(`)p FJ(From)49 b FN(')20 b(lines.)208 315 y(F)o(or)f(more)h (information,)d(see)k FK(Con\002guring)d(Netscape)i(Mail)h(on)h FN(U)t FH(N)t(I)t(X)r FK(:)j(Why)c(the)f(Content-Length)e(F)-9 b(ormat)20 b(is)h(Bad)p FN(.)0 462 y FL(class)g FD(PortableUnixMailbox) p FJ(\()p FK(fp)p FC([)p FK(,)16 b(factory)c FC(])p FJ(\))208 562 y FN(A)24 b(less-strict)i(v)o(ersion)d(of)h FJ(UnixMailbox)p FN(,)g(which)g(considers)f(only)h(the)g(`)p FJ(From)49 b FN(')25 b(at)f(the)h(be)o(ginning)d(of)i(the)g(line)h(sepa-)208 662 y(rating)e(messages.)38 b(The)24 b(\223)p FK(name)g(time)p FN(\224)g(portion)f(of)h(the)h(From)f(line)g(is)i(ignored,)d(to)i (protect)e(against)h(some)g(v)n(ariations)f(that)208 761 y(are)d(observ)o(ed)e(in)i(practice.)25 b(This)20 b(w)o(orks)g(since)h(lines)f(in)h(the)f(message)g(which)g(be)o(gin)f (with)h FJ('From)49 b(')21 b FN(are)f(quoted)f(by)g(mail)208 861 y(handling)f(softw)o(are)i(at)g(deli)n(v)o(ery-time.)0 1008 y FL(class)h FD(MmdfMailbox)p FJ(\()p FK(fp)p FC([)p FK(,)c(factory)12 b FC(])p FJ(\))208 1107 y FN(Access)23 b(an)g(MMDF-style)f(mailbox,)g(where)g(all)i(messages)f(are)f (contained)g(in)g(a)i(single)e(\002le)i(and)e(separated)g(by)g(lines)h (con-)208 1207 y(sisting)i(of)g(4)g(control-A)e(characters.)38 b(The)25 b(\002le)h(object)e FK(fp)h FN(points)g(to)g(the)g(mailbox)f (\002le.)40 b(Optional)24 b FK(factory)h FN(is)h(as)f(with)h(the)208 1307 y FJ(UnixMailbox)18 b FN(class.)0 1453 y FL(class)j FD(MHMailbox)p FJ(\()p FK(dirname)p FC([)p FK(,)c(factory)12 b FC(])p FJ(\))208 1553 y FN(Access)20 b(an)g(MH)h(mailbox,)d(a)j (directory)d(with)j(each)e(message)h(in)h(a)f(separate)g(\002le)h(with) f(a)g(numeric)f(name.)24 b(The)c(name)g(of)g(the)208 1653 y(mailbox)e(directory)h(is)i(passed)f(in)g FK(dirname)p FN(.)25 b FK(factory)20 b FN(is)h(as)g(with)f(the)g FJ(UnixMailbox)f FN(class.)0 1800 y FL(class)i FD(BabylMailbox)p FJ(\()p FK(fp)p FC([)p FK(,)c(factory)12 b FC(])p FJ(\))208 1899 y FN(Access)24 b(a)g(Babyl)f(mailbox,)g(which)g(is)i(similar)f(to)g(an) f(MMDF)h(mailbox.)34 b(In)23 b(Babyl)h(format,)f(each)g(message)h(has)g (tw)o(o)f(sets)208 1999 y(of)29 b(headers,)h(the)g FK(original)e FN(headers)h(and)g(the)g FK(visible)h FN(headers.)52 b(The)29 b(original)g(headers)f(appear)g(before)g(a)i(line)g(contain-) 208 2098 y(ing)25 b(only)g FJ(')564 2113 y(***)763 2098 y(EOOH)1012 2113 y(***)1162 2098 y(')h FN(\(End-Of-Original-Headers\)) 21 b(and)k(the)h(visible)g(headers)f(appear)g(after)g(the)h FJ(EOOH)g FN(line.)208 2198 y(Babyl-compliant)18 b(mail)i(readers)g (will)h(sho)n(w)g(you)e(only)h(the)g(visible)h(headers,)e(and)h FJ(BabylMailbox)f FN(objects)h(will)i(return)208 2298 y(messages)17 b(containing)e(only)h(the)i(visible)f(headers.)23 b(Y)-9 b(ou')o(ll)16 b(ha)n(v)o(e)h(to)g(do)g(your)f(o)n(wn)g(parsing)h (of)g(the)g(mailbox)f(\002le)h(to)h(get)f(at)h(the)208 2397 y(original)j(headers.)30 b(Mail)23 b(messages)g(start)g(with)f (the)h(EOOH)f(line)h(and)e(end)h(with)h(a)g(line)f(containing)f(only)g FJ('\\037\\014')p FN(.)208 2497 y FK(factory)f FN(is)h(as)g(with)f(the) g FJ(UnixMailbox)f FN(class.)0 2644 y(If)g(you)f(wish)i(to)f(use)h(the) f(older)f(mailbox)g(classes)i(with)g(the)f FJ(email)g FN(module)f(rather)g(than)h(the)g(deprecated)e FJ(rfc822)i FN(module,)e(you)0 2743 y(can)j(do)g(so)g(as)h(follo)n(ws:)236 2982 y FA(import)44 b(email)236 3073 y(import)g(email.Errors)236 3164 y(import)g(mailbox)236 3347 y(def)h(msgfactory\(fp\):)416 3438 y(try:)595 3530 y(return)f(email.message_from_file\(fp\))416 3621 y(except)f(email.Errors.MessageParseError:)595 3712 y(#)i(Don't)f(return)f(None)i(since)f(that)g(will)595 3804 y(#)h(stop)f(the)g(mailbox)g(iterator)595 3895 y(return)g('')236 4078 y(mbox)g(=)h(mailbox.UnixMailbox\(fp,)c(msgfactory\))0 4364 y FN(Alternati)n(v)o(ely)-5 b(,)18 b(if)i(you)g(kno)n(w)f(your)g (mailbox)g(contains)g(only)g(well-formed)g(MIME)g(messages,)h(you)g (can)g(simplify)f(this)i(to:)236 4602 y FA(import)44 b(email)236 4694 y(import)g(mailbox)236 4876 y(mbox)g(=)h (mailbox.UnixMailbox\(fp,)c(email.message_from_file\))p 0 5549 3901 4 v 0 5649 a FI(7.3.)52 b FJ(mailbox)22 b FI(\227)h(Manipulate)i(mailbo)n(x)n(es)e(in)h(v)n(ar)q(ious)e(f)n(or)r (mats)1619 b(235)p eop end %%Page: 236 248 TeXDict begin 236 247 bop 0 83 a Fv(7.3.5)100 b(Examples)0 286 y FN(A)21 b(simple)f(e)o(xample)f(of)h(printing)e(the)i(subjects)h (of)f(all)g(messages)h(in)f(a)h(mailbox)e(that)h(seem)g(interesting:) 236 524 y FA(import)44 b(mailbox)236 615 y(for)h(message)e(in)i (mailbox.mbox\('\230/mbox'\):)416 707 y(subject)e(=)i (message['subject'])311 b(#)44 b(Could)g(possibly)g(be)g(None.)416 798 y(if)g(subject)g(and)g('python')g(in)g(subject.lower\(\):)595 889 y(print)g(subject)0 1176 y FN(T)-7 b(o)23 b(cop)o(y)f(all)i(mail)f (from)e(a)j(Babyl)f(mailbox)e(to)i(an)g(MH)g(mailbox,)f(con)m(v)o (erting)e(all)k(of)e(the)h(format-speci\002c)e(information)g(that)i (can)0 1276 y(be)d(con)m(v)o(erted:)236 1514 y FA(import)44 b(mailbox)236 1605 y(destination)f(=)i(mailbox.MH\('\230/Mail'\))236 1696 y(destination.lock\(\))236 1788 y(for)g(message)e(in)i (mailbox.Babyl\('\230/RMAIL'\):)416 1879 y (destination.add\(MHMessage\(message\)\))236 1970 y (destination.flush\(\))236 2062 y(destination.unlock\(\))0 2348 y FN(This)20 b(e)o(xample)e(sorts)h(mail)h(from)e(se)n(v)o(eral)h (mailing)g(lists)h(into)g(dif)n(ferent)d(mailbox)o(es,)h(being)h (careful)f(to)i(a)n(v)n(oid)f(mail)g(corruption)e(due)0 2448 y(to)22 b(concurrent)d(modi\002cation)h(by)i(other)f(programs,)f (mail)i(loss)g(due)f(to)h(interruption)e(of)h(the)h(program,)e(or)h (premature)f(termination)0 2547 y(due)g(to)g(malformed)e(messages)i(in) h(the)f(mailbox:)p 0 5549 3901 4 v 0 5649 a FI(236)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 237 249 TeXDict begin 237 248 bop 236 174 a FA(import)44 b(mailbox)236 266 y(import)g(email.Errors)236 448 y(list_names)f(=)i (\('python-list',)d('python-dev',)h('python-bugs'\))236 631 y(boxes)h(=)h(dict\(\(name,)e(mailbox.mbox\('\230/email/\045s')d (\045)45 b(name\)\))f(for)g(name)g(in)h(list_names\))236 722 y(inbox)f(=)h(mailbox.Maildir\('\230/Maildir',)40 b(factory=None\))236 905 y(for)45 b(key)f(in)g(inbox.iterkeys\(\):)416 996 y(try:)595 1088 y(message)g(=)g(inbox[key])416 1179 y(except)f(email.Errors.MessageParseError:)595 1270 y(continue)716 b(#)45 b(The)f(message)f(is)i(malformed.)e(Just)h(leave)g(it.)416 1453 y(for)g(name)g(in)h(list_names:)595 1544 y(list_id)f(=)g (message['list-id'])595 1636 y(if)g(list_id)g(and)g(name)h(in)f (list_id:)774 1727 y(#)h(Get)f(mailbox)g(to)g(use)774 1818 y(box)h(=)f(boxes[name])774 2001 y(#)h(Write)f(copy)g(to)h(disk)f (before)f(removing)h(original.)774 2092 y(#)h(If)f(there's)g(a)h (crash,)f(you)g(might)g(duplicate)f(a)i(message,)e(but)774 2183 y(#)i(that's)f(better)g(than)g(losing)f(a)i(message)f(completely.) 774 2275 y(box.lock\(\))774 2366 y(box.add\(message\))774 2457 y(box.flush\(\))774 2549 y(box.unlock\(\))774 2731 y(#)h(Remove)f(original)f(message)774 2823 y(inbox.lock\(\))774 2914 y(inbox.discard\(key\))774 3005 y(inbox.flush\(\))774 3097 y(inbox.unlock\(\))774 3188 y(break)672 b(#)45 b(Found)e (destination,)g(so)i(stop)f(looking.)236 3371 y(for)h(box)f(in)g (boxes.itervalues\(\):)416 3462 y(box.close\(\))0 3972 y FE(7.4)121 b Fx(mhlib)32 b FE(\227)g(Access)h(to)h(MH)f(mailbo)l(x)l (es)0 4205 y FN(The)20 b FJ(mhlib)g FN(module)e(pro)o(vides)h(a)i (Python)e(interf)o(ace)g(to)h(MH)h(folders)e(and)h(their)g(contents.)0 4352 y(The)30 b(module)f(contains)h(three)g(basic)g(classes,)k FJ(MH)p FN(,)c(which)g(represents)g(a)h(particular)e(collection)g(of)h (folders,)i FJ(Folder)p FN(,)g(which)0 4451 y(represents)19 b(a)i(single)f(folder)m(,)e(and)i FJ(Message)p FN(,)f(which)h (represents)f(a)i(single)f(message.)0 4598 y FL(class)h FD(MH)p FJ(\()p FC([)p FK(path)p FC([)p FK(,)d(pr)l(o\002le)12 b FC(])g(])p FJ(\))208 4698 y(MH)20 b FN(represents)f(a)i(collection)e (of)h(MH)g(folders.)0 4845 y FL(class)h FD(Folder)p FJ(\()p FK(mh,)d(name)p FJ(\))208 4944 y FN(The)h FJ(Folder)h FN(class)h(represents)f(a)g(single)g(folder)f(and)h(its)h(messages.)0 5091 y FL(class)g FD(Message)p FJ(\()p FK(folder)-9 b(,)18 b(number)r FC([)p FK(,)h(name)12 b FC(])p FJ(\))208 5191 y(Message)54 b FN(objects)h(represent)e(indi)n(vidual)h(messages)h(in)g (a)g(folder)-5 b(.)129 b(The)54 b(Message)i(class)f(is)h(deri)n(v)o(ed) e(from)208 5291 y FJ(mimetools.Message)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(7.4.)e FJ(mhlib)22 b FI(\227)h(Access)f(to)h(MH)h (mailbo)n(x)n(es)2289 b(237)p eop end %%Page: 238 250 TeXDict begin 238 249 bop 0 83 a Fv(7.4.1)100 b(MH)28 b(Objects)0 286 y FJ(MH)20 b FN(instances)g(ha)n(v)o(e)g(the)g(follo)n (wing)f(methods:)0 433 y FD(error)p FJ(\()p FK(format)q FC([)p FK(,)g(...)12 b FC(])p FJ(\))208 532 y FN(Print)20 b(an)g(error)f(message)h(\226)g(can)g(be)g(o)o(v)o(erridden.)0 679 y FD(getprofile)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 779 y FN(Return)f(a)i(pro\002le)e(entry)h(\()p FJ(None)f FN(if)i(not)f(set\).)0 926 y FD(getpath)p FJ(\(\))208 1025 y FN(Return)f(the)i(mailbox)d(pathname.)0 1172 y FD(getcontext)p FJ(\(\))208 1272 y FN(Return)h(the)i(current)d(folder)h (name.)0 1419 y FD(setcontext)p FJ(\()p FK(name)p FJ(\))208 1518 y FN(Set)h(the)h(current)d(folder)h(name.)0 1665 y FD(listfolders)p FJ(\(\))208 1765 y FN(Return)g(a)i(list)g(of)f (top-le)n(v)o(el)f(folders.)0 1912 y FD(listallfolders)p FJ(\(\))208 2011 y FN(Return)g(a)i(list)g(of)f(all)h(folders.)0 2158 y FD(listsubfolders)p FJ(\()p FK(name)p FJ(\))208 2258 y FN(Return)e(a)i(list)g(of)f(direct)g(subfolders)f(of)g(the)i(gi) n(v)o(en)e(folder)-5 b(.)0 2405 y FD(listallsubfolders)p FJ(\()p FK(name)p FJ(\))208 2504 y FN(Return)19 b(a)i(list)g(of)f(all)h (subfolders)e(of)g(the)i(gi)n(v)o(en)e(folder)-5 b(.)0 2651 y FD(makefolder)p FJ(\()p FK(name)p FJ(\))208 2751 y FN(Create)20 b(a)h(ne)n(w)f(folder)-5 b(.)0 2898 y FD(deletefolder)p FJ(\()p FK(name)p FJ(\))208 2997 y FN(Delete)20 b(a)h(folder)e(\226)h(must)g(ha)n(v)o(e)g(no)f (subfolders.)0 3144 y FD(openfolder)p FJ(\()p FK(name)p FJ(\))208 3244 y FN(Return)g(a)i(ne)n(w)f(open)f(folder)g(object.)0 3529 y Fv(7.4.2)100 b(F)m(older)29 b(Objects)0 3732 y FJ(Folder)20 b FN(instances)g(represent)f(open)g(folders)g(and)h(ha)n (v)o(e)f(the)i(follo)n(wing)d(methods:)0 3879 y FD(error)p FJ(\()p FK(format)q FC([)p FK(,)h(...)12 b FC(])p FJ(\))208 3978 y FN(Print)20 b(an)g(error)f(message)h(\226)g(can)g(be)g(o)o(v)o (erridden.)0 4125 y FD(getfullname)p FJ(\(\))208 4225 y FN(Return)f(the)i(folder')-5 b(s)19 b(full)h(pathname.)0 4372 y FD(getsequencesfilename)p FJ(\(\))208 4471 y FN(Return)f(the)i (full)f(pathname)e(of)i(the)g(folder')-5 b(s)20 b(sequences)f(\002le.)0 4618 y FD(getmessagefilename)p FJ(\()p FK(n)p FJ(\))208 4718 y FN(Return)g(the)i(full)f(pathname)e(of)i(message)g FK(n)g FN(of)g(the)g(folder)-5 b(.)0 4865 y FD(listmessages)p FJ(\(\))208 4964 y FN(Return)19 b(a)i(list)g(of)f(messages)g(in)h(the)f (folder)f(\(as)i(numbers\).)0 5111 y FD(getcurrent)p FJ(\(\))208 5211 y FN(Return)e(the)i(current)d(message)i(number)-5 b(.)0 5358 y FD(setcurrent)p FJ(\()p FK(n)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(238)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 239 251 TeXDict begin 239 250 bop 208 83 a FN(Set)20 b(the)h(current)d(message) j(number)d(to)i FK(n)p FN(.)0 230 y FD(parsesequence)p FJ(\()p FK(seq)p FJ(\))208 330 y FN(P)o(arse)g(msgs)g(syntax)g(into)g (list)h(of)f(messages.)0 476 y FD(getlast)p FJ(\(\))208 576 y FN(Get)g(last)h(message,)f(or)g FJ(0)h FN(if)f(no)g(messages)g (are)g(in)h(the)f(folder)-5 b(.)0 723 y FD(setlast)p FJ(\()p FK(n)p FJ(\))208 823 y FN(Set)20 b(last)h(message)g(\(internal) e(use)h(only\).)0 969 y FD(getsequences)p FJ(\(\))208 1069 y FN(Return)j(dictionary)e(of)i(sequences)g(in)h(folder)-5 b(.)34 b(The)23 b(sequence)f(names)h(are)h(used)f(as)h(k)o(e)o(ys,)g (and)f(the)g(v)n(alues)g(are)h(the)f(lists)i(of)208 1169 y(message)20 b(numbers)e(in)j(the)f(sequences.)0 1316 y FD(putsequences)p FJ(\()p FK(dict)q FJ(\))208 1415 y FN(Return)f(dictionary)g(of)h(sequences)f(in)h(folder)f(name:)25 b(list.)0 1562 y FD(removemessages)p FJ(\()p FK(list)q FJ(\))208 1662 y FN(Remo)o(v)o(e)19 b(messages)h(in)g(list)h(from)f (folder)-5 b(.)0 1808 y FD(refilemessages)p FJ(\()p FK(list,)18 b(tofolder)r FJ(\))208 1908 y FN(Mo)o(v)o(e)h(messages)h(in)g(list)h (to)g(other)e(folder)-5 b(.)0 2055 y FD(movemessage)p FJ(\()p FK(n,)18 b(tofolder)-9 b(,)19 b(ton)p FJ(\))208 2155 y FN(Mo)o(v)o(e)g(one)g(message)h(to)h(a)f(gi)n(v)o(en)f (destination)g(in)i(another)d(folder)-5 b(.)0 2301 y FD(copymessage)p FJ(\()p FK(n,)18 b(tofolder)-9 b(,)19 b(ton)p FJ(\))208 2401 y FN(Cop)o(y)g(one)h(message)g(to)g(a)h(gi)n(v)o (en)e(destination)g(in)h(another)f(folder)-5 b(.)0 2686 y Fv(7.4.3)100 b(Message)29 b(Objects)0 2889 y FN(The)20 b FJ(Message)f FN(class)i(adds)f(one)g(method)f(to)h(those)g(of)g FJ(mimetools.Message)p FN(:)0 3036 y FD(openmessage)p FJ(\()p FK(n)p FJ(\))208 3135 y FN(Return)f(a)i(ne)n(w)f(open)f (message)h(object)g(\(costs)g(a)h(\002le)g(descriptor\).)0 3463 y FE(7.5)121 b Fx(mimetools)31 b FE(\227)h(T)-14 b(ools)34 b(f)l(or)g(parsing)g(MIME)e(messages)0 3696 y FL(Depr)o(ecated)22 b(since)i(r)o(elease)f(2.3.)34 b FN(The)23 b FJ(email)f FN(package)g(should)h(be)g(used)g(in)g (preference)f(to)h(the)g FJ(mimetools)f FN(module.)33 b(This)0 3795 y(module)19 b(is)i(present)e(only)h(to)g(maintain)g (backw)o(ard)e(compatibility)-5 b(.)0 3942 y(This)25 b(module)f(de\002nes)g(a)h(subclass)h(of)e(the)h FJ(rfc822)f FN(module')-5 b(s)24 b FJ(Message)g FN(class)i(and)e(a)i(number)d(of)h (utility)h(functions)f(that)h(are)0 4042 y(useful)20 b(for)f(the)h(manipulation)e(for)i(MIME)g(multipart)f(or)h(encoded)e (message.)0 4189 y(It)i(de\002nes)g(the)h(follo)n(wing)d(items:)0 4336 y FL(class)j FD(Message)p FJ(\()p FK(fp)p FC([)p FK(,)d(seekable)12 b FC(])p FJ(\))208 4435 y FN(Return)23 b(a)h(ne)n(w)g(instance)g(of)f(the)h FJ(Message)g FN(class.)37 b(This)24 b(is)h(a)f(subclass)g(of)g(the)g FJ(rfc822.Message)e FN(class,)k(with)e(some)208 4535 y(additional)18 b(methods)i(\(see)g (belo)n(w\).)k(The)c FK(seekable)f FN(ar)o(gument)f(has)j(the)f(same)g (meaning)f(as)i(for)e FJ(rfc822.Message)p FN(.)0 4682 y FD(choose_boundary)p FJ(\(\))208 4781 y FN(Return)25 b(a)h(unique)e(string)h(that)g(has)h(a)g(high)f(lik)o(elihood)f(of)h (being)g(usable)g(as)h(a)g(part)f(boundary)-5 b(.)38 b(The)25 b(string)g(has)h(the)g(form)208 4881 y FJ(')p FK(hostipaddr)r FJ(.)p FK(uid)r FJ(.)p FK(pid)r FJ(.)p FK(timestamp)p FJ(.)p FK(r)o(an)o(do)o(m)p FJ(')p FN(.)0 5028 y FD(decode)p FJ(\()p FK(input,)18 b(output,)h(encoding)p FJ(\))208 5127 y FN(Read)34 b(data)h(encoded)d(using)i(the)h(allo)n (wed)f(MIME)g FK(encoding)f FN(from)g(open)h(\002le)h(object)f FK(input)h FN(and)f(write)h(the)f(decoded)208 5227 y(data)d(to)h(open)e (\002le)j(object)e FK(output)q FN(.)58 b(V)-9 b(alid)32 b(v)n(alues)f(for)g FK(encoding)f FN(include)g FJ('base64')p FN(,)k FJ('quoted-printable')p FN(,)208 5327 y FJ('uuencode')p FN(,)23 b FJ('x-uuencode')p FN(,)h FJ('uue')p FN(,)h FJ('x-uue')p FN(,)f FJ('7bit')p FN(,)h(and)f FJ('8bit')p FN(.)37 b(Decoding)23 b(messages)h(encoded)p 0 5549 3901 4 v 0 5649 a FI(7.5.)52 b FJ(mimetools)22 b FI(\227)h(T)-10 b(ools)23 b(f)n(or)f(parsing)h(MIME)h(messages)1747 b(239)p eop end %%Page: 240 252 TeXDict begin 240 251 bop 208 83 a FN(in)20 b FJ('7bit')g FN(or)f FJ('8bit')h FN(has)h(no)e(ef)n(fect.)25 b(The)20 b(input)f(is)i(simply)f(copied)f(to)h(the)h(output.)0 230 y FD(encode)p FJ(\()p FK(input,)d(output,)h(encoding)p FJ(\))208 330 y FN(Read)f(data)g(from)g(open)f(\002le)i(object)f FK(input)h FN(and)e(write)i(it)g(encoded)d(using)i(the)h(allo)n(wed)e (MIME)h FK(encoding)e FN(to)j(open)e(\002le)i(object)208 429 y FK(output)q FN(.)24 b(V)-9 b(alid)20 b(v)n(alues)g(for)f FK(encoding)f FN(are)i(the)h(same)f(as)h(for)e FJ(decode\(\))p FN(.)0 576 y FD(copyliteral)p FJ(\()p FK(input,)e(output)q FJ(\))208 676 y FN(Read)j(lines)h(from)e(open)g(\002le)i FK(input)g FN(until)h FH(E)t(O)t(F)g FN(and)e(write)g(them)g(to)g(open) f(\002le)i FK(output)q FN(.)0 823 y FD(copybinary)p FJ(\()p FK(input,)c(output)q FJ(\))208 922 y FN(Read)j(blocks)g(until)j FH(E)t(O)t(F)f FN(from)e(open)g(\002le)h FK(input)g FN(and)f(write)h (them)f(to)h(open)e(\002le)i FK(output)q FN(.)26 b(The)20 b(block)g(size)h(is)g(currently)e(\002x)o(ed)208 1022 y(at)h(8192.)0 1169 y FL(See)h(Also:)0 1316 y FN(Module)e FJ(email)h FN(\(section)f(7.1\):)208 1415 y(Comprehensi)n(v)o(e)e (email)j(handling)f(package;)f(supersedes)i(the)g FJ(mimetools)f FN(module.)0 1562 y(Module)g FJ(rfc822)h FN(\(section)f(7.10\):)208 1662 y(Pro)o(vides)g(the)h(base)g(class)h(for)f FJ(mimetools.Message)p FN(.)0 1808 y(Module)f FJ(multifile)g FN(\(section)h(7.9\):)208 1908 y(Support)e(for)i(reading)f(\002les)i(which)e(contain)h(distinct)g (parts,)g(such)g(as)h(MIME)e(data.)0 2055 y FO(http://www)l(.cs)o (.uu.nl/w)o(ais/html)o(/na)o(-di)o(r/mai)o(l/mime)o(-f)n(a)o(q/.)o (html)208 2155 y FN(The)j(MIME)g(Frequently)f(Ask)o(ed)h(Questions)h (document.)30 b(F)o(or)22 b(an)h(o)o(v)o(ervie)n(w)d(of)j(MIME,)f(see)h (the)g(answer)f(to)h(question)e(1.1)208 2254 y(in)f(P)o(art)g(1)g(of)g (this)h(document.)0 2539 y Fv(7.5.1)100 b(Additional)30 b(Methods)f(of)f(Message)h(Objects)0 2742 y FN(The)20 b FJ(Message)f FN(class)i(de\002nes)f(the)h(follo)n(wing)d(methods)h (in)i(addition)e(to)h(the)g FJ(rfc822.Message)e FN(methods:)0 2889 y FD(getplist)p FJ(\(\))208 2989 y FN(Return)28 b(the)i(parameter)d(list)k(of)d(the)i FO(Content-T)-9 b(ype:)40 b FN(header)-5 b(.)51 b(This)30 b(is)g(a)f(list)i(of)e (strings.)52 b(F)o(or)28 b(parameters)g(of)h(the)h(form)208 3088 y(`)p FK(k)o(e)n(y)p FJ(=)p FK(value)p FN(',)40 b FK(k)o(e)n(y)e FN(is)h(con)m(v)o(erted)c(to)j(lo)n(wer)g(case)g(b)n (ut)g FK(value)g FN(is)h(not.)78 b(F)o(or)38 b(e)o(xample,)j(if)d(the)g (message)g(contains)g(the)208 3188 y(header)29 b(`)p FJ(Content-type:)97 b(text/html;)48 b(spam=1;)g(Spam=2;)h(Spam)p FN(')30 b(then)g FJ(getplist\(\))f FN(will)j(return)208 3287 y(the)20 b(Python)f(list)i FJ(['spam=1',)48 b('spam=2',)g('Spam']) p FN(.)0 3434 y FD(getparam)p FJ(\()p FK(name)p FJ(\))208 3534 y FN(Return)22 b(the)g FK(value)h FN(of)f(the)h(\002rst)g (parameter)e(\(as)i(returned)e(by)h FJ(getplist\(\))p FN(\))f(of)i(the)f(form)g(`)p FK(name)p FJ(=)p FK(value)p FN(')e(for)i(the)h(gi)n(v)o(en)208 3634 y FK(name)p FN(.)h(If)c FK(value)f FN(is)j(surrounded)17 b(by)j(quotes)f(of)h(the)g(form)f(`)p FJ(<)p FN(...)p FJ(>)p FN(')g(or)h(`)p FJ(")p FN(...)p FJ(")p FN(',)f(these)h(are)h(remo)o(v)o(ed.)0 3780 y FD(getencoding)p FJ(\(\))208 3880 y FN(Return)15 b(the)i(encoding)d (speci\002ed)i(in)h(the)f FO(Content-T)-9 b(r)o(ansf)n(er-Encoding)o(:) 18 b FN(message)e(header)-5 b(.)23 b(If)16 b(no)g(such)g(header)f(e)o (xists,)j(return)208 3980 y FJ('7bit')p FN(.)24 b(The)c(encoding)e(is)j (con)m(v)o(erted)d(to)i(lo)n(wer)g(case.)0 4127 y FD(gettype)p FJ(\(\))208 4226 y FN(Return)c(the)h(message)g(type)g(\(of)f(the)h (form)f(`)p FK(type)p FJ(/)p FK(subtype)p FN('\))e(as)k(speci\002ed)f (in)g(the)g FO(Content-T)-9 b(ype:)20 b FN(header)-5 b(.)24 b(If)16 b(no)h(such)g(header)208 4326 y(e)o(xists,)j(return)f FJ('text/plain')p FN(.)k(The)d(type)g(is)h(con)m(v)o(erted)c(to)k(lo)n (wer)f(case.)0 4473 y FD(getmaintype)p FJ(\(\))208 4572 y FN(Return)j(the)h(main)g(type)g(as)h(speci\002ed)f(in)g(the)g FO(Content-T)-9 b(ype:)30 b FN(header)-5 b(.)37 b(If)24 b(no)f(such)h(header)f(e)o(xists,)j(return)d FJ('text')p FN(.)36 b(The)208 4672 y(main)19 b(type)h(is)h(con)m(v)o(erted)d(to)i (lo)n(wer)g(case.)0 4819 y FD(getsubtype)p FJ(\(\))208 4918 y FN(Return)k(the)i(subtype)e(as)i(speci\002ed)f(in)h(the)f FO(Content-T)-9 b(ype:)33 b FN(header)-5 b(.)40 b(If)25 b(no)g(such)g(header)f(e)o(xists,)j(return)d FJ('plain')p FN(.)40 b(The)208 5018 y(subtype)19 b(is)i(con)m(v)o(erted)c(to)k(lo)n (wer)e(case.)p 0 5549 3901 4 v 0 5649 a FI(240)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 241 253 TeXDict begin 241 252 bop 0 87 a FE(7.6)121 b Fx(mimetypes)31 b FE(\227)h(Map)i(\002lenames)g(to)g(MIME)e(types)0 320 y FN(The)16 b FJ(mimetypes)f FN(module)h(con)m(v)o(erts)e(between)i(a)h (\002lename)f(or)g(URL)h(and)f(the)g(MIME)g(type)g(associated)h(with)f (the)h(\002lename)f(e)o(xten-)0 420 y(sion.)31 b(Con)m(v)o(ersions)21 b(are)h(pro)o(vided)e(from)h(\002lename)h(to)g(MIME)g(type)g(and)g (from)f(MIME)h(type)g(to)g(\002lename)g(e)o(xtension;)g(encodings)0 519 y(are)e(not)g(supported)e(for)i(the)g(latter)g(con)m(v)o(ersion.)0 666 y(The)g(module)f(pro)o(vides)g(one)h(class)i(and)e(a)h(number)d(of) j(con)m(v)o(enience)c(functions.)25 b(The)20 b(functions)f(are)i(the)f (normal)g(interf)o(ace)f(to)i(this)0 766 y(module,)e(b)n(ut)h(some)g (applications)f(may)g(be)i(interested)e(in)i(the)f(class)h(as)g(well.)0 913 y(The)i(functions)f(described)g(belo)n(w)h(pro)o(vide)e(the)i (primary)f(interf)o(ace)h(for)f(this)i(module.)33 b(If)24 b(the)f(module)f(has)h(not)g(been)g(initialized,)0 1012 y(the)o(y)c(will)i(call)g FJ(init\(\))f FN(if)g(the)o(y)g(rely)f(on)h (the)g(information)e FJ(init\(\))i FN(sets)h(up.)0 1159 y FD(guess_type)p FJ(\()p FK(\002lename)p FC([)p FK(,)c(strict)c FC(])p FJ(\))208 1259 y FN(Guess)26 b(the)g(type)f(of)h(a)g(\002le)h (based)f(on)f(its)i(\002lename)e(or)h(URL,)g(gi)n(v)o(en)f(by)h FK(\002lename)p FN(.)41 b(The)25 b(return)g(v)n(alue)g(is)i(a)g(tuple)e FJ(\()p FK(type)p FJ(,)208 1358 y FK(encoding)p FJ(\))19 b FN(where)h FK(type)i FN(is)g FJ(None)f FN(if)h(the)f(type)g(can')o(t) f(be)h(guessed)g(\(missing)g(or)g(unkno)n(wn)e(suf)n(\002x\))h(or)h(a)h (string)f(of)g(the)h(form)208 1458 y FJ(')p FK(type)p FJ(/)p FK(subtype)p FJ(')p FN(,)17 b(usable)j(for)g(a)g(MIME)g FO(content-type:)j FN(header.)208 1591 y FK(encoding)g FN(is)j FJ(None)f FN(for)g(no)g(encoding)e(or)i(the)h(name)e(of)h(the)h (program)d(used)i(to)g(encode)g(\(e.g.)39 b FL(compr)o(ess)26 b FN(or)f FL(gzip)p FN(\).)40 b(The)208 1691 y(encoding)24 b(is)j(suitable)f(for)f(use)i(as)g(a)f FO(Content-Encoding:)33 b FN(header)m(,)26 b FK(not)g FN(as)g(a)h FO(Content-T)-9 b(r)o(ansf)n(er-Encoding)o(:)32 b FN(header)-5 b(.)42 b(The)208 1790 y(mappings)17 b(are)h(table)h(dri)n(v)o(en.)k(Encoding) 16 b(suf)n(\002x)o(es)j(are)f(case)i(sensiti)n(v)o(e;)f(type)f(suf)n (\002x)o(es)g(are)h(\002rst)h(tried)e(case)h(sensiti)n(v)o(ely)-5 b(,)18 b(then)208 1890 y(case)i(insensiti)n(v)o(ely)-5 b(.)208 2023 y(Optional)24 b FK(strict)k FN(is)e(a)g(\003ag)f (specifying)f(whether)g(the)h(list)h(of)f(kno)n(wn)f(MIME)h(types)g(is) h(limited)f(to)g(only)g(the)g(of)n(\002cial)g(types)208 2122 y(re)o(gistered)i(with)h(IAN)m(A)g(are)h(recognized.)47 b(When)28 b FK(strict)j FN(is)e(true)f(\(the)g(def)o(ault\),)h(only)e (the)i(IAN)m(A)f(types)g(are)g(supported;)208 2222 y(when)19 b FK(strict)k FN(is)e(f)o(alse,)g(some)f(additional)e(non-standard)g(b) n(ut)i(commonly)e(used)i(MIME)f(types)h(are)h(also)f(recognized.)0 2369 y FD(guess_all_extensions)p FJ(\()p FK(type)p FC([)p FK(,)c(strict)d FC(])p FJ(\))208 2468 y FN(Guess)19 b(the)g(e)o (xtensions)f(for)g(a)i(\002le)f(based)g(on)f(its)i(MIME)f(type,)f(gi)n (v)o(en)g(by)h FK(type)p FN(.)24 b(The)19 b(return)f(v)n(alue)g(is)i(a) f(list)h(of)f(strings)g(gi)n(ving)208 2568 y(all)f(possible)h (\002lename)e(e)o(xtensions,)h(including)e(the)j(leading)e(dot)h(\(`)p FJ(.)p FN('\).)23 b(The)18 b(e)o(xtensions)g(are)g(not)g(guaranteed)e (to)i(ha)n(v)o(e)g(been)208 2668 y(associated)i(with)g(an)o(y)f (particular)g(data)h(stream,)g(b)n(ut)g(w)o(ould)g(be)g(mapped)e(to)j (the)f(MIME)g(type)g FK(type)g FN(by)f FJ(guess_type\(\))p FN(.)208 2801 y(Optional)g FK(strict)k FN(has)d(the)g(same)h(meaning)d (as)j(with)g(the)f FJ(guess_type\(\))e FN(function.)0 2947 y FD(guess_extension)p FJ(\()p FK(type)p FC([)p FK(,)f(strict)c FC(])p FJ(\))208 3047 y FN(Guess)29 b(the)f(e)o (xtension)f(for)h(a)h(\002le)g(based)f(on)g(its)i(MIME)e(type,)i(gi)n (v)o(en)d(by)h FK(type)p FN(.)50 b(The)28 b(return)f(v)n(alue)h(is)i(a) f(string)f(gi)n(ving)f(a)208 3147 y(\002lename)f(e)o(xtension,)h (including)e(the)i(leading)f(dot)h(\(`)p FJ(.)p FN('\).)44 b(The)27 b(e)o(xtension)f(is)h(not)g(guaranteed)e(to)i(ha)n(v)o(e)f (been)h(associated)208 3246 y(with)k(an)o(y)f(particular)f(data)i (stream,)i(b)n(ut)e(w)o(ould)f(be)g(mapped)g(to)h(the)f(MIME)h(type)f FK(type)h FN(by)f FJ(guess_type\(\))p FN(.)55 b(If)31 b(no)208 3346 y(e)o(xtension)18 b(can)i(be)g(guessed)g(for)g FK(type)p FN(,)f FJ(None)h FN(is)i(returned.)208 3479 y(Optional)d FK(strict)k FN(has)d(the)g(same)h(meaning)d(as)j(with)g (the)f FJ(guess_type\(\))e FN(function.)0 3626 y(Some)i(additional)f (functions)f(and)i(data)g(items)h(are)f(a)n(v)n(ailable)g(for)f (controlling)f(the)j(beha)n(vior)d(of)i(the)g(module.)0 3772 y FD(init)p FJ(\()p FC([)p FK(\002les)12 b FC(])p FJ(\))208 3872 y FN(Initialize)23 b(the)h(internal)g(data)g (structures.)35 b(If)24 b(gi)n(v)o(en,)g FK(\002les)g FN(must)g(be)g(a)h(sequence)e(of)h(\002le)g(names)g(which)g(should)f (be)h(used)f(to)208 3972 y(augment)c(the)h(def)o(ault)g(type)g(map.)25 b(If)20 b(omitted,)g(the)h(\002le)g(names)f(to)g(use)h(are)g(tak)o(en)f (from)f FJ(knownfiles)p FN(.)25 b(Each)20 b(\002le)h(named)208 4071 y(in)f FK(\002les)g FN(or)g FJ(knownfiles)f FN(tak)o(es)i (precedence)d(o)o(v)o(er)h(those)h(named)f(before)g(it.)25 b(Calling)20 b FJ(init\(\))g FN(repeatedly)f(is)i(allo)n(wed.)0 4218 y FD(read_mime_types)p FJ(\()p FK(\002lename)p FJ(\))208 4318 y FN(Load)27 b(the)h(type)f(map)h(gi)n(v)o(en)e(in)j(the)f(\002le) g FK(\002lename)p FN(,)h(if)f(it)h(e)o(xists.)48 b(The)28 b(type)g(map)f(is)i(returned)d(as)j(a)f(dictionary)e(mapping)208 4417 y(\002lename)21 b(e)o(xtensions,)f(including)g(the)i(leading)f (dot)g(\(`)p FJ(.)p FN('\),)g(to)h(strings)g(of)f(the)h(form)f FJ(')p FK(type)p FJ(/)p FK(subtype)p FJ(')p FN(.)27 b(If)22 b(the)f(\002le)i FK(\002lename)208 4517 y FN(does)c(not)h(e)o(xist)h (or)f(cannot)f(be)h(read,)f FJ(None)h FN(is)h(returned.)0 4664 y FD(add_type)p FJ(\()p FK(type)o(,)d(e)n(xt)q FC([)p FK(,)j(strict)13 b FC(])p FJ(\))208 4764 y FN(Add)25 b(a)h(mapping)e(from)g(the)i(mimetype)e FK(type)i FN(to)g(the)f(e)o (xtension)g FK(e)n(xt)q FN(.)42 b(When)26 b(the)f(e)o(xtension)g(is)h (already)f(kno)n(wn,)g(the)h(ne)n(w)208 4863 y(type)21 b(will)i(replace)e(the)h(old)f(one.)30 b(When)22 b(the)g(type)f(is)i (already)e(kno)n(wn)g(the)g(e)o(xtension)g(will)i(be)f(added)e(to)i (the)g(list)h(of)f(kno)n(wn)208 4963 y(e)o(xtensions.)208 5096 y(When)e FK(strict)j FN(is)e(the)f(mapping)e(will)j(added)e(to)h (the)h(of)n(\002cial)f(MIME)f(types,)h(otherwise)g(to)g(the)g (non-standard)d(ones.)0 5243 y FD(inited)208 5342 y FN(Flag)j (indicating)f(whether)g(or)h(not)g(the)g(global)f(data)h(structures)g (ha)n(v)o(e)f(been)h(initialized.)k(This)d(is)g(set)g(to)f(true)g(by)g FJ(init\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(7.6.)52 b FJ(mimetypes)22 b FI(\227)h(Map)g(\002lenames)g(to)h(MIME)g(types) 1900 b(241)p eop end %%Page: 242 254 TeXDict begin 242 253 bop 0 83 a FD(knownfiles)208 183 y FN(List)21 b(of)f(type)g(map)g(\002le)i(names)e(commonly)e (installed.)26 b(These)21 b(\002les)g(are)g(typically)e(named)h(`)p FO(mime)o(.types)p FN(')f(and)h(are)h(installed)208 282 y(in)f(dif)n(ferent)e(locations)i(by)g(dif)n(ferent)e(packages.)0 429 y FD(suffix_map)208 529 y FN(Dictionary)c(mapping)f(suf)n(\002x)o (es)i(to)h(suf)n(\002x)o(es.)23 b(This)16 b(is)g(used)f(to)h(allo)n(w)g (recognition)d(of)i(encoded)f(\002les)i(for)f(which)g(the)h(encoding) 208 628 y(and)f(the)i(type)f(are)g(indicated)g(by)g(the)g(same)h(e)o (xtension.)22 b(F)o(or)16 b(e)o(xample,)g(the)g(`)p FO(.tgz)p FN(')g(e)o(xtension)f(is)i(mapped)e(to)i(`)p FO(.tar)l(.gz)p FN(')e(to)i(allo)n(w)208 728 y(the)j(encoding)e(and)i(type)f(to)i(be)f (recognized)e(separately)-5 b(.)0 875 y FD(encodings_map)208 975 y FN(Dictionary)18 b(mapping)h(\002lename)g(e)o(xtensions)g(to)i (encoding)d(types.)0 1121 y FD(types_map)208 1221 y FN(Dictionary)g (mapping)h(\002lename)g(e)o(xtensions)g(to)i(MIME)f(types.)0 1368 y FD(common_types)208 1468 y FN(Dictionary)e(mapping)h(\002lename) g(e)o(xtensions)g(to)i(non-standard,)c(b)n(ut)j(commonly)e(found)g (MIME)i(types.)0 1614 y(The)g FJ(MimeTypes)f FN(class)i(may)f(be)g (useful)g(for)f(applications)g(which)h(may)g(w)o(ant)g(more)f(than)h (one)g(MIME-type)e(database:)0 1761 y FL(class)j FD(MimeTypes)p FJ(\()p FC([)p FK(\002lenames)12 b FC(])p FJ(\))208 1861 y FN(This)26 b(class)h(represents)e(a)i(MIME-types)d(database.)42 b(By)27 b(def)o(ault,)f(it)h(pro)o(vides)d(access)j(to)f(the)g(same)h (database)e(as)i(the)f(rest)208 1961 y(of)21 b(this)i(module.)28 b(The)22 b(initial)g(database)f(is)i(a)g(cop)o(y)e(of)g(that)h(pro)o (vided)e(by)h(the)h(module,)f(and)g(may)h(be)g(e)o(xtended)d(by)j (loading)208 2060 y(additional)f(`)p FO(mime)o(.types)p FN('-style)g(\002les)j(into)f(the)g(database)f(using)g(the)h FJ(read\(\))f FN(or)h FJ(readfp\(\))f FN(methods.)32 b(The)22 b(mapping)208 2160 y(dictionaries)d(may)g(also)i(be)f(cleared) f(before)g(loading)g(additional)g(data)h(if)g(the)h(def)o(ault)e(data)h (is)h(not)f(desired.)208 2293 y(The)29 b(optional)g FK(\002lenames)h FN(parameter)e(can)i(be)g(used)g(to)g(cause)h(additional)d(\002les)j (to)g(be)f(loaded)f(\223on)h(top\224)f(of)h(the)g(def)o(ault)208 2392 y(database.)208 2525 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 2672 y(An)h(e)o(xample)f(usage)h(of)g(the)g(module:)236 2910 y FA(>>>)45 b(import)e(mimetypes)236 3001 y(>>>)i (mimetypes.init\(\))236 3093 y(>>>)g(mimetypes.knownfiles)236 3184 y(['/etc/mime.types',)d('/etc/httpd/mime.types',)f(...)j(])236 3275 y(>>>)h(mimetypes.suffix_map['.tgz'])236 3367 y('.tar.gz')236 3458 y(>>>)g(mimetypes.encodings_map['.gz'])236 3549 y('gzip')236 3641 y(>>>)g(mimetypes.types_map['.tgz'])236 3732 y('application/x-tar-gz')0 4157 y Fv(7.6.1)100 b(MimeT)-12 b(ypes)29 b(Objects)0 4360 y FJ(MimeTypes)19 b FN(instances)h(pro)o (vide)e(an)i(interf)o(ace)g(which)f(is)j(v)o(ery)d(lik)o(e)h(that)g(of) g(the)g FJ(mimetypes)g FN(module.)0 4507 y FD(suffix_map)208 4606 y FN(Dictionary)14 b(mapping)f(suf)n(\002x)o(es)i(to)h(suf)n (\002x)o(es.)23 b(This)16 b(is)g(used)f(to)h(allo)n(w)g(recognition)d (of)i(encoded)f(\002les)i(for)f(which)g(the)h(encoding)208 4706 y(and)f(the)i(type)f(are)g(indicated)g(by)g(the)g(same)h(e)o (xtension.)22 b(F)o(or)16 b(e)o(xample,)g(the)g(`)p FO(.tgz)p FN(')g(e)o(xtension)f(is)i(mapped)e(to)i(`)p FO(.tar)l(.gz)p FN(')e(to)i(allo)n(w)208 4805 y(the)k(encoding)f(and)h(type)g(to)h(be)f (recognized)f(separately)-5 b(.)28 b(This)22 b(is)g(initially)g(a)g (cop)o(y)f(of)g(the)h(global)e FJ(suffix_map)h FN(de\002ned)208 4905 y(in)f(the)g(module.)0 5052 y FD(encodings_map)208 5152 y FN(Dictionary)15 b(mapping)f(\002lename)i(e)o(xtensions)f(to)i (encoding)d(types.)24 b(This)16 b(is)h(initially)g(a)g(cop)o(y)e(of)h (the)h(global)e FJ(encodings_-)208 5251 y(map)20 b FN(de\002ned)f(in)h (the)g(module.)0 5398 y FD(types_map)p 0 5549 3901 4 v 0 5649 a FI(242)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 243 255 TeXDict begin 243 254 bop 208 83 a FN(Dictionary)26 b(mapping)f (\002lename)i(e)o(xtensions)f(to)i(MIME)f(types.)47 b(This)27 b(is)i(initially)e(a)h(cop)o(y)e(of)i(the)f(global)g FJ(types_map)208 183 y FN(de\002ned)19 b(in)h(the)g(module.)0 330 y FD(common_types)208 429 y FN(Dictionary)g(mapping)g(\002lename)h (e)o(xtensions)f(to)i(non-standard,)d(b)n(ut)j(commonly)d(found)h(MIME) h(types.)29 b(This)22 b(is)h(initially)e(a)208 529 y(cop)o(y)e(of)h (the)g(global)f FJ(common_types)g FN(de\002ned)g(in)h(the)h(module.)0 676 y FD(guess_extension)p FJ(\()p FK(type)p FC([)p FK(,)c(strict)c FC(])p FJ(\))208 775 y FN(Similar)20 b(to)g(the)g FJ (guess_extension\(\))e FN(function,)g(using)i(the)g(tables)g(stored)g (as)h(part)f(of)g(the)g(object.)0 922 y FD(guess_type)p FJ(\()p FK(url)p FC([)p FK(,)e(strict)13 b FC(])p FJ(\))208 1022 y FN(Similar)20 b(to)g(the)g FJ(guess_type\(\))f FN(function,)f(using)i(the)g(tables)g(stored)g(as)h(part)f(of)g(the)g (object.)0 1169 y FD(read)p FJ(\()p FK(path)p FJ(\))208 1268 y FN(Load)f(MIME)h(information)d(from)j(a)g(\002le)h(named)e FK(path)p FN(.)24 b(This)d(uses)f FJ(readfp\(\))g FN(to)g(parse)g(the)g (\002le.)0 1415 y FD(readfp)p FJ(\()p FK(\002le)p FJ(\))208 1515 y FN(Load)25 b(MIME)h(type)f(information)f(from)h(an)h(open)f (\002le.)44 b(The)26 b(\002le)h(must)f(ha)n(v)o(e)f(the)i(format)e(of)h (the)g(standard)f(`)p FO(mime)o(.types)p FN(')208 1614 y(\002les.)0 1942 y FE(7.7)121 b Fx(MimeWriter)30 b FE(\227)j(Gener)r (ic)h(MIME)e(\002le)h(wr)r(iter)0 2175 y FL(Depr)o(ecated)20 b(since)h(r)o(elease)f(2.3.)27 b FN(The)20 b FJ(email)h FN(package)e(should)h(be)g(used)h(in)g(preference)e(to)i(the)f FJ(MimeWriter)g FN(module.)25 b(This)0 2274 y(module)19 b(is)i(present)e(only)h(to)g(maintain)g(backw)o(ard)e(compatibility)-5 b(.)0 2421 y(This)29 b(module)e(de\002nes)h(the)h(class)g FJ(MimeWriter)p FN(.)49 b(The)28 b FJ(MimeWriter)g FN(class)h (implements)f(a)h(basic)g(formatter)e(for)h(creating)0 2521 y(MIME)21 b(multi-part)f(\002les.)30 b(It)22 b(doesn')o(t)e(seek)i (around)d(the)j(output)e(\002le)i(nor)f(does)g(it)i(use)e(lar)o(ge)g (amounts)f(of)i(b)n(uf)n(fer)e(space.)29 b(Y)-9 b(ou)21 b(must)0 2620 y(write)f(the)g(parts)g(out)g(in)g(the)g(order)f(that)h (the)o(y)f(should)g(occur)g(in)h(the)g(\002nal)g(\002le.)26 b FJ(MimeWriter)19 b FN(does)g(b)n(uf)n(fer)g(the)h(headers)f(you)g (add,)0 2720 y(allo)n(wing)g(you)h(to)g(rearrange)e(their)i(order)-5 b(.)0 2867 y FL(class)21 b FD(MimeWriter)p FJ(\()p FK(fp)p FJ(\))208 2966 y FN(Return)g(a)i(ne)n(w)e(instance)h(of)g(the)g FJ(MimeWriter)e FN(class.)32 b(The)21 b(only)h(ar)o(gument)d(passed,)j FK(fp)p FN(,)h(is)g(a)f(\002le)h(object)e(to)h(be)g(used)g(for)208 3066 y(writing.)i(Note)c(that)g(a)h FJ(StringIO)e FN(object)h(could)f (also)i(be)f(used.)0 3351 y Fv(7.7.1)100 b(MimeWr)q(iter)29 b(Objects)0 3554 y FJ(MimeWriter)19 b FN(instances)h(ha)n(v)o(e)g(the)g (follo)n(wing)e(methods:)0 3701 y FD(addheader)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(value)p FC([)p FK(,)h(pr)m(e\002x)12 b FC(])p FJ(\))208 3800 y FN(Add)18 b(a)h(header)f(line)h(to)g(the)g (MIME)f(message.)25 b(The)18 b FK(k)o(e)n(y)h FN(is)h(the)f(name)f(of)h (the)g(header)m(,)e(where)h(the)h FK(value)g FN(ob)o(viously)d(pro)o (vides)208 3900 y(the)h(v)n(alue)g(of)h(the)f(header)-5 b(.)24 b(The)17 b(optional)f(ar)o(gument)g FK(pr)m(e\002x)h FN(determines)g(where)g(the)g(header)g(is)i(inserted;)f(`)p FJ(0)p FN(')f(means)g(append)208 4000 y(at)j(the)g(end,)g(`)p FJ(1)p FN(')g(is)h(insert)f(at)h(the)f(start.)25 b(The)20 b(def)o(ault)g(is)h(to)f(append.)0 4147 y FD(flushheaders)p FJ(\(\))208 4246 y FN(Causes)h(all)h(headers)e(accumulated)f(so)j(f)o (ar)f(to)g(be)g(written)f(out)h(\(and)f(for)o(gotten\).)25 b(This)c(is)h(useful)e(if)i(you)e(don')o(t)f(need)i(a)g(body)208 4346 y(part)e(at)i(all,)g(e.g.)e(for)h(a)g(subpart)g(of)g(type)f FO(message/rfc822)g FN(that')-5 b(s)20 b(\(mis\)used)f(to)i(store)f (some)g(header)n(-lik)o(e)f(information.)0 4493 y FD(startbody)p FJ(\()p FK(ctype)p FC([)p FK(,)f(plist)q FC([)p FK(,)i(pr)m(e\002x)12 b FC(])g(])p FJ(\))208 4592 y FN(Returns)22 b(a)h(\002le-lik)o(e)f (object)g(which)g(can)g(be)g(used)g(to)h(write)f(to)h(the)f(body)f(of)h (the)g(message.)32 b(The)22 b(content-type)e(is)j(set)g(to)g(the)208 4692 y(pro)o(vided)16 b FK(ctype)p FN(,)i(and)g(the)h(optional)e (parameter)g FK(plist)j FN(pro)o(vides)d(additional)g(parameters)h(for) g(the)g(content-type)e(declaration.)208 4792 y FK(pr)m(e\002x)k FN(functions)e(as)j(in)g FJ(addheader\(\))d FN(e)o(xcept)h(that)i(the)f (def)o(ault)f(is)j(to)e(insert)g(at)h(the)f(start.)0 4938 y FD(startmultipartbody)p FJ(\()p FK(subtype)p FC([)p FK(,)15 b(boundary)p FC([)p FK(,)j(plist)q FC([)p FK(,)j(pr)m(e\002x)12 b FC(])g(])g(])p FJ(\))208 5038 y FN(Returns)28 b(a)h(\002le-lik)o(e)f (object)g(which)g(can)g(be)g(used)g(to)h(write)f(to)h(the)f(body)f(of)h (the)h(message.)49 b(Additionally)-5 b(,)28 b(this)h(method)208 5138 y(initializes)g(the)g(multi-part)f(code,)i(where)e FK(subtype)g FN(pro)o(vides)f(the)i(multipart)f(subtype,)i FK(boundary)d FN(may)h(pro)o(vide)f(a)j(user)n(-)208 5237 y(de\002ned)25 b(boundary)f(speci\002cation,)k(and)e FK(plist)j FN(pro)o(vides)c(optional)g(parameters)h(for)g(the)h (subtype.)43 b FK(pr)m(e\002x)27 b FN(functions)e(as)i(in)208 5337 y FJ(startbody\(\))p FN(.)c(Subparts)c(should)g(be)i(created)e (using)h FJ(nextpart\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(7.7.)52 b FJ(MimeWriter)21 b FI(\227)i(Gener)q(ic)g(MIME)h(\002le) f(wr)q(iter)2057 b(243)p eop end %%Page: 244 256 TeXDict begin 244 255 bop 0 83 a FD(nextpart)p FJ(\(\))208 183 y FN(Returns)20 b(a)h(ne)n(w)f(instance)g(of)g FJ(MimeWriter)f FN(which)h(represents)g(an)g(indi)n(vidual)f(part)h(in)h(a)f(multipart) g(message.)25 b(This)c(may)208 282 y(be)c(used)h(to)g(write)g(the)g (part)f(as)i(well)f(as)h(used)e(for)g(creating)g(recursi)n(v)o(ely)f (comple)o(x)g(multipart)h(messages.)24 b(The)18 b(message)g(must)208 382 y(\002rst)i(be)h(initialized)e(with)i FJ(startmultipartbody\(\))c FN(before)i(using)g FJ(nextpart\(\))p FN(.)0 529 y FD(lastpart)p FJ(\(\))208 628 y FN(This)g(is)h(used)f(to)g(designate)f(the)h(last)h (part)f(of)g(a)h(multipart)e(message,)h(and)f(should)g FK(always)i FN(be)f(used)g(when)f(writing)h(multipart)208 728 y(messages.)0 1055 y FE(7.8)121 b Fx(mimify)31 b FE(\227)i(MIME)g(processing)h(of)g(mail)e(messages)0 1288 y FL(Depr)o(ecated)15 b(since)j(r)o(elease)d(2.3.)24 b FN(The)16 b FJ(email)g FN(package)f(should)g(be)i(used)f(in)h (preference)d(to)j(the)f FJ(mimify)g FN(module.)22 b(This)17 b(module)0 1388 y(is)k(present)f(only)f(to)h(maintain)g(backw)o(ard)e (compatibility)-5 b(.)0 1535 y(The)23 b FJ(mimify)f FN(module)g (de\002nes)h(tw)o(o)g(functions)f(to)h(con)m(v)o(ert)e(mail)i(messages) h(to)f(and)f(from)h(MIME)f(format.)33 b(The)22 b(mail)i(message)0 1634 y(can)h(be)f(either)h(a)g(simple)g(message)f(or)h(a)g(so-called)f (multipart)g(message.)38 b(Each)24 b(part)h(is)g(treated)g(separately) -5 b(.)37 b(Mimifying)23 b(\(a)i(part)0 1734 y(of\))18 b(a)h(message)g(entails)g(encoding)d(the)j(message)g(as)g (quoted-printable)c(if)k(it)h(contains)e(an)o(y)g(characters)f(that)i (cannot)f(be)g(represented)0 1834 y(using)26 b(7-bit)j FH(A)t(S)t(C)t(I)t(I)r FN(.)47 b(Unmimifying)24 b(\(a)j(part)g(of\))f (a)i(message)e(entails)i(undoing)c(the)j(quoted-printable)d(encoding.) 43 b(Mimify)26 b(and)0 1933 y(unmimify)18 b(are)i(especially)g(useful)g (when)f(a)i(message)f(has)g(to)h(be)f(edited)g(before)e(being)i(sent.) 25 b(T)-7 b(ypical)20 b(use)g(w)o(ould)f(be:)236 2171 y FA(unmimify)44 b(message)236 2263 y(edit)g(message)236 2354 y(mimify)g(message)236 2445 y(send)g(message)0 2732 y FN(The)20 b(modules)f(de\002nes)h(the)g(follo)n(wing)f(user)n (-callable)g(functions)g(and)g(user)n(-settable)h(v)n(ariables:)0 2879 y FD(mimify)p FJ(\()p FK(in\002le)o(,)e(out\002le)p FJ(\))208 2978 y FN(Cop)o(y)h(the)h(message)g(in)g FK(in\002le)g FN(to)g FK(out\002le)p FN(,)f(con)m(v)o(erting)e(parts)j(to)g (quoted-printable)c(and)k(adding)e(MIME)i(mail)g(headers)f(when)208 3078 y(necessary)-5 b(.)24 b FK(in\002le)c FN(and)g FK(out\002le)f FN(can)h(be)h(\002le)g(objects)f(\(actually)-5 b(,)19 b(an)o(y)g(object)h(that)g(has)h(a)g FJ(readline\(\))e FN(method)g(\(for)g FK(in\002le)p FN(\))208 3178 y(or)k(a)h FJ(write\(\))f FN(method)g(\(for)g FK(out\002le)p FN(\)\))f(or)h (strings)h(naming)f(the)h(\002les.)36 b(If)24 b FK(in\002le)f FN(and)h FK(out\002le)f FN(are)g(both)g(strings,)i(the)o(y)e(may)208 3277 y(ha)n(v)o(e)c(the)h(same)h(v)n(alue.)0 3424 y FD(unmimify)p FJ(\()p FK(in\002le)o(,)d(out\002le)p FC([)p FK(,)h(decode)p 1186 3424 25 4 v 28 w(base64)12 b FC(])p FJ(\))208 3524 y FN(Cop)o(y)25 b(the)g(message)h(in)f FK(in\002le)g FN(to)h FK(out\002le)p FN(,)g(decoding)d(all)j(quoted-printable)c (parts.)41 b FK(in\002le)25 b FN(and)g FK(out\002le)g FN(can)g(be)h(\002le)g(objects)208 3623 y(\(actually)-5 b(,)18 b(an)o(y)h(object)g(that)h(has)g(a)g FJ(readline\(\))f FN(method)f(\(for)h FK(in\002le)p FN(\))g(or)g(a)i FJ(write\(\))e FN(method)f(\(for)h FK(out\002le)p FN(\)\))f(or)i(strings)208 3723 y(naming)27 b(the)i(\002les.)52 b(If)29 b FK(in\002le)f FN(and)g FK(out\002le)g FN(are)h(both)f(strings,)j(the)o(y)d(may)h(ha)n (v)o(e)f(the)h(same)g(v)n(alue.)50 b(If)29 b(the)g FK(decode)p 3642 3723 V 28 w(base64)208 3823 y FN(ar)o(gument)17 b(is)22 b(pro)o(vided)17 b(and)j(tests)h(true,)f(an)o(y)f(parts)h(that) h(are)f(coded)f(in)h(the)g(base64)g(encoding)e(are)i(decoded)e(as)j (well.)0 3970 y FD(mime_decode_header)p FJ(\()p FK(line)p FJ(\))208 4069 y FN(Return)15 b(a)h(decoded)e(v)o(ersion)h(of)h(the)g (encoded)e(header)g(line)i(in)h FK(line)p FN(.)23 b(This)16 b(only)f(supports)g(the)h(ISO)g(8859-1)e(charset)i(\(Latin-1\).)0 4216 y FD(mime_encode_header)p FJ(\()p FK(line)p FJ(\))208 4316 y FN(Return)j(a)i(MIME-encoded)c(v)o(ersion)i(of)h(the)g(header)f (line)h(in)h FK(line)p FN(.)0 4463 y FD(MAXLEN)208 4562 y FN(By)27 b(def)o(ault,)g(a)g(part)f(will)h(be)g(encoded)e(as)i (quoted-printable)c(when)j(it)h(contains)f(an)o(y)g(non-)r FH(A)t(S)t(C)t(I)t(I)i FN(characters)e(\(characters)208 4662 y(with)20 b(the)g(8th)g(bit)g(set\),)h(or)f(if)g(there)g(are)g(an) o(y)f(lines)i(longer)e(than)h FJ(MAXLEN)f FN(characters)g(\(def)o(ault) h(v)n(alue)f(200\).)0 4809 y FD(CHARSET)208 4908 y FN(When)g(not)h (speci\002ed)f(in)h(the)g(mail)g(headers,)f(a)h(character)f(set)h(must) g(be)g(\002lled)g(in.)25 b(The)19 b(string)h(used)g(is)g(stored)g(in)g FJ(CHARSET)p FN(,)208 5008 y(and)f(the)h(def)o(ault)g(v)n(alue)f(is)j (ISO-8859-1)17 b(\(also)j(kno)n(wn)f(as)i(Latin1)e(\(latin-one\)\).)0 5155 y(This)h(module)f(can)h(also)h(be)f(used)g(from)f(the)h(command)e (line.)25 b(Usage)c(is)g(as)g(follo)n(ws:)p 0 5549 3901 4 v 0 5649 a FI(244)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 245 257 TeXDict begin 245 256 bop 236 174 a FA(mimify.py)44 b(-e)g([-l)g (length])g([infile)g([outfile]])236 266 y(mimify.py)g(-d)g([-b])g ([infile)g([outfile]])0 505 y FN(to)23 b(encode)f(\(mimify\))g(and)h (decode)e(\(unmimify\))g(respecti)n(v)o(ely)-5 b(.)32 b FK(in\002le)23 b FN(def)o(aults)g(to)g(standard)f(input,)h FK(out\002le)g FN(def)o(aults)f(to)i(standard)0 605 y(output.)g(The)c (same)g(\002le)h(can)f(be)g(speci\002ed)g(for)f(input)h(and)f(output.)0 752 y(If)i(the)g FL(-l)g FN(option)f(is)i(gi)n(v)o(en)e(when)h (encoding,)e(if)i(there)g(are)g(an)o(y)f(lines)h(longer)f(than)h(the)g (speci\002ed)g FK(length)p FN(,)f(the)h(containing)e(part)i(will)0 851 y(be)f(encoded.)0 998 y(If)g(the)g FL(-b)h FN(option)e(is)i(gi)n(v) o(en)e(when)g(decoding,)f(an)o(y)i(base64)f(parts)h(will)h(be)f (decoded)f(as)h(well.)0 1145 y FL(See)h(Also:)0 1292 y FN(Module)e FJ(quopri)h FN(\(section)f(7.14\):)208 1392 y(Encode)f(and)i(decode)f(MIME)h(quoted-printable)c(\002les.)0 1719 y FE(7.9)121 b Fx(multifile)31 b FE(\227)h(Suppor)5 b(t)35 b(f)l(or)f(\002les)f(containing)i(distinct)e(par)5 b(ts)0 1952 y FL(Depr)o(ecated)22 b(since)i(r)o(elease)f(2.5.)34 b FN(The)23 b FJ(email)f FN(package)g(should)h(be)g(used)g(in)g (preference)f(to)h(the)g FJ(multifile)f FN(module.)33 b(This)0 2051 y(module)19 b(is)i(present)e(only)h(to)g(maintain)g (backw)o(ard)e(compatibility)-5 b(.)0 2198 y(The)18 b FJ(MultiFile)g FN(object)g(enables)h(you)e(to)i(treat)g(sections)g(of)f (a)i(te)o(xt)e(\002le)i(as)f(\002le-lik)o(e)g(input)f(objects,)g(with)h FJ('')g FN(being)f(returned)f(by)0 2298 y FJ(readline\(\))h FN(when)g(a)i(gi)n(v)o(en)e(delimiter)g(pattern)h(is)h(encountered.)i (The)d(def)o(aults)f(of)h(this)h(class)g(are)f(designed)f(to)h(mak)o(e) g(it)h(useful)0 2397 y(for)g(parsing)f(MIME)h(multipart)f(messages,)h (b)n(ut)g(by)g(subclassing)f(it)i(and)f(o)o(v)o(erriding)d(methods)i (it)i(can)f(be)g(easily)h(adapted)e(for)g(more)0 2497 y(general)g(use.)0 2644 y FL(class)i FD(MultiFile)p FJ(\()p FK(fp)p FC([)p FK(,)d(seekable)12 b FC(])p FJ(\))208 2744 y FN(Create)21 b(a)h(multi-\002le.)29 b(Y)-9 b(ou)21 b(must)g(instantiate)h(this)g(class)g(with)g(an)f(input)g(object)g(ar)o (gument)e(for)i(the)h FJ(MultiFile)e FN(instance)208 2843 y(to)g(get)g(lines)h(from,)e(such)h(as)g(a)h(\002le)g(object)f (returned)e(by)i FJ(open\(\))p FN(.)208 2976 y FJ(MultiFile)28 b FN(only)h(e)n(v)o(er)f(looks)i(at)g(the)f(input)g(object')-5 b(s)29 b FJ(readline\(\))p FN(,)i FJ(seek\(\))e FN(and)g FJ(tell\(\))g FN(methods,)i(and)e(the)208 3076 y(latter)22 b(tw)o(o)g(are)g(only)f(needed)g(if)i(you)e(w)o(ant)h(random)e(access)j (to)f(the)g(indi)n(vidual)f(MIME)g(parts.)31 b(T)-7 b(o)22 b(use)g FJ(MultiFile)f FN(on)h(a)208 3175 y(non-seekable)15 b(stream)j(object,)f(set)i(the)f(optional)f FK(seekable)g FN(ar)o(gument)f(to)i(f)o(alse;)h(this)f(will)h(pre)n(v)o(ent)d(using)i (the)g(input)f(object')-5 b(s)208 3275 y FJ(seek\(\))19 b FN(and)h FJ(tell\(\))f FN(methods.)0 3422 y(It)28 b(will)h(be)f (useful)g(to)g(kno)n(w)f(that)h(in)h FJ(MultiFile)p FN(')-5 b(s)27 b(vie)n(w)h(of)g(the)g(w)o(orld,)h(te)o(xt)f(is)h(composed)e(of) g(three)h(kinds)g(of)f(lines:)42 b(data,)0 3521 y(section-di)n(viders,) 33 b(and)f(end-mark)o(ers.)59 b(MultiFile)32 b(is)i(designed)d(to)h (support)f(parsing)h(of)g(messages)g(that)h(may)e(ha)n(v)o(e)h (multiple)0 3621 y(nested)20 b(message)g(parts,)g(each)g(with)g(its)h (o)n(wn)f(pattern)f(for)h(section-di)n(vider)d(and)j(end-mark)o(er)e (lines.)0 3768 y FL(See)j(Also:)0 3915 y FN(Module)e FJ(email)h FN(\(section)f(7.1\):)208 4014 y(Comprehensi)n(v)o(e)e (email)j(handling)f(package;)f(supersedes)i(the)g FJ(multifile)f FN(module.)0 4299 y Fv(7.9.1)100 b(MultiFile)29 b(Objects)0 4502 y FN(A)21 b FJ(MultiFile)e FN(instance)h(has)g(the)g(follo)n(wing) f(methods:)0 4649 y FD(readline)p FJ(\()p FK(str)r FJ(\))208 4749 y FN(Read)g(a)h(line.)25 b(If)19 b(the)g(line)h(is)g(data)f(\(not) g(a)h(section-di)n(vider)c(or)j(end-mark)o(er)e(or)i(real)h(EOF\))f (return)f(it.)26 b(If)19 b(the)g(line)h(matches)f(the)208 4848 y(most-recently-stack)o(ed)d(boundary)-5 b(,)17 b(return)i FJ('')h FN(and)f(set)i FJ(self.last)e FN(to)h(1)g(or)g(0)g (according)e(as)j(the)f(match)f(is)i(or)f(is)h(not)f(an)208 4948 y(end-mark)o(er)-5 b(.)30 b(If)22 b(the)h(line)g(matches)f(an)o(y) g(other)g(stack)o(ed)g(boundary)-5 b(,)20 b(raise)j(an)g(error)-5 b(.)31 b(On)23 b(encountering)d(end-of-\002le)g(on)j(the)208 5048 y(underlying)17 b(stream)j(object,)g(the)g(method)f(raises)h FJ(Error)g FN(unless)g(all)h(boundaries)d(ha)n(v)o(e)i(been)f(popped.)0 5195 y FD(readlines)p FJ(\()p FK(str)r FJ(\))208 5294 y FN(Return)g(all)i(lines)g(remaining)d(in)i(this)h(part)f(as)h(a)g (list)g(of)f(strings.)p 0 5549 3901 4 v 0 5649 a FI(7.9.)52 b FJ(multifile)22 b FI(\227)h(Suppor)s(t)h(f)n(or)e(\002les)h (containing)h(distinct)g(par)s(ts)1518 b(245)p eop end %%Page: 246 258 TeXDict begin 246 257 bop 0 83 a FD(read)p FJ(\(\))208 183 y FN(Read)24 b(all)h(lines,)h(up)e(to)h(the)f(ne)o(xt)g(section.)38 b(Return)24 b(them)g(as)h(a)g(single)g(\(multiline\))e(string.)37 b(Note)25 b(that)g(this)g(doesn')o(t)e(tak)o(e)h(a)208 282 y(size)c(ar)o(gument!)0 429 y FD(seek)p FJ(\()p FK(pos)p FC([)p FK(,)f(whence)12 b FC(])p FJ(\))208 529 y FN(Seek.)24 b(Seek)c(indices)g(are)f(relati)n(v)o(e)g(to)h(the)g(start)h(of)e(the)h (current)e(section.)25 b(The)20 b FK(pos)f FN(and)g FK(whence)h FN(ar)o(guments)e(are)h(interpreted)208 628 y(as)h(for)g(a)h(\002le)f (seek.)0 775 y FD(tell)p FJ(\(\))208 875 y FN(Return)f(the)i(\002le)f (position)g(relati)n(v)o(e)f(to)h(the)h(start)f(of)g(the)g(current)f (section.)0 1022 y FD(next)p FJ(\(\))208 1121 y FN(Skip)c(lines)h(to)f (the)h(ne)o(xt)f(section)g(\(that)g(is,)i(read)e(lines)h(until)f(a)h (section-di)n(vider)d(or)i(end-mark)o(er)e(has)j(been)f(consumed\).)21 b(Return)208 1221 y(true)e(if)i(there)f(is)h(such)f(a)g(section,)g(f)o (alse)h(if)f(an)g(end-mark)o(er)e(is)j(seen.)k(Re-enable)19 b(the)i(most-recently-pushed)16 b(boundary)-5 b(.)0 1368 y FD(is_data)p FJ(\()p FK(str)r FJ(\))208 1468 y FN(Return)23 b(true)g(if)i FK(str)i FN(is)d(data)g(and)f(f)o(alse)i(if)f(it)g(might) g(be)f(a)i(section)e(boundary)-5 b(.)33 b(As)25 b(written,)f(it)g (tests)h(for)f(a)g(pre\002x)f(other)g(than)208 1567 y FJ('--')j FN(at)h(start)g(of)f(line)h(\(which)f(all)h(MIME)f (boundaries)f(ha)n(v)o(e\))g(b)n(ut)i(it)g(is)h(declared)d(so)i(it)g (can)g(be)f(o)o(v)o(erridden)e(in)i(deri)n(v)o(ed)208 1667 y(classes.)208 1800 y(Note)f(that)g(this)h(test)g(is)g(used)f (intended)f(as)h(a)h(f)o(ast)g(guard)e(for)g(the)h(real)h(boundary)c (tests;)29 b(if)c(it)h(al)o(w)o(ays)g(returns)e(f)o(alse)i(it)g(will) 208 1899 y(merely)19 b(slo)n(w)h(processing,)f(not)h(cause)g(it)h(to)f (f)o(ail.)0 2046 y FD(push)p FJ(\()p FK(str)r FJ(\))208 2146 y FN(Push)c(a)g(boundary)d(string.)24 b(When)15 b(a)i(decorated)d(v)o(ersion)h(of)h(this)g(boundary)e(is)j(found)d(as)j (an)f(input)f(line,)i(it)g(will)f(be)g(interpreted)208 2245 y(as)28 b(a)h(section-di)n(vider)d(or)i(end-mark)o(er)d (\(depending)g(on)j(the)g(decoration,)g(see)h(RFC)g(2045\).)47 b(All)29 b(subsequent)e(reads)h(will)208 2345 y(return)23 b(the)i(empty)f(string)g(to)h(indicate)f(end-of-\002le,)g(until)g(a)h (call)h(to)e FJ(pop\(\))h FN(remo)o(v)o(es)e(the)i(boundary)c(a)26 b(or)e FJ(next\(\))g FN(call)208 2445 y(reenables)19 b(it.)208 2577 y(It)28 b(is)h(possible)f(to)g(push)f(more)g(than)h(one) g(boundary)-5 b(.)45 b(Encountering)25 b(the)j(most-recently-pushed)c (boundary)h(will)k(return)208 2677 y(EOF;)20 b(encountering)d(an)o(y)j (other)f(boundary)f(will)i(raise)h(an)f(error)-5 b(.)0 2824 y FD(pop)p FJ(\(\))208 2924 y FN(Pop)19 b(a)i(section)f(boundary) -5 b(.)22 b(This)e(boundary)d(will)k(no)f(longer)f(be)h(interpreted)f (as)h(EOF)-7 b(.)0 3070 y FD(section_divider)p FJ(\()p FK(str)r FJ(\))208 3170 y FN(T)l(urn)28 b(a)h(boundary)e(into)h(a)i (section-di)n(vider)d(line.)51 b(By)30 b(def)o(ault,)g(this)g(method)e (prepends)f FJ('--')i FN(\(which)f(MIME)h(section)208 3270 y(boundaries)19 b(ha)n(v)o(e\))i(b)n(ut)h(it)g(is)h(declared)d(so) i(it)h(can)e(be)h(o)o(v)o(erridden)c(in)k(deri)n(v)o(ed)e(classes.)31 b(This)21 b(method)g(need)g(not)g(append)f(LF)208 3369 y(or)f(CR-LF)-7 b(,)22 b(as)f(comparison)d(with)i(the)g(result)g (ignores)g(trailing)f(whitespace.)0 3516 y FD(end_marker)p FJ(\()p FK(str)r FJ(\))208 3616 y FN(T)l(urn)25 b(a)i(boundary)d (string)i(into)h(an)f(end-mark)o(er)e(line.)45 b(By)27 b(def)o(ault,)g(this)g(method)e(prepends)g FJ('--')h FN(and)h(appends)e FJ('--')208 3715 y FN(\(lik)o(e)h(a)i (MIME-multipart)c(end-of-message)g(mark)o(er\))i(b)n(ut)h(it)g(is)h (declared)e(so)h(it)g(can)g(be)g(o)o(v)o(erridden)d(in)j(deri)n(v)o(ed) e(classes.)208 3815 y(This)20 b(method)f(need)g(not)h(append)f(LF)h(or) g(CR-LF)-7 b(,)21 b(as)g(comparison)d(with)j(the)f(result)g(ignores)f (trailing)h(whitespace.)0 3962 y(Finally)-5 b(,)19 b FJ(MultiFile)g FN(instances)i(ha)n(v)o(e)e(tw)o(o)i(public)e(instance)h (v)n(ariables:)0 4109 y FD(level)208 4208 y FN(Nesting)g(depth)f(of)h (the)g(current)f(part.)0 4355 y FD(last)208 4455 y FN(T)m(rue)g(if)i (the)f(last)h(end-of-\002le)d(w)o(as)j(for)f(an)g(end-of-message)d (mark)o(er)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(246)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 247 259 TeXDict begin 247 258 bop 0 83 a Fv(7.9.2)100 b Fm(MultiFile)26 b Fv(Example)0 377 y FA(import)44 b(mimetools)0 469 y(import)g (multifile)0 560 y(import)g(StringIO)0 743 y(def)g (extract_mime_part_matching\(stream,)39 b(mimetype\):)179 834 y("""Return)44 b(the)g(first)g(element)g(in)g(a)h(multipart)e(MIME) h(message)g(on)g(stream)179 925 y(matching)g(mimetype.""")179 1108 y(msg)h(=)f(mimetools.Message\(stream\))179 1199 y(msgtype)g(=)h(msg.gettype\(\))179 1290 y(params)f(=)h (msg.getplist\(\))179 1473 y(data)f(=)h(StringIO.StringIO\(\))179 1564 y(if)g(msgtype[:10])e(==)h("multipart/":)359 1747 y(file)g(=)g(multifile.MultiFile\(stream\))359 1838 y (file.push\(msg.getparam\("boundary"\)\))359 1930 y(while)g (file.next\(\):)538 2021 y(submsg)g(=)g(mimetools.Message\(file\))538 2112 y(try:)717 2204 y(data)g(=)h(StringIO.StringIO\(\))717 2295 y(mimetools.decode\(file,)c(data,)j(submsg.getencoding\(\)\))538 2386 y(except)g(ValueError:)717 2478 y(continue)538 2569 y(if)g(submsg.gettype\(\))f(==)h(mimetype:)717 2660 y(break)359 2752 y(file.pop\(\))179 2843 y(return)g(data.getvalue\(\))0 3292 y FE(7.10)121 b Fx(rfc822)32 b FE(\227)h(P)-5 b(arse)33 b(RFC)h(2822)h(mail)e(headers)0 3525 y FL(Depr)o(ecated)15 b(since)j(r)o(elease)d(2.3.)24 b FN(The)16 b FJ(email)g FN(package)f(should)g(be)i(used)f(in)h(preference)d(to)j(the)f FJ(rfc822)g FN(module.)22 b(This)17 b(module)0 3624 y(is)k(present)f (only)f(to)h(maintain)g(backw)o(ard)e(compatibility)-5 b(.)0 3771 y(This)19 b(module)e(de\002nes)i(a)g(class,)g FJ(Message)p FN(,)f(which)h(represents)e(an)i(\223email)g(message\224)f (as)h(de\002ned)f(by)g(the)h(Internet)f(standard)f(RFC)0 3871 y(2822.)189 3841 y FF(6)260 3871 y FN(Such)25 b(messages)g (consist)g(of)g(a)g(collection)f(of)h(message)f(headers,)h(and)g(a)g (message)g(body)-5 b(.)37 b(This)26 b(module)d(also)i(de\002nes)g(a)0 3970 y(helper)19 b(class)j FJ(AddressList)d FN(for)g(parsing)h(RFC)i (2822)d(addresses.)25 b(Please)c(refer)e(to)i(the)f(RFC)i(for)e (information)e(on)i(the)g(speci\002c)0 4070 y(syntax)g(of)f(RFC)j(2822) d(messages.)0 4217 y(The)h FJ(mailbox)f FN(module)g(pro)o(vides)g (classes)i(to)f(read)g(mailbox)o(es)f(produced)e(by)j(v)n(arious)f (end-user)g(mail)h(programs.)0 4364 y FL(class)h FD(Message)p FJ(\()p FK(\002le)p FC([)p FK(,)d(seekable)12 b FC(])p FJ(\))208 4463 y FN(A)21 b FJ(Message)g FN(instance)g(is)h (instantiated)f(with)h(an)f(input)g(object)g(as)h(parameter)-5 b(.)27 b(Message)22 b(relies)f(only)g(on)g(the)g(input)g(object)208 4563 y(ha)n(ving)c(a)j FJ(readline\(\))e FN(method;)g(in)h(particular)m (,)f(ordinary)e(\002le)k(objects)f(qualify)-5 b(.)23 b(Instantiation)18 b(reads)g(headers)h(from)f(the)208 4663 y(input)23 b(object)g(up)h(to)g(a)g(delimiter)g(line)g(\(normally) e(a)i(blank)f(line\))h(and)f(stores)i(them)e(in)h(the)g(instance.)36 b(The)24 b(message)g(body)-5 b(,)208 4762 y(follo)n(wing)18 b(the)i(headers,)f(is)i(not)f(consumed.)208 4895 y(This)k(class)h(can)f (w)o(ork)g(with)g(an)o(y)g(input)f(object)h(that)g(supports)f(a)i FJ(readline\(\))e FN(method.)35 b(If)25 b(the)f(input)f(object)h(has)g (seek)208 4995 y(and)k(tell)i(capability)-5 b(,)30 b(the)g FJ(rewindbody\(\))d FN(method)h(will)i(w)o(ork;)k(also,)d(ille)o(gal)e (lines)h(will)g(be)f(pushed)f(back)h(onto)g(the)208 5094 y(input)23 b(stream.)38 b(If)24 b(the)h(input)f(object)g(lacks)g(seek)h (b)n(ut)f(has)h(an)g FJ(unread\(\))e FN(method)g(that)i(can)f(push)g (back)g(a)h(line)f(of)h(input,)p 0 5165 1560 4 v 90 5221 a FB(6)120 5244 y FH(This)d(module)i(originally)i(conformed)e(to)f(RFC) g(822,)h(hence)h(the)e(name.)39 b(Since)24 b(then,)h(RFC)e(2822)h(has)f (been)g(released)j(as)c(an)i(update)g(to)f(RFC)g(822.)39 b(This)0 5323 y(module)18 b(should)g(be)f(considered)i(RFC)e (2822-conformant,)j(especially)g(in)d(cases)h(where)g(the)g(syntax)g (or)e(semantics)j(ha)o(v)o(e)f(changed)h(since)f(RFC)f(822.)p 0 5549 3901 4 v 0 5649 a FI(7.10.)52 b FJ(rfc822)22 b FI(\227)h(P)m(arse)g(RFC)g(2822)g(mail)i(headers)1984 b(247)p eop end %%Page: 248 260 TeXDict begin 248 259 bop 208 83 a FJ(Message)19 b FN(will)i(use)g (that)f(to)h(push)f(back)f(ille)o(gal)h(lines.)26 b(Thus)20 b(this)h(class)g(can)f(be)h(used)f(to)g(parse)g(messages)h(coming)e (from)g(a)208 183 y(b)n(uf)n(fered)f(stream.)208 315 y(The)23 b(optional)g FK(seekable)g FN(ar)o(gument)e(is)k(pro)o(vided)c (as)k(a)f(w)o(orkaround)d(for)i(certain)h(stdio)f(libraries)h(in)g (which)f FJ(tell\(\))g FN(dis-)208 415 y(cards)f(b)n(uf)n(fered)e(data) j(before)e(disco)o(v)o(ering)f(that)j(the)f FJ(lseek\(\))g FN(system)h(call)g(doesn')o(t)e(w)o(ork.)32 b(F)o(or)22 b(maximum)f(portability)-5 b(,)208 515 y(you)26 b(should)h(set)h(the)g (seekable)f(ar)o(gument)e(to)j(zero)f(to)h(pre)n(v)o(ent)e(that)h (initial)h FJ(tell\(\))g FN(when)f(passing)g(in)h(an)f(unseekable)208 614 y(object)19 b(such)h(as)h(a)g(\002le)g(object)e(created)h(from)f(a) h(sock)o(et)g(object.)208 747 y(Input)c(lines)i(as)g(read)f(from)g(the) g(\002le)h(may)f(either)g(be)h(terminated)e(by)h(CR-LF)i(or)e(by)g(a)h (single)f(linefeed;)h(a)g(terminating)e(CR-LF)208 847 y(is)21 b(replaced)e(by)g(a)i(single)f(linefeed)f(before)g(the)h(line)h (is)g(stored.)208 980 y(All)40 b(header)e(matching)g(is)j(done)d (independent)f(of)i(upper)f(or)i(lo)n(wer)f(case;)49 b(e.g.)39 b FK(m)p FJ(['From'])p FN(,)44 b FK(m)p FJ(['from'])38 b FN(and)208 1079 y FK(m)p FJ(['FROM'])19 b FN(all)i(yield)e(the)i (same)f(result.)0 1226 y FL(class)h FD(AddressList)p FJ(\()p FK(\002eld)r FJ(\))208 1326 y FN(Y)-9 b(ou)19 b(may)h(instantiate)g(the)g FJ(AddressList)e FN(helper)h(class)i(using) f(a)g(single)g(string)g(parameter)m(,)e(a)j(comma-separated)c(list)k (of)208 1425 y(RFC)g(2822)e(addresses)h(to)g(be)g(parsed.)25 b(\(The)19 b(parameter)g FJ(None)h FN(yields)g(an)g(empty)f(list.\))0 1572 y FD(quote)p FJ(\()p FK(str)r FJ(\))208 1672 y FN(Return)36 b(a)i(ne)n(w)f(string)g(with)g(backslashes)g(in)g FK(str)j FN(replaced)c(by)h(tw)o(o)h(backslashes)e(and)h(double)f(quotes)g (replaced)g(by)208 1772 y(backslash-double)17 b(quote.)0 1918 y FD(unquote)p FJ(\()p FK(str)r FJ(\))208 2018 y FN(Return)25 b(a)i(ne)n(w)e(string)h(which)f(is)i(an)f FK(unquoted)e FN(v)o(ersion)h(of)g FK(str)r FN(.)44 b(If)26 b FK(str)j FN(ends)d(and)f(be)o(gins)g(with)h(double)f(quotes,)h(the)o (y)g(are)208 2118 y(stripped)19 b(of)n(f.)24 b(Lik)o(e)n(wise)c(if)h FK(str)i FN(ends)d(and)g(be)o(gins)f(with)h(angle)g(brack)o(ets,)f(the) o(y)h(are)g(stripped)f(of)n(f.)0 2265 y FD(parseaddr)p FJ(\()p FK(addr)m(ess)p FJ(\))208 2364 y FN(P)o(arse)f FK(addr)m(ess)p FN(,)g(which)f(should)g(be)h(the)h(v)n(alue)e(of)h (some)g(address-containing)c(\002eld)19 b(such)f(as)g FO(T)-9 b(o:)24 b FN(or)18 b FO(Cc:)p FN(,)h(into)f(its)h(constituent) 208 2464 y(\223realname\224)g(and)i(\223email)g(address\224)g(parts.)29 b(Returns)21 b(a)g(tuple)g(of)g(that)h(information,)d(unless)i(the)h (parse)f(f)o(ails,)h(in)f(which)g(case)208 2563 y(a)f(2-tuple)f FJ(\(None,)49 b(None\))20 b FN(is)h(returned.)0 2710 y FD(dump_address_pair)p FJ(\()p FK(pair)r FJ(\))208 2810 y FN(The)k(in)m(v)o(erse)f(of)h FJ(parseaddr\(\))p FN(,)g(this)h(tak)o(es)g(a)g(2-tuple)e(of)h(the)g(form)g FJ(\()p FK(r)m(ealname)p FJ(,)48 b FK(email)p 3041 2810 25 4 v 29 w(addr)m(ess)p FJ(\))25 b FN(and)g(returns)g(the)208 2910 y(string)i(v)n(alue)f(suitable)i(for)e(a)i FO(T)-9 b(o:)39 b FN(or)27 b FO(Cc:)41 b FN(header)-5 b(.)45 b(If)28 b(the)f(\002rst)h(element)f(of)g FK(pair)i FN(is)g(f)o(alse,)g (then)e(the)g(second)g(element)g(is)208 3009 y(returned)18 b(unmodi\002ed.)0 3156 y FD(parsedate)p FJ(\()p FK(date)p FJ(\))208 3256 y FN(Attempts)h(to)h(parse)f(a)h(date)g(according)d(to)j (the)g(rules)f(in)h(RFC)h(2822.)j(ho)n(we)n(v)o(er)m(,)17 b(some)i(mailers)h(don')o(t)e(follo)n(w)h(that)g(format)g(as)208 3355 y(speci\002ed,)d(so)i FJ(parsedate\(\))d FN(tries)i(to)g(guess)g (correctly)e(in)i(such)g(cases.)24 b FK(date)16 b FN(is)i(a)f(string)g (containing)e(an)h(RFC)j(2822)c(date,)208 3455 y(such)26 b(as)h FJ('Mon,)49 b(20)h(Nov)f(1995)g(19:12:08)f(-0500')p FN(.)c(If)27 b(it)g(succeeds)g(in)g(parsing)e(the)i(date,)h FJ(parsedate\(\))208 3555 y FN(returns)19 b(a)j(9-tuple)d(that)i(can)g (be)g(passed)f(directly)g(to)h FJ(time.mktime\(\))p FN(;)f(otherwise)g FJ(None)g FN(will)i(be)f(returned.)k(Note)20 b(that)208 3654 y(\002elds)g(6,)g(7,)g(and)g(8)g(of)g(the)g(result)h(tuple)e(are)h (not)g(usable.)0 3801 y FD(parsedate_tz)p FJ(\()p FK(date)p FJ(\))208 3901 y FN(Performs)d(the)i(same)f(function)f(as)i FJ(parsedate\(\))p FN(,)f(b)n(ut)g(returns)g(either)g FJ(None)g FN(or)h(a)g(10-tuple;)e(the)i(\002rst)g(9)g(elements)f(mak)o (e)208 4000 y(up)24 b(a)h(tuple)f(that)h(can)f(be)h(passed)g(directly)f (to)g FJ(time.mktime\(\))p FN(,)g(and)g(the)h(tenth)f(is)i(the)e(of)n (fset)h(of)f(the)h(date')-5 b(s)25 b(timezone)208 4100 y(from)c(UTC)i(\(which)f(is)i(the)e(of)n(\002cial)h(term)f(for)g (Greenwich)g(Mean)g(T)m(ime\).)32 b(\(Note)22 b(that)h(the)f(sign)h(of) f(the)h(timezone)e(of)n(fset)i(is)208 4200 y(the)c(opposite)f(of)h(the) g(sign)g(of)g(the)g FJ(time.timezone)e FN(v)n(ariable)h(for)h(the)g (same)g(timezone;)f(the)i(latter)f(v)n(ariable)f(follo)n(ws)h(the)208 4299 y(POSIX)j(standard)f(while)h(this)g(module)f(follo)n(ws)h(RFC)h (2822.\))29 b(If)22 b(the)g(input)f(string)h(has)g(no)f(timezone,)h (the)g(last)g(element)g(of)208 4399 y(the)e(tuple)g(returned)e(is)j FJ(None)p FN(.)k(Note)20 b(that)g(\002elds)h(6,)f(7,)g(and)g(8)g(of)g (the)g(result)g(tuple)g(are)g(not)g(usable.)0 4546 y FD(mktime_tz)p FJ(\()p FK(tuple)p FJ(\))208 4645 y FN(T)l(urn)k(a)i (10-tuple)d(as)k(returned)c(by)i FJ(parsedate_tz\(\))e FN(into)i(a)h(UTC)g(timestamp.)40 b(If)25 b(the)g(timezone)g(item)g(in) h(the)f(tuple)208 4745 y(is)e FJ(None)p FN(,)h(assume)e(local)h(time.) 33 b(Minor)22 b(de\002cienc)o(y:)30 b(this)23 b(\002rst)h(interprets)e (the)h(\002rst)g(8)g(elements)g(as)g(a)h(local)f(time)g(and)f(then)208 4845 y(compensates)16 b(for)h(the)g(timezone)g(dif)n(ference;)f(this)i (may)f(yield)h(a)g(slight)f(error)g(around)e(daylight)i(sa)n(vings)g (time)h(switch)g(dates.)208 4944 y(Not)i(enough)e(to)i(w)o(orry)g (about)f(for)g(common)g(use.)0 5091 y FL(See)i(Also:)0 5238 y FN(Module)e FJ(email)h FN(\(section)f(7.1\):)208 5338 y(Comprehensi)n(v)o(e)e(email)j(handling)f(package;)f(supersedes)i (the)g FJ(rfc822)g FN(module.)p 0 5549 3901 4 v 0 5649 a FI(248)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 249 261 TeXDict begin 249 260 bop 0 83 a FN(Module)19 b FJ(mailbox)g FN(\(section)h(7.3\):)208 183 y(Classes)h(to)g(read)e(v)n(arious)g (mailbox)g(formats)h(produced)d(by)j(end-user)f(mail)h(programs.)0 330 y(Module)f FJ(mimetools)g FN(\(section)h(7.5\):)208 429 y(Subclass)g(of)g FJ(rfc822.Message)e FN(that)i(handles)g(MIME)f (encoded)g(messages.)0 714 y Fv(7.10.1)101 b(Message)28 b(Objects)0 917 y FN(A)21 b FJ(Message)e FN(instance)h(has)g(the)h (follo)n(wing)d(methods:)0 1064 y FD(rewindbody)p FJ(\(\))208 1163 y FN(Seek)i(to)g(the)g(start)h(of)f(the)g(message)g(body)-5 b(.)23 b(This)e(only)e(w)o(orks)h(if)g(the)h(\002le)f(object)g(is)h (seekable.)0 1310 y FD(isheader)p FJ(\()p FK(line)p FJ(\))208 1410 y FN(Returns)k(a)g(line')-5 b(s)26 b(canonicalized)d(\002eldname)h (\(the)h(dictionary)f(k)o(e)o(y)g(that)i(will)f(be)h(used)f(to)g(inde)o (x)f(it\))h(if)h(the)f(line)g(is)i(a)e(le)o(gal)208 1510 y(RFC)c(2822)f(header;)f(otherwise)h(returns)f FJ(None)i FN(\(implying)d(that)j(parsing)e(should)g(stop)i(here)f(and)g(the)g (line)h(be)f(pushed)f(back)208 1609 y(on)g(the)i(input)e(stream\).)24 b(It)d(is)g(sometimes)f(useful)g(to)g(o)o(v)o(erride)e(this)j(method)d (in)j(a)f(subclass.)0 1756 y FD(islast)p FJ(\()p FK(line)p FJ(\))208 1856 y FN(Return)h(true)h(if)h(the)f(gi)n(v)o(en)f(line)i(is) g(a)g(delimiter)e(on)h(which)g(Message)g(should)g(stop.)31 b(The)22 b(delimiter)g(line)g(is)h(consumed,)e(and)208 1955 y(the)f(\002le)i(object')-5 b(s)20 b(read)g(location)g(positioned) f(immediately)h(after)g(it.)27 b(By)21 b(def)o(ault)f(this)i(method)d (just)i(checks)f(that)h(the)g(line)g(is)208 2055 y(blank,)e(b)n(ut)h (you)f(can)h(o)o(v)o(erride)e(it)j(in)f(a)h(subclass.)0 2202 y FD(iscomment)p FJ(\()p FK(line)p FJ(\))208 2301 y FN(Return)27 b FJ(True)g FN(if)h(the)g(gi)n(v)o(en)e(line)i(should)e (be)i(ignored)e(entirely)-5 b(,)28 b(just)g(skipped.)46 b(By)28 b(def)o(ault)f(this)h(is)h(a)f(stub)f(that)h(al)o(w)o(ays)208 2401 y(returns)19 b FJ(False)p FN(,)g(b)n(ut)i(you)e(can)h(o)o(v)o (erride)e(it)j(in)f(a)h(subclass.)0 2548 y FD(getallmatchingheaders)p FJ(\()p FK(name)p FJ(\))208 2648 y FN(Return)f(a)h(list)h(of)f(lines)g (consisting)g(of)f(all)i(headers)e(matching)f FK(name)p FN(,)i(if)g(an)o(y)-5 b(.)26 b(Each)20 b(physical)g(line,)h(whether)f (it)i(is)f(a)h(contin-)208 2747 y(uation)d(line)h(or)g(not,)g(is)h(a)f (separate)g(list)h(item.)26 b(Return)19 b(the)h(empty)g(list)h(if)g(no) e(header)g(matches)h FK(name)p FN(.)0 2894 y FD(getfirstmatchingheader) p FJ(\()p FK(name)p FJ(\))208 2994 y FN(Return)27 b(a)i(list)g(of)e (lines)i(comprising)d(the)i(\002rst)h(header)d(matching)h FK(name)p FN(,)i(and)f(its)h(continuation)c(line\(s\),)30 b(if)e(an)o(y)-5 b(.)47 b(Return)208 3093 y FJ(None)20 b FN(if)g(there)g(is)h(no)f(header)f(matching)f FK(name)p FN(.)0 3240 y FD(getrawheader)p FJ(\()p FK(name)p FJ(\))208 3340 y FN(Return)27 b(a)g(single)h(string)f(consisting)g(of)g(the)g(te) o(xt)g(after)g(the)h(colon)e(in)i(the)f(\002rst)h(header)f(matching)f FK(name)p FN(.)46 b(This)27 b(includes)208 3439 y(leading)20 b(whitespace,)g(the)h(trailing)g(linefeed,)f(and)h(internal)f (linefeeds)g(and)h(whitespace)g(if)g(there)g(an)o(y)f(continuation)f (line\(s\))208 3539 y(were)h(present.)k(Return)c FJ(None)g FN(if)g(there)g(is)h(no)f(header)f(matching)f FK(name)p FN(.)0 3686 y FD(getheader)p FJ(\()p FK(name)p FC([)p FK(,)f(default)c FC(])p FJ(\))208 3786 y FN(Lik)o(e)24 b FJ(getrawheader\()p FK(name)p FJ(\))p FN(,)f(b)n(ut)i(strip)g (leading)f(and)g(trailing)g(whitespace.)39 b(Internal)23 b(whitespace)h(is)i(not)f(stripped.)208 3885 y(The)c(optional)f FK(default)i FN(ar)o(gument)e(can)h(be)h(used)f(to)h(specify)f(a)h(dif) n(ferent)e(def)o(ault)h(to)g(be)h(returned)e(when)h(there)g(is)i(no)e (header)208 3985 y(matching)d FK(name)p FN(.)0 4132 y FD(get)p FJ(\()p FK(name)p FC([)p FK(,)g(default)13 b FC(])p FJ(\))208 4231 y FN(An)20 b(alias)h(for)e FJ(getheader\(\))p FN(,)g(to)h(mak)o(e)g(the)g(interf)o(ace)f(more)h(compatible)e(with)j (re)o(gular)d(dictionaries.)0 4378 y FD(getaddr)p FJ(\()p FK(name)p FJ(\))208 4478 y FN(Return)29 b(a)i(pair)f FJ(\()p FK(full)g(name)p FJ(,)49 b FK(email)30 b(addr)m(ess)p FJ(\))g FN(parsed)f(from)g(the)i(string)e(returned)g(by)h FJ(getheader\()p FK(name)p FJ(\))p FN(.)52 b(If)30 b(no)208 4577 y(header)21 b(matching)g FK(name)g FN(e)o(xists,)i(return)f FJ(\(None,)48 b(None\))p FN(;)23 b(otherwise)f(both)g(the)g(full)g (name)g(and)g(the)g(address)g(are)g(\(pos-)208 4677 y(sibly)e(empty\))f (strings.)208 4810 y(Example:)84 b(If)50 b FK(m)p FN(')-5 b(s)51 b(\002rst)g FO(F)m(rom:)84 b FN(header)49 b(contains)h(the)g (string)g FJ('jack@cwi.nl)e(\(Jack)g(Jansen\)')p FN(,)57 b(then)208 4910 y FJ(m.getaddr\('From'\))25 b FN(will)k(yield)f(the)g (pair)g FJ(\('Jack)48 b(Jansen',)h('jack@cwi.nl'\))p FN(.)d(If)28 b(the)h(header)d(con-)208 5009 y(tained)19 b FJ('Jack)49 b(Jansen)g(')18 b FN(instead,)i(it)h(w)o (ould)e(yield)h(the)g(e)o(xact)g(same)g(result.)0 5156 y FD(getaddrlist)p FJ(\()p FK(name)p FJ(\))208 5256 y FN(This)k(is)h(similar)g(to)g FJ(getaddr\()p FK(list)q FJ(\))p FN(,)g(b)n(ut)f(parses)g(a)h(header)e(containing)g(a)i(list)g (of)f(email)h(addresses)f(\(e.g.)f(a)i FO(T)-9 b(o:)33 b FN(header\))208 5355 y(and)24 b(returns)h(a)h(list)g(of)g FJ(\()p FK(full)f(name)p FJ(,)49 b FK(email)25 b(addr)m(ess)p FJ(\))g FN(pairs)h(\(e)n(v)o(en)e(if)i(there)f(w)o(as)h(only)e(one)h (address)g(in)h(the)f(header\).)40 b(If)p 0 5549 3901 4 v 0 5649 a FI(7.10.)52 b FJ(rfc822)22 b FI(\227)h(P)m(arse)g(RFC)g (2822)g(mail)i(headers)1984 b(249)p eop end %%Page: 250 262 TeXDict begin 250 261 bop 208 83 a FN(there)19 b(is)i(no)f(header)f (matching)g FK(name)p FN(,)g(return)g(an)h(empty)g(list.)208 216 y(If)j(multiple)f(headers)g(e)o(xist)i(that)f(match)g(the)g(named)f (header)g(\(e.g.)33 b(if)23 b(there)g(are)g(se)n(v)o(eral)g FO(Cc:)32 b FN(headers\),)22 b(all)i(are)f(parsed)f(for)208 315 y(addresses.)i(An)o(y)c(continuation)e(lines)i(the)g(named)f (headers)h(contain)f(are)h(also)g(parsed.)0 462 y FD(getdate)p FJ(\()p FK(name)p FJ(\))208 562 y FN(Retrie)n(v)o(e)k(a)h(header)e (using)i FJ(getheader\(\))e FN(and)h(parse)g(it)i(into)e(a)h(9-tuple)f (compatible)f(with)i FJ(time.mktime\(\))p FN(;)g(note)208 662 y(that)20 b(\002elds)h(6,)f(7,)g(and)f(8)h(are)h(not)e(usable.)25 b(If)20 b(there)g(is)h(no)f(header)f(matching)f FK(name)p FN(,)i(or)g(it)h(is)g(unparsable,)d(return)h FJ(None)p FN(.)208 794 y(Date)29 b(parsing)f(appears)g(to)h(be)g(a)h(black)e (art,)j(and)e(not)f(all)i(mailers)f(adhere)f(to)h(the)g(standard.)50 b(While)30 b(it)g(has)f(been)f(tested)208 894 y(and)d(found)f(correct)h (on)h(a)g(lar)o(ge)f(collection)g(of)h(email)g(from)f(man)o(y)g (sources,)i(it)f(is)h(still)g(possible)f(that)g(this)h(function)d(may) 208 994 y(occasionally)18 b(yield)i(an)g(incorrect)f(result.)0 1141 y FD(getdate_tz)p FJ(\()p FK(name)p FJ(\))208 1240 y FN(Retrie)n(v)o(e)28 b(a)i(header)e(using)h FJ(getheader\(\))f FN(and)h(parse)g(it)h(into)f(a)h(10-tuple;)i(the)e(\002rst)g(9)f (elements)g(will)h(mak)o(e)f(a)h(tuple)208 1340 y(compatible)c(with)j FJ(time.mktime\(\))p FN(,)f(and)g(the)g(10th)g(is)h(a)g(number)d(gi)n (ving)h(the)i(of)n(fset)e(of)h(the)h(date')-5 b(s)28 b(timezone)g(from)208 1439 y(UTC.)18 b(Note)g(that)h(\002elds)g(6,)f (7,)h(and)e(8)i(are)f(not)g(usable.)24 b(Similarly)18 b(to)h FJ(getdate\(\))p FN(,)e(if)h(there)g(is)i(no)d(header)h (matching)e FK(name)p FN(,)208 1539 y(or)j(it)i(is)h(unparsable,)c (return)h FJ(None)p FN(.)0 1686 y FJ(Message)72 b FN(instances)g(also)h (support)e(a)i(limited)f(mapping)f(interf)o(ace.)180 b(In)73 b(particular:)128 b FK(m)p FJ([name])72 b FN(is)h(lik)o(e)0 1786 y FK(m)p FJ(.getheader\(name\))18 b FN(b)n(ut)j(raises)h FJ(KeyError)e FN(if)h(there)g(is)h(no)e(matching)g(header;)g(and)g FJ(len\()p FK(m)p FJ(\))p FN(,)h FK(m)p FJ(.get\()p FK(name)p FC([)p FJ(,)47 b FK(de-)0 1885 y(fault)13 b FC(])p FJ(\))p FN(,)19 b FK(m)p FJ(.has_key\()p FK(name)p FJ(\))p FN(,)e FK(m)p FJ(.keys\(\))p FN(,)i FK(m)p FJ(.values\(\))f FK(m)p FJ(.items\(\))p FN(,)g(and)h FK(m)p FJ(.setdefault\()p FK(name)p FC([)p FJ(,)46 b FK(default)0 1985 y FC(])p FJ(\))18 b FN(act)g(as)h(e)o(xpected,)d(with)i(the)g(one)g(dif)n (ference)d(that)j FJ(setdefault\(\))f FN(uses)h(an)g(empty)f(string)g (as)i(the)f(def)o(ault)f(v)n(alue.)23 b FJ(Message)0 2084 y FN(instances)c(also)g(support)e(the)i(mapping)e(writable)i (interf)o(ace)f FK(m)p FJ([name])48 b(=)i(value)18 b FN(and)h FJ(del)49 b FK(m)p FJ([name])p FN(.)24 b FJ(Message)18 b FN(objects)0 2184 y(do)g(not)g(support)g(the)g FJ(clear\(\))p FN(,)g FJ(copy\(\))p FN(,)g FJ(popitem\(\))p FN(,)g(or)g FJ(update\(\))g FN(methods)f(of)i(the)f(mapping)f(interf)o(ace.)23 b(\(Support)17 b(for)0 2284 y FJ(get\(\))j FN(and)f FJ(setdefault\(\))g FN(w)o(as)i(only)e(added)g(in)i(Python)e(2.2.\))0 2431 y(Finally)-5 b(,)19 b FJ(Message)h FN(instances)g(ha)n(v)o(e)g(some)g (public)f(instance)h(v)n(ariables:)0 2577 y FD(headers)208 2677 y FN(A)25 b(list)h(containing)e(the)h(entire)g(set)h(of)e(header)g (lines,)j(in)e(the)g(order)f(in)i(which)e(the)o(y)h(were)g(read)f(\(e)o (xcept)g(that)h(setitem)h(calls)208 2777 y(may)g(disturb)h(this)h (order\).)44 b(Each)27 b(line)h(contains)e(a)i(trailing)f(ne)n(wline.) 45 b(The)27 b(blank)g(line)g(terminating)f(the)h(headers)g(is)h(not)208 2876 y(contained)18 b(in)i(the)h(list.)0 3023 y FD(fp)208 3123 y FN(The)e(\002le)i(or)f(\002le-lik)o(e)g(object)g(passed)g(at)h (instantiation)e(time.)25 b(This)c(can)f(be)g(used)g(to)g(read)g(the)g (message)g(content.)0 3270 y FD(unixfrom)208 3369 y FN(The)j(U)t FH(N)t(I)t(X)h FN(`)p FJ(From)49 b FN(')22 b(line,)g(if)g(the)f (message)h(had)f(one,)g(or)h(an)f(empty)g(string.)29 b(This)22 b(is)g(needed)f(to)g(re)o(generate)f(the)i(message)208 3469 y(in)e(some)g(conte)o(xts,)f(such)h(as)h(an)f FJ(mbox)p FN(-style)f(mailbox)g(\002le.)0 3754 y Fv(7.10.2)101 b(AddressList)29 b(Objects)0 3957 y FN(An)20 b FJ(AddressList)f FN(instance)h(has)g(the)g(follo)n(wing)f(methods:)0 4104 y FD(__len__)p FJ(\(\))208 4203 y FN(Return)g(the)i(number)d(of)i (addresses)g(in)g(the)g(address)g(list.)0 4350 y FD(__str__)p FJ(\(\))208 4450 y FN(Return)49 b(a)h(canonicalized)e(string)i (representation)e(of)h(the)h(address)g(list.)115 b(Addresses)50 b(are)f(rendered)f(in)i(\224name\224)208 4549 y(\241host@domain\277)18 b(form,)h(comma-separated.)0 4696 y FD(__add__)p FJ(\()p FK(alist)q FJ(\))208 4796 y FN(Return)j(a)i(ne)n(w)f FJ(AddressList)e FN(instance)i(that)g(contains)g(all)g(addresses)g(in)g (both)g FJ(AddressList)e FN(operands,)h(with)h(du-)208 4895 y(plicates)d(remo)o(v)o(ed)e(\(set)i(union\).)0 5042 y FD(__iadd__)p FJ(\()p FK(alist)q FJ(\))208 5142 y FN(In-place)e(v)o(ersion)h(of)h FJ(__add__\(\))p FN(;)f(turns)g(this) i FJ(AddressList)d FN(instance)i(into)g(the)g(union)e(of)i(itself)h (and)e(the)h(right-hand)208 5242 y(instance,)f FK(alist)q FN(.)0 5388 y FD(__sub__)p FJ(\()p FK(alist)q FJ(\))p 0 5549 3901 4 v 0 5649 a FI(250)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 251 263 TeXDict begin 251 262 bop 208 83 a FN(Return)26 b(a)i(ne)n(w)f FJ(AddressList)f FN(instance)g(that)i(contains)e(e)n(v)o(ery)g(address) h(in)g(the)g(left-hand)f FJ(AddressList)g FN(operand)208 183 y(that)20 b(is)h(not)f(present)f(in)i(the)f(right-hand)e(address)h (operand)f(\(set)j(dif)n(ference\).)0 330 y FD(__isub__)p FJ(\()p FK(alist)q FJ(\))208 429 y FN(In-place)d(v)o(ersion)h(of)h FJ(__sub__\(\))p FN(,)f(remo)o(ving)f(addresses)i(in)g(this)h(list)g (which)f(are)g(also)g(in)h FK(alist)q FN(.)0 576 y(Finally)-5 b(,)19 b FJ(AddressList)g FN(instances)h(ha)n(v)o(e)g(one)f(public)h (instance)g(v)n(ariable:)0 723 y FD(addresslist)208 823 y FN(A)g(list)h(of)e(tuple)h(string)f(pairs,)h(one)f(per)g(address.)25 b(In)19 b(each)h(member)m(,)e(the)h(\002rst)i(is)g(the)e(canonicalized) f(name)h(part,)h(the)f(second)208 922 y(is)i(the)f(actual)g (route-address)e(\(`)p FJ(@)p FN('-separated)g(username-host.domain)d (pair\).)0 1250 y FE(7.11)121 b Fx(base64)32 b FE(\227)h(RFC)h(3548:)43 b(Base16,)35 b(Base32,)f(Base64)h(Data)g(Encodings)0 1482 y FN(This)16 b(module)e(pro)o(vides)g(data)h(encoding)f(and)h (decoding)e(as)j(speci\002ed)g(in)f(RFC)j(3548.)k(This)15 b(standard)g(de\002nes)g(the)h(Base16,)g(Base32,)0 1582 y(and)23 b(Base64)g(algorithms)f(for)h(encoding)e(and)h(decoding)g (arbitrary)f(binary)h(strings)h(into)g(te)o(xt)h(strings)f(that)g(can)g (be)g(safely)g(sent)h(by)0 1682 y(email,)d(used)g(as)h(parts)f(of)g (URLs,)h(or)e(included)g(as)i(part)f(of)f(an)h(HTTP)h(POST)f(request.) 27 b(The)21 b(encoding)e(algorithm)g(is)k(not)d(the)h(same)0 1781 y(as)g(the)f FL(uuencode)h FN(program.)0 1928 y(There)16 b(are)h(tw)o(o)g(interf)o(aces)f(pro)o(vided)f(by)h(this)h(module.)23 b(The)16 b(modern)g(interf)o(ace)g(supports)f(encoding)g(and)h (decoding)f(string)i(objects)0 2028 y(using)h(all)g(three)g(alphabets.) 23 b(The)18 b(le)o(gac)o(y)f(interf)o(ace)g(pro)o(vides)g(for)g (encoding)f(and)i(decoding)e(to)i(and)g(from)f(\002le-lik)o(e)h (objects)g(as)h(well)0 2127 y(as)i(strings,)f(b)n(ut)g(only)f(using)h (the)g(Base64)g(standard)f(alphabet.)0 2274 y(The)h(modern)e(interf)o (ace,)h(which)h(w)o(as)h(introduced)d(in)i(Python)f(2.4,)h(pro)o (vides:)0 2421 y FD(b64encode)p FJ(\()p FK(s)p FC([)p FK(,)f(altc)o(har)o(s)12 b FC(])p FJ(\))208 2521 y FN(Encode)18 b(a)j(string)f(use)g(Base64.)208 2654 y FK(s)d FN(is)h(the)f(string)g (to)g(encode.)23 b(Optional)16 b FK(altc)o(har)o(s)g FN(must)h(be)g(a)h(string)e(of)h(at)h(least)f(length)f(2)h (\(additional)f(characters)g(are)h(ignored\))208 2753 y(which)23 b(speci\002es)i(an)f(alternati)n(v)o(e)f(alphabet)g(for)g (the)i FJ(+)f FN(and)g FJ(/)g FN(characters.)36 b(This)25 b(allo)n(ws)f(an)g(application)f(to)h(e.g.)37 b(generate)208 2853 y(URL)20 b(or)g(\002lesystem)h(safe)f(Base64)g(strings.)25 b(The)20 b(def)o(ault)g(is)h FJ(None)p FN(,)e(for)h(which)g(the)g (standard)f(Base64)h(alphabet)f(is)i(used.)208 2986 y(The)e(encoded)g (string)h(is)h(returned.)0 3133 y FD(b64decode)p FJ(\()p FK(s)p FC([)p FK(,)e(altc)o(har)o(s)12 b FC(])p FJ(\))208 3232 y FN(Decode)19 b(a)h(Base64)h(encoded)d(string.)208 3365 y FK(s)f FN(is)h(the)f(string)g(to)g(decode.)23 b(Optional)16 b FK(altc)o(har)o(s)g FN(must)h(be)g(a)h(string)e(of)h (at)h(least)f(length)f(2)h(\(additional)f(characters)g(are)h(ignored\)) 208 3465 y(which)i(speci\002es)i(the)f(alternati)n(v)o(e)f(alphabet)g (used)h(instead)g(of)g(the)g FJ(+)h FN(and)e FJ(/)i FN(characters.)208 3597 y(The)16 b(decoded)f(string)h(is)i(returned.)k(A)17 b FJ(TypeError)f FN(is)h(raised)g(if)g FK(s)h FN(were)e(incorrectly)f (padded)g(or)i(if)g(there)f(are)h(non-alphabet)208 3697 y(characters)i(present)g(in)i(the)f(string.)0 3844 y FD(standard_b64encode)p FJ(\()p FK(s)p FJ(\))208 3944 y FN(Encode)e(string)i FK(s)h FN(using)f(the)g(standard)f(Base64)h (alphabet.)0 4090 y FD(standard_b64decode)p FJ(\()p FK(s)p FJ(\))208 4190 y FN(Decode)f(string)h FK(s)h FN(using)e(the)i(standard) e(Base64)h(alphabet.)0 4337 y FD(urlsafe_b64encode)p FJ(\()p FK(s)p FJ(\))208 4437 y FN(Encode)g(string)h FK(s)i FN(using)e(a)h(URL-safe)g(alphabet,)f(which)g(substitutes)h FJ(-)g FN(instead)g(of)f FJ(+)h FN(and)g FJ(_)g FN(instead)f(of)h FJ(/)g FN(in)g(the)g(standard)208 4536 y(Base64)e(alphabet.)0 4683 y FD(urlsafe_b64decode)p FJ(\()p FK(s)p FJ(\))208 4783 y FN(Decode)g(string)h FK(s)i FN(using)e(a)h(URL-safe)f(alphabet,) g(which)g(substitutes)h FJ(-)f FN(instead)h(of)f FJ(+)h FN(and)f FJ(_)h FN(instead)f(of)h FJ(/)f FN(in)h(the)g(standard)208 4882 y(Base64)e(alphabet.)0 5029 y FD(b32encode)p FJ(\()p FK(s)p FJ(\))208 5129 y FN(Encode)e(a)j(string)f(using)f(Base32.)25 b FK(s)c FN(is)h(the)e(string)g(to)g(encode.)k(The)19 b(encoded)g(string)h(is)h(returned.)0 5276 y FD(b32decode)p FJ(\()p FK(s)p FC([)p FK(,)e(casefold)r FC([)p FK(,)g(map01)12 b FC(])g(])p FJ(\))208 5375 y FN(Decode)19 b(a)h(Base32)h(encoded)d (string.)p 0 5549 3901 4 v 0 5649 a FI(7.11.)52 b FJ(base64)22 b FI(\227)h(RFC)g(3548:)29 b(Base16,)24 b(Base32,)g(Base64)f(Data)h (Encodings)1122 b(251)p eop end %%Page: 252 264 TeXDict begin 252 263 bop 208 83 a FK(s)25 b FN(is)h(the)f(string)f(to) h(decode.)38 b(Optional)24 b FK(casefold)i FN(is)g(a)f(\003ag)g (specifying)e(whether)h(a)h(lo)n(wercase)g(alphabet)e(is)j(acceptable)e (as)208 183 y(input.)g(F)o(or)c(security)f(purposes,)g(the)h(def)o (ault)f(is)j FJ(False)p FN(.)208 315 y(RFC)f(3548)d(allo)n(ws)i(for)f (optional)g(mapping)f(of)h(the)h(digit)g(0)f(\(zero\))g(to)h(the)g (letter)g(O)g(\(oh\),)e(and)i(for)f(optional)f(mapping)g(of)i(the)208 415 y(digit)h(1)g(\(one\))f(to)h(either)g(the)g(letter)h(I)f(\(e)o (ye\))f(or)h(letter)h(L)f(\(el\).)28 b(The)21 b(optional)f(ar)o(gument) f FK(map01)g FN(when)i(not)g FJ(None)p FN(,)g(speci\002es)208 515 y(which)c(letter)h(the)f(digit)h(1)g(should)e(be)i(mapped)e(to)i (\(when)f FK(map01)f FN(is)j(not)e FJ(None)p FN(,)h(the)g(digit)f(0)h (is)h(al)o(w)o(ays)f(mapped)e(to)i(the)f(letter)208 614 y(O\).)j(F)o(or)f(security)h(purposes)f(the)h(def)o(ault)g(is)h FJ(None)p FN(,)f(so)g(that)g(0)h(and)e(1)i(are)f(not)g(allo)n(wed)f(in) h(the)h(input.)208 747 y(The)16 b(decoded)f(string)h(is)i(returned.)k (A)17 b FJ(TypeError)f FN(is)h(raised)g(if)g FK(s)h FN(were)e (incorrectly)f(padded)g(or)i(if)g(there)f(are)h(non-alphabet)208 847 y(characters)i(present)g(in)i(the)f(string.)0 994 y FD(b16encode)p FJ(\()p FK(s)p FJ(\))208 1093 y FN(Encode)e(a)j (string)f(using)f(Base16.)208 1226 y FK(s)i FN(is)g(the)f(string)g(to)g (encode.)k(The)c(encoded)e(string)i(is)h(returned.)0 1373 y FD(b16decode)p FJ(\()p FK(s)p FC([)p FK(,)e(casefold)13 b FC(])p FJ(\))208 1473 y FN(Decode)19 b(a)h(Base16)h(encoded)d (string.)208 1605 y FK(s)25 b FN(is)h(the)f(string)f(to)h(decode.)38 b(Optional)24 b FK(casefold)i FN(is)g(a)f(\003ag)g(specifying)e (whether)h(a)h(lo)n(wercase)g(alphabet)e(is)j(acceptable)e(as)208 1705 y(input.)g(F)o(or)c(security)f(purposes,)g(the)h(def)o(ault)f(is)j FJ(False)p FN(.)208 1838 y(The)16 b(decoded)f(string)h(is)i(returned.)k (A)17 b FJ(TypeError)f FN(is)h(raised)g(if)g FK(s)h FN(were)e (incorrectly)f(padded)g(or)i(if)g(there)f(are)h(non-alphabet)208 1938 y(characters)i(present)g(in)i(the)f(string.)0 2084 y(The)g(le)o(gac)o(y)e(interf)o(ace:)0 2231 y FD(decode)p FJ(\()p FK(input,)g(output)q FJ(\))208 2331 y FN(Decode)27 b(the)h(contents)g(of)g(the)g FK(input)h FN(\002le)g(and)e(write)i(the) f(resulting)f(binary)g(data)h(to)h(the)f FK(output)g FN(\002le.)50 b FK(input)29 b FN(and)f FK(output)208 2431 y FN(must)19 b(either)g(be)g(\002le)h(objects)f(or)h(objects)f (that)g(mimic)g(the)h(\002le)g(object)f(interf)o(ace.)k FK(input)e FN(will)f(be)f(read)g(until)g FK(input)q FJ(.read\(\))208 2530 y FN(returns)g(an)h(empty)f(string.)0 2677 y FD(decodestring)p FJ(\()p FK(s)p FJ(\))208 2777 y FN(Decode)d(the)h(string)g FK(s)p FN(,)i(which)d(must)i(contain)e(one)h(or)g(more)f(lines)i(of)f (base64)f(encoded)g(data,)h(and)g(return)f(a)i(string)e(containing)208 2876 y(the)k(resulting)f(binary)g(data.)0 3023 y FD(encode)p FJ(\()p FK(input,)f(output)q FJ(\))208 3123 y FN(Encode)30 b(the)i(contents)f(of)g(the)h FK(input)h FN(\002le)f(and)g(write)g(the) f(resulting)g(base64)g(encoded)f(data)i(to)g(the)g FK(output)g FN(\002le.)60 b FK(input)208 3222 y FN(and)26 b FK(output)i FN(must)g(either)f(be)g(\002le)h(objects)f(or)h(objects)f(that)g(mimic) h(the)f(\002le)h(object)f(interf)o(ace.)46 b FK(input)28 b FN(will)g(be)g(read)f(until)208 3322 y FK(input)q FJ(.read\(\))20 b FN(returns)h(an)g(empty)g(string.)29 b FJ(encode\(\))21 b FN(returns)g(the)g(encoded)f(data)i(plus)g(a)g(trailing)f(ne)n(wline) g(character)208 3422 y(\()p FJ('\\n')p FN(\).)0 3569 y FD(encodestring)p FJ(\()p FK(s)p FJ(\))208 3668 y FN(Encode)i(the)j (string)f FK(s)p FN(,)i(which)e(can)g(contain)f(arbitrary)g(binary)g (data,)j(and)d(return)h(a)g(string)g(containing)f(one)h(or)g(more)f (lines)208 3768 y(of)d(base64-encoded)e(data.)31 b FJ(encodestring\(\)) 20 b FN(returns)h(a)i(string)f(containing)e(one)h(or)h(more)g(lines)g (of)g(base64-encoded)208 3867 y(data)e(al)o(w)o(ays)g(including)f(an)h (e)o(xtra)f(trailing)h(ne)n(wline)f(\()p FJ('\\n')p FN(\).)0 4014 y(An)h(e)o(xample)f(usage)h(of)g(the)g(module:)236 4253 y FA(>>>)45 b(import)e(base64)236 4344 y(>>>)i(encoded)e(=)i (base64.b64encode\('data)c(to)j(be)h(encoded'\))236 4435 y(>>>)g(encoded)236 4526 y('ZGF0YSB0byBiZSBlbmNvZGVk')236 4618 y(>>>)g(data)f(=)g(base64.b64decode\(encoded\))236 4709 y(>>>)h(data)236 4800 y('data)f(to)h(be)f(encoded')0 5088 y FL(See)21 b(Also:)0 5234 y FN(Module)e FJ(binascii)g FN(\(section)h(7.13\):)208 5334 y(Support)e(module)h(containing)h FH(A)t(S)t(C)t(I)t(I)r FN(-to-binary)f(and)h(binary-to-)r FH(A)t(S)t(C)t(I)t(I)g FN(con)m(v)o(ersions.)p 0 5549 3901 4 v 0 5649 a FI(252)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 253 265 TeXDict begin 253 264 bop 0 83 a FN(RFC)22 b(1521,)c(\223)p FK(MIME)j(\(Multipurpose)d(Internet)i(Mail)h(Extensions\))e(P)-7 b(art)20 b(One:)25 b(Mec)o(hanisms)20 b(for)g(Specifying)f(and)g (Describing)h(the)g(F)-9 b(ormat)20 b(of)g(Internet)g(Messa)o(g)o(e)h (Bodies)p FN(\224)208 183 y(Section)e(5.2,)h(\223Base64)g(Content-T)m (ransfer)n(-Encoding,)-6 b(\224)14 b(pro)o(vides)19 b(the)h (de\002nition)f(of)h(the)g(base64)f(encoding.)0 510 y FE(7.12)121 b Fx(binhex)32 b FE(\227)h(Encode)h(and)h(decode)g(binhe)l (x4)h(\002les)0 743 y FN(This)31 b(module)e(encodes)g(and)h(decodes)f (\002les)i(in)g(binhe)o(x4)d(format,)k(a)f(format)e(allo)n(wing)g (representation)g(of)h(Macintosh)f(\002les)i(in)2 843 y FH(A)t(S)t(C)t(I)t(I)r FN(.)c(On)20 b(the)g(Macintosh,)g(both)f (forks)h(of)g(a)g(\002le)h(and)f(the)h(\002nder)e(information)f(are)i (encoded)f(\(or)g(decoded\),)f(on)i(other)g(platforms)0 942 y(only)f(the)i(data)f(fork)f(is)i(handled.)0 1089 y(The)f FJ(binhex)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 1236 y FD(binhex)p FJ(\()p FK(input,)f(output)q FJ(\))208 1336 y FN(Con)m(v)o(ert)g(a)i(binary)e(\002le)i(with)g (\002lename)f FK(input)i FN(to)f(binhe)o(x)e(\002le)i FK(output)q FN(.)k(The)19 b FK(output)h FN(parameter)e(can)i(either)f (be)h(a)g(\002lename)f(or)208 1435 y(a)h(\002le-lik)o(e)g(object)g (\(an)o(y)f(object)h(supporting)e(a)i FJ(write\(\))g FN(and)f FJ(close\(\))h FN(method\).)0 1582 y FD(hexbin)p FJ(\()p FK(input)q FC([)p FK(,)e(output)13 b FC(])p FJ(\))208 1682 y FN(Decode)25 b(a)i(binhe)o(x)d(\002le)j FK(input)q FN(.)43 b FK(input)27 b FN(may)f(be)g(a)h(\002lename)e(or)h(a)h (\002le-lik)o(e)f(object)g(supporting)e FJ(read\(\))i FN(and)f FJ(close\(\))208 1781 y FN(methods.)33 b(The)23 b(resulting)g(\002le)h(is)g(written)g(to)f(a)h(\002le)g(named)f FK(output)q FN(,)g(unless)g(the)h(ar)o(gument)d(is)j(omitted)f(in)h (which)f(case)h(the)208 1881 y(output)19 b(\002lename)g(is)i(read)f (from)f(the)h(binhe)o(x)f(\002le.)0 2028 y(The)h(follo)n(wing)e(e)o (xception)h(is)i(also)f(de\002ned:)0 2175 y FL(exception)f FD(Error)208 2274 y FN(Exception)d(raised)j(when)f(something)f(can')o (t)h(be)h(encoded)e(using)h(the)g(binhe)o(x)f(format)h(\(for)g(e)o (xample,)f(a)i(\002lename)f(is)i(too)e(long)208 2374 y(to)i(\002t)h(in)f(the)g(\002lename)g(\002eld\),)g(or)g(when)f(input)h (is)h(not)f(properly)e(encoded)g(binhe)o(x)h(data.)0 2521 y FL(See)i(Also:)0 2668 y FN(Module)e FJ(binascii)g FN(\(section)h(7.13\):)208 2767 y(Support)e(module)h(containing)h FH(A)t(S)t(C)t(I)t(I)r FN(-to-binary)f(and)h(binary-to-)r FH(A)t(S)t(C)t(I)t(I)g FN(con)m(v)o(ersions.)0 3052 y Fv(7.12.1)101 b(Notes)0 3255 y FN(There)19 b(is)i(an)g(alternati)n(v)o (e,)d(more)i(po)n(werful)e(interf)o(ace)h(to)i(the)f(coder)f(and)h (decoder)m(,)e(see)i(the)h(source)e(for)h(details.)0 3402 y(If)31 b(you)g(code)f(or)h(decode)f(te)o(xt\002les)i(on)f (non-Macintosh)d(platforms)i(the)o(y)h(will)h(still)h(use)e(the)h (Macintosh)e(ne)n(wline)h(con)m(v)o(ention)0 3502 y(\(carriage-return) 17 b(as)k(end)e(of)h(line\).)0 3648 y(As)h(of)f(this)h(writing,)e FJ(hexbin\(\))g FN(appears)h(to)g(not)g(w)o(ork)f(in)i(all)f(cases.)0 3976 y FE(7.13)121 b Fx(binascii)31 b FE(\227)i(Con)n(v)m(er)5 b(t)34 b(betw)o(een)i(binar)t(y)e(and)j Fl(A)6 b(S)g(C)g(I)g(I)0 4209 y FN(The)21 b FJ(binascii)g FN(module)g(contains)g(a)h(number)e (of)i(methods)e(to)i(con)m(v)o(ert)e(between)h(binary)f(and)i(v)n (arious)g FH(A)t(S)t(C)t(I)t(I)r FN(-encoded)f(binary)0 4308 y(representations.)39 b(Normally)-5 b(,)25 b(you)g(will)h(not)g (use)f(these)h(functions)e(directly)h(b)n(ut)h(use)f(wrapper)g(modules) f(lik)o(e)i FJ(uu)p FN(,)h FJ(base64)p FN(,)f(or)0 4408 y FJ(binhex)19 b FN(instead.)24 b(The)19 b FJ(binascii)f FN(module)g(contains)h(lo)n(w-le)n(v)o(el)f(functions)f(written)i(in)h (C)g(for)e(greater)h(speed)g(that)g(are)g(used)g(by)0 4508 y(the)h(higher)n(-le)n(v)o(el)e(modules.)0 4654 y(The)i FJ(binascii)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 4801 y FD(a2b_uu)p FJ(\()p FK(string)p FJ(\))208 4901 y FN(Con)m(v)o(ert)k(a)i(single)f(line)h(of)f(uuencoded) e(data)i(back)g(to)h(binary)e(and)h(return)g(the)h(binary)e(data.)38 b(Lines)24 b(normally)f(contain)h(45)208 5001 y(\(binary\))18 b(bytes,)h(e)o(xcept)h(for)f(the)h(last)i(line.)j(Line)19 b(data)i(may)e(be)h(follo)n(wed)f(by)h(whitespace.)0 5147 y FD(b2a_uu)p FJ(\()p FK(data)p FJ(\))208 5247 y FN(Con)m(v)o(ert)c(binary)h(data)i(to)f(a)h(line)f(of)i FH(A)t(S)t(C)t(I)t(I)i FN(characters,)c(the)g(return)f(v)n(alue)h(is)h (the)g(con)m(v)o(erted)c(line,)k(including)d(a)j(ne)n(wline)f(char)-5 b(.)208 5347 y(The)19 b(length)h(of)g FK(data)f FN(should)g(be)h(at)h (most)f(45.)p 0 5549 3901 4 v 0 5649 a FI(7.12.)52 b FJ(binhex)22 b FI(\227)h(Encode)h(and)f(decode)h(binhe)n(x4)f(\002les) 1877 b(253)p eop end %%Page: 254 266 TeXDict begin 254 265 bop 0 83 a FD(a2b_base64)p FJ(\()p FK(string)p FJ(\))208 183 y FN(Con)m(v)o(ert)20 b(a)i(block)f(of)g (base64)g(data)h(back)f(to)g(binary)g(and)g(return)g(the)g(binary)g (data.)29 b(More)21 b(than)h(one)f(line)h(may)f(be)g(passed)h(at)208 282 y(a)e(time.)0 429 y FD(b2a_base64)p FJ(\()p FK(data)p FJ(\))208 529 y FN(Con)m(v)o(ert)28 b(binary)h(data)i(to)f(a)h(line)f (of)i FH(A)t(S)t(C)t(I)t(I)i FN(characters)c(in)g(base64)g(coding.)54 b(The)30 b(return)f(v)n(alue)g(is)j(the)e(con)m(v)o(erted)e(line,)208 628 y(including)18 b(a)j(ne)n(wline)e(char)-5 b(.)25 b(The)20 b(length)f(of)h FK(data)f FN(should)h(be)g(at)g(most)h(57)e (to)i(adhere)e(to)h(the)g(base64)g(standard.)0 775 y FD(a2b_qp)p FJ(\()p FK(string)p FC([)p FK(,)f(header)14 b FC(])p FJ(\))208 875 y FN(Con)m(v)o(ert)20 b(a)j(block)e(of)h (quoted-printable)c(data)k(back)f(to)i(binary)d(and)i(return)f(the)h (binary)f(data.)30 b(More)22 b(than)f(one)h(line)g(may)g(be)208 975 y(passed)e(at)g(a)h(time.)k(If)20 b(the)g(optional)f(ar)o(gument)f FK(header)j FN(is)g(present)f(and)g(true,)f(underscores)f(will)j(be)f (decoded)f(as)i(spaces.)0 1121 y FD(b2a_qp)p FJ(\()p FK(data)p FC([)p FK(,)d(quotetabs,)g(iste)n(xt,)j(header)14 b FC(])p FJ(\))208 1221 y FN(Con)m(v)o(ert)21 b(binary)h(data)i(to)f(a) h(line\(s\))f(of)i FH(A)t(S)t(C)t(I)t(I)i FN(characters)22 b(in)i(quoted-printable)c(encoding.)32 b(The)23 b(return)f(v)n(alue)h (is)h(the)f(con-)208 1321 y(v)o(erted)c(line\(s\).)25 b(If)20 b(the)h(optional)e(ar)o(gument)f FK(quotetabs)h FN(is)i(present)f(and)g(true,)g(all)h(tabs)f(and)g(spaces)h(will)g(be)f (encoded.)k(If)d(the)208 1420 y(optional)g(ar)o(gument)f FK(iste)n(xt)26 b FN(is)d(present)f(and)h(true,)f(ne)n(wlines)h(are)f (not)h(encoded)e(b)n(ut)h(trailing)g(whitespace)h(will)g(be)g(encoded.) 208 1520 y(If)d(the)g(optional)f(ar)o(gument)f FK(header)j FN(is)h(present)d(and)h(true,)g(spaces)g(will)h(be)g(encoded)d(as)j (underscores)e(per)h(RFC1522.)k(If)d(the)208 1620 y(optional)i(ar)o (gument)f FK(header)j FN(is)g(present)f(and)g(f)o(alse,)i(ne)n(wline)d (characters)h(will)h(be)f(encoded)f(as)i(well;)i(otherwise)d(linefeed) 208 1719 y(con)m(v)o(ersion)17 b(might)j(corrupt)e(the)i(binary)f(data) h(stream.)0 1866 y FD(a2b_hqx)p FJ(\()p FK(string)p FJ(\))208 1966 y FN(Con)m(v)o(ert)f(binhe)o(x4)g(formatted)i FH(A)t(S)t(C)t(I)t (I)j FN(data)d(to)g(binary)-5 b(,)19 b(without)i(doing)e (RLE-decompression.)24 b(The)d(string)g(should)f(contain)208 2065 y(a)j(complete)f(number)g(of)h(binary)e(bytes,)j(or)f(\(in)g(case) g(of)g(the)g(last)i(portion)c(of)i(the)g(binhe)o(x4)e(data\))i(ha)n(v)o (e)f(the)i(remaining)d(bits)208 2165 y(zero.)0 2312 y FD(rledecode_hqx)p FJ(\()p FK(data)p FJ(\))208 2411 y FN(Perform)d(RLE-decompression)f(on)j(the)g(data,)f(as)i(per)f(the)g (binhe)o(x4)d(standard.)24 b(The)c(algorithm)e(uses)j FJ(0x90)e FN(after)h(a)g(byte)g(as)208 2511 y(a)k(repeat)g(indicator)m (,)g(follo)n(wed)f(by)h(a)h(count.)37 b(A)25 b(count)f(of)g FJ(0)h FN(speci\002es)g(a)g(byte)f(v)n(alue)g(of)g FJ(0x90)p FN(.)37 b(The)25 b(routine)e(returns)h(the)208 2611 y(decompressed)14 b(data,)j(unless)g(data)g(input)f(data)h(ends)f(in)h(an)g(orphaned)d (repeat)i(indicator)m(,)g(in)h(which)f(case)h(the)g FJ(Incomplete)208 2710 y FN(e)o(xception)h(is)j(raised.)0 2857 y FD(rlecode_hqx)p FJ(\()p FK(data)p FJ(\))208 2957 y FN(Perform)d(binhe)o(x4)g(style)j (RLE-compression)d(on)i FK(data)f FN(and)h(return)f(the)h(result.)0 3104 y FD(b2a_hqx)p FJ(\()p FK(data)p FJ(\))208 3203 y FN(Perform)25 b(he)o(xbin4)f(binary-to-)r FH(A)t(S)t(C)t(I)t(I)k FN(translation)d(and)h(return)g(the)h(resulting)f(string.)44 b(The)26 b(ar)o(gument)e(should)i(already)g(be)208 3303 y(RLE-coded,)18 b(and)h(ha)n(v)o(e)h(a)h(length)e(di)n(visible)h(by)f (3)i(\(e)o(xcept)e(possibly)g(the)h(last)h(fragment\).)0 3450 y FD(crc_hqx)p FJ(\()p FK(data,)d(cr)m(c)p FJ(\))208 3549 y FN(Compute)h(the)h(binhe)o(x4)e(crc)i(v)n(alue)g(of)g FK(data)p FN(,)f(starting)g(with)i(an)f(initial)g FK(cr)m(c)h FN(and)f(returning)e(the)i(result.)0 3696 y FD(crc32)p FJ(\()p FK(data)p FC([)p FK(,)e(cr)m(c)12 b FC(])p FJ(\))208 3796 y FN(Compute)21 b(CRC-32,)i(the)g(32-bit)e(checksum)g(of)h(data,)h (starting)f(with)g(an)h(initial)g(crc.)31 b(This)23 b(is)g(consistent)f (with)h(the)f(ZIP)h(\002le)208 3896 y(checksum.)f(Since)c(the)f (algorithm)f(is)i(designed)e(for)h(use)h(as)g(a)g(checksum)e (algorithm,)g(it)i(is)h(not)e(suitable)g(for)g(use)h(as)g(a)g(general) 208 3995 y(hash)h(algorithm.)24 b(Use)d(as)g(follo)n(ws:)623 4219 y FA(print)44 b(binascii.crc32\("hello)d(world"\))623 4311 y(#)k(Or,)f(in)h(two)f(pieces:)623 4402 y(crc)g(=)h (binascii.crc32\("hello"\))623 4493 y(crc)f(=)h(binascii.crc32\(")d (world",)i(crc\))623 4585 y(print)g(crc)0 4788 y FD(b2a_hex)p FJ(\()p FK(data)p FJ(\))0 4888 y FD(hexlify)p FJ(\()p FK(data)p FJ(\))208 4988 y FN(Return)16 b(the)h(he)o(xadecimal)d (representation)h(of)i(the)f(binary)g FK(data)p FN(.)23 b(Ev)o(ery)15 b(byte)h(of)h FK(data)f FN(is)i(con)m(v)o(erted)c(into)i (the)h(corresponding)208 5087 y(2-digit)i(he)o(x)g(representation.)k (The)d(resulting)f(string)h(is)h(therefore)d(twice)j(as)g(long)e(as)i (the)f(length)g(of)g FK(data)p FN(.)0 5234 y FD(a2b_hex)p FJ(\()p FK(he)n(xstr)r FJ(\))0 5334 y FD(unhexlify)p FJ(\()p FK(he)n(xstr)r FJ(\))p 0 5549 3901 4 v 0 5649 a FI(254)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 255 267 TeXDict begin 255 266 bop 208 83 a FN(Return)14 b(the)i(binary)e(data)h (represented)e(by)i(the)g(he)o(xadecimal)f(string)g FK(he)n(xstr)r FN(.)24 b(This)16 b(function)d(is)k(the)e(in)m(v)o(erse)f(of)h FJ(b2a_hex\(\))p FN(.)208 183 y FK(he)n(xstr)31 b FN(must)e(contain)f (an)h(e)n(v)o(en)f(number)g(of)g(he)o(xadecimal)f(digits)j(\(which)e (can)h(be)g(upper)e(or)i(lo)n(wer)g(case\),)i(otherwise)d(a)208 282 y FJ(TypeError)19 b FN(is)i(raised.)0 429 y FL(exception)e FD(Error)208 529 y FN(Exception)f(raised)i(on)g(errors.)k(These)c(are)g (usually)g(programming)c(errors.)0 676 y FL(exception)j FD(Incomplete)208 775 y FN(Exception)d(raised)j(on)f(incomplete)f (data.)25 b(These)18 b(are)h(usually)f(not)g(programming)d(errors,)j(b) n(ut)h(may)f(be)h(handled)e(by)h(reading)208 875 y(a)i(little)h(more)f (data)g(and)f(trying)g(again.)0 1022 y FL(See)i(Also:)0 1169 y FN(Module)e FJ(base64)h FN(\(section)f(7.11\):)208 1268 y(Support)f(for)i(base64)f(encoding)f(used)i(in)g(MIME)g(email)g (messages.)0 1415 y(Module)f FJ(binhex)h FN(\(section)f(7.12\):)208 1515 y(Support)f(for)i(the)g(binhe)o(x)f(format)g(used)h(on)f(the)i (Macintosh.)0 1662 y(Module)e FJ(uu)h FN(\(section)g(7.15\):)208 1761 y(Support)e(for)i(UU)g(encoding)f(used)g(on)j(U)t FH(N)t(I)t(X)r FN(.)0 1908 y(Module)d FJ(quopri)h FN(\(section)f (7.14\):)208 2008 y(Support)f(for)i(quoted-printable)c(encoding)i(used) i(in)h(MIME)e(email)i(messages.)0 2335 y FE(7.14)121 b Fx(quopri)32 b FE(\227)h(Encode)h(and)h(decode)g(MIME)e(quoted-pr)r (intab)n(le)j(data)0 2568 y FN(This)19 b(module)e(performs)g (quoted-printable)e(transport)i(encoding)g(and)h(decoding,)e(as)k (de\002ned)d(in)i(RFC)h(1521:)j(\223MIME)18 b(\(Multipur)n(-)0 2668 y(pose)j(Internet)e(Mail)j(Extensions\))d(P)o(art)i(One:)27 b(Mechanisms)20 b(for)h(Specifying)e(and)h(Describing)g(the)h(F)o (ormat)f(of)h(Internet)f(Message)0 2767 y(Bodies\224.)37 b(The)24 b(quoted-printable)d(encoding)h(is)k(designed)d(for)g(data)i (where)e(there)h(are)g(relati)n(v)o(ely)g(fe)n(w)g(nonprintable)d (characters;)0 2867 y(the)g(base64)e(encoding)g(scheme)h(a)n(v)n (ailable)g(via)h(the)f FJ(base64)g FN(module)f(is)j(more)e(compact)f (if)i(there)f(are)h(man)o(y)e(such)h(characters,)g(as)0 2966 y(when)g(sending)f(a)h(graphics)f(\002le.)0 3113 y FD(decode)p FJ(\()p FK(input,)f(output)q FC([)p FK(,header)c FC(])p FJ(\))208 3213 y FN(Decode)31 b(the)i(contents)e(of)i(the)f FK(input)i FN(\002le)f(and)f(write)g(the)h(resulting)f(decoded)e (binary)h(data)i(to)f(the)h FK(output)g FN(\002le.)62 b FK(input)208 3313 y FN(and)26 b FK(output)i FN(must)g(either)f(be)g (\002le)h(objects)f(or)h(objects)f(that)g(mimic)h(the)f(\002le)h (object)f(interf)o(ace.)46 b FK(input)28 b FN(will)g(be)g(read)f(until) 208 3412 y FK(input)q FJ(.readline\(\))20 b FN(returns)j(an)g(empty)f (string.)33 b(If)23 b(the)h(optional)d(ar)o(gument)g FK(header)j FN(is)g(present)f(and)f(true,)i(underscore)208 3512 y(will)29 b(be)f(decoded)f(as)i(space.)49 b(This)29 b(is)g(used)f(to)h(decode)e(\223Q\224-encoded)f(headers)h(as)i (described)e(in)i(RFC)h(1522:)40 b(\223MIME)208 3612 y(\(Multipurpose)17 b(Internet)i(Mail)i(Extensions\))e(P)o(art)h(T)-7 b(w)o(o:)25 b(Message)c(Header)e(Extensions)g(for)h(Non-ASCII)f(T)-6 b(e)o(xt\224.)0 3758 y FD(encode)p FJ(\()p FK(input,)18 b(output,)h(quotetabs)p FJ(\))208 3858 y FN(Encode)29 b(the)j(contents)e(of)h(the)h FK(input)g FN(\002le)g(and)f(write)g(the) h(resulting)e(quoted-printable)e(data)j(to)g(the)h FK(output)f FN(\002le.)59 b FK(input)208 3958 y FN(and)26 b FK(output)i FN(must)g(either)f(be)g(\002le)h(objects)f(or)h(objects)f(that)g(mimic) h(the)f(\002le)h(object)f(interf)o(ace.)46 b FK(input)28 b FN(will)g(be)g(read)f(until)208 4057 y FK(input)q FJ(.readline\(\))19 b FN(returns)j(an)g(empty)f(string.)31 b FK(quotetabs)20 b FN(is)k(a)e(\003ag)g(which)g(controls)f(whether)h(to)g(encode)f (embedded)208 4157 y(spaces)26 b(and)h(tabs;)j(when)c(true)g(it)i (encodes)d(such)i(embedded)d(whitespace,)k(and)e(when)g(f)o(alse)h(it)h (lea)n(v)o(es)e(them)h(unencoded.)208 4257 y(Note)20 b(that)g(spaces)g(and)g(tabs)h(appearing)d(at)i(the)h(end)e(of)h(lines) h(are)f(al)o(w)o(ays)g(encoded,)f(as)i(per)e(RFC)j(1521.)0 4403 y FD(decodestring)p FJ(\()p FK(s)p FC([)p FK(,header)14 b FC(])p FJ(\))208 4503 y FN(Lik)o(e)20 b FJ(decode\(\))p FN(,)f(e)o(xcept)g(that)h(it)h(accepts)f(a)h(source)e(string)h(and)g (returns)f(the)h(corresponding)d(decoded)h(string.)0 4650 y FD(encodestring)p FJ(\()p FK(s)p FC([)p FK(,)g(quotetabs)12 b FC(])p FJ(\))208 4749 y FN(Lik)o(e)19 b FJ(encode\(\))p FN(,)g(e)o(xcept)g(that)h(it)h(accepts)f(a)g(source)f(string)h(and)f (returns)g(the)h(corresponding)c(encoded)j(string.)24 b FK(quotetabs)208 4849 y FN(is)d(optional)e(\(def)o(aulting)f(to)i (0\),)g(and)f(is)j(passed)e(straight)f(through)g(to)h FJ(encode\(\))p FN(.)0 4996 y FL(See)h(Also:)0 5143 y FN(Module)e FJ(mimify)h FN(\(section)f(7.8\):)208 5242 y(General)g(utilities)i(for)f(processing)e(of)i(MIME)g(messages.)0 5389 y(Module)f FJ(base64)h FN(\(section)f(7.11\):)p 0 5549 3901 4 v 0 5649 a FI(7.14.)52 b FJ(quopri)22 b FI(\227)h(Encode)h(and)f(decode)h(MIME)g(quoted-pr)q(intab)n(le)h(data) 1313 b(255)p eop end %%Page: 256 268 TeXDict begin 256 267 bop 208 83 a FN(Encode)18 b(and)i(decode)f(MIME)h (base64)f(data)0 410 y FE(7.15)121 b Fx(uu)33 b FE(\227)g(Encode)h(and) h(decode)g(uuencode)i(\002les)0 643 y FN(This)32 b(module)d(encodes)i (and)g(decodes)f(\002les)i(in)g(uuencode)d(format,)j(allo)n(wing)f (arbitrary)f(binary)g(data)h(to)g(be)h(transferred)d(o)o(v)o(er)0 743 y(ASCII-only)21 b(connections.)29 b(Where)n(v)o(er)21 b(a)h(\002le)h(ar)o(gument)d(is)j(e)o(xpected,)e(the)i(methods)e (accept)h(a)g(\002le-lik)o(e)g(object.)31 b(F)o(or)22 b(backw)o(ards)0 843 y(compatibility)-5 b(,)14 b(a)i(string)f (containing)f(a)i(pathname)d(is)k(also)e(accepted,)h(and)e(the)i (corresponding)c(\002le)k(will)g(be)g(opened)d(for)i(reading)f(and)0 942 y(writing;)21 b(the)g(pathname)f FJ('-')h FN(is)h(understood)c(to)j (mean)g(the)g(standard)f(input)g(or)h(output.)26 b(Ho)n(we)n(v)o(er)m (,)20 b(this)h(interf)o(ace)f(is)i(deprecated;)0 1042 y(it')-5 b(s)19 b(better)e(for)g(the)h(caller)g(to)f(open)g(the)h (\002le)g(itself,)h(and)e(be)h(sure)f(that,)h(when)f(required,)g(the)g (mode)g(is)i FJ('rb')e FN(or)h FJ('wb')f FN(on)g(W)m(indo)n(ws.)0 1189 y(This)j(code)g(w)o(as)h(contrib)n(uted)d(by)i(Lance)g (Ellinghouse,)e(and)h(modi\002ed)g(by)h(Jack)g(Jansen.)0 1336 y(The)g FJ(uu)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (functions:)0 1482 y FD(encode)p FJ(\()p FK(in)p 420 1482 25 4 v 28 w(\002le)o(,)h(out)p 697 1482 V 29 w(\002le)p FC([)p FK(,)g(name)p FC([)p FK(,)f(mode)12 b FC(])g(])p FJ(\))208 1582 y FN(Uuencode)24 b(\002le)i FK(in)p 773 1582 V 30 w(\002le)f FN(into)h(\002le)g FK(out)p 1325 1582 V 29 w(\002le)p FN(.)42 b(The)26 b(uuencoded)d(\002le)j(will)h(ha) n(v)o(e)e(the)h(header)f(specifying)f FK(name)h FN(and)h FK(mode)f FN(as)208 1682 y(the)f(def)o(aults)h(for)f(the)g(results)h (of)g(decoding)d(the)j(\002le.)39 b(The)25 b(def)o(ault)f(def)o(aults)g (are)g(tak)o(en)h(from)e FK(in)p 3113 1682 V 30 w(\002le)p FN(,)i(or)g FJ('-')g FN(and)f FJ(0666)208 1781 y FN(respecti)n(v)o(ely) -5 b(.)0 1928 y FD(decode)p FJ(\()p FK(in)p 420 1928 V 28 w(\002le)p FC([)p FK(,)20 b(out)p 738 1928 V 29 w(\002le)p FC([)p FK(,)g(mode)p FC([)p FK(,)f(quiet)13 b FC(])f(])g(])p FJ(\))208 2028 y FN(This)20 b(call)h(decodes)e (uuencoded)f(\002le)j FK(in)p 1383 2028 V 29 w(\002le)g FN(placing)e(the)h(result)h(on)e(\002le)i FK(out)p 2465 2028 V 29 w(\002le)p FN(.)26 b(If)20 b FK(out)p 2826 2028 V 29 w(\002le)g FN(is)i(a)e(pathname,)f FK(mode)h FN(is)h(used)208 2127 y(to)f(set)g(the)g(permission)f(bits)i(if)f(the)g (\002le)h(must)f(be)f(created.)25 b(Def)o(aults)20 b(for)f FK(out)p 2470 2127 V 29 w(\002le)h FN(and)f FK(mode)h FN(are)f(tak)o(en)h(from)f(the)h(uuencode)208 2227 y(header)-5 b(.)24 b(Ho)n(we)n(v)o(er)m(,)18 b(if)i(the)g(\002le)h(speci\002ed)f (in)h(the)f(header)f(already)g(e)o(xists,)h(a)h FJ(uu.Error)e FN(is)i(raised.)208 2360 y FJ(decode\(\))27 b FN(may)h(print)h(a)g(w)o (arning)e(to)i(standard)e(error)h(if)h(the)f(input)g(w)o(as)i(produced) c(by)i(an)h(incorrect)e(uuencoder)f(and)208 2459 y(Python)19 b(could)g(reco)o(v)o(er)f(from)h(that)h(error)-5 b(.)25 b(Setting)20 b FK(quiet)h FN(to)f(a)h(true)f(v)n(alue)f(silences)i (this)g(w)o(arning.)0 2606 y FL(exception)e FD(Error)p FJ(\(\))208 2706 y FN(Subclass)28 b(of)g FJ(Exception)p FN(,)i(this)f(can)f(be)g(raised)h(by)f FJ(uu.decode\(\))f FN(under)g(v)n(arious)g(situations,)j(such)f(as)g(described)208 2806 y(abo)o(v)o(e,)18 b(b)n(ut)i(also)h(including)d(a)j(badly)e (formatted)f(header)m(,)h(or)h(truncated)e(input)i(\002le.)0 2952 y FL(See)h(Also:)0 3099 y FN(Module)e FJ(binascii)g FN(\(section)h(7.13\):)208 3199 y(Support)e(module)h(containing)h FH(A)t(S)t(C)t(I)t(I)r FN(-to-binary)f(and)h(binary-to-)r FH(A)t(S)t(C)t(I)t(I)g FN(con)m(v)o(ersions.)p 0 5549 3901 4 v 0 5649 a FI(256)2467 b(Chapter)23 b(7.)52 b(Inter)r(net)24 b(Data)f(Handling)p eop end %%Page: 257 269 TeXDict begin 257 268 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3535 427 y FG(EIGHT)p 0 515 V 521 978 a FT(Str)s(uctured)57 b(Mar)s(kup)g(Processing)g(T)-25 b(ools)0 1468 y FN(Python)18 b(supports)h(a)g(v)n(ariety)g(of)g(modules)f(to)i(w)o(ork)f(with)g(v)n (arious)g(forms)f(of)i(structured)e(data)h(markup.)k(This)c(includes)g (modules)f(to)0 1568 y(w)o(ork)23 b(with)g(the)h(Standard)e (Generalized)g(Markup)g(Language)f(\(SGML\))i(and)g(the)g(Hyperte)o(xt) f(Markup)g(Language)f(\(HTML\),)h(and)0 1667 y(se)n(v)o(eral)e(interf)o (aces)f(for)h(w)o(orking)e(with)j(the)f(Extensible)f(Markup)g(Language) f(\(XML\).)0 1814 y(It)j(is)g(important)e(to)i(note)f(that)g(modules)g (in)g(the)h FJ(xml)f FN(package)f(require)h(that)g(there)g(be)h(at)g (least)g(one)f(SAX-compliant)f(XML)h(parser)0 1914 y(a)n(v)n(ailable.)k (Starting)18 b(with)i(Python)d(2.3,)i(the)g(Expat)f(parser)g(is)i (included)d(with)j(Python,)d(so)j(the)f FJ(xml.parsers.expat)d FN(module)0 2013 y(will)26 b(al)o(w)o(ays)h(be)e(a)n(v)n(ailable.)41 b(Y)-9 b(ou)25 b(may)h(still)g(w)o(ant)g(to)g(be)g(a)o(w)o(are)f(of)h (the)f(PyXML)h(add-on)e(package;)j(that)e(package)g(pro)o(vides)f(an)0 2113 y(e)o(xtended)18 b(set)j(of)f(XML)g(libraries)g(for)g(Python.)0 2260 y(The)g(documentation)d(for)j(the)g FJ(xml.dom)f FN(and)h FJ(xml.sax)f FN(packages)g(are)h(the)h(de\002nition)e(of)h (the)g(Python)f(bindings)g(for)g(the)h(DOM)0 2359 y(and)g(SAX)g(interf) o(aces.)50 2486 y FD(HTMLParser)646 b FN(A)20 b(simple)g(parser)g(that) g(can)g(handle)f(HTML)h(and)g(XHTML.)50 2585 y FD(sgmllib)796 b FN(Only)19 b(as)i(much)e(of)h(an)g(SGML)h(parser)e(as)i(needed)e(to)i (parse)f(HTML.)50 2685 y FD(htmllib)796 b FN(A)20 b(parser)g(for)f (HTML)h(documents.)50 2785 y FD(htmlentitydefs)446 b FN(De\002nitions)19 b(of)h(HTML)g(general)f(entities.)50 2884 y FD(xml.parsers.expat)296 b FN(An)20 b(interf)o(ace)f(to)h(the)h (Expat)e(non-v)n(alidating)e(XML)j(parser)-5 b(.)50 2984 y FD(xml.dom)796 b FN(Document)18 b(Object)i(Model)g(API)g(for)g (Python.)50 3084 y FD(xml.dom.minidom)396 b FN(Lightweight)18 b(Document)h(Object)h(Model)f(\(DOM\))h(implementation.)50 3183 y FD(xml.dom.pulldom)396 b FN(Support)18 b(for)i(b)n(uilding)f (partial)h(DOM)g(trees)g(from)g(SAX)g(e)n(v)o(ents.)50 3283 y FD(xml.sax)796 b FN(P)o(ackage)19 b(containing)f(SAX2)i(base)h (classes)g(and)e(con)m(v)o(enience)f(functions.)50 3382 y FD(xml.sax.handler)396 b FN(Base)21 b(classes)g(for)f(SAX)g(e)n(v)o (ent)g(handlers.)50 3482 y FD(xml.sax.saxutils)346 b FN(Con)m(v)o(enience)17 b(functions)i(and)h(classes)h(for)e(use)i(with) f(SAX.)50 3582 y FD(xml.sax.xmlreader)296 b FN(Interf)o(ace)18 b(which)i(SAX-compliant)f(XML)h(parsers)g(must)g(implement.)50 3681 y FD(xml.etree.ElementTree)96 b FN(Implementation)17 b(of)j(the)g(ElementT)m(ree)f(API.)0 3824 y FL(See)i(Also:)0 3971 y FK(Python/XML)e(Libr)o(aries)0 4070 y Fy(\()p FO(http://p)n(yxml.sourcef)n(orge)o(.ne)o(t/)-6 b Fy(\))208 4170 y FN(Home)19 b(page)h(for)f(the)h(PyXML)g(package,)f(containing)f (an)i(e)o(xtension)f(of)h FJ(xml)g FN(package)f(b)n(undled)f(with)j (Python.)0 4498 y FE(8.1)121 b Fx(HTMLParser)30 b FE(\227)j(Simple)g (HTML)g(and)i(XHTML)e(parser)0 4730 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.2.)0 4877 y(This)f(module)f(de\002nes)h(a)h(class)g FJ(HTMLParser)e FN(which)h(serv)o(es)g(as)h(the)g(basis)f(for)g (parsing)f(te)o(xt)i(\002les)g(formatted)d(in)j(HTML)f(\(Hyper)n(-)0 4977 y(T)-6 b(e)o(xt)22 b(Mark-up)f(Language\))f(and)i(XHTML.)h(Unlik)o (e)f(the)h(parser)f(in)h FJ(htmllib)p FN(,)f(this)h(parser)f(is)i(not)e (based)g(on)h(the)f(SGML)h(parser)0 5076 y(in)d FJ(sgmllib)p FN(.)0 5223 y FL(class)h FD(HTMLParser)p FJ(\(\))208 5323 y FN(The)e FJ(HTMLParser)g FN(class)i(is)h(instantiated)d(without) h(ar)o(guments.)p 0 5549 3901 4 v 3762 5649 a FI(257)p eop end %%Page: 258 270 TeXDict begin 258 269 bop 208 83 a FN(An)36 b(HTMLP)o(arser)f(instance) h(is)h(fed)f(HTML)g(data)g(and)g(calls)h(handler)e(functions)f(when)i (tags)h(be)o(gin)e(and)g(end.)73 b(The)208 183 y FJ(HTMLParser)18 b FN(class)k(is)f(meant)e(to)i(be)f(o)o(v)o(erridden)d(by)j(the)g(user) g(to)g(pro)o(vide)e(a)j(desired)e(beha)n(vior)-5 b(.)208 315 y(Unlik)o(e)28 b(the)h(parser)f(in)g FJ(htmllib)p FN(,)i(this)f(parser)f(does)h(not)f(check)g(that)h(end)f(tags)h(match)f (start)h(tags)g(or)f(call)h(the)g(end-tag)208 415 y(handler)18 b(for)i(elements)g(which)f(are)i(closed)e(implicitly)h(by)g(closing)f (an)i(outer)e(element.)0 562 y(An)h(e)o(xception)f(is)i(de\002ned)e(as) i(well:)0 709 y FL(exception)e FD(HTMLParseError)208 808 y FN(Exception)d(raised)i(by)f(the)h FJ(HTMLParser)f FN(class)i(when)e(it)i(encounters)d(an)i(error)f(while)h(parsing.)23 b(This)18 b(e)o(xception)e(pro)o(vides)208 908 y(three)24 b(attrib)n(utes:)35 b FJ(msg)25 b FN(is)g(a)h(brief)e(message)h(e)o (xplaining)d(the)j(error)m(,)g FJ(lineno)f FN(is)i(the)f(number)e(of)i (the)g(line)g(on)f(which)h(the)208 1008 y(brok)o(en)g(construct)h(w)o (as)i(detected,)g(and)f FJ(offset)f FN(is)j(the)e(number)e(of)i (characters)f(into)h(the)h(line)f(at)h(which)e(the)i(construct)208 1107 y(starts.)0 1254 y FJ(HTMLParser)19 b FN(instances)h(ha)n(v)o(e)g (the)g(follo)n(wing)e(methods:)0 1401 y FD(reset)p FJ(\(\))208 1501 y FN(Reset)j(the)f(instance.)25 b(Loses)20 b(all)h(unprocessed)d (data.)25 b(This)20 b(is)h(called)f(implicitly)g(at)h(instantiation)e (time.)0 1648 y FD(feed)p FJ(\()p FK(data)p FJ(\))208 1747 y FN(Feed)28 b(some)h(te)o(xt)f(to)h(the)g(parser)-5 b(.)50 b(It)29 b(is)g(processed)f(insof)o(ar)g(as)h(it)g(consists)g(of) g(complete)e(elements;)33 b(incomplete)27 b(data)i(is)208 1847 y(b)n(uf)n(fered)18 b(until)i(more)f(data)h(is)h(fed)f(or)g FJ(close\(\))f FN(is)j(called.)0 1994 y FD(close)p FJ(\(\))208 2093 y FN(F)o(orce)15 b(processing)g(of)i(all)g(b)n(uf)n(fered)d(data)j (as)g(if)g(it)g(were)f(follo)n(wed)f(by)h(an)h(end-of-\002le)d(mark.)23 b(This)17 b(method)e(may)h(be)g(rede\002ned)208 2193 y(by)h(a)i(deri)n(v)o(ed)e(class)i(to)g(de\002ne)e(additional)g (processing)g(at)i(the)f(end)g(of)g(the)h(input,)e(b)n(ut)i(the)f (rede\002ned)f(v)o(ersion)g(should)g(al)o(w)o(ays)208 2293 y(call)j(the)g FJ(HTMLParser)f FN(base)i(class)g(method)e FJ(close\(\))p FN(.)0 2439 y FD(getpos)p FJ(\(\))208 2539 y FN(Return)g(current)g(line)h(number)f(and)g(of)n(fset.)0 2686 y FD(get_starttag_text)p FJ(\(\))208 2786 y FN(Return)e(the)h(te)o (xt)g(of)g(the)h(most)f(recently)f(opened)f(start)j(tag.)24 b(This)19 b(should)e(not)h(normally)e(be)i(needed)f(for)h(structured)e (process-)208 2885 y(ing,)25 b(b)n(ut)f(may)g(be)h(useful)f(in)g (dealing)g(with)h(HTML)f(\223as)h(deplo)o(yed\224)d(or)j(for)f (re-generating)d(input)j(with)h(minimal)f(changes)208 2985 y(\(whitespace)19 b(between)g(attrib)n(utes)h(can)g(be)g(preserv)o (ed,)e(etc.\).)0 3132 y FD(handle_starttag)p FJ(\()p FK(ta)o(g)o(,)f(attr)o(s)p FJ(\))208 3231 y FN(This)25 b(method)f(is)j(called)e(to)h(handle)e(the)i(start)g(of)f(a)h(tag.)41 b(It)26 b(is)g(intended)e(to)i(be)g(o)o(v)o(erridden)c(by)j(a)h(deri)n (v)o(ed)e(class;)29 b(the)c(base)208 3331 y(class)c(implementation)d (does)i(nothing.)208 3464 y(The)31 b FK(ta)o(g)g FN(ar)o(gument)e(is)j (the)f(name)g(of)g(the)g(tag)g(con)m(v)o(erted)e(to)j(lo)n(wer)e(case.) 59 b(The)31 b FK(attr)o(s)h FN(ar)o(gument)d(is)j(a)g(list)h(of)e FJ(\()p FK(name)p FJ(,)208 3563 y FK(value)p FJ(\))i FN(pairs)h(containing)f(the)h(attrib)n(utes)g(found)f(inside)h(the)h (tag')-5 b(s)34 b FJ(<>)h FN(brack)o(ets.)67 b(The)34 b FK(name)f FN(will)i(be)g(translated)e(to)208 3663 y(lo)n(wer)j(case)i (and)e(double)g(quotes)g(and)h(backslashes)g(in)g(the)g FK(value)g FN(ha)n(v)o(e)f(been)h(interpreted.)74 b(F)o(or)36 b(instance,)41 b(for)c(the)208 3763 y(tag)21 b FJ()p FN(,)18 b(this)k(method)f(w)o(ould)g(be) h(called)f(as)i(`)p FJ(handle_starttag\('a',)208 3862 y([\('href',)48 b('http://www.cwi.nl/'\)]\))p FN('.)0 4009 y FD(handle_startendtag)p FJ(\()p FK(ta)o(g)o(,)16 b(attr)o(s)p FJ(\))208 4109 y FN(Similar)28 b(to)g FJ (handle_starttag\(\))p FN(,)f(b)n(ut)h(called)g(when)g(the)g(parser)g (encounters)e(an)i(XHTML-style)f(empty)h(tag)g(\()p FJ()p FN(\).)39 b(This)25 b(method)f(may)h(be)g(o)o(v)o (erridden)d(by)j(subclasses)g(which)g(require)f(this)h(particular)f(le) o(xical)h(information;)h(the)208 4308 y(def)o(ault)19 b(implementation)f(simple)i(calls)h FJ(handle_starttag\(\))d FN(and)h FJ(handle_endtag\(\))p FN(.)0 4455 y FD(handle_endtag)p FJ(\()p FK(ta)o(g)p FJ(\))208 4555 y FN(This)h(method)e(is)j(called)f (to)h(handle)d(the)j(end)e(tag)h(of)g(an)g(element.)k(It)d(is)g (intended)d(to)i(be)g(o)o(v)o(erridden)d(by)j(a)g(deri)n(v)o(ed)e (class;)k(the)208 4654 y(base)e(class)h(implementation)d(does)i (nothing.)j(The)d FK(ta)o(g)g FN(ar)o(gument)e(is)j(the)f(name)g(of)g (the)g(tag)g(con)m(v)o(erted)e(to)i(lo)n(wer)g(case.)0 4801 y FD(handle_data)p FJ(\()p FK(data)p FJ(\))208 4901 y FN(This)g(method)g(is)h(called)g(to)g(process)f(arbitrary)f(data.)26 b(It)21 b(is)h(intended)d(to)i(be)f(o)o(v)o(erridden)e(by)i(a)h(deri)n (v)o(ed)e(class;)j(the)f(base)g(class)208 5000 y(implementation)d(does) h(nothing.)0 5147 y FD(handle_charref)p FJ(\()p FK(name)p FJ(\))208 5247 y FN(This)g(method)f(is)j(called)e(to)h(process)f(a)h (character)f(reference)e(of)j(the)f(form)g(`)p FJ(&#)p FK(r)m(ef)12 b FJ(;)p FN('.)24 b(It)c(is)g(intended)e(to)i(be)g(o)o(v)o (erridden)c(by)j(a)208 5346 y(deri)n(v)o(ed)f(class;)j(the)f(base)h (class)g(implementation)d(does)i(nothing.)p 0 5549 3901 4 v 0 5649 a FI(258)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 259 271 TeXDict begin 259 270 bop 0 83 a FD(handle_entityref)p FJ(\()p FK(name)p FJ(\))208 183 y FN(This)28 b(method)f(is)i(called)f (to)g(process)g(a)h(general)e(entity)h(reference)e(of)i(the)g(form)g(`) p FJ(&)p FK(name)p FJ(;)p FN(')i(where)e FK(name)f FN(is)j(an)e (general)208 282 y(entity)19 b(reference.)24 b(It)c(is)h(intended)e(to) h(be)g(o)o(v)o(erridden)d(by)j(a)h(deri)n(v)o(ed)d(class;)j(the)g(base) f(class)h(implementation)d(does)i(nothing.)0 429 y FD(handle_comment)p FJ(\()p FK(data)p FJ(\))208 529 y FN(This)32 b(method)f(is)j(called)e (when)g(a)h(comment)e(is)j(encountered.)59 b(The)32 b FK(comment)h FN(ar)o(gument)d(is)k(a)f(string)f(containing)f(the)208 628 y(te)o(xt)i(between)g(the)g(`)p FJ(--)p FN(')g(and)g(`)p FJ(--)p FN(')h(delimiters,)i(b)n(ut)d(not)h(the)f(delimiters)h (themselv)o(es.)64 b(F)o(or)33 b(e)o(xample,)i(the)f(comment)208 728 y(`)p FJ()p FN(')24 b(will)j(cause)g(this)g(method)e(to) i(be)f(called)h(with)f(the)h(ar)o(gument)d FJ('text')p FN(.)43 b(It)27 b(is)h(intended)d(to)h(be)h(o)o(v)o(er)n(-)208 828 y(ridden)18 b(by)i(a)h(deri)n(v)o(ed)d(class;)j(the)g(base)f(class) h(implementation)d(does)i(nothing.)0 975 y FD(handle_decl)p FJ(\()p FK(decl)p FJ(\))208 1074 y FN(Method)g(called)h(when)g(an)g (SGML)h(declaration)d(is)k(read)e(by)g(the)g(parser)-5 b(.)28 b(The)21 b FK(decl)h FN(parameter)d(will)k(be)e(the)g(entire)g (contents)208 1174 y(of)k(the)g(declaration)f(inside)i(the)f FJ()g FN(markup.)39 b(It)26 b(is)h(intended)d(to)h (be)h(o)o(v)o(erridden)c(by)j(a)h(deri)n(v)o(ed)e(class;)29 b(the)d(base)g(class)208 1273 y(implementation)18 b(does)h(nothing.)0 1420 y FD(handle_pi)p FJ(\()p FK(data)p FJ(\))208 1520 y FN(Method)d(called)h(when)g(a)h(processing)e(instruction)g(is)j (encountered.)i(The)c FK(data)g FN(parameter)f(will)i(contain)f(the)g (entire)g(process-)208 1620 y(ing)j(instruction.)26 b(F)o(or)21 b(e)o(xample,)e(for)i(the)g(processing)e(instruction)h FJ()p FN(,)19 b(this)j(method)d(w)o(ould)i(be) 208 1719 y(called)c(as)i FJ(handle_pi\("proc)47 b(color='red'"\))p FN(.)23 b(It)18 b(is)h(intended)e(to)h(be)g(o)o(v)o(erridden)d(by)j(a)g (deri)n(v)o(ed)f(class;)i(the)f(base)208 1819 y(class)j(implementation) d(does)i(nothing.)208 1952 y FL(Note:)34 b FN(The)24 b FJ(HTMLParser)g FN(class)i(uses)g(the)f(SGML)g(syntactic)g(rules)g (for)f(processing)g(instructions.)39 b(An)25 b(XHTML)g(pro-)208 2051 y(cessing)20 b(instruction)f(using)g(the)i(trailing)e(`)p FJ(?)p FN(')25 b(will)c(cause)f(the)g(`)p FJ(?)p FN(')25 b(to)20 b(be)h(included)d(in)j FK(data)p FN(.)0 2336 y Fv(8.1.1)100 b(Example)29 b(HTML)f(P)l(arser)h(Application)0 2539 y FN(As)21 b(a)f(basic)g(e)o(xample,)e(belo)n(w)i(is)g(a)h(v)o (ery)d(basic)i(HTML)g(parser)f(that)h(uses)h(the)f FJ(HTMLParser)e FN(class)j(to)f(print)f(out)h(tags)g(as)g(the)o(y)g(are)0 2639 y(encountered:)236 2877 y FA(from)44 b(HTMLParser)g(import)f (HTMLParser)236 3060 y(class)h(MyHTMLParser\(HTMLParser\):)416 3242 y(def)g(handle_starttag\(self,)d(tag,)j(attrs\):)595 3333 y(print)g("Encountered)f(the)h(beginning)f(of)i(a)f(\045s)h(tag")f (\045)h(tag)416 3516 y(def)f(handle_endtag\(self,)e(tag\):)595 3607 y(print)i("Encountered)f(the)h(end)g(of)h(a)f(\045s)h(tag")f(\045) h(tag)0 4118 y FE(8.2)121 b Fx(sgmllib)31 b FE(\227)i(Simple)f(SGML)h (parser)0 4350 y FN(This)22 b(module)e(de\002nes)i(a)g(class)h FJ(SGMLParser)d FN(which)i(serv)o(es)f(as)i(the)e(basis)i(for)e (parsing)g(te)o(xt)g(\002les)i(formatted)d(in)i(SGML)g(\(Stan-)0 4450 y(dard)c(Generalized)g(Mark-up)g(Language\).)k(In)d(f)o(act,)h(it) g(does)f(not)g(pro)o(vide)e(a)j(full)f(SGML)h(parser)f(\227)h(it)g (only)e(parses)i(SGML)f(insof)o(ar)0 4550 y(as)i(it)h(is)f(used)f(by)g (HTML,)g(and)g(the)h(module)e(only)h(e)o(xists)h(as)g(a)g(base)g(for)f (the)g FJ(htmllib)g FN(module.)25 b(Another)19 b(HTML)h(parser)g(which) 0 4649 y(supports)f(XHTML)h(and)g(of)n(fers)f(a)i(some)n(what)e(dif)n (ferent)f(interf)o(ace)i(is)h(a)n(v)n(ailable)f(in)g(the)g FJ(HTMLParser)f FN(module.)0 4796 y FL(class)i FD(SGMLParser)p FJ(\(\))208 4896 y FN(The)f FJ(SGMLParser)f FN(class)j(is)g (instantiated)e(without)g(ar)o(guments.)k(The)d(parser)f(is)h (hardcoded)e(to)h(recognize)f(the)i(follo)n(wing)208 4995 y(constructs:)349 5209 y FM(\017)o FN(Opening)e(and)h(closing)f (tags)i(of)f(the)g(form)f(`)p FJ(<)p FK(ta)o(g)48 b(attr)r FJ(=")p FK(value)p FJ(")g(...>)p FN(')20 b(and)g(`)p FJ()p FN(',)e(respecti)n(v)o(ely)-5 b(.)349 5341 y FM(\017)o FN(Numeric)19 b(character)g(references)g(of)h (the)g(form)f(`)p FJ(&#)p FK(name)p FJ(;)p FN('.)p 0 5549 3901 4 v 0 5649 a FI(8.2.)52 b FJ(sgmllib)22 b FI(\227)h(Simple)i (SGML)e(parser)2323 b(259)p eop end %%Page: 260 272 TeXDict begin 260 271 bop 349 83 a FM(\017)o FN(Entity)20 b(references)f(of)h(the)g(form)f(`)p FJ(&)p FK(name)p FJ(;)p FN('.)349 216 y FM(\017)o FN(SGML)k(comments)e(of)h(the)h(form)e (`)p FJ()p FN('.)31 b(Note)22 b(that)h(spaces,)f(tabs,)h(and)f(ne)n(wlines)g(are)h(allo)n(wed)e (between)390 315 y(the)f(trailing)g(`)p FJ(>)p FN(')g(and)g(the)g (immediately)f(preceding)f(`)p FJ(--)p FN('.)0 529 y(A)j(single)f(e)o (xception)e(is)j(de\002ned)e(as)i(well:)0 676 y FL(exception)e FD(SGMLParseError)208 775 y FN(Exception)f(raised)i(by)g(the)g FJ(SGMLParser)f FN(class)i(when)f(it)g(encounters)f(an)h(error)f(while) h(parsing.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 922 y FJ(SGMLParser)g FN(instances)h(ha)n(v)o(e)g(the)g(follo)n(wing)e (methods:)0 1069 y FD(reset)p FJ(\(\))208 1169 y FN(Reset)j(the)f (instance.)25 b(Loses)20 b(all)h(unprocessed)d(data.)25 b(This)20 b(is)h(called)f(implicitly)g(at)h(instantiation)e(time.)0 1316 y FD(setnomoretags)p FJ(\(\))208 1415 y FN(Stop)k(processing)g (tags.)36 b(T)m(reat)23 b(all)i(follo)n(wing)d(input)h(as)h(literal)g (input)f(\(CD)m(A)-9 b(T)h(A\).)23 b(\(This)h(is)h(only)e(pro)o(vided)e (so)j(the)g(HTML)208 1515 y(tag)c FJ()e FN(can)i(be)h (implemented.\))0 1662 y FD(setliteral)p FJ(\(\))208 1761 y FN(Enter)e(literal)i(mode)e(\(CD)m(A)-9 b(T)h(A)20 b(mode\).)0 1908 y FD(feed)p FJ(\()p FK(data)p FJ(\))208 2008 y FN(Feed)28 b(some)h(te)o(xt)f(to)h(the)g(parser)-5 b(.)50 b(It)29 b(is)g(processed)f(insof)o(ar)g(as)h(it)g(consists)g(of) g(complete)e(elements;)33 b(incomplete)27 b(data)i(is)208 2107 y(b)n(uf)n(fered)18 b(until)i(more)f(data)h(is)h(fed)f(or)g FJ(close\(\))f FN(is)j(called.)0 2254 y FD(close)p FJ(\(\))208 2354 y FN(F)o(orce)15 b(processing)g(of)i(all)g(b)n(uf)n(fered)d(data)j (as)g(if)g(it)g(were)f(follo)n(wed)f(by)h(an)h(end-of-\002le)d(mark.)23 b(This)17 b(method)e(may)h(be)g(rede\002ned)208 2454 y(by)h(a)i(deri)n(v)o(ed)e(class)i(to)g(de\002ne)e(additional)g (processing)g(at)i(the)f(end)g(of)g(the)h(input,)e(b)n(ut)i(the)f (rede\002ned)f(v)o(ersion)g(should)g(al)o(w)o(ays)208 2553 y(call)j FJ(close\(\))p FN(.)0 2700 y FD(get_starttag_text)p FJ(\(\))208 2800 y FN(Return)d(the)h(te)o(xt)g(of)g(the)h(most)f (recently)f(opened)f(start)j(tag.)24 b(This)19 b(should)e(not)h (normally)e(be)i(needed)f(for)h(structured)e(process-)208 2899 y(ing,)25 b(b)n(ut)f(may)g(be)h(useful)f(in)g(dealing)g(with)h (HTML)f(\223as)h(deplo)o(yed\224)d(or)j(for)f(re-generating)d(input)j (with)h(minimal)f(changes)208 2999 y(\(whitespace)19 b(between)g(attrib)n(utes)h(can)g(be)g(preserv)o(ed,)e(etc.\).)0 3146 y FD(handle_starttag)p FJ(\()p FK(ta)o(g)o(,)f(method,)i(attrib)n (utes)p FJ(\))208 3245 y FN(This)29 b(method)f(is)j(called)e(to)g (handle)g(start)h(tags)g(for)e(which)h(either)g(a)h FJ(start_)p FK(ta)o(g)p FJ(\(\))e FN(or)h FJ(do_)p FK(ta)o(g)p FJ(\(\))g FN(method)f(has)h(been)208 3345 y(de\002ned.)23 b(The)18 b FK(ta)o(g)h FN(ar)o(gument)d(is)j(the)g(name)f(of)g(the)h(tag)g(con)m (v)o(erted)d(to)i(lo)n(wer)g(case,)i(and)e(the)g FK(method)i FN(ar)o(gument)c(is)k(the)e(bound)208 3445 y(method)23 b(which)h(should)g(be)h(used)g(to)g(support)e(semantic)i (interpretation)d(of)j(the)g(start)g(tag.)39 b(The)25 b FK(attrib)n(utes)g FN(ar)o(gument)d(is)k(a)208 3544 y(list)21 b(of)f FJ(\()p FK(name)p FJ(,)48 b FK(value)p FJ(\))19 b FN(pairs)i(containing)d(the)i(attrib)n(utes)g(found)f (inside)h(the)g(tag')-5 b(s)20 b FJ(<>)h FN(brack)o(ets.)208 3677 y(The)f FK(name)g FN(has)h(been)f(translated)g(to)h(lo)n(wer)f (case.)27 b(Double)20 b(quotes)g(and)g(backslashes)h(in)g(the)f FK(value)g FN(ha)n(v)o(e)h(been)f(interpreted,)208 3777 y(as)h(well)g(as)h(kno)n(wn)d(character)h(references)f(and)h(kno)n(wn)f (entity)i(references)e(terminated)g(by)i(a)g(semicolon)f(\(normally)-5 b(,)18 b(entity)208 3876 y(references)h(can)h(be)h(terminated)e(by)i (an)o(y)e(non-alphanumerical)e(character)m(,)i(b)n(ut)h(this)h(w)o (ould)f(break)g(the)h(v)o(ery)e(common)g(case)208 3976 y(of)g FJ(<A)50 b(HREF="url?spam=1&eggs=2">)16 b FN(when)k FJ(eggs)g FN(is)h(a)f(v)n(alid)g(entity)g(name\).)208 4109 y(F)o(or)52 b(instance,)59 b(for)52 b(the)h(tag)f FJ(<A)e(HREF="http://www.cwi.nl/">)p FN(,)56 b(this)c(method)g(w)o (ould)f(be)i(called)f(as)208 4208 y(`)p FJ(unknown_starttag\('a',)45 b([\('href',)j('http://www.cwi.nl/'\)]\))p FN('.)28 b(The)22 b(base)h(implementation)208 4308 y(simply)c(calls)h FK(method)h FN(with)e FK(attrib)n(utes)h FN(as)g(the)g(only)e(ar)o(gument.)48 b(Ne)n(w)20 b(in)f(v)o(ersion)g(2.5:)f(Handling)h(of)g(entity)g(and)g (character)208 4408 y(references)f(within)i(attrib)n(ute)g(v)n(alues.)0 4555 y FD(handle_endtag)p FJ(\()p FK(ta)o(g)o(,)d(method)r FJ(\))208 4654 y FN(This)22 b(method)e(is)j(called)f(to)g(handle)f (endtags)g(for)h(which)f(an)h FJ(end_)p FK(ta)o(g)p FJ(\(\))f FN(method)g(has)h(been)f(de\002ned.)29 b(The)22 b FK(ta)o(g)g FN(ar)o(gument)208 4754 y(is)28 b(the)f(name)f(of)h(the)g(tag)g(con)m (v)o(erted)e(to)i(lo)n(wer)g(case,)i(and)d(the)i FK(method)g FN(ar)o(gument)d(is)j(the)f(bound)e(method)h(which)h(should)208 4853 y(be)d(used)g(to)h(support)e(semantic)h(interpretation)e(of)i(the) h(end)f(tag.)38 b(If)24 b(no)g FJ(end_)p FK(ta)o(g)p FJ(\(\))f FN(method)g(is)i(de\002ned)f(for)g(the)g(closing)208 4953 y(element,)19 b(this)i(handler)d(is)j(not)f(called.)25 b(The)20 b(base)g(implementation)e(simply)i(calls)h FK(method)r FN(.)0 5100 y FD(handle_data)p FJ(\()p FK(data)p FJ(\))208 5200 y FN(This)f(method)g(is)h(called)g(to)g(process)f(arbitrary)f (data.)26 b(It)21 b(is)h(intended)d(to)i(be)f(o)o(v)o(erridden)e(by)i (a)h(deri)n(v)o(ed)e(class;)j(the)f(base)g(class)208 5299 y(implementation)d(does)h(nothing.)p 0 5549 3901 4 v 0 5649 a FI(260)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 261 273 TeXDict begin 261 272 bop 0 83 a FD(handle_charref)p FJ(\()p FK(r)m(ef)12 b FJ(\))208 183 y FN(This)28 b(method)f(is)i (called)e(to)i(process)e(a)i(character)e(reference)f(of)i(the)g(form)f (`)p FJ(&#)p FK(r)m(ef)12 b FJ(;)p FN('.)48 b(The)28 b(base)g(implementation)e(uses)208 282 y FJ(convert_charref\(\))g FN(to)i(con)m(v)o(ert)f(the)i(reference)e(to)i(a)g(string.)50 b(If)28 b(that)h(method)f(returns)f(a)j(string,)g(it)f(is)h(passed)e (to)208 382 y FJ(handle_data\(\))p FN(,)23 b(otherwise)h FJ(unknown_charref\()p FK(r)m(ef)12 b FJ(\))23 b FN(is)i(called)g(to)g (handle)e(the)i(error)-5 b(.)77 b(Changed)23 b(in)i(v)o(ersion)208 482 y(2.5:)19 b(Use)i FJ(convert_charref\(\))d FN(instead)i(of)f (hard-coding)e(the)k(con)m(v)o(ersion.)0 628 y FD(convert_charref)p FJ(\()p FK(r)m(ef)12 b FJ(\))208 728 y FN(Con)m(v)o(ert)29 b(a)j(character)e(reference)f(to)j(a)f(string,)j(or)d FJ(None)p FN(.)58 b FK(r)m(ef)44 b FN(is)32 b(the)f(reference)f(passed) h(in)g(as)h(a)g(string.)57 b(In)31 b(the)g(base)208 828 y(implementation,)22 b FK(r)m(ef)37 b FN(must)25 b(be)f(a)g(decimal)g (number)e(in)j(the)f(range)f(0-255.)35 b(It)25 b(con)m(v)o(erts)d(the)i (code)g(point)f(found)g(using)h(the)208 927 y FJ(convert_codepoint\(\)) 15 b FN(method.)23 b(If)18 b FK(r)m(ef)32 b FN(is)19 b(in)m(v)n(alid)f(or)g(out)g(of)g(range,)g(this)h(method)e(returns)h FJ(None)p FN(.)24 b(This)18 b(method)g(is)208 1027 y(called)i(by)g(the) g(def)o(ault)f FJ(handle_charref\(\))f FN(implementation)g(and)i(by)g (the)g(attrib)n(ute)g(v)n(alue)g(parser)-5 b(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)208 1127 y(2.5.)0 1273 y FD(convert_codepoint)p FJ(\()p FK(codepoint)q FJ(\))208 1373 y FN(Con)m(v)o(ert)16 b(a)j(codepoint)d(to)j(a)g FJ(str)f FN(v)n(alue.)24 b(Encodings)16 b(can)i(be)g(handled)f(here)h(if)h(appropriate,)d(though)g(the)i(rest)h (of)f FJ(sgmllib)208 1473 y FN(is)j(obli)n(vious)d(on)i(this)h(matter) -5 b(.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 1620 y FD(handle_entityref)p FJ(\()p FK(r)m(ef)12 b FJ(\))208 1719 y FN(This)25 b(method)f(is)i(called)e(to)i(process)e(a)i(general)e (entity)h(reference)e(of)i(the)g(form)f(`)p FJ(&)p FK(r)m(ef)12 b FJ(;)p FN(')27 b(where)e FK(r)m(ef)38 b FN(is)26 b(an)f(general)f (entity)208 1819 y(reference.)36 b(It)24 b(con)m(v)o(erts)f FK(r)m(ef)38 b FN(by)24 b(passing)g(it)h(to)g FJ(convert_entityref\(\)) p FN(.)34 b(If)25 b(a)g(translation)e(is)j(returned,)d(it)i(calls)h (the)208 1918 y(method)19 b FJ(handle_data\(\))g FN(with)h(the)h (translation;)f(otherwise,)g(it)h(calls)h(the)e(method)g FJ(unknown_entityref\()p FK(r)m(ef)12 b FJ(\))p FN(.)208 2018 y(The)22 b(def)o(ault)f FJ(entitydefs)g FN(de\002nes)h (translations)g(for)g FJ(&amp;)p FN(,)g FJ(&apos)p FN(,)g FJ(&gt;)p FN(,)h FJ(&lt;)p FN(,)f(and)g FJ(&quot;)p FN(.)63 b(Changed)21 b(in)208 2118 y(v)o(ersion)d(2.5:)i(Use)h FJ(convert_entityref\(\))c FN(instead)j(of)g(hard-coding)d(the)j(con)m (v)o(ersion.)0 2265 y FD(convert_entityref)p FJ(\()p FK(r)m(ef)12 b FJ(\))208 2364 y FN(Con)m(v)o(ert)25 b(a)i(named)f (entity)g(reference)f(to)i(a)g FJ(str)g FN(v)n(alue,)g(or)f FJ(None)p FN(.)45 b(The)26 b(resulting)g(v)n(alue)g(will)h(not)g(be)g (parsed.)43 b FK(r)m(ef)d FN(will)208 2464 y(be)29 b(only)f(the)i(name) f(of)g(the)g(entity)-5 b(.)52 b(The)29 b(def)o(ault)g(implementation)e (looks)i(for)g FK(r)m(ef)42 b FN(in)29 b(the)h(instance)f(\(or)g (class\))h(v)n(ariable)208 2563 y FJ(entitydefs)23 b FN(which)h(should)g(be)h(a)g(mapping)e(from)h(entity)g(names)h(to)g (corresponding)c(translations.)38 b(If)25 b(no)f(translation)208 2663 y(is)e(a)n(v)n(ailable)f(for)g FK(r)m(ef)12 b FN(,)23 b(this)f(method)e(returns)h FJ(None)p FN(.)29 b(This)22 b(method)e(is)j(called)f(by)f(the)g(def)o(ault)g FJ (handle_entityref\(\))208 2763 y FN(implementation)d(and)h(by)h(the)g (attrib)n(ute)g(v)n(alue)f(parser)-5 b(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2910 y FD(handle_comment)p FJ(\()p FK(comment)q FJ(\))208 3009 y FN(This)32 b(method)f(is)j (called)e(when)g(a)h(comment)e(is)j(encountered.)59 b(The)32 b FK(comment)h FN(ar)o(gument)d(is)k(a)f(string)f(containing)f(the)208 3109 y(te)o(xt)24 b(between)h(the)g(`)p FJ(<!--)p FN(')f(and)g(`)p FJ(-->)p FN(')h(delimiters,)g(b)n(ut)g(not)g(the)g(delimiters)g (themselv)o(es.)39 b(F)o(or)24 b(e)o(xample,)h(the)g(comment)208 3208 y(`)p FJ(<!--text-->)p FN(')f(will)j(cause)g(this)g(method)e(to)i (be)f(called)h(with)f(the)h(ar)o(gument)d FJ('text')p FN(.)44 b(The)26 b(def)o(ault)g(method)f(does)208 3308 y(nothing.)0 3455 y FD(handle_decl)p FJ(\()p FK(data)p FJ(\))208 3555 y FN(Method)e(called)i(when)f(an)h(SGML)g(declaration)e (is)j(read)f(by)f(the)h(parser)-5 b(.)39 b(In)24 b(practice,)h(the)g FJ(DOCTYPE)f FN(declaration)g(is)i(the)208 3654 y(only)e(thing)h (observ)o(ed)f(in)h(HTML,)g(b)n(ut)h(the)g(parser)f(does)g(not)g (discriminate)g(among)f(dif)n(ferent)g(\(or)h(brok)o(en\))e (declarations.)208 3754 y(Internal)c(subsets)i(in)g(a)g FJ(DOCTYPE)f FN(declaration)f(are)i(not)f(supported.)k(The)d FK(data)f FN(parameter)f(will)i(be)g(the)g(entire)f(contents)g(of)208 3853 y(the)g(declaration)e(inside)i(the)h FJ(<!)p FN(...)p FJ(>)e FN(markup.)k(The)d(def)o(ault)g(implementation)e(does)h (nothing.)0 4000 y FD(report_unbalanced)p FJ(\()p FK(ta)o(g)p FJ(\))208 4100 y FN(This)h(method)f(is)i(called)f(when)f(an)i(end)e (tag)h(is)i(found)c(which)i(does)g(not)f(correspond)f(to)i(an)o(y)g (open)f(element.)0 4247 y FD(unknown_starttag)p FJ(\()p FK(ta)o(g)o(,)e(attrib)n(utes)p FJ(\))208 4346 y FN(This)25 b(method)f(is)i(called)f(to)h(process)e(an)i(unkno)n(wn)c(start)k(tag.) 40 b(It)26 b(is)g(intended)e(to)h(be)h(o)o(v)o(erridden)c(by)i(a)i (deri)n(v)o(ed)e(class;)29 b(the)208 4446 y(base)20 b(class)h (implementation)d(does)i(nothing.)0 4593 y FD(unknown_endtag)p FJ(\()p FK(ta)o(g)p FJ(\))208 4693 y FN(This)e(method)g(is)h(called)g (to)g(process)f(an)g(unkno)n(wn)e(end)j(tag.)24 b(It)19 b(is)h(intended)d(to)h(be)h(o)o(v)o(erridden)c(by)k(a)g(deri)n(v)o(ed)e (class;)j(the)e(base)208 4792 y(class)j(implementation)d(does)i (nothing.)0 4939 y FD(unknown_charref)p FJ(\()p FK(r)m(ef)12 b FJ(\))208 5039 y FN(This)25 b(method)f(is)i(called)e(to)i(process)e (unresolv)n(able)f(numeric)h(character)g(references.)38 b(Refer)25 b(to)g FJ(handle_charref\(\))208 5138 y FN(to)31 b(determine)e(what)i(is)h(handled)d(by)i(def)o(ault.)56 b(It)31 b(is)h(intended)e(to)h(be)g(o)o(v)o(erridden)c(by)k(a)g(deri)n (v)o(ed)e(class;)38 b(the)31 b(base)g(class)208 5238 y(implementation)18 b(does)h(nothing.)0 5385 y FD(unknown_entityref)p FJ(\()p FK(r)m(ef)12 b FJ(\))p 0 5549 3901 4 v 0 5649 a FI(8.2.)52 b FJ(sgmllib)22 b FI(\227)h(Simple)i(SGML)e(parser)2323 b(261)p eop end %%Page: 262 274 TeXDict begin 262 273 bop 208 83 a FN(This)19 b(method)f(is)i(called)f (to)h(process)e(an)i(unkno)n(wn)c(entity)j(reference.)k(It)d(is)g (intended)e(to)h(be)g(o)o(v)o(erridden)d(by)j(a)h(deri)n(v)o(ed)e (class;)208 183 y(the)i(base)g(class)h(implementation)d(does)i (nothing.)0 330 y(Apart)d(from)f(o)o(v)o(erriding)e(or)j(e)o(xtending)e (the)i(methods)f(listed)i(abo)o(v)o(e,)e(deri)n(v)o(ed)g(classes)i(may) f(also)g(de\002ne)g(methods)f(of)h(the)g(follo)n(wing)0 429 y(form)23 b(to)h(de\002ne)g(processing)f(of)g(speci\002c)i(tags.)37 b(T)-7 b(ag)24 b(names)g(in)g(the)g(input)f(stream)h(are)g(case)h (independent;)f(the)g FK(ta)o(g)g FN(occurring)d(in)0 529 y(method)e(names)h(must)g(be)g(in)g(lo)n(wer)g(case:)0 676 y FD(start_)p Fo(tag)p FJ(\()p FK(attrib)n(utes)p FJ(\))208 775 y FN(This)g(method)f(is)i(called)f(to)h(process)f(an)g (opening)e(tag)j FK(ta)o(g)p FN(.)k(It)c(has)f(preference)e(o)o(v)o(er) h FJ(do_)p FK(ta)o(g)p FJ(\(\))p FN(.)24 b(The)c FK(attrib)n(utes)h FN(ar)o(gument)208 875 y(has)f(the)g(same)h(meaning)d(as)j(described)e (for)h FJ(handle_starttag\(\))d FN(abo)o(v)o(e.)0 1022 y FD(do_)p Fo(tag)p FJ(\()p FK(attrib)n(utes)p FJ(\))208 1121 y FN(This)j(method)e(is)j(called)f(to)g(process)f(an)h(opening)e (tag)i FK(ta)o(g)g FN(for)f(which)g(no)h FJ(start_)p FK(ta)o(g)f FN(method)f(is)j(de\002ned.)j(The)19 b FK(attrib)n(utes)208 1221 y FN(ar)o(gument)e(has)k(the)f(same)g(meaning)f(as)i(described)e (for)g FJ(handle_starttag\(\))f FN(abo)o(v)o(e.)0 1368 y FD(end_)p Fo(tag)p FJ(\(\))208 1468 y FN(This)i(method)f(is)i(called) f(to)g(process)g(a)h(closing)e(tag)h FK(ta)o(g)p FN(.)0 1614 y(Note)g(that)g(the)g(parser)g(maintains)f(a)i(stack)f(of)g(open)f (elements)h(for)f(which)h(no)g(end)f(tag)h(has)h(been)e(found)g(yet.)25 b(Only)19 b(tags)i(processed)0 1714 y(by)i FJ(start_)p FK(ta)o(g)p FJ(\(\))e FN(are)i(pushed)f(on)h(this)g(stack.)34 b(De\002nition)23 b(of)f(an)h FJ(end_)p FK(ta)o(g)p FJ(\(\))f FN(method)g(is)i(optional)e(for)g(these)i(tags.)34 b(F)o(or)22 b(tags)0 1814 y(processed)f(by)i FJ(do_)p FK(ta)o(g)p FJ(\(\))e FN(or)h(by)h FJ(unknown_tag\(\))p FN(,)e(no)h FJ(end_)p FK(ta)o(g)p FJ(\(\))f FN(method)g(must)i(be)f(de\002ned;)h (if)g(de\002ned,)f(it)h(will)g(not)g(be)0 1913 y(used.)45 b(If)27 b(both)g FJ(start_)p FK(ta)o(g)p FJ(\(\))e FN(and)h FJ(do_)p FK(ta)o(g)p FJ(\(\))g FN(methods)g(e)o(xist)i(for)e(a)i(tag,)g (the)f FJ(start_)p FK(ta)o(g)p FJ(\(\))f FN(method)f(tak)o(es)j (precedence.)0 2340 y FE(8.3)121 b Fx(htmllib)31 b FE(\227)i(A)g (parser)h(f)l(or)g(HTML)g(documents)0 2573 y FN(This)d(module)e (de\002nes)h(a)h(class)g(which)f(can)g(serv)o(e)g(as)i(a)e(base)h(for)f (parsing)f(te)o(xt)i(\002les)g(formatted)e(in)h(the)h(HyperT)-6 b(e)o(xt)29 b(Mark-up)0 2673 y(Language)20 b(\(HTML\).)h(The)h(class)i (is)f(not)f(directly)g(concerned)e(with)i(I/O)h(\227)g(it)g(must)f(be)h (pro)o(vided)c(with)k(input)f(in)g(string)g(form)g(via)0 2772 y(a)g(method,)e(and)h(mak)o(es)g(calls)h(to)f(methods)g(of)g(a)g (\223formatter\224)f(object)h(in)g(order)f(to)i(produce)d(output.)27 b(The)21 b FJ(HTMLParser)f FN(class)j(is)0 2872 y(designed)g(to)h(be)g (used)g(as)h(a)f(base)g(class)h(for)f(other)f(classes)i(in)g(order)d (to)j(add)e(functionality)-5 b(,)22 b(and)i(allo)n(ws)g(most)g(of)g (its)h(methods)e(to)0 2972 y(be)f(e)o(xtended)e(or)i(o)o(v)o(erridden.) 27 b(In)22 b(turn,)g(this)h(class)g(is)g(deri)n(v)o(ed)d(from)h(and)h (e)o(xtends)f(the)h FJ(SGMLParser)f FN(class)i(de\002ned)e(in)h(module) 0 3071 y FJ(sgmllib)p FN(.)44 b(The)27 b FJ(HTMLParser)e FN(implementation)g(supports)h(the)g(HTML)h(2.0)f(language)f(as)j (described)d(in)i(RFC)i(1866.)43 b(T)-7 b(w)o(o)0 3171 y(implementations)25 b(of)h(formatter)g(objects)g(are)h(pro)o(vided)d (in)j(the)g FJ(formatter)f FN(module;)j(refer)d(to)h(the)f (documentation)e(for)i(that)0 3271 y(module)19 b(for)g(information)f (on)i(the)g(formatter)f(interf)o(ace.)0 3417 y(The)h(follo)n(wing)e(is) k(a)e(summary)f(of)h(the)g(interf)o(ace)f(de\002ned)h(by)f FJ(sgmllib.SGMLParser)p FN(:)125 3647 y FM(\017)41 b FN(The)23 b(interf)o(ace)g(to)h(feed)f(data)g(to)h(an)g(instance)f(is)i (through)d(the)h FJ(feed\(\))g FN(method,)g(which)h(tak)o(es)g(a)g (string)f(ar)o(gument.)33 b(This)208 3747 y(can)25 b(be)h(called)f (with)h(as)g(little)h(or)e(as)i(much)d(te)o(xt)i(at)g(a)g(time)g(as)g (desired;)i(`)p FJ(p.feed\(a\);)48 b(p.feed\(b\))p FN(')24 b(has)i(the)f(same)208 3847 y(ef)n(fect)f(as)i(`)p FJ(p.feed\(a+b\))p FN('.)37 b(When)25 b(the)g(data)f(contains)h(complete)f(HTML)g(markup)f (constructs,)j(these)f(are)g(processed)208 3946 y(immediately;)e (incomplete)e(constructs)i(are)f(sa)n(v)o(ed)h(in)g(a)h(b)n(uf)n(fer)-5 b(.)32 b(T)-7 b(o)24 b(force)e(processing)f(of)i(all)h(unprocessed)d (data,)i(call)h(the)208 4046 y FJ(close\(\))19 b FN(method.)208 4179 y(F)o(or)g(e)o(xample,)g(to)h(parse)g(the)g(entire)g(contents)g (of)g(a)g(\002le,)h(use:)444 4403 y FA (parser.feed\(open\('myfile.html'\).read\(\))o(\))444 4494 y(parser.close\(\))125 4800 y FM(\017)41 b FN(The)31 b(interf)o(ace)f(to)i(de\002ne)f(semantics)h(for)f(HTML)g(tags)h(is)g (v)o(ery)f(simple:)48 b(deri)n(v)o(e)30 b(a)i(class)g(and)f(de\002ne)g (methods)g(called)208 4899 y FJ(start_)p FK(ta)o(g)p FJ(\(\))p FN(,)20 b FJ(end_)p FK(ta)o(g)p FJ(\(\))p FN(,)h(or)g FJ(do_)p FK(ta)o(g)p FJ(\(\))p FN(.)29 b(The)22 b(parser)f(will)i(call) f(these)h(at)f(appropriate)d(moments:)28 b FJ(start_)p FK(ta)o(g)21 b FN(or)208 4999 y FJ(do_)p FK(ta)o(g)p FJ(\(\))e FN(is)j(called)e(when)h(an)f(opening)f(tag)i(of)f(the)h(form) f FJ(<)p FK(ta)o(g)49 b FJ(...>)20 b FN(is)i(encountered;)c FJ(end_)p FK(ta)o(g)p FJ(\(\))i FN(is)h(called)g(when)f(a)208 5099 y(closing)e(tag)i(of)f(the)g(form)g FJ(<)p FK(ta)o(g)p FJ(>)g FN(is)h(encountered.)i(If)d(an)h(opening)d(tag)j(requires)e(a)i (corresponding)c(closing)j(tag,)g(lik)o(e)h FJ(<H1>)208 5198 y FN(...)42 b FJ(</H1>)p FN(,)26 b(the)g(class)h(should)e (de\002ne)g(the)h FJ(start_)p FK(ta)o(g)p FJ(\(\))e FN(method;)k(if)e (a)g(tag)g(requires)f(no)g(closing)g(tag,)i(lik)o(e)g FJ(<P>)p FN(,)g(the)208 5298 y(class)21 b(should)e(de\002ne)h(the)g FJ(do_)p FK(ta)o(g)p FJ(\(\))f FN(method.)p 0 5549 3901 4 v 0 5649 a FI(262)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 263 275 TeXDict begin 263 274 bop 0 83 a FN(The)20 b(module)f(de\002nes)h(a)g (parser)g(class)h(and)f(an)g(e)o(xception:)0 230 y FL(class)h FD(HTMLParser)p FJ(\()p FK(formatter)r FJ(\))208 330 y FN(This)e(is)g(the)g(basic)g(HTML)g(parser)f(class.)25 b(It)19 b(supports)f(all)h(entity)g(names)f(required)f(by)i(the)g (XHTML)f(1.0)g(Recommendation)208 429 y(\()p FO(http://www)l (.w3.org/TR/xht)o(ml1)-6 b FN(\).)24 b(It)16 b(also)h(de\002nes)g (handlers)e(for)h(all)h(HTML)g(2.0)f(and)g(man)o(y)f(HTML)h(3.0)g(and)g (3.2)g(elements.)0 576 y FL(exception)j FD(HTMLParseError)208 676 y FN(Exception)f(raised)i(by)g(the)g FJ(HTMLParser)f FN(class)i(when)f(it)g(encounters)f(an)h(error)f(while)h(parsing.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 823 y FL(See)i(Also:)0 969 y FN(Module)e FJ(formatter)g FN(\(section)h(33.1\):)208 1069 y(Interf)o(ace)i(de\002nition)g(for)h(transforming)d(an)k (abstract)f(\003o)n(w)g(of)g(formatting)f(e)n(v)o(ents)g(into)h (speci\002c)h(output)e(e)n(v)o(ents)h(on)g(writer)208 1169 y(objects.)0 1316 y(Module)c FJ(HTMLParser)g FN(\(section)h (8.1\):)208 1415 y(Alternate)15 b(HTML)h(parser)f(that)h(of)n(fers)f(a) i(slightly)e(lo)n(wer)n(-le)n(v)o(el)g(vie)n(w)h(of)f(the)h(input,)g(b) n(ut)g(is)h(designed)e(to)h(w)o(ork)f(with)h(XHTML,)208 1515 y(and)21 b(does)i(not)f(implement)f(some)h(of)g(the)g(SGML)h (syntax)f(not)g(used)g(in)g(\223HTML)g(as)h(deplo)o(yed\224)e(and)h (which)f(isn')o(t)i(le)o(gal)e(for)208 1614 y(XHTML.)0 1761 y(Module)e FJ(htmlentitydefs)f FN(\(section)i(8.4\):)208 1861 y(De\002nition)f(of)h(replacement)e(te)o(xt)i(for)g(XHTML)g(1.0)f (entities.)0 2008 y(Module)g FJ(sgmllib)g FN(\(section)h(8.2\):)208 2107 y(Base)h(class)g(for)e FJ(HTMLParser)p FN(.)0 2392 y Fv(8.3.1)100 b(HTMLP)l(arser)29 b(Objects)0 2595 y FN(In)22 b(addition)e(to)i(tag)g(methods,)f(the)h FJ(HTMLParser)e FN(class)j(pro)o(vides)d(some)i(additional)e(methods)h(and)h(instance)f (v)n(ariables)g(for)g(use)0 2695 y(within)f(tag)g(methods.)0 2842 y FD(formatter)208 2941 y FN(This)g(is)h(the)f(formatter)f (instance)h(associated)g(with)g(the)g(parser)-5 b(.)0 3088 y FD(nofill)208 3188 y FN(Boolean)26 b(\003ag)i(which)f(should)g (be)h(true)f(when)g(whitespace)g(should)g(not)g(be)h(collapsed,)g(or)f (f)o(alse)i(when)e(it)h(should)f(be.)47 b(In)208 3287 y(general,)19 b(this)i(should)e(only)h(be)h(true)f(when)g(character)f (data)i(is)g(to)g(be)f(treated)g(as)h(\223preformatted\224)d(te)o(xt,)i (as)i(within)e(a)h FJ(<PRE>)208 3387 y FN(element.)j(The)c(def)o(ault)f (v)n(alue)h(is)h(f)o(alse.)k(This)c(af)n(fects)f(the)g(operation)e(of)i FJ(handle_data\(\))e FN(and)i FJ(save_end\(\))p FN(.)0 3534 y FD(anchor_bgn)p FJ(\()p FK(hr)m(ef)o(,)e(name)o(,)i(type)p FJ(\))208 3634 y FN(This)f(method)e(is)j(called)f(at)g(the)g(start)h (of)e(an)h(anchor)e(re)o(gion.)23 b(The)c(ar)o(guments)e(correspond)f (to)j(the)g(attrib)n(utes)g(of)g(the)g FJ(<A>)g FN(tag)208 3733 y(with)i(the)f(same)h(names.)27 b(The)20 b(def)o(ault)h (implementation)d(maintains)i(a)i(list)g(of)e(hyperlinks)f(\(de\002ned) g(by)h(the)h FJ(HREF)g FN(attrib)n(ute)208 3833 y(for)e FJ(<A>)h FN(tags\))g(within)g(the)h(document.)i(The)c(list)j(of)e (hyperlinks)d(is)22 b(a)n(v)n(ailable)d(as)i(the)f(data)g(attrib)n(ute) g FJ(anchorlist)p FN(.)0 3980 y FD(anchor_end)p FJ(\(\))208 4079 y FN(This)e(method)g(is)h(called)g(at)g(the)f(end)g(of)h(an)f (anchor)f(re)o(gion.)23 b(The)18 b(def)o(ault)g(implementation)f(adds)h (a)h(te)o(xtual)f(footnote)f(mark)o(er)208 4179 y(using)i(an)h(inde)o (x)f(into)h(the)g(list)i(of)e(hyperlinks)e(created)h(by)h FJ(anchor_bgn\(\))p FN(.)0 4326 y FD(handle_image)p FJ(\()p FK(sour)m(ce)o(,)e(alt)q FC([)p FK(,)i(ismap)p FC([)p FK(,)g(align)p FC([)p FK(,)f(width)p FC([)p FK(,)h(height)13 b FC(])f(])g(])g(])p FJ(\))208 4425 y FN(This)37 b(method)f(is)j (called)e(to)g(handle)g(images.)76 b(The)37 b(def)o(ault)g (implementation)e(simply)i(passes)i(the)e FK(alt)i FN(v)n(alue)e(to)h (the)208 4525 y FJ(handle_data\(\))18 b FN(method.)0 4672 y FD(save_bgn)p FJ(\(\))208 4772 y FN(Be)o(gins)g(sa)n(ving)h (character)f(data)g(in)h(a)h(b)n(uf)n(fer)d(instead)i(of)g(sending)e (it)j(to)f(the)g(formatter)e(object.)24 b(Retrie)n(v)o(e)19 b(the)f(stored)h(data)g(via)208 4871 y FJ(save_end\(\))p FN(.)k(Use)e(of)f(the)g FJ(save_bgn\(\))f FN(/)i FJ(save_end\(\))e FN(pair)h(may)f(not)h(be)g(nested.)0 5018 y FD(save_end)p FJ(\(\))208 5118 y FN(Ends)32 b(b)n(uf)n(fering)e(character)i(data)g (and)g(returns)g(all)h(data)g(sa)n(v)o(ed)f(since)h(the)g(preceding)d (call)j(to)g FJ(save_bgn\(\))p FN(.)61 b(If)33 b(the)208 5217 y FJ(nofill)d FN(\003ag)h(is)h(f)o(alse,)i(whitespace)d(is)h (collapsed)e(to)h(single)g(spaces.)58 b(A)32 b(call)f(to)g(this)h (method)e(without)g(a)i(preceding)208 5317 y(call)20 b(to)h FJ(save_bgn\(\))d FN(will)j(raise)g(a)f FJ(TypeError)g FN(e)o(xception.)p 0 5549 3901 4 v 0 5649 a FI(8.3.)52 b FJ(htmllib)22 b FI(\227)h(A)g(parser)g(f)n(or)f(HTML)h(documents)1985 b(263)p eop end %%Page: 264 276 TeXDict begin 264 275 bop 0 87 a FE(8.4)121 b Fx(htmlentitydefs)29 b FE(\227)k(De\002nitions)h(of)g(HTML)g(gener)o(al)h(entities)0 320 y FN(This)72 b(module)f(de\002nes)g(three)h(dictionaries,)84 b FJ(name2codepoint)p FN(,)e FJ(codepoint2name)p FN(,)h(and)71 b FJ(entitydefs)p FN(.)0 420 y FJ(entitydefs)23 b FN(is)i(used)f(by)g (the)g FJ(htmllib)g FN(module)f(to)h(pro)o(vide)e(the)j FJ(entitydefs)e FN(member)g(of)h(the)g FJ(HTMLParser)f FN(class.)0 519 y(The)d(de\002nition)g(pro)o(vided)e(here)i(contains)g (all)h(the)g(entities)g(de\002ned)e(by)i(XHTML)f(1.0)g(that)h(can)f(be) h(handled)e(using)h(simple)g(te)o(xtual)0 619 y(substitution)f(in)i (the)f(Latin-1)f(character)g(set)i(\(ISO-8859-1\).)0 766 y FD(entitydefs)208 866 y FN(A)f(dictionary)f(mapping)f(XHTML)i (1.0)f(entity)h(de\002nitions)g(to)g(their)g(replacement)e(te)o(xt)i (in)h(ISO)f(Latin-1.)0 1012 y FD(name2codepoint)208 1112 y FN(A)g(dictionary)f(that)h(maps)g(HTML)g(entity)g(names)g(to)g(the)g (Unicode)f(codepoints.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1259 y FD(codepoint2name)208 1358 y FN(A)h(dictionary)f(that)h(maps)g (Unicode)f(codepoints)f(to)j(HTML)f(entity)g(names.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1686 y FE(8.5)121 b Fx(xml.parsers.expat)28 b FE(\227)33 b(F)-6 b(ast)34 b(XML)f(parsing)h(using)g(Expat)0 1919 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 2066 y(The)f FJ(xml.parsers.expat)f FN(module)g(is)j(a)f(Python)f(interf)o(ace)f(to)i(the)g(Expat)f(non-v)n (alidating)e(XML)j(parser)-5 b(.)24 b(The)18 b(module)g(pro-)0 2165 y(vides)h(a)g(single)g(e)o(xtension)e(type,)i FJ(xmlparser)p FN(,)e(that)i(represents)f(the)h(current)f(state)i(of)e(an)h(XML)g (parser)-5 b(.)24 b(After)19 b(an)g FJ(xmlparser)0 2265 y FN(object)k(has)h(been)f(created,)h(v)n(arious)e(attrib)n(utes)i(of)f (the)h(object)f(can)g(be)h(set)g(to)g(handler)e(functions.)34 b(When)24 b(an)f(XML)h(document)e(is)0 2364 y(then)e(fed)f(to)i(the)f (parser)m(,)f(the)h(handler)f(functions)g(are)h(called)g(for)f(the)i (character)e(data)h(and)f(markup)g(in)h(the)g(XML)g(document.)0 2511 y(This)h(module)e(uses)j(the)e FJ(pyexpat)g FN(module)g(to)h(pro)o (vide)e(access)i(to)g(the)g(Expat)f(parser)-5 b(.)26 b(Direct)21 b(use)g(of)f(the)h FJ(pyexpat)f FN(module)g(is)0 2611 y(deprecated.)0 2758 y(This)g(module)f(pro)o(vides)g(one)g(e)o (xception)g(and)g(one)h(type)g(object:)0 2905 y FL(exception)f FD(ExpatError)208 3004 y FN(The)j(e)o(xception)f(raised)h(when)g(Expat) g(reports)g(an)h(error)-5 b(.)32 b(See)23 b(section)f(8.5.2,)g (\223ExpatError)e(Exceptions,)-6 b(\224)22 b(for)g(more)g(infor)n(-)208 3104 y(mation)d(on)h(interpreting)e(Expat)h(errors.)0 3251 y FL(exception)g FD(error)208 3350 y FN(Alias)i(for)e FJ(ExpatError)p FN(.)0 3497 y FD(XMLParserType)208 3597 y FN(The)g(type)h(of)g(the)g(return)f(v)n(alues)h(from)f(the)h FJ(ParserCreate\(\))f FN(function.)0 3744 y(The)h FJ(xml.parsers.expat) d FN(module)i(contains)h(tw)o(o)g(functions:)0 3891 y FD(ErrorString)p FJ(\()p FK(errno)p FJ(\))208 3990 y FN(Returns)g(an)g(e)o(xplanatory)d(string)j(for)g(a)g(gi)n(v)o(en)f (error)g(number)g FK(errno)p FN(.)0 4137 y FD(ParserCreate)p FJ(\()p FC([)p FK(encoding)p FC([)p FK(,)c(namespace)p 1449 4137 25 4 v 28 w(separ)o(ator)f FC(])e(])p FJ(\))208 4237 y FN(Creates)k(and)f(returns)f(a)i(ne)n(w)f FJ(xmlparser)g FN(object.)23 b FK(encoding)p FN(,)14 b(if)i(speci\002ed,)g(must)f(be)h (a)g(string)f(naming)f(the)h(encoding)f(used)208 4336 y(by)i(the)h(XML)g(data.)23 b(Expat)16 b(doesn')o(t)g(support)f(as)j (man)o(y)d(encodings)g(as)j(Python)e(does,)h(and)f(its)i(repertoire)d (of)h(encodings)g(can')o(t)208 4436 y(be)k(e)o(xtended;)f(it)i (supports)e(UTF-8,)h(UTF-16,)g(ISO-8859-1)d(\(Latin1\),)i(and)h(ASCII.) h(If)f FK(encoding)f FN(is)i(gi)n(v)o(en)e(it)j(will)f(o)o(v)o(erride) 208 4536 y(the)f(implicit)g(or)g(e)o(xplicit)f(encoding)f(of)i(the)h (document.)208 4669 y(Expat)26 b(can)h(optionally)e(do)i(XML)g (namespace)f(processing)g(for)g(you,)i(enabled)e(by)h(pro)o(viding)d(a) k(v)n(alue)e(for)h FK(namespace)p 3850 4669 V 27 w(-)208 4768 y(separ)o(ator)r FN(.)j(The)22 b(v)n(alue)g(must)g(be)h(a)g (one-character)c(string;)k(a)g FJ(ValueError)e FN(will)i(be)g(raised)f (if)h(the)f(string)g(has)h(an)f(ille)o(gal)208 4868 y(length)17 b(\()p FJ(None)g FN(is)i(considered)d(the)i(same)g(as)g(omission\).)24 b(When)17 b(namespace)g(processing)g(is)h(enabled,)f(element)g(type)h (names)208 4967 y(and)27 b(attrib)n(ute)g(names)h(that)g(belong)e(to)i (a)g(namespace)f(will)h(be)g(e)o(xpanded.)45 b(The)27 b(element)h(name)f(passed)g(to)h(the)g(element)208 5067 y(handlers)17 b FJ(StartElementHandler)f FN(and)i FJ(EndElementHandler) e FN(will)k(be)e(the)h(concatenation)e(of)h(the)h(namespace)208 5167 y(URI,)26 b(the)g(namespace)e(separator)h(character)m(,)g(and)h (the)g(local)g(part)f(of)h(the)g(name.)41 b(If)26 b(the)g(namespace)e (separator)h(is)i(a)f(zero)208 5266 y(byte)19 b(\()p FJ(chr\(0\))p FN(\))g(then)h(the)g(namespace)f(URI)i(and)e(the)i(local) f(part)g(will)h(be)f(concatenated)e(without)h(an)o(y)h(separator)-5 b(.)208 5399 y(F)o(or)19 b(e)o(xample,)g(if)h FK(namespace)p 1111 5399 V 28 w(separ)o(ator)h FN(is)h(set)f(to)f(a)h(space)f (character)f(\(`)49 b('\))20 b(and)f(the)i(follo)n(wing)d(document)g (is)j(parsed:)p 0 5549 3901 4 v 0 5649 a FI(264)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T) -10 b(ools)p eop end %%Page: 265 277 TeXDict begin 265 276 bop 444 174 a FA(<?xml)44 b(version="1.0"?>)444 266 y(<root)g(xmlns)178 b(=)45 b("http://default-namespace.org/")713 357 y(xmlns:py)e(=)i("http://www.python.org/ns/">)533 448 y(<py:elem1)f(/>)533 540 y(<elem2)g(xmlns="")g(/>)444 631 y(</root>)208 820 y FJ(StartElementHandler)17 b FN(will)k(recei)n (v)o(e)e(the)h(follo)n(wing)f(strings)h(for)f(each)h(element:)444 1045 y FA(http://default-namespace.org/)40 b(root)444 1136 y(http://www.python.org/ns/)g(elem1)444 1227 y(elem2)0 1431 y FL(See)21 b(Also:)0 1578 y FK(The)f(Expat)g(XML)h(P)-7 b(ar)o(ser)0 1678 y Fy(\()p FO(http://www)l(.libe)n(xpat.or)o(g/)h Fy(\))208 1777 y FN(Home)19 b(page)h(of)g(the)g(Expat)f(project.)0 2062 y Fv(8.5.1)100 b(XMLP)l(arser)30 b(Objects)0 2265 y FJ(xmlparser)19 b FN(objects)h(ha)n(v)o(e)g(the)g(follo)n(wing)e (methods:)0 2412 y FD(Parse)p FJ(\()p FK(data)p FC([)p FK(,)g(is\002nal)12 b FC(])p FJ(\))208 2512 y FN(P)o(arses)18 b(the)f(contents)g(of)h(the)g(string)f FK(data)p FN(,)g(calling)g(the)h (appropriate)e(handler)g(functions)g(to)i(process)f(the)h(parsed)f (data.)24 b FK(is\002nal)208 2611 y FN(must)c(be)g(true)g(on)g(the)g (\002nal)g(call)h(to)f(this)h(method.)i FK(data)d FN(can)g(be)g(the)g (empty)f(string)h(at)h(an)o(y)e(time.)0 2758 y FD(ParseFile)p FJ(\()p FK(\002le)p FJ(\))208 2858 y FN(P)o(arse)24 b(XML)g(data)h (reading)d(from)i(the)g(object)g FK(\002le)p FN(.)37 b FK(\002le)25 b FN(only)e(needs)h(to)g(pro)o(vide)f(the)h FJ(read\()p FK(nbytes)p FJ(\))f FN(method,)h(returning)208 2957 y(the)c(empty)f(string)h(when)g(there')-5 b(s)20 b(no)f(more)h(data.)0 3104 y FD(SetBase)p FJ(\()p FK(base)p FJ(\))208 3204 y FN(Sets)36 b(the)g(base)g(to)g(be)g(used)f(for)g (resolving)g(relati)n(v)o(e)g(URIs)h(in)g(system)g(identi\002ers)f(in)h (declarations.)71 b(Resolving)35 b(rel-)208 3304 y(ati)n(v)o(e)h (identi\002ers)g(is)i(left)f(to)g(the)f(application:)57 b(this)37 b(v)n(alue)f(will)i(be)f(passed)f(through)f(as)i(the)g FK(base)f FN(ar)o(gument)f(to)i(the)208 3403 y FJ (ExternalEntityRefHandler)p FN(,)45 b FJ(NotationDeclHandler)p FN(,)h(and)d FJ(UnparsedEntityDeclHandler)208 3503 y FN(functions.)0 3650 y FD(GetBase)p FJ(\(\))208 3749 y FN(Returns)17 b(a)i(string)e(containing)f(the)i(base)g(set)h(by)f(a)g (pre)n(vious)e(call)j(to)f FJ(SetBase\(\))p FN(,)f(or)h FJ(None)f FN(if)i FJ(SetBase\(\))d FN(hasn')o(t)h(been)208 3849 y(called.)0 3996 y FD(GetInputContext)p FJ(\(\))208 4095 y FN(Returns)g(the)h(input)f(data)h(that)g(generated)e(the)h (current)g(e)n(v)o(ent)g(as)h(a)g(string.)24 b(The)18 b(data)f(is)i(in)f(the)g(encoding)d(of)j(the)g(entity)f(which)208 4195 y(contains)k(the)i(te)o(xt.)32 b(When)22 b(called)h(while)f(an)h (e)n(v)o(ent)f(handler)f(is)i(not)g(acti)n(v)o(e,)f(the)h(return)e(v)n (alue)h(is)h FJ(None)p FN(.)65 b(Ne)n(w)23 b(in)g(v)o(ersion)208 4295 y(2.1.)0 4442 y FD(ExternalEntityParserCreate)p FJ(\()p FK(conte)n(xt)q FC([)p FK(,)15 b(encoding)d FC(])p FJ(\))208 4541 y FN(Create)19 b(a)h(\223child\224)f(parser)g(which)g (can)g(be)h(used)f(to)h(parse)f(an)g(e)o(xternal)g(parsed)f(entity)i (referred)d(to)j(by)f(content)g(parsed)f(by)i(the)208 4641 y(parent)i(parser)-5 b(.)33 b(The)22 b FK(conte)n(xt)i FN(parameter)e(should)g(be)g(the)h(string)g(passed)g(to)g(the)g FJ(ExternalEntityRefHandler\(\))208 4740 y FN(handler)14 b(function,)g(described)h(belo)n(w)-5 b(.)22 b(The)15 b(child)g(parser)g(is)i(created)e(with)h(the)f FJ(ordered_attributes)p FN(,)f FJ(returns_-)208 4840 y(unicode)19 b FN(and)h FJ(specified_attributes)d FN(set)k(to)f(the)g(v)n(alues)g(of)g(this)h (parser)-5 b(.)0 4987 y FD(UseForeignDTD)p FJ(\()p FC([)p FK(\003a)o(g)12 b FC(])p FJ(\))208 5087 y FN(Calling)95 b(this)h(with)f(a)h(true)e(v)n(alue)h(for)g FK(\003a)o(g)f FN(\(the)h(def)o(ault\))f(will)i(cause)f(Expat)g(to)g(call)h(the)208 5186 y FJ(ExternalEntityRefHandler)23 b FN(with)k FJ(None)f FN(for)h(all)g(ar)o(guments)e(to)i(allo)n(w)g(an)g(alternate)f(DTD)i (to)f(be)g(loaded.)44 b(If)208 5286 y(the)25 b(document)e(does)j(not)f (contain)f(a)i(document)d(type)i(declaration,)g(the)h FJ(ExternalEntityRefHandler)21 b FN(will)26 b(still)208 5385 y(be)20 b(called,)f(b)n(ut)i(the)f FJ(StartDoctypeDeclHandler)c FN(and)k FJ(EndDoctypeDeclHandler)d FN(will)k(not)f(be)g(called.)p 0 5549 3901 4 v 0 5649 a FI(8.5.)52 b FJ(xml.parsers.expat)20 b FI(\227)j(F)l(ast)g(XML)g(parsing)h(using)f(Expat)1493 b(265)p eop end %%Page: 266 278 TeXDict begin 266 277 bop 208 83 a FN(P)o(assing)20 b(a)g(f)o(alse)h(v) n(alue)f(for)f FK(\003a)o(g)h FN(will)h(cancel)e(a)i(pre)n(vious)e (call)h(that)g(passed)h(a)f(true)g(v)n(alue,)f(b)n(ut)h(otherwise)g (has)g(no)g(ef)n(fect.)208 216 y(This)g(method)g(can)g(only)g(be)h (called)f(before)f(the)i FJ(Parse\(\))f FN(or)g FJ(ParseFile\(\))g FN(methods)f(are)i(called;)f(calling)h(it)g(after)f(ei-)208 315 y(ther)15 b(of)g(those)h(ha)n(v)o(e)f(been)g(called)g(causes)h FJ(ExpatError)f FN(to)g(be)h(raised)g(with)f(the)h FJ(code)g FN(attrib)n(ute)f(set)h(to)g FJ(errors.XML_-)208 415 y(ERROR_CANT_CHANGE_FEATURE_ONCE_PA)o(RSING)o FN(.)208 548 y(Ne)n(w)k(in)g(v)o(ersion)f(2.3.)0 695 y FJ(xmlparser)g FN(objects)h(ha)n(v)o(e)g(the)g(follo)n(wing)e(attrib)n(utes:)0 842 y FD(buffer_size)208 941 y FN(The)k(size)i(of)f(the)h(b)n(uf)n(fer) e(used)h(when)f FJ(buffer_text)g FN(is)i(true.)34 b(This)24 b(v)n(alue)e(cannot)g(be)i(changed)d(at)j(this)g(time.)69 b(Ne)n(w)23 b(in)208 1041 y(v)o(ersion)18 b(2.3.)0 1188 y FD(buffer_text)208 1287 y FN(Setting)i(this)i(to)f(true)f(causes)i (the)f FJ(xmlparser)e FN(object)i(to)g(b)n(uf)n(fer)e(te)o(xtual)i (content)f(returned)f(by)h(Expat)g(to)i(a)n(v)n(oid)e(multiple)208 1387 y(calls)25 b(to)g(the)f FJ(CharacterDataHandler\(\))d FN(callback)j(whene)n(v)o(er)e(possible.)38 b(This)25 b(can)f(impro)o(v)o(e)e(performance)g(sub-)208 1487 y(stantially)e (since)i(Expat)e(normally)f(breaks)h(character)g(data)g(into)h(chunks)f (at)h(e)n(v)o(ery)f(line)h(ending.)k(This)c(attrib)n(ute)g(is)h(f)o (alse)f(by)208 1586 y(def)o(ault,)e(and)g(may)h(be)g(changed)f(at)h(an) o(y)g(time.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 1733 y FD(buffer_used)208 1833 y FN(If)k FJ(buffer_text)e FN(is)j(enabled,)f(the)g(number)e(of)i(bytes)g(stored)g(in)g(the)g(b)n (uf)n(fer)-5 b(.)33 b(These)23 b(bytes)g(represent)f(UTF-8)g(encoded) 208 1932 y(te)o(xt.)i(This)d(attrib)n(ute)f(has)g(no)g(meaningful)e (interpretation)g(when)h FJ(buffer_text)g FN(is)i(f)o(alse.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 2079 y FD(ordered_attributes)208 2179 y FN(Setting)k(this)h(attrib)n(ute)f(to)h(a)g(non-zero)d(inte)o (ger)i(causes)g(the)h(attrib)n(utes)f(to)h(be)g(reported)d(as)k(a)f (list)g(rather)f(than)g(a)h(dictionary)-5 b(.)208 2279 y(The)28 b(attrib)n(utes)h(are)g(presented)e(in)i(the)g(order)f(found)f (in)i(the)g(document)e(te)o(xt.)50 b(F)o(or)29 b(each)f(attrib)n(ute,)j (tw)o(o)e(list)h(entries)f(are)208 2378 y(presented:)d(the)c(attrib)n (ute)f(name)g(and)g(the)g(attrib)n(ute)g(v)n(alue.)29 b(\(Older)20 b(v)o(ersions)h(of)g(this)h(module)e(also)i(used)g(this)g (format.\))27 b(By)208 2478 y(def)o(ault,)19 b(this)i(attrib)n(ute)e (is)i(f)o(alse;)g(it)g(may)f(be)g(changed)e(at)j(an)o(y)e(time.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 2625 y FD(returns_unicode)208 2724 y FN(If)e(this)h(attrib)n(ute)g(is)g(set)h(to)f(a)g(non-zero)d (inte)o(ger)m(,)i(the)g(handler)g(functions)f(will)i(be)g(passed)g (Unicode)e(strings.)24 b(If)18 b FJ(returns_-)208 2824 y(unicode)g FN(is)j FJ(False)p FN(,)e(8-bit)g(strings)h(containing)e (UTF-8)h(encoded)f(data)h(will)i(be)f(passed)f(to)h(the)g(handlers.)j (This)d(is)h FJ(True)208 2924 y FN(by)f(def)o(ault)h(when)g(Python)f (is)i(b)n(uilt)f(with)h(Unicode)e(support.)56 b(Changed)19 b(in)j(v)o(ersion)e(1.6:)h(Can)g(be)g(changed)f(at)i(an)o(y)e(time)h (to)208 3023 y(af)n(fect)e(the)h(result)h(type.)0 3170 y FD(specified_attributes)208 3270 y FN(If)26 b(set)h(to)g(a)f (non-zero)e(inte)o(ger)m(,)j(the)f(parser)g(will)h(report)e(only)h (those)g(attrib)n(utes)g(which)g(were)g(speci\002ed)h(in)f(the)h (document)208 3369 y(instance)d(and)f(not)h(those)g(which)g(were)h (deri)n(v)o(ed)d(from)h(attrib)n(ute)h(declarations.)36 b(Applications)24 b(which)f(set)j(this)e(need)g(to)h(be)208 3469 y(especially)17 b(careful)f(to)i(use)f(what)h(additional)e (information)f(is)j(a)n(v)n(ailable)f(from)g(the)g(declarations)f(as)j (needed)d(to)h(comply)f(with)208 3569 y(the)23 b(standards)f(for)h(the) g(beha)n(vior)f(of)h(XML)g(processors.)33 b(By)24 b(def)o(ault,)f(this) h(attrib)n(ute)f(is)h(f)o(alse;)h(it)f(may)f(be)g(changed)f(at)h(an)o (y)208 3668 y(time.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 3815 y(The)51 b(follo)n(wing)f(attrib)n(utes)h(contain)g(v)n(alues)g (relating)f(to)i(the)f(most)h(recent)e(error)h(encountered)d(by)j(an)h FJ(xmlparser)0 3915 y FN(object,)70 b(and)61 b(will)h(only)e(ha)n(v)o (e)g(correct)g(v)n(alues)h(once)f(a)i(call)f(to)g FJ(Parse\(\))g FN(or)g FJ(ParseFile\(\))e FN(has)i(raised)g(a)0 4014 y FJ(xml.parsers.expat.ExpatError)16 b FN(e)o(xception.)0 4161 y FD(ErrorByteIndex)208 4261 y FN(Byte)k(inde)o(x)f(at)i(which)e (an)i(error)e(occurred.)0 4408 y FD(ErrorCode)208 4507 y FN(Numeric)14 b(code)h(specifying)f(the)i(problem.)22 b(This)16 b(v)n(alue)f(can)g(be)h(passed)f(to)h(the)g FJ(ErrorString\(\))e FN(function,)g(or)i(compared)208 4607 y(to)k(one)g(of)f(the)i(constants)e(de\002ned)h(in)g(the)g FJ(errors)g FN(object.)0 4754 y FD(ErrorColumnNumber)208 4853 y FN(Column)f(number)f(at)j(which)f(an)g(error)f(occurred.)0 5000 y FD(ErrorLineNumber)208 5100 y FN(Line)g(number)g(at)i(which)e (an)h(error)f(occurred.)0 5247 y(The)29 b(follo)n(wing)f(attrib)n(utes) h(contain)g(v)n(alues)g(relating)f(to)i(the)g(current)e(parse)h (location)f(in)i(an)f FJ(xmlparser)g FN(object.)52 b(During)28 b(a)0 5346 y(callback)21 b(reporting)f(a)i(parse)g(e)n(v)o(ent)f(the)o (y)g(indicate)h(the)g(location)f(of)g(the)h(\002rst)h(of)f(the)g (sequence)f(of)g(characters)g(that)h(generated)f(the)p 0 5549 3901 4 v 0 5649 a FI(266)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 267 279 TeXDict begin 267 278 bop 0 83 a FN(e)n(v)o(ent.)42 b(When)26 b(called)g(outside)g(of)g(a)h(callback,)f(the)h(position)e(indicated)g (will)i(be)f(just)h(past)g(the)f(last)h(parse)f(e)n(v)o(ent)f(\(re)o (gardless)g(of)0 183 y(whether)19 b(there)h(w)o(as)h(an)f(associated)g (callback\).)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)0 330 y FD(CurrentByteIndex)208 429 y FN(Current)g(byte)h(inde)o(x)f(in)h (the)g(parser)g(input.)0 576 y FD(CurrentColumnNumber)208 676 y FN(Current)f(column)g(number)f(in)i(the)h(parser)e(input.)0 823 y FD(CurrentLineNumber)208 922 y FN(Current)g(line)h(number)f(in)h (the)g(parser)g(input.)0 1069 y(Here)f(is)i(the)e(list)i(of)e(handlers) g(that)g(can)g(be)h(set.)25 b(T)-7 b(o)20 b(set)g(a)g(handler)e(on)h (an)h FJ(xmlparser)e FN(object)h FK(o)p FN(,)h(use)f FK(o)p FJ(.)p FK(handlername)47 b FJ(=)i FK(func)p FN(.)0 1169 y FK(handlername)21 b FN(must)j(be)f(tak)o(en)g(from)f(the)i (follo)n(wing)e(list,)j(and)e FK(func)g FN(must)g(be)g(a)h(callable)f (object)g(accepting)f(the)i(correct)e(number)0 1268 y(of)e(ar)o (guments.)j(The)d(ar)o(guments)e(are)i(all)h(strings,)f(unless)g (otherwise)f(stated.)0 1415 y FD(XmlDeclHandler)p FJ(\()p FK(ver)o(sion,)e(encoding)o(,)h(standalone)p FJ(\))208 1515 y FN(Called)26 b(when)g(the)g(XML)h(declaration)e(is)i(parsed.)43 b(The)26 b(XML)g(declaration)f(is)i(the)g(\(optional\))d(declaration)h (of)h(the)g(appli-)208 1614 y(cable)f(v)o(ersion)f(of)h(the)h(XML)f (recommendation,)e(the)j(encoding)d(of)i(the)h(document)d(te)o(xt,)k (and)e(an)g(optional)f(\223standalone\224)208 1714 y(declaration.)e FK(ver)o(sion)c FN(and)f FK(encoding)f FN(will)i(be)g(strings)g(of)f (the)h(type)g(dictated)f(by)g(the)h FJ(returns_unicode)d FN(attrib)n(ute,)j(and)208 1814 y FK(standalone)f FN(will)k(be)f FJ(1)g FN(if)g(the)g(document)e(is)j(declared)d(standalone,)h FJ(0)h FN(if)g(it)h(is)f(declared)f(not)h(to)g(be)f(standalone,)g(or)g FJ(-1)h FN(if)h(the)208 1913 y(standalone)d(clause)j(w)o(as)g(omitted.) j(This)c(is)h(only)f(a)n(v)n(ailable)f(with)i(Expat)e(v)o(ersion)g (1.95.0)f(or)i(ne)n(wer)-5 b(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.1.) 0 2060 y FD(StartDoctypeDeclHandler)p FJ(\()p FK(doctypeName)n(,)d (systemId,)20 b(publicId,)e(has)p 2459 2060 25 4 v 30 w(internal)p 2753 2060 V 28 w(subset)q FJ(\))208 2160 y FN(Called)26 b(when)g(Expat)g(be)o(gins)f(parsing)h(the)g(document)f (type)h(declaration)f(\()p FJ(<!DOCTYPE)47 b(...)p FN(\).)d(The)26 b FK(doctypeName)f FN(is)208 2259 y(pro)o(vided)c(e)o(xactly)j(as)h (presented.)35 b(The)24 b FK(systemId)j FN(and)c FK(publicId)i FN(parameters)e(gi)n(v)o(e)h(the)g(system)g(and)g(public)f (identi\002ers)h(if)208 2359 y(speci\002ed,)d(or)g FJ(None)h FN(if)g(omitted.)29 b FK(has)p 1358 2359 V 29 w(internal)p 1651 2359 V 29 w(subset)23 b FN(will)f(be)g(true)f(if)h(the)g(document) e(contains)h(and)g(internal)g(document)208 2459 y(declaration)d (subset.)25 b(This)c(requires)e(Expat)g(v)o(ersion)g(1.2)h(or)g(ne)n (wer)-5 b(.)0 2606 y FD(EndDoctypeDeclHandler)p FJ(\(\))208 2705 y FN(Called)20 b(when)g(Expat)f(is)i(done)e(parsing)h(the)g (document)e(type)i(declaration.)j(This)d(requires)g(Expat)f(v)o(ersion) g(1.2)g(or)h(ne)n(wer)-5 b(.)0 2852 y FD(ElementDeclHandler)p FJ(\()p FK(name)o(,)16 b(model)p FJ(\))208 2952 y FN(Called)22 b(once)f(for)g(each)h(element)f(type)h(declaration.)29 b FK(name)21 b FN(is)i(the)f(name)f(of)h(the)g(element)f(type,)h(and)f FK(model)h FN(is)h(a)f(represen-)208 3051 y(tation)d(of)h(the)h (content)e(model.)0 3198 y FD(AttlistDeclHandler)p FJ(\()p FK(elname)o(,)d(attname)o(,)j(type)o(,)h(default,)f(r)m(equir)m(ed)r FJ(\))208 3298 y FN(Called)e(for)f(each)g(declared)g(attrib)n(ute)g (for)h(an)f(element)h(type.)23 b(If)17 b(an)f(attrib)n(ute)h(list)h (declaration)d(declares)i(three)f(attrib)n(utes,)h(this)208 3397 y(handler)g(is)j(called)e(three)h(times,)g(once)f(for)g(each)h (attrib)n(ute.)24 b FK(elname)18 b FN(is)i(the)e(name)h(of)f(the)h (element)f(to)h(which)f(the)h(declaration)208 3497 y(applies)29 b(and)g FK(attname)g FN(is)i(the)e(name)g(of)h(the)g(attrib)n(ute)f (declared.)52 b(The)29 b(attrib)n(ute)h(type)f(is)i(a)f(string)f (passed)h(as)g FK(type)p FN(;)35 b(the)208 3597 y(possible)21 b(v)n(alues)h(are)g FJ('CDATA')p FN(,)f FJ('ID')p FN(,)g FJ('IDREF')p FN(,)g(...)31 b FK(default)22 b FN(gi)n(v)o(es)g(the)g (def)o(ault)f(v)n(alue)g(for)h(the)g(attrib)n(ute)f(used)h(when)208 3696 y(the)c(attrib)n(ute)g(is)h(not)f(speci\002ed)g(by)g(the)g (document)e(instance,)i(or)g FJ(None)g FN(if)h(there)e(is)j(no)d(def)o (ault)h(v)n(alue)g(\()p FJ(#IMPLIED)f FN(v)n(alues\).)208 3796 y(If)29 b(the)h(attrib)n(ute)f(is)i(required)c(to)j(be)g(gi)n(v)o (en)e(in)i(the)g(document)d(instance,)32 b FK(r)m(equir)m(ed)f FN(will)f(be)g(true.)53 b(This)30 b(requires)e(Expat)208 3896 y(v)o(ersion)18 b(1.95.0)h(or)h(ne)n(wer)-5 b(.)0 4042 y FD(StartElementHandler)p FJ(\()p FK(name)o(,)16 b(attrib)n(utes)p FJ(\))208 4142 y FN(Called)i(for)f(the)h(start)h(of)e (e)n(v)o(ery)g(element.)23 b FK(name)18 b FN(is)h(a)f(string)g (containing)e(the)i(element)f(name,)h(and)f FK(attrib)n(utes)h FN(is)h(a)f(dictionary)208 4242 y(mapping)g(attrib)n(ute)i(names)g(to)g (their)g(v)n(alues.)0 4389 y FD(EndElementHandler)p FJ(\()p FK(name)p FJ(\))208 4488 y FN(Called)g(for)g(the)g(end)f(of)h(e)n(v)o (ery)f(element.)0 4635 y FD(ProcessingInstructionHandler)p FJ(\()p FK(tar)m(g)o(et,)c(data)p FJ(\))208 4735 y FN(Called)20 b(for)g(e)n(v)o(ery)e(processing)h(instruction.)0 4882 y FD(CharacterDataHandler)p FJ(\()p FK(data)p FJ(\))208 4981 y FN(Called)i(for)g(character)e(data.)28 b(This)21 b(will)h(be)f(called)g(for)g(normal)f(character)g(data,)h(CD)m(A)-9 b(T)h(A)21 b(mark)o(ed)f(content,)g(and)g(ignorable)208 5081 y(whitespace.)36 b(Applications)23 b(which)h(must)g(distinguish)f (these)h(cases)h(can)f(use)h(the)f FJ(StartCdataSectionHandler)p FN(,)208 5180 y FJ(EndCdataSectionHandler)p FN(,)16 b(and)k FJ(ElementDeclHandler)d FN(callbacks)j(to)g(collect)g(the)g(required)f (information.)0 5327 y FD(UnparsedEntityDeclHandler)p FJ(\()p FK(entityName)o(,)c(base)o(,)20 b(systemId,)g(publicId,)e (notationName)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(8.5.)52 b FJ(xml.parsers.expat)20 b FI(\227)j(F)l(ast)g(XML)g(parsing)h(using)f (Expat)1493 b(267)p eop end %%Page: 268 280 TeXDict begin 268 279 bop 208 83 a FN(Called)22 b(for)g(unparsed)f (\(ND)m(A)-9 b(T)h(A\))22 b(entity)g(declarations.)30 b(This)23 b(is)h(only)d(present)h(for)g(v)o(ersion)f(1.2)h(of)g(the)h (Expat)f(library;)g(for)208 183 y(more)g(recent)h(v)o(ersions,)g(use)h FJ(EntityDeclHandler)d FN(instead.)34 b(\(The)23 b(underlying)e (function)g(in)j(the)f(Expat)g(library)f(has)208 282 y(been)d(declared)g(obsolete.\))0 429 y FD(EntityDeclHandler)p FJ(\()p FK(entityName)o(,)d(is)p 1375 429 25 4 v 31 w(par)o(ameter)p 1752 429 V 28 w(entity)-5 b(,)21 b(value)o(,)e(base)o(,)h(systemId,)g (publicId,)e(notationName)p FJ(\))208 529 y FN(Called)k(for)g(all)h (entity)f(declarations.)30 b(F)o(or)22 b(parameter)e(and)i(internal)g (entities,)h FK(value)e FN(will)j(be)e(a)g(string)g(gi)n(ving)f(the)i (declared)208 628 y(contents)h(of)g(the)h(entity;)i(this)e(will)h(be)e FJ(None)h FN(for)f(e)o(xternal)g(entities.)39 b(The)24 b FK(notationName)f FN(parameter)g(will)j(be)f FJ(None)f FN(for)208 728 y(parsed)d(entities,)h(and)g(the)g(name)f(of)h(the)g (notation)e(for)i(unparsed)e(entities.)31 b FK(is)p 2503 728 V 30 w(par)o(ameter)p 2879 728 V 28 w(entity)22 b FN(will)h(be)f(true)g(if)g(the)g(entity)208 828 y(is)29 b(a)h(parameter)d(entity)i(or)g(f)o(alse)g(for)g(general)e(entities)j (\(most)f(applications)e(only)h(need)h(to)g(be)g(concerned)e(with)i (general)208 927 y(entities\).)c(This)20 b(is)h(only)e(a)n(v)n(ailable) h(starting)g(with)g(v)o(ersion)f(1.95.0)g(of)g(the)i(Expat)e(library)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 1074 y FD(NotationDeclHandler)p FJ(\()p FK(notationName)o(,)14 b(base)o(,)20 b(systemId,)g(publicId)r FJ(\))208 1174 y FN(Called)27 b(for)f(notation)g(declarations.)44 b FK(notationName)p FN(,)27 b FK(base)p FN(,)h(and)e FK(systemId)r FN(,)j(and)e FK(publicId)g FN(are)g(strings)g(if)h(gi)n(v)o(en.)44 b(If)27 b(the)208 1273 y(public)19 b(identi\002er)g(is)j(omitted,)d FK(publicId)h FN(will)h(be)g FJ(None)p FN(.)0 1420 y FD(StartNamespaceDeclHandler)p FJ(\()p FK(pr)m(e\002x,)15 b(uri)p FJ(\))208 1520 y FN(Called)26 b(when)f(an)h(element)f(contains) h(a)g(namespace)f(declaration.)40 b(Namespace)26 b(declarations)e(are)i (processed)f(before)g(the)208 1620 y FJ(StartElementHandler)17 b FN(is)k(called)f(for)f(the)i(element)e(on)h(which)g(declarations)f (are)h(placed.)0 1766 y FD(EndNamespaceDeclHandler)p FJ(\()p FK(pr)m(e\002x)p FJ(\))208 1866 y FN(Called)44 b(when)f(the)g(closing)h(tag)f(is)i(reached)d(for)h(an)h(element)f (that)h(contained)e(a)i(namespace)f(declaration.)93 b(This)208 1966 y(is)39 b(called)f(once)g(for)g(each)g(namespace)g(declaration)e (on)j(the)f(element)g(in)h(the)f(re)n(v)o(erse)g(of)g(the)g(order)g (for)g(which)g(the)208 2065 y FJ(StartNamespaceDeclHandler)25 b FN(w)o(as)30 b(called)f(to)h(indicate)e(the)i(start)g(of)f(each)g (namespace)f(declaration')-5 b(s)28 b(scope.)208 2165 y(Calls)21 b(to)f(this)h(handler)e(are)h(made)g(after)f(the)i (corresponding)16 b FJ(EndElementHandler)i FN(for)h(the)i(end)e(of)h (the)g(element.)0 2312 y FD(CommentHandler)p FJ(\()p FK(data)p FJ(\))208 2411 y FN(Called)g(for)g(comments.)j FK(data)d FN(is)h(the)f(te)o(xt)g(of)g(the)g(comment,)f(e)o(xcluding)f (the)i(leading)f(`)p FJ(<!--)p FN(')g(and)h(trailing)g(`)p FJ(-->)p FN('.)0 2558 y FD(StartCdataSectionHandler)p FJ(\(\))208 2658 y FN(Called)29 b(at)h(the)f(start)g(of)g(a)h(CD)m(A)-9 b(T)h(A)29 b(section.)52 b(This)29 b(and)g FJ(EndCdataSectionHandler)c FN(are)k(needed)f(to)h(be)g(able)g(to)208 2758 y(identify)19 b(the)h(syntactical)g(start)g(and)g(end)g(for)f(CD)m(A)-9 b(T)h(A)21 b(sections.)0 2904 y FD(EndCdataSectionHandler)p FJ(\(\))208 3004 y FN(Called)f(at)h(the)f(end)g(of)g(a)g(CD)m(A)-9 b(T)h(A)21 b(section.)0 3151 y FD(DefaultHandler)p FJ(\()p FK(data)p FJ(\))208 3251 y FN(Called)d(for)g(an)o(y)g(characters)f(in)i (the)g(XML)f(document)f(for)g(which)h(no)g(applicable)g(handler)f(has)h (been)g(speci\002ed.)24 b(This)19 b(means)208 3350 y(characters)g(that) h(are)g(part)g(of)g(a)h(construct)e(which)g(could)h(be)g(reported,)e(b) n(ut)i(for)g(which)f(no)h(handler)f(has)h(been)g(supplied.)0 3497 y FD(DefaultHandlerExpand)p FJ(\()p FK(data)p FJ(\))208 3597 y FN(This)32 b(is)i(the)e(same)h(as)g(the)f FJ(DefaultHandler)p FN(,)h(b)n(ut)g(doesn')o(t)e(inhibit)h(e)o(xpansion)e(of)i(internal)g (entities.)62 b(The)32 b(entity)208 3696 y(reference)18 b(will)j(not)f(be)g(passed)g(to)g(the)h(def)o(ault)e(handler)-5 b(.)0 3843 y FD(NotStandaloneHandler)p FJ(\(\))208 3943 y FN(Called)20 b(if)h(the)f(XML)g(document)e(hasn')o(t)h(been)h (declared)f(as)i(being)e(a)h(standalone)f(document.)k(This)e(happens)d (when)i(there)g(is)208 4042 y(an)c(e)o(xternal)f(subset)i(or)g(a)g (reference)d(to)j(a)g(parameter)e(entity)-5 b(,)17 b(b)n(ut)f(the)h (XML)g(declaration)e(does)h(not)g(set)i(standalone)d(to)i FJ(yes)f FN(in)208 4142 y(an)i(XML)g(declaration.)23 b(If)c(this)f(handler)f(returns)h FJ(0)p FN(,)h(then)f(the)g(parser)g (will)h(thro)n(w)f(an)g FJ(XML_ERROR_NOT_STANDALONE)208 4242 y FN(error)-5 b(.)24 b(If)c(this)h(handler)d(is)j(not)f(set,)h(no) f(e)o(xception)e(is)j(raised)f(by)g(the)g(parser)g(for)f(this)i (condition.)0 4389 y FD(ExternalEntityRefHandler)p FJ(\()p FK(conte)n(xt,)15 b(base)o(,)20 b(systemId,)g(publicId)r FJ(\))208 4488 y FN(Called)f(for)g(references)e(to)j(e)o(xternal)e (entities.)25 b FK(base)18 b FN(is)j(the)e(current)f(base,)h(as)h(set)g (by)e(a)i(pre)n(vious)e(call)h(to)g FJ(SetBase\(\))p FN(.)24 b(The)208 4588 y(public)h(and)h(system)h(identi\002ers,)h FK(systemId)h FN(and)d FK(publicId)r FN(,)g(are)h(strings)f(if)h(gi)n (v)o(en;)i(if)e(the)g(public)e(identi\002er)h(is)i(not)e(gi)n(v)o(en,) 208 4687 y FK(publicId)20 b FN(will)h(be)f FJ(None)p FN(.)25 b(The)20 b FK(conte)n(xt)h FN(v)n(alue)f(is)h(opaque)d(and)i (should)f(only)h(be)g(used)g(as)h(described)d(belo)n(w)-5 b(.)208 4820 y(F)o(or)29 b(e)o(xternal)f(entities)i(to)f(be)h(parsed,)g (this)g(handler)e(must)i(be)f(implemented.)51 b(It)30 b(is)g(responsible)e(for)h(creating)g(the)g(sub-)208 4920 y(parser)17 b(using)h FJ(ExternalEntityParserCreate\()p FK(conte)n(xt)q FJ(\))p FN(,)c(initializing)k(it)h(with)f(the)h (appropriate)d(callbacks,)i(and)208 5019 y(parsing)f(the)h(entity)-5 b(.)24 b(This)18 b(handler)f(should)g(return)g(an)h(inte)o(ger;)g(if)h (it)g(returns)e FJ(0)p FN(,)i(the)f(parser)f(will)i(thro)n(w)f(an)g FJ(XML_ERROR_-)208 5119 y(EXTERNAL_ENTITY_HANDLING)e FN(error)m(,)i(otherwise)i(parsing)f(will)i(continue.)208 5252 y(If)f(this)g(handler)f(is)i(not)f(pro)o(vided,)d(e)o(xternal)i (entities)i(are)f(reported)e(by)i(the)g FJ(DefaultHandler)f FN(callback,)g(if)h(pro)o(vided.)p 0 5549 3901 4 v 0 5649 a FI(268)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 269 281 TeXDict begin 269 280 bop 0 83 a Fv(8.5.2)100 b(ExpatError)30 b(Exceptions)0 286 y FJ(ExpatError)19 b FN(e)o(xceptions)f(ha)n(v)o(e)i (a)h(number)d(of)i(interesting)f(attrib)n(utes:)0 433 y FD(code)208 532 y FN(Expat')-5 b(s)18 b(internal)g(error)g(number)f (for)i(the)f(speci\002c)i(error)-5 b(.)23 b(This)d(will)f(match)g(one)f (of)h(the)g(constants)f(de\002ned)g(in)h(the)g FJ(errors)208 632 y FN(object)g(from)g(this)i(module.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 779 y FD(lineno)208 879 y FN(Line)g(number)g(on)h(which)f(the)i(error)e(w)o(as)i(detected.)j(The) c(\002rst)h(line)f(is)h(numbered)d FJ(1)p FN(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.1.)0 1025 y FD(offset)208 1125 y FN(Character)h(of)n(fset)h(into)g(the)g(line)g(where)g(the)g(error)f (occurred.)k(The)d(\002rst)h(column)e(is)i(numbered)c FJ(0)p FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.1.)0 1410 y Fv(8.5.3)100 b(Example)0 1613 y FN(The)20 b(follo)n(wing)e (program)g(de\002nes)i(three)g(handlers)f(that)h(just)h(print)f(out)g (their)g(ar)o(guments.)236 1851 y FA(import)44 b(xml.parsers.expat)236 2034 y(#)h(3)g(handler)e(functions)236 2125 y(def)i (start_element\(name,)c(attrs\):)416 2216 y(print)j('Start)f (element:',)h(name,)g(attrs)236 2308 y(def)h(end_element\(name\):)416 2399 y(print)f('End)g(element:',)f(name)236 2490 y(def)i (char_data\(data\):)416 2582 y(print)f('Character)f(data:',)g (repr\(data\))236 2764 y(p)i(=)g(xml.parsers.expat.ParserCreate\(\))236 2947 y(p.StartElementHandler)d(=)i(start_element)236 3038 y(p.EndElementHandler)e(=)j(end_element)236 3130 y(p.CharacterDataHandler)c(=)k(char_data)236 3312 y(p.Parse\("""<?xml)d (version="1.0"?>)236 3404 y(<parent)i(id="top"><child1)e (name="paul">Text)g(goes)i(here</child1>)236 3495 y(<child2)g (name="fred">More)e(text</child2>)236 3586 y(</parent>""",)h(1\))0 3873 y FN(The)20 b(output)f(from)g(this)i(program)d(is:)236 4111 y FA(Start)44 b(element:)g(parent)g({'id':)f('top'})236 4202 y(Start)h(element:)g(child1)g({'name':)f('paul'})236 4294 y(Character)h(data:)g('Text)g(goes)g(here')236 4385 y(End)h(element:)e(child1)236 4476 y(Character)h(data:)g('\\n')236 4568 y(Start)g(element:)g(child2)g({'name':)f('fred'})236 4659 y(Character)h(data:)g('More)g(text')236 4750 y(End)h(element:)e (child2)236 4842 y(Character)h(data:)g('\\n')236 4933 y(End)h(element:)e(parent)p 0 5549 3901 4 v 0 5649 a FI(8.5.)52 b FJ(xml.parsers.expat)20 b FI(\227)j(F)l(ast)g(XML)g (parsing)h(using)f(Expat)1493 b(269)p eop end %%Page: 270 282 TeXDict begin 270 281 bop 0 83 a Fv(8.5.4)100 b(Content)29 b(Model)g(Descr)q(iptions)0 286 y FN(Content)18 b(modules)g(are)h (described)e(using)h(nested)h(tuples.)24 b(Each)18 b(tuple)h(contains)f (four)f(v)n(alues:)25 b(the)18 b(type,)h(the)f(quanti\002er)m(,)g(the)g (name,)0 386 y(and)i(a)g(tuple)g(of)g(children.)k(Children)19 b(are)h(simply)g(additional)f(content)g(module)g(descriptions.)0 532 y(The)j(v)n(alues)h(of)f(the)h(\002rst)h(tw)o(o)f(\002elds)g(are)g (constants)f(de\002ned)g(in)h(the)g FJ(model)f FN(object)h(of)f(the)h FJ(xml.parsers.expat)d FN(module.)0 632 y(These)g(constants)g(can)g(be) g(collected)f(in)i(tw)o(o)f(groups:)k(the)c(model)f(type)h(group)f(and) g(the)h(quanti\002er)f(group.)0 779 y(The)h(constants)g(in)g(the)g (model)f(type)h(group)f(are:)0 926 y FD(XML_CTYPE_ANY)208 1025 y FN(The)g(element)h(named)f(by)h(the)g(model)f(name)h(w)o(as)h (declared)e(to)h(ha)n(v)o(e)g(a)g(content)g(model)f(of)h FJ(ANY)p FN(.)0 1172 y FD(XML_CTYPE_CHOICE)208 1272 y FN(The)f(named)g(element)h(allo)n(ws)g(a)h(choice)e(from)g(a)i(number)d (of)i(options;)g(this)g(is)h(used)f(for)g(content)f(models)g(such)h(as) h FJ(\(A)50 b(|)f(B)208 1372 y(|)g(C\))p FN(.)0 1518 y FD(XML_CTYPE_EMPTY)208 1618 y FN(Elements)19 b(which)h(are)g (declared)f(to)h(be)h FJ(EMPTY)e FN(ha)n(v)o(e)h(this)h(model)e(type.)0 1765 y FD(XML_CTYPE_MIXED)0 1912 y(XML_CTYPE_NAME)0 2059 y(XML_CTYPE_SEQ)208 2158 y FN(Models)i(which)f(represent)h(a)g(series)h (of)g(models)e(which)h(follo)n(w)g(one)g(after)g(the)g(other)g(are)g (indicated)f(with)i(this)g(model)e(type.)208 2258 y(This)g(is)h(used)f (for)g(models)f(such)h(as)h FJ(\(A,)49 b(B,)h(C\))p FN(.)0 2405 y(The)20 b(constants)g(in)g(the)g(quanti\002er)f(group)g(are:)0 2552 y FD(XML_CQUANT_NONE)208 2651 y FN(No)h(modi\002er)f(is)i(gi)n(v)o (en,)e(so)h(it)h(can)f(appear)f(e)o(xactly)g(once,)h(as)h(for)e FJ(A)p FN(.)0 2798 y FD(XML_CQUANT_OPT)208 2898 y FN(The)g(model)h(is)h (optional:)j(it)d(can)f(appear)f(once)g(or)h(not)g(at)h(all,)f(as)h (for)f FJ(A?)p FN(.)0 3045 y FD(XML_CQUANT_PLUS)208 3144 y FN(The)f(model)h(must)g(occur)f(one)h(or)g(more)f(times)i(\(lik)o(e)f FJ(A+)p FN(\).)0 3291 y FD(XML_CQUANT_REP)208 3391 y FN(The)f(model)h(must)g(occur)f(zero)h(or)g(more)f(times,)h(as)h(for)f FJ(A)1897 3406 y(*)1947 3391 y FN(.)0 3676 y Fv(8.5.5)100 b(Expat)29 b(error)g(constants)0 3879 y FN(The)19 b(follo)n(wing)f (constants)g(are)i(pro)o(vided)c(in)k(the)f FJ(errors)g FN(object)g(of)g(the)g FJ(xml.parsers.expat)e FN(module.)23 b(These)c(constants)0 3978 y(are)31 b(useful)f(in)i(interpreting)d (some)h(of)h(the)g(attrib)n(utes)g(of)g(the)g FJ(ExpatError)e FN(e)o(xception)h(objects)g(raised)h(when)g(an)f(error)g(has)0 4078 y(occurred.)0 4225 y(The)20 b FJ(errors)f FN(object)h(has)h(the)f (follo)n(wing)e(attrib)n(utes:)0 4372 y FD(XML_ERROR_ASYNC_ENTITY)0 4518 y(XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY)o(_REF)208 4618 y FN(An)i(entity)g(reference)e(in)i(an)h(attrib)n(ute)e(v)n(alue)h (referred)e(to)j(an)f(e)o(xternal)f(entity)h(instead)g(of)g(an)g (internal)f(entity)-5 b(.)0 4765 y FD(XML_ERROR_BAD_CHAR_REF)208 4865 y FN(A)20 b(character)f(reference)g(referred)f(to)i(a)h(character) e(which)h(is)h(ille)o(gal)e(in)i(XML)f(\(for)f(e)o(xample,)g(character) g FJ(0)p FN(,)h(or)g(`)p FJ(&#0;)p FN('\).)0 5011 y FD (XML_ERROR_BINARY_ENTITY_REF)208 5111 y FN(An)g(entity)g(reference)e (referred)h(to)h(an)g(entity)g(which)g(w)o(as)h(declared)e(with)h(a)h (notation,)d(so)j(cannot)e(be)h(parsed.)0 5258 y FD (XML_ERROR_DUPLICATE_ATTRIBUTE)208 5358 y FN(An)g(attrib)n(ute)g(w)o (as)h(used)f(more)f(than)h(once)f(in)h(a)h(start)g(tag.)p 0 5549 3901 4 v 0 5649 a FI(270)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 271 283 TeXDict begin 271 282 bop 0 83 a FD(XML_ERROR_INCORRECT_ENCODING)0 230 y(XML_ERROR_INVALID_TOKEN)208 330 y FN(Raised)21 b(when)g(an)g(input)f(byte)h(could)f(not)h(properly)e(be)i(assigned)f (to)i(a)f(character;)g(for)f(e)o(xample,)g(a)h(NUL)h(byte)e(\(v)n(alue) g FJ(0)p FN(\))h(in)208 429 y(a)f(UTF-8)g(input)f(stream.)0 576 y FD(XML_ERROR_JUNK_AFTER_DOC_ELEMENT)208 676 y FN(Something)f (other)h(than)h(whitespace)g(occurred)e(after)i(the)g(document)e (element.)0 823 y FD(XML_ERROR_MISPLACED_XML_PI)208 922 y FN(An)i(XML)g(declaration)f(w)o(as)i(found)d(some)n(where)h(other)g (than)h(the)g(start)h(of)f(the)g(input)f(data.)0 1069 y FD(XML_ERROR_NO_ELEMENTS)208 1169 y FN(The)g(document)g(contains)g (no)h(elements)g(\(XML)g(requires)f(all)i(documents)d(to)i(contain)g(e) o(xactly)f(one)g(top-le)n(v)o(el)g(element\)..)0 1316 y FD(XML_ERROR_NO_MEMORY)208 1415 y FN(Expat)g(w)o(as)i(not)f(able)g (to)g(allocate)g(memory)f(internally)-5 b(.)0 1562 y FD(XML_ERROR_PARAM_ENTITY_REF)208 1662 y FN(A)20 b(parameter)f(entity)h (reference)e(w)o(as)j(found)e(where)g(it)i(w)o(as)g(not)f(allo)n(wed.)0 1808 y FD(XML_ERROR_PARTIAL_CHAR)208 1908 y FN(An)g(incomplete)e (character)h(w)o(as)i(found)e(in)h(the)g(input.)0 2055 y FD(XML_ERROR_RECURSIVE_ENTITY_REF)208 2155 y FN(An)i(entity)g (reference)f(contained)f(another)h(reference)g(to)h(the)g(same)h (entity;)g(possibly)f(via)g(a)h(dif)n(ferent)d(name,)i(and)g(possibly) 208 2254 y(indirectly)-5 b(.)0 2401 y FD(XML_ERROR_SYNTAX)208 2501 y FN(Some)19 b(unspeci\002ed)g(syntax)h(error)f(w)o(as)i (encountered.)0 2648 y FD(XML_ERROR_TAG_MISMATCH)208 2747 y FN(An)f(end)f(tag)i(did)e(not)h(match)g(the)g(innermost)f(open)g (start)i(tag.)0 2894 y FD(XML_ERROR_UNCLOSED_TOKEN)208 2994 y FN(Some)e(tok)o(en)h(\(such)f(as)i(a)g(start)g(tag\))f(w)o(as)h (not)e(closed)h(before)f(the)h(end)g(of)g(the)g(stream)g(or)g(the)g(ne) o(xt)g(tok)o(en)f(w)o(as)i(encountered.)0 3141 y FD (XML_ERROR_UNDEFINED_ENTITY)208 3240 y FN(A)f(reference)f(w)o(as)i (made)e(to)i(a)f(entity)g(which)g(w)o(as)h(not)f(de\002ned.)0 3387 y FD(XML_ERROR_UNKNOWN_ENCODING)208 3487 y FN(The)f(document)g (encoding)f(is)j(not)f(supported)e(by)i(Expat.)0 3634 y FD(XML_ERROR_UNCLOSED_CDATA_SECTION)208 3733 y FN(A)g(CD)m(A)-9 b(T)h(A)21 b(mark)o(ed)e(section)h(w)o(as)h(not)e(closed.)0 3880 y FD(XML_ERROR_EXTERNAL_ENTITY_HANDLING)0 4027 y (XML_ERROR_NOT_STANDALONE)208 4127 y FN(The)31 b(parser)h(determined)e (that)i(the)g(document)e(w)o(as)i(not)g(\223standalone\224)e(though)g (it)j(declared)e(itself)h(to)h(be)e(in)i(the)f(XML)208 4226 y(declaration,)18 b(and)i(the)g FJ(NotStandaloneHandler)d FN(w)o(as)k(set)g(and)e(returned)g FJ(0)p FN(.)0 4373 y FD(XML_ERROR_UNEXPECTED_STATE)0 4520 y (XML_ERROR_ENTITY_DECLARED_IN_PE)0 4667 y (XML_ERROR_FEATURE_REQUIRES_XML_DTD)208 4766 y FN(An)27 b(operation)e(w)o(as)j(requested)e(that)i(requires)e(DTD)h(support)f (to)i(be)f(compiled)f(in,)j(b)n(ut)e(Expat)f(w)o(as)i(con\002gured)d (without)208 4866 y(DTD)20 b(support.)j(This)e(should)e(ne)n(v)o(er)g (be)h(reported)e(by)i(a)h(standard)e(b)n(uild)h(of)f(the)i FJ(xml.parsers.expat)c FN(module.)0 5013 y FD (XML_ERROR_CANT_CHANGE_FEATURE_ONCE_)o(PARSIN)o(G)208 5113 y FN(A)27 b(beha)n(vioral)d(change)i(w)o(as)h(requested)e(after)h (parsing)g(started)g(that)h(can)f(only)g(be)g(changed)f(before)g (parsing)g(has)i(started.)208 5212 y(This)20 b(is)h(\(currently\))d (only)h(raised)h(by)g FJ(UseForeignDTD\(\))p FN(.)0 5359 y FD(XML_ERROR_UNBOUND_PREFIX)p 0 5549 3901 4 v 0 5649 a FI(8.5.)52 b FJ(xml.parsers.expat)20 b FI(\227)j(F)l(ast)g(XML)g (parsing)h(using)f(Expat)1493 b(271)p eop end %%Page: 272 284 TeXDict begin 272 283 bop 208 83 a FN(An)20 b(undeclared)e(pre\002x)h (w)o(as)i(found)e(when)g(namespace)g(processing)g(w)o(as)i(enabled.)0 230 y FD(XML_ERROR_UNDECLARING_PREFIX)208 330 y FN(The)e(document)g (attempted)g(to)h(remo)o(v)o(e)e(the)j(namespace)e(declaration)f (associated)i(with)h(a)f(pre\002x.)0 476 y FD(XML_ERROR_INCOMPLETE_PE) 208 576 y FN(A)g(parameter)f(entity)h(contained)e(incomplete)h(markup.) 0 723 y FD(XML_ERROR_XML_DECL)208 823 y FN(The)g(document)g(contained)f (no)i(document)e(element)i(at)g(all.)0 969 y FD(XML_ERROR_TEXT_DECL)208 1069 y FN(There)f(w)o(as)i(an)f(error)f(parsing)g(a)i(te)o(xt)f (declaration)f(in)h(an)g(e)o(xternal)f(entity)-5 b(.)0 1216 y FD(XML_ERROR_PUBLICID)208 1316 y FN(Characters)19 b(were)h(found)f(in)h(the)g(public)g(id)g(that)g(are)g(not)g(allo)n (wed.)0 1462 y FD(XML_ERROR_SUSPENDED)208 1562 y FN(The)i(requested)f (operation)g(w)o(as)j(made)e(on)g(a)h(suspended)e(parser)m(,)h(b)n(ut)h (isn')o(t)g(allo)n(wed.)31 b(This)23 b(includes)f(attempts)h(to)g(pro)o (vide)208 1662 y(additional)18 b(input)i(or)g(to)g(stop)g(the)g(parser) -5 b(.)0 1808 y FD(XML_ERROR_NOT_SUSPENDED)208 1908 y FN(An)20 b(attempt)g(to)g(resume)f(the)i(parser)e(w)o(as)i(made)f(when) f(the)i(parser)e(had)h(not)g(been)f(suspended.)0 2055 y FD(XML_ERROR_ABORTED)208 2155 y FN(This)h(should)f(not)h(be)g (reported)e(to)j(Python)e(applications.)0 2301 y FD(XML_ERROR_FINISHED) 208 2401 y FN(The)e(requested)f(operation)g(w)o(as)i(made)f(on)g(a)h (parser)f(which)g(w)o(as)h(\002nished)f(parsing)f(input,)i(b)n(ut)f (isn')o(t)g(allo)n(wed.)24 b(This)17 b(includes)208 2501 y(attempts)j(to)g(pro)o(vide)e(additional)h(input)g(or)h(to)h(stop)f (the)g(parser)-5 b(.)0 2648 y FD(XML_ERROR_SUSPEND_PE)0 2975 y FE(8.6)121 b Fx(xml.dom)31 b FE(\227)i(The)h(Document)h(Object)f (Model)g(API)0 3208 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 3355 y(The)i(Document)f(Object)i(Model,)f(or)g(\223DOM,)-6 b(\224)21 b(is)i(a)f(cross-language)d(API)j(from)e(the)i(W)-7 b(orld)21 b(W)m(ide)h(W)-7 b(eb)22 b(Consortium)f(\(W3C\))g(for)0 3454 y(accessing)i(and)g(modifying)e(XML)j(documents.)33 b(A)24 b(DOM)f(implementation)f(presents)h(an)g(XML)h(document)d(as)j (a)g(tree)g(structure,)0 3554 y(or)18 b(allo)n(ws)g(client)h(code)e(to) h(b)n(uild)g(such)g(a)h(structure)e(from)g(scratch.)24 b(It)18 b(then)g(gi)n(v)o(es)g(access)h(to)f(the)g(structure)f(through) f(a)j(set)g(of)f(objects)0 3654 y(which)i(pro)o(vided)d(well-kno)n(wn)i (interf)o(aces.)0 3800 y(The)e(DOM)h(is)h(e)o(xtremely)d(useful)h(for)g (random-access)e(applications.)23 b(SAX)18 b(only)f(allo)n(ws)h(you)f (a)h(vie)n(w)f(of)h(one)f(bit)h(of)f(the)h(document)0 3900 y(at)i(a)f(time.)25 b(If)19 b(you)f(are)i(looking)d(at)j(one)e (SAX)i(element,)f(you)f(ha)n(v)o(e)h(no)f(access)i(to)g(another)-5 b(.)23 b(If)c(you)f(are)i(looking)d(at)j(a)f(te)o(xt)g(node,)f(you)0 4000 y(ha)n(v)o(e)h(no)g(access)h(to)f(a)h(containing)d(element.)24 b(When)c(you)e(write)h(a)h(SAX)g(application,)e(you)g(need)h(to)h(k)o (eep)e(track)h(of)g(your)f(program')-5 b(s)0 4099 y(position)21 b(in)i(the)f(document)e(some)n(where)g(in)j(your)e(o)n(wn)g(code.)30 b(SAX)23 b(does)f(not)f(do)h(it)h(for)e(you.)30 b(Also,)23 b(if)f(you)f(need)h(to)g(look)f(ahead)0 4199 y(in)f(the)h(XML)f (document,)e(you)h(are)h(just)h(out)f(of)g(luck.)0 4346 y(Some)g(applications)e(are)i(simply)g(impossible)f(in)h(an)g(e)n(v)o (ent)f(dri)n(v)o(en)f(model)h(with)h(no)g(access)g(to)h(a)f(tree.)25 b(Of)20 b(course)f(you)g(could)g(b)n(uild)0 4445 y(some)h(sort)f(of)h (tree)g(yourself)e(in)i(SAX)g(e)n(v)o(ents,)f(b)n(ut)h(the)f(DOM)h (allo)n(ws)g(you)f(to)h(a)n(v)n(oid)g(writing)f(that)g(code.)25 b(The)19 b(DOM)h(is)h(a)f(standard)0 4545 y(tree)g(representation)e (for)i(XML)g(data.)0 4692 y(The)27 b(Document)e(Object)i(Model)g(is)h (being)e(de\002ned)g(by)h(the)g(W3C)h(in)f(stages,)i(or)e(\223le)n(v)o (els\224)g(in)g(their)g(terminology)-5 b(.)43 b(The)27 b(Python)0 4792 y(mapping)20 b(of)i(the)g(API)h(is)g(substantially)e (based)h(on)g(the)g(DOM)h(Le)n(v)o(el)e(2)h(recommendation.)28 b(The)22 b(mapping)e(of)i(the)g(Le)n(v)o(el)f(3)i(speci-)0 4891 y(\002cation,)e(currently)f(only)h(a)n(v)n(ailable)g(in)g(draft)g (form,)g(is)h(being)f(de)n(v)o(eloped)e(by)i(the)g(Python)f(XML)i (Special)f(Interest)h(Group)e(as)i(part)0 4991 y(of)e(the)g(PyXML)g (package.)k(Refer)c(to)h(the)f(documentation)e(b)n(undled)g(with)j (that)f(package)f(for)h(information)e(on)h(the)i(current)e(state)i(of)0 5090 y(DOM)f(Le)n(v)o(el)g(3)g(support.)0 5237 y(DOM)j(applications)f (typically)g(start)i(by)e(parsing)g(some)h(XML)g(into)g(a)g(DOM.)g(Ho)n (w)g(this)h(is)g(accomplished)d(is)j(not)f(co)o(v)o(ered)d(at)k(all)0 5337 y(by)e(DOM)g(Le)n(v)o(el)f(1,)h(and)g(Le)n(v)o(el)f(2)h(pro)o (vides)e(only)h(limited)h(impro)o(v)o(ements:)k(There)21 b(is)i(a)g FJ(DOMImplementation)c FN(object)j(class)p 0 5549 3901 4 v 0 5649 a FI(272)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 273 285 TeXDict begin 273 284 bop 0 83 a FN(which)17 b(pro)o(vides)e(access)j (to)f FJ(Document)g FN(creation)f(methods,)g(b)n(ut)i(no)e(w)o(ay)i(to) f(access)h(an)f(XML)g(reader/parser/Document)c(b)n(uilder)0 183 y(in)19 b(an)f(implementation-independen)o(t)13 b(w)o(ay)-5 b(.)24 b(There)18 b(is)h(also)g(no)f(well-de\002ned)f(w)o(ay)h(to)h (access)g(these)f(methods)f(without)h(an)g(e)o(xisting)0 282 y FJ(Document)k FN(object.)34 b(In)23 b(Python,)g(each)f(DOM)i (implementation)d(will)j(pro)o(vide)d(a)j(function)d FJ(getDOMImplementation\(\))p FN(.)0 382 y(DOM)g(Le)n(v)o(el)g(3)g (adds)g(a)h(Load/Store)e(speci\002cation,)g(which)h(de\002nes)g(an)g (interf)o(ace)f(to)h(the)h(reader)m(,)e(b)n(ut)h(this)g(is)i(not)d(yet) i(a)n(v)n(ailable)e(in)0 482 y(the)g(Python)f(standard)g(library)-5 b(.)0 628 y(Once)22 b(you)f(ha)n(v)o(e)g(a)h(DOM)h(document)d(object,)h (you)g(can)h(access)h(the)f(parts)g(of)f(your)g(XML)h(document)e (through)g(its)j(properties)d(and)0 728 y(methods.)38 b(These)25 b(properties)e(are)i(de\002ned)f(in)h(the)g(DOM)h (speci\002cation;)g(this)g(portion)d(of)i(the)g(reference)e(manual)h (describes)h(the)0 828 y(interpretation)18 b(of)i(the)g (speci\002cation)g(in)g(Python.)0 975 y(The)27 b(speci\002cation)f(pro) o(vided)f(by)i(the)g(W3C)h(de\002nes)f(the)g(DOM)h(API)g(for)e(Ja)n(v)n (a,)j(ECMAScript,)g(and)d(OMG)i(IDL.)f(The)g(Python)0 1074 y(mapping)j(de\002ned)i(here)g(is)h(based)f(in)g(lar)o(ge)g(part)g (on)f(the)i(IDL)f(v)o(ersion)f(of)h(the)g(speci\002cation,)j(b)n(ut)d (strict)h(compliance)e(is)i(not)0 1174 y(required)16 b(\(though)g(implementations)g(are)i(free)g(to)g(support)e(the)i (strict)h(mapping)d(from)h(IDL\).)g(See)i(section)f(8.6.3,)e (\223Conformance,)-6 b(\224)0 1273 y(for)20 b(a)g(detailed)g (discussion)f(of)h(mapping)f(requirements.)0 1420 y FL(See)i(Also:)0 1567 y FK(Document)e(Object)h(Model)g(\(DOM\))g(Le)o(vel)g(2)h (Speci\002cation)0 1667 y Fy(\()p FO(http://www)l(.w3.org/TR/DOM-Le)m (v)n(el-2)o(-Core)o(/)-6 b Fy(\))208 1766 y FN(The)19 b(W3C)i(recommendation)c(upon)i(which)h(the)g(Python)f(DOM)h(API)h(is)g (based.)0 1913 y FK(Document)e(Object)h(Model)g(\(DOM\))g(Le)o(vel)g(1) h(Speci\002cation)0 2013 y Fy(\()p FO(http://www)l (.w3.org/TR/REC-DOM-Le)m(v)n(el-)o(1/)-6 b Fy(\))208 2113 y FN(The)19 b(W3C)i(recommendation)c(for)j(the)g(DOM)g(supported)f (by)g FJ(xml.dom.minidom)p FN(.)0 2259 y FK(PyXML)0 2359 y Fy(\()p FO(http://p)n(yxml.sourcef)n(orge)o(.ne)o(t)-6 b Fy(\))208 2459 y FN(Users)20 b(that)h(require)e(a)h(full-featured)e (implementation)g(of)i(DOM)g(should)f(use)i(the)f(PyXML)g(package.)0 2606 y FK(Python)f(Langua)o(g)o(e)f(Mapping)h(Speci\002cation)0 2705 y Fy(\()p FO(http://www)l(.omg.org/docs/f)n(o)o(r)r(mal/)o(02)o (-11)o(-05)o(.pd)o(f)-6 b Fy(\))208 2805 y FN(This)20 b(speci\002es)h(the)f(mapping)e(from)h(OMG)i(IDL)f(to)g(Python.)0 3090 y Fv(8.6.1)100 b(Module)30 b(Contents)0 3293 y FN(The)20 b FJ(xml.dom)f FN(contains)h(the)g(follo)n(wing)f(functions:)0 3439 y FD(registerDOMImplementation)p FJ(\()p FK(name)o(,)c(factory)p FJ(\))208 3539 y FN(Re)o(gister)24 b(the)g FK(factory)h FN(function)d(with)j(the)f(name)g FK(name)p FN(.)37 b(The)24 b(f)o(actory)g(function)e(should)i(return)f(an)h(object)g(which)g (imple-)208 3639 y(ments)e(the)g FJ(DOMImplementation)e FN(interf)o(ace.)30 b(The)22 b(f)o(actory)f(function)f(can)i(return)f (the)i(same)f(object)g(e)n(v)o(ery)f(time,)h(or)g(a)208 3738 y(ne)n(w)d(one)g(for)g(each)g(call,)g(as)i(appropriate)c(for)i (the)g(speci\002c)h(implementation)d(\(e.g.)24 b(if)c(that)f (implementation)e(supports)i(some)208 3838 y(customization\).)0 3985 y FD(getDOMImplementation)p FJ(\()p FC([)p FK(name)p FC([)p FK(,)c(featur)m(es)d FC(])g(])p FJ(\))208 4084 y FN(Return)j(a)i(suitable)f(DOM)h(implementation.)k(The)16 b FK(name)g FN(is)h(either)f(well-kno)n(wn,)e(the)j(module)e(name)g(of) h(a)h(DOM)f(implemen-)208 4184 y(tation,)25 b(or)f FJ(None)p FN(.)39 b(If)25 b(it)g(is)h(not)f FJ(None)p FN(,)g(imports)f(the)h (corresponding)c(module)j(and)g(returns)g(a)h FJ(DOMImplementation)208 4284 y FN(object)c(if)i(the)f(import)g(succeeds.)31 b(If)22 b(no)g(name)f(is)j(gi)n(v)o(en,)d(and)h(if)g(the)h(en)m(vironment)c(v)n (ariable)i(PYTHON)p 3324 4284 25 4 v 30 w(DOM)h(is)i(set,)f(this)208 4383 y(v)n(ariable)c(is)i(used)f(to)g(\002nd)g(the)g(implementation.) 208 4516 y(If)k(name)g(is)i(not)f(gi)n(v)o(en,)f(this)i(e)o(xamines)d (the)i(a)n(v)n(ailable)g(implementations)d(to)j(\002nd)g(one)f(with)h (the)g(required)e(feature)h(set.)40 b(If)208 4616 y(no)23 b(implementation)e(can)j(be)f(found,)g(raise)h(an)g FJ(ImportError)p FN(.)34 b(The)23 b(features)g(list)i(must)f(be)f(a)h(sequence)f(of)g FJ(\()p FK(featur)m(e)p FJ(,)208 4715 y FK(ver)o(sion)p FJ(\))17 b FN(pairs)h(which)f(are)g(passed)h(to)f(the)h FJ(hasFeature\(\))e FN(method)g(on)h(a)n(v)n(ailable)g FJ(DOMImplementation)e FN(objects.)0 4862 y(Some)20 b(con)m(v)o (enience)d(constants)j(are)g(also)g(pro)o(vided:)0 5009 y FD(EMPTY_NAMESPACE)208 5109 y FN(The)26 b(v)n(alue)h(used)f(to)h (indicate)g(that)g(no)g(namespace)e(is)j(associated)f(with)g(a)h(node)e (in)h(the)g(DOM.)g(This)g(is)h(typically)e(found)208 5208 y(as)d(the)g FJ(namespaceURI)e FN(of)i(a)g(node,)f(or)h(used)f(as) i(the)f FK(namespaceURI)h FN(parameter)e(to)h(a)g (namespaces-speci\002c)e(method.)208 5308 y(Ne)n(w)f(in)g(v)o(ersion)f (2.2.)p 0 5549 3901 4 v 0 5649 a FI(8.6.)52 b FJ(xml.dom)22 b FI(\227)h(The)g(Document)h(Object)f(Model)h(API)1881 b(273)p eop end %%Page: 274 286 TeXDict begin 274 285 bop 0 83 a FD(XML_NAMESPACE)208 183 y FN(The)25 b(namespace)g(URI)i(associated)e(with)i(the)f(reserv)o (ed)e(pre\002x)i FJ(xml)p FN(,)h(as)g(de\002ned)e(by)g FK(Namespaces)h(in)g(XML)h FN(\(section)e(4\).)208 282 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 429 y FD(XMLNS_NAMESPACE)208 529 y FN(The)24 b(namespace)f(URI)i(for)e(namespace)g(declarations,)h (as)h(de\002ned)f(by)g FK(Document)f(Object)h(Model)g(\(DOM\))g(Le)o (vel)h(2)f(Cor)m(e)208 628 y(Speci\002cation)17 b FN(\(section)j (1.1.8\).)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 775 y FD(XHTML_NAMESPACE)208 875 y FN(The)24 b(URI)h(of)f(the)h(XHTML)f (namespace)f(as)i(de\002ned)f(by)g FK(XHTML)h(1.0:)33 b(The)24 b(Extensible)g(HyperT)-8 b(e)n(xt)26 b(Markup)e(Langua)o(g)o (e)208 975 y FN(\(section)19 b(3.1.1\).)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 1121 y(In)28 b(addition,)h FJ(xml.dom)e FN(contains)h(a)g(base)h FJ(Node)f FN(class)h(and)f(the)g (DOM)g(e)o(xception)f(classes.)50 b(The)28 b FJ(Node)g FN(class)h(pro)o(vided)d(by)0 1221 y(this)f(module)e(does)i(not)f (implement)f(an)o(y)h(of)h(the)f(methods)g(or)g(attrib)n(utes)h (de\002ned)e(by)h(the)h(DOM)g(speci\002cation;)h(concrete)d(DOM)0 1321 y(implementations)18 b(must)h(pro)o(vide)f(those.)25 b(The)19 b FJ(Node)g FN(class)i(pro)o(vided)c(as)k(part)e(of)g(this)i (module)d(does)h(pro)o(vide)f(the)i(constants)f(used)0 1420 y(for)e(the)g FJ(nodeType)g FN(attrib)n(ute)g(on)g(concrete)f FJ(Node)h FN(objects;)i(the)o(y)d(are)i(located)f(within)g(the)g(class) i(rather)d(than)h(at)h(the)g(module)e(le)n(v)o(el)0 1520 y(to)k(conform)e(with)j(the)f(DOM)g(speci\002cations.)0 1804 y Fv(8.6.2)100 b(Objects)28 b(in)g(the)g(DOM)0 2007 y FN(The)20 b(de\002niti)n(v)o(e)f(documentation)e(for)j(the)g(DOM)g (is)i(the)e(DOM)g(speci\002cation)g(from)f(the)h(W3C.)0 2154 y(Note)f(that)h(DOM)f(attrib)n(utes)g(may)g(also)h(be)f (manipulated)e(as)k(nodes)d(instead)h(of)g(as)h(simple)f(strings.)25 b(It)20 b(is)g(f)o(airly)f(rare)g(that)g(you)g(must)0 2253 y(do)h(this,)g(ho)n(we)n(v)o(er)m(,)e(so)i(this)h(usage)f(is)h (not)f(yet)g(documented.)106 2473 y FL(Interface)p 1201 2503 4 100 v 822 w(Section)p 1559 2503 V 99 w(Pur)o(pose)p 57 2507 3787 4 v 106 2576 a FJ(DOMImplementation)p 1201 2606 4 100 v 296 w FN(8.6.2)p 1559 2606 V 190 w(Interf)o(ace)f(to)h (the)h(underlying)c(implementation.)106 2676 y FJ(Node)p 1201 2706 V 946 w FN(8.6.2)p 1559 2706 V 190 w(Base)k(interf)o(ace)f (for)f(most)h(objects)g(in)h(a)f(document.)106 2776 y FJ(NodeList)p 1201 2806 V 746 w FN(8.6.2)p 1559 2806 V 190 w(Interf)o(ace)f(for)h(a)g(sequence)f(of)h(nodes.)106 2875 y FJ(DocumentType)p 1201 2905 V 546 w FN(8.6.2)p 1559 2905 V 190 w(Information)d(about)j(the)g(declarations)f(needed)g (to)h(process)g(a)g(document.)106 2975 y FJ(Document)p 1201 3005 V 746 w FN(8.6.2)p 1559 3005 V 190 w(Object)g(which)g (represents)f(an)h(entire)g(document.)106 3075 y FJ(Element)p 1201 3104 V 796 w FN(8.6.2)p 1559 3104 V 190 w(Element)g(nodes)f(in)h (the)h(document)d(hierarchy)-5 b(.)106 3174 y FJ(Attr)p 1201 3204 V 946 w FN(8.6.2)p 1559 3204 V 190 w(Attrib)n(ute)20 b(v)n(alue)f(nodes)h(on)g(element)f(nodes.)106 3274 y FJ(Comment)p 1201 3304 V 796 w FN(8.6.2)p 1559 3304 V 190 w(Representation)g(of)h(comments)f(in)h(the)g(source)g(document.) 106 3373 y FJ(Text)p 1201 3403 V 946 w FN(8.6.2)p 1559 3403 V 190 w(Nodes)g(containing)e(te)o(xtual)i(content)f(from)g(the)h (document.)106 3473 y FJ(ProcessingInstruction)p 1201 3503 V 96 w FN(8.6.2)p 1559 3503 V 190 w(Processing)g(instruction)e (representation.)0 3692 y(An)i(additional)f(section)h(describes)g(the)g (e)o(xceptions)e(de\002ned)i(for)f(w)o(orking)g(with)h(the)g(DOM)h(in)f (Python.)0 3959 y FI(DOMImplementation)25 b(Objects)0 4162 y FN(The)32 b FJ(DOMImplementation)d FN(interf)o(ace)i(pro)o (vides)f(a)i(w)o(ay)g(for)g(applications)e(to)i(determine)f(the)h(a)n (v)n(ailability)f(of)h(particular)0 4262 y(features)20 b(in)h(the)f(DOM)h(the)o(y)f(are)g(using.)26 b(DOM)21 b(Le)n(v)o(el)e(2)i(added)e(the)i(ability)f(to)h(create)f(ne)n(w)h FJ(Document)e FN(and)h FJ(DocumentType)0 4362 y FN(objects)g(using)g (the)g FJ(DOMImplementation)d FN(as)k(well.)0 4509 y FD(hasFeature)p FJ(\()p FK(featur)m(e)o(,)d(ver)o(sion)p FJ(\))208 4608 y FN(Return)h(true)h(if)h(the)f(feature)f(identi\002ed)g (by)h(the)g(pair)g(of)g(strings)g FK(featur)m(e)g FN(and)g FK(ver)o(sion)g FN(is)h(implemented.)0 4755 y FD(createDocument)p FJ(\()p FK(namespaceUri,)16 b(quali\002edName)o(,)i(doctype)p FJ(\))208 4855 y FN(Return)48 b(a)h(ne)n(w)f FJ(Document)g FN(object)g(\(the)h(root)f(of)g(the)h(DOM\),)f(with)h(a)g(child)g FJ(Element)f FN(object)g(ha)n(ving)g(the)208 4954 y(gi)n(v)o(en)c FK(namespaceUri)h FN(and)g FK(quali\002edName)p FN(.)100 b(The)46 b FK(doctype)f FN(must)h(be)g(a)g FJ(DocumentType)e FN(object)i(created)f(by)208 5054 y FJ(createDocumentType\(\))p FN(,)17 b(or)j FJ(None)p FN(.)25 b(In)c(the)f(Python)g(DOM)g(API,)h (the)f(\002rst)h(tw)o(o)g(ar)o(guments)e(can)h(also)h(be)f FJ(None)g FN(in)208 5154 y(order)e(to)j(indicate)e(that)i(no)e FJ(Element)h FN(child)g(is)h(to)f(be)g(created.)0 5300 y FD(createDocumentType)p FJ(\()p FK(quali\002edName)o(,)14 b(publicId,)19 b(systemId)r FJ(\))208 5400 y FN(Return)35 b(a)i(ne)n(w)f FJ(DocumentType)f FN(object)h(that)g(encapsulates)g(the) g(gi)n(v)o(en)f FK(quali\002edName)p FN(,)j FK(publicId)r FN(,)h(and)d FK(systemId)p 0 5549 3901 4 v 0 5649 a FI(274)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T) -10 b(ools)p eop end %%Page: 275 287 TeXDict begin 275 286 bop 208 83 a FN(strings,)19 b(representing)g(the) h(information)e(contained)g(in)i(an)h(XML)f(document)e(type)i (declaration.)0 351 y FI(Node)j(Objects)0 554 y FN(All)e(of)f(the)g (components)e(of)i(an)g(XML)g(document)e(are)j(subclasses)f(of)g FJ(Node)p FN(.)0 701 y FD(nodeType)208 801 y FN(An)h(inte)o(ger)f (representing)g(the)h(node)f(type.)28 b(Symbolic)20 b(constants)h(for)g (the)h(types)f(are)g(on)g(the)g FJ(Node)h FN(object:)27 b FJ(ELEMENT_-)208 900 y(NODE)p FN(,)39 b FJ(ATTRIBUTE_NODE)p FN(,)e FJ(TEXT_NODE)p FN(,)i FJ(CDATA_SECTION_NODE)p FN(,)d FJ(ENTITY_NODE)p FN(,)i FJ(PROCESSING_-)208 1000 y(INSTRUCTION_NODE)p FN(,)h FJ(COMMENT_NODE)p FN(,)i FJ(DOCUMENT_NODE)p FN(,)f FJ(DOCUMENT_TYPE_NODE)p FN(,)g FJ(NOTATION_-)208 1100 y(NODE)p FN(.)19 b(This)i(is)g(a)f(read-only)e (attrib)n(ute.)0 1246 y FD(parentNode)208 1346 y FN(The)k(parent)f(of)i (the)f(current)f(node,)h(or)h FJ(None)f FN(for)g(the)g(document)f (node.)31 b(The)22 b(v)n(alue)g(is)h(al)o(w)o(ays)g(a)g FJ(Node)g FN(object)f(or)g FJ(None)p FN(.)208 1446 y(F)o(or)h FJ(Element)h FN(nodes,)g(this)h(will)g(be)f(the)g(parent)f(element,)i (e)o(xcept)e(for)h(the)g(root)f(element,)i(in)f(which)g(case)g(it)h (will)g(be)g(the)208 1545 y FJ(Document)19 b FN(object.)24 b(F)o(or)c FJ(Attr)g FN(nodes,)f(this)i(is)g(al)o(w)o(ays)g FJ(None)p FN(.)j(This)d(is)g(a)g(read-only)c(attrib)n(ute.)0 1692 y FD(attributes)208 1792 y FN(A)26 b FJ(NamedNodeMap)f FN(of)g(attrib)n(ute)h(objects.)43 b(Only)25 b(elements)h(ha)n(v)o(e)g (actual)g(v)n(alues)f(for)h(this;)k(others)25 b(pro)o(vide)f FJ(None)i FN(for)208 1891 y(this)20 b(attrib)n(ute.)25 b(This)20 b(is)h(a)g(read-only)d(attrib)n(ute.)0 2038 y FD(previousSibling)208 2138 y FN(The)25 b(node)f(that)i(immediately)e (precedes)g(this)i(one)f(with)h(the)g(same)f(parent.)40 b(F)o(or)25 b(instance)g(the)h(element)f(with)h(an)f(end-tag)208 2238 y(that)e(comes)h(just)g(before)e(the)i FK(self)36 b FN(element')-5 b(s)24 b(start-tag.)34 b(Of)24 b(course,)g(XML)f (documents)f(are)i(made)f(up)g(of)g(more)g(than)g(just)208 2337 y(elements)18 b(so)h(the)g(pre)n(vious)f(sibling)g(could)g(be)h (te)o(xt,)f(a)i(comment,)d(or)i(something)e(else.)25 b(If)19 b(this)g(node)f(is)i(the)f(\002rst)g(child)g(of)g(the)208 2437 y(parent,)g(this)h(attrib)n(ute)g(will)h(be)f FJ(None)p FN(.)25 b(This)20 b(is)h(a)g(read-only)d(attrib)n(ute.)0 2584 y FD(nextSibling)208 2683 y FN(The)i(node)g(that)g(immediately)g (follo)n(ws)g(this)h(one)g(with)f(the)h(same)g(parent.)26 b(See)21 b(also)g FJ(previousSibling)p FN(.)j(If)d(this)g(is)h(the)208 2783 y(last)f(child)e(of)h(the)h(parent,)e(this)h(attrib)n(ute)g(will)h (be)f FJ(None)p FN(.)25 b(This)20 b(is)h(a)g(read-only)d(attrib)n(ute.) 0 2930 y FD(childNodes)208 3029 y FN(A)i(list)i(of)d(nodes)h(contained) e(within)i(this)h(node.)j(This)c(is)h(a)g(read-only)d(attrib)n(ute.)0 3176 y FD(firstChild)208 3276 y FN(The)h(\002rst)i(child)f(of)g(the)g (node,)f(if)i(there)e(are)h(an)o(y)-5 b(,)19 b(or)h FJ(None)p FN(.)25 b(This)20 b(is)h(a)g(read-only)d(attrib)n(ute.)0 3423 y FD(lastChild)208 3522 y FN(The)h(last)i(child)f(of)g(the)g (node,)f(if)i(there)e(are)i(an)o(y)-5 b(,)18 b(or)i FJ(None)p FN(.)25 b(This)20 b(is)i(a)e(read-only)e(attrib)n(ute.)0 3669 y FD(localName)208 3769 y FN(The)h(part)h(of)g(the)g FJ(tagName)g FN(follo)n(wing)e(the)j(colon)e(if)h(there)g(is)h(one,)f (else)g(the)h(entire)e FJ(tagName)p FN(.)25 b(The)19 b(v)n(alue)h(is)h(a)g(string.)0 3916 y FD(prefix)208 4015 y FN(The)k(part)g(of)g(the)g FJ(tagName)g FN(preceding)e(the)i (colon)g(if)h(there)e(is)j(one,)f(else)g(the)f(empty)g(string.)40 b(The)25 b(v)n(alue)g(is)h(a)g(string,)g(or)208 4115 y FJ(None)0 4262 y FD(namespaceURI)208 4362 y FN(The)19 b(namespace)g(associated)h(with)h(the)f(element)g(name.)k(This)c(will)h (be)f(a)h(string)f(or)g FJ(None)p FN(.)k(This)d(is)g(a)g(read-only)c (attrib)n(ute.)0 4508 y FD(nodeName)208 4608 y FN(This)k(has)g(a)g(dif) n(ferent)e(meaning)h(for)g(each)h(node)f(type;)h(see)g(the)g(DOM)g (speci\002cation)f(for)h(details.)27 b(Y)-9 b(ou)20 b(can)h(al)o(w)o (ays)h(get)f(the)208 4708 y(information)15 b(you)j(w)o(ould)f(get)h (here)g(from)f(another)g(property)f(such)i(as)h(the)f FJ(tagName)f FN(property)f(for)i(elements)g(or)g(the)g FJ(name)208 4807 y FN(property)j(for)i(attrib)n(utes.)36 b(F)o(or)23 b(all)i(node)e(types,)h(the)g(v)n(alue)f(of)g(this)i (attrib)n(ute)e(will)i(be)e(either)h(a)g(string)f(or)h FJ(None)p FN(.)35 b(This)24 b(is)h(a)208 4907 y(read-only)17 b(attrib)n(ute.)0 5054 y FD(nodeValue)208 5153 y FN(This)k(has)g(a)g (dif)n(ferent)f(meaning)f(for)i(each)f(node)g(type;)h(see)h(the)f(DOM)g (speci\002cation)f(for)h(details.)27 b(The)21 b(situation)f(is)i (similar)208 5253 y(to)e(that)g(with)h FJ(nodeName)p FN(.)j(The)19 b(v)n(alue)h(is)h(a)g(string)f(or)f FJ(None)p FN(.)0 5400 y FD(hasAttributes)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(8.6.)52 b FJ(xml.dom)22 b FI(\227)h(The)g(Document)h (Object)f(Model)h(API)1881 b(275)p eop end %%Page: 276 288 TeXDict begin 276 287 bop 208 83 a FN(Returns)20 b(true)f(if)i(the)f (node)f(has)i(an)o(y)e(attrib)n(utes.)0 230 y FD(hasChildNodes)p FJ(\(\))208 330 y FN(Returns)h(true)f(if)i(the)f(node)f(has)i(an)o(y)e (child)h(nodes.)0 476 y FD(isSameNode)p FJ(\()p FK(other)r FJ(\))208 576 y FN(Returns)j(true)f(if)i FK(other)h FN(refers)d(to)h (the)h(same)f(node)f(as)i(this)f(node.)33 b(This)23 b(is)h(especially)f (useful)g(for)f(DOM)i(implementations)208 676 y(which)19 b(use)i(an)o(y)e(sort)h(of)g(proxy)f(architecture)f(\(because)h(more)h (than)g(one)f(object)h(can)g(refer)f(to)i(the)f(same)g(node\).)208 808 y FL(Note:)46 b FN(This)32 b(is)g(based)f(on)g(a)h(proposed)d(DOM)i (Le)n(v)o(el)g(3)g(API)h(which)f(is)h(still)h(in)e(the)h(\223w)o (orking)d(draft\224)i(stage,)j(b)n(ut)d(this)208 908 y(particular)22 b(interf)o(ace)g(appears)h(uncontro)o(v)o(ersial.)31 b(Changes)23 b(from)f(the)i(W3C)g(will)g(not)g(necessarily)e(af)n(fect) h(this)h(method)e(in)208 1008 y(the)e(Python)f(DOM)h(interf)o(ace)g (\(though)e(an)o(y)h(ne)n(w)h(W3C)h(API)g(for)e(this)i(w)o(ould)e(also) i(be)f(supported\).)0 1155 y FD(appendChild)p FJ(\()p FK(ne)o(wChild)r FJ(\))208 1254 y FN(Add)f(a)i(ne)n(w)f(child)g(node)f (to)h(this)h(node)e(at)i(the)f(end)g(of)g(the)g(list)h(of)f(children,)e (returning)h FK(ne)o(wChild)r FN(.)0 1401 y FD(insertBefore)p FJ(\()p FK(ne)o(wChild,)e(r)m(efChild)r FJ(\))208 1501 y FN(Insert)27 b(a)h(ne)n(w)g(child)f(node)g(before)f(an)i(e)o(xisting) e(child.)48 b(It)28 b(must)f(be)h(the)g(case)g(that)g FK(r)m(efChild)i FN(is)f(a)f(child)f(of)h(this)g(node;)i(if)208 1600 y(not,)25 b FJ(ValueError)e FN(is)i(raised.)38 b FK(ne)o(wChild)26 b FN(is)g(returned.)36 b(If)24 b FK(r)m(efChild)j FN(is)e FJ(None)p FN(,)h(it)f(inserts)g FK(ne)o(wChild)h FN(at)f(the)f(end)g(of)h(the)208 1700 y(children')-5 b(s)19 b(list.)0 1847 y FD(removeChild)p FJ(\()p FK(oldChild)r FJ(\))208 1946 y FN(Remo)o(v)o(e)c(a)j(child)e(node.)23 b FK(oldChild)18 b FN(must)f(be)g(a)h(child)e(of)h(this)g(node;)h(if)f (not,)g FJ(ValueError)e FN(is)j(raised.)24 b FK(oldChild)18 b FN(is)g(returned)208 2046 y(on)h(success.)26 b(If)20 b FK(oldChild)i FN(will)e(not)g(be)g(used)g(further)m(,)e(its)k FJ(unlink\(\))d FN(method)g(should)g(be)h(called.)0 2193 y FD(replaceChild)p FJ(\()p FK(ne)o(wChild,)d(oldChild)r FJ(\))208 2293 y FN(Replace)28 b(an)g(e)o(xisting)f(node)h(with)g(a)h (ne)n(w)f(node.)48 b(It)28 b(must)h(be)f(the)g(case)h(that)f FK(oldChild)i FN(is)f(a)g(child)f(of)g(this)g(node;)k(if)c(not,)208 2392 y FJ(ValueError)18 b FN(is)k(raised.)0 2539 y FD(normalize)p FJ(\(\))208 2639 y FN(Join)c(adjacent)g(te)o(xt)h(nodes)f(so)h(that)g (all)g(stretches)g(of)f(te)o(xt)h(are)f(stored)g(as)i(single)e FJ(Text)h FN(instances.)24 b(This)19 b(simpli\002es)g(process-)208 2738 y(ing)g(te)o(xt)h(from)g(a)g(DOM)h(tree)f(for)f(man)o(y)g (applications.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 2885 y FD(cloneNode)p FJ(\()p FK(deep)p FJ(\))208 2985 y FN(Clone)h(this)g(node.)k(Setting)c FK(deep)g FN(means)g(to)g(clone)g (all)g(child)g(nodes)g(as)h(well.)k(This)20 b(returns)g(the)g(clone.)0 3253 y FI(NodeList)k(Objects)0 3456 y FN(A)29 b FJ(NodeList)e FN(represents)g(a)h(sequence)f(of)h(nodes.)48 b(These)28 b(objects)g(are)g(used)f(in)i(tw)o(o)f(w)o(ays)g(in)h(the)f(DOM)g(Core) g(recommen-)0 3556 y(dation:)40 b(the)28 b FJ(Element)f FN(objects)h(pro)o(vides)e(one)i(as)h(its)g(list)g(of)f(child)f(nodes,) i(and)f(the)g FJ(getElementsByTagName\(\))c FN(and)0 3655 y FJ(getElementsByTagNameNS\(\))16 b FN(methods)j(of)h FJ(Node)g FN(return)f(objects)h(with)h(this)f(interf)o(ace)g(to)g (represent)f(query)g(results.)0 3802 y(The)h(DOM)g(Le)n(v)o(el)g(2)g (recommendation)d(de\002nes)j(one)f(method)g(and)h(one)f(attrib)n(ute)h (for)g(these)g(objects:)0 3949 y FD(item)p FJ(\()p FK(i)p FJ(\))208 4049 y FN(Return)g(the)h FK(i)p FN(')o(th)f(item)i(from)e (the)h(sequence,)e(if)j(there)e(is)i(one,)f(or)f FJ(None)p FN(.)27 b(The)21 b(inde)o(x)f FK(i)i FN(is)f(not)g(allo)n(wed)f(to)i (be)f(less)h(then)e(zero)208 4148 y(or)f(greater)h(than)f(or)h(equal)g (to)g(the)g(length)g(of)g(the)g(sequence.)0 4295 y FD(length)208 4395 y FN(The)f(number)g(of)h(nodes)f(in)h(the)h(sequence.)0 4542 y(In)f(addition,)g(the)g(Python)g(DOM)h(interf)o(ace)e(requires)h (that)h(some)f(additional)g(support)f(is)j(pro)o(vided)c(to)i(allo)n(w) h FJ(NodeList)f FN(objects)0 4641 y(to)29 b(be)g(used)g(as)g(Python)f (sequences.)51 b(All)29 b FJ(NodeList)f FN(implementations)f(must)i (include)f(support)g(for)g FJ(__len__\(\))g FN(and)g FJ(_-)0 4741 y(_getitem__\(\))p FN(;)i(this)e(allo)n(ws)f(iteration)g (o)o(v)o(er)f(the)i FJ(NodeList)f FN(in)g FJ(for)h FN(statements)g(and) e(proper)g(support)g(for)h(the)h FJ(len\(\))0 4841 y FN(b)n(uilt-in)20 b(function.)0 4987 y(If)h(a)h(DOM)g(implementation)d (supports)h(modi\002cation)g(of)h(the)g(document,)f(the)h FJ(NodeList)g FN(implementation)e(must)i(also)h(support)0 5087 y(the)e FJ(__setitem__\(\))f FN(and)g FJ(__delitem__\(\))f FN(methods.)p 0 5549 3901 4 v 0 5649 a FI(276)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 277 289 TeXDict begin 277 288 bop 0 83 a FI(DocumentT)-10 b(ype)23 b(Objects)0 286 y FN(Information)17 b(about)i(the)g(notations)g(and)g (entities)h(declared)f(by)g(a)h(document)e(\(including)f(the)j(e)o (xternal)e(subset)i(if)g(the)g(parser)f(uses)h(it)0 386 y(and)h(can)g(pro)o(vide)e(the)i(information\))d(is)k(a)n(v)n(ailable)f (from)f(a)i FJ(DocumentType)d FN(object.)27 b(The)21 b FJ(DocumentType)e FN(for)i(a)h(document)0 485 y(is)h(a)n(v)n(ailable) f(from)f(the)h FJ(Document)f FN(object')-5 b(s)22 b FJ(doctype)f FN(attrib)n(ute;)i(if)f(there)g(is)h(no)e FJ(DOCTYPE)h FN(declaration)e(for)i(the)g(document,)0 585 y(the)e(document')-5 b(s)19 b FJ(doctype)g FN(attrib)n(ute)h(will)h(be)f(set)h(to)f FJ(None)g FN(instead)g(of)g(an)g(instance)g(of)g(this)h(interf)o(ace.)0 732 y FJ(DocumentType)e FN(is)i(a)f(specialization)g(of)f FJ(Node)p FN(,)h(and)g(adds)g(the)g(follo)n(wing)f(attrib)n(utes:)0 879 y FD(publicId)208 978 y FN(The)g(public)h(identi\002er)f(for)h(the) g(e)o(xternal)f(subset)h(of)g(the)g(document)f(type)g(de\002nition.)24 b(This)c(will)h(be)g(a)f(string)g(or)g FJ(None)p FN(.)0 1125 y FD(systemId)208 1225 y FN(The)h(system)h(identi\002er)g(for)f (the)h(e)o(xternal)f(subset)h(of)g(the)g(document)e(type)i (de\002nition.)29 b(This)22 b(will)h(be)f(a)g(URI)h(as)f(a)h(string,)f (or)208 1324 y FJ(None)p FN(.)0 1471 y FD(internalSubset)208 1571 y FN(A)31 b(string)f(gi)n(ving)f(the)i(complete)e(internal)h (subset)h(from)f(the)g(document.)54 b(This)31 b(does)g(not)f(include)f (the)i(brack)o(ets)f(which)208 1670 y(enclose)19 b(the)h(subset.)26 b(If)20 b(the)g(document)e(has)i(no)g(internal)g(subset,)g(this)g (should)g(be)g FJ(None)p FN(.)0 1817 y FD(name)208 1917 y FN(The)f(name)h(of)g(the)g(root)g(element)f(as)i(gi)n(v)o(en)e(in)h (the)h FJ(DOCTYPE)e FN(declaration,)f(if)j(present.)0 2064 y FD(entities)208 2163 y FN(This)f(is)i(a)f FJ(NamedNodeMap)e FN(gi)n(ving)h(the)g(de\002nitions)g(of)g(e)o(xternal)g(entities.)27 b(F)o(or)20 b(entity)g(names)h(de\002ned)e(more)h(than)g(once,)208 2263 y(only)g(the)h(\002rst)g(de\002nition)f(is)i(pro)o(vided)c (\(others)i(are)h(ignored)e(as)j(required)d(by)h(the)h(XML)g (recommendation\).)i(This)e(may)g(be)208 2363 y FJ(None)f FN(if)g(the)g(information)e(is)j(not)f(pro)o(vided)e(by)h(the)i(parser) m(,)e(or)h(if)g(no)g(entities)g(are)h(de\002ned.)0 2510 y FD(notations)208 2609 y FN(This)e(is)g(a)h FJ(NamedNodeMap)d FN(gi)n(ving)g(the)i(de\002nitions)f(of)h(notations.)k(F)o(or)c (notation)e(names)i(de\002ned)f(more)g(than)g(once,)g(only)208 2709 y(the)f(\002rst)i(de\002nition)e(is)h(pro)o(vided)e(\(others)h (are)g(ignored)g(as)h(required)e(by)i(the)f(XML)h(recommendation\).)j (This)d(may)f(be)h FJ(None)208 2808 y FN(if)i(the)g(information)e(is)j (not)f(pro)o(vided)e(by)h(the)i(parser)m(,)e(or)h(if)g(no)g(notations)f (are)h(de\002ned.)0 3077 y FI(Document)j(Objects)0 3280 y FN(A)g FJ(Document)e FN(represents)g(an)h(entire)g(XML)g(document,)e (including)g(its)j(constituent)e(elements,)h(attrib)n(utes,)h (processing)d(instruc-)0 3379 y(tions,)g(comments)f(etc.)25 b(Remeber)20 b(that)g(it)h(inherits)f(properties)f(from)g FJ(Node)p FN(.)0 3526 y FD(documentElement)208 3626 y FN(The)g(one)h(and)g(only)f(root)h(element)f(of)h(the)g(document.)0 3773 y FD(createElement)p FJ(\()p FK(ta)o(gName)p FJ(\))208 3872 y FN(Create)k(and)f(return)g(a)h(ne)n(w)g(element)f(node.)35 b(The)24 b(element)f(is)i(not)e(inserted)h(into)f(the)h(document)e (when)h(it)i(is)g(created.)35 b(Y)-9 b(ou)208 3972 y(need)19 b(to)h(e)o(xplicitly)g(insert)g(it)h(with)f(one)g(of)g(the)g(other)f (methods)g(such)h(as)h FJ(insertBefore\(\))d FN(or)i FJ(appendChild\(\))p FN(.)0 4119 y FD(createElementNS)p FJ(\()p FK(namespaceURI,)15 b(ta)o(gName)p FJ(\))208 4218 y FN(Create)31 b(and)f(return)g(a)i(ne)n(w)f(element)f(with)h(a)h (namespace.)56 b(The)31 b FK(ta)o(gName)f FN(may)h(ha)n(v)o(e)f(a)i (pre\002x.)57 b(The)30 b(element)h(is)h(not)208 4318 y(inserted)18 b(into)g(the)h(document)d(when)i(it)h(is)h(created.)k(Y) -9 b(ou)18 b(need)g(to)g(e)o(xplicitly)g(insert)g(it)i(with)f(one)f(of) g(the)h(other)e(methods)h(such)208 4418 y(as)i FJ(insertBefore\(\))f FN(or)h FJ(appendChild\(\))p FN(.)0 4564 y FD(createTextNode)p FJ(\()p FK(data)p FJ(\))208 4664 y FN(Create)e(and)g(return)g(a)h(te)o (xt)f(node)f(containing)g(the)i(data)f(passed)g(as)i(a)f(parameter)-5 b(.)23 b(As)c(with)g(the)f(other)g(creation)g(methods,)f(this)208 4764 y(one)i(does)h(not)g(insert)g(the)g(node)g(into)g(the)g(tree.)0 4911 y FD(createComment)p FJ(\()p FK(data)p FJ(\))208 5010 y FN(Create)c(and)f(return)g(a)h(comment)e(node)h(containing)f (the)i(data)g(passed)f(as)i(a)f(parameter)-5 b(.)23 b(As)16 b(with)g(the)g(other)f(creation)g(methods,)208 5110 y(this)20 b(one)g(does)g(not)g(insert)g(the)g(node)f(into)h(the)g(tree.)0 5257 y FD(createProcessingInstruction)p FJ(\()p FK(tar)m(g)o(et,)15 b(data)p FJ(\))208 5356 y FN(Create)25 b(and)f(return)f(a)i(processing) f(instruction)f(node)h(containing)f(the)h FK(tar)m(g)o(et)j FN(and)d FK(data)g FN(passed)g(as)i(parameters.)37 b(As)25 b(with)p 0 5549 3901 4 v 0 5649 a FI(8.6.)52 b FJ(xml.dom)22 b FI(\227)h(The)g(Document)h(Object)f(Model)h(API)1881 b(277)p eop end %%Page: 278 290 TeXDict begin 278 289 bop 208 83 a FN(the)20 b(other)f(creation)g (methods,)g(this)i(one)f(does)f(not)h(insert)h(the)f(node)f(into)h(the) g(tree.)0 230 y FD(createAttribute)p FJ(\()p FK(name)p FJ(\))208 330 y FN(Create)32 b(and)f(return)f(an)i(attrib)n(ute)f (node.)59 b(This)32 b(method)e(does)i(not)f(associate)h(the)g(attrib)n (ute)f(node)g(with)h(an)o(y)f(particular)208 429 y(element.)23 b(Y)-9 b(ou)18 b(must)h(use)g FJ(setAttributeNode\(\))d FN(on)i(the)h(appropriate)d FJ(Element)i FN(object)g(to)h(use)g(the)f (ne)n(wly)g(created)208 529 y(attrib)n(ute)h(instance.)0 676 y FD(createAttributeNS)p FJ(\()p FK(namespaceURI,)14 b(quali\002edName)p FJ(\))208 775 y FN(Create)29 b(and)f(return)g(an)h (attrib)n(ute)g(node)f(with)h(a)g(namespace.)51 b(The)28 b FK(ta)o(gName)h FN(may)f(ha)n(v)o(e)h(a)g(pre\002x.)51 b(This)29 b(method)f(does)208 875 y(not)e(associate)g(the)g(attrib)n (ute)g(node)g(with)g(an)o(y)g(particular)f(element.)42 b(Y)-9 b(ou)26 b(must)h(use)f FJ(setAttributeNode\(\))e FN(on)i(the)208 975 y(appropriate)17 b FJ(Element)j FN(object)f(to)i (use)f(the)g(ne)n(wly)g(created)f(attrib)n(ute)h(instance.)0 1121 y FD(getElementsByTagName)p FJ(\()p FK(ta)o(gName)p FJ(\))208 1221 y FN(Search)f(for)h(all)h(descendants)d(\(direct)i (children,)e(children')-5 b(s)20 b(children,)e(etc.\))25 b(with)c(a)f(particular)f(element)h(type)f(name.)0 1368 y FD(getElementsByTagNameNS)p FJ(\()p FK(namespaceUR)o(I,)14 b(localName)p FJ(\))208 1468 y FN(Search)30 b(for)h(all)h(descendants)e (\(direct)h(children,)i(children')-5 b(s)30 b(children,)j(etc.\))58 b(with)32 b(a)g(particular)e(namespace)g(URI)i(and)208 1567 y(localname.)23 b(The)d(localname)f(is)i(the)f(part)g(of)g(the)g (namespace)f(after)h(the)g(pre\002x.)0 1835 y FI(Element)25 b(Objects)0 2038 y FJ(Element)19 b FN(is)j(a)e(subclass)h(of)f FJ(Node)p FN(,)f(so)i(inherits)f(all)g(the)h(attrib)n(utes)f(of)g(that) g(class.)0 2185 y FD(tagName)208 2285 y FN(The)f(element)h(type)g (name.)k(In)c(a)h(namespace-using)c(document)h(it)j(may)f(ha)n(v)o(e)g (colons)f(in)h(it.)26 b(The)20 b(v)n(alue)f(is)j(a)e(string.)0 2432 y FD(getElementsByTagName)p FJ(\()p FK(ta)o(gName)p FJ(\))208 2531 y FN(Same)g(as)h(equi)n(v)n(alent)d(method)h(in)h(the)h FJ(Document)e FN(class.)0 2678 y FD(getElementsByTagNameNS)p FJ(\()p FK(ta)o(gName)p FJ(\))208 2778 y FN(Same)h(as)h(equi)n(v)n (alent)d(method)h(in)h(the)h FJ(Document)e FN(class.)0 2925 y FD(hasAttribute)p FJ(\()p FK(name)p FJ(\))208 3024 y FN(Returns)h(true)f(if)i(the)f(element)g(has)g(an)g(attrib)n (ute)g(named)f(by)h FK(name)p FN(.)0 3171 y FD(hasAttributeNS)p FJ(\()p FK(namespaceURI,)15 b(localName)p FJ(\))208 3271 y FN(Returns)20 b(true)f(if)i(the)f(element)g(has)g(an)g(attrib)n(ute)g (named)f(by)h FK(namespaceURI)i FN(and)e FK(localName)p FN(.)0 3418 y FD(getAttribute)p FJ(\()p FK(name)p FJ(\))208 3517 y FN(Return)29 b(the)h(v)n(alue)f(of)h(the)g(attrib)n(ute)f(named) g(by)h FK(name)f FN(as)i(a)f(string.)54 b(If)30 b(no)f(such)h(attrib)n (ute)g(e)o(xists,)i(an)e(empty)f(string)h(is)208 3617 y(returned,)18 b(as)j(if)f(the)g(attrib)n(ute)g(had)g(no)g(v)n(alue.)0 3764 y FD(getAttributeNode)p FJ(\()p FK(attrname)p FJ(\))208 3863 y FN(Return)f(the)i FJ(Attr)f FN(node)f(for)g(the)h(attrib)n(ute)g (named)f(by)h FK(attrname)p FN(.)0 4010 y FD(getAttributeNS)p FJ(\()p FK(namespaceURI,)15 b(localName)p FJ(\))208 4110 y FN(Return)j(the)h(v)n(alue)f(of)h(the)g(attrib)n(ute)f(named)g(by)g FK(namespaceURI)j FN(and)e FK(localName)f FN(as)h(a)h(string.)k(If)19 b(no)f(such)h(attrib)n(ute)f(e)o(xists,)208 4210 y(an)i(empty)f(string) h(is)h(returned,)d(as)j(if)g(the)f(attrib)n(ute)g(had)f(no)h(v)n(alue.) 0 4356 y FD(getAttributeNodeNS)p FJ(\()p FK(namespaceURI,)14 b(localName)p FJ(\))208 4456 y FN(Return)19 b(an)h(attrib)n(ute)g(v)n (alue)g(as)h(a)f(node,)f(gi)n(v)o(en)g(a)i FK(namespaceURI)h FN(and)d FK(localName)p FN(.)0 4603 y FD(removeAttribute)p FJ(\()p FK(name)p FJ(\))208 4703 y FN(Remo)o(v)o(e)g(an)h(attrib)n(ute) f(by)h(name.)25 b(No)20 b(e)o(xception)e(is)j(raised)f(if)h(there)e(is) j(no)d(matching)g(attrib)n(ute.)0 4849 y FD(removeAttributeNode)p FJ(\()p FK(oldAttr)r FJ(\))208 4949 y FN(Remo)o(v)o(e)f(and)i(return)f FK(oldAttr)i FN(from)e(the)h(attrib)n(ute)g(list,)h(if)f(present.)k(If) c FK(oldAttr)i FN(is)f(not)e(present,)h FJ(NotFoundErr)e FN(is)j(raised.)0 5096 y FD(removeAttributeNS)p FJ(\()p FK(namespaceURI,)14 b(localName)p FJ(\))208 5196 y FN(Remo)o(v)o(e)20 b(an)h(attrib)n(ute)g(by)f(name.)28 b(Note)21 b(that)g(it)h(uses)g(a)g (localName,)e(not)h(a)h(qname.)27 b(No)21 b(e)o(xception)e(is)j(raised) g(if)f(there)g(is)h(no)208 5295 y(matching)c(attrib)n(ute.)p 0 5549 3901 4 v 0 5649 a FI(278)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 279 291 TeXDict begin 279 290 bop 0 83 a FD(setAttribute)p FJ(\()p FK(name)o(,)17 b(value)p FJ(\))208 183 y FN(Set)j(an)h(attrib)n(ute)e (v)n(alue)h(from)f(a)i(string.)0 330 y FD(setAttributeNode)p FJ(\()p FK(ne)o(wAttr)r FJ(\))208 429 y FN(Add)32 b(a)h(ne)n(w)f (attrib)n(ute)g(node)g(to)g(the)h(element,)i(replacing)c(an)h(e)o (xisting)g(attrib)n(ute)g(if)h(necessary)f(if)h(the)g FJ(name)f FN(attrib)n(ute)208 529 y(matches.)72 b(If)36 b(a)g(replacement)f(occurs,)k(the)d(old)g(attrib)n(ute)f(node)g(will)i (be)f(returned.)71 b(If)36 b FK(ne)o(wAttr)i FN(is)f(already)e(in)i (use,)208 628 y FJ(InuseAttributeErr)17 b FN(will)k(be)f(raised.)0 775 y FD(setAttributeNodeNS)p FJ(\()p FK(ne)o(wAttr)r FJ(\))208 875 y FN(Add)d(a)i(ne)n(w)g(attrib)n(ute)f(node)f(to)i(the)f (element,)g(replacing)f(an)h(e)o(xisting)g(attrib)n(ute)g(if)h (necessary)e(if)i(the)f FJ(namespaceURI)f FN(and)208 975 y FJ(localName)24 b FN(attrib)n(utes)i(match.)41 b(If)26 b(a)g(replacement)e(occurs,)i(the)g(old)f(attrib)n(ute)g(node)g (will)i(be)e(returned.)40 b(If)26 b FK(ne)o(wAttr)i FN(is)208 1074 y(already)19 b(in)h(use,)g FJ(InuseAttributeErr)e FN(will)j(be)f(raised.)0 1221 y FD(setAttributeNS)p FJ(\()p FK(namespaceURI,)15 b(qname)o(,)k(value)p FJ(\))208 1321 y FN(Set)31 b(an)f(attrib)n(ute)g(v)n(alue)f(from)h(a)g(string,)j(gi)n (v)o(en)c(a)i FK(namespaceURI)h FN(and)e(a)g FK(qname)p FN(.)55 b(Note)30 b(that)g(a)h(qname)e(is)j(the)e(whole)208 1420 y(attrib)n(ute)19 b(name.)25 b(This)20 b(is)h(dif)n(ferent)e(than) g(abo)o(v)o(e.)0 1681 y FI(Attr)k(Objects)0 1884 y FJ(Attr)d FN(inherits)g(from)f FJ(Node)p FN(,)h(so)g(inherits)g(all)h(its)g (attrib)n(utes.)0 2031 y FD(name)208 2131 y FN(The)e(attrib)n(ute)h (name.)25 b(In)19 b(a)i(namespace-using)d(document)g(it)j(may)e(ha)n(v) o(e)h(colons)g(in)g(it.)0 2278 y FD(localName)208 2377 y FN(The)f(part)h(of)g(the)g(name)g(follo)n(wing)f(the)h(colon)f(if)h (there)g(is)h(one,)f(else)h(the)f(entire)g(name.)k(This)c(is)h(a)g (read-only)d(attrib)n(ute.)0 2524 y FD(prefix)208 2624 y FN(The)h(part)h(of)g(the)g(name)g(preceding)e(the)i(colon)g(if)g (there)g(is)h(one,)e(else)i(the)f(empty)g(string.)0 2885 y FI(NamedNodeMap)25 b(Objects)0 3088 y FJ(NamedNodeMap)19 b FN(does)g FK(not)h FN(inherit)g(from)f FJ(Node)p FN(.)0 3235 y FD(length)208 3334 y FN(The)g(length)h(of)g(the)g(attrib)n(ute)g (list.)0 3481 y FD(item)p FJ(\()p FK(inde)n(x)p FJ(\))208 3581 y FN(Return)g(an)h(attrib)n(ute)g(with)g(a)h(particular)d(inde)o (x.)27 b(The)20 b(order)g(you)g(get)h(the)g(attrib)n(utes)g(in)h(is)g (arbitrary)d(b)n(ut)i(will)h(be)f(consistent)208 3680 y(for)e(the)h(life)h(of)f(a)g(DOM.)g(Each)g(item)h(is)g(an)f(attrib)n (ute)g(node.)j(Get)e(its)g(v)n(alue)f(with)g(the)g FJ(value)g FN(attrib)n(ute.)0 3827 y(There)e(are)h(also)h(e)o(xperimental)d (methods)h(that)h(gi)n(v)o(e)f(this)i(class)g(more)e(mapping)f(beha)n (vior)-5 b(.)24 b(Y)-9 b(ou)18 b(can)h(use)h(them)e(or)h(you)f(can)h (use)h(the)0 3927 y(standardized)e FJ(getAttribute)1040 3942 y(*)1090 3927 y(\(\))g FN(f)o(amily)i(of)g(methods)f(on)h(the)g FJ(Element)f FN(objects.)0 4188 y FI(Comment)24 b(Objects)0 4391 y FJ(Comment)19 b FN(represents)h(a)g(comment)f(in)h(the)h(XML)f (document.)j(It)d(is)h(a)g(subclass)g(of)e FJ(Node)p FN(,)h(b)n(ut)g(cannot)g(ha)n(v)o(e)f(child)h(nodes.)0 4538 y FD(data)208 4637 y FN(The)26 b(content)g(of)g(the)h(comment)e (as)i(a)h(string.)44 b(The)26 b(attrib)n(ute)g(contains)g(all)i (characters)d(between)h(the)h(leading)f FJ(<!--)g FN(and)208 4737 y(trailing)19 b FJ(-->)p FN(,)h(b)n(ut)g(does)g(not)g(include)f (them.)0 4998 y FI(T)-10 b(e)n(xt)22 b(and)i(CD)m(A)-10 b(T)g(ASection)24 b(Objects)0 5201 y FN(The)18 b FJ(Text)g FN(interf)o(ace)g(represents)g(te)o(xt)g(in)h(the)f(XML)h(document.)j (If)c(the)h(parser)f(and)f(DOM)i(implementation)d(support)h(the)i(DOM') -5 b(s)0 5300 y(XML)29 b(e)o(xtension,)i(portions)d(of)h(the)g(te)o(xt) h(enclosed)e(in)i(CD)m(A)-9 b(T)h(A)30 b(mark)o(ed)e(sections)h(are)h (stored)f(in)g FJ(CDATASection)f FN(objects.)0 5400 y(These)20 b(tw)o(o)g(interf)o(aces)g(are)g(identical,)g(b)n(ut)g(pro)o(vide)e (dif)n(ferent)h(v)n(alues)g(for)h(the)g FJ(nodeType)f FN(attrib)n(ute.)p 0 5549 3901 4 v 0 5649 a FI(8.6.)52 b FJ(xml.dom)22 b FI(\227)h(The)g(Document)h(Object)f(Model)h(API)1881 b(279)p eop end %%Page: 280 292 TeXDict begin 280 291 bop 0 83 a FN(These)20 b(interf)o(aces)g(e)o (xtend)e(the)j FJ(Node)f FN(interf)o(ace.)k(The)o(y)19 b(cannot)g(ha)n(v)o(e)h(child)f(nodes.)0 230 y FD(data)208 330 y FN(The)g(content)h(of)f(the)i(te)o(xt)f(node)f(as)i(a)f(string.)0 476 y FL(Note:)40 b FN(The)28 b(use)h(of)e(a)i FJ(CDATASection)d FN(node)i(does)g(not)f(indicate)h(that)g(the)g(node)f(represents)h(a)g (complete)f(CD)m(A)-9 b(T)h(A)29 b(mark)o(ed)0 576 y(section,)21 b(only)g(that)g(the)h(content)e(of)h(the)g(node)g(w)o(as)h(part)f(of)g (a)h(CD)m(A)-9 b(T)h(A)21 b(section.)28 b(A)22 b(single)f(CD)m(A)-9 b(T)h(A)22 b(section)f(may)g(be)g(represented)0 676 y(by)i(more)g(than) h(one)f(node)g(in)h(the)g(document)e(tree.)36 b(There)23 b(is)h(no)g(w)o(ay)g(to)g(determine)e(whether)h(tw)o(o)h(adjacent)f FJ(CDATASection)0 775 y FN(nodes)c(represent)g(dif)n(ferent)g(CD)m(A)-9 b(T)h(A)20 b(mark)o(ed)f(sections.)0 1044 y FI(ProcessingInstr)q (uction)k(Objects)0 1246 y FN(Represents)17 b(a)h(processing)e (instruction)g(in)i(the)f(XML)g(document;)g(this)h(inherits)f(from)f (the)h FJ(Node)h FN(interf)o(ace)e(and)h(cannot)f(ha)n(v)o(e)h(child)0 1346 y(nodes.)0 1493 y FD(target)208 1593 y FN(The)i(content)h(of)f (the)i(processing)e(instruction)f(up)i(to)h(the)f(\002rst)h(whitespace) e(character)-5 b(.)24 b(This)d(is)g(a)g(read-only)c(attrib)n(ute.)0 1739 y FD(data)208 1839 y FN(The)i(content)h(of)f(the)i(processing)e (instruction)f(follo)n(wing)h(the)h(\002rst)h(whitespace)f(character)-5 b(.)0 2107 y FI(Exceptions)0 2310 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.1.)0 2457 y(The)29 b(DOM)g(Le)n(v)o(el)f(2)h(recommendation)d (de\002nes)j(a)g(single)g(e)o(xception,)g FJ(DOMException)p FN(,)g(and)g(a)g(number)e(of)i(constants)f(that)0 2557 y(allo)n(w)c(applications)f(to)h(determine)f(what)h(sort)h(of)e(error)g (occurred.)35 b FJ(DOMException)23 b FN(instances)h(carry)f(a)i FJ(code)f FN(attrib)n(ute)f(that)0 2656 y(pro)o(vides)18 b(the)j(appropriate)c(v)n(alue)j(for)g(the)g(speci\002c)g(e)o (xception.)0 2803 y(The)h(Python)g(DOM)h(interf)o(ace)f(pro)o(vides)e (the)j(constants,)f(b)n(ut)h(also)g(e)o(xpands)e(the)i(set)g(of)g(e)o (xceptions)e(so)i(that)g(a)g(speci\002c)f(e)o(xception)0 2903 y(e)o(xists)j(for)e(each)h(of)g(the)g(e)o(xception)f(codes)h (de\002ned)f(by)h(the)g(DOM.)g(The)g(implementations)e(must)j(raise)f (the)g(appropriate)e(speci\002c)0 3003 y(e)o(xception,)d(each)i(of)g (which)f(carries)h(the)h(appropriate)d(v)n(alue)h(for)h(the)g FJ(code)g FN(attrib)n(ute.)0 3149 y FL(exception)f FD(DOMException)208 3249 y FN(Base)h(e)o(xception)e(class)i(used)f(for)g(all)h(speci\002c)g (DOM)g(e)o(xceptions.)j(This)d(e)o(xception)d(class)k(cannot)d(be)i (directly)e(instantiated.)0 3396 y FL(exception)h FD(DomstringSizeErr) 208 3496 y FN(Raised)g(when)f(a)h(speci\002ed)g(range)f(of)g(te)o(xt)h (does)f(not)h(\002t)g(into)g(a)g(string.)24 b(This)19 b(is)h(not)e(kno)n(wn)g(to)h(be)f(used)h(in)g(the)g(Python)e(DOM)208 3595 y(implementations,)h(b)n(ut)i(may)f(be)i(recei)n(v)o(ed)d(from)h (DOM)i(implementations)d(not)i(written)g(in)g(Python.)0 3742 y FL(exception)f FD(HierarchyRequestErr)208 3842 y FN(Raised)h(when)g(an)g(attempt)g(is)h(made)f(to)g(insert)g(a)h(node) e(where)g(the)i(node)e(type)h(is)h(not)f(allo)n(wed.)0 3989 y FL(exception)f FD(IndexSizeErr)208 4088 y FN(Raised)h(when)g(an) g(inde)o(x)f(or)h(size)h(parameter)d(to)j(a)f(method)f(is)i(ne)o(gati)n (v)o(e)d(or)i(e)o(xceeds)g(the)g(allo)n(wed)f(v)n(alues.)0 4235 y FL(exception)g FD(InuseAttributeErr)208 4335 y FN(Raised)h(when)g(an)g(attempt)g(is)h(made)f(to)g(insert)g(an)g FJ(Attr)g FN(node)f(that)i(is)g(already)e(present)g(else)n(where)h(in)g (the)h(document.)0 4482 y FL(exception)e FD(InvalidAccessErr)208 4581 y FN(Raised)h(if)h(a)f(parameter)f(or)h(an)g(operation)e(is)k(not) d(supported)g(on)g(the)i(underlying)c(object.)0 4728 y FL(exception)i FD(InvalidCharacterErr)208 4828 y FN(This)27 b(e)o(xception)e(is)j(raised)f(when)g(a)g(string)g(parameter)f (contains)g(a)i(character)e(that)h(is)h(not)f(permitted)f(in)h(the)h (conte)o(xt)d(it')-5 b(s)208 4927 y(being)23 b(used)h(in)g(by)g(the)g (XML)g(1.0)g(recommendation.)33 b(F)o(or)24 b(e)o(xample,)f(attempting) g(to)h(create)g(an)g FJ(Element)g FN(node)f(with)h(a)208 5027 y(space)c(in)g(the)g(element)g(type)g(name)f(will)i(cause)f(this)h (error)e(to)h(be)g(raised.)0 5174 y FL(exception)f FD (InvalidModificationErr)208 5273 y FN(Raised)h(when)g(an)g(attempt)g (is)h(made)f(to)g(modify)e(the)j(type)e(of)h(a)h(node.)p 0 5549 3901 4 v 0 5649 a FI(280)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 281 293 TeXDict begin 281 292 bop 0 83 a FL(exception)19 b FD(InvalidStateErr) 208 183 y FN(Raised)h(when)g(an)g(attempt)g(is)h(made)f(to)g(use)g(an)g (object)g(that)g(is)h(not)f(de\002ned)g(or)f(is)j(no)d(longer)g (usable.)0 330 y FL(exception)g FD(NamespaceErr)208 429 y FN(If)g(an)g(attempt)g(is)i(made)e(to)g(change)f(an)o(y)h(object)g (in)h(a)f(w)o(ay)h(that)f(is)i(not)e(permitted)f(with)i(re)o(gard)d(to) j(the)f FK(Namespaces)g(in)h(XML)208 529 y FN(recommendation,)c(this)21 b(e)o(xception)d(is)j(raised.)0 676 y FL(exception)e FD(NotFoundErr)208 775 y FN(Exception)98 b(when)h(a)h(node)f(does)g (not)h(e)o(xist)g(in)g(the)g(referenced)d(conte)o(xt.)263 b(F)o(or)99 b(e)o(xample,)208 875 y FJ (NamedNodeMap.removeNamedItem\(\))41 b FN(will)47 b(raise)g(this)g(if)g (the)g(node)e(passed)i(in)g(does)f(not)g(e)o(xist)h(in)g(the)208 975 y(map.)0 1121 y FL(exception)19 b FD(NotSupportedErr)208 1221 y FN(Raised)h(when)g(the)g(implementation)e(does)i(not)g(support)f (the)h(requested)f(type)g(of)h(object)g(or)g(operation.)0 1368 y FL(exception)f FD(NoDataAllowedErr)208 1468 y FN(This)h(is)h(raised)f(if)h(data)f(is)h(speci\002ed)f(for)f(a)i(node)e (which)h(does)g(not)f(support)g(data.)0 1614 y FL(exception)g FD(NoModificationAllowedErr)208 1714 y FN(Raised)h(on)g(attempts)g(to)h (modify)d(an)i(object)g(where)f(modi\002cations)g(are)h(not)g(allo)n (wed)g(\(such)f(as)i(for)f(read-only)e(nodes\).)0 1861 y FL(exception)h FD(SyntaxErr)208 1961 y FN(Raised)h(when)g(an)g(in)m (v)n(alid)f(or)h(ille)o(gal)g(string)f(is)j(speci\002ed.)0 2107 y FL(exception)d FD(WrongDocumentErr)208 2207 y FN(Raised)f(when)f(a)h(node)f(is)i(inserted)e(in)h(a)g(dif)n(ferent)e (document)g(than)h(it)i(currently)d(belongs)g(to,)i(and)g(the)f (implementation)f(does)208 2307 y(not)j(support)g(migrating)g(the)h (node)f(from)g(one)h(document)e(to)j(the)f(other)-5 b(.)0 2454 y(The)25 b(e)o(xception)e(codes)h(de\002ned)g(in)i(the)f(DOM)g (recommendation)d(map)i(to)h(the)g(e)o(xceptions)f(described)g(abo)o(v) o(e)f(according)g(to)i(this)0 2553 y(table:)630 2762 y FL(Constant)p 2023 2792 4 100 v 1121 w(Exception)p 580 2796 2740 4 v 630 2865 a FJ(DOMSTRING_SIZE_ERR)p 2023 2895 4 100 v 545 w(DomstringSizeErr)630 2965 y (HIERARCHY_REQUEST_ERR)p 2023 2995 V 395 w(HierarchyRequestErr)630 3065 y(INDEX_SIZE_ERR)p 2023 3094 V 745 w(IndexSizeErr)630 3164 y(INUSE_ATTRIBUTE_ERR)p 2023 3194 V 495 w(InuseAttributeErr)630 3264 y(INVALID_ACCESS_ERR)p 2023 3294 V 545 w(InvalidAccessErr)630 3363 y(INVALID_CHARACTER_ERR)p 2023 3393 V 395 w(InvalidCharacterErr) 630 3463 y(INVALID_MODIFICATION_ERR)p 2023 3493 V 245 w(InvalidModificationErr)630 3563 y(INVALID_STATE_ERR)p 2023 3593 V 595 w(InvalidStateErr)630 3662 y(NAMESPACE_ERR)p 2023 3692 V 795 w(NamespaceErr)630 3762 y(NOT_FOUND_ERR)p 2023 3792 V 795 w(NotFoundErr)630 3862 y(NOT_SUPPORTED_ERR)p 2023 3891 V 595 w(NotSupportedErr)630 3961 y(NO_DATA_ALLOWED_ERR)p 2023 3991 V 495 w(NoDataAllowedErr)630 4061 y (NO_MODIFICATION_ALLOWED_ERR)p 2023 4091 V 95 w (NoModificationAllowedErr)630 4160 y(SYNTAX_ERR)p 2023 4190 V 945 w(SyntaxErr)630 4260 y(WRONG_DOCUMENT_ERR)p 2023 4290 V 545 w(WrongDocumentErr)0 4540 y Fv(8.6.3)100 b(Conf)m(or)r(mance)0 4743 y FN(This)17 b(section)g(describes)f(the)i (conformance)c(requirements)h(and)h(relationships)g(between)g(the)h (Python)f(DOM)h(API,)g(the)g(W3C)h(DOM)0 4843 y(recommendations,)f(and) i(the)i(OMG)f(IDL)g(mapping)e(for)i(Python.)0 5111 y FI(T)-10 b(ype)23 b(Mapping)0 5314 y FN(The)d(primiti)n(v)o(e)f(IDL)h (types)g(used)g(in)g(the)g(DOM)h(speci\002cation)e(are)h(mapped)f(to)h (Python)f(types)h(according)e(to)j(the)f(follo)n(wing)e(table.)p 0 5549 3901 4 v 0 5649 a FI(8.6.)52 b FJ(xml.dom)22 b FI(\227)h(The)g(Document)h(Object)f(Model)h(API)1881 b(281)p eop end %%Page: 282 294 TeXDict begin 282 293 bop 927 70 a FL(IDL)21 b(T)-6 b(ype)p 1573 100 4 100 v 355 w(Python)20 b(T)-6 b(ype)p 877 103 2146 4 v 927 173 a FJ(boolean)p 1573 203 4 100 v 347 w(IntegerType)19 b FN(\(with)h(a)h(v)n(alue)e(of)h FJ(0)h FN(or)f FJ(1)p FN(\))927 272 y FJ(int)p 1573 302 V 547 w(IntegerType)927 372 y(long)49 b(int)p 1573 402 V 298 w(IntegerType)927 472 y(unsigned)f(int)p 1573 501 V 99 w(IntegerType)0 697 y FN(Additionally)-5 b(,)17 b(the)j FJ(DOMString)e FN(de\002ned)g(in)i(the)f(recommendation)d(is)21 b(mapped)d(to)h(a)h(Python)e(string)h(or)h(Unicode)e(string.)24 b(Appli-)0 796 y(cations)c(should)f(be)h(able)g(to)h(handle)e(Unicode)g (whene)n(v)o(er)f(a)j(string)e(is)j(returned)c(from)h(the)h(DOM.)0 943 y(The)f(IDL)f FJ(null)h FN(v)n(alue)f(is)i(mapped)d(to)j FJ(None)p FN(,)e(which)h(may)f(be)h(accepted)f(or)g(pro)o(vided)f(by)h (the)h(implementation)e(whene)n(v)o(er)g FJ(null)0 1043 y FN(is)k(allo)n(wed)f(by)f(the)i(API.)0 1311 y FI(Accessor)g(Methods)0 1514 y FN(The)26 b(mapping)e(from)h(OMG)h(IDL)g(to)h(Python)e (de\002nes)g(accessor)h(functions)f(for)g(IDL)h FJ(attribute)f FN(declarations)g(in)h(much)g(the)0 1614 y(w)o(ay)20 b(the)g(Ja)n(v)n(a)h(mapping)d(does.)25 b(Mapping)19 b(the)h(IDL)g(declarations)236 1852 y FA(readonly)44 b(attribute)f(string)h(someValue;)640 1943 y(attribute)f(string)h (anotherValue;)0 2230 y FN(yields)18 b(three)g(accessor)g(functions:)k (a)d(\223get\224)f(method)f(for)g FJ(someValue)g FN(\()p FJ(_get_someValue\(\))p FN(\),)f(and)h(\223get\224)h(and)g(\223set\224) g(meth-)0 2329 y(ods)e(for)g FJ(anotherValue)f FN(\()p FJ(_get_anotherValue\(\))e FN(and)j FJ(_set_anotherValue\(\))p FN(\).)k(The)c(mapping,)f(in)h(particular)m(,)0 2429 y(does)h(not)f(require)g(that)h(the)g(IDL)g(attrib)n(utes)f(are)h (accessible)g(as)h(normal)e(Python)f(attrib)n(utes:)24 b FK(object)q FJ(.someValue)15 b FN(is)j FK(not)e FN(required)0 2529 y(to)k(w)o(ork,)g(and)f(may)h(raise)g(an)h FJ(AttributeError)p FN(.)0 2675 y(The)c(Python)f(DOM)i(API,)f(ho)n(we)n(v)o(er)m(,)f FK(does)h FN(require)f(that)h(normal)g(attrib)n(ute)f(access)i(w)o (ork.)24 b(This)17 b(means)g(that)h(the)f(typical)g(surrogates)0 2775 y(generated)25 b(by)g(Python)g(IDL)i(compilers)e(are)h(not)g(lik)o (ely)g(to)g(w)o(ork,)h(and)f(wrapper)f(objects)h(may)g(be)g(needed)f (on)g(the)i(client)f(if)h(the)0 2875 y(DOM)i(objects)f(are)g(accessed)h (via)f(CORB)m(A.)i(While)f(this)g(does)f(require)g(some)g(additional)f (consideration)f(for)i(CORB)m(A)i(DOM)0 2974 y(clients,)i(the)d (implementers)f(with)h(e)o(xperience)e(using)i(DOM)h(o)o(v)o(er)e(CORB) m(A)j(from)d(Python)g(do)h(not)g(consider)f(this)i(a)g(problem.)0 3074 y(Attrib)n(utes)20 b(that)g(are)h(declared)e FJ(readonly)g FN(may)h(not)f(restrict)i(write)f(access)h(in)f(all)h(DOM)f (implementations.)0 3221 y(In)k(the)h(Python)e(DOM)h(API,)h(accessor)f (functions)f(are)h(not)g(required.)36 b(If)24 b(pro)o(vided,)f(the)o(y) h(should)f(tak)o(e)h(the)h(form)e(de\002ned)h(by)g(the)0 3320 y(Python)e(IDL)h(mapping,)f(b)n(ut)i(these)f(methods)g(are)g (considered)e(unnecessary)h(since)i(the)f(attrib)n(utes)g(are)h (accessible)f(directly)g(from)0 3420 y(Python.)h(\223Set\224)c (accessors)h(should)e(ne)n(v)o(er)g(be)h(pro)o(vided)d(for)j FJ(readonly)f FN(attrib)n(utes.)0 3567 y(The)31 b(IDL)h(de\002nitions)e (do)h(not)h(fully)e(embody)g(the)i(requirements)d(of)i(the)h(W3C)g(DOM) g(API,)g(such)f(as)h(the)g(notion)e(of)h(certain)0 3666 y(objects,)26 b(such)g(as)g(the)f(return)g(v)n(alue)f(of)i FJ(getElementsByTagName\(\))p FN(,)d(being)h(\223li)n(v)o(e\224.)41 b(The)25 b(Python)f(DOM)i(API)g(does)f(not)0 3766 y(require)19 b(implementations)f(to)i(enforce)f(such)h(requirements.)0 4094 y FE(8.7)121 b Fx(xml.dom.minidom)29 b FE(\227)k(Lightw)o(eight)i (DOM)f(implementation)0 4326 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 4473 y FJ(xml.dom.minidom)g FN(is)j(a)g(light-weight)d(implementation)g (of)i(the)h(Document)d(Object)i(Model)g(interf)o(ace.)27 b(It)21 b(is)i(intended)c(to)j(be)0 4573 y(simpler)e(than)g(the)g(full) g(DOM)g(and)g(also)g(signi\002cantly)g(smaller)-5 b(.)0 4720 y(DOM)17 b(applications)f(typically)g(start)h(by)f(parsing)g(some) h(XML)f(into)h(a)g(DOM.)g(W)m(ith)g FJ(xml.dom.minidom)p FN(,)e(this)i(is)h(done)e(through)0 4819 y(the)k(parse)g(functions:)p 0 5549 3901 4 v 0 5649 a FI(282)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 283 295 TeXDict begin 283 294 bop 236 83 a FA(from)44 b(xml.dom.minidom)f (import)h(parse,)f(parseString)236 266 y(dom1)h(=)h (parse\('c:\\\\temp\\\\mydata.xml'\))40 b(#)45 b(parse)f(an)g(XML)g (file)h(by)f(name)236 448 y(datasource)f(=)i (open\('c:\\\\temp\\\\mydata.xml'\))236 540 y(dom2)f(=)h (parse\(datasource\))132 b(#)44 b(parse)g(an)h(open)f(file)236 722 y(dom3)g(=)h(parseString\('<myxml>Some)c(data<empty/>)i(some)h (more)g(data</myxml>'\))0 1009 y FN(The)20 b FJ(parse\(\))f FN(function)g(can)h(tak)o(e)g(either)g(a)g(\002lename)g(or)g(an)g(open) f(\002le)i(object.)0 1156 y FD(parse)p FJ(\()p FK(\002lename)p 588 1156 25 4 v 27 w(or)p 689 1156 V 30 w(\002le,)f(par)o(ser)r FJ(\))208 1255 y FN(Return)29 b(a)h FJ(Document)e FN(from)h(the)g(gi)n (v)o(en)g(input.)52 b FK(\002lename)p 2027 1255 V 28 w(or)p 2129 1255 V 30 w(\002le)29 b FN(may)h(be)f(either)g(a)h(\002le)g (name,)h(or)f(a)g(\002le-lik)o(e)f(object.)208 1355 y FK(par)o(ser)r FN(,)24 b(if)g(gi)n(v)o(en,)f(must)h(be)g(a)g(SAX2)g (parser)f(object.)35 b(This)24 b(function)e(will)i(change)e(the)i (document)e(handler)g(of)h(the)h(parser)208 1455 y(and)18 b(acti)n(v)n(ate)h(namespace)f(support;)h(other)f(parser)h (con\002guration)d(\(lik)o(e)k(setting)f(an)g(entity)g(resolv)o(er\))f (must)h(ha)n(v)o(e)g(been)g(done)208 1554 y(in)h(adv)n(ance.)0 1701 y(If)g(you)f(ha)n(v)o(e)h(XML)g(in)h(a)f(string,)g(you)f(can)h (use)g(the)h FJ(parseString\(\))d FN(function)g(instead:)0 1848 y FD(parseString)p FJ(\()p FK(string)p FC([)p FK(,)g(par)o(ser)c FC(])p FJ(\))208 1948 y FN(Return)27 b(a)i FJ(Document)e FN(that)i(represents)e(the)h FK(string)p FN(.)49 b(This)29 b(method)e(creates)h(a)g FJ(StringIO)g FN(object)f(for)h(the)g(string)g (and)208 2047 y(passes)20 b(that)h(on)e(to)i FJ(parse)p FN(.)0 2194 y(Both)f(functions)f(return)g(a)i FJ(Document)e FN(object)h(representing)e(the)i(content)f(of)h(the)g(document.)0 2341 y(What)k(the)f FJ(parse\(\))g FN(and)f FJ(parseString\(\))g FN(functions)g(do)h(is)h(connect)e(an)h(XML)h(parser)e(with)i(a)g (\223DOM)f(b)n(uilder\224)f(that)i(can)0 2441 y(accept)e(parse)g(e)n(v) o(ents)g(from)g(an)o(y)g(SAX)h(parser)f(and)g(con)m(v)o(ert)e(them)i (into)h(a)g(DOM)f(tree.)32 b(The)22 b(name)g(of)h(the)f(functions)f (are)i(perhaps)0 2540 y(misleading,)c(b)n(ut)i(are)f(easy)h(to)f(grasp) g(when)g(learning)f(the)i(interf)o(aces.)k(The)20 b(parsing)f(of)i(the) f(document)e(will)k(be)e(completed)f(before)0 2640 y(these)h(functions) f(return;)g(it')-5 b(s)22 b(simply)d(that)i(these)f(functions)f(do)h (not)f(pro)o(vide)g(a)h(parser)g(implementation)e(themselv)o(es.)0 2787 y(Y)-9 b(ou)23 b(can)h(also)g(create)g(a)g FJ(Document)g FN(by)f(calling)h(a)g(method)f(on)g(a)i(\223DOM)f(Implementation\224)d (object.)35 b(Y)-9 b(ou)24 b(can)g(get)g(this)g(object)0 2886 y(either)18 b(by)f(calling)h(the)g FJ(getDOMImplementation\(\))c FN(function)j(in)h(the)g FJ(xml.dom)f FN(package)g(or)h(the)g FJ(xml.dom.minidom)0 2986 y FN(module.)26 b(Using)21 b(the)g(implementation)d(from)i(the)h FJ(xml.dom.minidom)e FN(module)h(will)h(al)o(w)o(ays)h(return)e(a)h FJ(Document)f FN(instance)0 3086 y(from)i(the)h(minidom)e(implementation,)g(while)i (the)f(v)o(ersion)g(from)g FJ(xml.dom)g FN(may)g(pro)o(vide)f(an)i (alternate)f(implementation)e(\(this)0 3185 y(is)26 b(lik)o(ely)e(if)h (you)f(ha)n(v)o(e)g(the)h(PyXML)g(package)e(installed\).)38 b(Once)25 b(you)f(ha)n(v)o(e)g(a)h FJ(Document)p FN(,)g(you)f(can)g (add)h(child)f(nodes)g(to)h(it)g(to)0 3285 y(populate)19 b(the)h(DOM:)236 3432 y FA(from)44 b(xml.dom.minidom)f(import)h (getDOMImplementation)236 3614 y(impl)g(=)h(getDOMImplementation\(\)) 236 3797 y(newdoc)f(=)h(impl.createDocument\(None,)40 b("some_tag",)j(None\))236 3888 y(top_element)g(=)i (newdoc.documentElement)236 3980 y(text)f(=)h (newdoc.createTextNode\('Some)40 b(textual)k(content.'\))236 4071 y(top_element.appendChild\(text\))0 4357 y FN(Once)22 b(you)f(ha)n(v)o(e)g(a)h(DOM)h(document)d(object,)h(you)g(can)h(access) h(the)f(parts)g(of)f(your)g(XML)h(document)e(through)g(its)j (properties)d(and)0 4457 y(methods.)42 b(These)26 b(properties)e(are)i (de\002ned)f(in)i(the)f(DOM)g(speci\002cation.)42 b(The)26 b(main)g(property)e(of)i(the)g(document)e(object)h(is)j(the)0 4557 y FJ(documentElement)22 b FN(property)-5 b(.)35 b(It)24 b(gi)n(v)o(es)g(you)g(the)g(main)g(element)g(in)g(the)g(XML)h (document:)31 b(the)25 b(one)e(that)i(holds)e(all)i(others.)0 4656 y(Here)20 b(is)h(an)f(e)o(xample)f(program:)236 4895 y FA(dom3)44 b(=)h(parseString\("<myxml>Some)c(data</myxml>"\))236 4986 y(assert)j(dom3.documentElement.tagName)c(==)45 b("myxml")0 5272 y FN(When)24 b(you)g(are)h(\002nished)f(with)g(a)h (DOM,)g(you)f(should)f(clean)h(it)i(up.)37 b(This)25 b(is)h(necessary)d(because)h(some)h(v)o(ersions)e(of)i(Python)e(do)0 5372 y(not)f(support)f(garbage)g(collection)g(of)h(objects)h(that)f (refer)g(to)h(each)f(other)g(in)g(a)h(c)o(ycle.)31 b(Until)23 b(this)g(restriction)f(is)h(remo)o(v)o(ed)e(from)g(all)p 0 5549 3901 4 v 0 5649 a FI(8.7.)52 b FJ(xml.dom.minidom)20 b FI(\227)j(Lightw)o(eight)j(DOM)c(implementation)1477 b(283)p eop end %%Page: 284 296 TeXDict begin 284 295 bop 0 83 a FN(v)o(ersions)19 b(of)h(Python,)f(it) i(is)g(safest)g(to)f(write)g(your)f(code)h(as)h(if)f(c)o(ycles)g(w)o (ould)g(not)g(be)g(cleaned)f(up.)0 230 y(The)h(w)o(ay)g(to)g(clean)g (up)g(a)h(DOM)f(is)h(to)g(call)f(its)i FJ(unlink\(\))d FN(method:)236 468 y FA(dom1.unlink\(\))236 559 y(dom2.unlink\(\))236 651 y(dom3.unlink\(\))0 937 y FJ(unlink\(\))j FN(is)h(a)g FJ(xml.dom.minidom)p FN(-speci\002c)c(e)o(xtension)i(to)i(the)g(DOM)f (API.)h(After)f(calling)g FJ(unlink\(\))g FN(on)g(a)h(node,)f(the)0 1037 y(node)d(and)h(its)h(descendants)e(are)h(essentially)g(useless.)0 1184 y FL(See)h(Also:)0 1331 y FK(Document)e(Object)h(Model)g(\(DOM\))g (Le)o(vel)g(1)h(Speci\002cation)0 1430 y Fy(\()p FO(http://www)l (.w3.org/TR/REC-DOM-Le)m(v)n(el-)o(1/)-6 b Fy(\))208 1530 y FN(The)19 b(W3C)i(recommendation)c(for)j(the)g(DOM)g(supported)f (by)g FJ(xml.dom.minidom)p FN(.)0 1815 y Fv(8.7.1)100 b(DOM)27 b(Objects)0 2018 y FN(The)19 b(de\002nition)g(of)g(the)h(DOM)g (API)f(for)g(Python)g(is)h(gi)n(v)o(en)f(as)h(part)f(of)h(the)f FJ(xml.dom)g FN(module)f(documentation.)k(This)e(section)f(lists)0 2117 y(the)h(dif)n(ferences)f(between)g(the)h(API)h(and)e FJ(xml.dom.minidom)p FN(.)0 2264 y FD(unlink)p FJ(\(\))208 2364 y FN(Break)26 b(internal)g(references)f(within)h(the)h(DOM)g(so)g (that)f(it)i(will)f(be)f(garbage)f(collected)h(on)g(v)o(ersions)g(of)g (Python)f(without)208 2463 y(c)o(yclic)d(GC.)i(Ev)o(en)e(when)h(c)o (yclic)g(GC)h(is)g(a)n(v)n(ailable,)f(using)g(this)h(can)f(mak)o(e)g (lar)o(ge)f(amounts)g(of)h(memory)e(a)n(v)n(ailable)i(sooner)m(,)208 2563 y(so)i(calling)g(this)h(on)f(DOM)h(objects)f(as)h(soon)f(as)h(the) o(y)e(are)i(no)f(longer)f(needed)g(is)i(good)e(practice.)40 b(This)26 b(only)e(needs)h(to)h(be)208 2663 y(called)20 b(on)f(the)i FJ(Document)e FN(object,)g(b)n(ut)h(may)g(be)g(called)g (on)g(child)g(nodes)f(to)i(discard)e(children)g(of)h(that)g(node.)0 2810 y FD(writexml)p FJ(\()p FK(writer)r FC([)p FK(,indent=\224\224)p FC([)p FK(,addindent=\224\224)p FC([)p FK(,ne)n(wl=\224\224)12 b FC(])g(])g(])p FJ(\))208 2909 y FN(Write)27 b(XML)g(to)h(the)f (writer)g(object.)45 b(The)27 b(writer)g(should)f(ha)n(v)o(e)h(a)g FJ(write\(\))g FN(method)e(which)i(matches)g(that)g(of)g(the)g(\002le) 208 3009 y(object)d(interf)o(ace.)39 b(The)24 b FK(indent)i FN(parameter)e(is)i(the)f(indentation)e(of)i(the)g(current)f(node.)38 b(The)25 b FK(addindent)f FN(parameter)g(is)i(the)208 3108 y(incremental)18 b(indentation)f(to)j(use)g(for)e(subnodes)g(of)i (the)f(current)f(one.)25 b(The)19 b FK(ne)o(wl)g FN(parameter)f (speci\002es)i(the)g(string)f(to)h(use)f(to)208 3208 y(terminate)g(ne)n(wlines.)208 3341 y(Changed)k(in)h(v)o(ersion)f(2.1:) h(The)g(optional)f(k)o(e)o(yw)o(ord)g(parameters)g FK(indent)q FN(,)i FK(addindent)q FN(,)e(and)h FK(ne)o(wl)h FN(were)f(added)f(to)i (support)208 3441 y(pretty)19 b(output.)208 3573 y(Changed)25 b(in)i(v)o(ersion)f(2.3:)g(F)o(or)h(the)g FJ(Document)f FN(node,)h(an)g(additional)f(k)o(e)o(yw)o(ord)f(ar)o(gument)f FK(encoding)h FN(can)i(be)g(used)f(to)208 3673 y(specify)19 b(the)h(encoding)e(\002eld)j(of)f(the)g(XML)g(header)-5 b(.)0 3820 y FD(toxml)p FJ(\()p FC([)p FK(encoding)12 b FC(])p FJ(\))208 3919 y FN(Return)19 b(the)i(XML)f(that)g(the)g(DOM)h (represents)e(as)i(a)g(string.)208 4052 y(W)m(ith)f(no)g(ar)o(gument,)d (the)j(XML)g(header)f(does)h(not)g(specify)f(an)h(encoding,)e(and)h (the)h(result)g(is)h(Unicode)e(string)h(if)g(the)g(def)o(ault)208 4152 y(encoding)c(cannot)i(represent)f(all)j(characters)d(in)i(the)g (document.)k(Encoding)16 b(this)j(string)g(in)g(an)f(encoding)f(other)h (than)g(UTF-8)208 4252 y(is)j(lik)o(ely)f(incorrect,)e(since)j(UTF-8)e (is)j(the)e(def)o(ault)f(encoding)f(of)i(XML.)208 4384 y(W)m(ith)f(an)h(e)o(xplicit)f FK(encoding)f FN(ar)o(gument,)f(the)i (result)h(is)h(a)f(byte)f(string)g(in)h(the)g(speci\002ed)f(encoding.)j (It)e(is)h(recommended)16 b(that)208 4484 y(this)24 b(ar)o(gument)e(is) j(al)o(w)o(ays)f(speci\002ed.)37 b(T)-7 b(o)24 b(a)n(v)n(oid)g FJ(UnicodeError)e FN(e)o(xceptions)g(in)j(case)f(of)g(unrepresentable)d (te)o(xt)j(data,)208 4584 y(the)c(encoding)e(ar)o(gument)g(should)h(be) h(speci\002ed)g(as)h(\224utf-8\224.)208 4716 y(Changed)d(in)j(v)o (ersion)e(2.3:)g(the)i FK(encoding)d FN(ar)o(gument)f(w)o(as)22 b(introduced.)0 4863 y FD(toprettyxml)p FJ(\()p FC([)p FK(indent)q FC([)p FK(,)17 b(ne)o(wl)12 b FC(])g(])p FJ(\))208 4963 y FN(Return)19 b(a)i(pretty-printed)d(v)o(ersion)h(of)h (the)g(document.)j FK(indent)e FN(speci\002es)g(the)g(indentation)d (string)i(and)g(def)o(aults)g(to)g(a)h(tab)n(ula-)208 5063 y(tor;)f FK(ne)o(wl)g FN(speci\002es)h(the)f(string)g(emitted)g (at)g(the)h(end)e(of)h(each)g(line)g(and)g(def)o(aults)g(to)g FJ(\\n)p FN(.)208 5195 y(Ne)n(w)g(in)g(v)o(ersion)f(2.1.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.3:)h(the)g(encoding)e(ar)o(gument;)g (see)j FJ(toxml\(\))p FN(.)0 5342 y(The)f(follo)n(wing)e(standard)h (DOM)i(methods)e(ha)n(v)o(e)h(special)g(considerations)e(with)j FJ(xml.dom.minidom)p FN(:)p 0 5549 3901 4 v 0 5649 a FI(284)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g (Processing)g(T)-10 b(ools)p eop end %%Page: 285 297 TeXDict begin 285 296 bop 0 83 a FD(cloneNode)p FJ(\()p FK(deep)p FJ(\))208 183 y FN(Although)25 b(this)j(method)e(w)o(as)i (present)f(in)g(the)h(v)o(ersion)e(of)h FJ(xml.dom.minidom)e FN(packaged)h(with)h(Python)f(2.0,)j(it)f(w)o(as)208 282 y(seriously)19 b(brok)o(en.)k(This)e(has)f(been)g(corrected)e(for)i (subsequent)e(releases.)0 567 y Fv(8.7.2)100 b(DOM)27 b(Example)0 770 y FN(This)c(e)o(xample)e(program)f(is)j(a)g(f)o(airly)f (realistic)h(e)o(xample)e(of)h(a)g(simple)h(program.)29 b(In)22 b(this)h(particular)e(case,)i(we)g(do)f(not)g(tak)o(e)h(much)0 870 y(adv)n(antage)18 b(of)i(the)g(\003e)o(xibility)g(of)g(the)g(DOM.) 236 1058 y FA(import)44 b(xml.dom.minidom)236 1241 y(document)g(=)g ("""\\)236 1332 y(<slideshow>)236 1423 y(<title>Demo)f (slideshow</title>)236 1515 y(<slide><title>Slide)f(title</title>)236 1606 y(<point>This)h(is)i(a)f(demo</point>)236 1697 y(<point>Of)g(a)g (program)g(for)g(processing)f(slides</point>)236 1789 y(</slide>)236 1971 y(<slide><title>Another)f(demo)i(slide</title>)236 2063 y(<point>It)g(is)g(important</point>)236 2154 y(<point>To)g(have)g (more)g(than</point>)236 2245 y(<point>one)f(slide</point>)236 2337 y(</slide>)236 2428 y(</slideshow>)236 2519 y(""")236 2702 y(dom)i(=)f(xml.dom.minidom.parseString\(document\))236 2885 y(def)h(getText\(nodelist\):)416 2976 y(rc)f(=)h("")416 3067 y(for)f(node)g(in)h(nodelist:)595 3159 y(if)f(node.nodeType)f(==)i (node.TEXT_NODE:)774 3250 y(rc)g(=)f(rc)h(+)g(node.data)416 3341 y(return)e(rc)236 3524 y(def)i(handleSlideshow\(slideshow\):)416 3615 y(print)f("<html>")416 3706 y (handleSlideshowTitle\(slideshow.getEl)o(ements)o(ByTagN)o(ame\("t)o (itle"\))o([0]\))416 3798 y(slides)f(=)i (slideshow.getElementsByTagName\("slide"\))416 3889 y (handleToc\(slides\))416 3980 y(handleSlides\(slides\))416 4072 y(print)f("</html>")236 4254 y(def)h(handleSlides\(slides\):)416 4346 y(for)f(slide)g(in)g(slides:)595 4437 y(handleSlide\(slide\))236 4620 y(def)h(handleSlide\(slide\):)416 4711 y (handleSlideTitle\(slide.getElementsBy)o(TagNam)o(e\("tit)o(le"\)[0)o (]\))416 4802 y(handlePoints\(slide.getElementsByTagN)o(ame\("p)o (oint"\))o(\))236 4985 y(def)g(handleSlideshowTitle\(title\):)416 5076 y(print)f("<title>\045s</title>")d(\045)k (getText\(title.childNodes\))236 5259 y(def)g (handleSlideTitle\(title\):)416 5350 y(print)f("<h2>\045s</h2>")e(\045) j(getText\(title.childNodes\))p 0 5549 3901 4 v 0 5649 a FI(8.7.)52 b FJ(xml.dom.minidom)20 b FI(\227)j(Lightw)o(eight)j(DOM)c (implementation)1477 b(285)p eop end %%Page: 286 298 TeXDict begin 286 297 bop 236 174 a FA(def)45 b (handlePoints\(points\):)416 266 y(print)f("<ul>")416 357 y(for)g(point)g(in)g(points:)595 448 y(handlePoint\(point\))416 540 y(print)g("</ul>")236 722 y(def)h(handlePoint\(point\):)416 814 y(print)f("<li>\045s</li>")e(\045)j(getText\(point.childNodes\))236 996 y(def)g(handleToc\(slides\):)416 1088 y(for)f(slide)g(in)g(slides:) 595 1179 y(title)g(=)h(slide.getElementsByTagName\("title"\)[)o(0])595 1270 y(print)f("<p>\045s</p>")f(\045)i(getText\(title.childNodes\))236 1453 y(handleSlideshow\(dom\))0 1738 y Fv(8.7.3)100 b(minidom)29 b(and)g(the)f(DOM)f(standard)0 1941 y FN(The)20 b FJ(xml.dom.minidom)d FN(module)i(is)i(essentially)f(a)g(DOM)g(1.0-compatible)d(DOM)j(with)g (some)g(DOM)g(2)g(features)f(\(primarily)0 2040 y(namespace)g (features\).)0 2187 y(Usage)h(of)g(the)g(DOM)h(interf)o(ace)e(in)h (Python)g(is)h(straight-forw)o(ard.)h(The)e(follo)n(wing)e(mapping)h (rules)h(apply:)125 2417 y FM(\017)41 b FN(Interf)o(aces)15 b(are)h(accessed)h(through)d(instance)i(objects.)24 b(Applications)15 b(should)h(not)g(instantiate)g(the)h(classes)g(themselv)o(es;)g(the)o (y)208 2517 y(should)22 b(use)i(the)g(creator)f(functions)f(a)n(v)n (ailable)i(on)f(the)h FJ(Document)f FN(object.)35 b(Deri)n(v)o(ed)22 b(interf)o(aces)h(support)g(all)h(operations)208 2616 y(\(and)19 b(attrib)n(utes\))h(from)f(the)h(base)g(interf)o(aces,)g (plus)g(an)o(y)f(ne)n(w)h(operations.)125 2782 y FM(\017)41 b FN(Operations)20 b(are)h(used)g(as)h(methods.)28 b(Since)21 b(the)g(DOM)h(uses)g(only)e FJ(in)i FN(parameters,)e(the)h(ar)o (guments)f(are)h(passed)g(in)h(normal)208 2882 y(order)c(\(from)h(left) i(to)f(right\).)k(There)19 b(are)h(no)g(optional)f(ar)o(guments.)k FJ(void)d FN(operations)f(return)g FJ(None)p FN(.)125 3048 y FM(\017)41 b FN(IDL)16 b(attrib)n(utes)g(map)g(to)h(instance)f (attrib)n(utes.)23 b(F)o(or)16 b(compatibility)f(with)i(the)f(OMG)h (IDL)f(language)f(mapping)f(for)i(Python,)g(an)208 3148 y(attrib)n(ute)22 b FJ(foo)h FN(can)g(also)g(be)g(accessed)g(through)e (accessor)i(methods)f FJ(_get_foo\(\))g FN(and)g FJ(_set_foo\(\))p FN(.)32 b FJ(readonly)208 3247 y FN(attrib)n(utes)20 b(must)g(not)g(be)g(changed;)e(this)j(is)g(not)f(enforced)e(at)j (runtime.)125 3413 y FM(\017)41 b FN(The)20 b(types)h FJ(short)49 b(int)p FN(,)21 b FJ(unsigned)48 b(int)p FN(,)21 b FJ(unsigned)48 b(long)h(long)p FN(,)21 b(and)f FJ(boolean)g FN(all)i(map)e(to)h(Python)f(inte-)208 3513 y(ger)f(objects.)125 3679 y FM(\017)41 b FN(The)21 b(type)h FJ(DOMString)f FN(maps)g(to)h(Python)f(strings.)31 b FJ(xml.dom.minidom)19 b FN(supports)i(either)h(byte)f(or)h(Unicode)f (strings,)208 3779 y(b)n(ut)i(will)i(normally)d(produce)g(Unicode)h (strings.)36 b(V)-9 b(alues)24 b(of)f(type)h FJ(DOMString)f FN(may)g(also)h(be)g FJ(None)g FN(where)f(allo)n(wed)g(to)208 3878 y(ha)n(v)o(e)c(the)h(IDL)g FJ(null)g FN(v)n(alue)g(by)g(the)g(DOM) g(speci\002cation)g(from)f(the)h(W3C.)125 4044 y FM(\017)41 b FJ(const)182 b FN(declarations)g(map)g(to)h(v)n(ariables)f(in)h (their)f(respecti)n(v)o(e)g(scope)g(\(e.g.)208 4144 y FJ(xml.dom.minidom.Node.PROCESSING_I)o(NSTRU)o(CTION_)o(NODE)p FN(\))o(;)15 b(the)o(y)20 b(must)g(not)g(be)g(changed.)125 4310 y FM(\017)41 b FJ(DOMException)30 b FN(is)i(currently)f(not)g (supported)f(in)i FJ(xml.dom.minidom)p FN(.)58 b(Instead,)33 b FJ(xml.dom.minidom)d FN(uses)208 4410 y(standard)19 b(Python)g(e)o(xceptions)f(such)i(as)h FJ(TypeError)e FN(and)h FJ(AttributeError)p FN(.)125 4576 y FM(\017)41 b FJ(NodeList)23 b FN(objects)i(are)f(implemented)f(using)h(Python')-5 b(s)24 b(b)n(uilt-in)g(list)i(type.)38 b(Starting)25 b(with)f(Python)g(2.2,)h(these)g(objects)208 4675 y(pro)o(vide)19 b(the)j(interf)o(ace)f(de\002ned)g(in)h(the)g(DOM)g(speci\002cation,)f (b)n(ut)h(with)g(earlier)f(v)o(ersions)g(of)g(Python)g(the)o(y)g(do)g (not)h(support)208 4775 y(the)d(of)n(\002cial)f(API.)h(The)o(y)f(are,)h (ho)n(we)n(v)o(er)m(,)e(much)h(more)g(\223Pythonic\224)g(than)g(the)h (interf)o(ace)f(de\002ned)g(in)i(the)f(W3C)h(recommenda-)208 4875 y(tions.)0 5104 y(The)g(follo)n(wing)e(interf)o(aces)i(ha)n(v)o(e) g(no)f(implementation)f(in)j FJ(xml.dom.minidom)p FN(:)125 5334 y FM(\017)41 b FJ(DOMTimeStamp)p 0 5549 3901 4 v 0 5649 a FI(286)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 287 299 TeXDict begin 287 298 bop 125 83 a FM(\017)41 b FJ(DocumentType)18 b FN(\(added)h(in)h(Python)f(2.1\))125 249 y FM(\017)41 b FJ(DOMImplementation)17 b FN(\(added)i(in)h(Python)f(2.1\))125 415 y FM(\017)41 b FJ(CharacterData)125 581 y FM(\017)g FJ(CDATASection)125 747 y FM(\017)g FJ(Notation)125 913 y FM(\017)g FJ(Entity)125 1079 y FM(\017)g FJ(EntityReference)125 1245 y FM(\017)g FJ(DocumentFragment)0 1475 y FN(Most)20 b(of)g(these)h(re\003ect)f(information)e(in)i(the)g(XML)h(document)d (that)i(is)h(not)f(of)g(general)f(utility)h(to)g(most)h(DOM)f(users.)0 1803 y FE(8.8)121 b Fx(xml.dom.pulldom)29 b FE(\227)k(Suppor)5 b(t)34 b(f)l(or)h(b)n(uilding)e(par)5 b(tial)34 b(DOM)f(trees)0 2035 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 2182 y FJ(xml.dom.pulldom)h FN(allo)n(ws)j(b)n(uilding)e(only)g(selected)h (portions)g(of)g(a)g(Document)f(Object)h(Model)g(representation)e(of)i (a)h(docu-)0 2282 y(ment)d(from)f(SAX)i(e)n(v)o(ents.)0 2429 y FL(class)g FD(PullDOM)p FJ(\()p FC([)p FK(documentF)-6 b(actory)12 b FC(])p FJ(\))208 2528 y(xml.sax.handler.ContentHandler)j FN(implementation)j(that)i(...)0 2675 y FL(class)h FD(DOMEventStream)p FJ(\()p FK(str)m(eam,)c(par)o(ser)-9 b(,)21 b(b)n(ufsize)p FJ(\))208 2775 y FN(...)0 2922 y FL(class)g FD(SAX2DOM)p FJ(\()p FC([)p FK(documentF)-6 b(actory)12 b FC(])p FJ(\))208 3021 y(xml.sax.handler.ContentHandler)j FN(implementation)j(that)i(...) 0 3168 y FD(parse)p FJ(\()p FK(str)m(eam)p 528 3168 25 4 v 29 w(or)p 631 3168 V 29 w(string)p FC([)p FK(,)g(par)o(ser)r FC([)p FK(,)h(b)n(ufsize)12 b FC(])g(])p FJ(\))208 3268 y FN(...)0 3415 y FD(parseString)p FJ(\()p FK(string)p FC([)p FK(,)18 b(par)o(ser)c FC(])p FJ(\))208 3514 y FN(...)0 3661 y FD(default_bufsize)208 3761 y FN(Def)o(ault)19 b(v)n(alue)f(for)h(the)g FK(b)n(ufsize)h FN(parameter)e(to)h FJ(parse\(\))p FN(.)50 b(Changed)18 b(in)h(v)o(ersion)f(2.1:)h(The)g(v) n(alue)f(of)h(this)h(v)n(ariable)f(can)g(be)208 3861 y(changed)f(before)h(calling)g FJ(parse\(\))h FN(and)g(the)g(ne)n(w)g (v)n(alue)f(will)i(tak)o(e)f(ef)n(fect.)0 4145 y Fv(8.8.1)100 b(DOMEv)n(entStream)29 b(Objects)0 4334 y FD(getEvent)p FJ(\(\))208 4434 y FN(...)0 4581 y FD(expandNode)p FJ(\()p FK(node)p FJ(\))208 4680 y FN(...)0 4827 y FD(reset)p FJ(\(\))208 4927 y FN(...)p 0 5549 3901 4 v 0 5649 a FI(8.8.)52 b FJ(xml.dom.pulldom)20 b FI(\227)j(Suppor)s(t)i(f)n(or)d(b) n(uilding)k(par)s(tial)e(DOM)f(trees)1299 b(287)p eop end %%Page: 288 300 TeXDict begin 288 299 bop 0 88 a FE(8.9)121 b Fx(xml.sax)31 b FE(\227)i(Suppor)5 b(t)35 b(f)l(or)f(SAX2)f(parsers)0 321 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 468 y(The)24 b FJ(xml.sax)g FN(package)f(pro)o(vides)g(a)j(number)c(of)j(modules)e (which)i(implement)e(the)i(Simple)f(API)h(for)f(XML)h(\(SAX\))f(interf) o(ace)0 567 y(for)e(Python.)32 b(The)23 b(package)e(itself)j(pro)o (vides)d(the)i(SAX)g(e)o(xceptions)e(and)i(the)g(con)m(v)o(enience)d (functions)h(which)h(will)i(be)f(most)g(used)0 667 y(by)d(users)g(of)g (the)g(SAX)h(API.)0 814 y(The)f(con)m(v)o(enience)d(functions)i(are:)0 961 y FD(make_parser)p FJ(\()p FC([)p FK(par)o(ser)p 861 961 25 4 v 27 w(list)13 b FC(])p FJ(\))208 1060 y FN(Create)22 b(and)g(return)f(a)h(SAX)h FJ(XMLReader)e FN(object.)30 b(The)22 b(\002rst)h(parser)e(found)g(will)i(be)f(used.) 30 b(If)22 b FK(par)o(ser)p 3287 1060 V 30 w(list)j FN(is)e(pro)o (vided,)d(it)208 1160 y(must)e(be)g(a)g(sequence)f(of)h(strings)g (which)f(name)g(modules)g(that)h(ha)n(v)o(e)g(a)g(function)f(named)f FJ(create_parser\(\))p FN(.)22 b(Modules)208 1260 y(listed)e(in)h FK(par)o(ser)p 715 1260 V 29 w(list)i FN(will)e(be)f(used)g(before)f (modules)g(in)h(the)h(def)o(ault)e(list)i(of)f(parsers.)0 1407 y FD(parse)p FJ(\()p FK(\002lename)p 588 1407 V 27 w(or)p 689 1407 V 30 w(str)m(eam,)g(handler)r FC([)p FK(,)f(err)l(or)p 1496 1407 V 30 w(handler)14 b FC(])p FJ(\))208 1506 y FN(Create)22 b(a)h(SAX)g(parser)f(and)g(use)g(it)i(to) e(parse)g(a)h(document.)30 b(The)22 b(document,)e(passed)j(in)f(as)i FK(\002lename)p 3230 1506 V 28 w(or)p 3332 1506 V 29 w(str)m(eam)p FN(,)g(can)e(be)g(a)208 1606 y(\002lename)i(or)h(a)g (\002le)h(object.)39 b(The)25 b FK(handler)h FN(parameter)e(needs)g(to) h(be)g(a)h(SAX)g FJ(ContentHandler)d FN(instance.)39 b(If)25 b FK(err)l(or)p 3847 1606 V 30 w(-)208 1705 y(handler)k FN(is)g(gi)n(v)o(en,)g(it)g(must)f(be)h(a)g(SAX)g FJ(ErrorHandler)d FN(instance;)33 b(if)28 b(omitted,)i FJ(SAXParseException)25 b FN(will)30 b(be)208 1805 y(raised)20 b(on)f(all)i(errors.)j(There)c (is)h(no)e(return)g(v)n(alue;)h(all)h(w)o(ork)e(must)i(be)f(done)f(by)h (the)g FK(handler)h FN(passed)f(in.)0 1952 y FD(parseString)p FJ(\()p FK(string)o(,)e(handler)r FC([)p FK(,)h(err)l(or)p 1350 1952 V 30 w(handler)14 b FC(])p FJ(\))208 2052 y FN(Similar)20 b(to)g FJ(parse\(\))p FN(,)f(b)n(ut)i(parses)f(from)f(a)i (b)n(uf)n(fer)d FK(string)j FN(recei)n(v)o(ed)e(as)h(a)h(parameter)-5 b(.)0 2198 y(A)20 b(typical)f(SAX)h(application)d(uses)j(three)f(kinds) g(of)g(objects:)24 b(readers,)19 b(handlers)f(and)h(input)f(sources.)25 b(\223Reader\224)18 b(in)i(this)g(conte)o(xt)e(is)0 2298 y(another)i(term)g(for)h(parser)m(,)f(i.e.)h(some)f(piece)h(of)g(code)f (that)h(reads)g(the)g(bytes)g(or)f(characters)g(from)g(the)h(input)g (source,)f(and)g(produces)0 2398 y(a)25 b(sequence)f(of)g(e)n(v)o (ents.)38 b(The)24 b(e)n(v)o(ents)g(then)g(get)h(distrib)n(uted)f(to)h (the)f(handler)g(objects,)h(i.e.)g(the)f(reader)g(in)m(v)n(ok)o(es)g(a) h(method)e(on)i(the)0 2497 y(handler)-5 b(.)23 b(A)18 b(SAX)g(application)e(must)h(therefore)f(obtain)g(a)i(reader)e(object,) i(create)f(or)g(open)f(the)i(input)e(sources,)h(create)h(the)f (handlers,)0 2597 y(and)22 b(connect)e(these)j(objects)f(all)g (together)-5 b(.)30 b(As)23 b(the)f(\002nal)g(step)h(of)f(preparation,) e(the)i(reader)f(is)i(called)f(to)g(parse)g(the)g(input.)30 b(During)0 2697 y(parsing,)19 b(methods)g(on)h(the)g(handler)f(objects) h(are)g(called)g(based)g(on)f(structural)h(and)f(syntactic)h(e)n(v)o (ents)g(from)f(the)h(input)g(data.)0 2843 y(F)o(or)k(these)h(objects,)g (only)f(the)g(interf)o(aces)g(are)h(rele)n(v)n(ant;)h(the)o(y)d(are)i (normally)e(not)h(instantiated)g(by)g(the)h(application)e(itself.)39 b(Since)0 2943 y(Python)19 b(does)h(not)f(ha)n(v)o(e)h(an)g(e)o (xplicit)f(notion)g(of)h(interf)o(ace,)f(the)o(y)g(are)h(formally)f (introduced)e(as)k(classes,)g(b)n(ut)f(applications)f(may)g(use)0 3043 y(implementations)24 b(which)i(do)g(not)g(inherit)g(from)f(the)i (pro)o(vided)c(classes.)45 b(The)26 b FJ(InputSource)p FN(,)g FJ(Locator)p FN(,)h FJ(Attributes)p FN(,)0 3142 y FJ(AttributesNS)p FN(,)21 b(and)h FJ(XMLReader)g FN(interf)o(aces)h (are)g(de\002ned)e(in)j(the)f(module)e FJ(xml.sax.xmlreader)p FN(.)31 b(The)22 b(handler)g(in-)0 3242 y(terf)o(aces)e(are)g (de\002ned)e(in)i FJ(xml.sax.handler)p FN(.)j(F)o(or)d(con)m(v)o (enience,)c FJ(InputSource)j FN(\(which)g(is)h(often)f(instantiated)h (directly\))0 3342 y(and)g(the)g(handler)f(classes)i(are)f(also)h(a)n (v)n(ailable)e(from)g FJ(xml.sax)p FN(.)25 b(These)20 b(interf)o(aces)f(are)h(described)f(belo)n(w)-5 b(.)0 3488 y(In)20 b(addition)f(to)h(these)h(classes,)g FJ(xml.sax)e FN(pro)o(vides)f(the)j(follo)n(wing)d(e)o(xception)h(classes.)0 3635 y FL(exception)g FD(SAXException)p FJ(\()p FK(msg)p FC([)p FK(,)f(e)n(xception)12 b FC(])p FJ(\))208 3735 y FN(Encapsulate)k(an)i(XML)g(error)f(or)h(w)o(arning.)23 b(This)18 b(class)h(can)e(contain)g(basic)h(error)f(or)h(w)o(arning)f (information)e(from)i(either)h(the)208 3835 y(XML)24 b(parser)g(or)h(the)f(application:)33 b(it)25 b(can)g(be)f(subclassed)g (to)h(pro)o(vide)e(additional)g(functionality)g(or)h(to)h(add)f (localization.)208 3934 y(Note)c(that)h(although)d(the)j(handlers)e (de\002ned)h(in)h(the)f FJ(ErrorHandler)f FN(interf)o(ace)h(recei)n(v)o (e)f(instances)i(of)f(this)h(e)o(xception,)e(it)208 4034 y(is)i(not)f(required)e(to)i(actually)g(raise)g(the)h(e)o(xception)d (\227)j(it)g(is)g(also)f(useful)g(as)h(a)f(container)f(for)h (information.)208 4167 y(When)g(instantiated,)g FK(msg)h FN(should)e(be)i(a)g(human-readable)16 b(description)j(of)i(the)f (error)-5 b(.)26 b(The)20 b(optional)f FK(e)n(xception)h FN(parameter)m(,)208 4266 y(if)28 b(gi)n(v)o(en,)h(should)e(be)h FJ(None)g FN(or)g(an)g(e)o(xception)e(that)j(w)o(as)g(caught)e(by)h (the)g(parsing)f(code)g(and)h(is)h(being)f(passed)g(along)f(as)208 4366 y(information.)208 4499 y(This)20 b(is)h(the)f(base)h(class)g(for) e(the)h(other)g(SAX)h(e)o(xception)d(classes.)0 4646 y FL(exception)h FD(SAXParseException)p FJ(\()p FK(msg)o(,)e(e)n (xception,)i(locator)r FJ(\))208 4745 y FN(Subclass)25 b(of)h FJ(SAXException)e FN(raised)i(on)f(parse)h(errors.)40 b(Instances)26 b(of)f(this)h(class)h(are)f(passed)g(to)g(the)f(methods) g(of)h(the)208 4845 y(SAX)j FJ(ErrorHandler)e FN(interf)o(ace)h(to)h (pro)o(vide)e(information)f(about)i(the)h(parse)f(error)-5 b(.)51 b(This)29 b(class)g(supports)f(the)h(SAX)208 4944 y FJ(Locator)19 b FN(interf)o(ace)g(as)i(well)g(as)g(the)f FJ(SAXException)f FN(interf)o(ace.)0 5091 y FL(exception)g FD(SAXNotRecognizedException)p FJ(\()p FK(msg)p FC([)p FK(,)d(e)n(xception)c FC(])p FJ(\))208 5191 y FN(Subclass)22 b(of)g FJ(SAXException)e FN(raised)i(when)g(a)g(SAX)h FJ(XMLReader)e FN(is)i(confronted)c(with)k(an)f(unrecognized)d(feature) i(or)208 5291 y(property)-5 b(.)22 b(SAX)f(applications)e(and)g(e)o (xtensions)g(may)h(use)h(this)f(class)h(for)f(similar)g(purposes.)p 0 5549 3901 4 v 0 5649 a FI(288)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 289 301 TeXDict begin 289 300 bop 0 83 a FL(exception)19 b FD (SAXNotSupportedException)p FJ(\()p FK(msg)p FC([)p FK(,)d(e)n (xception)c FC(])p FJ(\))208 183 y FN(Subclass)k(of)f FJ(SAXException)f FN(raised)i(when)f(a)i(SAX)f FJ(XMLReader)f FN(is)i(ask)o(ed)e(to)h(enable)f(a)i(feature)e(that)g(is)i(not)f (supported,)208 282 y(or)21 b(to)h(set)h(a)g(property)c(to)k(a)f(v)n (alue)f(that)h(the)g(implementation)e(does)i(not)f(support.)29 b(SAX)23 b(applications)e(and)g(e)o(xtensions)g(may)208 382 y(use)f(this)h(class)g(for)e(similar)i(purposes.)0 529 y FL(See)g(Also:)0 676 y FK(SAX:)e(The)i(Simple)e(API)h(for)h(XML)0 775 y Fy(\()p FO(http://www)l(.saxproject.org/)-6 b Fy(\))208 875 y FN(This)29 b(site)h(is)g(the)f(focal)g(point)f(for)g(the)i (de\002nition)e(of)g(the)h(SAX)h(API.)f(It)h(pro)o(vides)d(a)j(Ja)n(v)n (a)f(implementation)e(and)h(online)208 975 y(documentation.)22 b(Links)d(to)i(implementations)d(and)i(historical)f(information)f(are)i (also)h(a)n(v)n(ailable.)0 1121 y(Module)e FJ(xml.sax.handler)f FN(\(section)i(8.10\):)208 1221 y(De\002nitions)f(of)h(the)g(interf)o (aces)g(for)g(application-pro)o(vided)15 b(objects.)0 1368 y(Module)k FJ(xml.sax.saxutils)f FN(\(section)h(8.11\):)208 1468 y(Con)m(v)o(enience)e(functions)i(for)h(use)g(in)g(SAX)h (applications.)0 1614 y(Module)e FJ(xml.sax.xmlreader)f FN(\(section)h(8.12\):)208 1714 y(De\002nitions)g(of)h(the)g(interf)o (aces)g(for)g(parser)n(-pro)o(vided)c(objects.)0 1999 y Fv(8.9.1)100 b(SAXException)31 b(Objects)0 2202 y FN(The)20 b FJ(SAXException)e FN(e)o(xception)h(class)i(supports)e(the)h(follo)n (wing)f(methods:)0 2349 y FD(getMessage)p FJ(\(\))208 2448 y FN(Return)g(a)i(human-readable)16 b(message)21 b(describing)d(the)i(error)f(condition.)0 2595 y FD(getException)p FJ(\(\))208 2695 y FN(Return)g(an)h(encapsulated)f(e)o(xception)f (object,)i(or)g FJ(None)p FN(.)0 3022 y FE(8.10)121 b Fx(xml.sax.handler)29 b FE(\227)k(Base)h(classes)f(f)l(or)h(SAX)e (handlers)0 3255 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 3402 y(The)25 b(SAX)i(API)e(de\002nes)h(four)e(kinds)h(of)h(handlers:) 35 b(content)24 b(handlers,)i(DTD)g(handlers,)f(error)g(handlers,)g (and)g(entity)h(resolv)o(ers.)0 3502 y(Applications)15 b(normally)f(only)i(need)f(to)h(implement)f(those)h(interf)o(aces)g (whose)f(e)n(v)o(ents)h(the)o(y)f(are)h(interested)g(in;)i(the)o(y)d (can)h(implement)0 3601 y(the)23 b(interf)o(aces)f(in)h(a)g(single)g (object)f(or)h(in)g(multiple)f(objects.)32 b(Handler)22 b(implementations)f(should)h(inherit)g(from)g(the)h(base)f(classes)0 3701 y(pro)o(vided)c(in)i(the)g(module)f FJ(xml.sax.handler)p FN(,)f(so)i(that)h(all)f(methods)f(get)i(def)o(ault)e(implementations.) 0 3848 y FL(class)i FD(ContentHandler)208 3947 y FN(This)h(is)h(the)g (main)f(callback)f(interf)o(ace)h(in)g(SAX,)h(and)f(the)g(one)g(most)h (important)e(to)h(applications.)30 b(The)22 b(order)g(of)g(e)n(v)o (ents)f(in)208 4047 y(this)f(interf)o(ace)g(mirrors)f(the)h(order)f(of) h(the)g(information)e(in)i(the)g(document.)0 4194 y FL(class)h FD(DTDHandler)208 4293 y FN(Handle)e(DTD)h(e)n(v)o(ents.)208 4426 y(This)g(interf)o(ace)f(speci\002es)i(only)e(those)h(DTD)h(e)n(v)o (ents)e(required)g(for)g(basic)i(parsing)e(\(unparsed)f(entities)i(and) g(attrib)n(utes\).)0 4573 y FL(class)h FD(EntityResolver)208 4673 y FN(Basic)e(interf)o(ace)e(for)h(resolving)e(entities.)25 b(If)18 b(you)f(create)h(an)g(object)g(implementing)e(this)i(interf)o (ace,)g(then)f(re)o(gister)h(the)g(object)208 4772 y(with)i(your)f(P)o (arser)m(,)g(the)h(parser)g(will)h(call)g(the)f(method)f(in)h(your)f (object)h(to)g(resolv)o(e)f(all)i(e)o(xternal)e(entities.)0 4919 y FL(class)i FD(ErrorHandler)208 5019 y FN(Interf)o(ace)16 b(used)h(by)g(the)g(parser)g(to)h(present)e(error)h(and)f(w)o(arning)h (messages)g(to)h(the)f(application.)23 b(The)17 b(methods)f(of)h(this)h (object)208 5119 y(control)h(whether)g(errors)g(are)h(immediately)f (con)m(v)o(erted)f(to)i(e)o(xceptions)f(or)g(are)i(handled)d(in)i(some) g(other)g(w)o(ay)-5 b(.)0 5265 y(In)20 b(addition)f(to)h(these)h (classes,)g FJ(xml.sax.handler)d FN(pro)o(vides)g(symbolic)h(constants) h(for)f(the)i(feature)e(and)h(property)e(names.)p 0 5549 3901 4 v 0 5649 a FI(8.10.)52 b FJ(xml.sax.handler)21 b FI(\227)i(Base)g(classes)f(f)n(or)g(SAX)i(handlers)1513 b(289)p eop end %%Page: 290 302 TeXDict begin 290 301 bop 0 83 a FD(feature_namespaces)208 183 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/namespac)o (es")208 282 y FN(true:)g(Perform)19 b(Namespace)h(processing.)208 382 y(f)o(alse:)25 b(Optionally)19 b(do)h(not)g(perform)e(Namespace)h (processing)g(\(implies)h(namespace-pre\002x)o(es;)d(def)o(ault\).)208 482 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g (read/write)0 628 y FD(feature_namespace_prefixes)208 728 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/namespac)o (e-pref)o(ixes")208 828 y FN(true:)g(Report)c(the)g(original)f (pre\002x)o(ed)g(names)h(and)g(attrib)n(utes)g(used)g(for)f(Namespace)h (declarations.)208 927 y(f)o(alse:)32 b(Do)24 b(not)f(report)g(attrib)n (utes)h(used)f(for)g(Namespace)g(declarations,)g(and)g(optionally)f(do) i(not)f(report)g(original)f(pre\002x)o(ed)208 1027 y(names)d(\(def)o (ault\).)208 1127 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h (parsing\))g(read/write)0 1273 y FD(feature_string_interning)208 1373 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/string-i)o (nterni)o(ng")208 1473 y FN(true:)37 b(All)27 b(element)f(names,)h (pre\002x)o(es,)g(attrib)n(ute)f(names,)h(Namespace)f(URIs,)i(and)e (local)g(names)g(are)h(interned)e(using)h(the)208 1572 y(b)n(uilt-in)19 b(intern)h(function.)208 1672 y(f)o(alse:)25 b(Names)c(are)f(not)g(necessarily)f(interned,)g(although)f(the)o(y)i (may)f(be)h(\(def)o(ault\).)208 1772 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g(read/write)0 1918 y FD(feature_validation)208 2018 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/validati)o(on")208 2118 y FN(true:)g(Report)c(all)h(v)n(alidation)e(errors)g(\(implies)h (e)o(xternal-general-entities)c(and)k(e)o(xternal-parameter)n (-entities\).)208 2217 y(f)o(alse:)25 b(Do)20 b(not)g(report)f(v)n (alidation)g(errors.)208 2317 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g(read/write)0 2464 y FD(feature_external_ges)208 2563 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/external)o(-gener)o(al-en)o(tities)o (")208 2663 y FN(true:)g(Include)19 b(all)i(e)o(xternal)e(general)g (\(te)o(xt\))g(entities.)208 2763 y(f)o(alse:)25 b(Do)20 b(not)g(include)g(e)o(xternal)e(general)i(entities.)208 2862 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g (read/write)0 3009 y FD(feature_external_pes)208 3109 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/features/external)o (-param)o(eter-)o(entiti)o(es")208 3208 y FN(true:)g(Include)19 b(all)i(e)o(xternal)e(parameter)g(entities,)h(including)e(the)j(e)o (xternal)d(DTD)j(subset.)208 3308 y(f)o(alse:)k(Do)20 b(not)g(include)g(an)o(y)f(e)o(xternal)g(parameter)g(entities,)h(e)n(v) o(en)f(the)h(e)o(xternal)f(DTD)i(subset.)208 3408 y(access:)k (\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g(read/write)0 3555 y FD(all_features)208 3654 y FN(List)h(of)g(all)h(features.)0 3801 y FD(property_lexical_handler)208 3901 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/properties/lexica)o(l-hand)o(ler") 208 4000 y FN(data)c(type:)k(xml.sax.sax2lib)m(.Le)o(xicalHandler)15 b(\(not)k(supported)g(in)h(Python)f(2\))208 4100 y(description:)k(An)e (optional)d(e)o(xtension)h(handler)g(for)g(le)o(xical)h(e)n(v)o(ents)g (lik)o(e)g(comments.)208 4200 y(access:)25 b(read/write)0 4346 y FD(property_declaration_handler)208 4446 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/properties/declar)o(ation-)o(handl) o(er")208 4546 y FN(data)c(type:)k(xml.sax.sax2lib)m(.DeclHandler)16 b(\(not)j(supported)g(in)h(Python)f(2\))208 4645 y(description:)k(An)e (optional)d(e)o(xtension)h(handler)g(for)g(DTD-related)g(e)n(v)o(ents)h (other)f(than)h(notations)f(and)h(unparsed)e(entities.)208 4745 y(access:)25 b(read/write)0 4892 y FD(property_dom_node)208 4991 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/properties/dom-no)o (de")208 5091 y FN(data)c(type:)k(or)o(g.w3c.dom.Node)15 b(\(not)20 b(supported)e(in)i(Python)f(2\))208 5191 y(description:)k (When)c(parsing,)g(the)g(current)f(DOM)i(node)f(being)f(visited)i(if)g (this)g(is)g(a)g(DOM)g(iterator;)f(when)g(not)g(parsing,)g(the)208 5290 y(root)g(DOM)i(node)e(for)g(iteration.)208 5390 y(access:)25 b(\(parsing\))19 b(read-only;)f(\(not)h(parsing\))g (read/write)p 0 5549 3901 4 v 0 5649 a FI(290)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 291 303 TeXDict begin 291 302 bop 0 83 a FD(property_xml_string)208 183 y FN(V)-9 b(alue:)24 b FJ("http://xml.org/sax/properties/xml-st)o (ring")208 282 y FN(data)c(type:)k(String)208 382 y(description:)f(The) d(literal)h(string)e(of)h(characters)g(that)g(w)o(as)h(the)f(source)g (for)f(the)h(current)f(e)n(v)o(ent.)208 482 y(access:)25 b(read-only)0 628 y FD(all_properties)208 728 y FN(List)20 b(of)g(all)h(kno)n(wn)e(property)f(names.)0 1010 y Fv(8.10.1)101 b(ContentHandler)30 b(Objects)0 1212 y FN(Users)20 b(are)g(e)o(xpected) e(to)h(subclass)h FJ(ContentHandler)e FN(to)i(support)e(their)h (application.)k(The)d(follo)n(wing)e(methods)g(are)i(called)f(by)0 1312 y(the)h(parser)g(on)g(the)g(appropriate)e(e)n(v)o(ents)h(in)i(the) f(input)f(document:)0 1459 y FD(setDocumentLocator)p FJ(\()p FK(locator)r FJ(\))208 1559 y FN(Called)h(by)g(the)g(parser)g (to)g(gi)n(v)o(e)f(the)i(application)d(a)j(locator)e(for)h(locating)f (the)h(origin)f(of)h(document)e(e)n(v)o(ents.)208 1688 y(SAX)j(parsers)g(are)g(strongly)f(encouraged)f(\(though)g(not)h (absolutely)g(required\))f(to)j(supply)e(a)i(locator:)k(if)21 b(it)h(does)f(so,)h(it)g(must)208 1787 y(supply)h(the)i(locator)e(to)i (the)g(application)e(by)h(in)m(v)n(oking)e(this)j(method)e(before)h(in) m(v)n(oking)e(an)o(y)i(of)g(the)h(other)e(methods)h(in)h(the)208 1887 y(DocumentHandler)17 b(interf)o(ace.)208 2016 y(The)f(locator)f (allo)n(ws)i(the)f(application)f(to)h(determine)f(the)h(end)g(position) g(of)g(an)o(y)f(document-related)e(e)n(v)o(ent,)j(e)n(v)o(en)f(if)i (the)f(parser)208 2116 y(is)k(not)e(reporting)f(an)i(error)-5 b(.)24 b(T)-7 b(ypically)i(,)18 b(the)h(application)e(will)j(use)f (this)h(information)c(for)j(reporting)e(its)j(o)n(wn)e(errors)g(\(such) h(as)208 2215 y(character)i(content)g(that)h(does)h(not)f(match)f(an)i (application')-5 b(s)21 b(b)n(usiness)i(rules\).)31 b(The)22 b(information)e(returned)g(by)i(the)g(locator)208 2315 y(is)f(probably)d(not)h(suf)n(\002cient)h(for)g(use)g(with)g(a)h (search)f(engine.)208 2444 y(Note)25 b(that)g(the)g(locator)g(will)h (return)e(correct)g(information)f(only)h(during)g(the)h(in)m(v)n (ocation)f(of)h(the)g(e)n(v)o(ents)f(in)i(this)g(interf)o(ace.)208 2544 y(The)19 b(application)g(should)g(not)h(attempt)g(to)g(use)h(it)g (at)f(an)o(y)g(other)f(time.)0 2690 y FD(startDocument)p FJ(\(\))208 2790 y FN(Recei)n(v)o(e)g(noti\002cation)g(of)h(the)h(be)o (ginning)c(of)j(a)h(document.)208 2919 y(The)c(SAX)g(parser)g(will)h (in)m(v)n(ok)o(e)e(this)i(method)e(only)h(once,)g(before)e(an)o(y)i (other)f(methods)h(in)g(this)h(interf)o(ace)e(or)i(in)f(DTDHandler)208 3019 y(\(e)o(xcept)h(for)i FJ(setDocumentLocator\(\))p FN(\).)0 3166 y FD(endDocument)p FJ(\(\))208 3265 y FN(Recei)n(v)o(e)f (noti\002cation)g(of)h(the)h(end)e(of)h(a)h(document.)208 3394 y(The)e(SAX)h(parser)f(will)h(in)m(v)n(ok)o(e)e(this)i(method)e (only)h(once,)g(and)g(it)h(will)g(be)f(the)h(last)g(method)e(in)m(v)n (ok)o(ed)g(during)g(the)h(parse.)25 b(The)208 3494 y(parser)20 b(shall)i(not)f(in)m(v)n(ok)o(e)f(this)i(method)e(until)h(it)h(has)f (either)g(abandoned)e(parsing)h(\(because)g(of)h(an)g(unreco)o(v)o (erable)d(error\))i(or)208 3594 y(reached)e(the)j(end)e(of)h(input.)0 3741 y FD(startPrefixMapping)p FJ(\()p FK(pr)m(e\002x,)c(uri)p FJ(\))208 3840 y FN(Be)o(gin)j(the)i(scope)e(of)h(a)h(pre\002x-URI)e (Namespace)g(mapping.)208 3969 y(The)h(information)e(from)i(this)i(e)n (v)o(ent)e(is)h(not)g(necessary)f(for)g(normal)g(Namespace)g (processing:)25 b(the)c(SAX)g(XML)g(reader)f(will)208 4069 y(automatically)j(replace)i(pre\002x)o(es)f(for)h(element)f(and)h (attrib)n(ute)f(names)h(when)g(the)g FJ(feature_namespaces)d FN(feature)j(is)208 4168 y(enabled)19 b(\(the)g(def)o(ault\).)208 4298 y(There)h(are)i(cases,)h(ho)n(we)n(v)o(er)m(,)c(when)i (applications)g(need)g(to)h(use)f(pre\002x)o(es)g(in)h(character)f (data)g(or)h(in)f(attrib)n(ute)h(v)n(alues,)f(where)208 4397 y(the)o(y)14 b(cannot)h(safely)g(be)h(e)o(xpanded)d (automatically;)i(the)h FJ(startPrefixMapping\(\))c FN(and)j FJ(endPrefixMapping\(\))208 4497 y FN(e)n(v)o(ents)k(supply)g(the)h (information)e(to)j(the)f(application)f(to)h(e)o(xpand)e(pre\002x)o(es) i(in)g(those)g(conte)o(xts)f(itself,)i(if)f(necessary)-5 b(.)208 4626 y(Note)25 b(that)h FJ(startPrefixMapping\(\))d FN(and)i FJ(endPrefixMapping\(\))e FN(e)n(v)o(ents)i(are)h(not)g (guaranteed)d(to)j(be)g(prop-)208 4726 y(erly)h(nested)h(relati)n(v)o (e)f(to)h(each-other:)39 b(all)29 b FJ(startPrefixMapping\(\))c FN(e)n(v)o(ents)i(will)i(occur)e(before)f(the)i(correspond-)208 4825 y(ing)h FJ(startElement\(\))g FN(e)n(v)o(ent,)i(and)f(all)h FJ(endPrefixMapping\(\))c FN(e)n(v)o(ents)j(will)h(occur)e(after)h(the) g(corresponding)208 4925 y FJ(endElement\(\))18 b FN(e)n(v)o(ent,)h(b)n (ut)h(their)g(order)f(is)i(not)f(guaranteed.)0 5072 y FD(endPrefixMapping)p FJ(\()p FK(pr)m(e\002x)p FJ(\))208 5171 y FN(End)f(the)h(scope)g(of)g(a)h(pre\002x-URI)e(mapping.)208 5300 y(See)52 b FJ(startPrefixMapping\(\))d FN(for)i(details.)121 b(This)52 b(e)n(v)o(ent)f(will)i(al)o(w)o(ays)f(occur)f(after)h(the)g (corresponding)208 5400 y FJ(endElement\(\))18 b FN(e)n(v)o(ent,)h(b)n (ut)h(the)g(order)f(of)h FJ(endPrefixMapping\(\))e FN(e)n(v)o(ents)h (is)i(not)f(otherwise)g(guaranteed.)p 0 5549 3901 4 v 0 5649 a FI(8.10.)52 b FJ(xml.sax.handler)21 b FI(\227)i(Base)g (classes)f(f)n(or)g(SAX)i(handlers)1513 b(291)p eop end %%Page: 292 304 TeXDict begin 292 303 bop 0 83 a FD(startElement)p FJ(\()p FK(name)o(,)17 b(attr)o(s)p FJ(\))208 183 y FN(Signals)j(the)g(start)h (of)f(an)g(element)f(in)i(non-namespace)c(mode.)208 315 y(The)25 b FK(name)h FN(parameter)e(contains)i(the)g(ra)o(w)g(XML)g (1.0)f(name)g(of)h(the)g(element)g(type)f(as)i(a)g(string)e(and)h(the)g FK(attr)o(s)h FN(parameter)208 415 y(holds)e(an)g(object)h(of)f(the)h FJ(Attributes)e FN(interf)o(ace)h(containing)f(the)i(attrib)n(utes)f (of)h(the)g(element.)41 b(The)25 b(object)g(passed)h(as)208 515 y FK(attr)o(s)g FN(may)g(be)f(re-used)g(by)g(the)h(parser;)i (holding)c(on)h(to)h(a)g(reference)e(to)i(it)h(is)f(not)g(a)g(reliable) f(w)o(ay)h(to)g(k)o(eep)f(a)h(cop)o(y)f(of)h(the)208 614 y(attrib)n(utes.)e(T)-7 b(o)21 b(k)o(eep)e(a)i(cop)o(y)e(of)h(the)g (attrib)n(utes,)g(use)h(the)f FJ(copy\(\))g FN(method)e(of)i(the)h FK(attr)o(s)g FN(object.)0 761 y FD(endElement)p FJ(\()p FK(name)p FJ(\))208 861 y FN(Signals)f(the)g(end)g(of)g(an)g(element)f (in)i(non-namespace)c(mode.)208 994 y(The)i FK(name)h FN(parameter)f(contains)g(the)h(name)g(of)g(the)g(element)g(type,)f (just)i(as)g(with)f(the)g FJ(startElement\(\))e FN(e)n(v)o(ent.)0 1141 y FD(startElementNS)p FJ(\()p FK(name)o(,)f(qname)o(,)i(attr)o(s)p FJ(\))208 1240 y FN(Signals)h(the)g(start)h(of)f(an)g(element)f(in)i (namespace)e(mode.)208 1373 y(The)g FK(name)g FN(parameter)g(contains)g (the)h(name)f(of)h(the)g(element)f(type)h(as)g(a)h FJ(\()p FK(uri)p FJ(,)49 b FK(localname)p FJ(\))18 b FN(tuple,)h(the)h FK(qname)f FN(parameter)208 1473 y(contains)28 b(the)h(ra)o(w)g(XML)g (1.0)f(name)h(used)g(in)g(the)g(source)f(document,)h(and)g(the)g FK(attr)o(s)h FN(parameter)e(holds)g(an)h(instance)g(of)208 1572 y(the)21 b FJ(AttributesNS)f FN(interf)o(ace)h(containing)f(the)i (attrib)n(utes)f(of)h(the)f(element.)29 b(If)22 b(no)f(namespace)g(is)h (associated)g(with)g(the)208 1672 y(element,)k(the)f FK(uri)h FN(component)e(of)h FK(name)g FN(will)h(be)g FJ(None)p FN(.)41 b(The)25 b(object)g(passed)h(as)g FK(attr)o(s)h FN(may)e(be)h(re-used)e(by)h(the)h(parser;)208 1772 y(holding)h(on)h (to)h(a)g(reference)e(to)i(it)g(is)h(not)e(a)h(reliable)f(w)o(ay)h(to)g (k)o(eep)f(a)h(cop)o(y)f(of)g(the)h(attrib)n(utes.)50 b(T)-7 b(o)29 b(k)o(eep)f(a)h(cop)o(y)f(of)h(the)208 1871 y(attrib)n(utes,)19 b(use)i(the)f FJ(copy\(\))g FN(method)e(of)i(the)h FK(attr)o(s)g FN(object.)208 2004 y(P)o(arsers)31 b(may)g(set)i(the)f FK(qname)e FN(parameter)g(to)i FJ(None)p FN(,)i(unless)e(the)g FJ(feature_namespace_prefixes)27 b FN(feature)k(is)208 2104 y(acti)n(v)n(ated.)0 2250 y FD(endElementNS)p FJ(\()p FK(name)o(,)17 b(qname)p FJ(\))208 2350 y FN(Signals)j(the)g(end)g(of)g(an)g(element)f(in)i (namespace)e(mode.)208 2483 y(The)25 b FK(name)f FN(parameter)g (contains)h(the)h(name)e(of)i(the)f(element)g(type,)h(just)g(as)g(with) g(the)f FJ(startElementNS\(\))e FN(method,)208 2583 y(lik)o(e)n(wise)d (the)g FK(qname)f FN(parameter)-5 b(.)0 2729 y FD(characters)p FJ(\()p FK(content)q FJ(\))208 2829 y FN(Recei)n(v)o(e)19 b(noti\002cation)g(of)h(character)f(data.)208 2962 y(The)h(P)o(arser)h (will)h(call)g(this)g(method)e(to)h(report)f(each)h(chunk)f(of)h (character)e(data.)28 b(SAX)22 b(parsers)f(may)g(return)f(all)i (contiguous)208 3062 y(character)g(data)i(in)g(a)g(single)g(chunk,)f (or)h(the)o(y)f(may)g(split)i(it)g(into)e(se)n(v)o(eral)g(chunks;)i(ho) n(we)n(v)o(er)m(,)d(all)j(of)e(the)h(characters)f(in)h(an)o(y)208 3161 y(single)c(e)n(v)o(ent)f(must)h(come)g(from)f(the)h(same)g(e)o (xternal)f(entity)h(so)h(that)f(the)g(Locator)f(pro)o(vides)g(useful)g (information.)208 3294 y FK(content)h FN(may)g(be)g(a)h(Unicode)e (string)h(or)g(a)g(byte)g(string;)g(the)g FJ(expat)g FN(reader)f(module)g(produces)f(al)o(w)o(ays)j(Unicode)e(strings.)208 3427 y FL(Note:)29 b FN(The)22 b(earlier)g(SAX)i(1)e(interf)o(ace)g (pro)o(vided)e(by)j(the)f(Python)g(XML)g(Special)h(Interest)f(Group)g (used)g(a)h(more)f(Ja)n(v)n(a-lik)o(e)208 3526 y(interf)o(ace)i(for)g (this)i(method.)38 b(Since)25 b(most)g(parsers)g(used)g(from)f(Python)g (did)h(not)f(tak)o(e)h(adv)n(antage)f(of)g(the)h(older)g(interf)o(ace,) 208 3626 y(the)d(simpler)g(signature)f(w)o(as)i(chosen)e(to)h(replace)g (it.)31 b(T)-7 b(o)22 b(con)m(v)o(ert)f(old)g(code)h(to)g(the)g(ne)n(w) g(interf)o(ace,)g(use)g FK(content)h FN(instead)f(of)208 3726 y(slicing)e(content)f(with)h(the)g(old)g FK(of)o(fset)i FN(and)e FK(length)f FN(parameters.)0 3873 y FD(ignorableWhitespace)p FJ(\()p FK(whitespace)p FJ(\))208 3972 y FN(Recei)n(v)o(e)g (noti\002cation)g(of)h(ignorable)f(whitespace)g(in)i(element)e (content.)208 4105 y(V)-9 b(alidating)22 b(P)o(arsers)h(must)g(use)g (this)h(method)e(to)h(report)f(each)h(chunk)f(of)h(ignorable)e (whitespace)h(\(see)i(the)f(W3C)h(XML)f(1.0)208 4205 y(recommendation,)18 b(section)k(2.10\):)28 b(non-v)n(alidating)19 b(parsers)j(may)f(also)i(use)f(this)h(method)e(if)h(the)o(y)f(are)h (capable)g(of)g(parsing)208 4304 y(and)d(using)h(content)f(models.)208 4437 y(SAX)24 b(parsers)g(may)g(return)f(all)i(contiguous)d(whitespace) i(in)g(a)h(single)f(chunk,)g(or)g(the)o(y)f(may)h(split)h(it)g(into)f (se)n(v)o(eral)g(chunks;)208 4537 y(ho)n(we)n(v)o(er)m(,)c(all)k(of)e (the)h(characters)e(in)i(an)o(y)f(single)h(e)n(v)o(ent)e(must)i(come)f (from)g(the)h(same)f(e)o(xternal)g(entity)-5 b(,)22 b(so)h(that)g(the)g (Locator)208 4636 y(pro)o(vides)18 b(useful)i(information.)0 4783 y FD(processingInstruction)p FJ(\()p FK(tar)m(g)o(et,)c(data)p FJ(\))208 4883 y FN(Recei)n(v)o(e)j(noti\002cation)g(of)h(a)h (processing)e(instruction.)208 5016 y(The)f(P)o(arser)h(will)g(in)m(v)n (ok)o(e)f(this)h(method)e(once)i(for)f(each)g(processing)g(instruction) f(found:)23 b(note)18 b(that)h(processing)f(instructions)208 5115 y(may)h(occur)g(before)g(or)h(after)g(the)g(main)g(document)e (element.)208 5248 y(A)j(SAX)h(parser)f(should)f(ne)n(v)o(er)g(report)g (an)h(XML)h(declaration)d(\(XML)i(1.0,)g(section)g(2.8\))f(or)h(a)h(te) o(xt)f(declaration)f(\(XML)g(1.0,)208 5348 y(section)g(4.3.1\))e(using) i(this)g(method.)p 0 5549 3901 4 v 0 5649 a FI(292)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T) -10 b(ools)p eop end %%Page: 293 305 TeXDict begin 293 304 bop 0 83 a FD(skippedEntity)p FJ(\()p FK(name)p FJ(\))208 183 y FN(Recei)n(v)o(e)19 b(noti\002cation)g(of)h (a)h(skipped)e(entity)-5 b(.)208 315 y(The)20 b(P)o(arser)g(will)h(in)m (v)n(ok)o(e)e(this)i(method)e(once)h(for)g(each)g(entity)g(skipped.)25 b(Non-v)n(alidating)18 b(processors)h(may)h(skip)g(entities)h(if)208 415 y(the)o(y)h(ha)n(v)o(e)g(not)g(seen)h(the)f(declarations)g (\(because,)g(for)g(e)o(xample,)f(the)i(entity)f(w)o(as)i(declared)d (in)i(an)g(e)o(xternal)e(DTD)i(subset\).)208 515 y(All)e(processors)f (may)g(skip)h(e)o(xternal)e(entities,)j(depending)c(on)i(the)h(v)n (alues)f(of)h(the)g FJ(feature_external_ges)c FN(and)k(the)208 614 y FJ(feature_external_pes)c FN(properties.)0 899 y Fv(8.10.2)101 b(DTDHandler)29 b(Objects)0 1102 y FJ(DTDHandler)19 b FN(instances)h(pro)o(vide)e(the)i(follo)n(wing)f(methods:)0 1249 y FD(notationDecl)p FJ(\()p FK(name)o(,)e(publicId,)h(systemId)r FJ(\))208 1349 y FN(Handle)h(a)i(notation)e(declaration)f(e)n(v)o(ent.) 0 1496 y FD(unparsedEntityDecl)p FJ(\()p FK(name)o(,)e(publicId,)i (systemId,)i(ndata)p FJ(\))208 1595 y FN(Handle)f(an)h(unparsed)f (entity)h(declaration)e(e)n(v)o(ent.)0 1880 y Fv(8.10.3)101 b(EntityResolv)n(er)28 b(Objects)0 2069 y FD(resolveEntity)p FJ(\()p FK(publicId,)16 b(systemId)r FJ(\))208 2169 y FN(Resolv)o(e)23 b(the)h(system)g(identi\002er)f(of)g(an)h(entity)f (and)g(return)g(either)g(the)h(system)g(identi\002er)f(to)h(read)f (from)g(as)h(a)g(string,)g(or)g(an)208 2268 y(InputSource)17 b(to)j(read)g(from.)k(The)c(def)o(ault)f(implementation)f(returns)i FK(systemId)r FN(.)0 2553 y Fv(8.10.4)101 b(ErrorHandler)30 b(Objects)0 2756 y FN(Objects)22 b(with)f(this)h(interf)o(ace)e(are)i (used)f(to)g(recei)n(v)o(e)g(error)f(and)h(w)o(arning)f(information)f (from)h(the)i FJ(XMLReader)p FN(.)27 b(If)21 b(you)g(create)g(an)0 2856 y(object)f(that)g(implements)f(this)i(interf)o(ace,)f(then)f(re)o (gister)h(the)g(object)g(with)h(your)e FJ(XMLReader)p FN(,)g(the)h(parser)g(will)h(call)f(the)h(methods)0 2955 y(in)32 b(your)f(object)h(to)h(report)e(all)h(w)o(arnings)g(and)g (errors.)60 b(There)31 b(are)h(three)g(le)n(v)o(els)g(of)g(errors)g(a)n (v)n(ailable:)49 b(w)o(arnings,)34 b(\(possibly\))0 3055 y(reco)o(v)o(erable)27 b(errors,)32 b(and)d(unreco)o(v)o(erable)d (errors.)54 b(All)30 b(methods)f(tak)o(e)h(a)h FJ(SAXParseException)c FN(as)k(the)f(only)f(parameter)-5 b(.)0 3154 y(Errors)19 b(and)h(w)o(arnings)f(may)h(be)g(con)m(v)o(erted)e(to)i(an)g(e)o (xception)e(by)i(raising)g(the)g(passed-in)f(e)o(xception)g(object.)0 3301 y FD(error)p FJ(\()p FK(e)n(xception)p FJ(\))208 3401 y FN(Called)j(when)f(the)g(parser)g(encounters)f(a)i(reco)o(v)o (erable)d(error)-5 b(.)29 b(If)21 b(this)h(method)e(does)i(not)f(raise) h(an)g(e)o(xception,)d(parsing)i(may)208 3501 y(continue,)i(b)n(ut)h (further)e(document)g(information)g(should)h(not)g(be)h(e)o(xpected)f (by)g(the)h(application.)35 b(Allo)n(wing)23 b(the)h(parser)f(to)208 3600 y(continue)18 b(may)i(allo)n(w)g(additional)f(errors)g(to)i(be)f (disco)o(v)o(ered)e(in)i(the)g(input)g(document.)0 3747 y FD(fatalError)p FJ(\()p FK(e)n(xception)p FJ(\))208 3847 y FN(Called)k(when)g(the)g(parser)f(encounters)g(an)h(error)f(it)i (cannot)e(reco)o(v)o(er)f(from;)j(parsing)e(is)i(e)o(xpected)e(to)h (terminate)f(when)h(this)208 3946 y(method)18 b(returns.)0 4093 y FD(warning)p FJ(\()p FK(e)n(xception)p FJ(\))208 4193 y FN(Called)k(when)g(the)h(parser)e(presents)i(minor)e(w)o(arning) g(information)f(to)j(the)f(application.)30 b(P)o(arsing)22 b(is)i(e)o(xpected)c(to)j(continue)208 4292 y(when)f(this)h(method)f (returns,)g(and)g(document)f(information)g(will)i(continue)f(to)h(be)f (passed)h(to)g(the)g(application.)31 b(Raising)24 b(an)208 4392 y(e)o(xception)18 b(in)i(this)h(method)e(will)i(cause)f(parsing)f (to)h(end.)0 4720 y FE(8.11)121 b Fx(xml.sax.saxutils)29 b FE(\227)k(SAX)f(Utilities)0 4952 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.0.)0 5099 y(The)32 b(module)g FJ(xml.sax.saxutils)e FN(contains)i(a)h(number)e(of)h(classes)i(and)e(functions)f(that)i(are) g(commonly)d(useful)i(when)0 5199 y(creating)19 b(SAX)i(applications,)e (either)h(in)g(direct)g(use,)g(or)g(as)h(base)f(classes.)p 0 5549 3901 4 v 0 5649 a FI(8.11.)52 b FJ(xml.sax.saxutils)20 b FI(\227)j(SAX)i(Utilities)2144 b(293)p eop end %%Page: 294 306 TeXDict begin 294 305 bop 0 83 a FD(escape)p FJ(\()p FK(data)p FC([)p FK(,)18 b(entities)12 b FC(])p FJ(\))208 183 y FN(Escape)19 b(`)p FJ(&)p FN(',)h(`)p FJ(<)p FN(',)g(and)f(`)p FJ(>)p FN(')h(in)h(a)f(string)g(of)g(data.)208 314 y(Y)-9 b(ou)25 b(can)g(escape)g(other)g(strings)h(of)f(data)h(by)f(passing)g (a)h(dictionary)e(as)i(the)g(optional)e FK(entities)i FN(parameter)-5 b(.)41 b(The)25 b(k)o(e)o(ys)g(and)208 413 y(v)n(alues)19 b(must)i(all)f(be)g(strings;)h(each)f(k)o(e)o(y)f (will)i(be)f(replaced)f(with)i(its)g(corresponding)16 b(v)n(alue.)0 560 y FD(unescape)p FJ(\()p FK(data)p FC([)p FK(,)h(entities)12 b FC(])p FJ(\))208 660 y FN(Unescape)19 b(`)p FJ(&amp;)p FN(',)g(`)p FJ(&lt;)p FN(',)g(and)h(`)p FJ(&gt;)p FN(')f(in)h(a)h(string)f(of)g(data.)208 791 y(Y)-9 b(ou)20 b(can)i(unescape)e(other)h(strings)g(of)g(data)h(by)f (passing)g(a)h(dictionary)d(as)k(the)e(optional)f FK(entities)i FN(parameter)-5 b(.)28 b(The)21 b(k)o(e)o(ys)g(and)208 890 y(v)n(alues)e(must)i(all)f(be)g(strings;)h(each)f(k)o(e)o(y)f(will) i(be)f(replaced)f(with)i(its)g(corresponding)16 b(v)n(alue.)208 1021 y(Ne)n(w)k(in)g(v)o(ersion)f(2.3.)0 1168 y FD(quoteattr)p FJ(\()p FK(data)p FC([)p FK(,)e(entities)12 b FC(])p FJ(\))208 1268 y FN(Similar)20 b(to)h FJ(escape\(\))p FN(,)e(b)n(ut)i(also)f(prepares)g FK(data)f FN(to)i(be)f(used)h(as)g (an)f(attrib)n(ute)g(v)n(alue.)26 b(The)20 b(return)f(v)n(alue)h(is)h (a)g(quoted)e(v)o(er)n(-)208 1367 y(sion)i(of)g FK(data)g FN(with)h(an)o(y)f(additional)f(required)g(replacements.)27 b FJ(quoteattr\(\))20 b FN(will)j(select)f(a)g(quote)e(character)h (based)g(on)208 1467 y(the)f(content)g(of)g FK(data)p FN(,)f(attempting)h(to)g(a)n(v)n(oid)h(encoding)d(an)o(y)i(quote)g (characters)f(in)i(the)f(string.)26 b(If)21 b(both)e(single-)h(and)g (double-)208 1566 y(quote)i(characters)g(are)i(already)e(in)h FK(data)p FN(,)g(the)h(double-quote)c(characters)i(will)i(be)f(encoded) f(and)h FK(data)f FN(will)i(be)g(wrapped)d(in)208 1666 y(double-quotes.)g(The)f(resulting)g(string)g(can)f(be)i(used)f (directly)f(as)i(an)f(attrib)n(ute)g(v)n(alue:)444 1888 y FA(>>>)44 b(print)g("<element)f(attr=\045s>")h(\045)g(quoteattr\("ab) f(')i(cd)f(\\")h(ef"\))444 1980 y(<element)e(attr="ab)h(')g(cd)h (&quot;)f(ef">)208 2167 y FN(This)22 b(function)f(is)j(useful)e(when)g (generating)f(attrib)n(ute)i(v)n(alues)f(for)g(HTML)g(or)h(an)o(y)f (SGML)h(using)f(the)h(reference)e(concrete)208 2267 y(syntax.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 2414 y FL(class)i FD(XMLGenerator)p FJ(\()p FC([)p FK(out)q FC([)p FK(,)c(encoding)12 b FC(])g(])p FJ(\))208 2513 y FN(This)22 b(class)g(implements)f(the)h FJ(ContentHandler)e FN(interf)o(ace)h(by)g(writing)g(SAX)h(e)n(v)o (ents)g(back)f(into)g(an)h(XML)g(document.)208 2613 y(In)i(other)f(w)o (ords,)i(using)f(an)h FJ(XMLGenerator)e FN(as)i(the)f(content)g (handler)f(will)i(reproduce)d(the)j(original)e(document)g(being)208 2712 y(parsed.)30 b FK(out)23 b FN(should)e(be)i(a)f(\002le-lik)o(e)g (object)g(which)g(will)h(def)o(ault)e(to)i FK(sys.stdout)q FN(.)31 b FK(encoding)20 b FN(is)j(the)f(encoding)f(of)h(the)g(output) 208 2812 y(stream)e(which)f(def)o(aults)h(to)g FJ('iso-8859-1')p FN(.)0 2959 y FL(class)h FD(XMLFilterBase)p FJ(\()p FK(base)p FJ(\))208 3059 y FN(This)k(class)h(is)h(designed)d(to)h(sit)i(between)d (an)i FJ(XMLReader)e FN(and)h(the)g(client)h(application')-5 b(s)24 b(e)n(v)o(ent)g(handlers.)40 b(By)26 b(def)o(ault,)208 3158 y(it)d(does)f(nothing)f(b)n(ut)i(pass)g(requests)f(up)g(to)h(the)g (reader)e(and)h(e)n(v)o(ents)g(on)g(to)h(the)g(handlers)e (unmodi\002ed,)g(b)n(ut)i(subclasses)g(can)208 3258 y(o)o(v)o(erride)17 b(speci\002c)k(methods)e(to)h(modify)f(the)h(e)n(v)o(ent)f(stream)h(or) g(the)h(con\002guration)c(requests)j(as)h(the)o(y)e(pass)i(through.)0 3405 y FD(prepare_input_source)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)16 b(base)c FC(])p FJ(\))208 3504 y FN(This)29 b(function)e(tak)o(es)j(an)f(input)g(source)f(and)h(an)g(optional)f (base)h(URL)h(and)f(returns)f(a)i(fully)e(resolv)o(ed)g FJ(InputSource)208 3604 y FN(object)e(ready)g(for)g(reading.)44 b(The)27 b(input)f(source)g(can)h(be)g(gi)n(v)o(en)f(as)i(a)f(string,)h (a)f(\002le-lik)o(e)g(object,)h(or)f(an)g FJ(InputSource)208 3704 y FN(object;)18 b(parsers)g(will)h(use)g(this)f(function)f(to)h (implement)g(the)g(polymorphic)d FK(sour)m(ce)j FN(ar)o(gument)e(to)j (their)f FJ(parse\(\))f FN(method.)0 4029 y FE(8.12)121 b Fx(xml.sax.xmlreader)29 b FE(\227)k(Interf)l(ace)i(f)l(or)g(XML)e (parsers)0 4262 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 4409 y(SAX)k(parsers)f(implement)f(the)i FJ(XMLReader)e FN(interf)o(ace.)31 b(The)o(y)22 b(are)g(implemented)f(in)h(a)h(Python) f(module,)f(which)h(must)h(pro)o(vide)0 4509 y(a)h(function)f FJ(create_parser\(\))p FN(.)34 b(This)24 b(function)f(is)i(in)m(v)n(ok) o(ed)d(by)i FJ(xml.sax.make_parser\(\))c FN(with)25 b(no)e(ar)o (guments)f(to)0 4608 y(create)e(a)h(ne)n(w)f(parser)f(object.)0 4755 y FL(class)i FD(XMLReader)p FJ(\(\))208 4855 y FN(Base)g(class)g (which)f(can)f(be)i(inherited)e(by)g(SAX)i(parsers.)0 5001 y FL(class)g FD(IncrementalParser)p FJ(\(\))208 5101 y FN(In)d(some)h(cases,)g(it)h(is)f(desirable)f(not)h(to)f(parse)h (an)g(input)f(source)g(at)h(once,)f(b)n(ut)h(to)f(feed)h(chunks)e(of)i (the)f(document)f(as)j(the)o(y)e(get)208 5201 y(a)n(v)n(ailable.)23 b(Note)c(that)f(the)g(reader)f(will)i(normally)e(not)h(read)g(the)g (entire)g(\002le,)h(b)n(ut)f(read)g(it)h(in)f(chunks)f(as)i(well;)h (still)f FJ(parse\(\))208 5300 y FN(w)o(on')o(t)e(return)g(until)g(the) i(entire)e(document)f(is)k(processed.)j(So)18 b(these)g(interf)o(aces)g (should)f(be)h(used)g(if)g(the)g(blocking)f(beha)n(viour)208 5400 y(of)i FJ(parse\(\))h FN(is)h(not)f(desirable.)p 0 5549 3901 4 v 0 5649 a FI(294)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 295 307 TeXDict begin 295 306 bop 208 83 a FN(When)27 b(the)h(parser)f(is)i (instantiated)e(it)h(is)h(ready)e(to)g(be)o(gin)g(accepting)f(data)i (from)f(the)g(feed)h(method)e(immediately)-5 b(.)46 b(After)208 183 y(parsing)18 b(has)i(been)f(\002nished)g(with)h(a)g(call)g(to)g (close)g(the)f(reset)h(method)e(must)i(be)g(called)f(to)h(mak)o(e)f (the)h(parser)f(ready)f(to)i(accept)208 282 y(ne)n(w)g(data,)f(either)h (from)f(feed)h(or)g(using)g(the)g(parse)g(method.)208 407 y(Note)28 b(that)h(these)f(methods)g(must)g FK(not)h FN(be)f(called)g(during)f(parsing,)i(that)g(is,)i(after)e(parse)f(has)h (been)e(called)i(and)f(before)f(it)208 507 y(returns.)208 632 y(By)d(def)o(ault,)g(the)g(class)h(also)f(implements)g(the)g(parse) f(method)g(of)h(the)g(XMLReader)f(interf)o(ace)g(using)h(the)g(feed,)g (close)g(and)208 732 y(reset)c(methods)f(of)h(the)g(IncrementalP)o (arser)e(interf)o(ace)h(as)i(a)g(con)m(v)o(enience)c(to)j(SAX)h(2.0)e (dri)n(v)o(er)g(writers.)0 878 y FL(class)i FD(Locator)p FJ(\(\))208 978 y FN(Interf)o(ace)g(for)h(associating)g(a)h(SAX)g(e)n (v)o(ent)f(with)h(a)g(document)d(location.)32 b(A)23 b(locator)e(object)i(will)g(return)e(v)n(alid)h(results)h(only)208 1078 y(during)17 b(calls)j(to)f(DocumentHandler)d(methods;)j(at)h(an)o (y)e(other)h(time,)g(the)g(results)h(are)f(unpredictable.)j(If)d (information)e(is)j(not)208 1177 y(a)n(v)n(ailable,)f(methods)g(may)h (return)f FJ(None)p FN(.)0 1324 y FL(class)i FD(InputSource)p FJ(\()p FC([)p FK(systemId)11 b FC(])p FJ(\))208 1424 y FN(Encapsulation)18 b(of)i(the)g(information)e(needed)g(by)i(the)g FJ(XMLReader)g FN(to)g(read)g(entities.)208 1549 y(This)29 b(class)i(may)e(include)g(information)f(about)g(the)i(public)f (identi\002er)m(,)i(system)f(identi\002er)m(,)h(byte)e(stream)h (\(possibly)e(with)208 1649 y(character)18 b(encoding)h(information\))e (and/or)i(the)h(character)f(stream)h(of)g(an)g(entity)-5 b(.)208 1774 y(Applications)22 b(will)j(create)e(objects)h(of)f(this)h (class)h(for)e(use)h(in)g(the)g FJ(XMLReader.parse\(\))d FN(method)h(and)i(for)f(returning)208 1873 y(from)c(EntityResolv)o(er) -5 b(.resolv)o(eEntity)g(.)208 1998 y(An)30 b FJ(InputSource)f FN(belongs)g(to)i(the)f(application,)h(the)f FJ(XMLReader)g FN(is)h(not)f(allo)n(wed)g(to)g(modify)f FJ(InputSource)208 2098 y FN(objects)20 b(passed)g(to)g(it)h(from)e(the)h(application,)f (although)f(it)j(may)f(mak)o(e)f(copies)h(and)g(modify)e(those.)0 2245 y FL(class)j FD(AttributesImpl)p FJ(\()p FK(attr)o(s)p FJ(\))208 2344 y FN(This)i(is)i(an)f(implementation)d(of)j(the)f FJ(Attributes)g FN(interf)o(ace)g(\(see)g(section)h(8.12.5\).)33 b(This)24 b(is)h(a)f(dictionary-lik)o(e)d(object)208 2444 y(which)f(represents)h(the)g(element)f(attrib)n(utes)h(in)h(a)f FJ(startElement\(\))f FN(call.)28 b(In)21 b(addition)f(to)h(the)g(most) h(useful)e(dictionary)208 2544 y(operations,)26 b(it)h(supports)e(a)i (number)e(of)h(other)g(methods)f(as)j(described)d(by)h(the)g(interf)o (ace.)43 b(Objects)27 b(of)f(this)h(class)h(should)208 2643 y(be)22 b(instantiated)g(by)h(readers;)g FK(attr)o(s)h FN(must)f(be)g(a)g(dictionary-lik)o(e)d(object)j(containing)e(a)i (mapping)e(from)g(attrib)n(ute)i(names)f(to)208 2743 y(attrib)n(ute)d(v)n(alues.)0 2890 y FL(class)i FD(AttributesNSImpl)p FJ(\()p FK(attr)o(s,)d(qnames)p FJ(\))208 2989 y FN(Namespace-a)o(w)o (are)13 b(v)n(ariant)i(of)g FJ(AttributesImpl)p FN(,)g(which)g(will)h (be)g(passed)g(to)g FJ(startElementNS\(\))p FN(.)21 b(It)16 b(is)g(deri)n(v)o(ed)208 3089 y(from)k FJ(AttributesImpl)p FN(,)f(b)n(ut)i(understands)f(attrib)n(ute)h(names)g(as)h(tw)o (o-tuples)e(of)h FK(namespaceURI)i FN(and)e FK(localname)p FN(.)27 b(In)208 3189 y(addition,)c(it)i(pro)o(vides)e(a)i(number)d(of) i(methods)f(e)o(xpecting)g(quali\002ed)g(names)h(as)h(the)o(y)f(appear) f(in)h(the)h(original)e(document.)208 3288 y(This)d(class)h(implements) e(the)h FJ(AttributesNS)f FN(interf)o(ace)g(\(see)i(section)f (8.12.6\).)0 3566 y Fv(8.12.1)101 b(XMLReader)30 b(Objects)0 3769 y FN(The)20 b FJ(XMLReader)f FN(interf)o(ace)g(supports)g(the)i (follo)n(wing)d(methods:)0 3916 y FD(parse)p FJ(\()p FK(sour)m(ce)p FJ(\))208 4016 y FN(Process)e(an)g(input)f(source,)h (producing)d(SAX)k(e)n(v)o(ents.)23 b(The)15 b FK(sour)m(ce)h FN(object)g(can)g(be)g(a)g(system)g(identi\002er)g(\(a)g(string)g (identifying)208 4115 y(the)28 b(input)g(source)g(\226)h(typically)f(a) h(\002le)g(name)g(or)f(an)h(URL\),)f(a)i(\002le-lik)o(e)e(object,)i(or) f(an)g FJ(InputSource)e FN(object.)50 b(When)208 4215 y FJ(parse\(\))28 b FN(returns,)i(the)g(input)e(is)i(completely)e (processed,)i(and)f(the)g(parser)f(object)h(can)g(be)g(discarded)f(or)h (reset.)52 b(As)30 b(a)208 4314 y(limitation,)21 b(the)i(current)d (implementation)g(only)i(accepts)g(byte)f(streams;)j(processing)c(of)i (character)f(streams)i(is)g(for)e(further)208 4414 y(study)-5 b(.)0 4561 y FD(getContentHandler)p FJ(\(\))208 4661 y FN(Return)19 b(the)i(current)d FJ(ContentHandler)p FN(.)0 4807 y FD(setContentHandler)p FJ(\()p FK(handler)r FJ(\))208 4907 y FN(Set)i(the)h(current)d FJ(ContentHandler)p FN(.)23 b(If)d(no)g FJ(ContentHandler)e FN(is)j(set,)g(content)e(e)n(v) o(ents)h(will)h(be)f(discarded.)0 5054 y FD(getDTDHandler)p FJ(\(\))208 5154 y FN(Return)f(the)i(current)d FJ(DTDHandler)p FN(.)0 5300 y FD(setDTDHandler)p FJ(\()p FK(handler)r FJ(\))208 5400 y FN(Set)i(the)h(current)d FJ(DTDHandler)p FN(.)24 b(If)c(no)g FJ(DTDHandler)f FN(is)i(set,)g(DTD)f(e)n(v)o(ents)g (will)h(be)f(discarded.)p 0 5549 3901 4 v 0 5649 a FI(8.12.)52 b FJ(xml.sax.xmlreader)20 b FI(\227)j(Interf)n(ace)g(f)n(or)f(XML)i (parsers)1617 b(295)p eop end %%Page: 296 308 TeXDict begin 296 307 bop 0 83 a FD(getEntityResolver)p FJ(\(\))208 183 y FN(Return)19 b(the)i(current)d FJ(EntityResolver)p FN(.)0 330 y FD(setEntityResolver)p FJ(\()p FK(handler)r FJ(\))208 429 y FN(Set)g(the)g(current)e FJ(EntityResolver)p FN(.)22 b(If)17 b(no)h FJ(EntityResolver)d FN(is)k(set,)f(attempts)g (to)g(resolv)o(e)f(an)g(e)o(xternal)f(entity)i(will)208 529 y(result)i(in)g(opening)e(the)j(system)f(identi\002er)g(for)f(the)h (entity)-5 b(,)20 b(and)f(f)o(ail)i(if)f(it)h(is)g(not)f(a)n(v)n (ailable.)0 676 y FD(getErrorHandler)p FJ(\(\))208 775 y FN(Return)f(the)i(current)d FJ(ErrorHandler)p FN(.)0 922 y FD(setErrorHandler)p FJ(\()p FK(handler)r FJ(\))208 1022 y FN(Set)25 b(the)g(current)f(error)g(handler)-5 b(.)38 b(If)25 b(no)g FJ(ErrorHandler)e FN(is)j(set,)h(errors)d(will)i (be)f(raised)g(as)h(e)o(xceptions,)e(and)g(w)o(arnings)208 1121 y(will)c(be)h(printed.)0 1268 y FD(setLocale)p FJ(\()p FK(locale)p FJ(\))208 1368 y FN(Allo)n(w)f(an)g(application)f(to)h(set) h(the)f(locale)g(for)g(errors)f(and)h(w)o(arnings.)208 1501 y(SAX)c(parsers)g(are)g(not)g(required)e(to)i(pro)o(vide)e (localization)h(for)g(errors)h(and)f(w)o(arnings;)i(if)f(the)o(y)f (cannot)g(support)g(the)h(requested)208 1600 y(locale,)22 b(ho)n(we)n(v)o(er)m(,)d(the)o(y)j(must)g(thro)n(w)f(a)h(SAX)h(e)o (xception.)28 b(Applications)21 b(may)g(request)h(a)g(locale)g(change)f (in)h(the)g(middle)f(of)208 1700 y(a)f(parse.)0 1847 y FD(getFeature)p FJ(\()p FK(featur)m(ename)p FJ(\))208 1946 y FN(Return)88 b(the)h(current)e(setting)i(for)f(feature)g FK(featur)m(ename)p FN(.)229 b(If)89 b(the)g(feature)f(is)i(not)e (recognized,)208 2046 y FJ(SAXNotRecognizedException)40 b FN(is)46 b(raised.)100 b(The)44 b(well-kno)n(wn)f(featurenames)g(are) i(listed)h(in)f(the)g(module)208 2146 y FJ(xml.sax.handler)p FN(.)0 2293 y FD(setFeature)p FJ(\()p FK(featur)m(ename)o(,)17 b(value)p FJ(\))208 2392 y FN(Set)j(the)g FK(featur)m(ename)f FN(to)h FK(value)p FN(.)k(If)c(the)h(feature)e(is)i(not)e(recognized,)f FJ(SAXNotRecognizedException)e FN(is)21 b(raised.)k(If)208 2492 y(the)20 b(feature)f(or)h(its)h(setting)f(is)h(not)f(supported)e (by)i(the)g(parser)m(,)f FK(SAXNotSupportedException)c FN(is)22 b(raised.)0 2639 y FD(getProperty)p FJ(\()p FK(pr)l(opertyname)p FJ(\))208 2738 y FN(Return)69 b(the)g(current)f (setting)i(for)e(property)g FK(pr)l(opertyname)p FN(.)171 b(If)69 b(the)h(property)d(is)k(not)e(recognized,)79 b(a)208 2838 y FJ(SAXNotRecognizedException)36 b FN(is)42 b(raised.)86 b(The)41 b(well-kno)n(wn)e(propertynames)e(are)k(listed)g (in)g(the)g(module)208 2938 y FJ(xml.sax.handler)p FN(.)0 3084 y FD(setProperty)p FJ(\()p FK(pr)l(opertyname)o(,)16 b(value)p FJ(\))208 3184 y FN(Set)j(the)f FK(pr)l(opertyname)f FN(to)i FK(value)p FN(.)k(If)c(the)f(property)e(is)k(not)e(recognized,) e FJ(SAXNotRecognizedException)f FN(is)k(raised.)208 3284 y(If)h(the)g(property)e(or)i(its)h(setting)f(is)h(not)f(supported) e(by)i(the)g(parser)m(,)f FK(SAXNotSupportedException)c FN(is)21 b(raised.)0 3569 y Fv(8.12.2)101 b(IncrementalP)l(arser)30 b(Objects)0 3772 y FN(Instances)20 b(of)g FJ(IncrementalParser)d FN(of)n(fer)i(the)h(follo)n(wing)f(additional)g(methods:)0 3918 y FD(feed)p FJ(\()p FK(data)p FJ(\))208 4018 y FN(Process)h(a)h (chunk)d(of)i FK(data)p FN(.)0 4165 y FD(close)p FJ(\(\))208 4265 y FN(Assume)j(the)g(end)f(of)h(the)g(document.)32 b(That)22 b(will)i(check)e(well-formedness)f(conditions)h(that)h(can)g (be)g(check)o(ed)f(only)g(at)i(the)208 4364 y(end,)19 b(in)m(v)n(ok)o(e)g(handlers,)g(and)g(may)h(clean)g(up)g(resources)f (allocated)g(during)g(parsing.)0 4511 y FD(reset)p FJ(\(\))208 4611 y FN(This)j(method)g(is)h(called)g(after)f(close)h(has)g(been)f (called)g(to)h(reset)g(the)g(parser)f(so)h(that)f(it)i(is)f(ready)f(to) h(parse)f(ne)n(w)h(documents.)208 4710 y(The)c(results)i(of)f(calling)g (parse)g(or)f(feed)h(after)g(close)g(without)g(calling)f(reset)i(are)f (unde\002ned.)0 4995 y Fv(8.12.3)101 b(Locator)29 b(Objects)0 5198 y FN(Instances)20 b(of)g FJ(Locator)f FN(pro)o(vide)f(these)j (methods:)0 5345 y FD(getColumnNumber)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(296)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 297 309 TeXDict begin 297 308 bop 208 83 a FN(Return)19 b(the)i(column)d (number)h(where)g(the)h(current)f(e)n(v)o(ent)h(ends.)0 230 y FD(getLineNumber)p FJ(\(\))208 330 y FN(Return)f(the)i(line)f (number)e(where)i(the)g(current)f(e)n(v)o(ent)g(ends.)0 476 y FD(getPublicId)p FJ(\(\))208 576 y FN(Return)g(the)i(public)e (identi\002er)g(for)h(the)g(current)f(e)n(v)o(ent.)0 723 y FD(getSystemId)p FJ(\(\))208 823 y FN(Return)g(the)i(system)f (identi\002er)f(for)h(the)g(current)f(e)n(v)o(ent.)0 1107 y Fv(8.12.4)101 b(InputSource)29 b(Objects)0 1296 y FD(setPublicId)p FJ(\()p FK(id)r FJ(\))208 1396 y FN(Sets)21 b(the)f(public)f(identi\002er)h(of)g(this)g FJ(InputSource)p FN(.)0 1543 y FD(getPublicId)p FJ(\(\))208 1642 y FN(Returns)g(the)g (public)f(identi\002er)h(of)g(this)g FJ(InputSource)p FN(.)0 1789 y FD(setSystemId)p FJ(\()p FK(id)r FJ(\))208 1889 y FN(Sets)h(the)f(system)g(identi\002er)g(of)g(this)g FJ(InputSource)p FN(.)0 2036 y FD(getSystemId)p FJ(\(\))208 2135 y FN(Returns)g(the)g(system)g(identi\002er)g(of)g(this)g FJ(InputSource)p FN(.)0 2282 y FD(setEncoding)p FJ(\()p FK(encoding)p FJ(\))208 2382 y FN(Sets)h(the)f(character)f(encoding)f (of)i(this)h FJ(InputSource)p FN(.)208 2515 y(The)29 b(encoding)f(must)i(be)g(a)h(string)e(acceptable)g(for)h(an)g(XML)g (encoding)e(declaration)g(\(see)i(section)g(4.3.3)f(of)g(the)i(XML)208 2614 y(recommendation\).)208 2747 y(The)16 b(encoding)f(attrib)n(ute)i (of)f(the)h FJ(InputSource)f FN(is)i(ignored)d(if)i(the)g FJ(InputSource)e FN(also)j(contains)e(a)h(character)f(stream.)0 2894 y FD(getEncoding)p FJ(\(\))208 2994 y FN(Get)k(the)g(character)f (encoding)f(of)i(this)h(InputSource.)0 3141 y FD(setByteStream)p FJ(\()p FK(byte\002le)p FJ(\))208 3240 y FN(Set)d(the)f(byte)g(stream)h (\(a)g(Python)e(\002le-lik)o(e)i(object)f(which)g(does)g(not)g(perform) f(byte-to-character)e(con)m(v)o(ersion\))g(for)j(this)h(input)208 3340 y(source.)208 3473 y(The)27 b(SAX)h(parser)f(will)h(ignore)f(this) h(if)g(there)f(is)h(also)g(a)g(character)e(stream)i(speci\002ed,)h(b)n (ut)e(it)i(will)f(use)g(a)g(byte)f(stream)g(in)208 3572 y(preference)18 b(to)i(opening)e(a)j(URI)g(connection)d(itself.)208 3705 y(If)g(the)h(application)f(kno)n(ws)g(the)h(character)f(encoding)e (of)j(the)g(byte)f(stream,)h(it)h(should)e(set)i(it)f(with)g(the)g (setEncoding)e(method.)0 3852 y FD(getByteStream)p FJ(\(\))208 3952 y FN(Get)j(the)g(byte)g(stream)g(for)g(this)g(input)g(source.)208 4084 y(The)f(getEncoding)f(method)h(will)i(return)e(the)h(character)f (encoding)f(for)h(this)i(byte)f(stream,)g(or)g(None)f(if)i(unkno)n(wn.) 0 4231 y FD(setCharacterStream)p FJ(\()p FK(c)o(har\002le)p FJ(\))208 4331 y FN(Set)g(the)f(character)g(stream)g(for)g(this)h (input)f(source.)25 b(\(The)20 b(stream)g(must)h(be)f(a)h(Python)e(1.6) h(Unicode-wrapped)d(\002le-lik)o(e)j(that)208 4431 y(performs)e(con)m (v)o(ersion)g(to)i(Unicode)f(strings.\))208 4563 y(If)g(there)h(is)h(a) g(character)d(stream)i(speci\002ed,)g(the)g(SAX)h(parser)e(will)i (ignore)e(an)o(y)g(byte)h(stream)g(and)f(will)i(not)f(attempt)f(to)i (open)208 4663 y(a)f(URI)h(connection)d(to)i(the)g(system)h (identi\002er)-5 b(.)0 4810 y FD(getCharacterStream)p FJ(\(\))208 4910 y FN(Get)20 b(the)g(character)f(stream)h(for)g(this)h (input)e(source.)p 0 5549 3901 4 v 0 5649 a FI(8.12.)52 b FJ(xml.sax.xmlreader)20 b FI(\227)j(Interf)n(ace)g(f)n(or)f(XML)i (parsers)1617 b(297)p eop end %%Page: 298 310 TeXDict begin 298 309 bop 0 83 a Fv(8.12.5)101 b(The)28 b Fm(Attributes)d Fv(Interf)m(ace)0 286 y FJ(Attributes)15 b FN(objects)h(implement)g(a)h(portion)e(of)h(the)g(mapping)f (protocol,)g(including)g(the)h(methods)g FJ(copy\(\))p FN(,)g FJ(get\(\))p FN(,)h FJ(has_-)0 386 y(key\(\))p FN(,)j FJ(items\(\))p FN(,)f FJ(keys\(\))p FN(,)g(and)h FJ(values\(\))p FN(.)k(The)c(follo)n(wing)e(methods)h(are)h(also)h(pro) o(vided:)0 532 y FD(getLength)p FJ(\(\))208 632 y FN(Return)e(the)i (number)d(of)i(attrib)n(utes.)0 779 y FD(getNames)p FJ(\(\))208 879 y FN(Return)f(the)i(names)e(of)h(the)g(attrib)n(utes.)0 1025 y FD(getType)p FJ(\()p FK(name)p FJ(\))208 1125 y FN(Returns)g(the)g(type)g(of)f(the)i(attrib)n(ute)e FK(name)p FN(,)h(which)f(is)j(normally)c FJ('CDATA')p FN(.)0 1272 y FD(getValue)p FJ(\()p FK(name)p FJ(\))208 1372 y FN(Return)h(the)i(v)n(alue)e(of)h(attrib)n(ute)g FK(name)p FN(.)0 1654 y Fv(8.12.6)101 b(The)28 b Fm(AttributesNS)d Fv(Interf)m(ace)0 1856 y FN(This)18 b(interf)o(ace)f(is)h(a)g(subtype)f (of)g(the)h FJ(Attributes)f FN(interf)o(ace)f(\(see)i(section)g (8.12.5\).)k(All)c(methods)f(supported)e(by)j(that)f(interf)o(ace)0 1956 y(are)j(also)h(a)n(v)n(ailable)e(on)h FJ(AttributesNS)f FN(objects.)0 2103 y(The)h(follo)n(wing)e(methods)i(are)g(also)g(a)n(v) n(ailable:)0 2250 y FD(getValueByQName)p FJ(\()p FK(name)p FJ(\))208 2349 y FN(Return)f(the)i(v)n(alue)e(for)h(a)g(quali\002ed)g (name.)0 2496 y FD(getNameByQName)p FJ(\()p FK(name)p FJ(\))208 2596 y FN(Return)f(the)i FJ(\()p FK(namespace)p FJ(,)47 b FK(localname)p FJ(\))18 b FN(pair)i(for)g(a)g(quali\002ed)g FK(name)p FN(.)0 2743 y FD(getQNameByName)p FJ(\()p FK(name)p FJ(\))208 2842 y FN(Return)f(the)i(quali\002ed)e(name)g(for)h(a)h FJ(\()p FK(namespace)p FJ(,)47 b FK(localname)p FJ(\))18 b FN(pair)-5 b(.)0 2989 y FD(getQNames)p FJ(\(\))208 3089 y FN(Return)19 b(the)i(quali\002ed)e(names)h(of)g(all)g(attrib)n (utes.)0 3414 y FE(8.13)121 b Fx(xml.etree.ElementTree)28 b FE(\227)33 b(The)h(ElementT)-14 b(ree)34 b(XML)f(API)0 3646 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3793 y(The)g(Element)f (type)h(is)h(a)g(\003e)o(xible)e(container)g(object,)g(designed)g(to)h (store)g(hierarchical)f(data)h(structures)g(in)g(memory)-5 b(.)22 b(The)d(type)g(can)0 3893 y(be)h(described)f(as)i(a)g(cross)f (between)f(a)i(list)g(and)f(a)g(dictionary)-5 b(.)0 4040 y(Each)20 b(element)f(has)i(a)f(number)f(of)h(properties)e(associated)i (with)h(it:)125 4254 y FM(\017)41 b FN(a)20 b(tag)g(which)g(is)h(a)g (string)f(identifying)e(what)i(kind)f(of)h(data)g(this)h(element)f (represents)f(\(the)h(element)f(type,)h(in)g(other)g(w)o(ords\).)125 4413 y FM(\017)41 b FN(a)20 b(number)f(of)g(attrib)n(utes,)h(stored)g (in)g(a)h(Python)e(dictionary)-5 b(.)125 4573 y FM(\017)41 b FN(a)20 b(te)o(xt)g(string.)125 4733 y FM(\017)41 b FN(an)20 b(optional)f(tail)h(string.)125 4892 y FM(\017)41 b FN(a)20 b(number)f(of)g(child)h(elements,)g(stored)g(in)g(a)h(Python) e(sequence)0 5106 y(T)-7 b(o)20 b(create)g(an)g(element)g(instance,)g (use)g(the)g(Element)g(or)g(SubElement)e(f)o(actory)h(functions.)0 5253 y(The)h FJ(ElementTree)f FN(class)i(can)f(be)g(used)g(to)g(wrap)g (an)g(element)g(structure,)f(and)g(con)m(v)o(ert)f(it)j(from)e(and)h (to)g(XML.)0 5400 y(A)h(C)g(implementation)d(of)i(this)g(API)h(is)g(a)n (v)n(ailable)f(as)h FJ(xml.etree.cElementTree)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(298)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 299 311 TeXDict begin 299 310 bop 0 83 a Fv(8.13.1)101 b(Functions)0 272 y FD(Comment)p FJ(\()p FC([)p FK(te)n(xt)13 b FC(])p FJ(\))208 372 y FN(Comment)25 b(element)h(f)o(actory)-5 b(.)42 b(This)27 b(f)o(actory)e(function)g(creates)i(a)g(special)f (element)g(that)h(will)g(be)g(serialized)f(as)h(an)g(XML)208 471 y(comment.)22 b(The)c(comment)e(string)i(can)f(be)h(either)g(an)f (8-bit)h(ASCII)g(string)f(or)h(a)g(Unicode)f(string.)24 b FK(te)n(xt)c FN(is)f(a)f(string)f(containing)208 571 y(the)j(comment)f(string.)208 704 y FD(Returns:)390 803 y FN(An)h(element)g(instance,)g(representing)e(a)i(comment.)0 950 y FD(dump)p FJ(\()p FK(elem)p FJ(\))208 1050 y FN(Writes)h(an)f (element)f(tree)i(or)e(element)h(structure)f(to)i(sys.stdout.)j(This)c (function)f(should)g(be)h(used)g(for)g(deb)n(ugging)d(only)-5 b(.)208 1183 y(The)19 b(e)o(xact)h(output)f(format)g(is)i (implementation)d(dependent.)23 b(In)d(this)h(v)o(ersion,)d(it')-5 b(s)22 b(written)d(as)i(an)g(ordinary)d(XML)i(\002le.)208 1315 y FK(elem)g FN(is)h(an)f(element)g(tree)g(or)g(an)g(indi)n(vidual) f(element.)0 1462 y FD(Element)p FJ(\()p FK(ta)o(g)p FC([)p FK(,)f(attrib)12 b FC(][)p FK(,)20 b(**e)n(xtr)o(a)12 b FC(])p FJ(\))208 1562 y FN(Element)21 b(f)o(actory)-5 b(.)29 b(This)22 b(function)f(returns)g(an)h(object)f(implementing)f (the)i(standard)f(Element)h(interf)o(ace.)29 b(The)22 b(e)o(xact)g(class)208 1662 y(or)e(type)g(of)g(that)h(object)f(is)i (implementation)c(dependent,)h(b)n(ut)h(it)i(will)f(al)o(w)o(ays)g(be)g (compatible)e(with)i(the)p 3304 1662 25 4 v 50 w(ElementInterf)o(ace) 208 1761 y(class)g(in)f(this)h(module.)208 1894 y(The)k(element)f (name,)i(attrib)n(ute)f(names,)h(and)f(attrib)n(ute)g(v)n(alues)g(can)g (be)g(either)g(8-bit)g(ASCII)g(strings)h(or)f(Unicode)f(strings.)208 1994 y FK(ta)o(g)18 b FN(is)j(the)e(element)f(name.)24 b FK(attrib)19 b FN(is)h(an)f(optional)f(dictionary)-5 b(,)17 b(containing)g(element)i(attrib)n(utes.)24 b FK(e)n(xtr)o(a)c FN(contains)e(additional)208 2093 y(attrib)n(utes,)h(gi)n(v)o(en)g(as)i (k)o(e)o(yw)o(ord)e(ar)o(guments.)208 2226 y FD(Returns:)390 2326 y FN(An)h(element)g(instance.)0 2473 y FD(fromstring)p FJ(\()p FK(te)n(xt)q FJ(\))208 2572 y FN(P)o(arses)g(an)g(XML)h (section)e(from)h(a)g(string)g(constant.)k(Same)d(as)f(XML.)g FK(te)n(xt)j FN(is)e(a)g(string)f(containing)e(XML)i(data.)208 2705 y FD(Returns:)390 2805 y FN(An)g(Element)g(instance.)0 2952 y FD(iselement)p FJ(\()p FK(element)q FJ(\))208 3051 y FN(Checks)g(if)g(an)g(object)g(appears)f(to)i(be)f(a)g(v)n(alid) g(element)g(object.)k FK(element)e FN(is)f(an)f(element)f(instance.)208 3184 y FD(Returns:)390 3284 y FN(A)i(true)f(v)n(alue)f(if)i(this)f(is)i (an)e(element)f(object.)0 3430 y FD(iterparse)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)f(e)o(vents)12 b FC(])p FJ(\))208 3530 y FN(P)o(arses)25 b(an)h(XML)f(section)g(into)g(an)h(element)e (tree)i(incrementally)-5 b(,)24 b(and)h(reports)f(what')-5 b(s)26 b(going)e(on)h(to)g(the)h(user)-5 b(.)40 b FK(sour)m(ce)26 b FN(is)208 3630 y(a)e(\002lename)f(or)g(\002le)h(object)f(containing)f (XML)i(data.)35 b FK(e)o(vents)23 b FN(is)i(a)f(list)h(of)e(e)n(v)o (ents)g(to)h(report)e(back.)35 b(If)23 b(omitted,)h(only)e(\223end\224) 208 3729 y(e)n(v)o(ents)d(are)h(reported.)208 3862 y FD(Returns:)390 3962 y FN(A)h(\(e)n(v)o(ent,)e(elem\))g(iterator)-5 b(.)0 4109 y FD(parse)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)18 b(par)o(ser)c FC(])p FJ(\))208 4208 y FN(P)o(arses)21 b(an)g(XML)g(section)g(into)g(an)g(element)g(tree.)28 b FK(sour)m(ce)21 b FN(is)h(a)f(\002lename)g(or)g(\002le)g(object)g (containing)e(XML)i(data.)28 b FK(par)o(ser)c FN(is)208 4308 y(an)c(optional)f(parser)g(instance.)25 b(If)20 b(not)g(gi)n(v)o(en,)e(the)i(standard)g(XML)-8 b(T)m(reeBuilder)18 b(parser)i(is)h(used.)208 4441 y FD(Returns:)390 4540 y FN(An)f(ElementT)m(ree)f(instance)0 4687 y FD(ProcessingInstruction)p FJ(\()p FK(tar)m(g)o(et)q FC([)p FK(,)d(te)n(xt)d FC(])p FJ(\))208 4787 y FN(PI)20 b(element)f(f)o(actory)-5 b(.)23 b(This)d(f)o(actory)e(function)g(creates)i(a)g(special)g(element)f (that)h(will)g(be)g(serialized)f(as)i(an)e(XML)h(processing)208 4887 y(instruction.)j FK(tar)m(g)o(et)f FN(is)f(a)g(string)f (containing)e(the)i(PI)h(tar)o(get.)j FK(te)n(xt)e FN(is)f(a)g(string)f (containing)e(the)i(PI)h(contents,)e(if)h(gi)n(v)o(en.)208 5019 y FD(Returns:)390 5119 y FN(An)g(element)g(instance,)g (representing)e(a)i(PI.)0 5266 y FD(SubElement)p FJ(\()p FK(par)m(ent,)d(ta)o(g)p FC([)p FK(,)j(attrib)12 b FC(])20 b([)p FK(,)g(**e)n(xtr)o(a)12 b FC(])p FJ(\))208 5365 y FN(Subelement)18 b(f)o(actory)-5 b(.)24 b(This)c(function)f(creates)h (an)g(element)f(instance,)h(and)g(appends)f(it)h(to)h(an)f(e)o(xisting) f(element.)p 0 5549 3901 4 v 0 5649 a FI(8.13.)52 b FJ (xml.etree.ElementTree)19 b FI(\227)24 b(The)f(ElementT)-10 b(ree)24 b(XML)g(API)1369 b(299)p eop end %%Page: 300 312 TeXDict begin 300 311 bop 208 83 a FN(The)25 b(element)f(name,)i (attrib)n(ute)f(names,)h(and)f(attrib)n(ute)g(v)n(alues)g(can)g(be)g (either)g(8-bit)g(ASCII)g(strings)h(or)f(Unicode)f(strings.)208 183 y FK(par)m(ent)h FN(is)h(the)e(parent)g(element.)38 b FK(ta)o(g)24 b FN(is)i(the)f(subelement)e(name.)38 b FK(attrib)24 b FN(is)i(an)f(optional)e(dictionary)-5 b(,)23 b(containing)g(element)208 282 y(attrib)n(utes.)h FK(e)n(xtr)o(a)d FN(contains)e(additional)g(attrib)n(utes,)h(gi)n(v)o (en)f(as)i(k)o(e)o(yw)o(ord)d(ar)o(guments.)208 415 y FD(Returns:)390 515 y FN(An)i(element)g(instance.)0 662 y FD(tostring)p FJ(\()p FK(element)q FC([)p FK(,)e(encoding)12 b FC(])p FJ(\))208 761 y FN(Generates)j(a)i(string)e(representation)f (of)i(an)g(XML)g(element,)g(including)e(all)j(subelements.)23 b FK(element)17 b FN(is)g(an)f(Element)f(instance.)208 861 y FK(encoding)j FN(is)j(the)f(output)f(encoding)f(\(def)o(ault)h (is)i(US-ASCII\).)208 994 y FD(Returns:)390 1093 y FN(An)f(encoded)f (string)h(containing)e(the)i(XML)g(data.)0 1240 y FD(XML)p FJ(\()p FK(te)n(xt)q FJ(\))208 1340 y FN(P)o(arses)k(an)g(XML)h (section)e(from)h(a)g(string)g(constant.)36 b(This)25 b(function)d(can)i(be)g(used)g(to)h(embed)e(\223XML)h(literals\224)g (in)h(Python)208 1439 y(code.)f FK(te)n(xt)e FN(is)f(a)g(string)f (containing)e(XML)i(data.)208 1572 y FD(Returns:)390 1672 y FN(An)g(Element)g(instance.)0 1819 y FD(XMLID)p FJ(\()p FK(te)n(xt)q FJ(\))208 1918 y FN(P)o(arses)25 b(an)f(XML)h(section)f(from)g(a)h(string)f(constant,)h(and)f(also)h (returns)e(a)i(dictionary)e(which)h(maps)h(from)e(element)h(id:s)h(to) 208 2018 y(elements.)f FK(te)n(xt)f FN(is)e(a)f(string)g(containing)f (XML)h(data.)208 2151 y FD(Returns:)390 2250 y FN(A)h(tuple)f (containing)e(an)i(Element)g(instance)f(and)h(a)h(dictionary)-5 b(.)0 2535 y Fv(8.13.2)101 b(ElementT)-12 b(ree)30 b(Objects)0 2734 y FL(class)21 b FD(ElementTree)p FJ(\()p FC([)p FK(element,)12 b FC(])17 b([)p FK(\002le)12 b FC(])p FJ(\))208 2833 y FN(ElementT)m(ree)20 b(wrapper)h(class.)32 b(This)22 b(class)h(represents)e(an)i(entire)e(element)h(hierarchy)-5 b(,)19 b(and)j(adds)g(some)g(e)o(xtra)f(support)g(for)208 2933 y(serialization)e(to)h(and)g(from)f(standard)g(XML.)208 3066 y FK(element)i FN(is)g(the)f(root)g(element.)k(The)c(tree)g(is)h (initialized)f(with)h(the)f(contents)f(of)h(the)g(XML)h FK(\002le)f FN(if)g(gi)n(v)o(en.)0 3213 y FD(_setroot)p FJ(\()p FK(element)q FJ(\))208 3312 y FN(Replaces)25 b(the)f(root)g(element)h(for)f(this)h(tree.)39 b(This)25 b(discards)f(the)h(current)e(contents)i(of)f(the)h(tree,)h(and)e (replaces)g(it)i(with)f(the)208 3412 y(gi)n(v)o(en)18 b(element.)25 b(Use)c(with)f(care.)25 b FK(element)c FN(is)g(an)f(element)g(instance.)0 3559 y FD(find)p FJ(\()p FK(path)p FJ(\))208 3658 y FN(Finds)g(the)g(\002rst)h(tople)n(v)o(el)e (element)h(with)g(gi)n(v)o(en)f(tag.)25 b(Same)20 b(as)h (getroot\(\).\002nd\(path\).)f FK(path)f FN(is)j(the)e(element)f(to)i (look)e(for)-5 b(.)208 3791 y FD(Returns:)390 3891 y FN(The)20 b(\002rst)h(matching)e(element,)g(or)h(None)g(if)g(no)g (element)f(w)o(as)i(found.)0 4038 y FD(findall)p FJ(\()p FK(path)p FJ(\))208 4137 y FN(Finds)f(all)h(tople)n(v)o(el)e(elements)g (with)i(the)f(gi)n(v)o(en)f(tag.)25 b(Same)20 b(as)h (getroot\(\).\002ndall\(path\).)f FK(path)g FN(is)h(the)f(element)g(to) g(look)f(for)-5 b(.)208 4270 y FD(Returns:)390 4370 y FN(A)21 b(list)g(or)f(iterator)g(containing)e(all)j(matching)d (elements,)i(in)g(section)g(order)-5 b(.)0 4517 y FD(findtext)p FJ(\()p FK(path)p FC([)p FK(,)17 b(default)c FC(])p FJ(\))208 4616 y FN(Finds)20 b(the)h(element)f(te)o(xt)h(for)f(the)h(\002rst)g (tople)n(v)o(el)f(element)g(with)h(gi)n(v)o(en)e(tag.)27 b(Same)20 b(as)i(getroot\(\).\002ndte)o(xt\(path\).)f FK(path)f FN(is)i(the)208 4716 y(tople)n(v)o(el)c(element)i(to)g(look)g (for)-5 b(.)25 b FK(default)20 b FN(is)i(the)e(v)n(alue)f(to)i(return)e (if)h(the)g(element)g(w)o(as)h(not)f(found.)208 4849 y FD(Returns:)390 4948 y FN(The)h(te)o(xt)g(content)f(of)g(the)h (\002rst)h(matching)e(element,)g(or)h(the)g(def)o(ault)f(v)n(alue)g(no) h(element)f(w)o(as)i(found.)j(Note)c(that)g(if)h(the)390 5048 y(element)e(has)g(is)h(found,)e(b)n(ut)h(has)g(no)g(te)o(xt)g (content,)f(this)i(method)d(returns)i(an)g(empty)f(string.)0 5195 y FD(getiterator)p FJ(\()p FC([)p FK(ta)o(g)12 b FC(])p FJ(\))208 5294 y FN(Creates)20 b(a)h(tree)g(iterator)e(for)h (the)g(root)g(element.)25 b(The)20 b(iterator)f(loops)h(o)o(v)o(er)f (all)i(elements)f(in)h(this)f(tree,)h(in)f(section)g(order)-5 b(.)25 b FK(ta)o(g)208 5394 y FN(is)c(the)f(tag)g(to)g(look)g(for)f (\(def)o(ault)g(is)j(to)e(return)f(all)i(elements\))p 0 5549 3901 4 v 0 5649 a FI(300)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 301 313 TeXDict begin 301 312 bop 208 83 a FD(Returns:)390 183 y FN(An)20 b(iterator)-5 b(.)0 330 y FD(getroot)p FJ(\(\))208 429 y FN(Gets)20 b(the)h(root)e(element)h(for)f(this)i(tree.)208 562 y FD(Returns:)390 662 y FN(An)f(element)g(instance.)0 808 y FD(parse)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)e(par)o(ser)c FC(])p FJ(\))208 908 y FN(Loads)20 b(an)h(e)o(xternal)f(XML)h(section)g (into)g(this)h(element)f(tree.)28 b FK(sour)m(ce)21 b FN(is)h(a)f(\002le)h(name)f(or)g(\002le)h(object.)27 b FK(par)o(ser)d FN(is)e(an)f(optional)208 1008 y(parser)e(instance.)25 b(If)20 b(not)g(gi)n(v)o(en,)e(the)i(standard)f(XML)-8 b(T)m(reeBuilder)19 b(parser)h(is)h(used.)208 1141 y FD(Returns:)390 1240 y FN(The)f(section)g(root)g(element.)0 1387 y FD(write)p FJ(\()p FK(\002le)p FC([)p FK(,)f(encoding)12 b FC(])p FJ(\))208 1487 y FN(Writes)22 b(the)f(element)f(tree)h(to)h(a) f(\002le,)h(as)g(XML.)f FK(\002le)g FN(is)h(a)f(\002le)h(name,)f(or)g (a)g(\002le)h(object)e(opened)g(for)g(writing.)27 b FK(encoding)19 b FN(is)k(the)208 1586 y(output)c(encoding)f(\(def)o(ault)h(is)i (US-ASCII\).)0 1871 y Fv(8.13.3)101 b(QName)27 b(Objects)0 2069 y FL(class)21 b FD(QName)p FJ(\()p FK(te)n(xt)p 610 2069 25 4 v 29 w(or)p 713 2069 V 29 w(uri)p FC([)p FK(,)g(ta)o(g)12 b FC(])p FJ(\))208 2169 y FN(QName)19 b(wrapper)-5 b(.)24 b(This)c(can)g(be)g(used)g(to)g(wrap)g(a)g(QName)g (attrib)n(ute)g(v)n(alue,)f(in)h(order)f(to)h(get)g(proper)f(namespace) f(handling)208 2269 y(on)j(output.)30 b FK(te)n(xt)p 701 2269 V 31 w(or)p 806 2269 V 29 w(uri)23 b FN(is)g(a)g(string)f (containing)e(the)j(QName)f(v)n(alue,)g(in)g(the)g(form)g FM(f)p FN(uri)p FM(g)p FN(local,)e(or)m(,)i(if)h(the)f(tag)h(ar)o (gument)d(is)208 2368 y(gi)n(v)o(en,)d(the)i(URI)h(part)f(of)f(a)i (QName.)k(If)19 b FK(ta)o(g)g FN(is)h(gi)n(v)o(en,)e(the)h(\002rst)h (ar)o(gument)c(is)k(interpreted)e(as)h(an)g(URI,)h(and)e(this)i(ar)o (gument)d(is)208 2468 y(interpreted)h(as)j(a)f(local)h(name.)208 2601 y FD(Returns:)390 2700 y FN(An)f(opaque)f(object,)g(representing)f (the)j(QName.)0 2985 y Fv(8.13.4)101 b(T)-12 b(reeBuilder)30 b(Objects)0 3183 y FL(class)21 b FD(TreeBuilder)p FJ(\()p FC([)p FK(element)p 1091 3183 V 26 w(factory)12 b FC(])p FJ(\))208 3283 y FN(Generic)26 b(element)h(structure)f(b)n(uilder)-5 b(.)45 b(This)27 b(b)n(uilder)g(con)m(v)o(erts)e(a)j(sequence)e(of)g (start,)k(data,)e(and)f(end)f(method)g(calls)i(to)f(a)208 3383 y(well-formed)17 b(element)h(structure.)24 b(Y)-9 b(ou)18 b(can)h(use)h(this)f(class)h(to)f(b)n(uild)g(an)g(element)g (structure)f(using)h(a)g(custom)g(XML)g(parser)m(,)208 3482 y(or)27 b(a)i(parser)e(for)g(some)h(other)f(XML-lik)o(e)h(format.) 47 b(The)27 b FK(element)p 2207 3482 V 29 w(factory)h FN(is)h(called)f(to)g(create)g(ne)n(w)f(Element)h(instances)208 3582 y(when)19 b(gi)n(v)o(en.)0 3729 y FD(close)p FJ(\(\))208 3828 y FN(Flushes)h(the)g(parser)g(b)n(uf)n(fers,)f(and)g(returns)h (the)g(tople)n(v)o(el)f(documen)f(element.)208 3961 y FD(Returns:)390 4061 y FN(An)i(Element)g(instance.)0 4208 y FD(data)p FJ(\()p FK(data)p FJ(\))208 4307 y FN(Adds)f(te)o(xt)h (to)g(the)g(current)e(element.)24 b FK(data)19 b FN(is)i(a)f(string.)25 b(This)20 b(should)f(be)g(either)h(an)g(8-bit)f(string)g(containing)f (ASCII)i(te)o(xt,)g(or)208 4407 y(a)g(Unicode)f(string.)0 4554 y FD(end)p FJ(\()p FK(ta)o(g)p FJ(\))208 4654 y FN(Closes)i(the)f(current)f(element.)24 b FK(ta)o(g)c FN(is)h(the)g(element)e(name.)208 4786 y FD(Returns:)390 4886 y FN(The)h(closed)g(element.)0 5033 y FD(start)p FJ(\()p FK(ta)o(g)o(,)f(attr)o(s)p FJ(\))208 5132 y FN(Opens)g(a)i(ne)n (w)f(element.)k FK(ta)o(g)c FN(is)i(the)e(element)f(name.)25 b FK(attr)o(s)c FN(is)g(a)g(dictionary)d(containing)g(element)i(attrib) n(utes.)208 5265 y FD(Returns:)390 5365 y FN(The)g(opened)f(element.)p 0 5549 3901 4 v 0 5649 a FI(8.13.)52 b FJ(xml.etree.ElementTree)19 b FI(\227)24 b(The)f(ElementT)-10 b(ree)24 b(XML)g(API)1369 b(301)p eop end %%Page: 302 314 TeXDict begin 302 313 bop 0 83 a Fv(8.13.5)101 b(XML)-11 b(T)f(reeBuilder)31 b(Objects)0 281 y FL(class)21 b FD(XMLTreeBuilder)p FJ(\()p FC([)p FK(html,)12 b FC(])17 b([)p FK(tar)m(g)o(et)c FC(])p FJ(\))208 381 y FN(Element)21 b(structure)g(b)n(uilder)g(for)g (XML)h(source)f(data,)h(based)g(on)f(the)h(e)o(xpat)f(parser)-5 b(.)30 b FK(html)22 b FN(are)g(prede\002ned)e(HTML)h(entities.)208 480 y(This)g(\003ag)g(is)g(not)g(supported)e(by)h(the)h(current)e (implementation.)25 b FK(tar)m(g)o(et)e FN(is)e(the)g(tar)o(get)f (object.)26 b(If)21 b(omitted,)f(the)h(b)n(uilder)f(uses)208 580 y(an)g(instance)f(of)h(the)h(standard)e(T)m(reeBuilder)g(class.)0 727 y FD(close)p FJ(\(\))208 827 y FN(Finishes)h(feeding)f(data)h(to)g (the)g(parser)-5 b(.)208 959 y FD(Returns:)390 1059 y FN(An)20 b(element)g(structure.)0 1206 y FD(doctype)p FJ(\()p FK(name)o(,)e(pubid,)h(system)p FJ(\))208 1306 y FN(Handles)k(a)h(doctype)e(declaration.)35 b FK(name)23 b FN(is)h(the)g(doctype)e(name.)36 b FK(pubid)24 b FN(is)h(the)f (public)f(identi\002er)-5 b(.)35 b FK(system)25 b FN(is)g(the)e(system) 208 1405 y(identi\002er)-5 b(.)0 1552 y FD(feed)p FJ(\()p FK(data)p FJ(\))208 1652 y FN(Feeds)20 b(data)g(to)g(the)h(parser)-5 b(.)208 1784 y FK(data)19 b FN(is)i(encoded)d(data.)p 0 5549 3901 4 v 0 5649 a FI(302)1965 b(Chapter)23 b(8.)52 b(Str)q(uctured)23 b(Mar)q(kup)g(Processing)g(T)-10 b(ools)p eop end %%Page: 303 315 TeXDict begin 303 314 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3614 427 y FG(NINE)p 0 515 V 2753 978 a FT(File)58 b(F)-6 b(or)5 b(mats)0 1457 y FN(The)25 b(modules)g(described)g(in)h(this)g (chapter)f(parse)g(v)n(arious)g(miscellaneous)g(\002le)h(formats)f (that)h(aren')o(t)f(markup)f(languages)g(or)i(are)0 1556 y(related)20 b(to)g(e-mail.)50 1683 y FD(csv)547 b FN(Write)21 b(and)f(read)f(tab)n(ular)h(data)g(to)g(and)g(from)f(delimited)h (\002les.)50 1782 y FD(ConfigParser)97 b FN(Con\002guration)18 b(\002le)j(parser)-5 b(.)50 1882 y FD(robotparser)147 b FN(Loads)20 b(a)g(`)p FO(robots)o(.txt)p FN(')f(\002le)i(and)e (answers)h(questions)g(about)f(fetchability)g(of)h(other)f(URLs.)50 1981 y FD(netrc)447 b FN(Loading)19 b(of)h(`)p FO(.netrc)p FN(')e(\002les.)50 2081 y FD(xdrlib)397 b FN(Encoders)19 b(and)h(decoders)e(for)i(the)g(External)f(Data)i(Representation)d (\(XDR\).)0 2385 y FE(9.1)121 b Fx(csv)32 b FE(\227)h(CSV)g(File)g (Reading)i(and)g(Wr)r(iting)0 2618 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.3.)0 2765 y(The)g(so-called)g(CSV)i(\(Comma)e(Separated)f(V)-9 b(alues\))19 b(format)g(is)h(the)g(most)g(common)d(import)i(and)g(e)o (xport)f(format)g(for)h(spreadsheets)0 2865 y(and)25 b(databases.)42 b(There)25 b(is)h(no)g(\223CSV)g(standard\224,)g(so)g (the)g(format)f(is)h(operationally)e(de\002ned)h(by)g(the)h(man)o(y)e (applications)h(which)0 2964 y(read)c(and)g(write)g(it.)30 b(The)21 b(lack)g(of)g(a)h(standard)e(means)h(that)h(subtle)f(dif)n (ferences)f(often)h(e)o(xist)g(in)h(the)f(data)h(produced)c(and)j (consumed)0 3064 y(by)j(dif)n(ferent)e(applications.)35 b(These)24 b(dif)n(ferences)e(can)i(mak)o(e)f(it)i(anno)o(ying)c(to)j (process)g(CSV)h(\002les)g(from)e(multiple)g(sources.)36 b(Still,)0 3163 y(while)29 b(the)g(delimiters)f(and)g(quoting)f (characters)h(v)n(ary)-5 b(,)29 b(the)g(o)o(v)o(erall)f(format)f(is)j (similar)f(enough)e(that)i(it)g(is)h(possible)e(to)h(write)g(a)0 3263 y(single)22 b(module)f(which)g(can)h(ef)n(\002ciently)g (manipulate)e(such)i(data,)g(hiding)f(the)h(details)h(of)f(reading)e (and)i(writing)f(the)h(data)g(from)g(the)0 3363 y(programmer)-5 b(.)0 3510 y(The)27 b FJ(csv)g FN(module)f(implements)h(classes)h(to)g (read)f(and)g(write)g(tab)n(ular)g(data)g(in)h(CSV)g(format.)46 b(It)27 b(allo)n(ws)h(programmers)c(to)k(say)-5 b(,)0 3609 y(\223write)20 b(this)h(data)f(in)g(the)g(format)f(preferred)f(by) h(Excel,)-6 b(\224)20 b(or)g(\223read)f(data)h(from)f(this)i(\002le)f (which)g(w)o(as)h(generated)d(by)i(Excel,)-6 b(\224)19 b(without)0 3709 y(kno)n(wing)29 b(the)j(precise)f(details)h(of)f(the)g (CSV)h(format)f(used)g(by)g(Excel.)58 b(Programmers)29 b(can)i(also)h(describe)f(the)g(CSV)h(formats)0 3808 y(understood)18 b(by)h(other)h(applications)f(or)h(de\002ne)f(their)h (o)n(wn)g(special-purpose)e(CSV)j(formats.)0 3955 y(The)26 b FJ(csv)g FN(module')-5 b(s)25 b FJ(reader)h FN(and)f FJ(writer)h FN(objects)g(read)f(and)h(write)g(sequences.)42 b(Programmers)24 b(can)i(also)g(read)g(and)f(write)0 4055 y(data)20 b(in)g(dictionary)f(form)g(using)h(the)g FJ(DictReader)f FN(and)g FJ(DictWriter)g FN(classes.)0 4202 y FL(Note:)24 b FN(This)19 b(v)o(ersion)f(of)h(the)g FJ(csv)g FN(module)f(doesn')o(t)g(support)g(Unicode)g(input.)24 b(Also,)19 b(there)g(are)g(currently)e(some)i(issues)i(re)o(garding)2 4301 y FH(A)t(S)t(C)t(I)t(I)31 b FN(NUL)c(characters.)46 b(Accordingly)-5 b(,)26 b(all)h(input)g(should)f(be)i(UTF-8)e(or)h (printable)h FH(A)t(S)t(C)t(I)t(I)j FN(to)d(be)f(safe;)k(see)d(the)f(e) o(xamples)f(in)0 4401 y(section)20 b(9.1.5.)j(These)d(restrictions)g (will)h(be)f(remo)o(v)o(ed)e(in)i(the)h(future.)0 4548 y FL(See)g(Also:)0 4695 y FN(PEP)g(305,)e(\223)p FK(CSV)h(F)l(ile)h (API)p FN(\224)208 4794 y(The)e(Python)g(Enhancement)f(Proposal)h (which)h(proposed)e(this)j(addition)e(to)h(Python.)0 5079 y Fv(9.1.1)100 b(Module)30 b(Contents)0 5282 y FN(The)20 b FJ(csv)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f(functions:)p 0 5549 3901 4 v 3762 5649 a FI(303)p eop end %%Page: 304 316 TeXDict begin 304 315 bop 0 83 a FD(reader)p FJ(\()p FK(csv\002le)p FC([)p FK(,)18 b(dialect=)p Fn('excel')12 b FC(][)p FK(,)18 b(fmtpar)o(am)12 b FC(])p FJ(\))208 183 y FN(Return)19 b(a)i(reader)d(object)i(which)f(will)i(iterate)f(o)o (v)o(er)f(lines)h(in)g(the)g(gi)n(v)o(en)f FK(csv\002le)p FN(.)25 b FK(csv\002le)20 b FN(can)g(be)g(an)o(y)f(object)g(which)h (supports)208 282 y(the)27 b(iterator)g(protocol)f(and)h(returns)g(a)h (string)g(each)f(time)h(its)h FJ(next)e FN(method)g(is)h(called)g(\227) g(\002le)g(objects)g(and)f(list)i(objects)208 382 y(are)24 b(both)g(suitable.)38 b(If)24 b FK(csv\002le)h FN(is)h(a)f(\002le)g (object,)g(it)g(must)g(be)f(opened)f(with)i(the)g('b')f(\003ag)g(on)h (platforms)e(where)h(that)h(mak)o(es)208 482 y(a)h(dif)n(ference.)41 b(An)26 b(optional)f FK(dialect)i FN(parameter)e(can)h(be)g(gi)n(v)o (en)f(which)h(is)h(used)f(to)g(de\002ne)g(a)g(set)h(of)f(parameters)f (speci\002c)208 581 y(to)i(a)h(particular)d(CSV)k(dialect.)46 b(It)27 b(may)g(be)g(an)g(instance)g(of)g(a)h(subclass)f(of)g(the)g FJ(Dialect)g FN(class)h(or)f(one)f(of)h(the)h(strings)208 681 y(returned)20 b(by)h(the)h FJ(list_dialects)e FN(function.)28 b(The)21 b(other)g(optional)g FK(fmtpar)o(am)g FN(k)o(e)o(yw)o(ord)f (ar)o(guments)g(can)h(be)h(gi)n(v)o(en)e(to)208 780 y(o)o(v)o(erride)c (indi)n(vidual)i(formatting)f(parameters)h(in)h(the)h(current)d (dialect.)25 b(F)o(or)19 b(full)g(details)g(about)g(the)g(dialect)g (and)f(formatting)208 880 y(parameters,)g(see)j(section)f(9.1.2,)f (\223Dialects)h(and)g(F)o(ormatting)e(P)o(arameters\224.)208 1013 y(All)i(data)g(read)g(are)g(returned)f(as)i(strings.)j(No)d (automatic)e(data)h(type)g(con)m(v)o(ersion)d(is)k(performed.)208 1146 y(Changed)26 b(in)i(v)o(ersion)f(2.5:)68 b(The)28 b(parser)f(is)i(no)n(w)e(stricter)h(with)g(respect)f(to)h(multi-line)f (quoted)g(\002elds.)48 b(Pre)n(viously)-5 b(,)28 b(if)g(a)208 1245 y(line)23 b(ended)g(within)h(a)g(quoted)e(\002eld)i(without)f(a)h (terminating)f(ne)n(wline)g(character)m(,)g(a)h(ne)n(wline)f(w)o(ould)g (be)h(inserted)f(into)h(the)208 1345 y(returned)h(\002eld.)46 b(This)28 b(beha)n(vior)e(caused)g(problems)g(when)h(reading)f(\002les) i(which)f(contained)e(carriage)h(return)h(characters)208 1445 y(within)e(\002elds.)44 b(The)25 b(beha)n(vior)g(w)o(as)i(changed) d(to)i(return)f(the)h(\002eld)h(without)e(inserting)g(ne)n(wlines.)43 b(As)27 b(a)f(consequence,)f(if)208 1544 y(ne)n(wlines)19 b(embedded)g(within)h(\002elds)g(are)h(important,)d(the)i(input)g (should)f(be)h(split)h(into)f(lines)h(in)f(a)h(manner)e(which)h (preserv)o(es)208 1644 y(the)g(ne)n(wline)f(characters.)0 1791 y FD(writer)p FJ(\()p FK(csv\002le)p FC([)p FK(,)f(dialect=)p Fn('excel')12 b FC(][)p FK(,)18 b(fmtpar)o(am)12 b FC(])p FJ(\))208 1890 y FN(Return)29 b(a)h(writer)f(object)g(responsible)f (for)h(con)m(v)o(erting)e(the)j(user')-5 b(s)29 b(data)h(into)f (delimited)g(strings)h(on)f(the)g(gi)n(v)o(en)g(\002le-lik)o(e)208 1990 y(object.)40 b FK(csv\002le)26 b FN(can)f(be)h(an)o(y)f(object)g (with)h(a)g FJ(write)f FN(method.)40 b(If)25 b FK(csv\002le)h FN(is)h(a)f(\002le)g(object,)g(it)h(must)e(be)h(opened)e(with)i(the)208 2090 y('b')21 b(\003ag)i(on)f(platforms)f(where)g(that)i(mak)o(es)f(a)h (dif)n(ference.)29 b(An)22 b(optional)f FK(dialect)j FN(parameter)c(can)j(be)f(gi)n(v)o(en)f(which)h(is)h(used)208 2189 y(to)k(de\002ne)g(a)h(set)h(of)e(parameters)f(speci\002c)i(to)g(a) g(particular)e(CSV)i(dialect.)47 b(It)28 b(may)f(be)h(an)f(instance)g (of)h(a)f(subclass)h(of)g(the)208 2289 y FJ(Dialect)18 b FN(class)i(or)f(one)g(of)g(the)g(strings)g(returned)e(by)i(the)g FJ(list_dialects)e FN(function.)23 b(The)c(other)f(optional)g FK(fmtpar)o(am)208 2388 y FN(k)o(e)o(yw)o(ord)24 b(ar)o(guments)h(can)h (be)h(gi)n(v)o(en)e(to)i(o)o(v)o(erride)d(indi)n(vidual)h(formatting)g (parameters)g(in)i(the)f(current)f(dialect.)44 b(F)o(or)27 b(full)208 2488 y(details)19 b(about)f(the)g(dialect)h(and)f (formatting)f(parameters,)h(see)h(section)g(9.1.2,)e(\223Dialects)i (and)g(F)o(ormatting)e(P)o(arameters\224.)23 b(T)-7 b(o)208 2588 y(mak)o(e)16 b(it)j(as)f(easy)f(as)h(possible)f(to)h(interf)o(ace) e(with)i(modules)e(which)h(implement)f(the)h(DB)i(API,)e(the)h(v)n (alue)e FJ(None)h FN(is)i(written)e(as)208 2687 y(the)h(empty)h (string.)24 b(While)19 b(this)h(isn')o(t)e(a)h(re)n(v)o(ersible)f (transformation,)e(it)k(mak)o(es)f(it)g(easier)g(to)g(dump)f(SQL)h (NULL)g(data)g(v)n(alues)208 2787 y(to)26 b(CSV)h(\002les)g(without)f (preprocessing)e(the)i(data)g(returned)f(from)g(a)i FJ(cursor.fetch) 2870 2802 y(*)2920 2787 y(\(\))d FN(call.)43 b(All)27 b(other)f(non-string)208 2887 y(data)20 b(are)g(stringi\002ed)f(with)i FJ(str\(\))e FN(before)g(being)g(written.)0 3033 y FD(register_dialect) p FJ(\()p FK(name)p FC([)p FK(,)d(dialect)d FC(][)p FK(,)19 b(fmtpar)o(am)12 b FC(])p FJ(\))208 3133 y FN(Associate)24 b FK(dialect)h FN(with)f FK(name)p FN(.)35 b FK(name)23 b FN(must)h(be)f(a)i(string)e(or)h(Unicode)e(object.)36 b(The)23 b(dialect)h(can)f(be)h(speci\002ed)g(either)f(by)208 3233 y(passing)f(a)h(sub-class)f(of)h FJ(Dialect)p FN(,)f(or)g(by)g FK(fmtpar)o(am)g FN(k)o(e)o(yw)o(ord)f(ar)o(guments,)g(or)h(both,)g (with)h(k)o(e)o(yw)o(ord)d(ar)o(guments)h(o)o(v)o(er)n(-)208 3332 y(riding)g(parameters)g(of)i(the)f(dialect.)32 b(F)o(or)22 b(full)h(details)g(about)e(the)i(dialect)f(and)g(formatting)f (parameters,)h(see)h(section)f(9.1.2,)208 3432 y(\223Dialects)e(and)g (F)o(ormatting)e(P)o(arameters\224.)0 3579 y FD(unregister_dialect)p FJ(\()p FK(name)p FJ(\))208 3678 y FN(Delete)h(the)f(dialect)h (associated)g(with)g FK(name)f FN(from)f(the)i(dialect)g(re)o(gistry)-5 b(.)23 b(An)c FJ(Error)f FN(is)i(raised)e(if)h FK(name)g FN(is)g(not)g(a)g(re)o(gistered)208 3778 y(dialect)h(name.)0 3925 y FD(get_dialect)p FJ(\()p FK(name)p FJ(\))208 4025 y FN(Return)f(the)i(dialect)f(associated)g(with)g FK(name)p FN(.)k(An)c FJ(Error)g FN(is)h(raised)f(if)h FK(name)e FN(is)j(not)d(a)i(re)o(gistered)e(dialect)h(name.)208 4157 y(Changed)26 b(in)i(v)o(ersion)f(2.5:)69 b(This)28 b(function)e(no)n(w)i(returns)f(an)h(immutable)e FJ(Dialect)p FN(.)48 b(Pre)n(viously)26 b(an)i(instance)g(of)g(the)208 4257 y(requested)15 b(dialect)i(w)o(as)h(returned.)k(Users)c(could)e (modify)g(the)h(underlying)d(class,)k(changing)d(the)i(beha)n(vior)f (of)h(acti)n(v)o(e)f(readers)208 4357 y(and)j(writers..)0 4504 y FD(list_dialects)p FJ(\(\))208 4603 y FN(Return)g(the)i(names)e (of)h(all)h(re)o(gistered)e(dialects.)0 4750 y FD(field_size_limit)p FJ(\()p FC([)p FK(ne)o(w)p 1028 4750 25 4 v 26 w(limit)13 b FC(])p FJ(\))208 4850 y FN(Returns)19 b(the)g(current)f(maximum)g (\002eld)i(size)g(allo)n(wed)f(by)g(the)g(parser)-5 b(.)24 b(If)c FK(ne)o(w)p 2499 4850 V 29 w(limit)i FN(is)e(gi)n(v)o(en,)e (this)i(becomes)f(the)g(ne)n(w)g(limit.)208 4949 y(Ne)n(w)h(in)g(v)o (ersion)f(2.5.)0 5096 y(The)h FJ(csv)g FN(module)f(de\002nes)h(the)g (follo)n(wing)f(classes:)0 5243 y FL(class)i FD(DictReader)p FJ(\()p FK(csv\002le)p FC([)p FK(,)42 b(\002eldnames=)p Fn(None)p FK(,)p FC([)p FK(,)f(r)m(estk)o(e)n(y=)p Fn(None)p FC([)p FK(,)j(r)m(estval=)p Fn(None)p FC([)p FK(,)f(dialect=)p Fn('excel')p FC([)p FK(,)f(*ar)m(gs,)737 5343 y(**kwds)12 b FC(])g(])g(])g(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(304)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 305 317 TeXDict begin 305 316 bop 208 83 a FN(Create)23 b(an)f(object)g(which)h (operates)f(lik)o(e)h(a)g(re)o(gular)e(reader)h(b)n(ut)g(maps)h(the)g (information)d(read)i(into)h(a)g(dict)g(whose)f(k)o(e)o(ys)h(are)208 183 y(gi)n(v)o(en)f(by)h(the)g(optional)46 b FK(\002eldnames)22 b FN(parameter)-5 b(.)34 b(If)23 b(the)h FK(\002eldnames)e FN(parameter)g(is)i(omitted,)f(the)h(v)n(alues)f(in)g(the)h(\002rst)g (ro)n(w)208 282 y(of)e(the)g FK(csv\002le)g FN(will)i(be)e(used)g(as)h (the)g(\002eldnames.)30 b(If)23 b(the)f(ro)n(w)g(read)g(has)g(fe)n(wer) g(\002elds)h(than)f(the)g(\002eldnames)g(sequence,)g(the)208 382 y(v)n(alue)e(of)h FK(r)m(estval)h FN(will)h(be)e(used)g(as)h(the)g (def)o(ault)e(v)n(alue.)28 b(If)21 b(the)h(ro)n(w)f(read)g(has)g(more)g (\002elds)h(than)f(the)g(\002eldnames)g(sequence,)208 482 y(the)d(remaining)f(data)h(is)i(added)d(as)i(a)g(sequence)f(k)o(e)o (yed)f(by)h(the)h(v)n(alue)f(of)g FK(r)m(estk)o(e)n(y)p FN(.)25 b(If)18 b(the)h(ro)n(w)f(read)g(has)g(fe)n(wer)g(\002elds)h (than)g(the)208 581 y(\002eldnames)g(sequence,)g(the)h(remaining)e(k)o (e)o(ys)i(tak)o(e)g(the)g(v)n(alue)f(of)h(the)g(optional)f FK(r)m(estval)i FN(parameter)-5 b(.)23 b(An)o(y)d(other)f(optional)g (or)208 681 y(k)o(e)o(yw)o(ord)f(ar)o(guments)g(are)i(passed)g(to)h (the)f(underlying)d FJ(reader)j FN(instance.)0 828 y FL(class)h FD(DictWriter)p FJ(\()p FK(csv\002le)o(,)61 b(\002eldnames)p FC([)p FK(,)h(r)m(estval=\224\224)p FC([)p FK(,)h(e)n(xtr)o(asaction=)p Fn('raise')p FC([)p FK(,)e(dialect=)p Fn('excel')p FC([)p FK(,)g(*ar)m(gs,)737 927 y(**kwds)12 b FC(])g(])g(])g(])p FJ(\))208 1011 y FN(Create)25 b(an)h(object)e(which)h(operates)g(lik)o(e)h(a)f(re)o (gular)f(writer)i(b)n(ut)f(maps)g(dictionaries)g(onto)f(output)g(ro)n (ws.)41 b(The)25 b FK(\002eldnames)208 1111 y FN(parameter)18 b(identi\002es)i(the)g(order)f(in)h(which)f(v)n(alues)h(in)g(the)g (dictionary)e(passed)i(to)g(the)g FJ(writerow\(\))e FN(method)h(are)h (written)208 1210 y(to)i(the)g FK(csv\002le)p FN(.)31 b(The)22 b(optional)f FK(r)m(estval)i FN(parameter)d(speci\002es)j(the) f(v)n(alue)g(to)g(be)g(written)g(if)h(the)f(dictionary)e(is)j(missing)g (a)f(k)o(e)o(y)208 1310 y(in)d FK(\002eldnames)p FN(.)24 b(If)c(the)f(dictionary)f(passed)i(to)g(the)g FJ(writerow\(\))e FN(method)h(contains)g(a)h(k)o(e)o(y)f(not)g(found)f(in)i FK(\002eldnames)p FN(,)f(the)208 1410 y(optional)e FK(e)n(xtr)o (asaction)g FN(parameter)g(indicates)h(what)g(action)g(to)g(tak)o(e.)25 b(If)18 b(it)h(is)g(set)g(to)f FJ('raise')g FN(a)h FJ(ValueError)e FN(is)i(raised.)208 1509 y(If)j(it)h(is)g(set)g(to)f FJ('ignore')p FN(,)g(e)o(xtra)g(v)n(alues)f(in)i(the)f(dictionary)f (are)h(ignored.)29 b(An)o(y)22 b(other)f(optional)g(or)h(k)o(e)o(yw)o (ord)f(ar)o(guments)208 1609 y(are)f(passed)g(to)g(the)g(underlying)e FJ(writer)h FN(instance.)208 1742 y(Note)h(that)h(unlik)o(e)e(the)i FJ(DictReader)e FN(class,)j(the)e FK(\002eldnames)f FN(parameter)g(of)h (the)h FJ(DictWriter)e FN(is)j(not)e(optional.)25 b(Since)208 1841 y(Python')-5 b(s)21 b FJ(dict)g FN(objects)h(are)g(not)f(ordered,) f(there)i(is)h(not)e(enough)f(information)g(a)n(v)n(ailable)h(to)h (deduce)f(the)g(order)g(in)h(which)208 1941 y(the)e(ro)n(w)g(should)f (be)h(written)g(to)g(the)g FK(csv\002le)p FN(.)0 2088 y FL(class)h FD(Dialect)208 2187 y FN(The)31 b FJ(Dialect)g FN(class)h(is)h(a)f(container)e(class)i(relied)f(on)g(primarily)f(for)h (its)i(attrib)n(utes,)h(which)d(are)h(used)f(to)h(de\002ne)f(the)208 2287 y(parameters)19 b(for)g(a)i(speci\002c)f FJ(reader)g FN(or)g FJ(writer)f FN(instance.)0 2434 y FL(class)i FD(excel)p FJ(\(\))208 2534 y FN(The)i FJ(excel)h FN(class)h(de\002nes) f(the)g(usual)g(properties)e(of)i(an)g(Excel-generated)d(CSV)k(\002le.) 37 b(It)25 b(is)g(re)o(gistered)d(with)j(the)f(dialect)208 2633 y(name)19 b FJ('excel')p FN(.)0 2780 y FL(class)i FD(excel_tab)p FJ(\(\))208 2880 y FN(The)j FJ(excel_tab)f FN(class)i(de\002nes)g(the)f(usual)h(properties)e(of)h(an)g (Excel-generated)e(T)-8 b(AB-delimited)23 b(\002le.)39 b(It)24 b(is)i(re)o(gistered)208 2979 y(with)20 b(the)g(dialect)g(name) g FJ('excel-tab')p FN(.)0 3126 y FL(class)h FD(Sniffer)p FJ(\(\))208 3226 y FN(The)e FJ(Sniffer)h FN(class)h(is)g(used)f(to)g (deduce)f(the)h(format)g(of)f(a)i(CSV)g(\002le.)0 3373 y(The)f FJ(Sniffer)f FN(class)i(pro)o(vides)e(tw)o(o)h(methods:)0 3520 y FD(sniff)p FJ(\()p FK(sample)p FC([)p FK(,delimiter)o(s=None)12 b FC(])p FJ(\))208 3619 y FN(Analyze)29 b(the)i(gi)n(v)o(en)f FK(sample)g FN(and)g(return)g(a)h FJ(Dialect)f FN(subclass)h (re\003ecting)f(the)g(parameters)g(found.)55 b(If)30 b(the)h(optional)208 3719 y FK(delimiter)o(s)21 b FN(parameter)d(is)j (gi)n(v)o(en,)e(it)i(is)g(interpreted)d(as)j(a)g(string)f(containing)e (possible)i(v)n(alid)g(delimiter)f(characters.)0 3866 y FD(has_header)p FJ(\()p FK(sample)p FJ(\))208 3965 y FN(Analyze)g(the)h(sample)h(te)o(xt)f(\(presumed)e(to)j(be)f(in)g (CSV)i(format\))d(and)h(return)f FJ(True)h FN(if)h(the)f(\002rst)h(ro)n (w)f(appears)f(to)i(be)f(a)h(series)208 4065 y(of)e(column)g(headers.)0 4212 y(The)h FJ(csv)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (constants:)0 4359 y FD(QUOTE_ALL)208 4458 y FN(Instructs)g FJ(writer)h FN(objects)g(to)g(quote)f(all)i(\002elds.)0 4605 y FD(QUOTE_MINIMAL)208 4705 y FN(Instructs)39 b FJ(writer)g FN(objects)g(to)h(only)f(quote)f(those)i(\002elds)g(which)f (contain)f(special)i(characters)f(such)g(as)i FK(delimiter)r FN(,)208 4804 y FK(quotec)o(har)20 b FN(or)g(an)o(y)f(of)h(the)g (characters)f(in)i FK(lineterminator)r FN(.)0 4951 y FD(QUOTE_NONNUMERIC)208 5051 y FN(Instructs)e FJ(writer)h FN(objects)g(to)g(quote)f(all)i(non-numeric)c(\002elds.)208 5184 y(Instructs)i(the)h(reader)g(to)g(con)m(v)o(ert)e(all)j (non-quoted)c(\002elds)j(to)h(type)f FK(\003oat)q FN(.)0 5331 y FD(QUOTE_NONE)p 0 5549 3901 4 v 0 5649 a FI(9.1.)52 b FJ(csv)23 b FI(\227)g(CSV)h(File)f(Reading)i(and)e(Wr)q(iting)2191 b(305)p eop end %%Page: 306 318 TeXDict begin 306 317 bop 208 83 a FN(Instructs)20 b FJ(writer)g FN(objects)h(to)g(ne)n(v)o(er)f(quote)g(\002elds.)27 b(When)21 b(the)g(current)f FK(delimiter)j FN(occurs)d(in)h(output)f (data)h(it)g(is)h(preceded)208 183 y(by)e(the)i(current)e FK(escapec)o(har)h FN(character)-5 b(.)27 b(If)22 b FK(escapec)o(har)f FN(is)h(not)f(set,)h(the)g(writer)f(will)h(raise)f FJ(Error)g FN(if)h(an)o(y)e(characters)g(that)208 282 y(require)e(escaping)i(are)g (encountered.)208 415 y(Instructs)f FJ(reader)h FN(to)g(perform)e(no)i (special)g(processing)f(of)h(quote)f(characters.)0 562 y(The)h FJ(csv)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f(e)o (xception:)0 709 y FL(exception)g FD(Error)208 808 y FN(Raised)h(by)g(an)o(y)f(of)h(the)h(functions)d(when)i(an)g(error)f (is)i(detected.)0 1093 y Fv(9.1.2)100 b(Dialects)28 b(and)h(F)m(or)r (matting)g(P)l(ar)o(ameters)0 1296 y FN(T)-7 b(o)17 b(mak)o(e)g(it)h (easier)f(to)g(specify)f(the)h(format)f(of)h(input)f(and)h(output)f (records,)g(speci\002c)h(formatting)e(parameters)h(are)h(grouped)e (together)0 1396 y(into)i(dialects.)24 b(A)17 b(dialect)g(is)g(a)h (subclass)f(of)f(the)h FJ(Dialect)f FN(class)i(ha)n(ving)e(a)h(set)g (of)g(speci\002c)g(methods)f(and)g(a)h(single)g FJ(validate\(\))0 1496 y FN(method.)61 b(When)32 b(creating)f FJ(reader)h FN(or)h FJ(writer)f FN(objects,)j(the)d(programmer)e(can)i(specify)g(a) h(string)f(or)h(a)f(subclass)h(of)g(the)0 1595 y FJ(Dialect)20 b FN(class)i(as)f(the)g(dialect)g(parameter)-5 b(.)25 b(In)20 b(addition)g(to,)h(or)f(instead)h(of,)f(the)h FK(dialect)h FN(parameter)m(,)c(the)j(programmer)d(can)i(also)0 1695 y(specify)c(indi)n(vidual)f(formatting)g(parameters,)h(which)g(ha) n(v)o(e)h(the)g(same)g(names)f(as)i(the)e(attrib)n(utes)h(de\002ned)f (belo)n(w)g(for)g(the)h FJ(Dialect)0 1794 y FN(class.)0 1941 y(Dialects)k(support)e(the)h(follo)n(wing)e(attrib)n(utes:)0 2088 y FD(delimiter)208 2188 y FN(A)i(one-character)e(string)i(used)g (to)g(separate)g(\002elds.)25 b(It)20 b(def)o(aults)g(to)h FJ(',')p FN(.)0 2335 y FD(doublequote)208 2434 y FN(Controls)e(ho)n(w)g (instances)h(of)g FK(quotec)o(har)f FN(appearing)f(inside)i(a)g (\002eld)g(should)f(be)h(themselv)o(es)f(be)h(quoted.)j(When)d FJ(True)p FN(,)g(the)208 2534 y(character)e(is)k(doubled.)h(When)d FJ(False)p FN(,)f(the)h FK(escapec)o(har)h FN(is)g(used)f(as)h(a)g (pre\002x)e(to)h(the)g FK(quotec)o(har)r FN(.)j(It)e(def)o(aults)f(to)g FJ(True)p FN(.)208 2667 y(On)e(output,)f(if)i FK(doublequote)c FN(is)k FJ(False)f FN(and)g(no)f FK(escapec)o(har)i FN(is)g(set,)g FJ(Error)f FN(is)h(raised)g(if)f(a)h FK(quotec)o(har)f FN(is)h(found)e(in)h(a)h(\002eld.)0 2814 y FD(escapechar)208 2913 y FN(A)29 b(one-character)d(string)j(used)g(by)f(the)h(writer)g (to)g(escape)g(the)g FK(delimiter)i FN(if)e FK(quoting)f FN(is)i(set)f(to)g FJ(QUOTE_NONE)f FN(and)h(the)208 3013 y FK(quotec)o(har)18 b FN(if)i FK(doublequote)15 b FN(is)20 b FJ(False)p FN(.)k(On)19 b(reading,)f(the)h FK(escapec)o(har)g FN(remo)o(v)o(es)e(an)o(y)h(special)h(meaning)f(from)g(the)h(follo)n (w-)208 3112 y(ing)g(character)-5 b(.)25 b(It)20 b(def)o(aults)g(to)g FJ(None)p FN(,)g(which)g(disables)g(escaping.)0 3259 y FD(lineterminator)208 3359 y FN(The)f(string)h(used)g(to)h(terminate) e(lines)h(produced)e(by)i(the)g FJ(writer)p FN(.)25 b(It)20 b(def)o(aults)g(to)g FJ('\\r\\n')p FN(.)208 3492 y FL(Note:)j FN(The)17 b FJ(reader)g FN(is)h(hard-coded)c(to)k(recognise)e(either)h FJ('\\r')g FN(or)h FJ('\\n')f FN(as)h(end-of-line,)d(and)i(ignores)g FK(lineterminator)r FN(.)208 3591 y(This)j(beha)n(vior)f(may)g(change)g (in)h(the)h(future.)0 3738 y FD(quotechar)208 3838 y FN(A)g(one-character)e(string)i(used)g(to)h(quote)e(\002elds)i (containing)d(special)j(characters,)e(such)h(as)h(the)g FK(delimiter)h FN(or)f FK(quotec)o(har)r FN(,)d(or)208 3938 y(which)g(contain)g(ne)n(w-line)h(characters.)k(It)c(def)o(aults)g (to)g FJ('"')p FN(.)0 4084 y FD(quoting)208 4184 y FN(Controls)g(when)h (quotes)f(should)g(be)i(generated)d(by)i(the)g(writer)g(and)f (recognised)g(by)h(the)g(reader)-5 b(.)27 b(It)21 b(can)g(tak)o(e)h(on) e(an)o(y)h(of)g(the)208 4284 y FJ(QUOTE_)508 4299 y(*)577 4284 y FN(constants)f(\(see)g(section)g(9.1.1\))f(and)g(def)o(aults)h (to)g FJ(QUOTE_MINIMAL)p FN(.)0 4431 y FD(skipinitialspace)208 4530 y FN(When)g FJ(True)p FN(,)f(whitespace)h(immediately)f(follo)n (wing)f(the)j FK(delimiter)h FN(is)f(ignored.)i(The)d(def)o(ault)g(is)h FJ(False)p FN(.)0 4815 y Fv(9.1.3)100 b(Reader)30 b(Objects)0 5018 y FN(Reader)20 b(objects)h(\()p FJ(DictReader)e FN(instances)h(and)g(objects)h(returned)e(by)h(the)g FJ(reader\(\))g FN(function\))f(ha)n(v)o(e)h(the)g(follo)n(wing)f (public)0 5118 y(methods:)0 5264 y FD(next)p FJ(\(\))208 5364 y FN(Return)g(the)i(ne)o(xt)e(ro)n(w)h(of)g(the)g(reader')-5 b(s)19 b(iterable)h(object)g(as)h(a)f(list,)h(parsed)f(according)e(to)i (the)g(current)f(dialect.)p 0 5549 3901 4 v 0 5649 a FI(306)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 307 319 TeXDict begin 307 318 bop 0 83 a FN(Reader)20 b(objects)g(ha)n(v)o(e)f (the)i(follo)n(wing)d(public)h(attrib)n(utes:)0 230 y FD(dialect)208 330 y FN(A)h(read-only)e(description)h(of)h(the)g (dialect)g(in)g(use)h(by)f(the)g(parser)-5 b(.)0 476 y FD(line_num)208 576 y FN(The)24 b(number)f(of)h(lines)h(read)f(from)g (the)h(source)f(iterator)-5 b(.)38 b(This)25 b(is)g(not)g(the)f(same)h (as)h(the)e(number)f(of)i(records)e(returned,)h(as)208 676 y(records)19 b(can)h(span)g(multiple)f(lines.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 961 y Fv(9.1.4)100 b(Wr)q(iter)29 b(Objects)0 1163 y FJ(Writer)16 b FN(objects)f(\()p FJ(DictWriter)g FN(instances)h(and)f(objects)h(returned)e(by)i(the)g FJ(writer\(\))f FN(function\))f(ha)n(v)o(e)i(the)g(follo)n(wing)e (public)0 1263 y(methods.)23 b(A)18 b FK(r)l(ow)g FN(must)f(be)h(a)f (sequence)g(of)g(strings)g(or)g(numbers)f(for)g FJ(Writer)h FN(objects)g(and)g(a)h(dictionary)d(mapping)h(\002eldnames)g(to)0 1363 y(strings)j(or)g(numbers)f(\(by)h(passing)g(them)g(through)e FJ(str\(\))i FN(\002rst\))h(for)f FJ(DictWriter)f FN(objects.)24 b(Note)c(that)f(comple)o(x)f(numbers)g(are)0 1462 y(written)h(out)f (surrounded)e(by)j(parens.)24 b(This)19 b(may)f(cause)h(some)g (problems)e(for)i(other)f(programs)f(which)h(read)h(CSV)h(\002les)g (\(assuming)0 1562 y(the)o(y)f(support)g(comple)o(x)g(numbers)f(at)j (all\).)0 1709 y FD(writerow)p FJ(\()p FK(r)l(ow)p FJ(\))208 1808 y FN(Write)f(the)h FK(r)l(ow)g FN(parameter)d(to)j(the)f(writer') -5 b(s)20 b(\002le)h(object,)f(formatted)e(according)g(to)j(the)f (current)f(dialect.)0 1955 y FD(writerows)p FJ(\()p FK(r)l(ows)p FJ(\))208 2055 y FN(Write)28 b(all)h(the)f FK(r)l(ows)i FN(parameters)c(\(a)j(list)g(of)f FK(r)l(ow)h FN(objects)f(as)g (described)f(abo)o(v)o(e\))f(to)j(the)f(writer')-5 b(s)28 b(\002le)h(object,)g(formatted)208 2155 y(according)18 b(to)i(the)g(current)f(dialect.)0 2301 y(Writer)h(objects)g(ha)n(v)o(e) g(the)g(follo)n(wing)f(public)g(attrib)n(ute:)0 2448 y FD(dialect)208 2548 y FN(A)h(read-only)e(description)h(of)h(the)g (dialect)g(in)g(use)h(by)f(the)g(writer)-5 b(.)0 2833 y Fv(9.1.5)100 b(Examples)0 3036 y FN(The)20 b(simplest)g(e)o(xample)f (of)h(reading)f(a)h(CSV)i(\002le:)236 3274 y FA(import)44 b(csv)236 3365 y(reader)g(=)h(csv.reader\(open\("some.csv",)40 b("rb"\)\))236 3457 y(for)45 b(row)f(in)g(reader:)416 3548 y(print)g(row)0 3834 y FN(Reading)19 b(a)i(\002le)g(with)f(an)g (alternate)g(format:)236 4073 y FA(import)44 b(csv)236 4164 y(reader)g(=)h(csv.reader\(open\("passwd",)40 b("rb"\),)k (delimiter=':',)f(quoting=csv.QUOTE_NONE\))236 4255 y(for)i(row)f(in)g (reader:)416 4347 y(print)g(row)0 4633 y FN(The)20 b(corresponding)d (simplest)j(possible)g(writing)g(e)o(xample)e(is:)236 4871 y FA(import)44 b(csv)236 4963 y(writer)g(=)h (csv.writer\(open\("some.csv",)40 b("wb"\)\))236 5054 y(writer.writerows\(someiterable\))0 5340 y FN(Re)o(gistering)19 b(a)i(ne)n(w)f(dialect:)p 0 5549 3901 4 v 0 5649 a FI(9.1.)52 b FJ(csv)23 b FI(\227)g(CSV)h(File)f(Reading)i(and)e(Wr)q(iting)2191 b(307)p eop end %%Page: 308 320 TeXDict begin 308 319 bop 236 174 a FA(import)44 b(csv)236 357 y(csv.register_dialect\('unixpwd',)c(delimiter=':',)i (quoting=csv.QUOTE_NONE\))236 540 y(reader)i(=)h (csv.reader\(open\("passwd",)40 b("rb"\),)k('unixpwd'\))0 826 y FN(A)21 b(slightly)f(more)f(adv)n(anced)f(use)j(of)e(the)i (reader)e(\227)i(catching)e(and)g(reporting)f(errors:)236 1064 y FA(import)44 b(csv,)g(sys)236 1156 y(filename)g(=)g("some.csv") 236 1247 y(reader)g(=)h(csv.reader\(open\(filename,)40 b("rb"\)\))236 1338 y(try:)416 1430 y(for)k(row)g(in)h(reader:)595 1521 y(print)f(row)236 1612 y(except)g(csv.Error,)f(e:)416 1704 y(sys.exit\('file)f(\045s,)i(line)h(\045d:)f(\045s')g(\045)h (\(filename,)e(reader.line_num,)f(e\)\))0 1990 y FN(And)20 b(while)g(the)g(module)f(doesn')o(t)g(directly)g(support)g(parsing)g (strings,)h(it)h(can)f(easily)g(be)g(done:)236 2228 y FA(import)44 b(csv)236 2320 y(for)h(row)f(in)g (csv.reader\(['one,two,three']\):)416 2411 y(print)g(row)0 2697 y FN(The)24 b FJ(csv)g FN(module)f(doesn')o(t)g(directly)h (support)f(reading)g(and)g(writing)h(Unicode,)g(b)n(ut)h(it)g(is)g (8-bit-clean)e(sa)n(v)o(e)h(for)g(some)g(problems)0 2797 y(with)h FH(A)t(S)t(C)t(I)t(I)i FN(NUL)c(characters.)32 b(So)23 b(you)f(can)h(write)g(functions)f(or)g(classes)i(that)f(handle) f(the)h(encoding)e(and)i(decoding)d(for)j(you)f(as)0 2897 y(long)d(as)i(you)f(a)n(v)n(oid)f(encodings)g(lik)o(e)h(UTF-16)g (that)g(use)g(NULs.)26 b(UTF-8)19 b(is)j(recommended.)0 3044 y FJ(unicode_csv_reader)28 b FN(belo)n(w)j(is)h(a)f(generator)e (that)i(wraps)g FJ(csv.reader)f FN(to)h(handle)f(Unicode)g(CSV)i(data)f (\(a)g(list)h(of)0 3143 y(Unicode)19 b(strings\).)26 b FJ(utf_8_encoder)18 b FN(is)k(a)f(generator)d(that)j(encodes)e(the)i (Unicode)e(strings)h(as)i(UTF-8,)d(one)h(string)h(\(or)e(ro)n(w\))h(at) 0 3243 y(a)d(time.)24 b(The)16 b(encoded)e(strings)j(are)f(parsed)g(by) g(the)g(CSV)i(reader)m(,)d(and)h FJ(unicode_csv_reader)e FN(decodes)h(the)i(UTF-8-encoded)0 3342 y(cells)k(back)e(into)h (Unicode:)236 3581 y FA(import)44 b(csv)236 3763 y(def)h (unicode_csv_reader\(unicode_csv_data,)38 b(dialect=csv.excel,)2926 3776 y(**)3016 3763 y(kwargs\):)416 3855 y(#)44 b(csv.py)g(doesn't)g (do)g(Unicode;)g(encode)f(temporarily)g(as)i(UTF-8:)416 3946 y(csv_reader)e(=)h(csv.reader\(utf_8_encoder\(unicode_csv_data)o (\),)1492 4037 y(dialect=dialect,)2254 4050 y(**)2344 4037 y(kwargs\))416 4129 y(for)g(row)g(in)h(csv_reader:)595 4220 y(#)g(decode)e(UTF-8)h(back)h(to)f(Unicode,)f(cell)i(by)f(cell:) 595 4311 y(yield)g([unicode\(cell,)e('utf-8'\))i(for)g(cell)g(in)h (row])236 4494 y(def)g(utf_8_encoder\(unicode_csv_data\):)416 4585 y(for)f(line)g(in)h(unicode_csv_data:)595 4677 y(yield)f (line.encode\('utf-8'\))0 4963 y FN(F)o(or)23 b(all)i(other)e (encodings)e(the)j(follo)n(wing)e FJ(UnicodeReader)g FN(and)h FJ(UnicodeWriter)f FN(classes)j(can)e(be)h(used.)35 b(The)o(y)23 b(tak)o(e)h(an)0 5063 y(additional)18 b FK(encoding)e FN(parameter)i(in)h(their)f(constructor)f(and)i(mak)o(e)f (sure)h(that)g(the)g(data)g(passes)g(the)g(real)g(reader)f(or)h(writer) f(encoded)0 5162 y(as)j(UTF-8:)p 0 5549 3901 4 v 0 5649 a FI(308)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 309 321 TeXDict begin 309 320 bop 236 174 a FA(import)44 b(csv,)g(codecs,)g (cStringIO)236 357 y(class)g(UTF8Recoder:)416 448 y(""")416 540 y(Iterator)f(that)h(reads)g(an)h(encoded)e(stream)h(and)g (reencodes)g(the)g(input)g(to)h(UTF-8)416 631 y(""")416 722 y(def)f(__init__\(self,)e(f,)j(encoding\):)595 814 y(self.reader)e(=)i(codecs.getreader\(encoding\)\(f\))416 996 y(def)f(__iter__\(self\):)595 1088 y(return)g(self)416 1270 y(def)g(next\(self\):)595 1362 y(return)g (self.reader.next\(\).encode\("utf-8"\))236 1544 y(class)g (UnicodeReader:)416 1636 y(""")416 1727 y(A)g(CSV)h(reader)e(which)h (will)h(iterate)e(over)h(lines)g(in)h(the)f(CSV)g(file)h("f",)416 1818 y(which)f(is)g(encoded)g(in)g(the)h(given)f(encoding.)416 1910 y(""")416 2092 y(def)g(__init__\(self,)e(f,)j(dialect=csv.excel,)d (encoding="utf-8",)3061 2105 y(**)3151 2092 y(kwds\):)595 2183 y(f)j(=)f(UTF8Recoder\(f,)f(encoding\))595 2275 y(self.reader)g(=)i(csv.reader\(f,)d(dialect=dialect,)2612 2288 y(**)2702 2275 y(kwds\))416 2457 y(def)i(next\(self\):)595 2549 y(row)g(=)h(self.reader.next\(\))595 2640 y(return)f([unicode\(s,) f("utf-8"\))g(for)h(s)h(in)g(row])416 2823 y(def)f(__iter__\(self\):) 595 2914 y(return)g(self)236 3097 y(class)g(UnicodeWriter:)416 3188 y(""")416 3279 y(A)g(CSV)h(writer)e(which)h(will)h(write)f(rows)g (to)g(CSV)g(file)h("f",)416 3371 y(which)f(is)g(encoded)g(in)g(the)h (given)f(encoding.)416 3462 y(""")416 3645 y(def)g(__init__\(self,)e (f,)j(dialect=csv.excel,)d(encoding="utf-8",)3061 3658 y(**)3151 3645 y(kwds\):)595 3736 y(#)j(Redirect)e(output)h(to)g(a)h (queue)595 3827 y(self.queue)e(=)i(cStringIO.StringIO\(\))595 3919 y(self.writer)e(=)i(csv.writer\(self.queue,)c(dialect=dialect,) 3016 3932 y(**)3106 3919 y(kwds\))595 4010 y(self.stream)i(=)i(f)595 4101 y(self.encoder)e(=)h(codecs.getincrementalencoder\(encoding\)\(\)) 416 4284 y(def)g(writerow\(self,)e(row\):)595 4375 y (self.writer.writerow\([s.encode\("utf-8")o(\))d(for)44 b(s)h(in)g(row]\))595 4467 y(#)g(Fetch)f(UTF-8)g(output)f(from)i(the)f (queue)g(...)595 4558 y(data)g(=)h(self.queue.getvalue\(\))595 4649 y(data)f(=)h(data.decode\("utf-8"\))595 4741 y(#)g(...)f(and)g (reencode)g(it)g(into)g(the)h(target)e(encoding)595 4832 y(data)h(=)h(self.encoder.encode\(data\))595 4923 y(#)g(write)f(to)g (the)g(target)g(stream)595 5015 y(self.stream.write\(data\))595 5106 y(#)h(empty)f(queue)595 5197 y(self.queue.truncate\(0\))416 5380 y(def)g(writerows\(self,)e(rows\):)595 5471 y(for)i(row)h(in)f (rows:)774 5562 y(self.writerow\(row\))p 0 5549 3901 4 v 0 5649 a FI(9.1.)52 b FJ(csv)23 b FI(\227)g(CSV)h(File)f(Reading)i (and)e(Wr)q(iting)2191 b(309)p eop end %%Page: 310 322 TeXDict begin 310 321 bop 0 409 a FE(9.2)121 b Fx(ConfigParser)30 b FE(\227)j(Con\002gur)o(ation)j(\002le)d(parser)0 642 y FN(This)23 b(module)f(de\002nes)h(the)g(class)i FJ(ConfigParser)p FN(.)67 b(The)22 b FJ(ConfigParser)g FN(class)i(implements)e(a)i(basic) f(con\002guration)e(\002le)0 741 y(parser)h(language)e(which)i(pro)o (vides)e(a)j(structure)e(similar)h(to)h(what)f(you)f(w)o(ould)h(\002nd) g(on)f(Microsoft)h(W)m(indo)n(ws)f(INI)h(\002les.)32 b(Y)-9 b(ou)22 b(can)0 841 y(use)e(this)h(to)f(write)h(Python)e (programs)f(which)i(can)g(be)g(customized)f(by)h(end)f(users)i(easily) -5 b(.)p 0 931 3901 17 v 0 1222 17 292 v 75 1046 a FL(W)g(ar)o(ning:)48 b FN(This)19 b(library)f(does)h FK(not)f FN(interpret)g(or)h(write)g (the)g(v)n(alue-type)d(pre\002x)o(es)i(used)h(in)g(the)g(W)m(indo)n(ws) f(Re)o(gistry)h(e)o(xtended)75 1146 y(v)o(ersion)g(of)h(INI)g(syntax.)p 3883 1222 V 0 1239 3901 17 v 0 1394 a(The)d(con\002guration)d(\002le)k (consists)f(of)g(sections,)g(led)g(by)g(a)h(`)p FJ([section])p FN(')d(header)h(and)g(follo)n(wed)g(by)g(`)p FJ(name:)99 b(value)p FN(')16 b(entries,)0 1494 y(with)i(continuations)d(in)i(the)h (style)f(of)g(RFC)i(822;)f(`)p FJ(name=value)p FN(')d(is)j(also)g (accepted.)23 b(Note)17 b(that)h(leading)e(whitespace)h(is)h(remo)o(v)o (ed)0 1593 y(from)i(v)n(alues.)27 b(The)21 b(optional)f(v)n(alues)g (can)h(contain)f(format)g(strings)h(which)g(refer)f(to)h(other)f(v)n (alues)h(in)g(the)g(same)g(section,)g(or)g(v)n(alues)0 1693 y(in)26 b(a)g(special)g FJ(DEFAULT)f FN(section.)42 b(Additional)24 b(def)o(aults)h(can)h(be)g(pro)o(vided)d(on)i (initialization)g(and)h(retrie)n(v)n(al.)40 b(Lines)26 b(be)o(ginning)0 1792 y(with)20 b(`)p FJ(#)p FN(')g(or)g(`)p FJ(;)p FN(')g(are)g(ignored)f(and)g(may)h(be)g(used)g(to)g(pro)o(vide)e (comments.)0 1939 y(F)o(or)i(e)o(xample:)236 2178 y FA([My)45 b(Section])236 2269 y(foodir:)f(\045\(dir\)s/whatever)236 2360 y(dir=frob)0 2647 y FN(w)o(ould)28 b(resolv)o(e)f(the)i(`)p FJ(\045\(dir\)s)p FN(')e(to)i(the)f(v)n(alue)g(of)g(`)p FJ(dir)p FN(')g(\(`)p FJ(frob)p FN(')f(in)i(this)g(case\).)50 b(All)29 b(reference)e(e)o(xpansions)g(are)h(done)g(on)0 2746 y(demand.)0 2893 y(Def)o(ault)f(v)n(alues)g(can)g(be)h (speci\002ed)f(by)g(passing)g(them)g(into)g(the)h FJ(ConfigParser)e FN(constructor)f(as)j(a)g(dictionary)-5 b(.)45 b(Additional)0 2993 y(def)o(aults)20 b(may)f(be)i(passed)f(into)g(the)g FJ(get\(\))g FN(method)e(which)i(will)h(o)o(v)o(erride)d(all)j(others.) 0 3140 y FL(class)g FD(RawConfigParser)p FJ(\()p FC([)p FK(defaults)12 b FC(])p FJ(\))208 3239 y FN(The)22 b(basic)h (con\002guration)d(object.)32 b(When)22 b FK(defaults)g FN(is)i(gi)n(v)o(en,)e(it)h(is)h(initialized)e(into)h(the)f(dictionary) f(of)i(intrinsic)f(def)o(aults.)208 3339 y(This)e(class)h(does)f(not)g (support)f(the)h(magical)f(interpolation)g(beha)n(vior)-5 b(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3486 y FL(class)i FD(ConfigParser)p FJ(\()p FC([)p FK(defaults)12 b FC(])p FJ(\))208 3585 y FN(Deri)n(v)o(ed)29 b(class)j(of)e FJ(RawConfigParser)f FN(that)h(implements)g(the)h(magical)f (interpolation)e(feature)i(and)g(adds)h(optional)208 3685 y(ar)o(guments)23 b(to)i(the)g FJ(get\(\))g FN(and)f FJ(items\(\))g FN(methods.)39 b(The)25 b(v)n(alues)f(in)i FK(defaults)e FN(must)h(be)g(appropriate)e(for)h(the)h(`)p FJ(\045\(\)s)p FN(')208 3785 y(string)f(interpolation.)35 b(Note)25 b(that)p 1246 3785 25 4 v 1276 3785 V 84 w FK(name)p 1487 3785 V 1516 3785 V 84 w FN(is)g(an)g(intrinsic)f(def)o (ault;)i(its)f(v)n(alue)f(is)h(the)g(section)f(name,)h(and)f(will)h(o)o (v)o(erride)208 3884 y(an)o(y)19 b(v)n(alue)g(pro)o(vided)f(in)i FK(defaults)p FN(.)208 4016 y(All)f(option)e(names)h(used)g(in)g (interpolation)f(will)i(be)f(passed)g(through)e(the)j FJ(optionxform\(\))d FN(method)h(just)i(lik)o(e)g(an)o(y)e(other)208 4115 y(option)22 b(name)h(reference.)32 b(F)o(or)23 b(e)o(xample,)g (using)g(the)g(def)o(ault)g(implementation)e(of)i FJ(optionxform\(\))f FN(\(which)g(con)m(v)o(erts)208 4215 y(option)d(names)g(to)i(lo)n(wer)e (case\),)h(the)h(v)n(alues)e(`)p FJ(foo)49 b(\045\(bar\)s)p FN(')19 b(and)h(`)p FJ(foo)49 b(\045\(BAR\)s)p FN(')19 b(are)h(equi)n(v)n(alent.)0 4362 y FL(class)h FD(SafeConfigParser)p FJ(\()p FC([)p FK(defaults)12 b FC(])p FJ(\))208 4461 y FN(Deri)n(v)o(ed)26 b(class)j(of)e FJ(ConfigParser)f FN(that)i(implements)f(a)h(more-sane)e(v)n(ariant)h(of)g(the)h(magical) f(interpolation)f(feature.)208 4561 y(This)20 b(implementation)e(is)i (more)g(predictable)e(as)j(well.)k(Ne)n(w)20 b(applications)f(should)g (prefer)g(this)i(v)o(ersion)d(if)j(the)o(y)e(don')o(t)f(need)208 4661 y(to)i(be)g(compatible)f(with)h(older)f(v)o(ersions)h(of)g (Python.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4807 y FL(exception)g FD(NoSectionError)208 4907 y FN(Exception)f(raised)i (when)g(a)g(speci\002ed)g(section)g(is)h(not)f(found.)0 5054 y FL(exception)f FD(DuplicateSectionError)208 5154 y FN(Exception)f(raised)i(if)g FJ(add_section\(\))f FN(is)i(called)f (with)g(the)g(name)g(of)g(a)h(section)f(that)g(is)h(already)e(present.) 0 5300 y FL(exception)g FD(NoOptionError)208 5400 y FN(Exception)f (raised)i(when)g(a)g(speci\002ed)g(option)f(is)i(not)f(found)e(in)j (the)f(speci\002ed)g(section.)p 0 5549 3901 4 v 0 5649 a FI(310)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 311 323 TeXDict begin 311 322 bop 0 83 a FL(exception)19 b FD (InterpolationError)208 183 y FN(Base)i(class)g(for)e(e)o(xceptions)g (raised)h(when)g(problems)e(occur)h(performing)f(string)i (interpolation.)0 330 y FL(exception)f FD(InterpolationDepthError)208 429 y FN(Exception)33 b(raised)h(when)h(string)f(interpolation)f (cannot)h(be)h(completed)e(because)h(the)h(number)e(of)i(iterations)f (e)o(xceeds)208 529 y FJ(MAX_INTERPOLATION_DEPTH)p FN(.)16 b(Subclass)k(of)g FJ(InterpolationError)p FN(.)0 676 y FL(exception)f FD(InterpolationMissingOptionError)208 775 y FN(Exception)14 b(raised)j(when)f(an)h(option)e(referenced)g (from)g(a)j(v)n(alue)e(does)g(not)g(e)o(xist.)24 b(Subclass)17 b(of)g FJ(InterpolationError)p FN(.)208 875 y(Ne)n(w)j(in)g(v)o(ersion) f(2.3.)0 1022 y FL(exception)g FD(InterpolationSyntaxError)208 1121 y FN(Exception)14 b(raised)i(when)f(the)h(source)g(te)o(xt)g(into) g(which)f(substitutions)h(are)g(made)f(does)h(not)g(conform)e(to)i(the) g(required)e(syntax.)208 1221 y(Subclass)20 b(of)g FJ (InterpolationError)p FN(.)48 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 1368 y FL(exception)g FD(MissingSectionHeaderError)208 1468 y FN(Exception)f(raised)i(when)g(attempting)e(to)j(parse)f(a)g (\002le)h(which)f(has)g(no)g(section)g(headers.)0 1614 y FL(exception)f FD(ParsingError)208 1714 y FN(Exception)f(raised)i (when)g(errors)f(occur)g(attempting)g(to)h(parse)g(a)h(\002le.)0 1861 y FD(MAX_INTERPOLATION_DEPTH)208 1961 y FN(The)k(maximum)f(depth)g (for)h(recursi)n(v)o(e)g(interpolation)e(for)i FJ(get\(\))g FN(when)g(the)h FK(r)o(aw)g FN(parameter)e(is)j(f)o(alse.)41 b(This)26 b(is)h(rele)n(v)n(ant)208 2060 y(only)19 b(for)g(the)i FJ(ConfigParser)d FN(class.)0 2207 y FL(See)j(Also:)0 2354 y FN(Module)e FJ(shlex)h FN(\(section)f(22.2\):)208 2454 y(Support)g(for)h(a)i(creating)g(U)t FH(N)t(I)t(X)i FN(shell-lik)o(e)c(mini-languages)f(which)h(can)h(be)g(used)g(as)h(an)e (alternate)h(format)f(for)g(application)208 2553 y(con\002guration)d (\002les.)0 2838 y Fv(9.2.1)100 b(Ra)n(wCon\002gP)l(arser)30 b(Objects)0 3041 y FJ(RawConfigParser)18 b FN(instances)i(ha)n(v)o(e)g (the)g(follo)n(wing)e(methods:)0 3188 y FD(defaults)p FJ(\(\))208 3287 y FN(Return)h(a)i(dictionary)d(containing)h(the)h (instance-wide)f(def)o(aults.)0 3434 y FD(sections)p FJ(\(\))208 3534 y FN(Return)g(a)i(list)g(of)f(the)g(sections)h(a)n(v)n (ailable;)e FJ(DEFAULT)h FN(is)h(not)f(included)e(in)j(the)f(list.)0 3681 y FD(add_section)p FJ(\()p FK(section)p FJ(\))208 3780 y FN(Add)58 b(a)i(section)e(named)g FK(section)h FN(to)g(the)g(instance.)141 b(If)59 b(a)h(section)f(by)f(the)h(gi)n(v)o (en)f(name)g(already)g(e)o(xists,)208 3880 y FJ(DuplicateSectionError) 16 b FN(is)22 b(raised.)0 4027 y FD(has_section)p FJ(\()p FK(section)p FJ(\))208 4127 y FN(Indicates)16 b(whether)g(the)h(named)f (section)g(is)i(present)e(in)i(the)f(con\002guration.)k(The)16 b FJ(DEFAULT)h FN(section)f(is)i(not)f(ackno)n(wledged.)0 4273 y FD(options)p FJ(\()p FK(section)p FJ(\))208 4373 y FN(Returns)j(a)g(list)h(of)f(options)g(a)n(v)n(ailable)f(in)i(the)f (speci\002ed)g FK(section)p FN(.)0 4520 y FD(has_option)p FJ(\()p FK(section,)e(option)p FJ(\))208 4620 y FN(If)e(the)g(gi)n(v)o (en)g(section)g(e)o(xists,)h(and)f(contains)g(the)h(gi)n(v)o(en)e (option,)h(return)f FJ(True)p FN(;)i(otherwise)f(return)g FJ(False)p FN(.)47 b(Ne)n(w)17 b(in)g(v)o(ersion)208 4719 y(1.6.)0 4866 y FD(read)p FJ(\()p FK(\002lenames)p FJ(\))208 4966 y FN(Attempt)24 b(to)i(read)e(and)h(parse)g(a)g(list)h (of)f(\002lenames,)h(returning)d(a)j(list)g(of)f(\002lenames)g(which)f (were)h(successfully)g(parsed.)39 b(If)208 5065 y FK(\002lenames)21 b FN(is)j(a)f(string)g(or)f(Unicode)g(string,)h(it)g(is)h(treated)e(as) i(a)f(single)g(\002lename.)32 b(If)23 b(a)g(\002le)g(named)f(in)h FK(\002lenames)f FN(cannot)g(be)208 5165 y(opened,)i(that)g(\002le)i (will)f(be)g(ignored.)37 b(This)25 b(is)g(designed)f(so)h(that)g(you)f (can)g(specify)g(a)i(list)f(of)g(potential)f(con\002guration)e(\002le) 208 5265 y(locations)g(\(for)h(e)o(xample,)f(the)i(current)e(directory) -5 b(,)21 b(the)j(user')-5 b(s)23 b(home)g(directory)-5 b(,)22 b(and)g(some)i(system-wide)e(directory\),)g(and)208 5364 y(all)27 b(e)o(xisting)e(con\002guration)f(\002les)j(in)g(the)g (list)g(will)g(be)g(read.)43 b(If)26 b(none)f(of)i(the)f(named)f (\002les)j(e)o(xist,)g(the)e FJ(ConfigParser)p 0 5549 3901 4 v 0 5649 a FI(9.2.)52 b FJ(ConfigParser)21 b FI(\227)i (Con\002gur)o(ation)h(\002le)f(parser)1964 b(311)p eop end %%Page: 312 324 TeXDict begin 312 323 bop 208 83 a FN(instance)27 b(will)h(contain)e (an)i(empty)e(dataset.)47 b(An)28 b(application)e(which)h(requires)f (initial)i(v)n(alues)f(to)h(be)f(loaded)g(from)f(a)i(\002le)208 183 y(should)19 b(load)g(the)i(required)d(\002le)j(or)f(\002les)h (using)f FJ(readfp\(\))f FN(before)g(calling)g FJ(read\(\))h FN(for)g(an)o(y)f(optional)g(\002les:)444 407 y FA(import)44 b(ConfigParser,)e(os)444 589 y(config)i(=)g (ConfigParser.ConfigParser\(\))444 681 y (config.readfp\(open\('defaults.cfg'\)\))444 772 y (config.read\(['site.cfg',)d (os.path.expanduser\('\230/.myapp.cfg'\)]\))208 928 y FN(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(Returns)h(list)i(of)e (successfully)f(parsed)h(\002lenames.)0 1075 y FD(readfp)p FJ(\()p FK(fp)p FC([)p FK(,)f(\002lename)12 b FC(])p FJ(\))208 1175 y FN(Read)18 b(and)g(parse)g(con\002guration)d(data)j (from)f(the)i(\002le)g(or)e(\002le-lik)o(e)i(object)e(in)i FK(fp)f FN(\(only)f(the)h FJ(readline\(\))f FN(method)g(is)i(used\).) 208 1274 y(If)h FK(\002lename)f FN(is)i(omitted)e(and)h FK(fp)g FN(has)h(a)f FJ(name)g FN(attrib)n(ute,)g(that)g(is)h(used)f (for)g FK(\002lename)p FN(;)f(the)h(def)o(ault)g(is)h(`)p FJ(<???>)p FN('.)0 1421 y FD(get)p FJ(\()p FK(section,)e(option)p FJ(\))208 1521 y FN(Get)h(an)g FK(option)f FN(v)n(alue)h(for)f(the)i (named)e FK(section)p FN(.)0 1668 y FD(getint)p FJ(\()p FK(section,)f(option)p FJ(\))208 1767 y FN(A)i(con)m(v)o(enience)d (method)i(which)h(coerces)g(the)g FK(option)f FN(in)h(the)g (speci\002ed)g FK(section)g FN(to)g(an)h(inte)o(ger)-5 b(.)0 1914 y FD(getfloat)p FJ(\()p FK(section,)18 b(option)p FJ(\))208 2014 y FN(A)i(con)m(v)o(enience)d(method)i(which)h(coerces)g (the)g FK(option)f FN(in)h(the)g(speci\002ed)g FK(section)g FN(to)g(a)h(\003oating)f(point)f(number)-5 b(.)0 2161 y FD(getboolean)p FJ(\()p FK(section,)18 b(option)p FJ(\))208 2260 y FN(A)30 b(con)m(v)o(enience)d(method)i(which)h(coerces)f(the)i FK(option)d FN(in)j(the)f(speci\002ed)g FK(section)g FN(to)g(a)h(Boolean)e(v)n(alue.)54 b(Note)30 b(that)h(the)208 2360 y(accepted)18 b(v)n(alues)h(for)g(the)g(option)g(are)g FJ("1")p FN(,)h FJ("yes")p FN(,)f FJ("true")p FN(,)f(and)h FJ("on")p FN(,)h(which)e(cause)i(this)g(method)e(to)i(return)e FJ(True)p FN(,)208 2460 y(and)i FJ("0")p FN(,)g FJ("no")p FN(,)g FJ("false")p FN(,)g(and)g FJ("off")p FN(,)g(which)g(cause)g(it)h (to)g(return)e FJ(False)p FN(.)26 b(These)20 b(string)h(v)n(alues)f (are)g(check)o(ed)f(in)i(a)208 2559 y(case-insensiti)n(v)o(e)e(manner) -5 b(.)24 b(An)o(y)19 b(other)g(v)n(alue)h(will)h(cause)f(it)h(to)f (raise)h FJ(ValueError)p FN(.)0 2706 y FD(items)p FJ(\()p FK(section)p FJ(\))208 2806 y FN(Return)e(a)i(list)g(of)f FJ(\()p FK(name)p FJ(,)48 b FK(value)p FJ(\))20 b FN(pairs)g(for)f (each)h(option)f(in)i(the)f(gi)n(v)o(en)f FK(section)p FN(.)0 2953 y FD(set)p FJ(\()p FK(section,)g(option,)g(value)p FJ(\))208 3052 y FN(If)29 b(the)h(gi)n(v)o(en)f(section)g(e)o(xists,)k (set)e(the)f(gi)n(v)o(en)e(option)h(to)h(the)g(speci\002ed)f(v)n(alue;) 34 b(otherwise)c(raise)g FJ(NoSectionError)p FN(.)208 3152 y(While)f(it)h(is)h(possible)e(to)g(use)h FJ(RawConfigParser)d FN(\(or)i FJ(ConfigParser)e FN(with)j FK(r)o(aw)g FN(parameters)e(set)i (to)g(true\))e(for)208 3252 y FK(internal)21 b FN(storage)g(of)h (non-string)e(v)n(alues,)i(full)g(functionality)e(\(including)g (interpolation)g(and)h(output)g(to)h(\002les\))h(can)e(only)h(be)208 3351 y(achie)n(v)o(ed)c(using)i(string)g(v)n(alues.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(1.6.)0 3498 y FD(write)p FJ(\()p FK(\002leobject)q FJ(\))208 3598 y FN(Write)25 b(a)g(representation)e(of)h(the)h(con\002guration)d(to)j(the)f (speci\002ed)h(\002le)g(object.)38 b(This)25 b(representation)e(can)h (be)h(parsed)f(by)g(a)208 3697 y(future)19 b FJ(read\(\))g FN(call.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.6.)0 3844 y FD(remove_option)p FJ(\()p FK(section,)e(option)p FJ(\))208 3944 y FN(Remo)o(v)o(e)g(the)i(speci\002ed)f FK(option)f FN(from)h(the)g(speci\002ed)h FK(section)p FN(.)24 b(If)18 b(the)h(section)f(does)h(not)f(e)o(xist,)h(raise)g FJ(NoSectionError)p FN(.)208 4043 y(If)h(the)g(option)f(e)o(xisted)g(to)i(be)f(remo)o(v)o (ed,)d(return)i FJ(True)p FN(;)i(otherwise)e(return)g FJ(False)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.6.)0 4190 y FD(remove_section)p FJ(\()p FK(section)p FJ(\))208 4290 y FN(Remo)o(v)o(e)26 b(the)i(speci\002ed)f FK(section)h FN(from)e(the)i(con\002guration.)45 b(If)27 b(the)h(section)f(in)h(f)o (act)g(e)o(xisted,)h(return)e FJ(True)p FN(.)47 b(Otherwise)208 4390 y(return)19 b FJ(False)p FN(.)0 4536 y FD(optionxform)p FJ(\()p FK(option)p FJ(\))208 4636 y FN(T)m(ransforms)d(the)h(option)g (name)g FK(option)g FN(as)h(found)e(in)i(an)g(input)f(\002le)h(or)f(as) i(passed)e(in)h(by)g(client)f(code)g(to)h(the)g(form)f(that)h(should) 208 4736 y(be)h(used)g(in)g(the)g(internal)f(structures.)24 b(The)19 b(def)o(ault)g(implementation)e(returns)h(a)h(lo)n(wer)n (-case)g(v)o(ersion)f(of)h FK(option)p FN(;)f(subclasses)208 4835 y(may)g(o)o(v)o(erride)f(this)i(or)g(client)g(code)f(can)h(set)h (an)e(attrib)n(ute)h(of)g(this)g(name)g(on)f(instances)h(to)g(af)n (fect)f(this)i(beha)n(vior)-5 b(.)23 b(Setting)c(this)208 4935 y(to)h FJ(str\(\))p FN(,)f(for)h(e)o(xample,)f(w)o(ould)g(mak)o(e) h(option)f(names)h(case)g(sensiti)n(v)o(e.)p 0 5549 3901 4 v 0 5649 a FI(312)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 313 325 TeXDict begin 313 324 bop 0 83 a Fv(9.2.2)100 b(Con\002gP)l(arser)30 b(Objects)0 286 y FN(The)i FJ(ConfigParser)f FN(class)j(e)o(xtends)d (some)i(methods)e(of)i(the)f FJ(RawConfigParser)f FN(interf)o(ace,)j (adding)d(some)i(optional)0 386 y(ar)o(guments.)0 532 y FD(get)p FJ(\()p FK(section,)19 b(option)p FC([)p FK(,)f(r)o(aw)p FC([)p FK(,)j(var)o(s)12 b FC(])g(])p FJ(\))208 632 y FN(Get)19 b(an)g FK(option)e FN(v)n(alue)h(for)g(the)h(named)f FK(section)p FN(.)24 b(All)c(the)e(`)p FJ(\045)p FN(')h(interpolations) e(are)i(e)o(xpanded)d(in)j(the)g(return)e(v)n(alues,)i(based)f(on)208 732 y(the)i(def)o(aults)g(passed)g(into)g(the)g(constructor)m(,)d(as)k (well)g(as)g(the)f(options)f FK(var)o(s)i FN(pro)o(vided,)d(unless)i (the)g FK(r)o(aw)h FN(ar)o(gument)d(is)j(true.)0 879 y FD(items)p FJ(\()p FK(section)p FC([)p FK(,)d(r)o(aw)p FC([)p FK(,)j(var)o(s)12 b FC(])g(])p FJ(\))208 978 y FN(Return)22 b(a)i(list)g(of)f FJ(\()p FK(name)p FJ(,)48 b FK(value)p FJ(\))22 b FN(pairs)i(for)e(each)h(option)f(in)h(the)g(gi) n(v)o(en)f FK(section)p FN(.)33 b(Optional)23 b(ar)o(guments)e(ha)n(v)o (e)h(the)h(same)208 1078 y(meaning)18 b(as)j(for)f(the)g FJ(get\(\))g FN(method.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1363 y Fv(9.2.3)100 b(Saf)m(eCon\002gP)l(arser)31 b(Objects)0 1566 y FN(The)25 b FJ(SafeConfigParser)d FN(class)k(implements)e(the)h (same)g(e)o(xtended)e(interf)o(ace)h(as)i FJ(ConfigParser)p FN(,)e(with)h(the)g(follo)n(wing)0 1665 y(addition:)0 1812 y FD(set)p FJ(\()p FK(section,)19 b(option,)g(value)p FJ(\))208 1912 y FN(If)d(the)h(gi)n(v)o(en)e(section)h(e)o(xists,)i (set)f(the)g(gi)n(v)o(en)e(option)h(to)g(the)h(speci\002ed)f(v)n(alue;) i(otherwise)e(raise)g FJ(NoSectionError)p FN(.)22 b FK(value)208 2011 y FN(must)e(be)g(a)h(string)e(\()p FJ(str)h FN(or)g FJ(unicode)p FN(\);)f(if)i(not,)e FJ(TypeError)h FN(is)h(raised.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 2339 y FE(9.3)121 b Fx(robotparser)30 b FE(\227)j(P)-5 b(arser)33 b(f)l(or)h(robots)n (.txt)0 2572 y FN(This)17 b(module)f(pro)o(vides)g(a)h(single)g(class,) i FJ(RobotFileParser)p FN(,)c(which)i(answers)g(questions)f(about)g (whether)h(or)f(not)h(a)h(particular)0 2671 y(user)25 b(agent)g(can)h(fetch)f(a)h(URL)g(on)f(the)h(W)-7 b(eb)26 b(site)h(that)e(published)f(the)i(`)p FO(robots)o(.txt)p FN(')e(\002le.)41 b(F)o(or)26 b(more)e(details)i(on)g(the)f(structure)g (of)0 2771 y(`)p FO(robots)o(.txt)p FN(')18 b(\002les,)j(see)g FO(http://www)l(.robotstxt.org/wc/no)o(rob)o(ots)o(.h)o(tml)-6 b FN(.)0 2918 y FL(class)21 b FD(RobotFileParser)p FJ(\(\))208 3017 y FN(This)f(class)h(pro)o(vides)e(a)h(set)h(of)f(methods)f(to)h (read,)g(parse)g(and)f(answer)h(questions)g(about)f(a)i(single)f(`)p FO(robots)o(.txt)p FN(')e(\002le.)208 3150 y FD(set_url)p FJ(\()p FK(url)p FJ(\))390 3250 y FN(Sets)j(the)g(URL)f(referring)f(to) h(a)g(`)p FO(robots)o(.txt)p FN(')f(\002le.)208 3383 y FD(read)p FJ(\(\))390 3482 y FN(Reads)i(the)f(`)p FO(robots)o(.txt)p FN(')e(URL)j(and)f(feeds)g(it)h(to)f(the)g(parser)-5 b(.)208 3615 y FD(parse)p FJ(\()p FK(lines)p FJ(\))390 3715 y FN(P)o(arses)21 b(the)f(lines)h(ar)o(gument.)208 3848 y FD(can_fetch)p FJ(\()p FK(user)o(a)o(g)o(ent,)c(url)p FJ(\))390 3947 y FN(Returns)26 b FJ(True)f FN(if)h(the)f FK(user)o(a)o(g)o(ent)h FN(is)h(allo)n(wed)d(to)i(fetch)f(the)g FK(url)h FN(according)e(to)h(the)h(rules)f(contained)f(in)i(the)f (parsed)390 4047 y(`)p FO(robots)o(.txt)p FN(')18 b(\002le.)208 4180 y FD(mtime)p FJ(\(\))390 4279 y FN(Returns)j(the)g(time)h(the)f FJ(robots.txt)f FN(\002le)h(w)o(as)h(last)g(fetched.)27 b(This)21 b(is)h(useful)f(for)f(long-running)e(web)j(spiders)f(that)390 4379 y(need)g(to)g(check)f(for)h(ne)n(w)g FJ(robots.txt)f FN(\002les)i(periodically)-5 b(.)208 4512 y FD(modified)p FJ(\(\))390 4611 y FN(Sets)21 b(the)g(time)f(the)g FJ(robots.txt)f FN(\002le)i(w)o(as)g(last)g(fetched)e(to)h(the)h(current)d(time.)0 4758 y(The)i(follo)n(wing)e(e)o(xample)h(demonstrates)g(basic)h(use)h (of)f(the)g(RobotFileP)o(arser)f(class.)p 0 5549 3901 4 v 0 5649 a FI(9.3.)52 b FJ(robotparser)21 b FI(\227)i(P)m(arser)f(f)n (or)h(robots)o(.txt)2172 b(313)p eop end %%Page: 314 326 TeXDict begin 314 325 bop 236 83 a FA(>>>)45 b(import)e(robotparser)236 174 y(>>>)i(rp)f(=)h(robotparser.RobotFileParser\(\))236 266 y(>>>)g(rp.set_url\("http://www.musi-cal.com/)o(robots)o(.txt"\)) 236 357 y(>>>)g(rp.read\(\))236 448 y(>>>)g(rp.can_fetch\(")1046 461 y(*)1091 448 y(",)d("http://www.musi-cal.com/cgi-bin/sea)o(rch?ci)o (ty=San)o(+Franc)o(isco"\))236 540 y(False)236 631 y(>>>)j (rp.can_fetch\(")1046 644 y(*)1091 631 y(",)d ("http://www.musi-cal.com/"\))236 722 y(True)0 1232 y FE(9.4)121 b Fx(netrc)32 b FE(\227)g(netrc)i(\002le)f(processing)0 1465 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.5.2.)0 1612 y(The)h FJ(netrc)g FN(class)h(parses)f(and)g(encapsulates)f(the)h (netrc)g(\002le)h(format)e(used)h(by)g(the)i(U)t FH(N)t(I)t(X)h FL(ftp)d FN(program)e(and)i(other)f(FTP)i(clients.)0 1759 y FL(class)g FD(netrc)p FJ(\()p FC([)p FK(\002le)12 b FC(])p FJ(\))208 1859 y FN(A)32 b FJ(netrc)f FN(instance)g(or)g (subclass)h(instance)f(encapsulates)g(data)g(from)g(a)h(netrc)f (\002le.)59 b(The)32 b(initialization)f(ar)o(gument,)g(if)208 1958 y(present,)c(speci\002es)h(the)f(\002le)h(to)f(parse.)45 b(If)27 b(no)g(ar)o(gument)e(is)j(gi)n(v)o(en,)f(the)g(\002le)h(`)p FO(.netrc)p FN(')e(in)h(the)g(user')-5 b(s)27 b(home)f(directory)g (will)208 2058 y(be)21 b(read.)29 b(P)o(arse)21 b(errors)g(will)h (raise)g FJ(NetrcParseError)e FN(with)h(diagnostic)g(information)e (including)h(the)h(\002le)h(name,)f(line)208 2157 y(number)m(,)c(and)j (terminating)f(tok)o(en.)0 2304 y FL(exception)g FD(NetrcParseError)208 2404 y FN(Exception)j(raised)h(by)h(the)g FJ(netrc)f FN(class)i(when)e(syntactical)h(errors)f(are)h(encountered)d(in)j (source)f(te)o(xt.)36 b(Instances)23 b(of)h(this)208 2504 y(e)o(xception)18 b(pro)o(vide)g(three)h(interesting)g(attrib)n (utes:)25 b FJ(msg)20 b FN(is)h(a)g(te)o(xtual)e(e)o(xplanation)f(of)i (the)g(error)m(,)e FJ(filename)h FN(is)i(the)f(name)208 2603 y(of)f(the)i(source)e(\002le,)i(and)e FJ(lineno)h FN(gi)n(v)o(es)g(the)g(line)g(number)f(on)g(which)h(the)g(error)f(w)o (as)i(found.)0 2888 y Fv(9.4.1)100 b(netrc)28 b(Objects)0 3091 y FN(A)21 b FJ(netrc)f FN(instance)f(has)i(the)f(follo)n(wing)f (methods:)0 3238 y FD(authenticators)p FJ(\()p FK(host)q FJ(\))208 3337 y FN(Return)k(a)i(3-tuple)e FJ(\()p FK(lo)o(gin)p FJ(,)49 b FK(account)q FJ(,)f FK(passwor)m(d)r FJ(\))24 b FN(of)g(authenticators)f(for)h FK(host)q FN(.)38 b(If)24 b(the)g(netrc)g(\002le)h(did)f(not)g(contain)g(an)208 3437 y(entry)19 b(for)h(the)g(gi)n(v)o(en)f(host,)i(return)e(the)h (tuple)g(associated)g(with)h(the)f(`def)o(ault')f(entry)-5 b(.)25 b(If)20 b(neither)f(matching)g(host)i(nor)e(def)o(ault)208 3537 y(entry)g(is)i(a)n(v)n(ailable,)f(return)f FJ(None)p FN(.)0 3684 y FD(__repr__)p FJ(\(\))208 3783 y FN(Dump)27 b(the)i(class)h(data)f(as)g(a)h(string)e(in)h(the)g(format)f(of)g(a)h (netrc)g(\002le.)51 b(\(This)29 b(discards)f(comments)g(and)g(may)g (reorder)g(the)208 3883 y(entries.\))0 4030 y(Instances)20 b(of)g FJ(netrc)f FN(ha)n(v)o(e)h(public)f(instance)h(v)n(ariables:)0 4177 y FD(hosts)208 4276 y FN(Dictionary)i(mapping)f(host)i(names)g(to) h FJ(\()p FK(lo)o(gin)p FJ(,)48 b FK(account)q FJ(,)g FK(passwor)m(d)r FJ(\))23 b FN(tuples.)35 b(The)23 b(`def)o(ault')f (entry)-5 b(,)22 b(if)i(an)o(y)-5 b(,)23 b(is)h(repre-)208 4376 y(sented)19 b(as)i(a)g(pseudo-host)d(by)i(that)g(name.)0 4523 y FD(macros)208 4622 y FN(Dictionary)e(mapping)h(macro)g(names)h (to)g(string)g(lists.)0 4769 y FL(Note:)j FN(P)o(assw)o(ords)16 b(are)h(limited)g(to)g(a)g(subset)g(of)g(the)g(ASCII)g(character)e (set.)25 b(V)-9 b(ersions)16 b(of)h(this)g(module)f(prior)f(to)i(2.3)g (were)f(e)o(xtremely)0 4869 y(limited.)40 b(Starting)25 b(with)g(2.3,)h(all)g(ASCII)f(punctuation)e(is)j(allo)n(wed)f(in)g (passw)o(ords.)40 b(Ho)n(we)n(v)o(er)m(,)24 b(note)h(that)g(whitespace) g(and)g(non-)0 4968 y(printable)c(characters)h(are)g(not)g(allo)n(wed)g (in)g(passw)o(ords.)31 b(This)23 b(is)g(a)g(limitation)f(of)g(the)g(w)o (ay)h(the)f(.netrc)g(\002le)h(is)g(parsed)f(and)g(may)g(be)0 5068 y(remo)o(v)o(ed)c(in)i(the)g(future.)p 0 5549 3901 4 v 0 5649 a FI(314)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 315 327 TeXDict begin 315 326 bop 0 86 a FE(9.5)121 b Fx(xdrlib)31 b FE(\227)i(Encode)i(and)f(decode)i(XDR)d(data)0 319 y FN(The)22 b FJ(xdrlib)g FN(module)f(supports)g(the)h(External)f(Data) i(Representation)e(Standard)g(as)i(described)e(in)h(RFC)i(1014,)d (written)h(by)g(Sun)0 419 y(Microsystems,)d(Inc.)25 b(June)20 b(1987.)j(It)e(supports)e(most)h(of)g(the)g(data)g(types)g(described)f (in)i(the)f(RFC.)0 566 y(The)e FJ(xdrlib)g FN(module)f(de\002nes)i(tw)o (o)g(classes,)g(one)f(for)g(packing)f(v)n(ariables)h(into)h(XDR)g (representation,)d(and)j(another)e(for)h(unpack-)0 665 y(ing)i(from)f(XDR)i(representation.)i(There)c(are)h(also)h(tw)o(o)f(e) o(xception)f(classes.)0 812 y FL(class)i FD(Packer)p FJ(\(\))208 912 y(Packer)30 b FN(is)h(the)g(class)g(for)f(packing)f (data)h(into)h(XDR)g(representation.)54 b(The)30 b FJ(Packer)g FN(class)i(is)f(instantiated)f(with)h(no)208 1011 y(ar)o(guments.)0 1158 y FL(class)21 b FD(Unpacker)p FJ(\()p FK(data)p FJ(\))208 1258 y(Unpacker)f FN(is)i(the)g(complementary)c(class)23 b(which)e(unpacks)f(XDR)i(data)f(v)n(alues)g(from)g(a)g(string)g(b)n (uf)n(fer)-5 b(.)28 b(The)21 b(input)g(b)n(uf)n(fer)208 1358 y(is)g(gi)n(v)o(en)e(as)i FK(data)p FN(.)0 1504 y FL(See)g(Also:)0 1651 y FN(RFC)h(1014,)c(\223)p FK(XDR:)i(External)g (Data)f(Repr)m(esentation)g(Standar)m(d)p FN(\224)208 1751 y(This)24 b(RFC)h(de\002ned)e(the)h(encoding)e(of)h(data)h(which)f (w)o(as)i(XDR)g(at)f(the)g(time)g(this)h(module)d(w)o(as)j(originally)d (written.)36 b(It)24 b(has)208 1851 y(apparently)18 b(been)h(obsoleted) g(by)h(RFC)i(1832.)0 1997 y(RFC)g(1832,)c(\223)p FK(XDR:)i(External)g (Data)f(Repr)m(esentation)g(Standar)m(d)p FN(\224)208 2097 y(Ne)n(wer)g(RFC)j(that)e(pro)o(vides)f(a)h(re)n(vised)g (de\002nition)f(of)h(XDR.)0 2382 y Fv(9.5.1)100 b(P)l(ac)n(k)n(er)29 b(Objects)0 2585 y FJ(Packer)20 b FN(instances)g(ha)n(v)o(e)f(the)i (follo)n(wing)d(methods:)0 2732 y FD(get_buffer)p FJ(\(\))208 2831 y FN(Returns)i(the)g(current)f(pack)g(b)n(uf)n(fer)g(as)i(a)g (string.)0 2978 y FD(reset)p FJ(\(\))208 3078 y FN(Resets)g(the)f(pack) g(b)n(uf)n(fer)f(to)h(the)g(empty)f(string.)0 3225 y(In)i(general,)f (you)h(can)g(pack)f(an)o(y)h(of)g(the)g(most)g(common)f(XDR)i(data)f (types)g(by)g(calling)g(the)g(appropriate)e FJ(pack_)p FK(type)p FJ(\(\))h FN(method.)0 3324 y(Each)34 b(method)f(tak)o(es)h (a)h(single)f(ar)o(gument,)h(the)f(v)n(alue)g(to)g(pack.)66 b(The)34 b(follo)n(wing)f(simple)h(data)g(type)g(packing)e(methods)i (are)0 3424 y(supported:)42 b FJ(pack_uint\(\))p FN(,)30 b FJ(pack_int\(\))p FN(,)h FJ(pack_enum\(\))p FN(,)f FJ(pack_bool\(\))p FN(,)g FJ(pack_uhyper\(\))p FN(,)g(and)f FJ(pack_-)0 3524 y(hyper\(\))p FN(.)0 3670 y FD(pack_float)p FJ(\()p FK(value)p FJ(\))208 3770 y FN(P)o(acks)20 b(the)g (single-precision)e(\003oating)i(point)f(number)f FK(value)p FN(.)0 3917 y FD(pack_double)p FJ(\()p FK(value)p FJ(\))208 4017 y FN(P)o(acks)i(the)g(double-precision)d(\003oating)i(point)h (number)e FK(value)p FN(.)0 4163 y(The)i(follo)n(wing)e(methods)i (support)e(packing)h(strings,)h(bytes,)g(and)f(opaque)g(data:)0 4310 y FD(pack_fstring)p FJ(\()p FK(n,)f(s)p FJ(\))208 4410 y FN(P)o(acks)k(a)g(\002x)o(ed)f(length)g(string,)h FK(s)p FN(.)31 b FK(n)22 b FN(is)h(the)f(length)f(of)h(the)g(string)g (b)n(ut)g(it)g(is)h FK(not)f FN(pack)o(ed)f(into)g(the)h(data)g(b)n(uf) n(fer)-5 b(.)29 b(The)22 b(string)g(is)208 4510 y(padded)c(with)i(null) g(bytes)g(if)h(necessary)e(to)i(guaranteed)d(4)i(byte)g(alignment.)0 4656 y FD(pack_fopaque)p FJ(\()p FK(n,)e(data)p FJ(\))208 4756 y FN(P)o(acks)i(a)g(\002x)o(ed)g(length)f(opaque)g(data)h(stream,) g(similarly)g(to)g FJ(pack_fstring\(\))p FN(.)0 4903 y FD(pack_string)p FJ(\()p FK(s)p FJ(\))208 5003 y FN(P)o(acks)j(a)g(v) n(ariable)f(length)g(string,)h FK(s)p FN(.)35 b(The)23 b(length)f(of)g(the)i(string)e(is)i(\002rst)g(pack)o(ed)e(as)i(an)f (unsigned)e(inte)o(ger)m(,)h(then)h(the)g(string)208 5102 y(data)d(is)h(pack)o(ed)e(with)h FJ(pack_fstring\(\))p FN(.)0 5249 y FD(pack_opaque)p FJ(\()p FK(data)p FJ(\))208 5349 y FN(P)o(acks)g(a)g(v)n(ariable)f(length)h(opaque)e(data)i (string,)g(similarly)g(to)g FJ(pack_string\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(9.5.)52 b FJ(xdrlib)22 b FI(\227)h(Encode)h(and)f(decode)h(XDR)f(data)2023 b(315)p eop end %%Page: 316 328 TeXDict begin 316 327 bop 0 83 a FD(pack_bytes)p FJ(\()p FK(bytes)p FJ(\))208 183 y FN(P)o(acks)20 b(a)g(v)n(ariable)f(length)h (byte)f(stream,)h(similarly)g(to)h FJ(pack_string\(\))p FN(.)0 330 y(The)f(follo)n(wing)e(methods)i(support)e(packing)h(arrays) h(and)f(lists:)0 476 y FD(pack_list)p FJ(\()p FK(list,)g(pac)n(k)p 802 476 25 4 v 29 w(item)p FJ(\))208 576 y FN(P)o(acks)g(a)h FK(list)j FN(of)c(homogeneous)d(items.)26 b(This)19 b(method)g(is)h (useful)f(for)g(lists)j(with)d(an)h(indeterminate)e(size;)i(i.e.)25 b(the)20 b(size)g(is)h(not)208 676 y(a)n(v)n(ailable)j(until)h(the)g (entire)g(list)h(has)f(been)f(w)o(alk)o(ed.)39 b(F)o(or)25 b(each)f(item)i(in)f(the)g(list,)i(an)e(unsigned)e(inte)o(ger)h FJ(1)h FN(is)h(pack)o(ed)e(\002rst,)208 775 y(follo)n(wed)c(by)i(the)f (data)h(v)n(alue)f(from)g(the)h(list.)31 b FK(pac)n(k)p 1735 775 V 29 w(item)22 b FN(is)h(the)f(function)e(that)i(is)h(called)f (to)g(pack)f(the)h(indi)n(vidual)e(item.)30 b(At)208 875 y(the)20 b(end)f(of)h(the)h(list,)g(an)f(unsigned)e(inte)o(ger)h FJ(0)i FN(is)g(pack)o(ed.)208 1008 y(F)o(or)e(e)o(xample,)g(to)h(pack)g (a)g(list)i(of)e(inte)o(gers,)f(the)h(code)f(might)h(appear)f(lik)o(e)h (this:)444 1232 y FA(import)44 b(xdrlib)444 1323 y(p)g(=)h (xdrlib.Packer\(\))444 1415 y(p.pack_list\([1,)d(2,)j(3],)f (p.pack_int\))0 1618 y FD(pack_farray)p FJ(\()p FK(n,)18 b(arr)o(ay)-5 b(,)20 b(pac)n(k)p 1062 1618 V 29 w(item)p FJ(\))208 1718 y FN(P)o(acks)e(a)h(\002x)o(ed)f(length)g(list)i(\()p FK(arr)o(ay)p FN(\))e(of)g(homogeneous)d(items.)25 b FK(n)19 b FN(is)h(the)e(length)g(of)h(the)f(list;)j(it)e(is)h FK(not)e FN(pack)o(ed)f(into)i(the)f(b)n(uf)n(fer)m(,)208 1817 y(b)n(ut)24 b(a)g FJ(ValueError)f FN(e)o(xception)f(is)j(raised)f (if)g FJ(len\()p FK(arr)o(ay)p FJ(\))f FN(is)i(not)f(equal)f(to)h FK(n)p FN(.)37 b(As)25 b(abo)o(v)o(e,)e FK(pac)n(k)p 3226 1817 V 29 w(item)h FN(is)h(the)f(function)208 1917 y(used)19 b(to)i(pack)e(each)h(element.)0 2064 y FD(pack_array)p FJ(\()p FK(list,)f(pac)n(k)p 852 2064 V 29 w(item)p FJ(\))208 2164 y FN(P)o(acks)i(a)g(v)n(ariable)f(length)g FK(list)k FN(of)d(homogeneous)d(items.)28 b(First,)22 b(the)f(length)f(of)h(the)g (list)h(is)g(pack)o(ed)e(as)i(an)f(unsigned)e(inte)o(ger)m(,)208 2263 y(then)g(each)h(element)g(is)h(pack)o(ed)e(as)i(in)f FJ(pack_farray\(\))e FN(abo)o(v)o(e.)0 2548 y Fv(9.5.2)100 b(Unpac)n(k)n(er)29 b(Objects)0 2751 y FN(The)20 b FJ(Unpacker)f FN(class)i(of)n(fers)f(the)g(follo)n(wing)e(methods:)0 2898 y FD(reset)p FJ(\()p FK(data)p FJ(\))208 2998 y FN(Resets)j(the)f(string)g(b)n(uf)n(fer)f(with)h(the)h(gi)n(v)o(en)d FK(data)p FN(.)0 3144 y FD(get_position)p FJ(\(\))208 3244 y FN(Returns)i(the)g(current)f(unpack)f(position)i(in)g(the)g (data)g(b)n(uf)n(fer)-5 b(.)0 3391 y FD(set_position)p FJ(\()p FK(position)p FJ(\))208 3491 y FN(Sets)26 b(the)g(data)f(b)n (uf)n(fer)g(unpack)f(position)g(to)i FK(position)p FN(.)41 b(Y)-9 b(ou)25 b(should)f(be)i(careful)f(about)f(using)i FJ(get_position\(\))d FN(and)208 3590 y FJ(set_position\(\))p FN(.)0 3737 y FD(get_buffer)p FJ(\(\))208 3837 y FN(Returns)d(the)g (current)f(unpack)f(data)i(b)n(uf)n(fer)f(as)i(a)g(string.)0 3984 y FD(done)p FJ(\(\))208 4083 y FN(Indicates)e(unpack)g (completion.)k(Raises)e(an)f FJ(Error)g FN(e)o(xception)e(if)j(all)g (of)f(the)g(data)g(has)g(not)g(been)g(unpack)o(ed.)0 4230 y(In)26 b(addition,)g(e)n(v)o(ery)e(data)i(type)g(that)g(can)g(be) g(pack)o(ed)f(with)h(a)g FJ(Packer)p FN(,)h(can)f(be)g(unpack)o(ed)e (with)i(an)g FJ(Unpacker)p FN(.)42 b(Unpacking)0 4330 y(methods)19 b(are)h(of)g(the)g(form)g FJ(unpack_)p FK(type)p FJ(\(\))p FN(,)e(and)h(tak)o(e)i(no)e(ar)o(guments.)k(The)o(y)c(return) g(the)i(unpack)o(ed)d(object.)0 4477 y FD(unpack_float)p FJ(\(\))208 4576 y FN(Unpacks)h(a)h(single-precision)f(\003oating)g (point)g(number)-5 b(.)0 4723 y FD(unpack_double)p FJ(\(\))208 4823 y FN(Unpacks)19 b(a)h(double-precision)d(\003oating)j(point)f (number)m(,)f(similarly)i(to)g FJ(unpack_float\(\))p FN(.)0 4970 y(In)g(addition,)f(the)h(follo)n(wing)e(methods)h(unpack)g (strings,)h(bytes,)g(and)f(opaque)g(data:)0 5116 y FD(unpack_fstring)p FJ(\()p FK(n)p FJ(\))208 5216 y FN(Unpacks)k(and)h(returns)f(a)i(\002x) o(ed)e(length)h(string.)36 b FK(n)25 b FN(is)g(the)f(number)f(of)g (characters)h(e)o(xpected.)35 b(P)o(adding)23 b(with)h(null)g(bytes)g (to)208 5316 y(guaranteed)18 b(4)i(byte)g(alignment)e(is)j(assumed.)p 0 5549 3901 4 v 0 5649 a FI(316)2862 b(Chapter)23 b(9.)52 b(File)24 b(F)n(or)r(mats)p eop end %%Page: 317 329 TeXDict begin 317 328 bop 0 83 a FD(unpack_fopaque)p FJ(\()p FK(n)p FJ(\))208 183 y FN(Unpacks)19 b(and)g(returns)h(a)g (\002x)o(ed)g(length)f(opaque)g(data)h(stream,)g(similarly)g(to)g FJ(unpack_fstring\(\))p FN(.)0 330 y FD(unpack_string)p FJ(\(\))208 429 y FN(Unpacks)i(and)h(returns)f(a)i(v)n(ariable)e (length)g(string.)34 b(The)23 b(length)f(of)h(the)g(string)g(is)h (\002rst)g(unpack)o(ed)e(as)h(an)h(unsigned)d(inte)o(ger)m(,)208 529 y(then)e(the)h(string)g(data)g(is)i(unpack)o(ed)c(with)i FJ(unpack_fstring\(\))p FN(.)0 676 y FD(unpack_opaque)p FJ(\(\))208 775 y FN(Unpacks)f(and)g(returns)h(a)g(v)n(ariable)f (length)h(opaque)e(data)i(string,)g(similarly)g(to)g FJ(unpack_string\(\))p FN(.)0 922 y FD(unpack_bytes)p FJ(\(\))208 1022 y FN(Unpacks)f(and)g(returns)h(a)g(v)n(ariable)f (length)h(byte)f(stream,)h(similarly)g(to)h FJ(unpack_string\(\))p FN(.)0 1169 y(The)f(follo)n(wing)e(methods)i(support)e(unpacking)g (arrays)i(and)f(lists:)0 1316 y FD(unpack_list)p FJ(\()p FK(unpac)n(k)p 845 1316 25 4 v 26 w(item)p FJ(\))208 1415 y FN(Unpacks)f(and)i(returns)f(a)h(list)h(of)f(homogeneous)c (items.)26 b(The)19 b(list)i(is)g(unpack)o(ed)d(one)h(element)g(at)i(a) f(time)g(by)g(\002rst)g(unpacking)208 1515 y(an)e(unsigned)e(inte)o (ger)h(\003ag.)24 b(If)18 b(the)h(\003ag)f(is)h FJ(1)p FN(,)f(then)g(the)g(item)h(is)g(unpack)o(ed)d(and)h(appended)f(to)i (the)g(list.)26 b(A)18 b(\003ag)h(of)e FJ(0)i FN(indicates)208 1614 y(the)h(end)f(of)h(the)h(list.)26 b FK(unpac)n(k)p 1076 1614 V 28 w(item)20 b FN(is)h(the)g(function)d(that)i(is)h(called) f(to)h(unpack)d(the)j(items.)0 1761 y FD(unpack_farray)p FJ(\()p FK(n,)c(unpac)n(k)p 1025 1761 V 28 w(item)p FJ(\))208 1861 y FN(Unpacks)g(and)g(returns)h(\(as)g(a)h(list\))g(a)g(\002x)o(ed) e(length)g(array)h(of)g(homogeneous)d(items.)24 b FK(n)19 b FN(is)g(number)d(of)i(list)h(elements)f(to)h(e)o(xpect)208 1961 y(in)h(the)g(b)n(uf)n(fer)-5 b(.)24 b(As)d(abo)o(v)o(e,)d FK(unpac)n(k)p 1251 1961 V 28 w(item)j FN(is)g(the)f(function)f(used)h (to)g(unpack)f(each)h(element.)0 2107 y FD(unpack_array)p FJ(\()p FK(unpac)n(k)p 895 2107 V 26 w(item)p FJ(\))208 2207 y FN(Unpacks)g(and)i(returns)f(a)h(v)n(ariable)e(length)h FK(list)k FN(of)c(homogeneous)e(items.)30 b(First,)23 b(the)f(length)f(of)g(the)h(list)h(is)f(unpack)o(ed)e(as)j(an)208 2307 y(unsigned)18 b(inte)o(ger)m(,)h(then)g(each)h(element)g(is)h (unpack)o(ed)d(as)j(in)f FJ(unpack_farray\(\))e FN(abo)o(v)o(e.)0 2592 y Fv(9.5.3)100 b(Exceptions)0 2794 y FN(Exceptions)19 b(in)h(this)h(module)e(are)h(coded)f(as)i(class)g(instances:)0 2941 y FL(exception)e FD(Error)208 3041 y FN(The)g(base)i(e)o(xception) d(class.)26 b FJ(Error)20 b FN(has)g(a)h(single)f(public)f(data)h (member)f FJ(msg)h FN(containing)e(the)j(description)d(of)i(the)h (error)-5 b(.)0 3188 y FL(exception)19 b FD(ConversionError)208 3287 y FN(Class)i(deri)n(v)o(ed)e(from)g FJ(Error)p FN(.)24 b(Contains)c(no)g(additional)f(instance)h(v)n(ariables.)0 3434 y(Here)g(is)h(an)f(e)o(xample)f(of)h(ho)n(w)g(you)f(w)o(ould)g (catch)h(one)g(of)g(these)g(e)o(xceptions:)236 3581 y FA(import)44 b(xdrlib)236 3672 y(p)h(=)g(xdrlib.Packer\(\))236 3764 y(try:)416 3855 y(p.pack_double\(8.01\))236 3946 y(except)f(xdrlib.ConversionError,)d(instance:)416 4038 y(print)j('packing)f(the)h(double)g(failed:',)f(instance.msg)p 0 5549 3901 4 v 0 5649 a FI(9.5.)52 b FJ(xdrlib)22 b FI(\227)h(Encode)h(and)f(decode)h(XDR)f(data)2023 b(317)p eop end %%Page: 318 330 TeXDict begin 318 329 bop 0 5549 3901 4 v 0 5649 a FI(318)p eop end %%Page: 319 331 TeXDict begin 319 330 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3661 427 y FG(TEN)p 0 515 V 1757 978 a FT(Cr)6 b(yptog)n(r)n(aphic)57 b(Ser)6 b(vices)0 1468 y FN(The)22 b(modules)e(described)h(in)h(this)g (chapter)f(implement)g(v)n(arious)g(algorithms)f(of)i(a)g (cryptographic)d(nature.)29 b(The)o(y)21 b(are)h(a)n(v)n(ailable)f(at)0 1568 y(the)f(discretion)f(of)h(the)h(installation.)j(Here')-5 b(s)20 b(an)h(o)o(v)o(ervie)n(w:)50 1694 y FD(hashlib)98 b FN(Secure)20 b(hash)g(and)f(message)h(digest)g(algorithms.)50 1794 y FD(hmac)248 b FN(K)n(e)o(yed-Hashing)18 b(for)h(Message)h (Authentication)f(\(HMA)m(C\))g(implementation)f(for)i(Python.)50 1893 y FD(md5)298 b FN(RSA)-9 b(')k(s)22 b(MD5)e(message)g(digest)g (algorithm.)50 1993 y FD(sha)298 b FN(NIST')-5 b(s)21 b(secure)f(hash)f(algorithm,)g(SHA.)0 2135 y(Hardcore)f(c)o(ypherpunks) f(will)j(probably)e(\002nd)h(the)h(cryptographic)c(modules)j(written)h (by)f(A.M.)h(K)o(uchling)e(of)h(further)g(interest;)h(the)0 2235 y(package)k(contains)i(modules)e(for)h(v)n(arious)g(encryption)f (algorithms,)h(most)h(notably)f(AES.)h(These)f(modules)g(are)h(not)f (distrib)n(uted)0 2334 y(with)d(Python)e(b)n(ut)i(a)n(v)n(ailable)f (separately)-5 b(.)27 b(See)22 b(the)g(URL)g FO(http://www)l(.amk.ca/p) n(ython/code)o(/cr)r(ypto)m(.h)o(tml)16 b FN(for)21 b(more)f (information.)0 2761 y FE(10.1)121 b Fx(hashlib)32 b FE(\227)g(Secure)i(hashes)h(and)g(message)f(digests)0 2994 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3141 y(This)j(module)e (implements)g(a)i(common)d(interf)o(ace)i(to)h(man)o(y)e(dif)n(ferent)g (secure)h(hash)g(and)g(message)g(digest)g(algorithms.)28 b(Included)0 3241 y(are)f(the)g(FIPS)g(secure)g(hash)f(algorithms)g (SHA1,)i(SHA224,)g(SHA256,)f(SHA384,)h(and)e(SHA512)g(\(de\002ned)f(in) j(FIPS)f(180-2\))e(as)0 3340 y(well)g(as)g(RSA)-9 b(')k(s)25 b(MD5)f(algorithm)f(\(de\002ned)g(in)h(Internet)f(RFC)j(1321\).)35 b(The)24 b(terms)g(secure)g(hash)g(and)g(message)g(digest)g(are)g (inter)n(-)0 3440 y(changeable.)f(Older)d(algorithms)f(were)h(called)g (message)g(digests.)25 b(The)20 b(modern)e(term)i(is)h(secure)f(hash.)0 3587 y FL(W)-5 b(ar)o(ning:)24 b FN(Some)c(algorithms)f(ha)n(v)o(e)g (kno)n(wn)g(hash)h(collision)g(weaknesses,)g(see)g(the)h(F)-6 b(A)h(Q)21 b(at)f(the)h(end.)0 3734 y(There)d(is)j(one)d(constructor)f (method)h(named)g(for)h(each)g(type)g(of)f FK(hash)p FN(.)24 b(All)c(return)e(a)i(hash)f(object)g(with)g(the)g(same)g (simple)h(interf)o(ace.)0 3833 y(F)o(or)e(e)o(xample:)24 b(use)19 b FJ(sha1\(\))f FN(to)h(create)f(a)h(SHA1)g(hash)g(object.)24 b(Y)-9 b(ou)18 b(can)g(no)n(w)h(feed)f(this)h(object)f(with)h (arbitrary)f(strings)g(using)h(the)0 3933 y FJ(update\(\))g FN(method.)24 b(At)c(an)o(y)g(point)f(you)h(can)f(ask)i(it)g(for)e(the) h FK(dig)o(est)h FN(of)e(the)i(concatenation)c(of)j(the)g(strings)h (fed)e(to)i(it)g(so)f(f)o(ar)g(using)0 4032 y(the)g FJ(digest\(\))f FN(or)h FJ(hexdigest\(\))f FN(methods.)0 4179 y(Constructors)43 b(for)g(hash)g(algorithms)g(that)h(are)g(al)o(w)o(ays)g(present)f(in)h (this)g(module)f(are)h FJ(md5\(\))p FN(,)49 b FJ(sha1\(\))p FN(,)g FJ(sha224\(\))p FN(,)0 4279 y FJ(sha256\(\))p FN(,)16 b FJ(sha384\(\))p FN(,)f(and)h FJ(sha512\(\))p FN(.)22 b(Additional)15 b(algorithms)g(may)g(also)i(be)f(a)n(v)n (ailable)f(depending)f(upon)g(the)i(OpenSSL)0 4379 y(library)j(that)h (Python)f(uses)i(on)f(your)f(platform.)0 4525 y(F)o(or)h(e)o(xample,)e (to)j(obtain)e(the)h(digest)g(of)g(the)g(string)g FJ('Nobody)49 b(inspects)f(the)h(spammish)g(repetition')p FN(:)236 4764 y FA(>>>)c(import)e(hashlib)236 4855 y(>>>)i(m)f(=)h (hashlib.md5\(\))236 4946 y(>>>)g(m.update\("Nobody)d(inspects"\))236 5038 y(>>>)j(m.update\(")e(the)h(spammish)g(repetition"\))236 5129 y(>>>)h(m.digest\(\))236 5220 y ('\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\x)o(c9\\xa1)o (\\x8d\\x)o(f0\\xff)o(\\xe9')p 0 5549 3901 4 v 3762 5649 a FI(319)p eop end %%Page: 320 332 TeXDict begin 320 331 bop 0 83 a FN(More)20 b(condensed:)236 321 y FA(>>>)45 b(hashlib.sha224\("Nobody)c(inspects)i(the)h(spammish)g (repetition"\).hexdigest\(\))236 413 y ('a4337bc45a8fc544c03f52dc550cd6e1e87021b)o(c89658)o(8bd79e)o(901e2')0 699 y FN(A)25 b(generic)f FJ(new\(\))g FN(constructor)f(that)i(tak)o (es)g(the)g(string)f(name)g(of)g(the)h(desired)f(algorithm)f(as)j(its)g (\002rst)f(parameter)e(also)i(e)o(xists)g(to)0 799 y(allo)n(w)i(access) h(to)g(the)f(abo)o(v)o(e)f(listed)h(hashes)g(as)h(well)g(as)g(an)o(y)f (other)f(algorithms)g(that)i(your)e(OpenSSL)g(library)h(may)f(of)n(fer) -5 b(.)46 b(The)0 898 y(named)19 b(constructors)g(are)h(much)f(f)o (aster)h(than)g FJ(new\(\))g FN(and)f(should)h(be)g(preferred.)0 1045 y(Using)g FJ(new\(\))g FN(with)g(an)g(algorithm)f(pro)o(vided)f (by)h(OpenSSL:)236 1283 y FA(>>>)45 b(h)f(=)h (hashlib.new\('ripemd160'\))236 1375 y(>>>)g(h.update\("Nobody)d (inspects)h(the)i(spammish)e(repetition"\))236 1466 y(>>>)i (h.hexdigest\(\))236 1557 y('cc4a5ce1b3df48aec5d22d1f16b894a0b894ecc)o (c')0 1844 y FN(The)20 b(follo)n(wing)e(v)n(alues)i(are)g(pro)o(vided)e (as)j(constant)e(attrib)n(utes)h(of)g(the)h(hash)f(objects)f(returned)g (by)h(the)g(constructors:)0 1991 y FD(digest_size)208 2090 y FN(The)f(size)i(of)f(the)g(resulting)g(hash)g(in)g(bytes.)0 2237 y FD(block_size)208 2337 y FN(The)f(internal)h(block)f(size)i(of)f (the)g(hash)g(algorithm)f(in)h(bytes.)0 2484 y(A)h(hash)f(object)f(has) i(the)f(follo)n(wing)e(methods:)0 2631 y FD(update)p FJ(\()p FK(ar)m(g)p FJ(\))208 2730 y FN(Update)i(the)h(hash)f(object)g (with)h(the)g(string)g FK(ar)m(g)p FN(.)26 b(Repeated)21 b(calls)g(are)g(equi)n(v)n(alent)e(to)i(a)g(single)g(call)g(with)g(the) g(concatenation)208 2830 y(of)e(all)i(the)f(ar)o(guments:)k FJ(m.update\(a\);)47 b(m.update\(b\))19 b FN(is)i(equi)n(v)n(alent)e (to)h FJ(m.update\(a+b\))p FN(.)0 2977 y FD(digest)p FJ(\(\))208 3076 y FN(Return)26 b(the)h(digest)g(of)f(the)h(strings)g (passed)g(to)g(the)g FJ(update\(\))f FN(method)f(so)i(f)o(ar)-5 b(.)46 b(This)27 b(is)h(a)f(string)f(of)h FJ(digest_size)208 3176 y FN(bytes)20 b(which)f(may)h(contain)f(non-)r FH(A)t(S)t(C)t(I)t (I)j FN(characters,)d(including)f(null)i(bytes.)0 3323 y FD(hexdigest)p FJ(\(\))208 3422 y FN(Lik)o(e)h FJ(digest\(\))g FN(e)o(xcept)f(the)i(digest)f(is)i(returned)d(as)i(a)g(string)f(of)h (double)e(length,)h(containing)e(only)i(he)o(xadecimal)f(digits.)208 3522 y(This)g(may)g(be)g(used)g(to)g(e)o(xchange)e(the)i(v)n(alue)g (safely)g(in)g(email)g(or)g(other)g(non-binary)d(en)m(vironments.)0 3669 y FD(copy)p FJ(\(\))208 3769 y FN(Return)24 b(a)g(cop)o(y)g (\(\223clone\224\))f(of)h(the)g(hash)g(object.)38 b(This)24 b(can)g(be)h(used)f(to)g(ef)n(\002ciently)g(compute)f(the)h(digests)h (of)f(strings)g(that)208 3868 y(share)19 b(a)i(common)d(initial)j (substring.)0 4015 y FL(See)g(Also:)0 4162 y FN(Module)e FJ(hmac)h FN(\(section)g(10.2\):)208 4262 y(A)g(module)f(to)h(generate) f(message)h(authentication)f(codes)g(using)h(hashes.)0 4408 y(Module)f FJ(base64)h FN(\(section)f(7.11\):)208 4508 y(Another)f(w)o(ay)j(to)f(encode)f(binary)g(hashes)h(for)f (non-binary)e(en)m(vironments.)0 4655 y FO(http://csrc.nist.go)o(v/pub) o(licati)o(on)o(s/\002ps/\002ps180-)o(2/\002ps18)o(0-2)o(.p)o(df)208 4755 y FN(The)i(FIPS)i(180-2)e(publication)f(on)i(Secure)g(Hash)g (Algorithms.)0 4901 y FO(http://www)l(.cr)r(yptog)o(r)o(aph)n(y)-7 b(.com/cne)o(ws/h)o(ash.)o(html)208 5001 y FN(Hash)24 b(Collision)g(F)-6 b(A)h(Q)25 b(with)f(information)e(on)i(which)g (algorithms)e(ha)n(v)o(e)i(kno)n(wn)f(issues)i(and)e(what)h(that)h (means)f(re)o(garding)208 5101 y(their)19 b(use.)p 0 5549 3901 4 v 0 5649 a FI(320)2415 b(Chapter)24 b(10.)52 b(Cr)r(yptog)o(r)o(aphic)23 b(Ser)r(vices)p eop end %%Page: 321 333 TeXDict begin 321 332 bop 0 87 a FE(10.2)121 b Fx(hmac)32 b FE(\227)h(K)-5 b(e)n(y)n(ed-Hashing)35 b(f)l(or)f(Message)g(A)l (uthentication)0 320 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 467 y(This)h(module)f(implements)g(the)i(HMA)m(C)f(algorithm)f(as)i (described)e(by)g(RFC)j(2104.)0 614 y FD(new)p FJ(\()p FK(k)o(e)n(y)p FC([)p FK(,)d(msg)p FC([)p FK(,)h(dig)o(estmod)12 b FC(])g(])p FJ(\))208 713 y FN(Return)21 b(a)i(ne)n(w)f(hmac)g (object.)30 b(If)22 b FK(msg)h FN(is)g(present,)f(the)g(method)f(call)h FJ(update\()p FK(msg)p FJ(\))f FN(is)i(made.)31 b FK(dig)o(estmod)23 b FN(is)g(the)g(digest)208 813 y(constructor)e(or)j(module)e(for)h(the) g(HMA)m(C)h(object)f(to)h(use.)36 b(It)23 b(def)o(aults)h(to)f(the)h FJ(hashlib.md5)e FN(constructor)-5 b(.)34 b FL(Note:)d FN(The)208 913 y(md5)21 b(hash)h(has)g(kno)n(wn)f(weaknesses)h(b)n(ut)g (remains)f(the)h(def)o(ault)g(for)f(backw)o(ards)g(compatibility)-5 b(.)29 b(Choose)21 b(a)i(better)f(one)f(for)208 1012 y(your)d(application.)0 1159 y(An)i(HMA)m(C)h(object)e(has)i(the)f (follo)n(wing)f(methods:)0 1306 y FD(update)p FJ(\()p FK(msg)p FJ(\))208 1406 y FN(Update)e(the)h(hmac)f(object)h(with)g(the) g(string)g FK(msg)p FN(.)25 b(Repeated)17 b(calls)i(are)f(equi)n(v)n (alent)e(to)j(a)f(single)g(call)h(with)f(the)g(concatenation)208 1505 y(of)h(all)i(the)f(ar)o(guments:)k FJ(m.update\(a\);)47 b(m.update\(b\))19 b FN(is)i(equi)n(v)n(alent)e(to)h FJ(m.update\(a)48 b(+)h(b\))p FN(.)0 1652 y FD(digest)p FJ(\(\))208 1752 y FN(Return)21 b(the)i(digest)f(of)g(the)g(strings)g (passed)g(to)h(the)f FJ(update\(\))f FN(method)g(so)i(f)o(ar)-5 b(.)31 b(This)23 b(string)f(will)h(be)f(the)g(same)g(length)g(as)208 1851 y(the)c FK(dig)o(est)p 531 1851 25 4 v 29 w(size)i FN(of)e(the)h(digest)f(gi)n(v)o(en)f(to)i(the)g(constructor)-5 b(.)22 b(It)d(may)f(contain)g(non-)r FH(A)t(S)t(C)t(I)t(I)i FN(characters,)e(including)e(NUL)j(bytes.)0 1998 y FD(hexdigest)p FJ(\(\))208 2098 y FN(Lik)o(e)k FJ(digest\(\))g FN(e)o(xcept)g(the)h (digest)f(is)i(returned)d(as)j(a)f(string)f(twice)h(the)g(length)f (containing)f(only)h(he)o(xadecimal)f(digits.)208 2198 y(This)e(may)g(be)g(used)g(to)g(e)o(xchange)e(the)i(v)n(alue)g(safely)g (in)g(email)g(or)g(other)g(non-binary)d(en)m(vironments.)0 2344 y FD(copy)p FJ(\(\))208 2444 y FN(Return)22 b(a)i(cop)o(y)e (\(\223clone\224\))f(of)i(the)g(hmac)g(object.)33 b(This)23 b(can)g(be)g(used)g(to)g(ef)n(\002ciently)g(compute)e(the)i(digests)h (of)e(strings)h(that)208 2544 y(share)c(a)i(common)d(initial)j (substring.)0 2691 y FL(See)g(Also:)0 2837 y FN(Module)e FJ(hashlib)g FN(\(section)h(10.1\):)208 2937 y(The)f(p)o(ython)g (module)g(pro)o(viding)e(secure)j(hash)g(functions.)0 3265 y FE(10.3)121 b Fx(md5)33 b FE(\227)f(MD5)i(message)g(digest)g (algor)r(ithm)0 3497 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)f(2.5.) k FN(Use)d(the)f FJ(hashlib)f FN(module)g(instead.)0 3644 y(This)29 b(module)f(implements)g(the)h(interf)o(ace)f(to)h(RSA)-9 b(')k(s)30 b(MD5)f(message)g(digest)f(algorithm)g(\(see)h(also)g (Internet)f(RFC)i(1321\).)50 b(Its)0 3744 y(use)23 b(is)g(quite)g (straightforw)o(ard:)d(use)j FJ(new\(\))f FN(to)h(create)f(an)h(md5)f (object.)32 b(Y)-9 b(ou)22 b(can)g(no)n(w)g(feed)g(this)i(object)e (with)h(arbitrary)e(strings)0 3843 y(using)e(the)h FJ(update\(\))f FN(method,)g(and)g(at)h(an)o(y)f(point)h(you)f(can)g(ask)h(it)h(for)e (the)h FK(dig)o(est)g FN(\(a)g(strong)f(kind)g(of)h(128-bit)e (checksum,)g(a.k.a.)0 3943 y(\223\002ngerprint\224\))g(of)i(the)g (concatenation)e(of)i(the)g(strings)g(fed)g(to)g(it)h(so)f(f)o(ar)h (using)e(the)h FJ(digest\(\))g FN(method.)0 4090 y(F)o(or)g(e)o (xample,)e(to)j(obtain)e(the)h(digest)g(of)g(the)g(string)g FJ('Nobody)49 b(inspects)f(the)h(spammish)g(repetition')p FN(:)236 4328 y FA(>>>)c(import)e(md5)236 4419 y(>>>)i(m)f(=)h (md5.new\(\))236 4511 y(>>>)g(m.update\("Nobody)d(inspects"\))236 4602 y(>>>)j(m.update\(")e(the)h(spammish)g(repetition"\))236 4693 y(>>>)h(m.digest\(\))236 4785 y ('\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\x)o(c9\\xa1)o (\\x8d\\x)o(f0\\xff)o(\\xe9')0 5071 y FN(More)20 b(condensed:)p 0 5549 3901 4 v 0 5649 a FI(10.2.)52 b FJ(hmac)23 b FI(\227)g(K)m(e)n (y)n(ed-Hashing)h(f)n(or)e(Message)h(A)n(uthentication)1614 b(321)p eop end %%Page: 322 334 TeXDict begin 322 333 bop 236 174 a FA(>>>)45 b(md5.new\("Nobody)d (inspects)h(the)i(spammish)e(repetition"\).digest\(\))236 266 y('\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\x)o(c9\\xa1)o (\\x8d\\x)o(f0\\xff)o(\\xe9')0 552 y FN(The)19 b(follo)n(wing)e(v)n (alues)h(are)h(pro)o(vided)e(as)i(constants)g(in)g(the)g(module)e(and)i (as)g(attrib)n(utes)g(of)g(the)g(md5)f(objects)g(returned)f(by)i FJ(new\(\))p FN(:)0 699 y FD(digest_size)208 799 y FN(The)g(size)i(of)f (the)g(resulting)g(digest)g(in)g(bytes.)25 b(This)20 b(is)h(al)o(w)o(ays)g FJ(16)p FN(.)0 946 y(The)f(md5)f(module)g(pro)o (vides)f(the)j(follo)n(wing)d(functions:)0 1092 y FD(new)p FJ(\()p FC([)p FK(ar)m(g)12 b FC(])p FJ(\))208 1192 y FN(Return)19 b(a)i(ne)n(w)f(md5)f(object.)25 b(If)20 b FK(ar)m(g)g FN(is)h(present,)e(the)h(method)f(call)i FJ(update\()p FK(ar)m(g)p FJ(\))d FN(is)j(made.)0 1339 y FD(md5)p FJ(\()p FC([)p FK(ar)m(g)12 b FC(])p FJ(\))208 1439 y FN(F)o(or)19 b(backw)o(ard)g(compatibility)g(reasons,)g(this)i (is)g(an)f(alternati)n(v)o(e)f(name)h(for)f(the)h FJ(new\(\))g FN(function.)0 1585 y(An)g(md5)g(object)f(has)i(the)f(follo)n(wing)e (methods:)0 1732 y FD(update)p FJ(\()p FK(ar)m(g)p FJ(\))208 1832 y FN(Update)i(the)h(md5)f(object)h(with)g(the)g(string)g FK(ar)m(g)p FN(.)27 b(Repeated)20 b(calls)i(are)f(equi)n(v)n(alent)f (to)h(a)g(single)g(call)h(with)f(the)g(concatenation)208 1932 y(of)e(all)i(the)f(ar)o(guments:)k FJ(m.update\(a\);)47 b(m.update\(b\))19 b FN(is)i(equi)n(v)n(alent)e(to)h FJ(m.update\(a+b\))p FN(.)0 2078 y FD(digest)p FJ(\(\))208 2178 y FN(Return)26 b(the)g(digest)g(of)g(the)h(strings)f(passed)h(to)f (the)g FJ(update\(\))g FN(method)f(so)i(f)o(ar)-5 b(.)44 b(This)26 b(is)i(a)e(16-byte)f(string)h(which)g(may)208 2278 y(contain)19 b(non-)r FH(A)t(S)t(C)t(I)t(I)j FN(characters,)d (including)f(null)i(bytes.)0 2425 y FD(hexdigest)p FJ(\(\))208 2524 y FN(Lik)o(e)f FJ(digest\(\))g FN(e)o(xcept)g(the)g(digest)h(is)h (returned)d(as)i(a)g(string)g(of)f(length)g(32,)g(containing)f(only)h (he)o(xadecimal)e(digits.)25 b(This)208 2624 y(may)19 b(be)h(used)g(to)h(e)o(xchange)d(the)i(v)n(alue)f(safely)h(in)h(email)f (or)g(other)f(non-binary)e(en)m(vironments.)0 2771 y FD(copy)p FJ(\(\))208 2870 y FN(Return)24 b(a)h(cop)o(y)f (\(\223clone\224\))f(of)h(the)h(md5)e(object.)38 b(This)25 b(can)f(be)h(used)f(to)h(ef)n(\002ciently)f(compute)f(the)i(digests)f (of)h(strings)f(that)208 2970 y(share)19 b(a)i(common)d(initial)j (substring.)0 3117 y FL(See)g(Also:)0 3264 y FN(Module)e FJ(sha)h FN(\(section)g(10.4\):)208 3363 y(Similar)28 b(module)g(implementing)e(the)j(Secure)g(Hash)g(Algorithm)e(\(SHA\).)h (The)h(SHA)g(algorithm)e(is)j(considered)d(a)i(more)208 3463 y(secure)19 b(hash.)0 3790 y FE(10.4)121 b Fx(sha)33 b FE(\227)f(SHA-1)i(message)g(digest)g(algor)r(ithm)0 4023 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)f(2.5.)k FN(Use)d(the)f FJ(hashlib)f FN(module)g(instead.)0 4170 y(This)28 b(module)f(implements)g(the)h(interf)o(ace)f(to)h(NIST')-5 b(s)28 b(secure)g(hash)g(algorithm,)g(kno)n(wn)e(as)j(SHA-1.)48 b(SHA-1)27 b(is)i(an)f(impro)o(v)o(ed)0 4270 y(v)o(ersion)22 b(of)h(the)h(original)e(SHA)i(hash)g(algorithm.)33 b(It)24 b(is)g(used)f(in)h(the)f(same)h(w)o(ay)g(as)g(the)f FJ(md5)h FN(module:)e(use)i FJ(new\(\))f FN(to)g(create)h(an)0 4369 y(sha)g(object,)g(then)f(feed)g(this)h(object)f(with)h(arbitrary)e (strings)i(using)f(the)h FJ(update\(\))f FN(method,)g(and)g(at)h(an)o (y)f(point)g(you)f(can)i(ask)g(it)0 4469 y(for)19 b(the)h FK(dig)o(est)f FN(of)h(the)f(concatenation)f(of)h(the)h(strings)g(fed)f (to)h(it)g(so)g(f)o(ar)-5 b(.)25 b(SHA-1)19 b(digests)h(are)g(160)f (bits)h(instead)f(of)h(MD5')-5 b(s)20 b(128)e(bits.)0 4616 y FD(new)p FJ(\()p FC([)p FK(string)12 b FC(])p FJ(\))208 4715 y FN(Return)19 b(a)i(ne)n(w)f(sha)g(object.)25 b(If)20 b FK(string)g FN(is)h(present,)f(the)g(method)f(call)h FJ(update\()p FK(string)p FJ(\))f FN(is)j(made.)0 4862 y(The)e(follo)n(wing)e(v)n(alues)i(are)g(pro)o(vided)e(as)j(constants)f (in)g(the)g(module)f(and)h(as)h(attrib)n(utes)f(of)g(the)g(sha)g (objects)g(returned)f(by)g FJ(new\(\))p FN(:)0 5009 y FD(blocksize)208 5109 y FN(Size)h(of)f(the)h(blocks)f(fed)g(into)h(the) f(hash)h(function;)e(this)i(is)h(al)o(w)o(ays)f FJ(1)p FN(.)25 b(This)20 b(size)g(is)h(used)e(to)h(allo)n(w)g(an)f(arbitrary)f (string)i(to)g(be)208 5208 y(hashed.)0 5355 y FD(digest_size)p 0 5549 3901 4 v 0 5649 a FI(322)2415 b(Chapter)24 b(10.)52 b(Cr)r(yptog)o(r)o(aphic)23 b(Ser)r(vices)p eop end %%Page: 323 335 TeXDict begin 323 334 bop 208 83 a FN(The)19 b(size)i(of)f(the)g (resulting)g(digest)g(in)g(bytes.)25 b(This)20 b(is)h(al)o(w)o(ays)g FJ(20)p FN(.)0 230 y(An)f(sha)h(object)e(has)i(the)f(same)g(methods)f (as)i(md5)f(objects:)0 377 y FD(update)p FJ(\()p FK(ar)m(g)p FJ(\))208 476 y FN(Update)i(the)h(sha)g(object)f(with)h(the)g(string)g FK(ar)m(g)p FN(.)32 b(Repeated)23 b(calls)g(are)g(equi)n(v)n(alent)e (to)j(a)f(single)g(call)g(with)g(the)g(concatenation)208 576 y(of)c(all)i(the)f(ar)o(guments:)k FJ(m.update\(a\);)47 b(m.update\(b\))19 b FN(is)i(equi)n(v)n(alent)e(to)h FJ(m.update\(a+b\))p FN(.)0 723 y FD(digest)p FJ(\(\))208 823 y FN(Return)26 b(the)g(digest)g(of)g(the)h(strings)f(passed)h(to)f (the)g FJ(update\(\))g FN(method)f(so)i(f)o(ar)-5 b(.)44 b(This)26 b(is)i(a)e(20-byte)f(string)h(which)g(may)208 922 y(contain)19 b(non-)r FH(A)t(S)t(C)t(I)t(I)j FN(characters,)d (including)f(null)i(bytes.)0 1069 y FD(hexdigest)p FJ(\(\))208 1169 y FN(Lik)o(e)f FJ(digest\(\))g FN(e)o(xcept)g(the)g(digest)h(is)h (returned)d(as)i(a)g(string)g(of)f(length)g(40,)g(containing)f(only)h (he)o(xadecimal)e(digits.)25 b(This)208 1268 y(may)19 b(be)h(used)g(to)h(e)o(xchange)d(the)i(v)n(alue)f(safely)h(in)h(email)f (or)g(other)f(non-binary)e(en)m(vironments.)0 1415 y FD(copy)p FJ(\(\))208 1515 y FN(Return)25 b(a)i(cop)o(y)f (\(\223clone\224\))f(of)h(the)g(sha)h(object.)43 b(This)26 b(can)h(be)f(used)g(to)h(ef)n(\002ciently)e(compute)g(the)h(digests)h (of)f(strings)g(that)208 1614 y(share)19 b(a)i(common)d(initial)j (substring.)0 1761 y FL(See)g(Also:)0 1908 y FK(Secur)m(e)f(Hash)g (Standar)m(d)0 2008 y Fy(\()p FO(http://csrc.nist.go)o(v/pub)o(licati)o (on)o(s/\002ps/\002ps180)o(-2/\002ps1)o(80-)o(2wi)o(thcha)o(ng)o(en)o (oti)o(ce)o(.p)o(df)-6 b Fy(\))208 2107 y FN(The)21 b(Secure)g(Hash)h (Algorithm)e(is)i(de\002ned)f(by)g(NIST)g(document)f(FIPS)i(PUB)h (180-2:)j FK(Secur)m(e)21 b(Hash)h(Standar)m(d)p FN(,)d(published)208 2207 y(in)h(August)g(2002.)0 2354 y FK(Crypto)o(gr)o(aphic)f(T)-8 b(oolkit)20 b(\(Secur)m(e)f(Hashing\))0 2454 y Fy(\()p FO(http://csrc.nist.go)o(v/encr)r(yption/tkhash.)o(html)-7 b Fy(\))208 2553 y FN(Links)19 b(from)h(NIST)g(to)g(v)n(arious)f (information)f(on)i(secure)g(hashing.)p 0 5549 3901 4 v 0 5649 a FI(10.4.)52 b FJ(sha)23 b FI(\227)g(SHA-1)g(message)g (digest)h(algor)q(ithm)2034 b(323)p eop end %%Page: 324 336 TeXDict begin 324 335 bop 0 5549 3901 4 v 0 5649 a FI(324)p eop end %%Page: 325 337 TeXDict begin 325 336 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3422 427 y FG(ELEVEN)p 0 515 V 1552 978 a FT(File)57 b(and)g(Director)6 b(y)58 b(Access)0 1466 y FN(The)20 b(modules)f(described)g(in)h(this)h (chapter)e(deal)h(with)h(disk)f(\002les)h(and)f(directories.)k(F)o(or)c (e)o(xample,)e(there)i(are)g(modules)f(for)h(reading)0 1566 y(the)j(properties)e(of)h(\002les,)i(manipulating)c(paths)i(in)h (a)g(portable)e(w)o(ay)-5 b(,)23 b(and)f(creating)f(temporary)g (\002les.)32 b(The)23 b(full)f(list)i(of)e(modules)f(in)0 1665 y(this)g(chapter)e(is:)50 1809 y FD(os.path)198 b FN(Common)19 b(pathname)f(manipulations.)50 1908 y FD(fileinput)98 b FN(Perl-lik)o(e)20 b(iteration)f(o)o(v)o(er)g(lines)h (from)g(multiple)f(input)h(streams,)g(with)g(\223sa)n(v)o(e)g(in)h (place\224)e(capability)-5 b(.)50 2008 y FD(stat)348 b FN(Utilities)21 b(for)f(interpreting)e(the)i(results)h(of)e FJ(os.stat\(\))p FN(,)g FJ(os.lstat\(\))g FN(and)h FJ(os.fstat\(\))p FN(.)50 2108 y FD(statvfs)198 b FN(Constants)20 b(for)g(interpreting)e (the)i(result)g(of)g FJ(os.statvfs\(\))p FN(.)50 2207 y FD(filecmp)198 b FN(Compare)19 b(\002les)i(ef)n(\002ciently)-5 b(.)50 2307 y FD(tempfile)148 b FN(Generate)19 b(temporary)f(\002les)j (and)f(directories.)50 2406 y FD(glob)350 b FN(U)t FH(N)t(I)t(X)23 b FN(shell)e(style)f(pathname)f(pattern)g(e)o(xpansion.)50 2506 y FD(fnmatch)200 b FN(U)t FH(N)t(I)t(X)23 b FN(shell)e(style)f (\002lename)g(pattern)f(matching.)50 2606 y FD(linecache)98 b FN(This)20 b(module)f(pro)o(vides)f(random)h(access)i(to)f(indi)n (vidual)e(lines)j(from)e(te)o(xt)h(\002les.)50 2705 y FD(shutil)248 b FN(High-le)n(v)o(el)18 b(\002le)j(operations,)e (including)f(cop)o(ying.)50 2805 y FD(dircache)148 b FN(Return)19 b(directory)g(listing,)h(with)g(cache)g(mechanism.)0 2947 y(Also)h(see)f(section)g(3.9)g(for)f(a)i(description)e(of)h (Python')-5 b(s)19 b(b)n(uilt-in)h(\002le)g(objects.)0 3094 y FL(See)h(Also:)0 3241 y FN(Module)e FJ(os)h FN(\(section)g (14.1\):)208 3340 y(Operating)e(system)j(interf)o(aces,)e(including)f (functions)h(to)i(w)o(ork)e(with)h(\002les)i(at)e(a)h(lo)n(wer)f(le)n (v)o(el)g(than)f(the)h(b)n(uilt-in)g(\002le)h(object.)0 3668 y FE(11.1)121 b Fx(os.path)32 b FE(\227)g(Common)i(pathname)i (manipulations)0 3901 y FN(This)20 b(module)f(implements)g(some)h (useful)g(functions)f(on)h(pathnames.)0 4047 y FL(W)-5 b(ar)o(ning:)48 b FN(On)32 b(W)m(indo)n(ws,)i(man)o(y)d(of)h(these)g (functions)e(do)i(not)g(properly)e(support)g(UNC)j(pathnames.)59 b FJ(splitunc\(\))31 b FN(and)0 4147 y FJ(ismount\(\))19 b FN(do)h(handle)f(them)h(correctly)-5 b(.)0 4294 y FD(abspath)p FJ(\()p FK(path)p FJ(\))208 4394 y FN(Return)35 b(a)i(normalized)d (absolutized)g(v)o(ersion)h(of)h(the)g(pathname)e FK(path)p FN(.)72 b(On)36 b(most)g(platforms,)j(this)d(is)h(equi)n(v)n(alent)d (to)208 4493 y FJ(normpath\(join\(os.getcwd\(\),)45 b FK(path)p FJ(\)\))p FN(.)k(Ne)n(w)20 b(in)h(v)o(ersion)e(1.5.2.)0 4640 y FD(basename)p FJ(\()p FK(path)p FJ(\))208 4740 y FN(Return)d(the)h(base)h(name)e(of)h(pathname)f FK(path)p FN(.)23 b(This)17 b(is)h(the)f(second)g(half)g(of)f(the)i(pair)e (returned)g(by)h FJ(split\()p FK(path)p FJ(\))p FN(.)k(Note)c(that)208 4839 y(the)h(result)h(of)g(this)g(function)e(is)j(dif)n(ferent)d(from)h (the)j(U)t FH(N)t(I)t(X)h FL(basename)d FN(program;)e(where)h FL(basename)h FN(for)f FJ('/foo/bar/')208 4939 y FN(returns)h FJ('bar')p FN(,)g(the)i FJ(basename\(\))e FN(function)f(returns)h(an)h (empty)g(string)g(\()p FJ('')p FN(\).)0 5086 y FD(commonprefix)p FJ(\()p FK(list)q FJ(\))208 5185 y FN(Return)i(the)g(longest)g(path)g (pre\002x)f(\(tak)o(en)h(character)n(-by-character\))c(that)k(is)i(a)f (pre\002x)e(of)h(all)h(paths)g(in)f FK(list)q FN(.)33 b(If)23 b FK(list)i FN(is)e(empty)-5 b(,)208 5285 y(return)19 b(the)h(empty)f(string)h(\()p FJ('')p FN(\).)k(Note)d(that)f(this)h (may)e(return)g(in)m(v)n(alid)g(paths)h(because)g(it)h(w)o(orks)f(a)g (character)f(at)i(a)f(time.)p 0 5549 3901 4 v 3762 5649 a FI(325)p eop end %%Page: 326 338 TeXDict begin 326 337 bop 0 83 a FD(dirname)p FJ(\()p FK(path)p FJ(\))208 183 y FN(Return)19 b(the)i(directory)d(name)i(of)f (pathname)g FK(path)p FN(.)24 b(This)c(is)i(the)e(\002rst)h(half)f(of)g (the)g(pair)g(returned)e(by)i FJ(split\()p FK(path)p FJ(\))p FN(.)0 330 y FD(exists)p FJ(\()p FK(path)p FJ(\))208 429 y FN(Return)g FJ(True)g FN(if)i FK(path)e FN(refers)g(to)h(an)g(e)o (xisting)f(path.)26 b(Returns)20 b FJ(False)h FN(for)f(brok)o(en)f (symbolic)h(links.)27 b(On)20 b(some)h(platforms,)208 529 y(this)e(function)e(may)i(return)f FJ(False)g FN(if)i(permission)e (is)i(not)e(granted)g(to)h(e)o(x)o(ecute)f FJ(os.stat\(\))g FN(on)g(the)h(requested)f(\002le,)i(e)n(v)o(en)208 628 y(if)g(the)g FK(path)g FN(physically)e(e)o(xists.)0 775 y FD(lexists)p FJ(\()p FK(path)p FJ(\))208 875 y FN(Return)33 b FJ(True)h FN(if)h FK(path)e FN(refers)h(to)g(an)g(e)o(xisting)f (path.)66 b(Returns)34 b FJ(True)g FN(for)g(brok)o(en)e(symbolic)h (links.)67 b(Equi)n(v)n(alent)32 b(to)208 975 y FJ(exists\(\))19 b FN(on)h(platforms)f(lacking)g FJ(os.lstat\(\))p FN(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 1121 y FD(expanduser)p FJ(\()p FK(path)p FJ(\))208 1221 y FN(On)e(U)t FH(N)t(I)t(X)r FN(,)h(return)c(the)i(ar)o(gument)d(with)j(an)g(initial)g(component)d (of)i(`)p FJ(\230)p FN(')h(or)f(`)p FJ(\230)p FK(user)r FN(')g(replaced)g(by)g(that)h FK(user)r FN(')-5 b(s)16 b(home)f(directory)-5 b(.)208 1321 y(An)29 b(initial)g(`)p FJ(\230)p FN(')g(is)h(replaced)e(by)h(the)g(en)m(vironment)d(v)n (ariable)i(HOME)h(if)h(it)g(is)g(set;)35 b(otherwise)28 b(the)h(current)f(user')-5 b(s)30 b(home)208 1420 y(directory)20 b(is)k(look)o(ed)d(up)h(in)h(the)g(passw)o(ord)f(directory)e(through)h (the)h(b)n(uilt-in)g(module)g FJ(pwd)p FN(.)32 b(An)22 b(initial)h(`)p FJ(\230)p FK(user)r FN(')f(is)i(look)o(ed)208 1520 y(up)19 b(directly)h(in)g(the)g(passw)o(ord)g(directory)-5 b(.)208 1653 y(On)23 b(W)m(indo)n(ws,)g(only)g(`)p FJ(\230)p FN(')g(is)h(supported;)f(it)h(is)g(replaced)e(by)h(the)g(en)m (vironment)e(v)n(ariable)h(HOME)h(or)g(by)g(a)h(combination)d(of)208 1752 y(HOMEDRIVE)e(and)h(HOMEP)-8 b(A)f(TH.)208 1885 y(If)20 b(the)g(e)o(xpansion)e(f)o(ails)j(or)f(if)g(the)g(path)g(does)g (not)g(be)o(gin)f(with)h(a)h(tilde,)f(the)g(path)g(is)h(returned)d (unchanged.)0 2032 y FD(expandvars)p FJ(\()p FK(path)p FJ(\))208 2132 y FN(Return)k(the)g(ar)o(gument)e(with)j(en)m(vironment) c(v)n(ariables)j(e)o(xpanded.)29 b(Substrings)21 b(of)h(the)h(form)e(`) p FJ($)p FK(name)p FN(')g(or)h(`)p FJ(${)p FK(name)p FJ(})p FN(')f(are)208 2231 y(replaced)e(by)i(the)g(v)n(alue)f(of)h(en)m (vironment)c(v)n(ariable)j FK(name)p FN(.)27 b(Malformed)19 b(v)n(ariable)h(names)g(and)h(references)e(to)i(non-e)o(xisting)208 2331 y(v)n(ariables)e(are)h(left)g(unchanged.)0 2478 y FD(getatime)p FJ(\()p FK(path)p FJ(\))208 2577 y FN(Return)26 b(the)h(time)f(of)h(last)g(access)h(of)e FK(path)p FN(.)44 b(The)26 b(return)g(v)n(alue)g(is)h(a)g(number)e(gi)n(ving)h(the)g (number)f(of)i(seconds)f(since)h(the)208 2677 y(epoch)22 b(\(see)i(the)g FJ(time)f FN(module\).)34 b(Raise)25 b FJ(os.error)e FN(if)h(the)g(\002le)g(does)g(not)f(e)o(xist)h(or)f(is) i(inaccessible.)72 b(Ne)n(w)24 b(in)g(v)o(ersion)208 2777 y(1.5.2.)123 b(Changed)24 b(in)i(v)o(ersion)e(2.3:)h(If)h FJ(os.stat_float_times\(\))c FN(returns)j(T)m(rue,)h(the)f(result)h(is) g(a)g(\003oating)f(point)208 2876 y(number)-5 b(.)0 3023 y FD(getmtime)p FJ(\()p FK(path)p FJ(\))208 3123 y FN(Return)22 b(the)h(time)g(of)g(last)h(modi\002cation)d(of)h FK(path)p FN(.)33 b(The)22 b(return)g(v)n(alue)g(is)i(a)g(number)d(gi)n(ving)g (the)i(number)e(of)i(seconds)f(since)208 3222 y(the)c(epoch)f(\(see)i (the)f FJ(time)g FN(module\).)23 b(Raise)c FJ(os.error)f FN(if)g(the)h(\002le)g(does)f(not)g(e)o(xist)g(or)g(is)i(inaccessible.) 49 b(Ne)n(w)18 b(in)h(v)o(ersion)208 3322 y(1.5.2.)123 b(Changed)24 b(in)i(v)o(ersion)e(2.3:)h(If)h FJ (os.stat_float_times\(\))c FN(returns)j(T)m(rue,)h(the)f(result)h(is)g (a)g(\003oating)f(point)208 3422 y(number)-5 b(.)0 3569 y FD(getctime)p FJ(\()p FK(path)p FJ(\))208 3668 y FN(Return)25 b(the)h(system')-5 b(s)26 b(ctime)g(which,)g(on)f(some)h(systems)g (\(lik)o(e)i(U)t FH(N)t(I)t(X)r FN(\))e(is)h(the)e(time)h(of)g(the)f (last)i(change,)e(and,)i(on)e(others)208 3768 y(\(lik)o(e)c(W)m(indo)n (ws\),)f(is)j(the)e(creation)f(time)i(for)f FK(path)p FN(.)27 b(The)21 b(return)f(v)n(alue)h(is)h(a)g(number)e(gi)n(ving)g (the)h(number)f(of)h(seconds)f(since)208 3867 y(the)e(epoch)f(\(see)i (the)f FJ(time)g FN(module\).)23 b(Raise)c FJ(os.error)f FN(if)g(the)h(\002le)g(does)f(not)g(e)o(xist)g(or)g(is)i(inaccessible.) 49 b(Ne)n(w)18 b(in)h(v)o(ersion)208 3967 y(2.3.)0 4114 y FD(getsize)p FJ(\()p FK(path)p FJ(\))208 4214 y FN(Return)g(the)i (size,)f(in)h(bytes,)f(of)g FK(path)p FN(.)k(Raise)d FJ(os.error)f FN(if)g(the)h(\002le)f(does)g(not)g(e)o(xist)h(or)f(is)h (inaccessible.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)208 4313 y(1.5.2.)0 4460 y FD(isabs)p FJ(\()p FK(path)p FJ(\))208 4560 y FN(Return)e FJ(True)h FN(if)h FK(path)e FN(is)i(an)f(absolute)g (pathname)e(\(be)o(gins)h(with)i(a)f(slash\).)0 4707 y FD(isfile)p FJ(\()p FK(path)p FJ(\))208 4806 y FN(Return)15 b FJ(True)h FN(if)h FK(path)e FN(is)i(an)f(e)o(xisting)g(re)o(gular)e (\002le.)25 b(This)16 b(follo)n(ws)g(symbolic)f(links,)i(so)f(both)g FJ(islink\(\))f FN(and)g FJ(isfile\(\))208 4906 y FN(can)20 b(be)g(true)g(for)f(the)h(same)h(path.)0 5053 y FD(isdir)p FJ(\()p FK(path)p FJ(\))208 5152 y FN(Return)h FJ(True)h FN(if)g FK(path)f FN(is)i(an)f(e)o(xisting)g(directory)-5 b(.)31 b(This)23 b(follo)n(ws)g(symbolic)f(links,)h(so)h(both)e FJ(islink\(\))g FN(and)g FJ(isdir\(\))208 5252 y FN(can)e(be)g(true)g (for)f(the)h(same)h(path.)0 5399 y FD(islink)p FJ(\()p FK(path)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(326)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 327 339 TeXDict begin 327 338 bop 208 83 a FN(Return)19 b FJ(True)g FN(if)i FK(path)d FN(refers)i(to)g(a)g(directory)e(entry)h(that)h(is)g (a)h(symbolic)d(link.)25 b(Al)o(w)o(ays)20 b FJ(False)g FN(if)g(symbolic)e(links)i(are)g(not)208 183 y(supported.)0 330 y FD(ismount)p FJ(\()p FK(path)p FJ(\))208 429 y FN(Return)h FJ(True)h FN(if)g(pathname)e FK(path)h FN(is)i(a)g FK(mount)e(point)p FN(:)28 b(a)22 b(point)f(in)h(a)h(\002le)f(system)g (where)g(a)g(dif)n(ferent)e(\002le)j(system)f(has)g(been)208 529 y(mounted.)39 b(The)25 b(function)e(checks)i(whether)g FK(path)p FN(')-5 b(s)25 b(parent,)g(`)p FK(path)p FI(/..)p FN(',)h(is)g(on)f(a)h(dif)n(ferent)e(de)n(vice)h(than)g FK(path)p FN(,)g(or)h(whether)208 628 y(`)p FK(path)p FI(/..)p FN(')i(and)21 b FK(path)g FN(point)f(to)i(the)g(same)g(i-node) e(on)h(the)h(same)g(de)n(vice)e(\227)j(this)f(should)e(detect)i(mount)e (points)h(for)g(all)k(U)t FH(N)t(I)t(X)208 728 y FN(and)19 b(POSIX)i(v)n(ariants.)0 875 y FD(join)p FJ(\()p FK(path1)p FC([)p FK(,)d(path2)p FC([)p FK(,)g(...)12 b FC(])g(])p FJ(\))208 975 y FN(Join)20 b(one)h(or)f(more)g(path)g(components)f (intelligently)-5 b(.)25 b(If)c(an)o(y)f(component)e(is)k(an)f (absolute)f(path,)g(all)i(pre)n(vious)d(components)208 1074 y(\(on)28 b(W)m(indo)n(ws,)j(including)c(the)j(pre)n(vious)d(dri)n (v)o(e)h(letter)m(,)k(if)d(there)g(w)o(as)h(one\))e(are)i(thro)n(wn)e (a)o(w)o(ay)-5 b(,)30 b(and)f(joining)f(continues.)208 1174 y(The)22 b(return)g(v)n(alue)g(is)h(the)g(concatenation)e(of)h FK(path1)p FN(,)g(and)g(optionally)f FK(path2)p FN(,)h(etc.,)i(with)f (e)o(xactly)e(one)i(directory)e(separator)208 1273 y(\()p FJ(os.sep)p FN(\))d(inserted)i(between)f(components,)f(unless)i FK(path2)f FN(is)i(empty)-5 b(.)23 b(Note)d(that)h(on)e(W)m(indo)n(ws,) h(since)g(there)f(is)i(a)g(current)208 1373 y(directory)d(for)h(each)h (dri)n(v)o(e,)f FJ(os.path.join\("c:",)46 b("foo"\))20 b FN(represents)f(a)h(path)g(relati)n(v)o(e)f(to)h(the)h(current)d (directory)208 1473 y(on)h(dri)n(v)o(e)g(`)p FO(C:)p FN(')h(\(`)p FO(c:f)n(oo)p FN('\),)e(not)i(`)p FO(c:)p Fk(nn)p FO(f)n(oo)p FN('.)0 1620 y FD(normcase)p FJ(\()p FK(path)p FJ(\))208 1719 y FN(Normalize)h(the)i(case)g(of)f(a)h (pathname.)30 b(On)25 b(U)t FH(N)t(I)t(X)r FN(,)f(this)f(returns)f(the) g(path)g(unchanged;)g(on)g(case-insensiti)n(v)o(e)f(\002lesystems,)208 1819 y(it)f(con)m(v)o(erts)f(the)h(path)g(to)g(lo)n(wercase.)25 b(On)20 b(W)m(indo)n(ws,)f(it)i(also)g(con)m(v)o(erts)d(forw)o(ard)h (slashes)i(to)f(backw)o(ard)f(slashes.)0 1966 y FD(normpath)p FJ(\()p FK(path)p FJ(\))208 2065 y FN(Normalize)i(a)h(pathname.)29 b(This)22 b(collapses)g(redundant)d(separators)i(and)h(up-le)n(v)o(el)e (references)h(so)h(that)g FJ(A//B)p FN(,)g FJ(A/./B)f FN(and)208 2165 y FJ(A/foo/../B)h FN(all)j(become)e FJ(A/B)p FN(.)h(It)h(does)f(not)f(normalize)g(the)h(case)h(\(use)f FJ(normcase\(\))f FN(for)h(that\).)36 b(On)24 b(W)m(indo)n(ws,)h(it)208 2265 y(con)m(v)o(erts)19 b(forw)o(ard)h(slashes)i(to)f(backw)o(ard)e (slashes.)29 b(It)21 b(should)g(be)g(understood)d(that)k(this)f(may)g (change)f(the)h(meaning)f(of)h(the)208 2364 y(path)e(if)i(it)g (contains)e(symbolic)g(links!)0 2511 y FD(realpath)p FJ(\()p FK(path)p FJ(\))208 2611 y FN(Return)j(the)h(canonical)e(path)i (of)f(the)h(speci\002ed)g(\002lename,)g(eliminating)e(an)o(y)h (symbolic)g(links)h(encountered)d(in)j(the)g(path)g(\(if)208 2710 y(the)o(y)c(are)h(supported)e(by)i(the)g(operating)f(system\).)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 2857 y FD(samefile)p FJ(\()p FK(path1,)e(path2)p FJ(\))208 2957 y FN(Return)i FJ(True)g FN(if)h(both)e(pathname)g(ar)o(guments)g(refer)g(to)i(the)g (same)f(\002le)h(or)g(directory)d(\(as)j(indicated)f(by)g(de)n(vice)f (number)g(and)208 3056 y(i-node)23 b(number\).)38 b(Raise)26 b(an)f(e)o(xception)e(if)i(a)h FJ(os.stat\(\))d FN(call)j(on)f(either)f (pathname)g(f)o(ails.)40 b(A)-6 b(v)n(ailability:)34 b(Macintosh,)210 3156 y(U)t FH(N)t(I)t(X)r FN(.)0 3303 y FD(sameopenfile)p FJ(\()p FK(fp1,)17 b(fp2)p FJ(\))208 3403 y FN(Return)i FJ(True)h FN(if)h(the)f(\002le)h(descriptors)e FK(fp1)h FN(and)f FK(fp2)h FN(refer)g(to)g(the)g(same)h(\002le.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 3549 y FD(samestat)p FJ(\()p FK(stat1,)d(stat2)p FJ(\))208 3649 y FN(Return)32 b FJ(True)h FN(if)h(the)f(stat)h(tuples)f FK(stat1)g FN(and)g FK(stat2)g FN(refer)f(to)i(the)f(same)g(\002le.)65 b(These)33 b(structures)f(may)h(ha)n(v)o(e)f(been)h(re-)208 3749 y(turned)25 b(by)h FJ(fstat\(\))p FN(,)h FJ(lstat\(\))p FN(,)g(or)g FJ(stat\(\))p FN(.)43 b(This)27 b(function)e(implements)h (the)g(underlying)e(comparison)h(used)h(by)208 3848 y FJ(samefile\(\))18 b FN(and)i FJ(sameopenfile\(\))p FN(.)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 3995 y FD(split)p FJ(\()p FK(path)p FJ(\))208 4095 y FN(Split)32 b(the)h(pathname)d FK(path)i FN(into)g(a)g(pair)m(,) j FJ(\()p FK(head)r FJ(,)48 b FK(tail)p FJ(\))32 b FN(where)g FK(tail)g FN(is)i(the)e(last)h(pathname)e(component)e(and)j FK(head)i FN(is)208 4194 y(e)n(v)o(erything)18 b(leading)h(up)h(to)h (that.)27 b(The)20 b FK(tail)h FN(part)g(will)g(ne)n(v)o(er)e(contain)h (a)h(slash;)h(if)f FK(path)e FN(ends)i(in)g(a)g(slash,)g FK(tail)g FN(will)g(be)g(empty)-5 b(.)208 4294 y(If)21 b(there)f(is)i(no)f(slash)h(in)f FK(path)p FN(,)g FK(head)h FN(will)g(be)f(empty)-5 b(.)27 b(If)21 b FK(path)f FN(is)i(empty)-5 b(,)20 b(both)g FK(head)j FN(and)d FK(tail)i FN(are)f(empty)-5 b(.)26 b(T)m(railing)21 b(slashes)208 4394 y(are)g(stripped)g(from)f FK(head)j FN(unless)f(it)g(is)h(the)e(root)g(\(one)g(or)g(more)g (slashes)h(only\).)28 b(In)22 b(nearly)e(all)j(cases,)f FJ(join\()p FK(head)r FJ(,)47 b FK(tail)p FJ(\))208 4493 y FN(equals)19 b FK(path)h FN(\(the)g(only)f(e)o(xception)f(being)i (when)f(there)h(were)g(multiple)f(slashes)i(separating)e FK(head)j FN(from)d FK(tail)p FN(\).)0 4640 y FD(splitdrive)p FJ(\()p FK(path)p FJ(\))208 4740 y FN(Split)g(the)h(pathname)d FK(path)i FN(into)g(a)h(pair)f FJ(\()p FK(drive)p FJ(,)49 b FK(tail)p FJ(\))19 b FN(where)g FK(drive)h FN(is)g(either)f(a)h(dri)n (v)o(e)e(speci\002cation)g(or)h(the)h(empty)e(string.)208 4839 y(On)23 b(systems)h(which)e(do)h(not)g(use)g(dri)n(v)o(e)g (speci\002cations,)g FK(drive)g FN(will)h(al)o(w)o(ays)g(be)f(the)g (empty)g(string.)33 b(In)23 b(all)h(cases,)h FK(drive)49 b FJ(+)208 4939 y FK(tail)20 b FN(will)h(be)f(the)g(same)h(as)g FK(path)p FN(.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(1.3.)0 5086 y FD(splitext)p FJ(\()p FK(path)p FJ(\))208 5186 y FN(Split)27 b(the)g(pathname)f FK(path)g FN(into)h(a)h(pair)f FJ(\()p FK(r)l(oot)q FJ(,)49 b FK(e)n(xt)q FJ(\))29 b FN(such)d(that)i FK(r)l(oot)51 b FJ(+)e FK(e)n(xt)j FJ(==)d FK(path)p FN(,)28 b(and)f FK(e)n(xt)i FN(is)f(empty)f(or)f(be)o(gins) 208 5285 y(with)20 b(a)h(period)d(and)i(contains)g(at)g(most)g(one)g (period.)p 0 5549 3901 4 v 0 5649 a FI(11.1.)52 b FJ(os.path)22 b FI(\227)h(Common)h(pathname)g(manipulations)1786 b(327)p eop end %%Page: 328 340 TeXDict begin 328 339 bop 0 83 a FD(splitunc)p FJ(\()p FK(path)p FJ(\))208 183 y FN(Split)55 b(the)g(pathname)e FK(path)i FN(into)f(a)i(pair)e FJ(\()p FK(unc)p FJ(,)49 b FK(r)m(est)q FJ(\))56 b FN(so)f(that)g FK(unc)g FN(is)h(the)f(UNC)g (mount)f(point)g(\(such)h(as)208 282 y FJ(r'\\\\host\\mount')p FN(\),)23 b(if)i(present,)g(and)g FK(r)m(est)i FN(the)e(rest)h(of)e (the)h(path)g(\(such)f(as)i FJ(r'\\path\\file.ext')p FN(\).)36 b(F)o(or)25 b(paths)208 382 y(containing)18 b(dri)n(v)o(e)h(letters,)h FK(unc)g FN(will)h(al)o(w)o(ays)f(be)h(the)f (empty)f(string.)25 b(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws.)0 529 y FD(walk)p FJ(\()p FK(path,)18 b(visit,)j(ar)m(g)p FJ(\))208 628 y FN(Calls)e(the)f(function)e FK(visit)21 b FN(with)d(ar)o(guments)e FJ(\()p FK(ar)m(g)p FJ(,)49 b FK(dirname)p FJ(,)f FK(names)p FJ(\))18 b FN(for)f(each)h(directory)e (in)i(the)g(directory)f(tree)h(rooted)208 728 y(at)29 b FK(path)f FN(\(including)f FK(path)h FN(itself,)k(if)d(it)h(is)f(a)h (directory\).)49 b(The)29 b(ar)o(gument)d FK(dirname)i FN(speci\002es)i(the)f(visited)g(directory)-5 b(,)29 b(the)208 828 y(ar)o(gument)19 b FK(names)i FN(lists)j(the)d(\002les)i (in)f(the)g(directory)e(\(gotten)g(from)h FJ(os.listdir\()p FK(dirname)p FJ(\))p FN(\).)26 b(The)c FK(visit)i FN(function)c(may)208 927 y(modify)d FK(names)j FN(to)f(in\003uence)g(the)g(set)h(of)f (directories)g(visited)g(belo)n(w)g FK(dirname)p FN(,)g(e.g.)24 b(to)c(a)n(v)n(oid)f(visiting)g(certain)g(parts)g(of)h(the)208 1027 y(tree.)k(\(The)c(object)g(referred)e(to)i(by)g FK(names)g FN(must)g(be)g(modi\002ed)f(in)i(place,)e(using)h FJ(del)g FN(or)g(slice)h(assignment.\))208 1160 y FL(Note:)69 b FN(Symbolic)42 b(links)h(to)g(directories)f(are)h(not)g(treated)f(as) i(subdirectories,)j(and)42 b(that)h FJ(walk\(\))g FN(therefore)e(will) 208 1259 y(not)g(visit)h(them.)88 b(T)-7 b(o)42 b(visit)g(link)o(ed)f (directories)f(you)h(must)g(identify)g(them)g(with)h FJ(os.path.islink\()p FK(\002le)p FJ(\))c FN(and)208 1359 y FJ(os.path.isdir\()p FK(\002le)p FJ(\))p FN(,)17 b(and)i(in)m(v)n(ok)o(e)g FJ(walk\(\))h FN(as)h(necessary)-5 b(.)208 1492 y FL(Note:)24 b FN(The)c(ne)n(wer)f FJ(os.walk\(\))g FN(generator)g(supplies)g(similar)i(functionality)d(and)i(can)g(be)g (easier)g(to)g(use.)0 1639 y FD(supports_unicode_filenames)208 1738 y FN(T)m(rue)h(if)h(arbitrary)e(Unicode)g(strings)i(can)f(be)h (used)f(as)i(\002le)f(names)f(\(within)g(limitations)h(imposed)e(by)i (the)f(\002le)i(system\),)e(and)208 1838 y(if)f FJ(os.listdir\(\))f FN(returns)g(Unicode)g(strings)h(for)g(a)g(Unicode)f(ar)o(gument.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2165 y FE(11.2)121 b Fx(fileinput)31 b FE(\227)i(Iter)o(ate)i(o)n(v)m(er)f(lines)f(from)g (m)o(ultiple)g(input)h(streams)0 2398 y FN(This)20 b(module)f (implements)g(a)i(helper)e(class)i(and)f(functions)f(to)h(quickly)f (write)h(a)h(loop)e(o)o(v)o(er)g(standard)g(input)h(or)f(a)i(list)g(of) f(\002les.)0 2545 y(The)g(typical)g(use)g(is:)236 2783 y FA(import)44 b(fileinput)236 2875 y(for)h(line)f(in)g (fileinput.input\(\):)416 2966 y(process\(line\))0 3252 y FN(This)26 b(iterates)g(o)o(v)o(er)f(the)h(lines)g(of)f(all)i (\002les)g(listed)f(in)g FJ(sys.argv[1:])p FN(,)f(def)o(aulting)g(to)h FJ(sys.stdin)e FN(if)i(the)g(list)h(is)g(empty)-5 b(.)41 b(If)0 3352 y(a)25 b(\002lename)e(is)i FJ('-')p FN(,)g(it)g(is)g(also)g (replaced)d(by)i FJ(sys.stdin)p FN(.)36 b(T)-7 b(o)24 b(specify)g(an)g(alternati)n(v)o(e)f(list)i(of)f(\002lenames,)g(pass)h (it)g(as)g(the)f(\002rst)0 3452 y(ar)o(gument)18 b(to)i FJ(input\(\))p FN(.)k(A)d(single)f(\002le)h(name)f(is)h(also)f(allo)n (wed.)0 3599 y(All)i(\002les)g(are)f(opened)e(in)j(te)o(xt)f(mode)f(by) h(def)o(ault,)f(b)n(ut)h(you)f(can)h(o)o(v)o(erride)e(this)j(by)f (specifying)e(the)i FK(mode)g FN(parameter)e(in)j(the)f(call)g(to)0 3698 y FJ(input\(\))e FN(or)h FJ(FileInput\(\))p FN(.)k(If)c(an)g(I/O)g (error)f(occurs)h(during)e(opening)h(or)h(reading)e(a)j(\002le,)g FJ(IOError)e FN(is)i(raised.)0 3845 y(If)g FJ(sys.stdin)e FN(is)j(used)e(more)g(than)g(once,)g(the)h(second)e(and)i(further)e (use)i(will)g(return)f(no)g(lines,)h(e)o(xcept)e(perhaps)h(for)g (interacti)n(v)o(e)0 3945 y(use,)g(or)g(if)h(it)f(has)h(been)e(e)o (xplicitly)h(reset)g(\(e.g.)k(using)c FJ(sys.stdin.seek\(0\))p FN(\).)0 4092 y(Empty)e(\002les)i(are)f(opened)f(and)h(immediately)e (closed;)j(the)f(only)f(time)i(their)e(presence)h(in)g(the)g(list)h(of) f(\002lenames)g(is)h(noticeable)e(at)i(all)0 4191 y(is)h(when)f(the)g (last)h(\002le)g(opened)d(is)j(empty)-5 b(.)0 4338 y(It)26 b(is)h(possible)f(that)g(the)g(last)h(line)f(of)f(a)i(\002le)f(does)g (not)g(end)f(in)h(a)h(ne)n(wline)e(character;)j(lines)e(are)g(returned) e(including)g(the)i(trailing)0 4438 y(ne)n(wline)20 b(when)f(it)i(is)g (present.)0 4585 y(Y)-9 b(ou)29 b(can)g(control)f(ho)n(w)h(\002les)h (are)f(opened)f(by)h(pro)o(viding)d(an)j(opening)f(hook)f(via)j(the)f FK(openhook)f FN(parameter)g(to)h FJ(input\(\))g FN(or)0 4684 y FJ(FileInput\(\))p FN(.)k(The)23 b(hook)f(must)i(be)f(a)h (function)d(that)j(tak)o(es)g(tw)o(o)f(ar)o(guments,)f FK(\002lename)g FN(and)h FK(mode)p FN(,)g(and)g(returns)g(an)g(accord-) 0 4784 y(ingly)c(opened)g(\002le-lik)o(e)h(object.)25 b(T)-7 b(w)o(o)20 b(useful)g(hooks)f(are)h(already)f(pro)o(vided)f(by)h (this)i(module.)0 4931 y(The)f(follo)n(wing)e(function)h(is)i(the)f (primary)f(interf)o(ace)g(of)h(this)h(module:)0 5078 y FD(input)p FJ(\()p FC([)p FK(\002les)p FC([)p FK(,)e(inplace)p FC([)p FK(,)f(bac)n(kup)p FC([)p FK(,)h(mode)p FC([)p FK(,)g(openhook)13 b FC(])f(])g(])g(])g(])p FJ(\))208 5177 y FN(Create)22 b(an)g(instance)f(of)h(the)g FJ(FileInput)f FN(class.)32 b(The)21 b(instance)h(will)h(be)f(used)g(as)g(global)f (state)i(for)f(the)g(functions)e(of)i(this)208 5277 y(module,)d(and)h (is)i(also)f(returned)e(to)i(use)g(during)f(iteration.)26 b(The)20 b(parameters)g(to)h(this)g(function)e(will)j(be)f(passed)g (along)f(to)h(the)208 5376 y(constructor)d(of)i(the)g FJ(FileInput)f FN(class.)p 0 5549 3901 4 v 0 5649 a FI(328)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 329 341 TeXDict begin 329 340 bop 208 83 a FN(Changed)18 b(in)j(v)o(ersion)e (2.5:)g(Added)g(the)i FK(mode)e FN(and)h FK(openhook)f FN(parameters.)0 230 y(The)28 b(follo)n(wing)f(functions)g(use)h(the)h (global)e(state)j(created)d(by)h FJ(input\(\))p FN(;)k(if)d(there)f(is) h(no)f(acti)n(v)o(e)g(state,)j FJ(RuntimeError)c FN(is)0 330 y(raised.)0 476 y FD(filename)p FJ(\(\))208 576 y FN(Return)19 b(the)i(name)e(of)h(the)g(\002le)h(currently)e(being)g (read.)24 b(Before)c(the)g(\002rst)h(line)f(has)h(been)e(read,)h (returns)f FJ(None)p FN(.)0 723 y FD(fileno)p FJ(\(\))208 823 y FN(Return)g(the)g(inte)o(ger)g(\223\002le)h(descriptor\224)e(for) h(the)h(current)e(\002le.)26 b(When)19 b(no)h(\002le)g(is)g(opened)e (\(before)g(the)i(\002rst)g(line)g(and)f(between)208 922 y(\002les\),)h(returns)f FJ(-1)p FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1069 y FD(lineno)p FJ(\(\))208 1169 y FN(Return)g(the)g(cumulati)n(v)o(e)f(line)i(number)d(of)j(the)f (line)h(that)g(has)f(just)h(been)f(read.)24 b(Before)19 b(the)h(\002rst)g(line)g(has)g(been)f(read,)f(returns)208 1268 y FJ(0)p FN(.)25 b(After)20 b(the)g(last)h(line)f(of)g(the)g(last) i(\002le)e(has)h(been)e(read,)h(returns)f(the)h(line)h(number)d(of)i (that)g(line.)0 1415 y FD(filelineno)p FJ(\(\))208 1515 y FN(Return)f(the)h(line)g(number)e(in)i(the)f(current)g(\002le.)25 b(Before)20 b(the)f(\002rst)i(line)f(has)g(been)f(read,)g(returns)g FJ(0)p FN(.)25 b(After)20 b(the)f(last)i(line)f(of)g(the)208 1614 y(last)h(\002le)f(has)h(been)e(read,)h(returns)f(the)h(line)h (number)d(of)i(that)g(line)g(within)g(the)h(\002le.)0 1761 y FD(isfirstline)p FJ(\(\))208 1861 y FN(Returns)f(true)f(if)i (the)f(line)g(just)h(read)f(is)h(the)f(\002rst)h(line)f(of)g(its)h (\002le,)g(otherwise)f(returns)f(f)o(alse.)0 2008 y FD(isstdin)p FJ(\(\))208 2107 y FN(Returns)h(true)f(if)i(the)f(last)h(line)f(w)o(as) i(read)d(from)g FJ(sys.stdin)p FN(,)g(otherwise)h(returns)f(f)o(alse.)0 2254 y FD(nextfile)p FJ(\(\))208 2354 y FN(Close)25 b(the)f(current)f (\002le)i(so)g(that)f(the)h(ne)o(xt)e(iteration)h(will)h(read)f(the)g (\002rst)i(line)e(from)f(the)i(ne)o(xt)f(\002le)h(\(if)f(an)o(y\);)h (lines)g(not)f(read)208 2454 y(from)e(the)h(\002le)g(will)h(not)f (count)f(to)n(w)o(ards)g(the)h(cumulati)n(v)o(e)f(line)h(count.)32 b(The)23 b(\002lename)f(is)i(not)f(changed)e(until)i(after)g(the)g (\002rst)208 2553 y(line)h(of)g(the)g(ne)o(xt)f(\002le)i(has)g(been)e (read.)36 b(Before)24 b(the)g(\002rst)h(line)f(has)h(been)e(read,)i (this)f(function)f(has)h(no)g(ef)n(fect;)i(it)f(cannot)e(be)208 2653 y(used)c(to)i(skip)f(the)g(\002rst)h(\002le.)26 b(After)20 b(the)g(last)h(line)f(of)g(the)g(last)h(\002le)g(has)g(been) e(read,)h(this)g(function)f(has)h(no)g(ef)n(fect.)0 2800 y FD(close)p FJ(\(\))208 2899 y FN(Close)g(the)h(sequence.)0 3046 y(The)f(class)h(which)f(implements)f(the)h(sequence)f(beha)n(vior) g(pro)o(vided)e(by)j(the)g(module)f(is)i(a)n(v)n(ailable)f(for)g (subclassing)f(as)i(well:)0 3193 y FL(class)g FD(FileInput)p FJ(\()p FC([)p FK(\002les)p FC([)p FK(,)d(inplace)p FC([)p FK(,)h(bac)n(kup)p FC([)p FK(,)f(mode)p FC([)p FK(,)h(openhook)13 b FC(])f(])g(])g(])g(])p FJ(\))208 3293 y FN(Class)67 b FJ(FileInput)e FN(is)i(the)f(implementation;)87 b(its)67 b(methods)e FJ(filename\(\))p FN(,)76 b FJ(fileno\(\))p FN(,)h FJ(lineno\(\))p FN(,)208 3392 y FJ(fileline\(\))p FN(,)23 b FJ(isfirstline\(\))p FN(,)g FJ(isstdin\(\))p FN(,)h FJ(nextfile\(\))f FN(and)g FJ(close\(\))h FN(correspond)d(to)k (the)f(functions)208 3492 y(of)e(the)i(same)f(name)f(in)i(the)f (module.)32 b(In)23 b(addition)f(it)i(has)f(a)g FJ(readline\(\))f FN(method)g(which)h(returns)f(the)h(ne)o(xt)f(input)h(line,)208 3591 y(and)d(a)i FJ(__getitem__\(\))d FN(method)h(which)g(implements)g (the)h(sequence)f(beha)n(vior)-5 b(.)27 b(The)20 b(sequence)g(must)h (be)g(accessed)g(in)208 3691 y(strictly)f(sequential)f(order;)g(random) g(access)i(and)e FJ(readline\(\))g FN(cannot)g(be)h(mix)o(ed.)208 3824 y(W)m(ith)f FK(mode)g FN(you)f(can)i(specify)e(which)h(\002le)h (mode)f(will)h(be)f(passed)g(to)h FJ(open\(\))p FN(.)k(It)c(must)f(be)h (one)e(of)h FJ('r')p FN(,)h FJ('rU')p FN(,)f FJ('U')g FN(and)208 3924 y FJ('rb')p FN(.)208 4056 y(The)26 b FK(openhook)q FN(,)g(when)g(gi)n(v)o(en,)h(must)f(be)h(a)g(function)e (that)i(tak)o(es)g(tw)o(o)g(ar)o(guments,)f FK(\002lename)f FN(and)h FK(mode)p FN(,)i(and)e(returns)g(an)208 4156 y(accordingly)17 b(opened)i(\002le-lik)o(e)h(object.)k(Y)-9 b(ou)20 b(cannot)f(use)h FK(inplace)g FN(and)f FK(openhook)g FN(together)-5 b(.)208 4289 y(Changed)18 b(in)j(v)o(ersion)e(2.5:)g (Added)g(the)i FK(mode)e FN(and)h FK(openhook)f FN(parameters.)0 4436 y FL(Optional)j(in-place)h(\002ltering:)29 b FN(if)23 b(the)g(k)o(e)o(yw)o(ord)e(ar)o(gument)f FK(inplace)p FJ(=1)h FN(is)j(passed)e(to)h FJ(input\(\))f FN(or)g(to)h(the)g FJ(FileInput)e FN(con-)0 4535 y(structor)m(,)d(the)i(\002le)g(is)h(mo)o (v)o(ed)d(to)h(a)h(backup)e(\002le)j(and)e(standard)f(output)g(is)j (directed)e(to)g(the)h(input)f(\002le)h(\(if)g(a)g(\002le)g(of)f(the)h (same)g(name)f(as)0 4635 y(the)h(backup)d(\002le)j(already)f(e)o (xists,)h(it)g(will)g(be)g(replaced)e(silently\).)24 b(This)c(mak)o(es)f(it)h(possible)g(to)f(write)h(a)g(\002lter)g(that)f (re)n(writes)h(its)g(input)0 4735 y(\002le)g(in)f(place.)25 b(If)19 b(the)g(k)o(e)o(yw)o(ord)f(ar)o(gument)f FK(bac)n(kup)p FJ(='.<some)46 b(extension>')18 b FN(is)i(also)g(gi)n(v)o(en,)e(it)i (speci\002es)g(the)f(e)o(xtension)f(for)0 4834 y(the)24 b(backup)f(\002le,)i(and)f(the)g(backup)f(\002le)i(remains)e(around;)i (by)f(def)o(ault,)g(the)g(e)o(xtension)f(is)i FJ('.bak')f FN(and)f(it)i(is)g(deleted)f(when)g(the)0 4934 y(output)19 b(\002le)i(is)g(closed.)k(In-place)18 b(\002ltering)i(is)h(disabled)f (when)f(standard)g(input)h(is)h(read.)0 5081 y FL(Ca)n(v)o(eat:)i FN(The)d(current)f(implementation)f(does)i(not)g(w)o(ork)f(for)h (MS-DOS)g(8+3)g(\002lesystems.)0 5228 y(The)g(tw)o(o)g(follo)n(wing)f (opening)f(hooks)h(are)h(pro)o(vided)e(by)i(this)g(module:)0 5374 y FD(hook_compressed)p FJ(\()p FK(\002lename)o(,)c(mode)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(11.2.)52 b FJ(fileinput)22 b FI(\227)h(Iter)o(ate)g(o)o(v)n(er)g(lines)g(from)h(m)o(ultiple)h (input)f(streams)1319 b(329)p eop end %%Page: 330 342 TeXDict begin 330 341 bop 208 83 a FN(T)m(ransparently)18 b(opens)h(\002les)j(compressed)d(with)h(gzip)g(and)g(bzip2)g (\(recognized)e(by)i(the)g(e)o(xtensions)f FJ('.gz')i FN(and)e FJ('.bz2')p FN(\))208 183 y(using)29 b(the)h FJ(gzip)g FN(and)g FJ(bz2)g FN(modules.)53 b(If)30 b(the)g(\002lename)g (e)o(xtension)e(is)j(not)f FJ('.gz')g FN(or)g FJ('.bz2')p FN(,)h(the)f(\002le)h(is)g(opened)208 282 y(normally)18 b(\(ie,)i(using)g FJ(open\(\))f FN(without)h(an)o(y)f(decompression\).) 208 415 y(Usage)h(e)o(xample:)k(`)p FJ(fi)49 b(=)g (fileinput.FileInput\(openhook=fileinpu)o(t.hoo)o(k_comp)o(resse)o(d\)) p FN(')208 548 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 695 y FD(hook_encoded)p FJ(\()p FK(encoding)p FJ(\))208 794 y FN(Returns)h(a)g(hook)f(which)h(opens)f(each)h(\002le)h(with)f FJ(codecs.open\(\))p FN(,)e(using)i(the)g(gi)n(v)o(en)f FK(encoding)f FN(to)j(read)e(the)h(\002le.)208 927 y(Usage)225 b(e)o(xample:)436 b(`)p FJ(fi)49 b(=)g (fileinput.FileInput\(openhook=fileinpu)o(t.hook)o(_-)208 1027 y(encoded\("iso-8859-1"\)\))p FN(')208 1160 y FL(Note:)29 b FN(W)m(ith)23 b(this)h(hook,)e FJ(FileInput)g FN(might)g(return)g (Unicode)f(strings)i(depending)e(on)h(the)h(speci\002ed)g FK(encoding)p FN(.)64 b(Ne)n(w)208 1259 y(in)20 b(v)o(ersion)f(2.5.)0 1587 y FE(11.3)121 b Fx(stat)32 b FE(\227)h(Inter)t(preting)j Fx(stat\(\))31 b FE(results)0 1820 y FN(The)c FJ(stat)g FN(module)f(de\002nes)h(constants)g(and)f(functions)g(for)h (interpreting)e(the)i(results)h(of)f FJ(os.stat\(\))p FN(,)g FJ(os.fstat\(\))f FN(and)0 1919 y FJ(os.lstat\(\))e FN(\(if)h(the)o(y)g(e)o(xist\).)40 b(F)o(or)25 b(complete)f(details)i (about)e(the)h FJ(stat\(\))p FN(,)h FJ(fstat\(\))f FN(and)f FJ(lstat\(\))h FN(calls,)i(consult)e(the)0 2019 y(documentation)17 b(for)j(your)f(system.)0 2166 y(The)h FJ(stat)g FN(module)f(de\002nes)h (the)g(follo)n(wing)e(functions)h(to)h(test)i(for)d(speci\002c)i (\002le)f(types:)0 2313 y FD(S_ISDIR)p FJ(\()p FK(mode)p FJ(\))208 2412 y FN(Return)f(non-zero)f(if)j(the)f(mode)f(is)i(from)e (a)i(directory)-5 b(.)0 2559 y FD(S_ISCHR)p FJ(\()p FK(mode)p FJ(\))208 2659 y FN(Return)19 b(non-zero)f(if)j(the)f(mode)f(is)i(from) e(a)i(character)e(special)h(de)n(vice)g(\002le.)0 2806 y FD(S_ISBLK)p FJ(\()p FK(mode)p FJ(\))208 2905 y FN(Return)f(non-zero) f(if)j(the)f(mode)f(is)i(from)e(a)i(block)e(special)h(de)n(vice)g (\002le.)0 3052 y FD(S_ISREG)p FJ(\()p FK(mode)p FJ(\))208 3152 y FN(Return)f(non-zero)f(if)j(the)f(mode)f(is)i(from)e(a)i(re)o (gular)e(\002le.)0 3299 y FD(S_ISFIFO)p FJ(\()p FK(mode)p FJ(\))208 3398 y FN(Return)g(non-zero)f(if)j(the)f(mode)f(is)i(from)e (a)i(FIFO)g(\(named)d(pipe\).)0 3545 y FD(S_ISLNK)p FJ(\()p FK(mode)p FJ(\))208 3645 y FN(Return)h(non-zero)f(if)j(the)f(mode)f(is) i(from)e(a)i(symbolic)e(link.)0 3792 y FD(S_ISSOCK)p FJ(\()p FK(mode)p FJ(\))208 3891 y FN(Return)g(non-zero)f(if)j(the)f (mode)f(is)i(from)e(a)i(sock)o(et.)0 4038 y(T)-7 b(w)o(o)20 b(additional)f(functions)g(are)h(de\002ned)f(for)h(more)f(general)g (manipulation)f(of)i(the)g(\002le')-5 b(s)22 b(mode:)0 4185 y FD(S_IMODE)p FJ(\()p FK(mode)p FJ(\))208 4285 y FN(Return)g(the)h(portion)f(of)h(the)g(\002le')-5 b(s)24 b(mode)e(that)h(can)g(be)g(set)h(by)e FJ(os.chmod\(\))p FN(\227that)g(is,)i(the)f(\002le')-5 b(s)25 b(permission)d(bits,)i (plus)208 4384 y(the)c(stick)o(y)g(bit,)g(set-group-id,)d(and)j (set-user)n(-id)f(bits)i(\(on)e(systems)i(that)f(support)f(them\).)0 4531 y FD(S_IFMT)p FJ(\()p FK(mode)p FJ(\))208 4631 y FN(Return)g(the)i(portion)d(of)i(the)g(\002le')-5 b(s)21 b(mode)f(that)g(describes)g(the)g(\002le)h(type)e(\(used)h(by)g(the)g FJ(S_IS)2951 4646 y(*)3001 4631 y(\(\))f FN(functions)g(abo)o(v)o(e\).) 0 4778 y(Normally)-5 b(,)21 b(you)g(w)o(ould)h(use)g(the)g FJ(os.path.is)1491 4793 y(*)1541 4778 y(\(\))f FN(functions)f(for)i (testing)g(the)g(type)g(of)g(a)g(\002le;)i(the)f(functions)d(here)i (are)g(useful)0 4877 y(when)d(you)f(are)i(doing)e(multiple)g(tests)j (of)e(the)g(same)h(\002le)g(and)f(wish)h(to)f(a)n(v)n(oid)g(the)h(o)o (v)o(erhead)c(of)k(the)f FJ(stat\(\))g FN(system)g(call)h(for)f(each)0 4977 y(test.)36 b(These)24 b(are)f(also)h(useful)f(when)g(checking)f (for)h(information)f(about)g(a)i(\002le)h(that)f(isn')o(t)f(handled)f (by)h FJ(os.path)p FN(,)h(lik)o(e)g(the)f(tests)0 5076 y(for)d(block)f(and)g(character)g(de)n(vices.)0 5223 y(All)27 b(the)g(v)n(ariables)e(belo)n(w)h(are)h(simply)f(symbolic)f (inde)o(x)o(es)h(into)g(the)g(10-tuple)f(returned)g(by)h FJ(os.stat\(\))p FN(,)h FJ(os.fstat\(\))e FN(or)0 5323 y FJ(os.lstat\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(330)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 331 343 TeXDict begin 331 342 bop 0 83 a FD(ST_MODE)208 183 y FN(Inode)18 b(protection)h(mode.)0 330 y FD(ST_INO)208 429 y FN(Inode)f(number)-5 b(.)0 576 y FD(ST_DEV)208 676 y FN(De)n(vice)19 b(inode)h(resides)g(on.)0 823 y FD(ST_NLINK)208 922 y FN(Number)e(of)i(links)h(to)f(the)g(inode.)0 1069 y FD(ST_UID)208 1169 y FN(User)g(id)g(of)g(the)h(o)n(wner)-5 b(.)0 1316 y FD(ST_GID)208 1415 y FN(Group)18 b(id)j(of)f(the)g(o)n (wner)-5 b(.)0 1562 y FD(ST_SIZE)208 1662 y FN(Size)20 b(in)h(bytes)f(of)g(a)g(plain)g(\002le;)h(amount)e(of)h(data)g(w)o (aiting)g(on)f(some)h(special)h(\002les.)0 1808 y FD(ST_ATIME)208 1908 y FN(T)m(ime)f(of)g(last)h(access.)0 2055 y FD(ST_MTIME)208 2155 y FN(T)m(ime)f(of)g(last)h(modi\002cation.)0 2301 y FD(ST_CTIME)208 2401 y FN(The)f(\223ctime\224)g(as)h(reported)e(by)h (the)h(operating)d(system.)27 b(On)20 b(some)h(systems)g(\(lik)o(e)h(U) t FH(N)t(I)t(X)r FN(\))f(is)h(the)e(time)h(of)f(the)h(last)g(metadata) 208 2501 y(change,)d(and,)i(on)f(others)h(\(lik)o(e)g(W)m(indo)n(ws\),) f(is)i(the)f(creation)g(time)g(\(see)g(platform)f(documentation)e(for)j (details\).)0 2648 y(The)k(interpretation)e(of)h(\223\002le)i(size\224) f(changes)f(according)f(to)i(the)g(\002le)h(type.)36 b(F)o(or)24 b(plain)f(\002les)i(this)g(is)g(the)f(size)g(of)g(the)g (\002le)h(in)f(bytes.)0 2747 y(F)o(or)e(FIFOs)i(and)e(sock)o(ets)h (under)e(most)i(\003a)n(v)n(ors)g(of)i(U)t FH(N)t(I)t(X)g FN(\(including)c(Linux)h(in)g(particular\),)g(the)h(\223size\224)g(is)h (the)e(number)f(of)i(bytes)0 2847 y(w)o(aiting)h(to)h(be)f(read)g(at)h (the)g(time)f(of)g(the)h(call)g(to)f FJ(os.stat\(\))p FN(,)h FJ(os.fstat\(\))p FN(,)f(or)g FJ(os.lstat\(\))p FN(;)h(this)g(can)f(sometimes)h(be)0 2946 y(useful,)h(especially)f(for) g(polling)f(one)h(of)g(these)h(special)f(\002les)i(after)e(a)h (non-blocking)21 b(open.)40 b(The)25 b(meaning)f(of)h(the)h(size)g (\002eld)f(for)0 3046 y(other)19 b(character)g(and)h(block)f(de)n (vices)h(v)n(aries)g(more,)f(depending)f(on)h(the)h(implementation)e (of)i(the)h(underlying)c(system)j(call.)0 3193 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(11.3.)52 b FJ(stat)23 b FI(\227)g(Inter)r (preting)h FJ(stat\(\))e FI(results)2185 b(331)p eop end %%Page: 332 344 TeXDict begin 332 343 bop 236 174 a FA(import)44 b(os,)g(sys)236 266 y(from)g(stat)h(import)998 279 y(*)236 448 y(def)g(walktree\(top,)d (callback\):)416 540 y('''recursively)g(descend)i(the)g(directory)f (tree)h(rooted)g(at)h(top,)550 631 y(calling)f(the)g(callback)g (function)f(for)h(each)g(regular)g(file''')416 814 y(for)g(f)h(in)f (os.listdir\(top\):)595 905 y(pathname)f(=)i(os.path.join\(top,)d(f\)) 595 996 y(mode)i(=)h(os.stat\(pathname\)[ST_MODE])595 1088 y(if)f(S_ISDIR\(mode\):)774 1179 y(#)h(It's)f(a)h(directory,)e (recurse)g(into)i(it)774 1270 y(walktree\(pathname,)d(callback\))595 1362 y(elif)i(S_ISREG\(mode\):)774 1453 y(#)h(It's)f(a)h(file,)f(call)g (the)g(callback)g(function)774 1544 y(callback\(pathname\))595 1636 y(else:)774 1727 y(#)h(Unknown)f(file)g(type,)g(print)g(a)g (message)774 1818 y(print)g('Skipping)g(\045s')g(\045)h(pathname)236 2001 y(def)g(visitfile\(file\):)416 2092 y(print)f('visiting',)f(file) 236 2275 y(if)i(__name__)e(==)i('__main__':)416 2366 y(walktree\(sys.argv[1],)c(visitfile\))0 2876 y FE(11.4)121 b Fx(statvfs)32 b FE(\227)g(Constants)k(used)e(with)g Fx(os.statvfs\(\))0 3109 y FN(The)22 b FJ(statvfs)f FN(module)g (de\002nes)g(constants)h(so)g(interpreting)e(the)i(result)g(if)g FJ(os.statvfs\(\))p FN(,)f(which)g(returns)h(a)g(tuple,)g(can)g(be)0 3209 y(made)d(without)f(remembering)f(\223magic)h(numbers.)-6 b(\224)23 b(Each)c(of)g(the)g(constants)g(de\002ned)f(in)i(this)g (module)d(is)k(the)e FK(inde)n(x)g FN(of)g(the)g(entry)f(in)0 3308 y(the)i(tuple)g(returned)e(by)i FJ(os.statvfs\(\))f FN(that)h(contains)f(the)i(speci\002ed)f(information.)0 3455 y FD(F_BSIZE)208 3555 y FN(Preferred)e(\002le)j(system)f(block)g (size.)0 3702 y FD(F_FRSIZE)208 3801 y FN(Fundamental)e(\002le)j (system)f(block)f(size.)0 3948 y FD(F_BLOCKS)208 4048 y FN(T)-7 b(otal)20 b(number)e(of)i(blocks)g(in)g(the)g(\002lesystem.)0 4195 y FD(F_BFREE)208 4294 y FN(T)-7 b(otal)20 b(number)e(of)i(free)g (blocks.)0 4441 y FD(F_BAVAIL)208 4541 y FN(Free)g(blocks)f(a)n(v)n (ailable)h(to)g(non-super)e(user)-5 b(.)0 4688 y FD(F_FILES)208 4787 y FN(T)e(otal)20 b(number)e(of)i(\002le)h(nodes.)0 4934 y FD(F_FFREE)208 5034 y FN(T)-7 b(otal)20 b(number)e(of)i(free)g (\002le)h(nodes.)0 5181 y FD(F_FAVAIL)208 5280 y FN(Free)f(nodes)f(a)n (v)n(ailable)h(to)g(non-super)e(user)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(332)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 333 345 TeXDict begin 333 344 bop 0 83 a FD(F_FLAG)208 183 y FN(Flags.)25 b(System)20 b(dependent:)j(see)e FJ(statvfs\(\))e FN(man)h(page.)0 330 y FD(F_NAMEMAX)208 429 y FN(Maximum)e(\002le)j (name)f(length.)0 757 y FE(11.5)121 b Fx(filecmp)32 b FE(\227)g(File)h(and)i(Director)t(y)e(Compar)r(isons)0 989 y FN(The)17 b FJ(filecmp)f FN(module)g(de\002nes)h(functions)f(to)h (compare)f(\002les)i(and)f(directories,)f(with)i(v)n(arious)e(optional) g(time/correctness)f(trade-)0 1089 y(of)n(fs.)0 1236 y(The)20 b FJ(filecmp)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 1383 y FD(cmp)p FJ(\()p FK(f1,)g(f2)p FC([)p FK(,)h(shallow)12 b FC(])p FJ(\))208 1482 y FN(Compare)19 b(the)h(\002les)h(named)e FK(f1)h FN(and)g FK(f2)p FN(,)g(returning)e FJ(True)i FN(if)h(the)o(y)e(seem)i(equal,)e FJ(False)h FN(otherwise.)208 1615 y(Unless)g FK(shallow)g FN(is)i(gi)n(v)o(en)c (and)i(is)h(f)o(alse,)g(\002les)g(with)f(identical)g FJ(os.stat\(\))f FN(signatures)g(are)h(tak)o(en)g(to)h(be)f(equal.)208 1748 y(Files)27 b(that)g(were)g(compared)d(using)i(this)h(function)e (will)j(not)e(be)h(compared)d(again)i(unless)h(their)f FJ(os.stat\(\))g FN(signature)208 1848 y(changes.)208 1981 y(Note)20 b(that)g(no)g(e)o(xternal)f(programs)f(are)i(called)g (from)f(this)i(function,)d(gi)n(ving)h(it)i(portability)e(and)g(ef)n (\002cienc)o(y)-5 b(.)0 2127 y FD(cmpfiles)p FJ(\()p FK(dir1,)18 b(dir2,)i(common)p FC([)p FK(,)f(shallow)12 b FC(])p FJ(\))208 2227 y FN(Returns)27 b(three)g(lists)i(of)f(\002le)g (names:)40 b FK(matc)o(h)p FN(,)28 b FK(mismatc)o(h)p FN(,)h FK(err)l(or)o(s)p FN(.)49 b FK(matc)o(h)27 b FN(contains)g(the)g (list)i(of)e(\002les)i(match)e(in)h(both)f(di-)208 2327 y(rectories,)d FK(mismatc)o(h)f FN(includes)g(the)h(names)g(of)g(those) f(that)h(don')o(t,)f(and)h FK(errr)l(os)h FN(lists)g(the)f(names)g(of)g (\002les)h(which)e(could)g(not)208 2426 y(be)h(compared.)36 b(Files)26 b(may)e(be)g(listed)h(in)g FK(err)l(or)o(s)h FN(because)e(the)g(user)h(may)f(lack)g(permission)g(to)h(read)f(them)g (or)g(man)o(y)f(other)208 2526 y(reasons,)c(b)n(ut)h(al)o(w)o(ays)h (that)f(the)g(comparison)f(could)g(not)h(be)g(done)f(for)g(some)h (reason.)208 2659 y(The)25 b FK(common)g FN(parameter)f(is)i(a)h(list)g (of)e(\002le)h(names)g(found)e(in)i(both)f(directories.)40 b(The)26 b FK(shallow)f FN(parameter)g(has)h(the)f(same)208 2758 y(meaning)18 b(and)i(def)o(ault)f(v)n(alue)h(as)h(for)e FJ(filecmp.cmp\(\))p FN(.)0 2905 y(Example:)236 3143 y FA(>>>)45 b(import)e(filecmp)236 3235 y(>>>)i (filecmp.cmp\('libundoc.tex',)40 b('libundoc.tex'\))236 3326 y(True)236 3417 y(>>>)45 b(filecmp.cmp\('libundoc.tex',)40 b('lib.tex'\))236 3509 y(False)0 3932 y Fv(11.5.1)101 b(The)28 b Fm(dircmp)e Fv(class)0 4135 y FJ(dircmp)20 b FN(instances)g(are)g(b)n(uilt)g(using)g(this)h(constructor:)0 4282 y FL(class)g FD(dircmp)p FJ(\()p FK(a,)e(b)p FC([)p FK(,)g(ignor)m(e)p FC([)p FK(,)g(hide)12 b FC(])g(])p FJ(\))208 4381 y FN(Construct)29 b(a)h(ne)n(w)f(directory)f(comparison) g(object,)j(to)f(compare)e(the)i(directories)f FK(a)g FN(and)g FK(b)p FN(.)54 b FK(ignor)m(e)29 b FN(is)i(a)f(list)g(of)g (names)208 4481 y(to)h(ignore,)h(and)f(def)o(aults)f(to)i FJ(['RCS',)48 b('CVS',)h('tags'])p FN(.)57 b FK(hide)30 b FN(is)i(a)g(list)g(of)f(names)g(to)g(hide,)i(and)e(def)o(aults)f(to) 208 4581 y FJ([os.curdir,)47 b(os.pardir])p FN(.)0 4728 y(The)20 b FJ(dircmp)f FN(class)j(pro)o(vides)c(the)i(follo)n(wing)f (methods:)0 4874 y FD(report)p FJ(\(\))208 4974 y FN(Print)h(\(to)g FJ(sys.stdout)p FN(\))e(a)j(comparison)d(between)h FK(a)i FN(and)e FK(b)p FN(.)0 5121 y FD(report_partial_closure)p FJ(\(\))208 5221 y FN(Print)h(a)g(comparison)f(between)g FK(a)h FN(and)g FK(b)g FN(and)g(common)e(immediate)h(subdirectories.)p 0 5549 3901 4 v 0 5649 a FI(11.5.)52 b FJ(filecmp)22 b FI(\227)h(File)h(and)g(Director)r(y)e(Compar)q(isons)1882 b(333)p eop end %%Page: 334 346 TeXDict begin 334 345 bop 0 83 a FD(report_full_closure)p FJ(\(\))208 183 y FN(Print)20 b(a)g(comparison)f(between)g FK(a)h FN(and)g FK(b)g FN(and)g(common)e(subdirectories)h(\(recursi)n (v)o(ely\).)0 330 y(The)25 b FJ(dircmp)g FN(of)n(fers)f(a)h(number)f (of)h(interesting)f(attrib)n(utes)h(that)g(may)g(be)g(used)g(to)h(get)f (v)n(arious)f(bits)i(of)f(information)d(about)j(the)0 429 y(directory)18 b(trees)j(being)e(compared.)0 576 y(Note)24 b(that)g(via)g FJ(__getattr__\(\))e FN(hooks,)h(all)i(attrib) n(utes)e(are)h(computed)e(lazily)-5 b(,)24 b(so)h(there)e(is)i(no)e (speed)h(penalty)f(if)h(only)f(those)0 676 y(attrib)n(utes)d(which)g (are)g(lightweight)f(to)h(compute)f(are)h(used.)0 823 y FD(left_list)208 922 y FN(Files)h(and)e(subdirectories)g(in)h FK(a)p FN(,)g(\002ltered)g(by)g FK(hide)g FN(and)f FK(ignor)m(e)p FN(.)0 1069 y FD(right_list)208 1169 y FN(Files)i(and)e(subdirectories) g(in)h FK(b)p FN(,)g(\002ltered)g(by)g FK(hide)g FN(and)f FK(ignor)m(e)p FN(.)0 1316 y FD(common)208 1415 y FN(Files)i(and)e (subdirectories)g(in)h(both)g FK(a)g FN(and)g FK(b)p FN(.)0 1562 y FD(left_only)208 1662 y FN(Files)h(and)e(subdirectories)g (only)g(in)i FK(a)p FN(.)0 1808 y FD(right_only)208 1908 y FN(Files)g(and)e(subdirectories)g(only)g(in)i FK(b)p FN(.)0 2055 y FD(common_dirs)208 2155 y FN(Subdirectories)d(in)i(both)g FK(a)g FN(and)g FK(b)p FN(.)0 2301 y FD(common_files)208 2401 y FN(Files)h(in)f(both)f FK(a)i FN(and)e FK(b)0 2548 y FD(common_funny)208 2648 y FN(Names)27 b(in)h(both)f FK(a)h FN(and)f FK(b)p FN(,)i(such)f(that)f(the)h(type)f(dif)n(fers)g (between)g(the)h(directories,)g(or)f(names)h(for)f(which)g FJ(os.stat\(\))208 2747 y FN(reports)19 b(an)h(error)-5 b(.)0 2894 y FD(same_files)208 2994 y FN(Files)21 b(which)e(are)i (identical)e(in)i(both)e FK(a)h FN(and)g FK(b)p FN(.)0 3141 y FD(diff_files)208 3240 y FN(Files)h(which)e(are)i(in)f(both)f FK(a)i FN(and)e FK(b)p FN(,)h(whose)g(contents)g(dif)n(fer)-5 b(.)0 3387 y FD(funny_files)208 3487 y FN(Files)21 b(which)e(are)i(in)f (both)f FK(a)i FN(and)e FK(b)p FN(,)h(b)n(ut)g(could)g(not)f(be)i (compared.)0 3634 y FD(subdirs)208 3733 y FN(A)f(dictionary)f(mapping)f (names)i(in)g FJ(common_dirs)f FN(to)h FJ(dircmp)g FN(objects.)0 4061 y FE(11.6)121 b Fx(tempfile)31 b FE(\227)i(Gener)o(ate)j(tempor)o (ar)t(y)d(\002les)g(and)i(director)r(ies)0 4293 y FN(This)20 b(module)f(generates)g(temporary)f(\002les)k(and)d(directories.)24 b(It)d(w)o(orks)e(on)h(all)h(supported)d(platforms.)0 4440 y(In)27 b(v)o(ersion)f(2.3)h(of)g(Python,)h(this)g(module)f(w)o (as)h(o)o(v)o(erhauled)c(for)j(enhanced)f(security)-5 b(.)45 b(It)28 b(no)n(w)f(pro)o(vides)f(three)h(ne)n(w)g(functions,)0 4540 y FJ(NamedTemporaryFile\(\))p FN(,)16 b FJ(mkstemp\(\))p FN(,)i(and)h FJ(mkdtemp\(\))p FN(,)f(which)h(should)f(eliminate)h(all)h (remaining)d(need)i(to)g(use)h(the)0 4640 y(insecure)e FJ(mktemp\(\))g FN(function.)23 b(T)-6 b(emporary)17 b(\002le)i(names)g(created)f(by)h(this)g(module)f(no)g(longer)g (contain)g(the)h(process)g(ID;)g(instead)0 4739 y(a)i(string)e(of)h (six)h(random)d(characters)i(is)h(used.)0 4886 y(Also,)26 b(all)g(the)f(user)n(-callable)e(functions)h(no)n(w)g(tak)o(e)h (additional)f(ar)o(guments)f(which)h(allo)n(w)h(direct)f(control)g(o)o (v)o(er)f(the)i(location)f(and)0 4986 y(name)29 b(of)g(temporary)e (\002les.)52 b(It)30 b(is)g(no)f(longer)f(necessary)g(to)i(use)f(the)g (global)g FK(tempdir)i FN(and)d FK(template)h FN(v)n(ariables.)51 b(T)-7 b(o)29 b(maintain)0 5085 y(backw)o(ard)16 b(compatibility)-5 b(,)16 b(the)h(ar)o(gument)e(order)i(is)h(some)n(what)f(odd;)g(it)h(is) h(recommended)14 b(to)k(use)g(k)o(e)o(yw)o(ord)d(ar)o(guments)h(for)h (clarity)-5 b(.)0 5232 y(The)20 b(module)f(de\002nes)h(the)g(follo)n (wing)e(user)n(-callable)i(functions:)0 5379 y FD(TemporaryFile)p FJ(\()p FC([)p FK(mode=)p Fn('w+b')p FC([)p FK(,)15 b(b)n(ufsize=)p Fn(-1)p FC([)p FK(,)20 b(suf)o(\002x)p FC([)p FK(,)g(pr)m(e\002x)p FC([)p FK(,)f(dir)14 b FC(])e(])g(])g(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(334)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 335 347 TeXDict begin 335 346 bop 208 83 a FN(Return)15 b(a)i(\002le)g(\(or)e (\002le-lik)o(e\))h(object)g(that)g(can)g(be)g(used)g(as)h(a)g (temporary)d(storage)h(area.)24 b(The)15 b(\002le)i(is)g(created)f (using)g FJ(mkstemp)p FN(.)208 183 y(It)26 b(will)h(be)f(destro)o(yed)e (as)j(soon)e(as)i(it)g(is)g(closed)e(\(including)f(an)i(implicit)g (close)g(when)g(the)g(object)f(is)i(garbage)d(collected\).)208 282 y(Under)c(U)t FH(N)t(I)t(X)r FN(,)h(the)e(directory)f(entry)h(for)g (the)h(\002le)g(is)h(remo)o(v)o(ed)c(immediately)h(after)i(the)f (\002le)i(is)f(created.)k(Other)c(platforms)e(do)208 382 y(not)j(support)f(this;)j(your)d(code)h(should)g(not)g(rely)g(on)g (a)h(temporary)e(\002le)i(created)f(using)g(this)h(function)e(ha)n (ving)g(or)h(not)h(ha)n(ving)208 482 y(a)e(visible)g(name)g(in)g(the)g (\002le)h(system.)208 614 y(The)k FK(mode)f FN(parameter)g(def)o(aults) h(to)h FJ('w+b')f FN(so)h(that)f(the)h(\002le)g(created)e(can)i(be)f (read)g(and)g(written)g(without)g(being)f(closed.)208 714 y(Binary)g(mode)g(is)h(used)g(so)g(that)g(it)g(beha)n(v)o(es)f (consistently)g(on)g(all)h(platforms)f(without)g(re)o(gard)e(for)j(the) f(data)h(that)g(is)g(stored.)208 814 y FK(b)n(ufsize)20 b FN(def)o(aults)g(to)g FJ(-1)p FN(,)h(meaning)d(that)j(the)f (operating)e(system)i(def)o(ault)g(is)h(used.)208 946 y(The)e FK(dir)r FN(,)i FK(pr)m(e\002x)f FN(and)f FK(suf)o(\002x)h FN(parameters)f(are)h(passed)g(to)h FJ(mkstemp\(\))p FN(.)0 1093 y FD(NamedTemporaryFile)p FJ(\()p FC([)p FK(mode=)p Fn('w+b')p FC([)p FK(,)15 b(b)n(ufsize=)p Fn(-1)p FC([)p FK(,)k(suf)o(\002x)p FC([)p FK(,)h(pr)m(e\002x)p FC([)p FK(,)f(dir)14 b FC(])e(])g(])g(])g(])p FJ(\))208 1193 y FN(This)19 b(function)f(operates)g(e)o(xactly)h(as)h FJ(TemporaryFile\(\))d FN(does,)i(e)o(xcept)g(that)g(the)h(\002le)g(is) g(guaranteed)d(to)j(ha)n(v)o(e)f(a)h(visible)208 1293 y(name)25 b(in)i(the)f(\002le)i(system)e(\(on)i(U)t FH(N)t(I)t(X)r FN(,)h(the)d(directory)f(entry)h(is)h(not)f(unlink)o(ed\).)42 b(That)26 b(name)g(can)g(be)g(retrie)n(v)o(ed)f(from)h(the)208 1392 y FJ(name)19 b FN(member)f(of)i(the)g(\002le)g(object.)k(Whether) 19 b(the)h(name)f(can)h(be)f(used)h(to)g(open)e(the)i(\002le)g(a)h (second)d(time,)i(while)g(the)g(named)208 1492 y(temporary)j(\002le)j (is)g(still)h(open,)e(v)n(aries)h(across)f(platforms)f(\(it)i(can)f(be) h(so)f(used)h(on)h(U)t FH(N)t(I)t(X)r FN(;)i(it)d(cannot)e(on)h(W)m (indo)n(ws)g(NT)h(or)208 1591 y(later\).)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1738 y FD(mkstemp)p FJ(\()p FC([)p FK(suf)o(\002x)p FC([)p FK(,)f(pr)m(e\002x)p FC([)p FK(,)h(dir)r FC([)p FK(,)h(te)n(xt)13 b FC(])f(])g(])g(])p FJ(\))208 1838 y FN(Creates)21 b(a)h(temporary)d(\002le)j(in)f(the)h (most)f(secure)g(manner)f(possible.)28 b(There)20 b(are)h(no)g(race)g (conditions)f(in)h(the)h(\002le')-5 b(s)22 b(creation,)208 1938 y(assuming)j(that)h(the)g(platform)f(properly)e(implements)i(the)i FJ(O_EXCL)e FN(\003ag)h(for)g FJ(os.open\(\))p FN(.)41 b(The)26 b(\002le)g(is)h(readable)e(and)208 2037 y(writable)16 b(only)h(by)g(the)g(creating)f(user)h(ID.)g(If)g(the)h(platform)d(uses) j(permission)e(bits)i(to)f(indicate)g(whether)f(a)i(\002le)g(is)g(e)o (x)o(ecutable,)208 2137 y(the)i(\002le)h(is)g(e)o(x)o(ecutable)d(by)i (no)g(one.)k(The)c(\002le)h(descriptor)d(is)k(not)d(inherited)g(by)h (child)g(processes.)208 2270 y(Unlik)o(e)d FJ(TemporaryFile\(\))p FN(,)e(the)j(user)f(of)h FJ(mkstemp\(\))e FN(is)j(responsible)d(for)h (deleting)g(the)g(temporary)e(\002le)k(when)e(done)208 2369 y(with)j(it.)208 2502 y(If)f FK(suf)o(\002x)g FN(is)i (speci\002ed,)e(the)g(\002le)i(name)d(will)j(end)e(with)g(that)h(suf)n (\002x,)f(otherwise)g(there)g(will)h(be)g(no)f(suf)n(\002x.)24 b FJ(mkstemp\(\))19 b FN(does)208 2602 y(not)g(put)h(a)h(dot)f(between) f(the)h(\002le)h(name)f(and)f(the)i(suf)n(\002x;)e(if)i(you)e(need)h (one,)f(put)h(it)h(at)g(the)f(be)o(ginning)d(of)j FK(suf)o(\002x)p FN(.)208 2735 y(If)g FK(pr)m(e\002x)g FN(is)h(speci\002ed,)e(the)i (\002le)f(name)g(will)h(be)o(gin)e(with)h(that)h(pre\002x;)e (otherwise,)g(a)i(def)o(ault)e(pre\002x)h(is)h(used.)208 2867 y(If)e FK(dir)j FN(is)f(speci\002ed,)e(the)h(\002le)g(will)h(be)e (created)g(in)h(that)g(directory;)e(otherwise,)h(a)h(def)o(ault)f (directory)f(is)j(used.)j(The)c(def)o(ault)f(di-)208 2967 y(rectory)c(is)i(chosen)f(from)g(a)h(platform-dependent)12 b(list,)18 b(b)n(ut)f(the)f(user)h(of)f(the)h(application)e(can)i (control)e(the)i(directory)e(location)208 3067 y(by)25 b(setting)g(the)h FK(TMPDIR)p FN(,)f FK(TEMP)h FN(or)f FK(TMP)h FN(en)m(vironment)d(v)n(ariables.)40 b(There)24 b(is)j(thus)e(no)g(guarantee)f(that)i(the)f(generated)208 3166 y(\002lename)h(will)h(ha)n(v)o(e)f(an)o(y)g(nice)g(properties,)g (such)h(as)g(not)f(requiring)f(quoting)f(when)i(passed)h(to)f(e)o (xternal)g(commands)f(via)208 3266 y FJ(os.popen\(\))p FN(.)208 3399 y(If)i FK(te)n(xt)j FN(is)e(speci\002ed,)h(it)f (indicates)f(whether)g(to)g(open)g(the)g(\002le)h(in)g(binary)e(mode)g (\(the)i(def)o(ault\))e(or)h(te)o(xt)g(mode.)46 b(On)28 b(some)208 3498 y(platforms,)18 b(this)j(mak)o(es)f(no)g(dif)n (ference.)208 3631 y FJ(mkstemp\(\))43 b FN(returns)g(a)i(tuple)e (containing)g(an)h(OS-le)n(v)o(el)g(handle)f(to)h(an)g(open)f(\002le)i (\(as)g(w)o(ould)e(be)i(returned)d(by)208 3731 y FJ(os.open\(\))p FN(\))18 b(and)i(the)g(absolute)g(pathname)e(of)i(that)g(\002le,)h(in)f (that)h(order)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3878 y FD(mkdtemp)p FJ(\()p FC([)p FK(suf)o(\002x)p FC([)p FK(,)f(pr)m(e\002x)p FC([)p FK(,)h(dir)14 b FC(])e(])g(])p FJ(\))208 3977 y FN(Creates)17 b(a)g(temporary)d(directory)h(in)i(the)g (most)g(secure)f(manner)f(possible.)24 b(There)16 b(are)g(no)h(race)f (conditions)f(in)i(the)g(directory')-5 b(s)208 4077 y(creation.)23 b(The)d(directory)f(is)i(readable,)e(writable,)g(and)h(searchable)f (only)g(by)h(the)g(creating)f(user)i(ID.)208 4210 y(The)d(user)i(of)f FJ(mkdtemp\(\))f FN(is)i(responsible)e(for)g(deleting)h(the)g (temporary)e(directory)g(and)i(its)h(contents)f(when)f(done)h(with)g (it.)208 4343 y(The)g FK(pr)m(e\002x)p FN(,)h FK(suf)o(\002x)p FN(,)g(and)f FK(dir)k FN(ar)o(guments)18 b(are)i(the)g(same)h(as)g(for) e FJ(mkstemp\(\))p FN(.)208 4475 y FJ(mkdtemp\(\))g FN(returns)g(the)h (absolute)g(pathname)e(of)i(the)g(ne)n(w)g(directory)-5 b(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.3.)0 4622 y FD(mktemp)p FJ(\()p FC([)p FK(suf)o(\002x)p FC([)p FK(,)g(pr)m(e\002x)p FC([)p FK(,)h(dir)14 b FC(])e(])g(])p FJ(\))208 4722 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)e(2.3.)24 b FN(Use)d FJ(mkstemp\(\))e FN(instead.)208 4855 y(Return)k(an)h (absolute)f(pathname)f(of)h(a)i(\002le)f(that)g(did)g(not)f(e)o(xist)h (at)g(the)g(time)g(the)g(call)g(is)h(made.)35 b(The)24 b FK(pr)m(e\002x)p FN(,)g FK(suf)o(\002x)p FN(,)g(and)f FK(dir)208 4954 y FN(ar)o(guments)18 b(are)i(the)g(same)g(as)h(for)f FJ(mkstemp\(\))p FN(.)208 5087 y FL(W)-5 b(ar)o(ning:)30 b FN(Use)24 b(of)f(this)h(function)d(may)i(introduce)f(a)h(security)g (hole)g(in)g(your)f(program.)33 b(By)23 b(the)h(time)f(you)g(get)g (around)e(to)208 5187 y(doing)d(an)o(ything)h(with)h(the)g(\002le)h (name)f(it)g(returns,)g(someone)e(else)j(may)f(ha)n(v)o(e)g(beaten)f (you)g(to)i(the)f(punch.)p 0 5549 3901 4 v 0 5649 a FI(11.6.)52 b FJ(tempfile)22 b FI(\227)h(Gener)o(ate)g(tempor)o(ar)r(y)h(\002les)e (and)i(director)q(ies)1515 b(335)p eop end %%Page: 336 348 TeXDict begin 336 347 bop 0 83 a FN(The)23 b(module)f(uses)i(tw)o(o)g (global)e(v)n(ariables)h(that)g(tell)i(it)f(ho)n(w)f(to)g(construct)g (a)g(temporary)f(name.)34 b(The)o(y)22 b(are)h(initialized)g(at)h(the)g (\002rst)0 183 y(call)f(to)g(an)o(y)f(of)g(the)g(functions)g(abo)o(v)o (e.)30 b(The)22 b(caller)h(may)f(change)f(them,)i(b)n(ut)f(this)i(is)f (discouraged;)f(use)g(the)h(appropriate)d(function)0 282 y(ar)o(guments,)e(instead.)0 429 y FD(tempdir)208 529 y FN(When)29 b(set)h(to)g(a)f(v)n(alue)g(other)g(than)g FJ(None)p FN(,)i(this)f(v)n(ariable)e(de\002nes)h(the)h(def)o(ault)e(v) n(alue)h(for)g(the)g FK(dir)j FN(ar)o(gument)27 b(to)j(all)g(the)208 628 y(functions)18 b(de\002ned)h(in)i(this)g(module.)208 761 y(If)29 b FJ(tempdir)g FN(is)i(unset)e(or)g FJ(None)h FN(at)g(an)o(y)f(call)h(to)g(an)o(y)e(of)i(the)f(abo)o(v)o(e)f (functions,)j(Python)d(searches)i(a)g(standard)e(list)j(of)208 861 y(directories)19 b(and)g(sets)j FK(tempdir)g FN(to)e(the)g(\002rst) h(one)f(which)f(the)i(calling)e(user)h(can)g(create)g(\002les)h(in.)26 b(The)19 b(list)j(is:)328 1074 y(1.)o(The)e(directory)f(named)g(by)g (the)i(TMPDIR)f(en)m(vironment)d(v)n(ariable.)328 1207 y(2.)o(The)j(directory)f(named)g(by)g(the)i(TEMP)f(en)m(vironment)d(v)n (ariable.)328 1340 y(3.)o(The)j(directory)f(named)g(by)g(the)i(TMP)f (en)m(vironment)d(v)n(ariable.)328 1473 y(4.)o(A)k(platform-speci\002c) d(location:)504 1605 y FM(\017)o FN(On)j(RiscOS,)g(the)f(directory)f (named)g(by)g(the)i(W)m(imp$ScrapDir)d(en)m(vironment)f(v)n(ariable.) 504 1722 y FM(\017)o FN(On)k(W)m(indo)n(ws,)e(the)h(directories)f(`)p FO(C:)p Fk(n)p FO(TEMP)p FN(',)h(`)p FO(C:)p Fk(n)p FO(TMP)p FN(',)g(`)p Fk(n)p FO(TEMP)p FN(',)f(and)h(`)p Fk(n)p FO(TMP)p FN(',)g(in)g(that)h(order)-5 b(.)504 1838 y FM(\017)o FN(On)21 b(all)f(other)g(platforms,)f(the)h(directories)f(`)p FO(/tmp)p FN(',)g(`)p FO(/v)n(ar/tmp)p FN(',)g(and)h(`)p FO(/usr/tmp)p FN(',)e(in)j(that)f(order)-5 b(.)328 1971 y(5.)o(As)21 b(a)g(last)g(resort,)e(the)i(current)e(w)o(orking)f (directory)-5 b(.)0 2137 y FD(gettempdir)p FJ(\(\))208 2236 y FN(Return)16 b(the)h(directory)f(currently)f(selected)i(to)h (create)e(temporary)f(\002les)j(in.)24 b(If)17 b FJ(tempdir)g FN(is)h(not)f FJ(None)p FN(,)g(this)h(simply)e(returns)208 2336 y(its)21 b(contents;)e(otherwise,)h(the)g(search)g(described)e (abo)o(v)o(e)h(is)i(performed,)c(and)j(the)g(result)h(returned.)0 2483 y FD(template)208 2583 y FL(Depr)o(ecated)e(since)i(r)o(elease)e (2.0.)24 b FN(Use)d FJ(gettempprefix\(\))d FN(instead.)208 2715 y(When)25 b(set)h(to)g(a)g(v)n(alue)f(other)g(than)g FJ(None)p FN(,)h(this)g(v)n(ariable)f(de\002nes)g(the)h(pre\002x)e(of)i (the)f(\002nal)h(component)d(of)i(the)h(\002lenames)208 2815 y(returned)17 b(by)h FJ(mktemp\(\))p FN(.)23 b(A)d(string)e(of)h (six)g(random)e(letters)i(and)f(digits)h(is)h(appended)c(to)j(the)g (pre\002x)f(to)h(mak)o(e)f(the)h(\002lename)208 2915 y(unique.)k(On)d(W)m(indo)n(ws,)g(the)g(def)o(ault)f(pre\002x)h(is)h(`) p FO(\230T)p FN(';)e(on)h(all)h(other)e(systems)i(it)g(is)g(`)p FO(tmp)p FN('.)208 3048 y(Older)f(v)o(ersions)h(of)g(this)h(module)d (used)i(to)h(require)e(that)h FJ(template)g FN(be)g(set)h(to)f FJ(None)g FN(after)g(a)h(call)g(to)f FJ(os.fork\(\))p FN(;)g(this)208 3147 y(has)f(not)g(been)f(necessary)h(since)g(v)o (ersion)f(1.5.2.)0 3294 y FD(gettempprefix)p FJ(\(\))208 3394 y FN(Return)g(the)g(\002lename)g(pre\002x)f(used)i(to)f(create)g (temporary)f(\002les.)25 b(This)20 b(does)f(not)g(contain)f(the)i (directory)d(component.)23 b(Using)208 3493 y(this)d(function)f(is)i (preferred)d(o)o(v)o(er)h(reading)f(the)j FK(template)e FN(v)n(ariable)g(directly)-5 b(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d (1.5.2.)0 3821 y FE(11.7)121 b Fx(glob)32 b FE(\227)k FC(U)6 b Fl(N)g(I)g(X)36 b FE(style)d(pathname)j(patter)s(n)g(e)l (xpansion)0 4053 y FN(The)19 b FJ(glob)h FN(module)e(\002nds)i(all)h (the)e(pathnames)g(matching)f(a)i(speci\002ed)g(pattern)f(according)e (to)j(the)g(rules)g(used)f(by)h(the)i(U)t FH(N)t(I)t(X)g FN(shell.)0 4153 y(No)16 b(tilde)h(e)o(xpansion)d(is)k(done,)e(b)n(ut) 1029 4168 y FJ(*)1079 4153 y FN(,)h FJ(?)p FN(,)h(and)e(character)f (ranges)g(e)o(xpressed)g(with)i FJ([])g FN(will)g(be)f(correctly)f (matched.)23 b(This)16 b(is)i(done)d(by)0 4253 y(using)g(the)g FJ(os.listdir\(\))f FN(and)h FJ(fnmatch.fnmatch\(\))d FN(functions)i(in)i(concert,)f(and)g(not)g(by)f(actually)h(in)m(v)n (oking)e(a)j(subshell.)0 4352 y(\(F)o(or)j(tilde)i(and)e(shell)i(v)n (ariable)e(e)o(xpansion,)f(use)i FJ(os.path.expanduser\(\))e FN(and)h FJ(os.path.expandvars\(\))p FN(.\))0 4499 y FD(glob)p FJ(\()p FK(pathname)p FJ(\))208 4599 y FN(Return)d(a)i (possibly-empty)c(list)19 b(of)d(path)h(names)g(that)g(match)g FK(pathname)p FN(,)e(which)i(must)g(be)g(a)h(string)e(containing)g(a)h (path)g(speci-)208 4698 y(\002cation.)23 b FK(pathname)16 b FN(can)i(be)g(either)f(absolute)g(\(lik)o(e)h(`)p FO (/usr/src/Python-1.5/Mak)o(e\002le)p FN('\))13 b(or)18 b(relati)n(v)o(e)f(\(lik)o(e)h(`)p FO(../../T)-9 b(ools/*/*.gif)p FN('\),)208 4798 y(and)19 b(can)h(contain)f(shell-style)h(wildcards.)25 b(Brok)o(en)19 b(symlinks)h(are)g(included)e(in)j(the)f(results)h(\(as) f(in)g(the)h(shell\).)0 4945 y FD(iglob)p FJ(\()p FK(pathname)p FJ(\))208 5045 y FN(Return)j(an)h(iterator)f(which)h(yields)f(the)h (same)h(v)n(alues)e(as)i FJ(glob\(\))e FN(without)g(actually)h(storing) f(them)g(all)i(simultaneously)-5 b(.)208 5144 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 5291 y(F)o(or)28 b(e)o(xample,)i(consider)d (a)i(directory)e(containing)g(only)h(the)h(follo)n(wing)e(\002les:)43 b(`)p FO(1.gif)p FN(',)29 b(`)p FO(2.txt)p FN(',)h(and)e(`)p FO(card.gif)p FN('.)49 b FJ(glob\(\))28 b FN(will)0 5391 y(produce)18 b(the)i(follo)n(wing)f(results.)25 b(Notice)20 b(ho)n(w)g(an)o(y)f(leading)g(components)f(of)i(the)h(path)e(are)h (preserv)o(ed.)p 0 5549 3901 4 v 0 5649 a FI(336)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 337 349 TeXDict begin 337 348 bop 236 174 a FA(>>>)45 b(import)e(glob)236 266 y(>>>)i(glob.glob\('./[0-9].)1271 279 y(*)1316 266 y('\))236 357 y(['./1.gif',)e('./2.txt'])236 448 y(>>>)i(glob.glob\(') 911 461 y(*)956 448 y(.gif'\))236 540 y(['1.gif',)f('card.gif'])236 631 y(>>>)h(glob.glob\('?.gif'\))236 722 y(['1.gif'])0 1009 y FL(See)21 b(Also:)0 1156 y FN(Module)e FJ(fnmatch)g FN(\(section)h(11.8\):)208 1256 y(Shell-style)f(\002lename)h(\(not)g (path\))f(e)o(xpansion)0 1583 y FE(11.8)121 b Fx(fnmatch)32 b FE(\227)j FC(U)6 b Fl(N)g(I)g(X)37 b FE(\002lename)d(patter)s(n)h (matching)0 1816 y FN(This)24 b(module)e(pro)o(vides)h(support)f(for)j (U)t FH(N)t(I)t(X)i FN(shell-style)d(wildcards,)g(which)f(are)h FK(not)f FN(the)h(same)g(as)h(re)o(gular)d(e)o(xpressions)g(\(which)0 1916 y(are)e(documented)e(in)i(the)g FJ(re)h FN(module\).)i(The)d (special)g(characters)f(used)h(in)g(shell-style)h(wildcards)e(are:)1228 2142 y FL(P)o(atter)o(n)p 1541 2172 4 100 v 97 w(Meaning)p 1178 2175 1545 4 v 1335 2260 a FJ(*)p 1541 2275 4 100 v 1592 2245 a FN(matches)h(e)n(v)o(erything)1335 2345 y FJ(?)p 1541 2374 V 207 w FN(matches)g(an)o(y)g(single)g(character) 1255 2444 y FJ([)p FK(seq)p FJ(])p 1541 2474 V 126 w FN(matches)g(an)o(y)g(character)f(in)h FK(seq)1230 2544 y FJ([!)p FK(seq)p FJ(])p 1541 2574 V 101 w FN(matches)g(an)o(y)g (character)f(not)g(in)i FK(seq)0 2769 y FN(Note)32 b(that)f(the)h (\002lename)f(separator)f(\()p FJ('/')h FN(on)j(U)t FH(N)t(I)t(X)r FN(\))e(is)g FK(not)g FN(special)f(to)h(this)g(module.)58 b(See)32 b(module)e FJ(glob)h FN(for)g(pathname)0 2869 y(e)o(xpansion)17 b(\()p FJ(glob)i FN(uses)h FJ(fnmatch\(\))e FN(to)i(match)e(pathname)g(se)o(gments\).)24 b(Similarly)-5 b(,)18 b(\002lenames)h(starting)g(with)h(a)g(period)e(are)h(not)0 2968 y(special)h(for)g(this)h(module,)d(and)i(are)g(matched)f(by)h(the) 1591 2983 y FJ(*)1662 2968 y FN(and)f FJ(?)26 b FN(patterns.)0 3115 y FD(fnmatch)p FJ(\()p FK(\002lename)o(,)17 b(pattern)p FJ(\))208 3215 y FN(T)-6 b(est)26 b(whether)e(the)h FK(\002lename)g FN(string)g(matches)g(the)g FK(pattern)g FN(string,)h(returning)d(true) i(or)g(f)o(alse.)41 b(If)25 b(the)h(operating)d(system)j(is)208 3314 y(case-insensiti)n(v)o(e,)d(then)h(both)f(parameters)g(will)h(be)g (normalized)f(to)h(all)g(lo)n(wer)n(-)g(or)g(upper)n(-case)e(before)h (the)h(comparison)e(is)208 3414 y(performed.)29 b(If)22 b(you)g(require)f(a)i(case-sensiti)n(v)o(e)f(comparison)f(re)o (gardless)g(of)h(whether)g(that')-5 b(s)23 b(standard)e(for)h(your)f (operating)208 3514 y(system,)f(use)g FJ(fnmatchcase\(\))e FN(instead.)208 3646 y(This)i(e)o(xample)f(will)i(print)e(all)i(\002le) g(names)f(in)g(the)g(current)f(directory)g(with)h(the)g(e)o(xtension)f FJ(.txt)p FN(:)444 3871 y FA(import)44 b(fnmatch)444 3962 y(import)g(os)444 4145 y(for)g(file)g(in)h(os.listdir\('.'\):)623 4236 y(if)g(fnmatch.fnmatch\(file,)c(')1789 4249 y(*)1834 4236 y(.txt'\):)802 4327 y(print)j(file)0 4531 y FD(fnmatchcase)p FJ(\()p FK(\002lename)o(,)17 b(pattern)p FJ(\))208 4631 y FN(T)-6 b(est)20 b(whether)g FK(\002lename)f FN(matches)g FK(pattern)p FN(,)h(returning)e(true)i(or)g(f)o(alse;)g(the)h (comparison)d(is)j(case-sensiti)n(v)o(e.)0 4777 y FD(filter)p FJ(\()p FK(names,)d(pattern)p FJ(\))208 4877 y FN(Return)32 b(the)i(subset)f(of)g(the)g(list)i(of)e FK(names)g FN(that)g(match)g FK(pattern)p FN(.)63 b(It)34 b(is)g(the)f(same)h(as)g FJ([n)49 b(for)g(n)h(in)f(names)g(if)208 4977 y(fnmatch\(n,)f (pattern\)])p FN(,)18 b(b)n(ut)j(implemented)d(more)h(ef)n(\002ciently) -5 b(.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 5123 y FD(translate)p FJ(\()p FK(pattern)p FJ(\))208 5223 y FN(Return)g(the)i(shell-style)f FK(pattern)f FN(con)m(v)o(erted)f(to) i(a)h(re)o(gular)d(e)o(xpression.)208 5356 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(11.8.)52 b FJ(fnmatch)22 b FI(\227)j FN(U)t FH(N)t(I)t(X)h FI(\002lename)d(patter)r(n)h (matching)1874 b(337)p eop end %%Page: 338 350 TeXDict begin 338 349 bop 444 174 a FA(>>>)44 b(import)g(fnmatch,)f(re) 444 266 y(>>>)444 357 y(>>>)h(regex)g(=)h(fnmatch.translate\(')1837 370 y(*)1882 357 y(.txt'\))444 448 y(>>>)f(regex)444 540 y('.)534 553 y(*)579 540 y(\\\\.txt$')444 631 y(>>>)g(reobj)g(=)h (re.compile\(regex\))444 722 y(>>>)f(print)g (reobj.match\('foobar.txt'\))444 814 y(<_sre.SRE_Match)e(object)i(at)g (0x...>)0 1018 y FL(See)21 b(Also:)0 1165 y FN(Module)e FJ(glob)h FN(\(section)g(11.7\):)210 1264 y(U)t FH(N)t(I)t(X)j FN(shell-style)d(path)g(e)o(xpansion.)0 1592 y FE(11.9)121 b Fx(linecache)31 b FE(\227)i(Random)i(access)e(to)h(te)l(xt)g(lines)0 1824 y FN(The)25 b FJ(linecache)g FN(module)g(allo)n(ws)h(one)f(to)h (get)g(an)o(y)f(line)h(from)e(an)o(y)i(\002le,)h(while)f(attempting)f (to)h(optimize)e(internally)-5 b(,)26 b(using)f(a)0 1924 y(cache,)h(the)g(common)e(case)i(where)f(man)o(y)g(lines)h(are)g(read)f (from)f(a)j(single)e(\002le.)42 b(This)26 b(is)h(used)e(by)h(the)f FJ(traceback)g FN(module)f(to)0 2024 y(retrie)n(v)o(e)19 b(source)g(lines)i(for)f(inclusion)f(in)h(the)g(formatted)f(traceback.) 0 2171 y(The)h FJ(linecache)f FN(module)g(de\002nes)h(the)g(follo)n (wing)e(functions:)0 2317 y FD(getline)p FJ(\()p FK(\002lename)o(,)f (lineno)p FC([)p FK(,)i(module)p 1260 2317 25 4 v 29 w(globals)12 b FC(])p FJ(\))208 2417 y FN(Get)24 b(line)h FK(lineno)e FN(from)g(\002le)i(named)e FK(\002lename)p FN(.)36 b(This)24 b(function)f(will)i(ne)n(v)o(er)e(thro)n(w)g(an)h(e)o (xception)f(\227)i(it)g(will)f(return)g FJ('')g FN(on)208 2517 y(errors)19 b(\(the)h(terminating)e(ne)n(wline)i(character)f(will) i(be)f(included)f(for)g(lines)i(that)f(are)g(found\).)208 2650 y(If)i(a)g(\002le)h(named)e FK(\002lename)g FN(is)i(not)f(found,)e (the)j(function)d(will)j(look)e(for)h(it)h(in)f(the)g(module)f(search)h (path,)f FJ(sys.path)p FN(,)h(after)208 2749 y(\002rst)f(checking)f (for)g(a)i(PEP)f(302)g FJ(__loader__)e FN(in)j FK(module)p 2025 2749 V 28 w(globals)p FN(,)e(in)h(case)h(the)f(module)f(w)o(as)h (imported)f(from)g(a)h(zip\002le)208 2849 y(or)e(other)h (non-\002lesystem)e(import)i(source.)208 2982 y(Ne)n(w)g(in)g(v)o (ersion)f(2.5:)h(The)g FK(module)p 1281 2982 V 28 w(globals)f FN(parameter)g(w)o(as)i(added.)0 3128 y FD(clearcache)p FJ(\(\))208 3228 y FN(Clear)f(the)g(cache.)25 b(Use)c(this)f(function)f (if)h(you)g(no)f(longer)g(need)h(lines)g(from)f(\002les)j(pre)n (viously)c(read)h(using)h FJ(getline\(\))p FN(.)0 3375 y FD(checkcache)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 3475 y FN(Check)21 b(the)h(cache)g(for)f(v)n(alidity)-5 b(.)30 b(Use)22 b(this)h(function)d(if)i(\002les)h(in)g(the)f(cache)f (may)h(ha)n(v)o(e)f(changed)f(on)i(disk,)g(and)g(you)f(require)208 3574 y(the)f(updated)e(v)o(ersion.)24 b(If)c FK(\002lename)f FN(is)i(omitted,)e(it)i(will)g(check)f(all)g(the)h(entries)f(in)g(the)g (cache.)0 3721 y(Example:)236 3959 y FA(>>>)45 b(import)e(linecache)236 4051 y(>>>)i(linecache.getline\('/etc/passwd',)39 b(4\))236 4142 y('sys:x:3:3:sys:/dev:/bin/sh\\n')0 4652 y FE(11.10)122 b Fx(shutil)31 b FE(\227)i(High-le)l(v)m(el)h(\002le)f(oper)o(ations)0 4885 y FN(The)19 b FJ(shutil)g FN(module)g(of)n(fers)g(a)h(number)e(of) h(high-le)n(v)o(el)e(operations)i(on)g(\002les)h(and)g(collections)f (of)g(\002les.)26 b(In)19 b(particular)m(,)f(functions)0 4984 y(are)i(pro)o(vided)e(which)h(support)g(\002le)i(cop)o(ying)e(and) g(remo)o(v)n(al.)0 5131 y FL(Ca)n(v)o(eat:)24 b FN(On)c(MacOS,)g(the)h (resource)e(fork)g(and)g(other)h(metadata)g(are)g(not)g(used.)25 b(F)o(or)20 b(\002le)h(copies,)e(this)i(means)f(that)g(resources)g (will)0 5231 y(be)g(lost)h(and)e(\002le)i(type)f(and)g(creator)f(codes) h(will)h(not)f(be)g(correct.)0 5378 y FD(copyfile)p FJ(\()p FK(sr)m(c,)f(dst)q FJ(\))p 0 5549 3901 4 v 0 5649 a FI(338)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 339 351 TeXDict begin 339 350 bop 208 83 a FN(Cop)o(y)17 b(the)g(contents)g(of) g(the)h(\002le)g(named)e FK(sr)m(c)j FN(to)f(a)g(\002le)g(named)e FK(dst)q FN(.)25 b(The)17 b(destination)g(location)f(must)i(be)f (writable;)h(otherwise,)208 183 y(an)23 b FJ(IOError)f FN(e)o(xception)f(will)j(be)f(raised.)33 b(If)23 b FK(dst)i FN(already)d(e)o(xists,)i(it)f(will)h(be)f(replaced.)32 b(Special)23 b(\002les)h(such)f(as)h(character)208 282 y(or)19 b(block)h(de)n(vices)f(and)h(pipes)g(cannot)f(be)h(copied)f (with)i(this)f(function.)k FK(sr)m(c)d FN(and)e FK(dst)k FN(are)d(path)f(names)h(gi)n(v)o(en)f(as)i(strings.)0 429 y FD(copyfileobj)p FJ(\()p FK(fsr)m(c,)e(fdst)q FC([)p FK(,)i(length)12 b FC(])p FJ(\))208 529 y FN(Cop)o(y)19 b(the)h(contents)g(of)g(the)g(\002le-lik)o(e)g(object)g FK(fsr)m(c)h FN(to)f(the)g(\002le-lik)o(e)g(object)g FK(fdst)q FN(.)26 b(The)20 b(inte)o(ger)f FK(length)p FN(,)g(if)h(gi)n(v)o(en,)f(is)i(the)f(b)n(uf)n(fer)208 628 y(size.)k(In)16 b(particular)m(,)f(a)i(ne)o(gati)n(v)o(e)d FK(length)i FN(v)n(alue)g(means)g(to)g(cop)o(y)g(the)g(data)g(without)g (looping)f(o)o(v)o(er)g(the)h(source)g(data)g(in)h(chunks;)208 728 y(by)24 b(def)o(ault)g(the)h(data)g(is)g(read)f(in)h(chunks)f(to)h (a)n(v)n(oid)f(uncontrolled)f(memory)g(consumption.)36 b(Note)25 b(that)g(if)g(the)f(current)g(\002le)208 828 y(position)e(of)g(the)h FK(fsr)m(c)h FN(object)e(is)i(not)e(0,)i(only)e (the)g(contents)h(from)e(the)i(current)f(\002le)h(position)f(to)h(the)g (end)f(of)h(the)g(\002le)g(will)h(be)208 927 y(copied.)0 1074 y FD(copymode)p FJ(\()p FK(sr)m(c,)19 b(dst)q FJ(\))208 1174 y FN(Cop)o(y)25 b(the)g(permission)f(bits)i(from)f FK(sr)m(c)h FN(to)g FK(dst)q FN(.)41 b(The)25 b(\002le)h(contents,)g(o) n(wner)m(,)f(and)g(group)e(are)j(unaf)n(fected.)38 b FK(sr)m(c)26 b FN(and)f FK(dst)j FN(are)208 1273 y(path)19 b(names)h(gi)n(v)o(en)f(as)i(strings.)0 1420 y FD(copystat)p FJ(\()p FK(sr)m(c,)e(dst)q FJ(\))208 1520 y FN(Cop)o(y)i(the)h (permission)e(bits,)j(last)f(access)g(time,)g(and)g(last)g (modi\002cation)e(time)i(from)f FK(sr)m(c)h FN(to)g FK(dst)q FN(.)30 b(The)22 b(\002le)g(contents,)f(o)n(wner)m(,)208 1620 y(and)e(group)g(are)h(unaf)n(fected.)j FK(sr)m(c)e FN(and)e FK(dst)j FN(are)f(path)e(names)h(gi)n(v)o(en)f(as)i(strings.)0 1766 y FD(copy)p FJ(\()p FK(sr)m(c,)f(dst)q FJ(\))208 1866 y FN(Cop)o(y)c(the)g(\002le)i FK(sr)m(c)f FN(to)g(the)g(\002le)g (or)f(directory)f FK(dst)q FN(.)25 b(If)16 b FK(dst)j FN(is)e(a)g(directory)-5 b(,)15 b(a)i(\002le)g(with)g(the)g(same)f (basename)g(as)h FK(sr)m(c)h FN(is)f(created)f(\(or)208 1966 y(o)o(v)o(erwritten\))h(in)k(the)f(directory)e(speci\002ed.)25 b(Permission)20 b(bits)g(are)g(copied.)k FK(sr)m(c)d FN(and)f FK(dst)i FN(are)e(path)g(names)g(gi)n(v)o(en)f(as)i(strings.)0 2113 y FD(copy2)p FJ(\()p FK(sr)m(c,)f(dst)q FJ(\))208 2212 y FN(Similar)26 b(to)g FJ(copy\(\))p FN(,)h(b)n(ut)f(last)h (access)g(time)f(and)g(last)h(modi\002cation)e(time)h(are)g(copied)f (as)i(well.)43 b(This)27 b(is)g(similar)f(to)h(the)210 2312 y(U)t FH(N)t(I)t(X)c FN(command)18 b FL(cp)j(-p)p FN(.)0 2459 y FD(copytree)p FJ(\()p FK(sr)m(c,)e(dst)q FC([)p FK(,)i(symlinks)12 b FC(])p FJ(\))208 2558 y FN(Recursi)n(v)o (ely)k(cop)o(y)g(an)h(entire)g(directory)f(tree)h(rooted)f(at)i FK(sr)m(c)p FN(.)25 b(The)17 b(destination)f(directory)-5 b(,)16 b(named)g(by)h FK(dst)q FN(,)h(must)g(not)f(already)208 2658 y(e)o(xist;)g(it)g(will)g(be)f(created)g(as)h(well)g(as)f(missing) h(parent)e(directories.)22 b(Permissions)17 b(and)e(times)i(of)f (directories)f(are)h(copied)f(with)208 2758 y FJ(copystat\(\))p FN(,)i(indi)n(vidual)f(\002les)j(are)g(copied)e(using)h FJ(copy2\(\))p FN(.)23 b(If)18 b FK(symlinks)h FN(is)g(true,)g (symbolic)e(links)h(in)h(the)f(source)g(tree)208 2857 y(are)k(represented)e(as)j(symbolic)e(links)h(in)h(the)f(ne)n(w)g (tree;)h(if)g(f)o(alse)f(or)g(omitted,)g(the)g(contents)g(of)g(the)g (link)o(ed)f(\002les)j(are)e(copied)208 2957 y(to)e(the)g(ne)n(w)g (tree.)25 b(If)20 b(e)o(xception\(s\))e(occur)m(,)h(an)h FJ(Error)g FN(is)h(raised)f(with)g(a)h(list)g(of)f(reasons.)208 3090 y(The)f(source)h(code)f(for)h(this)h(should)e(be)h(considered)e (an)i(e)o(xample)f(rather)h(than)f(a)i(tool.)208 3222 y(Changed)14 b(in)j(v)o(ersion)e(2.3:)g FJ(Error)h FN(is)h(raised)f(if) h(an)o(y)e(e)o(xceptions)g(occur)g(during)f(cop)o(ying,)h(rather)h (than)f(printing)g(a)i(message.)208 3355 y(Changed)j(in)i(v)o(ersion)e (2.5:)i(Create)g(intermediate)e(directories)h(needed)f(to)i(create)g FK(dst)q FN(,)h(rather)e(than)g(raising)g(an)h(error)-5 b(.)29 b(Cop)o(y)208 3455 y(permissions)19 b(and)h(times)g(of)g (directories)f(using)h FJ(copystat\(\))p FN(.)0 3602 y FD(rmtree)p FJ(\()p FK(path)p FC([)p FK(,)e(ignor)m(e)p 798 3602 25 4 v 28 w(err)l(or)o(s)p FC([)p FK(,)k(onerr)l(or)14 b FC(])e(])p FJ(\))208 3701 y FN(Delete)26 b(an)g(entire)g(directory)f (tree)h(\()p FK(path)f FN(must)h(point)g(to)g(a)h(directory\).)41 b(If)26 b FK(ignor)m(e)p 2687 3701 V 29 w(err)l(or)o(s)h FN(is)h(true,)f(errors)e(resulting)h(from)208 3801 y(f)o(ailed)f(remo)o (v)n(als)g(will)i(be)f(ignored;)i(if)e(f)o(alse)h(or)f(omitted,)g(such) g(errors)g(are)g(handled)e(by)i(calling)g(a)g(handler)f(speci\002ed)h (by)208 3901 y FK(onerr)l(or)c FN(or)m(,)d(if)i(that)f(is)h(omitted,)e (the)o(y)h(raise)g(an)g(e)o(xception.)208 4033 y(If)h FK(onerr)l(or)i FN(is)f(pro)o(vided,)d(it)j(must)g(be)f(a)h(callable)f (that)h(accepts)f(three)g(parameters:)26 b FK(function)p FN(,)20 b FK(path)p FN(,)h(and)g FK(e)n(xcinfo)p FN(.)28 b(The)21 b(\002rst)208 4133 y(parameter)m(,)k FK(function)p FN(,)g(is)i(the)f(function)e(which)h(raised)h(the)f(e)o(xception;)i(it) g(will)f(be)g FJ(os.listdir\(\))p FN(,)f FJ(os.remove\(\))208 4233 y FN(or)c FJ(os.rmdir\(\))p FN(.)30 b(The)21 b(second)h(parameter) m(,)e FK(path)p FN(,)i(will)h(be)f(the)g(path)f(name)h(passed)g(to)g FK(function)p FN(.)29 b(The)22 b(third)g(parameter)m(,)208 4332 y FK(e)n(xcinfo)p FN(,)c(will)h(be)f(the)g(e)o(xception)e (information)g(return)h(by)h FJ(sys.exc_info\(\))p FN(.)k(Exceptions)17 b(raised)h(by)g FK(onerr)l(or)i FN(will)f(not)208 4432 y(be)h(caught.)0 4579 y FD(move)p FJ(\()p FK(sr)m(c,)g(dst)q FJ(\))208 4678 y FN(Recursi)n(v)o(ely)f(mo)o(v)o(e)f(a)j(\002le)g(or)f (directory)e(to)j(another)d(location.)208 4811 y(If)j(the)i (destination)e(is)i(on)e(our)h(current)e(\002lesystem,)j(then)e(simply) h(use)h(rename.)29 b(Otherwise,)22 b(cop)o(y)f(src)i(to)f(the)g(dst)h (and)e(then)208 4911 y(remo)o(v)o(e)d(src.)208 5044 y(Ne)n(w)i(in)g(v)o (ersion)f(2.3.)0 5191 y FL(exception)g FD(Error)208 5290 y FN(This)32 b(e)o(xception)f(collects)i(e)o(xceptions)d(that)j(raised) f(during)f(a)i(mult-\002le)f(operation.)60 b(F)o(or)33 b FJ(copytree)p FN(,)h(the)e(e)o(xception)208 5390 y(ar)o(gument)17 b(is)22 b(a)e(list)h(of)f(3-tuples)g(\()p FK(sr)m(cname)p FN(,)f FK(dstname)p FN(,)g FK(e)n(xception)p FN(\).)p 0 5549 3901 4 v 0 5649 a FI(11.10.)52 b FJ(shutil)22 b FI(\227)h(High-le)n(v)n(el)h(\002le)f(oper)o(ations)2149 b(339)p eop end %%Page: 340 352 TeXDict begin 340 351 bop 208 83 a FN(Ne)n(w)20 b(in)g(v)o(ersion)f (2.3.)0 368 y Fv(11.10.1)101 b(Example)0 571 y FN(This)26 b(e)o(xample)e(is)i(the)g(implementation)d(of)j(the)f FJ(copytree\(\))f FN(function,)h(described)g(abo)o(v)o(e,)g(with)g(the) h(docstring)e(omitted.)40 b(It)0 670 y(demonstrates)19 b(man)o(y)g(of)h(the)g(other)f(functions)g(pro)o(vided)f(by)i(this)g (module.)236 909 y FA(def)45 b(copytree\(src,)d(dst,)i(symlinks=0\):) 416 1000 y(names)g(=)g(os.listdir\(src\))416 1091 y(os.mkdir\(dst\))416 1183 y(for)g(name)g(in)h(names:)595 1274 y(srcname)f(=)g (os.path.join\(src,)e(name\))595 1365 y(dstname)i(=)g (os.path.join\(dst,)e(name\))595 1457 y(try:)774 1548 y(if)j(symlinks)e(and)i(os.path.islink\(srcname\):)954 1639 y(linkto)e(=)i(os.readlink\(srcname\))954 1731 y (os.symlink\(linkto,)c(dstname\))774 1822 y(elif)j (os.path.isdir\(srcname\):)954 1913 y(copytree\(srcname,)e(dstname,)h (symlinks\))774 2005 y(else:)954 2096 y(copy2\(srcname,)f(dstname\))595 2187 y(except)i(\(IOError,)f(os.error\),)g(why:)774 2279 y(print)h("Can't)g(copy)g(\045s)h(to)f(\045s:)g(\045s")h(\045)f (\(`srcname`,)f(`dstname`,)h(str\(why\)\))0 2789 y FE(11.11)122 b Fx(dircache)31 b FE(\227)i(Cached)i(director)t(y)e(listings)0 3021 y FN(The)25 b FJ(dircache)f FN(module)g(de\002nes)h(a)h(function)e (for)g(reading)g(directory)g(listing)h(using)g(a)h(cache,)f(and)g (cache)g(in)m(v)n(alidation)e(using)0 3121 y(the)d FK(mtime)h FN(of)f(the)g(directory)-5 b(.)23 b(Additionally)-5 b(,)18 b(it)j(de\002nes)f(a)g(function)f(to)h(annotate)f(directories)g(by)h (appending)e(a)i(slash.)0 3268 y(The)g FJ(dircache)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f(functions:)0 3415 y FD(reset)p FJ(\(\))208 3514 y FN(Resets)i(the)f(directory)f (cache.)0 3661 y FD(listdir)p FJ(\()p FK(path)p FJ(\))208 3761 y FN(Return)h(a)i(directory)d(listing)i(of)g FK(path)p FN(,)f(as)i(gotten)e(from)g FJ(os.listdir\(\))p FN(.)26 b(Note)21 b(that)g(unless)g FK(path)g FN(changes,)f(further)f(call)208 3861 y(to)h FJ(listdir\(\))f FN(will)i(not)f(re-read)f(the)h(directory) e(structure.)208 3993 y(Note)j(that)g(the)h(list)g(returned)e(should)g (be)h(re)o(garded)e(as)j(read-only)-5 b(.)26 b(\(Perhaps)20 b(a)i(future)e(v)o(ersion)g(should)g(change)g(it)i(to)g(return)208 4093 y(a)e(tuple?\))0 4240 y FD(opendir)p FJ(\()p FK(path)p FJ(\))208 4339 y FN(Same)g(as)h FJ(listdir\(\))p FN(.)j(De\002ned)19 b(for)h(backw)o(ards)f(compatibility)-5 b(.)0 4486 y FD(annotate)p FJ(\()p FK(head,)17 b(list)q FJ(\))208 4586 y FN(Assume)g FK(list)k FN(is)e(a)f(list)h(of)e(paths)h(relati)n (v)o(e)f(to)h FK(head)r FN(,)f(and)g(append,)g(in)h(place,)g(a)g(`)p FJ(/)p FN(')f(to)h(each)g(path)f(which)g(points)h(to)g(a)g(directory)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(340)2333 b(Chapter)23 b(11.)52 b(File)24 b(and)g(Director)r(y)e(Access)p eop end %%Page: 341 353 TeXDict begin 341 352 bop 236 174 a FA(>>>)45 b(import)e(dircache)236 266 y(>>>)i(a)f(=)h(dircache.listdir\('/'\))236 357 y(>>>)g(a)f(=)h (a[:])f(#)h(Copy)f(the)g(return)g(value)g(so)g(we)h(can)f(change)g('a') 236 448 y(>>>)h(a)236 540 y(['bin',)f('boot',)g('cdrom',)f('dev',)h ('etc',)g('floppy',)f('home',)h('initrd',)f('lib',)h('lost+)236 631 y(found',)g('mnt',)g('proc',)f('root',)h('sbin',)g('tmp',)f('usr',) h('var',)g('vmlinuz'])236 722 y(>>>)h(dircache.annotate\('/',)c(a\))236 814 y(>>>)k(a)236 905 y(['bin/',)f('boot/',)f('cdrom/',)h('dev/',)f ('etc/',)h('floppy/',)f('home/',)g('initrd/',)h('lib/)236 996 y(',)h('lost+found/',)d('mnt/',)i('proc/',)f('root/',)h('sbin/',)f ('tmp/',)h('usr/',)g('var/',)f('vm)236 1088 y(linuz'])p 0 5549 3901 4 v 0 5649 a FI(11.11.)52 b FJ(dircache)22 b FI(\227)h(Cached)g(director)r(y)g(listings)2046 b(341)p eop end %%Page: 342 354 TeXDict begin 342 353 bop 0 5549 3901 4 v 0 5649 a FI(342)p eop end %%Page: 343 355 TeXDict begin 343 354 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3415 427 y FG(TWEL)-13 b(VE)p 0 515 V 881 978 a FT(Data)58 b(Compression)f(and)g(Archiving)0 1468 y FN(The)27 b(modules)f (described)g(in)h(this)h(chapter)e(support)f(data)i(compression)f(with) h(the)g(zlib,)i(gzip,)f(and)e(bzip2)h(algorithms,)g(and)g(the)0 1568 y(creation)19 b(of)h(ZIP-)g(and)g(tar)n(-format)e(archi)n(v)o(es.) 50 1694 y FD(zlib)248 b FN(Lo)n(w-le)n(v)o(el)19 b(interf)o(ace)g(to)h (compression)f(and)g(decompression)f(routines)i(compatible)e(with)j FL(gzip)p FN(.)50 1794 y FD(gzip)248 b FN(Interf)o(aces)19 b(for)h FL(gzip)g FN(compression)f(and)g(decompression)f(using)i (\002le)h(objects.)50 1893 y FD(bz2)298 b FN(Interf)o(ace)19 b(to)h(compression)f(and)g(decompression)f(routines)h(compatible)g (with)i FL(bzip2)p FN(.)50 1993 y FD(zipfile)98 b FN(Read)20 b(and)g(write)g(ZIP-format)f(archi)n(v)o(e)g(\002les.)50 2092 y FD(tarfile)98 b FN(Read)20 b(and)g(write)g(tar)n(-format)f (archi)n(v)o(e)g(\002les.)0 2397 y FE(12.1)121 b Fx(zlib)32 b FE(\227)h(Compression)i(compatib)n(le)e(with)h Fj(gzip)0 2630 y FN(F)o(or)25 b(applications)f(that)h(require)f(data)h (compression,)f(the)i(functions)d(in)j(this)f(module)f(allo)n(w)h (compression)f(and)g(decompression,)0 2729 y(using)19 b(the)h(zlib)g(library)-5 b(.)23 b(The)c(zlib)h(library)f(has)g(its)i (o)n(wn)e(home)g(page)g(at)h FO(http://www)l(.zlib)m(.net)-5 b FN(.)25 b(There)19 b(are)h(kno)n(wn)e(incompatibilities)0 2829 y(between)h(the)i(Python)e(module)g(and)g(v)o(ersions)g(of)h(the)h (zlib)f(library)f(earlier)h(than)g(1.1.3;)f(1.1.3)f(has)j(a)g(security) e(vulnerability)-5 b(,)18 b(so)i(we)0 2928 y(recommend)e(using)h(1.1.4) g(or)h(later)-5 b(.)0 3075 y(zlib')g(s)33 b(functions)e(ha)n(v)o(e)h (man)o(y)f(options)h(and)g(often)g(need)f(to)i(be)g(used)f(in)h(a)f (particular)g(order)-5 b(.)61 b(This)33 b(documentation)c(doesn')o(t)0 3175 y(attempt)d(to)h(co)o(v)o(er)e(all)j(of)e(the)h(permutations;)h (consult)e(the)h(zlib)g(manual)e(at)j FO(http://www)l(.zlib)m(.net/man) n(ual)o(.ht)o(ml)22 b FN(for)k(authoritati)n(v)o(e)0 3275 y(information.)0 3421 y(The)20 b(a)n(v)n(ailable)g(e)o(xception)e (and)i(functions)e(in)j(this)f(module)f(are:)0 3568 y FL(exception)g FD(error)208 3668 y FN(Exception)f(raised)i(on)g (compression)e(and)i(decompression)e(errors.)0 3815 y FD(adler32)p FJ(\()p FK(string)p FC([)p FK(,)h(value)12 b FC(])p FJ(\))208 3914 y FN(Computes)20 b(a)i(Adler)n(-32)d(checksum)h (of)h FK(string)p FN(.)28 b(\(An)21 b(Adler)n(-32)f(checksum)f(is)j (almost)g(as)g(reliable)e(as)i(a)g(CRC32)g(b)n(ut)f(can)g(be)208 4014 y(computed)g(much)i(more)f(quickly)-5 b(.\))33 b(If)23 b FK(value)g FN(is)h(present,)g(it)g(is)g(used)g(as)g(the)f(starting)g (v)n(alue)g(of)g(the)h(checksum;)f(otherwise,)208 4114 y(a)29 b(\002x)o(ed)g(def)o(ault)g(v)n(alue)f(is)j(used.)52 b(This)29 b(allo)n(ws)h(computing)d(a)j(running)d(checksum)h(o)o(v)o (er)g(the)h(concatenation)e(of)i(se)n(v)o(eral)208 4213 y(input)18 b(strings.)25 b(The)19 b(algorithm)f(is)i(not)f (cryptographically)d(strong,)i(and)h(should)g(not)g(be)g(used)g(for)g (authentication)f(or)h(digital)208 4313 y(signatures.)k(Since)17 b(the)g(algorithm)f(is)i(designed)e(for)g(use)i(as)g(a)f(checksum)f (algorithm,)g(it)i(is)g(not)f(suitable)g(for)g(use)g(as)h(a)g(general) 208 4413 y(hash)h(algorithm.)0 4559 y FD(compress)p FJ(\()p FK(string)p FC([)p FK(,)f(le)o(vel)12 b FC(])p FJ(\))208 4659 y FN(Compresses)27 b(the)g(data)g(in)h FK(string)p FN(,)h(returning)c(a)j(string)f(contained)f(compressed)g(data.)46 b FK(le)o(vel)28 b FN(is)g(an)f(inte)o(ger)g(from)f FJ(1)i FN(to)f FJ(9)208 4759 y FN(controlling)18 b(the)i(le)n(v)o(el)g(of)g (compression;)f FJ(1)h FN(is)i(f)o(astest)f(and)f(produces)e(the)i (least)h(compression,)e FJ(9)h FN(is)i(slo)n(west)f(and)e(produces)208 4858 y(the)h(most.)25 b(The)20 b(def)o(ault)f(v)n(alue)h(is)h FJ(6)p FN(.)k(Raises)d(the)e FJ(error)g FN(e)o(xception)e(if)i(an)o(y)g (error)f(occurs.)0 5005 y FD(compressobj)p FJ(\()p FC([)p FK(le)o(vel)12 b FC(])p FJ(\))208 5105 y FN(Returns)19 b(a)h(compression)e(object,)g(to)i(be)f(used)h(for)e(compressing)g (data)i(streams)f(that)h(w)o(on')o(t)e(\002t)j(into)e(memory)f(at)i (once.)k FK(le)o(vel)208 5204 y FN(is)f(an)f(inte)o(ger)g(from)f FJ(1)i FN(to)f FJ(9)h FN(controlling)d(the)j(le)n(v)o(el)f(of)g (compression;)g FJ(1)h FN(is)g(f)o(astest)g(and)f(produces)f(the)h (least)i(compression,)208 5304 y FJ(9)c FN(is)h(slo)n(west)g(and)f (produces)e(the)i(most.)25 b(The)20 b(def)o(ault)g(v)n(alue)f(is)i FJ(6)p FN(.)p 0 5549 3901 4 v 3762 5649 a FI(343)p eop end %%Page: 344 356 TeXDict begin 344 355 bop 0 83 a FD(crc32)p FJ(\()p FK(string)p FC([)p FK(,)19 b(value)12 b FC(])p FJ(\))208 183 y FN(Computes)21 b(a)h(CRC)i(\(Cyclic)e(Redundanc)o(y)d(Check\))i(checksum)g(of)h FK(string)p FN(.)30 b(If)22 b FK(value)g FN(is)g(present,)g(it)h(is)g (used)e(as)i(the)f(starting)208 282 y(v)n(alue)17 b(of)g(the)h (checksum;)f(otherwise,)g(a)h(\002x)o(ed)f(def)o(ault)g(v)n(alue)g(is)i (used.)24 b(This)18 b(allo)n(ws)g(computing)d(a)j(running)e(checksum)g (o)o(v)o(er)208 382 y(the)i(concatenation)e(of)i(se)n(v)o(eral)g(input) g(strings.)24 b(The)18 b(algorithm)f(is)j(not)e(cryptographically)c (strong,)k(and)g(should)f(not)h(be)h(used)208 482 y(for)k (authentication)f(or)i(digital)g(signatures.)37 b(Since)24 b(the)h(algorithm)d(is)j(designed)e(for)h(use)h(as)g(a)f(checksum)f (algorithm,)h(it)h(is)208 581 y(not)19 b(suitable)h(for)g(use)g(as)h(a) g(general)e(hash)h(algorithm.)0 728 y FD(decompress)p FJ(\()p FK(string)p FC([)p FK(,)e(wbits)p FC([)p FK(,)j(b)n(ufsize)12 b FC(])g(])p FJ(\))208 828 y FN(Decompresses)28 b(the)h(data)g(in)g FK(string)p FN(,)j(returning)27 b(a)j(string)e(containing)g(the)h (uncompressed)d(data.)52 b(The)29 b FK(wbits)h FN(parameter)208 927 y(controls)17 b(the)i(size)h(of)e(the)h(windo)n(w)f(b)n(uf)n(fer)-5 b(.)24 b(If)19 b FK(b)n(ufsize)g FN(is)h(gi)n(v)o(en,)d(it)j(is)g(used) e(as)i(the)f(initial)g(size)h(of)e(the)h(output)f(b)n(uf)n(fer)-5 b(.)23 b(Raises)208 1027 y(the)d FJ(error)g FN(e)o(xception)e(if)i(an)o (y)g(error)f(occurs.)208 1160 y(The)h(absolute)h(v)n(alue)g(of)g FK(wbits)h FN(is)g(the)f(base)h(tw)o(o)f(logarithm)e(of)i(the)h(size)g (of)f(the)g(history)f(b)n(uf)n(fer)g(\(the)h(\223windo)n(w)f (size\224\))i(used)208 1259 y(when)f(compressing)g(data.)31 b(Its)22 b(absolute)g(v)n(alue)g(should)f(be)h(between)f(8)i(and)e(15)h (for)g(the)g(most)g(recent)g(v)o(ersions)f(of)h(the)g(zlib)208 1359 y(library)-5 b(,)18 b(lar)o(ger)h(v)n(alues)h(resulting)g(in)g (better)g(compression)f(at)h(the)h(e)o(xpense)e(of)h(greater)f(memory)g (usage.)25 b(The)20 b(def)o(ault)f(v)n(alue)208 1459 y(is)25 b(15.)38 b(When)24 b FK(wbits)i FN(is)f(ne)o(gati)n(v)o(e,)e (the)i(standard)e FL(gzip)i FN(header)e(is)j(suppressed;)g(this)f(is)g (an)g(undocumented)c(feature)i(of)i(the)208 1558 y(zlib)20 b(library)-5 b(,)18 b(used)i(for)g(compatibility)e(with)j FL(unzip)p FN(')-5 b(s)21 b(compression)e(\002le)i(format.)208 1691 y FK(b)n(ufsize)g FN(is)g(the)g(initial)g(size)g(of)f(the)g(b)n (uf)n(fer)g(used)g(to)h(hold)e(decompressed)g(data.)26 b(If)20 b(more)g(space)g(is)i(required,)c(the)j(b)n(uf)n(fer)e(size)208 1791 y(will)h(be)g(increased)f(as)h(needed,)e(so)i(you)f(don')o(t)f(ha) n(v)o(e)h(to)h(get)g(this)g(v)n(alue)f(e)o(xactly)g(right;)h(tuning)e (it)j(will)f(only)f(sa)n(v)o(e)h(a)g(fe)n(w)g(calls)208 1890 y(to)g FJ(malloc\(\))p FN(.)k(The)c(def)o(ault)f(size)i(is)g (16384.)0 2037 y FD(decompressobj)p FJ(\()p FC([)p FK(wbits)12 b FC(])p FJ(\))208 2137 y FN(Returns)20 b(a)i(decompression)c(object,)i (to)i(be)e(used)h(for)f(decompressing)f(data)i(streams)g(that)g(w)o (on')o(t)f(\002t)h(into)g(memory)e(at)i(once.)208 2236 y(The)e FK(wbits)j FN(parameter)c(controls)h(the)i(size)f(of)g(the)h (windo)n(w)e(b)n(uf)n(fer)-5 b(.)0 2383 y(Compression)19 b(objects)h(support)f(the)h(follo)n(wing)e(methods:)0 2530 y FD(compress)p FJ(\()p FK(string)p FJ(\))208 2630 y FN(Compress)k FK(string)p FN(,)h(returning)d(a)j(string)f(containing) e(compressed)h(data)h(for)g(at)h(least)g(part)f(of)g(the)h(data)f(in)g FK(string)p FN(.)32 b(This)23 b(data)208 2729 y(should)16 b(be)i(concatenated)d(to)j(the)g(output)e(produced)f(by)i(an)o(y)g (preceding)e(calls)k(to)e(the)h FJ(compress\(\))e FN(method.)23 b(Some)17 b(input)208 2829 y(may)i(be)h(k)o(ept)g(in)h(internal)e(b)n (uf)n(fers)g(for)h(later)g(processing.)0 2976 y FD(flush)p FJ(\()p FC([)p FK(mode)12 b FC(])p FJ(\))208 3076 y FN(All)22 b(pending)d(input)i(is)h(processed,)e(and)h(a)h(string)f(containing)e (the)j(remaining)d(compressed)h(output)g(is)i(returned.)27 b FK(mode)21 b FN(can)208 3175 y(be)f(selected)g(from)f(the)i (constants)f FJ(Z_SYNC_FLUSH)p FN(,)e FJ(Z_FULL_FLUSH)p FN(,)g(or)i FJ(Z_FINISH)p FN(,)g(def)o(aulting)e(to)j FJ(Z_FINISH)p FN(.)208 3275 y FJ(Z_SYNC_FLUSH)g FN(and)i FJ(Z_FULL_FLUSH)e FN(allo)n(w)j(compressing)d(further)h(strings)h(of)g (data,)h(while)f FJ(Z_FINISH)f FN(\002nishes)208 3374 y(the)29 b(compressed)f(stream)i(and)f(pre)n(v)o(ents)f(compressing)g (an)o(y)h(more)g(data.)53 b(After)30 b(calling)f FJ(flush\(\))g FN(with)h FK(mode)f FN(set)h(to)208 3474 y FJ(Z_FINISH)p FN(,)19 b(the)h FJ(compress\(\))f FN(method)f(cannot)i(be)g(called)g (again;)f(the)h(only)g(realistic)g(action)g(is)h(to)f(delete)g(the)g (object.)0 3621 y FD(copy)p FJ(\(\))208 3721 y FN(Returns)25 b(a)h(cop)o(y)f(of)h(the)g(compression)e(object.)41 b(This)26 b(can)g(be)f(used)h(to)g(ef)n(\002ciently)f(compress)g(a)h(set)g(of)g (data)g(that)g(share)f(a)208 3820 y(common)18 b(initial)i(pre\002x.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 3967 y(Decompression)f(objects)i (support)f(the)h(follo)n(wing)f(methods,)g(and)g(tw)o(o)i(attrib)n (utes:)0 4114 y FD(unused_data)208 4214 y FN(A)j(string)h(which)e (contains)h(an)o(y)g(bytes)g(past)h(the)f(end)g(of)g(the)g(compressed)f (data.)38 b(That)24 b(is,)i(this)f(remains)e FJ("")i FN(until)f(the)h(last)208 4313 y(byte)20 b(that)h(contains)f (compression)f(data)i(is)h(a)n(v)n(ailable.)k(If)21 b(the)g(whole)f (string)h(turned)e(out)i(to)g(contain)f(compressed)f(data,)i(this)208 4413 y(is)g FJ("")p FN(,)f(the)g(empty)f(string.)208 4546 y(The)g(only)g(w)o(ay)h(to)h(determine)d(where)i(a)g(string)g(of)f (compressed)g(data)h(ends)g(is)g(by)g(actually)g(decompressing)d(it.)26 b(This)20 b(means)208 4645 y(that)h(when)g(compressed)f(data)h(is)h (contained)e(part)h(of)g(a)h(lar)o(ger)e(\002le,)i(you)e(can)h(only)g (\002nd)g(the)g(end)g(of)g(it)h(by)f(reading)f(data)h(and)208 4745 y(feeding)j(it)j(follo)n(wed)e(by)h(some)g(non-empty)d(string)j (into)g(a)g(decompression)e(object')-5 b(s)26 b FJ(decompress)f FN(method)g(until)h(the)208 4845 y FJ(unused_data)18 b FN(attrib)n(ute)i(is)h(no)f(longer)f(the)h(empty)f(string.)0 4991 y FD(unconsumed_tail)208 5091 y FN(A)25 b(string)f(that)h (contains)f(an)o(y)g(data)g(that)h(w)o(as)g(not)g(consumed)e(by)h(the)g (last)i FJ(decompress)d FN(call)i(because)f(it)i(e)o(xceeded)d(the)208 5191 y(limit)d(for)g(the)g(uncompressed)e(data)i(b)n(uf)n(fer)-5 b(.)25 b(This)20 b(data)g(has)h(not)f(yet)g(been)g(seen)g(by)g(the)h (zlib)f(machinery)-5 b(,)18 b(so)i(you)g(must)g(feed)208 5290 y(it)g(\(possibly)e(with)h(further)f(data)h(concatenated)f(to)h (it\))h(back)f(to)g(a)h(subsequent)e FJ(decompress)g FN(method)g(call)h(in)h(order)e(to)i(get)208 5390 y(correct)f(output.)p 0 5549 3901 4 v 0 5649 a FI(344)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 345 357 TeXDict begin 345 356 bop 0 83 a FD(decompress)p FJ(\()p FK(string)p FC([)p FK(,)18 b(max)p 967 83 25 4 v 29 w(length)12 b FC(])p FJ(\))208 183 y FN(Decompress)35 b FK(string)p FN(,)41 b(returning)34 b(a)j(string)f(containing)e(the)j(uncompressed)d (data)i(corresponding)d(to)k(at)g(least)g(part)f(of)208 282 y(the)c(data)g(in)g FK(string)p FN(.)62 b(This)32 b(data)g(should)g(be)g(concatenated)e(to)j(the)f(output)f(produced)f (by)h(an)o(y)h(preceding)e(calls)j(to)g(the)208 382 y FJ(decompress\(\))18 b FN(method.)24 b(Some)c(of)f(the)i(input)e(data)h (may)g(be)g(preserv)o(ed)e(in)j(internal)e(b)n(uf)n(fers)g(for)h(later) g(processing.)208 514 y(If)34 b(the)g(optional)f(parameter)g FK(max)p 1252 514 V 29 w(length)g FN(is)i(supplied)e(then)h(the)g (return)f(v)n(alue)h(will)h(be)f(no)g(longer)f(than)g FK(max)p 3647 514 V 30 w(length)p FN(.)208 614 y(This)c(may)g(mean)g (that)g(not)g(all)h(of)f(the)g(compressed)f(input)h(can)g(be)g (processed;)k(and)c(unconsumed)e(data)i(will)h(be)f(stored)208 713 y(in)f(the)h(attrib)n(ute)g FJ(unconsumed_tail)p FN(.)48 b(This)29 b(string)f(must)h(be)g(passed)g(to)g(a)g(subsequent)e (call)i(to)g FJ(decompress\(\))208 813 y FN(if)j(decompression)e(is)j (to)g(continue.)60 b(If)32 b FK(max)p 1609 813 V 29 w(length)g FN(is)h(not)f(supplied)f(then)h(the)g(whole)g(input)g(is)h (decompressed,)g(and)208 913 y FJ(unconsumed_tail)18 b FN(is)j(an)f(empty)f(string.)0 1059 y FD(flush)p FJ(\()p FC([)p FK(length)12 b FC(])p FJ(\))208 1159 y FN(All)25 b(pending)e(input)h(is)i(processed,)e(and)g(a)h(string)g(containing)e (the)i(remaining)d(uncompressed)h(output)g(is)j(returned.)37 b(After)208 1259 y(calling)18 b FJ(flush\(\))p FN(,)g(the)h FJ(decompress\(\))f FN(method)f(cannot)h(be)h(called)g(again;)g(the)g (only)f(realistic)h(action)g(is)h(to)f(delete)g(the)208 1358 y(object.)208 1490 y(The)g(optional)g(parameter)g FK(length)g FN(sets)j(the)e(initial)g(size)h(of)f(the)g(output)f(b)n (uf)n(fer)-5 b(.)0 1637 y FD(copy)p FJ(\(\))208 1737 y FN(Returns)25 b(a)h(cop)o(y)f(of)h(the)f(decompression)f(object.)41 b(This)26 b(can)f(be)h(used)g(to)f(sa)n(v)o(e)h(the)g(state)h(of)e(the) h(decompressor)d(midw)o(ay)208 1837 y(through)16 b(the)j(data)g(stream) f(in)h(order)f(to)h(speed)f(up)h(random)e(seeks)i(into)f(the)h(stream)g (at)g(a)g(future)f(point.)49 b(Ne)n(w)19 b(in)g(v)o(ersion)e(2.5.)0 1983 y FL(See)k(Also:)0 2130 y FN(Module)e FJ(gzip)h FN(\(section)g(12.2\):)208 2230 y(Reading)f(and)h(writing)f FL(gzip)p FN(-format)g(\002les.)0 2377 y FO(http://www)l(.zlib)m(.net) 208 2476 y FN(The)g(zlib)i(library)e(home)g(page.)0 2623 y FO(http://www)l(.zlib)m(.net/man)o(ua)o(l.h)o(tml)208 2723 y FN(The)g(zlib)i(manual)e(e)o(xplains)g(the)h(semantics)g(and)g (usage)g(of)g(the)g(library')-5 b(s)19 b(man)o(y)g(functions.)0 3050 y FE(12.2)121 b Fx(gzip)32 b FE(\227)h(Suppor)5 b(t)35 b(f)l(or)f Fj(gzip)g FE(\002les)0 3283 y FN(The)21 b(data)g(compression)f(pro)o(vided)f(by)i(the)g FJ(zlib)g FN(module)f(is)i(compatible)e(with)i(that)f(used)g(by)g(the)g(GNU)h (compression)e(program)0 3382 y FL(gzip)p FN(.)25 b(Accordingly)-5 b(,)16 b(the)j FJ(gzip)g FN(module)e(pro)o(vides)h(the)h FJ(GzipFile)f FN(class)i(to)f(read)f(and)h(write)g FL(gzip)p FN(-format)e(\002les,)j(automatically)0 3482 y(compressing)e(or)i (decompressing)e(the)j(data)f(so)g(it)h(looks)f(lik)o(e)h(an)f (ordinary)e(\002le)j(object.)j(Note)c(that)h(additional)e(\002le)i (formats)e(which)0 3581 y(can)31 b(be)g(decompressed)d(by)j(the)g FL(gzip)g FN(and)f FL(gunzip)i FN(programs,)f(such)g(as)g(those)g (produced)e(by)h FL(compr)o(ess)h FN(and)f FL(pack)p FN(,)k(are)d(not)0 3681 y(supported)18 b(by)i(this)h(module.)0 3828 y(The)f(module)f(de\002nes)h(the)g(follo)n(wing)e(items:)0 3975 y FL(class)j FD(GzipFile)p FJ(\()p FC([)p FK(\002lename)p FC([)p FK(,)c(mode)p FC([)p FK(,)i(compr)m(essle)o(vel)p FC([)p FK(,)g(\002leobj)12 b FC(])g(])g(])g(])p FJ(\))208 4074 y FN(Constructor)j(for)h(the)h FJ(GzipFile)f FN(class,)j(which)d (simulates)h(most)g(of)g(the)g(methods)e(of)i(a)g(\002le)h(object,)f (with)g(the)g(e)o(xception)e(of)208 4174 y(the)20 b FJ(readinto\(\))e FN(and)i FJ(truncate\(\))e FN(methods.)24 b(At)d(least)f(one)g(of)f FK(\002leobj)g FN(and)h FK(\002lename)f FN(must)h(be)g(gi)n(v)o(en)e(a) j(non-tri)n(vial)208 4274 y(v)n(alue.)208 4406 y(The)f(ne)n(w)g(class)i (instance)e(is)i(based)e(on)g FK(\002leobj)p FN(,)f(which)i(can)f(be)g (a)h(re)o(gular)e(\002le,)j(a)f FJ(StringIO)e FN(object,)h(or)h(an)o(y) e(other)h(object)208 4505 y(which)f(simulates)i(a)f(\002le.)26 b(It)20 b(def)o(aults)g(to)g FJ(None)p FN(,)g(in)h(which)e(case)i FK(\002lename)e FN(is)i(opened)e(to)h(pro)o(vide)e(a)j(\002le)f (object.)208 4638 y(When)28 b FK(\002leobj)g FN(is)i(not)f FJ(None)p FN(,)i(the)e FK(\002lename)e FN(ar)o(gument)g(is)j(only)e (used)h(to)g(be)g(included)e(in)i(the)g FL(gzip)g FN(\002le)h(header)m (,)f(which)208 4737 y(may)19 b(includes)g(the)h(original)f(\002lename)h (of)f(the)h(uncompressed)e(\002le.)25 b(It)c(def)o(aults)e(to)h(the)g (\002lename)g(of)f FK(\002leobj)p FN(,)g(if)i(discernible;)208 4837 y(otherwise,)e(it)i(def)o(aults)f(to)g(the)g(empty)f(string,)h (and)g(in)g(this)h(case)f(the)h(original)e(\002lename)g(is)i(not)f (included)f(in)h(the)h(header)-5 b(.)208 4969 y(The)21 b FK(mode)f FN(ar)o(gument)f(can)i(be)h(an)o(y)e(of)h FJ('r')p FN(,)g FJ('rb')p FN(,)h FJ('a')p FN(,)f FJ('ab')p FN(,)g FJ('w')p FN(,)g(or)g FJ('wb')p FN(,)h(depending)c(on)j(whether)g (the)g(\002le)h(will)208 5069 y(be)d(read)h(or)f(written.)25 b(The)19 b(def)o(ault)g(is)i(the)f(mode)e(of)i FK(\002leobj)f FN(if)h(discernible;)f(otherwise,)g(the)h(def)o(ault)f(is)h FJ('rb')p FN(.)25 b(If)20 b(not)f(gi)n(v)o(en,)208 5168 y(the)h('b')f(\003ag)i(will)g(be)f(added)f(to)h(the)g(mode)f(to)i (ensure)e(the)h(\002le)h(is)g(opened)e(in)h(binary)f(mode)g(for)h (cross-platform)e(portability)-5 b(.)208 5300 y(The)28 b FK(compr)m(essle)o(vel)g FN(ar)o(gument)e(is)j(an)f(inte)o(ger)f (from)h FJ(1)g FN(to)h FJ(9)g FN(controlling)d(the)i(le)n(v)o(el)g(of)g (compression;)j FJ(1)e FN(is)g(f)o(astest)g(and)208 5400 y(produces)18 b(the)i(least)h(compression,)d(and)i FJ(9)h FN(is)g(slo)n(west)f(and)g(produces)f(the)h(most)g(compression.)j(The)d (def)o(ault)f(is)j FJ(9)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(12.2.)52 b FJ(gzip)23 b FI(\227)g(Suppor)s(t)h(f)n(or)e FL(gzip)h FI(\002les)2444 b(345)p eop end %%Page: 346 358 TeXDict begin 346 357 bop 208 83 a FN(Calling)23 b(a)g FJ(GzipFile)f FN(object')-5 b(s)23 b FJ(close\(\))f FN(method)g(does)h (not)g(close)g FK(\002leobj)p FN(,)g(since)g(you)f(might)g(wish)i(to)f (append)e(more)208 183 y(material)27 b(after)h(the)f(compressed)g (data.)48 b(This)28 b(also)g(allo)n(ws)g(you)f(to)h(pass)h(a)f FJ(StringIO)f FN(object)g(opened)f(for)i(writing)f(as)208 282 y FK(\002leobj)p FN(,)19 b(and)g(retrie)n(v)o(e)g(the)h(resulting)g (memory)e(b)n(uf)n(fer)h(using)h(the)g FJ(StringIO)f FN(object')-5 b(s)20 b FJ(getvalue\(\))f FN(method.)0 429 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(mode)p FC([)p FK(,)h(compr)m(essle)o(vel)12 b FC(])g(])p FJ(\))208 529 y FN(This)30 b(is)i(a)f(shorthand)e(for)h FJ(GzipFile\()p FK(\002lename)p FJ(,)g FK(mode)p FJ(,)i FK(compr)m(essle)o(vel)p FJ(\))p FN(.)56 b(The)30 b FK(\002lename)f FN(ar)o(gument)g(is)i (required;)208 628 y FK(mode)19 b FN(def)o(aults)h(to)g FJ('rb')g FN(and)g FK(compr)m(essle)o(vel)g FN(def)o(aults)g(to)g FJ(9)p FN(.)0 775 y FL(See)h(Also:)0 922 y FN(Module)e FJ(zlib)h FN(\(section)g(12.1\):)208 1022 y(The)f(basic)i(data)f (compression)e(module)h(needed)g(to)h(support)f(the)h FL(gzip)h FN(\002le)g(format.)0 1349 y FE(12.3)121 b Fx(bz2)33 b FE(\227)f(Compression)j(compatib)n(le)f(with)f Fj(bzip2)0 1582 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1729 y(This)i(module)f(pro)o(vides)g(a)h(comprehensi)n(v)o(e)d(interf)o (ace)j(for)f(the)h(bz2)g(compression)e(library)-5 b(.)27 b(It)21 b(implements)f(a)i(complete)e(\002le)i(inter)n(-)0 1829 y(f)o(ace,)e(one-shot)f(\(de\)compression)e(functions,)h(and)i (types)g(for)f(sequential)h(\(de\)compression.)0 1975 y(Here)g(is)h(a)g(resume)e(of)h(the)g(features)g(of)n(fered)e(by)i(the) g(bz2)g(module:)125 2205 y FM(\017)41 b FJ(BZ2File)66 b FN(class)j(implements)d(a)i(complete)f(\002le)h(interf)o(ace,)78 b(including)66 b FJ(readline\(\))p FN(,)77 b FJ(readlines\(\))p FN(,)208 2305 y FJ(writelines\(\))p FN(,)18 b FJ(seek\(\))p FN(,)h(etc;)125 2471 y FM(\017)41 b FJ(BZ2File)19 b FN(class)i (implements)e(emulated)g FJ(seek\(\))h FN(support;)125 2637 y FM(\017)41 b FJ(BZ2File)19 b FN(class)i(implements)e(uni)n(v)o (ersal)g(ne)n(wline)h(support;)125 2803 y FM(\017)41 b FJ(BZ2File)19 b FN(class)i(of)n(fers)e(an)i(optimized)d(line)j (iteration)e(using)h(the)g(readahead)e(algorithm)h(borro)n(wed)f(from)h (\002le)i(objects;)125 2969 y FM(\017)41 b FN(Sequential)19 b(\(de\)compression)e(supported)h(by)i FJ(BZ2Compressor)e FN(and)i FJ(BZ2Decompressor)e FN(classes;)125 3135 y FM(\017)41 b FN(One-shot)19 b(\(de\)compression)e(supported)h(by)i FJ(compress\(\))f FN(and)g FJ(decompress\(\))g FN(functions;)125 3301 y FM(\017)41 b FN(Thread)18 b(safety)i(uses)h(indi)n(vidual)e (locking)f(mechanism;)125 3467 y FM(\017)41 b FN(Complete)19 b(inline)h(documentation;)0 3752 y Fv(12.3.1)101 b(\(De\)compression)30 b(of)d(\002les)0 3955 y FN(Handling)19 b(of)h(compressed)e(\002les)k (is)f(of)n(fered)d(by)i(the)g FJ(BZ2File)f FN(class.)0 4102 y FL(class)i FD(BZ2File)p FJ(\()p FK(\002lename)p FC([)p FK(,)c(mode)p FC([)p FK(,)i(b)n(uf)o(fering)p FC([)p FK(,)g(compr)m(essle)o(vel)12 b FC(])g(])g(])p FJ(\))208 4202 y FN(Open)18 b(a)i(bz2)e(\002le.)26 b(Mode)18 b(can)h(be)g(either)g FJ('r')g FN(or)g FJ('w')p FN(,)g(for)g(reading)e (\(def)o(ault\))h(or)h(writing.)24 b(When)19 b(opened)e(for)i(writing,) g(the)208 4301 y(\002le)25 b(will)h(be)e(created)g(if)h(it)h(doesn')o (t)d(e)o(xist,)j(and)e(truncated)f(otherwise.)38 b(If)25 b FK(b)n(uf)o(fering)f FN(is)h(gi)n(v)o(en,)g FJ(0)g FN(means)f(unb)n(uf)n(fered,)f(and)208 4401 y(lar)o(ger)d(numbers)g (specify)h(the)h(b)n(uf)n(fer)e(size;)k(the)d(def)o(ault)g(is)i FJ(0)p FN(.)30 b(If)22 b FK(compr)m(essle)o(vel)f FN(is)i(gi)n(v)o(en,) d(it)j(must)f(be)f(a)h(number)e(between)208 4500 y FJ(1)h FN(and)g FJ(9)p FN(;)h(the)f(def)o(ault)f(is)i FJ(9)p FN(.)28 b(Add)21 b(a)g(`)p FJ(U)p FN(')g(to)g(mode)f(to)i(open)e(the)h (\002le)h(for)e(input)g(with)i(uni)n(v)o(ersal)d(ne)n(wline)i(support.) 26 b(An)o(y)20 b(line)208 4600 y(ending)g(in)i(the)g(input)f(\002le)i (will)f(be)g(seen)g(as)h(a)f(`)p FJ(\\n)p FN(')f(in)h(Python.)29 b(Also,)22 b(a)h(\002le)f(so)h(opened)d(gains)h(the)h(attrib)n(ute)f FJ(newlines)p FN(;)208 4700 y(the)i(v)n(alue)f(for)h(this)g(attrib)n (ute)g(is)h(one)f(of)f FJ(None)h FN(\(no)g(ne)n(wline)f(read)h(yet\),)g FJ('\\r')p FN(,)g FJ('\\n')p FN(,)h FJ('\\r\\n')e FN(or)h(a)h(tuple)e (containing)208 4799 y(all)i(the)h(ne)n(wline)e(types)h(seen.)37 b(Uni)n(v)o(ersal)23 b(ne)n(wlines)h(are)g(a)n(v)n(ailable)g(only)f (when)h(reading.)35 b(Instances)24 b(support)f(iteration)g(in)208 4899 y(the)d(same)g(w)o(ay)g(as)h(normal)e FJ(file)h FN(instances.)0 5046 y FD(close)p FJ(\(\))208 5145 y FN(Close)29 b(the)g(\002le.)53 b(Sets)30 b(data)f(attrib)n(ute)g FJ(closed)f FN(to)h(true.)52 b(A)29 b(closed)g(\002le)h(cannot)e(be)h (used)g(for)f(further)g(I/O)h(operations.)208 5245 y FJ(close\(\))19 b FN(may)h(be)g(called)g(more)f(than)h(once)f(without)h (error)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(346)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 347 359 TeXDict begin 347 358 bop 0 83 a FD(read)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 183 y FN(Read)26 b(at)h(most)f FK(size)h FN(uncompressed)d(bytes,)j(returned)d(as)j(a)g(string.)42 b(If)26 b(the)g FK(size)i FN(ar)o(gument)23 b(is)28 b(ne)o(gati)n(v)o (e)c(or)h(omitted,)i(read)208 282 y(until)20 b(EOF)g(is)h(reached.)0 429 y FD(readline)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 529 y FN(Return)32 b(the)g(ne)o(xt)g(line)h(from)f(the)g (\002le,)37 b(as)c(a)g(string,)i(retaining)d(ne)n(wline.)61 b(A)33 b(non-ne)o(gati)n(v)o(e)c FK(size)34 b FN(ar)o(gument)c(limits)k (the)208 628 y(maximum)28 b(number)g(of)i(bytes)g(to)g(return)f(\(an)g (incomplete)g(line)h(may)g(be)g(returned)e(then\).)54 b(Return)29 b(an)h(empty)f(string)h(at)208 728 y(EOF)-7 b(.)0 875 y FD(readlines)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 975 y FN(Return)19 b(a)h(list)i(of)d(lines)i(read.)j (The)c(optional)e FK(size)j FN(ar)o(gument,)d(if)i(gi)n(v)o(en,)e(is)j (an)f(approximate)e(bound)g(on)i(the)g(total)g(number)e(of)208 1074 y(bytes)i(in)g(the)g(lines)h(returned.)0 1221 y FD(xreadlines)p FJ(\(\))208 1321 y FN(F)o(or)j(backw)o(ard)f (compatibility)-5 b(.)36 b FJ(BZ2File)24 b FN(objects)g(no)n(w)g (include)g(the)h(performance)c(optimizations)j(pre)n(viously)e(imple-) 208 1420 y(mented)17 b(in)h(the)h FJ(xreadlines)e FN(module.)23 b FL(Depr)o(ecated)17 b(since)i(r)o(elease)e(2.3.)24 b FN(This)19 b(e)o(xists)f(only)g(for)f(compatibility)g(with)i(the)208 1520 y(method)f(by)i(this)h(name)e(on)h FJ(file)g FN(objects,)g(which)g (is)h(deprecated.)i(Use)e FJ(for)49 b(line)g(in)g(file)20 b FN(instead.)0 1667 y FD(seek)p FJ(\()p FK(of)o(fset)q FC([)p FK(,)f(whence)12 b FC(])p FJ(\))208 1766 y FN(Mo)o(v)o(e)17 b(to)i(ne)n(w)g(\002le)h(position.)j(Ar)o(gument)17 b FK(of)o(fset)k FN(is)e(a)h(byte)e(count.)24 b(Optional)18 b(ar)o(gument)f FK(whence)h FN(def)o(aults)h(to)g FJ(os.SEEK_-)208 1866 y(SET)f FN(or)h FJ(0)g FN(\(of)n(fset)e(from)h(start)h(of)f (\002le;)i(of)n(fset)f(should)e(be)i FJ(>=)49 b(0)p FN(\);)19 b(other)f(v)n(alues)g(are)h FJ(os.SEEK_CUR)e FN(or)i FJ(1)g FN(\(mo)o(v)o(e)d(relati)n(v)o(e)208 1966 y(to)24 b(current)e(position;)j(of)n(fset)f(can)f(be)h(positi)n(v)o(e)f(or)h (ne)o(gati)n(v)o(e\),)e(and)h FJ(os.SEEK_END)g FN(or)g FJ(2)i FN(\(mo)o(v)o(e)d(relati)n(v)o(e)h(to)h(end)f(of)h(\002le;)208 2065 y(of)n(fset)19 b(is)i(usually)f(ne)o(gati)n(v)o(e,)e(although)g (man)o(y)h(platforms)g(allo)n(w)h(seeking)g(be)o(yond)e(the)i(end)f(of) h(a)h(\002le\).)208 2198 y(Note)26 b(that)h(seeking)f(of)g(bz2)g (\002les)i(is)f(emulated,)g(and)f(depending)e(on)i(the)h(parameters)e (the)i(operation)e(may)h(be)g(e)o(xtremely)208 2298 y(slo)n(w)-5 b(.)0 2445 y FD(tell)p FJ(\(\))208 2544 y FN(Return)19 b(the)i(current)d(\002le)j(position,)e(an)h(inte)o(ger)g(\(may)f(be)h (a)h(long)e(inte)o(ger\).)0 2691 y FD(write)p FJ(\()p FK(data)p FJ(\))208 2791 y FN(Write)g(string)f FK(data)g FN(to)h(\002le.)25 b(Note)19 b(that)g(due)f(to)h(b)n(uf)n(fering,)d FJ(close\(\))i FN(may)g(be)h(needed)e(before)h(the)g(\002le)i(on)e (disk)h(re\003ects)g(the)208 2890 y(data)h(written.)0 3037 y FD(writelines)p FJ(\()p FK(sequence)p 861 3037 25 4 v 26 w(of)p 952 3037 V 30 w(strings)p FJ(\))208 3137 y FN(Write)25 b(the)g(sequence)f(of)h(strings)g(to)g(the)g (\002le.)40 b(Note)24 b(that)i(ne)n(wlines)e(are)h(not)g(added.)38 b(The)24 b(sequence)g(can)h(be)g(an)o(y)f(iterable)208 3236 y(object)19 b(producing)f(strings.)25 b(This)20 b(is)h(equi)n(v)n(alent)d(to)j(calling)f(write\(\))f(for)h(each)g (string.)0 3521 y Fv(12.3.2)101 b(Sequential)30 b(\(de\)compression)0 3724 y FN(Sequential)19 b(compression)g(and)g(decompression)f(is)j (done)e(using)h(the)g(classes)i FJ(BZ2Compressor)c FN(and)i FJ(BZ2Decompressor)p FN(.)0 3871 y FL(class)h FD(BZ2Compressor)p FJ(\()p FC([)p FK(compr)m(essle)o(vel)12 b FC(])p FJ(\))208 3971 y FN(Create)k(a)h(ne)n(w)f(compressor)f(object.)23 b(This)17 b(object)f(may)g(be)g(used)g(to)h(compress)e(data)h (sequentially)-5 b(.)23 b(If)16 b(you)f(w)o(ant)i(to)f(compress)208 4070 y(data)28 b(in)h(one)f(shot,)i(use)f(the)f FJ(compress\(\))g FN(function)e(instead.)50 b(The)28 b FK(compr)m(essle)o(vel)h FN(parameter)m(,)f(if)h(gi)n(v)o(en,)g(must)g(be)f(a)208 4170 y(number)18 b(between)h FJ(1)i FN(and)f FJ(9)p FN(;)g(the)g(def)o (ault)g(is)h FJ(9)p FN(.)0 4317 y FD(compress)p FJ(\()p FK(data)p FJ(\))208 4417 y FN(Pro)o(vide)d(more)g(data)h(to)h(the)f (compressor)f(object.)24 b(It)c(will)g(return)e(chunks)h(of)g (compressed)f(data)h(whene)n(v)o(er)e(possible.)25 b(When)208 4516 y(you')l(v)o(e)c(\002nished)i(pro)o(viding)e(data)j(to)g (compress,)f(call)h(the)g FJ(flush\(\))f FN(method)g(to)h(\002nish)f (the)h(compression)e(process,)i(and)208 4616 y(return)19 b(what)h(is)h(left)f(in)h(internal)e(b)n(uf)n(fers.)0 4763 y FD(flush)p FJ(\(\))208 4862 y FN(Finish)28 b(the)f(compression)f (process)i(and)f(return)g(what)g(is)i(left)f(in)g(internal)f(b)n(uf)n (fers.)47 b(Y)-9 b(ou)27 b(must)h(not)f(use)h(the)g(compressor)208 4962 y(object)19 b(after)h(calling)g(this)h(method.)0 5109 y FL(class)g FD(BZ2Decompressor)p FJ(\(\))208 5208 y FN(Create)k(a)i(ne)n(w)e(decompressor)e(object.)41 b(This)26 b(object)f(may)g(be)h(used)f(to)h(decompress)e(data)i (sequentially)-5 b(.)39 b(If)26 b(you)f(w)o(ant)g(to)208 5308 y(decompress)18 b(data)i(in)h(one)e(shot,)h(use)h(the)f FJ(decompress\(\))e FN(function)h(instead.)p 0 5549 3901 4 v 0 5649 a FI(12.3.)52 b FJ(bz2)23 b FI(\227)g(Compression)g (compatib)n(le)i(with)e FL(bzip2)1948 b FI(347)p eop end %%Page: 348 360 TeXDict begin 348 359 bop 0 83 a FD(decompress)p FJ(\()p FK(data)p FJ(\))208 183 y FN(Pro)o(vide)22 b(more)g(data)i(to)f(the)h (decompressor)d(object.)34 b(It)24 b(will)g(return)f(chunks)f(of)h (decompressed)e(data)j(whene)n(v)o(er)d(possible.)208 282 y(If)e(you)g(try)h(to)g(decompress)e(data)i(after)f(the)h(end)f(of) g(stream)h(is)h(found,)d FJ(EOFError)h FN(will)h(be)g(raised.)k(If)c (an)o(y)f(data)h(w)o(as)g(found)208 382 y(after)f(the)i(end)e(of)h (stream,)g(it')o(ll)h(be)f(ignored)e(and)i(sa)n(v)o(ed)g(in)g FJ(unused_data)f FN(attrib)n(ute.)0 667 y Fv(12.3.3)101 b(One-shot)28 b(\(de\)compression)0 870 y FN(One-shot)19 b(compression)g(and)g(decompression)f(is)j(pro)o(vided)d(through)g(the) i FJ(compress\(\))f FN(and)h FJ(decompress\(\))e FN(functions.)0 1017 y FD(compress)p FJ(\()p FK(data)p FC([)p FK(,)f(compr)m(essle)o (vel)12 b FC(])p FJ(\))208 1116 y FN(Compress)24 b FK(data)g FN(in)g(one)g(shot.)39 b(If)24 b(you)g(w)o(ant)h(to)f(compress)g(data)h (sequentially)-5 b(,)23 b(use)i(an)g(instance)f(of)g FJ(BZ2Compressor)208 1216 y FN(instead.)g(The)c FK(compr)m(essle)o(vel) g FN(parameter)m(,)e(if)j(gi)n(v)o(en,)d(must)i(be)h(a)f(number)f (between)g FJ(1)h FN(and)g FJ(9)p FN(;)h(the)f(def)o(ault)f(is)j FJ(9)p FN(.)0 1363 y FD(decompress)p FJ(\()p FK(data)p FJ(\))208 1462 y FN(Decompress)53 b FK(data)h FN(in)g(one)g(shot.)128 b(If)55 b(you)e(w)o(ant)i(to)g(decompress)e(data)h(sequentially)-5 b(,)61 b(use)55 b(an)g(instance)f(of)208 1562 y FJ(BZ2Decompressor)18 b FN(instead.)0 1889 y FE(12.4)121 b Fx(zipfile)32 b FE(\227)g(W)l(or)r(k)i(with)f(ZIP)h(archiv)m(es)0 2122 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.6.)0 2269 y(The)g(ZIP)h(\002le)h (format)e(is)h(a)h(common)d(archi)n(v)o(e)g(and)h(compression)f (standard.)24 b(This)c(module)e(pro)o(vides)g(tools)i(to)g(create,)g (read,)f(write,)0 2369 y(append,)f(and)g(list)j(a)f(ZIP)f(\002le.)25 b(An)o(y)19 b(adv)n(anced)e(use)j(of)f(this)h(module)e(will)i(require)e (an)h(understanding)d(of)k(the)f(format,)f(as)i(de\002ned)e(in)0 2468 y FK(PKZIP)i(Application)f(Note)p FN(.)0 2615 y(This)f(module)f (does)h(not)g(currently)e(handle)h(ZIP)h(\002les)h(which)f(ha)n(v)o(e)f (appended)f(comments,)h(or)h(multi-disk)f(ZIP)h(\002les.)25 b(It)19 b(can)f(handle)0 2715 y(ZIP)i(\002les)h(that)g(use)f(the)g (ZIP64)g(e)o(xtensions)f(\(that)h(is)h(ZIP)f(\002les)h(that)f(are)h (more)e(than)h(4)g(GByte)g(in)h(size\).)0 2862 y(The)f(a)n(v)n(ailable) g(attrib)n(utes)g(of)g(this)g(module)f(are:)0 3009 y FL(exception)g FD(error)208 3108 y FN(The)g(error)g(raised)h(for)g(bad) g(ZIP)g(\002les.)0 3255 y FL(exception)f FD(LargeZipFile)208 3355 y FN(The)g(error)g(raised)h(when)g(a)h(ZIP)f(\002le)h(w)o(ould)e (require)g(ZIP64)g(functionality)g(b)n(ut)h(that)g(has)g(not)g(been)g (enabled.)0 3502 y FL(class)h FD(ZipFile)208 3601 y FN(The)e(class)j (for)d(reading)g(and)g(writing)h(ZIP)g(\002les.)26 b(See)21 b(\223)p FK(ZipF)l(ile)f(Objects)p FN(\224)h(\(section)e(12.4.1\))f (for)i(constructor)e(details.)0 3748 y FL(class)j FD(PyZipFile)208 3848 y FN(Class)g(for)f(creating)f(ZIP)h(archi)n(v)o(es)f(containing)g (Python)g(libraries.)0 3995 y FL(class)i FD(ZipInfo)p FJ(\()p FC([)p FK(\002lename)p FC([)p FK(,)c(date)p 1137 3995 25 4 v 29 w(time)12 b FC(])g(])p FJ(\))208 4094 y FN(Class)26 b(used)f(to)g(represent)f(information)e(about)i(a)i (member)d(of)i(an)g(archi)n(v)o(e.)38 b(Instances)25 b(of)f(this)i(class)g(are)f(returned)e(by)i(the)208 4194 y FJ(getinfo\(\))c FN(and)g FJ(infolist\(\))g FN(methods)g(of)h FJ(ZipFile)f FN(objects.)30 b(Most)23 b(users)f(of)g(the)g FJ(zipfile)f FN(module)g(will)i(not)208 4293 y(need)d(to)h(create)g (these,)h(b)n(ut)f(only)f(use)i(those)f(created)f(by)h(this)g(module.) 27 b FK(\002lename)20 b FN(should)g(be)h(the)g(full)g(name)g(of)g(the)g (archi)n(v)o(e)208 4393 y(member)m(,)g(and)i FK(date)p 814 4393 V 29 w(time)g FN(should)g(be)g(a)g(tuple)g(containing)e(six)j (\002elds)f(which)g(describe)f(the)h(time)g(of)g(the)g(last)h (modi\002cation)208 4493 y(to)c(the)g(\002le;)h(the)f(\002elds)h(are)f (described)f(in)h(section)g(12.4.3,)e(\223ZipInfo)h(Objects.)-6 b(\224)0 4640 y FD(is_zipfile)p FJ(\()p FK(\002lename)p FJ(\))208 4739 y FN(Returns)19 b FJ(True)h FN(if)g FK(\002lename)f FN(is)h(a)g(v)n(alid)g(ZIP)g(\002le)g(based)g(on)f(its)i(magic)e (number)m(,)e(otherwise)j(returns)f FJ(False)p FN(.)24 b(This)c(module)208 4839 y(does)f(not)h(currently)f(handle)g(ZIP)h (\002les)h(which)f(ha)n(v)o(e)g(appended)d(comments.)0 4986 y FD(ZIP_STORED)208 5085 y FN(The)i(numeric)g(constant)h(for)f(an) h(uncompressed)e(archi)n(v)o(e)h(member)-5 b(.)0 5232 y FD(ZIP_DEFLATED)208 5332 y FN(The)19 b(numeric)f(constant)h(for)g (the)h(usual)g(ZIP)g(compression)d(method.)24 b(This)c(requires)e(the)i (zlib)g(module.)j(No)d(other)f(compres-)p 0 5549 3901 4 v 0 5649 a FI(348)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 349 361 TeXDict begin 349 360 bop 208 83 a FN(sion)20 b(methods)f(are)h (currently)e(supported.)0 230 y FL(See)j(Also:)0 377 y FK(PKZIP)f(Application)f(Note)0 476 y Fy(\()p FO(http://www)l(.pkw)o (are)o(.com/b)o(usin)o(ess)p 1114 476 23 4 v 21 w(and)p 1261 476 V 26 w(de)n(v)n(elopers/de)n(v)n(eloper/a)o(pp)o(not)o(e/)-6 b Fy(\))208 576 y FN(Documentation)17 b(on)j(the)g(ZIP)g(\002le)h (format)e(by)h(Phil)h(Katz,)f(the)g(creator)f(of)h(the)h(format)e(and)g (algorithms)g(used.)0 723 y FK(Info-ZIP)g(Home)h(P)-7 b(a)o(g)o(e)0 823 y Fy(\()p FO(http://www)l(.inf)n(o-zip)m(.org/)o(pub) o(/i)o(nf)m(ozip/)g Fy(\))208 922 y FN(Information)17 b(about)i(the)h(Info-ZIP)f(project')-5 b(s)19 b(ZIP)i(archi)n(v)o(e)d (programs)h(and)g(de)n(v)o(elopment)f(libraries.)0 1207 y Fv(12.4.1)101 b(ZipFile)28 b(Objects)0 1405 y FL(class)21 b FD(ZipFile)p FJ(\()p FK(\002le)p FC([)p FK(,)d(mode)p FC([)p FK(,)h(compr)m(ession)p FC([)p FK(,)g(allowZip64)12 b FC(])g(])g(])p FJ(\))208 1505 y FN(Open)k(a)i(ZIP)g(\002le,)g(where)f FK(\002le)g FN(can)g(be)g(either)g(a)h(path)f(to)g(a)h(\002le)g(\(a)g (string\))e(or)h(a)h(\002le-lik)o(e)g(object.)23 b(The)17 b FK(mode)g FN(parameter)f(should)208 1604 y(be)22 b FJ('r')h FN(to)g(read)f(an)h(e)o(xisting)f(\002le,)i FJ('w')f FN(to)g(truncate)f(and)g(write)h(a)g(ne)n(w)g(\002le,)h(or)f FJ('a')f FN(to)h(append)f(to)h(an)f(e)o(xisting)g(\002le.)34 b(F)o(or)208 1704 y FK(mode)20 b FN(is)i FJ('a')f FN(and)f FK(\002le)h FN(refers)g(to)g(an)g(e)o(xisting)f(ZIP)h(\002le,)h(then)e (additional)g(\002les)i(are)f(added)e(to)j(it.)28 b(If)20 b FK(\002le)h FN(does)g(not)g(refer)f(to)h(a)208 1804 y(ZIP)h(\002le,)i(then)e(a)h(ne)n(w)g(ZIP)g(archi)n(v)o(e)e(is)i (appended)e(to)i(the)f(\002le.)33 b(This)23 b(is)h(meant)e(for)g (adding)f(a)i(ZIP)g(archi)n(v)o(e)e(to)i(another)e(\002le,)208 1903 y(such)e(as)i(`)p FO(p)n(ython.e)n(x)n(e)p FN('.)h(Using)444 2128 y FA(cat)44 b(myzip.zip)f(>>)i(python.exe)208 2318 y FN(also)34 b(w)o(orks,)i(and)d(at)h(least)h FL(W)o(inZip)f FN(can)g(read)f(such)g(\002les.)66 b FK(compr)m(ession)33 b FN(is)i(the)f(ZIP)f(compression)f(method)h(to)g(use)208 2417 y(when)24 b(writing)g(the)h(archi)n(v)o(e,)f(and)g(should)g(be)h FJ(ZIP_STORED)e FN(or)i FJ(ZIP_DEFLATED)p FN(;)e(unrecognized)f(v)n (alues)i(will)i(cause)208 2517 y FJ(RuntimeError)37 b FN(to)i(be)g(raised.)81 b(If)39 b FJ(ZIP_DEFLATED)e FN(is)j (speci\002ed)f(b)n(ut)g(the)g FJ(zlib)g FN(module)f(is)i(not)e(a)n(v)n (ailable,)208 2616 y FJ(RuntimeError)23 b FN(is)k(also)e(raised.)41 b(The)25 b(def)o(ault)g(is)h FJ(ZIP_STORED)p FN(.)e(If)h FK(allowZip64)g FN(is)h FJ(True)g FN(zip\002le)f(will)h(create)f(ZIP) 208 2716 y(\002les)20 b(that)g(use)g(the)g(ZIP64)f(e)o(xtensions)f (when)h(the)h(zip\002le)g(is)h(lar)o(ger)d(than)h(2)h(GB.)h(If)e(it)i (is)f(f)o(alse)h(\(the)e(def)o(ault\))g FJ(zipfile)g FN(will)208 2816 y(raise)i(an)g(e)o(xception)f(when)g(the)i(ZIP)f (\002le)h(w)o(ould)f(require)f(ZIP64)g(e)o(xtensions.)27 b(ZIP64)21 b(e)o(xtensions)f(are)h(disabled)f(by)h(def)o(ault)208 2915 y(because)e(the)h(def)o(ault)g FL(zip)h FN(and)e FL(unzip)i FN(commands)e(on)j(U)t FH(N)t(I)t(X)h FN(\(the)d(InfoZIP)e (utilities\))j(don')o(t)d(support)h(these)i(e)o(xtensions.)0 3062 y FD(close)p FJ(\(\))208 3162 y FN(Close)27 b(the)g(archi)n(v)o(e) e(\002le.)45 b(Y)-9 b(ou)26 b(must)h(call)g FJ(close\(\))f FN(before)g(e)o(xiting)f(your)h(program)e(or)j(essential)g(records)f (will)h(not)g(be)208 3261 y(written.)0 3408 y FD(getinfo)p FJ(\()p FK(name)p FJ(\))208 3508 y FN(Return)19 b(a)i FJ(ZipInfo)e FN(object)h(with)g(information)e(about)h(the)i(archi)n(v)o (e)d(member)h FK(name)p FN(.)0 3655 y FD(infolist)p FJ(\(\))208 3754 y FN(Return)j(a)i(list)g(containing)d(a)i FJ(ZipInfo)f FN(object)h(for)f(each)h(member)e(of)i(the)g(archi)n(v)o(e.)32 b(The)23 b(objects)g(are)f(in)i(the)f(same)g(order)208 3854 y(as)d(their)g(entries)g(in)h(the)f(actual)g(ZIP)g(\002le)h(on)f (disk)g(if)h(an)f(e)o(xisting)f(archi)n(v)o(e)g(w)o(as)i(opened.)0 4001 y FD(namelist)p FJ(\(\))208 4101 y FN(Return)e(a)i(list)g(of)f (archi)n(v)o(e)f(members)g(by)h(name.)0 4247 y FD(printdir)p FJ(\(\))208 4347 y FN(Print)g(a)g(table)h(of)e(contents)h(for)f(the)i (archi)n(v)o(e)d(to)j FJ(sys.stdout)p FN(.)0 4494 y FD(read)p FJ(\()p FK(name)p FJ(\))208 4594 y FN(Return)e(the)i(bytes)f(of)f(the)i (\002le)f(in)h(the)f(archi)n(v)o(e.)k(The)19 b(archi)n(v)o(e)g(must)h (be)h(open)e(for)g(read)h(or)g(append.)0 4740 y FD(testzip)p FJ(\(\))208 4840 y FN(Read)h(all)g(the)g(\002les)h(in)g(the)f(archi)n (v)o(e)e(and)i(check)f(their)h(CRC')-5 b(s)23 b(and)d(\002le)i (headers.)k(Return)21 b(the)g(name)f(of)h(the)g(\002rst)h(bad)e (\002le,)i(or)208 4940 y(else)e(return)f FJ(None)p FN(.)0 5087 y FD(write)p FJ(\()p FK(\002lename)p FC([)p FK(,)e(ar)m(cname)p FC([)p FK(,)i(compr)m(ess)p 1346 5087 25 4 v 30 w(type)12 b FC(])g(])p FJ(\))208 5186 y FN(Write)26 b(the)g(\002le)h(named)e FK(\002lename)g FN(to)h(the)g(archi)n(v)o(e,)g(gi)n(ving)f(it)i(the)f (archi)n(v)o(e)f(name)g FK(ar)m(cname)g FN(\(by)g(def)o(ault,)i(this)g (will)g(be)f(the)208 5286 y(same)21 b(as)h FK(\002lename)p FN(,)e(b)n(ut)h(without)f(a)i(dri)n(v)o(e)e(letter)h(and)f(with)i (leading)e(path)g(separators)h(remo)o(v)o(ed\).)k(If)20 b(gi)n(v)o(en,)g FK(compr)m(ess)p 3737 5286 V 30 w(type)208 5385 y FN(o)o(v)o(errides)f(the)j(v)n(alue)f(gi)n(v)o(en)g(for)g(the)g FK(compr)m(ession)g FN(parameter)g(to)g(the)h(constructor)e(for)h(the)h (ne)n(w)f(entry)-5 b(.)29 b(The)21 b(archi)n(v)o(e)g(must)p 0 5549 3901 4 v 0 5649 a FI(12.4.)52 b FJ(zipfile)22 b FI(\227)h(W)n(or)q(k)g(with)g(ZIP)h(archiv)n(es)2201 b(349)p eop end %%Page: 350 362 TeXDict begin 350 361 bop 208 83 a FN(be)20 b(open)f(with)h(mode)f FJ('w')i FN(or)f FJ('a')p FN(.)208 216 y FL(Note:)k FN(There)c(is)h(no) f(of)n(\002cial)g(\002le)i(name)d(encoding)g(for)g(ZIP)i(\002les.)27 b(If)20 b(you)f(ha)n(v)o(e)h(unicode)f(\002le)i(names,)f(please)h(con)m (v)o(ert)d(them)208 315 y(to)k(byte)g(strings)h(in)g(your)e(desired)h (encoding)e(before)h(passing)h(them)h(to)f FJ(write\(\))p FN(.)32 b(W)m(inZip)22 b(interprets)f(all)i(\002le)h(names)e(as)208 415 y(encoded)c(in)i(CP437,)g(also)g(kno)n(wn)f(as)i(DOS)g(Latin.)208 548 y FL(Note:)j FN(Archi)n(v)o(e)19 b(names)h(should)f(be)h(relati)n (v)o(e)f(to)i(the)f(archi)n(v)o(e)f(root,)g(that)h(is,)h(the)o(y)f (should)f(not)h(start)g(with)h(a)f(path)g(separator)-5 b(.)0 695 y FD(writestr)p FJ(\()p FK(zinfo)p 617 695 25 4 v 28 w(or)p 719 695 V 29 w(ar)m(cname)o(,)19 b(bytes)p FJ(\))208 794 y FN(Write)k(the)f(string)h FK(bytes)g FN(to)f(the)h(archi)n(v)o(e;)g FK(zinfo)p 1619 794 V 29 w(or)p 1722 794 V 30 w(ar)m(cname)e FN(is)j(either)e(the)h(\002le)g (name)f(it)h(will)h(be)e(gi)n(v)o(en)g(in)h(the)f(archi)n(v)o(e,)g(or) 208 894 y(a)g FJ(ZipInfo)g FN(instance.)31 b(If)22 b(it')-5 b(s)24 b(an)e(instance,)g(at)h(least)g(the)f(\002lename,)h(date,)f(and) g(time)g(must)h(be)f(gi)n(v)o(en.)30 b(If)22 b(it')-5 b(s)24 b(a)f(name,)f(the)208 994 y(date)e(and)f(time)i(is)g(set)g(to)f (the)g(current)f(date)h(and)g(time.)25 b(The)20 b(archi)n(v)o(e)f(must) h(be)g(opened)e(with)j(mode)e FJ('w')h FN(or)g FJ('a')p FN(.)0 1141 y(The)g(follo)n(wing)e(data)i(attrib)n(ute)g(is)h(also)g(a) n(v)n(ailable:)0 1287 y FD(debug)208 1387 y FN(The)30 b(le)n(v)o(el)g(of)h(deb)n(ug)e(output)h(to)h(use.)57 b(This)31 b(may)f(be)g(set)i(from)e FJ(0)h FN(\(the)f(def)o(ault,)j(no) d(output\))f(to)i FJ(3)g FN(\(the)g(most)f(output\).)208 1487 y(Deb)n(ugging)18 b(information)f(is)22 b(written)d(to)i FJ(sys.stdout)p FN(.)0 1772 y Fv(12.4.2)101 b(PyZipFile)28 b(Objects)0 1974 y FN(The)21 b FJ(PyZipFile)f FN(constructor)g(tak)o (es)i(the)f(same)h(parameters)e(as)i(the)g FJ(ZipFile)e FN(constructor)-5 b(.)28 b(Instances)21 b(ha)n(v)o(e)f(one)h(method)f (in)0 2074 y(addition)f(to)h(those)g(of)g FJ(ZipFile)g FN(objects.)0 2221 y FD(writepy)p FJ(\()p FK(pathname)p FC([)p FK(,)c(basename)c FC(])p FJ(\))208 2321 y FN(Search)25 b(for)g(\002les)i(`)p FO(*.p)n(y)p FN(')e(and)g(add)h(the)g (corresponding)c(\002le)27 b(to)f(the)f(archi)n(v)o(e.)41 b(The)25 b(corresponding)e(\002le)j(is)h(a)f(`)p FO(*.p)n(y)o(o)p FN(')f(\002le)h(if)208 2420 y(a)n(v)n(ailable,)c(else)h(a)g(`)p FO(*.p)n(yc)p FN(')f(\002le,)i(compiling)d(if)h(necessary)-5 b(.)31 b(If)23 b(the)f(pathname)f(is)i(a)g(\002le,)h(the)e(\002lename)g (must)h(end)f(with)h(`)p FO(.p)n(y)p FN(',)208 2520 y(and)c(just)h(the) g(\(corresponding)c(`)p FO(*.p)n(y[co])p FN('\))i(\002le)i(is)h(added)d (at)i(the)g(top)f(le)n(v)o(el)h(\(no)f(path)g(information\).)j(If)e(it) g(is)h(a)f(directory)-5 b(,)17 b(and)208 2619 y(the)i(directory)e(is)k (not)e(a)g(package)f(directory)-5 b(,)17 b(then)i(all)h(the)g(\002les)g (`)p FO(*.p)n(y[co])p FN(')e(are)h(added)f(at)i(the)g(top)f(le)n(v)o (el.)24 b(If)19 b(the)g(directory)f(is)i(a)208 2719 y(package)g (directory)-5 b(,)20 b(then)h(all)i(`)p FO(*.p)n(y[oc])p FN(')d(are)i(added)f(under)f(the)i(package)f(name)g(as)h(a)h(\002le)f (path,)g(and)f(if)h(an)o(y)f(subdirectories)208 2819 y(are)28 b(package)g(directories,)i(all)f(of)g(these)g(are)g(added)e (recursi)n(v)o(ely)-5 b(.)49 b FK(basename)27 b FN(is)j(intended)e(for) g(internal)g(use)h(only)-5 b(.)50 b(The)208 2918 y FJ(writepy\(\))19 b FN(method)f(mak)o(es)i(archi)n(v)o(es)g(with)g(\002le)h(names)f(lik)o (e)g(this:)623 3143 y FA(string.pyc)1433 b(#)45 b(Top)f(level)g(name) 623 3234 y(test/__init__.pyc)1118 b(#)45 b(Package)e(directory)623 3325 y(test/testall.pyc)1163 b(#)45 b(Module)f(test.testall)623 3417 y(test/bogus/__init__.pyc)848 b(#)45 b(Subpackage)e(directory)623 3508 y(test/bogus/myfile.pyc)938 b(#)45 b(Submodule)e (test.bogus.myfile)0 3850 y Fv(12.4.3)101 b(ZipInf)m(o)28 b(Objects)0 4052 y FN(Instances)21 b(of)g(the)g FJ(ZipInfo)f FN(class)i(are)g(returned)d(by)i(the)g FJ(getinfo\(\))f FN(and)h FJ(infolist\(\))f FN(methods)g(of)h FJ(ZipFile)f FN(objects.)0 4152 y(Each)g(object)f(stores)i(information)d(about)h(a)h (single)h(member)d(of)i(the)g(ZIP)h(archi)n(v)o(e.)0 4299 y(Instances)f(ha)n(v)o(e)f(the)h(follo)n(wing)f(attrib)n(utes:)0 4446 y FD(filename)208 4545 y FN(Name)h(of)f(the)i(\002le)g(in)f(the)g (archi)n(v)o(e.)0 4692 y FD(date_time)208 4792 y FN(The)f(time)i(and)e (date)h(of)g(the)h(last)g(modi\002cation)d(to)j(the)f(archi)n(v)o(e)f (member)-5 b(.)23 b(This)e(is)g(a)g(tuple)e(of)h(six)h(v)n(alues:)p 0 5549 3901 4 v 0 5649 a FI(350)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 351 363 TeXDict begin 351 362 bop 1466 70 a FL(Index)p 1717 100 4 100 v 99 w(V)-8 b(alue)p 1416 103 1277 4 v 1542 173 a FJ(0)p 1717 203 4 100 v 176 w FN(Y)g(ear)1542 272 y FJ(1)p 1717 302 V 176 w FN(Month)19 b(\(one-based\))1542 372 y FJ(2)p 1717 402 V 176 w FN(Day)h(of)g(month)f(\(one-based\))1542 472 y FJ(3)p 1717 501 V 176 w FN(Hours)h(\(zero-based\))1542 571 y FJ(4)p 1717 601 V 176 w FN(Minutes)g(\(zero-based\))1542 671 y FJ(5)p 1717 701 V 176 w FN(Seconds)g(\(zero-based\))0 802 y FD(compress_type)208 902 y FN(T)-7 b(ype)19 b(of)h(compression)f (for)g(the)h(archi)n(v)o(e)f(member)-5 b(.)0 1049 y FD(comment)208 1148 y FN(Comment)19 b(for)g(the)i(indi)n(vidual)d(archi)n(v)o(e)h (member)-5 b(.)0 1295 y FD(extra)208 1395 y FN(Expansion)15 b(\002eld)j(data.)24 b(The)18 b FK(PKZIP)g(Application)e(Note)i FN(contains)f(some)h(comments)e(on)i(the)f(internal)g(structure)g(of)h (the)g(data)208 1494 y(contained)g(in)i(this)h(string.)0 1641 y FD(create_system)208 1741 y FN(System)f(which)f(created)h(ZIP)g (archi)n(v)o(e.)0 1888 y FD(create_version)208 1987 y FN(PKZIP)g(v)o(ersion)f(which)h(created)f(ZIP)h(archi)n(v)o(e.)0 2134 y FD(extract_version)208 2234 y FN(PKZIP)g(v)o(ersion)f(needed)g (to)h(e)o(xtract)f(archi)n(v)o(e.)0 2381 y FD(reserved)208 2480 y FN(Must)h(be)g(zero.)0 2627 y FD(flag_bits)208 2727 y FN(ZIP)g(\003ag)g(bits.)0 2874 y FD(volume)208 2973 y FN(V)-11 b(olume)19 b(number)f(of)i(\002le)h(header)-5 b(.)0 3120 y FD(internal_attr)208 3220 y FN(Internal)19 b(attrib)n(utes.)0 3367 y FD(external_attr)208 3466 y FN(External)g(\002le)h(attrib)n(utes.)0 3613 y FD(header_offset)208 3713 y FN(Byte)g(of)n(fset)g(to)g(the)g(\002le)h(header)-5 b(.)0 3860 y FD(CRC)208 3959 y FN(CRC-32)20 b(of)g(the)g(uncompressed)e (\002le.)0 4106 y FD(compress_size)208 4206 y FN(Size)i(of)g(the)g (compressed)f(data.)0 4353 y FD(file_size)208 4452 y FN(Size)h(of)g(the)g(uncompressed)e(\002le.)0 4780 y FE(12.5)121 b Fx(tarfile)32 b FE(\227)g(Read)j(and)g(wr)r(ite)e(tar)h (archiv)m(e)g(\002les)0 5013 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 5159 y(The)h FJ(tarfile)f FN(module)g(mak)o(es)h(it)h(possible)f(to)g (read)g(and)g(create)g(tar)g(archi)n(v)o(es.)k(Some)c(f)o(acts)g(and)g (\002gures:)125 5389 y FM(\017)41 b FN(reads)19 b(and)h(writes)h FJ(gzip)f FN(and)f FJ(bzip2)h FN(compressed)f(archi)n(v)o(es.)p 0 5549 3901 4 v 0 5649 a FI(12.5.)52 b FJ(tarfile)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h(tar)f(archiv)n(e)f(\002les)1909 b(351)p eop end %%Page: 352 364 TeXDict begin 352 363 bop 125 83 a FM(\017)41 b FN(creates)20 b(POSIX)g(1003.1-1990)c(compliant)j(or)h(GNU)g(tar)h(compatible)e (archi)n(v)o(es.)125 249 y FM(\017)41 b FN(reads)19 b(GNU)i(tar)f(e)o (xtensions)f FK(longname)p FN(,)f FK(longlink)h FN(and)h FK(spar)o(se)p FN(.)125 415 y FM(\017)41 b FN(stores)20 b(pathnames)f(of)h(unlimited)f(length)g(using)h(GNU)g(tar)h(e)o (xtensions.)125 581 y FM(\017)41 b FN(handles)16 b(directories,)h(re)o (gular)f(\002les,)j(hardlinks,)d(symbolic)h(links,)h(\002fos,)g (character)e(de)n(vices)h(and)g(block)f(de)n(vices)h(and)g(is)i(able) 208 681 y(to)h(acquire)f(and)h(restore)f(\002le)i(information)d(lik)o (e)i(timestamp,)g(access)h(permissions)e(and)h(o)n(wner)-5 b(.)125 847 y FM(\017)41 b FN(can)20 b(handle)f(tape)h(de)n(vices.)0 1029 y FD(open)p FJ(\()p FC([)p FK(name)p FC([)p FK(,)e(mode)i FC([)p FK(,)g(\002leobj)p FC([)p FK(,)f(b)n(ufsize)12 b FC(])g(])g(])g(])p FJ(\))208 1129 y FN(Return)21 b(a)i FJ(TarFile)e FN(object)h(for)g(the)g(pathname)f FK(name)p FN(.)30 b(F)o(or)22 b(detailed)f(information)f(on)i FJ(TarFile)g FN(objects,)g(see)h FK(T)-8 b(arF)l(ile)208 1229 y(Objects)20 b FN(\(section)g(12.5.1\).)208 1362 y FK(mode)f FN(has)i(to)f(be)h(a)f (string)g(of)g(the)h(form)e FJ('filemode[:compression]')p FN(,)d(it)21 b(def)o(aults)f(to)h FJ('r')p FN(.)k(Here)20 b(is)h(a)g(full)f(list)i(of)208 1461 y(mode)d(combinations:)841 1573 y FL(mode)p 1285 1603 4 100 v 301 w(action)p 589 1607 2930 4 v 639 1676 a FJ('r')49 b(or)g('r:)1137 1691 y(*)1187 1676 y(')p 1285 1706 4 100 v 99 w FN(Open)20 b(for)f(reading)g(with)h(transparent)f(compression)f(\(recommended\).) 838 1776 y FJ('r:')p 1285 1806 V 298 w FN(Open)i(for)f(reading)g(e)o (xclusi)n(v)o(ely)f(without)i(compression.)788 1876 y FJ('r:gz')p 1285 1905 V 248 w FN(Open)g(for)f(reading)g(with)h(gzip)g (compression.)763 1975 y FJ('r:bz2')p 1285 2005 V 223 w FN(Open)g(for)f(reading)g(with)h(bzip2)g(compression.)664 2075 y FJ('a')49 b(or)g('a:')p 1285 2105 V 124 w FN(Open)20 b(for)f(appending)f(with)i(no)g(compression.)664 2174 y FJ('w')49 b(or)g('w:')p 1285 2204 V 124 w FN(Open)20 b(for)f(uncompressed)f(writing.)788 2274 y FJ('w:gz')p 1285 2304 V 248 w FN(Open)i(for)f(gzip)h(compressed)f(writing.)763 2374 y FJ('w:bz2')p 1285 2404 V 223 w FN(Open)h(for)f(bzip2)h (compressed)e(writing.)208 2502 y(Note)28 b(that)g FJ('a:gz')g FN(or)g FJ('a:bz2')f FN(is)i(not)f(possible.)49 b(If)28 b FK(mode)f FN(is)i(not)f(suitable)g(to)h(open)e(a)h(certain)g (\(compressed\))e(\002le)208 2602 y(for)f(reading,)h FJ(ReadError)f FN(is)i(raised.)42 b(Use)27 b FK(mode)e FJ('r')h FN(to)h(a)n(v)n(oid)f(this.)43 b(If)26 b(a)g(compression)e (method)h(is)i(not)f(supported,)208 2701 y FJ(CompressionError)17 b FN(is)k(raised.)208 2834 y(If)e FK(\002leobj)g FN(is)i(speci\002ed,)f (it)g(is)h(used)f(as)h(an)e(alternati)n(v)o(e)g(to)h(a)h(\002le)f (object)g(opened)e(for)h FK(name)p FN(.)24 b(It)d(is)f(supposed)f(to)h (be)g(at)g(position)208 2934 y(0.)208 3066 y(F)o(or)27 b(special)h(purposes,)h(there)e(is)i(a)f(second)g(format)e(for)i FK(mode)p FN(:)40 b FJ('filemode|[compression]')p FN(.)k FJ(open\(\))28 b FN(will)208 3166 y(return)e(a)i FJ(TarFile)e FN(object)h(that)h(processes)f(its)h(data)g(as)g(a)g(stream)f(of)g (blocks.)46 b(No)28 b(random)d(seeking)i(will)h(be)g(done)e(on)208 3266 y(the)21 b(\002le.)31 b(If)21 b(gi)n(v)o(en,)g FK(\002leobj)g FN(may)g(be)h(an)o(y)f(object)g(that)h(has)g(a)g FJ(read\(\))f FN(or)g FJ(write\(\))g FN(method)g(\(depending)e(on)i(the)h FK(mode)p FN(\).)208 3365 y FK(b)n(ufsize)31 b FN(speci\002es)g(the)g (blocksize)f(and)g(def)o(aults)h(to)g FJ(20)1953 3380 y(*)2053 3365 y(512)f FN(bytes.)57 b(Use)32 b(this)f(v)n(ariant)f(in)h (combination)d(with)j(e.g.)208 3465 y FJ(sys.stdin)p FN(,)21 b(a)i(sock)o(et)g(\002le)g(object)f(or)h(a)g(tape)f(de)n(vice.) 32 b(Ho)n(we)n(v)o(er)m(,)21 b(such)h(a)h FJ(TarFile)f FN(object)g(is)i(limited)e(in)h(that)f(it)i(does)208 3565 y(not)19 b(allo)n(w)i(to)f(be)g(accessed)g(randomly)-5 b(,)18 b(see)i(\223Examples\224)f(\(section)h(12.5.3\).)j(The)c (currently)g(possible)h(modes:)741 3694 y FL(Mode)p 1065 3724 V 172 w(Action)p 618 3727 2872 4 v 718 3797 a FJ('r|)868 3812 y(*)918 3797 y(')p 1065 3827 4 100 v 148 w FN(Open)g(a)g FK(str)m(eam)h FN(of)f(tar)g(blocks)g(for)f(reading)g(with)i (transparent)d(compression.)743 3896 y FJ('r|')p 1065 3926 V 173 w FN(Open)i(a)g FK(str)m(eam)h FN(of)f(uncompressed)e(tar)i (blocks)g(for)f(reading.)693 3996 y FJ('r|gz')p 1065 4026 V 123 w FN(Open)h(a)g(gzip)g(compressed)f FK(str)m(eam)i FN(for)e(reading.)668 4096 y FJ('r|bz2')p 1065 4126 V 98 w FN(Open)h(a)g(bzip2)g(compressed)e FK(str)m(eam)j FN(for)f(reading.)743 4195 y FJ('w|')p 1065 4225 V 173 w FN(Open)g(an)g(uncompressed)e FK(str)m(eam)i FN(for)g(writing.)693 4295 y FJ('w|gz')p 1065 4325 V 123 w FN(Open)g(an)g(gzip)g(compressed)e FK(str)m(eam)j FN(for)f(writing.)668 4395 y FJ('w|bz2')p 1065 4424 V 98 w FN(Open)g(an)g(bzip2)f(compressed)g FK(str)m(eam)i FN(for)e(writing.)0 4536 y FL(class)i FD(TarFile)208 4635 y FN(Class)32 b(for)d(reading)h(and)f(writing)h (tar)h(archi)n(v)o(es.)55 b(Do)30 b(not)h(use)f(this)h(class)h (directly)-5 b(,)32 b(better)e(use)g FJ(open\(\))g FN(instead.)56 b(See)208 4735 y(\223T)-7 b(arFile)20 b(Objects\224)g(\(section)g (12.5.1\).)0 4882 y FD(is_tarfile)p FJ(\()p FK(name)p FJ(\))208 4982 y FN(Return)f FJ(True)h FN(if)h FK(name)e FN(is)i(a)g(tar)f(archi)n(v)o(e)f(\002le,)i(that)f(the)g FJ(tarfile)g FN(module)f(can)h(read.)0 5128 y FL(class)h FD(TarFileCompat)p FJ(\()p FK(\002lename)p FC([)p FK(,)16 b(mode)p FC([)p FK(,)j(compr)m(ession)12 b FC(])g(])p FJ(\))208 5228 y FN(Class)21 b(for)e(limited)h(access)g(to)g(tar)g (archi)n(v)o(es)e(with)i(a)h FJ(zipfile)p FN(-lik)o(e)d(interf)o(ace.) 24 b(Please)c(consult)f(the)h(documentation)d(of)j(the)208 5328 y FJ(zipfile)f FN(module)g(for)g(more)h(details.)25 b FK(compr)m(ession)19 b FN(must)i(be)f(one)f(of)h(the)g(follo)n(wing)f (constants:)p 0 5549 3901 4 v 0 5649 a FI(352)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 353 365 TeXDict begin 353 364 bop 208 83 a FD(TAR_PLAIN)390 183 y FN(Constant)20 b(for)g(an)g(uncompressed)e(tar)i(archi)n(v)o(e.)208 315 y FD(TAR_GZIPPED)390 415 y FN(Constant)g(for)g(a)g FJ(gzip)g FN(compressed)f(tar)h(archi)n(v)o(e.)0 562 y FL(exception)f FD(TarError)208 662 y FN(Base)i(class)g(for)e(all)i FJ(tarfile)f FN(e)o(xceptions.)0 808 y FL(exception)f FD(ReadError)208 908 y FN(Is)24 b(raised)h(when)e(a)i(tar)f(archi)n(v)o (e)f(is)j(opened,)d(that)i(either)e(cannot)h(be)g(handled)f(by)h(the)g FJ(tarfile)g FN(module)f(or)h(is)h(someho)n(w)208 1008 y(in)m(v)n(alid.)0 1155 y FL(exception)19 b FD(CompressionError)208 1254 y FN(Is)h(raised)g(when)g(a)g(compression)f(method)g(is)i(not)f (supported)e(or)i(when)f(the)i(data)f(cannot)f(be)h(decoded)e(properly) -5 b(.)0 1401 y FL(exception)19 b FD(StreamError)208 1501 y FN(Is)h(raised)g(for)g(the)g(limitations)g(that)g(are)g(typical) g(for)g(stream-lik)o(e)f FJ(TarFile)h FN(objects.)0 1648 y FL(exception)f FD(ExtractError)208 1747 y FN(Is)h(raised)g(for)g FK(non-fatal)e FN(errors)h(when)h(using)g FJ(extract\(\))p FN(,)e(b)n(ut)j(only)e(if)h FJ(TarFile.errorlevel)47 b(==)i(2)p FN(.)0 1894 y FL(See)21 b(Also:)0 2041 y FN(Module)e FJ(zipfile)g FN(\(section)h(12.4\):)208 2141 y(Documentation)d(of)j (the)g FJ(zipfile)g FN(standard)f(module.)0 2287 y FK(GNU)i(tar)g (manual,)d(Basic)i(T)-8 b(ar)22 b(F)-9 b(ormat)0 2387 y Fy(\()p FO(http://www)l(.gn)o(u.org/softw)o(a)o(re/)o(tar/)o(man)o(u) o(al/)o(html)p 1490 2387 23 4 v 20 w(node/tar)p 1787 2387 V 24 w(134.html#SEC134)l Fy(\))208 2487 y FN(Documentation)17 b(for)j(tar)g(archi)n(v)o(e)f(\002les,)i(including)d(GNU)j(tar)f(e)o (xtensions.)0 2772 y Fv(12.5.1)101 b(T)-12 b(arFile)28 b(Objects)0 2975 y FN(The)19 b FJ(TarFile)g FN(object)f(pro)o(vides)g (an)h(interf)o(ace)g(to)g(a)h(tar)g(archi)n(v)o(e.)j(A)d(tar)f(archi)n (v)o(e)f(is)j(a)e(sequence)g(of)g(blocks.)24 b(An)19 b(archi)n(v)o(e)f(member)0 3074 y(\(a)h(stored)f(\002le\))h(is)g(made)g (up)f(of)g(a)h(header)f(block)f(follo)n(wed)h(by)g(data)h(blocks.)k(It) c(is)h(possible,)e(to)h(store)g(a)g(\002le)g(in)g(a)g(tar)g(archi)n(v)o (e)e(se)n(v)o(eral)0 3174 y(times.)25 b(Each)20 b(archi)n(v)o(e)f (member)g(is)i(represented)d(by)i(a)h FJ(TarInfo)e FN(object,)g(see)i FK(T)-8 b(arInfo)20 b(Objects)g FN(\(section)g(12.5.2\))e(for)i (details.)0 3321 y FL(class)h FD(TarFile)p FJ(\()p FC([)p FK(name)d FC([)p FK(,)i(mode)p FC([)p FK(,)f(\002leobj)12 b FC(])g(])g(])p FJ(\))208 3420 y FN(Open)19 b(an)h FK(\(uncompr)m (essed\))e FN(tar)j(archi)n(v)o(e)e FK(name)p FN(.)24 b FK(mode)c FN(is)h(either)f FJ('r')g FN(to)g(read)g(from)f(an)h(e)o (xisting)g(archi)n(v)o(e,)f FJ('a')h FN(to)g(append)208 3520 y(data)g(to)g(an)g(e)o(xisting)g(\002le)g(or)g FJ('w')g FN(to)h(create)f(a)g(ne)n(w)g(\002le)h(o)o(v)o(erwriting)d(an)i(e)o (xisting)f(one.)25 b FK(mode)19 b FN(def)o(aults)h(to)h FJ('r')p FN(.)208 3653 y(If)g FK(\002leobj)g FN(is)i(gi)n(v)o(en,)d(it) j(is)f(used)g(for)f(reading)f(or)i(writing)f(data.)29 b(If)22 b(it)g(can)g(be)g(determined,)d FK(mode)j FN(is)g(o)o(v)o (erridden)d(by)i FK(\002leobj)p FN(')-5 b(s)208 3752 y(mode.)24 b FK(\002leobj)19 b FN(will)i(be)f(used)g(from)f(position)g (0.)208 3885 y FL(Note:)24 b FK(\002leobj)19 b FN(is)i(not)f(closed,)g (when)f FJ(TarFile)h FN(is)h(closed.)0 4032 y FD(open)p FJ(\()p FK(...)p FJ(\))208 4132 y FN(Alternati)n(v)o(e)h(constructor)-5 b(.)32 b(The)23 b FJ(open\(\))g FN(function)e(on)i(module)f(le)n(v)o (el)h(is)h(actually)f(a)g(shortcut)g(to)g(this)h(classmethod.)33 b(See)208 4231 y(section)20 b(12.5)f(for)g(details.)0 4378 y FD(getmember)p FJ(\()p FK(name)p FJ(\))208 4478 y FN(Return)g(a)i FJ(TarInfo)e FN(object)h(for)g(member)e FK(name)p FN(.)25 b(If)20 b FK(name)f FN(can)h(not)g(be)g(found)f(in)h (the)g(archi)n(v)o(e,)f FJ(KeyError)g FN(is)i(raised.)208 4611 y FL(Note:)i FN(If)17 b(a)i(member)d(occurs)h(more)g(than)g(once)g (in)h(the)g(archi)n(v)o(e,)f(its)h(last)h(occurrence)d(is)i(assumed)g (to)f(be)h(the)g(most)g(up-to-date)208 4710 y(v)o(ersion.)0 4857 y FD(getmembers)p FJ(\(\))208 4957 y FN(Return)h(the)h(members)f (of)h(the)g(archi)n(v)o(e)f(as)i(a)g(list)g(of)f FJ(TarInfo)f FN(objects.)25 b(The)19 b(list)j(has)e(the)g(same)g(order)f(as)i(the)f (members)f(in)208 5056 y(the)h(archi)n(v)o(e.)0 5203 y FD(getnames)p FJ(\(\))208 5303 y FN(Return)f(the)i(members)e(as)i(a)f (list)h(of)f(their)g(names.)25 b(It)20 b(has)h(the)f(same)g(order)f(as) i(the)f(list)i(returned)c(by)i FJ(getmembers\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(12.5.)52 b FJ(tarfile)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h(tar)f(archiv)n(e)f(\002les)1909 b(353)p eop end %%Page: 354 366 TeXDict begin 354 365 bop 0 83 a FD(list)p FJ(\()p FK(verbose=T)-5 b(rue)p FJ(\))208 183 y FN(Print)20 b(a)h(table)g(of)f(contents)g(to)h FJ(sys.stdout)p FN(.)k(If)c FK(verbose)f FN(is)i FJ(False)p FN(,)e(only)g(the)h(names)f(of)h(the)f(members)g(are)h(printed.)k(If) 208 282 y(it)20 b(is)i FJ(True)p FN(,)d(output)g(similar)i(to)f(that)g (of)g FL(ls)h(-l)g FN(is)g(produced.)0 429 y FD(next)p FJ(\(\))208 529 y FN(Return)j(the)h(ne)o(xt)f(member)f(of)h(the)h (archi)n(v)o(e)e(as)j(a)f FJ(TarInfo)f FN(object,)h(when)f FJ(TarFile)g FN(is)i(opened)d(for)h(reading.)37 b(Return)208 628 y FJ(None)20 b FN(if)g(there)g(is)h(no)f(more)f(a)n(v)n(ailable.)0 775 y FD(extractall)p FJ(\()p FC([)p FK(path)p FC([)p FK(,)e(member)o(s)12 b FC(])g(])p FJ(\))208 875 y FN(Extract)43 b(all)h(members)f(from)g(the)h(archi)n(v)o(e)f(to)h(the)g(current)e(w)o (orking)h(directory)f(or)i(directory)e FK(path)p FN(.)95 b(If)44 b(optional)208 975 y FK(member)o(s)h FN(is)h(gi)n(v)o(en,)k(it) c(must)f(be)g(a)h(subset)f(of)g(the)g(list)h(returned)e(by)h FJ(getmembers\(\))p FN(.)98 b(Directory)44 b(informa-)208 1074 y(tions)35 b(lik)o(e)h(o)n(wner)m(,)j(modi\002cation)34 b(time)i(and)f(permissions)g(are)h(set)g(after)g(all)g(members)f(ha)n (v)o(e)g(been)g(e)o(xtracted.)70 b(This)208 1174 y(is)49 b(done)e(to)h(w)o(ork)g(around)e(tw)o(o)j(problems:)80 b(A)48 b(directory')-5 b(s)47 b(modi\002cation)g(time)h(is)h(reset)g (each)f(time)g(a)h(\002le)g(is)208 1273 y(created)44 b(in)h(it.)101 b(And,)51 b(if)46 b(a)f(directory')-5 b(s)44 b(permissions)h(do)f(not)h(allo)n(w)h(writing,)k(e)o(xtracting) 44 b(\002les)i(to)f(it)h(will)g(f)o(ail.)p 208 1316 3693 17 v 208 1690 17 374 v 282 1432 a FL(W)-5 b(ar)o(ning:)59 b FN(Ne)n(v)o(er)21 b(e)o(xtract)h(archi)n(v)o(es)f(from)h(untrusted)f (sources)h(without)f(prior)h(inspection.)30 b(It)23 b(is)g(possible)f (that)h(\002les)282 1531 y(are)e(created)f(outside)g(of)g FK(path)p FN(,)g(e.g.)26 b(members)20 b(that)g(ha)n(v)o(e)h(absolute)f (\002lenames)g(starting)g(with)h FJ("/")g FN(or)f(\002lenames)h(with) 282 1631 y(tw)o(o)g(dots)f FJ("..")p FN(.)p 3883 1690 V 208 1707 3693 17 v 208 1772 a(Ne)n(w)g(in)g(v)o(ersion)f(2.5.)0 1919 y FD(extract)p FJ(\()p FK(member)r FC([)p FK(,)f(path)12 b FC(])p FJ(\))208 2018 y FN(Extract)26 b(a)i(member)d(from)i(the)g (archi)n(v)o(e)f(to)h(the)g(current)f(w)o(orking)g(directory)-5 b(,)26 b(using)h(its)h(full)f(name.)45 b(Its)28 b(\002le)g(information) 208 2118 y(is)g(e)o(xtracted)e(as)i(accurately)e(as)j(possible.)46 b FK(member)30 b FN(may)d(be)g(a)h(\002lename)f(or)g(a)h FJ(TarInfo)f FN(object.)46 b(Y)-9 b(ou)27 b(can)g(specify)g(a)208 2217 y(dif)n(ferent)18 b(directory)h(using)g FK(path)p FN(.)208 2350 y FL(Note:)27 b FN(Because)22 b(the)g FJ(extract\(\))e FN(method)h(allo)n(ws)h(random)e(access)i(to)g(a)g(tar)g(archi)n(v)o(e) e(there)i(are)f(some)h(issues)h(you)e(must)208 2450 y(tak)o(e)f(care)g (of)g(yourself.)j(See)e(the)f(description)f(for)g FJ(extractall\(\))g FN(abo)o(v)o(e.)p 208 2526 V 208 2717 17 192 v 282 2641 a FL(W)-5 b(ar)o(ning:)50 b FN(See)21 b(the)f(w)o(arning)f(for)g FJ(extractall\(\))p FN(.)p 3883 2717 V 208 2734 3693 17 v 0 2846 a FD(extractfile)p FJ(\()p FK(member)r FJ(\))208 2946 y FN(Extract)e(a)i(member)e(from)g(the)h(archi)n(v)o(e)f(as)i(a)g (\002le)g(object.)24 b FK(member)c FN(may)e(be)g(a)h(\002lename)e(or)h (a)h FJ(TarInfo)f FN(object.)23 b(If)c FK(member)208 3046 y FN(is)i(a)f(re)o(gular)f(\002le,)h(a)h(\002le-lik)o(e)f(object)g (is)h(returned.)i(If)d FK(member)i FN(is)f(a)g(link,)e(a)i(\002le-lik)o (e)f(object)g(is)h(constructed)d(from)h(the)h(link')-5 b(s)208 3145 y(tar)o(get.)24 b(If)c FK(member)i FN(is)f(none)e(of)h (the)g(abo)o(v)o(e,)e FJ(None)i FN(is)i(returned.)208 3278 y FL(Note:)67 b FN(The)41 b(\002le-lik)o(e)h(object)f(is)i (read-only)c(and)j(pro)o(vides)e(the)h(follo)n(wing)g(methods:)67 b FJ(read\(\))p FN(,)46 b FJ(readline\(\))p FN(,)208 3378 y FJ(readlines\(\))p FN(,)18 b FJ(seek\(\))p FN(,)h FJ(tell\(\))p FN(.)0 3525 y FD(add)p FJ(\()p FK(name)p FC([)p FK(,)f(ar)m(cname)p FC([)p FK(,)h(r)m(ecur)o(sive)12 b FC(])g(])p FJ(\))208 3624 y FN(Add)24 b(the)h(\002le)g FK(name)f FN(to)h(the)g(archi)n(v)o(e.)38 b FK(name)24 b FN(may)g(be)h(an)o(y)f(type)g(of)h(\002le)h(\(directory)-5 b(,)23 b(\002fo,)i(symbolic)f(link,)i(etc.\).)38 b(If)25 b(gi)n(v)o(en,)208 3724 y FK(ar)m(cname)e FN(speci\002es)i(an)f (alternati)n(v)o(e)g(name)f(for)h(the)h(\002le)g(in)f(the)h(archi)n(v)o (e.)36 b(Directories)24 b(are)h(added)e(recursi)n(v)o(ely)f(by)j(def)o (ault.)208 3823 y(This)20 b(can)g(be)g(a)n(v)n(oided)f(by)h(setting)g FK(r)m(ecur)o(sive)h FN(to)f FJ(False)p FN(;)g(the)g(def)o(ault)g(is)h FJ(True)p FN(.)0 3970 y FD(addfile)p FJ(\()p FK(tarinfo)p FC([)p FK(,)d(\002leobj)12 b FC(])p FJ(\))208 4070 y FN(Add)25 b(the)i FJ(TarInfo)e FN(object)h FK(tarinfo)f FN(to)i(the)f(archi)n(v)o(e.)42 b(If)26 b FK(\002leobj)f FN(is)i(gi)n(v)o(en,)f FK(tarinfo)p FJ(.size)f FN(bytes)h(are)g(read)g (from)f(it)i(and)208 4170 y(added)19 b(to)h(the)g(archi)n(v)o(e.)k(Y)-9 b(ou)19 b(can)h(create)g FJ(TarInfo)g FN(objects)g(using)f FJ(gettarinfo\(\))p FN(.)208 4302 y FL(Note:)33 b FN(On)25 b(W)m(indo)n(ws)f(platforms,)g FK(\002leobj)g FN(should)g(al)o(w)o(ays) h(be)g(opened)e(with)i(mode)f FJ('rb')g FN(to)h(a)n(v)n(oid)g (irritation)f(about)g(the)208 4402 y(\002le)c(size.)0 4549 y FD(gettarinfo)p FJ(\()p FC([)p FK(name)p FC([)p FK(,)d(ar)m(cname)p FC([)p FK(,)i(\002leobj)12 b FC(])g(])g(])p FJ(\))208 4649 y FN(Create)30 b(a)h FJ(TarInfo)e FN(object)h(for)f (either)h(the)g(\002le)h FK(name)f FN(or)g(the)g(\002le)h(object)e FK(\002leobj)h FN(\(using)f FJ(os.fstat\(\))g FN(on)h(its)h(\002le)208 4748 y(descriptor\).)25 b(Y)-9 b(ou)20 b(can)h(modify)e(some)i(of)g (the)g FJ(TarInfo)p FN(')-5 b(s)20 b(attrib)n(utes)h(before)f(you)g (add)g(it)i(using)e FJ(addfile\(\))p FN(.)26 b(If)21 b(gi)n(v)o(en,)208 4848 y FK(ar)m(cname)e FN(speci\002es)h(an)h (alternati)n(v)o(e)d(name)i(for)g(the)g(\002le)h(in)f(the)g(archi)n(v)o (e.)0 4995 y FD(close)p FJ(\(\))208 5094 y FN(Close)g(the)h FJ(TarFile)p FN(.)j(In)c(write)g(mode,)f(tw)o(o)i(\002nishing)e(zero)h (blocks)f(are)h(appended)e(to)i(the)h(archi)n(v)o(e.)0 5241 y FD(posix)208 5341 y FN(If)e(true,)g(create)g(a)h(POSIX)g (1003.1-1990)15 b(compliant)j(archi)n(v)o(e.)23 b(GNU)d(e)o(xtensions)e (are)i(not)f(used,)g(because)g(the)o(y)f(are)i(not)f(part)p 0 5549 3901 4 v 0 5649 a FI(354)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 355 367 TeXDict begin 355 366 bop 208 83 a FN(of)20 b(the)g(POSIX)h(standard.)k (This)c(limits)g(the)f(length)g(of)g(\002lenames)h(to)f(at)h(most)g (256,)e(link)i(names)f(to)g(100)g(characters)g(and)g(the)208 183 y(maximum)g(\002le)i(size)h(to)f(8)f(gigabytes.)29 b(A)22 b FJ(ValueError)f FN(is)h(raised)g(if)g(a)g(\002le)h(e)o(xceeds) e(this)h(limit.)30 b(If)22 b(f)o(alse,)g(create)g(a)g(GNU)208 282 y(tar)d(compatible)g(archi)n(v)o(e.)k(It)d(will)g(not)f(be)h(POSIX) g(compliant,)e(b)n(ut)i(can)f(store)h(\002les)h(without)d(an)o(y)h(of)h (the)f(abo)o(v)o(e)f(restrictions.)208 382 y(Changed)g(in)j(v)o(ersion) e(2.4:)g FK(posix)i FN(def)o(aults)e(to)i FJ(False)p FN(.)0 529 y FD(dereference)208 628 y FN(If)i(f)o(alse,)i(add)e (symbolic)g(and)g(hard)g(links)h(to)g(archi)n(v)o(e.)35 b(If)23 b(true,)h(add)g(the)f(content)g(of)h(the)g(tar)o(get)e(\002les) j(to)f(the)g(archi)n(v)o(e.)34 b(This)208 728 y(has)20 b(no)g(ef)n(fect)f(on)h(systems)h(that)f(do)g(not)g(support)f(symbolic) g(links.)0 875 y FD(ignore_zeros)208 975 y FN(If)h(f)o(alse,)i(treat)f (an)g(empty)f(block)g(as)i(the)f(end)g(of)f(the)h(archi)n(v)o(e.)27 b(If)20 b(true,)h(skip)g(empty)f(\(and)g(in)m(v)n(alid\))g(blocks)g (and)h(try)g(to)g(get)g(as)208 1074 y(man)o(y)e(members)g(as)i (possible.)j(This)d(is)g(only)e(useful)h(for)f(concatenated)f(or)i (damaged)f(archi)n(v)o(es.)0 1221 y FD(debug=0)208 1321 y FN(T)-7 b(o)24 b(be)f(set)i(from)e FJ(0)h FN(\(no)f(deb)n(ug)g (messages;)j(the)e(def)o(ault\))e(up)i(to)g FJ(3)g FN(\(all)g(deb)n(ug) f(messages\).)35 b(The)24 b(messages)g(are)g(written)f(to)208 1420 y FJ(sys.stderr)p FN(.)0 1567 y FD(errorlevel)208 1667 y FN(If)e FJ(0)h FN(\(the)g(def)o(ault\),)f(all)h(errors)f(are)h (ignored)e(when)h(using)g FJ(extract\(\))p FN(.)29 b(Ne)n(v)o (ertheless,)21 b(the)o(y)g(appear)f(as)j(error)d(messages)208 1766 y(in)28 b(the)g(deb)n(ug)f(output,)h(when)g(deb)n(ugging)d(is)k (enabled.)47 b(If)28 b FJ(1)p FN(,)i(all)f FK(fatal)f FN(errors)f(are)h(raised)g(as)g FJ(OSError)g FN(or)f FJ(IOError)208 1866 y FN(e)o(xceptions.)c(If)d FJ(2)p FN(,)g(all)h FK(non-fatal)d FN(errors)i(are)g(raised)g(as)h FJ(TarError)e FN(e)o(xceptions)f(as)j(well.)0 2151 y Fv(12.5.2)101 b(T)-12 b(arInf)m(o)28 b(Objects)0 2354 y FN(A)19 b FJ(TarInfo)f FN(object)f(represents)h(one)g(member)f(in)h (a)h FJ(TarFile)p FN(.)24 b(Aside)19 b(from)e(storing)h(all)h(required) d(attrib)n(utes)j(of)f(a)g(\002le)i(\(lik)o(e)e(\002le)0 2453 y(type,)23 b(size,)i(time,)f(permissions,)f(o)n(wner)g(etc.\),)h (it)g(pro)o(vides)d(some)i(useful)g(methods)g(to)g(determine)f(its)j (type.)34 b(It)23 b(does)h FK(not)f FN(contain)0 2553 y(the)d(\002le')-5 b(s)21 b(data)g(itself.)0 2700 y FJ(TarInfo)e FN(objects)h(are)h(returned)d(by)i FJ(TarFile)p FN(')-5 b(s)20 b(methods)f FJ(getmember\(\))p FN(,)f FJ(getmembers\(\))h FN(and)g FJ(gettarinfo\(\))p FN(.)0 2847 y FL(class)i FD(TarInfo)p FJ(\()p FC([)p FK(name)12 b FC(])p FJ(\))208 2946 y FN(Create)20 b(a)h FJ(TarInfo)e FN(object.)0 3093 y FD(frombuf)p FJ(\(\))208 3193 y FN(Create)h(and)g(return)f(a)h FJ(TarInfo)g FN(object)f(from)h(a)g(string)g(b)n(uf)n(fer)-5 b(.)0 3340 y FD(tobuf)p FJ(\()p FK(posix)p FJ(\))208 3439 y FN(Create)23 b(a)g(string)f(b)n(uf)n(fer)g(from)f(a)j FJ(TarInfo)e FN(object.)32 b(See)23 b FJ(TarFile)p FN(')-5 b(s)22 b FJ(posix)h FN(attrib)n(ute)f(for)g(information)f(on)h(the)h FK(posix)208 3539 y FN(ar)o(gument.)f(It)f(def)o(aults)e(to)i FJ(False)p FN(.)208 3672 y(Ne)n(w)f(in)g(v)o(ersion)f(2.5:)h(The)g FK(posix)g FN(parameter)-5 b(.)0 3819 y(A)21 b FJ(TarInfo)e FN(object)h(has)g(the)g(follo)n(wing)f(public)g(data)h(attrib)n(utes:)0 3966 y FD(name)208 4065 y FN(Name)g(of)f(the)i(archi)n(v)o(e)d(member) -5 b(.)0 4212 y FD(size)208 4312 y FN(Size)20 b(in)h(bytes.)0 4459 y FD(mtime)208 4558 y FN(T)m(ime)f(of)g(last)h(modi\002cation.)0 4705 y FD(mode)208 4805 y FN(Permission)e(bits.)0 4952 y FD(type)208 5051 y FN(File)27 b(type.)42 b FK(type)26 b FN(is)i(usually)d(one)h(of)g(these)h(constants:)37 b FJ(REGTYPE)p FN(,)25 b FJ(AREGTYPE)p FN(,)g FJ(LNKTYPE)p FN(,)g FJ(SYMTYPE)p FN(,)h FJ(DIRTYPE)p FN(,)208 5151 y FJ(FIFOTYPE)p FN(,)d FJ(CONTTYPE)p FN(,)h FJ(CHRTYPE)p FN(,)g FJ(BLKTYPE)p FN(,)g FJ(GNUTYPE_SPARSE)p FN(.)e(T)-7 b(o)26 b(determine)d(the)i(type)f(of)h(a)g FJ(TarInfo)208 5251 y FN(object)19 b(more)h(con)m(v)o(eniently)-5 b(,)16 b(use)k(the)h FJ(is_)1487 5266 y(*)1537 5251 y(\(\))e FN(methods)g(belo)n(w)-5 b(.)0 5397 y FD(linkname)p 0 5549 3901 4 v 0 5649 a FI(12.5.)52 b FJ(tarfile)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h(tar)f(archiv)n(e)f(\002les)1909 b(355)p eop end %%Page: 356 368 TeXDict begin 356 367 bop 208 83 a FN(Name)20 b(of)f(the)i(tar)o(get)e (\002le)i(name,)e(which)h(is)h(only)e(present)h(in)g FJ(TarInfo)g FN(objects)g(of)g(type)f FJ(LNKTYPE)h FN(and)f FJ(SYMTYPE)p FN(.)0 230 y FD(uid)208 330 y FN(User)h(ID)g(of)g(the)h (user)f(who)f(originally)g(stored)h(this)g(member)-5 b(.)0 476 y FD(gid)208 576 y FN(Group)18 b(ID)j(of)f(the)g(user)g(who)g (originally)e(stored)i(this)h(member)-5 b(.)0 723 y FD(uname)208 823 y FN(User)20 b(name.)0 969 y FD(gname)208 1069 y FN(Group)e(name.)0 1216 y(A)j FJ(TarInfo)e FN(object)h(also)g(pro)o (vides)f(some)h(con)m(v)o(enient)d(query)i(methods:)0 1363 y FD(isfile)p FJ(\(\))208 1462 y FN(Return)g FJ(True)h FN(if)h(the)f FJ(Tarinfo)f FN(object)h(is)h(a)g(re)o(gular)d(\002le.)0 1609 y FD(isreg)p FJ(\(\))208 1709 y FN(Same)i(as)h FJ(isfile\(\))p FN(.)0 1856 y FD(isdir)p FJ(\(\))208 1955 y FN(Return)e FJ(True)h FN(if)h(it)g(is)g(a)f(directory)-5 b(.)0 2102 y FD(issym)p FJ(\(\))208 2202 y FN(Return)19 b FJ(True)h FN(if)h(it)g(is)g(a)f(symbolic)g(link.)0 2349 y FD(islnk)p FJ(\(\))208 2448 y FN(Return)f FJ(True)h FN(if)h(it)g(is)g(a)f(hard)g (link.)0 2595 y FD(ischr)p FJ(\(\))208 2695 y FN(Return)f FJ(True)h FN(if)h(it)g(is)g(a)f(character)f(de)n(vice.)0 2842 y FD(isblk)p FJ(\(\))208 2941 y FN(Return)g FJ(True)h FN(if)h(it)g(is)g(a)f(block)g(de)n(vice.)0 3088 y FD(isfifo)p FJ(\(\))208 3188 y FN(Return)f FJ(True)h FN(if)h(it)g(is)g(a)f(FIFO.)0 3335 y FD(isdev)p FJ(\(\))208 3434 y FN(Return)f FJ(True)h FN(if)h(it)g(is)g(one)e(of)h(character)f(de)n(vice,)g(block)h(de)n (vice)f(or)h(FIFO.)0 3719 y Fv(12.5.3)101 b(Examples)0 3922 y FN(Ho)n(w)20 b(to)g(e)o(xtract)g(an)g(entire)g(tar)g(archi)n(v)o (e)f(to)h(the)g(current)f(w)o(orking)g(directory:)236 4160 y FA(import)44 b(tarfile)236 4252 y(tar)h(=)f (tarfile.open\("sample.tar.gz"\))236 4343 y(tar.extractall\(\))236 4434 y(tar.close\(\))0 4721 y FN(Ho)n(w)20 b(to)g(create)g(an)g (uncompressed)e(tar)j(archi)n(v)o(e)d(from)h(a)i(list)g(of)f (\002lenames:)p 0 5549 3901 4 v 0 5649 a FI(356)2063 b(Chapter)24 b(12.)52 b(Data)23 b(Compression)g(and)h(Archiving)p eop end %%Page: 357 369 TeXDict begin 357 368 bop 236 174 a FA(import)44 b(tarfile)236 266 y(tar)h(=)f(tarfile.open\("sample.tar",)d("w"\))236 357 y(for)k(name)f(in)g(["foo",)g("bar",)g("quux"]:)416 448 y(tar.add\(name\))236 540 y(tar.close\(\))0 826 y FN(Ho)n(w)20 b(to)g(read)g(a)h(gzip)e(compressed)g(tar)h(archi)n(v)o(e) f(and)h(display)f(some)h(member)f(information:)236 1064 y FA(import)44 b(tarfile)236 1156 y(tar)h(=)f (tarfile.open\("sample.tar.gz",)c("r:gz"\))236 1247 y(for)45 b(tarinfo)e(in)i(tar:)416 1338 y(print)f(tarinfo.name,)e("is",)i (tarinfo.size,)f("bytes)h(in)g(size)g(and)h(is",)416 1430 y(if)f(tarinfo.isreg\(\):)595 1521 y(print)g("a)g(regular)g (file.")416 1612 y(elif)g(tarinfo.isdir\(\):)595 1704 y(print)g("a)g(directory.")416 1795 y(else:)595 1886 y(print)g("something)f(else.")236 1978 y(tar.close\(\))0 2264 y FN(Ho)n(w)20 b(to)g(create)g(a)h(tar)f(archi)n(v)o(e)f(with)h(f) o(ak)o(ed)g(information:)236 2502 y FA(import)44 b(tarfile)236 2594 y(tar)h(=)f(tarfile.open\("sample.tar.gz",)c("w:gz"\))236 2685 y(for)45 b(name)f(in)g(namelist:)416 2776 y(tarinfo)f(=)i (tar.gettarinfo\(name,)c("fakeproj-1.0/")i(+)h(name\))416 2868 y(tarinfo.uid)f(=)h(123)416 2959 y(tarinfo.gid)f(=)h(456)416 3050 y(tarinfo.uname)e(=)j("johndoe")416 3142 y(tarinfo.gname)d(=)j ("fake")416 3233 y(tar.addfile\(tarinfo,)c(file\(name\)\))236 3324 y(tar.close\(\))0 3611 y FN(The)20 b FK(only)g FN(w)o(ay)g(to)g(e) o(xtract)g(an)g(uncompressed)d(tar)k(stream)f(from)f FJ(sys.stdin)p FN(:)236 3849 y FA(import)44 b(sys)236 3940 y(import)g(tarfile)236 4032 y(tar)h(=)f(tarfile.open\(mode="r|",)d (fileobj=sys.stdin\))236 4123 y(for)k(tarinfo)e(in)i(tar:)416 4214 y(tar.extract\(tarinfo\))236 4306 y(tar.close\(\))p 0 5549 3901 4 v 0 5649 a FI(12.5.)52 b FJ(tarfile)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h(tar)f(archiv)n(e)f(\002les)1909 b(357)p eop end %%Page: 358 370 TeXDict begin 358 369 bop 0 5549 3901 4 v 0 5649 a FI(358)p eop end %%Page: 359 371 TeXDict begin 359 370 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3305 427 y FG(THIR)n(TEEN)p 0 515 V 2338 978 a FT(Data)57 b(P)-10 b(ersistence)0 1457 y FN(The)27 b(modules)f(described)g(in)h (this)h(chapter)e(support)g(storing)g(Python)g(data)h(in)g(a)h (persistent)f(form)f(on)h(disk.)46 b(The)27 b FJ(pickle)f FN(and)0 1556 y FJ(marshal)h FN(modules)f(can)h(turn)g(man)o(y)f (Python)h(data)g(types)g(into)g(a)h(stream)g(of)f(bytes)g(and)g(then)g (recreate)f(the)i(objects)f(from)g(the)0 1656 y(bytes.)32 b(The)23 b(v)n(arious)e(DBM-related)h(modules)g(support)f(a)i(f)o (amily)f(of)h(hash-based)e(\002le)i(formats)f(that)h(store)f(a)h (mapping)e(of)i(strings)0 1756 y(to)h(other)f(strings.)35 b(The)24 b FJ(bsddb)f FN(module)g(also)h(pro)o(vides)e(such)h (disk-based)g(string-to-string)e(mappings)h(based)i(on)f(hashing,)g (and)0 1855 y(also)e(supports)e(B-T)m(ree)h(and)f(record-based)f (formats.)0 2002 y(The)i(list)h(of)f(modules)f(described)g(in)h(this)h (chapter)e(is:)50 2145 y FD(pickle)198 b FN(Con)m(v)o(ert)19 b(Python)g(objects)h(to)g(streams)g(of)g(bytes)g(and)g(back.)50 2245 y FD(cPickle)148 b FN(F)o(aster)20 b(v)o(ersion)f(of)h FJ(pickle)p FN(,)g(b)n(ut)g(not)g(subclassable.)50 2345 y FD(copy_reg)98 b FN(Re)o(gister)20 b FJ(pickle)g FN(support)f (functions.)50 2444 y FD(shelve)198 b FN(Python)19 b(object)h (persistence.)50 2544 y FD(marshal)148 b FN(Con)m(v)o(ert)19 b(Python)g(objects)h(to)g(streams)g(of)g(bytes)g(and)g(back)f(\(with)h (dif)n(ferent)f(constraints\).)50 2643 y FD(anydbm)198 b FN(Generic)19 b(interf)o(ace)h(to)g(DBM-style)g(database)g(modules.) 50 2743 y FD(whichdb)148 b FN(Guess)21 b(which)e(DBM-style)i(module)d (created)i(a)g(gi)n(v)o(en)f(database.)50 2843 y FD(dbm)348 b FN(The)20 b(standard)f(\223database\224)g(interf)o(ace,)g(based)h(on) g(ndbm.)50 2942 y FD(gdbm)298 b FN(GNU')-5 b(s)21 b(reinterpretation)c (of)j(dbm.)50 3042 y FD(dbhash)198 b FN(DBM-style)20 b(interf)o(ace)g(to)g(the)g(BSD)h(database)f(library)-5 b(.)50 3142 y FD(bsddb)248 b FN(Interf)o(ace)19 b(to)h(Berk)o(ele)o(y)g (DB)h(database)e(library)50 3241 y FD(dumbdbm)148 b FN(Portable)19 b(implementation)f(of)i(the)g(simple)h(DBM)g(interf)o(ace.)50 3341 y FD(sqlite3)148 b FN(A)21 b(DB-API)f(2.0)g(implementation)e (using)h(SQLite)i(3.x.)0 3643 y FE(13.1)121 b Fx(pickle)32 b FE(\227)h(Python)h(object)g(ser)r(ialization)0 3876 y FN(The)24 b FJ(pickle)g FN(module)f(implements)h(a)g(fundamental,)f (b)n(ut)i(po)n(werful)d(algorithm)h(for)h(serializing)g(and)g (de-serializing)f(a)i(Python)0 3976 y(object)i(structure.)48 b(\223Pickling\224)27 b(is)h(the)g(process)g(whereby)e(a)i(Python)f (object)h(hierarchy)d(is)k(con)m(v)o(erted)c(into)j(a)g(byte)g(stream,) h(and)0 4075 y(\223unpickling\224)18 b(is)j(the)f(in)m(v)o(erse)f (operation,)g(whereby)f(a)j(byte)f(stream)g(is)h(con)m(v)o(erted)d (back)h(into)h(an)h(object)e(hierarchy)-5 b(.)23 b(Pickling)c(\(and)0 4175 y(unpickling\))f(is)j(alternati)n(v)o(ely)e(kno)n(wn)g(as)i (\223serialization\224,)e(\223marshalling,)-6 b(\224)2252 4145 y FF(1)2304 4175 y FN(or)20 b(\223\003attening\224,)f(ho)n(we)n(v) o(er)m(,)f(to)i(a)n(v)n(oid)g(confusion,)f(the)0 4275 y(terms)h(used)g(here)g(are)g(\223pickling\224)f(and)g (\223unpickling\224.)0 4422 y(This)h(documentation)e(describes)h(both)h (the)g FJ(pickle)f FN(module)g(and)h(the)g FJ(cPickle)g FN(module.)0 4706 y Fv(13.1.1)101 b(Relationship)29 b(to)f(other)h (Python)g(modules)0 4909 y FN(The)17 b FJ(pickle)g FN(module)f(has)h (an)h(optimized)e(cousin)g(called)h(the)h FJ(cPickle)e FN(module.)23 b(As)18 b(its)g(name)f(implies,)h FJ(cPickle)f FN(is)h(written)0 5009 y(in)j(C,)g(so)g(it)h(can)e(be)h(up)f(to)h(1000) e(times)i(f)o(aster)g(than)f FJ(pickle)p FN(.)26 b(Ho)n(we)n(v)o(er)19 b(it)j(does)e(not)g(support)g(subclassing)g(of)g(the)h FJ(Pickler\(\))0 5109 y FN(and)i FJ(Unpickler\(\))g FN(classes,)i (because)e(in)h FJ(cPickle)g FN(these)g(are)f(functions,)g(not)h (classes.)37 b(Most)24 b(applications)f(ha)n(v)o(e)g(no)g(need)0 5208 y(for)d(this)i(functionality)-5 b(,)19 b(and)h(can)h(bene\002t)g (from)f(the)h(impro)o(v)o(ed)e(performance)f(of)j FJ(cPickle)p FN(.)27 b(Other)20 b(than)h(that,)g(the)g(interf)o(aces)g(of)p 0 5279 1560 4 v 90 5335 a FB(1)120 5358 y FH(Don')o(t)c(confuse)h(this) g(with)f(the)h Fz(marshal)e FH(module)p 0 5549 3901 4 v 3762 5649 a FI(359)p eop end %%Page: 360 372 TeXDict begin 360 371 bop 0 83 a FN(the)26 b(tw)o(o)g(modules)f(are)h (nearly)f(identical;)k(the)d(common)e(interf)o(ace)h(is)i(described)e (in)h(this)g(manual)f(and)h(dif)n(ferences)e(are)i(pointed)0 183 y(out)21 b(where)g(necessary)-5 b(.)27 b(In)21 b(the)g(follo)n (wing)f(discussions,)h(we)h(use)f(the)h(term)f(\223pickle\224)f(to)i (collecti)n(v)o(ely)e(describe)g(the)h FJ(pickle)g FN(and)0 282 y FJ(cPickle)e FN(modules.)0 429 y(The)h(data)g(streams)g(the)h(tw) o(o)f(modules)f(produce)f(are)i(guaranteed)e(to)j(be)f (interchangeable.)0 576 y(Python)28 b(has)i(a)f(more)g(primiti)n(v)o(e) f(serialization)h(module)f(called)h FJ(marshal)p FN(,)h(b)n(ut)g(in)f (general)f FJ(pickle)h FN(should)g(al)o(w)o(ays)g(be)h(the)0 676 y(preferred)18 b(w)o(ay)i(to)h(serialize)f(Python)f(objects.)25 b FJ(marshal)19 b FN(e)o(xists)i(primarily)d(to)j(support)e(Python')-5 b(s)19 b(`)p FO(.p)n(yc)p FN(')h(\002les.)0 823 y(The)g FJ(pickle)f FN(module)g(dif)n(fers)h(from)f FJ(marshal)g FN(se)n(v)o(eral)h(signi\002cant)g(w)o(ays:)125 1047 y FM(\017)41 b FN(The)26 b FJ(pickle)g FN(module)f(k)o(eeps)i(track)f (of)g(the)h(objects)f(it)i(has)f(already)e(serialized,)j(so)f(that)g (later)g(references)e(to)i(the)f(same)208 1147 y(object)19 b(w)o(on')o(t)g(be)h(serialized)g(again.)k FJ(marshal)c FN(doesn')o(t)e(do)i(this.)208 1279 y(This)k(has)h(implications)e(both) g(for)h(recursi)n(v)o(e)f(objects)h(and)g(object)f(sharing.)36 b(Recursi)n(v)o(e)24 b(objects)g(are)g(objects)g(that)h(contain)208 1378 y(references)17 b(to)i(themselv)o(es.)24 b(These)18 b(are)h(not)f(handled)f(by)i(marshal,)f(and)g(in)h(f)o(act,)g (attempting)e(to)i(marshal)g(recursi)n(v)o(e)e(objects)208 1478 y(will)h(crash)f(your)f(Python)h(interpreter)-5 b(.)23 b(Object)17 b(sharing)g(happens)f(when)h(there)g(are)g(multiple) g(references)f(to)i(the)f(same)h(object)208 1578 y(in)j(dif)n(ferent)f (places)h(in)g(the)h(object)f(hierarchy)d(being)j(serialized.)28 b FJ(pickle)20 b FN(stores)i(such)f(objects)g(only)g(once,)f(and)h (ensures)208 1677 y(that)j(all)h(other)f(references)f(point)h(to)g(the) h(master)f(cop)o(y)-5 b(.)36 b(Shared)24 b(objects)g(remain)g(shared,)g (which)g(can)g(be)h(v)o(ery)e(important)208 1777 y(for)c(mutable)g (objects.)125 1941 y FM(\017)41 b FJ(marshal)24 b FN(cannot)h(be)h (used)f(to)h(serialize)g(user)n(-de\002ned)e(classes)j(and)e(their)g (instances.)41 b FJ(pickle)26 b FN(can)f(sa)n(v)o(e)h(and)f(restore)208 2041 y(class)h(instances)g(transparently)-5 b(,)24 b(ho)n(we)n(v)o(er)g (the)h(class)i(de\002nition)e(must)g(be)h(importable)e(and)h(li)n(v)o (e)g(in)h(the)g(same)g(module)e(as)208 2140 y(when)19 b(the)h(object)g(w)o(as)h(stored.)125 2304 y FM(\017)41 b FN(The)18 b FJ(marshal)f FN(serialization)h(format)f(is)i(not)f (guaranteed)f(to)h(be)g(portable)f(across)i(Python)e(v)o(ersions.)23 b(Because)c(its)g(primary)208 2404 y(job)h(in)g(life)h(is)h(to)e (support)f(`)p FO(.p)n(yc)p FN(')h(\002les,)i(the)e(Python)g (implementers)f(reserv)o(e)g(the)i(right)e(to)i(change)e(the)i (serialization)f(format)208 2504 y(in)f(non-backw)o(ards)e(compatible)h (w)o(ays)i(should)f(the)g(need)g(arise.)25 b(The)19 b FJ(pickle)g FN(serialization)g(format)g(is)h(guaranteed)e(to)i(be)208 2603 y(backw)o(ards)e(compatible)h(across)h(Python)f(releases.)p 0 2771 3901 17 v 0 3062 17 292 v 75 2887 a FL(W)-5 b(ar)o(ning:)56 b FN(The)21 b FJ(pickle)h FN(module)e(is)j(not)e(intended)g(to)h(be)f (secure)h(against)f(erroneous)f(or)h(maliciously)g(constructed)f(data.) 75 2986 y(Ne)n(v)o(er)f(unpickle)g(data)h(recei)n(v)o(ed)e(from)i(an)g (untrusted)e(or)i(unauthenticated)e(source.)p 3883 3062 V 0 3079 3901 17 v 0 3234 a(Note)23 b(that)g(serialization)f(is)i(a)f (more)g(primiti)n(v)o(e)e(notion)h(than)g(persistence;)i(although)d FJ(pickle)i FN(reads)f(and)h(writes)g(\002le)h(objects,)f(it)0 3334 y(does)j(not)g(handle)g(the)g(issue)h(of)f(naming)g(persistent)g (objects,)h(nor)f(the)g(\(e)n(v)o(en)g(more)f(complicated\))g(issue)i (of)f(concurrent)e(access)0 3433 y(to)i(persistent)f(objects.)41 b(The)25 b FJ(pickle)h FN(module)e(can)h(transform)f(a)i(comple)o(x)e (object)h(into)h(a)g(byte)f(stream)g(and)g(it)i(can)e(transform)0 3533 y(the)e(byte)f(stream)g(into)g(an)h(object)f(with)h(the)f(same)h (internal)f(structure.)31 b(Perhaps)22 b(the)g(most)h(ob)o(vious)e (thing)h(to)g(do)h(with)f(these)h(byte)0 3633 y(streams)18 b(is)h(to)f(write)g(them)g(onto)f(a)h(\002le,)h(b)n(ut)f(it)g(is)h (also)f(concei)n(v)n(able)e(to)i(send)g(them)f(across)h(a)g(netw)o(ork) f(or)h(store)g(them)f(in)h(a)g(database.)0 3732 y(The)i(module)f FJ(shelve)g FN(pro)o(vides)g(a)h(simple)h(interf)o(ace)e(to)h(pickle)g (and)g(unpickle)e(objects)i(on)g(DBM-style)g(database)g(\002les.)0 4016 y Fv(13.1.2)101 b(Data)28 b(stream)g(f)m(or)r(mat)0 4219 y FN(The)20 b(data)g(format)g(used)g(by)g FJ(pickle)f FN(is)j(Python-speci\002c.)h(This)e(has)f(the)h(adv)n(antage)d(that)j (there)f(are)g(no)g(restrictions)g(imposed)f(by)0 4319 y(e)o(xternal)h(standards)h(such)g(as)h(XDR)g(\(which)f(can')o(t)f (represent)g(pointer)g(sharing\);)h(ho)n(we)n(v)o(er)e(it)j(means)g (that)f(non-Python)d(programs)0 4418 y(may)i(not)g(be)g(able)g(to)g (reconstruct)f(pickled)g(Python)g(objects.)0 4565 y(By)25 b(def)o(ault,)f(the)h FJ(pickle)f FN(data)g(format)f(uses)i(a)g (printable)g FH(A)t(S)t(C)t(I)t(I)j FN(representation.)36 b(This)25 b(is)g(slightly)f(more)g(v)n(oluminous)e(than)i(a)0 4665 y(binary)h(representation.)43 b(The)26 b(big)h(adv)n(antage)e(of)h (using)g(printable)i FH(A)t(S)t(C)t(I)t(I)i FN(\(and)c(of)h(some)f (other)g(characteristics)g(of)h FJ(pickle)p FN(')-5 b(s)0 4765 y(representation\))24 b(is)k(that)f(for)f(deb)n(ugging)e(or)j (reco)o(v)o(ery)d(purposes)i(it)h(is)h(possible)e(for)g(a)i(human)d(to) i(read)f(the)h(pickled)f(\002le)h(with)g(a)0 4864 y(standard)19 b(te)o(xt)h(editor)-5 b(.)0 5011 y(There)19 b(are)h(currently)f(3)h (dif)n(ferent)f(protocols)f(which)i(can)g(be)g(used)g(for)g(pickling.) 125 5236 y FM(\017)41 b FN(Protocol)19 b(v)o(ersion)g(0)h(is)h(the)f (original)f(ASCII)i(protocol)d(and)i(is)h(backw)o(ards)e(compatible)g (with)h(earlier)g(v)o(ersions)f(of)h(Python.)125 5400 y FM(\017)41 b FN(Protocol)19 b(v)o(ersion)g(1)h(is)h(the)f(old)g (binary)f(format)g(which)h(is)h(also)f(compatible)f(with)h(earlier)g(v) o(ersions)f(of)h(Python.)p 0 5549 3901 4 v 0 5649 a FI(360)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 361 373 TeXDict begin 361 372 bop 125 83 a FM(\017)41 b FN(Protocol)19 b(v)o(ersion)g(2)h(w)o(as)h(introduced)d(in)i(Python)f(2.3.)24 b(It)d(pro)o(vides)d(much)i(more)f(ef)n(\002cient)h(pickling)f(of)g(ne) n(w-style)h(classes.)0 313 y(Refer)g(to)g(PEP)h(307)f(for)f(more)h (information.)0 460 y(If)f(a)g FK(pr)l(otocol)f FN(is)i(not)f (speci\002ed,)f(protocol)f(0)i(is)h(used.)k(If)19 b FK(pr)l(otocol)f FN(is)i(speci\002ed)f(as)g(a)h(ne)o(gati)n(v)o(e)c(v)n(alue)j(or)f FJ(HIGHEST_PROTOCOL)p FN(,)0 559 y(the)i(highest)g(protocol)e(v)o (ersion)h(a)n(v)n(ailable)h(will)h(be)f(used.)0 706 y(Changed)f(in)h(v) o(ersion)f(2.3:)h(Introduced)d(the)j FK(pr)l(otocol)g FN(parameter)-5 b(.)0 853 y(A)21 b(binary)e(format,)f(which)i(is)h (slightly)f(more)f(ef)n(\002cient,)h(can)g(be)g(chosen)f(by)h (specifying)f(a)h FK(pr)l(otocol)g FN(v)o(ersion)f(\277=)h(1.)0 1138 y Fv(13.1.3)101 b(Usage)0 1341 y FN(T)-7 b(o)20 b(serialize)h(an)f(object)g(hierarchy)-5 b(,)17 b(you)i(\002rst)i (create)f(a)h(pickler)m(,)e(then)h(you)f(call)i(the)f(pickler')-5 b(s)20 b FJ(dump\(\))f FN(method.)24 b(T)-7 b(o)20 b(de-serialize)0 1441 y(a)29 b(data)f(stream,)i(you)e(\002rst)h(create)f(an)g(unpickler) m(,)g(then)g(you)g(call)h(the)f(unpickler')-5 b(s)27 b FJ(load\(\))h FN(method.)48 b(The)28 b FJ(pickle)g FN(module)0 1540 y(pro)o(vides)18 b(the)j(follo)n(wing)d(constant:)0 1687 y FD(HIGHEST_PROTOCOL)208 1787 y FN(The)h(highest)h(protocol)e(v)o (ersion)h(a)n(v)n(ailable.)25 b(This)20 b(v)n(alue)g(can)g(be)g(passed) g(as)h(a)f FK(pr)l(otocol)g FN(v)n(alue.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1934 y FL(Note:)24 b FN(Be)d(sure)e(to)h(al) o(w)o(ays)h(open)e(pickle)g(\002les)i(created)e(with)h(protocols)e (\277=)i(1)g(in)g(binary)f(mode.)k(F)o(or)d(the)g(old)f(ASCII-based)g (pickle)0 2033 y(protocol)f(0)j(you)e(can)h(use)g(either)g(te)o(xt)g (mode)f(or)h(binary)f(mode)h(as)g(long)g(as)h(you)e(stay)h(consistent.) 0 2180 y(A)j(pickle)e(\002le)i(written)f(with)g(protocol)f(0)h(in)g (binary)f(mode)h(will)g(contain)g(lone)f(linefeeds)h(as)h(line)f (terminators)f(and)g(therefore)g(will)0 2280 y(look)e(\223funn)o(y\224) f(when)i(vie)n(wed)f(in)i(Notepad)e(or)h(other)f(editors)h(which)f(do)h (not)g(support)f(this)i(format.)0 2427 y(The)f FJ(pickle)f FN(module)g(pro)o(vides)g(the)h(follo)n(wing)f(functions)f(to)j(mak)o (e)e(the)i(pickling)d(process)i(more)g(con)m(v)o(enient:)0 2573 y FD(dump)p FJ(\()p FK(obj,)f(\002le)p FC([)p FK(,)g(pr)l(otocol) 12 b FC(])p FJ(\))208 2673 y FN(Write)24 b(a)h(pickled)d (representation)g(of)i FK(obj)g FN(to)g(the)g(open)f(\002le)h(object)g FK(\002le)p FN(.)36 b(This)24 b(is)h(equi)n(v)n(alent)d(to)j FJ(Pickler\()p FK(\002le)p FJ(,)47 b FK(pr)l(oto-)208 2773 y(col)p FJ(\).dump\()p FK(obj)p FJ(\))p FN(.)208 2906 y(If)37 b(the)h FK(pr)l(otocol)f FN(parameter)g(is)i(omitted,)i (protocol)36 b(0)i(is)h(used.)78 b(If)37 b FK(pr)l(otocol)h FN(is)g(speci\002ed)g(as)h(a)f(ne)o(gati)n(v)o(e)e(v)n(alue)h(or)208 3005 y FJ(HIGHEST_PROTOCOL)p FN(,)17 b(the)j(highest)g(protocol)e(v)o (ersion)h(will)i(be)f(used.)208 3138 y(Changed)e(in)j(v)o(ersion)e (2.3:)g(Introduced)f(the)i FK(pr)l(otocol)f FN(parameter)-5 b(.)208 3271 y FK(\002le)21 b FN(must)h(ha)n(v)o(e)f(a)h FJ(write\(\))e FN(method)h(that)g(accepts)h(a)g(single)f(string)g(ar)o (gument.)27 b(It)22 b(can)f(thus)h(be)f(a)h(\002le)g(object)f(opened)f (for)208 3370 y(writing,)f(a)i FJ(StringIO)e FN(object,)g(or)h(an)o(y)g (other)f(custom)g(object)h(that)g(meets)h(this)g(interf)o(ace.)0 3517 y FD(load)p FJ(\()p FK(\002le)p FJ(\))208 3617 y FN(Read)h(a)g(string)f(from)g(the)h(open)f(\002le)h(object)f FK(\002le)h FN(and)f(interpret)g(it)i(as)f(a)g(pickle)g(data)f(stream,) h(reconstructing)d(and)j(returning)208 3717 y(the)e(original)f(object)g (hierarchy)-5 b(.)23 b(This)d(is)h(equi)n(v)n(alent)e(to)h FJ(Unpickler\()p FK(\002le)p FJ(\).load\(\))p FN(.)208 3849 y FK(\002le)d FN(must)g(ha)n(v)o(e)f(tw)o(o)i(methods,)e(a)i FJ(read\(\))e FN(method)g(that)h(tak)o(es)h(an)f(inte)o(ger)f(ar)o (gument,)f(and)h(a)i FJ(readline\(\))e FN(method)f(that)208 3949 y(requires)k(no)i(ar)o(guments.)j(Both)d(methods)f(should)f (return)h(a)h(string.)26 b(Thus)21 b FK(\002le)g FN(can)f(be)h(a)g (\002le)g(object)g(opened)e(for)h(reading,)f(a)208 4049 y FJ(StringIO)g FN(object,)g(or)h(an)o(y)g(other)f(custom)h(object)f (that)h(meets)h(this)g(interf)o(ace.)208 4181 y(This)f(function)e (automatically)h(determines)g(whether)g(the)i(data)f(stream)g(w)o(as)h (written)f(in)g(binary)f(mode)g(or)h(not.)0 4328 y FD(dumps)p FJ(\()p FK(obj)p FC([)p FK(,)e(pr)l(otocol)12 b FC(])p FJ(\))208 4428 y FN(Return)19 b(the)i(pickled)e(representation)f(of)i (the)g(object)g(as)g(a)h(string,)f(instead)g(of)g(writing)f(it)i(to)f (a)h(\002le.)208 4561 y(If)37 b(the)h FK(pr)l(otocol)f FN(parameter)g(is)i(omitted,)i(protocol)36 b(0)i(is)h(used.)78 b(If)37 b FK(pr)l(otocol)h FN(is)g(speci\002ed)g(as)h(a)f(ne)o(gati)n (v)o(e)e(v)n(alue)h(or)208 4660 y FJ(HIGHEST_PROTOCOL)p FN(,)17 b(the)j(highest)g(protocol)e(v)o(ersion)h(will)i(be)f(used.)208 4793 y(Changed)e(in)j(v)o(ersion)e(2.3:)g(The)h FK(pr)l(otocol)g FN(parameter)e(w)o(as)j(added.)0 4940 y FD(loads)p FJ(\()p FK(string)p FJ(\))208 5040 y FN(Read)i(a)h(pickled)f(object)g (hierarchy)e(from)i(a)h(string.)34 b(Characters)24 b(in)f(the)h(string) f(past)h(the)g(pickled)e(object')-5 b(s)24 b(representation)208 5139 y(are)c(ignored.)0 5286 y(The)g FJ(pickle)f FN(module)g(also)i (de\002nes)f(three)f(e)o(xceptions:)p 0 5549 3901 4 v 0 5649 a FI(13.1.)52 b FJ(pickle)22 b FI(\227)h(Python)h(object)f(ser)q (ialization)2134 b(361)p eop end %%Page: 362 374 TeXDict begin 362 373 bop 0 83 a FL(exception)19 b FD(PickleError)208 183 y FN(A)h(common)f(base)h(class)h(for)f(the)g(other)f(e)o(xceptions) g(de\002ned)g(belo)n(w)-5 b(.)24 b(This)c(inherits)g(from)f FJ(Exception)p FN(.)0 330 y FL(exception)g FD(PicklingError)208 429 y FN(This)h(e)o(xception)e(is)j(raised)f(when)g(an)g(unpicklable)e (object)i(is)h(passed)f(to)g(the)h FJ(dump\(\))e FN(method.)0 576 y FL(exception)g FD(UnpicklingError)208 676 y FN(This)37 b(e)o(xception)e(is)k(raised)e(when)f(there)h(is)h(a)g(problem)e (unpickling)f(an)i(object.)75 b(Note)38 b(that)f(other)f(e)o(xceptions) g(may)208 775 y(also)24 b(be)h(raised)f(during)f(unpickling,)g (including)g(\(b)n(ut)h(not)h(necessarily)f(limited)g(to\))g FJ(AttributeError)p FN(,)g FJ(EOFError)p FN(,)208 875 y FJ(ImportError)p FN(,)18 b(and)i FJ(IndexError)p FN(.)0 1022 y(The)g FJ(pickle)f FN(module)g(also)i(e)o(xports)e(tw)o(o)h (callables)1593 992 y FF(2)1626 1022 y FN(,)g FJ(Pickler)g FN(and)f FJ(Unpickler)p FN(:)0 1169 y FL(class)i FD(Pickler)p FJ(\()p FK(\002le)p FC([)p FK(,)d(pr)l(otocol)12 b FC(])p FJ(\))208 1268 y FN(This)20 b(tak)o(es)g(a)h(\002le-lik)o(e)f(object)g (to)g(which)g(it)h(will)g(write)f(a)h(pickle)e(data)h(stream.)208 1401 y(If)i(the)g FK(pr)l(otocol)g FN(parameter)e(is)j(omitted,)f (protocol)f(0)h(is)h(used.)31 b(If)22 b FK(pr)l(otocol)g FN(is)h(speci\002ed)f(as)h(a)g(ne)o(gati)n(v)o(e)d(v)n(alue,)i(the)g (highest)208 1501 y(protocol)c(v)o(ersion)h(will)i(be)f(used.)208 1634 y(Changed)e(in)j(v)o(ersion)e(2.3:)g(Introduced)f(the)i FK(pr)l(otocol)f FN(parameter)-5 b(.)208 1766 y FK(\002le)25 b FN(must)g(ha)n(v)o(e)f(a)h FJ(write\(\))f FN(method)g(that)h(accepts) g(a)g(single)g(string)g(ar)o(gument.)37 b(It)25 b(can)g(thus)f(be)h(an) g(open)f(\002le)i(object,)f(a)208 1866 y FJ(StringIO)19 b FN(object,)g(or)h(an)o(y)g(other)f(custom)h(object)f(that)h(meets)h (this)g(interf)o(ace.)0 2013 y FJ(Pickler)e FN(objects)h(de\002ne)g (one)g(\(or)f(tw)o(o\))h(public)g(methods:)0 2160 y FD(dump)p FJ(\()p FK(obj)p FJ(\))208 2259 y FN(Write)i(a)f(pickled)g (representation)e(of)i FK(obj)g FN(to)g(the)h(open)e(\002le)i(object)f (gi)n(v)o(en)f(in)i(the)f(constructor)-5 b(.)27 b(Either)21 b(the)g(binary)f(or)j FH(A)t(S)t(C)t(I)t(I)208 2359 y FN(format)c(will)i(be)f(used,)f(depending)f(on)i(the)g(v)n(alue)g(of)f (the)i FK(pr)l(otocol)e FN(ar)o(gument)f(passed)i(to)g(the)h (constructor)-5 b(.)0 2506 y FD(clear_memo)p FJ(\(\))208 2606 y FN(Clears)29 b(the)g(pickler')-5 b(s)29 b(\223memo\224.)50 b(The)28 b(memo)g(is)i(the)f(data)g(structure)f(that)h(remembers)e (which)i(objects)f(the)h(pickler)f(has)208 2705 y(already)23 b(seen,)i(so)f(that)h(shared)e(or)h(recursi)n(v)o(e)f(objects)h (pickled)f(by)h(reference)f(and)g(not)h(by)g(v)n(alue.)37 b(This)24 b(method)f(is)i(useful)208 2805 y(when)19 b(re-using)g (picklers.)208 2938 y FL(Note:)33 b FN(Prior)24 b(to)h(Python)f(2.3,)h FJ(clear_memo\(\))e FN(w)o(as)i(only)f(a)n(v)n(ailable)g(on)g(the)h (picklers)f(created)g(by)g FJ(cPickle)p FN(.)38 b(In)25 b(the)208 3037 y FJ(pickle)c FN(module,)g(picklers)h(ha)n(v)o(e)f(an)i (instance)e(v)n(ariable)g(called)i FJ(memo)f FN(which)f(is)i(a)g (Python)e(dictionary)-5 b(.)29 b(So)22 b(to)g(clear)h(the)208 3137 y(memo)c(for)g(a)i FJ(pickle)f FN(module)e(pickler)m(,)h(you)h (could)f(do)h(the)g(follo)n(wing:)444 3361 y FA (mypickler.memo.clear\(\))208 3550 y FN(Code)g(that)g(does)g(not)g (need)f(to)h(support)f(older)h(v)o(ersions)f(of)h(Python)f(should)g (simply)h(use)g FJ(clear_memo\(\))p FN(.)0 3697 y(It)29 b(is)g(possible)f(to)h(mak)o(e)f(multiple)f(calls)i(to)g(the)f FJ(dump\(\))g FN(method)f(of)h(the)h(same)f FJ(Pickler)g FN(instance.)49 b(These)28 b(must)h(then)f(be)0 3797 y(matched)19 b(to)h(the)h(same)f(number)e(of)i(calls)h(to)g(the)f FJ(load\(\))g FN(method)e(of)i(the)h(corresponding)16 b FJ(Unpickler)j FN(instance.)25 b(If)20 b(the)g(same)0 3897 y(object)g(is)h(pickled)e(by)h(multiple)f FJ(dump\(\))h FN(calls,)h(the)f FJ(load\(\))f FN(will)i(all)g(yield)f(references)f (to)h(the)g(same)h(object.)3348 3866 y FF(3)0 4043 y FJ(Unpickler)e FN(objects)h(are)g(de\002ned)f(as:)0 4190 y FL(class)i FD(Unpickler)p FJ(\()p FK(\002le)p FJ(\))208 4290 y FN(This)k(tak)o(es)g(a)h(\002le-lik)o(e)f(object)f(from)g(which) h(it)g(will)h(read)f(a)g(pickle)g(data)g(stream.)39 b(This)25 b(class)h(automatically)e(determines)208 4390 y(whether)17 b(the)h(data)g(stream)g(w)o(as)h(written)f(in)h(binary)d(mode)i(or)g (not,)g(so)g(it)h(does)f(not)g(need)f(a)i(\003ag)f(as)h(in)g(the)f FJ(Pickler)f FN(f)o(actory)-5 b(.)208 4522 y FK(\002le)17 b FN(must)g(ha)n(v)o(e)f(tw)o(o)i(methods,)e(a)i FJ(read\(\))e FN(method)g(that)h(tak)o(es)h(an)f(inte)o(ger)f(ar)o(gument,)f(and)h(a) i FJ(readline\(\))e FN(method)f(that)208 4622 y(requires)k(no)i(ar)o (guments.)j(Both)d(methods)f(should)f(return)h(a)h(string.)26 b(Thus)21 b FK(\002le)g FN(can)f(be)h(a)g(\002le)g(object)g(opened)e (for)h(reading,)f(a)208 4722 y FJ(StringIO)g FN(object,)g(or)h(an)o(y)g (other)f(custom)h(object)f(that)h(meets)h(this)g(interf)o(ace.)p 0 4793 1560 4 v 90 4848 a FB(2)120 4872 y FH(In)f(the)h Fz(pickle)e FH(module)j(these)f(callables)j(are)d(classes,)h(which)f (you)g(could)g(subclass)h(to)e(customize)j(the)e(beha)o(vior)l(.)33 b(Ho)n(we)n(v)o(er)m(,)23 b(in)e(the)g Fz(cPickle)e FH(module)0 4951 y(these)26 b(callables)i(are)e(f)o(actory)h(functions)g(and)f(so)f (cannot)h(be)g(subclassed.)46 b(One)26 b(common)f(reason)h(to)f (subclass)h(is)f(to)h(control)h(what)f(objects)g(can)g(actually)i(be)0 5030 y(unpickled.)23 b(See)18 b(section)g(13.1.6)f(for)g(more)g (details.)90 5087 y FB(3)120 5111 y Fw(W)-6 b(arning)p FH(:)25 b(this)19 b(is)f(intended)j(for)d(pickling)j(multiple)g (objects)f(without)g(interv)o(ening)h(modi\002cations)g(to)e(the)g (objects)h(or)f(their)g(parts.)26 b(If)18 b(you)h(modify)g(an)g(object) 0 5189 y(and)k(then)g(pickle)i(it)e(again)g(using)g(the)h(same)e Fz(Pickler)f FH(instance,)26 b(the)d(object)i(is)d(not)h(pickled)i (again)e(\227)g(a)f(reference)j(to)e(it)g(is)g(pickled)h(and)f(the)g Fz(Unpickler)0 5268 y FH(will)c(return)g(the)g(old)f(v)n(alue,)i(not)f (the)f(modi\002ed)h(one.)24 b(There)19 b(are)g(tw)o(o)f(problems)h (here:)24 b(\(1\))19 b(detecting)i(changes,)e(and)g(\(2\))f (marshalling)i(a)e(minimal)h(set)g(of)e(changes.)0 5347 y(Garbage)i(Collection)h(may)d(also)g(become)i(a)e(problem)h(here.)p 0 5549 3901 4 v 0 5649 a FI(362)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 363 375 TeXDict begin 363 374 bop 0 83 a FJ(Unpickler)19 b FN(objects)h(ha)n(v) o(e)g(one)f(\(or)h(tw)o(o\))g(public)f(methods:)0 230 y FD(load)p FJ(\(\))208 330 y FN(Read)j(a)g(pickled)f(object)h (representation)e(from)h(the)h(open)f(\002le)i(object)f(gi)n(v)o(en)e (in)j(the)f(constructor)m(,)e(and)h(return)g(the)i(reconsti-)208 429 y(tuted)c(object)h(hierarchy)e(speci\002ed)i(therein.)0 576 y FD(noload)p FJ(\(\))208 676 y FN(This)j(is)h(just)f(lik)o(e)h FJ(load\(\))e FN(e)o(xcept)g(that)h(it)h(doesn')o(t)d(actually)i (create)g(an)o(y)f(objects.)33 b(This)23 b(is)h(useful)f(primarily)e (for)i(\002nding)208 775 y(what')-5 b(s)20 b(called)g(\223persistent)g (ids\224)g(that)g(may)g(be)g(referenced)e(in)i(a)h(pickle)e(data)h (stream.)25 b(See)20 b(section)g(13.1.5)e(belo)n(w)i(for)f(more)208 875 y(details.)208 1008 y FL(Note:)31 b FN(the)23 b FJ(noload\(\))g FN(method)f(is)j(currently)d(only)h(a)n(v)n(ailable)g(on)g FJ(Unpickler)g FN(objects)g(created)g(with)h(the)f FJ(cPickle)208 1107 y FN(module.)g FJ(pickle)d FN(module)f FJ(Unpickler)p FN(s)g(do)h(not)g(ha)n(v)o(e)f(the)h FJ(noload\(\))g FN(method.)0 1392 y Fv(13.1.4)101 b(What)28 b(can)g(be)h(pic)n(kled)f (and)h(unpic)n(kled?)0 1595 y FN(The)20 b(follo)n(wing)e(types)i(can)g (be)h(pickled:)125 1825 y FM(\017)41 b FJ(None)p FN(,)19 b FJ(True)p FN(,)h(and)g FJ(False)125 1991 y FM(\017)41 b FN(inte)o(gers,)19 b(long)g(inte)o(gers,)g(\003oating)h(point)f (numbers,)f(comple)o(x)h(numbers)125 2157 y FM(\017)41 b FN(normal)19 b(and)g(Unicode)g(strings)125 2323 y FM(\017)41 b FN(tuples,)19 b(lists,)j(sets,)f(and)e(dictionaries)h(containing)e (only)h(picklable)g(objects)125 2489 y FM(\017)41 b FN(functions)18 b(de\002ned)h(at)i(the)f(top)g(le)n(v)o(el)g(of)g(a)h(module)125 2655 y FM(\017)41 b FN(b)n(uilt-in)19 b(functions)g(de\002ned)g(at)i (the)f(top)g(le)n(v)o(el)g(of)g(a)g(module)125 2821 y FM(\017)41 b FN(classes)21 b(that)f(are)g(de\002ned)f(at)i(the)f(top)g (le)n(v)o(el)g(of)g(a)h(module)125 2987 y FM(\017)41 b FN(instances)19 b(of)g(such)h(classes)g(whose)g FJ(__dict__)e FN(or)h FJ(__setstate__\(\))f FN(is)i(picklable)f(\(see)h(section)f (13.1.5)f(for)h(details\))0 3217 y(Attempts)g(to)g(pickle)g (unpicklable)e(objects)i(will)h(raise)g(the)f FJ(PicklingError)e FN(e)o(xception;)h(when)g(this)i(happens,)e(an)h(unspeci\002ed)0 3317 y(number)d(of)h(bytes)g(may)g(ha)n(v)o(e)f(already)h(been)f (written)h(to)h(the)f(underlying)e(\002le.)24 b(T)m(rying)16 b(to)i(pickle)f(a)g(highly)f(recursi)n(v)o(e)g(data)i(structure)0 3417 y(may)h(e)o(xceed)f(the)i(maximum)d(recursion)h(depth,)h(a)h FJ(RuntimeError)d FN(will)k(be)e(raised)g(in)h(this)g(case.)25 b(Y)-9 b(ou)19 b(can)g(carefully)f(raise)i(this)0 3516 y(limit)h(with)f FJ(sys.setrecursionlimit\(\))p FN(.)0 3663 y(Note)28 b(that)h(functions)d(\(b)n(uilt-in)i(and)f(user)n (-de\002ned\))f(are)j(pickled)e(by)h(\223fully)f(quali\002ed\224)g (name)h(reference,)g(not)g(by)g(v)n(alue.)48 b(This)0 3763 y(means)23 b(that)h(only)e(the)i(function)d(name)i(is)i(pickled,)d (along)h(with)h(the)f(name)g(of)g(module)f(the)h(function)f(is)i (de\002ned)f(in.)35 b(Neither)23 b(the)0 3862 y(function')-5 b(s)25 b(code,)j(nor)d(an)o(y)h(of)h(its)g(function)e(attrib)n(utes)i (are)f(pickled.)43 b(Thus)26 b(the)h(de\002ning)e(module)h(must)g(be)h (importable)e(in)i(the)0 3962 y(unpickling)18 b(en)m(vironment,)f(and)i (the)i(module)d(must)j(contain)e(the)h(named)f(object,)h(otherwise)f (an)h(e)o(xception)f(will)h(be)h(raised.)3677 3932 y FF(4)0 4109 y FN(Similarly)-5 b(,)20 b(classes)i(are)f(pickled)f(by)h (named)f(reference,)f(so)i(the)g(same)g(restrictions)g(in)g(the)g (unpickling)e(en)m(vironment)f(apply)-5 b(.)26 b(Note)0 4208 y(that)21 b(none)f(of)g(the)h(class')-5 b(s)22 b(code)e(or)h(data) g(is)g(pickled,)f(so)h(in)g(the)g(follo)n(wing)e(e)o(xample)h(the)h (class)g(attrib)n(ute)g FJ(attr)f FN(is)i(not)f(restored)e(in)0 4308 y(the)h(unpickling)e(en)m(vironment:)236 4546 y FA(class)44 b(Foo:)416 4638 y(attr)g(=)g('a)h(class)f(attr')236 4820 y(picklestring)f(=)i(pickle.dumps\(Foo\))0 5107 y FN(These)20 b(restrictions)g(are)g(why)f(picklable)g(functions)g(and) h(classes)h(must)f(be)g(de\002ned)f(in)i(the)f(top)g(le)n(v)o(el)g(of)g (a)g(module.)p 0 5178 1560 4 v 90 5233 a FB(4)120 5257 y FH(The)c(e)o(xception)k(raised)e(will)g(lik)o(ely)i(be)d(an)g Fz(ImportError)e FH(or)i(an)g Fz(AttributeError)e FH(b)o(ut)i(it)h (could)g(be)f(something)i(else.)p 0 5549 3901 4 v 0 5649 a FI(13.1.)52 b FJ(pickle)22 b FI(\227)h(Python)h(object)f(ser)q (ialization)2134 b(363)p eop end %%Page: 364 376 TeXDict begin 364 375 bop 0 83 a FN(Similarly)-5 b(,)29 b(when)f(class)h(instances)f(are)g(pickled,)h(their)f(class')-5 b(s)29 b(code)e(and)h(data)g(are)g(not)g(pickled)f(along)g(with)h (them.)49 b(Only)28 b(the)0 183 y(instance)21 b(data)g(are)g(pickled.) 27 b(This)22 b(is)g(done)e(on)h(purpose,)e(so)j(you)e(can)h(\002x)h(b)n (ugs)f(in)g(a)h(class)g(or)f(add)g(methods)f(to)h(the)h(class)g(and)e (still)0 282 y(load)i(objects)g(that)g(were)g(created)g(with)g(an)g (earlier)g(v)o(ersion)f(of)h(the)g(class.)33 b(If)22 b(you)f(plan)h(to)g(ha)n(v)o(e)g(long-li)n(v)o(ed)e(objects)i(that)g (will)h(see)0 382 y(man)o(y)c(v)o(ersions)g(of)i(a)f(class,)h(it)g(may) f(be)h(w)o(orthwhile)e(to)h(put)g(a)h(v)o(ersion)e(number)g(in)h(the)g (objects)h(so)f(that)h(suitable)f(con)m(v)o(ersions)e(can)0 482 y(be)i(made)g(by)f(the)i(class')-5 b(s)21 b FJ(__setstate__\(\))d FN(method.)0 765 y Fv(13.1.5)101 b(The)28 b(pic)n(kle)g(protocol)0 968 y FN(This)22 b(section)f(describes)g(the)h(\223pickling)e (protocol\224)f(that)j(de\002nes)f(the)h(interf)o(ace)f(between)f(the)i (pickler/unpickler)c(and)j(the)h(objects)0 1068 y(that)j(are)f(being)g (serialized.)38 b(This)25 b(protocol)e(pro)o(vides)g(a)i(standard)f(w)o (ay)h(for)f(you)f(to)i(de\002ne,)g(customize,)g(and)f(control)g(ho)n(w) g(your)0 1167 y(objects)d(are)h(serialized)f(and)f(de-serialized.)28 b(The)21 b(description)f(in)h(this)h(section)f(doesn')o(t)f(co)o(v)o (er)g(speci\002c)i(customizations)e(that)h(you)0 1267 y(can)h(emplo)o(y)g(to)h(mak)o(e)f(the)h(unpickling)d(en)m(vironment)f (slightly)k(safer)f(from)g(untrusted)f(pickle)h(data)h(streams;)h(see)f (section)f(13.1.6)0 1366 y(for)e(more)f(details.)0 1633 y FI(Pic)n(kling)24 b(and)g(unpic)n(kling)h(nor)r(mal)e(class)g (instances)0 1836 y FN(When)g(a)g(pickled)f(class)i(instance)e(is)i (unpickled,)d(its)j FJ(__init__\(\))e FN(method)f(is)j(normally)d FK(not)i FN(in)m(v)n(ok)o(ed.)31 b(If)23 b(it)h(is)f(desirable)f(that)0 1936 y(the)27 b FJ(__init__\(\))e FN(method)h(be)g(called)h(on)f (unpickling,)g(an)h(old-style)f(class)i(can)e(de\002ne)g(a)i(method)d FJ(__getinitargs__-)0 2036 y(\(\))p FN(,)k(which)d(should)g(return)g(a) h FK(tuple)g FN(containing)e(the)i(ar)o(guments)e(to)i(be)g(passed)g (to)g(the)g(class)h(constructor)d(\()p FJ(__init__\(\))g FN(for)0 2135 y(e)o(xample\).)45 b(The)28 b FJ(__getinitargs__\(\))d FN(method)h(is)i(called)g(at)g(pickle)f(time;)32 b(the)27 b(tuple)g(it)i(returns)d(is)j(incorporated)c(in)j(the)0 2235 y(pickle)20 b(for)f(the)h(instance.)0 2382 y(Ne)n(w-style)h(types) g(can)g(pro)o(vide)e(a)i FJ(__getnewargs__\(\))e FN(method)h(that)h(is) h(used)f(for)g(protocol)e(2.)28 b(Implementing)18 b(this)k(method)0 2481 y(is)i(needed)e(if)i(the)f(type)g(establishes)g(some)g(internal)g (in)m(v)n(ariants)f(when)h(the)g(instance)g(is)h(created,)f(or)g(if)h (the)f(memory)e(allocation)i(is)0 2581 y(af)n(fected)f(by)h(the)h(v)n (alues)f(passed)g(to)h(the)f FJ(__new__\(\))g FN(method)f(for)h(the)g (type)g(\(as)h(it)g(is)h(for)d(tuples)i(and)f(strings\).)34 b(Instances)23 b(of)g(a)0 2681 y(ne)n(w-style)c(type)h FJ(C)h FN(are)f(created)f(using)236 2827 y FA(obj)45 b(=)f(C.__new__\(C,)1088 2840 y(*)1133 2827 y FK(ar)m(gs)p FJ(\))0 3122 y FN(where)16 b FK(ar)m(gs)h FN(is)h(the)e(result)h(of)f (calling)h FJ(__getnewargs__\(\))d FN(on)i(the)h(original)f(object;)h (if)g(there)f(is)i(no)e FJ(__getnewargs__\(\))p FN(,)0 3222 y(an)k(empty)f(tuple)h(is)h(assumed.)0 3369 y(Classes)f(can)e (further)f(in\003uence)g(ho)n(w)g(their)h(instances)g(are)h(pickled;)e (if)i(the)f(class)h(de\002nes)f(the)h(method)d FJ(__getstate__\(\))p FN(,)h(it)i(is)0 3468 y(called)e(and)g(the)g(return)g(state)h(is)g (pickled)e(as)i(the)g(contents)e(for)h(the)h(instance,)f(instead)g(of)g (the)h(contents)e(of)h(the)h(instance')-5 b(s)17 b(dictionary)-5 b(.)0 3568 y(If)20 b(there)g(is)h(no)f FJ(__getstate__\(\))e FN(method,)g(the)j(instance')-5 b(s)20 b FJ(__dict__)f FN(is)i(pickled.)0 3715 y(Upon)j(unpickling,)g(if)h(the)g(class)h(also) f(de\002nes)g(the)g(method)e FJ(__setstate__\(\))p FN(,)h(it)i(is)g (called)e(with)i(the)f(unpickled)e(state.)3772 3685 y FF(5)3845 3715 y FN(If)0 3815 y(there)g(is)h(no)e FJ(__setstate__\(\))f FN(method,)h(the)h(pickled)f(state)i(must)f(be)g(a)h(dictionary)d(and)h (its)i(items)g(are)f(assigned)g(to)g(the)g(ne)n(w)0 3914 y(instance')-5 b(s)25 b(dictionary)-5 b(.)36 b(If)25 b(a)g(class)h(de\002nes)e(both)g FJ(__getstate__\(\))f FN(and)h FJ(__setstate__\(\))p FN(,)g(the)h(state)g(object)g(needn')o (t)0 4014 y(be)20 b(a)h(dictionary)d(and)i(these)g(methods)f(can)h(do)g (what)g(the)o(y)g(w)o(ant.)1915 3984 y FF(6)p 0 4104 3901 17 v 0 4378 17 275 v 75 4219 a FL(W)-5 b(ar)o(ning:)57 b FN(F)o(or)21 b(ne)n(w-style)g(classes,)j(if)e FJ(__getstate__\(\))e FN(returns)h(a)h(f)o(alse)h(v)n(alue,)e(the)h FJ(__setstate__\(\))e FN(method)75 4319 y(will)h(not)f(be)g(called.)p 3883 4378 V 0 4395 3901 17 v 0 4670 a FI(Pic)n(kling)k(and)g(unpic)n(kling)h (e)n(xtension)d(types)0 4873 y FN(When)e(the)f FJ(Pickler)g FN(encounters)f(an)i(object)f(of)g(a)i(type)e(it)h(kno)n(ws)f(nothing)f (about)h(\227)h(such)g(as)g(an)g(e)o(xtension)e(type)h(\227)i(it)f (looks)f(in)0 4973 y(tw)o(o)h(places)g(for)f(a)i(hint)e(of)h(ho)n(w)f (to)h(pickle)g(it.)25 b(One)20 b(alternati)n(v)o(e)f(is)h(for)g(the)g (object)f(to)h(implement)f(a)h FJ(__reduce__\(\))e FN(method.)24 b(If)0 5072 y(pro)o(vided,)e(at)i(pickling)e(time)i FJ(__reduce__\(\))d FN(will)k(be)e(called)h(with)f(no)g(ar)o(guments,)f(and)h(it)i(must)e (return)g(either)g(a)h(string)f(or)g(a)0 5172 y(tuple.)p 0 5240 1560 4 v 90 5295 a FB(5)120 5319 y FH(These)17 b(methods)g(can)h(also)g(be)f(used)g(to)h(implement)h(cop)o(ying)f (class)g(instances.)90 5377 y FB(6)120 5400 y FH(This)e(protocol)j(is)e (also)h(used)f(by)g(the)h(shallo)n(w)g(and)g(deep)g(cop)o(ying)h (operations)g(de\002ned)f(in)g(the)f Fz(copy)f FH(module.)p 0 5549 3901 4 v 0 5649 a FI(364)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 365 377 TeXDict begin 365 376 bop 0 83 a FN(If)24 b(a)h(string)f(is)h (returned,)e(it)i(names)f(a)h(global)e(v)n(ariable)g(whose)h(contents)g (are)g(pickled)f(as)i(normal.)36 b(The)24 b(string)g(returned)f(by)h FJ(__-)0 183 y(reduce__)16 b FN(should)f(be)h(the)h(object')-5 b(s)16 b(local)h(name)e(relati)n(v)o(e)h(to)h(its)g(module;)g(the)f (pickle)g(module)f(searches)h(the)h(module)e(namespace)0 282 y(to)20 b(determine)f(the)h(object')-5 b(s)20 b(module.)0 429 y(When)h(a)h(tuple)f(is)h(returned,)d(it)j(must)f(be)g(between)g (tw)o(o)g(and)g(\002)n(v)o(e)g(elements)g(long.)27 b(Optional)20 b(elements)h(can)g(either)g(be)g(omitted,)g(or)0 529 y FJ(None)f FN(can)g(be)g(pro)o(vided)e(as)j(their)f(v)n(alue.)k(The)c (semantics)g(of)g(each)g(element)f(are:)125 759 y FM(\017)41 b FN(A)31 b(callable)f(object)g(that)h(will)g(be)g(called)f(to)h (create)f(the)h(initial)g(v)o(ersion)e(of)h(the)h(object.)56 b(The)30 b(ne)o(xt)g(element)g(of)g(the)h(tu-)208 858 y(ple)c(will)i(pro)o(vide)c(ar)o(guments)h(for)h(this)h(callable,)h (and)e(later)g(elements)h(pro)o(vide)d(additional)i(state)h (information)d(that)j(will)208 958 y(subsequently)18 b(be)i(used)g(to)g(fully)g(reconstruct)e(the)j(pickled)e(data.)208 1091 y(In)26 b(the)h(unpickling)e(en)m(vironment)f(this)k(object)e (must)h(be)g(either)g(a)h(class,)h(a)f(callable)e(re)o(gistered)g(as)i (a)f(\223safe)h(constructor\224)208 1190 y(\(see)g(belo)n(w\),)h(or)f (it)h(must)f(ha)n(v)o(e)g(an)g(attrib)n(ute)f FJ (__safe_for_unpickling__)e FN(with)j(a)h(true)f(v)n(alue.)48 b(Otherwise,)30 b(an)208 1290 y FJ(UnpicklingError)25 b FN(will)k(be)f(raised)f(in)h(the)g(unpickling)e(en)m(vironment.)45 b(Note)28 b(that)g(as)g(usual,)i(the)e(callable)f(itself)i(is)208 1390 y(pickled)19 b(by)h(name.)125 1556 y FM(\017)41 b FN(A)25 b(tuple)g(of)f(ar)o(guments)f(for)i(the)g(callable)g(object.) 79 b(Changed)24 b(in)h(v)o(ersion)f(2.5:)g(F)o(ormerly)-5 b(,)24 b(this)i(ar)o(gument)c(could)i(also)i(be)208 1655 y FJ(None)p FN(.)125 1821 y FM(\017)41 b FN(Optionally)-5 b(,)20 b(the)h(object')-5 b(s)22 b(state,)h(which)e(will)h(be)g(passed) f(to)h(the)g(object')-5 b(s)22 b FJ(__setstate__\(\))d FN(method)i(as)h(described)e(in)208 1921 y(section)g(13.1.5.)k(If)d (the)f(object)h(has)f(no)h FJ(__setstate__\(\))d FN(method,)h(then,)h (as)i(abo)o(v)o(e,)c(the)j(v)n(alue)f(must)h(be)f(a)h(dictionary)208 2021 y(and)e(it)i(will)g(be)f(added)f(to)i(the)f(object')-5 b(s)20 b FJ(__dict__)p FN(.)125 2187 y FM(\017)41 b FN(Optionally)-5 b(,)20 b(an)h(iterator)g(\(and)g(not)h(a)g(sequence\))e(yielding)g (successi)n(v)o(e)i(list)h(items.)30 b(These)21 b(list)i(items)f(will)h (be)e(pickled,)g(and)208 2286 y(appended)h(to)j(the)g(object)g(using)f (either)h FJ(obj.append\()p FK(item)p FJ(\))e FN(or)h FJ(obj.extend\()p FK(list)p 2933 2286 25 4 v 29 w(of)p 3027 2286 V 29 w(items)p FJ(\))p FN(.)40 b(This)25 b(is)h(primarily)208 2386 y(used)h(for)h(list)h(subclasses,)h(b)n(ut)e(may)f(be)h(used)g(by) f(other)g(classes)i(as)g(long)e(as)i(the)o(y)e(ha)n(v)o(e)g FJ(append\(\))g FN(and)g FJ(extend\(\))208 2486 y FN(methods)20 b(with)h(the)g(appropriate)e(signature.)27 b(\(Whether)20 b FJ(append\(\))g FN(or)h FJ(extend\(\))f FN(is)i(used)f(depends)f(on)g (which)h(pickle)208 2585 y(protocol)d(v)o(ersion)h(is)i(used)f(as)h (well)g(as)g(the)f(number)e(of)i(items)h(to)f(append,)e(so)j(both)e (must)h(be)h(supported.\))125 2751 y FM(\017)41 b FN(Optionally)-5 b(,)17 b(an)i(iterator)f(\(not)g(a)h(sequence\))f(yielding)f(successi)n (v)o(e)i(dictionary)e(items,)i(which)g(should)f(be)g(tuples)h(of)g(the) g(form)208 2851 y FJ(\()p FK(k)o(e)n(y)p FJ(,)48 b FK(value)p FJ(\))p FN(.)23 b(These)16 b(items)g(will)h(be)f(pickled)f(and)h (stored)g(to)g(the)g(object)f(using)h FJ(obj[)p FK(k)o(e)n(y)p FJ(])48 b(=)i FK(value)p FN(.)23 b(This)16 b(is)h(primarily)208 2950 y(used)i(for)h(dictionary)e(subclasses,)j(b)n(ut)f(may)g(be)g (used)g(by)g(other)f(classes)i(as)g(long)f(as)g(the)o(y)g(implement)f FJ(__setitem__)p FN(.)0 3180 y(It)28 b(is)h(sometimes)f(useful)g(to)g (kno)n(w)f(the)h(protocol)e(v)o(ersion)h(when)g(implementing)f FJ(__reduce__)p FN(.)47 b(This)28 b(can)g(be)g(done)f(by)h(im-)0 3280 y(plementing)g(a)i(method)e(named)g FJ(__reduce_ex__)g FN(instead)h(of)h FJ(__reduce__)p FN(.)51 b FJ(__reduce_ex__)p FN(,)30 b(when)f(it)i(e)o(xists,)h(is)0 3380 y(called)c(in)h (preference)e(o)o(v)o(er)g FJ(__reduce__)h FN(\(you)f(may)h(still)i (pro)o(vide)d FJ(__reduce__)g FN(for)h(backw)o(ards)f(compatibility\).) 49 b(The)0 3479 y FJ(__reduce_ex__)18 b FN(method)h(will)i(be)f(called) g(with)h(a)f(single)g(inte)o(ger)f(ar)o(gument,)f(the)i(protocol)f(v)o (ersion.)0 3626 y(The)27 b FJ(object)g FN(class)h(implements)f(both)f FJ(__reduce__)g FN(and)h FJ(__reduce_ex__)p FN(;)i(ho)n(we)n(v)o(er)m (,)e(if)h(a)g(subclass)f(o)o(v)o(errides)f FJ(__-)0 3726 y(reduce__)18 b FN(b)n(ut)g(not)g FJ(__reduce_ex__)p FN(,)f(the)i FJ(__reduce_ex__)e FN(implementation)f(detects)j(this)g (and)f(calls)h FJ(__reduce__)p FN(.)0 3873 y(An)h(alternati)n(v)o(e)f (to)h(implementing)e(a)i FJ(__reduce__\(\))f FN(method)g(on)g(the)h (object)g(to)g(be)g(pickled,)f(is)i(to)f(re)o(gister)f(the)i(callable)e (with)0 3972 y(the)i FJ(copy_reg)f FN(module.)26 b(This)21 b(module)f(pro)o(vides)f(a)i(w)o(ay)g(for)g(programs)e(to)i(re)o (gister)f(\223reduction)f(functions\224)h(and)g(constructors)0 4072 y(for)k(user)n(-de\002ned)f(types.)38 b(Reduction)24 b(functions)f(ha)n(v)o(e)h(the)h(same)g(semantics)g(and)f(interf)o(ace) g(as)h(the)g FJ(__reduce__\(\))e FN(method)0 4171 y(described)c(abo)o (v)o(e,)f(e)o(xcept)h(that)i(the)o(y)e(are)h(called)g(with)h(a)f (single)g(ar)o(gument,)e(the)i(object)g(to)g(be)g(pickled.)0 4318 y(The)g(re)o(gistered)f(constructor)f(is)j(deemed)e(a)i(\223safe)f (constructor\224)e(for)i(purposes)f(of)g(unpickling)f(as)j(described)e (abo)o(v)o(e.)0 4587 y FI(Pic)n(kling)24 b(and)g(unpic)n(kling)h(e)n (xter)r(nal)d(objects)0 4790 y FN(F)o(or)h(the)g(bene\002t)g(of)f (object)h(persistence,)g(the)g FJ(pickle)g FN(module)e(supports)h(the)h (notion)f(of)h(a)h(reference)d(to)i(an)g(object)g(outside)g(the)0 4889 y(pickled)k(data)g(stream.)47 b(Such)28 b(objects)f(are)g (referenced)f(by)h(a)h(\223persistent)f(id\224,)j(which)d(is)h(just)h (an)e(arbitrary)f(string)i(of)f(printable)2 4989 y FH(A)t(S)t(C)t(I)t (I)d FN(characters.)i(The)20 b(resolution)g(of)g(such)h(names)f(is)i (not)e(de\002ned)g(by)h(the)f FJ(pickle)h FN(module;)e(it)j(will)f (dele)o(gate)f(this)h(resolution)0 5088 y(to)f(user)g(de\002ned)g (functions)e(on)i(the)g(pickler)g(and)f(unpickler)-5 b(.)1789 5058 y FF(7)p 0 5160 1560 4 v 90 5214 a FB(7)120 5238 y FH(The)23 b(actual)j(mechanism)e(for)g(associating)i(these)e (user)g(de\002ned)h(functions)g(is)e(slightly)i(dif)n(ferent)i(for)c Fz(pickle)f FH(and)i Fz(cPickle)p FH(.)39 b(The)23 b(description)j(gi)n (v)o(en)0 5317 y(here)20 b(w)o(orks)f(the)g(same)g(for)g(both)g (implementations.)29 b(Users)19 b(of)g(the)g Fz(pickle)f FH(module)h(could)h(also)f(use)g(subclassing)i(to)e(ef)n(fect)i(the)e (same)g(results,)h(o)o(v)o(erriding)h(the)0 5396 y Fz (persistent_id\(\))14 b FH(and)k Fz(persistent_load\(\))c FH(methods)k(in)f(the)h(deri)n(v)o(ed)h(classes.)p 0 5549 3901 4 v 0 5649 a FI(13.1.)52 b FJ(pickle)22 b FI(\227)h(Python)h (object)f(ser)q(ialization)2134 b(365)p eop end %%Page: 366 378 TeXDict begin 366 377 bop 0 83 a FN(T)-7 b(o)24 b(de\002ne)g(e)o (xternal)f(persistent)h(id)h(resolution,)e(you)h(need)f(to)i(set)g(the) f FJ(persistent_id)f FN(attrib)n(ute)h(of)g(the)g(pickler)f(object)h (and)0 183 y(the)c FJ(persistent_load)e FN(attrib)n(ute)i(of)g(the)g (unpickler)e(object.)0 330 y(T)-7 b(o)18 b(pickle)e(objects)h(that)h (ha)n(v)o(e)f(an)g(e)o(xternal)f(persistent)h(id,)h(the)f(pickler)g (must)g(ha)n(v)o(e)g(a)h(custom)e FJ(persistent_id\(\))f FN(method)h(that)0 429 y(tak)o(es)j(an)f(object)f(as)i(an)f(ar)o (gument)e(and)i(returns)f(either)h FJ(None)g FN(or)g(the)g(persistent)g (id)g(for)g(that)g(object.)24 b(When)18 b FJ(None)g FN(is)h(returned,)e (the)0 529 y(pickler)j(simply)h(pickles)g(the)g(object)g(as)h(normal.)k (When)21 b(a)h(persistent)f(id)g(string)g(is)h(returned,)e(the)h (pickler)f(will)i(pickle)f(that)g(string,)0 628 y(along)e(with)i(a)f (mark)o(er)f(so)i(that)f(the)g(unpickler)f(will)i(recognize)d(the)i (string)g(as)h(a)g(persistent)f(id.)0 775 y(T)-7 b(o)21 b(unpickle)f(e)o(xternal)f(objects,)i(the)g(unpickler)e(must)i(ha)n(v)o (e)f(a)i(custom)e FJ(persistent_load\(\))f FN(function)g(that)i(tak)o (es)g(a)h(persis-)0 875 y(tent)e(id)h(string)f(and)f(returns)g(the)i (referenced)d(object.)0 1022 y(Here')-5 b(s)20 b(a)h(silly)g(e)o (xample)e(that)h FK(might)g FN(shed)g(more)f(light:)p 0 5549 3901 4 v 0 5649 a FI(366)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 367 379 TeXDict begin 367 378 bop 236 174 a FA(import)44 b(pickle)236 266 y(from)g(cStringIO)g(import)g(StringIO)236 448 y(src)h(=)f (StringIO\(\))236 540 y(p)h(=)g(pickle.Pickler\(src\))236 722 y(def)g(persistent_id\(obj\):)416 814 y(if)f(hasattr\(obj,)f ('x'\):)595 905 y(return)h('the)g(value)g(\045d')g(\045)h(obj.x)416 996 y(else:)595 1088 y(return)f(None)236 1270 y(p.persistent_id)f(=)h (persistent_id)236 1453 y(class)g(Integer:)416 1544 y(def)g (__init__\(self,)e(x\):)595 1636 y(self.x)i(=)g(x)416 1727 y(def)g(__str__\(self\):)595 1818 y(return)g('My)g(name)g(is)h (integer)e(\045d')i(\045)f(self.x)236 2001 y(i)h(=)g(Integer\(7\))236 2092 y(print)f(i)236 2183 y(p.dump\(i\))236 2366 y(datastream)f(=)i (src.getvalue\(\))236 2457 y(print)f(repr\(datastream\))236 2549 y(dst)h(=)f(StringIO\(datastream\))236 2731 y(up)h(=)f (pickle.Unpickler\(dst\))236 2914 y(class)g(FancyInteger\(Integer\):) 416 3005 y(def)g(__str__\(self\):)595 3097 y(return)g('I)g(am)h(the)f (integer)g(\045d')g(\045)h(self.x)236 3279 y(def)g (persistent_load\(persid\):)416 3371 y(if)f(persid.startswith\('the)d (value)j('\):)595 3462 y(value)g(=)h(int\(persid.split\(\)[2]\))595 3553 y(return)f(FancyInteger\(value\))416 3645 y(else:)595 3736 y(raise)g(pickle.UnpicklingError,)d('Invalid)i(persistent)g(id') 236 3919 y(up.persistent_load)f(=)j(persistent_load)236 4101 y(j)g(=)g(up.load\(\))236 4193 y(print)f(j)0 4479 y FN(In)27 b(the)g FJ(cPickle)f FN(module,)h(the)g(unpickler')-5 b(s)26 b FJ(persistent_load)e FN(attrib)n(ute)j(can)g(also)g(be)g(set)h (to)f(a)h(Python)d(list,)30 b(in)d(which)0 4579 y(case,)j(when)e(the)g (unpickler)f(reaches)g(a)i(persistent)f(id,)i(the)f(persistent)f(id)g (string)g(will)h(simply)f(be)g(appended)e(to)i(this)h(list.)50 b(This)0 4678 y(functionality)18 b(e)o(xists)i(so)g(that)f(a)h(pickle)f (data)h(stream)g(can)f(be)h(\223snif)n(fed\224)e(for)h(object)g (references)f(without)h(actually)g(instantiating)g(all)0 4778 y(the)26 b(objects)g(in)g(a)g(pickle.)769 4748 y FF(8)844 4778 y FN(Setting)g FJ(persistent_load)e FN(to)i(a)g(list)i (is)e(usually)g(used)g(in)g(conjunction)d(with)j(the)g FJ(noload\(\))0 4878 y FN(method)19 b(on)h(the)g(Unpickler)-5 b(.)p 0 4949 1560 4 v 90 5004 a FB(8)120 5028 y FH(W)g(e')o(ll)17 b(lea)o(v)o(e)i(you)e(with)h(the)g(image)f(of)g(Guido)h(and)g(Jim)e (sitting)j(around)f(snif)n(\002ng)g(pickles)h(in)e(their)h(li)n(ving)h (rooms.)p 0 5549 3901 4 v 0 5649 a FI(13.1.)52 b FJ(pickle)22 b FI(\227)h(Python)h(object)f(ser)q(ialization)2134 b(367)p eop end %%Page: 368 380 TeXDict begin 368 379 bop 0 83 a Fv(13.1.6)101 b(Subclassing)29 b(Unpic)n(klers)0 286 y FN(By)18 b(def)o(ault,)e(unpickling)f(will)j (import)e(an)o(y)g(class)j(that)e(it)h(\002nds)f(in)g(the)g(pickle)g (data.)24 b(Y)-9 b(ou)16 b(can)h(control)f(e)o(xactly)g(what)h(gets)h (unpickled)0 386 y(and)i(what)g(gets)h(called)f(by)g(customizing)e (your)h(unpickler)-5 b(.)24 b(Unfortunately)-5 b(,)17 b(e)o(xactly)j(ho)n(w)f(you)h(do)g(this)g(is)i(dif)n(ferent)c (depending)g(on)0 485 y(whether)h(you')l(re)f(using)i FJ(pickle)g FN(or)g FJ(cPickle)p FN(.)1503 455 y FF(9)0 632 y FN(In)f(the)h FJ(pickle)f FN(module,)g(you)f(need)h(to)h(deri)n (v)o(e)f(a)h(subclass)g(from)e FJ(Unpickler)p FN(,)h(o)o(v)o(erriding)e (the)i FJ(load_global\(\))f FN(method.)0 732 y FJ(load_global\(\))g FN(should)h(read)h(tw)o(o)h(lines)f(from)f(the)h(pickle)g(data)g (stream)g(where)g(the)g(\002rst)h(line)f(will)h(the)f(name)g(of)g(the)g (module)0 831 y(containing)i(the)i(class)g(and)g(the)f(second)g(line)h (will)h(be)e(the)h(name)f(of)h(the)g(instance')-5 b(s)23 b(class.)37 b(It)24 b(then)f(looks)h(up)f(the)h(class,)h(possibly)0 931 y(importing)e(the)j(module)e(and)h(digging)e(out)i(the)h(attrib)n (ute,)g(then)f(it)h(appends)e(what)h(it)h(\002nds)g(to)f(the)h (unpickler')-5 b(s)23 b(stack.)41 b(Later)25 b(on,)0 1031 y(this)d(class)g(will)h(be)e(assigned)g(to)h(the)f FJ(__class__)f FN(attrib)n(ute)h(of)h(an)f(empty)f(class,)j(as)f(a)g(w) o(ay)g(of)f(magically)f(creating)h(an)g(instance)0 1130 y(without)30 b(calling)g(its)i(class')-5 b(s)32 b FJ(__init__\(\))p FN(.)55 b(Y)-9 b(our)30 b(job)h(\(should)e(you)h(choose)g(to)h(accept)f (it\),)j(w)o(ould)d(be)h(to)g(ha)n(v)o(e)f FJ(load_-)0 1230 y(global\(\))21 b FN(push)h(onto)f(the)h(unpickler')-5 b(s)21 b(stack,)h(a)h(kno)n(wn)d(safe)j(v)o(ersion)e(of)g(an)o(y)h (class)h(you)e(deem)g(safe)i(to)f(unpickle.)29 b(It)23 b(is)g(up)e(to)0 1329 y(you)j(to)h(produce)e(such)i(a)g(class.)41 b(Or)25 b(you)f(could)g(raise)h(an)g(error)f(if)i(you)e(w)o(ant)h(to)g (disallo)n(w)g(all)g(unpickling)e(of)i(instances.)39 b(If)25 b(this)0 1429 y(sounds)19 b(lik)o(e)i(a)f(hack,)g(you')l(re)e (right.)24 b(Refer)c(to)h(the)f(source)f(code)h(to)g(mak)o(e)g(this)h (w)o(ork.)0 1576 y(Things)16 b(are)h(a)g(little)h(cleaner)e(with)h FJ(cPickle)p FN(,)f(b)n(ut)h(not)g(by)f(much.)23 b(T)-7 b(o)17 b(control)f(what)h(gets)g(unpickled,)e(you)h(can)h(set)g(the)g (unpickler')-5 b(s)0 1676 y FJ(find_global)23 b FN(attrib)n(ute)h(to)h (a)g(function)e(or)h FJ(None)p FN(.)38 b(If)25 b(it)g(is)g FJ(None)g FN(then)f(an)o(y)g(attempts)g(to)h(unpickle)e(instances)h (will)i(raise)f(an)0 1775 y FJ(UnpicklingError)p FN(.)53 b(If)30 b(it)h(is)g(a)f(function,)h(then)f(it)h(should)e(accept)h(a)g (module)f(name)h(and)f(a)i(class)g(name,)h(and)e(return)f(the)0 1875 y(corresponding)15 b(class)j(object.)24 b(It)18 b(is)h(responsible)e(for)h(looking)e(up)h(the)h(class)h(and)f (performing)d(an)o(y)i(necessary)g(imports,)h(and)f(it)i(may)0 1974 y(raise)h(an)h(error)e(to)h(pre)n(v)o(ent)e(instances)j(of)e(the)i (class)g(from)e(being)g(unpickled.)0 2121 y(The)h(moral)f(of)h(the)g (story)g(is)h(that)g(you)e(should)g(be)h(really)g(careful)f(about)g (the)i(source)e(of)h(the)g(strings)g(your)f(application)g(unpickles.)0 2406 y Fv(13.1.7)101 b(Example)0 2609 y FN(F)o(or)17 b(the)h(simplest)g(code,)f(use)h(the)f FJ(dump\(\))g FN(and)g FJ(load\(\))g FN(functions.)23 b(Note)18 b(that)f(a)h (self-referencing)d(list)k(is)f(pickled)f(and)g(restored)0 2709 y(correctly)-5 b(.)236 2947 y FA(import)44 b(pickle)236 3130 y(data1)g(=)h({'a':)f([1,)g(2.0,)g(3,)h(4+6j],)640 3221 y('b':)f(\('string',)f(u'Unicode)g(string'\),)640 3312 y('c':)h(None})236 3495 y(selfref_list)f(=)i([1,)f(2,)h(3])236 3586 y(selfref_list.append\(selfref_list\))236 3769 y(output)f(=)h (open\('data.pkl',)d('wb'\))236 3952 y(#)j(Pickle)f(dictionary)f(using) h(protocol)f(0.)236 4043 y(pickle.dump\(data1,)f(output\))236 4225 y(#)j(Pickle)f(the)g(list)g(using)g(the)h(highest)e(protocol)h (available.)236 4317 y(pickle.dump\(selfref_list,)d(output,)j(-1\))236 4499 y(output.close\(\))0 4786 y FN(The)23 b(follo)n(wing)f(e)o(xample) g(reads)i(the)f(resulting)g(pickled)f(data.)35 b(When)24 b(reading)e(a)i(pickle-containing)c(\002le,)25 b(you)d(should)h(open)g (the)0 4886 y(\002le)e(in)f(binary)f(mode)g(because)h(you)f(can')o(t)g (be)h(sure)h(if)f(the)g(ASCII)h(or)f(binary)f(format)g(w)o(as)i(used.)p 0 4957 1560 4 v 90 5012 a FB(9)120 5036 y FH(A)13 b(w)o(ord)i(of)f (caution:)23 b(the)15 b(mechanisms)g(described)h(here)g(use)e(internal) j(attrib)o(utes)g(and)d(methods,)i(which)f(are)g(subject)h(to)f(change) h(in)e(future)i(v)o(ersions)f(of)f(Python.)0 5115 y(W)-5 b(e)16 b(intend)j(to)e(someday)h(pro)o(vide)h(a)e(common)g(interf)o (ace)j(for)d(controlling)j(this)e(beha)o(vior)m(,)g(which)g(will)g(w)o (ork)g(in)f(either)i Fz(pickle)d FH(or)g Fz(cPickle)p FH(.)p 0 5549 3901 4 v 0 5649 a FI(368)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 369 381 TeXDict begin 369 380 bop 236 174 a FA(import)44 b(pprint,)g(pickle)236 357 y(pkl_file)g(=)g(open\('data.pkl',)f('rb'\))236 540 y(data1)h(=)h(pickle.load\(pkl_file\))236 631 y(pprint.pprint\(data1\)) 236 814 y(data2)f(=)h(pickle.load\(pkl_file\))236 905 y(pprint.pprint\(data2\))236 1088 y(pkl_file.close\(\))0 1374 y FN(Here')-5 b(s)19 b(a)h(lar)o(ger)e(e)o(xample)f(that)j(sho)n (ws)f(ho)n(w)f(to)i(modify)d(pickling)h(beha)n(vior)g(for)g(a)i(class.) 25 b(The)19 b FJ(TextReader)f FN(class)i(opens)e(a)i(te)o(xt)0 1474 y(\002le,)k(and)e(returns)g(the)h(line)g(number)e(and)h(line)h (contents)f(each)h(time)g(its)h FJ(readline\(\))d FN(method)h(is)h (called.)33 b(If)23 b(a)g FJ(TextReader)0 1573 y FN(instance)g(is)i (pickled,)f(all)g(attrib)n(utes)g FK(e)n(xcept)g FN(the)f(\002le)i (object)e(member)g(are)h(sa)n(v)o(ed.)35 b(When)24 b(the)g(instance)f (is)i(unpickled,)d(the)i(\002le)h(is)0 1673 y(reopened,)h(and)f (reading)g(resumes)h(from)g(the)g(last)h(location.)43 b(The)26 b FJ(__setstate__\(\))e FN(and)i FJ(__getstate__\(\))f FN(methods)0 1773 y(are)20 b(used)g(to)g(implement)f(this)i(beha)n (vior)-5 b(.)236 2011 y FA(class)44 b(TextReader:)416 2102 y("""Print)f(and)h(number)g(lines)g(in)h(a)f(text)g(file.""")416 2193 y(def)g(__init__\(self,)e(file\):)595 2285 y(self.file)h(=)i(file) 595 2376 y(self.fh)f(=)g(open\(file\))595 2467 y(self.lineno)f(=)i(0) 416 2650 y(def)f(readline\(self\):)595 2741 y(self.lineno)f(=)i (self.lineno)e(+)h(1)595 2833 y(line)g(=)h(self.fh.readline\(\))595 2924 y(if)f(not)h(line:)774 3015 y(return)f(None)595 3107 y(if)g(line.endswith\("\\n"\):)774 3198 y(line)g(=)h(line[:-1])595 3289 y(return)f("\045d:)g(\045s")g(\045)h(\(self.lineno,)d(line\))416 3472 y(def)i(__getstate__\(self\):)595 3563 y(odict)g(=)h (self.__dict__.copy\(\))c(#)k(copy)f(the)g(dict)g(since)g(we)h(change)f (it)595 3655 y(del)g(odict['fh'])626 b(#)45 b(remove)e(filehandle)h (entry)595 3746 y(return)g(odict)416 3929 y(def)g (__setstate__\(self,dict\):)595 4020 y(fh)g(=)h(open\(dict['file']\)) 266 b(#)45 b(reopen)e(file)595 4111 y(count)h(=)h(dict['lineno'])311 b(#)45 b(read)f(from)g(file...)595 4203 y(while)g(count:)761 b(#)45 b(until)f(line)g(count)g(is)g(restored)774 4294 y(fh.readline\(\))774 4385 y(count)g(=)h(count)f(-)h(1)595 4477 y(self.__dict__.update\(dict\))130 b(#)45 b(update)e(attributes) 595 4568 y(self.fh)h(=)g(fh)762 b(#)45 b(save)f(the)g(file)g(object)0 4854 y FN(A)21 b(sample)f(usage)f(might)h(be)g(something)f(lik)o(e)h (this:)p 0 5549 3901 4 v 0 5649 a FI(13.1.)52 b FJ(pickle)22 b FI(\227)h(Python)h(object)f(ser)q(ialization)2134 b(369)p eop end %%Page: 370 382 TeXDict begin 370 381 bop 236 174 a FA(>>>)45 b(import)e(TextReader)236 266 y(>>>)i(obj)f(=)h(TextReader.TextReader\("TextReader.py)o("\))236 357 y(>>>)g(obj.readline\(\))236 448 y('1:)g(#!/usr/local/bin/python') 236 540 y(>>>)g(#)f(\(more)g(invocations)f(of)i(obj.readline\(\))d (here\))236 631 y(...)j(obj.readline\(\))236 722 y('7:)g(class)f (TextReader:')236 814 y(>>>)h(import)e(pickle)236 905 y(>>>)i(pickle.dump\(obj,open\('save.p','w'\)\))0 1191 y FN(If)18 b(you)f(w)o(ant)i(to)f(see)h(that)f FJ(pickle)g FN(w)o(orks)g(across)g(Python)f(processes,)h(start)h(another)e(Python)g (session,)h(before)f(continuing.)22 b(What)0 1291 y(follo)n(ws)e(can)g (happen)e(from)h(either)h(the)g(same)h(process)f(or)f(a)i(ne)n(w)f (process.)236 1529 y FA(>>>)45 b(import)e(pickle)236 1621 y(>>>)i(reader)e(=)i(pickle.load\(open\('save.p'\)\))236 1712 y(>>>)g(reader.readline\(\))236 1803 y('8:)224 b("Print)44 b(and)g(number)g(lines)g(in)g(a)h(text)f(file."')0 2090 y FL(See)21 b(Also:)0 2237 y FN(Module)e FJ(copy_reg)g FN(\(section)h(13.3\):)208 2337 y(Pickle)g(interf)o(ace)f(constructor)f (re)o(gistration)h(for)h(e)o(xtension)e(types.)0 2484 y(Module)h FJ(shelve)h FN(\(section)f(13.4\):)208 2583 y(Inde)o(x)o(ed)e(databases)j(of)g(objects;)g(uses)h FJ(pickle)p FN(.)0 2730 y(Module)e FJ(copy)h FN(\(section)g(5.17\):)208 2830 y(Shallo)n(w)f(and)h(deep)g(object)f(cop)o(ying.)0 2977 y(Module)g FJ(marshal)g FN(\(section)h(13.5\):)208 3076 y(High-performance)c(serialization)j(of)h(b)n(uilt-in)g(types.)0 3404 y FE(13.2)121 b Fx(cPickle)32 b FE(\227)g(A)h(f)l(aster)i Fx(pickle)0 3637 y FN(The)21 b FJ(cPickle)g FN(module)f(supports)g (serialization)h(and)g(de-serialization)f(of)h(Python)g(objects,)g(pro) o(viding)e(an)i(interf)o(ace)g(and)g(func-)0 3736 y(tionality)d(nearly) f(identical)h(to)h(the)f FJ(pickle)g FN(module.)23 b(There)17 b(are)i(se)n(v)o(eral)f(dif)n(ferences,)e(the)j(most)f(important)f (being)g(performance)0 3836 y(and)j(subclassability)-5 b(.)0 3983 y(First,)29 b FJ(cPickle)c FN(can)i(be)f(up)g(to)h(1000)e (times)h(f)o(aster)h(than)f FJ(pickle)g FN(because)g(the)g(former)f(is) i(implemented)e(in)i(C.)g(Second,)f(in)0 4082 y(the)i FJ(cPickle)f FN(module)f(the)i(callables)g FJ(Pickler\(\))f FN(and)g FJ(Unpickler\(\))g FN(are)g(functions,)h(not)g(classes.)49 b(This)28 b(means)f(that)0 4182 y(you)e(cannot)g(use)i(them)f(to)g (deri)n(v)o(e)f(custom)h(pickling)f(and)g(unpickling)f(subclasses.)44 b(Most)26 b(applications)f(ha)n(v)o(e)h(no)g(need)f(for)h(this)0 4282 y(functionality)18 b(and)i(should)f(bene\002t)h(from)f(the)h (greatly)f(impro)o(v)o(ed)f(performance)f(of)j(the)g FJ(cPickle)g FN(module.)0 4428 y(The)32 b(pickle)g(data)h(stream)f (produced)e(by)i FJ(pickle)g FN(and)g FJ(cPickle)g FN(are)h(identical,) i(so)e(it)g(is)g(possible)g(to)f(use)h FJ(pickle)f FN(and)0 4528 y FJ(cPickle)19 b FN(interchangeably)e(with)k(e)o(xisting)e (pickles.)1628 4498 y FF(10)0 4675 y FN(There)i(are)h(additional)f (minor)g(dif)n(ferences)g(in)h(API)h(between)e FJ(cPickle)h FN(and)f FJ(pickle)p FN(,)h(ho)n(we)n(v)o(er)e(for)i(most)g (applications,)f(the)o(y)0 4775 y(are)f(interchangeable.)i(More)d (documentation)f(is)j(pro)o(vided)c(in)j(the)g FJ(pickle)g FN(module)f(documentation,)d(which)k(includes)f(a)i(list)g(of)0 4874 y(the)f(documented)e(dif)n(ferences.)p 0 4928 1560 4 v 66 4984 a FB(10)120 5007 y FH(Since)k(the)g(pickle)h(data)f(format) g(is)f(actually)k(a)c(tin)o(y)h(stack-oriented)j(programming)d (language,)j(and)c(some)g(freedom)h(is)g(tak)o(en)h(in)e(the)h (encodings)h(of)e(certain)0 5086 y(objects,)d(it)f(is)f(possible)i (that)g(the)f(tw)o(o)g(modules)g(produce)h(dif)n(ferent)h(data)f (streams)f(for)f(the)h(same)g(input)g(objects.)23 b(Ho)n(we)n(v)o(er)18 b(it)f(is)f(guaranteed)j(that)f(the)o(y)g(will)f(al)o(w)o(ays)0 5165 y(be)g(able)i(to)e(read)h(each)g(other')l(s)g(data)h(streams.)p 0 5549 3901 4 v 0 5649 a FI(370)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 371 383 TeXDict begin 371 382 bop 0 87 a FE(13.3)121 b Fx(copy_reg)31 b FE(\227)i(Register)h Fx(pickle)e FE(suppor)5 b(t)35 b(functions)0 320 y FN(The)18 b FJ(copy_reg)f FN(module)g(pro)o(vides)f (support)h(for)h(the)g FJ(pickle)g FN(and)f FJ(cPickle)h FN(modules.)23 b(The)18 b FJ(copy)g FN(module)f(is)i(lik)o(ely)f(to)g (use)0 420 y(this)k(in)g(the)f(future)g(as)h(well.)30 b(It)22 b(pro)o(vides)d(con\002guration)g(information)g(about)i(object) g(constructors)f(which)h(are)h(not)f(classes.)30 b(Such)0 519 y(constructors)19 b(may)g(be)h(f)o(actory)f(functions)g(or)h(class) h(instances.)0 666 y FD(constructor)p FJ(\()p FK(object)q FJ(\))208 766 y FN(Declares)h FK(object)i FN(to)f(be)g(a)g(v)n(alid)g (constructor)-5 b(.)31 b(If)23 b FK(object)h FN(is)g(not)e(callable)h (\(and)f(hence)g(not)h(v)n(alid)f(as)i(a)f(constructor\),)e(raises)208 866 y FJ(TypeError)p FN(.)0 1012 y FD(pickle)p FJ(\()p FK(type)o(,)e(function)p FC([)p FK(,)f(constructor)c FC(])p FJ(\))208 1112 y FN(Declares)28 b(that)h FK(function)e FN(should)g(be)i(used)f(as)h(a)g(\223reduction\224)e(function)f(for)i (objects)h(of)f(type)g FK(type)p FN(;)33 b FK(type)28 b FN(must)g(not)h(be)f(a)208 1212 y(\223classic\224)23 b(class)g(object.)31 b(\(Classic)23 b(classes)h(are)e(handled)f(dif)n (ferently;)g(see)i(the)g(documentation)c(for)j(the)g FJ(pickle)g FN(module)208 1311 y(for)d(details.\))25 b FK(function)19 b FN(should)g(return)g(either)h(a)h(string)e(or)h(a)h (tuple)f(containing)e(tw)o(o)i(or)g(three)g(elements.)208 1443 y(The)f(optional)g FK(constructor)j FN(parameter)m(,)c(if)i(pro)o (vided,)d(is)22 b(a)e(callable)g(object)g(which)f(can)h(be)g(used)g(to) g(reconstruct)f(the)h(object)208 1542 y(when)k(called)h(with)g(the)g (tuple)f(of)h(ar)o(guments)e(returned)g(by)i FK(function)e FN(at)j(pickling)e(time.)39 b FJ(TypeError)24 b FN(will)i(be)e(raised)h (if)208 1642 y FK(object)c FN(is)g(a)f(class)i(or)e FK(constructor)h FN(is)g(not)f(callable.)208 1773 y(See)g(the)g FJ(pickle)g FN(module)f(for)g(more)h(details)g(on)g(the)g(interf)o(ace)g(e)o (xpected)e(of)i FK(function)f FN(and)h FK(constructor)r FN(.)0 2100 y FE(13.4)121 b Fx(shelve)32 b FE(\227)h(Python)h(object)g (persistence)0 2332 y FN(A)20 b(\223shelf)5 b(\224)20 b(is)h(a)f(persistent,)g(dictionary-lik)o(e)d(object.)24 b(The)c(dif)n(ference)e(with)i(\223dbm\224)f(databases)h(is)h(that)f (the)g(v)n(alues)f(\(not)h(the)g(k)o(e)o(ys!\))0 2432 y(in)i(a)g(shelf)g(can)f(be)h(essentially)g(arbitrary)e(Python)g (objects)i(\227)g(an)o(ything)e(that)h(the)h FJ(pickle)f FN(module)g(can)g(handle.)28 b(This)22 b(includes)0 2532 y(most)k(class)h(instances,)g(recursi)n(v)o(e)e(data)h(types,)h(and)e (objects)h(containing)e(lots)i(of)g(shared)f(sub-objects.)41 b(The)26 b(k)o(e)o(ys)g(are)g(ordinary)0 2631 y(strings.)0 2778 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,\003a)o(g='c')p FC([)p FK(,pr)l(otoc)o(ol=)p Fn(Non)o(e)p FC([)p FK(,writebac)m(k=)p Fn(False)12 b FC(])f(])h(])p FJ(\))208 2878 y FN(Open)28 b(a)h(persistent)f(dictionary)-5 b(.)48 b(The)29 b(\002lename)f (speci\002ed)g(is)i(the)e(base)h(\002lename)f(for)g(the)h(underlying)d (database.)50 b(As)29 b(a)208 2977 y(side-ef)n(fect,)22 b(an)h(e)o(xtension)f(may)h(be)g(added)g(to)g(the)g(\002lename)g(and)g (more)f(than)h(one)g(\002le)h(may)f(be)g(created.)34 b(By)23 b(def)o(ault,)h(the)208 3077 y(underlying)17 b(database)i(\002le)i(is)g(opened)d(for)i(reading)e(and)h(writing.)25 b(The)19 b(optional)g FK(\003a)o(g)g FN(parameter)g(has)h(the)g(same)g (interpreta-)208 3177 y(tion)f(as)i(the)g FK(\003a)o(g)e FN(parameter)g(of)h FJ(anydbm.open)p FN(.)208 3308 y(By)26 b(def)o(ault,)g(v)o(ersion)e(0)i(pickles)f(are)h(used)f(to)h(serialize) g(v)n(alues.)40 b(The)26 b(v)o(ersion)e(of)h(the)h(pickle)f(protocol)f (can)h(be)h(speci\002ed)208 3408 y(with)20 b(the)g FK(pr)l(otocol)g FN(parameter)-5 b(.)49 b(Changed)19 b(in)h(v)o(ersion)f(2.3:)h(The)g FK(pr)l(otocol)f FN(parameter)g(w)o(as)i(added.)208 3539 y(By)e(def)o(ault,)f(mutations)h(to)g(persistent-dictionary)d(mutable)i (entries)h(are)g(not)g(automatically)e(written)i(back.)24 b(If)19 b(the)g(optional)208 3639 y FK(writebac)n(k)26 b FN(parameter)d(is)i(set)g(to)g FK(T)-5 b(rue)p FN(,)26 b(all)f(entries)f(accessed)h(are)f(cached)f(in)i(memory)-5 b(,)23 b(and)h(written)g(back)g(at)h(close)f(time;)208 3738 y(this)c(can)g(mak)o(e)g(it)h(handier)e(to)h(mutate)g(mutable)f (entries)h(in)h(the)f(persistent)g(dictionary)-5 b(,)18 b(b)n(ut,)i(if)h(man)o(y)e(entries)h(are)g(accessed,)208 3838 y(it)j(can)g(consume)e(v)n(ast)i(amounts)f(of)h(memory)e(for)h (the)h(cache,)g(and)f(it)h(can)g(mak)o(e)f(the)h(close)g(operation)e(v) o(ery)h(slo)n(w)h(since)g(all)208 3938 y(accessed)g(entries)g(are)g (written)g(back)f(\(there)g(is)i(no)f(w)o(ay)g(to)h(determine)d(which)i (accessed)g(entries)g(are)g(mutable,)g(nor)f(which)208 4037 y(ones)d(were)i(actually)e(mutated\).)0 4184 y(Shelv)o(e)j (objects)h(support)f(all)i(methods)e(supported)f(by)i(dictionaries.)32 b(This)24 b(eases)g(the)f(transition)f(from)g(dictionary)f(based)i (scripts)0 4284 y(to)d(those)g(requiring)e(persistent)i(storage.)0 4431 y(One)g(additional)f(method)g(is)i(supported:)0 4530 y FD(sync)p FJ(\(\))208 4630 y FN(Write)f(back)e(all)i(entries)g (in)g(the)f(cache)g(if)h(the)f(shelf)h(w)o(as)g(opened)e(with)h FK(writebac)n(k)j FN(set)e(to)g FK(T)-5 b(rue)p FN(.)25 b(Also)20 b(empty)f(the)g(cache)g(and)208 4730 y(synchronize)i(the)j (persistent)f(dictionary)f(on)h(disk,)h(if)g(feasible.)35 b(This)24 b(is)g(called)g(automatically)e(when)h(the)h(shelf)f(is)i (closed)208 4829 y(with)20 b FJ(close\(\))p FN(.)0 5113 y Fv(13.4.1)101 b(Restr)q(ictions)125 5300 y FM(\017)41 b FN(The)18 b(choice)g(of)g(which)g(database)g(package)f(will)j(be)e (used)g(\(such)g(as)i FJ(dbm)p FN(,)e FJ(gdbm)h FN(or)f FJ(bsddb)p FN(\))g(depends)f(on)h(which)g(interf)o(ace)208 5400 y(is)f(a)n(v)n(ailable.)24 b(Therefore)14 b(it)k(is)g(not)e(safe)h (to)g(open)f(the)h(database)f(directly)g(using)h FJ(dbm)p FN(.)24 b(The)16 b(database)g(is)i(also)f(\(unfortunately\))p 0 5549 3901 4 v 0 5649 a FI(13.3.)52 b FJ(copy_reg)22 b FI(\227)h(Register)g FJ(pickle)f FI(suppor)s(t)h(functions)1709 b(371)p eop end %%Page: 372 384 TeXDict begin 372 383 bop 208 83 a FN(subject)17 b(to)i(the)f (limitations)f(of)h FJ(dbm)p FN(,)g(if)h(it)f(is)h(used)f(\227)h(this)f (means)g(that)g(\(the)g(pickled)f(representation)f(of\))h(the)h (objects)g(stored)208 183 y(in)h(the)h(database)e(should)h(be)g(f)o (airly)g(small,)h(and)f(in)g(rare)g(cases)i(k)o(e)o(y)d(collisions)i (may)f(cause)g(the)g(database)g(to)h(refuse)f(updates.)125 448 y FM(\017)41 b FN(Depending)16 b(on)j(the)g(implementation,)e (closing)i(a)g(persistent)g(dictionary)e(may)i(or)g(may)f(not)h(be)g (necessary)f(to)h(\003ush)h(changes)208 548 y(to)f(disk.)24 b(The)19 b FJ(__del__)f FN(method)f(of)i(the)g FJ(Shelf)f FN(class)i(calls)g(the)f FJ(close)f FN(method,)g(so)h(the)g(programmer) d(generally)h(need)208 648 y(not)i(do)h(this)h(e)o(xplicitly)-5 b(.)125 814 y FM(\017)41 b FN(The)19 b FJ(shelve)h FN(module)f(does)g (not)h(support)f FK(concurr)m(ent)g FN(read/write)g(access)i(to)f (shelv)o(ed)f(objects.)25 b(\(Multiple)19 b(simultaneous)208 913 y(read)25 b(accesses)i(are)f(safe.\))42 b(When)26 b(a)g(program)e(has)i(a)h(shelf)f(open)f(for)g(writing,)i(no)e(other)h (program)d(should)i(ha)n(v)o(e)h(it)h(open)208 1013 y(for)d(reading)g (or)h(writing.)41 b(U)t FH(N)t(I)t(X)28 b FN(\002le)e(locking)e(can)h (be)g(used)g(to)h(solv)o(e)e(this,)j(b)n(ut)e(this)h(dif)n(fers)e (across)k(U)t FH(N)t(I)t(X)g FN(v)o(ersions)c(and)208 1112 y(requires)19 b(kno)n(wledge)f(about)h(the)h(database)g (implementation)e(used.)0 1295 y FL(class)j FD(Shelf)p FJ(\()p FK(dict)q FC([)p FK(,)e(pr)l(otocol=None)p FC([)p FK(,)f(writebac)n(k=F)-6 b(alse)12 b FC(])g(])p FJ(\))208 1395 y FN(A)20 b(subclass)h(of)f FJ(UserDict.DictMixin)d FN(which)j(stores)g(pickled)f(v)n(alues)h(in)g(the)h FK(dict)g FN(object.)208 1528 y(By)26 b(def)o(ault,)g(v)o(ersion)e(0)i (pickles)f(are)h(used)f(to)h(serialize)g(v)n(alues.)40 b(The)26 b(v)o(ersion)e(of)h(the)h(pickle)f(protocol)f(can)h(be)h (speci\002ed)208 1627 y(with)18 b(the)h FK(pr)l(otocol)f FN(parameter)-5 b(.)23 b(See)d(the)e FJ(pickle)g FN(documentation)e (for)i(a)h(discussion)f(of)h(the)f(pickle)h(protocols.)48 b(Changed)208 1727 y(in)20 b(v)o(ersion)f(2.3:)g(The)h FK(pr)l(otocol)g FN(parameter)e(w)o(as)j(added.)208 1860 y(If)g(the)h FK(writebac)n(k)i FN(parameter)d(is)i FJ(True)p FN(,)f(the)g(object)f(will)i(hold)e(a)i(cache)e(of)h(all)h(entries)f (accessed)g(and)f(write)h(them)g(back)f(to)208 1959 y(the)e FK(dict)h FN(at)g(sync)f(and)g(close)g(times.)25 b(This)19 b(allo)n(ws)h(natural)e(operations)f(on)i(mutable)f(entries,)h(b)n(ut)g (can)g(consume)f(much)g(more)208 2059 y(memory)g(and)i(mak)o(e)f(sync)h (and)g(close)g(tak)o(e)h(a)f(long)g(time.)0 2206 y FL(class)h FD(BsdDbShelf)p FJ(\()p FK(dict)q FC([)p FK(,)d(pr)l(otocol=None)p FC([)p FK(,)g(writebac)n(k=F)-6 b(alse)12 b FC(])g(])p FJ(\))208 2305 y FN(A)18 b(subclass)g(of)f FJ(Shelf)h FN(which)f(e)o(xposes)g FJ(first)p FN(,)g FJ(next)p FN(,)h FJ(previous)p FN(,)f FJ(last)h FN(and)f FJ(set_location)f FN(which)h(are)h(a)n(v)n(ail-)208 2405 y(able)e(in)h(the)f FJ(bsddb)h FN(module)e(b)n(ut)h(not)h(in)f(other)g(database)g(modules.) 23 b(The)16 b FK(dict)i FN(object)e(passed)g(to)h(the)g(constructor)d (must)j(sup-)208 2505 y(port)22 b(those)h(methods.)34 b(This)23 b(is)h(generally)e(accomplished)g(by)h(calling)g(one)f(of)h FJ(bsddb.hashopen)p FN(,)f FJ(bsddb.btopen)208 2604 y FN(or)i FJ(bsddb.rnopen)p FN(.)38 b(The)25 b(optional)f FK(pr)l(otocol)g FN(and)h FK(writebac)n(k)i FN(parameters)c(ha)n(v)o(e) i(the)g(same)g(interpretation)e(as)j(for)f(the)208 2704 y FJ(Shelf)19 b FN(class.)0 2851 y FL(class)i FD(DbfilenameShelf)p FJ(\()p FK(\002lename)p FC([)p FK(,)15 b(\003a)o(g='c')p FC([)p FK(,)k(pr)l(otocol=None)p FC([)p FK(,)f(writebac)n(k=F)-6 b(alse)12 b FC(])g(])g(])p FJ(\))208 2950 y FN(A)21 b(subclass)g(of)f FJ(Shelf)h FN(which)f(accepts)g(a)i FK(\002lename)d FN(instead)i(of)f (a)h(dict-lik)o(e)f(object.)26 b(The)21 b(underlying)d(\002le)j(will)h (be)e(opened)208 3050 y(using)e FJ(anydbm.open)p FN(.)23 b(By)c(def)o(ault,)f(the)g(\002le)i(will)f(be)g(created)f(and)g(opened) f(for)h(both)g(read)g(and)g(write.)25 b(The)18 b(optional)f FK(\003a)o(g)208 3150 y FN(parameter)e(has)j(the)f(same)h (interpretation)d(as)j(for)f(the)h FJ(open)f FN(function.)22 b(The)17 b(optional)f FK(pr)l(otocol)h FN(and)g FK(writebac)n(k)i FN(parameters)208 3249 y(ha)n(v)o(e)g(the)h(same)h(interpretation)d(as) j(for)e(the)h FJ(Shelf)g FN(class.)0 3534 y Fv(13.4.2)101 b(Example)0 3737 y FN(T)-7 b(o)20 b(summarize)f(the)i(interf)o(ace)e (\()p FJ(key)h FN(is)h(a)g(string,)e FJ(data)h FN(is)h(an)f(arbitrary)f (object\):)p 0 5549 3901 4 v 0 5649 a FI(372)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 373 385 TeXDict begin 373 384 bop 236 174 a FA(import)44 b(shelve)236 357 y(d)h(=)g(shelve.open\(filename\))c(#)k(open)f(--)g(file)g(may)h (get)f(suffix)g(added)g(by)g(low-level)1402 448 y(#)h(library)236 631 y(d[key])f(=)h(data)134 b(#)44 b(store)g(data)g(at)h(key)f (\(overwrites)f(old)h(data)h(if)954 722 y(#)f(using)g(an)h(existing)e (key\))236 814 y(data)h(=)h(d[key])134 b(#)44 b(retrieve)g(a)g(COPY)h (of)f(data)g(at)h(key)f(\(raise)g(KeyError)f(if)i(no)954 905 y(#)f(such)g(key\))236 996 y(del)h(d[key])268 b(#)44 b(delete)g(data)g(stored)g(at)g(key)h(\(raises)e(KeyError)954 1088 y(#)h(if)h(no)f(such)g(key\))236 1179 y(flag)g(=)h (d.has_key\(key\))132 b(#)45 b(true)f(if)h(the)f(key)g(exists)236 1270 y(klist)g(=)h(d.keys\(\))e(#)i(a)g(list)f(of)g(all)h(existing)e (keys)h(\(slow!\))236 1453 y(#)h(as)f(d)h(was)f(opened)g(WITHOUT)g (writeback=True,)e(beware:)236 1544 y(d['xx'])i(=)h(range\(4\))88 b(#)45 b(this)f(works)g(as)g(expected,)f(but...)236 1636 y(d['xx'].append\(5\))132 b(#)1223 1649 y(*)1268 1636 y(this)44 b(doesn't!)1852 1649 y(*)1940 1636 y(--)g(d['xx'])g(is)g (STILL)g(range\(4\)!!!)236 1818 y(#)h(having)f(opened)g(d)g(without)g (writeback=True,)e(you)i(need)h(to)f(code)g(carefully:)236 1910 y(temp)g(=)h(d['xx'])268 b(#)45 b(extracts)e(the)h(copy)236 2001 y(temp.append\(5\))267 b(#)45 b(mutates)e(the)i(copy)236 2092 y(d['xx'])f(=)h(temp)268 b(#)45 b(stores)e(the)i(copy)f(right)g (back,)g(to)g(persist)g(it)236 2275 y(#)h(or,)f (d=shelve.open\(filename,writeback=True\))39 b(would)44 b(let)g(you)g(just)g(code)236 2366 y(#)h(d['xx'].append\(5\))d(and)i (have)g(it)h(work)f(as)g(expected,)g(BUT)g(it)h(would)f(also)236 2457 y(#)h(consume)f(more)g(memory)g(and)g(make)g(the)g(d.close\(\))g (operation)f(slower.)236 2640 y(d.close\(\))313 b(#)44 b(close)g(it)0 2927 y FL(See)21 b(Also:)0 3074 y FN(Module)e FJ(anydbm)h FN(\(section)f(13.6\):)208 3174 y(Generic)g(interf)o(ace)g (to)i FJ(dbm)p FN(-style)e(databases.)0 3321 y(Module)g FJ(bsddb)h FN(\(section)f(13.11\):)208 3420 y(BSD)i FJ(db)f FN(database)g(interf)o(ace.)0 3567 y(Module)f FJ(dbhash)h FN(\(section)f(13.10\):)208 3667 y(Thin)g(layer)h(around)e(the)i FJ(bsddb)g FN(which)g(pro)o(vides)e(an)i FJ(open)g FN(function)f(lik)o (e)h(the)h(other)e(database)h(modules.)0 3814 y(Module)f FJ(dbm)h FN(\(section)g(13.8\):)208 3913 y(Standard)g(U)t FH(N)t(I)t(X)k FN(database)19 b(interf)o(ace.)0 4060 y(Module)g FJ(dumbdbm)g FN(\(section)h(13.12\):)208 4160 y(Portable)f(implementation)f(of)i(the)g FJ(dbm)g FN(interf)o(ace.)0 4307 y(Module)f FJ(gdbm)h FN(\(section)g(13.9\):)208 4406 y(GNU)g(database)g(interf)o(ace,)f(based)h(on)f(the)i FJ(dbm)f FN(interf)o(ace.)0 4553 y(Module)f FJ(pickle)h FN(\(section)f(13.1\):)208 4653 y(Object)h(serialization)f(used)h(by)g FJ(shelve)p FN(.)0 4800 y(Module)f FJ(cPickle)g FN(\(section)h(13.2\):) 208 4899 y(High-performance)c(v)o(ersion)i(of)i FJ(pickle)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(13.4.)52 b FJ(shelve)22 b FI(\227)h(Python)h(object)f(persistence)2147 b(373)p eop end %%Page: 374 386 TeXDict begin 374 385 bop 0 86 a FE(13.5)121 b Fx(marshal)32 b FE(\227)g(Inter)s(nal)j(Python)g(object)f(ser)r(ialization)0 319 y FN(This)26 b(module)f(contains)g(functions)f(that)i(can)g(read)f (and)h(write)g(Python)f(v)n(alues)g(in)h(a)g(binary)f(format.)41 b(The)26 b(format)e(is)j(speci\002c)f(to)0 419 y(Python,)19 b(b)n(ut)h(independent)e(of)i(machine)g(architecture)f(issues)i (\(e.g.,)e(you)h(can)g(write)g(a)h(Python)f(v)n(alue)f(to)i(a)g(\002le) g(on)f(a)h(PC,)g(transport)0 518 y(the)h(\002le)g(to)g(a)g(Sun,)f(and)g (read)g(it)h(back)f(there\).)29 b(Details)22 b(of)f(the)h(format)e(are) i(undocumented)c(on)j(purpose;)g(it)h(may)f(change)f(between)0 618 y(Python)f(v)o(ersions)g(\(although)f(it)j(rarely)f(does\).)1375 588 y FF(11)0 765 y FN(This)32 b(is)g(not)f(a)h(general)f (\223persistence\224)g(module.)57 b(F)o(or)32 b(general)e(persistence)h (and)g(transfer)g(of)g(Python)f(objects)i(through)d(RPC)0 865 y(calls,)e(see)f(the)g(modules)e FJ(pickle)h FN(and)g FJ(shelve)p FN(.)40 b(The)25 b FJ(marshal)f FN(module)g(e)o(xists)i (mainly)f(to)g(support)f(reading)g(and)h(writing)0 964 y(the)g(\223pseudo-compiled\224)c(code)j(for)g(Python)g(modules)f(of)i (`)p FO(.p)n(yc)p FN(')f(\002les.)40 b(Therefore,)23 b(the)i(Python)f(maintainers)g(reserv)o(e)f(the)i(right)0 1064 y(to)k(modify)e(the)i(marshal)g(format)e(in)i(backw)o(ard)f (incompatible)f(w)o(ays)i(should)f(the)h(need)f(arise.)52 b(If)28 b(you')l(re)f(serializing)i(and)f(de-)0 1163 y(serializing)20 b(Python)g(objects,)h(use)g(the)g FJ(pickle)f FN(module)f(instead)i(\227)h(the)e(performance)e(is)k(comparable,)d(v)o (ersion)h(independence)0 1263 y(is)h(guaranteed,)d(and)h(pickle)h (supports)f(a)i(substantially)e(wider)h(range)f(of)h(objects)g(than)g (marshal.)p 0 1353 3901 17 v 0 1627 17 275 v 75 1468 a FL(W)-5 b(ar)o(ning:)48 b FN(The)19 b FJ(marshal)f FN(module)f(is)j(not)e(intended)g(to)h(be)f(secure)h(against)f (erroneous)f(or)h(maliciously)g(constructed)f(data.)75 1568 y(Ne)n(v)o(er)i(unmarshal)g(data)h(recei)n(v)o(ed)e(from)h(an)i (untrusted)d(or)i(unauthenticated)e(source.)p 3883 1627 V 0 1644 3901 17 v 0 1799 a(Not)31 b(all)h(Python)e(object)h(types)g (are)g(supported;)j(in)e(general,)g(only)e(objects)h(whose)g(v)n(alue)g (is)h(independent)c(from)i(a)i(particular)0 1899 y(in)m(v)n(ocation)17 b(of)h(Python)g(can)g(be)h(written)f(and)g(read)g(by)h(this)g(module.)k (The)18 b(follo)n(wing)f(types)i(are)f(supported:)23 b FJ(None)p FN(,)18 b(inte)o(gers,)g(long)0 1998 y(inte)o(gers,)25 b(\003oating)g(point)f(numbers,)h(strings,)h(Unicode)f(objects,)h (tuples,)g(lists,)h(sets,)h(dictionaries,)d(and)g(code)f(objects,)i (where)f(it)0 2098 y(should)d(be)g(understood)e(that)j(tuples,)g(lists) h(and)e(dictionaries)g(are)g(only)g(supported)f(as)i(long)f(as)h(the)g (v)n(alues)f(contained)f(therein)h(are)0 2198 y(themselv)o(es)d (supported;)g(and)g(recursi)n(v)o(e)g(lists)j(and)d(dictionaries)g (should)h(not)f(be)i(written)f(\(the)o(y)f(will)i(cause)f(in\002nite)g (loops\).)p 0 2288 V 0 2579 17 292 v 75 2403 a FL(W)-5 b(ar)o(ning:)47 b FN(Some)17 b(unsupported)d(types)j(such)g(as)h (subclasses)g(of)f(b)n(uiltins)g(will)h(appear)e(to)i(marshal)e(and)h (unmarshal)f(correctly)-5 b(,)75 2503 y(b)n(ut)20 b(in)g(f)o(act,)g (their)g(type)g(will)h(change)e(and)g(the)i(additional)e(subclass)h (functionality)e(and)i(instance)g(attrib)n(utes)g(will)h(be)f(lost.)p 3883 2579 V 0 2595 3901 17 v 0 2751 a FL(Ca)n(v)o(eat:)33 b FN(On)25 b(machines)f(where)h(C')-5 b(s)26 b FJ(long)49 b(int)25 b FN(type)g(has)g(more)f(than)h(32)f(bits)i(\(such)e(as)i(the) f(DEC)h(Alpha\),)f(it)h(is)g(possible)e(to)0 2850 y(create)19 b(plain)f(Python)g(inte)o(gers)h(that)g(are)g(longer)e(than)i(32)g (bits.)25 b(If)19 b(such)f(an)h(inte)o(ger)f(is)i(marshaled)e(and)h (read)f(back)g(in)i(on)e(a)i(machine)0 2950 y(where)d(C')-5 b(s)18 b FJ(long)50 b(int)17 b FN(type)g(has)h(only)e(32)h(bits,)h(a)g (Python)e(long)h(inte)o(ger)f(object)h(is)h(returned)e(instead.)24 b(While)18 b(of)f(a)h(dif)n(ferent)d(type,)0 3049 y(the)21 b(numeric)f(v)n(alue)g(is)i(the)f(same.)28 b(\(This)20 b(beha)n(vior)g(is)i(ne)n(w)f(in)g(Python)f(2.2.)27 b(In)20 b(earlier)h(v)o(ersions,)f(all)i(b)n(ut)f(the)g(least-signi\002cant)f (32)0 3149 y(bits)h(of)f(the)g(v)n(alue)f(were)h(lost,)h(and)f(a)g(w)o (arning)f(message)h(w)o(as)h(printed.\))0 3296 y(There)e(are)h (functions)f(that)i(read/write)e(\002les)i(as)g(well)g(as)g(functions)d (operating)h(on)g(strings.)0 3443 y(The)h(module)f(de\002nes)h(these)g (functions:)0 3590 y FD(dump)p FJ(\()p FK(value)o(,)f(\002le)p FC([)p FK(,)g(ver)o(sion)12 b FC(])p FJ(\))208 3689 y FN(Write)22 b(the)f(v)n(alue)g(on)g(the)h(open)e(\002le.)30 b(The)21 b(v)n(alue)g(must)g(be)h(a)g(supported)d(type.)28 b(The)22 b(\002le)g(must)f(be)h(an)f(open)g(\002le)h(object)f(such)208 3789 y(as)h FJ(sys.stdout)f FN(or)h(returned)f(by)g FJ(open\(\))h FN(or)g FJ(posix.popen\(\))p FN(.)29 b(It)22 b(must)g(be)g(opened)f(in) h(binary)f(mode)g(\()p FJ('wb')h FN(or)208 3889 y FJ('w+b')p FN(\).)208 4021 y(If)d(the)g(v)n(alue)g(has)h(\(or)e(contains)h(an)g (object)g(that)h(has\))f(an)g(unsupported)e(type,)i(a)g FJ(ValueError)g FN(e)o(xception)e(is)j(raised)g(\227)g(b)n(ut)208 4121 y(garbage)e(data)i(will)h(also)f(be)g(written)g(to)h(the)f (\002le.)25 b(The)20 b(object)g(will)h(not)f(be)g(properly)e(read)h (back)h(by)g FJ(load\(\))p FN(.)208 4254 y(Ne)n(w)g(in)g(v)o(ersion)f (2.4:)h(The)g FK(ver)o(sion)g FN(ar)o(gument)e(indicates)i(the)g(data)g (format)f(that)h FJ(dump)g FN(should)g(use)g(\(see)g(belo)n(w\).)0 4401 y FD(load)p FJ(\()p FK(\002le)p FJ(\))208 4500 y FN(Read)j(one)g(v)n(alue)f(from)h(the)g(open)f(\002le)i(and)f(return)f (it.)35 b(If)23 b(no)g(v)n(alid)g(v)n(alue)g(is)h(read,)f(raise)h FJ(EOFError)p FN(,)f FJ(ValueError)f FN(or)208 4600 y FJ(TypeError)p FN(.)h(The)d(\002le)h(must)f(be)g(an)h(open)e(\002le)i (object)e(opened)g(in)h(binary)f(mode)g(\()p FJ('rb')h FN(or)g FJ('r+b')p FN(\).)208 4733 y FL(W)-5 b(ar)o(ning:)28 b FN(If)22 b(an)g(object)g(containing)f(an)h(unsupported)d(type)j(w)o (as)h(marshalled)e(with)i FJ(dump\(\))p FN(,)f FJ(load\(\))g FN(will)h(substitute)208 4832 y FJ(None)d FN(for)f(the)h (unmarshallable)e(type.)0 4979 y FD(dumps)p FJ(\()p FK(value)p FC([)p FK(,)g(ver)o(sion)12 b FC(])p FJ(\))208 5079 y FN(Return)24 b(the)g(string)g(that)h(w)o(ould)f(be)g(written)h(to)f(a)h (\002le)g(by)f FJ(dump\()p FK(value)p FJ(,)48 b FK(\002le)p FJ(\))p FN(.)38 b(The)24 b(v)n(alue)g(must)g(be)h(a)g(supported)d (type.)p 0 5150 1560 4 v 66 5206 a FB(11)120 5229 y FH(The)15 b(name)i(of)f(this)g(module)h(stems)f(from)g(a)g(bit)h(of)e (terminology)k(used)d(by)g(the)h(designers)g(of)f(Modula-3)i(\(amongst) e(others\),)h(who)f(use)g(the)h(term)f(\223marshalling\224)0 5308 y(for)i(shipping)h(of)f(data)g(around)h(in)f(a)g(self-contained)k (form.)g(Strictly)e(speaking,)f(\223to)g(marshal\224)g(means)f(to)g (con)m(v)o(ert)h(some)f(data)h(from)e(internal)k(to)d(e)o(xternal)i (form)d(\(in)0 5387 y(an)g(RPC)g(b)o(uf)n(fer)h(for)f(instance\))j(and) d(\223unmarshalling\224)k(for)c(the)h(re)n(v)o(erse)g(process.)p 0 5549 3901 4 v 0 5649 a FI(374)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 375 387 TeXDict begin 375 386 bop 208 83 a FN(Raise)21 b(a)f FJ(ValueError)f FN(e)o(xception)g(if)h(v)n(alue)g(has)g(\(or)g (contains)f(an)h(object)g(that)g(has\))g(an)g(unsupported)d(type.)208 216 y(Ne)n(w)j(in)g(v)o(ersion)f(2.4:)h(The)g FK(ver)o(sion)g FN(ar)o(gument)e(indicates)i(the)g(data)g(format)f(that)h FJ(dumps)g FN(should)f(use)i(\(see)f(belo)n(w\).)0 363 y FD(loads)p FJ(\()p FK(string)p FJ(\))208 462 y FN(Con)m(v)o(ert)26 b(the)i(string)f(to)h(a)g(v)n(alue.)47 b(If)28 b(no)f(v)n(alid)g(v)n (alue)g(is)i(found,)f(raise)g FJ(EOFError)p FN(,)g FJ(ValueError)e FN(or)i FJ(TypeError)p FN(.)208 562 y(Extra)19 b(characters)g(in)i(the) f(string)g(are)g(ignored.)0 709 y(In)g(addition,)f(the)h(follo)n(wing)e (constants)i(are)g(de\002ned:)0 856 y FD(version)208 955 y FN(Indicates)k(the)i(format)e(that)i(the)f(module)g(uses.)41 b(V)-9 b(ersion)25 b(0)g(is)i(the)e(historical)g(format,)h(v)o(ersion)e (1)i(\(added)e(in)h(Python)g(2.4\))208 1055 y(shares)19 b(interned)e(strings)i(and)g(v)o(ersion)f(2)h(\(added)f(in)h(Python)f (2.5\))g(uses)h(a)h(binary)e(format)g(for)g(\003oating)h(point)f (numbers.)23 b(The)208 1155 y(current)18 b(v)o(ersion)h(is)i(2.)208 1287 y(Ne)n(w)f(in)g(v)o(ersion)f(2.4.)0 1615 y FE(13.6)121 b Fx(anydbm)32 b FE(\227)h(Gener)r(ic)g(access)g(to)h(DBM-style)f (databases)0 1848 y FJ(anydbm)17 b FN(is)i(a)f(generic)e(interf)o(ace)h (to)h(v)n(ariants)f(of)g(the)h(DBM)g(database)f(\227)h FJ(dbhash)g FN(\(requires)e FJ(bsddb)p FN(\),)h FJ(gdbm)p FN(,)h(or)f FJ(dbm)p FN(.)24 b(If)18 b(none)0 1947 y(of)i(these)g (modules)f(is)j(installed,)d(the)i(slo)n(w-b)n(ut-simple)d (implementation)g(in)j(module)d FJ(dumbdbm)i FN(will)h(be)f(used.)0 2094 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)e(\003a)o(g)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 2194 y FN(Open)19 b(the)h(database)g(\002le)h FK(\002lename)e FN(and)g(return)g(a)i (corresponding)c(object.)208 2327 y(If)f(the)i(database)e(\002le)i (already)e(e)o(xists,)h(the)h FJ(whichdb)e FN(module)g(is)h(used)g(to)g (determine)f(its)i(type)f(and)f(the)h(appropriate)e(module)208 2426 y(is)21 b(used;)f(if)g(it)h(does)f(not)g(e)o(xist,)g(the)g (\002rst)h(module)e(listed)i(abo)o(v)o(e)d(that)i(can)g(be)h(imported)d (is)j(used.)208 2559 y(The)h(optional)f FK(\003a)o(g)g FN(ar)o(gument)f(can)i(be)h FJ('r')f FN(to)h(open)e(an)h(e)o(xisting)g (database)g(for)f(reading)g(only)-5 b(,)22 b FJ('w')g FN(to)h(open)e(an)h(e)o(xisting)208 2659 y(database)c(for)g(reading)f (and)h(writing,)g FJ('c')h FN(to)g(create)f(the)h(database)f(if)h(it)g (doesn')o(t)e(e)o(xist,)i(or)f FJ('n')p FN(,)h(which)f(will)i(al)o(w)o (ays)f(create)208 2758 y(a)h(ne)n(w)g(empty)f(database.)25 b(If)20 b(not)g(speci\002ed,)f(the)i(def)o(ault)e(v)n(alue)h(is)h FJ('r')p FN(.)208 2891 y(The)k(optional)f FK(mode)g FN(ar)o(gument)f (is)k(the)g(U)t FH(N)t(I)t(X)h FN(mode)d(of)g(the)g(\002le,)i(used)e (only)g(when)f(the)i(database)e(has)i(to)f(be)h(created.)39 b(It)208 2991 y(def)o(aults)19 b(to)i(octal)f FJ(0666)g FN(\(and)f(will)i(be)f(modi\002ed)f(by)h(the)g(pre)n(v)n(ailing)e (umask\).)0 3138 y FL(exception)h FD(error)208 3237 y FN(A)h(tuple)g(containing)f(the)h(e)o(xceptions)f(that)i(can)f(be)g (raised)g(by)g(each)g(of)g(the)h(supported)d(modules,)h(with)i(a)g (unique)d(e)o(xception)208 3337 y FJ(anydbm.error)g FN(as)j(the)f (\002rst)h(item)f(\227)h(the)f(latter)h(is)g(used)f(when)f FJ(anydbm.error)g FN(is)i(raised.)0 3484 y(The)e(object)h(returned)d (by)j FJ(open\(\))f FN(supports)f(most)i(of)g(the)f(same)h (functionality)e(as)i(dictionaries;)f(k)o(e)o(ys)g(and)h(their)f (corresponding)0 3583 y(v)n(alues)29 b(can)g(be)g(stored,)h(retrie)n(v) o(ed,)g(and)e(deleted,)j(and)d(the)i FJ(has_key\(\))e FN(and)g FJ(keys\(\))h FN(methods)f(are)h(a)n(v)n(ailable.)51 b(K)n(e)o(ys)29 b(and)0 3683 y(v)n(alues)20 b(must)g(al)o(w)o(ays)h(be) f(strings.)0 3830 y(The)29 b(follo)n(wing)f(e)o(xample)g(records)g (some)h(hostnames)g(and)g(a)g(corresponding)d(title,)32 b(and)d(then)g(prints)g(out)g(the)h(contents)e(of)i(the)0 3930 y(database:)p 0 5549 3901 4 v 0 5649 a FI(13.6.)52 b FJ(anydbm)22 b FI(\227)h(Gener)q(ic)g(access)f(to)h(DBM-style)g (databases)1620 b(375)p eop end %%Page: 376 388 TeXDict begin 376 387 bop 236 174 a FA(import)44 b(anydbm)236 357 y(#)h(Open)f(database,)f(creating)h(it)g(if)h(necessary.)236 448 y(db)g(=)f(anydbm.open\('cache',)e('c'\))236 631 y(#)j(Record)f(some)g(values)236 722 y(db['www.python.org'])e(=)i ('Python)g(Website')236 814 y(db['www.cnn.com'])e(=)j('Cable)f(News)g (Network')236 996 y(#)h(Loop)f(through)g(contents.)88 b(Other)44 b(dictionary)f(methods)236 1088 y(#)i(such)f(as)h (.keys\(\),)e(.values\(\))g(also)i(work.)236 1179 y(for)g(k,)f(v)h(in)f (db.iteritems\(\):)416 1270 y(print)g(k,)g('\\t',)g(v)236 1453 y(#)h(Storing)f(a)g(non-string)f(key)i(or)f(value)g(will)g(raise)g (an)h(exception)e(\(most)236 1544 y(#)i(likely)f(a)g(TypeError\).)236 1636 y(db['www.yahoo.com'])e(=)j(4)236 1818 y(#)g(Close)f(when)g(done.) 236 1910 y(db.close\(\))0 2197 y FL(See)21 b(Also:)0 2343 y FN(Module)e FJ(dbhash)h FN(\(section)f(13.10\):)208 2443 y(BSD)i FJ(db)f FN(database)g(interf)o(ace.)0 2590 y(Module)f FJ(dbm)h FN(\(section)g(13.8\):)208 2690 y(Standard)g(U)t FH(N)t(I)t(X)k FN(database)19 b(interf)o(ace.)0 2836 y(Module)g FJ(dumbdbm)g FN(\(section)h(13.12\):)208 2936 y(Portable)f(implementation)f(of)i(the)g FJ(dbm)g FN(interf)o(ace.)0 3083 y(Module)f FJ(gdbm)h FN(\(section)g(13.9\):)208 3183 y(GNU)g(database)g(interf)o(ace,)f(based)h(on)f(the)i FJ(dbm)f FN(interf)o(ace.)0 3329 y(Module)f FJ(shelve)h FN(\(section)f(13.4\):)208 3429 y(General)g(object)h(persistence)f(b)n (uilt)i(on)e(top)h(of)g(the)g(Python)f FJ(dbm)i FN(interf)o(ace.)0 3576 y(Module)e FJ(whichdb)g FN(\(section)h(13.7\):)208 3676 y(Utility)g(module)f(used)h(to)g(determine)f(the)h(type)g(of)g(an) g(e)o(xisting)f(database.)0 4003 y FE(13.7)121 b Fx(whichdb)32 b FE(\227)g(Guess)i(which)g(DBM)f(module)h(created)h(a)f(database)0 4236 y FN(The)26 b(single)g(function)f(in)h(this)h(module)e(attempts)h (to)h(guess)f(which)g(of)g(the)g(se)n(v)o(eral)g(simple)g(database)g (modules)f(a)n(v)n(ailable\226)p FJ(dbm)p FN(,)0 4335 y FJ(gdbm)p FN(,)20 b(or)g FJ(dbhash)p FN(\226should)d(be)j(used)g(to)h (open)e(a)h(gi)n(v)o(en)f(\002le.)0 4482 y FD(whichdb)p FJ(\()p FK(\002lename)p FJ(\))208 4582 y FN(Returns)j(one)h(of)f(the)h (follo)n(wing)f(v)n(alues:)30 b FJ(None)23 b FN(if)g(the)g(\002le)g (can')o(t)f(be)h(opened)e(because)i(it')-5 b(s)24 b(unreadable)c(or)j (doesn')o(t)e(e)o(xist;)208 4682 y(the)c(empty)g(string)h(\()p FJ('')p FN(\))f(if)h(the)g(\002le')-5 b(s)19 b(format)d(can')o(t)h(be)h (guessed;)g(or)g(a)g(string)f(containing)f(the)i(required)e(module)g (name,)i(such)208 4781 y(as)i FJ('dbm')g FN(or)g FJ('gdbm')p FN(.)0 5109 y FE(13.8)121 b Fx(dbm)33 b FE(\227)f(Simple)h (\223database\224)j(interf)l(ace)p 0 5549 3901 4 v 0 5649 a FI(376)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 377 389 TeXDict begin 377 388 bop 0 83 a FN(The)19 b FJ(dbm)g FN(module)f(pro)o(vides)g(an)h(interf)o(ace)g(to)g(the)j(U)t FH(N)t(I)t(X)g FN(\()p FJ(n)p FN(\))p FJ(dbm)d FN(library)-5 b(.)23 b(Dbm)c(objects)g(beha)n(v)o(e)f(lik)o(e)i(mappings)e (\(dictionaries\),)0 183 y(e)o(xcept)30 b(that)h(k)o(e)o(ys)g(and)f(v)n (alues)h(are)g(al)o(w)o(ays)g(strings.)58 b(Printing)30 b(a)h(dbm)f(object)h(doesn')o(t)e(print)i(the)g(k)o(e)o(ys)g(and)f(v)n (alues,)j(and)e(the)0 282 y FJ(items\(\))19 b FN(and)h FJ(values\(\))f FN(methods)g(are)i(not)e(supported.)0 429 y(This)i(module)e(can)i(be)f(used)h(with)g(the)f(\223classic\224)i (ndbm)d(interf)o(ace,)h(the)h(BSD)g(DB)h(compatibility)d(interf)o(ace,) h(or)g(the)h(GNU)g(GDBM)0 529 y(compatibility)i(interf)o(ace.)39 b(On)27 b(U)t FH(N)t(I)t(X)r FN(,)g(the)e FL(con\002gur)o(e)f FN(script)h(will)h(attempt)e(to)h(locate)g(the)g(appropriate)e(header)g (\002le)j(to)f(simplify)0 628 y(b)n(uilding)19 b(this)i(module.)0 775 y(The)f(module)f(de\002nes)h(the)g(follo)n(wing:)0 922 y FL(exception)f FD(error)208 1022 y FN(Raised)h(on)f (dbm-speci\002c)e(errors,)i(such)g(as)h(I/O)g(errors.)k FJ(KeyError)18 b FN(is)i(raised)g(for)e(general)h(mapping)e(errors)i (lik)o(e)h(specify-)208 1121 y(ing)f(an)i(incorrect)d(k)o(e)o(y)-5 b(.)0 1268 y FD(library)208 1368 y FN(Name)20 b(of)f(the)i FJ(ndbm)f FN(implementation)e(library)h(used.)0 1515 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(\003a)o(g)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 1614 y FN(Open)20 b(a)h(dbm)f(database)g(and)h(return)e(a)j(dbm)e(object.)26 b(The)20 b FK(\002lename)g FN(ar)o(gument)f(is)i(the)g(name)f(of)h(the) g(database)f(\002le)i(\(without)208 1714 y(the)f(`)p FO(.dir)p FN(')f(or)h(`)p FO(.pag)p FN(')f(e)o(xtensions;)h(note)g (that)h(the)f(BSD)i(DB)f(implementation)d(of)i(the)h(interf)o(ace)f (will)h(append)e(the)h(e)o(xtension)208 1814 y(`)p FO(.db)p FN(')d(and)i(only)f(create)h(one)g(\002le\).)208 1946 y(The)f(optional)g FK(\003a)o(g)h FN(ar)o(gument)e(must)i(be)g(one)g (of)g(these)g(v)n(alues:)789 2076 y FL(V)-8 b(alue)p 1037 2106 4 100 v 100 w(Meaning)p 740 2109 2629 4 v 815 2179 a FJ('r')p 1037 2209 4 100 v 124 w FN(Open)20 b(e)o(xisting)f (database)h(for)f(reading)g(only)g(\(def)o(ault\))815 2278 y FJ('w')p 1037 2308 V 124 w FN(Open)h(e)o(xisting)f(database)h (for)f(reading)g(and)g(writing)815 2378 y FJ('c')p 1037 2408 V 124 w FN(Open)h(database)f(for)h(reading)e(and)i(writing,)f (creating)h(it)g(if)h(it)g(doesn')o(t)e(e)o(xist)815 2478 y FJ('n')p 1037 2507 V 124 w FN(Al)o(w)o(ays)i(create)f(a)g(ne)n (w)-5 b(,)20 b(empty)f(database,)g(open)g(for)h(reading)f(and)g (writing)208 2606 y(The)25 b(optional)f FK(mode)g FN(ar)o(gument)f(is)k (the)g(U)t FH(N)t(I)t(X)h FN(mode)d(of)g(the)g(\002le,)i(used)e(only)g (when)f(the)i(database)e(has)i(to)f(be)h(created.)39 b(It)208 2705 y(def)o(aults)19 b(to)i(octal)f FJ(0666)p FN(.)0 2852 y FL(See)h(Also:)0 2999 y FN(Module)e FJ(anydbm)h FN(\(section)f(13.6\):)208 3099 y(Generic)g(interf)o(ace)g(to)i FJ(dbm)p FN(-style)e(databases.)0 3246 y(Module)g FJ(gdbm)h FN(\(section)g(13.9\):)208 3345 y(Similar)g(interf)o(ace)f(to)h(the)h (GNU)f(GDBM)h(library)-5 b(.)0 3492 y(Module)19 b FJ(whichdb)g FN(\(section)h(13.7\):)208 3592 y(Utility)g(module)f(used)h(to)g (determine)f(the)h(type)g(of)g(an)g(e)o(xisting)f(database.)0 3919 y FE(13.9)121 b Fx(gdbm)32 b FE(\227)h(GNU')-6 b(s)33 b(reinter)t(pretation)j(of)e(dbm)0 4152 y FN(This)c(module)f(is)h (quite)g(similar)g(to)g(the)g FJ(dbm)g FN(module,)h(b)n(ut)e(uses)i FJ(gdbm)f FN(instead)f(to)h(pro)o(vide)e(some)i(additional)e (functionality)-5 b(.)0 4252 y(Please)21 b(note)f(that)g(the)g(\002le)h (formats)e(created)h(by)g FJ(gdbm)g FN(and)f FJ(dbm)h FN(are)h(incompatible.)0 4398 y(The)e FJ(gdbm)g FN(module)f(pro)o (vides)f(an)i(interf)o(ace)g(to)g(the)g(GNU)h(DBM)g(library)-5 b(.)23 b FJ(gdbm)c FN(objects)g(beha)n(v)o(e)f(lik)o(e)h(mappings)f (\(dictionaries\),)0 4498 y(e)o(xcept)28 b(that)g(k)o(e)o(ys)h(and)f(v) n(alues)g(are)g(al)o(w)o(ays)h(strings.)50 b(Printing)28 b(a)h FJ(gdbm)g FN(object)f(doesn')o(t)f(print)h(the)g(k)o(e)o(ys)g (and)g(v)n(alues,)j(and)d(the)0 4598 y FJ(items\(\))19 b FN(and)h FJ(values\(\))f FN(methods)g(are)i(not)e(supported.)0 4745 y(The)h(module)f(de\002nes)h(the)g(follo)n(wing)e(constant)i(and)f (functions:)0 4891 y FL(exception)g FD(error)208 4991 y FN(Raised)i(on)f FJ(gdbm)p FN(-speci\002c)f(errors,)h(such)g(as)h (I/O)g(errors.)k FJ(KeyError)20 b FN(is)h(raised)f(for)g(general)g (mapping)e(errors)i(lik)o(e)h(speci-)208 5091 y(fying)e(an)h(incorrect) f(k)o(e)o(y)-5 b(.)0 5238 y FD(open)p FJ(\()p FK(\002lename)o(,)18 b FC([)p FK(\003a)o(g)o(,)h FC([)p FK(mode)12 b FC(])g(])p FJ(\))208 5337 y FN(Open)19 b(a)i FJ(gdbm)f FN(database)f(and)h(return) f(a)i FJ(gdbm)f FN(object.)k(The)c FK(\002lename)f FN(ar)o(gument)f(is) j(the)f(name)g(of)g(the)g(database)f(\002le.)p 0 5549 3901 4 v 0 5649 a FI(13.9.)52 b FJ(gdbm)23 b FI(\227)g(GNU')l(s)f (reinter)r(pretation)j(of)e(dbm)2097 b(377)p eop end %%Page: 378 390 TeXDict begin 378 389 bop 208 83 a FN(The)18 b(optional)g FK(\003a)o(g)h FN(ar)o(gument)e(can)i(be)g FJ('r')g FN(\(to)g(open)f (an)h(e)o(xisting)f(database)h(for)g(reading)e(only)i(\227)g(def)o (ault\),)f FJ('w')i FN(\(to)f(open)208 183 y(an)e(e)o(xisting)f (database)h(for)g(reading)e(and)i(writing\),)g FJ('c')g FN(\(which)f(creates)i(the)f(database)g(if)g(it)h(doesn')o(t)e(e)o (xist\),)h(or)g FJ('n')g FN(\(which)208 282 y(al)o(w)o(ays)j(creates)g (a)h(ne)n(w)f(empty)f(database\).)208 415 y(The)g(follo)n(wing)g (additional)g(characters)g(may)h(be)g(appended)e(to)i(the)g(\003ag)h (to)f(control)f(ho)n(w)h(the)g(database)f(is)i(opened:)349 628 y FM(\017)o FJ('f')f FN(\227)h(Open)f(the)g(database)g(in)g(f)o (ast)h(mode.)j(Writes)d(to)f(the)g(database)g(will)h(not)f(be)g (synchronized.)349 761 y FM(\017)o FJ('s')25 b FN(\227)f(Synchronized)e (mode.)36 b(This)25 b(will)g(cause)f(changes)f(to)i(the)f(database)g (will)h(be)f(immediately)f(written)h(to)h(the)390 861 y(\002le.)349 994 y FM(\017)o FJ('u')20 b FN(\227)h(Do)f(not)g(lock)g (database.)208 1207 y(Not)e(all)h(\003ags)f(are)g(v)n(alid)g(for)g(all) g(v)o(ersions)g(of)g FJ(gdbm)p FN(.)24 b(The)18 b(module)e(constant)i FJ(open_flags)f FN(is)i(a)f(string)g(of)g(supported)e(\003ag)208 1307 y(characters.)24 b(The)19 b(e)o(xception)g FJ(error)h FN(is)h(raised)f(if)g(an)g(in)m(v)n(alid)f(\003ag)i(is)g(speci\002ed.) 208 1439 y(The)k(optional)f FK(mode)g FN(ar)o(gument)f(is)k(the)g(U)t FH(N)t(I)t(X)h FN(mode)d(of)g(the)g(\002le,)i(used)e(only)g(when)f(the) i(database)e(has)i(to)f(be)h(created.)39 b(It)208 1539 y(def)o(aults)19 b(to)i(octal)f FJ(0666)p FN(.)0 1686 y(In)g(addition)f(to)h(the)g(dictionary-lik)o(e)e(methods,)h FJ(gdbm)h FN(objects)g(ha)n(v)o(e)g(the)g(follo)n(wing)e(methods:)0 1833 y FD(firstkey)p FJ(\(\))208 1932 y FN(It')-5 b(s)33 b(possible)f(to)g(loop)g(o)o(v)o(er)f(e)n(v)o(ery)g(k)o(e)o(y)g(in)i (the)f(database)g(using)g(this)h(method)e(and)g(the)i FJ(nextkey\(\))e FN(method.)60 b(The)208 2032 y(tra)n(v)o(ersal)19 b(is)i(ordered)d(by)h FJ(gdbm)p FN(')-5 b(s)20 b(internal)f(hash)h(v)n (alues,)f(and)h(w)o(on')o(t)f(be)g(sorted)h(by)f(the)h(k)o(e)o(y)f(v)n (alues.)25 b(This)20 b(method)e(returns)208 2132 y(the)i(starting)g(k)o (e)o(y)-5 b(.)0 2279 y FD(nextkey)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 2378 y FN(Returns)17 b(the)g(k)o(e)o(y)f(that)i(follo)n(ws)f FK(k)o(e)n(y)g FN(in)g(the)g(tra)n(v)o(ersal.)24 b(The)17 b(follo)n(wing)e(code)i(prints)g(e)n(v)o(ery)f(k)o(e)o(y)g(in)i(the)f (database)g FJ(db)p FN(,)g(without)208 2478 y(ha)n(ving)i(to)h(create)g (a)h(list)g(in)f(memory)f(that)h(contains)f(them)h(all:)444 2611 y FA(k)44 b(=)h(db.firstkey\(\))444 2702 y(while)f(k)g(!=)h(None:) 623 2793 y(print)f(k)623 2885 y(k)h(=)f(db.nextkey\(k\))0 3086 y FD(reorganize)p FJ(\(\))208 3186 y FN(If)15 b(you)g(ha)n(v)o(e)g (carried)f(out)i(a)g(lot)g(of)f(deletions)g(and)g(w)o(ould)g(lik)o(e)h (to)g(shrink)e(the)i(space)g(used)f(by)g(the)h FJ(gdbm)f FN(\002le,)i(this)f(routine)f(will)208 3285 y(reor)o(ganize)h(the)k (database.)k FJ(gdbm)c FN(will)g(not)g(shorten)f(the)g(length)g(of)h(a) g(database)f(\002le)i(e)o(xcept)d(by)i(using)f(this)h(reor)o (ganization;)208 3385 y(otherwise,)f(deleted)g(\002le)i(space)f(will)h (be)f(k)o(ept)g(and)g(reused)f(as)i(ne)n(w)f(\(k)o(e)o(y)-5 b(,)19 b(v)n(alue\))g(pairs)h(are)g(added.)0 3532 y FD(sync)p FJ(\(\))208 3632 y FN(When)26 b(the)h(database)f(has)h(been)f(opened)f (in)i(f)o(ast)g(mode,)g(this)g(method)f(forces)g(an)o(y)g(unwritten)f (data)i(to)g(be)f(written)h(to)g(the)208 3731 y(disk.)0 3878 y FL(See)21 b(Also:)0 4025 y FN(Module)e FJ(anydbm)h FN(\(section)f(13.6\):)208 4125 y(Generic)g(interf)o(ace)g(to)i FJ(dbm)p FN(-style)e(databases.)0 4271 y(Module)g FJ(whichdb)g FN(\(section)h(13.7\):)208 4371 y(Utility)g(module)f(used)h(to)g (determine)f(the)h(type)g(of)g(an)g(e)o(xisting)f(database.)0 4699 y FE(13.10)122 b Fx(dbhash)31 b FE(\227)i(DBM-style)g(interf)l (ace)i(to)f(the)g(BSD)f(database)j(libr)o(ar)t(y)0 4931 y FN(The)30 b FJ(dbhash)h FN(module)e(pro)o(vides)g(a)i(function)e(to)i (open)f(databases)g(using)h(the)f(BSD)i FJ(db)f FN(library)-5 b(.)55 b(This)31 b(module)f(mirrors)g(the)0 5031 y(interf)o(ace)24 b(of)g(the)h(other)f(Python)f(database)h(modules)g(that)h(pro)o(vide)e (access)i(to)g(DBM-style)f(databases.)39 b(The)24 b FJ(bsddb)g FN(module)g(is)0 5131 y(required)18 b(to)j(use)f FJ(dbhash)p FN(.)0 5277 y(This)g(module)f(pro)o(vides)g(an)h(e)o(xception)e(and)i (a)g(function:)p 0 5549 3901 4 v 0 5649 a FI(378)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 379 391 TeXDict begin 379 390 bop 0 83 a FL(exception)19 b FD(error)208 183 y FN(Exception)f(raised)i(on)g(database)f(errors)h(other)f(than)h FJ(KeyError)p FN(.)k(It)c(is)h(a)g(synon)o(ym)d(for)i FJ(bsddb.error)p FN(.)0 330 y FD(open)p FJ(\()p FK(path)p FC([)p FK(,)e(\003a)o(g)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 429 y FN(Open)19 b(a)i FJ(db)f FN(database)g(and)f(return)g (the)i(database)e(object.)25 b(The)19 b FK(path)h FN(ar)o(gument)e(is)j (the)f(name)g(of)f(the)i(database)e(\002le.)208 556 y(The)j FK(\003a)o(g)g FN(ar)o(gument)f(can)h(be)h FJ('r')g FN(\(the)g(def)o (ault\),)f FJ('w')p FN(,)h FJ('c')g FN(\(which)f(creates)h(the)g (database)f(if)h(it)h(doesn')o(t)d(e)o(xist\),)i(or)g FJ('n')208 656 y FN(\(which)c(al)o(w)o(ays)h(creates)g(a)h(ne)n(w)f (empty)f(database\).)24 b(F)o(or)c(platforms)e(on)i(which)g(the)g(BSD)h FJ(db)f FN(library)f(supports)g(locking,)g(an)208 756 y(`)p FJ(l)p FN(')g(can)h(be)h(appended)c(to)k(indicate)e(that)i (locking)d(should)i(be)g(used.)208 883 y(The)i(optional)f FK(mode)h FN(parameter)f(is)i(used)f(to)h(indicate)f(the)i(U)t FH(N)t(I)t(X)i FN(permission)21 b(bits)i(that)g(should)e(be)i(set)g(if) g(a)g(ne)n(w)f(database)208 982 y(must)e(be)g(created;)f(this)i(will)g (be)f(mask)o(ed)g(by)g(the)g(current)f(umask)g(v)n(alue)h(for)f(the)h (process.)0 1129 y FL(See)h(Also:)0 1276 y FN(Module)e FJ(anydbm)h FN(\(section)f(13.6\):)208 1376 y(Generic)g(interf)o(ace)g (to)i FJ(dbm)p FN(-style)e(databases.)0 1523 y(Module)g FJ(bsddb)h FN(\(section)f(13.11\):)208 1622 y(Lo)n(wer)n(-le)n(v)o(el)f (interf)o(ace)h(to)i(the)f(BSD)h FJ(db)f FN(library)-5 b(.)0 1769 y(Module)19 b FJ(whichdb)g FN(\(section)h(13.7\):)208 1869 y(Utility)g(module)f(used)h(to)g(determine)f(the)h(type)g(of)g(an) g(e)o(xisting)f(database.)0 2148 y Fv(13.10.1)101 b(Database)29 b(Objects)0 2351 y FN(The)19 b(database)f(objects)h(returned)e(by)i FJ(open\(\))g FN(pro)o(vide)e(the)i(methods)f(common)f(to)i(all)h(the)f (DBM-style)g(databases)g(and)f(mapping)0 2451 y(objects.)25 b(The)20 b(follo)n(wing)e(methods)h(are)h(a)n(v)n(ailable)g(in)g (addition)f(to)i(the)f(standard)f(methods.)0 2598 y FD(first)p FJ(\(\))208 2697 y FN(It')-5 b(s)22 b(possible)f(to)h(loop)f(o)o(v)o (er)f(e)n(v)o(ery)h(k)o(e)o(y/v)n(alue)e(pair)j(in)g(the)f(database)g (using)g(this)i(method)d(and)h(the)h FJ(next\(\))f FN(method.)28 b(The)208 2797 y(tra)n(v)o(ersal)22 b(is)i(ordered)e(by)g(the)i (databases)e(internal)h(hash)g(v)n(alues,)g(and)g(w)o(on')o(t)f(be)h (sorted)g(by)f(the)i(k)o(e)o(y)e(v)n(alues.)34 b(This)23 b(method)208 2897 y(returns)c(the)h(starting)g(k)o(e)o(y)-5 b(.)0 3044 y FD(last)p FJ(\(\))208 3143 y FN(Return)23 b(the)h(last)h(k)o(e)o(y/v)n(alue)d(pair)h(in)h(a)h(database)e(tra)n(v) o(ersal.)35 b(This)24 b(may)g(be)f(used)h(to)g(be)o(gin)f(a)h(re)n(v)o (erse-order)d(tra)n(v)o(ersal;)k(see)208 3243 y FJ(previous\(\))p FN(.)0 3390 y FD(next)p FJ(\(\))208 3489 y FN(Returns)20 b(the)h(k)o(e)o(y)f(ne)o(xt)g(k)o(e)o(y/v)n(alue)f(pair)h(in)h(a)g (database)f(tra)n(v)o(ersal.)26 b(The)20 b(follo)n(wing)f(code)h (prints)g(e)n(v)o(ery)g(k)o(e)o(y)g(in)g(the)h(database)208 3589 y FJ(db)p FN(,)f(without)f(ha)n(ving)g(to)i(create)f(a)g(list)h (in)g(memory)d(that)j(contains)e(them)h(all:)444 3716 y FA(print)44 b(db.first\(\))444 3807 y(for)g(i)h(in)f(xrange\(1,)g (len\(db\)\):)623 3899 y(print)g(db.next\(\))0 4100 y FD(previous)p FJ(\(\))208 4200 y FN(Returns)25 b(the)g(pre)n(vious)e(k) o(e)o(y/v)n(alue)h(pair)g(in)i(a)f(forw)o(ard-tra)n(v)o(ersal)d(of)j (the)g(database.)40 b(In)24 b(conjunction)f(with)i FJ(last\(\))p FN(,)h(this)208 4300 y(may)19 b(be)h(used)g(to)h(implement)e(a)h(re)n (v)o(erse-order)d(tra)n(v)o(ersal.)0 4446 y FD(sync)p FJ(\(\))208 4546 y FN(This)j(method)f(forces)g(an)o(y)h(unwritten)f (data)h(to)g(be)g(written)g(to)h(the)f(disk.)0 4868 y FE(13.11)122 b Fx(bsddb)32 b FE(\227)g(Interf)l(ace)k(to)e(Ber)r(k)n (ele)n(y)e(DB)i(libr)o(ar)t(y)0 5101 y FN(The)25 b FJ(bsddb)h FN(module)e(pro)o(vides)h(an)g(interf)o(ace)g(to)h(the)g(Berk)o(ele)o (y)f(DB)i(library)-5 b(.)40 b(Users)27 b(can)e(create)h(hash,)h(btree)e (or)h(record)e(based)0 5201 y(library)e(\002les)i(using)f(the)g (appropriate)d(open)i(call.)34 b(Bsddb)23 b(objects)g(beha)n(v)o(e)f (generally)g(lik)o(e)h(dictionaries.)32 b(K)n(e)o(ys)23 b(and)g(v)n(alues)g(must)0 5300 y(be)28 b(strings,)j(ho)n(we)n(v)o(er)m (,)d(so)g(to)h(use)g(other)e(objects)i(as)g(k)o(e)o(ys)f(or)g(to)h (store)f(other)g(kinds)g(of)g(objects)g(the)g(user)h(must)f(serialize)h (them)0 5400 y(someho)n(w)-5 b(,)18 b(typically)i(using)f FJ(marshal.dumps\(\))f FN(or)i FJ(pickle.dumps\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(13.11.)52 b FJ(bsddb)23 b FI(\227)g(Interf)n(ace)f(to)i(Ber)q(k)n(ele)n(y)g(DB)f(libr)o(ar)r(y) 1956 b(379)p eop end %%Page: 380 392 TeXDict begin 380 391 bop 0 83 a FN(The)20 b FJ(bsddb)g FN(module)e(requires)i(a)g(Berk)o(ele)o(y)g(DB)h(library)e(v)o(ersion)g (from)g(3.3)g(thru)h(4.5.)0 230 y FL(See)h(Also:)0 377 y FO(http://p)n(ybsddb)m(.sourcef)n(orge)n(.n)o(et/)208 476 y FN(The)29 b(website)h(with)h(documentation)c(for)i(the)h FJ(bsddb.db)f FN(Python)g(Berk)o(ele)o(y)g(DB)i(interf)o(ace)f(that)g (closely)g(mirrors)f(the)208 576 y(object)19 b(oriented)g(interf)o(ace) g(pro)o(vided)f(in)i(Berk)o(ele)o(y)g(DB)h(3)f(and)g(4.)0 723 y FO(http://www)l(.or)o(acle)o(.com/datab)o(ase/b)o(erk)o(ele)n (y-d)o(b/)208 823 y FN(The)f(Berk)o(ele)o(y)h(DB)h(library)-5 b(.)0 969 y(A)24 b(more)f(modern)e(DB,)k(DBEn)m(v)d(and)h(DBSequence)g (object)g(interf)o(ace)f(is)j(a)n(v)n(ailable)e(in)h(the)f FJ(bsddb.db)g FN(module)f(which)h(closely)0 1069 y(matches)j(the)g (Berk)o(ele)o(y)g(DB)h(C)g(API)g(documented)d(at)i(the)h(abo)o(v)o(e)d (URLs.)45 b(Additional)25 b(features)g(pro)o(vided)f(by)i(the)g FJ(bsddb.db)0 1169 y FN(API)21 b(include)e(\002ne)h(tuning,)f (transactions,)g(logging,)f(and)i(multiprocess)f(concurrent)e(database) j(access.)0 1316 y(The)c(follo)n(wing)f(is)i(a)g(description)d(of)i (the)h(le)o(gac)o(y)d FJ(bsddb)i FN(interf)o(ace)g(compatible)e(with)j (the)f(old)g(Python)f(bsddb)g(module.)23 b(Starting)15 b(in)0 1415 y(Python)k(2.5)g(this)h(interf)o(ace)f(should)f(be)i(safe)g (for)f(multithreaded)f(access.)25 b(The)19 b FJ(bsddb.db)g FN(API)h(is)h(recommended)16 b(for)j(threading)0 1515 y(users)h(as)h(it)g(pro)o(vides)e(better)g(control.)0 1662 y(The)26 b FJ(bsddb)f FN(module)f(de\002nes)i(the)g(follo)n(wing)e (functions)h(that)g(create)h(objects)g(that)g(access)g(the)g (appropriate)d(type)j(of)f(Berk)o(ele)o(y)0 1761 y(DB)f(\002le.)36 b(The)23 b(\002rst)h(tw)o(o)g(ar)o(guments)e(of)h(each)g(function)f (are)h(the)h(same.)35 b(F)o(or)23 b(ease)h(of)f(portability)-5 b(,)22 b(only)h(the)h(\002rst)g(tw)o(o)g(ar)o(guments)0 1861 y(should)19 b(be)h(used)g(in)h(most)f(instances.)0 2008 y FD(hashopen)p FJ(\()p FK(\002lename)p FC([)p FK(,)d(\003a)o(g)p FC([)p FK(,)i(mode)p FC([)p FK(,)g(pgsize)p FC([)p FK(,)h(f)o(factor)r FC([)p FK(,)f(nelem)p FC([)p FK(,)h(cac)o(hesize)p FC([)p FK(,)f(lor)m(der)r FC([)p FK(,)h(h\003a)o(gs)12 b FC(])g(])g(])g(])g(]) g(])g(])g(])p FJ(\))208 2107 y FN(Open)28 b(the)g(hash)h(format)f (\002le)h(named)f FK(\002lename)p FN(.)49 b(Files)30 b(ne)n(v)o(er)d(intended)h(to)g(be)h(preserv)o(ed)e(on)h(disk)h(may)f (be)h(created)f(by)208 2207 y(passing)23 b FJ(None)g FN(as)h(the)f FK(\002lename)p FN(.)34 b(The)23 b(optional)f FK(\003a)o(g)h FN(identi\002es)g(the)g(mode)g(used)g(to)g(open)g(the)g (\002le.)35 b(It)24 b(may)f(be)g(`)p FJ(r)p FN(')g(\(read)208 2307 y(only\),)i(`)p FJ(w)p FN(')g(\(read-write\))e(,)28 b(`)p FJ(c)p FN(')d(\(read-write)e(-)j(create)f(if)h(necessary;)h(the)f (def)o(ault\))e(or)i(`)p FJ(n)p FN(')f(\(read-write)e(-)j(truncate)f (to)g(zero)208 2406 y(length\).)g(The)c(other)e(ar)o(guments)g(are)i (rarely)f(used)g(and)h(are)f(just)i(passed)e(to)h(the)g(lo)n(w-le)n(v)o (el)f FJ(dbopen\(\))g FN(function.)25 b(Consult)208 2506 y(the)20 b(Berk)o(ele)o(y)f(DB)i(documentation)c(for)j(their)g(use)g (and)g(interpretation.)0 2653 y FD(btopen)p FJ(\()p FK(\002lename)p FC([)p FK(,)d(\003a)o(g)p FC([)p FK(,)i(mode)p FC([)p FK(,)g(bt\003a)o(gs)p FC([)p FK(,)g(cac)o(hesize)p FC([)p FK(,)h(maxk)o(e)n(ypa)o(g)o(e)p FC([)p FK(,)d(mink)o(e)n(ypa)o(g)o(e)p FC([)p FK(,)h(pgsize)p FC([)p FK(,)i(lor)m(der)14 b FC(])e(])g(])g(])g (])g(])g(])g(])p FJ(\))208 2752 y FN(Open)27 b(the)h(btree)g(format)f (\002le)h(named)f FK(\002lename)p FN(.)48 b(Files)29 b(ne)n(v)o(er)e(intended)f(to)i(be)g(preserv)o(ed)e(on)i(disk)g(may)g (be)g(created)f(by)208 2852 y(passing)c FJ(None)g FN(as)h(the)f FK(\002lename)p FN(.)34 b(The)23 b(optional)f FK(\003a)o(g)h FN(identi\002es)g(the)g(mode)g(used)g(to)g(open)g(the)g(\002le.)35 b(It)24 b(may)f(be)g(`)p FJ(r)p FN(')g(\(read)208 2952 y(only\),)k(`)p FJ(w)p FN(')f(\(read-write\),)h(`)p FJ(c)p FN(')f(\(read-write)f(-)j(create)e(if)h(necessary;)j(the)d(def)o (ault\))f(or)g(`)p FJ(n)p FN(')h(\(read-write)e(-)i(truncate)f(to)h (zero)208 3051 y(length\).)j(The)21 b(other)h(ar)o(guments)e(are)i (rarely)g(used)g(and)g(are)g(just)h(passed)f(to)g(the)h(lo)n(w-le)n(v)o (el)e(dbopen)f(function.)29 b(Consult)23 b(the)208 3151 y(Berk)o(ele)o(y)c(DB)i(documentation)c(for)j(their)g(use)g(and)g (interpretation.)0 3298 y FD(rnopen)p FJ(\()p FK(\002lename)p FC([)p FK(,)k(\003a)o(g)p FC([)p FK(,)h(mode)p FC([)p FK(,)h(rn\003a)o(gs)p FC([)p FK(,)g(cac)o(hesize)p FC([)p FK(,)f(pgsize)p FC([)p FK(,)i(lor)m(der)r FC([)p FK(,)f(rlen)p FC([)p FK(,)g(delim)p FC([)p FK(,)h(sour)m(ce)p FC([)p FK(,)f(pad)12 b FC(])g(])g(])g(])g(])g(])g(])g(])g(])350 3397 y(])p FJ(\))208 3481 y FN(Open)21 b(a)i(DB)g(record)d(format)h (\002le)i(named)e FK(\002lename)p FN(.)29 b(Files)24 b(ne)n(v)o(er)c(intended)h(to)h(be)g(preserv)o(ed)e(on)i(disk)g(may)g (be)g(created)f(by)208 3581 y(passing)i FJ(None)g FN(as)h(the)f FK(\002lename)p FN(.)34 b(The)23 b(optional)f FK(\003a)o(g)h FN(identi\002es)g(the)g(mode)g(used)g(to)g(open)g(the)g(\002le.)35 b(It)24 b(may)f(be)g(`)p FJ(r)p FN(')g(\(read)208 3680 y(only\),)k(`)p FJ(w)p FN(')f(\(read-write\),)h(`)p FJ(c)p FN(')f(\(read-write)f(-)j(create)e(if)h(necessary;)j(the)d(def)o (ault\))f(or)g(`)p FJ(n)p FN(')h(\(read-write)e(-)i(truncate)f(to)h (zero)208 3780 y(length\).)j(The)21 b(other)h(ar)o(guments)e(are)i (rarely)g(used)g(and)g(are)g(just)h(passed)f(to)g(the)h(lo)n(w-le)n(v)o (el)e(dbopen)f(function.)29 b(Consult)23 b(the)208 3880 y(Berk)o(ele)o(y)c(DB)i(documentation)c(for)j(their)g(use)g(and)g (interpretation.)0 4027 y FL(Note:)25 b FN(Be)o(ginning)18 b(in)j(2.3)f(some)i(U)t FH(N)t(I)t(X)h FN(v)o(ersions)d(of)g(Python)f (may)h(ha)n(v)o(e)g(a)h FJ(bsddb185)e FN(module.)24 b(This)d(is)g (present)f FK(only)g FN(to)h(allo)n(w)0 4126 y(backw)o(ards)i (compatibility)g(with)h(systems)h(which)f(ship)h(with)f(the)h(old)f (Berk)o(ele)o(y)f(DB)i(1.85)f(database)f(library)-5 b(.)36 b(The)24 b FJ(bsddb185)0 4226 y FN(module)19 b(should)g(ne)n(v)o(er)g (be)h(used)g(directly)f(in)i(ne)n(w)f(code.)0 4373 y FL(See)h(Also:)0 4520 y FN(Module)e FJ(dbhash)h FN(\(section)f (13.10\):)208 4619 y(DBM-style)h(interf)o(ace)f(to)i(the)f FJ(bsddb)0 4904 y Fv(13.11.1)101 b(Hash,)28 b(BT)-12 b(ree)29 b(and)g(Record)g(Objects)0 5107 y FN(Once)22 b(instantiated,)h(hash,)f(btree)h(and)f(record)f(objects)h(support)g (the)g(same)h(methods)e(as)j(dictionaries.)31 b(In)22 b(addition,)g(the)o(y)g(support)0 5207 y(the)e(methods)f(listed)i(belo) n(w)-5 b(.)50 b(Changed)19 b(in)h(v)o(ersion)f(2.3.1:)g(Added)g (dictionary)f(methods.)0 5353 y FD(close)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(380)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 381 393 TeXDict begin 381 392 bop 208 83 a FN(Close)21 b(the)g(underlying)d (\002le.)27 b(The)21 b(object)f(can)g(no)h(longer)e(be)i(accessed.)26 b(Since)21 b(there)g(is)g(no)g(open)e FJ(open)i FN(method)e(for)h (these)208 183 y(objects,)f(to)i(open)e(the)h(\002le)h(again)e(a)i(ne)n (w)f FJ(bsddb)f FN(module)g(open)g(function)g(must)h(be)g(called.)0 330 y FD(keys)p FJ(\(\))208 429 y FN(Return)g(the)h(list)i(of)e(k)o(e)o (ys)f(contained)g(in)h(the)g(DB)h(\002le.)29 b(The)21 b(order)f(of)g(the)i(list)g(is)g(unspeci\002ed)e(and)g(should)h(not)f (be)h(relied)g(on.)208 529 y(In)e(particular)m(,)g(the)h(order)f(of)h (the)g(list)h(returned)e(is)i(dif)n(ferent)d(for)i(dif)n(ferent)e (\002le)j(formats.)0 676 y FD(has_key)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 775 y FN(Return)e FJ(1)i FN(if)f(the)h(DB)g(\002le)f (contains)g(the)g(ar)o(gument)e(as)j(a)g(k)o(e)o(y)-5 b(.)0 922 y FD(set_location)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 1022 y FN(Set)24 b(the)g(cursor)g(to)g(the)g(item)g (indicated)f(by)h FK(k)o(e)n(y)g FN(and)f(return)g(a)i(tuple)f (containing)e(the)i(k)o(e)o(y)f(and)h(its)h(v)n(alue.)36 b(F)o(or)24 b(binary)f(tree)208 1121 y(databases)e(\(opened)e(using)i FJ(btopen\(\))p FN(\),)g(if)g FK(k)o(e)n(y)h FN(does)f(not)g(actually)g (e)o(xist)h(in)f(the)h(database,)f(the)g(cursor)g(will)h(point)f(to)h (the)208 1221 y(ne)o(xt)e(item)h(in)g(sorted)g(order)f(and)g(return)g (that)i(k)o(e)o(y)e(and)h(v)n(alue.)27 b(F)o(or)20 b(other)h (databases,)f FJ(KeyError)h FN(will)g(be)g(raised)g(if)h FK(k)o(e)n(y)f FN(is)208 1321 y(not)e(found)g(in)h(the)g(database.)0 1468 y FD(first)p FJ(\(\))208 1567 y FN(Set)i(the)f(cursor)f(to)i(the)f (\002rst)h(item)f(in)h(the)f(DB)h(\002le)g(and)f(return)f(it.)29 b(The)21 b(order)f(of)h(k)o(e)o(ys)g(in)h(the)f(\002le)h(is)g (unspeci\002ed,)e(e)o(xcept)g(in)208 1667 y(the)g(case)g(of)g(B-T)m (ree)g(databases.)25 b(This)20 b(method)f(raises)i FJ(bsddb.error)e FN(if)h(the)g(database)g(is)h(empty)-5 b(.)0 1814 y FD(next)p FJ(\(\))208 1913 y FN(Set)21 b(the)g(cursor)f(to)h(the)g(ne)o(xt)f (item)h(in)g(the)f(DB)i(\002le)g(and)e(return)g(it.)27 b(The)21 b(order)e(of)i(k)o(e)o(ys)f(in)h(the)g(\002le)g(is)h (unspeci\002ed,)e(e)o(xcept)f(in)208 2013 y(the)h(case)g(of)g(B-T)m (ree)g(databases.)0 2160 y FD(previous)p FJ(\(\))208 2259 y FN(Set)29 b(the)f(cursor)f(to)i(the)f(pre)n(vious)f(item)h(in)h (the)f(DB)i(\002le)f(and)e(return)h(it.)50 b(The)28 b(order)f(of)h(k)o (e)o(ys)g(in)g(the)h(\002le)g(is)g(unspeci\002ed,)208 2359 y(e)o(xcept)k(in)h(the)g(case)g(of)g(B-T)m(ree)g(databases.)66 b(This)34 b(is)h(not)f(supported)e(on)i(hashtable)f(databases)h (\(those)f(opened)f(with)208 2459 y FJ(hashopen\(\))p FN(\).)0 2606 y FD(last)p FJ(\(\))208 2705 y FN(Set)25 b(the)f(cursor)f(to)i(the)f(last)h(item)g(in)f(the)g(DB)h(\002le)g(and) f(return)f(it.)38 b(The)24 b(order)f(of)h(k)o(e)o(ys)g(in)h(the)f (\002le)h(is)g(unspeci\002ed.)36 b(This)25 b(is)208 2805 y(not)c(supported)e(on)j(hashtable)e(databases)i(\(those)f(opened)f (with)h FJ(hashopen\(\))p FN(\).)28 b(This)22 b(method)e(raises)i FJ(bsddb.error)208 2904 y FN(if)e(the)g(database)g(is)h(empty)-5 b(.)0 3051 y FD(sync)p FJ(\(\))208 3151 y FN(Synchronize)17 b(the)k(database)e(on)h(disk.)0 3298 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(13.11.)52 b FJ(bsddb)23 b FI(\227)g(Interf)n(ace)f (to)i(Ber)q(k)n(ele)n(y)g(DB)f(libr)o(ar)r(y)1956 b(381)p eop end %%Page: 382 394 TeXDict begin 382 393 bop 236 174 a FA(>>>)45 b(import)e(bsddb)236 266 y(>>>)i(db)f(=)h(bsddb.btopen\('/tmp/spam.db',)40 b('c'\))236 357 y(>>>)45 b(for)f(i)h(in)f(range\(10\):)f (db['\045d'\045i])g(=)i('\045d'\045)f(\(i)2254 370 y(*)2299 357 y(i\))236 448 y(...)236 540 y(>>>)h(db['3'])236 631 y('9')236 722 y(>>>)g(db.keys\(\))236 814 y(['0',)f('1',)g('2',)h('3',) f('4',)g('5',)g('6',)g('7',)g('8',)g('9'])236 905 y(>>>)h(db.first\(\)) 236 996 y(\('0',)f('0'\))236 1088 y(>>>)h(db.next\(\))236 1179 y(\('1',)f('1'\))236 1270 y(>>>)h(db.last\(\))236 1362 y(\('9',)f('81'\))236 1453 y(>>>)h(db.set_location\('2'\))236 1544 y(\('2',)f('4'\))236 1636 y(>>>)h(db.previous\(\))236 1727 y(\('1',)f('1'\))236 1818 y(>>>)h(for)f(k,)g(v)h(in)g (db.iteritems\(\):)236 1910 y(...)224 b(print)44 b(k,)g(v)236 2001 y(0)h(0)236 2092 y(1)g(1)236 2183 y(2)g(4)236 2275 y(3)g(9)236 2366 y(4)g(16)236 2457 y(5)g(25)236 2549 y(6)g(36)236 2640 y(7)g(49)236 2731 y(8)g(64)236 2823 y(9)g(81)236 2914 y(>>>)g('8')f(in)g(db)236 3005 y(True)236 3097 y(>>>)h(db.sync\(\))236 3188 y(0)0 3698 y FE(13.12)122 b Fx(dumbdbm)31 b FE(\227)i(P)-6 b(or)5 b(tab)n(le)34 b(DBM)f(implementation)0 3931 y FL(Note:)22 b FN(The)16 b FJ(dumbdbm)g FN(module)f(is)i(intended)e(as)i(a)f(last)h(resort)f(f)o (allback)g(for)f(the)i FJ(anydbm)e FN(module)g(when)h(no)g(more)f(rob)n (ust)h(module)0 4031 y(is)27 b(a)n(v)n(ailable.)40 b(The)25 b FJ(dumbdbm)g FN(module)f(is)j(not)e(written)h(for)e(speed)i(and)f(is) h(not)f(nearly)g(as)h(hea)n(vily)f(used)h(as)g(the)f(other)g(database)0 4130 y(modules.)0 4277 y(The)18 b FJ(dumbdbm)g FN(module)f(pro)o(vides) g(a)i(persistent)f(dictionary-lik)o(e)e(interf)o(ace)i(which)g(is)h (written)g(entirely)e(in)i(Python.)k(Unlik)o(e)18 b(other)0 4377 y(modules)k(such)h(as)h FJ(gdbm)f FN(and)g FJ(bsddb)p FN(,)g(no)g(e)o(xternal)f(library)g(is)i(required.)33 b(As)24 b(with)f(other)g(persistent)g(mappings,)f(the)h(k)o(e)o(ys)g (and)0 4476 y(v)n(alues)d(must)g(al)o(w)o(ays)h(be)f(strings.)0 4623 y(The)g(module)f(de\002nes)h(the)g(follo)n(wing:)0 4770 y FL(exception)f FD(error)208 4870 y FN(Raised)25 b(on)g(dumbdbm-speci\002c)d(errors,)j(such)g(as)h(I/O)g(errors.)39 b FJ(KeyError)24 b FN(is)j(raised)e(for)f(general)g(mapping)g(errors)g (lik)o(e)208 4969 y(specifying)18 b(an)i(incorrect)f(k)o(e)o(y)-5 b(.)0 5116 y FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)18 b(\003a)o(g)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 5216 y FN(Open)32 b(a)h(dumbdbm)c(database)k(and)f(return)f (a)i(dumbdbm)d(object.)62 b(The)32 b FK(\002lename)f FN(ar)o(gument)g(is)i(the)g(basename)e(of)i(the)208 5315 y(database)19 b(\002le)h(\(without)f(an)o(y)g(speci\002c)h(e)o (xtensions\).)j(When)d(a)g(dumbdbm)d(database)i(is)i(created,)e (\002les)h(with)g(`)p FO(.dat)p FN(')f(and)g(`)p FO(.dir)p FN(')p 0 5549 3901 4 v 0 5649 a FI(382)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 383 395 TeXDict begin 383 394 bop 208 83 a FN(e)o(xtensions)19 b(are)h(created.)208 216 y(The)e(optional)g FK(\003a)o(g)h FN(ar)o(gument)d(is)21 b(currently)c(ignored;)h(the)h(database)g(is)h (al)o(w)o(ays)f(opened)f(for)g(update,)g(and)h(will)h(be)f(created)f (if)208 315 y(it)i(does)g(not)g(e)o(xist.)208 448 y(The)25 b(optional)f FK(mode)g FN(ar)o(gument)f(is)k(the)g(U)t FH(N)t(I)t(X)h FN(mode)d(of)g(the)g(\002le,)i(used)e(only)g(when)f(the) i(database)e(has)i(to)f(be)h(created.)39 b(It)208 548 y(def)o(aults)26 b(to)h(octal)g FJ(0666)g FN(\(and)f(will)i(be)f (modi\002ed)f(by)h(the)g(pre)n(v)n(ailing)e(umask\).)90 b(Changed)26 b(in)h(v)o(ersion)f(2.2:)g(The)h FK(mode)208 648 y FN(ar)o(gument)17 b(w)o(as)k(ignored)e(in)h(earlier)g(v)o (ersions.)0 794 y FL(See)h(Also:)0 941 y FN(Module)e FJ(anydbm)h FN(\(section)f(13.6\):)208 1041 y(Generic)g(interf)o(ace)g (to)i FJ(dbm)p FN(-style)e(databases.)0 1188 y(Module)g FJ(dbm)h FN(\(section)g(13.8\):)208 1287 y(Similar)g(interf)o(ace)f(to) h(the)h(DBM/NDBM)g(library)-5 b(.)0 1434 y(Module)19 b FJ(gdbm)h FN(\(section)g(13.9\):)208 1534 y(Similar)g(interf)o(ace)f (to)h(the)h(GNU)f(GDBM)h(library)-5 b(.)0 1681 y(Module)19 b FJ(shelve)h FN(\(section)f(13.4\):)208 1780 y(Persistence)h(module)f (which)g(stores)i(non-string)d(data.)0 1927 y(Module)h FJ(whichdb)g FN(\(section)h(13.7\):)208 2027 y(Utility)g(module)f(used) h(to)g(determine)f(the)h(type)g(of)g(an)g(e)o(xisting)f(database.)0 2312 y Fv(13.12.1)101 b(Dumbdbm)29 b(Objects)0 2515 y FN(In)20 b(addition)g(to)g(the)h(methods)e(pro)o(vided)f(by)i(the)h FJ(UserDict.DictMixin)d FN(class,)j FJ(dumbdbm)f FN(objects)g(pro)o (vide)f(the)h(follo)n(wing)0 2614 y(methods.)0 2761 y FD(sync)p FJ(\(\))208 2861 y FN(Synchronize)14 b(the)j(on-disk)e (directory)g(and)i(data)f(\002les.)25 b(This)17 b(method)f(is)h(called) g(by)f(the)h FJ(sync)g FN(method)e(of)i FJ(Shelve)f FN(objects.)0 3188 y FE(13.13)122 b Fx(sqlite3)31 b FE(\227)i(DB-API)g(2.0)h(interf)l (ace)h(f)l(or)f(SQLite)g(databases)0 3421 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3568 y(SQLite)27 b(is)h(a)f(C)h(library)d (that)i(pro)o(vides)e(a)i(lightweight)f(disk-based)f(database)h(that)h (doesn')o(t)e(require)h(a)h(separate)f(serv)o(er)g(process)0 3668 y(and)20 b(allo)n(ws)g(accessing)g(the)g(database)f(using)h(a)g (nonstandard)e(v)n(ariant)h(of)g(the)i(SQL)f(query)f(language.)k(Some)d (applications)e(can)i(use)0 3767 y(SQLite)i(for)f(internal)g(data)g (storage.)29 b(It')-5 b(s)22 b(also)g(possible)g(to)f(prototype)f(an)h (application)f(using)i(SQLite)g(and)f(then)g(port)g(the)g(code)g(to)0 3867 y(a)g(lar)o(ger)d(database)i(such)g(as)h(PostgreSQL)f(or)f (Oracle.)0 4014 y(p)o(ysqlite)25 b(w)o(as)i(written)e(by)h(Gerhard)e(H) 5 b(\250)-33 b(aring)25 b(and)g(pro)o(vides)f(a)i(SQL)g(interf)o(ace)f (compliant)f(with)i(the)f(DB-API)h(2.0)f(speci\002cation)0 4113 y(described)19 b(by)h(PEP)g(249.)0 4260 y(T)-7 b(o)25 b(use)h(the)f(module,)f(you)h(must)g(\002rst)h(create)e(a)i FJ(Connection)e FN(object)g(that)h(represents)g(the)g(database.)39 b(Here)25 b(the)g(data)g(will)h(be)0 4360 y(stored)20 b(in)g(the)g(`)p FO(/tmp/e)n(xample)p FN(')d(\002le:)236 4598 y FA(conn)44 b(=)h(sqlite3.connect\('/tmp/example'\))0 4885 y FN(Y)-9 b(ou)20 b(can)g(also)g(supply)f(the)h(special)h(name)e (`)p FJ(:memory:)p FN(')24 b(to)c(create)g(a)h(database)e(in)i(RAM.)0 5031 y(Once)h(you)f(ha)n(v)o(e)h(a)g FJ(Connection)p FN(,)f(you)h(can)g(create)g(a)g FJ(Cursor)g FN(object)f(and)h(call)h (its)g FJ(execute\(\))e FN(method)g(to)h(perform)e(SQL)0 5131 y(commands:)p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g(interf)n(ace)f(f)n(or)f (SQLite)i(databases)1447 b(383)p eop end %%Page: 384 396 TeXDict begin 384 395 bop 236 174 a FA(c)45 b(=)g(conn.cursor\(\))236 357 y(#)g(Create)f(table)236 448 y(c.execute\('''create)e(table)i (stocks)236 540 y(\(date)g(text,)g(trans)g(text,)g(symbol)g(text,)281 631 y(qty)g(real,)g(price)g(real\)'''\))236 814 y(#)h(Insert)f(a)g(row) h(of)f(data)236 905 y(c.execute\("""insert)e(into)i(stocks)685 996 y(values)f(\('2006-01-05','BUY','RHAT',100,35.14\)"""\))236 1179 y(#)i(Save)f(\(commit\))g(the)g(changes)236 1270 y(conn.commit\(\))236 1453 y(#)h(We)f(can)h(also)f(close)g(the)g (cursor)g(if)h(we)f(are)g(done)g(with)h(it)236 1544 y(c.close\(\))0 1831 y FN(Usually)18 b(your)f(SQL)i(operations)e(will)i(need)f(to)h (use)f(v)n(alues)g(from)g(Python)f(v)n(ariables.)24 b(Y)-9 b(ou)17 b(shouldn')o(t)g(assemble)h(your)f(query)g(using)0 1930 y(Python')-5 b(s)19 b(string)g(operations)f(because)h(doing)f(so)i (is)h(insecure;)e(it)h(mak)o(es)g(your)e(program)f(vulnerable)h(to)i (an)f(SQL)h(injection)f(attack.)0 2077 y(Instead,)f(use)h(the)g (DB-API')-5 b(s)20 b(parameter)d(substitution.)24 b(Put)19 b(`)p FJ(?)p FN(')24 b(as)c(a)f(placeholder)e(where)n(v)o(er)g(you)h(w) o(ant)h(to)g(use)g(a)g(v)n(alue,)g(and)f(then)0 2177 y(pro)o(vide)h(a)j(tuple)f(of)g(v)n(alues)g(as)h(the)f(second)f(ar)o (gument)f(to)j(the)f(cursor')-5 b(s)21 b FJ(execute\(\))f FN(method.)27 b(\(Other)20 b(database)h(modules)f(may)0 2276 y(use)g(a)h(dif)n(ferent)e(placeholder)m(,)e(such)j(as)h(`)p FJ(\045s)p FN(')f(or)f(`)p FJ(:1)p FN('.\))25 b(F)o(or)19 b(e)o(xample:)236 2515 y FA(#)45 b(Never)f(do)g(this)h(--)f(insecure!) 236 2606 y(symbol)g(=)h('IBM')236 2697 y(c.execute\("...)e(where)h (symbol)g(=)g('\045s'")g(\045)h(symbol\))236 2880 y(#)g(Do)f(this)h (instead)236 2971 y(t)g(=)g(\(symbol,\))236 3063 y(c.execute\('select) 1043 3076 y(*)1133 3063 y(from)f(stocks)g(where)g(symbol=?',)f(t\))236 3245 y(#)i(Larger)f(example)236 3337 y(for)h(t)f(in)h (\(\('2006-03-28',)d('BUY',)i('IBM',)g(1000,)g(45.00\),)685 3428 y(\('2006-04-05',)e('BUY',)i('MSOFT',)f(1000,)h(72.00\),)685 3519 y(\('2006-04-06',)e('SELL',)i('IBM',)f(500,)i(53.00\),)640 3611 y(\):)416 3702 y(c.execute\('insert)d(into)i(stocks)g(values)f (\(?,?,?,?,?\)',)g(t\))0 3988 y FN(T)-7 b(o)26 b(retrie)n(v)o(e)e(data) i(after)f(e)o(x)o(ecuting)e(a)j(SELECT)g(statement,)g(you)f(can)g (either)g(treat)h(the)g(cursor)e(as)i(an)g(iterator)m(,)g(call)g(the)f (cursor')-5 b(s)0 4088 y FJ(fetchone\(\))19 b FN(method)g(to)h(retrie)n (v)o(e)f(a)i(single)f(matching)f(ro)n(w)-5 b(,)19 b(or)h(call)g FJ(fetchall\(\))f FN(to)h(get)h(a)f(list)i(of)d(the)i(matching)d(ro)n (ws.)0 4235 y(This)i(e)o(xample)f(uses)i(the)f(iterator)g(form:)p 0 5549 3901 4 v 0 5649 a FI(384)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 385 397 TeXDict begin 385 396 bop 236 174 a FA(>>>)45 b(c)f(=)h (conn.cursor\(\))236 266 y(>>>)g(c.execute\('select)1223 279 y(*)1312 266 y(from)f(stocks)g(order)g(by)h(price'\))236 357 y(>>>)g(for)f(row)g(in)h(c:)236 448 y(...)179 b(print)44 b(row)236 540 y(...)236 631 y(\(u'2006-01-05',)f(u'BUY',)g(u'RHAT',)h (100,)g(35.140000000000001\))236 722 y(\(u'2006-03-28',)f(u'BUY',)g (u'IBM',)h(1000,)g(45.0\))236 814 y(\(u'2006-04-06',)f(u'SELL',)g (u'IBM',)h(500,)g(53.0\))236 905 y(\(u'2006-04-05',)f(u'BUY',)g (u'MSOFT',)h(1000,)f(72.0\))236 996 y(>>>)0 1283 y FL(See)21 b(Also:)0 1430 y FO(http://www)l(.p)n(ysqlite)o(.org)208 1530 y FN(The)e(p)o(ysqlite)h(web)g(page.)0 1677 y FO(http://www)l (.sqlite)o(.org)208 1776 y FN(The)25 b(SQLite)h(web)g(page;)i(the)e (documentation)d(describes)j(the)g(syntax)f(and)g(the)h(a)n(v)n (ailable)g(data)g(types)f(for)h(the)g(supported)208 1876 y(SQL)20 b(dialect.)0 2023 y(PEP)h(249,)e(\223)p FK(Database)g(API)h (Speci\002cation)d(2.0)p FN(\224)208 2122 y(PEP)j(written)g(by)g (Marc-Andr)5 b(\264)-33 b(e)18 b(Lemb)n(ur)o(g.)0 2407 y Fv(13.13.1)101 b(Module)29 b(functions)g(and)g(constants)0 2596 y FD(PARSE_DECLTYPES)208 2696 y FN(This)20 b(constant)f(is)j (meant)d(to)i(be)f(used)g(with)g(the)g FK(detect)p 1825 2696 25 4 v 29 w(types)h FN(parameter)d(of)i(the)g FJ(connect)g FN(function.)208 2829 y(Setting)i(it)h(mak)o(es)f(the)g FJ(sqlite3)f FN(module)g(parse)h(the)g(declared)f(type)h(for)g(each)f (column)g(it)i(returns.)30 b(It)23 b(will)g(parse)f(out)g(the)208 2928 y(\002rst)f(w)o(ord)e(of)h(the)h(declared)e(type,)g(i.)26 b(e.)g(for)20 b(\224inte)o(ger)f(primary)f(k)o(e)o(y\224,)i(it)h(will)g (parse)f(out)g(\224inte)o(ger\224.)k(Then)19 b(for)h(that)g(column,)208 3028 y(it)f(will)h(look)e(into)h(the)g(con)m(v)o(erters)e(dictionary)g (and)i(use)g(the)g(con)m(v)o(erter)d(function)i(re)o(gistered)f(for)i (that)g(type)g(there.)24 b(Con)m(v)o(erter)208 3128 y(names)19 b(are)i(case-sensiti)n(v)o(e!)0 3274 y FD(PARSE_COLNAMES)208 3374 y FN(This)f(constant)f(is)j(meant)d(to)i(be)f(used)g(with)g(the)g FK(detect)p 1825 3374 V 29 w(types)h FN(parameter)d(of)i(the)g FJ(connect)g FN(function.)208 3507 y(Setting)26 b(this)h(mak)o(es)f (the)h(SQLite)g(interf)o(ace)f(parse)g(the)h(column)e(name)h(for)g (each)g(column)f(it)i(returns.)43 b(It)27 b(will)g(look)f(for)g(a)208 3607 y(string)d(formed)e([mytype])h(in)h(there,)h(and)e(then)h(decide)g (that)g('mytype')f(is)i(the)f(type)g(of)g(the)h(column.)33 b(It)24 b(will)g(try)f(to)h(\002nd)f(an)208 3706 y(entry)16 b(of)h('mytype')e(in)j(the)f(con)m(v)o(erters)e(dictionary)h(and)g (then)h(use)h(the)f(con)m(v)o(erter)e(function)g(found)h(there)h(to)g (return)f(the)h(v)n(alue.)208 3806 y(The)g(column)g(name)h(found)e(in)i FJ(cursor.description)e FN(is)j(only)e(the)h(\002rst)h(w)o(ord)f(of)f (the)i(column)d(name,)i(i.)25 b(e.)g(if)18 b(you)f(use)208 3905 y(something)h(lik)o(e)j FJ('as)49 b("x)h([datetime]"')18 b FN(in)j(your)e(SQL,)h(then)g(we)h(will)g(parse)f(out)g(e)n(v)o (erything)d(until)j(the)h(\002rst)g(blank)208 4005 y(for)e(the)h (column)f(name:)25 b(the)20 b(column)f(name)g(w)o(ould)h(simply)g(be)g (\224x\224.)0 4152 y FD(connect)p FJ(\()p FK(database)p FC([)p FK(,)d(timeout,)i(isolation)p 1367 4152 V 29 w(le)o(vel,)h (detect)p 1792 4152 V 29 w(types,)g(factory)12 b FC(])p FJ(\))208 4252 y FN(Opens)31 b(a)i(connection)d(to)j(the)f(SQLite)h (database)e(\002le)i FK(database)p FN(.)60 b(Y)-9 b(ou)31 b(can)h(use)h FJ(":memory:")e FN(to)h(open)f(a)i(database)208 4351 y(connection)18 b(to)i(a)h(database)e(that)h(resides)h(in)f(RAM)h (instead)f(of)g(on)g(disk.)208 4484 y(When)15 b(a)i(database)e(is)i (accessed)g(by)e(multiple)h(connections,)e(and)i(one)g(of)f(the)h (processes)g(modi\002es)g(the)g(database,)g(the)g(SQLite)208 4584 y(database)i(is)j(lock)o(ed)e(until)g(that)g(transaction)g(is)h (committed.)k(The)19 b FK(timeout)i FN(parameter)d(speci\002es)i(ho)n (w)e(long)h(the)h(connection)208 4683 y(should)f(w)o(ait)h(for)g(the)g (lock)f(to)i(go)e(a)o(w)o(ay)h(until)g(raising)f(an)h(e)o(xception.)j (The)d(def)o(ault)f(for)h(the)g(timeout)f(parameter)g(is)i(5.0)e (\(\002)n(v)o(e)208 4783 y(seconds\).)208 4916 y(F)o(or)27 b(the)h FK(isolation)p 777 4916 V 28 w(le)o(vel)g FN(parameter)m(,)f (please)h(see)g(the)g FJ(isolation_level)e FN(property)f(of)j FJ(Connection)e FN(objects)h(in)208 5015 y(section)20 b(13.13.2.)208 5148 y(SQLite)31 b(nati)n(v)o(ely)f(supports)h(only)f (the)i(types)f(TEXT)-6 b(,)31 b(INTEGER,)f(FLO)m(A)-9 b(T)j(,)31 b(BLOB)i(and)e(NULL.)g(If)g(you)f(w)o(ant)i(to)f(use)208 5248 y(other)23 b(types,)i(lik)o(e)f(you)f(ha)n(v)o(e)h(to)g(add)g (support)e(for)i(them)g(yourself.)35 b(The)24 b FK(detect)p 2609 5248 V 29 w(types)g FN(parameter)f(and)g(the)i(using)e(custom)208 5347 y FL(con)m(v)o(erters)c FN(re)o(gistered)f(with)j(the)f(module-le) n(v)o(el)e FJ(register_converter)f FN(function)h(allo)n(w)j(you)e(to)h (easily)h(do)e(that.)p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g(interf)n(ace)f(f)n(or)f (SQLite)i(databases)1447 b(385)p eop end %%Page: 386 398 TeXDict begin 386 397 bop 208 83 a FK(detect)p 412 83 25 4 v 29 w(types)16 b FN(def)o(aults)f(to)g(0)h(\(i.)24 b(e.)g(of)n(f,)15 b(no)h(type)f(detection\),)g(you)f(can)i(set)g(it)h (to)e(an)o(y)g(combination)e(of)j FJ(PARSE_DECLTYPES)208 183 y FN(and)j FJ(PARSE_COLNAMES)f FN(to)j(turn)e(type)h(detection)f (on.)208 311 y(By)g(def)o(ault,)g(the)g FJ(sqlite3)g FN(module)e(uses)j(its)h FJ(Connection)c FN(class)k(for)d(the)i (connect)e(call.)25 b(Y)-9 b(ou)18 b(can,)h(ho)n(we)n(v)o(er)m(,)e (subclass)208 411 y(the)29 b FJ(Connection)e FN(class)j(and)f(mak)o(e)f FJ(connect)g FN(use)i(your)d(class)j(instead)f(by)g(pro)o(viding)d (your)i(class)h(for)g(the)g FK(factory)208 511 y FN(parameter)-5 b(.)208 639 y(Consult)20 b(the)g(section)g(13.13.4)e(of)i(this)g (manual)f(for)h(details.)208 768 y(The)26 b FJ(sqlite3)g FN(module)f(internally)h(uses)h(a)g(statement)f(cache)h(to)f(a)n(v)n (oid)h(SQL)g(parsing)f(o)o(v)o(erhead.)41 b(If)27 b(you)f(w)o(ant)g(to) h(e)o(x-)208 867 y(plicitly)j(set)i(the)e(number)f(of)i(statements)f (that)h(are)g(cached)f(for)g(the)g(connection,)h(you)f(can)h(set)g(the) g FK(cac)o(hed)p 3527 867 V 27 w(statements)208 967 y FN(parameter)-5 b(.)23 b(The)d(currently)f(implemented)f(def)o(ault)h (is)j(to)e(cache)g(100)f(statements.)0 1114 y FD(register_converter)p FJ(\()p FK(typename)o(,)c(callable)p FJ(\))208 1213 y FN(Re)o(gisters)24 b(a)h(callable)f(to)h(con)m(v)o(ert)d(a)j (bytestring)e(from)h(the)g(database)g(into)g(a)h(custom)f(Python)f (type.)37 b(The)24 b(callable)g(will)i(be)208 1313 y(in)m(v)n(ok)o(ed) 14 b(for)i(all)h(database)e(v)n(alues)h(that)h(are)f(of)g(the)g(type)g FK(typename)p FN(.)23 b(Confer)15 b(the)h(parameter)f FK(detect)p 3135 1313 V 29 w(types)i FN(of)f(the)g FJ(connect)208 1413 y FN(function)24 b(for)i(ho)n(w)g(the)g(type)g(detection)g(w)o (orks.)43 b(Note)26 b(that)h(the)f(case)h(of)f FK(typename)g FN(and)f(the)i(name)f(of)g(the)g(type)g(in)h(your)208 1512 y(query)18 b(must)j(match!)0 1659 y FD(register_adapter)p FJ(\()p FK(type)o(,)c(callable)p FJ(\))208 1759 y FN(Re)o(gisters)22 b(a)h(callable)f(to)h(con)m(v)o(ert)d(the)i(custom)g(Python)f(type)h FK(type)g FN(into)g(one)g(of)g(SQLite')-5 b(s)23 b(supported)e(types.) 31 b(The)22 b(callable)208 1858 y FK(callable)d FN(accepts)i(as)g (single)f(parameter)f(the)i(Python)e(v)n(alue,)h(and)g(must)g(return)g (a)h(v)n(alue)f(of)g(the)g(follo)n(wing)f(types:)26 b(int,)21 b(long,)208 1958 y(\003oat,)f(str)g(\(UTF-8)g(encoded\),)e(unicode)g (or)i(b)n(uf)n(fer)-5 b(.)0 2105 y FD(complete_statement)p FJ(\()p FK(sql)p FJ(\))208 2205 y FN(Returns)17 b FJ(True)g FN(if)h(the)f(string)h FK(sql)g FN(contains)e(one)h(or)g(more)g (complete)f(SQL)i(statements)g(terminated)e(by)h(semicolons.)23 b(It)18 b(does)208 2304 y(not)j(v)o(erify)g(that)h(the)g(SQL)h(is)g (syntactically)e(correct,)g(only)h(that)g(there)f(are)h(no)g(unclosed)f (string)h(literals)g(and)g(the)g(statement)208 2404 y(is)f(terminated)e (by)g(a)i(semicolon.)208 2532 y(This)f(can)g(be)g(used)g(to)g(b)n(uild) g(a)h(shell)f(for)g(SQLite,)g(as)h(in)f(the)h(follo)n(wing)d(e)o (xample:)p 448 2729 23 4 v 471 2729 a Fy(statement.p)o(y)0 2887 y FD(enable_callback_tracebacks)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2986 y FN(By)f(def)o(ault)g(you)f(will)i(not)f(get)g(an)o(y)g (tracebacks)f(in)h(user)n(-de\002ned)f(functions,)g(aggre)o(gates,)f (con)m(v)o(erters,)h(authorizer)f(callbacks)208 3086 y(etc.)25 b(If)19 b(you)f(w)o(ant)i(to)g(deb)n(ug)e(them,)h(you)f(can)i (call)g(this)g(function)d(with)j FK(\003a)o(g)f FN(as)h(T)m(rue.)k (Afterw)o(ards,)18 b(you)h(will)h(get)g(tracebacks)208 3185 y(from)f(callbacks)g(on)h FJ(sys.stderr)p FN(.)k(Use)d FJ(False)e FN(to)i(disable)f(the)g(feature)f(again.)0 3466 y Fv(13.13.2)101 b(Connection)30 b(Objects)0 3669 y FN(A)21 b FJ(Connection)e FN(instance)g(has)i(the)f(follo)n(wing)f (attrib)n(utes)h(and)f(methods:)0 3816 y FD(isolation_level)208 3916 y FN(Get)j(or)f(set)h(the)g(current)e(isolation)h(le)n(v)o(el.)29 b(None)21 b(for)f(autocommit)g(mode)h(or)g(one)g(of)g (\224DEFERRED\224,)h(\224IMMEDIA)-9 b(TE\224)20 b(or)208 4016 y(\224EXLUSIVE\224.)k(See)c(\223Controlling)f(T)m (ransactions\224,)f(section)i(13.13.5,)e(for)i(a)g(more)f(detailed)h(e) o(xplanation.)0 4162 y FD(cursor)p FJ(\()p FC([)p FK(cur)o(sorClass)12 b FC(])p FJ(\))208 4262 y FN(The)23 b(cursor)g(method)f(accepts)h(a)i (single)e(optional)g(parameter)f FK(cur)o(sorClass)p FN(.)36 b(If)24 b(supplied,)f(this)h(must)g(be)f(a)h(custom)g(cursor) 208 4362 y(class)d(that)f(e)o(xtends)f FJ(sqlite3.Cursor)p FN(.)0 4509 y FD(execute)p FJ(\()p FK(sql,)g FC([)p FK(par)o(ameter)o (s)12 b FC(])p FJ(\))208 4608 y FN(This)19 b(is)h(a)g(nonstandard)d (shortcut)h(that)h(creates)h(an)f(intermediate)f(cursor)g(object)h(by)g (calling)g(the)g(cursor)f(method,)g(then)h(calls)208 4708 y(the)h(cursor')-5 b(s)19 b FJ(execute)h FN(method)f(with)h(the)g (parameters)f(gi)n(v)o(en.)0 4855 y FD(executemany)p FJ(\()p FK(sql,)f FC([)p FK(par)o(ameter)o(s)12 b FC(])p FJ(\))208 4954 y FN(This)19 b(is)h(a)g(nonstandard)d(shortcut)h(that)h (creates)h(an)f(intermediate)f(cursor)g(object)h(by)g(calling)g(the)g (cursor)f(method,)g(then)h(calls)208 5054 y(the)h(cursor')-5 b(s)19 b FJ(executemany)g FN(method)g(with)h(the)g(parameters)f(gi)n(v) o(en.)0 5201 y FD(executescript)p FJ(\()p FK(sql)p 802 5201 25 4 v 27 w(script)q FJ(\))208 5300 y FN(This)g(is)h(a)g (nonstandard)d(shortcut)h(that)h(creates)h(an)f(intermediate)f(cursor)g (object)h(by)g(calling)g(the)g(cursor)f(method,)g(then)h(calls)208 5400 y(the)h(cursor')-5 b(s)19 b FJ(executescript)g FN(method)g(with)h (the)g(parameters)f(gi)n(v)o(en.)p 0 5549 3901 4 v 0 5649 a FI(386)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 387 399 TeXDict begin 387 398 bop 0 83 a FD(create_function)p FJ(\()p FK(name)o(,)17 b(num)p 1167 83 25 4 v 28 w(par)o(ams,)j(func)p FJ(\))208 183 y FN(Creates)29 b(a)g(user)n(-de\002ned)e(function)h (that)g(you)g(can)h(later)g(use)g(from)f(within)h(SQL)g(statements)g (under)e(the)i(function)e(name)208 282 y FK(name)p FN(.)c FK(num)p 582 282 V 29 w(par)o(ams)c FN(is)h(the)f(number)e(of)h (parameters)g(the)h(function)e(accepts,)i(and)g FK(func)f FN(is)i(a)f(Python)f(callable)h(that)g(is)h(called)208 382 y(as)g(the)h(SQL)f(function.)208 515 y(The)f(function)g(can)h (return)f(an)o(y)g(of)h(the)g(types)g(supported)f(by)g(SQLite:)26 b(unicode,)18 b(str)m(,)j(int,)f(long,)f(\003oat,)h(b)n(uf)n(fer)f(and) h(None.)208 648 y(Example:)444 853 y FA(import)44 b(sqlite3)444 944 y(import)g(md5)444 1127 y(def)g(md5sum\(t\):)623 1218 y(return)g(md5.md5\(t\).hexdigest\(\))444 1401 y(con)g(=)h (sqlite3.connect\(":memory:"\))444 1492 y(con.create_function\("md5",) 40 b(1,)45 b(md5sum\))444 1583 y(cur)f(=)h(con.cursor\(\))444 1674 y(cur.execute\("select)c(md5\(?\)",)j(\("foo",\)\))444 1766 y(print)g(cur.fetchone\(\)[0])0 1932 y FD(create_aggregate)p FJ(\()p FK(name)o(,)16 b(num)p 1216 1932 V 29 w(par)o(ams,)k(a)o(g)o (gr)m(e)m(gate)p 1866 1932 V 27 w(class)p FJ(\))208 2031 y FN(Creates)g(a)h(user)n(-de\002ned)d(aggre)o(gate)g(function.)208 2164 y(The)26 b(aggre)o(gate)e(class)j(must)g(implement)e(a)i FJ(step)g FN(method,)f(which)g(accepts)h(the)f(number)f(of)h (parameters)g FK(num)p 3608 2164 V 28 w(par)o(ams)p FN(,)208 2264 y(and)19 b(a)i FJ(finalize)e FN(method)g(which)h(will)g(return)f (the)i(\002nal)f(result)g(of)g(the)g(aggre)o(gate.)208 2397 y(The)j FJ(finalize)h FN(method)f(can)h(return)f(an)o(y)g(of)h (the)h(types)f(supported)e(by)i(SQLite:)34 b(unicode,)23 b(str)m(,)i(int,)h(long,)e(\003oat,)h(b)n(uf)n(fer)208 2496 y(and)19 b(None.)208 2629 y(Example:)444 2834 y FA(import)44 b(sqlite3)444 3017 y(class)g(MySum:)623 3108 y(def)g(__init__\(self\):)802 3200 y(self.count)g(=)g(0)623 3382 y(def)g(step\(self,)g(value\):)802 3473 y(self.count)g(+=)g(value) 623 3656 y(def)g(finalize\(self\):)802 3747 y(return)g(self.count)444 3930 y(con)g(=)h(sqlite3.connect\(":memory:"\))444 4021 y(con.create_aggregate\("mysum",)40 b(1,)k(MySum\))444 4113 y(cur)g(=)h(con.cursor\(\))444 4204 y(cur.execute\("create)c (table)j(test\(i\)"\))444 4295 y(cur.execute\("insert)d(into)k (test\(i\))e(values)h(\(1\)"\))444 4387 y(cur.execute\("insert)d(into)k (test\(i\))e(values)h(\(2\)"\))444 4478 y(cur.execute\("select)d (mysum\(i\))j(from)g(test"\))444 4569 y(print)g(cur.fetchone\(\)[0])0 4735 y FD(create_collation)p FJ(\()p FK(name)o(,)16 b(callable)p FJ(\))208 4835 y FN(Creates)24 b(a)g(collation)f(with)h(the)g (speci\002ed)f FK(name)h FN(and)f FK(callable)p FN(.)35 b(The)23 b(callable)h(will)g(be)g(passed)g(tw)o(o)g(string)g(ar)o (guments.)33 b(It)208 4935 y(should)27 b(return)g(-1)h(if)g(the)g (\002rst)h(is)h(ordered)c(lo)n(wer)i(than)f(the)i(second,)g(0)f(if)g (the)o(y)g(are)g(ordered)e(equal)i(and)g(1)g(if)g(the)h(\002rst)g(is) 208 5034 y(ordered)16 b(higher)i(than)g(the)h(second.)k(Note)c(that)g (this)g(controls)f(sorting)g(\(ORDER)h(BY)h(in)f(SQL\))g(so)g(your)e (comparisons)g(don')o(t)208 5134 y(af)n(fect)i(other)h(SQL)g (operations.)208 5267 y(Note)g(that)g(the)g(callable)g(will)h(get)f (its)h(parameters)e(as)i(Python)e(bytestrings,)g(which)h(will)h (normally)d(be)j(encoded)d(in)i(UTF-8.)208 5400 y(The)f(follo)n(wing)g (e)o(xample)g(sho)n(ws)h(a)h(custom)e(collation)h(that)g(sorts)g (\224the)g(wrong)f(w)o(ay\224:)p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g(interf)n(ace) f(f)n(or)f(SQLite)i(databases)1447 b(387)p eop end %%Page: 388 400 TeXDict begin 388 399 bop 448 83 23 4 v 471 83 a Fy(re)n(v)o(erse.p)o (y)208 296 y FN(T)-7 b(o)20 b(remo)o(v)o(e)e(a)j(collation,)e(call)h FJ(create_collation)e FN(with)j(None)e(as)i(callable:)623 520 y FA(con.create_collation\("reverse",)40 b(None\))0 722 y FD(interrupt)p FJ(\(\))208 822 y FN(Y)-9 b(ou)19 b(can)g(call)h(this)g(method)f(from)f(a)j(dif)n(ferent)d(thread)g(to)i (abort)f(an)o(y)g(queries)g(that)h(might)f(be)g(e)o(x)o(ecuting)f(on)h (the)h(connection.)208 921 y(The)f(query)g(will)i(then)f(abort)f(and)h (the)g(caller)g(will)h(get)f(an)g(e)o(xception.)0 1068 y FD(set_authorizer)p FJ(\()p FK(authorizer)p 1102 1068 25 4 v 26 w(callbac)n(k)q FJ(\))208 1168 y FN(This)29 b(routine)e(re)o(gisters)h(a)i(callback.)50 b(The)28 b(callback)g(is)i(in)m(v)n(ok)o(ed)d(for)h(each)g(attempt)h(to)g (access)g(a)g(column)f(of)g(a)i(table)e(in)208 1267 y(the)23 b(database.)32 b(The)23 b(callback)f(should)g(return)g FJ(SQLITE_OK)g FN(if)h(access)h(is)g(allo)n(wed,)f FJ(SQLITE_DENY)e FN(if)j(the)f(entire)f(SQL)208 1367 y(statement)h(should)g(be)h (aborted)f(with)h(an)g(error)e(and)i FJ(SQLITE_IGNORE)e FN(if)i(the)g(column)e(should)h(be)h(treated)g(as)g(a)h(NULL)208 1467 y(v)n(alue.)f(These)c(constants)g(are)g(a)n(v)n(ailable)f(in)i (the)f FJ(sqlite3)f FN(module.)208 1600 y(The)26 b(\002rst)h(ar)o (gument)d(to)j(the)f(callback)g(signi\002es)h(what)f(kind)g(of)g (operation)f(is)i(to)g(be)g(authorized.)41 b(The)27 b(second)e(and)h (third)208 1699 y(ar)o(gument)e(will)k(be)f(ar)o(guments)d(or)j FJ(None)g FN(depending)d(on)j(the)g(\002rst)g(ar)o(gument.)43 b(The)27 b(4th)f(ar)o(gument)f(is)j(the)f(name)f(of)h(the)208 1799 y(database)c(\(\224main\224,)g(\224temp\224,)h(etc.\))35 b(if)24 b(applicable.)34 b(The)23 b(5th)h(ar)o(gument)d(is)k(the)e (name)g(of)h(the)f(inner)n(-most)g(trigger)f(or)i(vie)n(w)208 1898 y(that)c(is)h(responsible)e(for)g(the)i(access)f(attempt)g(or)g FJ(None)g FN(if)h(this)f(access)h(attempt)f(is)h(directly)f(from)f (input)g(SQL)i(code.)208 2031 y(Please)e(consult)e(the)h(SQLite)h (documentation)c(about)j(the)g(possible)g(v)n(alues)g(for)g(the)g (\002rst)h(ar)o(gument)d(and)i(the)g(meaning)f(of)h(the)208 2131 y(second)24 b(and)g(third)g(ar)o(gument)f(depending)f(on)j(the)g (\002rst)h(one.)38 b(All)26 b(necessary)e(constants)h(are)g(a)n(v)n (ailable)f(in)h(the)g FJ(sqlite3)208 2230 y FN(module.)0 2377 y FD(row_factory)208 2477 y FN(Y)-9 b(ou)20 b(can)g(change)g(this) h(attrib)n(ute)g(to)g(a)g(callable)g(that)g(accepts)f(the)h(cursor)f (and)h(the)f(original)g(ro)n(w)h(as)g(a)g(tuple)g(and)f(will)i(return) 208 2577 y(the)e(real)g(result)g(ro)n(w)-5 b(.)24 b(This)c(w)o(ay)-5 b(,)20 b(you)f(can)h(implement)f(more)g(adv)n(anced)f(w)o(ays)j(of)f (returning)e(results,)i(such)g(as)h(returning)d(an)208 2676 y(object)h(that)h(can)g(also)h(access)g(columns)e(by)h(name.)208 2809 y(Example:)p 448 3014 23 4 v 471 3014 a Fy(f)o(actory)-5 b(.p)o(y)208 3227 y FN(If)26 b(returning)f(a)i(tuple)f(doesn')o(t)g (suf)n(\002ce)g(and)g(you)g(w)o(ant)h(name-based)e(access)i(to)g (columns,)g(you)f(should)g(consider)g(setting)208 3327 y FJ(row_factory)33 b FN(to)i(the)g(highly-optimized)c FJ(sqlite3.Row)i FN(type.)68 b FJ(Row)35 b FN(pro)o(vides)e(both)h (inde)o(x-based)e(and)i(case-)208 3427 y(insensiti)n(v)o(e)27 b(name-based)f(access)j(to)f(columns)f(with)h(almost)g(no)g(memory)e(o) o(v)o(erhead.)46 b(It)28 b(will)h(probably)c(be)j(better)g(than)208 3526 y(your)18 b(o)n(wn)i(custom)g(dictionary-based)d(approach)h(or)i (e)n(v)o(en)f(a)i(db)p 2113 3526 25 4 v 28 w(ro)n(w)f(based)g (solution.)0 3673 y FD(text_factory)208 3773 y FN(Using)g(this)i (attrib)n(ute)f(you)f(can)g(control)g(what)h(objects)g(are)g(returned)e (for)h(the)h(TEXT)g(data)g(type.)27 b(By)21 b(def)o(ault,)f(this)i (attrib)n(ute)208 3872 y(is)30 b(set)g(to)g FJ(unicode)f FN(and)g(the)g FJ(sqlite3)g FN(module)f(will)j(return)d(Unicode)g (objects)i(for)f(TEXT)-6 b(.)28 b(If)i(you)e(w)o(ant)i(to)g(return)208 3972 y(bytestrings)19 b(instead,)g(you)h(can)g(set)h(it)g(to)f FJ(str)p FN(.)208 4105 y(F)o(or)25 b(ef)n(\002cienc)o(y)f(reasons,)i (there')-5 b(s)25 b(also)h(a)g(w)o(ay)f(to)h(return)e(Unicode)h (objects)g(only)f(for)h(non-ASCII)f(data,)j(and)e(bytestrings)208 4204 y(otherwise.)f(T)-7 b(o)20 b(acti)n(v)n(ate)g(it,)h(set)g(this)f (attrib)n(ute)g(to)h FJ(sqlite3.OptimizedUnicode)p FN(.)208 4337 y(Y)-9 b(ou)15 b(can)i(also)g(set)g(it)g(to)g(an)o(y)f(other)f (callable)i(that)f(accepts)h(a)g(single)f(bytestring)f(parameter)g(and) h(returns)g(the)h(resulting)e(object.)208 4470 y(See)20 b(the)g(follo)n(wing)f(e)o(xample)g(code)g(for)h(illustration:)p 448 4675 23 4 v 471 4675 a Fy(f)o(actory)-5 b(.p)o(y)0 4841 y FD(total_changes)208 4941 y FN(Returns)31 b(the)g(total)h (number)d(of)i(database)g(ro)n(ws)g(that)g(ha)n(v)o(e)g(been)g (modi\002ed,)h(inserted,)i(or)d(deleted)f(since)i(the)f(database)208 5040 y(connection)18 b(w)o(as)j(opened.)p 0 5549 3901 4 v 0 5649 a FI(388)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 389 401 TeXDict begin 389 400 bop 0 83 a Fv(13.13.3)101 b(Cursor)29 b(Objects)0 286 y FN(A)21 b FJ(Cursor)e FN(instance)h(has)h(the)f (follo)n(wing)e(attrib)n(utes)i(and)g(methods:)0 433 y FD(execute)p FJ(\()p FK(sql,)f FC([)p FK(par)o(ameter)o(s)12 b FC(])p FJ(\))208 532 y FN(Ex)o(ecutes)26 b(a)h(SQL)g(statement.)45 b(The)27 b(SQL)g(statement)g(may)f(be)h(parametrized)e(\(i.)46 b(e.)f(placeholders)25 b(instead)i(of)g(SQL)g(lit-)208 632 y(erals\).)44 b(The)27 b FJ(sqlite3)f FN(module)g(supports)f(tw)o (o)i(kinds)g(of)f(placeholders:)37 b(question)26 b(marks)g(\(qmark)f (style\))i(and)g(named)208 732 y(placeholders)18 b(\(named)h(style\).) 208 865 y(This)h(e)o(xample)f(sho)n(ws)h(ho)n(w)g(to)g(use)g (parameters)f(with)i(qmark)e(style:)p 448 1070 23 4 v 471 1070 a Fy(1.p)o(y)208 1283 y FN(This)h(e)o(xample)f(sho)n(ws)h(ho)n (w)g(to)g(use)g(the)h(named)e(style:)p 448 1488 V 471 1488 a Fy(2.p)o(y)208 1701 y FJ(execute\(\))f FN(will)i(only)f(e)o(x)o (ecute)f(a)h(single)h(SQL)g(statement.)k(If)19 b(you)g(try)g(to)h(e)o (x)o(ecute)e(more)g(than)h(one)g(statement)g(with)h(it,)g(it)208 1801 y(will)g(raise)h(a)g(W)-7 b(arning.)24 b(Use)d FJ (executescript\(\))d FN(if)i(you)g(w)o(ant)g(to)g(e)o(x)o(ecute)f (multiple)h(SQL)g(statements)g(with)h(one)e(call.)0 1948 y FD(executemany)p FJ(\()p FK(sql,)f(seq)p 852 1948 25 4 v 30 w(of)p 947 1948 V 29 w(par)o(ameter)o(s)p FJ(\))208 2047 y FN(Ex)o(ecutes)35 b(a)h(SQL)g(command)e(against)h(all)i (parameter)d(sequences)h(or)h(mappings)e(found)g(in)j(the)e(sequence)g FK(sql)p FN(.)73 b(The)208 2147 y FJ(sqlite3)19 b FN(module)g(also)h (allo)n(ws)h(using)e(an)i(iterator)e(yielding)g(parameters)g(instead)h (of)g(a)g(sequence.)p 448 2352 23 4 v 471 2352 a Fy(1.p)o(y)208 2565 y FN(Here')-5 b(s)20 b(a)h(shorter)e(e)o(xample)g(using)g(a)i (generator:)p 448 2770 V 471 2770 a Fy(2.p)o(y)0 2936 y FD(executescript)p FJ(\()p FK(sql)p 802 2936 25 4 v 27 w(script)q FJ(\))208 3036 y FN(This)e(is)h(a)g(nonstandard)c(con)m (v)o(enience)g(method)i(for)h(e)o(x)o(ecuting)e(multiple)h(SQL)i (statements)f(at)h(once.)k(It)19 b(issues)h(a)g(COMMIT)208 3135 y(statement)g(\002rst,)g(then)g(e)o(x)o(ecutes)f(the)h(SQL)h (script)f(it)h(gets)f(as)h(a)g(parameter)-5 b(.)208 3268 y FK(sql)p 310 3268 V 29 w(script)23 b FN(can)d(be)g(a)g(bytestring)f (or)h(a)h(Unicode)e(string.)208 3401 y(Example:)444 3606 y FA(import)44 b(sqlite3)444 3789 y(con)g(=)h (sqlite3.connect\(":memory:"\))444 3880 y(cur)f(=)h(con.cursor\(\))444 3971 y(cur.executescript\(""")623 4063 y(create)f(table)g(person\()802 4154 y(firstname,)802 4245 y(lastname,)802 4337 y(age)623 4428 y(\);)623 4611 y(create)g(table)g(book\()802 4702 y(title,)802 4793 y(author,)802 4885 y(published)623 4976 y(\);)623 5159 y(insert)g(into)g(book\(title,)f(author,)h (published\))623 5250 y(values)g(\()802 5341 y('Dirk)g(Gently''s)g (Holistic)f(Detective)h(Agency',)p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g(interf)n (ace)f(f)n(or)f(SQLite)i(databases)1447 b(389)p eop end %%Page: 390 402 TeXDict begin 390 401 bop 802 83 a FA('Douglas)44 b(Adams',)802 174 y(1987)623 266 y(\);)623 357 y("""\))0 523 y FD(rowcount)208 623 y FN(Although)28 b(the)j FJ(Cursor)f FN(class)i(of)f(the)f FJ(sqlite3)g FN(module)g(implements)f(this)j(attrib)n(ute,)g(the)f (database)f(engine')-5 b(s)30 b(o)n(wn)208 722 y(support)18 b(for)i(the)g(determination)e(of)i(\224ro)n(ws)g(af)n (fected\224/\224ro)n(ws)e(selected\224)i(is)h(quirk)o(y)-5 b(.)208 855 y(F)o(or)19 b FJ(SELECT)g FN(statements,)g FJ(rowcount)g FN(is)i(al)o(w)o(ays)f(None)f(because)g(we)h(cannot)e (determine)h(the)g(number)f(of)h(ro)n(ws)h(a)g(query)208 955 y(produced)d(until)j(all)h(ro)n(ws)f(were)g(fetched.)208 1088 y(F)o(or)h FJ(DELETE)h FN(statements,)g(SQLite)h(reports)e FJ(rowcount)g FN(as)i(0)f(if)h(you)e(mak)o(e)h(a)g FJ(DELETE)49 b(FROM)g(table)22 b FN(without)f(an)o(y)208 1187 y(condition.)208 1320 y(F)o(or)e FJ(executemany)g FN(statements,)h(the)g(number)f(of)h (modi\002cations)e(are)j(summed)e(up)g(into)h FJ(rowcount)p FN(.)208 1453 y(As)30 b(required)e(by)i(the)g(Python)f(DB)i(API)f (Spec,)i(the)e FJ(rowcount)f FN(attrib)n(ute)h(\224is)g(-1)g(in)g(case) h(no)e(e)o(x)o(ecuteXX\(\))f(has)i(been)208 1553 y(performed)17 b(on)j(the)g(cursor)f(or)h(the)g(ro)n(wcount)f(of)h(the)g(last)h (operation)d(is)j(not)f(determinable)e(by)i(the)g(interf)o(ace\224.)0 1837 y Fv(13.13.4)101 b(SQLite)28 b(and)h(Python)g(types)0 2040 y FI(Introduction)0 2243 y FN(SQLite)21 b(nati)n(v)o(ely)e (supports)g(the)h(follo)n(wing)e(types:)25 b(NULL,)20 b(INTEGER,)g(REAL,)g(TEXT)-6 b(,)20 b(BLOB.)0 2390 y(The)g(follo)n (wing)e(Python)h(types)h(can)g(thus)h(be)f(sent)g(to)h(SQLite)f (without)g(an)o(y)f(problem:)1474 2616 y FL(Python)g(type)p 2183 2646 4 100 v 334 w(SQLite)h(type)p 1189 2650 1523 4 v 1587 2719 a FJ(None)p 2183 2749 4 100 v 448 w FN(NULL)1612 2819 y FJ(int)p 2183 2849 V 473 w FN(INTEGER)1587 2919 y FJ(long)p 2183 2948 V 448 w FN(INTEGER)1562 3018 y FJ(float)p 2183 3048 V 423 w FN(REAL)1239 3118 y FJ(str)49 b(\(UTF8-encoded\))p 2183 3148 V 97 w FN(TEXT)1513 3217 y FJ(unicode)p 2183 3247 V 372 w FN(TEXT)1537 3317 y FJ(buffer)p 2183 3347 V 398 w FN(BLOB)0 3542 y(This)20 b(is)h(ho)n(w)f(SQLite)h(types)f(are)g(con)m(v)o(erted)d(to)k(Python)e (types)h(by)g(def)o(ault:)968 3768 y FL(SQLite)h(type)p 1443 3798 V 99 w(Python)e(type)p 918 3802 2064 4 v 1082 3871 a FJ(NULL)p 1443 3901 4 100 v 213 w FN(None)1007 3971 y FJ(INTEGER)p 1443 4001 V 138 w FN(int)h(or)g(long,)f(depending)f (on)h(size)1082 4071 y FJ(REAL)p 1443 4101 V 213 w FN(\003oat)1082 4170 y FJ(TEXT)p 1443 4200 V 213 w FN(depends)f(on)i(te)o(xt)p 2020 4170 25 4 v 29 w(f)o(actory)-5 b(,)19 b(unicode)f(by)i(def)o(ault) 1082 4270 y FJ(BLOB)p 1443 4300 4 100 v 213 w FN(b)n(uf)n(fer)0 4495 y(The)d(type)h(system)g(of)f(the)h FJ(sqlite3)f FN(module)f(is)j(e)o(xtensible)d(in)i(tw)o(o)g(w)o(ays:)25 b(you)16 b(can)i(store)g(additional)e(Python)h(types)g(in)h(a)g(SQLite) 0 4595 y(database)j(via)h(object)g(adaptation,)e(and)i(you)f(can)g(let) i(the)f FJ(sqlite3)f FN(module)g(con)m(v)o(ert)f(SQLite)i(types)g(to)g (dif)n(ferent)e(Python)h(types)0 4694 y(via)f(con)m(v)o(erters.)0 4963 y FI(Using)j(adapters)g(to)h(store)e(additional)k(Python)d(types)g (in)g(SQLite)h(databases)0 5165 y FN(As)c(described)f(before,)f(SQLite) i(supports)f(only)f(a)i(limited)g(set)g(of)g(types)f(nati)n(v)o(ely)-5 b(.)23 b(T)-7 b(o)20 b(use)g(other)f(Python)f(types)i(with)g(SQLite,)f (you)0 5265 y(must)26 b FL(adapt)g FN(them)g(to)g(one)g(of)g(the)g (sqlite3)h(module')-5 b(s)25 b(supported)f(types)i(for)g(SQLite:)38 b(one)25 b(of)h(NoneT)-7 b(ype,)26 b(int,)i(long,)f(\003oat,)h(str)m(,) 0 5365 y(unicode,)18 b(b)n(uf)n(fer)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(390)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 391 403 TeXDict begin 391 402 bop 0 83 a FN(The)32 b FJ(sqlite3)g FN(module)g(uses)h(Python)e(object)i(adaptation,)h(as)f(described)e(in) i(PEP)h(246)d(for)h(this.)63 b(The)33 b(protocol)e(to)i(use)g(is)0 183 y FJ(PrepareProtocol)p FN(.)0 330 y(There)19 b(are)h(tw)o(o)h(w)o (ays)f(to)h(enable)e(the)h FJ(sqlite3)g FN(module)f(to)h(adapt)g(a)g (custom)g(Python)f(type)h(to)g(one)g(of)g(the)g(supported)e(ones.)0 598 y FI(Letting)26 b(y)n(our)f(object)h(adapt)g(itself)83 b FN(This)23 b(is)f(a)h(good)e(approach)e(if)k(you)e(write)h(the)g (class)h(yourself.)29 b(Let')-5 b(s)23 b(suppose)e(you)g(ha)n(v)o(e)g (a)0 697 y(class)g(lik)o(e)g(this:)236 936 y FA(class)44 b(Point\(object\):)416 1027 y(def)g(__init__\(self,)e(x,)j(y\):)595 1118 y(self.x,)f(self.y)f(=)i(x,)g(y)0 1405 y FN(No)n(w)25 b(you)f(w)o(ant)i(to)f(store)g(the)g(point)g(in)g(a)h(single)f(SQLite)h (column.)38 b(First)26 b(you')o(ll)e(ha)n(v)o(e)h(to)g(choose)g(one)f (of)h(the)h(supported)d(types)0 1504 y(\002rst)f(to)f(be)g(used)g(for)f (representing)f(the)i(point.)27 b(Let')-5 b(s)22 b(just)f(use)h(str)f (and)g(separate)f(the)h(coordinates)f(using)g(a)i(semicolon.)k(Then)20 b(you)0 1604 y(need)e(to)i(gi)n(v)o(e)e(your)g(class)i(a)f(method)f FJ(__conform__\(self,)46 b(protocol\))18 b FN(which)h(must)g(return)f (the)h(con)m(v)o(erted)d(v)n(alue.)24 b(The)0 1704 y(parameter)19 b FK(pr)l(otocol)g FN(will)i(be)f FJ(PrepareProtocol)p FN(.)p 241 1892 23 4 v 263 1892 a Fy(point)p 420 1892 V 28 w(1.p)o(y)0 2160 y FI(Register)q(ing)31 b(an)f(adapter)g(callab)n (le)85 b FN(The)26 b(other)f(possibility)h(is)h(to)f(create)g(a)h (function)e(that)h(con)m(v)o(erts)e(the)j(type)e(to)i(the)f(string)0 2260 y(representation)18 b(and)i(re)o(gister)f(the)h(function)f(with)h FJ(register_adapter)p FN(.)0 2407 y FL(Note:)k FN(The)c(type/class)g (to)h(adapt)e(must)i(be)f(a)g(ne)n(w-style)g(class,)h(i.)k(e.)h(it)20 b(must)h(ha)n(v)o(e)e FJ(object)h FN(as)h(one)f(of)f(its)j(bases.)p 241 2595 V 263 2595 a Fy(point)p 420 2595 V 28 w(2.p)o(y)0 2792 y FN(The)93 b FJ(sqlite3)g FN(module)f(has)i(tw)o(o)g(def)o(ault)e (adapters)h(for)g(Python')-5 b(s)93 b(b)n(uilt-in)f FJ(datetime.date)g FN(and)0 2892 y FJ(datetime.datetime)39 b FN(types.)90 b(No)n(w)41 b(let')-5 b(s)43 b(suppose)e(we)h(w)o(ant)g(to)g(store)f FJ(datetime.datetime)e FN(objects)j(not)f(in)0 2991 y(ISO)21 b(representation,)c(b)n(ut)k(as)f(a)j(U)t FH(N)t(I)t(X)g FN(timestamp.)p 241 3180 V 263 3180 a Fy(datetime.p)o(y)0 3448 y FI(Con)n(v)n(er)s(ting)h(SQLite)g(v)n(alues)f(to)g(custom)g (Python)g(types)0 3651 y FN(Writing)i(an)g(adapter)f(lets)i(you)e(send) g(custom)h(Python)f(types)g(to)i(SQLite.)39 b(But)26 b(to)f(mak)o(e)f(it)i(really)f(useful)f(we)i(need)e(to)h(mak)o(e)g(the) 0 3750 y(Python)19 b(to)h(SQLite)h(to)f(Python)f(roundtrip)f(w)o(ork.)0 3897 y(Enter)i(con)m(v)o(erters.)0 4044 y(Let')-5 b(s)21 b(go)f(back)f(to)h(the)h FJ(Point)e FN(class.)26 b(W)-7 b(e)22 b(stored)d(the)i(x)f(and)f(y)i(coordinates)d(separated)h(via)i (semicolons)e(as)i(strings)f(in)g(SQLite.)0 4191 y(First,)h(we')o(ll)f (de\002ne)g(a)h(con)m(v)o(erter)c(function)i(that)h(accepts)g(the)g (string)g(as)h(a)g(parameter)d(and)i(constructs)f(a)i FJ(Point)f FN(object)g(from)f(it.)0 4338 y FL(Note:)41 b FN(Con)m(v)o(erter)26 b(functions)h FL(always)h FN(get)g(called)h (with)f(a)h(string,)h(no)e(matter)g(under)f(which)h(data)g(type)g(you)g (sent)g(the)h(v)n(alue)e(to)0 4437 y(SQLite.)0 4584 y FL(Note:)d FN(Con)m(v)o(erter)19 b(names)g(are)i(look)o(ed)d(up)i(in)h (a)f(case-sensiti)n(v)o(e)g(manner)-5 b(.)416 4823 y FA(def)44 b(convert_point\(s\):)595 4914 y(x,)g(y)h(=)g(map\(float,)e (s.split\(";"\)\))595 5005 y(return)h(Point\(x,)f(y\))0 5292 y FN(No)n(w)21 b(you)g(need)f(to)i(mak)o(e)f(the)g FJ(sqlite3)g FN(module)f(kno)n(w)g(that)i(what)f(you)f(select)i(from)f (the)g(database)g(is)h(actually)f(a)h(point.)27 b(There)0 5391 y(are)20 b(tw)o(o)h(w)o(ays)f(of)g(doing)f(this:)p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g(interf)n(ace)f(f)n(or)f(SQLite)i(databases) 1447 b(391)p eop end %%Page: 392 404 TeXDict begin 392 403 bop 125 83 a FM(\017)41 b FN(Implicitly)19 b(via)h(the)g(declared)f(type)125 249 y FM(\017)41 b FN(Explicitly)19 b(via)h(the)g(column)f(name)0 479 y(Both)e(w)o(ays)f (are)h(described)e(in)i(\223Module)e(Constants\224,)i(section)f (13.13.1,)f(in)h(the)h(entries)f(for)g(the)h(constants)f FJ(PARSE_DECLTYPES)0 579 y FN(and)k FJ(PARSE_COLNAMES)p FN(.)0 725 y(The)g(follo)n(wing)e(e)o(xample)h(illustrates)i(both)e (approaches.)p 241 914 23 4 v 263 914 a Fy(point.p)o(y)0 1182 y FI(Def)n(ault)24 b(adapters)f(and)g(con)n(v)n(er)s(ters)0 1385 y FN(There)c(are)h(def)o(ault)g(adapters)f(for)g(the)i(date)f(and) f(datetime)h(types)g(in)g(the)g(datetime)g(module.)j(The)o(y)c(will)i (be)f(sent)g(as)h(ISO)g(dates/ISO)0 1485 y(timestamps)f(to)g(SQLite.)0 1632 y(The)h(def)o(ault)h(con)m(v)o(erters)d(are)j(re)o(gistered)e (under)h(the)h(name)f(\224date\224)g(for)h FJ(datetime.date)e FN(and)h(under)f(the)i(name)f(\224timestamp\224)0 1731 y(for)f FJ(datetime.datetime)p FN(.)0 1878 y(This)i(w)o(ay)-5 b(,)21 b(you)g(can)g(use)h(date/timestamps)f(from)f(Python)h(without)g (an)o(y)f(additional)h(\002ddling)f(in)i(most)g(cases.)29 b(The)22 b(format)e(of)i(the)0 1978 y(adapters)d(is)j(also)e (compatible)f(with)h(the)g(e)o(xperimental)e(SQLite)j(date/time)f (functions.)0 2125 y(The)g(follo)n(wing)e(e)o(xample)h(demonstrates)g (this.)p 241 2313 V 263 2313 a Fy(datetime.p)o(y)0 2598 y Fv(13.13.5)101 b(Controlling)30 b(T)-12 b(r)o(ansactions)0 2801 y FN(By)25 b(def)o(ault,)h(the)f FJ(sqlite3)f FN(module)f(opens)i (transactions)f(implicitly)g(before)g(a)h(Data)g(Modi\002cation)f (Language)f(\(DML\))h(state-)0 2900 y(ment)29 b(\(i.e.)53 b(INSER)-5 b(T/UPD)m(A)c(TE/DELETE/REPLA)m(CE\),)26 b(and)j(commits)g (transactions)g(implicitly)g(before)f(a)h(non-DML,)f(non-)0 3000 y(query)19 b(statement)h(\(i.)25 b(e.)g(an)o(ything)18 b(other)i(than)g(SELECT/INSER)-5 b(T/UPD)m(A)c(TE/DELETE/REPLA)m(CE\).) 0 3147 y(So)39 b(if)f(you)g(are)g(within)h(a)g(transaction)e(and)h (issue)h(a)g(command)d(lik)o(e)j FJ(CREATE)49 b(TABLE)f(...)p FN(,)43 b FJ(VACUUM)p FN(,)38 b FJ(PRAGMA)p FN(,)g(the)0 3246 y FJ(sqlite3)30 b FN(module)f(will)i(commit)f(implicitly)g(before) f(e)o(x)o(ecuting)g(that)h(command.)54 b(There)30 b(are)h(tw)o(o)f (reasons)h(for)e(doing)h(that.)0 3346 y(The)25 b(\002rst)h(is)g(that)f (some)g(of)f(these)i(commands)d(don')o(t)g(w)o(ork)i(within)g (transactions.)38 b(The)25 b(other)f(reason)h(is)h(that)f(p)o(ysqlite)g (needs)f(to)0 3446 y(k)o(eep)c(track)f(of)h(the)h(transaction)e(state)h (\(if)h(a)f(transaction)f(is)i(acti)n(v)o(e)f(or)g(not\).)0 3593 y(Y)-9 b(ou)19 b(can)g(control)g(which)g(kind)f(of)i (\224BEGIN\224)f(statements)h(p)o(ysqlite)f(implicitly)g(e)o(x)o (ecutes)g(\(or)f(none)h(at)h(all\))g(via)f(the)h FK(isolation)p 3721 3593 25 4 v 29 w(le)o(vel)0 3692 y FN(parameter)f(to)h(the)g FJ(connect)g FN(call,)g(or)g(via)g(the)g FJ(isolation_level)e FN(property)g(of)i(connections.)0 3839 y(If)g(you)f(w)o(ant)i FL(autocommit)e(mode)p FN(,)h(then)g(set)h FJ(isolation_level)d FN(to)i(None.)0 3986 y(Otherwise)f(lea)n(v)o(e)g(it)h(at)g(its)g(def)o (ault,)f(which)g(will)h(result)f(in)g(a)h(plain)f(\224BEGIN\224)g (statement,)g(or)g(set)h(it)g(to)g(one)e(of)h(SQLite')-5 b(s)21 b(supported)0 4086 y(isolation)f(le)n(v)o(els:)25 b(DEFERRED,)20 b(IMMEDIA)-9 b(TE)19 b(or)h(EXCLUSIVE.)0 4232 y(As)30 b(the)g FJ(sqlite3)f FN(module)f(needs)h(to)h(k)o(eep)f (track)g(of)h(the)f(transaction)g(state,)j(you)d(should)g(not)g(use)h FJ(OR)49 b(ROLLBACK)29 b FN(or)g FJ(ON)0 4332 y(CONFLICT)48 b(ROLLBACK)18 b FN(in)g(your)f(SQL.)i(Instead,)f(catch)g(the)g FJ(IntegrityError)e FN(and)i(call)h(the)f FJ(rollback)g FN(method)e(of)j(the)0 4432 y(connection)f(yourself.)0 4717 y Fv(13.13.6)101 b(Using)28 b(p)m(ysqlite)h(ef\002ciently)0 4920 y FI(Using)23 b(shor)s(tcut)g(methods)0 5122 y FN(Using)30 b(the)f(nonstandard)f FJ(execute)p FN(,)j FJ(executemany)d FN(and)h FJ(executescript)f FN(methods)h(of)g(the)h FJ(Connection)e FN(object,)0 5222 y(your)18 b(code)g(can)h(be)g(written)f(more)g (concisely)h(because)f(you)g(don')o(t)f(ha)n(v)o(e)i(to)g(create)f(the) h(\(often)f(super\003uous\))f FJ(Cursor)i FN(objects)f(e)o(x-)0 5322 y(plicitly)-5 b(.)24 b(Instead,)19 b(the)h FJ(Cursor)g FN(objects)g(are)g(created)f(implicitly)g(and)h(these)g(shortcut)f (methods)g(return)g(the)h(cursor)f(objects.)24 b(This)p 0 5549 3901 4 v 0 5649 a FI(392)2649 b(Chapter)23 b(13.)52 b(Data)23 b(P)l(ersistence)p eop end %%Page: 393 405 TeXDict begin 393 404 bop 0 83 a FN(w)o(ay)-5 b(,)24 b(you)e(can)i(e)o(x)o(ecute)e(a)i(SELECT)g(statement)f(and)g(iterate)h (o)o(v)o(er)e(it)i(directly)f(using)g(only)g(a)h(single)f(call)h(on)f (the)h FJ(Connection)0 183 y FN(object.)p 241 371 23 4 v 263 371 a Fy(methods.p)o(y)0 639 y FI(Accessing)e(columns)i(b)n(y)f (name)g(instead)h(of)f(b)n(y)h(inde)n(x)0 842 y FN(One)c(useful)g (feature)f(of)h(the)g FJ(sqlite3)g FN(module)e(is)j(the)g(b)n(uiltin)f FJ(sqlite3.Row)e FN(class)j(designed)e(to)i(be)f(used)g(as)h(a)f(ro)n (w)g(f)o(actory)-5 b(.)0 989 y(Ro)n(ws)21 b(wrapped)d(with)j(this)f (class)i(can)e(be)g(accessed)g(both)f(by)h(inde)o(x)f(\(lik)o(e)h (tuples\))g(and)g(case-insensiti)n(v)o(ely)e(by)i(name:)236 1177 y FA(import)44 b(sqlite3)236 1360 y(con)h(=)f (sqlite3.connect\("mydb"\))236 1451 y(con.row_factory)f(=)h (sqlite3.Row)236 1634 y(cur)h(=)f(con.cursor\(\))236 1725 y(cur.execute\("select)e(name_last,)h(age)h(from)g(people"\))236 1817 y(for)h(row)f(in)g(cur:)416 1908 y(assert)f(row[0])h(==)h (row["name_last"])416 1999 y(assert)e(row["name_last"])g(==)h (row["nAmE_lAsT"])416 2091 y(assert)f(row[1])h(==)h(row["age"])416 2182 y(assert)e(row[1])h(==)h(row["AgE"])p 0 5549 3901 4 v 0 5649 a FI(13.13.)52 b FJ(sqlite3)22 b FI(\227)h(DB-API)h(2.0)g (interf)n(ace)f(f)n(or)f(SQLite)i(databases)1447 b(393)p eop end %%Page: 394 406 TeXDict begin 394 405 bop 0 5549 3901 4 v 0 5649 a FI(394)p eop end %%Page: 395 407 TeXDict begin 395 406 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3245 427 y FG(FOUR)n(TEEN)p 0 515 V 552 978 a FT(Gener)s(ic)57 b(Oper)n(ating)f(System)i(Ser)6 b(vices)0 1468 y FN(The)19 b(modules)f(described)f(in)i(this)h(chapter)e(pro)o(vide)f(interf)o (aces)h(to)h(operating)e(system)i(features)g(that)g(are)g(a)n(v)n (ailable)f(on)h(\(almost\))f(all)0 1568 y(operating)h(systems,)j(such)f (as)g(\002les)i(and)d(a)i(clock.)27 b(The)20 b(interf)o(aces)h(are)g (generally)f(modeled)f(after)i(the)i(U)t FH(N)t(I)t(X)h FN(or)d(C)h(interf)o(aces,)f(b)n(ut)0 1667 y(the)o(y)e(are)i(a)n(v)n (ailable)e(on)h(most)g(other)g(systems)g(as)h(well.)26 b(Here')-5 b(s)20 b(an)g(o)o(v)o(ervie)n(w:)50 1810 y FD(os)697 b FN(Miscellaneous)19 b(operating)g(system)h(interf)o(aces.) 50 1910 y FD(time)597 b FN(T)m(ime)20 b(access)h(and)e(con)m(v)o (ersions.)50 2010 y FD(optparse)397 b FN(More)19 b(con)m(v)o(enient,)f (\003e)o(xible,)h(and)h(po)n(werful)e(command-line)f(parsing)j(library) -5 b(.)50 2109 y FD(getopt)497 b FN(Portable)19 b(parser)h(for)f (command)g(line)h(options;)f(support)g(both)g(short)h(and)g(long)f (option)g(names.)50 2209 y FD(logging)447 b FN(Logging)18 b(module)h(for)g(Python)g(based)h(on)g(PEP)h(282.)50 2309 y FD(getpass)447 b FN(Portable)19 b(reading)g(of)h(passw)o(ords)g (and)f(retrie)n(v)n(al)h(of)g(the)g(userid.)50 2408 y FD(curses)497 b FN(An)20 b(interf)o(ace)f(to)i(the)f(curses)g(library) -5 b(,)19 b(pro)o(viding)e(portable)i(terminal)g(handling.)50 2508 y FD(curses.textpad)97 b FN(Emacs-lik)o(e)19 b(input)h(editing)f (in)h(a)h(curses)f(windo)n(w)-5 b(.)50 2607 y FD(curses.wrapper)97 b FN(T)-6 b(erminal)19 b(con\002guration)f(wrapper)g(for)i(curses)g (programs.)50 2707 y FD(curses.ascii)197 b FN(Constants)20 b(and)g(set-membership)e(functions)h(for)i FH(A)t(S)t(C)t(I)t(I)j FN(characters.)50 2807 y FD(curses.panel)197 b FN(A)21 b(panel)e(stack)h(e)o(xtension)f(that)h(adds)g(depth)g(to)g(curses)g (windo)n(ws.)50 2906 y FD(platform)397 b FN(Retrie)n(v)o(es)20 b(as)h(much)e(platform)g(identifying)f(data)i(as)h(possible.)50 3006 y FD(errno)547 b FN(Standard)19 b(errno)g(system)h(symbols.)50 3106 y FD(ctypes)497 b FN(A)21 b(foreign)d(function)h(library)g(for)g (Python.)0 3409 y FE(14.1)121 b Fx(os)33 b FE(\227)g(Miscellaneous)g (oper)o(ating)j(system)d(interf)l(aces)0 3642 y FN(This)22 b(module)f(pro)o(vides)f(a)j(more)e(portable)g(w)o(ay)h(of)g(using)f (operating)f(system)i(dependent)e(functionality)g(than)i(importing)e(a) i(oper)n(-)0 3742 y(ating)e(system)g(dependent)e(b)n(uilt-in)i(module)f (lik)o(e)h FJ(posix)g FN(or)g FJ(nt)p FN(.)0 3888 y(This)26 b(module)e(searches)h(for)g(an)g(operating)f(system)i(dependent)d(b)n (uilt-in)i(module)f(lik)o(e)i FJ(mac)f FN(or)h FJ(posix)f FN(and)g(e)o(xports)f(the)h(same)0 3988 y(functions)17 b(and)h(data)h(as)g(found)e(there.)24 b(The)19 b(design)f(of)g(all)h (Python')-5 b(s)18 b(b)n(uilt-in)h(operating)d(system)j(dependent)e (modules)g(is)j(such)e(that)0 4088 y(as)24 b(long)e(as)h(the)g(same)g (functionality)e(is)i(a)n(v)n(ailable,)g(it)h(uses)f(the)g(same)g (interf)o(ace;)g(for)f(e)o(xample,)g(the)h(function)e FJ(os.stat\()p FK(path)p FJ(\))0 4187 y FN(returns)e(stat)i (information)d(about)h FK(path)h FN(in)g(the)g(same)h(format)e(\(which) g(happens)g(to)h(ha)n(v)o(e)g(originated)e(with)j(the)f(POSIX)g(interf) o(ace\).)0 4334 y(Extensions)k(peculiar)h(to)g(a)h(particular)e (operating)g(system)i(are)f(also)h(a)n(v)n(ailable)f(through)e(the)i FJ(os)h FN(module,)f(b)n(ut)h(using)e(them)h(is)i(of)0 4434 y(course)19 b(a)i(threat)f(to)g(portability!)0 4581 y(Note)25 b(that)h(after)f(the)g(\002rst)i(time)e FJ(os)h FN(is)g(imported,)f(there)g(is)h FK(no)f FN(performance)e(penalty)h(in) i(using)f(functions)f(from)g FJ(os)i FN(instead)f(of)0 4680 y(directly)19 b(from)h(the)g(operating)e(system)i(dependent)e(b)n (uilt-in)i(module,)f(so)h(there)g(should)f(be)h FK(no)g FN(reason)f(not)h(to)h(use)f FJ(os)p FN(!)0 4827 y FL(exception)f FD(error)208 4927 y FN(This)k(e)o(xception)e(is)j(raised)e(when)h(a)g (function)e(returns)h(a)i(system-related)e(error)f(\(not)i(for)f(ille)o (gal)g(ar)o(gument)f(types)i(or)f(other)208 5026 y(incidental)i (errors\).)39 b(This)26 b(is)g(also)g(kno)n(wn)e(as)i(the)g(b)n (uilt-in)e(e)o(xception)g FJ(OSError)p FN(.)40 b(The)25 b(accompan)o(ying)d(v)n(alue)j(is)h(a)g(pair)208 5126 y(containing)15 b(the)j(numeric)e(error)h(code)g(from)g FJ(errno)g FN(and)g(the)h(corresponding)c(string,)k(as)g(w)o(ould)f(be) h(printed)e(by)h(the)h(C)h(func-)208 5226 y(tion)j FJ(perror\(\))p FN(.)30 b(See)22 b(the)h(module)e FJ(errno)p FN(,)h(which)g(contains)f (names)h(for)g(the)g(error)f(codes)h(de\002ned)f(by)h(the)g(underlying) 208 5325 y(operating)c(system.)p 0 5549 3901 4 v 3762 5649 a FI(395)p eop end %%Page: 396 408 TeXDict begin 396 407 bop 208 83 a FN(When)29 b(e)o(xceptions)e(are)j (classes,)i(this)e(e)o(xception)e(carries)h(tw)o(o)g(attrib)n(utes,)j FJ(errno)d FN(and)f FJ(strerror)p FN(.)52 b(The)29 b(\002rst)h(holds) 208 183 y(the)23 b(v)n(alue)f(of)h(the)g(C)i FJ(errno)d FN(v)n(ariable,)h(and)g(the)g(latter)g(holds)g(the)g(corresponding)d (error)i(message)h(from)f FJ(strerror\(\))p FN(.)208 282 y(F)o(or)i(e)o(xceptions)f(that)h(in)m(v)n(olv)o(e)f(a)i(\002le)g (system)g(path)f(\(such)g(as)h FJ(chdir\(\))f FN(or)g FJ(unlink\(\))p FN(\),)g(the)h(e)o(xception)e(instance)h(will)208 382 y(contain)19 b(a)h(third)g(attrib)n(ute,)f FJ(filename)p FN(,)g(which)h(is)h(the)f(\002le)h(name)f(passed)g(to)g(the)h (function.)0 529 y FD(name)208 628 y FN(The)31 b(name)h(of)g(the)g (operating)e(system)i(dependent)e(module)h(imported.)59 b(The)31 b(follo)n(wing)g(names)g(ha)n(v)o(e)h(currently)e(been)208 728 y(re)o(gistered:)23 b FJ('posix')p FN(,)d FJ('nt')p FN(,)f FJ('mac')p FN(,)h FJ('os2')p FN(,)g FJ('ce')p FN(,)f FJ('java')p FN(,)h FJ('riscos')p FN(.)0 875 y FD(path)208 975 y FN(The)d(corresponding)d(operating)h(system)j (dependent)d(standard)h(module)h(for)f(pathname)g(operations,)g(such)i (as)g FJ(posixpath)208 1074 y FN(or)30 b FJ(macpath)p FN(.)55 b(Thus,)33 b(gi)n(v)o(en)c(the)i(proper)d(imports,)33 b FJ(os.path.split\()p FK(\002le)p FJ(\))27 b FN(is)32 b(equi)n(v)n(alent)d(to)i(b)n(ut)f(more)g(portable)208 1174 y(than)23 b FJ(posixpath.split\()p FK(\002le)p FJ(\))p FN(.)32 b(Note)24 b(that)g(this)g(is)h(also)f(an)f(importable)f (module:)31 b(it)25 b(may)e(be)h(imported)e(directly)h(as)208 1273 y FJ(os.path)p FN(.)0 1558 y Fv(14.1.1)101 b(Process)28 b(P)l(ar)o(ameters)0 1761 y FN(These)20 b(functions)f(and)g(data)h (items)h(pro)o(vide)d(information)g(and)i(operate)f(on)h(the)g(current) f(process)g(and)h(user)-5 b(.)0 1908 y FD(environ)208 2008 y FN(A)21 b(mapping)f(object)g(representing)f(the)j(string)e(en)m (vironment.)25 b(F)o(or)c(e)o(xample,)f FJ(environ['HOME'])f FN(is)j(the)f(pathname)f(of)208 2107 y(your)e(home)i(directory)e(\(on)i (some)g(platforms\),)e(and)i(is)h(equi)n(v)n(alent)d(to)j FJ(getenv\("HOME"\))d FN(in)i(C.)208 2240 y(This)25 b(mapping)f(is)j (captured)d(the)h(\002rst)i(time)f(the)f FJ(os)h FN(module)e(is)j (imported,)e(typically)g(during)f(Python)g(startup)h(as)i(part)e(of)208 2340 y(processing)16 b(`)p FO(site)o(.p)n(y)p FN('.)23 b(Changes)18 b(to)g(the)h(en)m(vironment)c(made)i(after)h(this)h(time)f (are)h(not)e(re\003ected)h(in)g FJ(os.environ)p FN(,)g(e)o(xcept)208 2439 y(for)h(changes)g(made)h(by)g(modifying)d FJ(os.environ)i FN(directly)-5 b(.)208 2572 y(If)30 b(the)g(platform)f(supports)g(the)h FJ(putenv\(\))f FN(function,)i(this)g(mapping)d(may)i(be)g(used)g(to)h (modify)d(the)j(en)m(vironment)c(as)208 2672 y(well)22 b(as)h(query)e(the)h(en)m(vironment.)28 b FJ(putenv\(\))21 b FN(will)i(be)g(called)f(automatically)e(when)i(the)g(mapping)e(is)k (modi\002ed.)29 b FL(Note:)208 2772 y FN(Calling)20 b FJ(putenv\(\))f FN(directly)g(does)h(not)g(change)f FJ(os.environ)p FN(,)g(so)h(it')-5 b(s)22 b(better)e(to)g(modify)f FJ(os.environ)p FN(.)k FL(Note:)i FN(On)208 2871 y(some)d(platforms,)g(including)f (FreeBSD)j(and)e(Mac)h(OS)g(X,)h(setting)e FJ(environ)g FN(may)h(cause)g(memory)e(leaks.)33 b(Refer)23 b(to)g(the)208 2971 y(system)d(documentation)d(for)j FJ(putenv\(\))p FN(.)208 3104 y(If)30 b FJ(putenv\(\))f FN(is)i(not)f(pro)o(vided,)g(a) h(modi\002ed)e(cop)o(y)g(of)h(this)h(mapping)e(may)g(be)i(passed)f(to)g (the)g(appropriate)e(process-)208 3203 y(creation)19 b(functions)f(to)j(cause)f(child)g(processes)g(to)g(use)g(a)h (modi\002ed)e(en)m(vironment.)208 3336 y(If)g(the)h(platform)e (supports)g(the)i FJ(unsetenv\(\))e FN(function,)g(you)g(can)i(delete)f (items)h(in)g(this)g(mapping)e(to)h(unset)h(en)m(vironment)208 3436 y(v)n(ariables.)k FJ(unsetenv\(\))19 b FN(will)h(be)h(called)f (automatically)e(when)i(an)g(item)g(is)i(deleted)d(from)g FJ(os.environ)p FN(.)0 3583 y FD(chdir)p FJ(\()p FK(path)p FJ(\))0 3682 y FD(fchdir)p FJ(\()p FK(fd)r FJ(\))0 3782 y FD(getcwd)p FJ(\(\))208 3881 y FN(These)h(functions)e(are)i (described)f(in)i(\223Files)g(and)e(Directories\224)h(\(section)f (14.1.4\).)0 4028 y FD(ctermid)p FJ(\(\))208 4128 y FN(Return)g(the)i (\002lename)e(corresponding)e(to)j(the)g(controlling)f(terminal)g(of)h (the)g(process.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 4275 y FD(getegid)p FJ(\(\))208 4374 y FN(Return)16 b(the)i(ef)n(fecti)n(v)o(e)e(group)f(id)j(of)f(the) g(current)f(process.)23 b(This)18 b(corresponds)d(to)i(the)h(`set)f (id')g(bit)h(on)f(the)g(\002le)h(being)e(e)o(x)o(ecuted)208 4474 y(in)k(the)g(current)f(process.)24 b(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 4621 y FD(geteuid)p FJ(\(\))208 4721 y FN(Return)19 b(the)i(current)d(process')i(ef)n(fecti)n(v)o(e)f (user)h(id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 4867 y FD(getgid)p FJ(\(\))208 4967 y FN(Return)19 b(the)i(real)f(group)e(id)i(of)g(the)h(current)d(process.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 5114 y FD(getgroups)p FJ(\(\))208 5214 y FN(Return)19 b(list)j(of)d(supplemental)g(group)f(ids)j(associated)f(with)g(the)h (current)e(process.)24 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 5360 y FD(getlogin)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(396)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 397 409 TeXDict begin 397 408 bop 208 83 a FN(Return)48 b(the)h(name)g(of)g (the)g(user)g(logged)f(in)h(on)g(the)g(controlling)e(terminal)h(of)h (the)g(process.)111 b(F)o(or)49 b(most)g(pur)n(-)208 183 y(poses,)g(it)c(is)g(more)e(useful)h(to)g(use)g(the)g(en)m (vironment)d(v)n(ariable)i(LOGN)m(AME)g(to)h(\002nd)g(out)g(who)f(the)h (user)g(is,)51 b(or)208 282 y FJ(pwd.getpwuid\(os.getuid\(\)\)[0])23 b FN(to)29 b(get)g(the)f(login)g(name)g(of)g(the)h(currently)e(ef)n (fecti)n(v)o(e)g(user)h(ID.)h(A)-6 b(v)n(ailabil-)208 382 y(ity:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 529 y FD(getpgid)p FJ(\()p FK(pid)r FJ(\))208 628 y FN(Return)c(the)h(process)f(group)g (id)h(of)f(the)h(process)g(with)g(process)f(id)h FK(pid)r FN(.)36 b(If)24 b FK(pid)i FN(is)f(0,)g(the)f(process)f(group)f(id)i (of)g(the)g(current)208 728 y(process)19 b(is)i(returned.)j(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 875 y FD(getpgrp)p FJ(\(\))208 975 y FN(Return)g(the)i(id)f(of)g(the)g(current)f(process)h(group.)j(A) -6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 1121 y FD(getpid)p FJ(\(\))208 1221 y FN(Return)19 b(the)i(current)d (process)i(id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)0 1368 y FD(getppid)p FJ(\(\))208 1468 y FN(Return)e(the)i(parent')-5 b(s)19 b(process)h(id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 1614 y FD(getuid)p FJ(\(\))208 1714 y FN(Return)19 b(the)i(current)d (process')i(user)g(id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 1861 y FD(getenv)p FJ(\()p FK(varname)p FC([)p FK(,)18 b(value)12 b FC(])p FJ(\))208 1961 y FN(Return)19 b(the)i(v)n(alue)f(of)g(the)g(en)m(vironment)d(v)n (ariable)j FK(varname)f FN(if)i(it)g(e)o(xists,)f(or)g FK(value)g FN(if)h(it)g(doesn')o(t.)j FK(value)c FN(def)o(aults)f(to)i FJ(None)p FN(.)208 2060 y(A)-6 b(v)n(ailability:)24 b(most)c(\003a)n(v) n(ors)g(of)i(U)t FH(N)t(I)t(X)r FN(,)f(W)m(indo)n(ws.)0 2207 y FD(putenv)p FJ(\()p FK(varname)o(,)d(value)p FJ(\))208 2307 y FN(Set)23 b(the)g(en)m(vironment)e(v)n(ariable)h(named)g FK(varname)g FN(to)h(the)g(string)g FK(value)p FN(.)33 b(Such)23 b(changes)f(to)h(the)g(en)m(vironment)d(af)n(fect)j(sub-)208 2406 y(processes)j(started)i(with)f FJ(os.system\(\))p FN(,)g FJ(popen\(\))g FN(or)f FJ(fork\(\))h FN(and)g FJ(execv\(\))p FN(.)45 b(A)-6 b(v)n(ailability:)38 b(most)27 b(\003a)n(v)n(ors)h(of)210 2506 y(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)208 2639 y FL(Note:)39 b FN(On)28 b(some)g(platforms,)g(including)e(FreeBSD)j(and)e(Mac)h(OS)g(X,)g (setting)g FJ(environ)f FN(may)h(cause)g(memory)e(leaks.)208 2738 y(Refer)20 b(to)g(the)g(system)h(documentation)c(for)i(puten)m(v) -5 b(.)208 2871 y(When)25 b FJ(putenv\(\))g FN(is)h(supported,)f (assignments)g(to)h(items)g(in)g FJ(os.environ)e FN(are)i (automatically)e(translated)h(into)g(cor)n(-)208 2971 y(responding)h(calls)j(to)g FJ(putenv\(\))p FN(;)k(ho)n(we)n(v)o(er)m (,)28 b(calls)i(to)f FJ(putenv\(\))e FN(don')o(t)h(update)f FJ(os.environ)p FN(,)j(so)f(it)g(is)h(actually)208 3070 y(preferable)18 b(to)i(assign)g(to)h(items)f(of)g FJ(os.environ)p FN(.)0 3217 y FD(setegid)p FJ(\()p FK(e)m(gid)r FJ(\))208 3317 y FN(Set)g(the)h(current)d(process')-5 b(s)21 b(ef)n(fecti)n(v)o (e)d(group)h(id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 3464 y FD(seteuid)p FJ(\()p FK(euid)r FJ(\))208 3563 y FN(Set)20 b(the)h(current)d(process')-5 b(s)21 b(ef)n(fecti)n(v)o(e)d(user)i(id.)26 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 3710 y FD(setgid)p FJ(\()p FK(gid)r FJ(\))208 3810 y FN(Set)20 b(the)h(current)d(process')i(group) e(id.)25 b(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 3957 y FD(setgroups)p FJ(\()p FK(gr)l(oups)p FJ(\))208 4056 y FN(Set)20 b(the)f(list)i(of)e(supplemental)f(group)f(ids)j (associated)f(with)h(the)f(current)g(process)g(to)g FK(gr)l(oups)p FN(.)24 b FK(gr)l(oups)19 b FN(must)h(be)f(a)h(sequence,)208 4156 y(and)15 b(each)h(element)f(must)i(be)f(an)g(inte)o(ger)f (identifying)f(a)i(group.)22 b(This)16 b(operation)f(is)i(typical)e(a)n (v)n(ailable)h(only)f(to)i(the)f(superuser)-5 b(.)208 4256 y(A)f(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 4403 y FD(setpgrp)p FJ(\(\))208 4502 y FN(Calls)i(the)g(system)g(call)g FJ(setpgrp\(\))e FN(or)h FJ(setpgrp\(0,)48 b(0\))21 b FN(depending)d(on)i(which)g(v)o (ersion)f(is)j(implemented)c(\(if)j(an)o(y\).)208 4602 y(See)f(the)i(U)t FH(N)t(I)t(X)i FN(manual)19 b(for)g(the)i(semantics.) j(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 4749 y FD(setpgid)p FJ(\()p FK(pid,)18 b(pgrp)p FJ(\))208 4848 y FN(Calls)26 b(the)e(system)h(call)h FJ(setpgid\(\))d FN(to)i(set)h(the)f(process)f(group)f(id)i(of)f(the)h(process)g(with)g (id)g FK(pid)h FN(to)f(the)g(process)f(group)208 4948 y(with)c(id)g FK(pgrp)p FN(.)25 b(See)20 b(the)i(U)t FH(N)t(I)t(X)i FN(manual)19 b(for)g(the)i(semantics.)j(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 5095 y FD(setreuid)p FJ(\()p FK(ruid,)18 b(euid)r FJ(\))208 5194 y FN(Set)i(the)h(current)d(process')-5 b(s)21 b(real)f(and)f(ef)n (fecti)n(v)o(e)g(user)h(ids.)26 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 5341 y FD(setregid)p FJ(\()p FK(r)m(gid,)18 b(e)m(gid)r FJ(\))p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o(ating) g(system)e(interf)n(aces)1736 b(397)p eop end %%Page: 398 410 TeXDict begin 398 409 bop 208 83 a FN(Set)20 b(the)h(current)d (process')-5 b(s)21 b(real)f(and)f(ef)n(fecti)n(v)o(e)g(group)g(ids.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 230 y FD(getsid)p FJ(\()p FK(pid)r FJ(\))208 330 y FN(Calls)19 b(the)g(system)g(call)g FJ(getsid\(\))p FN(.)k(See)c(the)i(U)t FH(N)t(I)t(X)g FN(manual)d(for)f(the)i(semantics.)24 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)50 b(Ne)n(w)19 b(in)g(v)o(ersion)208 429 y(2.4.)0 576 y FD(setsid)p FJ(\(\))208 676 y FN(Calls)i(the)f(system)h(call)f FJ(setsid\(\))p FN(.)k(See)d(the)h(U)t FH(N)t(I)t(X)h FN(manual)c(for)h(the)g(semantics.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 823 y FD(setuid)p FJ(\()p FK(uid)r FJ(\))208 922 y FN(Set)20 b(the)h(current)d(process')i(user)g (id.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 1069 y FD(strerror)p FJ(\()p FK(code)p FJ(\))208 1169 y FN(Return)19 b(the)i(error)e(message)h(corresponding)c(to)21 b(the)f(error)f(code)g(in)i FK(code)p FN(.)j(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)0 1316 y FD(umask)p FJ(\()p FK(mask)q FJ(\))208 1415 y FN(Set)f(the)h(current) d(numeric)h(umask)h(and)f(returns)h(the)g(pre)n(vious)f(umask.)24 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)0 1562 y FD(uname)p FJ(\(\))208 1662 y FN(Return)g(a)i(5-tuple)e(containing)f(information)g(identifying)g (the)i(current)f(operating)g(system.)31 b(The)22 b(tuple)g(contains)f (5)i(strings:)208 1761 y FJ(\()p FK(sysname)p FJ(,)48 b FK(nodename)p FJ(,)f FK(r)m(elease)p FJ(,)i FK(ver)o(sion)p FJ(,)h FK(mac)o(hine)p FJ(\))p FN(.)55 b(Some)31 b(systems)g(truncate)f (the)h(nodename)e(to)i(8)g(charac-)208 1861 y(ters)26 b(or)f(to)h(the)g(leading)f(component;)h(a)g(better)g(w)o(ay)g(to)g (get)f(the)h(hostname)f(is)i FJ(socket.gethostname\(\))49 b FN(or)25 b(e)n(v)o(en)208 1961 y FJ (socket.gethostbyaddr\(socket.getho)o(stnam)o(e\(\)\))p FN(.)19 b(A)-6 b(v)n(ailability:)24 b(recent)c(\003a)n(v)n(ors)g(of)i (U)t FH(N)t(I)t(X)r FN(.)0 2107 y FD(unsetenv)p FJ(\()p FK(varname)p FJ(\))208 2207 y FN(Unset)f(\(delete\))g(the)g(en)m (vironment)e(v)n(ariable)h(named)g FK(varname)p FN(.)28 b(Such)21 b(changes)f(to)i(the)f(en)m(vironment)e(af)n(fect)i (subprocesses)208 2307 y(started)g(with)h FJ(os.system\(\))p FN(,)e FJ(popen\(\))g FN(or)i FJ(fork\(\))f FN(and)g FJ(execv\(\))p FN(.)28 b(A)-6 b(v)n(ailability:)27 b(most)21 b(\003a)n(v)n(ors)h(of)h(U)t FH(N)t(I)t(X)r FN(,)g(W)m(in-)208 2406 y(do)n(ws.)208 2536 y(When)f FJ(unsetenv\(\))e FN(is)k(supported,) c(deletion)h(of)h(items)h(in)f FJ(os.environ)f FN(is)i(automatically)e (translated)g(into)h(a)h(corre-)208 2636 y(sponding)d(call)i(to)g FJ(unsetenv\(\))p FN(;)g(ho)n(we)n(v)o(er)m(,)e(calls)i(to)g FJ(unsetenv\(\))f FN(don')o(t)f(update)h FJ(os.environ)p FN(,)g(so)i(it)f(is)h(actually)208 2736 y(preferable)18 b(to)i(delete)g(items)h(of)f FJ(os.environ)p FN(.)0 3018 y Fv(14.1.2)101 b(File)28 b(Object)f(Creation)0 3221 y FN(These)20 b(functions)f(create)h(ne)n(w)g(\002le)h(objects.)0 3368 y FD(fdopen)p FJ(\()p FK(fd)r FC([)p FK(,)e(mode)p FC([)p FK(,)g(b)n(ufsize)12 b FC(])g(])p FJ(\))208 3468 y FN(Return)23 b(an)i(open)e(\002le)i(object)f(connected)e(to)j(the)f (\002le)h(descriptor)e FK(fd)r FN(.)38 b(The)24 b FK(mode)f FN(and)h FK(b)n(ufsize)h FN(ar)o(guments)d(ha)n(v)o(e)i(the)g(same)208 3567 y(meaning)k(as)j(the)g(corresponding)c(ar)o(guments)h(to)i(the)h (b)n(uilt-in)e FJ(open\(\))h FN(function.)54 b(A)-6 b(v)n(ailability:) 44 b(Macintosh,)34 b(U)t FH(N)t(I)t(X)r FN(,)208 3667 y(W)m(indo)n(ws.)208 3797 y(Changed)21 b(in)i(v)o(ersion)f(2.3:)g(When) h(speci\002ed,)g(the)g FK(mode)f FN(ar)o(gument)f(must)i(no)n(w)f (start)h(with)h(one)e(of)h(the)f(letters)i(`)p FJ(r)p FN(',)f(`)p FJ(w)p FN(',)g(or)208 3897 y(`)p FJ(a)p FN(',)f(otherwise)f (a)i FJ(ValueError)e FN(is)i(raised.)95 b(Changed)21 b(in)i(v)o(ersion)e(2.5:)g(On)k(U)t FH(N)t(I)t(X)r FN(,)e(when)f(the)g FK(mode)g FN(ar)o(gument)e(starts)208 3996 y(with)i(`)p FJ(a)p FN(',)g(the)h FK(O)p 717 3996 25 4 v 29 w(APPEND)g FN(\003ag)f(is)h(set)g(on)f(the)h(\002le)g(descriptor)d(\(which)i(the)g FJ(fdopen\(\))g FN(implementation)e(already)h(does)208 4096 y(on)e(most)i(platforms\).)0 4243 y FD(popen)p FJ(\()p FK(command)r FC([)p FK(,)c(mode)p FC([)p FK(,)i(b)n(ufsize)12 b FC(])g(])p FJ(\))208 4343 y FN(Open)j(a)i(pipe)e(to)i(or)f(from)f FK(command)r FN(.)22 b(The)16 b(return)f(v)n(alue)g(is)i(an)g(open)e (\002le)i(object)e(connected)g(to)h(the)g(pipe,)g(which)g(can)g(be)g (read)208 4442 y(or)j(written)h(depending)d(on)j(whether)f FK(mode)g FN(is)i FJ('r')f FN(\(def)o(ault\))f(or)g FJ('w')p FN(.)25 b(The)20 b FK(b)n(ufsize)g FN(ar)o(gument)e(has)i(the)g(same)g (meaning)f(as)208 4542 y(the)k(corresponding)c(ar)o(gument)i(to)i(the)g (b)n(uilt-in)g FJ(open\(\))f FN(function.)32 b(The)23 b(e)o(xit)g(status)g(of)g(the)g(command)e(\(encoded)g(in)j(the)208 4641 y(format)18 b(speci\002ed)i(for)g FJ(wait\(\))p FN(\))f(is)i(a)n(v)n(ailable)e(as)i(the)f(return)f(v)n(alue)g(of)h(the) g FJ(close\(\))f FN(method)g(of)h(the)g(\002le)g(object,)g(e)o(xcept) 208 4741 y(that)g(when)f(the)h(e)o(xit)g(status)h(is)g(zero)f (\(termination)e(without)h(errors\),)g FJ(None)h FN(is)h(returned.)i(A) -6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)208 4841 y(W)m(indo)n(ws.)208 4971 y(The)i FJ(subprocess)g FN(module)f(pro)o(vides)g(more)h(po)n(werful)f(f)o(acilities)j(for)e (spa)o(wning)f(ne)n(w)i(processes)f(and)h(retrie)n(ving)e(their)208 5071 y(results;)e(using)g(that)g(module)f(is)i(preferable)d(to)j(using) e(this)i(function.)208 5201 y(Changed)16 b(in)i(v)o(ersion)e(2.0:)h (This)h(function)e(w)o(ork)o(ed)h(unreliably)f(under)g(W)m(indo)n(ws)h (in)h(earlier)g(v)o(ersions)e(of)i(Python.)23 b(This)18 b(w)o(as)208 5300 y(due)g(to)h(the)h(use)f(of)g(the)g FJ(_popen\(\))f FN(function)g(from)g(the)h(libraries)g(pro)o(vided)d (with)k(W)m(indo)n(ws.)k(Ne)n(wer)19 b(v)o(ersions)f(of)h(Python)208 5400 y(do)g(not)h(use)h(the)f(brok)o(en)e(implementation)g(from)h(the)i (W)m(indo)n(ws)e(libraries.)p 0 5549 3901 4 v 0 5649 a FI(398)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 399 411 TeXDict begin 399 410 bop 0 83 a FD(tmpfile)p FJ(\(\))208 183 y FN(Return)26 b(a)h(ne)n(w)f(\002le)i(object)e(opened)f(in)i (update)e(mode)h(\(`)p FJ(w+b)p FN('\).)43 b(The)26 b(\002le)i(has)f (no)f(directory)f(entries)i(associated)f(with)h(it)208 282 y(and)21 b(will)h(be)g(automatically)e(deleted)h(once)h(there)f (are)h(no)f(\002le)h(descriptors)f(for)g(the)h(\002le.)30 b(A)-6 b(v)n(ailability:)28 b(Macintosh,)23 b(U)t FH(N)t(I)t(X)r FN(,)208 382 y(W)m(indo)n(ws.)0 529 y(There)17 b(are)g(a)h(number)e(of) h(dif)n(ferent)f FJ(popen)1297 544 y(*)1347 529 y(\(\))g FN(functions)h(that)g(pro)o(vide)f(slightly)h(dif)n(ferent)f(w)o(ays)i (to)f(create)h(subprocesses.)23 b(Note)0 628 y(that)j(the)f FJ(subprocess)g FN(module)f(is)j(easier)e(to)h(use)g(and)f(more)g(po)n (werful;)h(consider)f(using)g(that)h(module)e(before)g(writing)h(code)0 728 y(using)20 b(the)g(lo)n(wer)n(-le)n(v)o(el)f FJ(popen)965 743 y(*)1015 728 y(\(\))g FN(functions.)0 875 y(F)o(or)28 b(each)h(of)f(the)h FJ(popen)804 890 y(*)854 875 y(\(\))f FN(v)n(ariants,)i(if)f FK(b)n(ufsize)g FN(is)h(speci\002ed,)g(it)f (speci\002es)h(the)e(b)n(uf)n(fer)g(size)h(for)f(the)h(I/O)g(pipes.)50 b FK(mode)p FN(,)30 b(if)0 975 y(pro)o(vided,)16 b(should)i(be)h(the)g (string)g FJ('b')g FN(or)f FJ('t')p FN(;)i(on)e(W)m(indo)n(ws)h(this)g (is)h(needed)e(to)h(determine)e(whether)h(the)h(\002le)h(objects)f (should)f(be)0 1074 y(opened)h(in)h(binary)f(or)h(te)o(xt)g(mode.)k (The)c(def)o(ault)f(v)n(alue)g(for)h FK(mode)g FN(is)h FJ('t')p FN(.)0 1221 y(Also,)f(for)f(each)h(of)f(these)h(v)n(ariants,)f (on)j(U)t FH(N)t(I)t(X)r FN(,)e FK(cmd)i FN(may)e(be)f(a)i(sequence,)d (in)i(which)f(case)i(ar)o(guments)c(will)k(be)f(passed)f(directly)g(to) 0 1321 y(the)24 b(program)d(without)i(shell)h(interv)o(ention)d(\(as)j (with)f FJ(os.spawnv\(\))p FN(\).)34 b(If)23 b FK(cmd)j FN(is)e(a)g(string)f(it)i(will)f(be)g(passed)f(to)h(the)f(shell)h(\(as) 0 1420 y(with)c FJ(os.system\(\))p FN(\).)0 1567 y(These)25 b(methods)f(do)g(not)h(mak)o(e)f(it)i(possible)e(to)h(retrie)n(v)o(e)f (the)h(e)o(xit)g(status)g(from)f(the)h(child)f(processes.)39 b(The)25 b(only)f(w)o(ay)h(to)g(control)0 1667 y(the)g(input)f(and)g (output)g(streams)g(and)h(also)g(retrie)n(v)o(e)e(the)i(return)f(codes) g(is)i(to)f(use)g(the)f FJ(Popen3)h FN(and)f FJ(Popen4)g FN(classes)i(from)e(the)0 1766 y FJ(popen2)c FN(module;)f(these)h(are)g (only)f(a)n(v)n(ailable)h(on)i(U)t FH(N)t(I)t(X)r FN(.)0 1913 y(F)o(or)31 b(a)g(discussion)g(of)f(possible)h(deadlock)e (conditions)h(related)g(to)h(the)g(use)h(of)e(these)h(functions,)h(see) g(\223Flo)n(w)f(Control)f(Issues\224)0 2013 y(\(section)20 b(17.4.2\).)0 2160 y FD(popen2)p FJ(\()p FK(cmd)r FC([)p FK(,)f(mode)p FC([)p FK(,)g(b)n(ufsize)12 b FC(])g(])p FJ(\))208 2259 y FN(Ex)o(ecutes)21 b FK(cmd)j FN(as)f(a)g(sub-process.) 29 b(Returns)22 b(the)g(\002le)h(objects)f FJ(\()p FK(c)o(hild)p 2301 2259 25 4 v 29 w(stdin)p FJ(,)49 b FK(c)o(hild)p 2757 2259 V 29 w(stdout)q FJ(\))p FN(.)30 b(A)-6 b(v)n(ailability:)29 b(Macintosh,)210 2359 y(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 2506 y FD(popen3)p FJ(\()p FK(cmd)r FC([)p FK(,)g(mode)p FC([)p FK(,)g(b)n(ufsize)12 b FC(])g(])p FJ(\))208 2606 y FN(Ex)o(ecutes)20 b FK(cmd)k FN(as)e(a)g(sub-process.)27 b(Returns)21 b(the)h(\002le)g(objects)f FJ(\()p FK(c)o(hild)p 2293 2606 V 29 w(stdin)p FJ(,)49 b FK(c)o(hild)p 2749 2606 V 28 w(stdout)q FJ(,)h FK(c)o(hild)p 3248 2606 V 28 w(stderr)r FJ(\))p FN(.)30 b(A)-6 b(v)n(ailabil-)208 2705 y(ity:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.) 50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 2852 y FD(popen4)p FJ(\()p FK(cmd)r FC([)p FK(,)g(mode)p FC([)p FK(,)g(b)n(ufsize)12 b FC(])g(])p FJ(\))208 2952 y FN(Ex)o(ecutes)22 b FK(cmd)k FN(as)e(a)g(sub-process.)33 b(Returns)24 b(the)f(\002le)h(objects)f FJ(\()p FK(c)o(hild)p 2315 2952 V 29 w(stdin)p FJ(,)49 b FK(c)o(hild)p 2771 2952 V 29 w(stdout)p 3004 2952 V 29 w(and)p 3159 2952 V 28 w(stderr)r FJ(\))p FN(.)35 b(A)-6 b(v)n(ailability:)208 3051 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.0.)0 3198 y(\(Note)26 b(that)g FK(c)o(hild)p 538 3198 V 28 w(stdin)p FJ(,)49 b FK(c)o(hild)p 993 3198 V 29 w(stdout)q FJ(,)g(and)g FK(c)o(hild)p 1691 3198 V 29 w(stderr)29 b FN(are)d(named)f(from)g(the)h(point)f(of)g(vie)n(w)h(of)g (the)g(child)f(process,)i(so)0 3298 y FK(c)o(hild)p 171 3298 V 29 w(stdin)20 b FN(is)h(the)f(child')-5 b(s)20 b(standard)f(input.\))0 3445 y(This)h(functionality)d(is)k(also)f(a)n (v)n(ailable)f(in)g(the)h FJ(popen2)f FN(module)f(using)h(functions)f (of)i(the)f(same)h(names,)f(b)n(ut)h(the)f(return)g(v)n(alues)g(of)0 3544 y(those)h(functions)f(ha)n(v)o(e)g(a)i(dif)n(ferent)e(order)-5 b(.)0 3829 y Fv(14.1.3)101 b(File)28 b(Descr)q(iptor)h(Oper)o(ations)0 4032 y FN(These)20 b(functions)f(operate)g(on)h(I/O)g(streams)g (referenced)e(using)i(\002le)h(descriptors.)0 4179 y(File)j (descriptors)f(are)g(small)h(inte)o(gers)f(corresponding)d(to)k(a)f (\002le)i(that)e(has)h(been)f(opened)f(by)h(the)g(current)g(process.)34 b(F)o(or)23 b(e)o(xample,)0 4279 y(standard)15 b(input)h(is)i(usually)e (\002le)h(descriptor)e(0,)j(standard)d(output)g(is)j(1,)f(and)f (standard)g(error)f(is)j(2.)24 b(Further)15 b(\002les)j(opened)d(by)h (a)h(process)0 4378 y(will)i(then)e(be)h(assigned)f(3,)h(4,)g(5,)h(and) e(so)h(forth.)23 b(The)18 b(name)f(\223\002le)h(descriptor\224)f(is)i (slightly)e(decepti)n(v)o(e;)g(on)j(U)t FH(N)t(I)t(X)h FN(platforms,)16 b(sock)o(ets)0 4478 y(and)k(pipes)g(are)g(also)g (referenced)e(by)i(\002le)h(descriptors.)0 4625 y FD(close)p FJ(\()p FK(fd)r FJ(\))208 4724 y FN(Close)f(\002le)h(descriptor)e FK(fd)r FN(.)25 b(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 4857 y FL(Note:)h FN(This)c(function)e(is)i(intended)e(for)g(lo)n(w-le)n(v)o(el)g(I/O)i (and)f(must)g(be)g(applied)g(to)g(a)h(\002le)g(descriptor)e(as)i (returned)d(by)i FJ(open\(\))208 4957 y FN(or)j FJ(pipe\(\))p FN(.)k(T)-7 b(o)21 b(close)f(a)h(\223\002le)f(object\224)g(returned)e (by)i(the)h(b)n(uilt-in)e(function)g FJ(open\(\))g FN(or)h(by)g FJ(popen\(\))g FN(or)g FJ(fdopen\(\))p FN(,)208 5056 y(use)g(its)h FJ(close\(\))f FN(method.)0 5203 y FD(dup)p FJ(\()p FK(fd)r FJ(\))208 5303 y FN(Return)f(a)i(duplicate)e(of)h (\002le)h(descriptor)e FK(fd)r FN(.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g (Miscellaneous)h(oper)o(ating)g(system)e(interf)n(aces)1736 b(399)p eop end %%Page: 400 412 TeXDict begin 400 411 bop 0 83 a FD(dup2)p FJ(\()p FK(fd,)19 b(fd2)p FJ(\))208 183 y FN(Duplicate)f(\002le)j(descriptor)d FK(fd)j FN(to)f FK(fd2)p FN(,)f(closing)g(the)g(latter)h(\002rst)g(if)g (necessary)-5 b(.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 330 y FD(fdatasync)p FJ(\()p FK(fd)r FJ(\))208 429 y FN(F)o(orce)f(write)h(of)g(\002le)h (with)g(\002ledescriptor)d FK(fd)23 b FN(to)d(disk.)25 b(Does)c(not)f(force)f(update)g(of)h(metadata.)k(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 576 y FD(fpathconf)p FJ(\()p FK(fd,)18 b(name)p FJ(\))208 676 y FN(Return)29 b(system)i(con\002guration)c(information)h(rele)n(v) n(ant)h(to)h(an)g(open)f(\002le.)55 b FK(name)30 b FN(speci\002es)g (the)h(con\002guration)c(v)n(alue)i(to)208 775 y(retrie)n(v)o(e;)21 b(it)h(may)g(be)f(a)i(string)e(which)g(is)i(the)f(name)f(of)g(a)h (de\002ned)f(system)h(v)n(alue;)g(these)g(names)f(are)h(speci\002ed)f (in)h(a)g(number)208 875 y(of)f(standards)g(\(POSIX.1,)i(U)t FH(N)t(I)t(X)i FN(95,)f(U)t FH(N)t(I)t(X)g FN(98,)e(and)f(others\).)29 b(Some)21 b(platforms)g(de\002ne)g(additional)g(names)g(as)i(well.)30 b(The)208 975 y(names)23 b(kno)n(wn)f(to)i(the)g(host)g(operating)e (system)i(are)f(gi)n(v)o(en)g(in)h(the)g FJ(pathconf_names)d FN(dictionary)-5 b(.)34 b(F)o(or)23 b(con\002guration)208 1074 y(v)n(ariables)f(not)i(included)e(in)i(that)g(mapping,)e(passing)i (an)f(inte)o(ger)g(for)g FK(name)g FN(is)i(also)f(accepted.)34 b(A)-6 b(v)n(ailability:)32 b(Macintosh,)210 1174 y(U)t FH(N)t(I)t(X)r FN(.)208 1307 y(If)22 b FK(name)h FN(is)h(a)f(string)g (and)f(is)i(not)f(kno)n(wn,)f FJ(ValueError)f FN(is)j(raised.)33 b(If)23 b(a)g(speci\002c)h(v)n(alue)e(for)g FK(name)g FN(is)i(not)f(supported)e(by)208 1406 y(the)d(host)g(system,)h(e)n(v)o (en)e(if)i(it)g(is)h(included)c(in)j FJ(pathconf_names)p FN(,)d(an)j FJ(OSError)e FN(is)j(raised)e(with)g FJ(errno.EINVAL)f FN(for)208 1506 y(the)j(error)f(number)-5 b(.)0 1653 y FD(fstat)p FJ(\()p FK(fd)r FJ(\))208 1752 y FN(Return)19 b(status)i(for)f(\002le)h(descriptor)d FK(fd)r FN(,)j(lik)o(e)f FJ(stat\(\))p FN(.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 1899 y FD(fstatvfs)p FJ(\()p FK(fd)r FJ(\))208 1999 y FN(Return)e(information)e(about)i(the) h(\002lesystem)g(containing)e(the)i(\002le)h(associated)f(with)g (\002le)g(descriptor)f FK(fd)r FN(,)h(lik)o(e)g FJ(statvfs\(\))p FN(.)208 2098 y(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 2245 y FD(fsync)p FJ(\()p FK(fd)r FJ(\))208 2345 y FN(F)o(orce)16 b(write)h(of)g(\002le)h(with)f(\002ledescriptor)f FK(fd)k FN(to)d(disk.)24 b(On)19 b(U)t FH(N)t(I)t(X)r FN(,)g(this)e(calls)h(the)f(nati)n(v)o(e)g FJ(fsync\(\))f FN(function;)h(on)f(W)m(indo)n(ws,)208 2445 y(the)k(MS)g FJ(_commit\(\))g FN(function.)208 2577 y(If)k(you')l(re)e(starting)i (with)h(a)g(Python)e(\002le)i(object)f FK(f)12 b FN(,)25 b(\002rst)h(do)e FK(f)12 b FJ(.flush\(\))p FN(,)24 b(and)g(then)g(do)g FJ(os.fsync\()p FK(f)12 b FJ(.fileno\(\)\))p FN(,)208 2677 y(to)29 b(ensure)f(that)h(all)h(internal)e(b)n(uf)n(fers)h (associated)f(with)i FK(f)42 b FN(are)29 b(written)g(to)g(disk.)52 b(A)-6 b(v)n(ailability:)42 b(Macintosh,)32 b(U)t FH(N)t(I)t(X)r FN(,)g(and)208 2777 y(W)m(indo)n(ws)19 b(starting)h(in)g(2.2.3.)0 2924 y FD(ftruncate)p FJ(\()p FK(fd,)e(length)p FJ(\))208 3023 y FN(T)m(runcate)29 b(the)i(\002le)h(corresponding)27 b(to)32 b(\002le)f(descriptor)f FK(fd)r FN(,)k(so)d(that)g(it)h(is)g (at)f(most)g FK(length)f FN(bytes)h(in)g(size.)58 b(A)-6 b(v)n(ailability:)208 3123 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(.)0 3270 y FD(isatty)p FJ(\()p FK(fd)r FJ(\))208 3369 y FN(Return)26 b FJ(True)i FN(if)f(the)h(\002le)g(descriptor)d FK(fd)30 b FN(is)e(open)f(and)g(connected)e(to)i(a)h(tty\(-lik)o(e\))e (de)n(vice,)i(else)g FJ(False)p FN(.)46 b(A)-6 b(v)n(ailability:)208 3469 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(.)0 3616 y FD(lseek)p FJ(\()p FK(fd,)e(pos,)h(how)p FJ(\))208 3715 y FN(Set)25 b(the)f(current)g(position)g(of)g(\002le)h(descriptor) e FK(fd)k FN(to)e(position)f FK(pos)p FN(,)h(modi\002ed)f(by)g FK(how)p FN(:)34 b FJ(0)25 b FN(to)g(set)g(the)g(position)f(relati)n(v) o(e)f(to)208 3815 y(the)k(be)o(ginning)f(of)h(the)h(\002le;)k FJ(1)c FN(to)g(set)h(it)f(relati)n(v)o(e)f(to)h(the)g(current)f (position;)k FJ(2)d FN(to)g(set)g(it)h(relati)n(v)o(e)e(to)h(the)g(end) f(of)g(the)h(\002le.)208 3915 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 4062 y FD(open)p FJ(\()p FK(\002le)o(,)e(\003a)o(gs)p FC([)p FK(,)h(mode)12 b FC(])p FJ(\))208 4161 y FN(Open)21 b(the)h(\002le)g FK(\002le)g FN(and)f(set)i(v)n(arious)e(\003ags)h (according)d(to)j FK(\003a)o(gs)g FN(and)f(possibly)g(its)i(mode)e (according)f(to)i FK(mode)p FN(.)29 b(The)21 b(def)o(ault)208 4261 y FK(mode)g FN(is)i FJ(0777)f FN(\(octal\),)g(and)f(the)h(current) f(umask)h(v)n(alue)f(is)i(\002rst)g(mask)o(ed)f(out.)30 b(Return)22 b(the)g(\002le)h(descriptor)e(for)g(the)h(ne)n(wly)208 4360 y(opened)c(\002le.)26 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 4493 y(F)o(or)16 b(a)h(description)e(of)h(the)h(\003ag)g(and)f(mode)f (v)n(alues,)i(see)g(the)g(C)g(run-time)e(documentation;)g(\003ag)i (constants)f(\(lik)o(e)g FJ(O_RDONLY)208 4593 y FN(and)j FJ(O_WRONLY)p FN(\))g(are)h(de\002ned)f(in)i(this)f(module)f(too)h (\(see)h(belo)n(w\).)208 4726 y FL(Note:)29 b FN(This)23 b(function)e(is)j(intended)d(for)i(lo)n(w-le)n(v)o(el)e(I/O.)i(F)o(or)g (normal)e(usage,)i(use)g(the)g(b)n(uilt-in)f(function)f FJ(open\(\))p FN(,)i(which)208 4825 y(returns)g(a)i(\223\002le)h (object\224)e(with)g FJ(read\(\))h FN(and)f FJ(write\(\))g FN(methods)f(\(and)h(man)o(y)f(more\).)38 b(T)-7 b(o)24 b(wrap)h(a)g(\002le)g(descriptor)e(in)i(a)208 4925 y(\223\002le)20 b(object\224,)g(use)g FJ(fdopen\(\))p FN(.)0 5072 y FD(openpty)p FJ(\(\))208 5171 y FN(Open)26 b(a)i(ne)n(w)g(pseudo-terminal)c(pair)-5 b(.)47 b(Return)27 b(a)h(pair)f(of)h(\002le)g(descriptors)e FJ(\()p FK(master)r FJ(,)49 b FK(slave)p FJ(\))28 b FN(for)f(the)g(pty) h(and)e(the)i(tty)-5 b(,)208 5271 y(respecti)n(v)o(ely)g(.)50 b(F)o(or)29 b(a)g(\(slightly\))g(more)f(portable)g(approach,)h(use)h (the)f FJ(pty)g FN(module.)51 b(A)-6 b(v)n(ailability:)42 b(Macintosh,)31 b(Some)208 5371 y(\003a)n(v)n(ors)20 b(of)i(U)t FH(N)t(I)t(X)r FN(.)p 0 5549 3901 4 v 0 5649 a FI(400)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 401 413 TeXDict begin 401 412 bop 0 83 a FD(pipe)p FJ(\(\))208 183 y FN(Create)17 b(a)g(pipe.)23 b(Return)16 b(a)h(pair)g(of)f(\002le) i(descriptors)d FJ(\()p FK(r)r FJ(,)50 b FK(w)p FJ(\))17 b FN(usable)g(for)f(reading)f(and)h(writing,)h(respecti)n(v)o(ely)-5 b(.)21 b(A)-6 b(v)n(ailability:)208 282 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 429 y FD(read)p FJ(\()p FK(fd,)e(n)p FJ(\))208 529 y FN(Read)26 b(at)h(most)f FK(n)h FN(bytes)f(from)f(\002le)i(descriptor)e FK(fd)r FN(.)44 b(Return)26 b(a)h(string)f(containing)e(the)j(bytes)f(read.)43 b(If)26 b(the)h(end)e(of)i(the)f(\002le)208 628 y(referred)18 b(to)i(by)g FK(fd)j FN(has)d(been)g(reached,)e(an)i(empty)g(string)g (is)h(returned.)i(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 759 y FL(Note:)h FN(This)c(function)e(is)i(intended)e(for)g(lo)n(w-le)n(v)o(el)g(I/O)i (and)f(must)g(be)g(applied)g(to)g(a)h(\002le)g(descriptor)e(as)i (returned)d(by)i FJ(open\(\))208 859 y FN(or)k FJ(pipe\(\))p FN(.)29 b(T)-7 b(o)22 b(read)f(a)h(\223\002le)g(object\224)f(returned)f (by)i(the)f(b)n(uilt-in)g(function)f FJ(open\(\))i FN(or)f(by)g FJ(popen\(\))g FN(or)h FJ(fdopen\(\))p FN(,)208 959 y(or)d FJ(sys.stdin)p FN(,)g(use)i(its)g FJ(read\(\))f FN(or)f FJ(readline\(\))g FN(methods.)0 1105 y FD(tcgetpgrp)p FJ(\()p FK(fd)r FJ(\))208 1205 y FN(Return)33 b(the)h(process)g(group)e (associated)i(with)h(the)f(terminal)f(gi)n(v)o(en)g(by)h FK(fd)i FN(\(an)e(open)f(\002le)i(descriptor)e(as)i(returned)d(by)208 1305 y FJ(open\(\))p FN(\).)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 1452 y FD(tcsetpgrp)p FJ(\()p FK(fd,)d(pg)p FJ(\))208 1551 y FN(Set)j(the)g(process)f(group)f (associated)h(with)h(the)g(terminal)f(gi)n(v)o(en)g(by)g FK(fd)j FN(\(an)d(open)g(\002le)h(descriptor)f(as)h(returned)e(by)h FJ(open\(\))p FN(\))208 1651 y(to)g FK(pg)p FN(.)k(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 1798 y FD(ttyname)p FJ(\()p FK(fd)r FJ(\))208 1897 y FN(Return)d(a)i(string)f(which)g(speci\002es)h(the)f(terminal)g (de)n(vice)g(associated)g(with)g(\002le-descriptor)f FK(fd)r FN(.)25 b(If)19 b FK(fd)j FN(is)e(not)f(associated)g(with)208 1997 y(a)h(terminal)g(de)n(vice,)f(an)h(e)o(xception)e(is)j(raised.)k (A)-6 b(v)n(ailability:Macintosh,)20 b(U)t FH(N)t(I)t(X)r FN(.)0 2144 y FD(write)p FJ(\()p FK(fd,)f(str)r FJ(\))208 2243 y FN(Write)k(the)g(string)g FK(str)j FN(to)d(\002le)h(descriptor)d FK(fd)r FN(.)34 b(Return)23 b(the)g(number)e(of)i(bytes)f(actually)h (written.)33 b(A)-6 b(v)n(ailability:)30 b(Macintosh,)210 2343 y(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)208 2474 y FL(Note:)h FN(This)c(function)e(is)i(intended)e(for)g(lo)n(w-le) n(v)o(el)g(I/O)i(and)f(must)g(be)g(applied)g(to)g(a)h(\002le)g (descriptor)e(as)i(returned)d(by)i FJ(open\(\))208 2573 y FN(or)j FJ(pipe\(\))p FN(.)k(T)-7 b(o)21 b(write)f(a)h(\223\002le)f (object\224)g(returned)e(by)i(the)h(b)n(uilt-in)e(function)g FJ(open\(\))g FN(or)h(by)g FJ(popen\(\))g FN(or)g FJ(fdopen\(\))p FN(,)208 2673 y(or)f FJ(sys.stdout)g FN(or)h FJ(sys.stderr)p FN(,)f(use)h(its)i FJ(write\(\))d FN(method.)0 2820 y(The)e(follo)n (wing)f(data)h(items)h(are)g(a)n(v)n(ailable)f(for)f(use)i(in)g (constructing)d(the)j FK(\003a)o(gs)f FN(parameter)f(to)h(the)h FJ(open\(\))f FN(function.)22 b(Some)17 b(items)0 2920 y(will)k(not)f(be)g(a)n(v)n(ailable)g(on)f(all)i(platforms.)j(F)o(or)c (descriptions)f(of)h(their)g(a)n(v)n(ailability)f(and)h(use,)g(consult) g FK(open)p FN(\(2\).)0 3066 y FD(O_RDONLY)0 3166 y(O_WRONLY)0 3266 y(O_RDWR)0 3365 y(O_APPEND)0 3465 y(O_CREAT)0 3565 y(O_EXCL)0 3664 y(O_TRUNC)208 3764 y FN(Options)28 b(for)h(the)g FK(\003a)o(g)g FN(ar)o(gument)e(to)i(the)g FJ(open\(\))g FN(function.)50 b(These)30 b(can)f(be)g(bit-wise)g(OR')l(d)g(together) -5 b(.)51 b(A)-6 b(v)n(ailability:)208 3863 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 4010 y FD(O_DSYNC)0 4110 y(O_RSYNC)0 4210 y(O_SYNC)0 4309 y(O_NDELAY)0 4409 y(O_NONBLOCK)0 4509 y(O_NOCTTY)0 4608 y(O_SHLOCK)0 4708 y(O_EXLOCK)208 4807 y FN(More)e(options)g(for)h(the)g FK(\003a)o(g)g FN(ar)o(gument)d(to)k(the)f FJ(open\(\))g FN(function.)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 4954 y FD(O_BINARY)208 5054 y FN(Option)27 b(for)g(the)g FK(\003a)o(g)g FN(ar)o(gument)f(to)i(the)f FJ(open\(\))h FN(function.)46 b(This)28 b(can)f(be)h(bit-wise)g(OR')l (d)f(together)g(with)h(those)f(listed)208 5154 y(abo)o(v)o(e.)c(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws.)0 5300 y FD(O_NOINHERIT)0 5400 y(O_SHORT_LIVED)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o(ating)g(system)e(interf)n (aces)1736 b(401)p eop end %%Page: 402 414 TeXDict begin 402 413 bop 0 83 a FD(O_TEMPORARY)0 183 y(O_RANDOM)0 282 y(O_SEQUENTIAL)0 382 y(O_TEXT)208 482 y FN(Options)28 b(for)h(the)g FK(\003a)o(g)g FN(ar)o(gument)e(to)i(the) g FJ(open\(\))g FN(function.)50 b(These)30 b(can)f(be)g(bit-wise)g(OR') l(d)g(together)-5 b(.)51 b(A)-6 b(v)n(ailability:)208 581 y(W)m(indo)n(ws.)0 728 y FD(SEEK_SET)0 828 y(SEEK_CUR)0 927 y(SEEK_END)208 1027 y FN(P)o(arameters)18 b(to)i(the)f FJ(lseek\(\))g FN(function.)k(Their)c(v)n(alues)g(are)g(0,)g(1,)h(and)f (2,)g(respecti)n(v)o(ely)-5 b(.)23 b(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws,)18 b(Macin-)208 1127 y(tosh,)j(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1411 y Fv(14.1.4)101 b(Files)28 b(and)g(Director)q(ies)0 1600 y FD(access)p FJ(\()p FK(path,)18 b(mode)p FJ(\))208 1700 y FN(Use)j(the)f(real)h(uid/gid)e(to)i(test)g(for)f(access)h(to)f FK(path)p FN(.)25 b(Note)c(that)f(most)h(operations)e(will)i(use)g(the) f(ef)n(fecti)n(v)o(e)f(uid/gid,)g(therefore)208 1800 y(this)k(routine)e(can)h(be)h(used)f(in)g(a)h(suid/sgid)f(en)m (vironment)e(to)i(test)i(if)e(the)h(in)m(v)n(oking)d(user)j(has)f(the)h (speci\002ed)f(access)h(to)g FK(path)p FN(.)208 1899 y FK(mode)28 b FN(should)f(be)i FJ(F_OK)g FN(to)g(test)g(the)g(e)o (xistence)f(of)g FK(path)p FN(,)i(or)f(it)g(can)g(be)f(the)h(inclusi)n (v)o(e)f(OR)h(of)g(one)f(or)h(more)f(of)g FJ(R_OK)p FN(,)208 1999 y FJ(W_OK)p FN(,)18 b(and)h FJ(X_OK)g FN(to)h(test)g(permissions.) k(Return)19 b FJ(True)g FN(if)g(access)h(is)h(allo)n(wed,)d FJ(False)h FN(if)h(not.)k(See)c(the)h(U)t FH(N)t(I)t(X)h FN(man)d(page)208 2098 y FK(access)p FN(\(2\))g(for)g(more)h (information.)i(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)f(W)m(indo)n(ws.)208 2231 y FL(Note:)42 b FN(Using)29 b FJ(access\(\))g FN(to)g(check)g(if)g(a)h(user)f(is)i (authorized)c(to)j(e.g.)52 b(open)28 b(a)i(\002le)g(before)e(actually)g (doing)g(so)i(using)208 2331 y FJ(open\(\))24 b FN(creates)h(a)h (security)e(hole,)i(because)e(the)h(user)g(might)f(e)o(xploit)g(the)h (short)g(time)g(interv)n(al)g(between)f(checking)f(and)208 2431 y(opening)18 b(the)i(\002le)h(to)f(manipulate)f(it.)208 2563 y FL(Note:)28 b FN(I/O)23 b(operations)e(may)h(f)o(ail)h(e)n(v)o (en)e(when)h FJ(access\(\))g FN(indicates)g(that)g(the)o(y)g(w)o(ould)g (succeed,)g(particularly)f(for)g(oper)n(-)208 2663 y(ations)i(on)f (netw)o(ork)g(\002lesystems)i(which)e(may)h(ha)n(v)o(e)g(permissions)f (semantics)h(be)o(yond)e(the)i(usual)g(POSIX)g(permission-bit)208 2763 y(model.)0 2909 y FD(F_OK)208 3009 y FN(V)-9 b(alue)19 b(to)i(pass)f(as)h(the)g FK(mode)e FN(parameter)g(of)h FJ(access\(\))f FN(to)h(test)h(the)g(e)o(xistence)e(of)h FK(path)p FN(.)0 3156 y FD(R_OK)208 3256 y FN(V)-9 b(alue)19 b(to)i(include)e(in)h(the)g FK(mode)g FN(parameter)f(of)h FJ(access\(\))f FN(to)h(test)h(the)f(readability)f(of)h FK(path)p FN(.)0 3402 y FD(W_OK)208 3502 y FN(V)-9 b(alue)19 b(to)i(include)e(in)h(the)g FK(mode)g FN(parameter)f(of)h FJ(access\(\))f FN(to)h(test)h(the)f(writability)g(of)g FK(path)p FN(.)0 3649 y FD(X_OK)208 3749 y FN(V)-9 b(alue)19 b(to)i(include)e(in)h(the)g FK(mode)g FN(parameter)f(of)h FJ(access\(\))f FN(to)h(determine)f(if)h FK(path)g FN(can)g(be)g(e)o(x) o(ecuted.)0 3895 y FD(chdir)p FJ(\()p FK(path)p FJ(\))208 3995 y FN(Change)f(the)h(current)f(w)o(orking)g(directory)f(to)i FK(path)p FN(.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 4142 y FD(fchdir)p FJ(\()p FK(fd)r FJ(\))208 4242 y FN(Change)e(the)i(current)e(w)o (orking)h(directory)e(to)j(the)g(directory)e(represented)g(by)h(the)h (\002le)g(descriptor)e FK(fd)r FN(.)27 b(The)20 b(descriptor)g(must)208 4341 y(refer)f(to)h(an)g(opened)f(directory)-5 b(,)18 b(not)i(an)g(open)f(\002le.)26 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4488 y FD(getcwd)p FJ(\(\))208 4588 y FN(Return)g(a)i(string)f (representing)e(the)i(current)f(w)o(orking)g(directory)-5 b(.)22 b(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 4735 y FD(getcwdu)p FJ(\(\))208 4834 y FN(Return)f(a)i(Unicode)e(object)h(representing)e (the)i(current)f(w)o(orking)g(directory)-5 b(.)26 b(A)-6 b(v)n(ailability:)27 b(Macintosh,)22 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 4934 y(Ne)n(w)e(in)g(v)o(ersion)f(2.3.)0 5081 y FD(chroot)p FJ(\()p FK(path)p FJ(\))208 5180 y FN(Change)g(the)h(root)g(directory)e(of)i(the)g(current)f(process)h(to) g FK(path)p FN(.)k(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 5327 y FD(chmod)p FJ(\()p FK(path,)f(mode)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(402)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 403 415 TeXDict begin 403 414 bop 208 83 a FN(Change)23 b(the)h(mode)f(of)h FK(path)g FN(to)g(the)g(numeric)f FK(mode)p FN(.)37 b FK(mode)23 b FN(may)h(tak)o(e)g(one)g(of)g(the)g(follo)n(wing)f(v)n (alues)g(\(as)i(de\002ned)e(in)i(the)208 183 y FJ(stat)20 b FN(module\))e(or)i(bitwise)h(or)n(-ed)e(combinations)f(of)i(them:)349 349 y FM(\017)o FJ(S_ISUID)349 482 y FM(\017)o FJ(S_ISGID)349 614 y FM(\017)o FJ(S_ENFMT)349 747 y FM(\017)o FJ(S_ISVTX)349 880 y FM(\017)o FJ(S_IREAD)349 1013 y FM(\017)o FJ(S_IWRITE)349 1146 y FM(\017)o FJ(S_IEXEC)349 1279 y FM(\017)o FJ(S_IRWXU)349 1411 y FM(\017)o FJ(S_IRUSR)349 1544 y FM(\017)o FJ(S_IWUSR)349 1677 y FM(\017)o FJ(S_IXUSR)349 1810 y FM(\017)o FJ(S_IRWXG)349 1943 y FM(\017)o FJ(S_IRGRP)349 2076 y FM(\017)o FJ(S_IWGRP)349 2208 y FM(\017)o FJ(S_IXGRP)349 2341 y FM(\017)o FJ(S_IRWXO)349 2474 y FM(\017)o FJ(S_IROTH)349 2607 y FM(\017)o FJ(S_IWOTH)349 2740 y FM(\017)o FJ(S_IXOTH)208 2906 y FN(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 3039 y FL(Note:)35 b FN(Although)25 b(W)m(indo)n(ws)g(supports)g FJ(chmod\(\))p FN(,)h(you)f(can)h(only)f(set)i(the)f(\002le')-5 b(s)27 b(read-only)c(\003ag)j(with)g(it)h(\(via)f(the)g FJ(S_-)208 3138 y(IWRITE)19 b FN(and)h FJ(S_IREAD)f FN(constants)h(or)g (a)h(corresponding)16 b(inte)o(ger)j(v)n(alue\).)24 b(All)d(other)e (bits)i(are)f(ignored.)0 3285 y FD(chown)p FJ(\()p FK(path,)e(uid,)i (gid)r FJ(\))208 3385 y FN(Change)g(the)i(o)n(wner)e(and)h(group)e(id)j (of)f FK(path)g FN(to)g(the)h(numeric)e FK(uid)j FN(and)e FK(gid)r FN(.)28 b(T)-7 b(o)22 b(lea)n(v)o(e)f(one)g(of)g(the)h(ids)f (unchanged,)e(set)j(it)g(to)208 3484 y(-1.)i(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 3631 y FD(lchown)p FJ(\()p FK(path,)d(uid,)h(gid)r FJ(\))208 3731 y FN(Change)e(the)h(o)n (wner)g(and)f(group)g(id)h(of)g FK(path)g FN(to)g(the)g(numeric)f FK(uid)j FN(and)e(gid.)24 b(This)18 b(function)f(will)i(not)f(follo)n (w)g(symbolic)f(links.)208 3830 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3977 y FD(link)p FJ(\()p FK(sr)m(c,)h(dst)q FJ(\))208 4077 y FN(Create)g(a)h(hard)e(link)h(pointing)e(to)j FK(sr)m(c)g FN(named)e FK(dst)q FN(.)26 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 4224 y FD(listdir)p FJ(\()p FK(path)p FJ(\))208 4323 y FN(Return)c(a)i(list)h(containing)c (the)i(names)h(of)f(the)g(entries)g(in)h(the)f(directory)-5 b(.)22 b(The)c(list)i(is)f(in)g(arbitrary)d(order)-5 b(.)24 b(It)18 b(does)h(not)f(include)208 4423 y(the)26 b(special)h(entries)g FJ('.')45 b FN(and)26 b FJ('..')45 b FN(e)n(v)o(en)25 b(if)i(the)o(y)f(are)h(present)f(in)h(the)g (directory)-5 b(.)42 b(A)-6 b(v)n(ailability:)38 b(Macintosh,)29 b(U)t FH(N)t(I)t(X)r FN(,)208 4523 y(W)m(indo)n(ws.)208 4656 y(Changed)20 b(in)h(v)o(ersion)f(2.3:)h(On)h(W)m(indo)n(ws)e (NT/2k/XP)h(and)i(U)t FH(N)t(I)t(X)r FN(,)g(if)e FK(path)g FN(is)h(a)g(Unicode)e(object,)h(the)h(result)f(will)h(be)g(a)f(list)208 4755 y(of)e(Unicode)g(objects.)0 4902 y FD(lstat)p FJ(\()p FK(path)p FJ(\))208 5002 y FN(Lik)o(e)i FJ(stat\(\))p FN(,)h(b)n(ut)f(do)h(not)f(follo)n(w)g(symbolic)g(links.)30 b(This)22 b(is)h(an)e(alias)i(for)e FJ(stat\(\))g FN(on)h(platforms)e (that)i(do)f(not)h(support)208 5101 y(symbolic)d(links,)h(such)g(as)h (W)m(indo)n(ws.)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o(ating)g(system)e(interf)n (aces)1736 b(403)p eop end %%Page: 404 416 TeXDict begin 404 415 bop 0 83 a FD(mkfifo)p FJ(\()p FK(path)p FC([)p FK(,)18 b(mode)12 b FC(])p FJ(\))208 183 y FN(Create)24 b(a)g(FIFO)h(\(a)f(named)f(pipe\))g(named)g FK(path)h FN(with)g(numeric)e(mode)i FK(mode)p FN(.)36 b(The)23 b(def)o(ault)h FK(mode)f FN(is)i FJ(0666)f FN(\(octal\).)36 b(The)208 282 y(current)18 b(umask)i(v)n(alue)f(is)j(\002rst)f(mask)o (ed)e(out)h(from)f(the)h(mode.)k(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)208 415 y(FIFOs)28 b(are)f(pipes)g(that)h(can)f(be)g(accessed)h(lik)o(e)g(re)o(gular)d (\002les.)48 b(FIFOs)28 b(e)o(xist)g(until)f(the)o(y)g(are)g(deleted)g (\(for)f(e)o(xample)g(with)208 515 y FJ(os.unlink\(\))p FN(\).)31 b(Generally)-5 b(,)22 b(FIFOs)i(are)f(used)g(as)h(rendezv)n (ous)d(between)h(\223client\224)h(and)f(\223serv)o(er\224)g(type)h (processes:)31 b(the)208 614 y(serv)o(er)23 b(opens)g(the)h(FIFO)g(for) g(reading,)f(and)h(the)g(client)g(opens)f(it)i(for)e(writing.)36 b(Note)24 b(that)g FJ(mkfifo\(\))f FN(doesn')o(t)g(open)g(the)208 714 y(FIFO)d(\227)h(it)g(just)g(creates)f(the)g(rendezv)n(ous)e(point.) 0 861 y FD(mknod)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(mode=0600,)h (de)o(vice)12 b FC(])p FJ(\))208 960 y FN(Create)31 b(a)g(\002lesystem) h(node)e(\(\002le,)k(de)n(vice)c(special)h(\002le)h(or)f(named)f (pipe\))g(named)g FK(\002lename)p FN(.)56 b FK(mode)31 b FN(speci\002es)g(both)g(the)208 1060 y(permissions)c(to)i(use)g(and)f (the)h(type)f(of)g(node)f(to)i(be)g(created,)g(being)f(combined)f (\(bitwise)h(OR\))h(with)g(one)f(of)g(S)p 3614 1060 25 4 v 30 w(IFREG,)208 1160 y(S)p 259 1160 V 30 w(IFCHR,)20 b(S)p 620 1160 V 30 w(IFBLK,)g(and)f(S)p 1117 1160 V 30 w(IFIFO)h(\(those)f(constants)g(are)g(a)n(v)n(ailable)g(in)h FJ(stat)p FN(\).)k(F)o(or)c(S)p 2903 1160 V 30 w(IFCHR)g(and)f(S)p 3383 1160 V 30 w(IFBLK,)h FK(de)o(vice)208 1259 y FN(de\002nes)i(the)g (ne)n(wly)g(created)f(de)n(vice)h(special)g(\002le)h(\(probably)d (using)h FJ(os.makedev\(\))p FN(\),)g(otherwise)h(it)h(is)g(ignored.)61 b(Ne)n(w)208 1359 y(in)20 b(v)o(ersion)f(2.3.)0 1506 y FD(major)p FJ(\()p FK(de)o(vice)p FJ(\))208 1605 y FN(Extracts)28 b(the)h(de)n(vice)f(major)h(number)e(from)h(a)h(ra)o(w)g (de)n(vice)f(number)f(\(usually)h(the)h FJ(st_dev)g FN(or)f FJ(st_rdev)g FN(\002eld)i(from)208 1705 y FJ(stat)p FN(\).)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 1852 y FD(minor)p FJ(\()p FK(de)o(vice)p FJ(\))208 1952 y FN(Extracts)28 b(the)h(de)n(vice)e(minor)h(number)f(from)h(a)h(ra)o(w)f(de)n(vice)g (number)f(\(usually)h(the)g FJ(st_dev)g FN(or)h FJ(st_rdev)f FN(\002eld)h(from)208 2051 y FJ(stat)p FN(\).)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2198 y FD(makedev)p FJ(\()p FK(major)-9 b(,)18 b(minor)r FJ(\))208 2298 y FN(Composes)h(a)i(ra)o(w) f(de)n(vice)f(number)g(from)g(the)h(major)f(and)h(minor)f(de)n(vice)g (numbers.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2445 y FD(mkdir)p FJ(\()p FK(path)p FC([)p FK(,)f(mode)12 b FC(])p FJ(\))208 2544 y FN(Create)21 b(a)g(directory)e(named)g FK(path)h FN(with)h(numeric)f(mode)f FK(mode)p FN(.)26 b(The)21 b(def)o(ault)f FK(mode)g FN(is)i FJ(0777)e FN(\(octal\).)26 b(On)21 b(some)f(systems,)208 2644 y FK(mode)g FN(is)j(ignored.)j (Where)21 b(it)h(is)h(used,)e(the)g(current)f(umask)h(v)n(alue)g(is)h (\002rst)g(mask)o(ed)f(out.)28 b(A)-6 b(v)n(ailability:)26 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)208 2743 y(W)m(indo)n(ws.)0 2890 y FD(makedirs)p FJ(\()p FK(path)p FC([)p FK(,)17 b(mode)12 b FC(])p FJ(\))208 2990 y FN(Recursi)n(v)o(e)24 b(directory)g(creation)g(function.)39 b(Lik)o(e)26 b FJ(mkdir\(\))p FN(,)f(b)n(ut)h(mak)o(es)f(all)h(intermediate-le)n(v)o (el)d(directories)h(needed)g(to)208 3090 y(contain)19 b(the)i(leaf)g(directory)-5 b(.)24 b(Thro)n(ws)c(an)h FJ(error)f FN(e)o(xception)f(if)i(the)g(leaf)g(directory)e(already)h(e) o(xists)h(or)f(cannot)g(be)h(created.)208 3189 y(The)c(def)o(ault)g FK(mode)h FN(is)g FJ(0777)g FN(\(octal\).)24 b(On)18 b(some)f(systems,)i FK(mode)e FN(is)i(ignored.)j(Where)c(it)h(is)g (used,)e(the)h(current)f(umask)g(v)n(alue)208 3289 y(is)j(\002rst)f (mask)o(ed)g(out.)24 b FL(Note:)g FJ(makedirs\(\))18 b FN(will)h(become)f(confused)g(if)h(the)g(path)g(elements)g(to)g (create)g(include)f FK(os.par)m(dir)r FN(.)208 3388 y(Ne)n(w)i(in)g(v)o (ersion)f(1.5.2.)75 b(Changed)19 b(in)i(v)o(ersion)d(2.3:)i(This)g (function)f(no)n(w)h(handles)f(UNC)i(paths)f(correctly)-5 b(.)0 3535 y FD(pathconf)p FJ(\()p FK(path,)17 b(name)p FJ(\))208 3635 y FN(Return)28 b(system)h(con\002guration)d(information) h(rele)n(v)n(ant)h(to)h(a)g(named)f(\002le.)52 b FK(name)28 b FN(speci\002es)i(the)f(con\002guration)d(v)n(alue)i(to)208 3735 y(retrie)n(v)o(e;)21 b(it)h(may)g(be)f(a)i(string)e(which)g(is)i (the)f(name)f(of)g(a)h(de\002ned)f(system)h(v)n(alue;)g(these)g(names)f (are)h(speci\002ed)f(in)h(a)g(number)208 3834 y(of)f(standards)g (\(POSIX.1,)i(U)t FH(N)t(I)t(X)i FN(95,)f(U)t FH(N)t(I)t(X)g FN(98,)e(and)f(others\).)29 b(Some)21 b(platforms)g(de\002ne)g (additional)g(names)g(as)i(well.)30 b(The)208 3934 y(names)23 b(kno)n(wn)f(to)i(the)g(host)g(operating)e(system)i(are)f(gi)n(v)o(en)g (in)h(the)g FJ(pathconf_names)d FN(dictionary)-5 b(.)34 b(F)o(or)23 b(con\002guration)208 4033 y(v)n(ariables)f(not)i(included) e(in)i(that)g(mapping,)e(passing)i(an)f(inte)o(ger)g(for)g FK(name)g FN(is)i(also)f(accepted.)34 b(A)-6 b(v)n(ailability:)32 b(Macintosh,)210 4133 y(U)t FH(N)t(I)t(X)r FN(.)208 4266 y(If)22 b FK(name)h FN(is)h(a)f(string)g(and)f(is)i(not)f(kno)n(wn,)f FJ(ValueError)f FN(is)j(raised.)33 b(If)23 b(a)g(speci\002c)h(v)n(alue) e(for)g FK(name)g FN(is)i(not)f(supported)e(by)208 4366 y(the)d(host)g(system,)h(e)n(v)o(en)e(if)i(it)g(is)h(included)c(in)j FJ(pathconf_names)p FN(,)d(an)j FJ(OSError)e FN(is)j(raised)e(with)g FJ(errno.EINVAL)f FN(for)208 4465 y(the)j(error)f(number)-5 b(.)0 4612 y FD(pathconf_names)208 4712 y FN(Dictionary)24 b(mapping)h(names)h(accepted)f(by)h FJ(pathconf\(\))f FN(and)h FJ(fpathconf\(\))e FN(to)j(the)f(inte)o(ger)f(v)n(alues)h (de\002ned)f(for)208 4811 y(those)19 b(names)g(by)h(the)g(host)f (operating)f(system.)25 b(This)20 b(can)f(be)h(used)g(to)f(determine)g (the)g(set)i(of)e(names)h(kno)n(wn)e(to)i(the)g(system.)208 4911 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 5058 y FD(readlink)p FJ(\()p FK(path)p FJ(\))208 5157 y FN(Return)47 b(a)h(string)g(representing)e(the)i(path)f(to)h (which)f(the)h(symbolic)f(link)h(points.)107 b(The)48 b(result)g(may)f(be)h(either)208 5257 y(an)42 b(absolute)f(or)h(relati) n(v)o(e)g(pathname;)52 b(if)42 b(it)h(is)h(relati)n(v)o(e,)i(it)d(may)f (be)h(con)m(v)o(erted)c(to)k(an)f(absolute)f(pathname)g(using)208 5357 y FJ(os.path.join\(os.path.dirname\()p FK(pa)o(th)p FJ(\),)i FK(r)m(esult)q FJ(\))p FN(.)26 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)p 0 5549 3901 4 v 0 5649 a FI(404)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 405 417 TeXDict begin 405 416 bop 0 83 a FD(remove)p FJ(\()p FK(path)p FJ(\))208 183 y FN(Remo)o(v)o(e)24 b(the)h(\002le)h FK(path)p FN(.)40 b(If)26 b FK(path)e FN(is)j(a)f(directory)-5 b(,)24 b FJ(OSError)h FN(is)h(raised;)i(see)e FJ(rmdir\(\))f FN(belo)n(w)g(to)h(remo)o(v)o(e)d(a)j(directory)-5 b(.)208 282 y(This)22 b(is)h(identical)e(to)i(the)f FJ(unlink\(\))f FN(function)f(documented)g(belo)n(w)-5 b(.)29 b(On)22 b(W)m(indo)n(ws,)g(attempting)f(to)h(remo)o(v)o(e)e(a)j(\002le)f(that) 208 382 y(is)h(in)f(use)h(causes)f(an)g(e)o(xception)f(to)h(be)g (raised;)h(on)h(U)t FH(N)t(I)t(X)r FN(,)g(the)e(directory)e(entry)i(is) h(remo)o(v)o(ed)d(b)n(ut)i(the)g(storage)g(allocated)f(to)208 482 y(the)d(\002le)h(is)g(not)f(made)f(a)n(v)n(ailable)h(until)g(the)g (original)g(\002le)g(is)i(no)d(longer)g(in)i(use.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)19 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 628 y FD(removedirs)p FJ(\()p FK(path)p FJ(\))208 728 y FN(Remo)o(v)o(es)30 b(directories)g(recursi)n (v)o(ely)-5 b(.)57 b(W)-7 b(orks)31 b(lik)o(e)h FJ(rmdir\(\))e FN(e)o(xcept)h(that,)j(if)d(the)h(leaf)f(directory)f(is)i(successfully) f(re-)208 828 y(mo)o(v)o(ed,)22 b FJ(removedirs\(\))g FN(tries)i(to)g(successi)n(v)o(ely)f(remo)o(v)o(e)f(e)n(v)o(ery)h (parent)g(directory)f(mentioned)f(in)j FK(path)f FN(until)h(an)g(error) 208 927 y(is)31 b(raised)e(\(which)h(is)h(ignored,)f(because)f(it)i (generally)e(means)g(that)i(a)f(parent)f(directory)g(is)i(not)e (empty\).)54 b(F)o(or)29 b(e)o(xample,)208 1027 y(`)p FJ(os.removedirs\('foo/bar/baz'\))p FN(')22 b(will)29 b(\002rst)f(remo)o(v)o(e)e(the)i(directory)e(`)p FJ('foo/bar/baz')p FN(',)h(and)g(then)h(re-)208 1127 y(mo)o(v)o(e)i(`)p FJ('foo/bar')p FN(')h(and)h(`)p FJ('foo')p FN(')f(if)h(the)o(y)g(are)g (empty)-5 b(.)60 b(Raises)34 b FJ(OSError)d FN(if)i(the)f(leaf)h (directory)d(could)i(not)g(be)208 1226 y(successfully)19 b(remo)o(v)o(ed.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.5.2.)0 1373 y FD(rename)p FJ(\()p FK(sr)m(c,)h(dst)q FJ(\))208 1473 y FN(Rename)f(the)g(\002le)h(or)f(directory)f FK(sr)m(c)j FN(to)e FK(dst)q FN(.)26 b(If)19 b FK(dst)j FN(is)e(a)g(directory)-5 b(,)17 b FJ(OSError)i FN(will)h(be)g(raised.)k(On)e(U)t FH(N)t(I)t(X)r FN(,)e(if)g FK(dst)h FN(e)o(xists)f(and)208 1572 y(is)i(a)h(\002le,)f(it)h(will)f(be)g(remo)o(v)o(ed)e(silently)i (if)g(the)g(user)f(has)h(permission.)29 b(The)22 b(operation)e(may)h(f) o(ail)h(on)g(some)h(U)t FH(N)t(I)t(X)i FN(\003a)n(v)n(ors)d(if)208 1672 y FK(sr)m(c)e FN(and)e FK(dst)j FN(are)e(on)g(dif)n(ferent)f (\002lesystems.)25 b(If)19 b(successful,)g(the)g(renaming)e(will)j(be)f (an)g(atomic)g(operation)e(\(this)i(is)i(a)e(POSIX)208 1772 y(requirement\).)33 b(On)25 b(W)m(indo)n(ws,)f(if)g FK(dst)i FN(already)d(e)o(xists,)i FJ(OSError)f FN(will)g(be)g(raised)g (e)n(v)o(en)f(if)i(it)g(is)g(a)f(\002le;)j(there)c(may)h(be)g(no)208 1871 y(w)o(ay)18 b(to)h(implement)e(an)h(atomic)g(rename)f(when)h FK(dst)j FN(names)d(an)g(e)o(xisting)g(\002le.)25 b(A)-6 b(v)n(ailability:)23 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)f(W)m(indo)n(ws.)0 2018 y FD(renames)p FJ(\()p FK(old,)f(ne)o(w)p FJ(\))208 2118 y FN(Recursi)n(v)o(e)k(directory)f(or)i(\002le)h (renaming)d(function.)32 b(W)-7 b(orks)23 b(lik)o(e)g FJ(rename\(\))p FN(,)g(e)o(xcept)f(creation)g(of)h(an)o(y)f (intermediate)g(di-)208 2217 y(rectories)c(needed)g(to)h(mak)o(e)g(the) g(ne)n(w)g(pathname)f(good)f(is)j(attempted)f(\002rst.)25 b(After)19 b(the)g(rename,)f(directories)g(corresponding)208 2317 y(to)28 b(rightmost)f(path)h(se)o(gments)f(of)h(the)g(old)g(name)g (will)g(be)h(pruned)d(a)o(w)o(ay)i(using)f FJ(removedirs\(\))p FN(.)97 b(Ne)n(w)29 b(in)f(v)o(ersion)208 2417 y(1.5.2.)208 2549 y FL(Note:)33 b FN(This)25 b(function)d(can)j(f)o(ail)g(with)g (the)f(ne)n(w)h(directory)e(structure)g(made)h(if)h(you)f(lack)h (permissions)e(needed)h(to)h(remo)o(v)o(e)208 2649 y(the)20 b(leaf)g(directory)e(or)i(\002le.)0 2796 y FD(rmdir)p FJ(\()p FK(path)p FJ(\))208 2895 y FN(Remo)o(v)o(e)f(the)h(directory)e FK(path)p FN(.)24 b(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 3042 y FD(stat)p FJ(\()p FK(path)p FJ(\))208 3142 y FN(Perform)f(a)i FJ(stat\(\))f FN(system)h(call)h(on)e(the)h(gi)n(v)o(en)e(path.)29 b(The)22 b(return)e(v)n(alue)h(is)i(an)f(object)f(whose)h(attrib)n (utes)f(correspond)e(to)208 3242 y(the)25 b(members)e(of)i(the)g FJ(stat)g FN(structure,)g(namely:)33 b FJ(st_mode)25 b FN(\(protection)d(bits\),)k FJ(st_ino)f FN(\(inode)e(number\),)h FJ(st_dev)208 3341 y FN(\(de)n(vice\),)16 b FJ(st_nlink)g FN(\(number)g(of)h(hard)f(links\),)i FJ(st_uid)e FN(\(user)h(ID)h(of)f (o)n(wner\),)f FJ(st_gid)h FN(\(group)f(ID)h(of)g(o)n(wner\),)g FJ(st_-)208 3441 y(size)h FN(\(size)i(of)e(\002le,)i(in)f(bytes\),)g FJ(st_atime)f FN(\(time)g(of)h(most)g(recent)f(access\),)i FJ(st_mtime)e FN(\(time)h(of)f(most)h(recent)g(content)208 3540 y(modi\002cation\),)h FJ(st_ctime)i FN(\(platform)e(dependent;)i (time)g(of)g(most)h(recent)e(metadata)h(change)f(on)j(U)t FH(N)t(I)t(X)r FN(,)g(or)e(the)g(time)h(of)208 3640 y(creation)c(on)g (W)m(indo)n(ws\):)444 3864 y FA(>>>)44 b(import)g(os)444 3956 y(>>>)g(statinfo)g(=)g(os.stat\('somefile.txt'\))444 4047 y(>>>)g(statinfo)444 4138 y(\(33188,)f(422511L,)h(769L,)g(1,)g (1032,)g(100,)h(926L,)f(1105022698,1105022732,)d(1105022732\))444 4230 y(>>>)j(statinfo.st_size)444 4321 y(926L)444 4412 y(>>>)208 4602 y FN(Changed)22 b(in)i(v)o(ersion)e(2.3:)h(If)g FJ(stat_float_times)e FN(returns)i(true,)h(the)f(time)h(v)n(alues)f (are)h(\003oats,)g(measuring)e(seconds.)208 4701 y(Fractions)e(of)g(a)h (second)e(may)h(be)h(reported)d(if)j(the)f(system)h(supports)e(that.)26 b(On)21 b(Mac)f(OS,)h(the)g(times)g(are)f(al)o(w)o(ays)h(\003oats.)26 b(See)208 4801 y FJ(stat_float_times)17 b FN(for)j(further)f (discussion.)208 4934 y(On)i(some)h(U)t FH(N)t(I)t(X)i FN(systems)e(\(such)e(as)i(Linux\),)d(the)i(follo)n(wing)f(attrib)n (utes)h(may)f(also)i(be)e(a)n(v)n(ailable:)27 b FJ(st_blocks)20 b FN(\(number)208 5033 y(of)15 b(blocks)h(allocated)f(for)h(\002le\),)h FJ(st_blksize)d FN(\(\002lesystem)i(blocksize\),)g FJ(st_rdev)f FN(\(type)g(of)h(de)n(vice)f(if)i(an)f(inode)f(de)n(vice\).)208 5133 y FJ(st_flags)k FN(\(user)h(de\002ned)f(\003ags)h(for)g(\002le\).) 208 5266 y(On)25 b(other)h(U)t FH(N)t(I)t(X)i FN(systems)e(\(such)f(as) h(FreeBSD\),)f(the)g(follo)n(wing)f(attrib)n(utes)h(may)f(be)h(a)n(v)n (ailable)g(\(b)n(ut)g(may)g(be)g(only)f(\002lled)208 5365 y(out)19 b(if)i(root)e(tries)i(to)f(use)h(them\):)j FJ(st_gen)c FN(\(\002le)h(generation)d(number\),)f FJ(st_birthtime)i FN(\(time)h(of)g(\002le)h(creation\).)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o (ating)g(system)e(interf)n(aces)1736 b(405)p eop end %%Page: 406 418 TeXDict begin 406 417 bop 208 83 a FN(On)20 b(Mac)g(OS)h(systems,)f (the)h(follo)n(wing)d(attrib)n(utes)i(may)g(also)g(be)h(a)n(v)n (ailable:)j FJ(st_rsize)p FN(,)19 b FJ(st_creator)p FN(,)g FJ(st_type)p FN(.)208 216 y(On)d(RISCOS)h(systems,)h(the)e(follo)n (wing)f(attrib)n(utes)h(are)g(also)h(a)n(v)n(ailable:)22 b FJ(st_ftype)16 b FN(\(\002le)g(type\),)g FJ(st_attrs)g FN(\(attrib)n(utes\),)208 315 y FJ(st_obtype)j FN(\(object)g(type\).) 208 448 y(F)o(or)c(backw)o(ard)g(compatibility)-5 b(,)15 b(the)h(return)f(v)n(alue)g(of)h FJ(stat\(\))g FN(is)h(also)g (accessible)f(as)h(a)f(tuple)g(of)g(at)h(least)g(10)f(inte)o(gers)f(gi) n(ving)208 548 y(the)21 b(most)g(important)e(\(and)h(portable\))f (members)h(of)h(the)g FJ(stat)g FN(structure,)f(in)h(the)g(order)f FJ(st_mode)p FN(,)g FJ(st_ino)p FN(,)g FJ(st_dev)p FN(,)208 648 y FJ(st_nlink)p FN(,)e FJ(st_uid)p FN(,)h FJ(st_gid)p FN(,)g FJ(st_size)p FN(,)f FJ(st_atime)p FN(,)h FJ(st_mtime)p FN(,)f FJ(st_ctime)p FN(.)24 b(More)19 b(items)h(may)f(be)h(added)208 747 y(at)f(the)g(end)f(by)h(some)g(implementations.)j(The)d(standard)f (module)f FJ(stat)i FN(de\002nes)g(functions)e(and)i(constants)f(that)h (are)g(useful)208 847 y(for)g(e)o(xtracting)g(information)e(from)j(a)g FJ(stat)g FN(structure.)k(\(On)c(W)m(indo)n(ws,)f(some)h(items)h(are)f (\002lled)h(with)f(dummy)e(v)n(alues.\))208 980 y FL(Note:)35 b FN(The)25 b(e)o(xact)g(meaning)f(and)i(resolution)e(of)h(the)h FJ(st_atime)p FN(,)g FJ(st_mtime)p FN(,)g(and)f FJ(st_ctime)f FN(members)h(depends)208 1079 y(on)g(the)g(operating)f(system)i(and)f (the)h(\002le)g(system.)41 b(F)o(or)26 b(e)o(xample,)f(on)g(W)m(indo)n (ws)g(systems)h(using)g(the)f(F)-6 b(A)d(T)26 b(or)f(F)-6 b(A)d(T32)25 b(\002le)208 1179 y(systems,)g FJ(st_mtime)f FN(has)h(2-second)e(resolution,)h(and)g FJ(st_atime)g FN(has)g(only)g(1-day)f(resolution.)37 b(See)25 b(your)e(operating)208 1279 y(system)d(documentation)d(for)j(details.)208 1411 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 1544 y(Changed)g(in)i(v)o(ersion)f(2.2:)g (Added)g(access)i(to)f(v)n(alues)f(as)i(attrib)n(utes)f(of)f(the)h (returned)e(object.)101 b(Changed)21 b(in)i(v)o(ersion)f(2.5:)208 1644 y(Added)d(st)p 510 1644 25 4 v 30 w(gen,)g(st)p 756 1644 V 31 w(birthtime.)0 1791 y FD(stat_float_times)p FJ(\()p FC([)p FK(ne)o(wvalue)12 b FC(])p FJ(\))208 1890 y FN(Determine)k(whether)h FJ(stat_result)f FN(represents)h(time)h (stamps)g(as)g(\003oat)g(objects.)24 b(If)17 b FK(ne)o(wvalue)g FN(is)i FJ(True)p FN(,)e(future)g(calls)h(to)208 1990 y FJ(stat\(\))h FN(return)g(\003oats,)i(if)f(it)h(is)g FJ(False)p FN(,)f(future)f(calls)i(return)e(ints.)25 b(If)20 b FK(ne)o(wvalue)f FN(is)i(omitted,)f(return)f(the)h(current)f (setting.)208 2123 y(F)o(or)g(compatibility)g(with)h(older)g(Python)f (v)o(ersions,)g(accessing)h FJ(stat_result)e FN(as)j(a)g(tuple)f(al)o (w)o(ays)g(returns)g(inte)o(gers.)208 2256 y(Changed)h(in)i(v)o(ersion) e(2.5:)i(Python)e(no)n(w)i(returns)e(\003oat)i(v)n(alues)g(by)f(def)o (ault.)32 b(Applications)22 b(which)g(do)g(not)h(w)o(ork)f(correctly) 208 2355 y(with)e(\003oating)f(point)h(time)g(stamps)h(can)f(use)g (this)h(function)d(to)j(restore)e(the)h(old)g(beha)n(viour)-5 b(.)208 2488 y(The)22 b(resolution)f(of)i(the)g(timestamps)f(\(that)h (is)g(the)g(smallest)h(possible)e(fraction\))f(depends)h(on)g(the)h (system.)33 b(Some)22 b(systems)208 2588 y(only)d(support)g(second)g (resolution;)g(on)h(these)g(systems,)h(the)f(fraction)f(will)i(al)o(w)o (ays)f(be)g(zero.)208 2721 y(It)26 b(is)h(recommended)d(that)i(this)h (setting)f(is)h(only)f(changed)e(at)j(program)d(startup)i(time)h(in)f (the)p 3018 2721 V 3048 2721 V 86 w FK(main)p 3245 2721 V 3274 2721 V 86 w FN(module;)i(libraries)208 2820 y(should)d(ne)n(v)o (er)g(change)h(this)h(setting.)44 b(If)27 b(an)f(application)f(uses)i (a)g(library)f(that)h(w)o(orks)f(incorrectly)f(if)i(\003oating)f(point) f(time)208 2920 y(stamps)20 b(are)g(processed,)f(this)i(application)d (should)i(turn)f(the)h(feature)f(of)n(f)h(until)g(the)g(library)f(has)i (been)e(corrected.)0 3067 y FD(statvfs)p FJ(\()p FK(path)p FJ(\))208 3166 y FN(Perform)j(a)h FJ(statvfs\(\))f FN(system)i(call)g (on)f(the)g(gi)n(v)o(en)f(path.)34 b(The)23 b(return)f(v)n(alue)h(is)h (an)f(object)g(whose)g(attrib)n(utes)g(describe)208 3266 y(the)30 b(\002lesystem)h(on)f(the)h(gi)n(v)o(en)e(path,)j(and)e (correspond)e(to)j(the)g(members)e(of)h(the)h FJ(statvfs)f FN(structure,)i(namely:)45 b FJ(f_-)208 3366 y(bsize)p FN(,)17 b FJ(f_frsize)p FN(,)g FJ(f_blocks)p FN(,)g FJ(f_bfree)p FN(,)g FJ(f_bavail)p FN(,)g FJ(f_files)p FN(,)g FJ(f_ffree)p FN(,)g FJ(f_favail)p FN(,)g FJ(f_flag)p FN(,)h FJ(f_-)208 3465 y(namemax)p FN(.)24 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)208 3598 y(F)o(or)h(backw)o(ard)f (compatibility)-5 b(,)27 b(the)g(return)f(v)n(alue)h(is)i(also)e (accessible)h(as)g(a)g(tuple)f(whose)g(v)n(alues)g(correspond)e(to)j (the)f(at-)208 3698 y(trib)n(utes,)21 b(in)g(the)g(order)f(gi)n(v)o(en) g(abo)o(v)o(e.)26 b(The)21 b(standard)f(module)g FJ(statvfs)g FN(de\002nes)h(constants)g(that)g(are)h(useful)e(for)h(e)o(xtract-)208 3797 y(ing)h(information)e(from)i(a)h FJ(statvfs)f FN(structure)g(when) g(accessing)g(it)i(as)f(a)h(sequence;)e(this)i(remains)e(useful)g(when) g(writing)208 3897 y(code)d(that)h(needs)g(to)g(w)o(ork)g(with)g(v)o (ersions)g(of)g(Python)f(that)h(don')o(t)e(support)h(accessing)h(the)g (\002elds)h(as)g(attrib)n(utes.)208 4030 y(Changed)d(in)j(v)o(ersion)e (2.2:)g(Added)g(access)i(to)g(v)n(alues)e(as)i(attrib)n(utes)f(of)g (the)g(returned)f(object.)0 4177 y FD(symlink)p FJ(\()p FK(sr)m(c,)g(dst)q FJ(\))208 4276 y FN(Create)h(a)h(symbolic)e(link)h (pointing)e(to)j FK(sr)m(c)g FN(named)e FK(dst)q FN(.)26 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 4423 y FD(tempnam)p FJ(\()p FC([)p FK(dir)r FC([)p FK(,)18 b(pr)m(e\002x)12 b FC(])g(])p FJ(\))208 4523 y FN(Return)24 b(a)h(unique)f(path)g(name)h(that)g(is)h(reasonable)d(for)h(creating)g (a)i(temporary)c(\002le.)40 b(This)25 b(will)h(be)f(an)g(absolute)f (path)g(that)208 4622 y(names)d(a)h(potential)e(directory)g(entry)h(in) g(the)h(directory)e FK(dir)j FN(or)f(a)g(common)d(location)i(for)g (temporary)e(\002les)j(if)g FK(dir)i FN(is)e(omitted)208 4722 y(or)29 b FJ(None)p FN(.)51 b(If)30 b(gi)n(v)o(en)e(and)g(not)h FJ(None)p FN(,)i FK(pr)m(e\002x)e FN(is)i(used)e(to)g(pro)o(vide)e(a)j (short)f(pre\002x)f(to)i(the)f(\002lename.)51 b(Applications)29 b(are)208 4822 y(responsible)15 b(for)i(properly)d(creating)i(and)h (managing)e(\002les)j(created)e(using)g(paths)h(returned)e(by)i FJ(tempnam\(\))p FN(;)g(no)g(automatic)208 4921 y(cleanup)22 b(is)i(pro)o(vided.)32 b(On)25 b(U)t FH(N)t(I)t(X)r FN(,)g(the)f(en)m (vironment)c(v)n(ariable)i(TMPDIR)i(o)o(v)o(errides)d FK(dir)r FN(,)k(while)e(on)g(W)m(indo)n(ws)g(the)g(TMP)208 5021 y(is)31 b(used.)57 b(The)30 b(speci\002c)h(beha)n(vior)e(of)i (this)g(function)e(depends)g(on)i(the)g(C)g(library)f(implementation;)k (some)d(aspects)g(are)208 5120 y(underspeci\002ed)d(in)j(system)h (documentation.)54 b FL(W)-5 b(ar)o(ning:)46 b FN(Use)31 b(of)g FJ(tempnam\(\))f FN(is)i(vulnerable)d(to)i(symlink)f(attacks;) 208 5220 y(consider)19 b(using)g FJ(tmpfile\(\))g FN(\(section)h (14.1.2\))e(instead.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)p 0 5549 3901 4 v 0 5649 a FI(406)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 407 419 TeXDict begin 407 418 bop 0 83 a FD(tmpnam)p FJ(\(\))208 183 y FN(Return)24 b(a)h(unique)f(path)g(name)h(that)g(is)h(reasonable) d(for)h(creating)g(a)i(temporary)c(\002le.)40 b(This)25 b(will)h(be)f(an)g(absolute)f(path)g(that)208 282 y(names)i(a)h (potential)f(directory)e(entry)i(in)h(a)g(common)e(location)g(for)h (temporary)f(\002les.)45 b(Applications)25 b(are)i(responsible)e(for) 208 382 y(properly)k(creating)i(and)g(managing)f(\002les)i(created)f (using)h(paths)f(returned)f(by)h FJ(tmpnam\(\))p FN(;)37 b(no)31 b(automatic)g(cleanup)g(is)208 482 y(pro)o(vided.)22 b FL(W)-5 b(ar)o(ning:)24 b FN(Use)d(of)e FJ(tmpnam\(\))g FN(is)i(vulnerable)d(to)i(symlink)g(attacks;)g(consider)f(using)g FJ(tmpfile\(\))g FN(\(section)208 581 y(14.1.2\))g(instead.)28 b(A)-6 b(v)n(ailability:)29 b(U)t FH(N)t(I)t(X)r FN(,)23 b(W)m(indo)n(ws.)28 b(This)22 b(function)d(probably)g(shouldn')o(t)h (be)h(used)g(on)g(W)m(indo)n(ws,)g(though:)208 681 y(Microsoft')-5 b(s)19 b(implementation)f(of)i FJ(tmpnam\(\))f FN(al)o(w)o(ays)i (creates)f(a)h(name)e(in)h(the)h(root)e(directory)f(of)i(the)h(current) d(dri)n(v)o(e,)h(and)208 780 y(that')-5 b(s)20 b(generally)e(a)i(poor)f (location)g(for)g(a)h(temp)f(\002le)i(\(depending)c(on)i(pri)n(vile)o (ges,)f(you)h(may)g(not)h(e)n(v)o(en)f(be)g(able)h(to)g(open)f(a)h (\002le)208 880 y(using)f(this)i(name\).)0 1027 y FD(TMP_MAX)208 1127 y FN(The)e(maximum)g(number)f(of)i(unique)f(names)h(that)g FJ(tmpnam\(\))f FN(will)i(generate)e(before)g(reusing)g(names.)0 1273 y FD(unlink)p FJ(\()p FK(path)p FJ(\))208 1373 y FN(Remo)o(v)o(e)k(the)i(\002le)h FK(path)p FN(.)38 b(This)25 b(is)h(the)f(same)g(function)e(as)j FJ(remove\(\))p FN(;)h(the)e FJ(unlink\(\))f FN(name)g(is)i(its)g(traditional)g(U)t FH(N)t(I)t(X)208 1473 y FN(name.)e(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 1620 y FD(utime)p FJ(\()p FK(path,)d(times)p FJ(\))208 1719 y FN(Set)29 b(the)g(access)g(and)f(modi\002ed)g(times)h(of)g(the)f (\002le)i(speci\002ed)e(by)h FK(path)p FN(.)49 b(If)29 b FK(times)h FN(is)f FJ(None)p FN(,)i(then)d(the)h(\002le')-5 b(s)30 b(access)f(and)208 1819 y(modi\002ed)19 b(times)i(are)g(set)h (to)f(the)g(current)e(time.)27 b(Otherwise,)21 b FK(times)g FN(must)g(be)g(a)g(2-tuple)f(of)g(numbers,)g(of)g(the)h(form)f FJ(\()p FK(atime)p FJ(,)208 1918 y FK(mtime)p FJ(\))j FN(which)f(is)i(used)f(to)g(set)h(the)f(access)h(and)e(modi\002ed)g (times,)i(respecti)n(v)o(ely)-5 b(.)31 b(Whether)23 b(a)g(directory)f (can)g(be)h(gi)n(v)o(en)f(for)208 2018 y FK(path)17 b FN(depends)g(on)h(whether)g(the)h(operating)d(system)j(implements)e (directories)h(as)h(\002les)h(\(for)d(e)o(xample,)g(W)m(indo)n(ws)h (does)g(not\).)208 2118 y(Note)27 b(that)g(the)g(e)o(xact)g(times)g (you)g(set)h(here)e(may)h(not)g(be)g(returned)e(by)i(a)h(subsequent)d FJ(stat\(\))i FN(call,)i(depending)c(on)i(the)208 2217 y(resolution)19 b(with)i(which)f(your)f(operating)g(system)h(records)g (access)h(and)f(modi\002cation)f(times;)i(see)h FJ(stat\(\))p FN(.)52 b(Changed)19 b(in)208 2317 y(v)o(ersion)f(2.0:)i(Added)f (support)g(for)h FJ(None)g FN(for)f FK(times)p FN(.)52 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 2464 y FD(walk)p FJ(\()p FK(top)p FC([)p FK(,)d(topdown)p Fn(=True)g FC([)p FK(,)j(onerr)l(or)p Fn(=None)12 b FC(])g(])p FJ(\))208 2563 y(walk\(\))26 b FN(generates)g(the)g(\002le)i(names)e(in)h(a)g(directory)e(tree,)j (by)f(w)o(alking)f(the)g(tree)h(either)g(top)f(do)n(wn)g(or)g(bottom)g (up.)44 b(F)o(or)208 2663 y(each)20 b(directory)f(in)i(the)g(tree)f (rooted)g(at)h(directory)e FK(top)i FN(\(including)d FK(top)j FN(itself\),)f(it)i(yields)f(a)g(3-tuple)e FJ(\()p FK(dirpath)p FJ(,)48 b FK(dirnames)p FJ(,)208 2763 y FK(\002lenames)p FJ(\))p FN(.)208 2895 y FK(dirpath)26 b FN(is)j(a)f(string,)i(the)d(path)h(to)g(the)f(directory)-5 b(.)46 b FK(dirnames)27 b FN(is)i(a)f(list)h(of)f(the)g(names)f(of)h (the)f(subdirectories)g(in)h FK(dirpath)208 2995 y FN(\(e)o(xcluding)19 b FJ('.')30 b FN(and)22 b FJ('..')p FN(\).)29 b FK(\002lenames)22 b FN(is)g(a)h(list)g(of)f(the)g(names)f(of)h(the)g(non-directory)c (\002les)23 b(in)f FK(dirpath)p FN(.)30 b(Note)21 b(that)i(the)208 3095 y(names)18 b(in)i(the)f(lists)h(contain)e(no)h(path)f(components.) 23 b(T)-7 b(o)19 b(get)g(a)g(full)g(path)g(\(which)f(be)o(gins)g(with)i FK(top)p FN(\))e(to)h(a)h(\002le)f(or)g(directory)e(in)208 3194 y FK(dirpath)p FN(,)i(do)g FJ(os.path.join\()p FK(dirpath)p FJ(,)46 b FK(name)p FJ(\))p FN(.)208 3327 y(If)19 b(optional)g(ar)o (gument)e FK(topdown)h FN(is)j(true)e(or)h(not)f(speci\002ed,)g(the)h (triple)g(for)f(a)h(directory)e(is)i(generated)e(before)h(the)g (triples)h(for)208 3427 y(an)o(y)k(of)h(its)h(subdirectories)e (\(directories)g(are)h(generated)f(top)h(do)n(wn\).)39 b(If)25 b FK(topdown)f FN(is)i(f)o(alse,)h(the)e(triple)h(for)e(a)i (directory)e(is)208 3526 y(generated)18 b(after)i(the)g(triples)g(for)g (all)h(of)f(its)h(subdirectories)d(\(directories)h(are)h(generated)f (bottom)g(up\).)208 3659 y(When)f FK(topdown)f FN(is)i(true,)g(the)f (caller)h(can)f(modify)f(the)h FK(dirnames)g FN(list)i(in-place)d (\(perhaps)g(using)h FJ(del)h FN(or)f(slice)h(assignment\),)208 3759 y(and)26 b FJ(walk\(\))h FN(will)h(only)f(recurse)g(into)g(the)g (subdirectories)f(whose)h(names)g(remain)g(in)g FK(dirnames)p FN(;)k(this)d(can)f(be)g(used)g(to)208 3859 y(prune)f(the)i(search,)i (impose)d(a)i(speci\002c)f(order)f(of)h(visiting,)i(or)e(e)n(v)o(en)f (to)h(inform)f FJ(walk\(\))g FN(about)g(directories)g(the)i(caller)208 3958 y(creates)20 b(or)g(renames)g(before)f(it)i(resumes)f FJ(walk\(\))g FN(again.)k(Modifying)18 b FK(dirnames)i FN(when)g FK(topdown)f FN(is)i(f)o(alse)g(is)h(inef)n(fecti)n(v)o(e,) 208 4058 y(because)d(in)h(bottom-up)e(mode)h(the)i(directories)e(in)h FK(dirnames)g FN(are)g(generated)e(before)h FK(dirpath)g FN(itself)i(is)g(generated.)208 4191 y(By)c(def)o(ault)e(errors)h(from) f(the)i FJ(os.listdir\(\))e FN(call)i(are)f(ignored.)22 b(If)16 b(optional)g(ar)o(gument)e FK(onerr)l(or)k FN(is)g (speci\002ed,)e(it)i(should)208 4290 y(be)g(a)g(function;)f(it)i(will)g (be)f(called)g(with)g(one)f(ar)o(gument,)f(an)i FJ(OSError)g FN(instance.)23 b(It)c(can)f(report)f(the)h(error)f(to)h(continue)e (with)208 4390 y(the)i(w)o(alk,)h(or)g(raise)g(the)g(e)o(xception)e(to) i(abort)f(the)g(w)o(alk.)25 b(Note)19 b(that)g(the)f(\002lename)h(is)g (a)n(v)n(ailable)g(as)g(the)g FJ(filename)f FN(attrib)n(ute)208 4490 y(of)h(the)i(e)o(xception)d(object.)208 4622 y FL(Note:)44 b FN(If)30 b(you)f(pass)h(a)h(relati)n(v)o(e)e(pathname,)i(don')o(t)d (change)h(the)h(current)f(w)o(orking)g(directory)f(between)h (resumptions)g(of)208 4722 y FJ(walk\(\))p FN(.)24 b FJ(walk\(\))c FN(ne)n(v)o(er)e(changes)i(the)g(current)f(directory)-5 b(,)17 b(and)j(assumes)h(that)f(its)h(caller)f(doesn')o(t)f(either)-5 b(.)208 4855 y FL(Note:)23 b FN(On)17 b(systems)i(that)f(support)e (symbolic)h(links,)h(links)g(to)g(subdirectories)e(appear)g(in)i FK(dirnames)f FN(lists,)j(b)n(ut)e FJ(walk\(\))f FN(will)208 4954 y(not)k(visit)i(them)f(\(in\002nite)f(loops)h(are)g(hard)f(to)h(a) n(v)n(oid)g(when)f(follo)n(wing)g(symbolic)g(links\).)30 b(T)-7 b(o)22 b(visit)h(link)o(ed)e(directories,)g(you)208 5054 y(can)f(identify)f(them)g(with)i FJ(os.path.islink\()p FK(path)p FJ(\))p FN(,)16 b(and)k(in)m(v)n(ok)o(e)e FJ(walk\()p FK(path)p FJ(\))h FN(on)g(each)h(directly)-5 b(.)208 5187 y(This)29 b(e)o(xample)g(displays)g(the)h(number)e(of)h(bytes)h (tak)o(en)f(by)h(non-directory)c(\002les)31 b(in)e(each)h(directory)e (under)g(the)i(starting)208 5287 y(directory)-5 b(,)17 b(e)o(xcept)j(that)g(it)h(doesn')o(t)d(look)i(under)f(an)o(y)g(CVS)i (subdirectory:)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o(ating)g(system)e(interf)n (aces)1736 b(407)p eop end %%Page: 408 420 TeXDict begin 408 419 bop 444 174 a FA(import)44 b(os)444 266 y(from)g(os.path)g(import)f(join,)h(getsize)444 357 y(for)g(root,)g(dirs,)g(files)g(in)h(os.walk\('python/Lib/email'\):)623 448 y(print)f(root,)g("consumes",)623 540 y(print)g (sum\(getsize\(join\(root,)d(name\)\))j(for)g(name)h(in)f(files\),)623 631 y(print)g("bytes)g(in",)g(len\(files\),)f("non-directory)g(files") 623 722 y(if)i('CVS')f(in)g(dirs:)802 814 y(dirs.remove\('CVS'\))87 b(#)45 b(don't)f(visit)g(CVS)g(directories)208 1003 y FN(In)17 b(the)g(ne)o(xt)g(e)o(xample,)f(w)o(alking)h(the)h(tree)f (bottom)g(up)g(is)h(essential:)24 b FJ(rmdir\(\))17 b FN(doesn')o(t)f(allo)n(w)i(deleting)e(a)i(directory)e(before)208 1103 y(the)k(directory)e(is)j(empty:)444 1327 y FA(#)44 b(Delete)g(everything)f(reachable)h(from)g(the)g(directory)g(named)g (in)g('top',)444 1418 y(#)g(assuming)g(there)g(are)g(no)h(symbolic)e (links.)444 1510 y(#)h(CAUTION:)89 b(This)44 b(is)g(dangerous!)88 b(For)45 b(example,)e(if)i(top)f(==)h('/',)f(it)444 1601 y(#)g(could)g(delete)g(all)h(your)f(disk)g(files.)444 1692 y(import)g(os)444 1783 y(for)g(root,)g(dirs,)g(files)g(in)h (os.walk\(top,)d(topdown=False\):)623 1875 y(for)i(name)h(in)f(files:) 802 1966 y(os.remove\(os.path.join\(root,)d(name\)\))623 2057 y(for)j(name)h(in)f(dirs:)802 2149 y (os.rmdir\(os.path.join\(root,)d(name\)\))208 2338 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2623 y Fv(14.1.5)101 b(Process)28 b(Management)0 2826 y FN(These)20 b(functions)f(may)g(be)i (used)f(to)g(create)g(and)f(manage)g(processes.)0 2973 y(The)k(v)n(arious)f FJ(exec)619 2988 y(*)669 2973 y(\(\))g FN(functions)g(tak)o(e)h(a)g(list)h(of)f(ar)o(guments)e(for)h(the)h(ne) n(w)g(program)e(loaded)h(into)h(the)g(process.)33 b(In)23 b(each)f(case,)0 3073 y(the)f(\002rst)g(of)g(these)f(ar)o(guments)f(is) j(passed)e(to)h(the)g(ne)n(w)f(program)f(as)i(its)h(o)n(wn)e(name)g (rather)g(than)g(as)h(an)g(ar)o(gument)d(a)j(user)g(may)f(ha)n(v)o(e)0 3172 y(typed)f(on)h(a)h(command)d(line.)25 b(F)o(or)20 b(the)g(C)h(programmer)m(,)c(this)k(is)g(the)f FJ(argv[0])f FN(passed)h(to)h(a)g(program')-5 b(s)18 b FJ(main\(\))p FN(.)24 b(F)o(or)c(e)o(xample,)0 3272 y(`)p FJ(os.execv\('/bin/echo',) 46 b(['foo',)i('bar']\))p FN(')24 b(will)i(only)e(print)h(`)p FJ(bar)p FN(')f(on)h(standard)f(output;)i(`)p FJ(foo)p FN(')f(will)g(seem)0 3371 y(to)20 b(be)g(ignored.)0 3518 y FD(abort)p FJ(\(\))208 3618 y FN(Generate)33 b(a)i FJ(SIGABRT)f FN(signal)h(to)f(the)h(current)e(process.)68 b(On)36 b(U)t FH(N)t(I)t(X)r FN(,)j(the)c(def)o(ault)e(beha)n(vior)g (is)j(to)f(produce)d(a)j(core)208 3718 y(dump;)d(on)c(W)m(indo)n(ws,)i (the)f(process)g(immediately)e(returns)h(an)h(e)o(xit)g(code)f(of)g FJ(3)p FN(.)52 b(Be)29 b(a)o(w)o(are)g(that)g(programs)e(which)h(use) 208 3817 y FJ(signal.signal\(\))h FN(to)i(re)o(gister)g(a)g(handler)f (for)h FJ(SIGABRT)f FN(will)i(beha)n(v)o(e)f(dif)n(ferently)-5 b(.)55 b(A)-6 b(v)n(ailability:)47 b(Macintosh,)210 3917 y(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)0 4064 y FD(execl)p FJ(\()p FK(path,)d(ar)m(g0,)h(ar)m(g1,)h(...)p FJ(\))0 4163 y FD(execle)p FJ(\()p FK(path,)e(ar)m(g0,)h(ar)m(g1,)g (...,)h(en)m(v)p FJ(\))0 4263 y FD(execlp)p FJ(\()p FK(\002le)o(,)f(ar) m(g0,)g(ar)m(g1,)g(...)p FJ(\))0 4363 y FD(execlpe)p FJ(\()p FK(\002le)o(,)g(ar)m(g0,)g(ar)m(g1,)g(...,)h(en)m(v)p FJ(\))0 4462 y FD(execv)p FJ(\()p FK(path,)e(ar)m(gs)p FJ(\))0 4562 y FD(execve)p FJ(\()p FK(path,)g(ar)m(gs,)i(en)m(v)p FJ(\))0 4661 y FD(execvp)p FJ(\()p FK(\002le)o(,)f(ar)m(gs)p FJ(\))0 4761 y FD(execvpe)p FJ(\()p FK(\002le)o(,)g(ar)m(gs,)h(en)m(v)p FJ(\))208 4861 y FN(These)e(functions)f(all)j(e)o(x)o(ecute)d(a)i(ne)n (w)g(program,)d(replacing)i(the)g(current)g(process;)h(the)o(y)f(do)g (not)g(return.)24 b(On)c(U)t FH(N)t(I)t(X)r FN(,)g(the)f(ne)n(w)208 4960 y(e)o(x)o(ecutable)24 b(is)j(loaded)e(into)i(the)f(current)f (process,)i(and)f(will)h(ha)n(v)o(e)f(the)g(same)h(process)f(ID)g(as)h (the)f(caller)-5 b(.)44 b(Errors)26 b(will)h(be)208 5060 y(reported)18 b(as)j FJ(OSError)e FN(e)o(xceptions.)208 5193 y(The)g(`)p FJ(l)p FN(')h(and)f(`)p FJ(v)p FN(')h(v)n(ariants)f (of)h(the)g FJ(exec)1442 5208 y(*)1492 5193 y(\(\))f FN(functions)g(dif)n(fer)g(in)h(ho)n(w)f(command-line)f(ar)o(guments)g (are)h(passed.)25 b(The)20 b(`)p FJ(l)p FN(')208 5292 y(v)n(ariants)h(are)h(perhaps)f(the)h(easiest)h(to)f(w)o(ork)g(with)g (if)h(the)f(number)e(of)i(parameters)f(is)i(\002x)o(ed)e(when)h(the)g (code)g(is)h(written;)g(the)208 5392 y(indi)n(vidual)e(parameters)h (simply)h(become)f(additional)g(parameters)h(to)g(the)g FJ(execl)2694 5407 y(*)2744 5392 y(\(\))g FN(functions.)33 b(The)23 b(`)p FJ(v)p FN(')g(v)n(ariants)g(are)p 0 5549 3901 4 v 0 5649 a FI(408)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 409 421 TeXDict begin 409 420 bop 208 83 a FN(good)21 b(when)h(the)g(number)f (of)i(parameters)e(is)i(v)n(ariable,)f(with)h(the)g(ar)o(guments)d (being)i(passed)g(in)h(a)g(list)h(or)e(tuple)h(as)g(the)f FK(ar)m(gs)208 183 y FN(parameter)-5 b(.)30 b(In)21 b(either)h(case,)h (the)f(ar)o(guments)f(to)h(the)g(child)g(process)g(should)f(start)i (with)f(the)g(name)g(of)g(the)g(command)f(being)208 282 y(run,)e(b)n(ut)h(this)h(is)g(not)f(enforced.)208 415 y(The)f(v)n(ariants)h(which)f(include)g(a)i(`)p FJ(p)p FN(')e(near)h(the)g(end)g(\()p FJ(execlp\(\))p FN(,)e FJ(execlpe\(\))p FN(,)h FJ(execvp\(\))p FN(,)g(and)g FJ(execvpe\(\))p FN(\))g(will)208 515 y(use)k(the)g(P)-8 b(A)f(TH)23 b(en)m(vironment)d(v)n(ariable)i(to)h(locate)g(the)f (program)f FK(\002le)p FN(.)33 b(When)23 b(the)g(en)m(vironment)d(is)k (being)e(replaced)f(\(using)208 614 y(one)f(of)i(the)f FJ(exec)764 629 y(*)814 614 y(e\(\))g FN(v)n(ariants,)g(discussed)g(in) h(the)f(ne)o(xt)g(paragraph\),)e(the)i(ne)n(w)g(en)m(vironment)e(is)j (used)f(as)i(the)e(source)g(of)208 714 y(the)k(P)-8 b(A)f(TH)25 b(v)n(ariable.)38 b(The)25 b(other)f(v)n(ariants,)i FJ(execl\(\))p FN(,)f FJ(execle\(\))p FN(,)g FJ(execv\(\))p FN(,)g(and)g FJ(execve\(\))p FN(,)g(will)h(not)e(use)i(the)208 814 y(P)-8 b(A)f(TH)20 b(v)n(ariable)f(to)i(locate)f(the)g(e)o(x)o (ecutable;)e FK(path)i FN(must)g(contain)f(an)h(appropriate)e(absolute) h(or)h(relati)n(v)o(e)g(path.)208 946 y(F)o(or)d FJ(execle\(\))p FN(,)f FJ(execlpe\(\))p FN(,)h FJ(execve\(\))p FN(,)f(and)h FJ(execvpe\(\))f FN(\(note)h(that)g(these)h(all)g(end)f(in)g(`)p FJ(e)p FN('\),)g(the)g FK(en)m(v)g FN(parameter)208 1046 y(must)31 b(be)h(a)g(mapping)e(which)h(is)i(used)e(to)h(de\002ne)f(the) h(en)m(vironment)d(v)n(ariables)h(for)i(the)f(ne)n(w)h(process;)37 b(the)32 b FJ(execl\(\))p FN(,)208 1146 y FJ(execlp\(\))p FN(,)c FJ(execv\(\))p FN(,)g(and)f FJ(execvp\(\))g FN(all)h(cause)g (the)f(ne)n(w)h(process)f(to)h(inherit)f(the)g(en)m(vironment)e(of)i (the)h(current)208 1245 y(process.)c(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 1392 y FD(_exit)p FJ(\()p FK(n)p FJ(\))208 1492 y FN(Exit)31 b(to)g(the)g(system)g(with)g(status)h FK(n)p FN(,)h(without)e(calling)f (cleanup)g(handlers,)i(\003ushing)e(stdio)h(b)n(uf)n(fers,)i(etc.)57 b(A)-6 b(v)n(ailability:)208 1591 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 1724 y FL(Note:)h FN(The)c(standard)e(w)o(ay)h(to)h(e)o(xit)f(is)h FJ(sys.exit\()p FK(n)p FJ(\))p FN(.)k FJ(_exit\(\))17 b FN(should)f(normally)g(only)h (be)g(used)g(in)h(the)f(child)g(process)208 1824 y(after)i(a)i FJ(fork\(\))p FN(.)0 1971 y(The)k(follo)n(wing)f(e)o(xit)i(codes)f(are) g(a)h(de\002ned,)g(and)f(can)g(be)h(used)f(with)h FJ(_exit\(\))p FN(,)g(although)d(the)o(y)i(are)h(not)f(required.)39 b(These)26 b(are)0 2070 y(typically)g(used)g(for)g(system)g(programs)f (written)h(in)g(Python,)h(such)f(as)h(a)g(mail)g(serv)o(er')-5 b(s)26 b(e)o(xternal)f(command)f(deli)n(v)o(ery)h(program.)0 2170 y FL(Note:)30 b FN(Some)22 b(of)h(these)g(may)g(not)f(be)h(a)n(v)n (ailable)f(on)h(all)i(U)t FH(N)t(I)t(X)h FN(platforms,)d(since)g(there) f(is)i(some)f(v)n(ariation.)31 b(These)23 b(constants)g(are)0 2270 y(de\002ned)c(where)h(the)o(y)f(are)h(de\002ned)g(by)f(the)i (underlying)c(platform.)0 2417 y FD(EX_OK)208 2516 y FN(Exit)j(code)f(that)h(means)g(no)g(error)f(occurred.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 2663 y FD(EX_USAGE)208 2763 y FN(Exit)28 b(code)f(that)i(means)f(the)g (command)f(w)o(as)i(used)f(incorrectly)-5 b(,)28 b(such)g(as)h(when)e (the)i(wrong)e(number)f(of)i(ar)o(guments)f(are)208 2862 y(gi)n(v)o(en.)c(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3009 y FD(EX_DATAERR)208 3109 y FN(Exit)h(code)f(that)h(means)g(the)h (input)e(data)h(w)o(as)h(incorrect.)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3256 y FD(EX_NOINPUT)208 3355 y FN(Exit)24 b(code)f(that)h(means)g(an)g(input)f(\002le)i(did)e(not)h (e)o(xist)g(or)g(w)o(as)h(not)f(readable.)35 b(A)-6 b(v)n(ailability:) 32 b(Macintosh,)25 b(U)t FH(N)t(I)t(X)r FN(.)75 b(Ne)n(w)24 b(in)208 3455 y(v)o(ersion)18 b(2.3.)0 3602 y FD(EX_NOUSER)208 3701 y FN(Exit)i(code)f(that)h(means)g(a)h(speci\002ed)f(user)g(did)g (not)g(e)o(xist.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3848 y FD(EX_NOHOST)208 3948 y FN(Exit)h(code)f(that)h(means)g(a)h (speci\002ed)f(host)g(did)g(not)g(e)o(xist.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.3.)0 4095 y FD(EX_UNAVAILABLE)208 4194 y FN(Exit)g(code)g(that)g(means)g(that)h(a)g (required)d(service)i(is)i(una)n(v)n(ailable.)j(A)-6 b(v)n(ailability:)23 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)50 b(Ne)n(w)19 b(in)f(v)o(ersion)f(2.3.)0 4341 y FD(EX_SOFTWARE)208 4441 y FN(Exit)22 b(code)f(that)h(means)g(an)g (internal)f(softw)o(are)h(error)f(w)o(as)i(detected.)30 b(A)-6 b(v)n(ailability:)28 b(Macintosh,)23 b(U)t FH(N)t(I)t(X)r FN(.)63 b(Ne)n(w)23 b(in)f(v)o(ersion)208 4541 y(2.3.)0 4687 y FD(EX_OSERR)208 4787 y FN(Exit)29 b(code)h(that)g(means)f(an)h (operating)e(system)i(error)f(w)o(as)h(detected,)i(such)d(as)i(the)f (inability)f(to)h(fork)f(or)g(create)h(a)g(pipe.)208 4887 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 5034 y FD(EX_OSFILE)208 5133 y FN(Exit)29 b(code)f(that)i(means)f(some)g (system)g(\002le)h(did)f(not)g(e)o(xist,)j(could)c(not)h(be)g(opened,)h (or)f(had)f(some)i(other)e(kind)g(of)h(error)-5 b(.)208 5233 y(A)f(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 5380 y FD(EX_CANTCREAT)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o(ating)g(system)e(interf)n (aces)1736 b(409)p eop end %%Page: 410 422 TeXDict begin 410 421 bop 208 83 a FN(Exit)21 b(code)g(that)g(means)g (a)h(user)g(speci\002ed)f(output)f(\002le)i(could)f(not)g(be)g (created.)28 b(A)-6 b(v)n(ailability:)27 b(Macintosh,)22 b(U)t FH(N)t(I)t(X)r FN(.)60 b(Ne)n(w)21 b(in)208 183 y(v)o(ersion)d(2.3.)0 330 y FD(EX_IOERR)208 429 y FN(Exit)h(code)g (that)h(means)f(that)h(an)f(error)f(occurred)g(while)i(doing)e(I/O)i (on)f(some)g(\002le.)26 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)208 529 y(in)20 b(v)o(ersion)f(2.3.)0 676 y FD(EX_TEMPFAIL)208 775 y FN(Exit)26 b(code)f(that)h(means)g(a)g (temporary)e(f)o(ailure)h(occurred.)41 b(This)26 b(indicates)g (something)e(that)i(may)g(not)g(really)f(be)h(an)g(error)m(,)208 875 y(such)k(as)h(a)g(netw)o(ork)e(connection)f(that)j(couldn')o(t)d (be)j(made)e(during)g(a)i(retryable)e(operation.)54 b(A)-6 b(v)n(ailability:)45 b(Macintosh,)210 975 y(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1121 y FD(EX_PROTOCOL)208 1221 y FN(Exit)j(code)g(that)g(means)g(that)h(a)f (protocol)f(e)o(xchange)f(w)o(as)j(ille)o(gal,)g(in)m(v)n(alid,)e(or)h (not)g(understood.)29 b(A)-6 b(v)n(ailability:)29 b(Macintosh,)210 1321 y(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.) 0 1468 y FD(EX_NOPERM)208 1567 y FN(Exit)i(code)f(that)h(means)g(that)g (there)f(were)h(insuf)n(\002cient)f(permissions)g(to)i(perform)d(the)i (operation)e(\(b)n(ut)h(not)h(intended)f(for)g(\002le)208 1667 y(system)g(problems\).)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 1814 y FD(EX_CONFIG)208 1913 y FN(Exit)j(code)g(that)h(means)g(that)f(some)h(kind)f(of)g (con\002guration)f(error)g(occurred.)31 b(A)-6 b(v)n(ailability:)29 b(Macintosh,)24 b(U)t FH(N)t(I)t(X)r FN(.)67 b(Ne)n(w)23 b(in)208 2013 y(v)o(ersion)18 b(2.3.)0 2160 y FD(EX_NOTFOUND)208 2259 y FN(Exit)h(code)f(that)i(means)f(something)e(lik)o(e)j(\223an)f (entry)f(w)o(as)i(not)f(found\224.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)19 b(in)h(v)o(ersion)208 2359 y(2.3.)0 2506 y FD(fork)p FJ(\(\))208 2606 y FN(F)o(ork)f(a)i(child)e(process.)25 b(Return)20 b FJ(0)g FN(in)g(the)h(child,)e(the)h(child')-5 b(s)21 b(process)e(id)i(in)f(the)g(parent.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 2752 y FD(forkpty)p FJ(\(\))208 2852 y FN(F)o(ork)j(a)h(child)f(process,)i(using)e(a)i(ne)n (w)e(pseudo-terminal)e(as)k(the)f(child')-5 b(s)25 b(controlling)e (terminal.)38 b(Return)24 b(a)i(pair)e(of)h FJ(\()p FK(pid)r FJ(,)208 2952 y FK(fd)r FJ(\))p FN(,)18 b(where)f FK(pid)j FN(is)f FJ(0)f FN(in)g(the)g(child,)g(the)g(ne)n(w)g(child')-5 b(s)18 b(process)f(id)h(in)g(the)g(parent,)f(and)h FK(fd)i FN(is)f(the)f(\002le)h(descriptor)d(of)i(the)g(master)208 3051 y(end)h(of)g(the)h(pseudo-terminal.)i(F)o(or)d(a)h(more)f (portable)f(approach,)g(use)h(the)h FJ(pty)g FN(module.)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)19 b(Some)208 3151 y(\003a)n(v)n(ors)h(of)i(U)t FH(N)t(I)t(X)r FN(.)0 3298 y FD(kill)p FJ(\()p FK(pid,)d(sig)p FJ(\))208 3397 y FN(Send)j(signal)g FK(sig)h FN(to)g(the)g(process)f FK(pid)r FN(.)32 b(Constants)22 b(for)g(the)h(speci\002c)g(signals)g(a)n(v)n (ailable)f(on)g(the)g(host)h(platform)e(are)i(de\002ned)208 3497 y(in)d(the)g FJ(signal)g FN(module.)j(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 3644 y FD(killpg)p FJ(\()p FK(pgid,)d(sig)p FJ(\))208 3744 y FN(Send)h(the)i(signal)f FK(sig)g FN(to)h(the)f(process)g(group)e FK(pgid)r FN(.)24 b(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3890 y FD(nice)p FJ(\()p FK(incr)m(ement)q FJ(\))208 3990 y FN(Add)g FK(incr)m(ement)i FN(to)g(the)f(process')-5 b(s)20 b(\223niceness\224.)25 b(Return)19 b(the)i(ne)n(w)f(niceness.)k (A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 4137 y FD(plock)p FJ(\()p FK(op)p FJ(\))208 4237 y FN(Lock)k(program)e(se)o(gments)i(into)h(memory)-5 b(.)40 b(The)25 b(v)n(alue)h(of)f FK(op)h FN(\(de\002ned)e(in)i FJ(<sys/lock.h>)p FN(\))e(determines)h(which)g(se)o(g-)208 4336 y(ments)20 b(are)g(lock)o(ed.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 4483 y FD(popen)p FJ(\()p FK(...)p FJ(\))0 4583 y FD(popen2)p FJ(\()p FK(...)p FJ(\))0 4682 y FD(popen3)p FJ(\()p FK(...)p FJ(\))0 4782 y FD(popen4)p FJ(\()p FK(...)p FJ(\))208 4882 y FN(Run)30 b(child)h(processes,)i(returning)28 b(opened)i(pipes)g(for)g (communications.)55 b(These)30 b(functions)g(are)g(described)g(in)h (section)208 4981 y(14.1.2.)0 5128 y FD(spawnl)p FJ(\()p FK(mode)o(,)18 b(path,)h(...)p FJ(\))0 5228 y FD(spawnle)p FJ(\()p FK(mode)o(,)f(path,)h(...,)h(en)m(v)p FJ(\))0 5327 y FD(spawnlp)p FJ(\()p FK(mode)o(,)e(\002le)o(,)i(...)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(410)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 411 423 TeXDict begin 411 422 bop 0 83 a FD(spawnlpe)p FJ(\()p FK(mode)o(,)18 b(\002le)o(,)i(...,)g(en)m(v)p FJ(\))0 183 y FD(spawnv)p FJ(\()p FK(mode)o(,)e(path,)h(ar)m(gs)p FJ(\))0 282 y FD(spawnve)p FJ(\()p FK(mode)o(,)f(path,)h(ar)m(gs,)h(en) m(v)p FJ(\))0 382 y FD(spawnvp)p FJ(\()p FK(mode)o(,)e(\002le)o(,)i(ar) m(gs)p FJ(\))0 482 y FD(spawnvpe)p FJ(\()p FK(mode)o(,)e(\002le)o(,)i (ar)m(gs,)g(en)m(v)p FJ(\))208 581 y FN(Ex)o(ecute)e(the)j(program)d FK(path)h FN(in)h(a)h(ne)n(w)f(process.)208 714 y(\(Note)d(that)i(the)f FJ(subprocess)f FN(module)f(pro)o(vides)h(more)g(po)n(werful)f(f)o (acilities)j(for)f(spa)o(wning)e(ne)n(w)i(processes)g(and)g(retrie)n (v-)208 814 y(ing)h(their)h(results;)h(using)f(that)g(module)f(is)i (preferable)d(to)i(using)g(these)g(functions.\))208 946 y(If)27 b FK(mode)f FN(is)i FJ(P_NOWAIT)p FN(,)e(this)i(function)d (returns)i(the)g(process)f(ID)i(of)f(the)g(ne)n(w)g(process;)j(if)d FK(mode)g FN(is)h FJ(P_WAIT)p FN(,)e(returns)208 1046 y(the)h(process')-5 b(s)27 b(e)o(xit)g(code)f(if)i(it)g(e)o(xits)f (normally)-5 b(,)26 b(or)h FJ(-)p FK(signal)p FN(,)h(where)f FK(signal)g FN(is)h(the)f(signal)g(that)g(killed)g(the)g(process.)46 b(On)208 1146 y(W)m(indo)n(ws,)19 b(the)h(process)g(ID)g(will)h (actually)f(be)g(the)g(process)g(handle,)f(so)h(can)g(be)g(used)g(with) h(the)f FJ(waitpid\(\))f FN(function.)208 1279 y(The)k(`)p FJ(l)p FN(')h(and)g(`)p FJ(v)p FN(')g(v)n(ariants)g(of)g(the)g FJ(spawn)1522 1294 y(*)1572 1279 y(\(\))f FN(functions)g(dif)n(fer)g (in)h(ho)n(w)g(command-line)e(ar)o(guments)g(are)i(passed.)37 b(The)208 1378 y(`)p FJ(l)p FN(')21 b(v)n(ariants)h(are)f(perhaps)g (the)h(easiest)h(to)f(w)o(ork)g(with)g(if)g(the)g(number)e(of)i (parameters)f(is)i(\002x)o(ed)e(when)g(the)h(code)g(is)h(written;)208 1478 y(the)d(indi)n(vidual)e(parameters)h(simply)g(become)g(additional) g(parameters)f(to)j(the)f FJ(spawnl)2840 1493 y(*)2890 1478 y(\(\))e FN(functions.)24 b(The)c(`)p FJ(v)p FN(')f(v)n(ariants) 208 1577 y(are)24 b(good)g(when)g(the)g(number)f(of)i(parameters)e(is)j (v)n(ariable,)f(with)g(the)f(ar)o(guments)f(being)h(passed)g(in)h(a)g (list)h(or)f(tuple)f(as)i(the)208 1677 y FK(ar)m(gs)h FN(parameter)-5 b(.)45 b(In)26 b(either)h(case,)i(the)e(ar)o(guments)f (to)h(the)g(child)g(process)g(must)g(start)g(with)h(the)f(name)g(of)f (the)i(command)208 1777 y(being)19 b(run.)208 1910 y(The)37 b(v)n(ariants)g(which)h(include)f(a)h(second)f(`)p FJ(p)p FN(')h(near)f(the)h(end)g(\()p FJ(spawnlp\(\))p FN(,)i FJ(spawnlpe\(\))p FN(,)h FJ(spawnvp\(\))p FN(,)g(and)208 2009 y FJ(spawnvpe\(\))p FN(\))28 b(will)k(use)e(the)h(P)-8 b(A)f(TH)31 b(en)m(vironment)c(v)n(ariable)i(to)i(locate)f(the)h (program)d FK(\002le)p FN(.)56 b(When)30 b(the)h(en)m(vironment)208 2109 y(is)26 b(being)f(replaced)f(\(using)h(one)g(of)g(the)h FJ(spawn)1660 2124 y(*)1710 2109 y(e\(\))e FN(v)n(ariants,)i(discussed) g(in)g(the)f(ne)o(xt)g(paragraph\),)f(the)i(ne)n(w)f(en)m(viron-)208 2208 y(ment)e(is)i(used)f(as)h(the)f(source)g(of)f(the)i(P)-8 b(A)f(TH)24 b(v)n(ariable.)36 b(The)24 b(other)f(v)n(ariants,)h FJ(spawnl\(\))p FN(,)g FJ(spawnle\(\))p FN(,)g FJ(spawnv\(\))p FN(,)208 2308 y(and)i FJ(spawnve\(\))p FN(,)h(will)g(not)f(use)h(the)g (P)-8 b(A)f(TH)27 b(v)n(ariable)f(to)h(locate)f(the)h(e)o(x)o (ecutable;)h FK(path)e FN(must)h(contain)e(an)i(appropriate)208 2408 y(absolute)19 b(or)h(relati)n(v)o(e)f(path.)208 2540 y(F)o(or)27 b FJ(spawnle\(\))p FN(,)h FJ(spawnlpe\(\))p FN(,)g FJ(spawnve\(\))p FN(,)g(and)g FJ(spawnvpe\(\))e FN(\(note)h(that)h(these)f(all)i(end)e(in)h(`)p FJ(e)p FN('\),)g(the)g FK(en)m(v)208 2640 y FN(parameter)k(must)i(be)g(a)g (mapping)e(which)h(is)i(used)f(to)g(de\002ne)f(the)h(en)m(vironment)c (v)n(ariables)k(for)f(the)h(ne)n(w)f(process;)41 b(the)208 2740 y FJ(spawnl\(\))p FN(,)18 b FJ(spawnlp\(\))p FN(,)h FJ(spawnv\(\))p FN(,)f(and)h FJ(spawnvp\(\))g FN(all)h(cause)g(the)f (ne)n(w)h(process)f(to)h(inherit)f(the)h(en)m(vironment)208 2839 y(of)f(the)i(current)e(process.)208 2972 y(As)i(an)f(e)o(xample,)e (the)i(follo)n(wing)f(calls)i(to)f FJ(spawnlp\(\))f FN(and)h FJ(spawnvpe\(\))f FN(are)h(equi)n(v)n(alent:)444 3196 y FA(import)44 b(os)444 3288 y(os.spawnlp\(os.P_WAIT,)d('cp',)j('cp',)g ('index.html',)f('/dev/null'\))444 3470 y(L)h(=)h(['cp',)f ('index.html',)f('/dev/null'])444 3562 y(os.spawnvpe\(os.P_WAIT,)e ('cp',)j(L,)g(os.environ\))208 3751 y FN(A)-6 b(v)n(ailability:)36 b(U)t FH(N)t(I)t(X)r FN(,)27 b(W)m(indo)n(ws.)39 b FJ(spawnlp\(\))p FN(,)25 b FJ(spawnlpe\(\))p FN(,)g FJ(spawnvp\(\))f FN(and)g FJ(spawnvpe\(\))g FN(are)h(not)g(a)n(v)n(ail-)208 3851 y(able)20 b(on)f(W)m(indo)n(ws.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f (1.6.)0 3998 y FD(P_NOWAIT)0 4097 y(P_NOWAITO)208 4197 y FN(Possible)g(v)n(alues)g(for)g(the)g FK(mode)g FN(parameter)f(to)i (the)f FJ(spawn)1980 4212 y(*)2030 4197 y(\(\))g FN(f)o(amily)f(of)i (functions.)j(If)c(either)g(of)g(these)h(v)n(alues)f(is)h(gi)n(v)o(en,) 208 4296 y(the)25 b FJ(spawn)585 4311 y(*)635 4296 y(\(\))f FN(functions)g(will)i(return)e(as)i(soon)e(as)i(the)f(ne)n(w)g(process) g(has)g(been)g(created,)g(with)g(the)h(process)e(ID)i(as)g(the)208 4396 y(return)19 b(v)n(alue.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.6.)0 4543 y FD(P_WAIT)208 4643 y FN(Possible)29 b(v)n(alue)g(for)g(the)g FK(mode)g FN(parameter)f(to)i(the)f FJ(spawn)2028 4658 y(*)2078 4643 y(\(\))g FN(f)o(amily)f(of)i(functions.)51 b(If)29 b(this)h(is)g(gi)n(v)o(en)f(as)h FK(mode)p FN(,)h(the)208 4742 y FJ(spawn)458 4757 y(*)508 4742 y(\(\))22 b FN(functions)f(will)j (not)f(return)e(until)i(the)g(ne)n(w)g(process)g(has)g(run)f(to)h (completion)e(and)i(will)h(return)d(the)i(e)o(xit)g(code)208 4842 y(of)k(the)h(process)g(the)g(run)f(is)i(successful,)h(or)d FJ(-)p FK(signal)h FN(if)g(a)h(signal)e(kills)i(the)f(process.)48 b(A)-6 b(v)n(ailability:)40 b(Macintosh,)31 b(U)t FH(N)t(I)t(X)r FN(,)208 4941 y(W)m(indo)n(ws.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(1.6.) 0 5088 y FD(P_DETACH)0 5188 y(P_OVERLAY)208 5288 y FN(Possible)28 b(v)n(alues)f(for)h(the)g FK(mode)f FN(parameter)g(to)h(the)g FJ(spawn)2049 5303 y(*)2099 5288 y(\(\))f FN(f)o(amily)g(of)h (functions.)47 b(These)27 b(are)h(less)h(portable)e(than)208 5387 y(those)c(listed)h(abo)o(v)o(e.)34 b FJ(P_DETACH)23 b FN(is)i(similar)f(to)g FJ(P_NOWAIT)p FN(,)e(b)n(ut)i(the)g(ne)n(w)f (process)g(is)i(detached)d(from)h(the)h(console)f(of)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g (Miscellaneous)h(oper)o(ating)g(system)e(interf)n(aces)1736 b(411)p eop end %%Page: 412 424 TeXDict begin 412 423 bop 208 83 a FN(the)21 b(calling)g(process.)28 b(If)21 b FJ(P_OVERLAY)g FN(is)h(used,)f(the)h(current)e(process)h (will)h(be)f(replaced;)g(the)h FJ(spawn)3302 98 y(*)3352 83 y(\(\))e FN(function)g(will)208 183 y(not)f(return.)24 b(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.6.)0 330 y FD(startfile)p FJ(\()p FK(path)p FC([)p FK(,)e(oper)o(ation)12 b FC(])p FJ(\))208 429 y FN(Start)20 b(a)h(\002le)g(with)f(its)h(associated)f (application.)208 562 y(When)28 b FK(oper)o(ation)f FN(is)i(not)g (speci\002ed)f(or)g FJ('open')p FN(,)i(this)f(acts)h(lik)o(e)f (double-clicking)c(the)k(\002le)g(in)g(W)m(indo)n(ws)f(Explorer)m(,)g (or)208 662 y(gi)n(ving)16 b(the)i(\002le)g(name)g(as)g(an)g(ar)o (gument)e(to)i(the)f FL(start)h FN(command)e(from)g(the)i(interacti)n (v)o(e)f(command)f(shell:)24 b(the)18 b(\002le)g(is)h(opened)208 761 y(with)h(whate)n(v)o(er)f(application)f(\(if)i(an)o(y\))f(its)j(e)o (xtension)c(is)k(associated.)208 894 y(When)27 b(another)g FK(oper)o(ation)f FN(is)j(gi)n(v)o(en,)f(it)g(must)g(be)g(a)g (\223command)e(v)o(erb\224)h(that)h(speci\002es)g(what)g(should)f(be)h (done)e(with)j(the)208 994 y(\002le.)54 b(Common)28 b(v)o(erbs)h (documented)e(by)j(Microsoft)e(are)i FJ('print')f FN(and)g FJ('edit')h FN(\(to)f(be)h(used)f(on)h(\002les\))g(as)h(well)f(as)208 1093 y FJ('explore')19 b FN(and)g FJ('find')h FN(\(to)g(be)g(used)g(on) g(directories\).)208 1226 y FJ(startfile\(\))25 b FN(returns)h(as)h (soon)f(as)i(the)e(associated)h(application)e(is)j(launched.)43 b(There)26 b(is)h(no)g(option)e(to)i(w)o(ait)g(for)g(the)208 1326 y(application)j(to)i(close,)i(and)d(no)g(w)o(ay)h(to)g(retrie)n(v) o(e)f(the)g(application')-5 b(s)31 b(e)o(xit)g(status.)60 b(The)32 b FK(path)f FN(parameter)f(is)i(relati)n(v)o(e)f(to)208 1425 y(the)d(current)f(directory)-5 b(.)48 b(If)29 b(you)e(w)o(ant)i (to)g(use)g(an)f(absolute)g(path,)i(mak)o(e)e(sure)g(the)h(\002rst)g (character)f(is)h(not)f(a)h(slash)h(\(`)p FJ(/)p FN('\);)208 1525 y(the)25 b(underlying)d(W)m(in32)i FJ(ShellExecute\(\))f FN(function)g(doesn')o(t)h(w)o(ork)g(if)i(it)f(is.)41 b(Use)25 b(the)g FJ(os.path.normpath\(\))208 1625 y FN(function)d(to)j (ensure)f(that)h(the)g(path)f(is)h(properly)e(encoded)g(for)h(W)m (in32.)37 b(A)-6 b(v)n(ailability:)34 b(W)m(indo)n(ws.)76 b(Ne)n(w)25 b(in)g(v)o(ersion)e(2.0.)208 1724 y(Ne)n(w)d(in)g(v)o (ersion)f(2.5:)h(The)g FK(oper)o(ation)e FN(parameter)-5 b(.)0 1871 y FD(system)p FJ(\()p FK(command)r FJ(\))208 1971 y FN(Ex)o(ecute)36 b(the)h(command)f(\(a)h(string\))g(in)h(a)f (subshell.)77 b(This)37 b(is)i(implemented)c(by)i(calling)g(the)h (Standard)e(C)i(function)208 2070 y FJ(system\(\))p FN(,)20 b(and)h(has)h(the)g(same)f(limitations.)29 b(Changes)21 b(to)h FJ(posix.environ)p FN(,)d FJ(sys.stdin)p FN(,)i(etc.)h(are)f (not)g(re\003ected)208 2170 y(in)f(the)g(en)m(vironment)d(of)j(the)g(e) o(x)o(ecuted)f(command.)208 2303 y(On)25 b(U)t FH(N)t(I)t(X)r FN(,)g(the)f(return)f(v)n(alue)g(is)h(the)g(e)o(xit)f(status)i(of)e (the)h(process)f(encoded)f(in)h(the)h(format)f(speci\002ed)g(for)g FJ(wait\(\))p FN(.)35 b(Note)208 2402 y(that)21 b(POSIX)h(does)g(not)f (specify)g(the)h(meaning)e(of)h(the)h(return)f(v)n(alue)g(of)g(the)h(C) g FJ(system\(\))f FN(function,)f(so)i(the)g(return)e(v)n(alue)208 2502 y(of)f(the)i(Python)e(function)f(is)j(system-dependent.)208 2635 y(On)c(W)m(indo)n(ws,)f(the)h(return)f(v)n(alue)g(is)i(that)f (returned)e(by)i(the)g(system)g(shell)h(after)e(running)f FK(command)r FN(,)h(gi)n(v)o(en)g(by)g(the)h(W)m(indo)n(ws)208 2734 y(en)m(vironment)k(v)n(ariable)i(COMSPEC:)i(on)f FL(command.com)g FN(systems)h(\(W)m(indo)n(ws)e(95,)i(98)f(and)f(ME\))h (this)h(is)g(al)o(w)o(ays)g FJ(0)p FN(;)i(on)208 2834 y FL(cmd.exe)c FN(systems)i(\(W)m(indo)n(ws)e(NT)-6 b(,)24 b(2000)f(and)h(XP\))g(this)h(is)g(the)f(e)o(xit)g(status)h(of)f(the)g (command)f(run;)i(on)f(systems)g(using)g(a)208 2934 y(non-nati)n(v)o(e) 17 b(shell,)j(consult)g(your)f(shell)i(documentation.)208 3067 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)208 3199 y(The)i FJ(subprocess)g FN(module)f(pro)o(vides)g(more)h(po)n(werful)f(f)o(acilities)j(for)e (spa)o(wning)f(ne)n(w)i(processes)f(and)h(retrie)n(ving)e(their)208 3299 y(results;)e(using)g(that)g(module)f(is)i(preferable)d(to)j(using) e(this)i(function.)0 3446 y FD(times)p FJ(\(\))208 3545 y FN(Return)i(a)g(5-tuple)g(of)g(\003oating)f(point)h(numbers)f (indicating)g(accumulated)g(\(processor)f(or)j(other\))e(times,)i(in)g (seconds.)34 b(The)208 3645 y(items)26 b(are:)38 b(user)26 b(time,)i(system)e(time,)i(children')-5 b(s)25 b(user)h(time,)i (children')-5 b(s)25 b(system)i(time,)g(and)f(elapsed)g(real)g(time)h (since)f(a)208 3745 y(\002x)o(ed)16 b(point)f(in)i(the)g(past,)g(in)g (that)g(order)-5 b(.)23 b(See)17 b(the)i(U)t FH(N)t(I)t(X)g FN(manual)d(page)g FK(times)p FN(\(2\))g(or)h(the)f(corresponding)d(W)m (indo)n(ws)j(Platform)208 3844 y(API)k(documentation.)i(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)0 3991 y FD(wait)p FJ(\(\))208 4091 y FN(W)-7 b(ait)23 b(for)f(completion)f(of)h(a)h(child)f(process,) h(and)f(return)f(a)i(tuple)f(containing)f(its)i(pid)g(and)f(e)o(xit)g (status)h(indication:)29 b(a)23 b(16-bit)208 4190 y(number)m(,)15 b(whose)i(lo)n(w)h(byte)f(is)h(the)f(signal)h(number)d(that)j(killed)f (the)g(process,)h(and)e(whose)i(high)e(byte)h(is)h(the)g(e)o(xit)f (status)h(\(if)g(the)208 4290 y(signal)23 b(number)e(is)j(zero\);)g (the)f(high)f(bit)h(of)g(the)g(lo)n(w)h(byte)e(is)i(set)g(if)g(a)f (core)g(\002le)g(w)o(as)h(produced.)32 b(A)-6 b(v)n(ailability:)30 b(Macintosh,)210 4390 y(U)t FH(N)t(I)t(X)r FN(.)0 4537 y FD(waitpid)p FJ(\()p FK(pid,)18 b(options)p FJ(\))208 4636 y FN(The)h(details)i(of)f(this)h(function)d(dif)n(fer)h(on)j(U)t FH(N)t(I)t(X)h FN(and)d(W)m(indo)n(ws.)208 4769 y(On)30 b(U)t FH(N)t(I)t(X)r FN(:)43 b(W)-7 b(ait)30 b(for)e(completion)f(of)h (a)i(child)e(process)g(gi)n(v)o(en)f(by)i(process)f(id)h FK(pid)r FN(,)h(and)e(return)g(a)h(tuple)f(containing)f(its)208 4869 y(process)e(id)i(and)e(e)o(xit)h(status)h(indication)e(\(encoded)f (as)j(for)f FJ(wait\(\))p FN(\).)42 b(The)26 b(semantics)g(of)g(the)g (call)h(are)f(af)n(fected)f(by)h(the)208 4968 y(v)n(alue)19 b(of)h(the)g(inte)o(ger)f FK(options)p FN(,)g(which)h(should)f(be)h FJ(0)h FN(for)e(normal)g(operation.)208 5101 y(If)e FK(pid)i FN(is)g(greater)e(than)g FJ(0)p FN(,)h FJ(waitpid\(\))e FN(requests)i(status)g(information)d(for)i(that)h(speci\002c)f (process.)24 b(If)17 b FK(pid)j FN(is)e FJ(0)p FN(,)h(the)e(request)208 5201 y(is)k(for)e(the)i(status)g(of)f(an)o(y)f(child)h(in)h(the)f (process)g(group)e(of)i(the)h(current)e(process.)24 b(If)d FK(pid)h FN(is)f FJ(-1)p FN(,)f(the)h(request)e(pertains)h(to)g(an)o(y) 208 5300 y(child)g(of)g(the)h(current)e(process.)26 b(If)21 b FK(pid)h FN(is)g(less)g(than)e FJ(-1)p FN(,)h(status)g(is)h (requested)d(for)h(an)o(y)g(process)g(in)h(the)g(process)f(group)f FJ(-)p FK(pid)208 5400 y FN(\(the)g(absolute)h(v)n(alue)f(of)h FK(pid)r FN(\).)p 0 5549 3901 4 v 0 5649 a FI(412)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 413 425 TeXDict begin 413 424 bop 208 83 a FN(On)21 b(W)m(indo)n(ws:)28 b(W)-7 b(ait)24 b(for)d(completion)f(of)h(a)i(process)e(gi)n(v)o(en)g (by)g(process)h(handle)e FK(pid)r FN(,)i(and)g(return)e(a)i(tuple)g (containing)e FK(pid)r FN(,)208 183 y(and)e(its)h(e)o(xit)f(status)i (shifted)e(left)h(by)f(8)g(bits)h(\(shifting)f(mak)o(es)g (cross-platform)e(use)j(of)f(the)h(function)e(easier\).)24 b(A)19 b FK(pid)h FN(less)g(than)208 282 y(or)g(equal)g(to)h FJ(0)g FN(has)f(no)h(special)f(meaning)f(on)i(W)m(indo)n(ws,)e(and)i (raises)g(an)f(e)o(xception.)25 b(The)20 b(v)n(alue)g(of)g(inte)o(ger)f FK(options)h FN(has)h(no)208 382 y(ef)n(fect.)i FK(pid)e FN(can)e(refer)f(to)h(an)o(y)f(process)g(whose)h(id)g(is)h(kno)n(wn,)d (not)h(necessarily)h(a)g(child)f(process.)24 b(The)19 b FJ(spawn\(\))f FN(functions)208 482 y(called)i(with)g FJ(P_NOWAIT)f FN(return)g(suitable)h(process)g(handles.)0 628 y FD(wait3)p FJ(\()p FC([)p FK(options)12 b FC(])p FJ(\))208 728 y FN(Similar)k(to)g FJ(waitpid\(\))p FN(,)g(e)o(xcept)f (no)h(process)g(id)g(ar)o(gument)e(is)k(gi)n(v)o(en)d(and)g(a)i (3-element)e(tuple)h(containing)e(the)i(child')-5 b(s)17 b(pro-)208 828 y(cess)i(id,)f(e)o(xit)h(status)g(indication,)e(and)g (resource)g(usage)h(information)e(is)k(returned.)i(Refer)c(to)h FJ(resource)p FN(.)p FJ(getrusage\(\))208 927 y FN(for)24 b(details)i(on)f(resource)f(usage)h(information.)39 b(The)25 b(option)f(ar)o(gument)f(is)j(the)g(same)f(as)i(that)e(pro)o(vided)e (to)j FJ(waitpid\(\))208 1027 y FN(and)19 b FJ(wait4\(\))p FN(.)24 b(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1174 y FD(wait4)p FJ(\()p FK(pid,)f(options)p FJ(\))208 1273 y FN(Similar)k(to)h FJ(waitpid\(\))p FN(,)f(e)o(xcept)g(a)h(3-element)e (tuple,)h(containing)f(the)i(child')-5 b(s)22 b(process)h(id,)g(e)o (xit)f(status)h(indication,)f(and)208 1373 y(resource)29 b(usage)g(information)f(is)j(returned.)54 b(Refer)30 b(to)g FJ(resource)p FN(.)p FJ(getrusage\(\))d FN(for)j(details)g(on)g (resource)f(usage)208 1473 y(information.)24 b(The)d(ar)o(guments)e(to) i FJ(wait4\(\))f FN(are)h(the)g(same)h(as)f(those)g(pro)o(vided)e(to)i FJ(waitpid\(\))p FN(.)26 b(A)-6 b(v)n(ailability:)28 b(U)t FH(N)t(I)t(X)r FN(.)208 1572 y(Ne)n(w)20 b(in)g(v)o(ersion)f (2.5.)0 1719 y FD(WNOHANG)208 1819 y FN(The)29 b(option)g(for)g FJ(waitpid\(\))f FN(to)i(return)f(immediately)f(if)i(no)g(child)f (process)g(status)i(is)g(a)n(v)n(ailable)e(immediately)-5 b(.)52 b(The)208 1918 y(function)18 b(returns)h FJ(\(0,)50 b(0\))20 b FN(in)g(this)h(case.)k(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 2065 y FD(WCONTINUED)208 2165 y FN(This)e(option)f(causes)i(child)f(processes)g(to)h(be)g (reported)d(if)j(the)o(y)f(ha)n(v)o(e)g(been)f(continued)g(from)g(a)i (job)f(control)g(stop)g(since)h(their)208 2265 y(status)g(w)o(as)h (last)h(reported.)h(A)-6 b(v)n(ailability:)24 b(Some)e(U)t FH(N)t(I)t(X)h FN(systems.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 2411 y FD(WUNTRACED)208 2511 y FN(This)j(option)f(causes)h(child)g (processes)g(to)h(be)f(reported)e(if)j(the)o(y)e(ha)n(v)o(e)h(been)g (stopped)f(b)n(ut)h(their)g(current)f(state)i(has)f(not)g(been)208 2611 y(reported)c(since)i(the)o(y)g(were)g(stopped.)k(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2758 y(The)g(follo)n (wing)g(functions)f(tak)o(e)i(a)g(process)f(status)i(code)e(as)h (returned)e(by)h FJ(system\(\))p FN(,)g FJ(wait\(\))p FN(,)g(or)h FJ(waitpid\(\))e FN(as)j(a)f(param-)0 2857 y(eter)-5 b(.)25 b(The)o(y)19 b(may)h(be)g(used)g(to)h(determine)d(the) j(disposition)e(of)h(a)g(process.)0 3004 y FD(WCOREDUMP)p FJ(\()p FK(status)p FJ(\))208 3104 y FN(Returns)h FJ(True)h FN(if)g(a)h(core)e(dump)g(w)o(as)h(generated)f(for)g(the)h(process,)g (otherwise)f(it)i(returns)e FJ(False)p FN(.)29 b(A)-6 b(v)n(ailability:)28 b(Macin-)208 3203 y(tosh,)21 b(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3350 y FD(WIFCONTINUED)p FJ(\()p FK(status)p FJ(\))208 3450 y FN(Returns)g FJ(True)g FN(if)g(the)g(process)g(has)h(been)e (continued)g(from)g(a)h(job)g(control)f(stop,)h(otherwise)g(it)h (returns)e FJ(False)p FN(.)25 b(A)-6 b(v)n(ailabil-)208 3549 y(ity:)27 b(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3696 y FD(WIFSTOPPED)p FJ(\()p FK(status)p FJ(\))208 3796 y FN(Returns)h FJ(True)g FN(if)g(the)g (process)g(has)g(been)g(stopped,)f(otherwise)g(it)i(returns)e FJ(False)p FN(.)25 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 3943 y FD(WIFSIGNALED)p FJ(\()p FK(status)p FJ(\))208 4042 y FN(Returns)18 b FJ(True)h FN(if)g(the)g(process)g(e)o(xited)f(due)g(to)i(a)f(signal,)g(otherwise) f(it)i(returns)e FJ(False)p FN(.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 4189 y FD(WIFEXITED)p FJ(\()p FK(status)p FJ(\))208 4289 y FN(Returns)29 b FJ(True)h FN(if)g(the)g(process)g(e)o(xited)f(using)g(the)h FK(e)n(xit)p FN(\(2\))f(system)h(call,)j(otherwise)c(it)i(returns)e FJ(False)p FN(.)53 b(A)-6 b(v)n(ailability:)208 4389 y(Macintosh,)21 b(U)t FH(N)t(I)t(X)r FN(.)0 4535 y FD(WEXITSTATUS)p FJ(\()p FK(status)p FJ(\))208 4635 y FN(If)k FJ(WIFEXITED\()p FK(status)p FJ(\))f FN(is)j(true,)g(return)e(the)g(inte)o(ger)g (parameter)f(to)i(the)g FK(e)n(xit)p FN(\(2\))g(system)g(call.)42 b(Otherwise,)27 b(the)f(return)208 4735 y(v)n(alue)19 b(is)i(meaningless.)j(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 4882 y FD(WSTOPSIG)p FJ(\()p FK(status)p FJ(\))208 4981 y FN(Return)e(the)i(signal)f(which)f(caused)h(the)g (process)g(to)g(stop.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)0 5128 y FD(WTERMSIG)p FJ(\()p FK(status)p FJ(\))208 5228 y FN(Return)e(the)i(signal)f(which)f (caused)h(the)g(process)g(to)g(e)o(xit.)25 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.1.)52 b FJ(os)23 b FI(\227)g(Miscellaneous)h(oper)o (ating)g(system)e(interf)n(aces)1736 b(413)p eop end %%Page: 414 426 TeXDict begin 414 425 bop 0 83 a Fv(14.1.6)101 b(Miscellaneous)29 b(System)f(Inf)m(or)r(mation)0 266 y FD(confstr)p FJ(\()p FK(name)p FJ(\))208 366 y FN(Return)18 b(string-v)n(alued)e(system)j (con\002guration)d(v)n(alues.)24 b FK(name)18 b FN(speci\002es)i(the)e (con\002guration)f(v)n(alue)h(to)h(retrie)n(v)o(e;)f(it)h(may)f(be)h(a) 208 466 y(string)f(which)h(is)h(the)g(name)e(of)h(a)h(de\002ned)e (system)i(v)n(alue;)e(these)i(names)f(are)g(speci\002ed)g(in)g(a)h (number)d(of)i(standards)g(\(POSIX,)210 565 y(U)t FH(N)t(I)t(X)29 b FN(95,)h(U)t FH(N)t(I)t(X)g FN(98,)e(and)e(others\).)44 b(Some)27 b(platforms)f(de\002ne)g(additional)f(names)i(as)h(well.)45 b(The)27 b(names)f(kno)n(wn)g(to)h(the)208 665 y(host)e(operating)f (system)i(are)f(gi)n(v)o(en)f(as)j(the)e(k)o(e)o(ys)h(of)f(the)h FJ(confstr_names)d FN(dictionary)-5 b(.)39 b(F)o(or)25 b(con\002guration)e(v)n(ariables)208 765 y(not)c(included)g(in)h(that)h (mapping,)d(passing)i(an)g(inte)o(ger)f(for)g FK(name)h FN(is)h(also)g(accepted.)i(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)208 892 y(If)f(the)g (con\002guration)d(v)n(alue)j(speci\002ed)g(by)f FK(name)h FN(isn')o(t)g(de\002ned,)f FJ(None)h FN(is)h(returned.)208 1019 y(If)h FK(name)h FN(is)h(a)f(string)g(and)f(is)i(not)f(kno)n(wn,)f FJ(ValueError)f FN(is)j(raised.)33 b(If)23 b(a)g(speci\002c)h(v)n(alue) e(for)g FK(name)g FN(is)i(not)f(supported)e(by)208 1119 y(the)g(host)h(system,)f(e)n(v)o(en)g(if)h(it)g(is)g(included)e(in)i FJ(confstr_names)p FN(,)e(an)h FJ(OSError)g FN(is)h(raised)g(with)f FJ(errno.EINVAL)f FN(for)208 1219 y(the)g(error)f(number)-5 b(.)0 1366 y FD(confstr_names)208 1465 y FN(Dictionary)20 b(mapping)g(names)h(accepted)g(by)g FJ(confstr\(\))g FN(to)g(the)h(inte)o(ger)f(v)n(alues)g(de\002ned)g(for)g(those)g(names) h(by)f(the)h(host)208 1565 y(operating)16 b(system.)24 b(This)19 b(can)f(be)g(used)g(to)g(determine)f(the)i(set)g(of)f(names)g (kno)n(wn)e(to)j(the)f(system.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)210 1664 y(U)t FH(N)t(I)t(X)r FN(.)0 1811 y FD(getloadavg)p FJ(\(\))208 1911 y FN(Return)g(the)h(number)e(of)i (processes)f(in)h(the)g(system)g(run)f(queue)g(a)n(v)o(eraged)f(o)o(v)o (er)h(the)h(last)g(1,)h(5,)g(and)e(15)h(minutes)f(or)h(raises)208 2011 y FJ(OSError)19 b FN(if)h(the)h(load)e(a)n(v)o(erage)g(w)o(as)i (unobtainable.)208 2138 y(Ne)n(w)f(in)g(v)o(ersion)f(2.3.)0 2285 y FD(sysconf)p FJ(\()p FK(name)p FJ(\))208 2385 y FN(Return)24 b(inte)o(ger)n(-v)n(alued)d(system)k(con\002guration)d (v)n(alues.)38 b(If)24 b(the)h(con\002guration)d(v)n(alue)i (speci\002ed)g(by)h FK(name)f FN(isn')o(t)g(de\002ned,)208 2484 y FJ(-1)17 b FN(is)h(returned.)23 b(The)17 b(comments)f(re)o (garding)e(the)j FK(name)g FN(parameter)f(for)h FJ(confstr\(\))f FN(apply)g(here)h(as)h(well;)h(the)e(dictionary)208 2584 y(that)j(pro)o(vides)e(information)g(on)i(the)g(kno)n(wn)f(names)h(is)h (gi)n(v)o(en)e(by)g FJ(sysconf_names)p FN(.)k(A)-6 b(v)n(ailability:)25 b(Macintosh,)c(U)t FH(N)t(I)t(X)r FN(.)0 2731 y FD(sysconf_names)208 2830 y FN(Dictionary)f(mapping)g(names)h(accepted)g(by)g FJ(sysconf\(\))g FN(to)g(the)h(inte)o(ger)f(v)n(alues)g(de\002ned)g (for)g(those)g(names)h(by)f(the)h(host)208 2930 y(operating)16 b(system.)24 b(This)19 b(can)f(be)g(used)g(to)g(determine)f(the)i(set)g (of)f(names)g(kno)n(wn)e(to)j(the)f(system.)24 b(A)-6 b(v)n(ailability:)24 b(Macintosh,)210 3030 y(U)t FH(N)t(I)t(X)r FN(.)0 3176 y(The)c(follo)n(w)f(data)h(v)n(alues)g(are)g(used)g(to)h (support)d(path)i(manipulation)e(operations.)23 b(These)d(are)h (de\002ned)e(for)g(all)i(platforms.)0 3323 y(Higher)n(-le)n(v)o(el)d (operations)h(on)h(pathnames)f(are)h(de\002ned)f(in)h(the)g FJ(os.path)g FN(module.)0 3470 y FD(curdir)208 3570 y FN(The)f(constant)f(string)h(used)h(by)f(the)g(operating)f(system)h(to) h(refer)e(to)i(the)f(current)f(directory)-5 b(.)23 b(F)o(or)c(e)o (xample:)k FJ('.')i FN(for)19 b(POSIX)208 3669 y(or)g FJ(':')26 b FN(for)19 b(Mac)h(OS)h(9.)k(Also)c(a)n(v)n(ailable)f(via)g FJ(os.path)p FN(.)0 3816 y FD(pardir)208 3916 y FN(The)d(constant)h (string)f(used)h(by)g(the)g(operating)e(system)i(to)g(refer)g(to)g(the) g(parent)f(directory)-5 b(.)22 b(F)o(or)c(e)o(xample:)k FJ('..')j FN(for)17 b(POSIX)208 4016 y(or)i FJ('::')25 b FN(for)20 b(Mac)g(OS)h(9.)k(Also)c(a)n(v)n(ailable)e(via)i FJ(os.path)p FN(.)0 4162 y FD(sep)208 4262 y FN(The)i(character)f(used) i(by)f(the)g(operating)f(system)i(to)g(separate)f(pathname)f (components,)g(for)h(e)o(xample,)g(`)p FJ(/)p FN(')g(for)g(POSIX)h(or) 208 4362 y(`)p FJ(:)p FN(')j(for)21 b(Mac)h(OS)g(9.)30 b(Note)21 b(that)h(kno)n(wing)e(this)i(is)h(not)e(suf)n(\002cient)g(to) h(be)g(able)f(to)h(parse)f(or)h(concatenate)e(pathnames)g(\227)i(use) 208 4461 y FJ(os.path.split\(\))c FN(and)h FJ(os.path.join\(\))f FN(\227)j(b)n(ut)f(it)h(is)g(occasionally)e(useful.)24 b(Also)d(a)n(v)n(ailable)f(via)g FJ(os.path)p FN(.)0 4608 y FD(altsep)208 4708 y FN(An)j(alternati)n(v)o(e)g(character)f (used)i(by)f(the)h(operating)e(system)i(to)g(separate)f(pathname)g (components,)f(or)h FJ(None)h FN(if)g(only)f(one)208 4807 y(separator)d(character)g(e)o(xists.)29 b(This)21 b(is)i(set)f(to)f(`)p FJ(/)p FN(')g(on)g(W)m(indo)n(ws)g(systems)h (where)f FJ(sep)g FN(is)h(a)g(backslash.)28 b(Also)22 b(a)n(v)n(ailable)f(via)208 4907 y FJ(os.path)p FN(.)0 5054 y FD(extsep)208 5154 y FN(The)29 b(character)f(which)h(separates)h (the)f(base)h(\002lename)f(from)g(the)g(e)o(xtension;)k(for)c(e)o (xample,)h(the)g(`)p FJ(.)p FN(')53 b(in)30 b(`)p FO(os)o(.p)n(y)p FN('.)52 b(Also)208 5253 y(a)n(v)n(ailable)19 b(via)h FJ(os.path)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 5400 y FD(pathsep)p 0 5549 3901 4 v 0 5649 a FI(414)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 415 427 TeXDict begin 415 426 bop 208 83 a FN(The)24 b(character)g(con)m(v)o (entionally)e(used)j(by)g(the)g(operating)f(system)h(to)g(separate)g (search)g(path)g(components)e(\(as)i(in)h(P)-8 b(A)f(TH\),)208 183 y(such)19 b(as)i(`)p FJ(:)p FN(')k(for)20 b(POSIX)g(or)g(`)p FJ(;)p FN(')g(for)g(W)m(indo)n(ws.)k(Also)d(a)n(v)n(ailable)e(via)i FJ(os.path)p FN(.)0 330 y FD(defpath)208 429 y FN(The)j(def)o(ault)g (search)g(path)g(used)g(by)g FJ(exec)1507 444 y(*)1557 429 y(p)1607 444 y(*)1657 429 y(\(\))f FN(and)h FJ(spawn)2175 444 y(*)2225 429 y(p)2275 444 y(*)2325 429 y(\(\))g FN(if)g(the)h(en)m (vironment)c(doesn')o(t)i(ha)n(v)o(e)h(a)h FJ('PATH')208 529 y FN(k)o(e)o(y)-5 b(.)23 b(Also)e(a)n(v)n(ailable)f(via)g FJ(os.path)p FN(.)0 676 y FD(linesep)208 775 y FN(The)h(string)g(used)h (to)g(separate)f(\(or)m(,)g(rather)m(,)g(terminate\))f(lines)i(on)g (the)f(current)g(platform.)28 b(This)22 b(may)f(be)h(a)g(single)f (character)m(,)208 875 y(such)e(as)h FJ('\\n')f FN(for)g(POSIX)g(or)g FJ('\\r')h FN(for)e(Mac)i(OS,)f(or)g(multiple)g(characters,)f(for)h(e)o (xample,)f FJ('\\r\\n')h FN(for)g(W)m(indo)n(ws.)24 b(Do)208 975 y(not)e(use)h FK(os.linesep)f FN(as)i(a)f(line)g(terminator)e(when) h(writing)g(\002les)i(opened)d(in)i(te)o(xt)g(mode)e(\(the)i(def)o (ault\);)g(use)g(a)g(single)g FJ('\\n')208 1074 y FN(instead,)c(on)h (all)h(platforms.)0 1221 y FD(devnull)208 1321 y FN(The)e(\002le)i (path)f(of)g(the)g(null)h(de)n(vice.)j(F)o(or)c(e)o(xample:)k FJ('/dev/null')19 b FN(for)g(POSIX)i(or)f FJ('Dev:Nul')f FN(for)h(Mac)g(OS)h(9.)k(Also)208 1420 y(a)n(v)n(ailable)19 b(via)h FJ(os.path)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 1705 y Fv(14.1.7)101 b(Miscellaneous)29 b(Functions)0 1894 y FD(urandom)p FJ(\()p FK(n)p FJ(\))208 1994 y FN(Return)19 b(a)i(string)f(of)g FK(n)g FN(random)e(bytes)i(suitable)g(for)g (cryptographic)d(use.)208 2127 y(This)24 b(function)f(returns)h(random) f(bytes)i(from)e(an)i(OS-speci\002c)g(randomness)d(source.)38 b(The)25 b(returned)d(data)j(should)f(be)g(un-)208 2226 y(predictable)19 b(enough)g(for)h(cryptographic)e(applications,)i (though)f(its)j(e)o(xact)f(quality)f(depends)g(on)g(the)h(OS)h (implementation.)208 2326 y(On)30 b(a)h(UNIX-lik)o(e)f(system)g(this)h (will)g(query)e(/de)n(v/urandom,)h(and)f(on)h(W)m(indo)n(ws)g(it)h (will)g(use)g(CryptGenRandom.)53 b(If)30 b(a)208 2425 y(randomness)18 b(source)h(is)i(not)f(found,)f FJ(NotImplementedError)e FN(will)k(be)f(raised.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 2753 y FE(14.2)121 b Fx(time)32 b FE(\227)h(Time)g(access)g(and)i(con)n (v)m(ersions)0 2986 y FN(This)24 b(module)e(pro)o(vides)h(v)n(arious)f (time-related)h(functions.)34 b(It)24 b(is)h(al)o(w)o(ays)f(a)n(v)n (ailable,)g(b)n(ut)g(not)g(all)g(functions)e(are)i(a)n(v)n(ailable)g (on)f(all)0 3085 y(platforms.)k(Most)21 b(of)g(the)g(functions)f (de\002ned)g(in)i(this)f(module)f(call)i(platform)d(C)j(library)f (functions)e(with)j(the)f(same)g(name.)28 b(It)21 b(may)0 3185 y(sometimes)i(be)h(helpful)e(to)i(consult)f(the)g(platform)f (documentation,)g(because)g(the)i(semantics)g(of)f(these)h(functions)e (v)n(aries)h(among)0 3285 y(platforms.)0 3431 y(An)d(e)o(xplanation)e (of)i(some)g(terminology)e(and)h(con)m(v)o(entions)f(is)j(in)f(order)-5 b(.)125 3661 y FM(\017)41 b FN(The)20 b FK(epoc)o(h)g FN(is)i(the)f(point)f(where)g(the)h(time)g(starts.)28 b(On)21 b(January)f(1st)i(of)e(that)h(year)m(,)f(at)i(0)f(hours,)f(the) h(\223time)g(since)g(the)g(epoch\224)208 3761 y(is)g(zero.)j(F)o(or)e (U)t FH(N)t(I)t(X)r FN(,)f(the)f(epoch)f(is)i(1970.)j(T)-7 b(o)20 b(\002nd)g(out)g(what)g(the)g(epoch)f(is,)i(look)e(at)i FJ(gmtime\(0\))p FN(.)125 3927 y FM(\017)41 b FN(The)24 b(functions)g(in)h(this)h(module)e(do)h(not)g(handle)f(dates)h(and)g (times)g(before)f(the)h(epoch)f(or)h(f)o(ar)g(in)g(the)h(future.)38 b(The)25 b(cut-of)n(f)208 4027 y(point)19 b(in)h(the)h(future)e(is)i (determined)d(by)i(the)g(C)h(library;)e(for)j(U)t FH(N)t(I)t(X)r FN(,)f(it)g(is)g(typically)e(in)h(2038.)125 4193 y FM(\017)41 b FL(Y)-9 b(ear)21 b(2000)g(\(Y2K\))g(issues)p FN(:)31 b(Python)21 b(depends)f(on)i(the)g(platform')-5 b(s)21 b(C)i(library)-5 b(,)21 b(which)h(generally)e(doesn')o(t)h(ha)n(v)o(e)g (year)h(2000)208 4292 y(issues,)32 b(since)e(all)g(dates)g(and)f(times) h(are)f(represented)f(internally)h(as)h(seconds)f(since)h(the)f(epoch.) 52 b(Functions)29 b(accepting)208 4392 y(a)d FJ(struct_time)f FN(\(see)h(belo)n(w\))f(generally)g(require)g(a)h(4-digit)f(year)-5 b(.)43 b(F)o(or)26 b(backw)o(ard)e(compatibility)-5 b(,)26 b(2-digit)f(years)h(are)208 4491 y(supported)20 b(if)i(the)h(module)e (v)n(ariable)g FJ(accept2dyear)f FN(is)j(a)g(non-zero)d(inte)o(ger;)i (this)h(v)n(ariable)e(is)i(initialized)f(to)h FJ(1)f FN(unless)208 4591 y(the)g(en)m(vironment)e(v)n(ariable)h(PYTHONY2K)h (is)i(set)f(to)g(a)g(non-empty)d(string,)i(in)h(which)f(case)h(it)g(is) h(initialized)e(to)h FJ(0)p FN(.)32 b(Thus,)208 4691 y(you)21 b(can)i(set)g(PYTHONY2K)g(to)g(a)g(non-empty)d(string)i(in)h (the)g(en)m(vironment)d(to)i(require)g(4-digit)g(years)g(for)g(all)h (year)g(input.)208 4790 y(When)d(2-digit)g(years)g(are)h(accepted,)e (the)o(y)h(are)h(con)m(v)o(erted)d(according)h(to)i(the)f(POSIX)h(or)g (X/Open)f(standard:)25 b(v)n(alues)20 b(69-99)208 4890 y(are)28 b(mapped)e(to)j(1969-1999,)d(and)h(v)n(alues)h(0\22668)f(are)h (mapped)f(to)h(2000\2262068.)45 b(V)-9 b(alues)28 b(100\2261899)d(are)j (al)o(w)o(ays)g(ille)o(gal.)208 4990 y(Note)19 b(that)g(this)h(is)h(ne) n(w)e(as)h(of)f(Python)f(1.5.2\(a2\);)f(earlier)i(v)o(ersions,)f(up)h (to)h(Python)e(1.5.1)g(and)h(1.5.2a1,)e(w)o(ould)i(add)f(1900)g(to)208 5089 y(year)h(v)n(alues)h(belo)n(w)g(1900.)125 5255 y FM(\017)41 b FN(UTC)21 b(is)h(Coordinated)d(Uni)n(v)o(ersal)h(T)m(ime)h (\(formerly)e(kno)n(wn)h(as)i(Greenwich)d(Mean)i(T)m(ime,)g(or)g (GMT\).)f(The)h(acron)o(ym)e(UTC)208 5355 y(is)i(not)f(a)g(mistak)o(e)g (b)n(ut)h(a)f(compromise)e(between)i(English)f(and)h(French.)p 0 5549 3901 4 v 0 5649 a FI(14.2.)52 b FJ(time)23 b FI(\227)g(Time)g (access)f(and)h(con)n(v)n(ersions)2107 b(415)p eop end %%Page: 416 428 TeXDict begin 416 427 bop 125 83 a FM(\017)41 b FN(DST)18 b(is)i(Daylight)d(Sa)n(ving)h(T)m(ime,)h(an)f(adjustment)f(of)i(the)f (timezone)f(by)h(\(usually\))f(one)h(hour)g(during)e(part)i(of)h(the)f (year)-5 b(.)24 b(DST)208 183 y(rules)17 b(are)h(magic)f(\(determined)e (by)j(local)f(la)o(w\))h(and)f(can)g(change)g(from)f(year)h(to)h(year) -5 b(.)24 b(The)18 b(C)g(library)f(has)h(a)g(table)f(containing)208 282 y(the)23 b(local)f(rules)h(\(often)f(it)i(is)g(read)e(from)g(a)i (system)f(\002le)g(for)g(\003e)o(xibility\))f(and)g(is)i(the)f(only)f (source)g(of)h(T)m(rue)f(W)m(isdom)h(in)g(this)208 382 y(respect.)125 548 y FM(\017)41 b FN(The)20 b(precision)g(of)h(the)g(v) n(arious)e(real-time)i(functions)e(may)i(be)g(less)h(than)e(suggested)g (by)g(the)h(units)g(in)h(which)e(their)h(v)n(alue)f(or)208 648 y(ar)o(gument)d(is)k(e)o(xpressed.)i(E.g.)c(on)h(most)i(U)t FH(N)t(I)t(X)h FN(systems,)d(the)f(clock)h(\223ticks\224)g(only)f(50)g (or)h(100)f(times)h(a)g(second,)f(and)g(on)h(the)208 747 y(Mac,)g(times)g(are)g(only)g(accurate)f(to)h(whole)g(seconds.)125 913 y FM(\017)41 b FN(On)34 b(the)h(other)e(hand,)k(the)d(precision)g (of)g FJ(time\(\))g FN(and)g FJ(sleep\(\))g FN(is)h(better)f(than)g (their)i(U)t FH(N)t(I)t(X)i FN(equi)n(v)n(alents:)52 b(times)208 1013 y(are)38 b(e)o(xpressed)f(as)i(\003oating)f(point)f (numbers,)42 b FJ(time\(\))c FN(returns)f(the)i(most)f(accurate)f(time) i(a)n(v)n(ailable)f(\(using)i(U)t FH(N)t(I)t(X)208 1112 y FJ(gettimeofday\(\))d FN(where)h(a)n(v)n(ailable\),)43 b(and)c FJ(sleep\(\))f FN(will)i(accept)f(a)g(time)h(with)f(a)h (nonzero)d(fraction)h(\()r(U)t FH(N)t(I)t(X)208 1212 y FJ(select\(\))19 b FN(is)i(used)f(to)g(implement)f(this,)i(where)e(a) n(v)n(ailable\).)125 1378 y FM(\017)41 b FN(The)15 b(time)i(v)n(alue)e (as)i(returned)e(by)g FJ(gmtime\(\))p FN(,)h FJ(localtime\(\))p FN(,)f(and)h FJ(strptime\(\))p FN(,)f(and)h(accepted)f(by)h FJ(asctime\(\))p FN(,)208 1478 y FJ(mktime\(\))h FN(and)h FJ(strftime\(\))p FN(,)f(is)i(a)g(sequence)e(of)h(9)g(inte)o(gers.)24 b(The)18 b(return)f(v)n(alues)h(of)g FJ(gmtime\(\))p FN(,)f FJ(localtime\(\))p FN(,)208 1577 y(and)i FJ(strptime\(\))g FN(also)i(of)n(fer)e(attrib)n(ute)g(names)h(for)g(indi)n(vidual)e (\002elds.)820 1785 y FL(Index)p 1071 1815 4 100 v 99 w(Attrib)n(ute)p 1569 1815 V 168 w(V)-8 b(alues)p 770 1818 2568 4 v 901 1888 a FN(0)p 1071 1918 4 100 v 179 w FJ(tm_year)p 1569 1918 V 149 w FN(\(for)19 b(e)o(xample,)f(1993\))901 1987 y(1)p 1071 2017 V 179 w FJ(tm_mon)p 1569 2017 V 199 w FN(range)h([1,12])901 2087 y(2)p 1071 2117 V 179 w FJ(tm_mday)p 1569 2117 V 149 w FN(range)g([1,31])901 2187 y(3)p 1071 2216 V 179 w FJ(tm_hour)p 1569 2216 V 149 w FN(range)g([0,23])901 2286 y(4)p 1071 2316 V 179 w FJ(tm_min)p 1569 2316 V 199 w FN(range)g([0,59])901 2386 y(5)p 1071 2416 V 179 w FJ(tm_sec)p 1569 2416 V 199 w FN(range)g([0,61];)f(see)j FL(\(1\))f FN(in)g FJ(strftime\(\))f FN(description)901 2485 y(6)p 1071 2515 V 179 w FJ(tm_wday)p 1569 2515 V 149 w FN(range)g([0,6],)f(Monday)h(is)i(0)901 2585 y(7)p 1071 2615 V 179 w FJ(tm_yday)p 1569 2615 V 149 w FN(range)e([1,366])901 2685 y(8)p 1071 2715 V 179 w FJ(tm_isdst)p 1569 2715 V 99 w FN(0,)h(1)g(or)g(-1;)g(see)h(belo)n(w) 208 2896 y(Note)26 b(that)h(unlik)o(e)f(the)g(C)i(structure,)f(the)g (month)e(v)n(alue)h(is)h(a)g(range)f(of)g(1-12,)h(not)f(0-11.)43 b(A)27 b(year)f(v)n(alue)g(will)i(be)e(handled)208 2995 y(as)i(described)e(under)g(\223Y)-8 b(ear)27 b(2000)f(\(Y2K\))h (issues\224)h(abo)o(v)o(e.)45 b(A)28 b FJ(-1)g FN(ar)o(gument)d(as)k (the)e(daylight)f(sa)n(vings)i(\003ag,)h(passed)e(to)208 3095 y FJ(mktime\(\))19 b FN(will)i(usually)e(result)i(in)f(the)g (correct)f(daylight)g(sa)n(vings)h(state)h(to)g(be)f(\002lled)g(in.)208 3228 y(When)i(a)h(tuple)f(with)g(an)h(incorrect)e(length)h(is)h(passed) f(to)h(a)g(function)e(e)o(xpecting)f(a)j FJ(struct_time)p FN(,)e(or)i(ha)n(ving)e(elements)208 3327 y(of)e(the)i(wrong)e(type,)g (a)i FJ(TypeError)e FN(is)i(raised.)208 3460 y(Changed)28 b(in)i(v)o(ersion)e(2.2:)h(The)g(time)h(v)n(alue)f(sequence)g(w)o(as)h (changed)e(from)g(a)i(tuple)g(to)f(a)i FJ(struct_time)p FN(,)f(with)g(the)208 3560 y(addition)18 b(of)i(attrib)n(ute)g(names)g (for)g(the)g(\002elds.)0 3790 y(The)g(module)f(de\002nes)h(the)g(follo) n(wing)e(functions)h(and)h(data)g(items:)0 3937 y FD(accept2dyear)208 4036 y FN(Boolean)g(v)n(alue)g(indicating)g(whether)f(tw)o(o-digit)i (year)f(v)n(alues)g(will)i(be)f(accepted.)26 b(This)21 b(is)h(true)f(by)f(def)o(ault,)g(b)n(ut)h(will)h(be)f(set)208 4136 y(to)g(f)o(alse)i(if)f(the)f(en)m(vironment)e(v)n(ariable)h (PYTHONY2K)i(has)g(been)f(set)h(to)g(a)g(non-empty)d(string.)29 b(It)22 b(may)f(also)h(be)g(modi\002ed)208 4236 y(at)e(run)g(time.)0 4382 y FD(altzone)208 4482 y FN(The)k(of)n(fset)g(of)g(the)h(local)f (DST)h(timezone,)g(in)f(seconds)g(west)i(of)e(UTC,)h(if)g(one)f(is)h (de\002ned.)37 b(This)25 b(is)h(ne)o(gati)n(v)o(e)c(if)j(the)g(local) 208 4582 y(DST)18 b(timezone)e(is)j(east)f(of)g(UTC)g(\(as)g(in)g(W)-7 b(estern)18 b(Europe,)e(including)g(the)i(UK\).)f(Only)g(use)h(this)h (if)e FJ(daylight)g FN(is)i(nonzero.)0 4729 y FD(asctime)p FJ(\()p FC([)p FK(t)13 b FC(])p FJ(\))208 4828 y FN(Con)m(v)o(ert)20 b(a)i(tuple)g(or)f FJ(struct_time)f FN(representing)g(a)i(time)g(as)h (returned)d(by)h FJ(gmtime\(\))g FN(or)h FJ(localtime\(\))e FN(to)i(a)g(24-)208 4928 y(character)f(string)h(of)g(the)g(follo)n (wing)f(form:)28 b FJ('Sun)49 b(Jun)h(20)f(23:21:05)f(1993')p FN(.)31 b(If)23 b FK(t)h FN(is)f(not)f(pro)o(vided,)f(the)h(current)208 5027 y(time)d(as)h(returned)e(by)h FJ(localtime\(\))f FN(is)i(used.)25 b(Locale)18 b(information)f(is)k(not)e(used)g(by)g FJ(asctime\(\))p FN(.)k FL(Note:)h FN(Unlik)o(e)c(the)208 5127 y(C)h(function)d(of)i(the)g(same)h(name,)e(there)h(is)h(no)f (trailing)f(ne)n(wline.)50 b(Changed)19 b(in)h(v)o(ersion)f(2.1:)h (Allo)n(wed)g FK(t)i FN(to)e(be)g(omitted.)0 5274 y FD(clock)p FJ(\(\))208 5374 y FN(On)h(U)t FH(N)t(I)t(X)r FN(,)f(return)e(the)h (current)f(processor)g(time)i(as)g(a)f(\003oating)g(point)f(number)g(e) o(xpressed)g(in)h(seconds.)24 b(The)19 b(precision,)f(and)p 0 5549 3901 4 v 0 5649 a FI(416)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 417 429 TeXDict begin 417 428 bop 208 83 a FN(in)26 b(f)o(act)f(the)h(v)o(ery)f (de\002nition)g(of)g(the)h(meaning)e(of)i(\223processor)e(time\224,)j (depends)e(on)g(that)h(of)f(the)h(C)h(function)d(of)i(the)f(same)208 183 y(name,)19 b(b)n(ut)h(in)g(an)o(y)g(case,)g(this)h(is)g(the)f (function)f(to)h(use)h(for)e(benchmarking)e(Python)i(or)h(timing)f (algorithms.)208 315 y(On)k(W)m(indo)n(ws,)g(this)h(function)d(returns) i(w)o(all-clock)f(seconds)h(elapsed)f(since)i(the)f(\002rst)h(call)g (to)f(this)h(function,)e(as)i(a)f(\003oating)208 415 y(point)h(number)m(,)h(based)g(on)g(the)h(W)m(in32)f(function)e FJ(QueryPerformanceCounter\(\))p FN(.)37 b(The)26 b(resolution)e(is)i (typically)208 515 y(better)19 b(than)h(one)g(microsecond.)0 662 y FD(ctime)p FJ(\()p FC([)p FK(secs)12 b FC(])p FJ(\))208 761 y FN(Con)m(v)o(ert)36 b(a)j(time)f(e)o(xpressed)e(in)j(seconds)e (since)h(the)g(epoch)f(to)h(a)h(string)f(representing)e(local)i(time.) 78 b(If)38 b FK(secs)h FN(is)g(not)208 861 y(pro)o(vided)i(or)i FJ(None)p FN(,)49 b(the)44 b(current)e(time)i(as)g(returned)e(by)h FJ(time\(\))g FN(is)i(used.)95 b FJ(ctime\()p FK(secs)p FJ(\))43 b FN(is)i(equi)n(v)n(alent)c(to)208 960 y FJ (asctime\(localtime\()p FK(secs)p FJ(\)\))p FN(.)48 b(Locale)29 b(information)d(is)k(not)f(used)g(by)f FJ(ctime\(\))p FN(.)103 b(Changed)28 b(in)h(v)o(ersion)f(2.1:)208 1060 y(Allo)n(wed)19 b FK(secs)i FN(to)g(be)f(omitted.)75 b(Changed)19 b(in)i(v)o(ersion)e(2.4:)g(If)h FK(secs)h FN(is)g FJ(None)p FN(,)f(the)g(current)f(time)i(is)g(used.)0 1207 y FD(daylight)208 1307 y FN(Nonzero)d(if)j(a)f(DST)h(timezone)e (is)i(de\002ned.)0 1453 y FD(gmtime)p FJ(\()p FC([)p FK(secs)12 b FC(])p FJ(\))208 1553 y FN(Con)m(v)o(ert)k(a)i(time)g(e)o (xpressed)e(in)i(seconds)f(since)h(the)g(epoch)f(to)h(a)g FJ(struct_time)e FN(in)i(UTC)g(in)g(which)g(the)f(dst)i(\003ag)e(is)i (al)o(w)o(ays)208 1653 y(zero.)34 b(If)23 b FK(secs)i FN(is)f(not)f(pro)o(vided)e(or)i FJ(None)p FN(,)h(the)g(current)e(time) h(as)i(returned)c(by)i FJ(time\(\))g FN(is)i(used.)34 b(Fractions)23 b(of)h(a)f(second)208 1752 y(are)i(ignored.)38 b(See)26 b(abo)o(v)o(e)d(for)i(a)g(description)f(of)h(the)g FJ(struct_time)f FN(object.)40 b(See)25 b FJ(calendar.timegm\(\))e FN(for)i(the)208 1852 y(in)m(v)o(erse)19 b(of)i(this)g(function.)52 b(Changed)20 b(in)g(v)o(ersion)g(2.1:)g(Allo)n(wed)g FK(secs)i FN(to)f(be)f(omitted.)81 b(Changed)20 b(in)g(v)o(ersion)g (2.4:)g(If)h FK(secs)208 1952 y FN(is)g FJ(None)p FN(,)e(the)i(current) e(time)h(is)h(used.)0 2098 y FD(localtime)p FJ(\()p FC([)p FK(secs)12 b FC(])p FJ(\))208 2198 y FN(Lik)o(e)25 b FJ(gmtime\(\))g FN(b)n(ut)h(con)m(v)o(erts)e(to)h(local)h(time.)42 b(If)25 b FK(secs)i FN(is)f(not)g(pro)o(vided)d(or)i FJ(None)p FN(,)i(the)e(current)g(time)h(as)g(returned)e(by)208 2298 y FJ(time\(\))18 b FN(is)i(used.)25 b(The)19 b(dst)g(\003ag)g(is)i (set)f(to)f FJ(1)h FN(when)e(DST)i(applies)f(to)g(the)g(gi)n(v)o(en)f (time.)50 b(Changed)18 b(in)i(v)o(ersion)e(2.1:)g(Allo)n(wed)208 2397 y FK(secs)j FN(to)f(be)g(omitted.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.4:)h(If)g FK(secs)h FN(is)g FJ(None)p FN(,)f(the)g(current)f(time)h(is)h(used.)0 2544 y FD(mktime)p FJ(\()p FK(t)q FJ(\))208 2644 y FN(This)j(is)i(the)f(in)m(v)o(erse)e (function)g(of)i FJ(localtime\(\))p FN(.)37 b(Its)25 b(ar)o(gument)e(is)i(the)g FJ(struct_time)e FN(or)i(full)f(9-tuple)g (\(since)h(the)208 2743 y(dst)f(\003ag)f(is)i(needed;)f(use)f FJ(-1)h FN(as)g(the)g(dst)g(\003ag)g(if)f(it)i(is)f(unkno)n(wn\))d (which)i(e)o(xpresses)g(the)g(time)h(in)g FK(local)f FN(time,)h(not)f(UTC.)h(It)208 2843 y(returns)f(a)h(\003oating)f(point) g(number)m(,)g(for)g(compatibility)f(with)i FJ(time\(\))p FN(.)36 b(If)24 b(the)f(input)h(v)n(alue)f(cannot)g(be)g(represented)g (as)h(a)208 2943 y(v)n(alid)h(time,)i(either)e FJ(OverflowError)f FN(or)i FJ(ValueError)e FN(will)j(be)f(raised)f(\(which)g(depends)g(on) g(whether)g(the)h(in)m(v)n(alid)208 3042 y(v)n(alue)e(is)i(caught)d(by) i(Python)f(or)g(the)h(underlying)e(C)i(libraries\).)39 b(The)24 b(earliest)i(date)e(for)h(which)f(it)i(can)e(generate)g(a)i (time)f(is)208 3142 y(platform-dependent.)0 3289 y FD(sleep)p FJ(\()p FK(secs)p FJ(\))208 3388 y FN(Suspend)18 b(e)o(x)o(ecution)f (for)i(the)g(gi)n(v)o(en)f(number)f(of)j(seconds.)k(The)19 b(ar)o(gument)d(may)j(be)h(a)f(\003oating)g(point)f(number)g(to)h (indicate)g(a)208 3488 y(more)h(precise)h(sleep)g(time.)28 b(The)21 b(actual)g(suspension)f(time)h(may)g(be)g(less)h(than)f(that)g (requested)f(because)g(an)o(y)h(caught)f(signal)208 3588 y(will)26 b(terminate)f(the)g FJ(sleep\(\))g FN(follo)n(wing)f(e)o(x)o (ecution)f(of)j(that)f(signal')-5 b(s)26 b(catching)e(routine.)40 b(Also,)27 b(the)f(suspension)e(time)208 3687 y(may)19 b(be)h(longer)f(than)h(requested)f(by)h(an)g(arbitrary)e(amount)h (because)h(of)g(the)g(scheduling)e(of)i(other)g(acti)n(vity)f(in)i(the) f(system.)0 3834 y FD(strftime)p FJ(\()p FK(format)q FC([)p FK(,)f(t)13 b FC(])p FJ(\))208 3934 y FN(Con)m(v)o(ert)i(a)i (tuple)g(or)f FJ(struct_time)g FN(representing)f(a)i(time)g(as)h (returned)d(by)h FJ(gmtime\(\))g FN(or)h FJ(localtime\(\))e FN(to)j(a)f(string)208 4033 y(as)g(speci\002ed)g(by)g(the)g FK(format)h FN(ar)o(gument.)k(If)17 b FK(t)i FN(is)f(not)f(pro)o (vided,)e(the)i(current)f(time)h(as)h(returned)d(by)h FJ(localtime\(\))g FN(is)i(used.)208 4133 y FK(format)24 b FN(must)g(be)f(a)g(string.)34 b FJ(ValueError)22 b FN(is)i(raised)f(if)h(an)o(y)e(\002eld)i(in)f FK(t)j FN(is)e(outside)f(of)g(the)g(allo)n(wed)f(range.)68 b(Changed)22 b(in)208 4233 y(v)o(ersion)i(2.1:)g(Allo)n(wed)h FK(t)j FN(to)d(be)g(omitted.)122 b(Changed)24 b(in)i(v)o(ersion)e(2.4:)h FJ(ValueError)f FN(raised)h(if)g(a)h(\002eld)g(in)f FK(t)j FN(is)e(out)f(of)208 4332 y(range.)100 b(Changed)21 b(in)i(v)o(ersion)f (2.5:)g(0)h(is)h(no)n(w)f(a)g(le)o(gal)f(ar)o(gument)f(for)h(an)o(y)g (position)g(in)h(the)g(time)g(tuple;)h(if)g(it)f(is)h(normally)208 4432 y(ille)o(gal)19 b(the)h(v)n(alue)g(is)h(forced)e(to)h(a)h(correct) e(one..)208 4565 y(The)f(follo)n(wing)g(directi)n(v)o(es)g(can)h(be)g (embedded)e(in)i(the)g FK(format)i FN(string.)j(The)o(y)18 b(are)h(sho)n(wn)f(without)h(the)g(optional)f(\002eld)h(width)208 4664 y(and)g(precision)g(speci\002cation,)g(and)h(are)g(replaced)f(by)h (the)g(indicated)f(characters)h(in)g(the)g FJ(strftime\(\))f FN(result:)p 0 5549 3901 4 v 0 5649 a FI(14.2.)52 b FJ(time)23 b FI(\227)g(Time)g(access)f(and)h(con)n(v)n(ersions)2107 b(417)p eop end %%Page: 418 430 TeXDict begin 418 429 bop 699 70 a FL(Dir)o(ecti)o(v)o(e)p 1067 100 4 100 v 98 w(Meaning)p 3159 100 V 1778 w(Notes)p 649 103 2810 4 v 809 173 a FJ(\045a)p 1067 203 4 100 v 209 w FN(Locale')-5 b(s)20 b(abbre)n(viated)e(weekday)h(name.)p 3159 203 V 809 272 a FJ(\045A)p 1067 302 V 209 w FN(Locale')-5 b(s)20 b(full)g(weekday)f(name.)p 3159 302 V 809 372 a FJ(\045b)p 1067 402 V 209 w FN(Locale')-5 b(s)20 b(abbre)n(viated)e (month)h(name.)p 3159 402 V 809 472 a FJ(\045B)p 1067 501 V 209 w FN(Locale')-5 b(s)20 b(full)g(month)f(name.)p 3159 501 V 809 571 a FJ(\045c)p 1067 601 V 209 w FN(Locale')-5 b(s)20 b(appropriate)e(date)i(and)g(time)g(representation.)p 3159 601 V 809 671 a FJ(\045d)p 1067 701 V 209 w FN(Day)g(of)g(the)g (month)f(as)i(a)g(decimal)e(number)g([01,31].)p 3159 701 V 809 770 a FJ(\045H)p 1067 800 V 209 w FN(Hour)h(\(24-hour)d (clock\))i(as)i(a)g(decimal)e(number)g([00,23].)p 3159 800 V 809 870 a FJ(\045I)p 1067 900 V 209 w FN(Hour)h(\(12-hour)d (clock\))i(as)i(a)g(decimal)e(number)g([01,12].)p 3159 900 V 809 970 a FJ(\045j)p 1067 1000 V 209 w FN(Day)h(of)g(the)g(year)g (as)h(a)g(decimal)e(number)f([001,366].)p 3159 1000 V 809 1069 a FJ(\045m)p 1067 1099 V 209 w FN(Month)h(as)i(a)g(decimal)e (number)g([01,12].)p 3159 1099 V 809 1169 a FJ(\045M)p 1067 1199 V 209 w FN(Minute)h(as)h(a)f(decimal)g(number)e([00,59].)p 3159 1199 V 809 1269 a FJ(\045p)p 1067 1298 V 209 w FN(Locale')-5 b(s)20 b(equi)n(v)n(alent)f(of)h(either)f(AM)i(or)f(PM.)p 3159 1298 V 793 w(\(1\))809 1368 y FJ(\045S)p 1067 1398 V 209 w FN(Second)f(as)i(a)g(decimal)e(number)g([00,61].)p 3159 1398 V 906 w(\(2\))809 1468 y FJ(\045U)p 1067 1697 4 299 v 209 w FN(W)-7 b(eek)34 b(number)d(of)i(the)g(year)g(\(Sunday)f (as)h(the)h(\002rst)g(day)e(of)h(the)1118 1567 y(week\))22 b(as)i(a)f(decimal)f(number)f([00,53].)30 b(All)23 b(days)f(in)h(a)g (ne)n(w)g(year)1118 1667 y(preceding)18 b(the)i(\002rst)h(Sunday)e(are) h(considered)f(to)h(be)g(in)h(week)f(0.)p 3159 1697 V 3261 1468 a(\(3\))809 1767 y FJ(\045w)p 1067 1797 4 100 v 209 w FN(W)-7 b(eekday)20 b(as)h(a)f(decimal)g(number)e ([0\(Sunday\),6].)p 3159 1797 V 809 1866 a FJ(\045W)p 1067 2095 4 299 v 209 w FN(W)-7 b(eek)31 b(number)e(of)i(the)f(year)h (\(Monday)d(as)k(the)e(\002rst)i(day)e(of)g(the)1118 1966 y(week\))22 b(as)i(a)f(decimal)f(number)f([00,53].)30 b(All)23 b(days)f(in)h(a)g(ne)n(w)g(year)1118 2066 y(preceding)18 b(the)i(\002rst)h(Monday)e(are)h(considered)e(to)j(be)f(in)g(week)g(0.) p 3159 2095 V 3261 1866 a(\(3\))809 2165 y FJ(\045x)p 1067 2195 4 100 v 209 w FN(Locale')-5 b(s)20 b(appropriate)e(date)i (representation.)p 3159 2195 V 809 2265 a FJ(\045X)p 1067 2295 V 209 w FN(Locale')-5 b(s)20 b(appropriate)e(time)i (representation.)p 3159 2295 V 809 2364 a FJ(\045y)p 1067 2394 V 209 w FN(Y)-8 b(ear)20 b(without)f(century)g(as)i(a)g (decimal)e(number)g([00,99].)p 3159 2394 V 809 2464 a FJ(\045Y)p 1067 2494 V 209 w FN(Y)-8 b(ear)20 b(with)g(century)f(as)i (a)g(decimal)e(number)-5 b(.)p 3159 2494 V 809 2564 a FJ(\045Z)p 1067 2594 V 209 w FN(T)m(ime)20 b(zone)g(name)f(\(no)h (characters)f(if)h(no)g(time)h(zone)e(e)o(xists\).)p 3159 2594 V 809 2663 a FJ(\045\045)p 1067 2693 V 209 w FN(A)i(literal)f(`)p FJ(\045)p FN(')g(character)-5 b(.)p 3159 2693 V 208 2790 a(Notes:)208 3003 y FL(\(1\))n FN(When)28 b(used)f(with)h(the)f FJ(strptime\(\))g FN(function,)g(the)h FJ(\045p)g FN(directi)n(v)o(e)e(only)h(af)n(fects)g(the)g(output)g (hour)f(\002eld)i(if)g(the)f FJ(\045I)390 3103 y FN(directi)n(v)o(e)19 b(is)i(used)f(to)h(parse)e(the)i(hour)-5 b(.)208 3236 y FL(\(2\))n FN(The)20 b(range)f(really)h(is)h FJ(0)g FN(to)f FJ(61)p FN(;)h(this)f(accounts)g(for)f(leap)h(seconds)g(and)f (the)i(\(v)o(ery)d(rare\))i(double)f(leap)h(seconds.)208 3369 y FL(\(3\))n FN(When)k(used)g(with)h(the)f FJ(strptime\(\))f FN(function,)g FJ(\045U)i FN(and)e FJ(\045W)i FN(are)f(only)f(used)h (in)h(calculations)e(when)h(the)g(day)g(of)g(the)390 3468 y(week)c(and)g(the)g(year)g(are)g(speci\002ed.)208 3682 y(Here)e(is)h(an)g(e)o(xample,)e(a)i(format)e(for)h(dates)h (compatible)d(with)j(that)g(speci\002ed)f(in)g(the)h(RFC)h(2822)d (Internet)g(email)i(standard.)3867 3652 y FF(1)444 3906 y FA(>>>)44 b(from)g(time)g(import)g(gmtime,)g(strftime)444 3997 y(>>>)g(strftime\("\045a,)f(\045d)h(\045b)h(\045Y)f (\045H:\045M:\045S)g(+0000",)f(gmtime\(\)\))444 4089 y('Thu,)h(28)g(Jun)h(2001)f(14:17:15)f(+0000')208 4278 y FN(Additional)30 b(directi)n(v)o(es)g(may)h(be)h(supported)d(on)i (certain)g(platforms,)i(b)n(ut)f(only)e(the)i(ones)f(listed)h(here)f (ha)n(v)o(e)g(a)h(meaning)208 4378 y(standardized)18 b(by)i(ANSI)g(C.)208 4510 y(On)g(some)g(platforms,)e(an)i(optional)f (\002eld)i(width)e(and)h(precision)f(speci\002cation)g(can)h (immediately)f(follo)n(w)g(the)i(initial)f(`)p FJ(\045)p FN(')g(of)208 4610 y(a)h(directi)n(v)o(e)e(in)i(the)g(follo)n(wing)e (order;)g(this)i(is)h(also)f(not)f(portable.)25 b(The)c(\002eld)g (width)f(is)h(normally)e(2)i(e)o(xcept)f(for)g FJ(\045j)h FN(where)f(it)208 4710 y(is)h(3.)0 4857 y FD(strptime)p FJ(\()p FK(string)p FC([)p FK(,)d(format)13 b FC(])p FJ(\))208 4956 y FN(P)o(arse)23 b(a)h(string)g(representing)d(a)j(time) g(according)e(to)i(a)g(format.)34 b(The)23 b(return)g(v)n(alue)g(is)h (a)h FJ(struct_time)d FN(as)i(returned)e(by)208 5056 y FJ(gmtime\(\))d FN(or)h FJ(localtime\(\))p FN(.)p 0 5122 1560 4 v 90 5178 a FB(1)120 5201 y FH(The)e(use)g(of)g Fz(\045Z)g FH(is)g(no)n(w)h(deprecated,)i(b)o(ut)d(the)h Fz(\045z)f FH(escape)i(that)f(e)o(xpands)h(to)e(the)h(preferred)i (hour/minute)f(of)n(fset)g(is)e(not)g(supported)i(by)f(all)g(ANSI)f(C)g (libraries.)0 5280 y(Also,)e(a)g(strict)h(reading)h(of)e(the)g (original)i(1982)f(RFC)f(822)g(standard)h(calls)h(for)d(a)h(tw)o (o-digit)j(year)e(\(\045y)f(rather)h(than)g(\045Y\),)e(b)o(ut)i (practice)h(mo)o(v)o(ed)e(to)h(4-digit)g(years)g(long)0 5359 y(before)h(the)g(year)g(2000.)j(The)c(4-digit)i(year)e(has)h(been) g(mandated)g(by)f(RFC)h(2822,)f(which)h(obsoletes)g(RFC)g(822.)p 0 5549 3901 4 v 0 5649 a FI(418)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 419 431 TeXDict begin 419 430 bop 208 83 a FN(The)28 b FK(format)j FN(parameter)d(uses)i(the)f(same)h(directi)n(v)o(es)e(as)i(those)f (used)g(by)g FJ(strftime\(\))p FN(;)j(it)e(def)o(aults)f(to)h FJ("\045a)49 b(\045b)g(\045d)208 183 y(\045H:\045M:\045S)f(\045Y")25 b FN(which)f(matches)h(the)g(formatting)e(returned)g(by)h FJ(ctime\(\))p FN(.)39 b(If)25 b FK(string)g FN(cannot)f(be)g(parsed)h (according)208 282 y(to)f FK(format)q FN(,)h(or)e(if)h(it)h(has)f(e)o (xcess)g(data)g(after)f(parsing,)h FJ(ValueError)e FN(is)j(raised.)36 b(The)23 b(def)o(ault)g(v)n(alues)h(used)g(to)g(\002ll)g(in)g(an)o(y) 208 382 y(missing)c(data)g(when)f(more)h(accurate)f(v)n(alues)h(cannot) f(be)h(inferred)f(are)h FJ(\(1900,)48 b(1,)i(1,)f(0,)h(0,)f(0,)h(0,)f (1,)g(-1\))p FN(.)208 513 y(F)o(or)19 b(e)o(xample:)444 643 y FA(>>>)44 b(import)g(time)444 735 y(>>>)g(time.strptime\("30)e (Nov)i(00",)h("\045d)f(\045b)g(\045y"\))444 826 y(\(2000,)g(11,)g(30,)g (0,)h(0,)f(0,)h(3,)f(335,)g(-1\))208 1013 y FN(Support)29 b(for)g(the)i FJ(\045Z)g FN(directi)n(v)o(e)e(is)i(based)f(on)h(the)f (v)n(alues)g(contained)f(in)i FJ(tzname)f FN(and)g(whether)f FJ(daylight)h FN(is)h(true.)208 1113 y(Because)20 b(of)g(this,)h(it)g (is)h(platform-speci\002c)c(e)o(xcept)h(for)h(recognizing)e(UTC)j(and)f (GMT)g(which)g(are)g(al)o(w)o(ays)h(kno)n(wn)e(\(and)h(are)208 1212 y(considered)e(to)i(be)g(non-daylight)e(sa)n(vings)i(timezones\).) 0 1359 y FD(struct_time)208 1459 y FN(The)k(type)h(of)f(the)h(time)h(v) n(alue)e(sequence)g(returned)f(by)h FJ(gmtime\(\))p FN(,)h FJ(localtime\(\))p FN(,)g(and)f FJ(strptime\(\))p FN(.)78 b(Ne)n(w)25 b(in)208 1558 y(v)o(ersion)18 b(2.2.)0 1705 y FD(time)p FJ(\(\))208 1805 y FN(Return)g(the)h(time)g(as)g(a)g (\003oating)f(point)g(number)f(e)o(xpressed)h(in)h(seconds)f(since)h (the)f(epoch,)g(in)h(UTC.)g(Note)g(that)g(e)n(v)o(en)e(though)208 1905 y(the)g(time)h(is)h(al)o(w)o(ays)f(returned)e(as)j(a)f(\003oating) f(point)g(number)m(,)f(not)h(all)h(systems)h(pro)o(vide)c(time)j(with)g (a)g(better)g(precision)e(than)h(1)208 2004 y(second.)25 b(While)d(this)f(function)e(normally)g(returns)h(non-decreasing)e(v)n (alues,)i(it)i(can)e(return)g(a)h(lo)n(wer)f(v)n(alue)h(than)f(a)h(pre) n(vious)208 2104 y(call)f(if)h(the)f(system)g(clock)g(has)g(been)g(set) h(back)e(between)h(the)g(tw)o(o)g(calls.)0 2251 y FD(timezone)208 2350 y FN(The)29 b(of)n(fset)f(of)h(the)h(local)f(\(non-DST\))e (timezone,)k(in)e(seconds)g(west)h(of)f(UTC)h(\(ne)o(gati)n(v)o(e)d(in) i(most)h(of)f(W)-7 b(estern)29 b(Europe,)208 2450 y(positi)n(v)o(e)19 b(in)h(the)g(US,)h(zero)f(in)g(the)g(UK\).)0 2597 y FD(tzname)208 2696 y FN(A)i(tuple)f(of)g(tw)o(o)h(strings:)28 b(the)22 b(\002rst)g(is)h(the)f(name)f(of)g(the)h(local)f(non-DST)f(timezone,)h (the)h(second)e(is)j(the)f(name)f(of)g(the)h(local)208 2796 y(DST)e(timezone.)k(If)c(no)g(DST)g(timezone)g(is)h(de\002ned,)e (the)h(second)f(string)h(should)f(not)h(be)g(used.)0 2943 y FD(tzset)p FJ(\(\))208 3043 y FN(Resets)g(the)g(time)f(con)m(v)o (ersion)e(rules)i(used)g(by)g(the)h(library)e(routines.)24 b(The)19 b(en)m(vironment)d(v)n(ariable)j(TZ)g(speci\002es)h(ho)n(w)f (this)h(is)208 3142 y(done.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)208 3273 y(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)208 3404 y FL(Note:)32 b FN(Although)22 b(in)j(man)o(y)e(cases,)j (changing)c(the)i(TZ)g(en)m(vironment)e(v)n(ariable)h(may)h(af)n(fect)f (the)h(output)g(of)f(functions)g(lik)o(e)208 3503 y FJ(localtime)c FN(without)g(calling)h FJ(tzset)p FN(,)f(this)i(beha)n(vior)e(should)g (not)h(be)g(relied)g(on.)208 3634 y(The)f(TZ)i(en)m(vironment)c(v)n (ariable)i(should)g(contain)g(no)h(whitespace.)208 3764 y(The)f(standard)g(format)h(of)f(the)i(TZ)f(en)m(vironment)d(v)n (ariable)i(is:)26 b(\(whitespace)20 b(added)f(for)g(clarity\))-295 3926 y(std)i(of)n(fset)e([dst)i([of)n(fset)n([,start[/time],)e (end[/time]]]])208 4088 y(Where:)35 4297 y(std)i(and)e(dstThree)45 b(or)g(more)f(alphanumerics)g(gi)n(ving)g(the)h(timezone)f(abbre)n (viations.)99 b(These)45 b(will)h(be)f(propagated)e(into)390 4396 y(time.tzname)203 4525 y(of)n(fset)o(The)23 b(of)n(fset)g(has)g (the)g(form:)30 b FM(\006)24 b FN(hh[:mm[:ss]].)32 b(This)23 b(indicates)g(the)g(v)n(alue)g(added)f(the)h(local)g(time)g(to)h(arri)n (v)o(e)e(at)h(UTC.)390 4624 y(If)f(preceded)e(by)h(a)h('-',)f(the)h (timezone)f(is)h(east)h(of)e(the)h(Prime)f(Meridian;)h(otherwise,)f(it) h(is)h(west.)30 b(If)22 b(no)f(of)n(fset)g(follo)n(ws)390 4724 y(dst,)g(summer)e(time)h(is)h(assumed)f(to)g(be)g(one)g(hour)f (ahead)g(of)h(standard)f(time.)49 4853 y(start[/time)o(,end[/time]])e (Indicates)h(when)g(to)h(change)e(to)i(and)f(back)g(from)g(DST)-6 b(.)19 b(The)f(format)g(of)g(the)h(start)g(and)f(end)h(dates)f(are)h (one)390 4952 y(of)h(the)g(follo)n(wing:)472 5087 y(J)p FK(n)o FN(The)g(Julian)f(day)g FK(n)g FN(\(1)h(\241=)f FK(n)h FN(\241=)f(365\).)24 b(Leap)19 b(days)g(are)g(not)g(counted,)f (so)i(in)g(all)g(years)f(February)f(28)h(is)h(day)f(59)g(and)545 5186 y(March)h(1)g(is)h(day)f(60.)504 5300 y FK(n)o FN(The)31 b(zero-based)f(Julian)h(day)f(\(0)h(\241=)g FK(n)h FN(\241=)f(365\).)56 b(Leap)31 b(days)g(are)g(counted,)h(and)f(it)h(is)g(possible)f(to)g (refer)f(to)545 5400 y(February)19 b(29.)p 0 5549 3901 4 v 0 5649 a FI(14.2.)52 b FJ(time)23 b FI(\227)g(Time)g(access)f(and)h (con)n(v)n(ersions)2107 b(419)p eop end %%Page: 420 432 TeXDict begin 420 431 bop 285 83 a FN(M)p FK(m)p FN(.)p FK(n)p FN(.)p FK(d)p FN(The)20 b FK(d)r FN(')o(th)g(day)f(\(0)h(\241=)h FK(d)h FN(\241=)f(6\))f(or)f(week)h FK(n)h FN(of)f(month)f FK(m)i FN(of)f(the)g(year)g(\(1)g(\241=)g FK(n)g FN(\241=)g(5,)h(1)f (\241=)g FK(m)h FN(\241=)f(12,)g(where)f(week)h(5)545 183 y(means)h(\224the)f(last)h FK(d)i FN(day)d(in)h(month)e FK(m)p FN(\224)i(which)f(may)f(occur)h(in)h(either)f(the)g(fourth)f(or) h(the)h(\002fth)f(week\).)25 b(W)-7 b(eek)21 b(1)g(is)545 282 y(the)g(\002rst)g(week)f(in)g(which)g(the)g FK(d)r FN(')o(th)f(day)h(occurs.)k(Day)c(zero)g(is)h(Sunday)-5 b(.)390 423 y(time)19 b(has)h(the)f(same)g(format)f(as)h(of)n(fset)g(e) o(xcept)f(that)h(no)f(leading)g(sign)h(\('-')f(or)h('+'\))g(is)g(allo)n (wed.)24 b(The)19 b(def)o(ault,)f(if)h(time)h(is)390 523 y(not)g(gi)n(v)o(en,)f(is)i(02:00:00.)444 828 y FA(>>>)44 b(os.environ['TZ'])e(=)j('EST+05EDT,M4.1.0,M10.5.0')444 919 y(>>>)f(time.tzset\(\))444 1010 y(>>>)g(time.strftime\('\045X)e (\045x)j(\045Z'\))444 1102 y('02:07:36)e(05/08/03)h(EDT')444 1193 y(>>>)g(os.environ['TZ'])e(=)j('AEST-10AEDT-11,M10.5.0,M3.5.0')444 1284 y(>>>)f(time.tzset\(\))444 1376 y(>>>)g(time.strftime\('\045X)e (\045x)j(\045Z'\))444 1467 y('16:08:12)e(05/08/03)h(AEST')208 1656 y FN(On)17 b(man)o(y)h(U)t FH(N)t(I)t(X)i FN(systems)d (\(including)e(*BSD,)j(Linux,)e(Solaris,)i(and)f(Darwin\),)f(it)i(is)g (more)f(con)m(v)o(enient)d(to)j(use)h(the)f(system')-5 b(s)208 1756 y(zoneinfo)23 b(\()p FK(tz\002le)p FN(\(5\)\))h(database)h (to)h(specify)f(the)h(timezone)e(rules.)42 b(T)-7 b(o)25 b(do)h(this,)h(set)f(the)g(TZ)g(en)m(vironment)c(v)n(ariable)j(to)h (the)208 1856 y(path)21 b(of)g(the)h(required)e(timezone)g(data\002le,) i(relati)n(v)o(e)f(to)h(the)g(root)f(of)g(the)h(systems)g('zoneinfo')d (timezone)i(database,)g(usually)208 1955 y(located)d(at)i(`)p FO(/usr/share/z)o(oneinf)n(o)p FN('.)g(F)o(or)f(e)o(xample,)f FJ('US/Eastern')p FN(,)g FJ('Australia/Melbourne')p FN(,)e FJ('Egypt')j FN(or)208 2055 y FJ('Europe/Amsterdam')p FN(.)444 2188 y FA(>>>)44 b(os.environ['TZ'])e(=)j('US/Eastern')444 2279 y(>>>)f(time.tzset\(\))444 2370 y(>>>)g(time.tzname)444 2462 y(\('EST',)f('EDT'\))444 2553 y(>>>)h(os.environ['TZ'])e(=)j ('Egypt')444 2644 y(>>>)f(time.tzset\(\))444 2736 y(>>>)g(time.tzname) 444 2827 y(\('EET',)f('EEST'\))0 3031 y FL(See)21 b(Also:)0 3178 y FN(Module)e FJ(datetime)g FN(\(section)h(5.1\):)208 3278 y(More)f(object-oriented)e(interf)o(ace)j(to)g(dates)h(and)e (times.)0 3424 y(Module)g FJ(locale)h FN(\(section)f(21.2\):)208 3524 y(Internationalization)j(services.)43 b(The)26 b(locale)g (settings)g(can)g(af)n(fect)g(the)g(return)f(v)n(alues)g(for)h(some)g (of)g(the)g(functions)e(in)j(the)208 3624 y FJ(time)20 b FN(module.)0 3771 y(Module)f FJ(calendar)g FN(\(section)h(5.2\):)208 3870 y(General)f(calendar)n(-related)f(functions.)23 b FJ(timegm\(\))d FN(is)h(the)f(in)m(v)o(erse)f(of)h FJ(gmtime\(\))f FN(from)g(this)i(module.)0 4198 y FE(14.3)121 b Fx(optparse)31 b FE(\227)i(More)h(po)n(w)o(erful)h(command)f(line)f (option)i(parser)0 4430 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4577 y FJ(optparse)28 b FN(is)j(a)e(more)g(con)m(v)o(enient,)f(\003e)o (xible,)j(and)e(po)n(werful)e(library)i(for)f(parsing)h(command-line)d (options)j(than)f FJ(getopt)p FN(.)0 4677 y FJ(optparse)i FN(uses)h(a)h(more)e(declarati)n(v)o(e)f(style)i(of)g(command-line)d (parsing:)46 b(you)30 b(create)g(an)h(instance)g(of)f FJ(OptionParser)p FN(,)0 4777 y(populate)19 b(it)i(with)g(options,)e (and)h(parse)g(the)h(command)d(line.)26 b FJ(optparse)19 b FN(allo)n(ws)i(users)g(to)f(specify)g(options)g(in)g(the)h(con)m(v)o (entional)0 4876 y(GNU/POSIX)g(syntax,)e(and)g(additionally)g (generates)g(usage)h(and)g(help)f(messages)i(for)e(you.)0 5023 y(Here')-5 b(s)20 b(an)h(e)o(xample)d(of)i(using)g FJ(optparse)f FN(in)i(a)f(simple)g(script:)p 0 5549 3901 4 v 0 5649 a FI(420)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 421 433 TeXDict begin 421 432 bop 236 174 a FA(from)44 b(optparse)g(import)g (OptionParser)236 266 y([...])236 357 y(parser)g(=)h(OptionParser\(\)) 236 448 y(parser.add_option\("-f",)c("--file",)j(dest="filename",)1043 540 y(help="write)f(report)h(to)g(FILE",)g(metavar="FILE"\))236 631 y(parser.add_option\("-q",)d("--quiet",)1043 722 y(action="store_false",)g(dest="verbose",)i(default=True,)1043 814 y(help="don't)g(print)h(status)g(messages)f(to)i(stdout"\))236 996 y(\(options,)f(args\))g(=)g(parser.parse_args\(\))0 1283 y FN(W)m(ith)20 b(these)h(fe)n(w)f(lines)h(of)e(code,)h(users)g (of)g(your)f(script)h(can)g(no)n(w)g(do)g(the)g(\223usual)g(thing\224)f (on)h(the)g(command-line,)d(for)j(e)o(xample:)236 1521 y FA(<yourscript>)43 b(--file=outfile)g(-q)0 1807 y FN(As)31 b(it)h(parses)e(the)h(command)e(line,)k FJ(optparse)c FN(sets)j(attrib)n(utes)e(of)h(the)f FJ(options)g FN(object)g(returned) f(by)h FJ(parse_args\(\))0 1907 y FN(based)k(on)f(user)n(-supplied)f (command-line)f(v)n(alues.)66 b(When)34 b FJ(parse_args\(\))e FN(returns)h(from)g(parsing)g(this)i(command)d(line,)0 2007 y FJ(options.filename)21 b FN(will)j(be)f FJ("outfile")g FN(and)g FJ(options.verbose)e FN(will)j(be)f FJ(False)p FN(.)35 b FJ(optparse)22 b FN(supports)g(both)0 2106 y(long)28 b(and)g(short)h(options,)g(allo)n(ws)g(short)g(options)f(to)h (be)f(mer)o(ged)f(together)m(,)i(and)g(allo)n(ws)g(options)f(to)h(be)f (associated)h(with)g(their)0 2206 y(ar)o(guments)18 b(in)i(a)h(v)n (ariety)e(of)h(w)o(ays.)26 b(Thus,)19 b(the)h(follo)n(wing)f(command)f (lines)j(are)f(all)g(equi)n(v)n(alent)f(to)h(the)h(abo)o(v)o(e)d(e)o (xample:)236 2444 y FA(<yourscript>)43 b(-f)i(outfile)e(--quiet)236 2536 y(<yourscript>)g(--quiet)h(--file)g(outfile)236 2627 y(<yourscript>)f(-q)i(-foutfile)236 2718 y(<yourscript>)e (-qfoutfile)0 3005 y FN(Additionally)-5 b(,)18 b(users)i(can)g(run)g (one)f(of)236 3243 y FA(<yourscript>)43 b(-h)236 3334 y(<yourscript>)g(--help)0 3621 y FN(and)20 b FJ(optparse)f FN(will)i(print)e(out)h(a)h(brief)e(summary)g(of)h(your)f(script')-5 b(s)21 b(options:)236 3859 y FA(usage:)44 b(<yourscript>)f([options]) 236 4042 y(options:)326 4133 y(-h,)h(--help)537 b(show)44 b(this)h(help)f(message)f(and)i(exit)326 4224 y(-f)f(FILE,)g (--file=FILE)88 b(write)44 b(report)g(to)g(FILE)326 4316 y(-q,)g(--quiet)492 b(don't)44 b(print)g(status)g(messages)f(to)i (stdout)0 4602 y FN(where)20 b(the)g(v)n(alue)f(of)h FK(your)o(script)g FN(is)i(determined)c(at)j(runtime)e(\(normally)f (from)h FJ(sys.argv[0])p FN(\).)0 4887 y Fv(14.3.1)101 b(Bac)n(kg)o(round)0 5090 y FJ(optparse)40 b FN(w)o(as)i(e)o(xplicitly) e(designed)g(to)h(encourage)e(the)i(creation)f(of)h(programs)e(with)i (straightforw)o(ard,)j(con)m(v)o(entional)0 5189 y(command-line)23 b(interf)o(aces.)40 b(T)-7 b(o)25 b(that)h(end,)g(it)g(supports)e(only) h(the)h(most)f(common)f(command-line)e(syntax)j(and)g(semantics)g(con-) 0 5289 y(v)o(entionally)17 b(used)j(under)g(U)t FH(N)t(I)t(X)r FN(.)25 b(If)20 b(you)e(are)h(unf)o(amiliar)g(with)g(these)h(con)m(v)o (entions,)c(read)j(this)h(section)f(to)h(acquaint)e(yourself)g(with)0 5389 y(them.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i (option)f(parser)1426 b(421)p eop end %%Page: 422 434 TeXDict begin 422 433 bop 0 83 a FI(T)-10 b(er)r(minology)0 272 y FL(ar)o(gument)41 b FN(a)29 b(string)g(entered)f(on)g(the)h (command-line,)g(and)f(passed)h(by)g(the)g(shell)g(to)g FJ(execl\(\))g FN(or)f FJ(execv\(\))p FN(.)51 b(In)29 b(Python,)208 372 y(ar)o(guments)d(are)j(elements)f(of)h FJ(sys.argv[1:])41 b FN(\()p FJ(sys.argv[0])27 b FN(is)i(the)g(name)f (of)h(the)g(program)d(being)i(e)o(x)o(ecuted\).)210 471 y(U)t FH(N)t(I)t(X)23 b FN(shells)e(also)f(use)h(the)f(term)g(\223w)o (ord\224.)208 604 y(It)d(is)i(occasionally)d(desirable)h(to)h (substitute)f(an)h(ar)o(gument)d(list)k(other)e(than)g FJ(sys.argv[1:])p FN(,)f(so)i(you)f(should)f(read)h(\223ar)o(gu-)208 704 y(ment\224)g(as)i(\223an)f(element)f(of)h FJ(sys.argv[1:])p FN(,)f(or)g(of)h(some)g(other)f(list)i(pro)o(vided)d(as)j(a)f (substitute)g(for)g FJ(sys.argv[1:])p FN(\224.)0 870 y FL(option)61 b FN(an)32 b(ar)o(gument)e(used)h(to)h(supply)f(e)o (xtra)h(information)d(to)j(guide)f(or)h(customize)f(the)h(e)o(x)o (ecution)d(of)j(a)g(program.)58 b(There)208 969 y(are)29 b(man)o(y)f(dif)n(ferent)g(syntax)o(es)h(for)g(options;)k(the)d (traditional)g(U)t FH(N)t(I)t(X)j FN(syntax)c(is)h(a)g(hyphen)e (\(\223-\224\))g(follo)n(wed)h(by)g(a)h(single)208 1069 y(letter)m(,)c(e.g.)40 b FJ("-x")25 b FN(or)h FJ("-F")p FN(.)40 b(Also,)27 b(traditional)f(U)t FH(N)t(I)t(X)j FN(syntax)24 b(allo)n(ws)i(multiple)f(options)f(to)i(be)f(mer)o(ged)f (into)h(a)h(single)208 1169 y(ar)o(gument,)17 b(e.g.)25 b FJ("-x)50 b(-F")20 b FN(is)h(equi)n(v)n(alent)e(to)h FJ("-xF")p FN(.)25 b(The)20 b(GNU)h(project)f(introduced)e(a)i(double)f (hyphen)f(follo)n(wed)h(by)h(a)208 1268 y(series)i(of)f (hyphen-separated)d(w)o(ords,)j(e.g.)29 b FL(--\002le)22 b FN(or)f FL(--dry-run)p FN(.)29 b(These)21 b(are)h(the)g(only)f(tw)o (o)g(option)g(syntax)o(es)g(pro)o(vided)e(by)208 1368 y FJ(optparse)p FN(.)208 1501 y(Some)g(other)h(option)f(syntax)o(es)g (that)h(the)h(w)o(orld)e(has)i(seen)f(include:)307 1667 y FM(\017)41 b FN(a)26 b(hyphen)e(follo)n(wed)g(by)h(a)h(fe)n(w)g (letters,)h(e.g.)41 b FJ("-pf")25 b FN(\(this)h(is)h FK(not)e FN(the)h(same)g(as)g(multiple)f(options)g(mer)o(ged)f(into)h (a)390 1766 y(single)20 b(ar)o(gument\))307 1899 y FM(\017)41 b FN(a)22 b(hyphen)d(follo)n(wed)h(by)h(a)g(whole)g(w)o(ord,)g(e.g.)28 b FJ("-file")20 b FN(\(this)i(is)g(technically)e(equi)n(v)n(alent)g(to) h(the)h(pre)n(vious)d(syntax,)390 1999 y(b)n(ut)h(the)o(y)g(aren')o(t)f (usually)g(seen)i(in)f(the)g(same)h(program\))307 2132 y FM(\017)41 b FN(a)21 b(plus)f(sign)g(follo)n(wed)f(by)h(a)g(single)g (letter)m(,)g(or)g(a)h(fe)n(w)f(letters,)g(or)g(a)h(w)o(ord,)e(e.g.)25 b FJ("+f")p FN(,)19 b FJ("+rgb")307 2264 y FM(\017)41 b FN(a)21 b(slash)g(follo)n(wed)d(by)i(a)h(letter)m(,)f(or)g(a)g(fe)n (w)g(letters,)h(or)f(a)g(w)o(ord,)g(e.g.)k FJ("/f")p FN(,)c FJ("/file")208 2430 y FN(These)27 b(option)f(syntax)o(es)g(are)h (not)g(supported)e(by)i FJ(optparse)p FN(,)h(and)f(the)o(y)f(ne)n(v)o (er)g(will)i(be.)46 b(This)27 b(is)h(deliberate:)39 b(the)27 b(\002rst)208 2530 y(three)20 b(are)h(non-standard)d(on)j(an)o(y)f(en)m (vironment,)e(and)j(the)g(last)h(only)e(mak)o(es)h(sense)g(if)h(you')l (re)d(e)o(xclusi)n(v)o(ely)g(tar)o(geting)g(VMS,)208 2630 y(MS-DOS,)h(and/or)f(W)m(indo)n(ws.)0 2796 y FL(option)h(ar)o (gument)40 b FN(an)25 b(ar)o(gument)e(that)i(follo)n(ws)f(an)h(option,) f(is)i(closely)f(associated)f(with)h(that)g(option,)g(and)f(is)i (consumed)d(from)208 2895 y(the)c(ar)o(gument)f(list)i(when)g(that)f (option)g(is.)26 b(W)m(ith)20 b FJ(optparse)p FN(,)e(option)h(ar)o (guments)e(may)j(either)f(be)h(in)g(a)g(separate)f(ar)o(gument)208 2995 y(from)g(their)h(option:)444 3128 y FA(-f)44 b(foo)444 3219 y(--file)g(foo)208 3492 y FN(or)19 b(included)g(in)h(the)h(same)f (ar)o(gument:)444 3624 y FA(-ffoo)444 3716 y(--file=foo)208 3988 y FN(T)-7 b(ypically)i(,)22 b(a)h(gi)n(v)o(en)f(option)g(either)g (tak)o(es)i(an)e(ar)o(gument)f(or)i(it)g(doesn')o(t.)32 b(Lots)23 b(of)g(people)f(w)o(ant)h(an)g(\223optional)f(option)f(ar)o (gu-)208 4088 y(ments\224)g(feature,)g(meaning)f(that)i(some)f(options) g(will)h(tak)o(e)g(an)f(ar)o(gument)e(if)j(the)o(y)f(see)h(it,)h(and)e (w)o(on')o(t)g(if)g(the)o(y)g(don')o(t.)28 b(This)22 b(is)208 4188 y(some)n(what)c(contro)o(v)o(ersial,)e(because)i(it)i (mak)o(es)e(parsing)g(ambiguous:)23 b(if)c FJ("-a")g FN(tak)o(es)g(an)g(optional)e(ar)o(gument)g(and)h FJ("-b")h FN(is)208 4287 y(another)h(option)h(entirely)-5 b(,)21 b(ho)n(w)h(do)g(we)g(interpret)f FJ("-ab")p FN(?)31 b(Because)22 b(of)g(this)h(ambiguity)-5 b(,)20 b FJ(optparse)h FN(does)h(not)g (support)208 4387 y(this)e(feature.)0 4553 y FL(positional)g(ar)o (gument)40 b FN(something)26 b(lefto)o(v)o(er)f(in)i(the)f(ar)o(gument) f(list)j(after)e(options)g(ha)n(v)o(e)g(been)g(parsed,)i(i.e.)45 b(after)26 b(options)g(and)208 4652 y(their)19 b(ar)o(guments)g(ha)n(v) o(e)g(been)h(parsed)f(and)h(remo)o(v)o(ed)e(from)h(the)h(ar)o(gument)e (list.)0 4819 y FL(r)o(equir)o(ed)i(option)40 b FN(an)20 b(option)f(that)i(must)f(be)g(supplied)f(on)h(the)g(command-line;)d (note)j(that)g(the)g(phrase)f(\223required)g(option\224)f(is)j(self-) 208 4918 y(contradictory)15 b(in)j(English.)23 b FJ(optparse)17 b FN(doesn')o(t)g(pre)n(v)o(ent)f(you)h(from)g(implementing)f(required) g(options,)h(b)n(ut)h(doesn')o(t)e(gi)n(v)o(e)208 5018 y(you)26 b(much)h(help)g(at)i(it)f(either)-5 b(.)48 b(See)28 b FJ(examples/required_1.py)c FN(and)j FJ(examples/required_2.py)e FN(in)j(the)208 5117 y FJ(optparse)19 b FN(source)g(distrib)n(ution)g (for)h(tw)o(o)g(w)o(ays)h(to)f(implement)f(required)f(options)i(with)g FJ(optparse)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(422)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 423 435 TeXDict begin 423 434 bop 0 83 a FN(F)o(or)20 b(e)o(xample,)e(consider) h(this)i(hypothetical)d(command-line:)236 321 y FA(prog)44 b(-v)h(--report)e(/tmp/report.txt)g(foo)h(bar)0 608 y FL(-v)22 b FN(and)h FL(--r)o(eport)e FN(are)h(both)g(options.)32 b(Assuming)22 b(that)h FL(--r)o(eport)e FN(tak)o(es)i(one)f(ar)o (gument,)f FJ("/tmp/report.txt")f FN(is)k(an)f(option)0 707 y(ar)o(gument.)g FJ("foo")c FN(and)h FJ("bar")g FN(are)g (positional)f(ar)o(guments.)0 976 y FI(What)24 b(are)f(options)h(f)n (or?)0 1179 y FN(Options)29 b(are)g(used)g(to)g(pro)o(vide)e(e)o(xtra)i (information)e(to)i(tune)g(or)g(customize)f(the)i(e)o(x)o(ecution)d(of) i(a)g(program.)50 b(In)29 b(case)h(it)g(w)o(asn')o(t)0 1278 y(clear)m(,)e(options)e(are)h(usually)f FK(optional)p FN(.)44 b(A)27 b(program)e(should)h(be)g(able)h(to)g(run)f(just)i (\002ne)f(with)g(no)g(options)f(whatsoe)n(v)o(er)-5 b(.)43 b(\(Pick)27 b(a)0 1378 y(random)d(program)g(from)h(the)j(U)t FH(N)t(I)t(X)h FN(or)d(GNU)g(toolsets.)43 b(Can)26 b(it)h(run)e (without)g(an)o(y)h(options)f(at)h(all)h(and)e(still)i(mak)o(e)f (sense?)43 b(The)0 1477 y(main)21 b(e)o(xceptions)g(are)g FJ(find)p FN(,)h FJ(tar)p FN(,)g(and)f FJ(dd)p FN(\227all)h(of)g(which) f(are)h(mutant)f(oddballs)f(that)i(ha)n(v)o(e)g(been)f(rightly)f (criticized)i(for)f(their)0 1577 y(non-standard)c(syntax)j(and)f (confusing)g(interf)o(aces.\))0 1724 y(Lots)f(of)f(people)g(w)o(ant)h (their)g(programs)e(to)h(ha)n(v)o(e)h(\223required)e(options\224.)23 b(Think)16 b(about)h(it.)25 b(If)18 b(it')-5 b(s)18 b(required,)f(then) g(it')-5 b(s)19 b FK(not)e(optional)p FN(!)23 b(If)0 1824 y(there)17 b(is)i(a)g(piece)e(of)h(information)e(that)i(your)e (program)g(absolutely)h(requires)g(in)h(order)f(to)h(run)f (successfully)-5 b(,)17 b(that')-5 b(s)19 b(what)e(positional)0 1923 y(ar)o(guments)h(are)i(for)-5 b(.)0 2070 y(As)26 b(an)e(e)o(xample)f(of)i(good)e(command-line)f(interf)o(ace)i(design,)h (consider)e(the)i(humble)f FJ(cp)g FN(utility)-5 b(,)26 b(for)e(cop)o(ying)f(\002les.)39 b(It)25 b(doesn')o(t)0 2170 y(mak)o(e)e(much)f(sense)i(to)g(try)f(to)g(cop)o(y)g(\002les)h (without)f(supplying)e(a)j(destination)e(and)h(at)h(least)g(one)f (source.)34 b(Hence,)23 b FJ(cp)h FN(f)o(ails)g(if)f(you)0 2269 y(run)c(it)i(with)g(no)e(ar)o(guments.)k(Ho)n(we)n(v)o(er)m(,)18 b(it)j(has)g(a)f(\003e)o(xible,)g(useful)f(syntax)h(that)g(does)g(not)g (require)f(an)o(y)g(options)g(at)i(all:)236 2508 y FA(cp)45 b(SOURCE)f(DEST)236 2599 y(cp)h(SOURCE)f(...)g(DEST-DIR)0 2885 y FN(Y)-9 b(ou)28 b(can)h(get)g(pretty)f(f)o(ar)h(with)g(just)g (that.)51 b(Most)29 b FJ(cp)g FN(implementations)e(pro)o(vide)g(a)i(b)n (unch)f(of)h(options)e(to)i(tweak)g(e)o(xactly)f(ho)n(w)0 2985 y(the)c(\002les)h(are)f(copied:)31 b(you)23 b(can)h(preserv)o(e)e (mode)h(and)g(modi\002cation)g(time,)h(a)n(v)n(oid)g(follo)n(wing)e (symlinks,)i(ask)g(before)f(clobbering)0 3085 y(e)o(xisting)c(\002les,) h(etc.)25 b(But)19 b(none)g(of)g(this)g(distracts)h(from)e(the)h(core)g (mission)g(of)g FJ(cp)p FN(,)h(which)e(is)j(to)e(cop)o(y)f(either)h (one)g(\002le)h(to)f(another)m(,)f(or)0 3184 y(se)n(v)o(eral)i(\002les) h(to)f(another)f(directory)-5 b(.)0 3453 y FI(What)24 b(are)f(positional)i(arguments)e(f)n(or?)0 3655 y FN(Positional)d(ar)o (guments)e(are)i(for)g(those)g(pieces)g(of)g(information)e(that)i(your) f(program)f(absolutely)-5 b(,)18 b(positi)n(v)o(ely)h(requires)g(to)i (run.)0 3802 y(A)c(good)e(user)i(interf)o(ace)e(should)h(ha)n(v)o(e)g (as)h(fe)n(w)g(absolute)f(requirements)e(as)k(possible.)23 b(If)16 b(your)g(program)e(requires)i(17)g(distinct)h(pieces)0 3902 y(of)k(information)e(in)i(order)f(to)h(run)f(successfully)-5 b(,)20 b(it)i(doesn')o(t)e(much)g(matter)h FK(how)g FN(you)f(get)h (that)g(information)e(from)h(the)h(user\227most)0 4002 y(people)g(will)i(gi)n(v)o(e)f(up)f(and)h(w)o(alk)h(a)o(w)o(ay)f (before)e(the)o(y)i(successfully)g(run)f(the)h(program.)29 b(This)23 b(applies)f(whether)f(the)h(user)g(interf)o(ace)0 4101 y(is)j(a)f(command-line,)e(a)i(con\002guration)d(\002le,)k(or)f(a) g(GUI:)g(if)g(you)f(mak)o(e)g(that)h(man)o(y)f(demands)f(on)i(your)e (users,)j(most)f(of)f(them)h(will)0 4201 y(simply)c(gi)n(v)o(e)f(up.)0 4348 y(In)g(short,)g(try)g(to)g(minimize)g(the)g(amount)f(of)h (information)e(that)j(users)f(are)g(absolutely)g(required)e(to)j (supply\227use)e(sensible)h(def)o(aults)0 4447 y(whene)n(v)o(er)g (possible.)27 b(Of)21 b(course,)f(you)g(also)h(w)o(ant)g(to)g(mak)o(e)g (your)e(programs)h(reasonably)f(\003e)o(xible.)26 b(That')-5 b(s)21 b(what)g(options)f(are)h(for)-5 b(.)0 4547 y(Again,)19 b(it)i(doesn')o(t)d(matter)i(if)g(the)o(y)g(are)g(entries)g(in)g(a)g (con\002g)g(\002le,)g(widgets)g(in)g(the)g(\223Preferences\224)f (dialog)g(of)h(a)g(GUI,)g(or)g(command-)0 4647 y(line)32 b(options\227the)e(more)i(options)e(you)h(implement,)j(the)e(more)f (\003e)o(xible)g(your)g(program)e(is,)36 b(and)31 b(the)h(more)f (complicated)g(its)0 4746 y(implementation)23 b(becomes.)40 b(T)-7 b(oo)25 b(much)f(\003e)o(xibility)h(has)g(dra)o(wbacks)f(as)i (well,)h(of)e(course;)i(too)e(man)o(y)f(options)h(can)g(o)o(v)o (erwhelm)0 4846 y(users)20 b(and)g(mak)o(e)g(your)f(code)g(much)g (harder)g(to)i(maintain.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i (option)f(parser)1426 b(423)p eop end %%Page: 424 436 TeXDict begin 424 435 bop 0 83 a Fv(14.3.2)101 b(T)-12 b(utor)q(ial)0 286 y FN(While)19 b FJ(optparse)e FN(is)j(quite)e(\003e) o(xible)g(and)g(po)n(werful,)f(it')-5 b(s)19 b(also)g(straightforw)o (ard)d(to)j(use)f(in)h(most)f(cases.)25 b(This)19 b(section)f(co)o(v)o (ers)g(the)0 386 y(code)i(patterns)f(that)h(are)h(common)d(to)i(an)o(y) g FJ(optparse)p FN(-based)e(program.)0 532 y(First,)j(you)e(need)h(to)g (import)f(the)h(OptionP)o(arser)f(class;)i(then,)f(early)f(in)i(the)f (main)g(program,)d(create)j(an)h(OptionP)o(arser)d(instance:)236 771 y FA(from)44 b(optparse)g(import)g(OptionParser)236 862 y([...])236 953 y(parser)g(=)h(OptionParser\(\))0 1240 y FN(Then)19 b(you)h(can)g(start)g(de\002ning)f(options.)24 b(The)c(basic)g(syntax)g(is:)236 1478 y FA(parser.add_option\(opt_str,) 41 b(...,)1043 1569 y(attr=value,)i(...\))0 1856 y FN(Each)19 b(option)g(has)h(one)f(or)h(more)f(option)f(strings,)i(such)f(as)i FL(-f)f FN(or)f FL(--\002le)p FN(,)h(and)f(se)n(v)o(eral)g(option)g (attrib)n(utes)g(that)h(tell)h FJ(optparse)e FN(what)0 1956 y(to)h(e)o(xpect)g(and)f(what)h(to)h(do)e(when)h(it)h(encounters)d (that)j(option)e(on)g(the)i(command)d(line.)0 2103 y(T)-7 b(ypically)i(,)19 b(each)h(option)f(will)h(ha)n(v)o(e)g(one)g(short)f (option)g(string)h(and)g(one)g(long)f(option)g(string,)h(e.g.:)236 2341 y FA(parser.add_option\("-f",)41 b("--file",)j(...\))0 2628 y FN(Y)-9 b(ou')l(re)17 b(free)i(to)g(de\002ne)f(as)i(man)o(y)e (short)g(option)g(strings)h(and)f(as)i(man)o(y)d(long)i(option)e (strings)i(as)h(you)e(lik)o(e)h(\(including)e(zero\),)h(as)h(long)0 2727 y(as)i(there)f(is)h(at)f(least)h(one)f(option)f(string)h(o)o(v)o (erall.)0 2874 y(The)e(option)f(strings)h(passed)h(to)f FJ(add_option\(\))f FN(are)h(ef)n(fecti)n(v)o(ely)e(labels)j(for)f(the) g(option)f(de\002ned)g(by)h(that)h(call.)24 b(F)o(or)18 b(bre)n(vity)-5 b(,)17 b(we)0 2974 y(will)k(frequently)c(refer)i(to)h FK(encountering)e(an)h(option)g FN(on)g(the)h(command)e(line;)i(in)g (reality)-5 b(,)19 b FJ(optparse)g FN(encounters)f FK(option)h(strings) 0 3073 y FN(and)h(looks)f(up)h(options)f(from)g(them.)0 3220 y(Once)h(all)h(of)f(your)f(options)g(are)h(de\002ned,)f(instruct)h FJ(optparse)f FN(to)h(parse)g(your)f(program')-5 b(s)19 b(command)f(line:)236 3458 y FA(\(options,)44 b(args\))g(=)g (parser.parse_args\(\))0 3745 y FN(\(If)23 b(you)g(lik)o(e,)h(you)e (can)i(pass)g(a)f(custom)g(ar)o(gument)e(list)k(to)f FJ(parse_args\(\))p FN(,)e(b)n(ut)h(that')-5 b(s)24 b(rarely)f (necessary:)31 b(by)23 b(def)o(ault)g(it)h(uses)0 3845 y FJ(sys.argv[1:])p FN(.\))0 3991 y FJ(parse_args\(\))19 b FN(returns)g(tw)o(o)h(v)n(alues:)125 4205 y FM(\017)41 b FJ(options)p FN(,)18 b(an)i(object)f(containing)f(v)n(alues)h(for)h (all)g(of)f(your)g(options\227e.g.)k(if)d FL(--\002le)g FN(tak)o(es)g(a)g(single)f(string)h(ar)o(gument,)d(then)208 4304 y FJ(options.file)h FN(will)j(be)f(the)g(\002lename)g(supplied)f (by)h(the)g(user)m(,)g(or)g FJ(None)g FN(if)g(the)g(user)g(did)g(not)g (supply)f(that)h(option)125 4470 y FM(\017)41 b FJ(args)p FN(,)19 b(the)i(list)g(of)f(positional)f(ar)o(guments)f(lefto)o(v)o(er) h(after)g(parsing)h(options)0 4684 y(This)i(tutorial)g(section)g(only)f (co)o(v)o(ers)g(the)h(four)f(most)i(important)d(option)h(attrib)n (utes:)29 b FJ(action)p FN(,)22 b FJ(type)p FN(,)g FJ(dest)g FN(\(destination\),)f(and)0 4783 y FJ(help)p FN(.)k(Of)20 b(these,)g FJ(action)g FN(is)h(the)f(most)g(fundamental.)0 5052 y FI(Understanding)k(option)g(actions)0 5254 y FN(Actions)32 b(tell)h FJ(optparse)e FN(what)h(to)g(do)g(when)g(it)g(encounters)f(an) h(option)f(on)g(the)i(command)d(line.)61 b(There)31 b(is)i(a)f(\002x)o (ed)g(set)h(of)0 5354 y(actions)26 b(hard-coded)d(into)i FJ(optparse)p FN(;)j(adding)d(ne)n(w)h(actions)f(is)i(an)f(adv)n(anced) e(topic)i(co)o(v)o(ered)e(in)i(section)f(14.3.5,)h(Extending)p 0 5549 3901 4 v 0 5649 a FI(424)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 425 437 TeXDict begin 425 436 bop 0 83 a FJ(optparse)p FN(.)49 b(Most)29 b(actions)f(tell)h FJ(optparse)f FN(to)g(store)h(a)g(v)n (alue)e(in)i(some)f(v)n(ariable\227for)f(e)o(xample,)h(tak)o(e)h(a)g (string)f(from)g(the)0 183 y(command)18 b(line)i(and)g(store)g(it)h(in) g(an)f(attrib)n(ute)f(of)h FJ(options)p FN(.)0 330 y(If)g(you)f(don')o (t)g(specify)g(an)i(option)d(action,)i FJ(optparse)f FN(def)o(aults)h(to)g FJ(store)p FN(.)0 598 y FI(The)j(store)g(action)0 801 y FN(The)c(most)g(common)e(option)h(action)h(is)h FJ(store)p FN(,)f(which)g(tells)h FJ(optparse)e FN(to)i(tak)o(e)f(the)g (ne)o(xt)g(ar)o(gument)d(\(or)j(the)g(remainder)f(of)h(the)0 900 y(current)g(ar)o(gument\),)e(ensure)j(that)g(it)h(is)g(of)f(the)g (correct)f(type,)h(and)f(store)h(it)h(to)g(your)e(chosen)g (destination.)0 1047 y(F)o(or)h(e)o(xample:)236 1285 y FA(parser.add_option\("-f",)41 b("--file",)1043 1377 y(action="store",)i(type="string",)f(dest="filename"\))0 1663 y FN(No)n(w)20 b(let')-5 b(s)21 b(mak)o(e)f(up)g(a)g(f)o(ak)o(e)g (command)f(line)h(and)f(ask)i FJ(optparse)e FN(to)h(parse)g(it:)236 1901 y FA(args)44 b(=)h(["-f",)f("foo.txt"])236 1993 y(\(options,)g(args\))g(=)g(parser.parse_args\(args\))0 2279 y FN(When)36 b FJ(optparse)f FN(sees)i(the)f(option)f(string)h FJ("-f")p FN(,)k(it)d(consumes)e(the)h(ne)o(xt)f(ar)o(gument,)j FJ("foo.txt")p FN(,)h(and)c(stores)i(it)f(in)0 2379 y FJ(options.filename)p FN(.)23 b(So,)d(after)g(this)g(call)h(to)f FJ(parse_args\(\))p FN(,)f FJ(options.filename)e FN(is)k FJ("foo.txt")p FN(.)0 2526 y(Some)28 b(other)g(option)f(types)i (supported)d(by)i FJ(optparse)g FN(are)g FJ(int)h FN(and)f FJ(float)p FN(.)49 b(Here')-5 b(s)29 b(an)g(option)e(that)h(e)o(xpects) g(an)h(inte)o(ger)0 2625 y(ar)o(gument:)236 2772 y FA (parser.add_option\("-n",)41 b(type="int",)i(dest="num"\))0 3059 y FN(Note)18 b(that)h(this)g(option)e(has)i(no)f(long)g(option)f (string,)h(which)g(is)h(perfectly)e(acceptable.)24 b(Also,)19 b(there')-5 b(s)18 b(no)g(e)o(xplicit)g(action,)g(since)h(the)0 3158 y(def)o(ault)g(is)j FJ(store)p FN(.)0 3305 y(Let')-5 b(s)25 b(parse)f(another)f(f)o(ak)o(e)i(command-line.)35 b(This)24 b(time,)i(we')o(ll)f(jam)f(the)h(option)e(ar)o(gument)f (right)i(up)g(against)g(the)h(option:)32 b(since)0 3405 y FJ("-n42")20 b FN(\(one)f(ar)o(gument\))e(is)22 b(equi)n(v)n(alent)c (to)i FJ("-n)50 b(42")20 b FN(\(tw)o(o)g(ar)o(guments\),)d(the)k(code) 236 3643 y FA(\(options,)44 b(args\))g(=)g (parser.parse_args\(["-n42"]\))236 3734 y(print)g(options.num)0 4021 y FN(will)21 b(print)f FJ("42")p FN(.)0 4168 y(If)i(you)e(don')o (t)g(specify)h(a)h(type,)g FJ(optparse)f FN(assumes)g FJ(string)p FN(.)29 b(Combined)21 b(with)g(the)h(f)o(act)g(that)g(the)f (def)o(ault)g(action)h(is)g FJ(store)p FN(,)0 4267 y(that)e(means)g (our)g(\002rst)h(e)o(xample)d(can)i(be)g(a)h(lot)f(shorter:)236 4414 y FA(parser.add_option\("-f",)41 b("--file",)j(dest="filename"\))0 4701 y FN(If)25 b(you)e(don')o(t)g(supply)h(a)h(destination,)f FJ(optparse)g FN(\002gures)g(out)h(a)g(sensible)g(def)o(ault)e(from)h (the)h(option)e(strings:)34 b(if)25 b(the)g(\002rst)g(long)0 4800 y(option)e(string)h(is)h FL(--f)n(oo-bar)p FN(,)e(then)h(the)g (def)o(ault)f(destination)h(is)h FJ(foo_bar)p FN(.)36 b(If)24 b(there)g(are)g(no)g(long)f(option)g(strings,)i FJ(optparse)0 4900 y FN(looks)20 b(at)g(the)h(\002rst)g(short)e(option) g(string:)25 b(the)20 b(def)o(ault)g(destination)f(for)h FJ("-f")g FN(is)h FJ(f)p FN(.)0 5047 y FJ(optparse)i FN(also)h(includes)e(b)n(uilt-in)h FJ(long)h FN(and)f FJ(complex)g FN(types.)35 b(Adding)22 b(types)h(is)i(co)o(v)o(ered)c (in)j(section)f(14.3.5,)g(Extending)0 5147 y FJ(optparse)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(425)p eop end %%Page: 426 438 TeXDict begin 426 437 bop 0 83 a FI(Handling)25 b(boolean)f(\(\003ag\)) e(options)0 286 y FN(Flag)c(options\227set)f(a)i(v)n(ariable)d(to)i (true)g(or)g(f)o(alse)g(when)f(a)h(particular)f(option)g(is)i (seen\227are)e(quite)g(common.)23 b FJ(optparse)17 b FN(supports)0 386 y(them)22 b(with)g(tw)o(o)h(separate)e(actions,)h FJ(store_true)f FN(and)h FJ(store_false)p FN(.)29 b(F)o(or)22 b(e)o(xample,)f(you)g(might)h(ha)n(v)o(e)f(a)i FJ(verbose)e FN(\003ag)0 485 y(that)f(is)h(turned)e(on)h(with)g FJ("-v")g FN(and)g(of)n(f)g(with)g FJ("-q")p FN(:)236 723 y FA (parser.add_option\("-v",)41 b(action="store_true",)h(dest="verbose"\)) 236 815 y(parser.add_option\("-q",)f(action="store_false",)g (dest="verbose"\))0 1101 y FN(Here)22 b(we)g(ha)n(v)o(e)f(tw)o(o)h(dif) n(ferent)e(options)h(with)h(the)f(same)h(destination,)f(which)g(is)i (perfectly)d(OK.)i(\(It)g(just)g(means)g(you)e(ha)n(v)o(e)i(to)f(be)h (a)0 1201 y(bit)e(careful)g(when)f(setting)h(def)o(ault)g(v)n (alues\227see)g(belo)n(w)-5 b(.\))0 1348 y(When)19 b FJ(optparse)f FN(encounters)g FJ("-v")h FN(on)f(the)i(command)d(line,)i (it)h(sets)g FJ(options.verbose)d FN(to)i FJ(True)p FN(;)h(when)e(it)i (encounters)0 1447 y FJ("-q")p FN(,)g FJ(options.verbose)e FN(is)j(set)g(to)f FJ(False)p FN(.)0 1716 y FI(Other)j(actions)0 1919 y FN(Some)d(other)f(actions)h(supported)e(by)i FJ(optparse)f FN(are:)0 2132 y FD(store_const)39 b FN(store)21 b(a)f(constant)g(v)n (alue)0 2298 y FD(append)40 b FN(append)19 b(this)i(option')-5 b(s)19 b(ar)o(gument)f(to)i(a)h(list)0 2464 y FD(count)41 b FN(increment)18 b(a)j(counter)e(by)g(one)0 2630 y FD(callback)40 b FN(call)21 b(a)f(speci\002ed)g(function)0 2843 y(These)g(are)g(co)o (v)o(ered)e(in)j(section)e(14.3.3,)g(Reference)g(Guide)g(and)h(section) g(14.3.4,)e(Option)h(Callbacks.)0 3112 y FI(Def)n(ault)24 b(v)n(alues)0 3314 y FN(All)i(of)e(the)i(abo)o(v)o(e)d(e)o(xamples)h (in)m(v)n(olv)o(e)f(setting)i(some)g(v)n(ariable)f(\(the)h (\223destination\224\))e(when)i(certain)f(command-line)f(options)h(are) 0 3414 y(seen.)g(What)17 b(happens)f(if)h(those)g(options)f(are)h(ne)n (v)o(er)f(seen?)24 b(Since)17 b(we)g(didn')o(t)f(supply)g(an)o(y)g(def) o(aults,)h(the)o(y)f(are)h(all)h(set)g(to)f FJ(None)p FN(.)23 b(This)0 3514 y(is)c(usually)f(\002ne,)h(b)n(ut)g(sometimes)f (you)g(w)o(ant)g(more)g(control.)23 b FJ(optparse)18 b FN(lets)h(you)f(supply)f(a)i(def)o(ault)f(v)n(alue)g(for)g(each)g (destination,)0 3613 y(which)i(is)h(assigned)e(before)g(the)h(command)f (line)h(is)h(parsed.)0 3760 y(First,)e(consider)e(the)h(v)o (erbose/quiet)e(e)o(xample.)23 b(If)18 b(we)g(w)o(ant)g FJ(optparse)g FN(to)g(set)h FJ(verbose)e FN(to)i FJ(True)e FN(unless)i FJ("-q")f FN(is)h(seen,)f(then)0 3860 y(we)j(can)f(do)f (this:)236 4098 y FA(parser.add_option\("-v",)41 b (action="store_true",)h(dest="verbose",)g(default=True\))236 4189 y(parser.add_option\("-q",)f(action="store_false",)g (dest="verbose"\))0 4476 y FN(Since)19 b(def)o(ault)f(v)n(alues)g (apply)g(to)h(the)g FK(destination)e FN(rather)h(than)h(to)g(an)o(y)f (particular)f(option,)h(and)g(these)h(tw)o(o)g(options)f(happen)f(to)i (ha)n(v)o(e)0 4576 y(the)h(same)h(destination,)d(this)j(is)g(e)o (xactly)f(equi)n(v)n(alent:)236 4814 y FA(parser.add_option\("-v",)41 b(action="store_true",)h(dest="verbose"\))236 4905 y (parser.add_option\("-q",)f(action="store_false",)g(dest="verbose",)i (default=True\))0 5192 y FN(Consider)20 b(this:)p 0 5549 3901 4 v 0 5649 a FI(426)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 427 439 TeXDict begin 427 438 bop 236 174 a FA(parser.add_option\("-v",)41 b(action="store_true",)h(dest="verbose",)g(default=False\))236 266 y(parser.add_option\("-q",)f(action="store_false",)g (dest="verbose",)i(default=True\))0 552 y FN(Again,)23 b(the)g(def)o(ault)f(v)n(alue)g(for)h FJ(verbose)f FN(will)i(be)f FJ(True)p FN(:)31 b(the)23 b(last)h(def)o(ault)e(v)n(alue)g(supplied)g (for)h(an)o(y)f(particular)g(destination)g(is)0 652 y(the)e(one)g(that) g(counts.)0 799 y(A)g(clearer)f(w)o(ay)h(to)g(specify)f(def)o(ault)g(v) n(alues)g(is)i(the)f FJ(set_defaults\(\))d FN(method)h(of)i(OptionP)o (arser)m(,)e(which)h(you)g(can)g(call)h(at)g(an)o(y)0 898 y(time)g(before)f(calling)h FJ(parse_args\(\))p FN(:)236 1137 y FA(parser.set_defaults\(verbose=True\))236 1228 y(parser.add_option\(...\))236 1319 y(\(options,)44 b(args\))g(=)g (parser.parse_args\(\))0 1606 y FN(As)29 b(before,)f(the)g(last)h(v)n (alue)f(speci\002ed)g(for)f(a)h(gi)n(v)o(en)f(option)g(destination)g (is)i(the)f(one)g(that)g(counts.)48 b(F)o(or)28 b(clarity)-5 b(,)29 b(try)f(to)g(use)g(one)0 1705 y(method)19 b(or)h(the)g(other)f (of)h(setting)g(def)o(ault)g(v)n(alues,)f(not)h(both.)0 1974 y FI(Gener)o(ating)k(help)0 2176 y FJ(optparse)p FN(')-5 b(s)23 b(ability)f(to)i(generate)e(help)g(and)h(usage)g(te)o (xt)g(automatically)e(is)j(useful)f(for)f(creating)h(user)n(-friendly)d (command-line)0 2276 y(interf)o(aces.)29 b(All)22 b(you)f(ha)n(v)o(e)g (to)g(do)h(is)g(supply)f(a)h FJ(help)f FN(v)n(alue)g(for)g(each)g (option,)g(and)g(optionally)f(a)i(short)f(usage)g(message)h(for)f(your) 0 2376 y(whole)f(program.)i(Here')-5 b(s)21 b(an)f(OptionP)o(arser)f (populated)f(with)i(user)n(-friendly)e(\(documented\))f(options:)236 2614 y FA(usage)44 b(=)h("usage:)f(\045prog)g([options])f(arg1)h(arg2") 236 2705 y(parser)g(=)h(OptionParser\(usage=usage\))236 2797 y(parser.add_option\("-v",)c("--verbose",)1043 2888 y(action="store_true",)h(dest="verbose",)g(default=True,)1043 2979 y(help="make)h(lots)i(of)f(noise)g([default]"\))236 3071 y(parser.add_option\("-q",)d("--quiet",)1043 3162 y(action="store_false",)g(dest="verbose",)1043 3253 y(help="be)j(vewwy) g(quiet)g(\(I'm)g(hunting)f(wabbits\)"\))236 3345 y (parser.add_option\("-f",)e("--filename",)1043 3436 y(metavar="FILE",)i (help="write)f(output)i(to)h(FILE"\),)236 3527 y (parser.add_option\("-m",)c("--mode",)1043 3619 y (default="intermediate",)1043 3710 y(help="interaction)h(mode:)i (novice,)g(intermediate,)e(")1267 3801 y("or)j(expert)f([default:)f (\045default]"\))0 4088 y FN(If)22 b FJ(optparse)f FN(encounters)g (either)g FL(-h)i FN(or)f FL(--help)g FN(on)g(the)g(command-line,)e(or) h(if)i(you)e(just)i(call)f FJ(parser.print_help\(\))p FN(,)e(it)0 4187 y(prints)g(the)g(follo)n(wing)f(to)h(standard)f (output:)236 4334 y FA(usage:)44 b(<yourscript>)f([options])g(arg1)h (arg2)236 4517 y(options:)326 4608 y(-h,)g(--help)537 b(show)44 b(this)h(help)f(message)f(and)i(exit)326 4699 y(-v,)f(--verbose)402 b(make)44 b(lots)h(of)f(noise)g([default])326 4791 y(-q,)g(--quiet)492 b(be)45 b(vewwy)f(quiet)g(\(I'm)g(hunting)f (wabbits\))326 4882 y(-f)h(FILE,)g(--filename=FILE)1312 4973 y(write)g(output)g(to)g(FILE)326 5065 y(-m)g(MODE,)g(--mode=MODE) 88 b(interaction)43 b(mode:)h(novice,)g(intermediate,)e(or)1312 5156 y(expert)i([default:)f(intermediate])p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o (erful)h(command)f(line)i(option)f(parser)1426 b(427)p eop end %%Page: 428 440 TeXDict begin 428 439 bop 0 83 a FN(\(If)20 b(the)g(help)g(output)f(is) i(triggered)d(by)i(a)h(help)e(option,)g FJ(optparse)g FN(e)o(xits)i(after)e(printing)g(the)h(help)g(te)o(xt.\))0 230 y(There')-5 b(s)20 b(a)g(lot)h(going)e(on)g(here)h(to)g(help)g FJ(optparse)f FN(generate)g(the)i(best)f(possible)g(help)g(message:)125 443 y FM(\017)41 b FN(the)20 b(script)g(de\002nes)g(its)h(o)n(wn)f (usage)g(message:)444 667 y FA(usage)44 b(=)g("usage:)g(\045prog)g ([options])f(arg1)i(arg2")208 940 y FJ(optparse)67 b FN(e)o(xpands)f FJ("\045prog")i FN(in)g(the)h(usage)e(string)h(to)h (the)f(name)g(of)g(the)g(current)f(program,)78 b(i.e.)208 1039 y FJ(os.path.basename\(sys.argv[0]\))p FN(.)19 b(The)e(e)o (xpanded)e(string)i(is)i(then)e(printed)f(before)g(the)i(detailed)f (option)f(help.)208 1172 y(If)40 b(you)g(don')o(t)f(supply)h(a)h(usage) g(string,)k FJ(optparse)40 b FN(uses)h(a)g(bland)f(b)n(ut)h(sensible)g (def)o(ault:)66 b(\223)p FJ(usage:)98 b(\045prog)208 1272 y([options]")p FN(,)18 b(which)i(is)h(\002ne)f(if)h(your)e(script) h(doesn')o(t)f(tak)o(e)h(an)o(y)f(positional)g(ar)o(guments.)125 1438 y FM(\017)41 b FN(e)n(v)o(ery)17 b(option)h(de\002nes)g(a)i(help)e (string,)h(and)f(doesn')o(t)f(w)o(orry)h(about)g(line-)g(wrapping\227)p FJ(optparse)e FN(tak)o(es)j(care)g(of)f(wrapping)208 1538 y(lines)i(and)g(making)f(the)h(help)g(output)e(look)i(good.)125 1704 y FM(\017)41 b FN(options)24 b(that)h(tak)o(e)g(a)g(v)n(alue)f (indicate)h(this)g(f)o(act)g(in)h(their)e(automatically-generated)d (help)k(message,)g(e.g.)39 b(for)25 b(the)g(\223mode\224)208 1803 y(option:)444 2027 y FA(-m)44 b(MODE,)g(--mode=MODE)208 2300 y FN(Here,)29 b(\223MODE\224)f(is)h(called)f(the)g(meta-v)n (ariable:)39 b(it)29 b(stands)g(for)e(the)h(ar)o(gument)e(that)i(the)g (user)g(is)h(e)o(xpected)e(to)h(supply)f(to)208 2400 y FL(-m)p FN(/)p FL(--mode)p FN(.)60 b(By)32 b(def)o(ault,)i FJ(optparse)d FN(con)m(v)o(erts)g(the)h(destination)f(v)n(ariable)g (name)g(to)h(uppercase)f(and)g(uses)i(that)f(for)208 2499 y(the)c(meta-v)n(ariable.)49 b(Sometimes,)30 b(that')-5 b(s)29 b(not)g(what)f(you)g(w)o(ant\227for)g(e)o(xample,)h(the)g FL(--\002lename)f FN(option)g(e)o(xplicitly)f(sets)208 2599 y FJ(metavar="FILE")p FN(,)17 b(resulting)j(in)g(this)h (automatically-generated)16 b(option)j(description:)444 2732 y FA(-f)44 b(FILE,)g(--filename=FILE)208 3004 y FN(This)20 b(is)g(important)f(for)g(more)g(than)g(just)h(sa)n(ving)g (space,)f(though:)24 b(the)c(manually)e(written)h(help)h(te)o(xt)f (uses)i(the)f(meta-v)n(ariable)208 3104 y(\223FILE\224)f(to)i(clue)f (the)h(user)f(in)g(that)h(there')-5 b(s)20 b(a)h(connection)d(between)i (the)g(semi-formal)f(syntax)h(\223-f)g(FILE\224)g(and)g(the)g(informal) 208 3203 y(semantic)27 b(description)f(\223write)i(output)e(to)i (FILE\224.)f(This)h(is)h(a)f(simple)f(b)n(ut)h(ef)n(fecti)n(v)o(e)e(w)o (ay)i(to)g(mak)o(e)f(your)g(help)g(te)o(xt)g(a)h(lot)208 3303 y(clearer)19 b(and)h(more)f(useful)h(for)f(end)h(users.)125 3469 y FM(\017)41 b FN(options)25 b(that)h(ha)n(v)o(e)f(a)h(def)o(ault) g(v)n(alue)f(can)h(include)f FJ(\045default)g FN(in)h(the)g(help)g (string\227)p FJ(optparse)e FN(will)i(replace)g(it)g(with)208 3569 y FJ(str\(\))15 b FN(of)h(the)g(option')-5 b(s)15 b(def)o(ault)g(v)n(alue.)23 b(If)16 b(an)g(option)e(has)j(no)e(def)o (ault)g(v)n(alue)h(\(or)f(the)h(def)o(ault)f(v)n(alue)h(is)g FJ(None)p FN(\),)g FJ(\045default)208 3668 y FN(e)o(xpands)i(to)i FJ(none)p FN(.)0 3882 y(When)g(dealing)g(with)h(man)o(y)e(options,)h (it)h(is)h(con)m(v)o(enient)17 b(to)k(group)e(these)i(options)e(for)h (better)h(help)f(output.)25 b(An)20 b FJ(OptionParser)0 3981 y FN(can)g(contain)f(se)n(v)o(eral)h(option)f(groups,)f(each)i(of) g(which)g(can)g(contain)f(se)n(v)o(eral)g(options.)0 4128 y(Continuing)f(with)j(the)f(parser)g(de\002ned)f(abo)o(v)o(e,)f (adding)h(an)h FJ(OptionGroup)f FN(to)h(a)h(parser)e(is)i(easy:)236 4366 y FA(group)44 b(=)h(OptionGroup\(parser,)d(``Dangerous)g (Options'',)1133 4458 y(``Caution:)h(use)h(these)g(options)g(at)g(your) h(own)f(risk.)89 b(``)1133 4549 y(``It)44 b(is)h(believed)e(that)h (some)g(of)h(them)f(bite.''\))236 4640 y(group.add_option\(``-g'',)d (action=''store_true'',)g(help=''Group)i(option.''\))236 4732 y(parser.add_option_group\(group\))0 5018 y FN(This)20 b(w)o(ould)g(result)g(in)g(the)h(follo)n(wing)d(help)i(output:)p 0 5549 3901 4 v 0 5649 a FI(428)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 429 441 TeXDict begin 429 440 bop 236 174 a FA(usage:)89 b([options])43 b(arg1)h(arg2)236 357 y(options:)326 448 y(-h,)g(--help)492 b(show)45 b(this)f(help)g(message)f(and)i(exit)326 540 y(-v,)f(--verbose)357 b(make)45 b(lots)f(of)g(noise)g([default])326 631 y(-q,)g(--quiet)447 b(be)45 b(vewwy)f(quiet)g(\(I'm)g(hunting)g (wabbits\))326 722 y(-fFILE,)g(--file=FILE)87 b(write)44 b(output)g(to)h(FILE)326 814 y(-mMODE,)f(--mode=MODE)87 b(interaction)43 b(mode:)h(one)h(of)f('novice',)f('intermediate')1267 905 y([default],)h('expert')326 1088 y(Dangerous)f(Options:)416 1179 y(Caution:)g(use)h(of)h(these)f(options)g(is)g(at)g(your)h(own)f (risk.)89 b(It)44 b(is)h(believed)e(that)416 1270 y(some)h(of)g(them)g (bite.)416 1362 y(-g)761 b(Group)44 b(option.)0 1773 y FI(Pr)q(inting)25 b(a)e(v)n(ersion)g(str)q(ing)0 1976 y FN(Similar)e(to)g(the)g(brief)f(usage)g(string,)h FJ(optparse)f FN(can)g(also)h(print)g(a)g(v)o(ersion)e(string)i(for)f(your)g (program.)k(Y)-9 b(ou)21 b(ha)n(v)o(e)f(to)h(supply)f(the)0 2075 y(string)g(as)h(the)f FJ(version)f FN(ar)o(gument)f(to)j(OptionP)o (arser:)236 2314 y FA(parser)44 b(=)h(OptionParser\(usage="\045prog)40 b([-f])k([-q]",)g(version="\045prog)f(1.0"\))0 2600 y FJ("\045prog")26 b FN(is)j(e)o(xpanded)24 b(just)k(lik)o(e)f(it)h(is)g (in)g FJ(usage)p FN(.)45 b(Apart)27 b(from)f(that,)j FJ(version)d FN(can)h(contain)f(an)o(ything)f(you)i(lik)o(e.)46 b(When)0 2700 y(you)26 b(supply)f(it,)k FJ(optparse)d FN(automatically)f(adds)h(a)h FL(--v)o(ersion)f FN(option)g(to)h(your)e (parser)-5 b(.)44 b(If)27 b(it)g(encounters)e(this)i(option)e(on)i(the) 0 2799 y(command)18 b(line,)i(it)h(e)o(xpands)e(your)g FJ(version)g FN(string)h(\(by)f(replacing)g FJ("\045prog")p FN(\),)g(prints)h(it)h(to)f(stdout,)g(and)f(e)o(xits.)0 2946 y(F)o(or)h(e)o(xample,)e(if)j(your)e(script)h(is)h(called)f FJ(/usr/bin/foo)p FN(:)236 3184 y FA($)45 b(/usr/bin/foo)e(--version) 236 3276 y(foo)i(1.0)0 3687 y FI(Ho)o(w)23 b FJ(optparse)e FI(handles)j(errors)0 3890 y FN(There)g(are)g(tw)o(o)h(broad)e(classes) j(of)e(errors)g(that)h FJ(optparse)f FN(has)g(to)h(w)o(orry)f(about:)33 b(programmer)21 b(errors)j(and)g(user)h(errors.)37 b(Pro-)0 3990 y(grammer)32 b(errors)h(are)g(usually)g(erroneous)e(calls)k(to)e FJ(parser.add_option\(\))p FN(,)h(e.g.)65 b(in)m(v)n(alid)32 b(option)g(strings,)37 b(unkno)n(wn)0 4089 y(option)29 b(attrib)n(utes,)i(missing)f(option)f(attrib)n(utes,)j(etc.)54 b(These)29 b(are)h(dealt)g(with)g(in)g(the)f(usual)h(w)o(ay:)45 b(raise)30 b(an)f(e)o(xception)f(\(either)0 4189 y FJ (optparse.OptionError)17 b FN(or)j FJ(TypeError)p FN(\))f(and)g(let)i (the)f(program)e(crash.)0 4336 y(Handling)25 b(user)h(errors)f(is)j (much)d(more)g(important,)h(since)h(the)o(y)e(are)h(guaranteed)e(to)j (happen)d(no)i(matter)g(ho)n(w)g(stable)g(your)f(code)0 4435 y(is.)h FJ(optparse)19 b FN(can)g(automatically)g(detect)g(some)h (user)g(errors,)f(such)g(as)i(bad)e(option)g(ar)o(guments)f(\(passing)h FJ("-n)49 b(4x")20 b FN(where)f FL(-n)0 4535 y FN(tak)o(es)i(an)f(inte) o(ger)g(ar)o(gument\),)e(missing)i(ar)o(guments)f(\()p FJ("-n")h FN(at)h(the)f(end)g(of)h(the)f(command)f(line,)h(where)g FL(-n)h FN(tak)o(es)g(an)g(ar)o(gument)d(of)0 4635 y(an)o(y)h(type\).) 24 b(Also,)d(you)e(can)h(call)h FJ(parser.error\(\))d FN(to)i(signal)g(an)g(application-de\002ned)d(error)i(condition:)236 4873 y FA(\(options,)44 b(args\))g(=)g(parser.parse_args\(\))236 4964 y([...])236 5055 y(if)h(options.a)e(and)h(options.b:)416 5147 y(parser.error\("options)d(-a)j(and)h(-b)f(are)g(mutually)g (exclusive"\))p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i (option)f(parser)1426 b(429)p eop end %%Page: 430 442 TeXDict begin 430 441 bop 0 83 a FN(In)17 b(either)g(case,)h FJ(optparse)e FN(handles)h(the)g(error)f(the)i(same)f(w)o(ay:)24 b(it)18 b(prints)f(the)g(program')-5 b(s)16 b(usage)g(message)i(and)e (an)i(error)e(message)0 183 y(to)k(standard)f(error)g(and)h(e)o(xits)g (with)h(error)e(status)i(2.)0 330 y(Consider)f(the)g(\002rst)h(e)o (xample)d(abo)o(v)o(e,)h(where)g(the)i(user)f(passes)g FJ("4x")g FN(to)h(an)f(option)f(that)h(tak)o(es)h(an)f(inte)o(ger:)236 568 y FA($)45 b(/usr/bin/foo)e(-n)h(4x)236 659 y(usage:)g(foo)g ([options])236 842 y(foo:)g(error:)g(option)g(-n:)g(invalid)g(integer)g (value:)f('4x')0 1128 y FN(Or)m(,)20 b(where)f(the)i(user)f(f)o(ails)h (to)f(pass)h(a)f(v)n(alue)g(at)g(all:)236 1366 y FA($)45 b(/usr/bin/foo)e(-n)236 1458 y(usage:)h(foo)g([options])236 1640 y(foo:)g(error:)g(-n)h(option)f(requires)f(an)i(argument)0 1927 y FJ(optparse)p FN(-generated)19 b(error)j(messages)h(tak)o(e)f (care)h(al)o(w)o(ays)g(to)g(mention)f(the)g(option)g(in)m(v)n(olv)o(ed) e(in)j(the)g(error;)g(be)g(sure)f(to)h(do)g(the)0 2027 y(same)d(when)g(calling)g FJ(parser.error\(\))e FN(from)h(your)g (application)g(code.)0 2173 y(If)i FJ(optparse)p FN(')-5 b(s)20 b(def)o(ault)h(error)n(-handling)c(beha)n(viour)i(does)i(not)f (suite)i(your)d(needs,)i(you')o(ll)f(need)g(to)h(subclass)h(OptionP)o (arser)d(and)0 2273 y(o)o(v)o(erride)f FJ(exit\(\))i FN(and/or)e FJ(error\(\))p FN(.)0 2541 y FI(Putting)25 b(it)e(all)h(together)0 2744 y FN(Here')-5 b(s)20 b(what)h FJ(optparse)p FN(-based)d(scripts)i(usually)g(look)f(lik)o(e:)236 2982 y FA(from)44 b(optparse)g(import)g(OptionParser)236 3074 y([...])236 3165 y(def)h(main\(\):)416 3256 y(usage)f(=)g("usage:) g(\045prog)g([options])f(arg")416 3348 y(parser)g(=)i (OptionParser\(usage\))416 3439 y(parser.add_option\("-f",)c("--file",) i(dest="filename",)1223 3530 y(help="read)g(data)h(from)g(FILENAME"\)) 416 3622 y(parser.add_option\("-v",)d("--verbose",)1223 3713 y(action="store_true",)g(dest="verbose"\))416 3804 y(parser.add_option\("-q",)g("--quiet",)1223 3896 y (action="store_false",)g(dest="verbose"\))416 3987 y([...])416 4078 y(\(options,)i(args\))h(=)h(parser.parse_args\(\))416 4170 y(if)f(len\(args\))f(!=)i(1:)595 4261 y(parser.error\("incorrect)c (number)j(of)g(arguments"\))416 4352 y(if)g(options.verbose:)595 4444 y(print)g("reading)f(\045s...")h(\045)h(options.filename)416 4535 y([...])236 4718 y(if)g(__name__)e(==)i("__main__":)416 4809 y(main\(\))p 0 5549 3901 4 v 0 5649 a FI(430)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 431 443 TeXDict begin 431 442 bop 0 83 a Fv(14.3.3)101 b(Ref)m(erence)29 b(Guide)0 286 y FI(Creating)24 b(the)f(parser)0 489 y FN(The)d(\002rst)h(step)f(in)h(using)e FJ(optparse)h FN(is)h(to)f(create)g(an)g(OptionP)o(arser)f(instance:)236 727 y FA(parser)44 b(=)h(OptionParser\(...\))0 1014 y FN(The)24 b(OptionP)o(arser)e(constructor)g(has)i(no)g(required)e(ar)o (guments,)g(b)n(ut)i(a)h(number)d(of)h(optional)g(k)o(e)o(yw)o(ord)f (ar)o(guments.)34 b(Y)-9 b(ou)24 b(should)0 1113 y(al)o(w)o(ays)d(pass) f(them)g(as)h(k)o(e)o(yw)o(ord)d(ar)o(guments,)g(i.e.)25 b(do)20 b(not)g(rely)g(on)g(the)g(order)f(in)h(which)g(the)g(ar)o (guments)e(are)i(declared.)208 1326 y FD(usage)f FL(\(default:)24 b FD("\045prog)49 b([options]")p FL(\))39 b FN(The)24 b(usage)g(summary)f(to)i(print)e(when)h(your)f(program)f(is)k(run)d (in-)390 1426 y(correctly)k(or)i(with)f(a)h(help)f(option.)49 b(When)29 b FJ(optparse)e FN(prints)i(the)f(usage)g(string,)i(it)g(e)o (xpands)d FJ(\045prog)h FN(to)390 1526 y FJ (os.path.basename\(sys.argv[0]\))18 b FN(\(or)k(to)h FJ(prog)f FN(if)h(you)f(passed)h(that)f(k)o(e)o(yw)o(ord)f(ar)o (gument\).)30 b(T)-7 b(o)390 1625 y(suppress)20 b(a)h(usage)e(message,) h(pass)h(the)f(special)g(v)n(alue)g FJ(optparse.SUPPRESS_USAGE)p FN(.)208 1758 y FD(option_list)e FL(\(default:)24 b FD([])p FL(\))41 b FN(A)35 b(list)h(of)f(Option)f(objects)h(to)g(populate)e (the)i(parser)f(with.)69 b(The)35 b(options)f(in)390 1858 y FJ(option_list)21 b FN(are)i(added)e(after)h(an)o(y)g(options)f (in)i FJ(standard_option_list)c FN(\(a)j(class)i(attrib)n(ute)e(that) 390 1957 y(may)27 b(be)f(set)i(by)e(OptionP)o(arser)g(subclasses\),)i (b)n(ut)f(before)e(an)o(y)h(v)o(ersion)g(or)h(help)f(options.)44 b(Deprecated;)29 b(use)390 2057 y FJ(add_option\(\))19 b FN(after)h(creating)f(the)h(parser)g(instead.)208 2190 y FD(option_class)e FL(\(default:)24 b(optparse.Option\))39 b FN(Class)21 b(to)f(use)f(when)g(adding)f(options)h(to)g(the)h(parser) f(in)g FJ(add_-)390 2290 y(option\(\))p FN(.)208 2422 y FD(version)g FL(\(default:)24 b FD(None)p FL(\))41 b FN(A)30 b(v)o(ersion)e(string)i(to)g(print)f(when)g(the)h(user)g (supplies)f(a)h(v)o(ersion)f(option.)52 b(If)30 b(you)390 2522 y(supply)22 b(a)h(true)g(v)n(alue)f(for)g FJ(version)p FN(,)h FJ(optparse)f FN(automatically)f(adds)i(a)g(v)o(ersion)f(option) f(with)i(the)g(single)390 2622 y(option)c(string)h FL(--v)o(ersion)p FN(.)k(The)c(substring)f FJ("\045prog")h FN(is)h(e)o(xpanded)d(the)i (same)g(as)h(for)f FJ(usage)p FN(.)208 2754 y FD(conflict_handler)d FL(\(default:)24 b FD("error")p FL(\))40 b FN(Speci\002es)21 b(what)g(to)g(do)g(when)f(options)g(with)h(con\003icting)e(option)390 2854 y(strings)h(are)g(added)g(to)g(the)g(parser;)g(see)g(section)g (14.3.3,)f(Con\003icts)h(between)g(options.)208 2987 y FD(description)e FL(\(default:)24 b FD(None)p FL(\))41 b FN(A)50 b(paragraph)d(of)i(te)o(xt)h(gi)n(ving)e(a)i(brief)f(o)o(v)o (ervie)n(w)f(of)h(your)f(program.)390 3087 y FJ(optparse)27 b FN(reformats)f(this)i(paragraph)d(to)j(\002t)h(the)e(current)g (terminal)f(width)i(and)f(prints)g(it)h(when)f(the)h(user)390 3186 y(requests)20 b(help)g(\(after)f FJ(usage)p FN(,)h(b)n(ut)g (before)f(the)h(list)h(of)f(options\).)208 3319 y FD(formatter)f FL(\(default:)24 b(a)c(new)h(IndentedHelpF)n(ormatter\))39 b FN(An)44 b(instance)f(of)h(optparse.HelpF)o(ormatter)c(that)390 3419 y(will)32 b(be)g(used)f(for)f(printing)g(help)h(te)o(xt.)59 b FJ(optparse)30 b FN(pro)o(vides)g(tw)o(o)h(concrete)f(classes)j(for)e (this)h(purpose:)390 3518 y(IndentedHelpF)o(ormatter)16 b(and)k(T)m(itledHelpF)o(ormatter)-5 b(.)208 3651 y FD(add_help_option) 18 b FL(\(default:)24 b FD(True)p FL(\))40 b FN(If)26 b(true,)g FJ(optparse)f FN(will)i(add)e(a)h(help)f(option)g(\(with)g (option)g(strings)390 3751 y FJ("-h")20 b FN(and)g FL(--help)p FN(\))g(to)g(the)g(parser)-5 b(.)208 3884 y FD(prog)40 b FN(The)65 b(string)g(to)h(use)f(when)g(e)o(xpanding)e FJ("\045prog")h FN(in)i FJ(usage)f FN(and)g FJ(version)f FN(instead)h(of)390 3983 y FJ(os.path.basename\(sys.argv[0]\))p FN(.)0 4251 y FI(P)l(opulating)25 b(the)f(parser)0 4454 y FN(There)c(are)h(se)n(v)o(eral)f(w)o(ays)h(to)h(populate)d(the)i (parser)f(with)h(options.)26 b(The)21 b(preferred)e(w)o(ay)i(is)g(by)g (using)f FJ(OptionParser.add_-)0 4554 y(option\(\))p FN(,)f(as)i(sho)n(wn)e(in)i(section)f(14.3.2,)e(the)i(tutorial.)k FJ(add_option\(\))19 b FN(can)h(be)g(called)g(in)g(one)g(of)g(tw)o(o)g (w)o(ays:)125 4767 y FM(\017)41 b FN(pass)20 b(it)h(an)f(Option)g (instance)g(\(as)g(returned)e(by)i FJ(make_option\(\))p FN(\))125 4933 y FM(\017)41 b FN(pass)21 b(it)g(an)o(y)f(combination)e (of)j(positional)e(and)h(k)o(e)o(yw)o(ord)f(ar)o(guments)g(that)i(are)f (acceptable)g(to)g FJ(make_option\(\))f FN(\(i.e.,)h(to)208 5033 y(the)g(Option)f(constructor\),)f(and)h(it)i(will)g(create)f(the)g (Option)g(instance)g(for)f(you)0 5246 y(The)h(other)f(alternati)n(v)o (e)g(is)i(to)g(pass)f(a)h(list)g(of)f(pre-constructed)d(Option)j (instances)g(to)g(the)g(OptionP)o(arser)f(constructor)m(,)f(as)j(in:)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(431)p eop end %%Page: 432 444 TeXDict begin 432 443 bop 236 174 a FA(option_list)43 b(=)i([)416 266 y(make_option\("-f",)d("--filename",)954 357 y(action="store",)g(type="string",)g(dest="filename"\),)416 448 y(make_option\("-q",)g("--quiet",)954 540 y(action="store_false",)f (dest="verbose"\),)416 631 y(])236 722 y(parser)j(=)h (OptionParser\(option_list=option_list\))0 1009 y FN(\()p FJ(make_option\(\))17 b FN(is)i(a)h(f)o(actory)d(function)g(for)h (creating)g(Option)g(instances;)h(currently)f(it)h(is)h(an)f(alias)g (for)f(the)h(Option)f(construc-)0 1108 y(tor)-5 b(.)31 b(A)23 b(future)e(v)o(ersion)g(of)g FJ(optparse)h FN(may)f(split)i (Option)f(into)f(se)n(v)o(eral)h(classes,)h(and)f FJ(make_option\(\))e FN(will)j(pick)f(the)g(right)0 1208 y(class)f(to)f(instantiate.)25 b(Do)20 b(not)g(instantiate)g(Option)g(directly)-5 b(.\))0 1476 y FI(De\002ning)24 b(options)0 1679 y FN(Each)c(Option)h(instance) f(represents)g(a)h(set)h(of)f(synon)o(ymous)d(command-line)g(option)i (strings,)g(e.g.)27 b FL(-f)21 b FN(and)f FL(--\002le)p FN(.)27 b(Y)-9 b(ou)21 b(can)f(specify)0 1779 y(an)o(y)f(number)g(of)h (short)f(or)h(long)g(option)f(strings,)h(b)n(ut)g(you)f(must)h(specify) g(at)h(least)g(one)e(o)o(v)o(erall)g(option)g(string.)0 1926 y(The)h(canonical)f(w)o(ay)h(to)g(create)g(an)g(Option)g(instance) g(is)h(with)f(the)g FJ(add_option\(\))f FN(method)g(of)h FJ(OptionParser)p FN(:)236 2164 y FA(parser.add_option\(opt_str[,)41 b(...],)j(attr=value,)e(...\))0 2450 y FN(T)-7 b(o)20 b(de\002ne)g(an)g(option)f(with)h(only)g(a)g(short)g(option)f(string:) 236 2689 y FA(parser.add_option\("-f",)41 b(attr=value,)i(...\))0 2975 y FN(And)20 b(to)g(de\002ne)g(an)g(option)f(with)h(only)g(a)g (long)g(option)e(string:)236 3213 y FA(parser.add_option\("--foo",)41 b(attr=value,)i(...\))0 3500 y FN(The)23 b(k)o(e)o(yw)o(ord)e(ar)o (guments)g(de\002ne)i(attrib)n(utes)g(of)g(the)h(ne)n(w)f(Option)f (object.)34 b(The)22 b(most)i(important)d(option)h(attrib)n(ute)h(is)h FJ(action)p FN(,)0 3600 y(and)19 b(it)i(lar)o(gely)d(determines)h (which)g(other)g(attrib)n(utes)h(are)g(rele)n(v)n(ant)e(or)i(required.) j(If)d(you)f(pass)h(irrele)n(v)n(ant)e(option)h(attrib)n(utes,)h(or)f (f)o(ail)0 3699 y(to)h(pass)h(required)d(ones,)i FJ(optparse)f FN(raises)i(an)f(OptionError)e(e)o(xception)g(e)o(xplaining)g(your)h (mistak)o(e.)0 3846 y(An)30 b(options')-5 b(s)29 b FK(action)h FN(determines)e(what)i FJ(optparse)f FN(does)h(when)g(it)g(encounters)e (this)j(option)e(on)g(the)h(command-line.)52 b(The)0 3946 y(standard)19 b(option)g(actions)h(hard-coded)d(into)j FJ(optparse)f FN(are:)0 4159 y FD(store)41 b FN(store)20 b(this)g(option')-5 b(s)20 b(ar)o(gument)e(\(def)o(ault\))0 4325 y FD(store_const)39 b FN(store)21 b(a)f(constant)g(v)n(alue)0 4491 y FD(store_true)40 b FN(store)20 b(a)g(true)g(v)n(alue)0 4657 y FD(store_false)39 b FN(store)21 b(a)f(f)o(alse)h(v)n(alue)0 4823 y FD(append)40 b FN(append)19 b(this)i(option')-5 b(s)19 b(ar)o(gument)f(to)i(a)h(list)0 4989 y FD(append_const)39 b FN(append)19 b(a)h(constant)g(v)n(alue)f(to)i(a)f(list)0 5155 y FD(count)41 b FN(increment)18 b(a)j(counter)e(by)g(one)0 5321 y FD(callback)40 b FN(call)21 b(a)f(speci\002ed)g(function)p 0 5549 3901 4 v 0 5649 a FI(432)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 433 445 TeXDict begin 433 444 bop 0 83 a FD(help)41 b FN(print)19 b(a)i(usage)f(message)g(including)e(all)j(options)e(and)h(the)g (documentation)d(for)j(them)0 296 y(\(If)k(you)h(don')o(t)e(supply)h (an)h(action,)g(the)g(def)o(ault)f(is)i FJ(store)p FN(.)39 b(F)o(or)25 b(this)g(action,)h(you)e(may)g(also)i(supply)e FJ(type)h FN(and)f FJ(dest)h FN(option)0 396 y(attrib)n(utes;)20 b(see)h(belo)n(w)-5 b(.\))0 543 y(As)27 b(you)e(can)h(see,)j(most)d (actions)g(in)m(v)n(olv)o(e)f(storing)g(or)h(updating)e(a)j(v)n(alue)f (some)n(where.)41 b FJ(optparse)26 b FN(al)o(w)o(ays)g(creates)h(a)f (special)0 642 y(object)32 b(for)f(this,)k(con)m(v)o(entionally)29 b(called)j FJ(options)f FN(\(it)i(happens)d(to)j(be)f(an)g(instance)f (of)h FJ(optparse.Values)p FN(\).)58 b(Option)0 742 y(ar)o(guments)17 b(\(and)i(v)n(arious)f(other)h(v)n(alues\))f(are)i(stored)e(as)j (attrib)n(utes)e(of)g(this)h(object,)f(according)e(to)j(the)f FJ(dest)g FN(\(destination\))f(option)0 842 y(attrib)n(ute.)0 989 y(F)o(or)i(e)o(xample,)e(when)i(you)f(call)236 1227 y FA(parser.parse_args\(\))0 1513 y FN(one)h(of)g(the)g(\002rst)h (things)e FJ(optparse)h FN(does)g(is)h(create)f(the)g FJ(options)f FN(object:)236 1751 y FA(options)44 b(=)h(Values\(\))0 2038 y FN(If)20 b(one)g(of)g(the)g(options)f(in)h(this)h(parser)f(is)h (de\002ned)e(with)236 2276 y FA(parser.add_option\("-f",)41 b("--file",)j(action="store",)e(type="string",)g(dest="filename"\))0 2563 y FN(and)20 b(the)g(command-line)d(being)i(parsed)h(includes)f(an) o(y)h(of)g(the)g(follo)n(wing:)236 2801 y FA(-ffoo)236 2892 y(-f)45 b(foo)236 2984 y(--file=foo)236 3075 y(--file)f(foo)0 3361 y FN(then)20 b FJ(optparse)p FN(,)f(on)h(seeing)f(this)i(option,)e (will)i(do)f(the)g(equi)n(v)n(alent)e(of)236 3508 y FA (options.filename)42 b(=)j("foo")0 3795 y FN(The)24 b FJ(type)f FN(and)h FJ(dest)f FN(option)g(attrib)n(utes)h(are)g(almost)g (as)g(important)f(as)h FJ(action)p FN(,)g(b)n(ut)g FJ(action)f FN(is)i(the)f(only)f(one)h(that)g(mak)o(es)0 3894 y(sense)d(for)e FK(all)i FN(options.)0 4163 y FI(Standard)j(option)g(actions)0 4366 y FN(The)29 b(v)n(arious)e(option)h(actions)g(all)i(ha)n(v)o(e)e (slightly)h(dif)n(ferent)e(requirements)g(and)h(ef)n(fects.)51 b(Most)29 b(actions)f(ha)n(v)o(e)h(se)n(v)o(eral)f(rele)n(v)n(ant)0 4465 y(option)21 b(attrib)n(utes)h(which)g(you)g(may)g(specify)f(to)i (guide)e FJ(optparse)p FN(')-5 b(s)22 b(beha)n(viour;)g(a)g(fe)n(w)h (ha)n(v)o(e)e(required)g(attrib)n(utes,)i(which)e(you)0 4565 y(must)f(specify)g(for)f(an)o(y)h(option)f(using)g(that)i(action.) 125 4778 y FM(\017)41 b FJ(store)19 b FN([rele)n(v)n(ant:)24 b FJ(type)p FN(,)c FJ(dest)p FN(,)g FJ(nargs)p FN(,)f FJ(choices)p FN(])208 4911 y(The)24 b(option)g(must)h(be)g(follo)n(wed) e(by)i(an)f(ar)o(gument,)g(which)g(is)i(con)m(v)o(erted)c(to)k(a)f(v)n (alue)f(according)f(to)i FJ(type)g FN(and)f(stored)g(in)208 5011 y FJ(dest)p FN(.)50 b(If)28 b FJ(nargs)g Ft(>)h FN(1,)i(multiple)d(ar)o(guments)e(will)k(be)e(consumed)f(from)h(the)g (command)f(line;)33 b(all)c(will)h(be)e(con)m(v)o(erted)208 5110 y(according)18 b(to)i FJ(type)g FN(and)g(stored)f(to)i FJ(dest)f FN(as)h(a)f(tuple.)25 b(See)20 b(the)h(\223Option)e (types\224)h(section)g(belo)n(w)-5 b(.)208 5243 y(If)20 b FJ(choices)f FN(is)i(supplied)e(\(a)i(list)g(or)f(tuple)g(of)f (strings\),)h(the)g(type)g(def)o(aults)g(to)g FJ(choice)p FN(.)208 5376 y(If)g FJ(type)g FN(is)h(not)f(supplied,)e(it)j(def)o (aults)f(to)g FJ(string)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h (command)f(line)i(option)f(parser)1426 b(433)p eop end %%Page: 434 446 TeXDict begin 434 445 bop 208 83 a FN(If)31 b FJ(dest)g FN(is)h(not)e(supplied,)j FJ(optparse)d FN(deri)n(v)o(es)g(a)i (destination)e(from)g(the)h(\002rst)h(long)e(option)g(string)h(\(e.g.,) i FL(--f)n(oo-bar)208 183 y FN(implies)26 b FJ(foo_bar)p FN(\).)42 b(If)26 b(there)g(are)g(no)g(long)g(option)f(strings,)j FJ(optparse)d FN(deri)n(v)o(es)g(a)i(destination)e(from)h(the)g (\002rst)h(short)208 282 y(option)19 b(string)g(\(e.g.,)g FJ("-f")h FN(implies)h FJ(f)p FN(\).)208 415 y(Example:)444 639 y FA(parser.add_option\("-f"\))444 731 y(parser.add_option\("-p",) 41 b(type="float",)h(nargs=3,)i(dest="point"\))208 1003 y FN(As)21 b(it)f(parses)h(the)f(command)e(line)444 1227 y FA(-f)44 b(foo.txt)g(-p)g(1)h(-3.5)f(4)h(-fbar.txt)208 1500 y FJ(optparse)19 b FN(will)i(set)444 1724 y FA(options.f)43 b(=)i("foo.txt")444 1815 y(options.point)d(=)j(\(1.0,)f(-3.5,)g(4.0\)) 444 1907 y(options.f)f(=)i("bar.txt")125 2212 y FM(\017)c FJ(store_const)18 b FN([required:)23 b FJ(const)p FN(;)d(rele)n(v)n (ant:)k FJ(dest)p FN(])208 2345 y(The)19 b(v)n(alue)h FJ(const)g FN(is)h(stored)f(in)g FJ(dest)p FN(.)208 2478 y(Example:)444 2611 y FA(parser.add_option\("-q",)41 b("--quiet",)1251 2702 y(action="store_const",)g(const=0,)j (dest="verbose"\))444 2793 y(parser.add_option\("-v",)d("--verbose",) 1251 2885 y(action="store_const",)g(const=1,)j(dest="verbose"\))444 2976 y(parser.add_option\("--noisy",)1251 3067 y(action="store_const",) d(const=2,)j(dest="verbose"\))208 3340 y FN(If)20 b FL(--noisy)f FN(is)i(seen,)f FJ(optparse)g FN(will)h(set)444 3565 y FA(options.verbose)42 b(=)j(2)125 3870 y FM(\017)c FJ(store_true)18 b FN([rele)n(v)n(ant:)24 b FJ(dest)p FN(])208 4003 y(A)c(special)h(case)f(of)g FJ(store_const)f FN(that)h(stores)h(a)f(true)g(v)n(alue)g(to)g FJ(dest)p FN(.)125 4169 y FM(\017)41 b FJ(store_false)18 b FN([rele)n(v)n(ant:)24 b FJ(dest)p FN(])208 4302 y(Lik)o(e)c FJ(store_true)p FN(,)e(b)n(ut)i(stores)h(a)g(f)o(alse)f(v)n(alue.)208 4435 y(Example:)444 4568 y FA(parser.add_option\("--clobber",)40 b(action="store_true",)h(dest="clobber"\))444 4659 y (parser.add_option\("--no-clobber",)e(action="store_false",)i (dest="clobber"\))125 4965 y FM(\017)g FJ(append)19 b FN([rele)n(v)n(ant:)24 b FJ(type)p FN(,)c FJ(dest)p FN(,)f FJ(nargs)p FN(,)h FJ(choices)p FN(])208 5097 y(The)25 b(option)g(must)h(be)h(follo)n(wed)d(by)i(an)g(ar)o(gument,)f(which)h (is)h(appended)d(to)i(the)g(list)i(in)e FJ(dest)p FN(.)43 b(If)26 b(no)f(def)o(ault)h(v)n(alue)f(for)208 5197 y FJ(dest)g FN(is)h(supplied,)g(an)f(empty)g(list)h(is)g(automatically)e (created)h(when)g FJ(optparse)f FN(\002rst)j(encounters)c(this)j (option)f(on)g(the)208 5297 y(command-line.)i(If)22 b FJ(nargs)g Ft(>)g FN(1,)g(multiple)g(ar)o(guments)e(are)i(consumed,)e (and)i(a)g(tuple)g(of)g(length)f FJ(nargs)h FN(is)h(appended)c(to)208 5396 y FJ(dest)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(434)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 435 447 TeXDict begin 435 446 bop 208 83 a FN(The)19 b(def)o(aults)h(for)g FJ(type)g FN(and)f FJ(dest)h FN(are)h(the)f(same)g(as)h(for)f(the)g FJ(store)g FN(action.)208 216 y(Example:)444 440 y FA (parser.add_option\("-t",)41 b("--tracks",)i(action="append",)f (type="int"\))208 712 y FN(If)20 b FJ("-t3")f FN(is)j(seen)e(on)g(the)g (command-line,)d FJ(optparse)i FN(does)h(the)g(equi)n(v)n(alent)f(of:) 444 937 y FA(options.tracks)42 b(=)j([])444 1028 y (options.tracks.append\(int\("3"\)\))208 1301 y FN(If,)19 b(a)i(little)g(later)f(on,)g FL(--tracks=4)f FN(is)i(seen,)f(it)h (does:)444 1525 y FA(options.tracks.append\(int\("4"\)\))125 1831 y FM(\017)41 b FJ(append_const)18 b FN([required:)23 b FJ(const)p FN(;)d(rele)n(v)n(ant:)k FJ(dest)p FN(])208 1964 y(Lik)o(e)f FJ(store_const)p FN(,)h(b)n(ut)g(the)g(v)n(alue)f FJ(const)h FN(is)h(appended)c(to)k FJ(dest)p FN(;)g(as)g(with)f FJ(append)p FN(,)g FJ(dest)g FN(def)o(aults)g(to)g FJ(None)p FN(,)208 2063 y(and)19 b(an)h(empty)g(list)h(is)g(automatically)e (created)g(the)h(\002rst)h(time)g(the)f(option)f(is)i(encountered.)125 2229 y FM(\017)41 b FJ(count)19 b FN([rele)n(v)n(ant:)24 b FJ(dest)p FN(])208 2362 y(Increment)e(the)j(inte)o(ger)f(stored)g(at) h FJ(dest)p FN(.)38 b(If)25 b(no)f(def)o(ault)g(v)n(alue)g(is)h (supplied,)g FJ(dest)f FN(is)i(set)f(to)g(zero)f(before)g(being)f (incre-)208 2462 y(mented)c(the)h(\002rst)h(time.)208 2595 y(Example:)444 2819 y FA(parser.add_option\("-v",)41 b(action="count",)h(dest="verbosity"\))208 3091 y FN(The)19 b(\002rst)i(time)g FJ("-v")f FN(is)h(seen)f(on)g(the)g(command)e(line,) i FJ(optparse)g FN(does)g(the)g(equi)n(v)n(alent)e(of:)444 3315 y FA(options.verbosity)42 b(=)i(0)444 3407 y(options.verbosity)e (+=)i(1)208 3679 y FN(Ev)o(ery)18 b(subsequent)h(occurrence)f(of)i FJ("-v")g FN(results)g(in)444 3903 y FA(options.verbosity)42 b(+=)i(1)125 4209 y FM(\017)d FJ(callback)19 b FN([required:)k FJ(callback)p FN(;)c(rele)n(v)n(ant:)24 b FJ(type)p FN(,)c FJ(nargs)p FN(,)g FJ(callback_args)p FN(,)e FJ(callback_kwargs)p FN(])208 4342 y(Call)j(the)f(function)e(speci\002ed)i(by)g FJ(callback)p FN(,)f(which)h(is)h(called)f(as)444 4475 y FA(func\(option,)43 b(opt_str,)g(value,)h(parser,)2103 4488 y(*)2148 4475 y(args,)2416 4488 y(**)2506 4475 y(kwargs\))208 4747 y FN(See)20 b(section)g(14.3.4,)e(Option)i(Callbacks)g(for)f(more) h(detail.)125 4913 y FM(\017)41 b FJ(help)208 5046 y FN(Prints)20 b(a)h(complete)f(help)g(message)g(for)g(all)h(the)f (options)g(in)g(the)h(current)e(option)g(parser)-5 b(.)26 b(The)20 b(help)g(message)g(is)h(constructed)208 5146 y(from)e(the)h FJ(usage)g FN(string)g(passed)g(to)g(OptionP)o(arser')-5 b(s)19 b(constructor)f(and)i(the)g FJ(help)g FN(string)g(passed)g(to)g (e)n(v)o(ery)f(option.)208 5279 y(If)g(no)h FJ(help)f FN(string)h(is)h(supplied)d(for)i(an)f(option,)g(it)h(will)h(still)g (be)f(listed)g(in)g(the)g(help)f(message.)25 b(T)-7 b(o)20 b(omit)g(an)f(option)g(entirely)-5 b(,)208 5378 y(use)20 b(the)g(special)g(v)n(alue)g FJ(optparse.SUPPRESS_HELP)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(435)p eop end %%Page: 436 448 TeXDict begin 436 447 bop 208 83 a FJ(optparse)19 b FN(automatically)g (adds)g(a)i FJ(help)f FN(option)f(to)h(all)h(OptionP)o(arsers,)e(so)h (you)g(do)f(not)h(normally)f(need)g(to)i(create)f(one.)208 216 y(Example:)444 440 y FA(from)44 b(optparse)f(import)h (OptionParser,)f(SUPPRESS_HELP)444 622 y(parser)h(=)g(OptionParser\(\)) 444 714 y(parser.add_option\("-h",)d("--help",)i(action="help"\),)444 805 y(parser.add_option\("-v",)e(action="store_true",)g (dest="verbose",)1251 896 y(help="Be)i(moderately)g(verbose"\))444 987 y(parser.add_option\("--file",)d(dest="filename",)1251 1079 y(help="Input)j(file)h(to)g(read)h(data)f(from"\),)444 1170 y(parser.add_option\("--secret",)c(help=SUPPRESS_HELP\))208 1442 y FN(If)30 b FJ(optparse)g FN(sees)h(either)g FL(h)g FN(or)f FL(--help)h FN(on)f(the)h(command)d(line,)34 b(it)d(will)g(print)f(something)f(lik)o(e)i(the)g(follo)n(wing)e(help) 208 1542 y(message)20 b(to)g(stdout)g(\(assuming)f FJ(sys.argv[0])f FN(is)k FJ("foo.py")p FN(\):)444 1766 y FA(usage:)44 b(foo.py)f([options])444 1949 y(options:)533 2040 y(-h,)i(--help)357 b(Show)45 b(this)f(help)g(message)g(and)g(exit)533 2131 y(-v)717 b(Be)45 b(moderately)e(verbose)533 2223 y(--file=FILENAME)132 b(Input)44 b(file)h(to)f(read)g(data)g(from)208 2495 y FN(After)19 b(printing)g(the)h(help)g(message,)g FJ(optparse)f FN(terminates)h(your)f(process)g(with)i FJ(sys.exit\(0\))p FN(.)125 2660 y FM(\017)41 b FJ(version)208 2793 y FN(Prints)30 b(the)f(v)o(ersion)g(number)f(supplied)g(to)i(the)g(OptionP)o(arser)e (to)i(stdout)f(and)g(e)o(xits.)54 b(The)29 b(v)o(ersion)g(number)f(is)i (actually)208 2893 y(formatted)e(and)h(printed)g(by)h(the)f FJ(print_version\(\))f FN(method)h(of)g(OptionP)o(arser)-5 b(.)54 b(Generally)28 b(only)i(rele)n(v)n(ant)e(if)j(the)208 2992 y FJ(version)21 b FN(ar)o(gument)f(is)j(supplied)e(to)i(the)f (OptionP)o(arser)f(constructor)-5 b(.)30 b(As)23 b(with)f FJ(help)g FN(options,)g(you)f(will)i(rarely)f(create)208 3092 y FJ(version)d FN(options,)g(since)h FJ(optparse)g FN(automatically)e(adds)i(them)g(when)g(needed.)0 3360 y FI(Option)k(attr)q(ib)n(utes)0 3563 y FN(The)e(follo)n(wing)f(option) g(attrib)n(utes)h(may)g(be)h(passed)f(as)h(k)o(e)o(yw)o(ord)e(ar)o (guments)f(to)i FJ(parser.add_option\(\))p FN(.)29 b(If)22 b(you)g(pass)h(an)0 3662 y(option)d(attrib)n(ute)h(that)g(is)h(not)f (rele)n(v)n(ant)g(to)g(a)h(particular)e(option,)g(or)h(f)o(ail)g(to)h (pass)g(a)f(required)f(option)g(attrib)n(ute,)h FJ(optparse)f FN(raises)0 3762 y(OptionError)-5 b(.)125 3974 y FM(\017)41 b FJ(action)19 b FN(\(def)o(ault:)24 b FJ("store")p FN(\))208 4107 y(Determines)h FJ(optparse)p FN(')-5 b(s)26 b(beha)n(viour)e(when) i(this)h(option)e(is)j(seen)e(on)g(the)h(command)d(line;)30 b(the)c(a)n(v)n(ailable)g(options)g(are)208 4207 y(documented)17 b(abo)o(v)o(e.)125 4372 y FM(\017)41 b FJ(type)20 b FN(\(def)o(ault:)k FJ("string")p FN(\))208 4505 y(The)f(ar)o(gument)e(type)i(e)o(xpected)f (by)h(this)h(option)e(\(e.g.,)i FJ("string")e FN(or)i FJ("int")p FN(\);)g(the)g(a)n(v)n(ailable)f(option)f(types)h(are)h (docu-)208 4604 y(mented)19 b(belo)n(w)-5 b(.)125 4770 y FM(\017)41 b FJ(dest)20 b FN(\(def)o(ault:)k(deri)n(v)o(ed)18 b(from)h(option)g(strings\))208 4903 y(If)j(the)g(option')-5 b(s)22 b(action)f(implies)i(writing)f(or)g(modifying)e(a)i(v)n(alue)g (some)n(where,)f(this)i(tells)h FJ(optparse)d FN(where)h(to)g(write)h (it:)208 5002 y FJ(dest)d FN(names)f(an)i(attrib)n(ute)e(of)h(the)g FJ(options)g FN(object)g(that)g FJ(optparse)f FN(b)n(uilds)h(as)h(it)g (parses)f(the)g(command)f(line.)125 5168 y FM(\017)41 b FJ(default)19 b FN(\(deprecated\))208 5300 y(The)25 b(v)n(alue)g(to)h(use)g(for)f(this)h(option')-5 b(s)25 b(destination)g(if)h(the)g(option)e(is)j(not)f(seen)f(on)h(the)g (command)d(line.)42 b(Deprecated;)27 b(use)208 5400 y FJ(parser.set_defaults\(\))16 b FN(instead.)p 0 5549 3901 4 v 0 5649 a FI(436)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 437 449 TeXDict begin 437 448 bop 125 83 a FM(\017)41 b FJ(nargs)19 b FN(\(def)o(ault:)25 b(1\))208 216 y(Ho)n(w)17 b(man)o(y)f(ar)o (guments)g(of)h(type)g FJ(type)g FN(should)g(be)g(consumed)f(when)h (this)h(option)e(is)j(seen.)24 b(If)17 b Ft(>)h FN(1,)g FJ(optparse)e FN(will)j(store)208 315 y(a)h(tuple)g(of)g(v)n(alues)g (to)g FJ(dest)p FN(.)125 482 y FM(\017)41 b FJ(const)208 614 y FN(F)o(or)19 b(actions)h(that)h(store)f(a)g(constant)g(v)n(alue,) f(the)h(constant)g(v)n(alue)f(to)i(store.)125 780 y FM(\017)41 b FJ(choices)208 913 y FN(F)o(or)19 b(options)h(of)g(type)f FJ("choice")p FN(,)g(the)h(list)i(of)e(strings)g(the)g(user)g(may)g (choose)f(from.)125 1079 y FM(\017)41 b FJ(callback)208 1212 y FN(F)o(or)20 b(options)g(with)h(action)f FJ("callback")p FN(,)g(the)h(callable)f(to)h(call)h(when)e(this)h(option)f(is)i(seen.) 27 b(See)21 b(section)f(14.3.4,)f(Option)208 1312 y(Callbacks)h(for)f (detail)i(on)e(the)i(ar)o(guments)d(passed)i(to)g FJ(callable)p FN(.)125 1478 y FM(\017)41 b FJ(callback_args)p FN(,)18 b FJ(callback_kwargs)208 1611 y FN(Additional)f(positional)h(and)g(k)o (e)o(yw)o(ord)g(ar)o(guments)e(to)j(pass)h(to)f FJ(callback)f FN(after)g(the)h(four)f(standard)g(callback)g(ar)o(guments.)125 1777 y FM(\017)41 b FJ(help)208 1910 y FN(Help)23 b(te)o(xt)g(to)h (print)e(for)h(this)h(option)e(when)h(listing)g(all)h(a)n(v)n(ailable)f (options)f(after)h(the)h(user)f(supplies)g(a)h FJ(help)f FN(option)f(\(such)208 2009 y(as)j FL(--help)p FN(\).)40 b(If)25 b(no)f(help)h(te)o(xt)g(is)h(supplied,)f(the)g(option)e(will)j (be)f(listed)h(without)e(help)h(te)o(xt.)39 b(T)-7 b(o)25 b(hide)g(this)g(option,)g(use)h(the)208 2109 y(special)20 b(v)n(alue)f FJ(SUPPRESS_HELP)p FN(.)125 2275 y FM(\017)41 b FJ(metavar)19 b FN(\(def)o(ault:)24 b(deri)n(v)o(ed)19 b(from)g(option)g(strings\))208 2408 y(Stand-in)14 b(for)h(the)g (option)f(ar)o(gument\(s\))f(to)i(use)h(when)e(printing)g(help)h(te)o (xt.)23 b(See)16 b(section)f(14.3.2,)f(the)i(tutorial)e(for)h(an)g(e)o (xample.)0 2676 y FI(Standard)24 b(option)g(types)0 2879 y FJ(optparse)19 b FN(has)g(six)h(b)n(uilt-in)f(option)f(types:)25 b FJ(string)p FN(,)19 b FJ(int)p FN(,)g FJ(long)p FN(,)g FJ(choice)p FN(,)g FJ(float)g FN(and)g FJ(complex)p FN(.)24 b(If)19 b(you)g(need)g(to)g(add)0 2978 y(ne)n(w)h(option)f(types,)h (see)g(section)g(14.3.5,)f(Extending)f FJ(optparse)p FN(.)0 3125 y(Ar)o(guments)k(to)j(string)f(options)g(are)g(not)g(check) o(ed)f(or)i(con)m(v)o(erted)c(in)k(an)o(y)f(w)o(ay:)33 b(the)25 b(te)o(xt)f(on)g(the)h(command)d(line)j(is)g(stored)f(in)h (the)0 3225 y(destination)19 b(\(or)h(passed)g(to)g(the)g(callback\))f (as-is.)0 3372 y(Inte)o(ger)g(ar)o(guments)f(\(type)h FJ(int)h FN(or)g FJ(long)p FN(\))g(are)g(parsed)f(as)i(follo)n(ws:)307 3585 y FM(\017)41 b FN(if)21 b(the)f(number)e(starts)j(with)g FJ(0x)p FN(,)f(it)h(is)g(parsed)e(as)i(a)g(he)o(xadecimal)d(number)307 3718 y FM(\017)41 b FN(if)21 b(the)f(number)e(starts)j(with)g FJ(0)p FN(,)f(it)h(is)g(parsed)e(as)i(an)g(octal)f(number)307 3851 y FM(\017)41 b FN(if)21 b(the)f(number)e(starts)j(with)g FJ(0b)p FN(,)f(it)h(is)g(parsed)e(as)i(a)g(binary)e(number)307 3984 y FM(\017)41 b FN(otherwise,)19 b(the)i(number)d(is)j(parsed)f(as) h(a)f(decimal)g(number)0 4197 y(The)j(con)m(v)o(ersion)d(is)k(done)e (by)h(calling)g(either)f FJ(int\(\))h FN(or)g FJ(long\(\))f FN(with)i(the)f(appropriate)e(base)i(\(2,)g(8,)h(10,)f(or)g(16\).)33 b(If)22 b(this)i(f)o(ails,)0 4297 y(so)d(will)f FJ(optparse)p FN(,)g(although)e(with)i(a)h(more)e(useful)h(error)f(message.)0 4443 y FJ(float)h FN(and)g FJ(complex)g FN(option)g(ar)o(guments)e(are) j(con)m(v)o(erted)d(directly)i(with)h FJ(float\(\))f FN(and)g FJ(complex\(\))p FN(,)f(with)i(similar)g(error)n(-)0 4543 y(handling.)0 4690 y FJ(choice)d FN(options)g(are)h(a)h(subtype)e (of)g FJ(string)h FN(options.)k(The)c FJ(choices)f FN(option)g(attrib)n (ute)h(\(a)g(sequence)e(of)i(strings\))g(de\002nes)g(the)0 4790 y(set)h(of)e(allo)n(wed)g(option)g(ar)o(guments.)k FJ(optparse.check_choice\(\))15 b FN(compares)j(user)n(-supplied)f (option)g(ar)o(guments)g(against)0 4889 y(this)k(master)f(list)h(and)f (raises)h(OptionV)-9 b(alueError)16 b(if)21 b(an)f(in)m(v)n(alid)f (string)h(is)h(gi)n(v)o(en.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h (command)f(line)i(option)f(parser)1426 b(437)p eop end %%Page: 438 450 TeXDict begin 438 449 bop 0 83 a FI(P)m(arsing)23 b(arguments)0 286 y FN(The)d(whole)g(point)f(of)h(creating)f(and)h(populating)e(an)i (OptionP)o(arser)e(is)j(to)g(call)f(its)i FJ(parse_args\(\))c FN(method:)236 524 y FA(\(options,)44 b(args\))g(=)g (parser.parse_args\(args=None,)c(values=None\))0 811 y FN(where)20 b(the)g(input)f(parameters)g(are)0 1013 y FD(args)41 b FN(the)20 b(list)h(of)f(ar)o(guments)e(to)j(process)e (\(def)o(ault:)25 b FJ(sys.argv[1:])p FN(\))0 1174 y FD(values)40 b FN(object)20 b(to)g(store)h(option)d(ar)o(guments)h(in)h (\(def)o(ault:)k(a)d(ne)n(w)f(instance)g(of)f(optparse.V)-9 b(alues\))0 1376 y(and)20 b(the)g(return)f(v)n(alues)h(are)0 1578 y FD(options)40 b FN(the)20 b(same)h(object)e(that)i(w)o(as)g (passed)f(in)g(as)h FJ(options)p FN(,)e(or)h(the)g(optparse.V)-9 b(alues)19 b(instance)g(created)h(by)g FJ(optparse)0 1739 y FD(args)41 b FN(the)20 b(lefto)o(v)o(er)e(positional)i(ar)o (guments)e(after)i(all)g(options)g(ha)n(v)o(e)f(been)h(processed)0 1942 y(The)k(most)h(common)e(usage)h(is)i(to)f(supply)f(neither)f(k)o (e)o(yw)o(ord)g(ar)o(gument.)36 b(If)25 b(you)f(supply)f FJ(options)p FN(,)i(it)h(will)f(be)g(modi\002ed)e(with)0 2041 y(repeated)f FJ(setattr\(\))g FN(calls)i(\(roughly)d(one)h(for)h (e)n(v)o(ery)f(option)g(ar)o(gument)f(stored)i(to)g(an)g(option)f (destination\))g(and)h(returned)e(by)0 2141 y FJ(parse_args\(\))p FN(.)0 2288 y(If)h FJ(parse_args\(\))e FN(encounters)g(an)o(y)h(errors) g(in)h(the)g(ar)o(gument)d(list,)k(it)g(calls)g(the)e(OptionP)o(arser') -5 b(s)21 b FJ(error\(\))g FN(method)g(with)h(an)0 2387 y(appropriate)h(end-user)g(error)h(message.)39 b(This)25 b(ultimately)f(terminates)g(your)g(process)g(with)h(an)g(e)o(xit)g (status)h(of)e(2)h(\(the)g(traditional)2 2487 y(U)t FH(N)t(I)t(X)e FN(e)o(xit)d(status)h(for)f(command-line)d(errors\).)0 2753 y FI(Quer)r(ying)23 b(and)h(manipulating)i(y)n(our)d(option)h (parser)0 2956 y FN(Sometimes,)29 b(it')-5 b(s)29 b(useful)e(to)h(pok)o (e)f(around)f(your)h(option)f(parser)h(and)h(see)g(what')-5 b(s)28 b(there.)48 b(OptionP)o(arser)26 b(pro)o(vides)g(a)i(couple)f (of)0 3055 y(methods)19 b(to)h(help)g(you)f(out:)0 3258 y FD(has_option\(opt_str\))38 b FN(Return)24 b(true)h(if)g(the)g (OptionP)o(arser)e(has)j(an)e(option)g(with)h(option)f(string)g FJ(opt_str)h FN(\(e.g.,)g FL(-q)g FN(or)208 3357 y FL(--v)o(erbose)p FN(\).)0 3518 y FD(get_option\(opt_str\))38 b FN(Returns)29 b(the)f(Option)g(instance)h(with)g(the)f(option)g(string)g FJ(opt_str)p FN(,)i(or)f FJ(None)f FN(if)h(no)g(options)208 3618 y(ha)n(v)o(e)19 b(that)h(option)f(string.)0 3778 y FD(remove_option\(opt_str\))37 b FN(If)31 b(the)f(OptionP)o(arser)f (has)i(an)f(option)f(corresponding)e(to)k FJ(opt_str)p FN(,)h(that)e(option)f(is)j(re-)208 3878 y(mo)o(v)o(ed.)22 b(If)d(that)h(option)e(pro)o(vided)f(an)o(y)h(other)h(option)f (strings,)h(all)h(of)f(those)g(option)f(strings)i(become)e(in)m(v)n (alid.)23 b(If)c FJ(opt_str)208 3977 y FN(does)g(not)h(occur)f(in)i(an) o(y)e(option)g(belonging)f(to)i(this)h(OptionP)o(arser)m(,)d(raises)j (V)-9 b(alueError)k(.)0 4243 y FI(Con\003icts)22 b(betw)o(een)i (options)0 4446 y FN(If)c(you')l(re)e(not)i(careful,)f(it')-5 b(s)21 b(easy)g(to)f(de\002ne)g(options)f(with)h(con\003icting)f (option)g(strings:)236 4684 y FA(parser.add_option\("-n",)41 b("--dry-run",)i(...\))236 4776 y([...])236 4867 y (parser.add_option\("-n",)e("--noisy",)i(...\))0 5154 y FN(\(This)20 b(is)h(particularly)e(true)g(if)i(you')l(v)o(e)d (de\002ned)h(your)g(o)n(wn)h(OptionP)o(arser)e(subclass)j(with)f(some)g (standard)f(options.\))0 5300 y(Ev)o(ery)25 b(time)h(you)f(add)h(an)g (option,)g FJ(optparse)f FN(checks)g(for)h(con\003icts)g(with)g(e)o (xisting)f(options.)42 b(If)26 b(it)g(\002nds)h(an)o(y)-5 b(,)26 b(it)g(in)m(v)n(ok)o(es)g(the)0 5400 y(current)19 b(con\003ict-handling)e(mechanism.)24 b(Y)-9 b(ou)19 b(can)h(set)h(the)f(con\003ict-handling)d(mechanism)i(either)h(in)g (the)h(constructor:)p 0 5549 3901 4 v 0 5649 a FI(438)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 439 451 TeXDict begin 439 450 bop 236 174 a FA(parser)44 b(=)h (OptionParser\(...,)d(conflict_handler=handler\))0 461 y FN(or)20 b(with)g(a)h(separate)f(call:)236 699 y FA (parser.set_conflict_handler\(handler\))0 986 y FN(The)g(a)n(v)n (ailable)g(con\003ict)f(handlers)g(are:)208 1199 y FD(error)g FL(\(default\))40 b FN(assume)20 b(option)f(con\003icts)h(are)h(a)f (programming)d(error)i(and)h(raise)g(OptionCon\003ictError)208 1331 y FD(resolve)40 b FN(resolv)o(e)19 b(option)g(con\003icts)h (intelligently)f(\(see)i(belo)n(w\))0 1544 y(As)g(an)f(e)o(xample,)f (let')-5 b(s)21 b(de\002ne)e(an)i(OptionP)o(arser)d(that)i(resolv)o(es) g(con\003icts)g(intelligently)f(and)h(add)g(con\003icting)e(options)i (to)g(it:)236 1783 y FA(parser)44 b(=)h (OptionParser\(conflict_handler="resolv)o(e"\))236 1874 y(parser.add_option\("-n",)c("--dry-run",)i(...,)h(help="do)g(no)g (harm"\))236 1965 y(parser.add_option\("-n",)d("--noisy",)i(...,)h (help="be)g(noisy"\))0 2252 y FN(At)32 b(this)g(point,)h FJ(optparse)e FN(detects)g(that)h(a)f(pre)n(viously-added)d(option)i (is)i(already)f(using)f(the)i FJ("-n")f FN(option)f(string.)59 b(Since)0 2351 y FJ(conflict_handler)21 b FN(is)k FJ("resolve")p FN(,)d(it)j(resolv)o(es)e(the)g(situation)g(by)g(remo)o(ving)e FJ("-n")j FN(from)e(the)i(earlier)f(option')-5 b(s)22 b(list)j(of)0 2451 y(option)d(strings.)35 b(No)n(w)23 b FL(--dry-run)g FN(is)h(the)g(only)e(w)o(ay)i(for)f(the)g(user)g(to)h (acti)n(v)n(ate)f(that)h(option.)33 b(If)23 b(the)h(user)f(asks)h(for)f (help,)h(the)f(help)0 2551 y(message)d(will)h(re\003ect)f(that:)236 2789 y FA(options:)326 2880 y(--dry-run)223 b(do)44 b(no)h(harm)326 2971 y([...])326 3063 y(-n,)f(--noisy)134 b(be)44 b(noisy)0 3349 y FN(It')-5 b(s)21 b(possible)f(to)g(whittle)h(a)o(w)o(ay)e(the)i (option)e(strings)h(for)f(a)i(pre)n(viously-added)16 b(option)j(until)h(there)g(are)g(none)f(left,)h(and)g(the)g(user)g(has) 0 3449 y(no)h(w)o(ay)h(of)g(in)m(v)n(oking)e(that)i(option)e(from)h (the)h(command-line.)27 b(In)22 b(that)g(case,)g FJ(optparse)f FN(remo)o(v)o(es)f(that)i(option)f(completely)-5 b(,)20 b(so)0 3549 y(it)h(doesn')o(t)e(sho)n(w)h(up)f(in)i(help)e(te)o(xt)h (or)g(an)o(ywhere)f(else.)25 b(Carrying)19 b(on)h(with)g(our)g(e)o (xisting)f(OptionP)o(arser:)236 3787 y FA (parser.add_option\("--dry-run",)40 b(...,)k(help="new)f(dry-run)h (option"\))0 4073 y FN(At)27 b(this)h(point,)f(the)g(original)e FL(-n)p FN(/)p FL(--dry-run)h FN(option)f(is)j(no)e(longer)g (accessible,)i(so)f FJ(optparse)f FN(remo)o(v)o(es)f(it,)k(lea)n(ving)d (this)h(help)0 4173 y(te)o(xt:)236 4411 y FA(options:)326 4502 y([...])326 4594 y(-n,)44 b(--noisy)134 b(be)44 b(noisy)326 4685 y(--dry-run)223 b(new)44 b(dry-run)g(option)0 5097 y FI(Clean)o(up)0 5300 y FN(OptionP)o(arser)23 b(instances)h(ha)n (v)o(e)g(se)n(v)o(eral)g(c)o(yclic)g(references.)37 b(This)24 b(should)g(not)g(be)g(a)h(problem)e(for)h(Python')-5 b(s)24 b(garbage)e(collector)m(,)0 5400 y(b)n(ut)k(you)g(may)g(wish)h (to)g(break)e(the)h(c)o(yclic)h(references)e(e)o(xplicitly)g(by)h (calling)g FJ(destroy\(\))g FN(on)g(your)f(OptionP)o(arser)g(once)g (you)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(439)p eop end %%Page: 440 452 TeXDict begin 440 451 bop 0 83 a FN(are)20 b(done)g(with)g(it.)27 b(This)20 b(is)i(particularly)c(useful)i(in)h(long-running)16 b(applications)k(where)g(lar)o(ge)f(object)h(graphs)f(are)i(reachable)e (from)0 183 y(your)g(OptionP)o(arser)-5 b(.)0 444 y FI(Other)23 b(methods)0 647 y FN(OptionP)o(arser)c(supports)g(se)n(v)o(eral)g (other)h(public)f(methods:)125 828 y FM(\017)41 b FJ (set_usage\(usage\))208 953 y FN(Set)33 b(the)f(usage)h(string)f (according)e(to)j(the)f(rules)h(described)e(abo)o(v)o(e)g(for)h(the)h FJ(usage)f FN(constructor)e(k)o(e)o(yw)o(ord)h(ar)o(gument.)208 1052 y(P)o(assing)20 b FJ(None)g FN(sets)h(the)f(def)o(ault)g(usage)g (string;)g(use)g FJ(SUPPRESS_USAGE)e FN(to)i(suppress)g(a)h(usage)f (message.)125 1202 y FM(\017)41 b FJ(enable_interspersed_args\(\))p FN(,)15 b FJ(disable_interspersed_args\(\))208 1327 y FN(Enable/disable)j(positional)h(ar)o(guments)f(interspersed)h(with)i (options,)d(similar)j(to)f(GNU)h(getopt)e(\(enabled)f(by)i(def)o (ault\).)k(F)o(or)208 1427 y(e)o(xample,)18 b(if)j FJ("-a")f FN(and)g FJ("-b")g FN(are)g(both)g(simple)g(options)g(that)g(tak)o(e)h (no)f(ar)o(guments,)e FJ(optparse)h FN(normally)g(accepts)h(this)208 1527 y(syntax:)444 1743 y FA(prog)44 b(-a)g(arg1)h(-b)f(arg2)208 2007 y FN(and)19 b(treats)i(it)g(as)g(equi)n(v)n(alent)d(to)444 2223 y FA(prog)44 b(-a)g(-b)h(arg1)f(arg2)208 2488 y FN(T)-7 b(o)30 b(disable)g(this)h(feature,)g(call)g FJ (disable_interspersed_args\(\))p FN(.)51 b(This)30 b(restores)g (traditional)h(U)t FH(N)t(I)t(X)i FN(syntax,)208 2587 y(where)19 b(option)g(parsing)g(stops)i(with)f(the)g(\002rst)h (non-option)c(ar)o(gument.)125 2737 y FM(\017)41 b FJ (set_defaults\(dest=value,)k(...\))208 2862 y FN(Set)19 b(def)o(ault)g(v)n(alues)f(for)h(se)n(v)o(eral)f(option)g(destinations) h(at)g(once.)24 b(Using)19 b FJ(set_defaults\(\))e FN(is)j(the)f (preferred)e(w)o(ay)i(to)h(set)208 2962 y(def)o(ault)c(v)n(alues)h(for) g(options,)g(since)g(multiple)g(options)g(can)g(share)g(the)g(same)h (destination.)23 b(F)o(or)17 b(e)o(xample,)f(if)i(se)n(v)o(eral)f (\223mode\224)208 3062 y(options)i(all)i(set)g(the)f(same)g (destination,)f(an)o(y)g(one)h(of)g(them)g(can)g(set)h(the)f(def)o (ault,)f(and)h(the)g(last)h(one)f(wins:)444 3278 y FA (parser.add_option\("--advanced",)39 b(action="store_const",)1251 3369 y(dest="mode",)k(const="advanced",)1251 3460 y(default="novice"\)) 176 b(#)45 b(overridden)e(below)444 3552 y (parser.add_option\("--novice",)d(action="store_const",)1251 3643 y(dest="mode",)j(const="novice",)1251 3734 y(default="advanced"\)) 86 b(#)45 b(overrides)e(above)h(setting)208 3999 y FN(T)-7 b(o)20 b(a)n(v)n(oid)g(this)h(confusion,)c(use)k FJ(set_defaults\(\))p FN(:)444 4215 y FA(parser.set_defaults\(mode="advanced"\))444 4306 y(parser.add_option\("--advanced",)39 b(action="store_const",)1251 4398 y(dest="mode",)k(const="advanced"\))444 4489 y (parser.add_option\("--novice",)d(action="store_const",)1251 4580 y(dest="mode",)j(const="novice"\))0 4998 y Fv(14.3.4)101 b(Option)28 b(Callbac)n(ks)0 5201 y FN(When)j FJ(optparse)p FN(')-5 b(s)30 b(b)n(uilt-in)g(actions)g(and)h(types)f(aren')o(t)g (quite)g(enough)f(for)h(your)f(needs,)k(you)d(ha)n(v)o(e)g(tw)o(o)h (choices:)46 b(e)o(xtend)0 5300 y FJ(optparse)20 b FN(or)g(de\002ne)g (a)h(callback)e(option.)25 b(Extending)18 b FJ(optparse)i FN(is)h(more)f(general,)f(b)n(ut)h(o)o(v)o(erkill)f(for)h(a)h(lot)f(of) h(simple)f(cases.)0 5400 y(Quite)g(often)g(a)g(simple)g(callback)g(is)h (all)g(you)e(need.)p 0 5549 3901 4 v 0 5649 a FI(440)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 441 453 TeXDict begin 441 452 bop 0 83 a FN(There)19 b(are)h(tw)o(o)h(steps)g (to)f(de\002ning)f(a)i(callback)e(option:)125 296 y FM(\017)41 b FN(de\002ne)19 b(the)h(option)f(itself)i(using)f(the)g FJ(callback)f FN(action)125 462 y FM(\017)41 b FN(write)20 b(the)g(callback;)g(this)g(is)h(a)g(function)e(\(or)g(method\))g(that)h (tak)o(es)g(at)h(least)g(four)e(ar)o(guments,)f(as)j(described)e(belo)n (w)0 731 y FI(De\002ning)24 b(a)f(callbac)n(k)g(option)0 934 y FN(As)c(al)o(w)o(ays,)f(the)g(easiest)g(w)o(ay)g(to)g(de\002ne)f (a)h(callback)f(option)g(is)h(by)g(using)f(the)h FJ (parser.add_option\(\))d FN(method.)22 b(Apart)c(from)0 1033 y FJ(action)p FN(,)h(the)i(only)e(option)g(attrib)n(ute)h(you)f (must)h(specify)g(is)h FJ(callback)p FN(,)e(the)h(function)f(to)h (call:)236 1180 y FA(parser.add_option\("-c",)41 b(action="callback",)h (callback=my_callback\))0 1467 y FJ(callback)24 b FN(is)h(a)g(function) e(\(or)g(other)h(callable)g(object\),)h(so)f(you)g(must)g(ha)n(v)o(e)g (already)g(de\002ned)f FJ(my_callback\(\))g FN(when)g(you)0 1566 y(create)30 b(this)g(callback)f(option.)54 b(In)29 b(this)i(simple)f(case,)i FJ(optparse)e FN(doesn')o(t)e(e)n(v)o(en)h (kno)n(w)g(if)h FL(-c)g FN(tak)o(es)h(an)o(y)e(ar)o(guments,)h(which)0 1666 y(usually)d(means)g(that)h(the)g(option)e(tak)o(es)i(no)f(ar)o (guments\227the)e(mere)j(presence)e(of)i FL(-c)f FN(on)h(the)f (command-line)e(is)k(all)f(it)g(needs)f(to)0 1765 y(kno)n(w)-5 b(.)35 b(In)23 b(some)h(circumstances,)f(though,)g(you)g(might)h(w)o (ant)g(your)e(callback)h(to)h(consume)f(an)h(arbitrary)e(number)g(of)i (command-)0 1865 y(line)c(ar)o(guments.)j(This)e(is)g(where)e(writing)h (callbacks)g(gets)g(trick)o(y;)f(it')-5 b(s)22 b(co)o(v)o(ered)c(later) i(in)g(this)h(section.)0 2012 y FJ(optparse)c FN(al)o(w)o(ays)h(passes) g(four)e(particular)g(ar)o(guments)g(to)i(your)e(callback,)h(and)g(it)h (will)g(only)f(pass)h(additional)e(ar)o(guments)g(if)h(you)0 2112 y(specify)j(them)f(via)i FJ(callback_args)d FN(and)h FJ(callback_kwargs)p FN(.)k(Thus,)d(the)g(minimal)f(callback)h (function)e(signature)h(is:)236 2258 y FA(def)45 b (my_callback\(option,)c(opt,)j(value,)g(parser\):)0 2545 y FN(The)20 b(four)f(ar)o(guments)f(to)i(a)h(callback)e(are)i (described)d(belo)n(w)-5 b(.)0 2692 y(There)19 b(are)h(se)n(v)o(eral)g (other)f(option)g(attrib)n(utes)h(that)h(you)e(can)h(supply)f(when)h (you)f(de\002ne)h(a)g(callback)g(option:)0 2905 y FD(type)41 b FN(has)15 b(its)h(usual)g(meaning:)21 b(as)16 b(with)f(the)g FJ(store)g FN(or)g FJ(append)g FN(actions,)h(it)g(instructs)f FJ(optparse)f FN(to)h(consume)f(one)h(ar)o(gument)208 3005 y(and)22 b(con)m(v)o(ert)g(it)i(to)g FJ(type)p FN(.)34 b(Rather)24 b(than)f(storing)f(the)i(con)m(v)o(erted)d(v)n(alue\(s\))h (an)o(ywhere,)g(though,)g FJ(optparse)h FN(passes)h(it)g(to)208 3104 y(your)18 b(callback)i(function.)0 3270 y FD(nargs)41 b FN(also)24 b(has)h(its)h(usual)e(meaning:)33 b(if)24 b(it)i(is)f(supplied)f(and)g Ft(>)g FN(1,)i FJ(optparse)e FN(will)h(consume)e FJ(nargs)h FN(ar)o(guments,)g(each)g(of)208 3370 y(which)19 b(must)h(be)h(con)m(v)o(ertible)c(to)k FJ(type)p FN(.)j(It)d(then)f(passes)g(a)h(tuple)f(of)g(con)m(v)o(erted) d(v)n(alues)j(to)g(your)f(callback.)0 3536 y FD(callback_args)39 b FN(a)21 b(tuple)e(of)h(e)o(xtra)g(positional)f(ar)o(guments)f(to)j (pass)f(to)h(the)f(callback)0 3702 y FD(callback_kwargs)39 b FN(a)20 b(dictionary)f(of)h(e)o(xtra)f(k)o(e)o(yw)o(ord)f(ar)o (guments)h(to)h(pass)h(to)f(the)g(callback)0 3970 y FI(Ho)o(w)j (callbac)n(ks)g(are)g(called)0 4173 y FN(All)e(callbacks)f(are)g (called)g(as)h(follo)n(ws:)236 4320 y FA(func\(option,)43 b(opt_str,)h(value,)f(parser,)1895 4333 y(*)1940 4320 y(args,)2209 4333 y(**)2299 4320 y(kwargs\))0 4607 y FN(where)0 4820 y FD(option)d FN(is)22 b(the)e(Option)f(instance)h (that')-5 b(s)21 b(calling)e(the)i(callback)0 4986 y FD(opt_str)40 b FN(is)21 b(the)e(option)g(string)g(seen)h(on)f(the)g (command-line)e(that')-5 b(s)20 b(triggering)e(the)h(callback.)24 b(\(If)19 b(an)h(abbre)n(viated)d(long)i(option)208 5086 y(w)o(as)24 b(used,)f FJ(opt_str)g FN(will)h(be)f(the)g(full,)h (canonical)e(option)g(string\227e.g.)33 b(if)24 b(the)f(user)g(puts)g FL(--f)n(oo)f FN(on)h(the)g(command-line)208 5185 y(as)d(an)h(abbre)n (viation)c(for)j FL(--f)n(oobar)p FN(,)e(then)i FJ(opt_str)f FN(will)i(be)f FL(--f)n(oobar)p FN(.\))p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o (erful)h(command)f(line)i(option)f(parser)1426 b(441)p eop end %%Page: 442 454 TeXDict begin 442 453 bop 0 83 a FD(value)41 b FN(is)22 b(the)f(ar)o(gument)e(to)j(this)g(option)e(seen)h(on)g(the)h (command-line.)j FJ(optparse)c FN(will)h(only)e(e)o(xpect)h(an)g(ar)o (gument)e(if)j FJ(type)208 183 y FN(is)32 b(set;)37 b(the)31 b(type)g(of)g FJ(value)g FN(will)h(be)f(the)g(type)g(implied)f(by)h (the)g(option')-5 b(s)31 b(type.)57 b(If)31 b FJ(type)g FN(for)g(this)h(option)e(is)i FJ(None)208 282 y FN(\(no)26 b(ar)o(gument)e(e)o(xpected\),)i(then)g FJ(value)h FN(will)g(be)g FJ(None)p FN(.)44 b(If)27 b FJ(nargs)f Ft(>)h FN(1,)h FJ(value)f FN(will)g(be)g(a)g(tuple)f(of)h(v)n(alues)f(of)h(the)208 382 y(appropriate)17 b(type.)0 548 y FD(parser)40 b FN(is)32 b(the)e(OptionP)o(arser)f(instance)h(dri)n(ving)f(the)h(whole)g(thing,) i(mainly)d(useful)h(because)g(you)f(can)h(access)h(some)f(other)208 648 y(interesting)19 b(data)h(through)e(its)j(instance)f(attrib)n (utes:)208 814 y FD(parser.largs)39 b FN(the)20 b(current)e(list)j(of)f (lefto)o(v)o(er)e(ar)o(guments,)g(ie.)25 b(ar)o(guments)18 b(that)i(ha)n(v)o(e)f(been)h(consumed)e(b)n(ut)i(are)f(neither)390 913 y(options)f(nor)h(option)f(ar)o(guments.)k(Feel)e(free)f(to)g (modify)e FJ(parser.largs)p FN(,)h(e.g.)24 b(by)19 b(adding)e(more)i (ar)o(guments)e(to)i(it.)390 1013 y(\(This)h(list)i(will)e(become)f FJ(args)p FN(,)h(the)g(second)g(return)f(v)n(alue)g(of)h FJ(parse_args\(\))p FN(.\))208 1146 y FD(parser.rargs)39 b FN(the)26 b(current)e(list)j(of)e(remaining)f(ar)o(guments,)h(ie.)42 b(with)26 b FJ(opt_str)f FN(and)g FJ(value)g FN(\(if)h(applicable\))e (re-)390 1245 y(mo)o(v)o(ed,)c(and)i(only)f(the)h(ar)o(guments)e(follo) n(wing)g(them)i(still)h(there.)30 b(Feel)22 b(free)g(to)g(modify)e FJ(parser.rargs)p FN(,)h(e.g.)30 b(by)390 1345 y(consuming)18 b(more)i(ar)o(guments.)208 1478 y FD(parser.values)39 b FN(the)16 b(object)h(where)f(option)f(v)n(alues)h(are)h(by)f(def)o (ault)g(stored)h(\(an)f(instance)g(of)h(optparse.OptionV)-9 b(alues\).)390 1577 y(This)20 b(lets)h(callbacks)e(use)i(the)e(same)i (mechanism)d(as)j(the)f(rest)g(of)g FJ(optparse)f FN(for)g(storing)g (option)g(v)n(alues;)g(you)g(don')o(t)390 1677 y(need)k(to)g(mess)h (around)d(with)j(globals)e(or)h(closures.)34 b(Y)-9 b(ou)23 b(can)g(also)g(access)h(or)f(modify)f(the)h(v)n(alue\(s\))f(of)h(an)o (y)g(options)390 1777 y(already)c(encountered)f(on)i(the)g (command-line.)0 1943 y FD(args)41 b FN(is)21 b(a)g(tuple)e(of)h (arbitrary)f(positional)g(ar)o(guments)f(supplied)h(via)i(the)f FJ(callback_args)e FN(option)h(attrib)n(ute.)0 2109 y FD(kwargs)40 b FN(is)22 b(a)e(dictionary)f(of)g(arbitrary)g(k)o(e)o(yw) o(ord)f(ar)o(guments)h(supplied)g(via)h FJ(callback_kwargs)p FN(.)0 2377 y FI(Raising)k(errors)e(in)h(a)h(callbac)n(k)0 2580 y FN(The)k(callback)g(function)f(should)h(raise)h(OptionV)-9 b(alueError)26 b(if)j(there)f(are)h(an)o(y)f(problems)f(with)i(the)g (option)e(or)i(its)h(ar)o(gument\(s\).)0 2680 y FJ(optparse)23 b FN(catches)h(this)g(and)f(terminates)g(the)h(program,)e(printing)h (the)g(error)g(message)h(you)f(supply)f(to)i(stderr)-5 b(.)36 b(Y)-9 b(our)23 b(message)0 2779 y(should)e(be)h(clear)m(,)f (concise,)h(accurate,)f(and)h(mention)e(the)i(option)f(at)h(f)o(ault.) 30 b(Otherwise,)22 b(the)g(user)g(will)g(ha)n(v)o(e)g(a)g(hard)f(time)h (\002guring)0 2879 y(out)e(what)g(he)g(did)g(wrong.)0 3147 y FI(Callbac)n(k)k(e)n(xample)f(1:)29 b(tr)q(ivial)24 b(callbac)n(k)0 3350 y FN(Here')-5 b(s)20 b(an)h(e)o(xample)d(of)i(a)h (callback)e(option)g(that)i(tak)o(es)f(no)g(ar)o(guments,)e(and)h (simply)h(records)f(that)i(the)f(option)f(w)o(as)i(seen:)236 3588 y FA(def)45 b(record_foo_seen\(option,)c(opt_str,)i(value,)h (parser\):)416 3680 y(parser.saw_foo)e(=)j(True)236 3862 y(parser.add_option\("--foo",)c(action="callback",)g (callback=record_foo_seen\))0 4149 y FN(Of)20 b(course,)g(you)f(could)g (do)h(that)g(with)g(the)h FJ(store_true)e FN(action.)0 4417 y FI(Callbac)n(k)24 b(e)n(xample)f(2:)29 b(chec)n(k)22 b(option)i(order)0 4620 y FN(Here')-5 b(s)24 b(a)f(slightly)h(more)e (interesting)h(e)o(xample:)30 b(record)22 b(the)h(f)o(act)h(that)f FJ("-a")h FN(is)g(seen,)g(b)n(ut)f(blo)n(w)g(up)g(if)h(it)g(comes)f (after)g FJ("-b")g FN(in)0 4720 y(the)d(command-line.)p 0 5549 3901 4 v 0 5649 a FI(442)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 443 455 TeXDict begin 443 454 bop 236 174 a FA(def)45 b(check_order\(option,)c (opt_str,)j(value,)f(parser\):)416 266 y(if)h(parser.values.b:)595 357 y(raise)g(OptionValueError\("can't)d(use)j(-a)h(after)f(-b"\))416 448 y(parser.values.a)e(=)j(1)236 540 y([...])236 631 y(parser.add_option\("-a",)c(action="callback",)h (callback=check_order\))236 722 y(parser.add_option\("-b",)f (action="store_true",)h(dest="b"\))0 1135 y FI(Callbac)n(k)24 b(e)n(xample)f(3:)29 b(chec)n(k)22 b(option)i(order)f(\(gener)o(aliz)o (ed\))0 1338 y FN(If)e(you)g(w)o(ant)g(to)g(re-use)g(this)h(callback)e (for)h(se)n(v)o(eral)g(similar)g(options)f(\(set)i(a)g(\003ag,)f(b)n (ut)g(blo)n(w)g(up)g(if)h FJ("-b")f FN(has)g(already)f(been)h(seen\),)0 1437 y(it)g(needs)f(a)g(bit)h(of)f(w)o(ork:)k(the)c(error)g(message)g (and)f(the)h(\003ag)h(that)f(it)h(sets)g(must)f(be)h(generalized.)236 1676 y FA(def)45 b(check_order\(option,)c(opt_str,)j(value,)f (parser\):)416 1767 y(if)h(parser.values.b:)595 1858 y(raise)g(OptionValueError\("can't)d(use)j(\045s)h(after)f(-b")g(\045)h (opt_str\))416 1949 y(setattr\(parser.values,)c(option.dest,)h(1\))236 2041 y([...])236 2132 y(parser.add_option\("-a",)f(action="callback",)h (callback=check_order,)f(dest='a'\))236 2223 y (parser.add_option\("-b",)g(action="store_true",)h(dest="b"\))236 2315 y(parser.add_option\("-c",)f(action="callback",)h (callback=check_order,)f(dest='c'\))0 2727 y FI(Callbac)n(k)24 b(e)n(xample)f(4:)29 b(chec)n(k)22 b(arbitr)o(ar)r(y)h(condition)0 2930 y FN(Of)c(course,)f(you)h(could)f(put)g(an)o(y)h(condition)e(in)i (there\227you')l(re)d(not)j(limited)g(to)g(checking)e(the)i(v)n(alues)g (of)g(already-de\002ned)d(options.)0 3030 y(F)o(or)k(e)o(xample,)e(if)j (you)e(ha)n(v)o(e)h(options)f(that)h(should)f(not)h(be)g(called)g(when) g(the)g(moon)f(is)i(full,)f(all)h(you)e(ha)n(v)o(e)h(to)g(do)g(is)h (this:)236 3268 y FA(def)45 b(check_moon\(option,)c(opt_str,)j(value,)g (parser\):)416 3359 y(if)g(is_moon_full\(\):)595 3451 y(raise)g(OptionValueError\("\045s)d(option)j(invalid)g(when)g(moon)g (is)h(full")1626 3542 y(\045)g(opt_str\))416 3633 y (setattr\(parser.values,)c(option.dest,)h(1\))236 3725 y([...])236 3816 y(parser.add_option\("--foo",)1043 3907 y(action="callback",)g(callback=check_moon,)f(dest="foo"\))0 4194 y FN(\(The)20 b(de\002nition)f(of)g FJ(is_moon_full\(\))g FN(is)i(left)f(as)h(an)f(e)o(x)o(ercise)f(for)h(the)g(reader)-5 b(.\))0 4462 y FI(Callbac)n(k)24 b(e)n(xample)f(5:)29 b(\002x)n(ed)22 b(arguments)0 4665 y FN(Things)g(get)h(slightly)f(more) g(interesting)g(when)g(you)g(de\002ne)g(callback)g(options)f(that)i (tak)o(e)g(a)g(\002x)o(ed)f(number)f(of)h(ar)o(guments.)31 b(Speci-)0 4765 y(fying)22 b(that)g(a)i(callback)d(option)h(tak)o(es)h (ar)o(guments)e(is)i(similar)g(to)g(de\002ning)f(a)h FJ(store)f FN(or)h FJ(append)f FN(option:)29 b(if)23 b(you)f(de\002ne)g FJ(type)p FN(,)0 4864 y(then)e(the)h(option)e(tak)o (es)i(one)f(ar)o(gument)e(that)j(must)f(be)h(con)m(v)o(ertible)d(to)j (that)f(type;)h(if)f(you)g(further)f(de\002ne)h FJ(nargs)p FN(,)g(then)g(the)h(option)0 4964 y(tak)o(es)g FJ(nargs)e FN(ar)o(guments.)0 5111 y(Here')-5 b(s)20 b(an)h(e)o(xample)d(that)j (just)f(emulates)g(the)g(standard)f FJ(store)h FN(action:)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(443)p eop end %%Page: 444 456 TeXDict begin 444 455 bop 236 174 a FA(def)45 b(store_value\(option,)c (opt_str,)j(value,)f(parser\):)416 266 y(setattr\(parser.values,)e (option.dest,)h(value\))236 357 y([...])236 448 y (parser.add_option\("--foo",)1043 540 y(action="callback",)g (callback=store_value,)1043 631 y(type="int",)h(nargs=3,)h (dest="foo"\))0 917 y FN(Note)23 b(that)h FJ(optparse)e FN(tak)o(es)i(care)f(of)g(consuming)e(3)i(ar)o(guments)f(and)g(con)m(v) o(erting)f(them)i(to)g(inte)o(gers)g(for)f(you;)i(all)g(you)f(ha)n(v)o (e)f(to)0 1017 y(do)e(is)h(store)f(them.)25 b(\(Or)20 b(whate)n(v)o(er;)e(ob)o(viously)g(you)i(don')o(t)e(need)i(a)g (callback)g(for)f(this)i(e)o(xample.\))0 1281 y FI(Callbac)n(k)j(e)n (xample)f(6:)29 b(v)n(ar)q(iab)n(le)24 b(arguments)0 1484 y FN(Things)g(get)i(hairy)e(when)h(you)f(w)o(ant)i(an)f(option)f (to)h(tak)o(e)g(a)h(v)n(ariable)e(number)g(of)h(ar)o(guments.)38 b(F)o(or)25 b(this)g(case,)i(you)d(must)i(write)f(a)0 1584 y(callback,)17 b(as)h FJ(optparse)e FN(doesn')o(t)g(pro)o(vide)f (an)o(y)h(b)n(uilt-in)h(capabilities)g(for)g(it.)24 b(And)17 b(you)f(ha)n(v)o(e)h(to)h(deal)f(with)g(certain)g(intricacies)g(of)0 1683 y(con)m(v)o(entional)k(U)t FH(N)t(I)t(X)k FN(command-line)19 b(parsing)i(that)i FJ(optparse)e FN(normally)f(handles)h(for)h(you.)30 b(In)21 b(particular)m(,)g(callbacks)h(should)0 1783 y(implement)d(the)h(con)m(v)o(entional)d(rules)j(for)g(bare)g FL(--)g FN(and)f FL(-)i FN(ar)o(guments:)125 1977 y FM(\017)41 b FN(either)19 b FL(--)h FN(or)g FL(-)h FN(can)f(be)g(option)f(ar)o (guments)125 2133 y FM(\017)41 b FN(bare)19 b FL(--)h FN(\(if)g(not)g(the)g(ar)o(gument)e(to)j(some)f(option\):)j(halt)e (command-line)c(processing)i(and)g(discard)h(the)g FL(--)125 2289 y FM(\017)41 b FN(bare)36 b FL(-)h FN(\(if)g(not)f(the)h(ar)o (gument)d(to)j(some)g(option\):)57 b(halt)37 b(command-line)d (processing)h(b)n(ut)i(k)o(eep)f(the)h FL(-)g FN(\(append)e(it)i(to)208 2389 y FJ(parser.largs)p FN(\))0 2582 y(If)20 b(you)f(w)o(ant)h(an)f (option)g(that)h(tak)o(es)g(a)g(v)n(ariable)f(number)f(of)i(ar)o (guments,)d(there)j(are)g(se)n(v)o(eral)f(subtle,)g(trick)o(y)g(issues) i(to)f(w)o(orry)f(about.)0 2682 y(The)k(e)o(xact)g(implementation)e (you)i(choose)f(will)j(be)e(based)g(on)g(which)g(trade-of)n(fs)f(you')l (re)f(willing)i(to)h(mak)o(e)f(for)g(your)f(application)0 2782 y(\(which)d(is)i(why)f FJ(optparse)f FN(doesn')o(t)g(support)f (this)j(sort)g(of)e(thing)h(directly\).)0 2929 y(Ne)n(v)o(ertheless,)f (here')-5 b(s)20 b(a)h(stab)f(at)h(a)f(callback)g(for)f(an)i(option)d (with)j(v)n(ariable)e(ar)o(guments:)236 3167 y FA(def)45 b(vararg_callback\(option,)c(opt_str,)i(value,)h(parser\):)416 3258 y(assert)f(value)h(is)h(None)416 3349 y(done)f(=)g(0)416 3441 y(value)g(=)g([])416 3532 y(rargs)g(=)g(parser.rargs)416 3623 y(while)g(rargs:)595 3715 y(arg)g(=)h(rargs[0])595 3897 y(#)g(Stop)f(if)g(we)h(hit)f(an)h(arg)f(like)g("--foo",)f("-a",)h ("-fx",)g("--file=f",)595 3989 y(#)h(etc.)89 b(Note)44 b(that)g(this)g(also)g(stops)g(on)h("-3")f(or)g("-3.0",)g(so)g(if)595 4080 y(#)h(your)f(option)g(takes)g(numeric)f(values,)h(you)g(will)g (need)g(to)h(handle)595 4171 y(#)g(this.)595 4263 y(if)f(\(\(arg[:2])g (==)g("--")g(and)h(len\(arg\))e(>)i(2\))f(or)774 4354 y(\(arg[:1])g(==)g("-")h(and)f(len\(arg\))f(>)i(1)g(and)f(arg[1])g(!=)g ("-"\)\):)774 4445 y(break)595 4537 y(else:)774 4628 y(value.append\(arg\))774 4719 y(del)h(rargs[0])460 4902 y(setattr\(parser.values,)d(option.dest,)g(value\))236 5085 y([...])236 5176 y(parser.add_option\("-c",)f("--callback",)1043 5267 y(action="callback",)h(callback=varargs\))p 0 5549 3901 4 v 0 5649 a FI(444)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 445 457 TeXDict begin 445 456 bop 0 83 a FN(The)26 b(main)g(weakness)h(with)f (this)i(particular)d(implementation)f(is)k(that)e(ne)o(gati)n(v)o(e)f (numbers)g(in)i(the)f(ar)o(guments)f(follo)n(wing)g FJ("-c")0 183 y FN(will)20 b(be)g(interpreted)e(as)j(further)d(options)h (\(probably)e(causing)i(an)g(error\),)f(rather)h(than)h(as)g(ar)o (guments)e(to)i FJ("-c")p FN(.)k(Fixing)19 b(this)i(is)f(left)0 282 y(as)h(an)f(e)o(x)o(ercise)f(for)h(the)g(reader)-5 b(.)0 567 y Fv(14.3.5)101 b(Extending)29 b Fm(optparse)0 770 y FN(Since)19 b(the)f(tw)o(o)h(major)f(controlling)f(f)o(actors)h (in)h(ho)n(w)g FJ(optparse)e FN(interprets)h(command-line)e(options)i (are)h(the)f(action)g(and)h(type)f(of)0 870 y(each)i(option,)f(the)h (most)g(lik)o(ely)g(direction)f(of)h(e)o(xtension)f(is)i(to)f(add)g(ne) n(w)g(actions)g(and)f(ne)n(w)h(types.)0 1138 y FI(Adding)25 b(ne)n(w)e(types)0 1341 y FN(T)-7 b(o)27 b(add)f(ne)n(w)g(types,)i(you) d(need)h(to)h(de\002ne)f(your)f(o)n(wn)h(subclass)h(of)f FJ(optparse)p FN(')-5 b(s)26 b(Option)g(class.)45 b(This)26 b(class)i(has)e(a)h(couple)f(of)0 1441 y(attrib)n(utes)20 b(that)g(de\002ne)g FJ(optparse)p FN(')-5 b(s)20 b(types:)25 b FJ(TYPES)20 b FN(and)f FJ(TYPE_CHECKER)p FN(.)0 1587 y FJ(TYPES)h FN(is)h(a)g(tuple)e(of)h(type)g(names;)g(in)g(your)f (subclass,)h(simply)g(de\002ne)g(a)h(ne)n(w)f(tuple)f FJ(TYPES)h FN(that)g(b)n(uilds)h(on)e(the)i(standard)e(one.)0 1734 y FJ(TYPE_CHECKER)j FN(is)i(a)f(dictionary)f(mapping)f(type)i (names)g(to)g(type-checking)d(functions.)33 b(A)24 b(type-checking)c (function)h(has)j(the)0 1834 y(follo)n(wing)19 b(signature:)236 2072 y FA(def)45 b(check_mytype\(option,)c(opt,)j(value\))0 2359 y FN(where)30 b FJ(option)f FN(is)j(an)e FJ(Option)g FN(instance,)i FJ(opt)e FN(is)i(an)e(option)f(string)h(\(e.g.,)i FJ("-f")p FN(\),)g(and)e FJ(value)g FN(is)h(the)f(string)g(from)g(the)0 2458 y(command)19 b(line)i(that)g(must)g(be)g(check)o(ed)f(and)g(con)m (v)o(erted)f(to)i(your)e(desired)i(type.)26 b FJ(check_mytype\(\))19 b FN(should)h(return)g(an)h(object)0 2558 y(of)i(the)g(hypothetical)d (type)j FJ(mytype)p FN(.)32 b(The)23 b(v)n(alue)f(returned)f(by)i(a)g (type-checking)d(function)h(will)j(wind)e(up)h(in)g(the)g(OptionV)-9 b(alues)0 2657 y(instance)20 b(returned)e(by)i FJ (OptionParser.parse_args\(\))p FN(,)c(or)k(be)g(passed)g(to)g(a)h (callback)e(as)i(the)f FJ(value)g FN(parameter)-5 b(.)0 2804 y(Y)c(our)22 b(type-checking)d(function)i(should)h(raise)h (OptionV)-9 b(alueError)19 b(if)k(it)g(encounters)e(an)o(y)h(problems.) 31 b(OptionV)-9 b(alueError)19 b(tak)o(es)k(a)0 2904 y(single)17 b(string)g(ar)o(gument,)f(which)h(is)h(passed)f(as-is)i(to) e(OptionP)o(arser')-5 b(s)16 b FJ(error\(\))h FN(method,)f(which)h(in)h (turn)f(prepends)e(the)j(program)0 3004 y(name)i(and)f(the)h(string)g FJ("error:")g FN(and)f(prints)h(e)n(v)o(erything)e(to)i(stderr)g (before)f(terminating)f(the)i(process.)0 3150 y(Here')-5 b(s)23 b(a)h(silly)g(e)o(xample)e(that)h(demonstrates)f(adding)g(a)i FJ(complex)e FN(option)g(type)h(to)g(parse)g(Python-style)f(comple)o(x) f(numbers)h(on)0 3250 y(the)f(command)d(line.)27 b(\(This)21 b(is)g(e)n(v)o(en)f(sillier)i(than)e(it)h(used)g(to)g(be,)f(because)g FJ(optparse)g FN(1.3)g(added)g(b)n(uilt-in)g(support)f(for)h(comple)o (x)0 3350 y(numbers,)e(b)n(ut)j(ne)n(v)o(er)d(mind.\))0 3497 y(First,)j(the)f(necessary)f(imports:)236 3735 y FA(from)44 b(copy)h(import)e(copy)236 3826 y(from)h(optparse)g(import)g (Option,)f(OptionValueError)0 4113 y FN(Y)-9 b(ou)22 b(need)g(to)g(de\002ne)g(your)g(type-check)o(er)e(\002rst,)j(since)g (it')-5 b(s)23 b(referred)e(to)i(later)f(\(in)h(the)f FJ(TYPE_CHECKER)f FN(class)i(attrib)n(ute)g(of)f(your)0 4212 y(Option)d(subclass\):)236 4450 y FA(def)45 b (check_complex\(option,)c(opt,)j(value\):)416 4542 y(try:)595 4633 y(return)g(complex\(value\))416 4724 y(except)f(ValueError:)595 4816 y(raise)h(OptionValueError\()774 4907 y("option)g(\045s:)g (invalid)g(complex)f(value:)h(\045r")h(\045)f(\(opt,)g(value\)\))0 5194 y FN(Finally)-5 b(,)19 b(the)i(Option)e(subclass:)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i(option)f(parser) 1426 b(445)p eop end %%Page: 446 458 TeXDict begin 446 457 bop 236 174 a FA(class)44 b(MyOption)g (\(Option\):)416 266 y(TYPES)g(=)g(Option.TYPES)f(+)i(\("complex",\)) 416 357 y(TYPE_CHECKER)d(=)j(copy\(Option.TYPE_CHECKER\))416 448 y(TYPE_CHECKER["complex"])c(=)j(check_complex)0 735 y FN(\(If)29 b(we)h(didn')o(t)e(mak)o(e)h(a)h FJ(copy\(\))f FN(of)g FJ(Option.TYPE_CHECKER)p FN(,)d(we)k(w)o(ould)f(end)g(up)g (modifying)e(the)i FJ(TYPE_CHECKER)0 834 y FN(attrib)n(ute)24 b(of)g FJ(optparse)p FN(')-5 b(s)24 b(Option)g(class.)38 b(This)25 b(being)e(Python,)h(nothing)f(stops)i(you)e(from)h(doing)f (that)h(e)o(xcept)g(good)f(manners)0 934 y(and)d(common)e(sense.\))0 1081 y(That')-5 b(s)19 b(it!)25 b(No)n(w)19 b(you)f(can)h(write)h(a)f (script)g(that)g(uses)h(the)f(ne)n(w)g(option)f(type)g(just)i(lik)o(e)f (an)o(y)f(other)h FJ(optparse)p FN(-based)d(script,)k(e)o(xcept)0 1181 y(you)f(ha)n(v)o(e)h(to)g(instruct)g(your)f(OptionP)o(arser)g(to)h (use)g(MyOption)f(instead)h(of)g(Option:)236 1419 y FA(parser)44 b(=)h(OptionParser\(option_class=MyOption\))236 1510 y(parser.add_option\("-c",)c(type="complex"\))0 1797 y FN(Alternately)-5 b(,)21 b(you)h(can)g(b)n(uild)g(your)f(o)n(wn)h (option)f(list)j(and)e(pass)h(it)g(to)g(OptionP)o(arser;)f(if)g(you)g (don')o(t)f(use)h FJ(add_option\(\))f FN(in)i(the)0 1896 y(abo)o(v)o(e)c(w)o(ay)-5 b(,)19 b(you)g(don')o(t)g(need)g(to)i(tell)g (OptionP)o(arser)d(which)i(option)f(class)i(to)f(use:)236 2134 y FA(option_list)43 b(=)i([MyOption\("-c",)d(action="store",)g (type="complex",)h(dest="c"\)])236 2226 y(parser)h(=)h (OptionParser\(option_list=option_list\))0 2637 y FI(Adding)25 b(ne)n(w)e(actions)0 2840 y FN(Adding)g(ne)n(w)h(actions)g(is)h(a)f (bit)h(trickier)m(,)e(because)h(you)f(ha)n(v)o(e)h(to)g(understand)e (that)i FJ(optparse)f FN(has)i(a)f(couple)f(of)h(classi\002cations)0 2940 y(for)c(actions:)0 3153 y FL(\223stor)o(e\224)e(actions)41 b FN(actions)20 b(that)g(result)g(in)g FJ(optparse)f FN(storing)g(a)i(v)n(alue)e(to)h(an)g(attrib)n(ute)g(of)g(the)g (current)e(OptionV)-9 b(alues)19 b(instance;)208 3253 y(these)h(options)f(require)g(a)i FJ(dest)f FN(attrib)n(ute)f(to)i(be)f (supplied)f(to)h(the)h(Option)e(constructor)0 3419 y FL(\223typed\224)g(actions)41 b FN(actions)26 b(that)g(tak)o(e)g(a)h(v) n(alue)f(from)f(the)h(command)e(line)j(and)f(e)o(xpect)f(it)i(to)f(be)g (of)g(a)h(certain)f(type;)j(or)d(rather)m(,)g(a)208 3518 y(string)19 b(that)i(can)f(be)g(con)m(v)o(erted)d(to)k(a)f(certain)g (type.)k(These)c(options)g(require)f(a)h FJ(type)g FN(attrib)n(ute)g (to)g(the)h(Option)e(constructor)-5 b(.)0 3731 y(These)23 b(are)h(o)o(v)o(erlapping)c(sets:)33 b(some)24 b(def)o(ault)f (\223store\224)g(actions)g(are)h FJ(store)p FN(,)f FJ(store_const)p FN(,)g FJ(append)p FN(,)h(and)f FJ(count)p FN(,)h(while)0 3831 y(the)c(def)o(ault)g(\223typed\224)f(actions)h(are)g FJ(store)p FN(,)f FJ(append)p FN(,)h(and)f FJ(callback)p FN(.)0 3978 y(When)f(you)f(add)h(an)g(action,)g(you)f(need)g(to)h(cate) o(gorize)f(it)i(by)f(listing)g(it)h(in)f(at)h(least)f(one)g(of)g(the)g (follo)n(wing)e(class)k(attrib)n(utes)e(of)f(Option)0 4078 y(\(all)j(are)h(lists)g(of)f(strings\):)0 4291 y FD(ACTIONS)40 b FN(all)21 b(actions)f(must)g(be)g(listed)h(in)f(A)m (CTIONS)0 4457 y FD(STORE_ACTIONS)39 b FN(\223store\224)20 b(actions)g(are)g(additionally)e(listed)j(here)0 4623 y FD(TYPED_ACTIONS)39 b FN(\223typed\224)19 b(actions)h(are)g (additionally)f(listed)h(here)0 4789 y FD(ALWAYS_TYPED_ACTIONS)38 b FN(actions)17 b(that)h(al)o(w)o(ays)h(tak)o(e)e(a)i(type)e(\(i.e.)24 b(whose)18 b(options)e(al)o(w)o(ays)j(tak)o(e)f(a)g(v)n(alue\))f(are)g (additionally)208 4889 y(listed)27 b(here.)46 b(The)27 b(only)f(ef)n(fect)h(of)g(this)h(is)g(that)f FJ(optparse)g FN(assigns)g(the)h(def)o(ault)e(type,)j FJ(string)p FN(,)f(to)f (options)g(with)g(no)208 4988 y(e)o(xplicit)19 b(type)h(whose)g(action) f(is)j(listed)e(in)h FJ(ALWAYS_TYPED_ACTIONS)p FN(.)0 5202 y(In)27 b(order)e(to)i(actually)g(implement)e(your)h(ne)n(w)h (action,)h(you)e(must)h(o)o(v)o(erride)d(Option')-5 b(s)27 b FJ(take_action\(\))e FN(method)g(and)i(add)f(a)0 5301 y(case)21 b(that)f(recognizes)f(your)g(action.)p 0 5549 3901 4 v 0 5649 a FI(446)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 447 459 TeXDict begin 447 458 bop 0 83 a FN(F)o(or)28 b(e)o(xample,)g(let')-5 b(s)29 b(add)f(an)g FJ(extend)f FN(action.)48 b(This)29 b(is)g(similar)f(to)g(the)g(standard)f FJ(append)h FN(action,)h(b)n(ut) f(instead)g(of)g(taking)f(a)0 183 y(single)20 b(v)n(alue)f(from)g(the)h (command-line)d(and)j(appending)d(it)k(to)f(an)g(e)o(xisting)f(list,)i FJ(extend)e FN(will)i(tak)o(e)f(multiple)g(v)n(alues)f(in)h(a)h(single) 0 282 y(comma-delimited)27 b(string,)k(and)e(e)o(xtend)g(an)g(e)o (xisting)g(list)i(with)e(them.)53 b(That)29 b(is,)k(if)d FL(--names)f FN(is)i(an)e FJ(extend)g FN(option)g(of)g(type)0 382 y FJ(string)p FN(,)19 b(the)i(command)d(line)236 529 y FA(--names=foo,bar)43 b(--names)g(blah)h(--names)g(ding,dong)0 815 y FN(w)o(ould)19 b(result)i(in)f(a)h(list)236 962 y FA(["foo",)44 b("bar",)g("blah",)f("ding",)h("dong"])0 1249 y FN(Again)19 b(we)i(de\002ne)e(a)i(subclass)g(of)e(Option:)236 1396 y FA(class)44 b(MyOption)g(\(Option\):)416 1578 y(ACTIONS)f(=)i(Option.ACTIONS)d(+)j(\("extend",\))416 1670 y(STORE_ACTIONS)d(=)j(Option.STORE_ACTIONS)c(+)k(\("extend",\))416 1761 y(TYPED_ACTIONS)d(=)j(Option.TYPED_ACTIONS)c(+)k(\("extend",\))416 1852 y(ALWAYS_TYPED_ACTIONS)c(=)k(Option.ALWAYS_TYPED_ACTIONS)40 b(+)45 b(\("extend",\))416 2035 y(def)f(take_action\(self,)e(action,)i (dest,)f(opt,)i(value,)e(values,)h(parser\):)595 2126 y(if)g(action)g(==)h("extend":)774 2217 y(lvalue)f(=)h (value.split\(","\))774 2309 y(values.ensure_value\(dest,)c ([]\).extend\(lvalue\))595 2400 y(else:)774 2491 y (Option.take_action\()954 2583 y(self,)j(action,)f(dest,)h(opt,)g (value,)g(values,)g(parser\))0 2869 y FN(Features)20 b(of)g(note:)125 3083 y FM(\017)41 b FJ(extend)35 b FN(both)g(e)o (xpects)g(a)h(v)n(alue)f(on)h(the)g(command-line)d(and)i(stores)h(that) g(v)n(alue)f(some)n(where,)j(so)e(it)h(goes)e(in)h(both)208 3182 y FJ(STORE_ACTIONS)18 b FN(and)i FJ(TYPED_ACTIONS)125 3348 y FM(\017)41 b FN(to)22 b(ensure)f(that)g FJ(optparse)g FN(assigns)i(the)e(def)o(ault)g(type)h(of)f FJ(string)h FN(to)f FJ(extend)h FN(actions,)f(we)i(put)e(the)h FJ(extend)f FN(action)208 3448 y(in)f FJ(ALWAYS_TYPED_ACTIONS)d FN(as)k(well)125 3614 y FM(\017)41 b FJ(MyOption.take_action\(\))58 b FN(implements)j(just)i(this)g(one)f(ne)n(w)g(action,)71 b(and)62 b(passes)h(control)e(back)g(to)208 3714 y FJ (Option.take_action\(\))17 b FN(for)i(the)h(standard)f FJ(optparse)h FN(actions)125 3880 y FM(\017)41 b FJ(values)17 b FN(is)j(an)e(instance)g(of)h(the)f(optparse)p 1485 3880 25 4 v 28 w(parser)-5 b(.V)c(alues)18 b(class,)h(which)f(pro)o (vides)f(the)h(v)o(ery)g(useful)g FJ(ensure_value\(\))208 3979 y FN(method.)23 b FJ(ensure_value\(\))18 b FN(is)j(essentially)g FJ(getattr\(\))e FN(with)h(a)h(safety)f(v)n(alv)o(e;)f(it)i(is)g (called)f(as)444 4203 y FA(values.ensure_value\(attr,)40 b(value\))208 4476 y FN(If)22 b(the)i FJ(attr)e FN(attrib)n(ute)h(of)g FJ(values)f FN(doesn')o(t)g(e)o(xist)h(or)g(is)h(None,)f(then)f(ensure) p 2580 4476 V 29 w(v)n(alue\(\))f(\002rst)j(sets)g(it)g(to)f FJ(value)p FN(,)h(and)e(then)208 4575 y(returns)17 b(')l(v)n(alue.)23 b(This)c(is)h(v)o(ery)d(handy)g(for)h(actions)g(lik)o(e)h FJ(extend)p FN(,)f FJ(append)p FN(,)g(and)g FJ(count)p FN(,)g(all)h(of)g(which)f(accumulate)f(data)208 4675 y(in)f(a)h(v)n(ariable)f(and)g(e)o(xpect)g(that)h(v)n(ariable)e(to)i (be)g(of)f(a)h(certain)f(type)g(\(a)h(list)h(for)e(the)g(\002rst)i(tw)o (o,)f(an)g(inte)o(ger)e(for)h(the)h(latter\).)24 b(Using)208 4775 y FJ(ensure_value\(\))c FN(means)i(that)h(scripts)g(using)f(your)f (action)h(don')o(t)f(ha)n(v)o(e)h(to)h(w)o(orry)e(about)h(setting)g(a)h (def)o(ault)f(v)n(alue)g(for)208 4874 y(the)i(option)f(destinations)g (in)i(question;)g(the)o(y)f(can)g(just)h(lea)n(v)o(e)f(the)g(def)o (ault)g(as)h(None)e(and)h FJ(ensure_value\(\))e FN(will)k(tak)o(e)208 4974 y(care)20 b(of)f(getting)h(it)h(right)e(when)h(it')-5 b(s)21 b(needed.)p 0 5549 3901 4 v 0 5649 a FI(14.3.)52 b FJ(optparse)22 b FI(\227)h(More)g(po)o(w)o(erful)h(command)f(line)i (option)f(parser)1426 b(447)p eop end %%Page: 448 460 TeXDict begin 448 459 bop 0 87 a FE(14.4)121 b Fx(getopt)32 b FE(\227)h(P)-5 b(arser)33 b(f)l(or)h(command)g(line)g(options)0 320 y FN(This)24 b(module)e(helps)h(scripts)h(to)f(parse)h(the)f (command)f(line)h(ar)o(guments)e(in)j FJ(sys.argv)p FN(.)34 b(It)24 b(supports)e(the)i(same)f(con)m(v)o(entions)e(as)0 420 y(the)g(U)t FH(N)t(I)t(X)i FJ(getopt\(\))18 b FN(function)g (\(including)f(the)i(special)h(meanings)e(of)h(ar)o(guments)e(of)i(the) h(form)e(`)p FJ(-)p FN(')h(and)g(`)p FJ(--)p FN('\).)k(Long)c(options)0 519 y(similar)e(to)h(those)f(supported)e(by)i(GNU)h(softw)o(are)f(may)f (be)i(used)f(as)h(well)f(via)h(an)f(optional)f(third)g(ar)o(gument.)22 b(This)17 b(module)f(pro)o(vides)0 619 y(a)21 b(single)f(function)e (and)i(an)g(e)o(xception:)0 766 y FD(getopt)p FJ(\()p FK(ar)m(gs,)f(options)p FC([)p FK(,)g(long)p 1015 766 25 4 v 28 w(options)12 b FC(])p FJ(\))208 866 y FN(P)o(arses)28 b(command)f(line)h(options)g(and)g(parameter)f(list.)50 b FK(ar)m(gs)29 b FN(is)g(the)g(ar)o(gument)d(list)j(to)g(be)f(parsed,) h(without)f(the)h(leading)208 965 y(reference)d(to)j(the)g(running)d (program.)48 b(T)-7 b(ypically)i(,)29 b(this)g(means)f(`)p FJ(sys.argv[1:])p FN('.)48 b FK(options)27 b FN(is)j(the)e(string)h(of) f(option)208 1065 y(letters)d(that)g(the)g(script)f(w)o(ants)i(to)f (recognize,)f(with)h(options)f(that)h(require)e(an)i(ar)o(gument)d (follo)n(wed)i(by)g(a)h(colon)f(\(`)p FJ(:)p FN(';)j(i.e.,)208 1164 y(the)20 b(same)g(format)f(that)k(U)t FH(N)t(I)t(X)g FJ(getopt\(\))c FN(uses\).)208 1297 y FL(Note:)36 b FN(Unlik)o(e)26 b(GNU)g FJ(getopt\(\))p FN(,)h(after)f(a)g(non-option)d(ar)o(gument,)i (all)i(further)e(ar)o(guments)f(are)i(considered)e(also)j(non-)208 1397 y(options.)d(This)c(is)h(similar)f(to)h(the)f(w)o(ay)g(non-GNU)h (U)t FH(N)t(I)t(X)i FN(systems)e(w)o(ork.)208 1530 y FK(long)p 362 1530 V 28 w(options)p FN(,)c(if)g(speci\002ed,)h(must)f (be)g(a)h(list)g(of)f(strings)g(with)h(the)f(names)g(of)g(the)g(long)f (options)h(which)f(should)h(be)g(supported.)208 1629 y(The)22 b(leading)f FJ('--')i FN(characters)e(should)h(not)g(be)h (included)e(in)h(the)h(option)e(name.)32 b(Long)21 b(options)h(which)g (require)f(an)h(ar)o(gu-)208 1729 y(ment)c(should)g(be)h(follo)n(wed)e (by)h(an)h(equal)f(sign)h(\(`)p FJ(=)p FN('\).)24 b(T)-7 b(o)19 b(accept)f(only)g(long)g(options,)g FK(options)g FN(should)g(be)g(an)h(empty)f(string.)208 1829 y(Long)k(options)g(on)h (the)g(command)e(line)j(can)f(be)g(recognized)e(so)i(long)g(as)h(the)o (y)e(pro)o(vide)f(a)j(pre\002x)f(of)g(the)g(option)f(name)g(that)208 1928 y(matches)e(e)o(xactly)h(one)f(of)h(the)g(accepted)f(options.)27 b(F)o(or)21 b(e)o(xample,)f(if)h FK(long)p 2408 1928 V 28 w(options)g FN(is)h FJ(['foo',)48 b('frob'])p FN(,)21 b(the)g(option)208 2028 y FL(--f)n(o)e FN(will)i(match)e(as)i FL(--f)n(oo)p FN(,)e(b)n(ut)h FL(--f)f FN(will)i(not)f(match)g (uniquely)-5 b(,)18 b(so)i FJ(GetoptError)f FN(will)i(be)f(raised.)208 2161 y(The)i(return)g(v)n(alue)h(consists)h(of)f(tw)o(o)g(elements:)31 b(the)23 b(\002rst)h(is)g(a)g(list)g(of)f FJ(\()p FK(option)p FJ(,)48 b FK(value)p FJ(\))22 b FN(pairs;)j(the)e(second)f(is)i(the)g (list)g(of)208 2260 y(program)18 b(ar)o(guments)h(left)i(after)f(the)h (option)e(list)j(w)o(as)g(stripped)e(\(this)g(is)i(a)f(trailing)f (slice)i(of)e FK(ar)m(gs)p FN(\).)27 b(Each)20 b(option-and-v)n(alue) 208 2360 y(pair)25 b(returned)f(has)j(the)f(option)e(as)j(its)g (\002rst)g(element,)f(pre\002x)o(ed)f(with)h(a)g(hyphen)e(for)h(short)h (options)f(\(e.g.,)h FJ('-x')p FN(\))g(or)f(tw)o(o)208 2460 y(hyphens)f(for)h(long)h(options)f(\(e.g.,)i FJ('--long-option')p FN(\),)e(and)h(the)g(option)g(ar)o(gument)e(as)j(its)g(second)e (element,)j(or)e(an)208 2559 y(empty)21 b(string)i(if)g(the)f(option)g (has)g(no)h(ar)o(gument.)30 b(The)22 b(options)g(occur)f(in)i(the)g (list)g(in)g(the)g(same)g(order)e(in)i(which)f(the)o(y)g(were)208 2659 y(found,)c(thus)i(allo)n(wing)f(multiple)h(occurrences.)j(Long)c (and)g(short)h(options)f(may)h(be)g(mix)o(ed.)0 2806 y FD(gnu_getopt)p FJ(\()p FK(ar)m(gs,)e(options)p FC([)p FK(,)h(long)p 1214 2806 V 28 w(options)12 b FC(])p FJ(\))208 2905 y FN(This)27 b(function)f(w)o(orks)g(lik)o(e)i FJ(getopt\(\))p FN(,)g(e)o(xcept)e(that)h(GNU)h(style)g(scanning)e(mode)g(is)i(used)f (by)g(def)o(ault.)45 b(This)28 b(means)208 3005 y(that)19 b(option)f(and)h(non-option)d(ar)o(guments)h(may)i(be)g(intermix)o(ed.) j(The)d FJ(getopt\(\))g FN(function)e(stops)j(processing)e(options)g (as)208 3105 y(soon)h(as)i(a)g(non-option)c(ar)o(gument)h(is)j (encountered.)208 3237 y(If)f(the)h(\002rst)g(character)f(of)g(the)h (option)e(string)i(is)g(`+',)g(or)f(if)h(the)g(en)m(vironment)c(v)n (ariable)j(POSIXL)-8 b(Y)p 3118 3237 V 29 w(CORRECT)22 b(is)g(set,)f(then)208 3337 y(option)e(processing)f(stops)j(as)g(soon)e (as)i(a)g(non-option)c(ar)o(gument)h(is)j(encountered.)208 3470 y(Ne)n(w)f(in)g(v)o(ersion)f(2.3.)0 3617 y FL(exception)g FD(GetoptError)208 3716 y FN(This)d(is)g(raised)g(when)f(an)h (unrecognized)c(option)j(is)i(found)d(in)i(the)f(ar)o(gument)f(list)j (or)e(when)g(an)h(option)f(requiring)e(an)j(ar)o(gument)208 3816 y(is)23 b(gi)n(v)o(en)f(none.)32 b(The)23 b(ar)o(gument)e(to)i (the)g(e)o(xception)e(is)j(a)f(string)g(indicating)e(the)i(cause)g(of)g (the)g(error)-5 b(.)32 b(F)o(or)23 b(long)f(options,)h(an)208 3916 y(ar)o(gument)14 b(gi)n(v)o(en)i(to)h(an)g(option)f(which)g(does)h (not)g(require)e(one)i(will)g(also)h(cause)f(this)g(e)o(xception)e(to)i (be)g(raised.)24 b(The)17 b(attrib)n(utes)208 4015 y FJ(msg)25 b FN(and)g FJ(opt)g FN(gi)n(v)o(e)g(the)h(error)e(message)h (and)g(related)g(option;)i(if)f(there)f(is)h(no)f(speci\002c)h(option)e (to)i(which)f(the)g(e)o(xception)208 4115 y(relates,)20 b FJ(opt)g FN(is)h(an)f(empty)g(string.)208 4248 y(Changed)e(in)j(v)o (ersion)e(1.6:)g(Introduced)f FJ(GetoptError)g FN(as)j(a)g(synon)o(ym)d (for)h FJ(error)p FN(.)0 4395 y FL(exception)g FD(error)208 4494 y FN(Alias)i(for)e FJ(GetoptError)p FN(;)g(for)g(backw)o(ard)g (compatibility)-5 b(.)0 4641 y(An)20 b(e)o(xample)f(using)h(only)h(U)t FH(N)t(I)t(X)i FN(style)e(options:)p 0 5549 3901 4 v 0 5649 a FI(448)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 449 461 TeXDict begin 449 460 bop 236 174 a FA(>>>)45 b(import)e(getopt)236 266 y(>>>)i(args)f(=)g('-a)h(-b)f(-cfoo)g(-d)h(bar)f(a1)h (a2'.split\(\))236 357 y(>>>)g(args)236 448 y(['-a',)f('-b',)g ('-cfoo',)g('-d',)g('bar',)f('a1',)h('a2'])236 540 y(>>>)h(optlist,)e (args)h(=)h(getopt.getopt\(args,)c('abc:d:'\))236 631 y(>>>)k(optlist)236 722 y([\('-a',)f(''\),)g(\('-b',)g(''\),)g(\('-c',) g('foo'\),)f(\('-d',)h('bar'\)])236 814 y(>>>)h(args)236 905 y(['a1',)f('a2'])0 1191 y FN(Using)20 b(long)f(option)g(names)h(is) h(equally)f(easy:)236 1430 y FA(>>>)45 b(s)f(=)h('--condition=foo)d (--testing)h(--output-file)g(abc.def)h(-x)g(a1)h(a2')236 1521 y(>>>)g(args)f(=)g(s.split\(\))236 1612 y(>>>)h(args)236 1704 y(['--condition=foo',)d('--testing',)h('--output-file',)f ('abc.def',)h('-x',)h('a1',)g('a2'])236 1795 y(>>>)h(optlist,)e(args)h (=)h(getopt.getopt\(args,)c('x',)k([)236 1886 y(...)224 b('condition=',)43 b('output-file=',)f('testing']\))236 1978 y(>>>)j(optlist)236 2069 y([\('--condition',)d('foo'\),)i (\('--testing',)f(''\),)h(\('--output-file',)e('abc.def'\),)h(\('-x',) 281 2160 y(''\)])236 2252 y(>>>)i(args)236 2343 y(['a1',)f('a2'])0 2629 y FN(In)20 b(a)h(script,)f(typical)f(usage)h(is)h(something)e(lik) o(e)h(this:)236 2868 y FA(import)44 b(getopt,)g(sys)236 3050 y(def)h(main\(\):)416 3142 y(try:)595 3233 y(opts,)f(args)g(=)h (getopt.getopt\(sys.argv[1:],)40 b("ho:v",)k(["help",)f("output="]\)) 416 3324 y(except)g(getopt.GetoptError,)f(err:)595 3416 y(#)j(print)f(help)g(information)f(and)h(exit:)595 3507 y(print)g(str\(err\))f(#)i(will)f(print)g(something)f(like)i("option)e (-a)i(not)f(recognized")595 3598 y(usage\(\))595 3690 y(sys.exit\(2\))416 3781 y(output)f(=)i(None)416 3872 y(verbose)e(=)i(False)416 3963 y(for)f(o,)g(a)h(in)g(opts:)595 4055 y(if)f(o)h(==)g("-v":)774 4146 y(verbose)f(=)h(True)595 4237 y(elif)f(o)h(in)f(\("-h",)g("--help"\):)774 4329 y(usage\(\))774 4420 y(sys.exit\(\))595 4511 y(elif)g(o)h(in)f(\("-o",) g("--output"\):)774 4603 y(output)g(=)h(a)595 4694 y(else:)774 4785 y(assert)f(False,)g("unhandled)f(option")416 4877 y(#)h(...)236 5059 y(if)h(__name__)e(==)i("__main__":)416 5151 y(main\(\))p 0 5549 3901 4 v 0 5649 a FI(14.4.)52 b FJ(getopt)22 b FI(\227)h(P)m(arser)g(f)n(or)f(command)i(line)g (options)1909 b(449)p eop end %%Page: 450 462 TeXDict begin 450 461 bop 0 83 a FL(See)21 b(Also:)0 230 y FN(Module)e FJ(optparse)g FN(\(section)h(14.3\):)208 330 y(More)f(object-oriented)e(command)i(line)h(option)f(parsing.)0 657 y FE(14.5)121 b Fx(logging)32 b FE(\227)g(Logging)k(f)l(acility)d (f)l(or)h(Python)0 890 y FN(Ne)n(w)23 b(in)g(v)o(ersion)e(2.3.)64 b(This)23 b(module)e(de\002nes)i(functions)e(and)h(classes)i(which)e (implement)f(a)i(\003e)o(xible)f(error)g(logging)e(system)j(for)0 989 y(applications.)0 1136 y(Logging)c(is)j(performed)d(by)i(calling)g (methods)f(on)g(instances)i(of)f(the)g FJ(Logger)g FN(class)h (\(hereafter)d(called)i FK(lo)o(g)o(g)o(er)o(s)p FN(\).)28 b(Each)21 b(instance)0 1236 y(has)28 b(a)h(name,)g(and)e(the)o(y)h(are) f(conceptually)f(arranged)g(in)i(a)h(name)e(space)h(hierarchy)e(using)h (dots)h(\(periods\))f(as)h(separators.)48 b(F)o(or)0 1336 y(e)o(xample,)22 b(a)h(logger)f(named)g(\224scan\224)h(is)h(the)f (parent)f(of)h(loggers)f(\224scan.te)o(xt\224,)g(\224scan.html\224)g (and)g(\224scan.pdf\224.)32 b(Logger)21 b(names)i(can)0 1435 y(be)d(an)o(ything)e(you)i(w)o(ant,)g(and)f(indicate)h(the)g(area) g(of)g(an)g(application)f(in)h(which)g(a)g(logged)f(message)h (originates.)0 1582 y(Logged)c(messages)i(also)g(ha)n(v)o(e)g(le)n(v)o (els)g(of)f(importance)f(associated)i(with)g(them.)24 b(The)17 b(def)o(ault)h(le)n(v)o(els)f(pro)o(vided)f(are)i FJ(DEBUG)p FN(,)f FJ(INFO)p FN(,)0 1682 y FJ(WARNING)p FN(,)g FJ(ERROR)h FN(and)g FJ(CRITICAL)p FN(.)f(As)i(a)f(con)m(v)o (enience,)e(you)h(indicate)g(the)i(importance)d(of)i(a)g(logged)f (message)h(by)g(calling)g(an)0 1781 y(appropriate)d(method)i(of)g FJ(Logger)p FN(.)23 b(The)18 b(methods)e(are)i FJ(debug\(\))p FN(,)f FJ(info\(\))p FN(,)g FJ(warning\(\))p FN(,)g FJ(error\(\))g FN(and)g FJ(critical\(\))p FN(,)0 1881 y(which)j(mirror)f(the)h(def)o (ault)g(le)n(v)o(els.)25 b(Y)-9 b(ou)20 b(are)g(not)g(constrained)e(to) j(use)f(these)h(le)n(v)o(els:)k(you)20 b(can)g(specify)g(your)f(o)n(wn) g(and)h(use)h(a)f(more)0 1981 y(general)f FJ(Logger)h FN(method,)e FJ(log\(\))p FN(,)i(which)g(tak)o(es)g(an)g(e)o(xplicit)g (le)n(v)o(el)g(ar)o(gument.)0 2127 y(The)k(numeric)e(v)n(alues)i(of)f (logging)f(le)n(v)o(els)i(are)g(gi)n(v)o(en)f(in)h(the)g(follo)n(wing)e (table.)36 b(These)23 b(are)h(primarily)f(of)g(interest)h(if)g(you)f(w) o(ant)h(to)0 2227 y(de\002ne)g(your)f(o)n(wn)h(le)n(v)o(els,)i(and)e (need)g(them)g(to)g(ha)n(v)o(e)g(speci\002c)h(v)n(alues)f(relati)n(v)o (e)g(to)h(the)f(prede\002ned)f(le)n(v)o(els.)38 b(If)24 b(you)g(de\002ne)g(a)h(le)n(v)o(el)0 2327 y(with)20 b(the)h(same)f (numeric)f(v)n(alue,)g(it)i(o)o(v)o(erwrites)e(the)h(prede\002ned)e(v)n (alue;)i(the)g(prede\002ned)e(name)i(is)h(lost.)1442 2553 y FL(Le)o(v)o(el)p 1889 2583 4 100 v 306 w(Numeric)g(v)o(alue)p 1392 2586 1116 4 v 1442 2656 a FJ(CRITICAL)p 1889 2686 4 100 v 98 w FN(50)1442 2755 y FJ(ERROR)p 1889 2785 V 248 w FN(40)1442 2855 y FJ(WARNING)p 1889 2885 V 148 w FN(30)1442 2955 y FJ(INFO)p 1889 2985 V 298 w FN(20)1442 3054 y FJ(DEBUG)p 1889 3084 V 248 w FN(10)1442 3154 y FJ(NOTSET)p 1889 3184 V 198 w FN(0)0 3379 y(Le)n(v)o(els)31 b(can)g(also)g(be)g(associated)g(with)g(loggers,)i(being)d(set)i (either)f(by)f(the)i(de)n(v)o(eloper)c(or)j(through)e(loading)h(a)h(sa) n(v)o(ed)g(logging)0 3479 y(con\002guration.)21 b(When)c(a)g(logging)e (method)h(is)h(called)g(on)f(a)i(logger)m(,)d(the)i(logger)e(compares)h (its)i(o)n(wn)e(le)n(v)o(el)h(with)g(the)f(le)n(v)o(el)h(associated)0 3578 y(with)22 b(the)h(method)d(call.)32 b(If)22 b(the)g(logger')-5 b(s)21 b(le)n(v)o(el)h(is)h(higher)e(than)h(the)g(method)f(call')-5 b(s,)23 b(no)f(logging)f(message)h(is)h(actually)f(generated.)0 3678 y(This)e(is)h(the)g(basic)f(mechanism)f(controlling)f(the)i(v)o (erbosity)f(of)h(logging)e(output.)0 3825 y(Logging)e(messages)j(are)f (encoded)f(as)i(instances)f(of)g(the)h FJ(LogRecord)e FN(class.)25 b(When)18 b(a)h(logger)e(decides)h(to)h(actually)e(log)h (an)h(e)n(v)o(ent,)0 3924 y(a)i FJ(LogRecord)e FN(instance)h(is)h (created)e(from)g(the)h(logging)f(message.)0 4071 y(Logging)25 b(messages)h(are)h(subjected)e(to)i(a)g(dispatch)f(mechanism)f(through) g(the)h(use)h(of)f FK(handler)o(s)p FN(,)i(which)e(are)g(instances)h (of)f(sub-)0 4171 y(classes)36 b(of)f(the)g FJ(Handler)f FN(class.)71 b(Handlers)34 b(are)h(responsible)f(for)h(ensuring)e(that) i(a)h(logged)d(message)i(\(in)g(the)g(form)f(of)h(a)0 4271 y FJ(LogRecord)p FN(\))27 b(ends)h(up)g(in)h(a)g(particular)e (location)h(\(or)g(set)h(of)f(locations\))g(which)g(is)h(useful)f(for)g (the)h(tar)o(get)e(audience)h(for)f(that)0 4370 y(message)20 b(\(such)f(as)h(end)f(users,)h(support)e(desk)i(staf)n(f,)f(system)h (administrators,)e(de)n(v)o(elopers\).)23 b(Handlers)18 b(are)i(passed)g FJ(LogRecord)0 4470 y FN(instances)g(intended)f(for)h (particular)f(destinations.)25 b(Each)20 b(logger)f(can)h(ha)n(v)o(e)g (zero,)f(one)h(or)g(more)g(handlers)f(associated)h(with)h(it)g(\(via)0 4569 y(the)g FJ(addHandler\(\))d FN(method)i(of)g FJ(Logger)p FN(\).)25 b(In)20 b(addition)f(to)i(an)o(y)f(handlers)f(directly)h (associated)g(with)h(a)g(logger)m(,)d FK(all)j(handler)o(s)0 4669 y(associated)e(with)i(all)f(ancestor)o(s)h(of)f(the)g(lo)o(g)o(g)o (er)g FN(are)g(called)g(to)h(dispatch)e(the)h(message.)0 4816 y(Just)25 b(as)g(for)f(loggers,)g(handlers)f(can)h(ha)n(v)o(e)f (le)n(v)o(els)h(associated)g(with)h(them.)37 b(A)24 b(handler')-5 b(s)23 b(le)n(v)o(el)h(acts)h(as)g(a)g(\002lter)f(in)h(the)f(same)h(w)o (ay)0 4916 y(as)h(a)f(logger')-5 b(s)24 b(le)n(v)o(el)g(does.)39 b(If)25 b(a)g(handler)f(decides)g(to)h(actually)g(dispatch)f(an)h(e)n (v)o(ent,)g(the)f FJ(emit\(\))h FN(method)e(is)j(used)f(to)g(send)g (the)0 5015 y(message)20 b(to)g(its)i(destination.)h(Most)e(user)n (-de\002ned)d(subclasses)j(of)f FJ(Handler)f FN(will)i(need)f(to)g(o)o (v)o(erride)e(this)j FJ(emit\(\))p FN(.)0 5162 y(In)f(addition)f(to)h (the)g(base)h FJ(Handler)e FN(class,)i(man)o(y)e(useful)h(subclasses)g (are)g(pro)o(vided:)104 5392 y(1.)41 b FJ(StreamHandler)18 b FN(instances)i(send)g(error)f(messages)h(to)h(streams)f(\(\002le-lik) o(e)g(objects\).)p 0 5549 3901 4 v 0 5649 a FI(450)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 451 463 TeXDict begin 451 462 bop 104 83 a FN(2.)41 b FJ(FileHandler)18 b FN(instances)i(send)g(error)f(messages)i(to)f(disk)g(\002les.)104 247 y(3.)41 b FJ(BaseRotatingHandler)19 b FN(is)k(the)f(base)g(class)h (for)e(handlers)g(that)h(rotate)g(log)f(\002les)i(at)g(a)f(certain)g (point.)29 b(It)22 b(is)h(not)f(meant)208 346 y(to)e(be)g(instantiated) g(directly)-5 b(.)23 b(Instead,)d(use)g FJ(RotatingFileHandler)d FN(or)j FJ(TimedRotatingFileHandler)p FN(.)104 510 y(4.)41 b FJ(RotatingFileHandler)14 b FN(instances)j(send)g(error)f(messages)h (to)g(disk)g(\002les,)i(with)e(support)f(for)h(maximum)e(log)i(\002le)h (sizes)208 609 y(and)h(log)h(\002le)h(rotation.)104 773 y(5.)41 b FJ(TimedRotatingFileHandler)23 b FN(instances)28 b(send)f(error)g(messages)g(to)h(disk)g(\002les)g(rotating)f(the)g(log) h(\002le)g(at)g(certain)208 872 y(timed)19 b(interv)n(als.)104 1036 y(6.)41 b FJ(SocketHandler)18 b FN(instances)i(send)g(error)f (messages)h(to)h(TCP/IP)g(sock)o(ets.)104 1200 y(7.)41 b FJ(DatagramHandler)18 b FN(instances)i(send)g(error)f(messages)h(to)g (UDP)h(sock)o(ets.)104 1363 y(8.)41 b FJ(SMTPHandler)18 b FN(instances)i(send)g(error)f(messages)i(to)f(a)h(designated)d(email) j(address.)104 1527 y(9.)41 b FJ(SysLogHandler)18 b FN(instances)i (send)g(error)f(messages)h(to)h(a)h(U)t FH(N)t(I)t(X)h FN(syslog)d(daemon,)f(possibly)g(on)h(a)h(remote)e(machine.)62 1690 y(10.)41 b FJ(NTEventLogHandler)17 b FN(instances)j(send)g(error)f (messages)i(to)f(a)h(W)m(indo)n(ws)e(NT/2000/XP)g(e)n(v)o(ent)g(log.)62 1854 y(11.)41 b FJ(MemoryHandler)25 b FN(instances)h(send)h(error)f (messages)g(to)h(a)h(b)n(uf)n(fer)d(in)i(memory)-5 b(,)26 b(which)h(is)g(\003ushed)g(whene)n(v)o(er)d(speci\002c)208 1953 y(criteria)19 b(are)i(met.)62 2117 y(12.)41 b FJ(HTTPHandler)18 b FN(instances)i(send)g(error)f(messages)i(to)f(an)g(HTTP)g(serv)o(er)g (using)f(either)h(`)p FJ(GET)p FN(')g(or)g(`)p FJ(POST)p FN(')f(semantics.)0 2340 y(The)29 b FJ(StreamHandler)f FN(and)g FJ(FileHandler)g FN(classes)j(are)e(de\002ned)g(in)g(the)h (core)e(logging)g(package.)51 b(The)29 b(other)g(handlers)0 2440 y(are)24 b(de\002ned)f(in)h(a)h(sub-)e(module,)g FJ(logging.handlers)p FN(.)34 b(\(There)23 b(is)i(also)g(another)d (sub-module,)h FJ(logging.config)p FN(,)f(for)0 2540 y(con\002guration)c(functionality)-5 b(.\))0 2687 y(Logged)17 b(messages)h(are)h(formatted)e(for)g(presentation)g(through)g (instances)h(of)g(the)h FJ(Formatter)e FN(class.)25 b(The)o(y)18 b(are)g(initialized)g(with)0 2786 y(a)j(format)e(string)h(suitable)g (for)f(use)i(with)f(the)g(\045)h(operator)d(and)i(a)h(dictionary)-5 b(.)0 2933 y(F)o(or)23 b(formatting)f(multiple)h(messages)h(in)f(a)h (batch,)g(instances)f(of)h FJ(BufferingFormatter)c FN(can)k(be)f(used.) 35 b(In)24 b(addition)e(to)i(the)0 3033 y(format)19 b(string)h(\(which) f(is)i(applied)f(to)g(each)g(message)g(in)g(the)g(batch\),)f(there)h (is)h(pro)o(vision)d(for)i(header)f(and)h(trailer)g(format)f(strings.)0 3180 y(When)24 b(\002ltering)g(based)g(on)g(logger)f(le)n(v)o(el)h (and/or)f(handler)g(le)n(v)o(el)h(is)h(not)f(enough,)f(instances)h(of)h FJ(Filter)e FN(can)h(be)h(added)e(to)h(both)0 3279 y FJ(Logger)k FN(and)g FJ(Handler)g FN(instances)h(\(through)d(their)i FJ(addFilter\(\))f FN(method\).)49 b(Before)28 b(deciding)f(to)i (process)f(a)h(message)0 3379 y(further)m(,)17 b(both)i(loggers)f(and)h (handlers)f(consult)g(all)i(their)f(\002lters)h(for)f(permission.)k(If) c(an)o(y)g(\002lter)g(returns)g(a)g(f)o(alse)h(v)n(alue,)e(the)i (message)0 3478 y(is)h(not)f(processed)f(further)-5 b(.)0 3625 y(The)21 b(basic)h FJ(Filter)e FN(functionality)g(allo)n(ws)h (\002ltering)g(by)g(speci\002c)h(logger)e(name.)28 b(If)21 b(this)h(feature)e(is)j(used,)e(messages)g(sent)h(to)g(the)0 3725 y(named)d(logger)g(and)h(its)h(children)e(are)h(allo)n(wed)f (through)f(the)j(\002lter)m(,)f(and)f(all)i(others)f(dropped.)0 3872 y(In)g(addition)f(to)h(the)g(classes)i(described)d(abo)o(v)o(e,)f (there)i(are)g(a)g(number)f(of)h(module-)e(le)n(v)o(el)i(functions.)0 4019 y FD(getLogger)p FJ(\()p FC([)p FK(name)12 b FC(])p FJ(\))208 4118 y FN(Return)22 b(a)i(logger)e(with)h(the)g(speci\002ed)g (name)g(or)m(,)g(if)g(no)g(name)g(is)h(speci\002ed,)f(return)f(a)i (logger)e(which)g(is)i(the)f(root)g(logger)f(of)208 4218 y(the)d(hierarchy)-5 b(.)22 b(If)e(speci\002ed,)f(the)h(name)f(is)i (typically)e(a)h(dot-separated)e(hierarchical)g(name)h(lik)o(e)i FK(\224a\224)p FN(,)f FK(\224a.b\224)f FN(or)h FK(\224a.b)m(.c.d\224)p FN(.)208 4317 y(Choice)g(of)f(these)i(names)f(is)h(entirely)e(up)h(to)g (the)h(de)n(v)o(eloper)c(who)j(is)h(using)f(logging.)208 4449 y(All)k(calls)h(to)f(this)g(function)e(with)i(a)g(gi)n(v)o(en)f (name)g(return)g(the)h(same)g(logger)e(instance.)36 b(This)24 b(means)f(that)h(logger)f(instances)208 4549 y(ne)n(v)o(er)18 b(need)i(to)g(be)g(passed)g(between)g(dif)n(ferent)e(parts)i(of)g(an)h (application.)0 4696 y FD(getLoggerClass)p FJ(\(\))208 4795 y FN(Return)d(either)g(the)h(standard)e FJ(Logger)i FN(class,)g(or)g(the)f(last)i(class)g(passed)e(to)h FJ (setLoggerClass\(\))p FN(.)j(This)d(function)e(may)208 4895 y(be)j(called)h(from)e(within)i(a)g(ne)n(w)f(class)i (de\002nition,)d(to)i(ensure)f(that)g(installing)h(a)g(customised)f FJ(Logger)g FN(class)h(will)h(not)e(undo)208 4994 y(customisations)f (already)g(applied)g(by)h(other)f(code.)25 b(F)o(or)19 b(e)o(xample:)489 5217 y FA(class)44 b (MyLogger\(logging.getLoggerClass\(\)\):)668 5309 y(#)h(...)f(override) f(behaviour)h(here)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python) 2103 b(451)p eop end %%Page: 452 464 TeXDict begin 452 463 bop 0 83 a FD(debug)p FJ(\()p FK(msg)p FC([)p FK(,)19 b(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 183 y FN(Logs)23 b(a)i(message)f(with)g(le)n(v)o (el)g FJ(DEBUG)g FN(on)f(the)h(root)g(logger)-5 b(.)36 b(The)24 b FK(msg)g FN(is)h(the)f(message)g(format)f(string,)i(and)e (the)h FK(ar)m(gs)h FN(are)208 282 y(the)e(ar)o(guments)f(which)h(are)g (mer)o(ged)f(into)i FK(msg)g FN(using)f(the)g(string)h(formatting)d (operator)-5 b(.)34 b(\(Note)23 b(that)h(this)g(means)g(that)f(you)208 382 y(can)d(use)g(k)o(e)o(yw)o(ords)f(in)h(the)g(format)f(string,)h (together)f(with)h(a)h(single)f(dictionary)e(ar)o(gument.\))208 515 y(There)e(are)i(tw)o(o)g(k)o(e)o(yw)o(ord)e(ar)o(guments)f(in)j FK(kwar)m(gs)g FN(which)f(are)h(inspected:)23 b FK(e)n(xc)p 2503 515 25 4 v 30 w(info)17 b FN(which,)g(if)h(it)h(does)e(not)g(e)n (v)n(aluate)g(as)h(f)o(alse,)208 614 y(causes)j(e)o(xception)f (information)g(to)h(be)h(added)f(to)g(the)h(logging)e(message.)29 b(If)22 b(an)f(e)o(xception)f(tuple)i(\(in)f(the)h(format)e(returned) 208 714 y(by)k FJ(sys.exc_info\(\))p FN(\))e(is)j(pro)o(vided,)e(it)i (is)g(used;)h(otherwise,)f FJ(sys.exc_info\(\))d FN(is)k(called)e(to)h (get)f(the)g(e)o(xception)208 814 y(information.)208 946 y(The)c(other)g(optional)g(k)o(e)o(yw)o(ord)f(ar)o(gument)f(is)k FK(e)n(xtr)o(a)f FN(which)f(can)h(be)g(used)g(to)g(pass)g(a)g (dictionary)e(which)i(is)g(used)g(to)g(populate)208 1046 y(the)p 334 1046 V 364 1046 V 79 w(dict)p 519 1046 V 548 1046 V 79 w(of)e(the)g(LogRecord)f(created)h(for)f(the)i(logging)d (e)n(v)o(ent)i(with)g(user)n(-de\002ned)f(attrib)n(utes.)25 b(These)19 b(custom)g(attrib)n(utes)208 1146 y(can)h(then)f(be)h(used)g (as)h(you)f(lik)o(e.)25 b(F)o(or)20 b(e)o(xample,)e(the)o(y)i(could)f (be)h(incorporated)d(into)j(logged)f(messages.)25 b(F)o(or)20 b(e)o(xample:)489 1370 y FA(FORMAT)43 b(=)i("\045\(asctime\)-15s)d (\045\(clientip\)s)h(\045\(user\)-8s)g(\045\(message\)s")489 1461 y(logging.basicConfig\(format=FORMAT\))489 1553 y(d)h(=)h({'clientip':)e('192.168.0.1',)f('user':)i('fbloggs'})489 1644 y(logging.warning\("Protocol)c(problem:)k(\045s",)g("connection)f (reset",)h(extra=d\))208 1833 y FN(w)o(ould)19 b(print)h(something)e (lik)o(e)444 2057 y FA(2006-02-08)43 b(22:20:02,165)g(192.168.0.1)g (fbloggs)88 b(Protocol)44 b(problem:)f(connection)g(reset)208 2247 y FN(The)22 b(k)o(e)o(ys)g(in)g(the)h(dictionary)d(passed)j(in)f FK(e)n(xtr)o(a)h FN(should)e(not)h(clash)h(with)g(the)f(k)o(e)o(ys)g (used)g(by)g(the)h(logging)d(system.)32 b(\(See)23 b(the)208 2347 y FJ(Formatter)c FN(documentation)e(for)i(more)h(information)e(on) h(which)h(k)o(e)o(ys)g(are)g(used)g(by)g(the)g(logging)e(system.\))208 2479 y(If)h(you)g(choose)f(to)i(use)g(these)f(attrib)n(utes)h(in)f (logged)f(messages,)i(you)f(need)f(to)i(e)o(x)o(ercise)f(some)g(care.) 25 b(In)19 b(the)g(abo)o(v)o(e)f(e)o(xample,)208 2579 y(for)25 b(instance,)i(the)f FJ(Formatter)f FN(has)h(been)g(set)h(up)e (with)h(a)h(format)e(string)h(which)f(e)o(xpects)h('clientip')f(and)g ('user')g(in)i(the)208 2679 y(attrib)n(ute)g(dictionary)e(of)j(the)f (LogRecord.)45 b(If)27 b(these)h(are)f(missing,)i(the)f(message)f(will) i(not)e(be)g(logged)f(because)h(a)h(string)208 2778 y(formatting)18 b(e)o(xception)g(will)j(occur)-5 b(.)24 b(So)d(in)f(this)h(case,)f(you) g(al)o(w)o(ays)g(need)g(to)g(pass)h(the)f FK(e)n(xtr)o(a)g FN(dictionary)f(with)h(these)h(k)o(e)o(ys.)208 2911 y(While)32 b(this)g(might)f(be)g(anno)o(ying,)h(this)g(feature)f(is)i(intended)d (for)h(use)g(in)h(specialized)f(circumstances,)i(such)f(as)g(multi-)208 3011 y(threaded)26 b(serv)o(ers)i(where)g(the)g(same)h(code)f(e)o(x)o (ecutes)f(in)h(man)o(y)g(conte)o(xts,)h(and)f(interesting)f(conditions) g(which)h(arise)h(are)208 3110 y(dependent)16 b(on)i(this)h(conte)o(xt) f(\(such)g(as)h(remote)f(client)g(IP)h(address)g(and)f(authenticated)f (user)h(name,)g(in)h(the)g(abo)o(v)o(e)e(e)o(xample\).)208 3210 y(In)i(such)h(circumstances,)f(it)i(is)g(lik)o(ely)f(that)h (specialized)e FJ(Formatter)p FN(s)h(w)o(ould)f(be)h(used)g(with)g (particular)f FJ(Handler)p FN(s.)208 3343 y(Changed)f(in)j(v)o(ersion)e (2.5:)g FK(e)n(xtr)o(a)i FN(w)o(as)g(added.)0 3490 y FD(info)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)p FC([)p FK(,)h(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 3589 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o(el)g FJ(INFO)g FN(on)g(the)g(root)g (logger)-5 b(.)24 b(The)c(ar)o(guments)e(are)i(interpreted)e(as)j(for)f FJ(debug\(\))p FN(.)0 3736 y FD(warning)p FJ(\()p FK(msg)p FC([)p FK(,)f(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 3836 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v) o(el)g FJ(WARNING)g FN(on)f(the)i(root)e(logger)-5 b(.)24 b(The)c(ar)o(guments)e(are)i(interpreted)f(as)i(for)e FJ(debug\(\))p FN(.)0 3983 y FD(error)p FJ(\()p FK(msg)p FC([)p FK(,)g(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 4082 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v) o(el)g FJ(ERROR)g FN(on)g(the)g(root)g(logger)-5 b(.)24 b(The)19 b(ar)o(guments)g(are)h(interpreted)e(as)j(for)f FJ(debug\(\))p FN(.)0 4229 y FD(critical)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)p FC([)p FK(,)i(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 4329 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v) o(el)g FJ(CRITICAL)f FN(on)h(the)g(root)g(logger)-5 b(.)24 b(The)c(ar)o(guments)e(are)i(interpreted)e(as)j(for)f FJ(debug\(\))p FN(.)0 4476 y FD(exception)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)12 b FC(])p FJ(\))208 4575 y FN(Logs)j(a)i (message)f(with)g(le)n(v)o(el)g FJ(ERROR)g FN(on)g(the)g(root)g(logger) -5 b(.)22 b(The)16 b(ar)o(guments)e(are)j(interpreted)d(as)j(for)e FJ(debug\(\))p FN(.)23 b(Exception)208 4675 y(info)c(is)i(added)e(to)i (the)f(logging)e(message.)25 b(This)20 b(function)f(should)g(only)g(be) h(called)g(from)g(an)g(e)o(xception)e(handler)-5 b(.)0 4822 y FD(log)p FJ(\()p FK(le)o(vel,)19 b(msg)p FC([)p FK(,)h(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 4921 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o(el)g FK(le)o(vel)h FN(on)e(the)i(root)e(logger)-5 b(.)24 b(The)c(other)f(ar) o(guments)f(are)j(interpreted)d(as)j(for)e FJ(debug\(\))p FN(.)0 5068 y FD(disable)p FJ(\()p FK(lvl)p FJ(\))208 5168 y FN(Pro)o(vides)k(an)h(o)o(v)o(erriding)d(le)n(v)o(el)j FK(lvl)h FN(for)f(all)h(loggers)e(which)h(tak)o(es)h(precedence)d(o)o (v)o(er)h(the)h(logger')-5 b(s)24 b(o)n(wn)f(le)n(v)o(el.)37 b(When)25 b(the)208 5268 y(need)16 b(arises)j(to)e(temporarily)f (throttle)h(logging)f(output)g(do)n(wn)h(across)g(the)h(whole)f (application,)f(this)j(function)c(can)j(be)f(useful.)p 0 5549 3901 4 v 0 5649 a FI(452)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 453 465 TeXDict begin 453 464 bop 0 83 a FD(addLevelName)p FJ(\()p FK(lvl,)18 b(le)o(velName)p FJ(\))208 183 y FN(Associates)30 b(le)n(v)o(el)f FK(lvl)h FN(with)g(te)o(xt)g FK(le)o(velName)f FN(in)h(an)f(internal)g(dictionary)-5 b(,)30 b(which)f(is)h(used)g(to)f (map)h(numeric)e(le)n(v)o(els)h(to)h(a)208 282 y(te)o(xtual)21 b(representation,)f(for)i(e)o(xample)f(when)g(a)i FJ(Formatter)e FN(formats)g(a)i(message.)31 b(This)22 b(function)f(can)h(also)g(be)g (used)g(to)208 382 y(de\002ne)17 b(your)g(o)n(wn)h(le)n(v)o(els.)24 b(The)18 b(only)f(constraints)g(are)i(that)f(all)h(le)n(v)o(els)f(used) g(must)g(be)g(re)o(gistered)f(using)g(this)i(function,)e(le)n(v)o(els) 208 482 y(should)i(be)h(positi)n(v)o(e)f(inte)o(gers)h(and)f(the)o(y)h (should)f(increase)h(in)g(increasing)f(order)g(of)h(se)n(v)o(erity)-5 b(.)0 628 y FD(getLevelName)p FJ(\()p FK(lvl)p FJ(\))208 728 y FN(Returns)23 b(the)i(te)o(xtual)e(representation)f(of)i(logging) e(le)n(v)o(el)i FK(lvl)p FN(.)37 b(If)24 b(the)g(le)n(v)o(el)g(is)h (one)f(of)f(the)i(prede\002ned)d(le)n(v)o(els)i FJ(CRITICAL)p FN(,)208 828 y FJ(ERROR)p FN(,)d FJ(WARNING)p FN(,)g FJ(INFO)g FN(or)h FJ(DEBUG)g FN(then)f(you)g(get)h(the)g(corresponding) c(string.)30 b(If)22 b(you)f(ha)n(v)o(e)g(associated)h(le)n(v)o(els)f (with)208 927 y(names)k(using)g FJ(addLevelName\(\))e FN(then)i(the)h(name)f(you)g(ha)n(v)o(e)g(associated)g(with)h FK(lvl)g FN(is)g(returned.)40 b(If)25 b(a)h(numeric)e(v)n(alue)208 1027 y(corresponding)j(to)k(one)g(of)g(the)g(de\002ned)f(le)n(v)o(els)h (is)h(passed)f(in,)i(the)e(corresponding)d(string)j(representation)e (is)j(returned.)208 1127 y(Otherwise,)19 b(the)h(string)g(\224Le)n(v)o (el)g(\045s\224)h(\045)g(lvl)f(is)h(returned.)0 1273 y FD(makeLogRecord)p FJ(\()p FK(attr)m(dict)q FJ(\))208 1373 y FN(Creates)d(and)g(returns)f(a)h(ne)n(w)g FJ(LogRecord)f FN(instance)h(whose)g(attrib)n(utes)g(are)g(de\002ned)f(by)h FK(attr)m(dict)q FN(.)24 b(This)19 b(function)d(is)j(useful)208 1473 y(for)e(taking)h(a)h(pickled)f FJ(LogRecord)f FN(attrib)n(ute)h (dictionary)-5 b(,)17 b(sent)i(o)o(v)o(er)e(a)i(sock)o(et,)f(and)g (reconstituting)f(it)i(as)h(a)f FJ(LogRecord)208 1572 y FN(instance)g(at)i(the)f(recei)n(ving)f(end.)0 1719 y FD(basicConfig)p FJ(\()p FC([)p FK(**kwar)m(gs)12 b FC(])p FJ(\))208 1819 y FN(Does)23 b(basic)g(con\002guration)d(for)i (the)h(logging)e(system)i(by)g(creating)f(a)h FJ(StreamHandler)e FN(with)i(a)g(def)o(ault)g FJ(Formatter)208 1918 y FN(and)47 b(adding)f(it)i(to)g(the)g(root)f(logger)-5 b(.)106 b(The)48 b(functions)e FJ(debug\(\))p FN(,)53 b FJ(info\(\))p FN(,)h FJ(warning\(\))p FN(,)f FJ(error\(\))47 b FN(and)208 2018 y FJ(critical\(\))18 b FN(will)j(call)g FJ(basicConfig\(\))d FN(automatically)h(if)i(no)e(handlers)g(are)h(de\002ned)g(for)f(the)h (root)g(logger)-5 b(.)208 2151 y(Changed)18 b(in)j(v)o(ersion)e(2.4:)g (F)o(ormerly)-5 b(,)18 b FJ(basicConfig)h FN(did)h(not)g(tak)o(e)g(an)o (y)f(k)o(e)o(yw)o(ord)g(ar)o(guments.)208 2284 y(The)g(follo)n(wing)g (k)o(e)o(yw)o(ord)f(ar)o(guments)g(are)j(supported.)257 2495 y FL(F)n(ormat)p 704 2524 4 100 v 232 w(Description)p 208 2528 5688 4 v 257 2598 a FJ(filename)p 704 2627 4 100 v 99 w FN(Speci\002es)f(that)g(a)h(FileHandler)e(be)h(created,)g (using)f(the)h(speci\002ed)g(\002lename,)g(rather)f(than)h(a)h (StreamHandler)-5 b(.)257 2697 y FJ(filemode)p 704 2727 V 99 w FN(Speci\002es)20 b(the)g(mode)f(to)i(open)e(the)h(\002le,)h(if) f(\002lename)g(is)h(speci\002ed)f(\(if)g(\002lemode)f(is)j (unspeci\002ed,)c(it)j(def)o(aults)f(to)g('a'\).)257 2797 y FJ(format)p 704 2827 V 199 w FN(Use)g(the)h(speci\002ed)e (format)h(string)f(for)h(the)g(handler)-5 b(.)257 2896 y FJ(datefmt)p 704 2926 V 149 w FN(Use)20 b(the)h(speci\002ed)e (date/time)h(format.)257 2996 y FJ(level)p 704 3026 V 249 w FN(Set)g(the)h(root)e(logger)g(le)n(v)o(el)h(to)g(the)g (speci\002ed)g(le)n(v)o(el.)257 3096 y FJ(stream)p 704 3126 V 199 w FN(Use)g(the)h(speci\002ed)e(stream)i(to)f(initialize)g (the)g(StreamHandler)-5 b(.)24 b(Note)c(that)g(this)h(ar)o(gument)d(is) j(incompatible)d(with)j('\002lename')e(-)h(if)h(both)e(are)h(present,)f (')-5 b(stream')20 b(is)h(ignored.)0 3233 y FD(shutdown)p FJ(\(\))208 3333 y FN(Informs)d(the)i(logging)f(system)h(to)h(perform)d (an)i(orderly)e(shutdo)n(wn)h(by)h(\003ushing)f(and)h(closing)f(all)i (handlers.)0 3480 y FD(setLoggerClass)p FJ(\()p FK(klass)p FJ(\))208 3580 y FN(T)-6 b(ells)21 b(the)g(logging)f(system)h(to)g(use) g(the)g(class)h FK(klass)g FN(when)e(instantiating)g(a)i(logger)-5 b(.)26 b(The)21 b(class)h(should)e(de\002ne)g FJ(__init_-)208 3679 y(_\(\))h FN(such)g(that)h(only)e(a)i(name)f(ar)o(gument)e(is)k (required,)c(and)i(the)h FJ(__init__\(\))e FN(should)h(call)g FJ(Logger.__init__\(\))p FN(.)208 3779 y(This)k(function)e(is)i (typically)f(called)h(before)e(an)o(y)h(loggers)g(are)h(instantiated)f (by)g(applications)g(which)g(need)g(to)h(use)g(custom)208 3878 y(logger)18 b(beha)n(vior)-5 b(.)0 4025 y FL(See)21 b(Also:)0 4172 y FN(PEP)g(282,)e(\223)p FK(A)h(Lo)o(g)o(ging)f(System)p FN(\224)208 4272 y(The)g(proposal)g(which)h(described)f(this)h(feature) g(for)f(inclusion)g(in)i(the)f(Python)f(standard)g(library)-5 b(.)0 4419 y(Original)19 b(Python)h FJ(logging)f FN(package)208 4518 y(This)27 b(is)g(the)g(original)f(source)g(for)g(the)h FJ(logging)f FN(package.)43 b(The)26 b(v)o(ersion)g(of)g(the)h(package) f(a)n(v)n(ailable)g(from)g(this)h(site)h(is)208 4618 y(suitable)20 b(for)g(use)g(with)h(Python)e(1.5.2,)g(2.1.x)g(and)h (2.2.x,)f(which)h(do)g(not)g(include)f(the)i FJ(logging)f FN(package)f(in)h(the)h(standard)208 4718 y(library)-5 b(.)0 5002 y Fv(14.5.1)101 b(Logger)29 b(Objects)0 5205 y FN(Loggers)g(ha)n(v)o(e)h(the)h(follo)n(wing)e(attrib)n(utes)i(and)f (methods.)55 b(Note)31 b(that)f(Loggers)g(are)g(ne)n(v)o(er)g (instantiated)g(directly)-5 b(,)31 b(b)n(ut)g(al)o(w)o(ays)0 5305 y(through)18 b(the)i(module-le)n(v)o(el)e(function)g FJ(logging.getLogger\(name\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility) e(f)n(or)f(Python)2103 b(453)p eop end %%Page: 454 466 TeXDict begin 454 465 bop 0 83 a FD(propagate)208 183 y FN(If)28 b(this)i(e)n(v)n(aluates)e(to)h(f)o(alse,)i(logging)d (messages)h(are)g(not)f(passed)h(by)g(this)g(logger)f(or)g(by)h(child)f (loggers)g(to)h(higher)f(le)n(v)o(el)208 282 y(\(ancestor\))18 b(loggers.)24 b(The)c(constructor)e(sets)k(this)e(attrib)n(ute)g(to)g (1.)0 429 y FD(setLevel)p FJ(\()p FK(lvl)p FJ(\))208 529 y FN(Sets)h(the)f(threshold)f(for)h(this)h(logger)e(to)h FK(lvl)p FN(.)26 b(Logging)18 b(messages)j(which)f(are)g(less)h(se)n(v) o(ere)f(than)g FK(lvl)h FN(will)g(be)f(ignored.)k(When)208 628 y(a)g(logger)f(is)i(created,)f(the)g(le)n(v)o(el)g(is)h(set)g(to)f FJ(NOTSET)g FN(\(which)f(causes)h(all)h(messages)f(to)g(be)g(processed) f(when)h(the)g(logger)f(is)208 728 y(the)h(root)g(logger)m(,)g(or)h (dele)o(gation)d(to)j(the)g(parent)e(when)h(the)h(logger)e(is)j(a)f (non-root)d(logger\).)37 b(Note)25 b(that)g(the)f(root)g(logger)g(is) 208 828 y(created)19 b(with)h(le)n(v)o(el)g FJ(WARNING)p FN(.)208 960 y(The)g(term)h(\224dele)o(gation)d(to)k(the)f(parent\224)e (means)i(that)g(if)g(a)h(logger)d(has)j(a)f(le)n(v)o(el)g(of)f(NO)m (TSET)-6 b(,)20 b(its)i(chain)f(of)f(ancestor)h(loggers)208 1060 y(is)g(tra)n(v)o(ersed)e(until)h(either)g(an)g(ancestor)f(with)h (a)h(le)n(v)o(el)f(other)f(than)h(NO)m(TSET)g(is)h(found,)d(or)i(the)g (root)g(is)h(reached.)208 1193 y(If)e(an)g(ancestor)f(is)i(found)e (with)h(a)h(le)n(v)o(el)e(other)h(than)f(NO)m(TSET)-6 b(,)19 b(then)f(that)i(ancestor')-5 b(s)18 b(le)n(v)o(el)h(is)h (treated)f(as)h(the)f(ef)n(fecti)n(v)o(e)f(le)n(v)o(el)208 1293 y(of)h(the)i(logger)e(where)g(the)h(ancestor)g(search)g(be)o(gan,) e(and)h(is)i(used)f(to)h(determine)d(ho)n(w)i(a)h(logging)d(e)n(v)o (ent)h(is)j(handled.)208 1425 y(If)f(the)g(root)g(is)i(reached,)d(and)h (it)h(has)g(a)g(le)n(v)o(el)f(of)g(NO)m(TSET)-6 b(,)21 b(then)g(all)h(messages)g(will)g(be)f(processed.)28 b(Otherwise,)21 b(the)h(root')-5 b(s)208 1525 y(le)n(v)o(el)19 b(will)i(be)f(used)g(as) h(the)f(ef)n(fecti)n(v)o(e)f(le)n(v)o(el.)0 1672 y FD(isEnabledFor)p FJ(\()p FK(lvl)p FJ(\))208 1772 y FN(Indicates)38 b(if)h(a)h(message)e (of)h(se)n(v)o(erity)f FK(lvl)i FN(w)o(ould)e(be)h(processed)f(by)h (this)g(logger)-5 b(.)81 b(This)39 b(method)e(checks)i(\002rst)h(the) 208 1871 y(module-le)n(v)o(el)22 b(le)n(v)o(el)i(set)h(by)f FJ(logging.disable\(lvl\))e FN(and)i(then)g(the)h(logger')-5 b(s)23 b(ef)n(fecti)n(v)o(e)h(le)n(v)o(el)g(as)h(determined)e(by)208 1971 y FJ(getEffectiveLevel\(\))p FN(.)0 2118 y FD(getEffectiveLevel)p FJ(\(\))208 2217 y FN(Indicates)17 b(the)h(ef)n(fecti)n(v)o(e)f(le)n(v) o(el)g(for)h(this)g(logger)-5 b(.)24 b(If)18 b(a)g(v)n(alue)f(other)h (than)f FJ(NOTSET)h FN(has)g(been)f(set)i(using)f FJ(setLevel\(\))p FN(,)f(it)i(is)208 2317 y(returned.)29 b(Otherwise,)22 b(the)g(hierarchy)e(is)j(tra)n(v)o(ersed)f(to)n(w)o(ards)f(the)i(root)e (until)h(a)h(v)n(alue)e(other)h(than)g FJ(NOTSET)f FN(is)i(found,)e (and)208 2417 y(that)f(v)n(alue)f(is)i(returned.)0 2563 y FD(debug)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 2663 y FN(Logs)24 b(a)h(message)g(with)g(le)n(v)o(el)f FJ(DEBUG)g FN(on)h(this)g(logger)-5 b(.)38 b(The)24 b FK(msg)h FN(is)h(the)f (message)f(format)g(string,)h(and)f(the)h FK(ar)m(gs)g FN(are)g(the)208 2763 y(ar)o(guments)20 b(which)j(are)g(mer)o(ged)e (into)h FK(msg)i FN(using)e(the)h(string)f(formatting)f(operator)-5 b(.)32 b(\(Note)23 b(that)g(this)g(means)g(that)g(you)f(can)208 2862 y(use)e(k)o(e)o(yw)o(ords)f(in)h(the)g(format)f(string,)h (together)f(with)h(a)h(single)f(dictionary)e(ar)o(gument.\))208 2995 y(There)e(are)i(tw)o(o)g(k)o(e)o(yw)o(ord)e(ar)o(guments)f(in)j FK(kwar)m(gs)g FN(which)f(are)h(inspected:)23 b FK(e)n(xc)p 2503 2995 25 4 v 30 w(info)17 b FN(which,)g(if)h(it)h(does)e(not)g(e)n (v)n(aluate)g(as)h(f)o(alse,)208 3095 y(causes)j(e)o(xception)f (information)g(to)h(be)h(added)f(to)g(the)h(logging)e(message.)29 b(If)22 b(an)f(e)o(xception)f(tuple)i(\(in)f(the)h(format)e(returned) 208 3194 y(by)k FJ(sys.exc_info\(\))p FN(\))e(is)j(pro)o(vided,)e(it)i (is)g(used;)h(otherwise,)f FJ(sys.exc_info\(\))d FN(is)k(called)e(to)h (get)f(the)g(e)o(xception)208 3294 y(information.)208 3427 y(The)c(other)g(optional)g(k)o(e)o(yw)o(ord)f(ar)o(gument)f(is)k FK(e)n(xtr)o(a)f FN(which)f(can)h(be)g(used)g(to)g(pass)g(a)g (dictionary)e(which)i(is)g(used)g(to)g(populate)208 3526 y(the)p 334 3526 V 364 3526 V 79 w(dict)p 519 3526 V 548 3526 V 79 w(of)e(the)g(LogRecord)f(created)h(for)f(the)i(logging)d (e)n(v)o(ent)i(with)g(user)n(-de\002ned)f(attrib)n(utes.)25 b(These)19 b(custom)g(attrib)n(utes)208 3626 y(can)h(then)f(be)h(used)g (as)h(you)f(lik)o(e.)25 b(F)o(or)20 b(e)o(xample,)e(the)o(y)i(could)f (be)h(incorporated)d(into)j(logged)f(messages.)25 b(F)o(or)20 b(e)o(xample:)489 3850 y FA(FORMAT)43 b(=)i("\045\(asctime\)-15s)d (\045\(clientip\)s)h(\045\(user\)-8s)g(\045\(message\)s")489 3942 y(logging.basicConfig\(format=FORMAT\))489 4033 y(d)h(=)h({)g('clientip')e(:)h('192.168.0.1',)f('user')h(:)g('fbloggs') g(})489 4124 y(logger)f(=)i(logging.getLogger\("tcpserver"\))489 4216 y(logger.warning\("Protocol)40 b(problem:)k(\045s",)g("connection) f(reset",)h(extra=d\))208 4405 y FN(w)o(ould)19 b(print)h(something)e (lik)o(e)444 4629 y FA(2006-02-08)43 b(22:20:02,165)g(192.168.0.1)g (fbloggs)88 b(Protocol)44 b(problem:)f(connection)g(reset)208 4819 y FN(The)22 b(k)o(e)o(ys)g(in)g(the)h(dictionary)d(passed)j(in)f FK(e)n(xtr)o(a)h FN(should)e(not)h(clash)h(with)g(the)f(k)o(e)o(ys)g (used)g(by)g(the)h(logging)d(system.)32 b(\(See)23 b(the)208 4918 y FJ(Formatter)c FN(documentation)e(for)i(more)h(information)e(on) h(which)h(k)o(e)o(ys)g(are)g(used)g(by)g(the)g(logging)e(system.\))208 5051 y(If)h(you)g(choose)f(to)i(use)g(these)f(attrib)n(utes)h(in)f (logged)f(messages,)i(you)f(need)f(to)i(e)o(x)o(ercise)f(some)g(care.) 25 b(In)19 b(the)g(abo)o(v)o(e)f(e)o(xample,)208 5151 y(for)25 b(instance,)i(the)f FJ(Formatter)f FN(has)h(been)g(set)h(up)e (with)h(a)h(format)e(string)h(which)f(e)o(xpects)h('clientip')f(and)g ('user')g(in)i(the)208 5250 y(attrib)n(ute)g(dictionary)e(of)j(the)f (LogRecord.)45 b(If)27 b(these)h(are)f(missing,)i(the)f(message)f(will) i(not)e(be)g(logged)f(because)h(a)h(string)208 5350 y(formatting)18 b(e)o(xception)g(will)j(occur)-5 b(.)24 b(So)d(in)f(this)h(case,)f(you) g(al)o(w)o(ays)g(need)g(to)g(pass)h(the)f FK(e)n(xtr)o(a)g FN(dictionary)f(with)h(these)h(k)o(e)o(ys.)p 0 5549 3901 4 v 0 5649 a FI(454)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 455 467 TeXDict begin 455 466 bop 208 83 a FN(While)32 b(this)g(might)f(be)g (anno)o(ying,)h(this)g(feature)f(is)i(intended)d(for)h(use)g(in)h (specialized)f(circumstances,)i(such)f(as)g(multi-)208 183 y(threaded)26 b(serv)o(ers)i(where)g(the)g(same)h(code)f(e)o(x)o (ecutes)f(in)h(man)o(y)g(conte)o(xts,)h(and)f(interesting)f(conditions) g(which)h(arise)h(are)208 282 y(dependent)16 b(on)i(this)h(conte)o(xt)f (\(such)g(as)h(remote)f(client)g(IP)h(address)g(and)f(authenticated)f (user)h(name,)g(in)h(the)g(abo)o(v)o(e)e(e)o(xample\).)208 382 y(In)i(such)h(circumstances,)f(it)i(is)g(lik)o(ely)f(that)h (specialized)e FJ(Formatter)p FN(s)h(w)o(ould)f(be)h(used)g(with)g (particular)f FJ(Handler)p FN(s.)208 515 y(Changed)f(in)j(v)o(ersion)e (2.5:)g FK(e)n(xtr)o(a)i FN(w)o(as)g(added.)0 662 y FD(info)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)p FC([)p FK(,)h(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 761 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o (el)g FJ(INFO)g FN(on)g(this)h(logger)-5 b(.)24 b(The)c(ar)o(guments)e (are)i(interpreted)e(as)j(for)f FJ(debug\(\))p FN(.)0 908 y FD(warning)p FJ(\()p FK(msg)p FC([)p FK(,)f(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 1008 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o(el)g FJ(WARNING)g FN(on)f(this)i(logger)-5 b(.)24 b(The)c(ar)o(guments)e(are)i (interpreted)f(as)i(for)e FJ(debug\(\))p FN(.)0 1155 y FD(error)p FJ(\()p FK(msg)p FC([)p FK(,)g(*ar)m(gs)p FC([)p FK(,)g(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 1254 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o(el)g FJ(ERROR)g FN(on)g(this)h(logger)-5 b(.)24 b(The)19 b(ar)o(guments)g(are)h (interpreted)e(as)j(for)f FJ(debug\(\))p FN(.)0 1401 y FD(critical)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)p FC([)p FK(,)i(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 1501 y FN(Logs)19 b(a)i(message)f(with)g(le)n(v)o(el)g FJ(CRITICAL)f FN(on)h(this)h(logger)-5 b(.)24 b(The)c(ar)o(guments)e(are)i (interpreted)f(as)h(for)g FJ(debug\(\))p FN(.)0 1648 y FD(log)p FJ(\()p FK(lvl,)g(msg)p FC([)p FK(,)g(*ar)m(gs)p FC([)p FK(,)f(**kwar)m(gs)12 b FC(])g(])p FJ(\))208 1747 y FN(Logs)19 b(a)i(message)f(with)g(inte)o(ger)f(le)n(v)o(el)h FK(lvl)h FN(on)f(this)h(logger)-5 b(.)24 b(The)c(other)f(ar)o(guments)f (are)i(interpreted)f(as)h(for)g FJ(debug\(\))p FN(.)0 1894 y FD(exception)p FJ(\()p FK(msg)p FC([)p FK(,)e(*ar)m(gs)12 b FC(])p FJ(\))208 1994 y FN(Logs)23 b(a)h(message)g(with)g(le)n(v)o (el)g FJ(ERROR)f FN(on)h(this)g(logger)-5 b(.)35 b(The)24 b(ar)o(guments)d(are)j(interpreted)e(as)j(for)e FJ(debug\(\))p FN(.)35 b(Exception)208 2093 y(info)19 b(is)i(added)e(to)i(the)f (logging)e(message.)25 b(This)20 b(method)f(should)g(only)h(be)g (called)g(from)f(an)h(e)o(xception)e(handler)-5 b(.)0 2240 y FD(addFilter)p FJ(\()p FK(\002lt)q FJ(\))208 2340 y FN(Adds)20 b(the)g(speci\002ed)g(\002lter)g FK(\002lt)i FN(to)f(this)f(logger)-5 b(.)0 2487 y FD(removeFilter)p FJ(\()p FK(\002lt)q FJ(\))208 2586 y FN(Remo)o(v)o(es)19 b(the)h(speci\002ed)g(\002lter)h FK(\002lt)g FN(from)f(this)g(logger)-5 b(.)0 2733 y FD(filter)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 2833 y FN(Applies)20 b(this)g(logger')-5 b(s)20 b(\002lters)g(to)h(the) f(record)f(and)g(returns)h(a)g(true)g(v)n(alue)g(if)g(the)g(record)f (is)i(to)g(be)f(processed.)0 2980 y FD(addHandler)p FJ(\()p FK(hdlr)r FJ(\))208 3079 y FN(Adds)g(the)g(speci\002ed)g(handler)e FK(hdlr)k FN(to)f(this)g(logger)-5 b(.)0 3226 y FD(removeHandler)p FJ(\()p FK(hdlr)r FJ(\))208 3326 y FN(Remo)o(v)o(es)19 b(the)h(speci\002ed)g(handler)f FK(hdlr)j FN(from)d(this)i(logger)-5 b(.)0 3473 y FD(findCaller)p FJ(\(\))208 3572 y FN(Finds)23 b(the)h(caller')-5 b(s)24 b(source)f(\002lename)g(and)g(line)g(number) -5 b(.)34 b(Returns)23 b(the)h(\002lename,)g(line)f(number)f(and)h (function)f(name)h(as)h(a)208 3672 y(3-element)d(tuple.)65 b(Changed)22 b(in)g(v)o(ersion)g(2.4:)g(The)g(function)f(name)h(w)o(as) i(added.)31 b(In)23 b(earlier)f(v)o(ersions,)g(the)h(\002lename)f(and) 208 3772 y(line)e(number)e(were)i(returned)f(as)i(a)f(2-element)f (tuple..)0 3918 y FD(handle)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 4018 y FN(Handles)g(a)i(record)e(by)h(passing)g(it)h(to)f (all)h(handlers)e(associated)h(with)h(this)f(logger)f(and)h(its)h (ancestors)f(\(until)g(a)h(f)o(alse)f(v)n(alue)g(of)208 4118 y FK(pr)l(opa)o(gate)e FN(is)j(found\).)j(This)c(method)f(is)i (used)f(for)g(unpickled)e(records)i(recei)n(v)o(ed)e(from)i(a)g(sock)o (et,)g(as)h(well)g(as)g(those)f(created)208 4217 y(locally)-5 b(.)24 b(Logger)n(-le)n(v)o(el)17 b(\002ltering)j(is)h(applied)e(using) h FJ(filter\(\))p FN(.)0 4364 y FD(makeRecord)p FJ(\()p FK(name)o(,)d(lvl,)k(fn,)f(lno,)g(msg)o(,)g(ar)m(gs,)g(e)n(xc)p 1621 4364 25 4 v 30 w(info)g FC([)p FK(,)g(func,)g(e)n(xtr)o(a)12 b FC(])p FJ(\))208 4464 y FN(This)26 b(is)h(a)f(f)o(actory)f(method)g (which)h(can)g(be)g(o)o(v)o(erridden)c(in)27 b(subclasses)f(to)h (create)e(specialized)h FJ(LogRecord)f FN(instances.)208 4563 y(Changed)18 b(in)j(v)o(ersion)e(2.5:)g FK(func)h FN(and)g FK(e)n(xtr)o(a)g FN(were)g(added.)0 4848 y Fv(14.5.2)101 b(Basic)28 b(e)m(xample)0 5051 y FN(Changed)19 b(in)h(v)o(ersion)f (2.4:)h(formerly)e FJ(basicConfig)h FN(did)h(not)f(tak)o(e)i(an)o(y)e (k)o(e)o(yw)o(ord)f(ar)o(guments.)0 5198 y(The)24 b FJ(logging)f FN(package)g(pro)o(vides)f(a)j(lot)f(of)g(\003e)o(xibility)-5 b(,)24 b(and)g(its)h(con\002guration)c(can)j(appear)f(daunting.)35 b(This)24 b(section)g(demon-)0 5298 y(strates)d(that)f(simple)g(use)h (of)f(the)g(logging)e(package)h(is)i(possible.)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n (acility)e(f)n(or)f(Python)2103 b(455)p eop end %%Page: 456 468 TeXDict begin 456 467 bop 0 83 a FN(The)20 b(simplest)g(e)o(xample)f (sho)n(ws)h(logging)f(to)h(the)g(console:)236 321 y FA(import)44 b(logging)236 504 y(logging.debug\('A)e(debug)i(message'\))236 595 y(logging.info\('Some)e(information'\))236 687 y (logging.warning\('A)g(shot)i(across)g(the)g(bows'\))0 973 y FN(If)20 b(you)f(run)h(the)g(abo)o(v)o(e)e(script,)i(you')o(ll)g (see)h(this:)236 1211 y FA(WARNING:root:A)43 b(shot)h(across)g(the)g (bows)0 1498 y FN(Because)16 b(no)f(particular)g(logger)f(w)o(as)j (speci\002ed,)f(the)g(system)g(used)f(the)h(root)f(logger)-5 b(.)22 b(The)16 b(deb)n(ug)e(and)i(info)f(messages)h(didn')o(t)e (appear)0 1597 y(because)k(by)h(def)o(ault,)f(the)i(root)e(logger)g(is) i(con\002gured)d(to)i(only)f(handle)g(messages)h(with)h(a)f(se)n(v)o (erity)f(of)h(W)-10 b(ARNING)20 b(or)f(abo)o(v)o(e.)k(The)0 1697 y(message)28 b(format)g(is)h(also)g(a)f(con\002guration)e(def)o (ault,)k(as)f(is)g(the)f(output)g(destination)f(of)h(the)h(messages)f (-)h FJ(sys.stderr)p FN(.)48 b(The)0 1797 y(se)n(v)o(erity)19 b(le)n(v)o(el,)h(the)g(message)g(format)f(and)h(destination)f(can)h(be) g(easily)h(changed,)d(as)j(sho)n(wn)e(in)h(the)h(e)o(xample)d(belo)n (w:)236 1943 y FA(import)44 b(logging)236 2126 y (logging.basicConfig\(level=logging.DEBUG,)1133 2217 y(format='\045\(asctime\)s)d(\045\(levelname\)s)i(\045\(message\)s',) 1133 2309 y(filename='/tmp/myapp.log',)1133 2400 y(filemode='w'\))236 2491 y(logging.debug\('A)f(debug)i(message'\))236 2583 y(logging.info\('Some)e(information'\))236 2674 y(logging.warning\('A)g (shot)i(across)g(the)g(bows'\))0 2961 y FN(The)33 b FJ(basicConfig\(\)) f FN(method)g(is)j(used)e(to)h(change)e(the)i(con\002guration)d(def)o (aults,)36 b(which)d(results)h(in)g(output)e(\(written)h(to)0 3060 y FJ(/tmp/myapp.log)p FN(\))18 b(which)h(should)h(look)f (something)g(lik)o(e)h(the)g(follo)n(wing:)236 3298 y FA(2004-07-02)43 b(13:00:08,743)g(DEBUG)h(A)h(debug)f(message)236 3390 y(2004-07-02)f(13:00:08,743)g(INFO)h(Some)h(information)236 3481 y(2004-07-02)e(13:00:08,743)g(WARNING)h(A)h(shot)f(across)f(the)i (bows)0 3768 y FN(This)24 b(time,)h(all)f(messages)g(with)g(a)h(se)n(v) o(erity)e(of)g(DEB)o(UG)i(or)e(abo)o(v)o(e)f(were)i(handled,)f(and)g (the)h(format)f(of)h(the)g(messages)g(w)o(as)g(also)0 3867 y(changed,)18 b(and)i(output)f(went)h(to)g(the)g(speci\002ed)g (\002le)h(rather)f(than)f(the)h(console.)0 4014 y(F)o(ormatting)g(uses) h(standard)f(Python)g(string)h(formatting)f(-)h(see)h(section)f(3.6.2.) 26 b(The)21 b(format)f(string)h(tak)o(es)h(the)f(follo)n(wing)e(common) 0 4114 y(speci\002ers.)25 b(F)o(or)20 b(a)h(complete)e(list)i(of)f (speci\002ers,)g(consult)f(the)i FJ(Formatter)e FN(documentation.)50 4422 y FL(F)n(ormat)p 746 4452 4 100 v 480 w(Description)p 0 4455 6955 4 v 50 4525 a FJ(\045\(name\)s)p 746 4554 4 100 v 347 w FN(Name)h(of)g(the)g(logger)f(\(logging)f(channel\).)50 4624 y FJ(\045\(levelname\)s)p 746 4654 V 97 w FN(T)-6 b(e)o(xt)20 b(logging)e(le)n(v)o(el)i(for)g(the)g(message)g(\()p FJ('DEBUG')p FN(,)f FJ('INFO')p FN(,)g FJ('WARNING')p FN(,)g FJ('ERROR')p FN(,)g FJ('CRITICAL')p FN(\).)50 4724 y FJ(\045\(asctime\)s)p 746 4754 V 197 w FN(Human-readable)e(time) j(when)g(the)g FJ(LogRecord)f FN(w)o(as)i(created.)j(By)d(def)o(ault)f (this)g(is)h(of)f(the)h(form)e(\2232003-07-08)d(16:49:45,896\224)g (\(the)k(numbers)e(after)i(the)g(comma)g(are)g(millisecond)f(portion)g (of)g(the)i(time\).)50 4823 y FJ(\045\(message\)s)p 746 4853 V 197 w FN(The)f(logged)f(message.)0 5049 y(T)-7 b(o)20 b(change)f(the)h(date/time)g(format,)f(you)g(can)h(pass)h(an)f (additional)f(k)o(e)o(yw)o(ord)f(parameter)m(,)g FK(datefmt)q FN(,)j(as)f(in)h(the)f(follo)n(wing:)p 0 5549 3901 4 v 0 5649 a FI(456)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 457 469 TeXDict begin 457 468 bop 236 174 a FA(import)44 b(logging)236 357 y(logging.basicConfig\(level=logging.DEBUG,)1133 448 y(format='\045\(asctime\)s)d(\045\(levelname\)-8s)i (\045\(message\)s',)1133 540 y(datefmt='\045a,)g(\045d)h(\045b)h(\045Y) f(\045H:\045M:\045S',)1133 631 y(filename='/temp/myapp.log',)1133 722 y(filemode='w'\))236 814 y(logging.debug\('A)e(debug)i(message'\)) 236 905 y(logging.info\('Some)e(information'\))236 996 y(logging.warning\('A)g(shot)i(across)g(the)g(bows'\))0 1283 y FN(which)20 b(w)o(ould)f(result)h(in)h(output)e(lik)o(e)236 1521 y FA(Fri,)44 b(02)h(Jul)f(2004)g(13:06:18)g(DEBUG)178 b(A)45 b(debug)f(message)236 1612 y(Fri,)g(02)h(Jul)f(2004)g(13:06:18)g (INFO)223 b(Some)44 b(information)236 1704 y(Fri,)g(02)h(Jul)f(2004)g (13:06:18)g(WARNING)88 b(A)45 b(shot)f(across)g(the)g(bows)0 1990 y FN(The)20 b(date)g(format)f(string)h(follo)n(ws)g(the)g (requirements)e(of)i FJ(strftime\(\))f FN(-)h(see)h(the)f (documentation)d(for)j(the)g FJ(time)g FN(module.)0 2137 y(If,)g(instead)f(of)h(sending)f(logging)f(output)h(to)h(the)g(console) f(or)h(a)g(\002le,)g(you')l(d)e(rather)i(use)g(a)g(\002le-lik)o(e)g (object)g(which)f(you)g(ha)n(v)o(e)g(created)0 2237 y(separately)-5 b(,)25 b(you)f(can)h(pass)h(it)g(to)g FJ(basicConfig\(\))d FN(using)i(the)g FK(str)m(eam)h FN(k)o(e)o(yw)o(ord)d(ar)o(gument.)38 b(Note)25 b(that)g(if)h(both)e FK(str)m(eam)i FN(and)0 2336 y FK(\002lename)19 b FN(k)o(e)o(yw)o(ord)f(ar)o(guments)h(are)h (passed,)f(the)i FK(str)m(eam)f FN(ar)o(gument)e(is)j(ignored.)0 2483 y(Of)e(course,)e(you)h(can)g(put)g(v)n(ariable)f(information)f(in) j(your)e(output.)23 b(T)-7 b(o)18 b(do)g(this,)h(simply)f(ha)n(v)o(e)g (the)g(message)h(be)f(a)h(format)e(string)h(and)0 2583 y(pass)j(in)f(additional)f(ar)o(guments)f(containing)g(the)j(v)n (ariable)e(information,)e(as)k(in)f(the)h(follo)n(wing)d(e)o(xample:) 236 2821 y FA(import)44 b(logging)236 3004 y (logging.basicConfig\(level=logging.DEBUG,)1133 3095 y(format='\045\(asctime\)s)d(\045\(levelname\)-8s)i(\045\(message\)s',) 1133 3186 y(datefmt='\045a,)g(\045d)h(\045b)h(\045Y)f (\045H:\045M:\045S',)1133 3278 y(filename='/temp/myapp.log',)1133 3369 y(filemode='w'\))236 3460 y(logging.error\('Pack)e(my)i(box)h (with)f(\045d)g(dozen)g(\045s',)g(5,)h('liquor)f(jugs'\))0 3747 y FN(which)20 b(w)o(ould)f(result)h(in)236 3985 y FA(Wed,)44 b(21)h(Jul)f(2004)g(15:35:16)g(ERROR)178 b(Pack)44 b(my)h(box)f(with)g(5)h(dozen)f(liquor)g(jugs)0 4408 y Fv(14.5.3)101 b(Logging)30 b(to)e(m)o(ultiple)g(destinations)0 4611 y FN(Let')-5 b(s)23 b(say)f(you)g(w)o(ant)g(to)h(log)f(to)g (console)g(and)g(\002le)h(with)f(dif)n(ferent)f(message)h(formats)f (and)h(in)h(dif)n(fering)d(circumstances.)30 b(Say)22 b(you)0 4711 y(w)o(ant)i(to)h(log)f(messages)g(with)g(le)n(v)o(els)g (of)g(DEB)o(UG)h(and)f(higher)f(to)h(\002le,)i(and)d(those)h(messages)h (at)f(le)n(v)o(el)g(INFO)h(and)e(higher)g(to)i(the)0 4810 y(console.)30 b(Let')-5 b(s)23 b(also)f(assume)h(that)f(the)g (\002le)h(should)e(contain)g(timestamps,)i(b)n(ut)f(the)g(console)g (messages)g(should)f(not.)31 b(Here')-5 b(s)22 b(ho)n(w)0 4910 y(you)d(can)h(achie)n(v)o(e)f(this:)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n (acility)e(f)n(or)f(Python)2103 b(457)p eop end %%Page: 458 470 TeXDict begin 458 469 bop 236 174 a FA(import)44 b(logging)236 357 y(#)h(set)f(up)h(logging)e(to)i(file)f(-)h(see)f(previous)f (section)h(for)g(more)h(details)236 448 y (logging.basicConfig\(level=logging.DEBUG,)1133 540 y (format='\045\(asctime\)s)c(\045\(name\)-12s)i(\045\(levelname\)-8s)g (\045\(message\)s',)1133 631 y(datefmt='\045m-\045d)f(\045H:\045M',) 1133 722 y(filename='/temp/myapp.log',)1133 814 y(filemode='w'\))236 905 y(#)j(define)f(a)g(Handler)g(which)g(writes)g(INFO)g(messages)f(or) i(higher)f(to)g(the)h(sys.stderr)236 996 y(console)f(=)h (logging.StreamHandler\(\))236 1088 y(console.setLevel\(logging.INFO\)) 236 1179 y(#)g(set)f(a)h(format)f(which)g(is)g(simpler)g(for)g(console) g(use)236 1270 y(formatter)g(=)g(logging.Formatter\('\045\(name\)-12s:) c(\045\(levelname\)-8s)i(\045\(message\)s'\))236 1362 y(#)j(tell)f(the)g(handler)g(to)h(use)f(this)g(format)236 1453 y(console.setFormatter\(formatter\))236 1544 y(#)h(add)f(the)h (handler)e(to)i(the)f(root)g(logger)236 1636 y (logging.getLogger\(''\).addHandler\(console)o(\))236 1818 y(#)h(Now,)f(we)h(can)f(log)g(to)h(the)f(root)g(logger,)g(or)g (any)h(other)f(logger.)f(First)h(the)h(root...)236 1910 y(logging.info\('Jackdaws)c(love)k(my)f(big)g(sphinx)g(of)h(quartz.'\)) 236 2092 y(#)g(Now,)f(define)g(a)h(couple)e(of)i(other)f(loggers)f (which)h(might)g(represent)g(areas)g(in)g(your)236 2183 y(#)h(application:)236 2366 y(logger1)f(=)h (logging.getLogger\('myapp.area1'\))236 2457 y(logger2)f(=)h (logging.getLogger\('myapp.area2'\))236 2640 y(logger1.debug\('Quick)d (zephyrs)h(blow,)h(vexing)g(daft)g(Jim.'\))236 2731 y (logger1.info\('How)e(quickly)i(daft)g(jumping)g(zebras)f(vex.'\))236 2823 y(logger2.warning\('Jail)f(zesty)i(vixen)g(who)g(grabbed)f(pay)i (from)f(quack.'\))236 2914 y(logger2.error\('The)e(five)i(boxing)g (wizards)g(jump)g(quickly.'\))0 3201 y FN(When)20 b(you)f(run)h(this,)g (on)g(the)g(console)g(you)f(will)i(see)236 3439 y FA(root)358 b(:)45 b(INFO)223 b(Jackdaws)44 b(love)g(my)g(big)h(sphinx)f(of)g (quartz.)236 3530 y(myapp.area1)f(:)i(INFO)223 b(How)45 b(quickly)e(daft)h(jumping)g(zebras)g(vex.)236 3621 y(myapp.area2)f(:)i (WARNING)88 b(Jail)45 b(zesty)f(vixen)f(who)i(grabbed)e(pay)i(from)f (quack.)236 3713 y(myapp.area2)f(:)i(ERROR)178 b(The)45 b(five)f(boxing)g(wizards)f(jump)h(quickly.)0 3999 y FN(and)20 b(in)g(the)g(\002le)h(you)e(will)i(see)g(something)e(lik)o(e) 236 4237 y FA(10-22)44 b(22:19)g(root)403 b(INFO)224 b(Jackdaws)43 b(love)h(my)h(big)f(sphinx)g(of)g(quartz.)236 4329 y(10-22)g(22:19)g(myapp.area1)88 b(DEBUG)179 b(Quick)43 b(zephyrs)h(blow,)g(vexing)g(daft)g(Jim.)236 4420 y(10-22)g(22:19)g (myapp.area1)88 b(INFO)224 b(How)44 b(quickly)f(daft)i(jumping)e (zebras)h(vex.)236 4511 y(10-22)g(22:19)g(myapp.area2)88 b(WARNING)h(Jail)44 b(zesty)g(vixen)g(who)g(grabbed)g(pay)g(from)g (quack.)236 4603 y(10-22)g(22:19)g(myapp.area2)88 b(ERROR)179 b(The)44 b(five)g(boxing)g(wizards)f(jump)i(quickly.)0 4889 y FN(As)21 b(you)e(can)h(see,)h(the)f(DEB)o(UG)h(message)f(only)f (sho)n(ws)h(up)g(in)h(the)f(\002le.)25 b(The)20 b(other)g(messages)g (are)g(sent)h(to)f(both)f(destinations.)0 5036 y(This)h(e)o(xample)f (uses)i(console)e(and)h(\002le)h(handlers,)e(b)n(ut)h(you)f(can)h(use)g (an)o(y)g(number)e(and)i(combination)e(of)i(handlers)f(you)g(choose.)p 0 5549 3901 4 v 0 5649 a FI(458)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 459 471 TeXDict begin 459 470 bop 0 83 a Fv(14.5.4)101 b(Sending)30 b(and)f(receiving)g(logging)h(e)m(v)n(ents)e(across)g(a)g(netw)o(or)q (k)0 286 y FN(Let')-5 b(s)24 b(say)g(you)f(w)o(ant)g(to)h(send)f (logging)f(e)n(v)o(ents)h(across)g(a)h(netw)o(ork,)f(and)g(handle)g (them)g(at)h(the)f(recei)n(ving)f(end.)35 b(A)24 b(simple)f(w)o(ay)h (of)0 386 y(doing)19 b(this)i(is)g(attaching)e(a)h FJ(SocketHandler)f FN(instance)h(to)g(the)g(root)g(logger)f(at)h(the)g(sending)f(end:)236 624 y FA(import)44 b(logging,)g(logging.handlers)236 806 y(rootLogger)f(=)i(logging.getLogger\(''\))236 898 y(rootLogger.setLevel\(logging.DEBUG\))236 989 y(socketHandler)e(=)i (logging.handlers.SocketHandler\('loca)o(lhost')o(,)1133 1080 y(logging.handlers.DEFAULT_TCP_LOGGING_P)o(ORT\))236 1172 y(#)g(don't)f(bother)g(with)g(a)h(formatter,)e(since)h(a)g(socket) g(handler)g(sends)g(the)g(event)g(as)236 1263 y(#)h(an)f(unformatted)f (pickle)236 1354 y(rootLogger.addHandler\(socketHandler\))236 1537 y(#)i(Now,)f(we)h(can)f(log)g(to)h(the)f(root)g(logger,)g(or)g (any)h(other)f(logger.)f(First)h(the)h(root...)236 1628 y(logging.info\('Jackdaws)c(love)k(my)f(big)g(sphinx)g(of)h(quartz.'\)) 236 1811 y(#)g(Now,)f(define)g(a)h(couple)e(of)i(other)f(loggers)f (which)h(might)g(represent)g(areas)g(in)g(your)236 1902 y(#)h(application:)236 2085 y(logger1)f(=)h (logging.getLogger\('myapp.area1'\))236 2176 y(logger2)f(=)h (logging.getLogger\('myapp.area2'\))236 2359 y(logger1.debug\('Quick)d (zephyrs)h(blow,)h(vexing)g(daft)g(Jim.'\))236 2450 y (logger1.info\('How)e(quickly)i(daft)g(jumping)g(zebras)f(vex.'\))236 2542 y(logger2.warning\('Jail)f(zesty)i(vixen)g(who)g(grabbed)f(pay)i (from)f(quack.'\))236 2633 y(logger2.error\('The)e(five)i(boxing)g (wizards)g(jump)g(quickly.'\))0 2919 y FN(At)21 b(the)f(recei)n(ving)f (end,)g(you)g(can)h(set)h(up)f(a)h(recei)n(v)o(er)d(using)i(the)g FJ(SocketServer)f FN(module.)k(Here)d(is)i(a)e(basic)h(w)o(orking)d(e)o (xample:)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python)2103 b(459)p eop end %%Page: 460 472 TeXDict begin 460 471 bop 236 174 a FA(import)44 b(cPickle)236 266 y(import)g(logging)236 357 y(import)g(logging.handlers)236 448 y(import)g(SocketServer)236 540 y(import)g(struct)236 814 y(class)g(LogRecordStreamHandler\(SocketServer.Stre)o(amRequ)o (estHan)o(dler\):)416 905 y("""Handler)f(for)h(a)h(streaming)e(logging) h(request.)416 1088 y(This)g(basically)f(logs)h(the)h(record)e(using)h (whatever)g(logging)f(policy)h(is)416 1179 y(configured)f(locally.)416 1270 y(""")416 1453 y(def)h(handle\(self\):)595 1544 y(""")595 1636 y(Handle)g(multiple)f(requests)h(-)g(each)g(expected)g (to)g(be)h(a)g(4-byte)e(length,)595 1727 y(followed)g(by)i(the)f (LogRecord)g(in)g(pickle)g(format.)f(Logs)i(the)f(record)595 1818 y(according)f(to)i(whatever)e(policy)h(is)g(configured)g(locally.) 595 1910 y(""")595 2001 y(while)g(1:)774 2092 y(chunk)g(=)h (self.connection.recv\(4\))774 2183 y(if)g(len\(chunk\))e(<)i(4:)954 2275 y(break)774 2366 y(slen)f(=)h(struct.unpack\(">L",)d(chunk\)[0]) 774 2457 y(chunk)i(=)h(self.connection.recv\(slen\))774 2549 y(while)f(len\(chunk\))f(<)i(slen:)954 2640 y(chunk)f(=)g(chunk)g (+)h(self.connection.recv\(slen)40 b(-)45 b(len\(chunk\)\))774 2731 y(obj)g(=)f(self.unPickle\(chunk\))774 2823 y(record)g(=)h (logging.makeLogRecord\(obj\))774 2914 y (self.handleLogRecord\(record\))416 3097 y(def)f(unPickle\(self,)e (data\):)595 3188 y(return)i(cPickle.loads\(data\))416 3371 y(def)g(handleLogRecord\(self,)d(record\):)595 3462 y(#)k(if)f(a)h(name)f(is)g(specified,)g(we)g(use)g(the)h(named)f (logger)f(rather)h(than)g(the)h(one)595 3553 y(#)g(implied)e(by)i(the)f (record.)595 3645 y(if)g(self.server.logname)e(is)j(not)f(None:)774 3736 y(name)g(=)h(self.server.logname)595 3827 y(else:)774 3919 y(name)f(=)h(record.name)595 4010 y(logger)f(=)g (logging.getLogger\(name\))595 4101 y(#)h(N.B.)f(EVERY)g(record)g(gets) g(logged.)f(This)h(is)h(because)f(Logger.handle)595 4193 y(#)h(is)f(normally)g(called)f(AFTER)h(logger-level)f(filtering.)g(If)i (you)f(want)595 4284 y(#)h(to)f(do)h(filtering,)e(do)h(it)h(at)f(the)g (client)g(end)h(to)f(save)g(wasting)595 4375 y(#)h(cycles)e(and)i (network)e(bandwidth!)595 4467 y(logger.handle\(record\))236 4649 y(class)h(LogRecordSocketReceiver\(SocketServer.Thr)o(eading)o (TCPSer)o(ver\):)416 4741 y("""simple)f(TCP)h(socket-based)f(logging)h (receiver)f(suitable)h(for)g(testing.)416 4832 y(""")416 5015 y(allow_reuse_address)d(=)k(1)416 5197 y(def)f(__init__\(self,)e (host='localhost',)998 5289 y (port=logging.handlers.DEFAULT_TCP_LOGGING)o(_PORT,)998 5380 y(handler=LogRecordStreamHandler\):)595 5471 y (SocketServer.ThreadingTCPServer.__init)o(__\(sel)o(f,)d(\(host,)44 b(port\),)g(handler\))595 5562 y(self.abort)f(=)i(0)595 5654 y(self.timeout)e(=)h(1)595 5745 y(self.logname)f(=)h(None)416 5928 y(def)g(serve_until_stopped\(self\):)595 6019 y(import)g(select) 595 6110 y(abort)g(=)h(0)595 6202 y(while)f(not)g(abort:)774 6293 y(rd,)h(wr,)f(ex)g(=)h(select.select\([self.socket.fileno\(\)],) 1985 6384 y([],)f([],)1985 6476 y(self.timeout\))774 6567 y(if)h(rd:)954 6658 y(self.handle_request\(\))774 6750 y(abort)f(=)h(self.abort)236 6932 y(def)g(main\(\):)416 7024 y(logging.basicConfig\()595 7115 y (format="\045\(relativeCreated\)5d)40 b(\045\(name\)-15s)j (\045\(levelname\)-8s)f(\045\(message\)s"\))416 7206 y(tcpserver)h(=)i(LogRecordSocketReceiver\(\))416 7298 y(print)f("About)f(to)i(start)f(TCP)g(server...")416 7389 y(tcpserver.serve_until_stopped\(\))236 7572 y(if)h(__name__)e(==) i("__main__":)416 7663 y(main\(\))p 0 5549 3901 4 v 0 5649 a FI(460)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 461 473 TeXDict begin 461 472 bop 0 83 a FN(First)24 b(run)e(the)h(serv)o(er)m (,)g(and)f(then)h(the)g(client.)34 b(On)23 b(the)g(client)g(side,)h (nothing)d(is)j(printed)e(on)h(the)g(console;)h(on)e(the)h(serv)o(er)g (side,)g(you)0 183 y(should)c(see)i(something)e(lik)o(e:)236 421 y FA(About)44 b(to)h(start)f(TCP)g(server...)371 512 y(59)g(root)538 b(INFO)223 b(Jackdaws)43 b(love)i(my)f(big)g (sphinx)g(of)h(quartz.)371 603 y(59)f(myapp.area1)223 b(DEBUG)178 b(Quick)44 b(zephyrs)g(blow,)g(vexing)f(daft)i(Jim.)371 695 y(69)f(myapp.area1)223 b(INFO)g(How)44 b(quickly)g(daft)g(jumping)g (zebras)g(vex.)371 786 y(69)g(myapp.area2)223 b(WARNING)88 b(Jail)44 b(zesty)g(vixen)g(who)g(grabbed)g(pay)g(from)h(quack.)371 877 y(69)f(myapp.area2)223 b(ERROR)178 b(The)44 b(five)g(boxing)g (wizards)g(jump)g(quickly.)0 1295 y Fv(14.5.5)101 b(Handler)29 b(Objects)0 1498 y FN(Handlers)20 b(ha)n(v)o(e)h(the)g(follo)n(wing)e (attrib)n(utes)i(and)g(methods.)27 b(Note)21 b(that)g FJ(Handler)f FN(is)i(ne)n(v)o(er)e(instantiated)g(directly;)h(this)h (class)g(acts)0 1598 y(as)g(a)g(base)g(for)f(more)g(useful)g (subclasses.)29 b(Ho)n(we)n(v)o(er)m(,)20 b(the)i FJ(__init__\(\))e FN(method)g(in)i(subclasses)g(needs)f(to)h(call)g FJ(Handler._-)0 1697 y(_init__\(\))p FN(.)0 1844 y FD(__init__)p FJ(\()p FK(le)o(vel=)p Fn(NOTSET)5 b FJ(\))208 1944 y FN(Initializes)25 b(the)h FJ(Handler)f FN(instance)g(by)g(setting)h(its)g(le)n(v)o(el,)h (setting)e(the)h(list)h(of)e(\002lters)i(to)e(the)h(empty)f(list)h(and) g(creating)e(a)208 2044 y(lock)19 b(\(using)h FJ(createLock\(\))p FN(\))e(for)h(serializing)h(access)h(to)f(an)g(I/O)h(mechanism.)0 2190 y FD(createLock)p FJ(\(\))208 2290 y FN(Initializes)f(a)i(thread)e (lock)g(which)g(can)h(be)g(used)g(to)g(serialize)g(access)g(to)g (underlying)d(I/O)k(functionality)c(which)j(may)f(not)h(be)208 2390 y(threadsafe.)0 2537 y FD(acquire)p FJ(\(\))208 2636 y FN(Acquires)e(the)h(thread)f(lock)h(created)g(with)g FJ(createLock\(\))p FN(.)0 2783 y FD(release)p FJ(\(\))208 2883 y FN(Releases)h(the)f(thread)f(lock)h(acquired)f(with)h FJ(acquire\(\))p FN(.)0 3030 y FD(setLevel)p FJ(\()p FK(lvl)p FJ(\))208 3129 y FN(Sets)f(the)f(threshold)f(for)h(this)g (handler)f(to)i FK(lvl)p FN(.)25 b(Logging)16 b(messages)i(which)g(are) g(less)i(se)n(v)o(ere)d(than)h FK(lvl)h FN(will)g(be)f(ignored.)23 b(When)208 3229 y(a)d(handler)f(is)i(created,)e(the)h(le)n(v)o(el)g(is) h(set)g(to)g FJ(NOTSET)e FN(\(which)h(causes)g(all)h(messages)f(to)h (be)f(processed\).)0 3376 y FD(setFormatter)p FJ(\()p FK(form)p FJ(\))208 3475 y FN(Sets)h(the)f FJ(Formatter)f FN(for)h(this)g(handler)f(to)h FK(form)p FN(.)0 3622 y FD(addFilter)p FJ(\()p FK(\002lt)q FJ(\))208 3722 y FN(Adds)g(the)g(speci\002ed)g(\002lter)g FK(\002lt)i FN(to)f(this)f(handler)-5 b(.)0 3869 y FD(removeFilter)p FJ(\()p FK(\002lt)q FJ(\))208 3968 y FN(Remo)o(v)o(es)19 b(the)h(speci\002ed)g(\002lter)h FK(\002lt)g FN(from)f(this)g(handler) -5 b(.)0 4115 y FD(filter)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 4215 y FN(Applies)20 b(this)g(handler')-5 b(s)19 b(\002lters)i(to)g(the)f(record)f(and)g(returns)h(a)g(true)g(v)n(alue)g (if)g(the)g(record)f(is)i(to)g(be)f(processed.)0 4362 y FD(flush)p FJ(\(\))208 4461 y FN(Ensure)25 b(all)h(logging)e(output)h (has)h(been)g(\003ushed.)41 b(This)26 b(v)o(ersion)f(does)h(nothing)e (and)i(is)g(intended)f(to)h(be)g(implemented)e(by)208 4561 y(subclasses.)0 4708 y FD(close)p FJ(\(\))208 4807 y FN(T)m(idy)i(up)g(an)o(y)f(resources)h(used)g(by)g(the)h(handler)-5 b(.)42 b(This)27 b(v)o(ersion)e(does)h(nothing)f(and)h(is)h(intended)e (to)i(be)f(implemented)f(by)208 4907 y(subclasses.)0 5054 y FD(handle)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 5154 y FN(Conditionally)14 b(emits)j(the)f(speci\002ed)g(logging)e (record,)i(depending)d(on)j(\002lters)h(which)e(may)h(ha)n(v)o(e)g (been)f(added)g(to)i(the)f(handler)-5 b(.)208 5253 y(Wraps)20 b(the)g(actual)g(emission)g(of)g(the)g(record)f(with)h (acquisition/release)f(of)h(the)g(I/O)h(thread)e(lock.)0 5400 y FD(handleError)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python)2103 b(461)p eop end %%Page: 462 474 TeXDict begin 462 473 bop 208 83 a FN(This)28 b(method)f(should)g(be)h (called)g(from)g(handlers)f(when)h(an)g(e)o(xception)e(is)j (encountered)d(during)h(an)h FJ(emit\(\))f FN(call.)50 b(By)208 183 y(def)o(ault)26 b(it)i(does)f(nothing,)g(which)g(means)g (that)g(e)o(xceptions)f(get)h(silently)h(ignored.)44 b(This)28 b(is)g(what)f(is)h(mostly)f(w)o(anted)g(for)208 282 y(a)j(logging)f(system)h(-)h(most)f(users)g(will)h(not)f(care)g (about)f(errors)h(in)g(the)h(logging)d(system,)33 b(the)o(y)c(are)h (more)g(interested)f(in)208 382 y(application)20 b(errors.)28 b(Y)-9 b(ou)21 b(could,)g(ho)n(we)n(v)o(er)m(,)f(replace)h(this)h(with) g(a)g(custom)f(handler)f(if)i(you)f(wish.)30 b(The)21 b(speci\002ed)g(record)g(is)208 482 y(the)f(one)f(which)h(w)o(as)h (being)e(processed)g(when)h(the)g(e)o(xception)f(occurred.)0 628 y FD(format)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 728 y FN(Do)h(formatting)e(for)i(a)g(record)f(-)h(if)h(a)f(formatter)f (is)i(set,)g(use)f(it.)26 b(Otherwise,)20 b(use)g(the)g(def)o(ault)g (formatter)f(for)g(the)h(module.)0 875 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 975 y FN(Do)f(whate)n(v)o(er)f(it)i(tak)o (es)g(to)g(actually)e(log)i(the)f(speci\002ed)g(logging)f(record.)23 b(This)d(v)o(ersion)e(is)i(intended)e(to)i(be)f(implemented)f(by)208 1074 y(subclasses)i(and)g(so)g(raises)h(a)g FJ(NotImplementedError)p FN(.)0 1342 y FI(StreamHandler)0 1545 y FN(The)36 b FJ(StreamHandler)e FN(class,)41 b(located)36 b(in)h(the)f(core)g FJ(logging)f FN(package,)k(sends)d(logging)f(output)g(to)h(streams)h(such)f(as)0 1645 y FK(sys.stdout)q FN(,)24 b FK(sys.stderr)i FN(or)d(an)o(y)g (\002le-lik)o(e)g(object)f(\(or)m(,)h(more)g(precisely)-5 b(,)22 b(an)o(y)h(object)f(which)h(supports)f FJ(write\(\))h FN(and)f FJ(flush\(\))0 1745 y FN(methods\).)0 1891 y FL(class)f FD(StreamHandler)p FJ(\()p FC([)p FK(strm)12 b FC(])p FJ(\))208 1991 y FN(Returns)21 b(a)h(ne)n(w)f(instance)g(of)g (the)h FJ(StreamHandler)d FN(class.)30 b(If)21 b FK(strm)i FN(is)g(speci\002ed,)e(the)g(instance)g(will)i(use)e(it)h(for)f (logging)208 2091 y(output;)e(otherwise,)g FK(sys.stderr)k FN(will)e(be)f(used.)0 2238 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 2337 y FN(If)g(a)g(formatter)f(is)i(speci\002ed,)e(it)i(is)g (used)f(to)g(format)f(the)h(record.)k(The)c(record)e(is)j(then)f (written)g(to)g(the)g(stream)g(with)h(a)f(trailing)208 2437 y(ne)n(wline.)29 b(If)22 b(e)o(xception)e(information)g(is)j (present,)e(it)i(is)g(formatted)d(using)i FJ (traceback.print_exception\(\))17 b FN(and)208 2536 y(appended)g(to)k (the)f(stream.)0 2683 y FD(flush)p FJ(\(\))208 2783 y FN(Flushes)15 b(the)h(stream)f(by)g(calling)g(its)i FJ(flush\(\))d FN(method.)22 b(Note)16 b(that)f(the)h FJ(close\(\))e FN(method)g(is)j(inherited)d(from)g FJ(Handler)208 2883 y FN(and)19 b(so)i(does)f(nothing,)e(so)i(an)h(e)o(xplicit)e FJ(flush\(\))h FN(call)g(may)g(be)g(needed)f(at)i(times.)0 3151 y FI(FileHandler)0 3354 y FN(The)h FJ(FileHandler)g FN(class,)i(located)e(in)h(the)g(core)f FJ(logging)g FN(package,)g(sends)h(logging)e(output)h(to)h(a)g(disk)g(\002le.)33 b(It)23 b(inherits)g(the)0 3453 y(output)c(functionality)f(from)h FJ(StreamHandler)p FN(.)0 3600 y FL(class)i FD(FileHandler)p FJ(\()p FK(\002lename)p FC([)p FK(,)16 b(mode)c FC(])p FJ(\))208 3700 y FN(Returns)26 b(a)h(ne)n(w)f(instance)g(of)g(the)g FJ(FileHandler)f FN(class.)44 b(The)26 b(speci\002ed)h(\002le)g(is)g (opened)e(and)g(used)h(as)i(the)e(stream)g(for)208 3800 y(logging.)d(If)d FK(mode)f FN(is)j(not)d(speci\002ed,)h FJ('a')g FN(is)h(used.)k(By)c(def)o(ault,)e(the)h(\002le)h(gro)n(ws)f (inde\002nitely)-5 b(.)0 3946 y FD(close)p FJ(\(\))208 4046 y FN(Closes)21 b(the)f(\002le.)0 4193 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 4293 y FN(Outputs)f(the)h(record)f (to)i(the)f(\002le.)0 4561 y FI(RotatingFileHandler)0 4764 y FN(The)25 b FJ(RotatingFileHandler)e FN(class,)k(located)e(in)h (the)g FJ(logging.handlers)d FN(module,)i(supports)g(rotation)f(of)h (disk)h(log)0 4863 y(\002les.)0 5010 y FL(class)21 b FD(RotatingFileHandler)p FJ(\()p FK(\002lename)p FC([)p FK(,)15 b(mode)p FC([)p FK(,)k(maxBytes)p FC([)p FK(,)g(bac)n(kupCount) 13 b FC(])f(])g(])p FJ(\))208 5110 y FN(Returns)24 b(a)i(ne)n(w)e (instance)h(of)f(the)h FJ(RotatingFileHandler)d FN(class.)40 b(The)25 b(speci\002ed)f(\002le)i(is)g(opened)d(and)h(used)h(as)h(the) 208 5209 y(stream)20 b(for)f(logging.)k(If)d FK(mode)g FN(is)h(not)f(speci\002ed,)g FJ('a')g FN(is)h(used.)k(By)20 b(def)o(ault,)g(the)g(\002le)h(gro)n(ws)e(inde\002nitely)-5 b(.)208 5342 y(Y)c(ou)22 b(can)h(use)g(the)g FK(maxBytes)g FN(and)f FK(bac)n(kupCount)g FN(v)n(alues)h(to)g(allo)n(w)g(the)g (\002le)g(to)g FK(r)l(ollo)o(ver)h FN(at)f(a)h(predetermined)c(size.)34 b(When)p 0 5549 3901 4 v 0 5649 a FI(462)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 463 475 TeXDict begin 463 474 bop 208 83 a FN(the)22 b(size)i(is)g(about)e(to)h (be)f(e)o(xceeded,)g(the)h(\002le)g(is)h(closed)e(and)h(a)g(ne)n(w)g (\002le)g(is)h(silently)f(opened)e(for)h(output.)32 b(Rollo)o(v)o(er)21 b(occurs)208 183 y(whene)n(v)o(er)c(the)i(current)f(log)g(\002le)i(is)g (nearly)e FK(maxBytes)h FN(in)g(length;)g(if)g FK(maxBytes)g FN(is)h(zero,)f(rollo)o(v)o(er)e(ne)n(v)o(er)g(occurs.)24 b(If)19 b FK(bac)n(kup-)208 282 y(Count)h FN(is)g(non-zero,)d(the)i (system)h(will)g(sa)n(v)o(e)f(old)g(log)g(\002les)h(by)f(appending)d (the)k(e)o(xtensions)e(\224.1\224,)h(\224.2\224)f(etc.,)i(to)f(the)g (\002lename.)208 382 y(F)o(or)j(e)o(xample,)h(with)g(a)h FK(bac)n(kupCount)e FN(of)h(5)g(and)g(a)g(base)h(\002le)g(name)e(of)h (`)p FO(app)m(.log)p FN(',)e(you)h(w)o(ould)h(get)g(`)p FO(app)m(.log)p FN(',)e(`)p FO(app)m(.log.1)p FN(',)208 482 y(`)p FO(app)m(.log.2)p FN(',)f(up)j(to)g(`)p FO(app)m(.log.5)p FN('.)31 b(The)23 b(\002le)h(being)e(written)h(to)g(is)i(al)o(w)o(ays)e (`)p FO(app)m(.log)p FN('.)32 b(When)23 b(this)h(\002le)g(is)g (\002lled,)g(it)g(is)g(closed)208 581 y(and)c(renamed)g(to)i(`)p FO(app)m(.log.1)p FN(',)c(and)j(if)g(\002les)i(`)p FO(app)m(.log.1)p FN(',)18 b(`)p FO(app)m(.log.2)p FN(',)g(etc.)28 b(e)o(xist,)22 b(then)f(the)o(y)g(are)g(renamed)f(to)h(`)p FO(app)m(.log.2)p FN(',)208 681 y(`)p FO(app)m(.log.3)p FN(')16 b(etc.)26 b(respecti)n(v)o(ely)-5 b(.)0 828 y FD(doRollover)p FJ(\(\))208 927 y FN(Does)20 b(a)h(rollo)o(v)o(er)m(,)c(as)k(described)e(abo)o(v)o (e.)0 1074 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 1174 y FN(Outputs)g(the)h(record)f(to)i(the)f(\002le,)g(catering)g(for) f(rollo)o(v)o(er)f(as)j(described)e(pre)n(viously)-5 b(.)0 1442 y FI(TimedRotatingFileHandler)0 1645 y FN(The)30 b FJ(TimedRotatingFileHandler)c FN(class,)33 b(located)d(in)g(the)g FJ(logging.handlers)e FN(module,)j(supports)e(rotation)g(of)0 1745 y(disk)20 b(log)g(\002les)h(at)g(certain)f(timed)f(interv)n(als.)0 1891 y FL(class)i FD(TimedRotatingFileHandler)p FJ(\()p FK(\002lename)14 b FC([)p FK(,when)20 b FC([)p FK(,interval)f FC([)p FK(,bac)n(kupCount)13 b FC(])f(])g(])p FJ(\))208 1991 y FN(Returns)23 b(a)g(ne)n(w)g(instance)g(of)g(the)g FJ(TimedRotatingFileHandler)c FN(class.)35 b(The)23 b(speci\002ed)g (\002le)h(is)g(opened)d(and)i(used)208 2091 y(as)e(the)g(stream)f(for)g (logging.)25 b(On)c(rotating)e(it)j(also)f(sets)g(the)g(\002lename)f (suf)n(\002x.)26 b(Rotating)20 b(happens)g(based)g(on)g(the)h(product)e (of)208 2190 y FK(when)h FN(and)f FK(interval)p FN(.)208 2323 y(Y)-9 b(ou)22 b(can)i(use)f(the)h FK(when)f FN(to)h(specify)f (the)g(type)g(of)g FK(interval)p FN(.)35 b(The)23 b(list)i(of)e (possible)g(v)n(alues)g(is,)i(note)e(that)h(the)o(y)f(are)g(not)g(case) 208 2423 y(sensiti)n(v)o(e:)1470 2535 y FL(V)-8 b(alue)p 1818 2565 4 100 v 199 w(T)i(ype)21 b(of)f(inter)o(v)o(al)p 1420 2568 1268 4 v 1470 2638 a FN(S)p 1818 2668 4 100 v 353 w(Seconds)1470 2738 y(M)p 1818 2768 V 325 w(Minutes)1470 2837 y(H)p 1818 2867 V 339 w(Hours)1470 2937 y(D)p 1818 2967 V 339 w(Days)1470 3037 y(W)p 1818 3067 V 321 w(W)-7 b(eek)21 b(day)f(\(0=Monday\))1470 3136 y(midnight)p 1818 3166 V 97 w(Roll)h(o)o(v)o(er)e(at)h(midnight)208 3265 y(If)26 b FK(bac)n(kupCount)g FN(is)i(non-zero,)e(the)h(system)g (will)h(sa)n(v)o(e)f(old)f(log)h(\002les)h(by)e(appending)f(e)o (xtensions)g(to)i(the)g(\002lename.)45 b(The)208 3364 y(e)o(xtensions)29 b(are)h(date-and-time)e(based,)k(using)e(the)g (strftime)g(format)f FJ(\045Y-\045m-\045d_\045H-\045M-\045S)f FN(or)i(a)h(leading)e(portion)208 3464 y(thereof,)i(depending)c(on)j (the)g(rollo)o(v)o(er)e(interv)n(al.)54 b(At)31 b(most)f FK(bac)n(kupCount)f FN(\002les)i(will)g(be)f(k)o(ept,)i(and)e(if)g (more)f(w)o(ould)h(be)208 3563 y(created)19 b(when)h(rollo)o(v)o(er)e (occurs,)h(the)h(oldest)g(one)g(is)h(deleted.)0 3710 y FD(doRollover)p FJ(\(\))208 3810 y FN(Does)f(a)h(rollo)o(v)o(er)m(,)c (as)k(described)e(abo)o(v)o(e.)0 3957 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 4056 y FN(Outputs)g(the)h(record)f(to)i (the)f(\002le,)g(catering)g(for)f(rollo)o(v)o(er)f(as)j(described)e (abo)o(v)o(e.)0 4325 y FI(Soc)n(k)n(etHandler)0 4528 y FN(The)33 b FJ(SocketHandler)e FN(class,)37 b(located)c(in)g(the)g FJ(logging.handlers)e FN(module,)k(sends)e(logging)f(output)g(to)h(a)h (netw)o(ork)0 4627 y(sock)o(et.)25 b(The)20 b(base)g(class)h(uses)g(a)f (TCP)h(sock)o(et.)0 4774 y FL(class)g FD(SocketHandler)p FJ(\()p FK(host,)c(port)q FJ(\))208 4874 y FN(Returns)i(a)h(ne)n(w)g (instance)f(of)g(the)h FJ(SocketHandler)e FN(class)i(intended)e(to)i (communicate)e(with)i(a)g(remote)e(machine)h(whose)208 4973 y(address)g(is)i(gi)n(v)o(en)e(by)h FK(host)i FN(and)d FK(port)q FN(.)0 5120 y FD(close)p FJ(\(\))208 5220 y FN(Closes)i(the)f(sock)o(et.)0 5367 y FD(handleError)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python)2103 b(463)p eop end %%Page: 464 476 TeXDict begin 464 475 bop 0 83 a FD(emit)p FJ(\(\))208 183 y FN(Pickles)27 b(the)g(record')-5 b(s)26 b(attrib)n(ute)h (dictionary)e(and)h(writes)i(it)g(to)f(the)g(sock)o(et)g(in)g(binary)f (format.)44 b(If)27 b(there)g(is)h(an)e(error)g(with)208 282 y(the)f(sock)o(et,)i(silently)f(drops)f(the)g(pack)o(et.)41 b(If)26 b(the)g(connection)d(w)o(as)k(pre)n(viously)d(lost,)j (re-establishes)e(the)h(connection.)39 b(T)-7 b(o)208 382 y(unpickle)18 b(the)i(record)f(at)i(the)f(recei)n(ving)f(end)g (into)h(a)h FJ(LogRecord)p FN(,)e(use)h(the)g FJ(makeLogRecord\(\))e FN(function.)0 529 y FD(handleError)p FJ(\(\))208 628 y FN(Handles)24 b(an)g(error)g(which)g(has)h(occurred)e(during)g FJ(emit\(\))p FN(.)38 b(The)24 b(most)h(lik)o(ely)f(cause)h(is)g(a)g (lost)h(connection.)36 b(Closes)26 b(the)208 728 y(sock)o(et)20 b(so)g(that)g(we)h(can)f(retry)f(on)h(the)g(ne)o(xt)g(e)n(v)o(ent.)0 875 y FD(makeSocket)p FJ(\(\))208 975 y FN(This)26 b(is)h(a)f(f)o (actory)f(method)g(which)h(allo)n(ws)g(subclasses)g(to)h(de\002ne)e (the)h(precise)g(type)g(of)f(sock)o(et)h(the)o(y)g(w)o(ant.)43 b(The)25 b(def)o(ault)208 1074 y(implementation)18 b(creates)i(a)g(TCP) h(sock)o(et)f(\()p FJ(socket.SOCK_STREAM)p FN(\).)0 1221 y FD(makePickle)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 1321 y FN(Pickles)15 b(the)h(record')-5 b(s)14 b(attrib)n(ute)h (dictionary)e(in)i(binary)f(format)h(with)g(a)h(length)e(pre\002x,)h (and)g(returns)f(it)i(ready)f(for)f(transmission)208 1420 y(across)20 b(the)g(sock)o(et.)0 1567 y FD(send)p FJ(\()p FK(pac)n(k)o(et)q FJ(\))208 1667 y FN(Send)k(a)h(pickled)f (string)g FK(pac)n(k)o(et)i FN(to)f(the)g(sock)o(et.)39 b(This)25 b(function)e(allo)n(ws)i(for)f(partial)h(sends)f(which)h(can) f(happen)f(when)i(the)208 1766 y(netw)o(ork)19 b(is)i(b)n(usy)-5 b(.)0 2035 y FI(Datag)o(r)o(amHandler)0 2238 y FN(The)21 b FJ(DatagramHandler)f FN(class,)j(located)e(in)h(the)g FJ(logging.handlers)d FN(module,)h(inherits)i(from)f FJ(SocketHandler)e FN(to)0 2337 y(support)g(sending)g(logging)f (messages)j(o)o(v)o(er)d(UDP)j(sock)o(ets.)0 2484 y FL(class)g FD(DatagramHandler)p FJ(\()p FK(host,)c(port)q FJ(\))208 2584 y FN(Returns)29 b(a)g(ne)n(w)g(instance)g(of)g(the)g FJ(DatagramHandler)e FN(class)j(intended)d(to)j(communicate)d(with)i(a) g(remote)g(machine)208 2683 y(whose)19 b(address)h(is)h(gi)n(v)o(en)e (by)h FK(host)i FN(and)d FK(port)q FN(.)0 2830 y FD(emit)p FJ(\(\))208 2930 y FN(Pickles)27 b(the)g(record')-5 b(s)26 b(attrib)n(ute)h(dictionary)e(and)h(writes)i(it)g(to)f(the)g(sock)o(et) g(in)g(binary)f(format.)44 b(If)27 b(there)g(is)h(an)e(error)g(with)208 3029 y(the)e(sock)o(et,)i(silently)f(drops)e(the)i(pack)o(et.)38 b(T)-7 b(o)25 b(unpickle)e(the)i(record)e(at)i(the)g(recei)n(ving)e (end)h(into)h(a)g FJ(LogRecord)p FN(,)g(use)g(the)208 3129 y FJ(makeLogRecord\(\))18 b FN(function.)0 3276 y FD(makeSocket)p FJ(\(\))208 3376 y FN(The)d(f)o(actory)f(method)g(of) h FJ(SocketHandler)f FN(is)i(here)f(o)o(v)o(erridden)d(to)k(create)f(a) h(UDP)g(sock)o(et)f(\()p FJ(socket.SOCK_DGRAM)p FN(\).)0 3522 y FD(send)p FJ(\()p FK(s)p FJ(\))208 3622 y FN(Send)k(a)i(pickled) e(string)h(to)g(a)h(sock)o(et.)0 3890 y FI(SysLogHandler)0 4093 y FN(The)e FJ(SysLogHandler)f FN(class,)i(located)f(in)g(the)h FJ(logging.handlers)d FN(module,)h(supports)g(sending)g(logging)g (messages)i(to)f(a)0 4193 y(remote)g(or)h(local)i(U)t FH(N)t(I)t(X)i FN(syslog.)0 4340 y FL(class)d FD(SysLogHandler)p FJ(\()p FC([)p FK(addr)m(ess)p FC([)p FK(,)c(facility)12 b FC(])g(])p FJ(\))208 4439 y FN(Returns)30 b(a)i(ne)n(w)f(instance)f (of)h(the)g FJ(SysLogHandler)e FN(class)j(intended)d(to)i(communicate)e (with)i(a)h(remote)g(U)t FH(N)t(I)t(X)i FN(ma-)208 4539 y(chine)c(whose)g(address)g(is)i(gi)n(v)o(en)e(by)g FK(addr)m(ess)g FN(in)h(the)g(form)f(of)g(a)h FJ(\()p FK(host)q FJ(,)50 b FK(port)q FJ(\))31 b FN(tuple.)56 b(If)31 b FK(addr)m(ess)f FN(is)i(not)e(speci\002ed,)208 4639 y FJ(\('localhost',)47 b(514\))25 b FN(is)i(used.)41 b(The)25 b(address)g(is)h(used)g(to)f (open)g(a)h(UDP)g(sock)o(et.)41 b(An)25 b(alternati)n(v)o(e)g(to)g(pro) o(viding)e(a)208 4738 y FJ(\()p FK(host)q FJ(,)49 b FK(port)q FJ(\))27 b FN(tuple)f(is)h(pro)o(viding)d(an)i(address)g(as)i(a)f (string,)g(for)f(e)o(xample)f(\224/de)n(v/log\224.)42 b(In)27 b(this)g(case,)h(a)f(Unix)f(domain)208 4838 y(sock)o(et)20 b(is)h(used)f(to)g(send)g(the)g(message)g(to)h(the)f(syslog.)k(If)c FK(facility)h FN(is)g(not)f(speci\002ed,)f FJ(LOG_USER)h FN(is)h(used.)0 4985 y FD(close)p FJ(\(\))208 5084 y FN(Closes)g(the)f(sock)o(et)g(to)g(the)h(remote)e(host.)0 5231 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 5331 y FN(The)j(record)f(is)i(formatted,)e(and)h(then)g(sent)g(to)h (the)f(syslog)g(serv)o(er)-5 b(.)31 b(If)23 b(e)o(xception)d (information)g(is)j(present,)f(it)h(is)h FK(not)e FN(sent)g(to)p 0 5549 3901 4 v 0 5649 a FI(464)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 465 477 TeXDict begin 465 476 bop 208 83 a FN(the)20 b(serv)o(er)-5 b(.)0 230 y FD(encodePriority)p FJ(\()p FK(facility)g(,)18 b(priority)p FJ(\))208 330 y FN(Encodes)d(the)h(f)o(acility)h(and)e (priority)g(into)i(an)f(inte)o(ger)-5 b(.)23 b(Y)-9 b(ou)16 b(can)g(pass)h(in)f(strings)h(or)f(inte)o(gers)g(-)g(if)h(strings)f (are)h(passed,)f(internal)208 429 y(mapping)i(dictionaries)h(are)h (used)g(to)g(con)m(v)o(ert)f(them)g(to)i(inte)o(gers.)0 697 y FI(NTEv)n(entLogHandler)0 900 y FN(The)27 b FJ(NTEventLogHandler) e FN(class,)31 b(located)c(in)h(the)f FJ(logging.handlers)f FN(module,)h(supports)g(sending)g(logging)f(mes-)0 1000 y(sages)31 b(to)f(a)h(local)f(W)m(indo)n(ws)g(NT)-6 b(,)30 b(W)m(indo)n(ws)g(2000)e(or)i(W)m(indo)n(ws)g(XP)h(e)n(v)o(ent)e(log.) 55 b(Before)30 b(you)f(can)h(use)h(it,)i(you)d(need)f(Mark)0 1100 y(Hammond')-5 b(s)19 b(W)m(in32)g(e)o(xtensions)g(for)h(Python)f (installed.)0 1246 y FL(class)i FD(NTEventLogHandler)p FJ(\()p FK(appname)p FC([)p FK(,)14 b(dllname)p FC([)p FK(,)19 b(lo)o(gtype)12 b FC(])g(])p FJ(\))208 1346 y FN(Returns)25 b(a)h(ne)n(w)g(instance)f(of)h(the)f FJ (NTEventLogHandler)f FN(class.)42 b(The)25 b FK(appname)f FN(is)j(used)e(to)h(de\002ne)f(the)h(application)208 1446 y(name)17 b(as)h(it)g(appears)f(in)h(the)f(e)n(v)o(ent)g(log.)24 b(An)17 b(appropriate)e(re)o(gistry)i(entry)g(is)h(created)f(using)g (this)h(name.)24 b(The)17 b FK(dllname)g FN(should)208 1545 y(gi)n(v)o(e)22 b(the)i(fully)f(quali\002ed)g(pathname)f(of)h(a)h (.dll)g(or)f(.e)o(x)o(e)g(which)g(contains)g(message)g(de\002nitions)g (to)h(hold)f(in)g(the)h(log)f(\(if)h(not)208 1645 y(speci\002ed,)k FJ('win32service.pyd')d FN(is)k(used)e(-)h(this)g(is)g(installed)g (with)f(the)h(W)m(in32)f(e)o(xtensions)f(and)h(contains)g(some)208 1745 y(basic)f(placeholder)f(message)h(de\002nitions.)44 b(Note)26 b(that)h(use)g(of)f(these)h(placeholders)e(will)i(mak)o(e)f (your)g(e)n(v)o(ent)g(logs)g(big,)i(as)208 1844 y(the)d(entire)g (message)g(source)g(is)h(held)f(in)h(the)f(log.)40 b(If)26 b(you)e(w)o(ant)i(slimmer)f(logs,)h(you)f(ha)n(v)o(e)f(to)i(pass)g(in)f (the)h(name)f(of)g(your)208 1944 y(o)n(wn)20 b(.dll)g(or)h(.e)o(x)o(e)f (which)g(contains)g(the)h(message)f(de\002nitions)g(you)g(w)o(ant)h(to) g(use)g(in)f(the)h(e)n(v)o(ent)f(log\).)26 b(The)20 b FK(lo)o(gtype)g FN(is)i(one)e(of)208 2043 y FJ('Application')p FN(,)e FJ('System')h FN(or)h FJ('Security')p FN(,)e(and)i(def)o(aults)g (to)g FJ('Application')p FN(.)0 2190 y FD(close)p FJ(\(\))208 2290 y FN(At)h(this)g(point,)f(you)g(can)h(remo)o(v)o(e)e(the)i (application)e(name)h(from)g(the)h(re)o(gistry)f(as)h(a)h(source)e(of)g (e)n(v)o(ent)g(log)h(entries.)27 b(Ho)n(we)n(v)o(er)m(,)208 2390 y(if)18 b(you)f(do)g(this,)i(you)e(will)i(not)f(be)g(able)f(to)i (see)f(the)g(e)n(v)o(ents)g(as)g(you)f(intended)g(in)h(the)g(Ev)o(ent)f (Log)g(V)-5 b(ie)n(wer)18 b(-)g(it)h(needs)f(to)g(be)g(able)208 2489 y(to)i(access)h(the)f(re)o(gistry)f(to)h(get)h(the)f(.dll)g(name.) k(The)c(current)f(v)o(ersion)g(does)h(not)g(do)g(this)g(\(in)g(f)o(act) h(it)g(doesn')o(t)d(do)i(an)o(ything\).)0 2636 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 2736 y FN(Determines)f(the)h (message)g(ID,)g(e)n(v)o(ent)g(cate)o(gory)e(and)i(e)n(v)o(ent)f(type,) g(and)h(then)g(logs)g(the)g(message)g(in)g(the)h(NT)f(e)n(v)o(ent)f (log.)0 2883 y FD(getEventCategory)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 2982 y FN(Returns)e(the)h(e)n(v)o(ent)f(cate)o(gory)g(for)g (the)h(record.)23 b(Ov)o(erride)16 b(this)j(if)f(you)f(w)o(ant)h(to)g (specify)f(your)g(o)n(wn)h(cate)o(gories.)23 b(This)18 b(v)o(ersion)208 3082 y(returns)h(0.)0 3229 y FD(getEventType)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 3328 y FN(Returns)i(the)h(e)n(v)o (ent)e(type)h(for)g(the)h(record.)28 b(Ov)o(erride)20 b(this)i(if)g(you)f(w)o(ant)g(to)h(specify)f(your)g(o)n(wn)g(types.)29 b(This)21 b(v)o(ersion)g(does)g(a)208 3428 y(mapping)c(using)i(the)h (handler')-5 b(s)18 b(typemap)g(attrib)n(ute,)h(which)g(is)h(set)g(up)f (in)h FJ(__init__\(\))e FN(to)i(a)g(dictionary)d(which)i(contains)208 3528 y(mappings)k(for)h FJ(DEBUG)p FN(,)g FJ(INFO)p FN(,)g FJ(WARNING)p FN(,)g FJ(ERROR)g FN(and)h FJ(CRITICAL)p FN(.)e(If)i(you)f(are)g(using)h(your)e(o)n(wn)h(le)n(v)o(els,)i(you)e (will)208 3627 y(either)19 b(need)h(to)g(o)o(v)o(erride)e(this)j (method)e(or)h(place)f(a)i(suitable)f(dictionary)f(in)h(the)g(handler') -5 b(s)19 b FK(typemap)g FN(attrib)n(ute.)0 3774 y FD(getMessageID)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 3874 y FN(Returns)e(the)h(message)f (ID)h(for)f(the)h(record.)k(If)c(you)f(are)g(using)g(your)g(o)n(wn)g (messages,)h(you)f(could)f(do)i(this)g(by)f(ha)n(ving)g(the)g FK(msg)208 3973 y FN(passed)i(to)h(the)g(logger)e(being)h(an)g(ID)h (rather)f(than)g(a)h(format)f(string.)24 b(Then,)19 b(in)g(here,)g(you) g(could)g(use)h(a)g(dictionary)e(lookup)f(to)208 4073 y(get)j(the)g(message)g(ID.)g(This)g(v)o(ersion)f(returns)h(1,)g(which) f(is)j(the)e(base)g(message)g(ID)g(in)h(`)p FO(win32ser)r(vice)o(.p)n (yd)p FN('.)0 4341 y FI(SMTPHandler)0 4544 y FN(The)i FJ(SMTPHandler)g FN(class,)i(located)e(in)h(the)g FJ(logging.handlers)d FN(module,)i(supports)g(sending)g(logging)f(messages)i(to)g(an)0 4644 y(email)c(address)g(via)g(SMTP)-9 b(.)0 4791 y FL(class)21 b FD(SMTPHandler)p FJ(\()p FK(mailhost,)c(fr)l(omaddr)-9 b(,)19 b(toaddr)o(s,)h(subject)q FJ(\))208 4890 y FN(Returns)h(a)h(ne)n (w)g(instance)f(of)h(the)f FJ(SMTPHandler)f FN(class.)31 b(The)21 b(instance)h(is)g(initialized)g(with)f(the)h(from)f(and)g(to)h (addresses)208 4990 y(and)d(subject)h(line)h(of)f(the)g(email.)25 b(The)20 b FK(toaddr)o(s)g FN(should)f(be)i(a)f(list)i(of)e(strings.)25 b(T)-7 b(o)21 b(specify)e(a)i(non-standard)c(SMTP)k(port,)e(use)208 5090 y(the)h(\(host,)f(port\))g(tuple)h(format)f(for)h(the)g FK(mailhost)h FN(ar)o(gument.)i(If)d(you)f(use)i(a)f(string,)g(the)g (standard)f(SMTP)i(port)e(is)i(used.)0 5236 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 5336 y FN(F)o(ormats)e(the)h (record)f(and)h(sends)g(it)h(to)f(the)h(speci\002ed)e(addressees.)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python)2103 b(465)p eop end %%Page: 466 478 TeXDict begin 466 477 bop 0 83 a FD(getSubject)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 183 y FN(If)20 b(you)f(w)o(ant)h(to)h (specify)e(a)i(subject)f(line)g(which)g(is)h(record-dependent,)15 b(o)o(v)o(erride)j(this)j(method.)0 451 y FI(Memor)r(yHandler)0 654 y FN(The)d FJ(MemoryHandler)f FN(class,)j(located)e(in)g(the)h FJ(logging.handlers)d FN(module,)i(supports)f(b)n(uf)n(fering)g(of)h (logging)f(records)g(in)0 753 y(memory)-5 b(,)19 b(periodically)g (\003ushing)h(them)h(to)g(a)g FK(tar)m(g)o(et)g FN(handler)-5 b(.)26 b(Flushing)20 b(occurs)g(whene)n(v)o(er)f(the)i(b)n(uf)n(fer)f (is)i(full,)f(or)f(when)h(an)f(e)n(v)o(ent)0 853 y(of)g(a)h(certain)e (se)n(v)o(erity)g(or)h(greater)g(is)h(seen.)0 1000 y FJ(MemoryHandler)34 b FN(is)j(a)g(subclass)g(of)e(the)i(more)e(general) g FJ(BufferingHandler)p FN(,)j(which)d(is)i(an)g(abstract)f(class.)73 b(This)0 1100 y(b)n(uf)n(fers)35 b(logging)f(records)h(in)i(memory)-5 b(.)70 b(Whene)n(v)o(er)35 b(each)h(record)e(is)j(added)e(to)i(the)f(b) n(uf)n(fer)m(,)i(a)e(check)g(is)h(made)e(by)h(calling)0 1199 y FJ(shouldFlush\(\))26 b FN(to)h(see)h(if)g(the)f(b)n(uf)n(fer)f (should)h(be)g(\003ushed.)46 b(If)27 b(it)h(should,)g(then)f FJ(flush\(\))g FN(is)h(e)o(xpected)e(to)h(do)g(the)h(need-)0 1299 y(ful.)0 1446 y FL(class)21 b FD(BufferingHandler)p FJ(\()p FK(capacity)p FJ(\))208 1545 y FN(Initializes)f(the)g(handler)f (with)h(a)h(b)n(uf)n(fer)e(of)g(the)i(speci\002ed)f(capacity)-5 b(.)0 1692 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 1792 y FN(Appends)18 b(the)j(record)d(to)j(the)f(b)n(uf)n(fer)-5 b(.)24 b(If)c FJ(shouldFlush\(\))e FN(returns)i(true,)f(calls)i FJ(flush\(\))f FN(to)g(process)g(the)g(b)n(uf)n(fer)-5 b(.)0 1939 y FD(flush)p FJ(\(\))208 2038 y FN(Y)c(ou)19 b(can)h(o)o(v)o(erride)e(this)j(to)f(implement)f(custom)h(\003ushing)f (beha)n(vior)-5 b(.)24 b(This)c(v)o(ersion)f(just)i(zaps)f(the)g(b)n (uf)n(fer)f(to)h(empty)-5 b(.)0 2185 y FD(shouldFlush)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 2285 y FN(Returns)32 b(true)f(if)i(the)f(b)n(uf)n(fer)f(is)i(up)e(to)i(capacity)-5 b(.)59 b(This)32 b(method)f(can)h(be)g(o)o(v)o(erridden)d(to)j (implement)f(custom)g(\003ushing)208 2384 y(strate)o(gies.)0 2531 y FL(class)21 b FD(MemoryHandler)p FJ(\()p FK(capacity)p FC([)p FK(,)16 b(\003ushLe)o(vel)j FC([)p FK(,)h(tar)m(g)o(et)13 b FC(])f(])p FJ(\))208 2631 y FN(Returns)17 b(a)h(ne)n(w)g(instance)f (of)g(the)h FJ(MemoryHandler)e FN(class.)25 b(The)17 b(instance)g(is)i(initialized)e(with)h(a)g(b)n(uf)n(fer)e(size)j(of)e FK(capacity)p FN(.)208 2731 y(If)30 b FK(\003ushLe)o(vel)f FN(is)j(not)e(speci\002ed,)i FJ(ERROR)f FN(is)g(used.)55 b(If)31 b(no)f FK(tar)m(g)o(et)i FN(is)f(speci\002ed,)i(the)d(tar)o (get)g(will)h(need)f(to)g(be)h(set)g(using)208 2830 y FJ(setTarget\(\))18 b FN(before)h(this)i(handler)e(does)g(an)o(ything)g (useful.)0 2977 y FD(close)p FJ(\(\))208 3077 y FN(Calls)i FJ(flush\(\))p FN(,)e(sets)i(the)g(tar)o(get)e(to)h FJ(None)g FN(and)g(clears)g(the)h(b)n(uf)n(fer)-5 b(.)0 3224 y FD(flush)p FJ(\(\))208 3323 y FN(F)o(or)16 b(a)i FJ(MemoryHandler)p FN(,)e(\003ushing)g(means)h(just)h(sending)e(the)h(b)n(uf)n(fered)f (records)g(to)h(the)h(tar)o(get,)e(if)i(there)f(is)h(one.)23 b(Ov)o(erride)208 3423 y(if)d(you)f(w)o(ant)i(dif)n(ferent)d(beha)n (vior)-5 b(.)0 3570 y FD(setTarget)p FJ(\()p FK(tar)m(g)o(et)q FJ(\))208 3669 y FN(Sets)21 b(the)f(tar)o(get)f(handler)g(for)h(this)g (handler)-5 b(.)0 3816 y FD(shouldFlush)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 3916 y FN(Checks)20 b(for)f(b)n(uf)n(fer)g(full)h(or)g(a)h (record)e(at)h(the)g FK(\003ushLe)o(vel)g FN(or)g(higher)-5 b(.)0 4184 y FI(HTTPHandler)0 4387 y FN(The)27 b FJ(HTTPHandler)e FN(class,)k(located)d(in)h(the)g FJ(logging.handlers)e FN(module,)i(supports)e(sending)h(logging)f(messages)i(to)g(a)0 4487 y(W)-7 b(eb)21 b(serv)o(er)m(,)e(using)g(either)h(`)p FJ(GET)p FN(')g(or)f(`)p FJ(POST)p FN(')h(semantics.)0 4634 y FL(class)h FD(HTTPHandler)p FJ(\()p FK(host,)c(url)p FC([)p FK(,)k(method)12 b FC(])p FJ(\))208 4733 y FN(Returns)27 b(a)g(ne)n(w)h(instance)f(of)g(the)g FJ(HTTPHandler)f FN(class.)47 b(The)27 b(instance)g(is)h(initialized)f(with)h(a)f(host)h (address,)g(url)f(and)208 4833 y(HTTP)21 b(method.)k(The)c FK(host)h FN(can)f(be)f(of)h(the)g(form)f FJ(host:port)p FN(,)f(should)h(you)g(need)g(to)h(use)g(a)h(speci\002c)f(port)f(number) -5 b(.)25 b(If)c(no)208 4932 y FK(method)g FN(is)g(speci\002ed,)f(`)p FJ(GET)p FN(')f(is)i(used.)0 5079 y FD(emit)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 5179 y FN(Sends)f(the)g(record)f(to)h(the)g (W)-7 b(eb)21 b(serv)o(er)e(as)i(an)f(URL-encoded)f(dictionary)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(466)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 467 479 TeXDict begin 467 478 bop 0 83 a Fv(14.5.6)101 b(F)m(or)r(matter)29 b(Objects)0 286 y FJ(Formatter)p FN(s)h(ha)n(v)o(e)h(the)g(follo)n (wing)e(attrib)n(utes)i(and)f(methods.)56 b(The)o(y)30 b(are)h(responsible)f(for)g(con)m(v)o(erting)e(a)k FJ(LogRecord)d FN(to)0 386 y(\(usually\))21 b(a)i(string)f(which)g(can)g(be)h (interpreted)d(by)i(either)g(a)h(human)e(or)h(an)h(e)o(xternal)e (system.)32 b(The)22 b(base)g FJ(Formatter)f FN(allo)n(ws)i(a)0 485 y(formatting)18 b(string)i(to)g(be)h(speci\002ed.)j(If)c(none)f(is) j(supplied,)c(the)j(def)o(ault)e(v)n(alue)h(of)g FJ('\045\(message\)s') e FN(is)j(used.)0 632 y(A)c(F)o(ormatter)f(can)h(be)f(initialized)h (with)g(a)g(format)f(string)g(which)h(mak)o(es)g(use)g(of)f(kno)n (wledge)f(of)h(the)h FJ(LogRecord)f FN(attrib)n(utes)h(-)g(such)0 732 y(as)22 b(the)g(def)o(ault)f(v)n(alue)g(mentioned)e(abo)o(v)o(e)h (making)g(use)i(of)g(the)f(f)o(act)h(that)g(the)f(user')-5 b(s)22 b(message)f(and)h(ar)o(guments)d(are)j(pre-formatted)0 831 y(into)30 b(a)g FJ(LogRecord)p FN(')-5 b(s)29 b FK(messa)o(g)o(e)h FN(attrib)n(ute.)53 b(This)30 b(format)f(string)h(contains)f(standard)f (p)o(ython)h(\045-style)h(mapping)e(k)o(e)o(ys.)53 b(See)0 931 y(section)20 b(3.6.2,)f(\223String)g(F)o(ormatting)g(Operations,)-6 b(\224)19 b(for)g(more)g(information)f(on)i(string)g(formatting.)0 1078 y(Currently)-5 b(,)18 b(the)j(useful)e(mapping)g(k)o(e)o(ys)g(in)i (a)f FJ(LogRecord)f FN(are:)50 1386 y FL(F)n(ormat)p 1044 1416 4 100 v 779 w(Description)p 0 1419 7254 4 v 50 1489 a FJ(\045\(name\)s)p 1044 1519 4 100 v 646 w FN(Name)h(of)g(the)g(logger)f(\(logging)f(channel\).)50 1588 y FJ(\045\(levelno\)s)p 1044 1618 V 496 w FN(Numeric)h(logging)g (le)n(v)o(el)g(for)h(the)g(message)g(\()p FJ(DEBUG)p FN(,)f FJ(INFO)p FN(,)h FJ(WARNING)p FN(,)f FJ(ERROR)p FN(,)h FJ(CRITICAL)p FN(\).)50 1688 y FJ(\045\(levelname\)s)p 1044 1718 V 396 w FN(T)-6 b(e)o(xt)20 b(logging)e(le)n(v)o(el)i(for)g (the)g(message)g(\()p FJ('DEBUG')p FN(,)f FJ('INFO')p FN(,)g FJ('WARNING')p FN(,)g FJ('ERROR')p FN(,)g FJ('CRITICAL')p FN(\).)50 1788 y FJ(\045\(pathname\)s)p 1044 1817 V 446 w FN(Full)h(pathname)f(of)h(the)g(source)g(\002le)g(where)g(the)g (logging)f(call)h(w)o(as)h(issued)g(\(if)f(a)n(v)n(ailable\).)50 1887 y FJ(\045\(filename\)s)p 1044 1917 V 446 w FN(Filename)g(portion)e (of)i(pathname.)50 1987 y FJ(\045\(module\)s)p 1044 2017 V 546 w FN(Module)f(\(name)g(portion)g(of)h(\002lename\).)50 2086 y FJ(\045\(funcName\)s)p 1044 2116 V 446 w FN(Name)g(of)g (function)e(containing)h(the)h(logging)e(call.)50 2186 y FJ(\045\(lineno\)d)p 1044 2216 V 546 w FN(Source)h(line)h(number)f (where)g(the)i(logging)d(call)j(w)o(as)g(issued)f(\(if)g(a)n(v)n (ailable\).)50 2286 y FJ(\045\(created\)f)p 1044 2316 V 496 w FN(T)m(ime)g(when)g(the)g FJ(LogRecord)f FN(w)o(as)i(created)e (\(as)i(returned)d(by)i FJ(time.time\(\))p FN(\).)50 2385 y FJ(\045\(relativeCreated\)d)p 1044 2415 V 96 w FN(T)m(ime)g(in)g(milliseconds)g(when)f(the)i(LogRecord)d(w)o(as)j (created,)e(relati)n(v)o(e)h(to)g(the)g(time)g(the)h(logging)d(module)h (w)o(as)i(loaded.)50 2485 y FJ(\045\(asctime\)s)p 1044 2515 V 496 w FN(Human-readable)c(time)j(when)g(the)g FJ(LogRecord)f FN(w)o(as)i(created.)j(By)d(def)o(ault)e(this)i(is)g(of) f(the)g(form)g(\2232003-07-08)c(16:49:45,896\224)g(\(the)k(numbers)e (after)i(the)g(comma)f(are)i(millisecond)e(portion)f(of)i(the)h (time\).)50 2585 y FJ(\045\(msecs\)d)p 1044 2614 V 596 w FN(Millisecond)e(portion)g(of)h(the)g(time)g(when)g(the)g FJ(LogRecord)f FN(w)o(as)i(created.)50 2684 y FJ(\045\(thread\)d)p 1044 2714 V 546 w FN(Thread)e(ID)h(\(if)g(a)n(v)n(ailable\).)50 2784 y FJ(\045\(threadName\)s)p 1044 2814 V 346 w FN(Thread)f(name)g (\(if)h(a)n(v)n(ailable\).)50 2883 y FJ(\045\(process\)d)p 1044 2913 V 496 w FN(Process)g(ID)h(\(if)f(a)n(v)n(ailable\).)50 2983 y FJ(\045\(message\)s)p 1044 3013 V 496 w FN(The)g(logged)e (message,)i(computed)e(as)j FJ(msg)50 b(\045args)p FN(.)0 3208 y(Changed)19 b(in)h(v)o(ersion)f(2.5:)h FK(funcName)f FN(w)o(as)i(added.)0 3355 y FL(class)g FD(Formatter)p FJ(\()p FC([)p FK(fmt)q FC([)p FK(,)e(datefmt)13 b FC(])f(])p FJ(\))208 3455 y FN(Returns)23 b(a)h(ne)n(w)f(instance)g(of)g(the)h FJ(Formatter)e FN(class.)36 b(The)23 b(instance)g(is)i(initialized)e (with)h(a)g(format)e(string)h(for)g(the)h(mes-)208 3554 y(sage)32 b(as)g(a)h(whole,)h(as)e(well)h(as)g(a)f(format)f(string)g (for)h(the)g(date/time)f(portion)g(of)g(a)i(message.)60 b(If)32 b(no)f FK(fmt)j FN(is)f(speci\002ed,)208 3654 y FJ('\045\(message\)s')18 b FN(is)j(used.)k(If)20 b(no)g FK(datefmt)h FN(is)g(speci\002ed,)f(the)g(ISO8601)e(date)i(format)g(is) h(used.)0 3801 y FD(format)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 3901 y FN(The)j(record')-5 b(s)23 b(attrib)n(ute)h (dictionary)f(is)i(used)f(as)h(the)g(operand)d(to)j(a)f(string)h (formatting)d(operation.)36 b(Returns)24 b(the)g(resulting)208 4000 y(string.)k(Before)20 b(formatting)g(the)h(dictionary)-5 b(,)19 b(a)j(couple)e(of)h(preparatory)e(steps)j(are)f(carried)f(out.) 28 b(The)21 b FK(messa)o(g)o(e)h FN(attrib)n(ute)f(of)208 4100 y(the)15 b(record)g(is)h(computed)e(using)h FK(msg)h FN(\045)h FK(ar)m(gs)p FN(.)23 b(If)16 b(the)g(formatting)d(string)j (contains)f FJ('\(asctime\)')p FN(,)g FJ(formatTime\(\))f FN(is)208 4199 y(called)k(to)i(format)e(the)h(e)n(v)o(ent)f(time.)24 b(If)19 b(there)g(is)h(e)o(xception)d(information,)g(it)i(is)h (formatted)e(using)g FJ(formatException\(\))208 4299 y FN(and)h(appended)f(to)i(the)h(message.)0 4446 y FD(formatTime)p FJ(\()p FK(r)m(ecor)m(d)r FC([)p FK(,)d(datefmt)13 b FC(])p FJ(\))208 4546 y FN(This)25 b(method)f(should)g(be)h(called)g (from)f FJ(format\(\))g FN(by)g(a)i(formatter)e(which)g(w)o(ants)i(to)f (mak)o(e)g(use)g(of)g(a)g(formatted)f(time.)208 4645 y(This)f(method)f(can)i(be)f(o)o(v)o(erridden)d(in)k(formatters)e(to)i (pro)o(vide)e(for)h(an)o(y)f(speci\002c)i(requirement,)e(b)n(ut)h(the)h (basic)g(beha)n(vior)e(is)208 4745 y(as)f(follo)n(ws:)j(if)d FK(datefmt)g FN(\(a)g(string\))e(is)i(speci\002ed,)f(it)h(is)g(used)f (with)g FJ(time.strftime\(\))e FN(to)j(format)e(the)h(creation)f(time)i (of)208 4844 y(the)f(record.)j(Otherwise,)d(the)g(ISO8601)f(format)g (is)i(used.)k(The)20 b(resulting)f(string)h(is)h(returned.)0 4991 y FD(formatException)p FJ(\()p FK(e)n(xc)p 914 4991 25 4 v 27 w(info)p FJ(\))208 5091 y FN(F)o(ormats)d(the)h(speci\002ed)g (e)o(xception)e(information)g(\(a)i(standard)f(e)o(xception)f(tuple)i (as)g(returned)f(by)g FJ(sys.exc_info\(\))p FN(\))f(as)208 5191 y(a)k(string.)28 b(This)22 b(def)o(ault)e(implementation)f(just)j (uses)g FJ(traceback.print_exception\(\))p FN(.)h(The)e(resulting)g (string)g(is)208 5290 y(returned.)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e (f)n(or)f(Python)2103 b(467)p eop end %%Page: 468 480 TeXDict begin 468 479 bop 0 83 a Fv(14.5.7)101 b(Filter)28 b(Objects)0 286 y FJ(Filter)p FN(s)c(can)f(be)h(used)g(by)f FJ(Handler)p FN(s)h(and)f FJ(Logger)p FN(s)h(for)f(more)g (sophisticated)g(\002ltering)h(than)f(is)i(pro)o(vided)c(by)j(le)n(v)o (els.)36 b(The)0 386 y(base)30 b(\002lter)h(class)g(only)e(allo)n(ws)h (e)n(v)o(ents)g(which)f(are)h(belo)n(w)g(a)g(certain)g(point)f(in)h (the)g(logger)f(hierarchy)-5 b(.)52 b(F)o(or)30 b(e)o(xample,)h(a)f (\002lter)0 485 y(initialized)18 b(with)g(\224A.B\224)h(will)g(allo)n (w)f(e)n(v)o(ents)f(logged)g(by)h(loggers)f(\224A.B\224,)i (\224A.B.C\224,)g(\224A.B.C.D\224,)f(\224A.B.D\224)g(etc.)25 b(b)n(ut)18 b(not)g(\224A.BB\224,)0 585 y(\224B.A.B\224)j(etc.)k(If)20 b(initialized)g(with)g(the)g(empty)g(string,)f(all)i(e)n(v)o(ents)f (are)g(passed.)0 732 y FL(class)h FD(Filter)p FJ(\()p FC([)p FK(name)12 b FC(])p FJ(\))208 831 y FN(Returns)30 b(an)h(instance)f(of)h(the)g FJ(Filter)f FN(class.)58 b(If)31 b FK(name)f FN(is)i(speci\002ed,)h(it)e(names)g(a)g(logger)e (which,)k(together)d(with)h(its)208 931 y(children,)18 b(will)j(ha)n(v)o(e)f(its)h(e)n(v)o(ents)e(allo)n(wed)h(through)e(the)i (\002lter)-5 b(.)26 b(If)20 b(no)g(name)f(is)i(speci\002ed,)f(allo)n (ws)h(e)n(v)o(ery)d(e)n(v)o(ent.)0 1078 y FD(filter)p FJ(\()p FK(r)m(ecor)m(d)r FJ(\))208 1177 y FN(Is)25 b(the)g (speci\002ed)g(record)f(to)h(be)g(logged?)39 b(Returns)25 b(zero)f(for)h(no,)h(nonzero)d(for)h(yes.)40 b(If)25 b(deemed)f(appropriate,)g(the)h(record)208 1277 y(may)19 b(be)h(modi\002ed)f(in-place)h(by)f(this)i(method.)0 1562 y Fv(14.5.8)101 b(LogRecord)30 b(Objects)0 1765 y FJ(LogRecord)21 b FN(instances)i(are)f(created)g(e)n(v)o(ery)f(time)i (something)e(is)i(logged.)30 b(The)o(y)22 b(contain)f(all)i(the)g (information)d(pertinent)h(to)i(the)0 1864 y(e)n(v)o(ent)j(being)f (logged.)43 b(The)26 b(main)h(information)d(passed)i(in)h(is)h(in)e (msg)h(and)f(ar)o(gs,)h(which)f(are)h(combined)d(using)j(msg)f(\045)h (ar)o(gs)f(to)0 1964 y(create)21 b(the)g(message)g(\002eld)g(of)g(the)g (record.)27 b(The)21 b(record)e(also)j(includes)e(information)f(such)i (as)h(when)e(the)h(record)f(w)o(as)i(created,)f(the)0 2064 y(source)e(line)i(where)e(the)i(logging)d(call)j(w)o(as)g(made,)e (and)h(an)o(y)f(e)o(xception)f(information)g(to)i(be)h(logged.)0 2211 y FL(class)g FD(LogRecord)p FJ(\()p FK(name)o(,)c(lvl,)k(pathname) o(,)d(lineno,)h(msg)o(,)i(ar)m(gs,)f(e)n(xc)p 2122 2211 25 4 v 29 w(info)g FC([)p FK(,)h(func)12 b FC(])p FJ(\))208 2310 y FN(Returns)22 b(an)h(instance)f(of)g FJ(LogRecord)g FN(initialized)g(with)h(interesting)f(information.)30 b(The)22 b FK(name)g FN(is)i(the)e(logger)g(name;)h FK(lvl)208 2410 y FN(is)g(the)f(numeric)e(le)n(v)o(el;)j FK(pathname)d FN(is)j(the)f(absolute)g(pathname)e(of)i(the)g(source)g(\002le)g(in)h (which)e(the)h(logging)f(call)h(w)o(as)h(made;)208 2509 y FK(lineno)18 b FN(is)j(the)e(line)h(number)d(in)j(that)g(\002le)g (where)f(the)g(logging)f(call)i(is)g(found;)e FK(msg)i FN(is)h(the)e(user)n(-supplied)f(message)h(\(a)h(format)208 2609 y(string\);)28 b FK(ar)m(gs)d FN(is)i(the)f(tuple)f(which,)i (together)d(with)i FK(msg)p FN(,)h(mak)o(es)f(up)f(the)h(user)g (message;)i(and)e FK(e)n(xc)p 3189 2609 V 29 w(info)g FN(is)h(the)e(e)o(xception)208 2709 y(tuple)19 b(obtained)g(by)g (calling)h FJ(sys.exc_info\(\))47 b FN(\(or)19 b FJ(None)p FN(,)h(if)g(no)g(e)o(xception)e(information)f(is)k(a)n(v)n(ailable\).)j (The)c FK(func)g FN(is)208 2808 y(the)g(name)f(of)h(the)h(function)d (from)h(which)h(the)g(logging)f(call)h(w)o(as)h(made.)k(If)20 b(not)g(speci\002ed,)f(it)i(def)o(aults)f(to)g FJ(None)p FN(.)51 b(Changed)208 2908 y(in)20 b(v)o(ersion)f(2.5:)g FK(func)h FN(w)o(as)h(added.)0 3055 y FD(getMessage)p FJ(\(\))208 3154 y FN(Returns)15 b(the)h(message)f(for)g(this)h FJ(LogRecord)f FN(instance)g(after)h(mer)o(ging)d(an)o(y)i(user)n (-supplied)f(ar)o(guments)f(with)j(the)g(message.)0 3439 y Fv(14.5.9)101 b(Thread)29 b(Saf)m(ety)0 3642 y FN(The)16 b(logging)e(module)h(is)i(intended)e(to)h(be)g(thread-safe)f(without)h (an)o(y)f(special)h(w)o(ork)g(needing)e(to)j(be)f(done)f(by)h(its)h (clients.)24 b(It)16 b(achie)n(v)o(es)0 3742 y(this)24 b(though)d(using)i(threading)e(locks;)k(there)d(is)i(one)f(lock)g(to)g (serialize)g(access)h(to)f(the)g(module')-5 b(s)23 b(shared)f(data,)i (and)e(each)h(handler)0 3842 y(also)e(creates)f(a)g(lock)g(to)g (serialize)h(access)g(to)f(its)h(underlying)d(I/O.)0 4126 y Fv(14.5.10)101 b(Con\002gur)o(ation)0 4329 y FI(Con\002gur)o (ation)24 b(functions)0 4532 y FN(The)g(follo)n(wing)f(functions)g (con\002gure)g(the)h(logging)f(module.)37 b(The)o(y)23 b(are)i(located)f(in)g(the)h FJ(logging.config)e FN(module.)36 b(Their)0 4632 y(use)27 b(is)g(optional)f(\227)h(you)e(can)i (con\002gure)d(the)j(logging)e(module)g(using)h(these)h(functions)e(or) h(by)g(making)g(calls)h(to)g(the)f(main)g(API)0 4732 y(\(de\002ned)18 b(in)h FJ(logging)f FN(itself\))h(and)f(de\002ning)g (handlers)g(which)g(are)h(declared)f(either)g(in)h FJ(logging)g FN(or)f FJ(logging.handlers)p FN(.)0 4878 y FD(fileConfig)p FJ(\()p FK(fname)p FC([)p FK(,)f(defaults)12 b FC(])p FJ(\))208 4978 y FN(Reads)20 b(the)g(logging)e(con\002guration)f(from)h (a)j(Con\002gP)o(arser)n(-format)c(\002le)j(named)f FK(fname)p FN(.)24 b(This)c(function)e(can)h(be)h(called)g(se)n(v-)208 5078 y(eral)f(times)h(from)e(an)h(application,)f(allo)n(wing)g(an)i (end)f(user)g(the)g(ability)g(to)h(select)g(from)e(v)n(arious)g (pre-canned)f(con\002gurations)208 5177 y(\(if)23 b(the)h(de)n(v)o (eloper)e(pro)o(vides)g(a)i(mechanism)f(to)h(present)f(the)h(choices)f (and)g(load)h(the)g(chosen)f(con\002guration\).)33 b(Def)o(aults)23 b(to)208 5277 y(be)d(passed)g(to)g(Con\002gP)o(arser)f(can)h(be)g (speci\002ed)g(in)h(the)f FK(defaults)f FN(ar)o(gument.)p 0 5549 3901 4 v 0 5649 a FI(468)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 469 481 TeXDict begin 469 480 bop 0 83 a FD(listen)p FJ(\()p FC([)p FK(port)13 b FC(])p FJ(\))208 183 y FN(Starts)27 b(up)e(a)i(sock)o(et)f(serv)o(er)g(on)g(the)g(speci\002ed)g(port,)h (and)f(listens)h(for)e(ne)n(w)h(con\002gurations.)41 b(If)27 b(no)e(port)h(is)h(speci\002ed,)h(the)208 282 y(module')-5 b(s)20 b(def)o(ault)h FJ(DEFAULT_LOGGING_CONFIG_PORT)c FN(is)23 b(used.)29 b(Logging)20 b(con\002gurations)f(will)k(be)e(sent) h(as)h(a)f(\002le)208 382 y(suitable)g(for)g(processing)f(by)h FJ(fileConfig\(\))p FN(.)30 b(Returns)23 b(a)g FJ(Thread)f FN(instance)g(on)g(which)g(you)f(can)i(call)g FJ(start\(\))e FN(to)208 482 y(start)i(the)f(serv)o(er)m(,)g(and)g(which)g(you)f(can)i FJ(join\(\))e FN(when)h(appropriate.)30 b(T)-7 b(o)22 b(stop)h(the)f(serv)o(er)m(,)g(call)h FJ(stopListening\(\))p FN(.)208 581 y(T)-7 b(o)21 b(send)g(a)h(con\002guration)d(to)i(the)h (sock)o(et,)f(read)g(in)h(the)f(con\002guration)e(\002le)j(and)f(send)g (it)h(to)g(the)f(sock)o(et)g(as)i(a)e(string)h(of)f(bytes)208 681 y(preceded)d(by)i(a)g(four)n(-byte)e(length)i(pack)o(ed)f(in)h (binary)f(using)h(struct.)p FJ(pack\('>L',)47 b(n\))p FN(.)0 828 y FD(stopListening)p FJ(\(\))208 927 y FN(Stops)24 b(the)g(listening)f(serv)o(er)g(which)h(w)o(as)h(created)e(with)h(a)g (call)h(to)f FJ(listen\(\))p FN(.)35 b(This)25 b(is)f(typically)g (called)f(before)g(calling)208 1027 y FJ(join\(\))c FN(on)h(the)g (return)f(v)n(alue)h(from)f FJ(listen\(\))p FN(.)0 1295 y FI(Con\002gur)o(ation)24 b(\002le)f(f)n(or)r(mat)0 1498 y FN(The)h(con\002guration)d(\002le)j(format)f(understood)f(by)h FJ(fileConfig\(\))f FN(is)j(based)f(on)f(Con\002gP)o(arser)g (functionality)-5 b(.)33 b(The)24 b(\002le)h(must)0 1598 y(contain)i(sections)h(called)f FJ([loggers])p FN(,)i FJ([handlers])d FN(and)h FJ([formatters])f FN(which)i(identify)e(by)i (name)f(the)h(entities)g(of)0 1697 y(each)g(type)f(which)h(are)f (de\002ned)g(in)i(the)f(\002le.)48 b(F)o(or)28 b(each)g(such)f(entity) -5 b(,)29 b(there)f(is)h(a)f(separate)g(section)f(which)h(identi\002ed) f(ho)n(w)g(that)0 1797 y(entity)h(is)i(con\002gured.)48 b(Thus,)30 b(for)e(a)h(logger)e(named)h FJ(log01)g FN(in)h(the)f FJ([loggers])g FN(section,)i(the)f(rele)n(v)n(ant)e(con\002guration)f (de-)0 1897 y(tails)j(are)f(held)g(in)h(a)f(section)g FJ([logger_log01])p FN(.)48 b(Similarly)-5 b(,)29 b(a)g(handler)d (called)i FJ(hand01)g FN(in)h(the)f FJ([handlers])f FN(section)0 1996 y(will)f(ha)n(v)o(e)e(its)i(con\002guration)c(held)i(in)h(a)g (section)g(called)f FJ([handler_hand01])p FN(,)f(while)i(a)h(formatter) d(called)h FJ(form01)h FN(in)g(the)0 2096 y FJ([formatters])17 b FN(section)h(will)h(ha)n(v)o(e)f(its)h(con\002guration)d(speci\002ed) i(in)h(a)f(section)g(called)h FJ([formatter_form01])p FN(.)i(The)d(root)0 2195 y(logger)h(con\002guration)e(must)k(be)f (speci\002ed)g(in)g(a)h(section)f(called)g FJ([logger_root])p FN(.)0 2342 y(Examples)f(of)h(these)g(sections)h(in)f(the)g(\002le)h (are)f(gi)n(v)o(en)f(belo)n(w)-5 b(.)236 2489 y FA([loggers])236 2581 y(keys=root,log02,log03,log04,log05,log06,)o(log07)236 2763 y([handlers])236 2855 y(keys=hand01,hand02,hand03,hand04,hand05,)o (hand06)o(,hand0)o(7,hand)o(08,han)o(d09)236 3037 y([formatters])236 3128 y(keys=form01,form02,form03,form04,form05,)o(form06)o(,form0)o (7,form)o(08,for)o(m09)0 3415 y FN(The)20 b(root)f(logger)g(must)h (specify)g(a)h(le)n(v)o(el)e(and)h(a)h(list)g(of)f(handlers.)k(An)c(e)o (xample)f(of)h(a)g(root)g(logger)f(section)h(is)h(gi)n(v)o(en)e(belo)n (w)-5 b(.)236 3562 y FA([logger_root])236 3653 y(level=NOTSET)236 3745 y(handlers=hand01)0 4031 y FN(The)31 b FJ(level)h FN(entry)f(can)g(be)h(one)f(of)g FJ(DEBUG,)49 b(INFO,)g(WARNING,)f (ERROR,)h(CRITICAL)31 b FN(or)g FJ(NOTSET)p FN(.)g(F)o(or)h(the)f(root) 0 4131 y(logger)24 b(only)-5 b(,)25 b FJ(NOTSET)g FN(means)g(that)g (all)h(messages)g(will)g(be)f(logged.)39 b(Le)n(v)o(el)25 b(v)n(alues)g(are)g FJ(eval\(\))p FN(uated)f(in)h(the)g(conte)o(xt)f (of)i(the)0 4230 y FJ(logging)19 b FN(package')-5 b(s)20 b(namespace.)0 4377 y(The)i FJ(handlers)f FN(entry)h(is)h(a)g (comma-separated)c(list)k(of)f(handler)f(names,)h(which)g(must)g (appear)f(in)i(the)f FJ([handlers])f FN(section.)0 4477 y(These)f(names)g(must)g(appear)f(in)h(the)h FJ([handlers])e FN(section)h(and)f(ha)n(v)o(e)h(corresponding)c(sections)21 b(in)f(the)g(con\002guration)e(\002le.)0 4624 y(F)o(or)26 b(loggers)f(other)g(than)h(the)g(root)f(logger)m(,)h(some)g(additional) e(information)g(is)j(required.)41 b(This)26 b(is)h(illustrated)e(by)h (the)g(follo)n(wing)0 4723 y(e)o(xample.)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n (acility)e(f)n(or)f(Python)2103 b(469)p eop end %%Page: 470 482 TeXDict begin 470 481 bop 236 174 a FA([logger_parser])236 266 y(level=DEBUG)236 357 y(handlers=hand01)236 448 y(propagate=1)236 540 y(qualname=compiler.parser)0 826 y FN(The)25 b FJ(level)g FN(and)g FJ(handlers)g FN(entries)g(are)g(interpreted)f(as)i(for)f(the) h(root)e(logger)m(,)h(e)o(xcept)g(that)g(if)h(a)g(non-root)d(logger')-5 b(s)25 b(le)n(v)o(el)g(is)0 926 y(speci\002ed)17 b(as)h FJ(NOTSET)p FN(,)e(the)h(system)g(consults)g(loggers)f(higher)g(up)h (the)g(hierarchy)d(to)k(determine)d(the)i(ef)n(fecti)n(v)o(e)f(le)n(v)o (el)h(of)g(the)g(logger)-5 b(.)0 1025 y(The)19 b FJ(propagate)f FN(entry)g(is)j(set)f(to)f(1)h(to)f(indicate)g(that)g(messages)g(must)h (propagate)c(to)k(handlers)e(higher)g(up)h(the)g(logger)f(hierarchy)0 1125 y(from)g(this)h(logger)m(,)e(or)h(0)h(to)g(indicate)f(that)g (messages)h(are)g FL(not)f FN(propagated)e(to)i(handlers)g(up)g(the)h (hierarchy)-5 b(.)21 b(The)e FJ(qualname)e FN(entry)0 1225 y(is)k(the)f(hierarchical)f(channel)g(name)g(of)h(the)h(logger)m (,)d(that)i(is)h(to)g(say)f(the)g(name)g(used)g(by)g(the)g(application) e(to)j(get)f(the)g(logger)-5 b(.)0 1372 y(Sections)20 b(which)g(specify)f(handler)g(con\002guration)f(are)i(e)o(x)o (empli\002ed)e(by)i(the)g(follo)n(wing.)236 1610 y FA([handler_hand01]) 236 1701 y(class=StreamHandler)236 1792 y(level=NOTSET)236 1884 y(formatter=form01)236 1975 y(args=\(sys.stdout,\))0 2262 y FN(The)25 b FJ(class)f FN(entry)g(indicates)h(the)g(handler')-5 b(s)24 b(class)h(\(as)h(determined)d(by)h FJ(eval\(\))g FN(in)h(the)g FJ(logging)g FN(package')-5 b(s)23 b(namespace\).)0 2361 y(The)d FJ(level)g FN(is)h(interpreted)d(as)j(for)f(loggers,)f (and)g FJ(NOTSET)h FN(is)h(tak)o(en)f(to)g(mean)g(\224log)f(e)n(v)o (erything\224.)0 2508 y(The)36 b FJ(formatter)e FN(entry)h(indicates)h (the)g(k)o(e)o(y)f(name)h(of)f(the)h(formatter)e(for)i(this)g(handler) -5 b(.)71 b(If)36 b(blank,)j(a)d(def)o(ault)f(formatter)0 2608 y(\()p FJ(logging._defaultFormatter)p FN(\))22 b(is)28 b(used.)44 b(If)26 b(a)h(name)g(is)g(speci\002ed,)h(it)f(must)g(appear) f(in)h(the)f FJ([formatters])f FN(sec-)0 2707 y(tion)20 b(and)g(ha)n(v)o(e)f(a)i(corresponding)c(section)i(in)i(the)f (con\002guration)e(\002le.)0 2854 y(The)h FJ(args)f FN(entry)-5 b(,)18 b(when)g FJ(eval\(\))p FN(uated)f(in)i(the)g(conte)o(xt)f(of)g (the)h FJ(logging)f FN(package')-5 b(s)18 b(namespace,)f(is)j(the)f (list)h(of)f(ar)o(guments)d(to)0 2954 y(the)22 b(constructor)f(for)h (the)g(handler)f(class.)33 b(Refer)22 b(to)h(the)f(constructors)f(for)h (the)g(rele)n(v)n(ant)g(handlers,)f(or)h(to)h(the)f(e)o(xamples)g(belo) n(w)-5 b(,)21 b(to)0 3053 y(see)g(ho)n(w)e(typical)h(entries)g(are)g (constructed.)p 0 5549 3901 4 v 0 5649 a FI(470)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 471 483 TeXDict begin 471 482 bop 236 174 a FA([handler_hand02])236 266 y(class=FileHandler)236 357 y(level=DEBUG)236 448 y(formatter=form02)236 540 y(args=\('python.log',)42 b('w'\))236 722 y([handler_hand03])236 814 y (class=handlers.SocketHandler)236 905 y(level=INFO)236 996 y(formatter=form03)236 1088 y(args=\('localhost',)g (handlers.DEFAULT_TCP_LOGGING_PORT\))236 1270 y([handler_hand04])236 1362 y(class=handlers.DatagramHandler)236 1453 y(level=WARN)236 1544 y(formatter=form04)236 1636 y(args=\('localhost',)g (handlers.DEFAULT_UDP_LOGGING_PORT\))236 1818 y([handler_hand05])236 1910 y(class=handlers.SysLogHandler)236 2001 y(level=ERROR)236 2092 y(formatter=form05)236 2183 y(args=\(\('localhost',)g (handlers.SYSLOG_UDP_PORT\),)e(handlers.SysLogHandler.LOG_USER\))236 2366 y([handler_hand06])236 2457 y(class=handlers.NTEventLogHandler)236 2549 y(level=CRITICAL)236 2640 y(formatter=form06)236 2731 y(args=\('Python)j(Application',)g('',)h('Application'\))236 2914 y([handler_hand07])236 3005 y(class=handlers.SMTPHandler)236 3097 y(level=WARN)236 3188 y(formatter=form07)236 3279 y(args=\('localhost',)e('from@abc',)h(['user1@abc',)g('user2@xyz'],)f ('Logger)i(Subject'\))236 3462 y([handler_hand08])236 3553 y(class=handlers.MemoryHandler)236 3645 y(level=NOTSET)236 3736 y(formatter=form08)236 3827 y(target=)236 3919 y(args=\(10,)g (ERROR\))236 4101 y([handler_hand09])236 4193 y (class=handlers.HTTPHandler)236 4284 y(level=NOTSET)236 4375 y(formatter=form09)236 4467 y(args=\('localhost:9022',)d('/log',)j ('GET'\))0 4753 y FN(Sections)20 b(which)g(specify)f(formatter)g (con\002guration)e(are)k(typi\002ed)e(by)h(the)g(follo)n(wing.)236 4991 y FA([formatter_form01])236 5083 y(format=F1)44 b(\045\(asctime\)s)f(\045\(levelname\)s)f(\045\(message\)s)236 5174 y(datefmt=)236 5265 y(class=logging.Formatter)p 0 5549 3901 4 v 0 5649 a FI(14.5.)52 b FJ(logging)22 b FI(\227)h(Logging)i(f)n(acility)e(f)n(or)f(Python)2103 b(471)p eop end %%Page: 472 484 TeXDict begin 472 483 bop 0 83 a FN(The)25 b FJ(format)f FN(entry)g(is)i(the)f(o)o(v)o(erall)f(format)g(string,)h(and)g(the)g FJ(datefmt)f FN(entry)g(is)i(the)f FJ(strftime\(\))p FN(-compatible)c(date/time)0 183 y(format)31 b(string.)60 b(If)32 b(empty)-5 b(,)33 b(the)f(package)e(substitutes)j(ISO8601)d (format)h(date/times,)j(which)e(is)h(almost)e(equi)n(v)n(alent)g(to)h (spec-)0 282 y(ifying)f(the)i(date)f(format)f(string)i(\224The)f (ISO8601)e(format)i(also)g(speci\002es)h(milliseconds,)i(which)d(are)g (appended)e(to)j(the)g(result)0 382 y(of)28 b(using)f(the)h(abo)o(v)o (e)e(format)h(string,)i(with)f(a)g(comma)f(separator)-5 b(.)47 b(An)28 b(e)o(xample)e(time)i(in)g(ISO8601)e(format)h(is)i FJ(2003-01-23)0 482 y(00:29:50,411)p FN(.)0 628 y(The)f FJ(class)h FN(entry)f(is)i(optional.)49 b(It)29 b(indicates)f(the)h (name)f(of)h(the)g(formatter')-5 b(s)27 b(class)j(\(as)f(a)g(dotted)f (module)g(and)g(class)i(name.\))0 728 y(This)f(option)f(is)i(useful)f (for)f(instantiating)g(a)i FJ(Formatter)e FN(subclass.)52 b(Subclasses)29 b(of)g FJ(Formatter)f FN(can)h(present)f(e)o(xception)0 828 y(tracebacks)19 b(in)h(an)h(e)o(xpanded)c(or)j(condensed)e(format.) 0 1155 y FE(14.6)121 b Fx(getpass)32 b FE(\227)g(P)-6 b(or)5 b(tab)n(le)34 b(pass)l(w)o(ord)h(input)0 1388 y FN(The)20 b FJ(getpass)f FN(module)g(pro)o(vides)g(tw)o(o)h (functions:)0 1535 y FD(getpass)p FJ(\()p FC([)p FK(pr)l(ompt)q FC([)p FK(,)e(str)m(eam)12 b FC(])g(])p FJ(\))208 1634 y FN(Prompt)29 b(the)h(user)f(for)h(a)g(passw)o(ord)f(without)h (echoing.)52 b(The)30 b(user)g(is)g(prompted)e(using)i(the)g(string)f FK(pr)l(ompt)q FN(,)k(which)c(de-)208 1734 y(f)o(aults)c(to)g FJ('Password:)98 b(')p FN(.)40 b(On)27 b(U)t FH(N)t(I)t(X)r FN(,)g(the)e(prompt)f(is)i(written)f(to)g(the)g(\002le-lik)o(e)g (object)g FK(str)m(eam)p FN(,)h(which)f(def)o(aults)f(to)208 1834 y FJ(sys.stdout)18 b FN(\(this)j(ar)o(gument)d(is)j(ignored)d(on)i (W)m(indo)n(ws\).)208 1966 y(A)-6 b(v)n(ailability:)24 b(Macintosh,)d(U)t FH(N)t(I)t(X)r FN(,)g(W)m(indo)n(ws.)50 b(Changed)19 b(in)h(v)o(ersion)f(2.5:)h(The)f FK(str)m(eam)i FN(parameter)e(w)o(as)i(added.)0 2113 y FD(getuser)p FJ(\(\))208 2213 y FN(Return)e(the)i(\223login)e(name\224)g(of)h(the)g (user)-5 b(.)26 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(,)21 b(W)m(indo)n(ws.)208 2346 y(This)h(function)f(checks)g(the)i (en)m(vironment)c(v)n(ariables)i(LOGN)m(AME,)h(USER,)h(LN)m(AME)f(and)f (USERN)m(AME,)i(in)f(order)m(,)f(and)208 2445 y(returns)j(the)i(v)n (alue)f(of)h(the)f(\002rst)i(one)e(which)g(is)i(set)f(to)g(a)g (non-empty)d(string.)42 b(If)25 b(none)g(are)g(set,)j(the)e(login)f (name)g(from)g(the)208 2545 y(passw)o(ord)19 b(database)h(is)h (returned)d(on)i(systems)h(which)e(support)g(the)h FJ(pwd)g FN(module,)f(otherwise,)g(an)h(e)o(xception)f(is)i(raised.)0 2873 y FE(14.7)121 b Fx(curses)32 b FE(\227)h(T)-14 b(er)s(minal)32 b(handling)k(f)l(or)e(char)o(acter-cell)f(displa)l(ys)0 3105 y FN(Changed)19 b(in)h(v)o(ersion)f(1.6:)h(Added)f(support)g(for)g (the)h FJ(ncurses)g FN(library)f(and)h(con)m(v)o(erted)d(to)k(a)f (package.)0 3252 y(The)h FJ(curses)g FN(module)e(pro)o(vides)h(an)h (interf)o(ace)g(to)g(the)g(curses)g(library)-5 b(,)20 b(the)i(de-f)o(acto)d(standard)i(for)f(portable)g(adv)n(anced)f (terminal)0 3352 y(handling.)0 3499 y(While)i(curses)g(is)g(most)g (widely)f(used)h(in)f(the)j(U)t FH(N)t(I)t(X)h FN(en)m(vironment,)17 b(v)o(ersions)j(are)g(a)n(v)n(ailable)h(for)f(DOS,)h(OS/2,)f(and)g (possibly)g(other)0 3598 y(systems)g(as)g(well.)26 b(This)20 b(e)o(xtension)e(module)g(is)i(designed)f(to)h(match)f(the)g(API)h(of)g (ncurses,)f(an)g(open-source)e(curses)j(library)e(hosted)0 3698 y(on)i(Linux)f(and)h(the)g(BSD)h(v)n(ariants)e(of)j(U)t FH(N)t(I)t(X)r FN(.)0 3845 y FL(See)f(Also:)0 3992 y FN(Module)e FJ(curses.ascii)g FN(\(section)g(14.10\):)208 4091 y(Utilities)i(for)e(w)o(orking)g(with)j FH(A)t(S)t(C)t(I)t(I)i FN(characters,)19 b(re)o(gardless)g(of)h(your)f(locale)h(settings.)0 4238 y(Module)f FJ(curses.panel)g FN(\(section)g(14.11\):)208 4338 y(A)h(panel)g(stack)g(e)o(xtension)f(that)h(adds)g(depth)f(to)i (curses)f(windo)n(ws.)0 4485 y(Module)f FJ(curses.textpad)f FN(\(section)i(14.8\):)208 4584 y(Editable)f(te)o(xt)h(widget)g(for)f (curses)i(supporting)d FL(Emacs)p FN(-lik)o(e)i(bindings.)0 4731 y(Module)f FJ(curses.wrapper)f FN(\(section)i(14.9\):)208 4831 y(Con)m(v)o(enience)d(function)i(to)h(ensure)f(proper)g(terminal)g (setup)h(and)g(resetting)g(on)f(application)g(entry)h(and)f(e)o(xit.)0 4978 y FK(Cur)o(ses)j(Pr)l(o)o(gr)o(amming)c(with)j(Python)0 5077 y Fy(\()p FO(http://www)l(.p)n(ython.org/d)o(oc/h)o(o)o(wt)o (o/curse)o(s/curses)o(.html)-7 b Fy(\))208 5177 y FN(T)l(utorial)29 b(material)g(on)g(using)g(curses)h(with)g(Python,)h(by)e(Andre)n(w)f(K) o(uchling)g(and)i(Eric)f(Raymond,)h(is)h(a)n(v)n(ailable)e(on)h(the)208 5277 y(Python)19 b(W)-7 b(eb)20 b(site.)p 0 5549 3901 4 v 0 5649 a FI(472)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 473 485 TeXDict begin 473 484 bop 0 83 a FN(The)29 b(`)p FO(Demo/curses/)p FN(')f(directory)g(in)i(the)g(Python)e(source)h(distrib)n(ution)f (contains)h(some)g(e)o(xample)f(programs)g(using)h(the)h(curses)0 183 y(bindings)19 b(pro)o(vided)e(by)j(this)h(module.)0 468 y Fv(14.7.1)101 b(Functions)0 670 y FN(The)20 b(module)f FJ(curses)g FN(de\002nes)h(the)g(follo)n(wing)f(e)o(xception:)0 817 y FL(exception)g FD(error)208 917 y FN(Exception)f(raised)i(when)g (a)g(curses)g(library)f(function)g(returns)g(an)h(error)-5 b(.)0 1064 y FL(Note:)30 b FN(Whene)n(v)o(er)22 b FK(x)i FN(or)f FK(y)h FN(ar)o(guments)d(to)i(a)h(function)e(or)h(a)g(method)f (are)h(optional,)g(the)o(y)f(def)o(ault)h(to)g(the)h(current)d(cursor)i (location.)0 1163 y(Whene)n(v)o(er)c FK(attr)j FN(is)f(optional,)e(it)i (def)o(aults)f(to)g FJ(A_NORMAL)p FN(.)0 1310 y(The)g(module)f FJ(curses)g FN(de\002nes)h(the)g(follo)n(wing)f(functions:)0 1457 y FD(baudrate)p FJ(\(\))208 1557 y FN(Returns)i(the)g(output)f (speed)h(of)g(the)g(terminal)f(in)i(bits)f(per)g(second.)27 b(On)22 b(softw)o(are)e(terminal)h(emulators)f(it)i(will)g(ha)n(v)o(e)f (a)g(\002x)o(ed)208 1656 y(high)j(v)n(alue.)38 b(Included)23 b(for)h(historical)h(reasons;)i(in)e(former)e(times,)j(it)g(w)o(as)g (used)e(to)h(write)g(output)f(loops)h(for)f(time)h(delays)208 1756 y(and)19 b(occasionally)g(to)h(change)f(interf)o(aces)h(depending) d(on)j(the)g(line)h(speed.)0 1903 y FD(beep)p FJ(\(\))208 2003 y FN(Emit)f(a)g(short)g(attention)g(sound.)0 2149 y FD(can_change_color)p FJ(\(\))208 2249 y FN(Returns)g(true)f(or)h(f)o (alse,)h(depending)c(on)j(whether)f(the)i(programmer)c(can)j(change)f (the)h(colors)f(displayed)g(by)h(the)g(terminal.)0 2396 y FD(cbreak)p FJ(\(\))208 2496 y FN(Enter)g(cbreak)h(mode.)27 b(In)21 b(cbreak)f(mode)h(\(sometimes)g(called)g(\223rare\224)g(mode\)) f(normal)g(tty)h(line)h(b)n(uf)n(fering)d(is)j(turned)e(of)n(f)h(and) 208 2595 y(characters)j(are)g(a)n(v)n(ailable)h(to)g(be)g(read)f(one)h (by)f(one.)39 b(Ho)n(we)n(v)o(er)m(,)24 b(unlik)o(e)g(ra)o(w)h(mode,)g (special)g(characters)f(\(interrupt,)g(quit,)208 2695 y(suspend,)g(and)f(\003o)n(w)h(control\))f(retain)h(their)g(ef)n(fects) g(on)g(the)g(tty)g(dri)n(v)o(er)f(and)h(calling)f(program.)35 b(Calling)24 b(\002rst)h FJ(raw\(\))f FN(then)208 2794 y FJ(cbreak\(\))19 b FN(lea)n(v)o(es)h(the)g(terminal)g(in)g(cbreak)f (mode.)0 2941 y FD(color_content)p FJ(\()p FK(color)p 881 2941 25 4 v 27 w(number)r FJ(\))208 3041 y FN(Returns)j(the)g (intensity)g(of)h(the)f(red,)g(green,)g(and)g(blue)g(\(RGB\))h (components)d(in)j(the)f(color)g FK(color)p 3087 3041 V 29 w(number)r FN(,)g(which)g(must)h(be)208 3141 y(between)f FJ(0)h FN(and)g FJ(COLORS)p FN(.)f(A)i(3-tuple)d(is)j(returned,)e (containing)f(the)i(R,G,B)h(v)n(alues)f(for)f(the)h(gi)n(v)o(en)f (color)m(,)g(which)h(will)h(be)208 3240 y(between)19 b FJ(0)i FN(\(no)e(component\))e(and)j FJ(1000)g FN(\(maximum)e(amount) h(of)h(component\).)0 3387 y FD(color_pair)p FJ(\()p FK(color)p 731 3387 V 27 w(number)r FJ(\))208 3487 y FN(Returns)31 b(the)h(attrib)n(ute)f(v)n(alue)g(for)g(displaying)f(te)o (xt)i(in)g(the)g(speci\002ed)f(color)-5 b(.)59 b(This)32 b(attrib)n(ute)f(v)n(alue)g(can)h(be)g(combined)208 3586 y(with)23 b FJ(A_STANDOUT)p FN(,)f FJ(A_REVERSE)p FN(,)g(and)g(the)h (other)g FJ(A_)1978 3601 y(*)2051 3586 y FN(attrib)n(utes.)34 b FJ(pair_number\(\))21 b FN(is)k(the)e(counterpart)e(to)i(this)208 3686 y(function.)0 3833 y FD(curs_set)p FJ(\()p FK(visibility)p FJ(\))208 3932 y FN(Sets)28 b(the)f(cursor)f(state.)47 b FK(visibility)28 b FN(can)f(be)h(set)g(to)f(0,)i(1,)g(or)e(2,)i(for)e (in)m(visible,)h(normal,)f(or)g(v)o(ery)g(visible.)46 b(If)27 b(the)g(terminal)208 4032 y(supports)f(the)i(visibility)g (requested,)h(the)f(pre)n(vious)e(cursor)h(state)i(is)g(returned;)h (otherwise,)f(an)f(e)o(xception)e(is)j(raised.)48 b(On)208 4132 y(man)o(y)19 b(terminals,)g(the)h(\223visible\224)g(mode)f(is)j (an)e(underline)e(cursor)h(and)h(the)g(\223v)o(ery)f(visible\224)h (mode)f(is)i(a)g(block)e(cursor)-5 b(.)0 4279 y FD(def_prog_mode)p FJ(\(\))208 4378 y FN(Sa)n(v)o(es)23 b(the)g(current)f(terminal)g(mode) g(as)i(the)f(\223program\224)e(mode,)i(the)g(mode)f(when)g(the)h (running)e(program)g(is)j(using)f(curses.)208 4478 y(\(Its)28 b(counterpart)f(is)i(the)g(\223shell\224)g(mode,)h(for)e(when)g(the)g (program)f(is)j(not)e(in)h(curses.\))50 b(Subsequent)27 b(calls)i(to)g FJ(reset_-)208 4577 y(prog_mode\(\))18 b FN(will)j(restore)f(this)h(mode.)0 4724 y FD(def_shell_mode)p FJ(\(\))208 4824 y FN(Sa)n(v)o(es)i(the)g(current)e(terminal)h(mode)g (as)h(the)g(\223shell\224)g(mode,)f(the)h(mode)f(when)g(the)h(running)e (program)f(is)k(not)f(using)f(curses.)208 4924 y(\(Its)28 b(counterpart)e(is)j(the)f(\223program\224)e(mode,)j(when)f(the)g (program)e(is)j(using)f(curses)g(capabilities.\))49 b(Subsequent)26 b(calls)j(to)208 5023 y FJ(reset_shell_mode\(\))17 b FN(will)k(restore)f(this)g(mode.)0 5170 y FD(delay_output)p FJ(\()p FK(ms)p FJ(\))208 5270 y FN(Inserts)g(an)g FK(ms)h FN(millisecond)e(pause)h(in)g(output.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e(char)o(acter-cell)f(displa)n(ys) 1487 b(473)p eop end %%Page: 474 486 TeXDict begin 474 485 bop 0 83 a FD(doupdate)p FJ(\(\))208 183 y FN(Update)21 b(the)h(physical)f(screen.)30 b(The)21 b(curses)h(library)f(k)o(eeps)h(tw)o(o)g(data)g(structures,)g(one)f (representing)f(the)i(current)f(physical)208 282 y(screen)f(contents)h (and)g(a)g(virtual)g(screen)g(representing)e(the)i(desired)g(ne)o(xt)f (state.)29 b(The)21 b FJ(doupdate\(\))f FN(ground)f(updates)i(the)208 382 y(physical)e(screen)g(to)i(match)e(the)i(virtual)e(screen.)208 515 y(The)30 b(virtual)h(screen)f(may)h(be)g(updated)e(by)i(a)h FJ(noutrefresh\(\))d FN(call)i(after)g(write)g(operations)f(such)h(as)g FJ(addstr\(\))208 614 y FN(ha)n(v)o(e)26 b(been)f(performed)f(on)j(a)g (windo)n(w)-5 b(.)42 b(The)26 b(normal)g FJ(refresh\(\))f FN(call)i(is)h(simply)e FJ(noutrefresh\(\))f FN(follo)n(wed)g(by)208 714 y FJ(doupdate\(\))p FN(;)18 b(if)i(you)e(ha)n(v)o(e)h(to)h(update)e (multiple)h(windo)n(ws,)g(you)f(can)i(speed)f(performance)d(and)j (perhaps)g(reduce)f(screen)208 814 y(\003ick)o(er)i(by)f(issuing)h FJ(noutrefresh\(\))f FN(calls)i(on)e(all)i(windo)n(ws,)e(follo)n(wed)g (by)h(a)h(single)f FJ(doupdate\(\))p FN(.)0 960 y FD(echo)p FJ(\(\))208 1060 y FN(Enter)f(echo)h(mode.)k(In)c(echo)f(mode,)g(each)h (character)f(input)g(is)i(echoed)e(to)i(the)f(screen)g(as)g(it)h(is)h (entered.)0 1207 y FD(endwin)p FJ(\(\))208 1307 y FN(De-initialize)d (the)i(library)-5 b(,)18 b(and)i(return)f(terminal)g(to)h(normal)f (status.)0 1453 y FD(erasechar)p FJ(\(\))208 1553 y FN(Returns)k(the)h (user')-5 b(s)25 b(current)d(erase)j(character)-5 b(.)35 b(Under)25 b(U)t FH(N)t(I)t(X)i FN(operating)22 b(systems)j(this)g(is)g (a)f(property)e(of)i(the)g(controlling)208 1653 y(tty)c(of)g(the)g (curses)g(program,)e(and)i(is)h(not)f(set)h(by)f(the)g(curses)g (library)f(itself.)0 1800 y FD(filter)p FJ(\(\))208 1899 y FN(The)j FJ(filter\(\))f FN(routine,)h(if)h(used,)f(must)h(be)f (called)h(before)e FJ(initscr\(\))g FN(is)j(called.)31 b(The)23 b(ef)n(fect)e(is)j(that,)f(during)e(those)208 1999 y(calls,)h(LINES)f(is)i(set)f(to)g(1;)g(the)g(capabilities)f (clear)m(,)h(cup,)f(cud,)g(cud1,)g(cuu1,)f(cuu,)h(vpa)g(are)h (disabled;)g(and)f(the)g(home)g(string)208 2098 y(is)j(set)h(to)f(the)g (v)n(alue)g(of)f(cr)-5 b(.)37 b(The)23 b(ef)n(fect)h(is)h(that)f(the)g (cursor)f(is)i(con\002ned)d(to)i(the)g(current)f(line,)h(and)g(so)g (are)g(screen)g(updates.)208 2198 y(This)c(may)g(be)g(used)g(for)f (enabling)g(character)n(-at-a-time)f(line)i(editing)f(without)h (touching)e(the)i(rest)h(of)f(the)g(screen.)0 2345 y FD(flash)p FJ(\(\))208 2445 y FN(Flash)25 b(the)f(screen.)38 b(That)24 b(is,)i(change)d(it)i(to)g(re)n(v)o(erse-video)d(and)i(then)g (change)f(it)i(back)f(in)g(a)h(short)g(interv)n(al.)36 b(Some)25 b(people)208 2544 y(prefer)18 b(such)i(as)h(`visible)f(bell') g(to)g(the)h(audible)e(attention)g(signal)h(produced)e(by)i FJ(beep\(\))p FN(.)0 2691 y FD(flushinp)p FJ(\(\))208 2791 y FN(Flush)k(all)h(input)e(b)n(uf)n(fers.)36 b(This)24 b(thro)n(ws)g(a)o(w)o(ay)g(an)o(y)f(typeahead)g(that)h(has)g(been)g (typed)f(by)h(the)g(user)g(and)g(has)g(not)g(yet)g(been)208 2890 y(processed)19 b(by)g(the)i(program.)0 3037 y FD(getmouse)p FJ(\(\))208 3137 y FN(After)d FJ(getch\(\))g FN(returns)g FJ(KEY_MOUSE)g FN(to)h(signal)g(a)g(mouse)g(e)n(v)o(ent,)f(this)h (method)f(should)f(be)i(call)h(to)f(retrie)n(v)o(e)e(the)i(queued)208 3236 y(mouse)25 b(e)n(v)o(ent,)h(represented)e(as)j(a)f(5-tuple)e FJ(\()p FK(id)r FJ(,)50 b FK(x)p FJ(,)f FK(y)p FJ(,)h FK(z)p FJ(,)g FK(bstate)p FJ(\))p FN(.)41 b FK(id)29 b FN(is)e(an)e(ID)h(v)n(alue)g(used)f(to)h(distinguish)f(multi-)208 3336 y(ple)h(de)n(vices,)h(and)e FK(x)p FN(,)j FK(y)p FN(,)g FK(z)f FN(are)f(the)h(e)n(v)o(ent')-5 b(s)25 b(coordinates.)42 b(\()p FK(z)26 b FN(is)h(currently)e(unused.\).)41 b FK(bstate)26 b FN(is)h(an)f(inte)o(ger)f(v)n(alue)h(whose)208 3436 y(bits)f(will)g(be)g(set)g(to)g(indicate)f(the)h(type)f(of)h(e)n (v)o(ent,)g(and)f(will)h(be)g(the)g(bitwise)g(OR)g(of)g(one)f(or)g (more)g(of)h(the)f(follo)n(wing)f(con-)208 3535 y(stants,)d(where)g FK(n)g FN(is)i(the)e(b)n(utton)f(number)g(from)g(1)h(to)h(4:)k FJ(BUTTON)p FK(n)p FJ(_PRESSED)p FN(,)18 b FJ(BUTTON)p FK(n)p FJ(_RELEASED)p FN(,)f FJ(BUTTON)p FK(n)p FJ(_-)208 3635 y(CLICKED)p FN(,)j FJ(BUTTON)p FK(n)p FJ(_DOUBLE_CLICKED)p FN(,)e FJ(BUTTON)p FK(n)p FJ(_TRIPLE_CLICKED)p FN(,)g FJ(BUTTON_SHIFT)p FN(,)h FJ(BUTTON_-)208 3735 y(CTRL)p FN(,)g FJ(BUTTON_ALT)p FN(.)0 3881 y FD(getsyx)p FJ(\(\))208 3981 y FN(Returns)i(the)g(current)f(coordinates)g(of)h(the)g(virtual)g (screen)g(cursor)g(in)g(y)h(and)e(x.)29 b(If)21 b(lea)n(v)o(eok)g(is)h (currently)e(true,)h(then)g(-1,-1)f(is)208 4081 y(returned.)0 4228 y FD(getwin)p FJ(\()p FK(\002le)p FJ(\))208 4327 y FN(Reads)h(windo)n(w)f(related)g(data)h(stored)f(in)i(the)e(\002le)i (by)f(an)f(earlier)h FJ(putwin\(\))f FN(call.)28 b(The)20 b(routine)g(then)g(creates)h(and)g(initial-)208 4427 y(izes)f(a)h(ne)n(w)f(windo)n(w)f(using)h(that)g(data,)g(returning)e (the)i(ne)n(w)g(windo)n(w)f(object.)0 4574 y FD(has_colors)p FJ(\(\))208 4673 y FN(Returns)h(true)f(if)i(the)f(terminal)g(can)g (display)f(colors;)h(otherwise,)f(it)i(returns)e(f)o(alse.)0 4820 y FD(has_ic)p FJ(\(\))208 4920 y FN(Returns)g(true)h(if)g(the)g (terminal)f(has)h(insert-)g(and)f(delete-)h(character)f(capabilities.) 24 b(This)c(function)e(is)j(included)e(for)g(historical)208 5019 y(reasons)g(only)-5 b(,)19 b(as)i(all)g(modern)d(softw)o(are)i (terminal)f(emulators)h(ha)n(v)o(e)f(such)h(capabilities.)0 5166 y FD(has_il)p FJ(\(\))208 5266 y FN(Returns)29 b(true)h(if)g(the)g (terminal)f(has)h(insert-)g(and)f(delete-line)g(capabilities,)j(or)d (can)h(simulate)g(them)f(using)h(scrolling)f(re-)208 5366 y(gions.)23 b(This)c(function)d(is)j(included)e(for)h(historical)g (reasons)f(only)-5 b(,)17 b(as)i(all)g(modern)e(softw)o(are)g(terminal) h(emulators)f(ha)n(v)o(e)h(such)p 0 5549 3901 4 v 0 5649 a FI(474)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 475 487 TeXDict begin 475 486 bop 208 83 a FN(capabilities.)0 230 y FD(has_key)p FJ(\()p FK(c)o(h)p FJ(\))208 330 y FN(T)-7 b(ak)o(es)20 b(a)h(k)o(e)o(y)e(v)n(alue)h FK(c)o(h)p FN(,)f(and)h(returns)f(true)h(if)h(the)f(current)f(terminal)g(type)h (recognizes)f(a)h(k)o(e)o(y)g(with)g(that)h(v)n(alue.)0 476 y FD(halfdelay)p FJ(\()p FK(tenths)p FJ(\))208 576 y FN(Used)f(for)g(half-delay)e(mode,)h(which)h(is)h(similar)f(to)h (cbreak)e(mode)g(in)i(that)f(characters)f(typed)g(by)h(the)h(user)f (are)g(immediately)208 676 y(a)n(v)n(ailable)g(to)g(the)h(program.)j (Ho)n(we)n(v)o(er)m(,)18 b(after)j(blocking)d(for)i FK(tenths)h FN(tenths)f(of)h(seconds,)e(an)i(e)o(xception)e(is)i(raised)f(if)h (nothing)208 775 y(has)16 b(been)f(typed.)23 b(The)15 b(v)n(alue)h(of)g FK(tenths)g FN(must)g(be)g(a)g(number)e(between)i(1)g (and)f(255.)23 b(Use)17 b FJ(nocbreak\(\))d FN(to)j(lea)n(v)o(e)e (half-delay)208 875 y(mode.)0 1022 y FD(init_color)p FJ(\()p FK(color)p 731 1022 25 4 v 27 w(number)-9 b(,)19 b(r)-9 b(,)21 b(g)o(,)f(b)p FJ(\))208 1121 y FN(Changes)15 b(the)g(de\002nition)f(of)i(a)g(color)m(,)f(taking)f(the)i(number)d(of) j(the)f(color)g(to)g(be)h(changed)e(follo)n(wed)g(by)h(three)g(RGB)h(v) n(alues)g(\(for)208 1221 y(the)j(amounts)g(of)h(red,)f(green,)g(and)g (blue)h(components\).)i(The)e(v)n(alue)f(of)h FK(color)p 2492 1221 V 29 w(number)h FN(must)f(be)g(between)f FJ(0)h FN(and)f FJ(COLORS)p FN(.)208 1321 y(Each)i(of)h FK(r)r FN(,)g FK(g)p FN(,)h FK(b)p FN(,)f(must)g(be)g(a)g(v)n(alue)f(between)g FJ(0)i FN(and)e FJ(1000)p FN(.)30 b(When)22 b FJ(init_color\(\))e FN(is)j(used,)e(all)i(occurrences)d(of)h(that)208 1420 y(color)g(on)h(the)g(screen)g(immediately)f(change)g(to)i(the)f(ne)n(w) g(de\002nition.)30 b(This)23 b(function)e(is)i(a)g(no-op)d(on)i(most)h (terminals;)g(it)g(is)208 1520 y(acti)n(v)o(e)c(only)h(if)g FJ(can_change_color\(\))d FN(returns)j FJ(1)p FN(.)0 1667 y FD(init_pair)p FJ(\()p FK(pair)p 644 1667 V 27 w(number)-9 b(,)19 b(fg)o(,)i(bg)p FJ(\))208 1766 y FN(Changes)26 b(the)g(de\002nition)g(of)g(a)i(color)n(-pair)-5 b(.)43 b(It)27 b(tak)o(es)g(three)f(ar)o(guments:)36 b(the)27 b(number)e(of)h(the)h(color)n(-pair)e(to)i(be)g(changed,)208 1866 y(the)21 b(fore)o(ground)d(color)j(number)m(,)e(and)i(the)h (background)c(color)i(number)-5 b(.)28 b(The)21 b(v)n(alue)g(of)g FK(pair)p 2965 1866 V 30 w(number)h FN(must)g(be)f(between)g FJ(1)208 1966 y FN(and)j FJ(COLOR_PAIRS)48 b(-)h(1)25 b FN(\(the)g FJ(0)g FN(color)f(pair)g(is)i(wired)e(to)h(white)g(on)f (black)g(and)h(cannot)e(be)i(changed\).)36 b(The)25 b(v)n(alue)f(of)208 2065 y FK(fg)d FN(and)g FK(bg)g FN(ar)o(guments)e(must)i(be)g(between)g FJ(0)h FN(and)e FJ(COLORS)p FN(.)h(If)g(the)g(color)n(-pair)f(w)o(as)i (pre)n(viously)d(initialized,)i(the)h(screen)f(is)208 2165 y(refreshed)d(and)i(all)h(occurrences)d(of)i(that)g(color)n(-pair) e(are)j(changed)d(to)i(the)g(ne)n(w)g(de\002nition.)0 2312 y FD(initscr)p FJ(\(\))208 2411 y FN(Initialize)h(the)h(library)-5 b(.)28 b(Returns)21 b(a)i FJ(WindowObject)d FN(which)h(represents)g (the)h(whole)f(screen.)29 b FL(Note:)e FN(If)22 b(there)f(is)i(an)f (error)208 2511 y(opening)c(the)i(terminal,)f(the)h(underlying)e (curses)i(library)f(may)h(cause)g(the)g(interpreter)f(to)h(e)o(xit.)0 2658 y FD(isendwin)p FJ(\(\))208 2758 y FN(Returns)g(true)f(if)i FJ(endwin\(\))e FN(has)i(been)e(called)h(\(that)g(is,)h(the)f(curses)g (library)f(has)i(been)e(deinitialized\).)0 2904 y FD(keyname)p FJ(\()p FK(k)q FJ(\))208 3004 y FN(Return)k(the)h(name)f(of)h(the)g(k)o (e)o(y)f(numbered)e FK(k)q FN(.)37 b(The)24 b(name)f(of)g(a)i(k)o(e)o (y)e(generating)f(printable)g(ASCII)j(character)d(is)j(the)f(k)o(e)o (y')-5 b(s)208 3104 y(character)g(.)23 b(The)c(name)g(of)g(a)h (control-k)o(e)o(y)c(combination)h(is)j(a)g(tw)o(o-character)d(string)i (consisting)g(of)g(a)h(caret)f(follo)n(wed)f(by)h(the)208 3203 y(corresponding)g(printable)i(ASCII)i(character)-5 b(.)32 b(The)22 b(name)g(of)g(an)h(alt-k)o(e)o(y)f(combination)e (\(128-255\))f(is)24 b(a)f(string)f(consisting)208 3303 y(of)d(the)i(pre\002x)e(`M-')h(follo)n(wed)e(by)i(the)g(name)g(of)g (the)g(corresponding)d(ASCII)j(character)-5 b(.)0 3450 y FD(killchar)p FJ(\(\))208 3549 y FN(Returns)19 b(the)g(user')-5 b(s)19 b(current)f(line)h(kill)h(character)-5 b(.)24 b(Under)c(U)t FH(N)t(I)t(X)i FN(operating)17 b(systems)j(this)g(is)g(a) f(property)f(of)g(the)i(controlling)208 3649 y(tty)g(of)g(the)g(curses) g(program,)e(and)i(is)h(not)f(set)h(by)f(the)g(curses)g(library)f (itself.)0 3796 y FD(longname)p FJ(\(\))208 3896 y FN(Returns)i(a)h (string)g(containing)d(the)j(terminfo)e(long)h(name)g(\002eld)h (describing)e(the)i(current)e(terminal.)29 b(The)21 b(maximum)f(length) 208 3995 y(of)f(a)i(v)o(erbose)e(description)f(is)k(128)d(characters.) 24 b(It)c(is)h(de\002ned)f(only)f(after)h(the)g(call)h(to)f FJ(initscr\(\))p FN(.)0 4142 y FD(meta)p FJ(\()p FK(yes)p FJ(\))208 4242 y FN(If)g FK(yes)g FN(is)i(1,)e(allo)n(w)g(8-bit)f (characters)g(to)i(be)f(input.)k(If)c FK(yes)h FN(is)g(0,)f(allo)n(w)g (only)g(7-bit)f(chars.)0 4389 y FD(mouseinterval)p FJ(\()p FK(interval)p FJ(\))208 4488 y FN(Sets)h(the)g(maximum)e(time)i(in)g (milliseconds)f(that)g(can)h(elapse)g(between)e(press)i(and)f(release)h (e)n(v)o(ents)f(in)h(order)e(for)h(them)h(to)g(be)208 4588 y(recognized)i(as)j(a)f(click,)i(and)d(returns)h(the)g(pre)n (vious)f(interv)n(al)g(v)n(alue.)37 b(The)24 b(def)o(ault)f(v)n(alue)h (is)h(200)f(msec,)h(or)f(one)g(\002fth)g(of)g(a)208 4687 y(second.)0 4834 y FD(mousemask)p FJ(\()p FK(mousemask)q FJ(\))208 4934 y FN(Sets)h(the)f(mouse)g(e)n(v)o(ents)f(to)h(be)h (reported,)e(and)g(returns)h(a)g(tuple)g FJ(\()p FK(availmask)q FJ(,)49 b FK(oldmask)q FJ(\))p FN(.)36 b FK(availmask)25 b FN(indicates)f(which)208 5034 y(of)19 b(the)i(speci\002ed)f(mouse)f (e)n(v)o(ents)h(can)g(be)g(reported;)e(on)i(complete)f(f)o(ailure)h(it) h(returns)e(0.)25 b FK(oldmask)c FN(is)g(the)g(pre)n(vious)d(v)n(alue)i (of)208 5133 y(the)g(gi)n(v)o(en)f(windo)n(w')-5 b(s)19 b(mouse)h(e)n(v)o(ent)f(mask.)25 b(If)20 b(this)h(function)d(is)j(ne)n (v)o(er)e(called,)h(no)f(mouse)h(e)n(v)o(ents)g(are)g(e)n(v)o(er)f (reported.)0 5280 y FD(napms)p FJ(\()p FK(ms)p FJ(\))208 5380 y FN(Sleep)h(for)f FK(ms)i FN(milliseconds.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e(char)o(acter-cell)f(displa)n(ys) 1487 b(475)p eop end %%Page: 476 488 TeXDict begin 476 487 bop 0 83 a FD(newpad)p FJ(\()p FK(nlines,)19 b(ncols)p FJ(\))208 183 y FN(Creates)i(and)g(returns)g(a) g(pointer)g(to)g(a)h(ne)n(w)f(pad)g(data)g(structure)f(with)i(the)f(gi) n(v)o(en)f(number)g(of)h(lines)h(and)f(columns.)27 b(A)22 b(pad)f(is)208 282 y(returned)d(as)j(a)f(windo)n(w)g(object.)208 415 y(A)i(pad)f(is)i(lik)o(e)g(a)f(windo)n(w)-5 b(,)21 b(e)o(xcept)g(that)h(it)g(is)h(not)f(restricted)f(by)h(the)g(screen)f (size,)i(and)f(is)h(not)e(necessarily)h(associated)f(with)208 515 y(a)g(particular)e(part)i(of)f(the)h(screen.)26 b(P)o(ads)21 b(can)g(be)g(used)f(when)g(a)i(lar)o(ge)d(windo)n(w)h(is)i(needed,)d (and)i(only)f(a)h(part)f(of)h(the)g(windo)n(w)208 614 y(will)i(be)h(on)e(the)h(screen)g(at)h(one)e(time.)34 b(Automatic)23 b(refreshes)f(of)h(pads)g(\(such)f(as)i(from)e (scrolling)h(or)f(echoing)g(of)h(input\))f(do)208 714 y(not)g(occur)-5 b(.)31 b(The)22 b FJ(refresh\(\))f FN(and)h FJ(noutrefresh\(\))f FN(methods)g(of)h(a)h(pad)f(require)f(6)i(ar)o (guments)d(to)j(specify)e(the)i(part)208 814 y(of)18 b(the)i(pad)e(to)h(be)g(displayed)f(and)h(the)g(location)f(on)h(the)g (screen)g(to)g(be)g(used)g(for)f(the)h(display)-5 b(.)24 b(The)19 b(ar)o(guments)e(are)i(pminro)n(w)-5 b(,)208 913 y(pmincol,)19 b(sminro)n(w)-5 b(,)20 b(smincol,)h(smaxro)n(w)-5 b(,)20 b(smaxcol;)h(the)g(p)g(ar)o(guments)e(refer)i(to)g(the)g(upper)f (left)i(corner)d(of)i(the)g(pad)g(re)o(gion)208 1013 y(to)26 b(be)f(displayed)g(and)g(the)h(s)h(ar)o(guments)d(de\002ne)h(a) h(clipping)f(box)g(on)g(the)h(screen)f(within)h(which)f(the)h(pad)g(re) o(gion)e(is)j(to)f(be)208 1112 y(displayed.)0 1259 y FD(newwin)p FJ(\()p FC([)p FK(nlines,)18 b(ncols,)12 b FC(])20 b FK(be)m(gin)p 1085 1259 25 4 v 28 w(y)-5 b(,)21 b(be)m(gin)p 1370 1259 V 28 w(x)p FJ(\))208 1359 y FN(Return)45 b(a)i(ne)n(w)f(windo)n(w)-5 b(,)51 b(whose)46 b(left-upper)f(corner)g(is)i(at)g FJ(\()p FK(be)m(gin)p 2421 1359 V 28 w(y)p FJ(,)i FK(be)m(gin)p 2768 1359 V 28 w(x)p FJ(\))p FN(,)k(and)46 b(whose)g(height/width)f(is)208 1459 y FK(nlines)p FN(/)p FK(ncols)p FN(.)208 1591 y(By)20 b(def)o(ault,)f(the)i(windo)n(w)e(will)i(e)o(xtend)e(from)g(the)h (speci\002ed)g(position)f(to)i(the)f(lo)n(wer)f(right)h(corner)f(of)h (the)g(screen.)0 1738 y FD(nl)p FJ(\(\))208 1838 y FN(Enter)28 b(ne)n(wline)g(mode.)50 b(This)29 b(mode)f(translates)h(the)g(return)f (k)o(e)o(y)g(into)h(ne)n(wline)f(on)g(input,)i(and)f(translates)g(ne)n (wline)f(into)208 1938 y(return)19 b(and)g(line-feed)g(on)h(output.)j (Ne)n(wline)d(mode)g(is)h(initially)f(on.)0 2084 y FD(nocbreak)p FJ(\(\))208 2184 y FN(Lea)n(v)o(e)f(cbreak)g(mode.)24 b(Return)c(to)g(normal)f(\223cook)o(ed\224)g(mode)g(with)h(line)h(b)n (uf)n(fering.)0 2331 y FD(noecho)p FJ(\(\))208 2431 y FN(Lea)n(v)o(e)e(echo)h(mode.)k(Echoing)18 b(of)i(input)g(characters)f (is)i(turned)e(of)n(f.)0 2577 y FD(nonl)p FJ(\(\))208 2677 y FN(Lea)n(v)o(e)25 b(ne)n(wline)f(mode.)40 b(Disable)26 b(translation)e(of)i(return)e(into)h(ne)n(wline)g(on)g(input,)h(and)f (disable)g(lo)n(w-le)n(v)o(el)f(translation)h(of)208 2777 y(ne)n(wline)20 b(into)g(ne)n(wline/return)f(on)h(output)f(\(b)n (ut)i(this)g(does)g(not)f(change)f(the)i(beha)n(vior)e(of)i FJ(addch\('\\n'\))p FN(,)e(which)h(al)o(w)o(ays)208 2876 y(does)26 b(the)g(equi)n(v)n(alent)e(of)i(return)f(and)h(line)g(feed)g (on)g(the)g(virtual)g(screen\).)42 b(W)m(ith)26 b(translation)g(of)n (f,)h(curses)f(can)g(sometimes)208 2976 y(speed)19 b(up)h(v)o(ertical)g (motion)f(a)h(little;)h(also,)g(it)g(will)f(be)h(able)f(to)g(detect)g (the)g(return)f(k)o(e)o(y)h(on)g(input.)0 3123 y FD(noqiflush)p FJ(\(\))208 3222 y FN(When)j(the)h(noqi\003ush)f(routine)g(is)i(used,)f (normal)f(\003ush)h(of)g(input)f(and)h(output)e(queues)i(associated)f (with)i(the)f(INTR,)g(Q)o(UIT)208 3322 y(and)f(SUSP)j(characters)d (will)i(not)f(be)h(done.)36 b(Y)-9 b(ou)24 b(may)g(w)o(ant)g(to)h(call) g FJ(noqiflush\(\))e FN(in)h(a)h(signal)f(handler)f(if)i(you)e(w)o(ant) 208 3422 y(output)c(to)h(continue)f(as)h(though)f(the)h(interrupt)f (had)g(not)h(occurred,)e(after)i(the)g(handler)f(e)o(xits.)0 3569 y FD(noraw)p FJ(\(\))208 3668 y FN(Lea)n(v)o(e)g(ra)o(w)h(mode.)k (Return)c(to)g(normal)f(\223cook)o(ed\224)g(mode)g(with)h(line)g(b)n (uf)n(fering.)0 3815 y FD(pair_content)p FJ(\()p FK(pair)p 794 3815 V 27 w(number)r FJ(\))208 3915 y FN(Returns)g(a)g(tuple)g FJ(\()p FK(fg)p FJ(,)49 b FK(bg)p FJ(\))20 b FN(containing)e(the)i (colors)g(for)f(the)h(requested)f(color)h(pair)-5 b(.)25 b(The)19 b(v)n(alue)h(of)g FK(pair)p 3339 3915 V 29 w(number)h FN(must)g(be)208 4014 y(between)e FJ(1)i FN(and)e FJ(COLOR_PAIRS)48 b(-)i(1)p FN(.)0 4161 y FD(pair_number)p FJ(\()p FK(attr)r FJ(\))208 4261 y FN(Returns)21 b(the)i(number)d(of)i(the)g(color)n (-pair)e(set)j(by)f(the)g(attrib)n(ute)f(v)n(alue)h FK(attr)r FN(.)31 b FJ(color_pair\(\))20 b FN(is)j(the)f(counterpart)e(to)i(this) 208 4360 y(function.)0 4507 y FD(putp)p FJ(\()p FK(string)p FJ(\))208 4607 y FN(Equi)n(v)n(alent)16 b(to)j FJ(tputs\(str,)47 b(1,)j(putchar\))p FN(;)18 b(emits)h(the)f(v)n(alue)g(of)g(a)h (speci\002ed)f(terminfo)e(capability)i(for)g(the)g(current)208 4707 y(terminal.)24 b(Note)c(that)g(the)g(output)f(of)h(putp)g(al)o(w)o (ays)g(goes)g(to)h(standard)e(output.)0 4853 y FD(qiflush)p FJ(\()g FC([)p FK(\003a)o(g)12 b FC(])19 b FJ(\))208 4953 y FN(If)i FK(\003a)o(g)h FN(is)g(f)o(alse,)h(the)f(ef)n(fect)f(is) i(the)f(same)g(as)h(calling)e FJ(noqiflush\(\))p FN(.)29 b(If)22 b FK(\003a)o(g)f FN(is)i(true,)e(or)h(no)g(ar)o(gument)d(is)k (pro)o(vided,)d(the)208 5053 y(queues)f(will)i(be)f(\003ushed)g(when)f (these)h(control)f(characters)h(are)g(read.)0 5200 y FD(raw)p FJ(\(\))208 5299 y FN(Enter)d(ra)o(w)i(mode.)k(In)18 b(ra)o(w)h(mode,)e(normal)h(line)g(b)n(uf)n(fering)f(and)h(processing)f (of)h(interrupt,)f(quit,)i(suspend,)e(and)h(\003o)n(w)h(control)208 5399 y(k)o(e)o(ys)g(are)i(turned)d(of)n(f;)i(characters)f(are)h (presented)f(to)i(curses)f(input)f(functions)g(one)h(by)f(one.)p 0 5549 3901 4 v 0 5649 a FI(476)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 477 489 TeXDict begin 477 488 bop 0 83 a FD(reset_prog_mode)p FJ(\(\))208 183 y FN(Restores)20 b(the)g(terminal)g(to)g (\223program\224)e(mode,)h(as)i(pre)n(viously)d(sa)n(v)o(ed)i(by)g FJ(def_prog_mode\(\))p FN(.)0 330 y FD(reset_shell_mode)p FJ(\(\))208 429 y FN(Restores)g(the)g(terminal)g(to)g(\223shell\224)h (mode,)e(as)h(pre)n(viously)f(sa)n(v)o(ed)h(by)f FJ(def_shell_mode\(\)) p FN(.)0 576 y FD(setsyx)p FJ(\()p FK(y)-5 b(,)19 b(x)p FJ(\))208 676 y FN(Sets)i(the)f(virtual)f(screen)h(cursor)f(to)i FK(y)p FN(,)f FK(x)p FN(.)26 b(If)20 b FK(y)g FN(and)g FK(x)h FN(are)f(both)f(-1,)h(then)g(lea)n(v)o(eok)f(is)i(set.)0 823 y FD(setupterm)p FJ(\()p FC([)p FK(termstr)-9 b(,)19 b(fd)14 b FC(])p FJ(\))208 922 y FN(Initializes)25 b(the)g(terminal.)38 b FK(termstr)29 b FN(is)d(a)f(string)g(gi)n(ving)f(the)h(terminal)f (name;)j(if)e(omitted,)g(the)g(v)n(alue)g(of)f(the)h(TERM)h(en)m(vi-) 208 1022 y(ronment)20 b(v)n(ariable)h(will)i(be)g(used.)31 b FK(fd)24 b FN(is)f(the)g(\002le)g(descriptor)e(to)h(which)g(an)o(y)f (initialization)h(sequences)f(will)i(be)g(sent;)g(if)g(not)208 1121 y(supplied,)18 b(the)j(\002le)f(descriptor)f(for)h FJ(sys.stdout)f FN(will)i(be)f(used.)0 1268 y FD(start_color)p FJ(\(\))208 1368 y FN(Must)f(be)g(called)f(if)i(the)f(programmer)c(w)o (ants)20 b(to)f(use)g(colors,)f(and)h(before)e(an)o(y)i(other)f(color)g (manipulation)e(routine)i(is)i(called.)208 1468 y(It)g(is)h(good)e (practice)g(to)i(call)f(this)h(routine)e(right)h(after)g FJ(initscr\(\))p FN(.)208 1600 y FJ(start_color\(\))c FN(initializes)j(eight)f(basic)h(colors)e(\(black,)h(red,)g(green,)f (yello)n(w)-5 b(,)18 b(blue,)g(magenta,)f(c)o(yan,)h(and)g(white\),)g (and)208 1700 y(tw)o(o)k(global)g(v)n(ariables)f(in)i(the)f FJ(curses)g FN(module,)f FJ(COLORS)h FN(and)g FJ(COLOR_PAIRS)p FN(,)f(containing)f(the)j(maximum)d(number)208 1800 y(of)i(colors)g (and)g(color)n(-pairs)g(the)h(terminal)f(can)g(support.)31 b(It)23 b(also)h(restores)e(the)h(colors)f(on)g(the)h(terminal)f(to)h (the)g(v)n(alues)f(the)o(y)208 1899 y(had)d(when)h(the)g(terminal)f(w)o (as)i(just)g(turned)e(on.)0 2046 y FD(termattrs)p FJ(\(\))208 2146 y FN(Returns)h(a)g(logical)g(OR)h(of)f(all)h(video)f(attrib)n (utes)g(supported)e(by)i(the)g(terminal.)25 b(This)20 b(information)e(is)j(useful)f(when)g(a)h(curses)208 2245 y(program)d(needs)h(complete)g(control)g(o)o(v)o(er)g(the)h(appearance) f(of)g(the)i(screen.)0 2392 y FD(termname)p FJ(\(\))208 2492 y FN(Returns)f(the)g(v)n(alue)f(of)h(the)g(en)m(vironment)e(v)n (ariable)h(TERM,)h(truncated)e(to)j(14)f(characters.)0 2639 y FD(tigetflag)p FJ(\()p FK(capname)p FJ(\))208 2738 y FN(Returns)g(the)g(v)n(alue)g(of)g(the)g(Boolean)g(capability)f (corresponding)e(to)j(the)h(terminfo)e(capability)g(name)h FK(capname)p FN(.)j(The)d(v)n(alue)208 2838 y FJ(-1)g FN(is)i(returned)c(if)j FK(capname)e FN(is)i(not)g(a)g(Boolean)e (capability)-5 b(,)19 b(or)i FJ(0)f FN(if)h(it)g(is)h(canceled)d(or)i (absent)f(from)f(the)i(terminal)f(descrip-)208 2938 y(tion.)0 3084 y FD(tigetnum)p FJ(\()p FK(capname)p FJ(\))208 3184 y FN(Returns)g(the)h(v)n(alue)f(of)g(the)g(numeric)g(capability)f (corresponding)e(to)k(the)g(terminfo)e(capability)h(name)g FK(capname)p FN(.)k(The)c(v)n(alue)208 3284 y FJ(-2)32 b FN(is)i(returned)c(if)j FK(capname)e FN(is)j(not)e(a)h(numeric)e (capability)-5 b(,)34 b(or)e FJ(-1)h FN(if)g(it)g(is)g(canceled)f(or)g (absent)g(from)g(the)g(terminal)208 3383 y(description.)0 3530 y FD(tigetstr)p FJ(\()p FK(capname)p FJ(\))208 3630 y FN(Returns)c(the)h(v)n(alue)e(of)i(the)f(string)g(capability)g (corresponding)d(to)k(the)f(terminfo)f(capability)h(name)g FK(capname)p FN(.)48 b FJ(None)29 b FN(is)208 3729 y(returned)18 b(if)i FK(capname)f FN(is)i(not)f(a)g(string)g(capability)-5 b(,)19 b(or)h(is)h(canceled)e(or)h(absent)g(from)f(the)h(terminal)g (description.)0 3876 y FD(tparm)p FJ(\()p FK(str)r FC([)p FK(,...)12 b FC(])p FJ(\))208 3976 y FN(Instantiates)k(the)h(string)g FK(str)j FN(with)e(the)f(supplied)f(parameters,)g(where)h FK(str)j FN(should)c(be)h(a)g(parameterized)e(string)i(obtained)f(from) 208 4076 y(the)h(terminfo)f(database.)23 b(E.g.)h FJ (tparm\(tigetstr\("cup"\),)45 b(5,)50 b(3\))17 b FN(could)f(result)i (in)f FJ('\\033[6;4H')p FN(,)f(the)h(e)o(xact)208 4175 y(result)j(depending)d(on)j(terminal)g(type.)0 4322 y FD(typeahead)p FJ(\()p FK(fd)r FJ(\))208 4422 y FN(Speci\002es)j(that)g (the)g(\002le)h(descriptor)e FK(fd)j FN(be)f(used)e(for)h(typeahead)e (checking.)32 b(If)23 b FK(fd)j FN(is)e FJ(-1)p FN(,)g(then)e(no)h (typeahead)e(checking)h(is)208 4521 y(done.)208 4654 y(The)g(curses)h(library)f(does)g(\223line-break)o(out)e (optimization\224)h(by)i(looking)e(for)h(typeahead)f(periodically)g (while)i(updating)e(the)208 4754 y(screen.)j(If)19 b(input)g(is)h (found,)e(and)h(it)h(is)g(coming)e(from)h(a)h(tty)-5 b(,)19 b(the)g(current)f(update)h(is)h(postponed)d(until)j(refresh)e (or)h(doupdate)f(is)208 4853 y(called)e(again,)g(allo)n(wing)f(f)o (aster)h(response)g(to)g(commands)f(typed)g(in)i(adv)n(ance.)22 b(This)16 b(function)f(allo)n(ws)i(specifying)d(a)j(dif)n(ferent)208 4953 y(\002le)j(descriptor)f(for)h(typeahead)e(checking.)0 5100 y FD(unctrl)p FJ(\()p FK(c)o(h)p FJ(\))208 5200 y FN(Returns)25 b(a)h(string)f(which)g(is)i(a)e(printable)g (representation)e(of)i(the)h(character)e FK(c)o(h)p FN(.)41 b(Control)25 b(characters)f(are)i(displayed)e(as)i(a)208 5299 y(caret)20 b(follo)n(wed)e(by)i(the)g(character)m(,)f(for)g(e)o (xample)g(as)i FJ(\210C)p FN(.)f(Printing)g(characters)f(are)h(left)g (as)h(the)o(y)f(are.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e (char)o(acter-cell)f(displa)n(ys)1487 b(477)p eop end %%Page: 478 490 TeXDict begin 478 489 bop 0 83 a FD(ungetch)p FJ(\()p FK(c)o(h)p FJ(\))208 183 y FN(Push)20 b FK(c)o(h)g FN(so)g(the)g(ne)o (xt)g FJ(getch\(\))f FN(will)i(return)e(it.)26 b FL(Note:)e FN(Only)c(one)g FK(c)o(h)g FN(can)g(be)g(pushed)f(before)f FJ(getch\(\))i FN(is)h(called.)0 330 y FD(ungetmouse)p FJ(\()p FK(id,)d(x,)i(y)-5 b(,)21 b(z,)g(bstate)p FJ(\))208 429 y FN(Push)f(a)g FJ(KEY_MOUSE)f FN(e)n(v)o(ent)h(onto)f(the)h(input) g(queue,)f(associating)g(the)h(gi)n(v)o(en)f(state)i(data)f(with)h(it.) 0 576 y FD(use_env)p FJ(\()p FK(\003a)o(g)p FJ(\))208 676 y FN(If)e(used,)g(this)h(function)e(should)g(be)h(called)h(before)e FJ(initscr\(\))g FN(or)h(ne)n(wterm)g(are)g(called.)24 b(When)c FK(\003a)o(g)e FN(is)j(f)o(alse,)f(the)f(v)n(alues)208 775 y(of)i(lines)h(and)f(columns)g(speci\002ed)g(in)h(the)g(terminfo)e (database)h(will)h(be)g(used,)g(e)n(v)o(en)e(if)i(en)m(vironment)d(v)n (ariables)i(LINES)g(and)208 875 y(COLUMNS)e(\(used)g(by)g(def)o(ault\)) g(are)g(set,)h(or)g(if)f(curses)h(is)g(running)e(in)h(a)h(windo)n(w)f (\(in)g(which)g(case)h(def)o(ault)e(beha)n(vior)g(w)o(ould)208 975 y(be)i(to)g(use)g(the)h(windo)n(w)e(size)i(if)f(LINES)g(and)g (COLUMNS)g(are)h(not)e(set\).)0 1121 y FD(use_default_colors)p FJ(\(\))208 1221 y FN(Allo)n(w)j(use)h(of)f(def)o(ault)f(v)n(alues)h (for)g(colors)g(on)g(terminals)g(supporting)e(this)j(feature.)30 b(Use)23 b(this)g(to)g(support)e(transparenc)o(y)e(in)208 1321 y(your)25 b(application.)45 b(The)26 b(def)o(ault)h(color)f(is)i (assigned)f(to)g(the)g(color)f(number)g(-1.)45 b(After)27 b(calling)g(this)g(function,)g FJ(init_-)208 1420 y(pair\(x,)48 b(curses.COLOR_RED,)f(-1\))18 b FN(initializes,)h(for)f(instance,)g (color)g(pair)g FK(x)h FN(to)f(a)h(red)f(fore)o(ground)d(color)j(on)g (the)208 1520 y(def)o(ault)h(background.)0 1805 y Fv(14.7.2)101 b(Windo)o(w)28 b(Objects)0 2008 y FN(W)m(indo)n(w)19 b(objects,)h(as)h(returned)d(by)i FJ(initscr\(\))f FN(and)h FJ(newwin\(\))f FN(abo)o(v)o(e,)f(ha)n(v)o(e)i(the)g(follo)n(wing)f (methods:)0 2155 y FD(addch)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)12 b FC(])20 b FK(c)o(h)p FC([)p FK(,)g(attr)14 b FC(])p FJ(\))208 2254 y FL(Note:)31 b FN(A)24 b FK(c)o(har)o(acter)f FN(means)g(a)i(C)f(character)f(\(an)i FH(A)t(S)t(C)t(I)t(I)i FN(code\),)d(rather)f(then)g(a)h(Python)f(character)f(\(a)i(string)g (of)f(length)g(1\).)208 2354 y(\(This)17 b(note)g(is)i(true)e(whene)n (v)o(er)f(the)h(documentation)e(mentions)h(a)j(character)-5 b(.\))22 b(The)c(b)n(uiltin)f FJ(ord\(\))g FN(is)i(handy)d(for)h(con)m (v)o(e)o(ying)208 2453 y(strings)j(to)g(codes.)208 2586 y(P)o(aint)i(character)g FK(c)o(h)g FN(at)i FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))23 b FN(with)g(attrib)n(utes)g FK(attr)r FN(,)h(o)o(v)o(erwriting)c(an)o(y)i(character)g(pre)n (viously)f(painter)g(at)j(that)f(location.)208 2686 y(By)d(def)o(ault,) f(the)i(character)e(position)g(and)h(attrib)n(utes)g(are)g(the)g (current)f(settings)h(for)g(the)g(windo)n(w)f(object.)0 2833 y FD(addnstr)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)12 b FC(])20 b FK(str)-9 b(,)21 b(n)p FC([)p FK(,)f(attr)14 b FC(])p FJ(\))208 2932 y FN(P)o(aint)25 b(at)g(most)g FK(n)h FN(characters)e(of)h(the)g(string)g FK(str)j FN(at)d FJ(\()p FK(y)p FJ(,)50 b FK(x)p FJ(\))25 b FN(with)h(attrib)n(utes)f FK(attr)r FN(,)h(o)o(v)o(erwriting)d(an)o(ything)g(pre)n(viously)g(on) 208 3032 y(the)d(display)-5 b(.)0 3179 y FD(addstr)p FJ(\()p FC([)p FK(y)g(,)19 b(x,)12 b FC(])20 b FK(str)r FC([)p FK(,)h(attr)14 b FC(])p FJ(\))208 3279 y FN(P)o(aint)20 b(the)g(string)g FK(str)j FN(at)e FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))21 b FN(with)f(attrib)n(utes)g FK(attr)r FN(,)h(o)o(v)o(erwriting)c(an)o(ything)h(pre)n(viously)h(on)g(the)i (display)-5 b(.)0 3425 y FD(attroff)p FJ(\()p FK(attr)r FJ(\))208 3525 y FN(Remo)o(v)o(e)19 b(attrib)n(ute)g FK(attr)k FN(from)c(the)h(\223background\224)d(set)k(applied)e(to)h (all)h(writes)g(to)f(the)g(current)f(windo)n(w)-5 b(.)0 3672 y FD(attron)p FJ(\()p FK(attr)r FJ(\))208 3772 y FN(Add)19 b(attrib)n(ute)h FK(attr)j FN(from)c(the)h (\223background\224)c(set)21 b(applied)f(to)g(all)h(writes)f(to)h(the)f (current)f(windo)n(w)-5 b(.)0 3918 y FD(attrset)p FJ(\()p FK(attr)r FJ(\))208 4018 y FN(Set)20 b(the)h(\223background\224)16 b(set)21 b(of)f(attrib)n(utes)g(to)g FK(attr)r FN(.)26 b(This)20 b(set)h(is)g(initially)f(0)h(\(no)e(attrib)n(utes\).)0 4165 y FD(bkgd)p FJ(\()p FK(c)o(h)p FC([)p FK(,)g(attr)14 b FC(])p FJ(\))208 4265 y FN(Sets)20 b(the)g(background)c(property)i (of)h(the)h(windo)n(w)f(to)h(the)f(character)g FK(c)o(h)p FN(,)g(with)h(attrib)n(utes)g FK(attr)r FN(.)25 b(The)19 b(change)g(is)h(then)g(applied)208 4364 y(to)g(e)n(v)o(ery)f(character) g(position)g(in)h(that)h(windo)n(w:)349 4530 y FM(\017)o FN(The)f(attrib)n(ute)g(of)g(e)n(v)o(ery)f(character)g(in)h(the)g (windo)n(w)f(is)i(changed)e(to)h(the)g(ne)n(w)g(background)d(attrib)n (ute.)349 4663 y FM(\017)o FN(Where)n(v)o(er)i(the)h(former)f (background)d(character)j(appears,)g(it)i(is)h(changed)c(to)i(the)g(ne) n(w)g(background)d(character)-5 b(.)0 4810 y FD(bkgdset)p FJ(\()p FK(c)o(h)p FC([)p FK(,)18 b(attr)c FC(])p FJ(\))208 4910 y FN(Sets)29 b(the)g(windo)n(w')-5 b(s)28 b(background.)48 b(A)29 b(windo)n(w')-5 b(s)28 b(background)d(consists)30 b(of)e(a)i(character)d(and)h(an)o(y)g(combination)f(of)h(at-)208 5009 y(trib)n(utes.)c(The)17 b(attrib)n(ute)h(part)g(of)g(the)g (background)c(is)19 b(combined)d(\(OR'ed\))h(with)i(all)f(non-blank)e (characters)h(that)h(are)g(written)208 5109 y(into)j(the)h(windo)n(w)-5 b(.)28 b(Both)22 b(the)g(character)e(and)i(attrib)n(ute)f(parts)h(of)f (the)h(background)d(are)i(combined)f(with)i(the)g(blank)f(charac-)208 5208 y(ters.)34 b(The)23 b(background)d(becomes)i(a)i(property)d(of)i (the)g(character)f(and)h(mo)o(v)o(es)f(with)i(the)f(character)f (through)f(an)o(y)h(scrolling)208 5308 y(and)d(insert/delete)h (line/character)e(operations.)p 0 5549 3901 4 v 0 5649 a FI(478)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 479 491 TeXDict begin 479 490 bop 0 83 a FD(border)p FJ(\()p FC([)p FK(ls)p FC([)p FK(,)19 b(r)o(s)p FC([)p FK(,)i(ts)p FC([)p FK(,)g(bs)p FC([)p FK(,)f(tl)p FC([)p FK(,)h(tr)r FC([)p FK(,)f(bl)p FC([)p FK(,)g(br)14 b FC(])e(])g(])g(])g(])g(])g(])g (])p FJ(\))208 183 y FN(Dra)o(w)20 b(a)g(border)f(around)f(the)j(edges) f(of)g(the)g(windo)n(w)-5 b(.)24 b(Each)c(parameter)f(speci\002es)h (the)h(character)e(to)h(use)h(for)f(a)g(speci\002c)h(part)208 282 y(of)16 b(the)g(border;)g(see)h(the)g(table)f(belo)n(w)g(for)g (more)g(details.)24 b(The)16 b(characters)f(can)i(be)f(speci\002ed)g (as)h(inte)o(gers)f(or)g(as)h(one-character)208 382 y(strings.)208 515 y FL(Note:)39 b FN(A)29 b FJ(0)f FN(v)n(alue)f(for)h(an)o(y)f (parameter)f(will)j(cause)f(the)g(def)o(ault)f(character)f(to)i(be)g (used)g(for)f(that)h(parameter)-5 b(.)47 b(K)n(e)o(yw)o(ord)208 614 y(parameters)19 b(can)h FK(not)f FN(be)h(used.)25 b(The)20 b(def)o(aults)g(are)g(listed)h(in)f(this)h(table:)1133 744 y FL(P)o(arameter)p 1559 773 4 100 v 98 w(Description)p 2325 773 V 355 w(Default)f(v)o(alue)p 1084 777 1941 4 v 1133 847 a FK(ls)p 1559 876 4 100 v 422 w FN(Left)g(side)p 2325 876 V 473 w FJ(ACS_VLINE)1133 946 y FK(r)o(s)p 1559 976 V 414 w FN(Right)h(side)p 2325 976 V 426 w FJ(ACS_VLINE)1133 1046 y FK(ts)p 1559 1076 V 422 w FN(T)-7 b(op)p 2325 1076 V 638 w FJ(ACS_HLINE)1133 1145 y FK(bs)p 1559 1175 V 403 w FN(Bottom)p 2325 1175 V 516 w FJ(ACS_HLINE)1133 1245 y FK(tl)p 1559 1275 V 431 w FN(Upper)n(-left)19 b(corner)p 2325 1275 V 187 w FJ(ACS_ULCORNER)1133 1345 y FK(tr)p 1559 1375 V 422 w FN(Upper)n(-right)f(corner)p 2325 1375 V 141 w FJ(ACS_URCORNER)1133 1444 y FK(bl)p 1559 1474 V 412 w FN(Bottom-left)h(corner)p 2325 1474 V 144 w FJ(ACS_LLCORNER)1133 1544 y FK(br)p 1559 1574 V 403 w FN(Bottom-right)g(corner)p 2325 1574 V 97 w FJ(ACS_LRCORNER)0 1709 y FD(box)p FJ(\()p FC([)p FK(vertc)o(h,)g(hor)m(c)o(h)12 b FC(])p FJ(\))208 1809 y FN(Similar)20 b(to)h FJ(border\(\))p FN(,)f(b)n(ut)g(both)g FK(ls)i FN(and)e FK(r)o(s)i FN(are)e FK(vertc)o(h)h FN(and)f(both)g FK(ts)h FN(and)f(bs)h(are)g FK(hor)m(c)o(h)p FN(.)k(The)20 b(def)o(ault)g(corner)g(characters)208 1908 y(are)g(al)o(w)o(ays)g(used)g(by)g(this)h(function.)0 2055 y FD(clear)p FJ(\(\))208 2155 y FN(Lik)o(e)f FJ(erase\(\))p FN(,)f(b)n(ut)h(also)h(causes)f(the)g(whole)g(windo)n(w)f(to)h(be)h (repainted)d(upon)h(ne)o(xt)g(call)i(to)f FJ(refresh\(\))p FN(.)0 2302 y FD(clearok)p FJ(\()p FK(yes)p FJ(\))208 2401 y FN(If)g FK(yes)g FN(is)i(1,)e(the)g(ne)o(xt)f(call)i(to)f FJ(refresh\(\))f FN(will)i(clear)f(the)g(windo)n(w)g(completely)-5 b(.)0 2548 y FD(clrtobot)p FJ(\(\))208 2648 y FN(Erase)24 b(from)f(cursor)g(to)i(the)f(end)g(of)g(the)g(windo)n(w:)33 b(all)25 b(lines)f(belo)n(w)g(the)g(cursor)g(are)g(deleted,)g(and)g (then)g(the)g(equi)n(v)n(alent)f(of)208 2748 y FJ(clrtoeol\(\))18 b FN(is)k(performed.)0 2894 y FD(clrtoeol)p FJ(\(\))208 2994 y FN(Erase)e(from)f(cursor)g(to)h(the)h(end)e(of)h(the)g(line.)0 3141 y FD(cursyncup)p FJ(\(\))208 3241 y FN(Updates)k(the)h(current)e (cursor)h(position)g(of)h(all)g(the)g(ancestors)f(of)h(the)g(windo)n(w) f(to)h(re\003ect)g(the)f(current)g(cursor)g(position)g(of)208 3340 y(the)c(windo)n(w)-5 b(.)0 3487 y FD(delch)p FJ(\()p FC([)p FK(y)g(,)19 b(x)12 b FC(])p FJ(\))208 3587 y FN(Delete)20 b(an)o(y)f(character)g(at)i FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))p FN(.)0 3734 y FD(deleteln)p FJ(\(\))208 3833 y FN(Delete)20 b(the)g(line)g(under)f(the)h(cursor)-5 b(.)25 b(All)c(follo)n(wing)d(lines)j(are)f(mo)o(v)o(ed)e(up)i(by)g(1)g (line.)0 3980 y FD(derwin)p FJ(\()p FC([)p FK(nlines,)e(ncols,)12 b FC(])20 b FK(be)m(gin)p 1085 3980 25 4 v 28 w(y)-5 b(,)21 b(be)m(gin)p 1370 3980 V 28 w(x)p FJ(\))208 4080 y FN(An)i(abbre)n(viation)f(for)h(\223deri)n(v)o(e)g(windo)n(w\224,)g FJ(derwin\(\))g FN(is)i(the)f(same)g(as)h(calling)e FJ(subwin\(\))p FN(,)h(e)o(xcept)f(that)h FK(be)m(gin)p 3696 4080 V 28 w(y)g FN(and)208 4179 y FK(be)m(gin)p 396 4179 V 28 w(x)18 b FN(are)f(relati)n(v)o(e)f(to)i(the)f(origin)g(of)g(the)g(windo)n(w)-5 b(,)16 b(rather)h(than)g(relati)n(v)o(e)f(to)i(the)f(entire)g(screen.) 24 b(Returns)17 b(a)h(windo)n(w)e(object)208 4279 y(for)j(the)h(deri)n (v)o(ed)f(windo)n(w)-5 b(.)0 4426 y FD(echochar)p FJ(\()p FK(c)o(h)p FC([)p FK(,)18 b(attr)c FC(])p FJ(\))208 4525 y FN(Add)19 b(character)g FK(c)o(h)h FN(with)g(attrib)n(ute)g FK(attr)r FN(,)h(and)e(immediately)g(call)i FJ(refresh\(\))e FN(on)h(the)g(windo)n(w)-5 b(.)0 4672 y FD(enclose)p FJ(\()p FK(y)g(,)19 b(x)p FJ(\))208 4772 y FN(T)-6 b(ests)30 b(whether)e(the)i(gi)n(v)o(en)e(pair)h(of)g(screen-relati)n(v)o(e)e (character)n(-cell)h(coordinates)f(are)j(enclosed)e(by)h(the)g(gi)n(v)o (en)f(windo)n(w)-5 b(,)208 4872 y(returning)19 b(true)j(or)f(f)o(alse.) 30 b(It)22 b(is)h(useful)e(for)h(determining)d(what)j(subset)g(of)f (the)h(screen)g(windo)n(ws)f(enclose)g(the)h(location)f(of)g(a)208 4971 y(mouse)e(e)n(v)o(ent.)0 5118 y FD(erase)p FJ(\(\))208 5218 y FN(Clear)h(the)g(windo)n(w)-5 b(.)0 5365 y FD(getbegyx)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e(char)o (acter-cell)f(displa)n(ys)1487 b(479)p eop end %%Page: 480 492 TeXDict begin 480 491 bop 208 83 a FN(Return)19 b(a)i(tuple)f FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))21 b FN(of)f(co-ordinates)e(of)i (upper)n(-left)e(corner)-5 b(.)0 230 y FD(getch)p FJ(\()p FC([)p FK(y)g(,)19 b(x)12 b FC(])p FJ(\))208 330 y FN(Get)23 b(a)g(character)-5 b(.)33 b(Note)23 b(that)g(the)g(inte)o(ger)e (returned)h(does)g FK(not)h FN(ha)n(v)o(e)f(to)h(be)g(in)i FH(A)t(S)t(C)t(I)t(I)i FN(range:)i(function)22 b(k)o(e)o(ys,)h(k)o(e)o (ypad)e(k)o(e)o(ys)208 429 y(and)e(so)i(on)f(return)f(numbers)f(higher) h(than)h(256.)k(In)c(no-delay)e(mode,)h(-1)h(is)h(returned)d(if)j (there)f(is)h(no)f(input.)0 576 y FD(getkey)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x)12 b FC(])p FJ(\))208 676 y FN(Get)22 b(a)g(character)m(,)f(returning)f(a)i(string)g(instead)g(of)g (an)f(inte)o(ger)m(,)g(as)i FJ(getch\(\))e FN(does.)30 b(Function)21 b(k)o(e)o(ys,)h(k)o(e)o(ypad)e(k)o(e)o(ys)i(and)f(so)208 775 y(on)k(return)g(a)h(multibyte)f(string)h(containing)e(the)i(k)o(e)o (y)g(name.)41 b(In)26 b(no-delay)e(mode,)i(an)g(e)o(xception)e(is)j (raised)f(if)g(there)g(is)h(no)208 875 y(input.)0 1022 y FD(getmaxyx)p FJ(\(\))208 1121 y FN(Return)19 b(a)i(tuple)f FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))21 b FN(of)f(the)g(height)f(and)h (width)g(of)g(the)g(windo)n(w)-5 b(.)0 1268 y FD(getparyx)p FJ(\(\))208 1368 y FN(Returns)20 b(the)h(be)o(ginning)d(coordinates)h (of)h(this)i(windo)n(w)d(relati)n(v)o(e)h(to)h(its)h(parent)e(windo)n (w)f(into)i(tw)o(o)g(inte)o(ger)e(v)n(ariables)h(y)h(and)208 1468 y(x.)k(Returns)20 b FJ(-1,-1)f FN(if)i(this)g(windo)n(w)e(has)h (no)g(parent.)0 1614 y FD(getstr)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x)12 b FC(])p FJ(\))208 1714 y FN(Read)20 b(a)h(string)e(from) h(the)g(user)m(,)f(with)i(primiti)n(v)o(e)e(line)h(editing)f(capacity) -5 b(.)0 1861 y FD(getyx)p FJ(\(\))208 1961 y FN(Return)19 b(a)i(tuple)f FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))21 b FN(of)f(current)e(cursor)i(position)f(relati)n(v)o(e)g(to)i(the)f (windo)n(w')-5 b(s)20 b(upper)n(-left)e(corner)-5 b(.)0 2107 y FD(hline)p FJ(\()p FC([)p FK(y)g(,)19 b(x,)12 b FC(])20 b FK(c)o(h,)g(n)p FJ(\))208 2207 y FN(Display)g(a)g (horizontal)f(line)h(starting)g(at)g FJ(\()p FK(y)p FJ(,)50 b FK(x)p FJ(\))20 b FN(with)h(length)e FK(n)h FN(consisting)g(of)g(the) g(character)f FK(c)o(h)p FN(.)0 2354 y FD(idcok)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2454 y FN(If)k FK(\003a)o(g)g FN(is)i(f)o(alse,)f(curses)g(no)f(longer)g(considers)f(using)h(the)h (hardw)o(are)e(insert/delete)h(character)g(feature)f(of)i(the)g (terminal;)g(if)208 2553 y FK(\003a)o(g)e FN(is)i(true,)g(use)f(of)g (character)f(insertion)g(and)h(deletion)f(is)i(enabled.)33 b(When)23 b(curses)g(is)h(\002rst)g(initialized,)f(use)h(of)f (character)208 2653 y(insert/delete)c(is)i(enabled)e(by)h(def)o(ault.)0 2800 y FD(idlok)p FJ(\()p FK(yes)p FJ(\))208 2899 y FN(If)25 b(called)g(with)h FK(yes)f FN(equal)g(to)h(1,)g FJ(curses)f FN(will)h(try)f(and)g(use)h(hardw)o(are)e(line)h(editing)g(f)o (acilities.)41 b(Otherwise,)26 b(line)g(inser)n(-)208 2999 y(tion/deletion)18 b(are)i(disabled.)0 3146 y FD(immedok)p FJ(\()p FK(\003a)o(g)p FJ(\))208 3245 y FN(If)f FK(\003a)o(g)h FN(is)g(true,)g(an)o(y)f(change)g(in)h(the)g(windo)n(w)f(image)g (automatically)g(causes)h(the)g(windo)n(w)f(to)h(be)g(refreshed;)e(you) h(no)h(longer)208 3345 y(ha)n(v)o(e)e(to)i(call)g FJ(refresh\(\))e FN(yourself.)23 b(Ho)n(we)n(v)o(er)m(,)17 b(it)k(may)d(de)o(grade)g (performance)e(considerably)-5 b(,)17 b(due)i(to)g(repeated)f(calls)i (to)208 3445 y(wrefresh.)j(This)e(option)e(is)i(disabled)e(by)h(def)o (ault.)0 3591 y FD(inch)p FJ(\()p FC([)p FK(y)-5 b(,)20 b(x)12 b FC(])p FJ(\))208 3691 y FN(Return)21 b(the)g(character)f(at)j (the)e(gi)n(v)o(en)f(position)h(in)h(the)f(windo)n(w)-5 b(.)28 b(The)21 b(bottom)f(8)i(bits)g(are)g(the)f(character)f(proper)m (,)g(and)h(upper)208 3791 y(bits)f(are)g(the)h(attrib)n(utes.)0 3938 y FD(insch)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)12 b FC(])20 b FK(c)o(h)p FC([)p FK(,)g(attr)14 b FC(])p FJ(\))208 4037 y FN(P)o(aint)20 b(character)f FK(c)o(h)h FN(at)g FJ(\()p FK(y)p FJ(,)50 b FK(x)p FJ(\))20 b FN(with)h(attrib)n (utes)f FK(attr)r FN(,)g(mo)o(ving)e(the)j(line)f(from)f(position)g FK(x)i FN(right)f(by)g(one)f(character)-5 b(.)0 4184 y FD(insdelln)p FJ(\()p FK(nlines)p FJ(\))208 4284 y FN(Inserts)30 b FK(nlines)g FN(lines)g(into)g(the)g(speci\002ed)g (windo)n(w)f(abo)o(v)o(e)g(the)h(current)e(line.)55 b(The)30 b FK(nlines)g FN(bottom)f(lines)i(are)f(lost.)55 b(F)o(or)208 4383 y(ne)o(gati)n(v)o(e)18 b FK(nlines)p FN(,)i(delete)g FK(nlines)g FN(lines)h(starting)f(with)g(the)g(one)g(under)f(the)h (cursor)m(,)f(and)h(mo)o(v)o(e)f(the)h(remaining)e(lines)j(up.)k(The) 208 4483 y(bottom)19 b FK(nlines)h FN(lines)g(are)g(cleared.)25 b(The)19 b(current)g(cursor)h(position)f(remains)g(the)i(same.)0 4630 y FD(insertln)p FJ(\(\))208 4729 y FN(Insert)e(a)i(blank)e(line)h (under)f(the)h(cursor)-5 b(.)25 b(All)c(follo)n(wing)d(lines)j(are)f (mo)o(v)o(ed)e(do)n(wn)h(by)h(1)g(line.)0 4876 y FD(insnstr)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)12 b FC(])20 b FK(str)-9 b(,)21 b(n)f FC([)p FK(,)h(attr)14 b FC(])p FJ(\))208 4976 y FN(Insert)22 b(a)i(character)d(string)i(\(as)g(man)o(y)f (characters)g(as)i(will)g(\002t)f(on)g(the)g(line\))g(before)e(the)i (character)f(under)g(the)h(cursor)m(,)f(up)g(to)208 5076 y FK(n)j FN(characters.)38 b(If)25 b FK(n)g FN(is)h(zero)f(or)g(ne)o (gati)n(v)o(e,)f(the)h(entire)f(string)h(is)h(inserted.)39 b(All)26 b(characters)e(to)h(the)g(right)g(of)f(the)i(cursor)e(are)208 5175 y(shifted)h(right,)i(with)g(the)f(rightmost)f(characters)g(on)h (the)g(line)g(being)g(lost.)43 b(The)26 b(cursor)f(position)h(does)g (not)f(change)g(\(after)208 5275 y(mo)o(ving)18 b(to)i FK(y)p FN(,)g FK(x)p FN(,)h(if)g(speci\002ed\).)p 0 5549 3901 4 v 0 5649 a FI(480)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 481 493 TeXDict begin 481 492 bop 0 83 a FD(insstr)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)32 b FC(])21 b FK(str)i FC([)p FK(,)e(attr)14 b FC(])p FJ(\))208 183 y FN(Insert)25 b(a)h(character)e(string)i(\(as)g(man)o(y)e(characters)h(as)h(will)h (\002t)f(on)g(the)f(line\))h(before)e(the)i(character)e(under)g(the)i (cursor)-5 b(.)41 b(All)208 282 y(characters)23 b(to)h(the)g(right)g (of)g(the)g(cursor)f(are)h(shifted)g(right,)g(with)g(the)g(rightmost)f (characters)g(on)h(the)g(line)g(being)g(lost.)37 b(The)208 382 y(cursor)19 b(position)g(does)h(not)g(change)f(\(after)g(mo)o(ving) f(to)j FK(y)p FN(,)f FK(x)p FN(,)h(if)f(speci\002ed\).)0 529 y FD(instr)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x)12 b FC(])21 b([)p FK(,)f(n)12 b FC(])p FJ(\))208 628 y FN(Returns)27 b(a)g(string)g(of)g(characters,)h(e)o(xtracted)e(from)g (the)i(windo)n(w)e(starting)h(at)h(the)f(current)f(cursor)g(position,)i (or)f(at)h FK(y)p FN(,)h FK(x)f FN(if)208 728 y(speci\002ed.)c(Attrib)n (utes)d(are)f(stripped)f(from)g(the)i(characters.)j(If)c FK(n)g FN(is)h(speci\002ed,)f FJ(instr\(\))g FN(returns)f(return)g(a)i (string)f(at)h(most)208 828 y FK(n)f FN(characters)f(long)g(\(e)o (xclusi)n(v)o(e)g(of)h(the)g(trailing)g(NUL\).)0 975 y FD(is_linetouched)p FJ(\()p FK(line)p FJ(\))208 1074 y FN(Returns)d(true)h(if)g(the)g(speci\002ed)f(line)h(w)o(as)h (modi\002ed)d(since)i(the)g(last)h(call)f(to)g FJ(refresh\(\))p FN(;)g(otherwise)f(returns)g(f)o(alse.)24 b(Raises)208 1174 y(a)c FJ(curses.error)f FN(e)o(xception)f(if)i FK(line)h FN(is)g(not)f(v)n(alid)f(for)h(the)g(gi)n(v)o(en)f(windo)n(w)-5 b(.)0 1321 y FD(is_wintouched)p FJ(\(\))208 1420 y FN(Returns)20 b(true)f(if)i(the)f(speci\002ed)g(windo)n(w)f(w)o(as)i(modi\002ed)e (since)i(the)f(last)h(call)f(to)h FJ(refresh\(\))p FN(;)e(otherwise)h (returns)f(f)o(alse.)0 1567 y FD(keypad)p FJ(\()p FK(yes)p FJ(\))208 1667 y FN(If)f FK(yes)i FN(is)g(1,)f(escape)g(sequences)f (generated)f(by)i(some)g(k)o(e)o(ys)g(\(k)o(e)o(ypad,)d(function)i(k)o (e)o(ys\))g(will)i(be)f(interpreted)e(by)i FJ(curses)p FN(.)24 b(If)208 1766 y FK(yes)c FN(is)h(0,)f(escape)g(sequences)g (will)h(be)f(left)g(as)h(is)g(in)g(the)f(input)f(stream.)0 1913 y FD(leaveok)p FJ(\()p FK(yes)p FJ(\))208 2013 y FN(If)32 b FK(yes)g FN(is)h(1,)i(cursor)d(is)h(left)f(where)g(it)h(is)g (on)e(update,)j(instead)e(of)g(being)f(at)i(\223cursor)e(position.)-6 b(\224)60 b(This)32 b(reduces)g(cursor)208 2113 y(mo)o(v)o(ement)17 b(where)j(possible.)25 b(If)20 b(possible)f(the)i(cursor)e(will)i(be)f (made)g(in)m(visible.)208 2245 y(If)g FK(yes)g FN(is)i(0,)e(cursor)f (will)i(al)o(w)o(ays)f(be)g(at)h(\223cursor)e(position\224)g(after)h (an)g(update.)0 2392 y FD(move)p FJ(\()p FK(ne)o(w)p 388 2392 25 4 v 28 w(y)-5 b(,)21 b(ne)o(w)p 623 2392 V 30 w(x)p FJ(\))208 2492 y FN(Mo)o(v)o(e)e(cursor)g(to)h FJ(\()p FK(ne)o(w)p 921 2492 V 29 w(y)p FJ(,)50 b FK(ne)o(w)p 1220 2492 V 29 w(x)p FJ(\))p FN(.)0 2639 y FD(mvderwin)p FJ(\()p FK(y)-5 b(,)19 b(x)p FJ(\))208 2738 y FN(Mo)o(v)o(es)25 b(the)h(windo)n(w)f(inside)h(its)h(parent)e(windo)n(w)-5 b(.)42 b(The)26 b(screen-relati)n(v)o(e)e(parameters)h(of)g(the)i (windo)n(w)e(are)h(not)g(changed.)208 2838 y(This)20 b(routine)f(is)i(used)f(to)g(display)g(dif)n(ferent)e(parts)j(of)e(the) i(parent)e(windo)n(w)g(at)i(the)f(same)g(physical)f(position)h(on)g (the)g(screen.)0 2985 y FD(mvwin)p FJ(\()p FK(ne)o(w)p 438 2985 V 28 w(y)-5 b(,)21 b(ne)o(w)p 673 2985 V 29 w(x)p FJ(\))208 3084 y FN(Mo)o(v)o(e)e(the)h(windo)n(w)f(so)h(its)i (upper)n(-left)c(corner)h(is)i(at)g FJ(\()p FK(ne)o(w)p 1946 3084 V 29 w(y)p FJ(,)49 b FK(ne)o(w)p 2244 3084 V 30 w(x)p FJ(\))p FN(.)0 3231 y FD(nodelay)p FJ(\()p FK(yes)p FJ(\))208 3331 y FN(If)20 b FK(yes)g FN(is)i FJ(1)p FN(,)e FJ(getch\(\))f FN(will)i(be)f(non-blocking.)0 3478 y FD(notimeout)p FJ(\()p FK(yes)p FJ(\))208 3577 y FN(If)g FK(yes)g FN(is)i FJ(1)p FN(,)e(escape)g(sequences)f(will)i (not)f(be)g(timed)g(out.)208 3710 y(If)26 b FK(yes)i FN(is)f FJ(0)p FN(,)i(after)e(a)g(fe)n(w)g(milliseconds,)g(an)g(escape) g(sequence)e(will)j(not)e(be)h(interpreted,)g(and)f(will)i(be)e(left)h (in)g(the)g(input)208 3810 y(stream)20 b(as)h(is.)0 3957 y FD(noutrefresh)p FJ(\(\))208 4056 y FN(Mark)e(for)g(refresh)g(b)n(ut) h(w)o(ait.)26 b(This)20 b(function)e(updates)i(the)g(data)f(structure)g (representing)f(the)i(desired)g(state)g(of)g(the)g(windo)n(w)-5 b(,)208 4156 y(b)n(ut)20 b(does)g(not)g(force)f(an)h(update)f(of)h(the) g(physical)f(screen.)25 b(T)-7 b(o)20 b(accomplish)f(that,)h(call)h FJ(doupdate\(\))p FN(.)0 4303 y FD(overlay)p FJ(\()p FK(destwin)p FC([)p FK(,)e(sminr)l(ow)-6 b(,)20 b(smincol,)g(dminr)l (ow)-6 b(,)20 b(dmincol,)f(dmaxr)l(ow)-6 b(,)19 b(dmaxcol)12 b FC(])p FJ(\))208 4403 y FN(Ov)o(erlay)20 b(the)h(windo)n(w)g(on)g (top)g(of)g FK(destwin)p FN(.)29 b(The)22 b(windo)n(ws)e(need)h(not)g (be)h(the)f(same)h(size,)g(only)f(the)h(o)o(v)o(erlapping)c(re)o(gion)i (is)208 4502 y(copied.)j(This)d(cop)o(y)e(is)j(non-destructi)n(v)o(e,) 16 b(which)j(means)g(that)g(the)h(current)e(background)e(character)i (does)h(not)g(o)o(v)o(erwrite)f(the)208 4602 y(old)h(contents)h(of)g FK(destwin)p FN(.)208 4735 y(T)-7 b(o)22 b(get)f(\002ne-grained)f (control)h(o)o(v)o(er)f(the)i(copied)f(re)o(gion,)f(the)i(second)f (form)g(of)h FJ(overlay\(\))e FN(can)i(be)g(used.)29 b FK(sminr)l(ow)23 b FN(and)208 4834 y FK(smincol)k FN(are)h(the)g (upper)n(-left)f(coordinates)f(of)i(the)g(source)f(windo)n(w)-5 b(,)28 b(and)g(the)g(other)f(v)n(ariables)g(mark)g(a)i(rectangle)d(in)j (the)208 4934 y(destination)19 b(windo)n(w)-5 b(.)0 5081 y FD(overwrite)p FJ(\()p FK(destwin)p FC([)p FK(,)18 b(sminr)l(ow)-6 b(,)21 b(smincol,)f(dminr)l(ow)-6 b(,)19 b(dmincol,)g(dmaxr)l(ow)-6 b(,)20 b(dmaxcol)12 b FC(])p FJ(\))208 5180 y FN(Ov)o(erwrite)28 b(the)i(windo)n(w)f(on)h(top)g(of)g FK(destwin)p FN(.)54 b(The)30 b(windo)n(ws)f(need)g(not)h(be)g(the)g (same)g(size,)j(in)d(which)g(case)g(only)g(the)208 5280 y(o)o(v)o(erlapping)d(re)o(gion)j(is)i(copied.)56 b(This)32 b(cop)o(y)e(is)i(destructi)n(v)o(e,)g(which)e(means)h(that)g(the)g (current)f(background)e(character)208 5380 y(o)o(v)o(erwrites)18 b(the)i(old)g(contents)g(of)g FK(destwin)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e(char)o(acter-cell)f(displa)n(ys) 1487 b(481)p eop end %%Page: 482 494 TeXDict begin 482 493 bop 208 83 a FN(T)-7 b(o)24 b(get)g (\002ne-grained)e(control)h(o)o(v)o(er)g(the)h(copied)f(re)o(gion,)h (the)g(second)f(form)g(of)h FJ(overwrite\(\))f FN(can)h(be)g(used.)37 b FK(sminr)l(ow)208 183 y FN(and)27 b FK(smincol)h FN(are)g(the)g (upper)n(-left)e(coordinates)g(of)i(the)g(source)f(windo)n(w)-5 b(,)29 b(the)f(other)f(v)n(ariables)g(mark)g(a)i(rectangle)d(in)j(the) 208 282 y(destination)19 b(windo)n(w)-5 b(.)0 429 y FD(putwin)p FJ(\()p FK(\002le)p FJ(\))208 529 y FN(Writes)21 b(all)g(data)g (associated)f(with)h(the)g(windo)n(w)f(into)g(the)h(pro)o(vided)d (\002le)j(object.)26 b(This)21 b(information)d(can)j(be)f(later)h (retrie)n(v)o(ed)208 628 y(using)e(the)h FJ(getwin\(\))g FN(function.)0 775 y FD(redrawln)p FJ(\()p FK(be)m(g)o(,)e(num)p FJ(\))208 875 y FN(Indicates)i(that)i(the)g FK(num)f FN(screen)g(lines,)h(starting)g(at)g(line)f FK(be)m(g)p FN(,)g(are)h(corrupted)d(and)i(should)g(be)g(completely)f(redra)o(wn)g (on)i(the)208 975 y(ne)o(xt)d FJ(refresh\(\))g FN(call.)0 1121 y FD(redrawwin)p FJ(\(\))208 1221 y FN(T)-7 b(ouches)19 b(the)h(entire)g(windo)n(w)-5 b(,)18 b(causing)i(it)h(to)f(be)g (completely)f(redra)o(wn)f(on)i(the)g(ne)o(xt)g FJ(refresh\(\))f FN(call.)0 1368 y FD(refresh)p FJ(\()p FC([)p FK(pminr)l(ow)-6 b(,)18 b(pmincol,)h(sminr)l(ow)-6 b(,)21 b(smincol,)f(smaxr)l(ow)-6 b(,)20 b(smaxcol)12 b FC(])p FJ(\))208 1468 y FN(Update)19 b(the)h(display)g(immediately)f(\(sync)g(actual)h(screen)g(with)g(pre)n (vious)f(dra)o(wing/deleting)e(methods\).)208 1600 y(The)31 b(6)g(optional)g(ar)o(guments)e(can)j(only)e(be)i(speci\002ed)f(when)g (the)h(windo)n(w)e(is)j(a)f(pad)f(created)g(with)h FJ(newpad\(\))p FN(.)58 b(The)208 1700 y(additional)17 b(parameters)g(are)i(needed)f (to)g(indicate)h(what)f(part)h(of)f(the)h(pad)f(and)g(screen)h(are)f (in)m(v)n(olv)o(ed.)23 b FK(pminr)l(ow)18 b FN(and)h FK(pmincol)208 1800 y FN(specify)i(the)g(upper)g(left-hand)f(corner)g (of)i(the)f(rectangle)g(to)h(be)g(displayed)e(in)i(the)g(pad.)29 b FK(sminr)l(ow)p FN(,)23 b FK(smincol)p FN(,)f FK(smaxr)l(ow)p FN(,)g(and)208 1899 y FK(smaxcol)j FN(specify)g(the)h(edges)g(of)f(the) h(rectangle)f(to)h(be)g(displayed)e(on)i(the)g(screen.)41 b(The)26 b(lo)n(wer)f(right-hand)e(corner)i(of)h(the)208 1999 y(rectangle)21 b(to)i(be)g(displayed)e(in)i(the)g(pad)f(is)i (calculated)e(from)g(the)h(screen)f(coordinates,)f(since)i(the)g (rectangles)f(must)h(be)g(the)208 2098 y(same)28 b(size.)49 b(Both)28 b(rectangles)f(must)i(be)f(entirely)f(contained)f(within)i (their)g(respecti)n(v)o(e)f(structures.)48 b(Ne)o(gati)n(v)o(e)26 b(v)n(alues)i(of)208 2198 y FK(pminr)l(ow)p FN(,)20 b FK(pmincol)p FN(,)f FK(sminr)l(ow)p FN(,)h(or)g FK(smincol)g FN(are)h(treated)e(as)i(if)g(the)o(y)e(were)h(zero.)0 2345 y FD(scroll)p FJ(\()p FC([)p FK(lines)48 b Fn(=)i(1)12 b FC(])p FJ(\))208 2445 y FN(Scroll)20 b(the)g(screen)g(or)g(scrolling) f(re)o(gion)g(upw)o(ard)f(by)i FK(lines)h FN(lines.)0 2591 y FD(scrollok)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2691 y FN(Controls)h(what)i(happens)e(when)g(the)i(cursor)e(of)h(a)h (windo)n(w)e(is)i(mo)o(v)o(ed)e(of)n(f)g(the)i(edge)e(of)h(the)h(windo) n(w)e(or)h(scrolling)f(re)o(gion,)208 2791 y(either)i(as)i(a)g(result)f (of)g(a)h(ne)n(wline)f(action)f(on)h(the)g(bottom)g(line,)h(or)f (typing)f(the)h(last)h(character)e(of)h(the)h(last)g(line.)40 b(If)25 b FK(\003a)o(g)g FN(is)208 2890 y(f)o(alse,)d(the)g(cursor)f (is)i(left)f(on)f(the)h(bottom)f(line.)30 b(If)21 b FK(\003a)o(g)g FN(is)i(true,)f(the)g(windo)n(w)e(is)j(scrolled)e(up)h(one)f(line.)30 b(Note)22 b(that)g(in)g(order)208 2990 y(to)e(get)g(the)g(physical)f (scrolling)h(ef)n(fect)f(on)h(the)g(terminal,)g(it)g(is)i(also)e (necessary)g(to)g(call)h FJ(idlok\(\))p FN(.)0 3137 y FD(setscrreg)p FJ(\()p FK(top,)d(bottom)p FJ(\))208 3236 y FN(Set)i(the)h(scrolling)e(re)o(gion)g(from)g(line)h FK(top)g FN(to)g(line)h FK(bottom)p FN(.)j(All)c(scrolling)g(actions)g (will)h(tak)o(e)f(place)g(in)g(this)h(re)o(gion.)0 3383 y FD(standend)p FJ(\(\))208 3483 y FN(T)l(urn)e(of)n(f)g(the)i (standout)e(attrib)n(ute.)24 b(On)d(some)f(terminals)f(this)i(has)f (the)h(side)f(ef)n(fect)g(of)g(turning)e(of)n(f)i(all)h(attrib)n(utes.) 0 3630 y FD(standout)p FJ(\(\))208 3729 y FN(T)l(urn)e(on)h(attrib)n (ute)g FK(A)p 842 3729 25 4 v 29 w(ST)l(ANDOUT)6 b FN(.)0 3876 y FD(subpad)p FJ(\()p FC([)p FK(nlines,)18 b(ncols,)12 b FC(])20 b FK(be)m(gin)p 1085 3876 V 28 w(y)-5 b(,)21 b(be)m(gin)p 1370 3876 V 28 w(x)p FJ(\))208 3976 y FN(Return)49 b(a)h(sub-windo)n(w)-5 b(,)54 b(whose)c(upper)n(-left)d(corner)i(is)h (at)h FJ(\()p FK(be)m(gin)p 2407 3976 V 27 w(y)p FJ(,)f FK(be)m(gin)p 2754 3976 V 28 w(x)p FJ(\))p FN(,)57 b(and)49 b(whose)h(width/height)e(is)208 4076 y FK(ncols)p FN(/)p FK(nlines)p FN(.)0 4222 y FD(subwin)p FJ(\()p FC([)p FK(nlines,)18 b(ncols,)12 b FC(])20 b FK(be)m(gin)p 1085 4222 V 28 w(y)-5 b(,)21 b(be)m(gin)p 1370 4222 V 28 w(x)p FJ(\))208 4322 y FN(Return)49 b(a)h(sub-windo)n(w)-5 b(,)54 b(whose)c(upper)n(-left)d(corner)i(is)h(at)h FJ(\()p FK(be)m(gin)p 2407 4322 V 27 w(y)p FJ(,)f FK(be)m(gin)p 2754 4322 V 28 w(x)p FJ(\))p FN(,)57 b(and)49 b(whose)h(width/height)e (is)208 4422 y FK(ncols)p FN(/)p FK(nlines)p FN(.)208 4555 y(By)20 b(def)o(ault,)f(the)i(sub-windo)n(w)d(will)j(e)o(xtend)e (from)g(the)h(speci\002ed)g(position)f(to)h(the)h(lo)n(wer)e(right)h (corner)f(of)h(the)g(windo)n(w)-5 b(.)0 4701 y FD(syncdown)p FJ(\(\))208 4801 y FN(T)e(ouches)16 b(each)h(location)g(in)h(the)f (windo)n(w)f(that)i(has)g(been)f(touched)e(in)j(an)o(y)f(of)g(its)h (ancestor)f(windo)n(ws.)23 b(This)18 b(routine)e(is)j(called)208 4901 y(by)g FJ(refresh\(\))p FN(,)g(so)i(it)g(should)e(almost)h(ne)n(v) o(er)f(be)h(necessary)f(to)i(call)f(it)h(manually)-5 b(.)0 5048 y FD(syncok)p FJ(\()p FK(\003a)o(g)p FJ(\))208 5147 y FN(If)17 b(called)h(with)h FK(\003a)o(g)e FN(set)i(to)f(true,)g (then)f FJ(syncup\(\))h FN(is)h(called)f(automatically)e(whene)n(v)o (er)g(there)i(is)h(a)f(change)f(in)h(the)g(windo)n(w)-5 b(.)0 5294 y FD(syncup)p FJ(\(\))208 5394 y FN(T)e(ouches)19 b(all)i(locations)e(in)i(ancestors)e(of)h(the)g(windo)n(w)g(that)g(ha)n (v)o(e)f(been)h(changed)e(in)j(the)f(windo)n(w)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(482)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 483 495 TeXDict begin 483 494 bop 0 83 a FD(timeout)p FJ(\()p FK(delay)p FJ(\))208 183 y FN(Sets)22 b(blocking)e(or)h(non-blocking)c (read)k(beha)n(vior)f(for)h(the)g(windo)n(w)-5 b(.)28 b(If)21 b FK(delay)g FN(is)h(ne)o(gati)n(v)o(e,)d(blocking)h(read)h(is) h(used)f(\(which)208 282 y(will)28 b(w)o(ait)g(inde\002nitely)f(for)g (input\).)46 b(If)27 b FK(delay)h FN(is)g(zero,)h(then)e(non-blocking)d (read)j(is)i(used,)g(and)e(-1)g(will)i(be)e(returned)f(by)208 382 y FJ(getch\(\))g FN(if)i(no)f(input)g(is)i(w)o(aiting.)47 b(If)27 b FK(delay)g FN(is)i(positi)n(v)o(e,)f(then)f FJ(getch\(\))g FN(will)h(block)f(for)g FK(delay)g FN(milliseconds,)h (and)208 482 y(return)19 b(-1)g(if)i(there)f(is)h(still)g(no)f(input)f (at)i(the)f(end)g(of)g(that)g(time.)0 628 y FD(touchline)p FJ(\()p FK(start,)f(count)q FC([)p FK(,)g(c)o(hang)o(ed)11 b FC(])p FJ(\))208 728 y FN(Pretend)21 b FK(count)i FN(lines)f(ha)n(v)o (e)g(been)f(changed,)g(starting)h(with)g(line)h FK(start)q FN(.)32 b(If)22 b FK(c)o(hang)o(ed)g FN(is)h(supplied,)f(it)h (speci\002es)f(whether)g(the)208 828 y(af)n(fected)d(lines)h(are)g (mark)o(ed)f(as)i(ha)n(ving)e(been)h(changed)e(\()p FK(c)o(hang)o(ed)r FN(=1\))f(or)j(unchanged)d(\()p FK(c)o(hang)o(ed)r FN(=0\).)0 975 y FD(touchwin)p FJ(\(\))208 1074 y FN(Pretend)i(the)h(whole)g (windo)n(w)f(has)h(been)g(changed,)e(for)i(purposes)e(of)i(dra)o(wing)f (optimizations.)0 1221 y FD(untouchwin)p FJ(\(\))208 1321 y FN(Marks)g(all)i(lines)g(in)f(the)g(windo)n(w)g(as)g(unchanged)e (since)i(the)g(last)h(call)g(to)f FJ(refresh\(\))p FN(.)0 1468 y FD(vline)p FJ(\()p FC([)p FK(y)-5 b(,)19 b(x,)12 b FC(])20 b FK(c)o(h,)g(n)p FJ(\))208 1567 y FN(Display)g(a)g(v)o (ertical)g(line)g(starting)g(at)g FJ(\()p FK(y)p FJ(,)50 b FK(x)p FJ(\))20 b FN(with)h(length)e FK(n)h FN(consisting)g(of)g(the) g(character)f FK(c)o(h)p FN(.)0 1852 y Fv(14.7.3)101 b(Constants)0 2055 y FN(The)20 b FJ(curses)f FN(module)g(de\002nes)h (the)g(follo)n(wing)f(data)h(members:)0 2202 y FD(ERR)208 2301 y FN(Some)f(curses)i(routines)e(that)h(return)f(an)h(inte)o(ger)m (,)f(such)h(as)h FJ(getch\(\))p FN(,)e(return)g FJ(ERR)h FN(upon)f(f)o(ailure.)0 2448 y FD(OK)208 2548 y FN(Some)g(curses)i (routines)e(that)h(return)f(an)h(inte)o(ger)m(,)f(such)h(as)h FJ(napms\(\))p FN(,)e(return)g FJ(OK)h FN(upon)f(success.)0 2695 y FD(version)208 2794 y FN(A)h(string)g(representing)e(the)i (current)f(v)o(ersion)g(of)h(the)g(module.)k(Also)d(a)n(v)n(ailable)e (as)i FJ(__version__)p FN(.)0 2941 y(Se)n(v)o(eral)e(constants)h(are)g (a)n(v)n(ailable)g(to)g(specify)g(character)f(cell)h(attrib)n(utes:) 1115 3168 y FL(Attrib)n(ute)p 1761 3197 4 100 v 366 w(Meaning)p 1065 3201 1770 4 v 1115 3271 a FJ(A_ALTCHARSET)p 1761 3300 4 100 v 97 w FN(Alternate)g(character)f(set)i(mode.)1115 3370 y FJ(A_BLINK)p 1761 3400 V 347 w FN(Blink)g(mode.)1115 3470 y FJ(A_BOLD)p 1761 3500 V 397 w FN(Bold)g(mode.)1115 3569 y FJ(A_DIM)p 1761 3599 V 447 w FN(Dim)g(mode.)1115 3669 y FJ(A_NORMAL)p 1761 3699 V 297 w FN(Normal)f(attrib)n(ute.)1115 3769 y FJ(A_STANDOUT)p 1761 3799 V 197 w FN(Standout)f(mode.)1115 3868 y FJ(A_UNDERLINE)p 1761 3898 V 147 w FN(Underline)g(mode.)0 4093 y(K)n(e)o(ys)25 b(are)g(referred)f(to)h(by)g(inte)o(ger)f (constants)h(with)h(names)f(starting)g(with)g(`)p FJ(KEY_)p FN('.)39 b(The)25 b(e)o(xact)g(k)o(e)o(ycaps)f(a)n(v)n(ailable)h(are)g (system)0 4193 y(dependent.)695 4463 y FL(K)n(ey)20 b(constant)p 1391 4493 V 284 w(K)n(ey)p 645 4497 2610 4 v 645 4497 V 695 4566 a FJ(KEY_MIN)p 1391 4596 4 100 v 397 w FN(Minimum)f(k)o(e)o (y)h(v)n(alue)695 4666 y FJ(KEY_BREAK)p 1391 4696 V 297 w FN(Break)g(k)o(e)o(y)g(\(unreliable\))695 4766 y FJ(KEY_DOWN)p 1391 4795 V 347 w FN(Do)n(wn-arro)n(w)695 4865 y FJ(KEY_UP)p 1391 4895 V 447 w FN(Up-arro)n(w)695 4965 y FJ(KEY_LEFT)p 1391 4995 V 347 w FN(Left-arro)n(w)695 5064 y FJ(KEY_RIGHT)p 1391 5094 V 297 w FN(Right-arro)n(w)695 5164 y FJ(KEY_HOME)p 1391 5194 V 347 w FN(Home)g(k)o(e)o(y)g(\(upw)o(ard+left)e(arro)n(w\)) 695 5264 y FJ(KEY_BACKSPACE)p 1391 5294 V 97 w FN(Backspace)i (\(unreliable\))695 5363 y FJ(KEY_F0)p 1391 5393 V 447 w FN(Function)f(k)o(e)o(ys.)25 b(Up)20 b(to)g(64)g(function)f(k)o(e)o (ys)h(are)g(supported.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e (char)o(acter-cell)f(displa)n(ys)1487 b(483)p eop end %%Page: 484 496 TeXDict begin 484 495 bop 695 70 a FL(K)n(ey)20 b(constant)p 1391 100 4 100 v 284 w(K)n(ey)p 645 103 2610 4 v 645 103 V 695 173 a FJ(KEY_F)p FK(n)p 1391 203 4 100 v 455 w FN(V)-9 b(alue)20 b(of)g(function)e(k)o(e)o(y)i FK(n)695 272 y FJ(KEY_DL)p 1391 302 V 447 w FN(Delete)h(line)695 372 y FJ(KEY_IL)p 1391 402 V 447 w FN(Insert)f(line)695 472 y FJ(KEY_DC)p 1391 501 V 447 w FN(Delete)h(character)695 571 y FJ(KEY_IC)p 1391 601 V 447 w FN(Insert)f(char)g(or)g(enter)f (insert)i(mode)695 671 y FJ(KEY_EIC)p 1391 701 V 397 w FN(Exit)f(insert)h(char)e(mode)695 770 y FJ(KEY_CLEAR)p 1391 800 V 297 w FN(Clear)i(screen)695 870 y FJ(KEY_EOS)p 1391 900 V 397 w FN(Clear)g(to)f(end)g(of)g(screen)695 970 y FJ(KEY_EOL)p 1391 1000 V 397 w FN(Clear)h(to)f(end)g(of)g(line) 695 1069 y FJ(KEY_SF)p 1391 1099 V 447 w FN(Scroll)g(1)h(line)f(forw)o (ard)695 1169 y FJ(KEY_SR)p 1391 1199 V 447 w FN(Scroll)g(1)h(line)f (backw)o(ard)f(\(re)n(v)o(erse\))695 1269 y FJ(KEY_NPAGE)p 1391 1298 V 297 w FN(Ne)o(xt)h(page)695 1368 y FJ(KEY_PPAGE)p 1391 1398 V 297 w FN(Pre)n(vious)g(page)695 1468 y FJ(KEY_STAB)p 1391 1498 V 347 w FN(Set)h(tab)695 1567 y FJ(KEY_CTAB)p 1391 1597 V 347 w FN(Clear)g(tab)695 1667 y FJ(KEY_CATAB)p 1391 1697 V 297 w FN(Clear)g(all)g(tabs)695 1767 y FJ(KEY_ENTER)p 1391 1797 V 297 w FN(Enter)f(or)g(send)g(\(unreliable\))695 1866 y FJ(KEY_SRESET)p 1391 1896 V 247 w FN(Soft)g(\(partial\))g(reset) g(\(unreliable\))695 1966 y FJ(KEY_RESET)p 1391 1996 V 297 w FN(Reset)i(or)d(hard)h(reset)g(\(unreliable\))695 2066 y FJ(KEY_PRINT)p 1391 2095 V 297 w FN(Print)695 2165 y FJ(KEY_LL)p 1391 2195 V 447 w FN(Home)g(do)n(wn)f(or)h(bottom)f (\(lo)n(wer)g(left\))695 2265 y FJ(KEY_A1)p 1391 2295 V 447 w FN(Upper)h(left)g(of)g(k)o(e)o(ypad)695 2364 y FJ(KEY_A3)p 1391 2394 V 447 w FN(Upper)g(right)f(of)h(k)o(e)o(ypad) 695 2464 y FJ(KEY_B2)p 1391 2494 V 447 w FN(Center)g(of)g(k)o(e)o(ypad) 695 2564 y FJ(KEY_C1)p 1391 2594 V 447 w FN(Lo)n(wer)g(left)g(of)g(k)o (e)o(ypad)695 2663 y FJ(KEY_C3)p 1391 2693 V 447 w FN(Lo)n(wer)g(right) f(of)h(k)o(e)o(ypad)695 2763 y FJ(KEY_BTAB)p 1391 2793 V 347 w FN(Back)h(tab)695 2863 y FJ(KEY_BEG)p 1391 2892 V 397 w FN(Be)o(g)g(\(be)o(ginning\))695 2962 y FJ(KEY_CANCEL)p 1391 2992 V 247 w FN(Cancel)695 3062 y FJ(KEY_CLOSE)p 1391 3092 V 297 w FN(Close)695 3161 y FJ(KEY_COMMAND)p 1391 3191 V 197 w FN(Cmd)g(\(command\))695 3261 y FJ(KEY_COPY)p 1391 3291 V 347 w FN(Cop)o(y)695 3361 y FJ(KEY_CREATE)p 1391 3391 V 247 w FN(Create)695 3460 y FJ(KEY_END)p 1391 3490 V 397 w FN(End)695 3560 y FJ(KEY_EXIT)p 1391 3590 V 347 w FN(Exit)695 3660 y FJ(KEY_FIND)p 1391 3689 V 347 w FN(Find)695 3759 y FJ(KEY_HELP)p 1391 3789 V 347 w FN(Help)695 3859 y FJ(KEY_MARK)p 1391 3889 V 347 w FN(Mark)695 3958 y FJ(KEY_MESSAGE)p 1391 3988 V 197 w FN(Message)695 4058 y FJ(KEY_MOVE)p 1391 4088 V 347 w FN(Mo)o(v)o(e)695 4158 y FJ(KEY_NEXT)p 1391 4188 V 347 w FN(Ne)o(xt)695 4257 y FJ(KEY_OPEN)p 1391 4287 V 347 w FN(Open)695 4357 y FJ(KEY_OPTIONS)p 1391 4387 V 197 w FN(Options)695 4457 y FJ(KEY_PREVIOUS)p 1391 4487 V 147 w FN(Pre)n(v)f(\(pre)n(vious\))695 4556 y FJ(KEY_REDO)p 1391 4586 V 347 w FN(Redo)695 4656 y FJ(KEY_REFERENCE)p 1391 4686 V 97 w FN(Ref)h(\(reference\))695 4755 y FJ(KEY_REFRESH)p 1391 4785 V 197 w FN(Refresh)695 4855 y FJ(KEY_REPLACE)p 1391 4885 V 197 w FN(Replace)695 4955 y FJ(KEY_RESTART)p 1391 4985 V 197 w FN(Restart)695 5054 y FJ(KEY_RESUME)p 1391 5084 V 247 w FN(Resume)695 5154 y FJ(KEY_SAVE)p 1391 5184 V 347 w FN(Sa)n(v)o(e)695 5254 y FJ(KEY_SBEG)p 1391 5284 V 347 w FN(Shifted)f(Be)o(g)g(\(be)o(ginning\))695 5353 y FJ(KEY_SCANCEL)p 1391 5383 V 197 w FN(Shifted)g(Cancel)p 0 5549 3901 4 v 0 5649 a FI(484)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 485 497 TeXDict begin 485 496 bop 695 70 a FL(K)n(ey)20 b(constant)p 1391 100 4 100 v 284 w(K)n(ey)p 645 103 2610 4 v 645 103 V 695 173 a FJ(KEY_SCOMMAND)p 1391 203 4 100 v 147 w FN(Shifted)g(Command)695 272 y FJ(KEY_SCOPY)p 1391 302 V 297 w FN(Shifted)g(Cop)o(y)695 372 y FJ(KEY_SCREATE)p 1391 402 V 197 w FN(Shifted)g(Create)695 472 y FJ(KEY_SDC)p 1391 501 V 397 w FN(Shifted)g(Delete)g(char)695 571 y FJ(KEY_SDL)p 1391 601 V 397 w FN(Shifted)g(Delete)g(line)695 671 y FJ(KEY_SELECT)p 1391 701 V 247 w FN(Select)695 770 y FJ(KEY_SEND)p 1391 800 V 347 w FN(Shifted)g(End)695 870 y FJ(KEY_SEOL)p 1391 900 V 347 w FN(Shifted)g(Clear)h(line)695 970 y FJ(KEY_SEXIT)p 1391 1000 V 297 w FN(Shifted)f(Dxit)695 1069 y FJ(KEY_SFIND)p 1391 1099 V 297 w FN(Shifted)g(Find)695 1169 y FJ(KEY_SHELP)p 1391 1199 V 297 w FN(Shifted)g(Help)695 1269 y FJ(KEY_SHOME)p 1391 1298 V 297 w FN(Shifted)g(Home)695 1368 y FJ(KEY_SIC)p 1391 1398 V 397 w FN(Shifted)g(Input)695 1468 y FJ(KEY_SLEFT)p 1391 1498 V 297 w FN(Shifted)g(Left)g(arro)n(w) 695 1567 y FJ(KEY_SMESSAGE)p 1391 1597 V 147 w FN(Shifted)g(Message)695 1667 y FJ(KEY_SMOVE)p 1391 1697 V 297 w FN(Shifted)g(Mo)o(v)o(e)695 1767 y FJ(KEY_SNEXT)p 1391 1797 V 297 w FN(Shifted)g(Ne)o(xt)695 1866 y FJ(KEY_SOPTIONS)p 1391 1896 V 147 w FN(Shifted)g(Options)695 1966 y FJ(KEY_SPREVIOUS)p 1391 1996 V 97 w FN(Shifted)g(Pre)n(v)695 2066 y FJ(KEY_SPRINT)p 1391 2095 V 247 w FN(Shifted)g(Print)695 2165 y FJ(KEY_SREDO)p 1391 2195 V 297 w FN(Shifted)g(Redo)695 2265 y FJ(KEY_SREPLACE)p 1391 2295 V 147 w FN(Shifted)g(Replace)695 2364 y FJ(KEY_SRIGHT)p 1391 2394 V 247 w FN(Shifted)g(Right)g(arro)n(w) 695 2464 y FJ(KEY_SRSUME)p 1391 2494 V 247 w FN(Shifted)g(Resume)695 2564 y FJ(KEY_SSAVE)p 1391 2594 V 297 w FN(Shifted)g(Sa)n(v)o(e)695 2663 y FJ(KEY_SSUSPEND)p 1391 2693 V 147 w FN(Shifted)g(Suspend)695 2763 y FJ(KEY_SUNDO)p 1391 2793 V 297 w FN(Shifted)g(Undo)695 2863 y FJ(KEY_SUSPEND)p 1391 2892 V 197 w FN(Suspend)695 2962 y FJ(KEY_UNDO)p 1391 2992 V 347 w FN(Undo)695 3062 y FJ(KEY_MOUSE)p 1391 3092 V 297 w FN(Mouse)g(e)n(v)o(ent)f(has)i (occurred)695 3161 y FJ(KEY_RESIZE)p 1391 3191 V 247 w FN(T)-6 b(erminal)20 b(resize)g(e)n(v)o(ent)695 3261 y FJ(KEY_MAX)p 1391 3291 V 397 w FN(Maximum)f(k)o(e)o(y)h(v)n(alue)0 3703 y(On)e(VT100s)f(and)h(their)g(softw)o(are)g(emulations,)f(such)h (as)h(X)g(terminal)e(emulators,)g(there)h(are)g(normally)f(at)h(least)h (four)e(function)g(k)o(e)o(ys)0 3802 y(\()p FJ(KEY_F1)p FN(,)30 b FJ(KEY_F2)p FN(,)g FJ(KEY_F3)p FN(,)g FJ(KEY_F4)p FN(\))e(a)n(v)n(ailable,)j(and)d(the)h(arro)n(w)f(k)o(e)o(ys)h(mapped)e (to)i FJ(KEY_UP)p FN(,)f FJ(KEY_DOWN)p FN(,)g FJ(KEY_-)0 3902 y(LEFT)23 b FN(and)g FJ(KEY_RIGHT)f FN(in)h(the)g(ob)o(vious)f(w)o (ay)-5 b(.)33 b(If)23 b(your)f(machine)g(has)h(a)h(PC)g(k)o(e)o (yboard,)d(it)j(is)g(safe)g(to)f(e)o(xpect)f(arro)n(w)g(k)o(e)o(ys)h (and)0 4002 y(twelv)o(e)d(function)e(k)o(e)o(ys)i(\(older)f(PC)i(k)o(e) o(yboards)d(may)i(ha)n(v)o(e)f(only)h(ten)g(function)e(k)o(e)o(ys\);)i (also,)g(the)g(follo)n(wing)f(k)o(e)o(ypad)f(mappings)h(are)0 4101 y(standard:)1443 4275 y FL(K)n(eycap)p 1939 4304 V 281 w(Constant)p 1393 4308 1114 4 v 1443 4378 a FJ(Insert)p 1939 4407 4 100 v 248 w FN(KEY)p 2167 4378 25 4 v 29 w(IC)1443 4477 y FJ(Delete)p 1939 4507 4 100 v 248 w FN(KEY)p 2167 4477 25 4 v 29 w(DC)1443 4577 y FJ(Home)p 1939 4607 4 100 v 348 w FN(KEY)p 2167 4577 25 4 v 29 w(HOME)1443 4676 y FJ(End)p 1939 4706 4 100 v 398 w FN(KEY)p 2167 4676 25 4 v 29 w(END)1443 4776 y FJ(Page)49 b(Up)p 1939 4806 4 100 v 199 w FN(KEY)p 2167 4776 25 4 v 29 w(NP)-8 b(A)m(GE)1443 4876 y FJ(Page)49 b(Down)p 1939 4906 4 100 v 99 w FN(KEY)p 2167 4876 25 4 v 29 w(PP)-8 b(A)m(GE)0 5065 y(The)19 b(follo)n(wing)e(table)j(lists)g(characters)f (from)f(the)h(alternate)g(character)f(set.)25 b(These)19 b(are)g(inherited)f(from)g(the)i(VT100)e(terminal,)g(and)0 5164 y(will)g(generally)d(be)j(a)n(v)n(ailable)e(on)h(softw)o(are)g (emulations)f(such)h(as)g(X)h(terminals.)24 b(When)17 b(there)f(is)i(no)f(graphic)f(a)n(v)n(ailable,)h(curses)g(f)o(alls)0 5264 y(back)j(on)f(a)i(crude)e(printable)g(ASCII)h(approximation.)i FL(Note:)j FN(These)20 b(are)g(a)n(v)n(ailable)f(only)h(after)g FJ(initscr\(\))f FN(has)h(been)g(called.)p 0 5549 3901 4 v 0 5649 a FI(14.7.)52 b FJ(curses)22 b FI(\227)h(T)-10 b(er)r(minal)24 b(handling)h(f)n(or)e(char)o(acter-cell)f(displa)n(ys) 1487 b(485)p eop end %%Page: 486 498 TeXDict begin 486 497 bop 943 70 a FL(A)-5 b(CS)21 b(code)p 1589 100 4 100 v 354 w(Meaning)p 893 103 2114 4 v 893 103 V 943 173 a FJ(ACS_BBSS)p 1589 203 4 100 v 298 w FN(alternate)e(name)h(for)f(upper)g(right)h(corner)943 272 y FJ(ACS_BLOCK)p 1589 302 V 248 w FN(solid)g(square)f(block)943 372 y FJ(ACS_BOARD)p 1589 402 V 248 w FN(board)f(of)i(squares)943 472 y FJ(ACS_BSBS)p 1589 501 V 298 w FN(alternate)f(name)h(for)f (horizontal)g(line)943 571 y FJ(ACS_BSSB)p 1589 601 V 298 w FN(alternate)g(name)h(for)f(upper)g(left)h(corner)943 671 y FJ(ACS_BSSS)p 1589 701 V 298 w FN(alternate)f(name)h(for)f(top)h (tee)943 770 y FJ(ACS_BTEE)p 1589 800 V 298 w FN(bottom)f(tee)943 870 y FJ(ACS_BULLET)p 1589 900 V 198 w FN(b)n(ullet)943 970 y FJ(ACS_CKBOARD)p 1589 1000 V 148 w FN(check)o(er)g(board)f (\(stipple\))943 1069 y FJ(ACS_DARROW)p 1589 1099 V 198 w FN(arro)n(w)h(pointing)f(do)n(wn)943 1169 y FJ(ACS_DEGREE)p 1589 1199 V 198 w FN(de)o(gree)g(symbol)943 1269 y FJ(ACS_DIAMOND)p 1589 1298 V 148 w FN(diamond)943 1368 y FJ(ACS_GEQUAL)p 1589 1398 V 198 w FN(greater)n(-than-or)n(-equal-to)943 1468 y FJ(ACS_HLINE)p 1589 1498 V 248 w FN(horizontal)g(line)943 1567 y FJ(ACS_LANTERN)p 1589 1597 V 148 w FN(lantern)h(symbol)943 1667 y FJ(ACS_LARROW)p 1589 1697 V 198 w FN(left)h(arro)n(w)943 1767 y FJ(ACS_LEQUAL)p 1589 1797 V 198 w FN(less-than-or)n(-equal-to) 943 1866 y FJ(ACS_LLCORNER)p 1589 1896 V 98 w FN(lo)n(wer)f(left-hand)g (corner)943 1966 y FJ(ACS_LRCORNER)p 1589 1996 V 98 w FN(lo)n(wer)g(right-hand)f(corner)943 2066 y FJ(ACS_LTEE)p 1589 2095 V 298 w FN(left)i(tee)943 2165 y FJ(ACS_NEQUAL)p 1589 2195 V 198 w FN(not-equal)e(sign)943 2265 y FJ(ACS_PI)p 1589 2295 V 398 w FN(letter)i(pi)943 2364 y FJ(ACS_PLMINUS)p 1589 2394 V 148 w FN(plus-or)n(-minus)d(sign)943 2464 y FJ(ACS_PLUS)p 1589 2494 V 298 w FN(big)i(plus)i(sign)943 2564 y FJ(ACS_RARROW)p 1589 2594 V 198 w FN(right)e(arro)n(w)943 2663 y FJ(ACS_RTEE)p 1589 2693 V 298 w FN(right)g(tee)943 2763 y FJ(ACS_S1)p 1589 2793 V 398 w FN(scan)h(line)g(1)943 2863 y FJ(ACS_S3)p 1589 2892 V 398 w FN(scan)g(line)g(3)943 2962 y FJ(ACS_S7)p 1589 2992 V 398 w FN(scan)g(line)g(7)943 3062 y FJ(ACS_S9)p 1589 3092 V 398 w FN(scan)g(line)g(9)943 3161 y FJ(ACS_SBBS)p 1589 3191 V 298 w FN(alternate)f(name)h(for)f(lo)n (wer)h(right)g(corner)943 3261 y FJ(ACS_SBSB)p 1589 3291 V 298 w FN(alternate)f(name)h(for)f(v)o(ertical)h(line)943 3361 y FJ(ACS_SBSS)p 1589 3391 V 298 w FN(alternate)f(name)h(for)f (right)h(tee)943 3460 y FJ(ACS_SSBB)p 1589 3490 V 298 w FN(alternate)f(name)h(for)f(lo)n(wer)h(left)g(corner)943 3560 y FJ(ACS_SSBS)p 1589 3590 V 298 w FN(alternate)f(name)h(for)f (bottom)g(tee)943 3660 y FJ(ACS_SSSB)p 1589 3689 V 298 w FN(alternate)g(name)h(for)f(left)i(tee)943 3759 y FJ(ACS_SSSS)p 1589 3789 V 298 w FN(alternate)e(name)h(for)f(crosso)o(v)o(er)g(or)h (big)f(plus)943 3859 y FJ(ACS_STERLING)p 1589 3889 V 98 w FN(pound)f(sterling)943 3958 y FJ(ACS_TTEE)p 1589 3988 V 298 w FN(top)h(tee)943 4058 y FJ(ACS_UARROW)p 1589 4088 V 198 w FN(up)g(arro)n(w)943 4158 y FJ(ACS_ULCORNER)p 1589 4188 V 98 w FN(upper)f(left)j(corner)943 4257 y FJ(ACS_URCORNER)p 1589 4287 V 98 w FN(upper)d(right)i(corner)943 4357 y FJ(ACS_VLINE)p 1589 4387 V 248 w FN(v)o(ertical)f(line)0 4863 y(The)h(follo)n(wing)e(table)j(lists)g(the)f(prede\002ned)f (colors:)p 0 5549 3901 4 v 0 5649 a FI(486)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 487 499 TeXDict begin 487 498 bop 1142 70 a FL(Constant)p 1837 100 4 100 v 423 w(Color)p 1092 103 1717 4 v 1142 173 a FJ(COLOR_BLACK)p 1837 203 4 100 v 197 w FN(Black)1142 272 y FJ(COLOR_BLUE)p 1837 302 V 247 w FN(Blue)1142 372 y FJ(COLOR_CYAN)p 1837 402 V 247 w FN(Cyan)20 b(\(light)g(greenish)f (blue\))1142 472 y FJ(COLOR_GREEN)p 1837 501 V 197 w FN(Green)1142 571 y FJ(COLOR_MAGENTA)p 1837 601 V 97 w FN(Magenta)g(\(purplish)g(red\))1142 671 y FJ(COLOR_RED)p 1837 701 V 297 w FN(Red)1142 770 y FJ(COLOR_WHITE)p 1837 800 V 197 w FN(White)1142 870 y FJ(COLOR_YELLOW)p 1837 900 V 147 w FN(Y)-8 b(ello)n(w)0 1257 y FE(14.8)121 b Fx(curses.textpad)30 b FE(\227)i(T)-14 b(e)l(xt)34 b(input)h(widget)f (f)l(or)h(curses)e(prog)o(r)o(ams)0 1489 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.6.)0 1636 y(The)g FJ(curses.textpad)f FN(module)g(pro)o(vides)g(a)i FJ(Textbox)f FN(class)h(that)g(handles)f (elementary)f(te)o(xt)h(editing)g(in)h(a)g(curses)f(windo)n(w)-5 b(,)0 1736 y(supporting)13 b(a)j(set)h(of)e(k)o(e)o(ybindings)e (resembling)h(those)i(of)f(Emacs)g(\(thus,)h(also)g(of)g(Netscape)f(Na) n(vigator)m(,)g(BBedit)h(6.x,)g(FrameMak)o(er)m(,)0 1836 y(and)23 b(man)o(y)g(other)g(programs\).)34 b(The)24 b(module)e(also)i(pro)o(vides)e(a)j(rectangle-dra)o(wing)20 b(function)i(useful)i(for)f(framing)f(te)o(xt)i(box)o(es)f(or)0 1935 y(for)d(other)f(purposes.)0 2082 y(The)h(module)f FJ(curses.textpad)f FN(de\002nes)i(the)g(follo)n(wing)f(function:)0 2229 y FD(rectangle)p FJ(\()p FK(win,)g(uly)-5 b(,)20 b(ulx,)g(lry)-5 b(,)21 b(lrx)p FJ(\))208 2329 y FN(Dra)o(w)c(a)h (rectangle.)23 b(The)17 b(\002rst)h(ar)o(gument)d(must)j(be)f(a)h (windo)n(w)f(object;)g(the)h(remaining)e(ar)o(guments)f(are)j (coordinates)d(relati)n(v)o(e)208 2428 y(to)25 b(that)h(windo)n(w)-5 b(.)40 b(The)25 b(second)g(and)g(third)g(ar)o(guments)f(are)i(the)f(y)h (and)f(x)h(coordinates)e(of)h(the)h(upper)e(left)i(hand)f(corner)f(of) 208 2528 y(the)i(rectangle)f(to)i(be)f(dra)o(wn;)j(the)d(fourth)f(and)h (\002fth)g(ar)o(guments)f(are)h(the)h(y)f(and)g(x)g(coordinates)f(of)h (the)h(lo)n(wer)f(right)g(hand)208 2627 y(corner)-5 b(.)23 b(The)17 b(rectangle)g(will)i(be)f(dra)o(wn)e(using)i(VT100/IBM)f(PC)i (forms)e(characters)g(on)g(terminals)h(that)g(mak)o(e)f(this)i (possible)208 2727 y(\(including)h(xterm)i(and)g(most)h(other)f(softw)o (are)h(terminal)f(emulators\).)31 b(Otherwise)23 b(it)g(will)h(be)e (dra)o(wn)g(with)h(ASCII)g(dashes,)208 2827 y(v)o(ertical)c(bars,)h (and)g(plus)g(signs.)0 3112 y Fv(14.8.1)101 b(T)-12 b(e)m(xtbo)m(x)28 b(objects)0 3314 y FN(Y)-9 b(ou)20 b(can)g(instantiate)g(a)g FJ(Textbox)g FN(object)f(as)i(follo)n(ws:)0 3461 y FL(class)g FD(Textbox)p FJ(\()p FK(win)p FJ(\))208 3561 y FN(Return)e(a)i(te)o (xtbox)d(widget)i(object.)k(The)c FK(win)h FN(ar)o(gument)d(should)h (be)h(a)g(curses)h FJ(WindowObject)d FN(in)i(which)g(the)g(te)o(xtbox)f (is)208 3661 y(to)h(be)g(contained.)j(The)d(edit)g(cursor)f(of)h(the)g (te)o(xtbox)e(is)j(initially)f(located)f(at)i(the)f(upper)f(left)h (hand)f(corner)g(of)g(the)h(containing)208 3760 y(windo)n(w)-5 b(,)18 b(with)i(coordinates)f FJ(\(0,)49 b(0\))p FN(.)25 b(The)20 b(instance')-5 b(s)20 b FJ(stripspaces)f FN(\003ag)h(is)h (initially)g(on.)0 3907 y FJ(Textbox)e FN(objects)h(ha)n(v)o(e)g(the)g (follo)n(wing)f(methods:)0 4054 y FD(edit)p FJ(\()p FC([)p FK(validator)14 b FC(])p FJ(\))208 4154 y FN(This)i(is)h(the)f(entry)f (point)g(you)g(will)i(normally)d(use.)24 b(It)16 b(accepts)g(editing)g (k)o(e)o(ystrok)o(es)e(until)i(one)g(of)f(the)h(termination)f(k)o(e)o (ystrok)o(es)208 4253 y(is)24 b(entered.)35 b(If)24 b FK(validator)h FN(is)f(supplied,)g(it)g(must)g(be)g(a)g(function.)35 b(It)24 b(will)g(be)g(called)g(for)f(each)g(k)o(e)o(ystrok)o(e)g (entered)g(with)h(the)208 4353 y(k)o(e)o(ystrok)o(e)18 b(as)j(a)g(parameter;)e(command)g(dispatch)g(is)i(done)f(on)g(the)g (result.)26 b(This)20 b(method)f(returns)h(the)g(windo)n(w)f(contents)h (as)208 4452 y(a)g(string;)g(whether)f(blanks)h(in)g(the)g(windo)n(w)g (are)g(included)e(is)j(af)n(fected)e(by)h(the)g FJ(stripspaces)f FN(member)-5 b(.)0 4599 y FD(do_command)p FJ(\()p FK(c)o(h)p FJ(\))208 4699 y FN(Process)20 b(a)h(single)f(command)e(k)o(e)o(ystrok) o(e.)23 b(Here)d(are)g(the)h(supported)d(special)i(k)o(e)o(ystrok)o (es:)p 0 5549 3901 4 v 0 5649 a FI(14.8.)52 b FJ(curses.textpad)21 b FI(\227)i(T)-10 b(e)n(xt)22 b(input)i(widget)g(f)n(or)e(curses)g (prog)o(r)o(ams)1327 b(487)p eop end %%Page: 488 500 TeXDict begin 488 499 bop 716 70 a FL(K)n(eystr)o(ok)o(e)p 1212 100 4 100 v 186 w(Action)p 666 103 2776 4 v 716 173 a FJ(Control-A)p 1212 203 4 100 v 98 w FN(Go)20 b(to)g(left)h(edge) e(of)h(windo)n(w)-5 b(.)716 272 y FJ(Control-B)p 1212 302 V 98 w FN(Cursor)19 b(left,)i(wrapping)d(to)i(pre)n(vious)f(line)h (if)h(appropriate.)716 372 y FJ(Control-D)p 1212 402 V 98 w FN(Delete)f(character)f(under)g(cursor)-5 b(.)716 472 y FJ(Control-E)p 1212 501 V 98 w FN(Go)20 b(to)g(right)g(edge)f (\(stripspaces)h(of)n(f\))f(or)h(end)g(of)g(line)g(\(stripspaces)f (on\).)716 571 y FJ(Control-F)p 1212 601 V 98 w FN(Cursor)g(right,)h (wrapping)e(to)i(ne)o(xt)g(line)g(when)g(appropriate.)716 671 y FJ(Control-G)p 1212 701 V 98 w FN(T)-6 b(erminate,)19 b(returning)f(the)i(windo)n(w)f(contents.)716 770 y FJ(Control-H)p 1212 800 V 98 w FN(Delete)h(character)f(backw)o(ard.)716 870 y FJ(Control-J)p 1212 900 V 98 w FN(T)-6 b(erminate)19 b(if)h(the)g(windo)n(w)g(is)h(1)f(line,)g(otherwise)g(insert)g(ne)n (wline.)716 970 y FJ(Control-K)p 1212 1000 V 98 w FN(If)g(line)g(is)h (blank,)e(delete)h(it,)h(otherwise)e(clear)h(to)h(end)e(of)h(line.)716 1069 y FJ(Control-L)p 1212 1099 V 98 w FN(Refresh)g(screen.)716 1169 y FJ(Control-N)p 1212 1199 V 98 w FN(Cursor)f(do)n(wn;)h(mo)o(v)o (e)e(do)n(wn)h(one)h(line.)716 1269 y FJ(Control-O)p 1212 1298 V 98 w FN(Insert)f(a)i(blank)e(line)i(at)f(cursor)f (location.)716 1368 y FJ(Control-P)p 1212 1398 V 98 w FN(Cursor)g(up;)h(mo)o(v)o(e)f(up)h(one)f(line.)208 1495 y(Mo)o(v)o(e)27 b(operations)g(do)i(nothing)e(if)i(the)g(cursor)f(is)i (at)f(an)g(edge)f(where)g(the)h(mo)o(v)o(ement)e(is)j(not)e(possible.) 51 b(The)28 b(follo)n(wing)208 1595 y(synon)o(yms)18 b(are)i(supported)e(where)i(possible:)1456 1723 y FL(Constant)p 2152 1753 V 423 w(K)n(eystr)o(ok)o(e)p 1406 1756 1296 4 v 1456 1826 a FJ(KEY_LEFT)p 2152 1856 4 100 v 347 w(Control-B)1456 1926 y(KEY_RIGHT)p 2152 1955 V 297 w(Control-F)1456 2025 y(KEY_UP)p 2152 2055 V 447 w(Control-P)1456 2125 y(KEY_DOWN)p 2152 2155 V 347 w(Control-N)1456 2224 y(KEY_BACKSPACE)p 2152 2254 V 97 w(Control-h)208 2351 y FN(All)f(other)f(k)o(e)o(ystrok)o (es)f(are)i(treated)f(as)h(a)g(command)e(to)i(insert)g(the)f(gi)n(v)o (en)g(character)f(and)h(mo)o(v)o(e)g(right)g(\(with)g(line)h (wrapping\).)0 2498 y FD(gather)p FJ(\(\))208 2598 y FN(This)i(method)f(returns)h(the)g(windo)n(w)g(contents)f(as)j(a)e (string;)h(whether)f(blanks)g(in)g(the)h(windo)n(w)e(are)h(included)f (is)j(af)n(fected)d(by)208 2698 y(the)g FJ(stripspaces)e FN(member)-5 b(.)0 2844 y FD(stripspaces)208 2944 y FN(This)26 b(data)g(member)e(is)j(a)g(\003ag)f(which)f(controls)g(the)h (interpretation)e(of)i(blanks)f(in)h(the)g(windo)n(w)-5 b(.)41 b(When)26 b(it)g(is)h(on,)g(trailing)208 3044 y(blanks)18 b(on)g(each)h(line)g(are)g(ignored;)f(an)o(y)g(cursor)g (motion)g(that)h(w)o(ould)f(land)h(the)g(cursor)f(on)g(a)i(trailing)e (blank)g(goes)h(to)g(the)g(end)208 3143 y(of)g(that)i(line)f(instead,)g (and)f(trailing)h(blanks)g(are)g(stripped)f(when)g(the)i(windo)n(w)e (contents)g(are)h(gathered.)0 3470 y FE(14.9)121 b Fx(curses.wrapper)30 b FE(\227)i(T)-14 b(er)s(minal)33 b(handler)i(f)l(or)f(curses)g(prog)o (r)o(ams)0 3703 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.6.)0 3850 y(This)e(module)e(supplies)h(one)g(function,)g FJ(wrapper\(\))p FN(,)f(which)i(runs)f(another)f(function)g(which)h(should)f(be)i(the)f (rest)h(of)g(your)e(curses-)0 3949 y(using)22 b(application.)30 b(If)22 b(the)h(application)d(raises)j(an)g(e)o(xception,)e FJ(wrapper\(\))g FN(will)i(restore)f(the)g(terminal)g(to)h(a)f(sane)h (state)g(before)0 4049 y(re-raising)c(the)h(e)o(xception)e(and)i (generating)e(a)j(traceback.)0 4196 y FD(wrapper)p FJ(\()p FK(func,)d(...)p FJ(\))208 4295 y FN(Wrapper)k(function)f(that)i (initializes)h(curses)f(and)g(calls)h(another)d(function,)h FK(func)p FN(,)i(restoring)d(normal)h(k)o(e)o(yboard/screen)e(be-)208 4395 y(ha)n(vior)f(on)i(error)-5 b(.)25 b(The)c(callable)f(object)g FK(func)g FN(is)i(then)e(passed)h(the)g(main)f(windo)n(w)g(')-5 b(stdscr')20 b(as)i(its)f(\002rst)h(ar)o(gument,)c(follo)n(wed)208 4495 y(by)h(an)o(y)h(other)f(ar)o(guments)f(passed)i(to)h FJ(wrapper\(\))p FN(.)0 4641 y(Before)26 b(calling)g(the)g(hook)f (function,)h FJ(wrapper\(\))f FN(turns)h(on)g(cbreak)f(mode,)i(turns)f (of)n(f)g(echo,)h(enables)f(the)g(terminal)g(k)o(e)o(ypad,)0 4741 y(and)21 b(initializes)h(colors)g(if)g(the)f(terminal)h(has)g (color)e(support.)29 b(On)22 b(e)o(xit)f(\(whether)g(normally)f(or)h (by)h(e)o(xception\))d(it)k(restores)e(cook)o(ed)0 4841 y(mode,)e(turns)h(on)g(echo,)f(and)g(disables)i(the)f(terminal)f(k)o(e) o(ypad.)0 5167 y FE(14.10)122 b Fx(curses.ascii)30 b FE(\227)i(Utilities)h(f)l(or)h(ASCII)g(char)o(acters)0 5400 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.6.)p 0 5549 3901 4 v 0 5649 a FI(488)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 489 501 TeXDict begin 489 500 bop 0 83 a FN(The)31 b FJ(curses.ascii)f FN(module)h(supplies)g(name)g(constants)h(for)h FH(A)t(S)t(C)t(I)t(I)i FN(characters)c(and)g(functions)f(to)i(test)h(membership)c(in)0 183 y(v)n(arious)21 b FH(A)t(S)t(C)t(I)t(I)j FN(character)19 b(classes.)26 b(The)20 b(constants)f(supplied)g(are)i(names)e(for)h (control)f(characters)g(as)i(follo)n(ws:)1091 381 y FL(Name)p 1346 411 4 100 v 99 w(Meaning)p 1041 414 1819 4 v 1091 484 a FJ(NUL)p 1346 514 4 100 v 1091 583 a(SOH)p 1346 613 V 157 w FN(Start)f(of)g(heading,)f(console)g(interrupt)1091 683 y FJ(STX)p 1346 713 V 157 w FN(Start)h(of)g(te)o(xt)1091 783 y FJ(ETX)p 1346 812 V 157 w FN(End)f(of)h(te)o(xt)1091 882 y FJ(EOT)p 1346 912 V 157 w FN(End)f(of)h(transmission)1091 982 y FJ(ENQ)p 1346 1012 V 157 w FN(Enquiry)-5 b(,)17 b(goes)j(with)h FJ(ACK)f FN(\003o)n(w)g(control)1091 1081 y FJ(ACK)p 1346 1111 V 157 w FN(Ackno)n(wledgement)1091 1181 y FJ(BEL)p 1346 1211 V 157 w FN(Bell)1091 1281 y FJ(BS)p 1346 1311 V 207 w FN(Backspace)1091 1380 y FJ(TAB)p 1346 1410 V 157 w FN(T)-7 b(ab)1091 1480 y FJ(HT)p 1346 1510 V 207 w FN(Alias)21 b(for)e FJ(TAB)p FN(:)i(\223Horizontal)d (tab\224)1091 1580 y FJ(LF)p 1346 1609 V 207 w FN(Line)i(feed)1091 1679 y FJ(NL)p 1346 1709 V 207 w FN(Alias)h(for)e FJ(LF)p FN(:)i(\223Ne)n(w)f(line\224)1091 1779 y FJ(VT)p 1346 1809 V 207 w FN(V)-9 b(ertical)20 b(tab)1091 1878 y FJ(FF)p 1346 1908 V 207 w FN(F)o(orm)f(feed)1091 1978 y FJ(CR)p 1346 2008 V 207 w FN(Carriage)g(return)1091 2078 y FJ(SO)p 1346 2108 V 207 w FN(Shift-out,)f(be)o(gin)h(alternate)h(character)f (set)1091 2177 y FJ(SI)p 1346 2207 V 207 w FN(Shift-in,)g(resume)g(def) o(ault)h(character)f(set)1091 2277 y FJ(DLE)p 1346 2307 V 157 w FN(Data-link)g(escape)1091 2377 y FJ(DC1)p 1346 2406 V 157 w FN(XON,)h(for)g(\003o)n(w)g(control)1091 2476 y FJ(DC2)p 1346 2506 V 157 w FN(De)n(vice)g(control)e(2,)j (block-mode)c(\003o)n(w)j(control)1091 2576 y FJ(DC3)p 1346 2606 V 157 w FN(XOFF)-7 b(,)21 b(for)e(\003o)n(w)i(control)1091 2675 y FJ(DC4)p 1346 2705 V 157 w FN(De)n(vice)f(control)e(4)1091 2775 y FJ(NAK)p 1346 2805 V 157 w FN(Ne)o(gati)n(v)o(e)g(ackno)n (wledgement)1091 2875 y FJ(SYN)p 1346 2905 V 157 w FN(Synchronous)f (idle)1091 2974 y FJ(ETB)p 1346 3004 V 157 w FN(End)i(transmission)h (block)1091 3074 y FJ(CAN)p 1346 3104 V 157 w FN(Cancel)1091 3174 y FJ(EM)p 1346 3203 V 207 w FN(End)f(of)h(medium)1091 3273 y FJ(SUB)p 1346 3303 V 157 w FN(Substitute)1091 3373 y FJ(ESC)p 1346 3403 V 157 w FN(Escape)1091 3472 y FJ(FS)p 1346 3502 V 207 w FN(File)h(separator)1091 3572 y FJ(GS)p 1346 3602 V 207 w FN(Group)e(separator)1091 3672 y FJ(RS)p 1346 3702 V 207 w FN(Record)g(separator)m(,)g (block-mode)e(terminator)1091 3771 y FJ(US)p 1346 3801 V 207 w FN(Unit)j(separator)1091 3871 y FJ(SP)p 1346 3901 V 207 w FN(Space)1091 3971 y FJ(DEL)p 1346 4001 V 157 w FN(Delete)0 4168 y(Note)27 b(that)g(man)o(y)e(of)i(these)g(ha)n (v)o(e)f(little)i(practical)e(signi\002cance)g(in)h(modern)e(usage.)44 b(The)26 b(mnemonics)g(deri)n(v)o(e)f(from)h(teleprinter)0 4267 y(con)m(v)o(entions)17 b(that)k(predate)e(digital)h(computers.)0 4414 y(The)g(module)f(supplies)h(the)g(follo)n(wing)e(functions,)h (patterned)g(on)g(those)h(in)h(the)f(standard)f(C)i(library:)0 4561 y FD(isalnum)p FJ(\()p FK(c)p FJ(\))208 4661 y FN(Checks)f(for)f (an)j FH(A)t(S)t(C)t(I)t(I)i FN(alphanumeric)18 b(character;)h(it)i(is) g(equi)n(v)n(alent)d(to)j(`)p FJ(isalpha\()p FK(c)p FJ(\))47 b(or)j(isdigit\()p FK(c)p FJ(\))p FN('.)0 4807 y FD(isalpha)p FJ(\()p FK(c)p FJ(\))208 4907 y FN(Checks)20 b(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(alphabetic)19 b(character;)g(it)i(is)g(equi)n (v)n(alent)e(to)h(`)p FJ(isupper\()p FK(c)p FJ(\))48 b(or)h(islower\()p FK(c)p FJ(\))p FN('.)0 5054 y FD(isascii)p FJ(\()p FK(c)p FJ(\))208 5154 y FN(Checks)20 b(for)f(a)i(character)e(v) n(alue)g(that)i(\002ts)g(in)f(the)g(7-bit)i FH(A)t(S)t(C)t(I)t(I)i FN(set.)0 5300 y FD(isblank)p FJ(\()p FK(c)p FJ(\))208 5400 y FN(Checks)c(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(whitespace)c(character)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(14.10.)52 b FJ(curses.ascii)21 b FI(\227)i(Utilities)i(f)n (or)d(ASCII)i(char)o(acters)1717 b(489)p eop end %%Page: 490 502 TeXDict begin 490 501 bop 0 83 a FD(iscntrl)p FJ(\()p FK(c)p FJ(\))208 183 y FN(Checks)20 b(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(control)19 b(character)g(\(in)h(the)g(range)f(0x00)g(to)h(0x1f\).)0 330 y FD(isdigit)p FJ(\()p FK(c)p FJ(\))208 429 y FN(Checks)g(for)f(an) j FH(A)t(S)t(C)t(I)t(I)i FN(decimal)c(digit,)f(`)p FJ(0)p FN(')h(through)e(`)p FJ(9)p FN('.)25 b(This)20 b(is)h(equi)n(v)n(alent) e(to)h(`)p FK(c)50 b FJ(in)f(string.digits)p FN('.)0 576 y FD(isgraph)p FJ(\()p FK(c)p FJ(\))208 676 y FN(Checks)20 b(for)h FH(A)t(S)t(C)t(I)t(I)j FN(an)o(y)19 b(printable)g(character)g (e)o(xcept)g(space.)0 823 y FD(islower)p FJ(\()p FK(c)p FJ(\))208 922 y FN(Checks)h(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(lo)n(wer)n(-case)c(character)-5 b(.)0 1069 y FD(isprint)p FJ(\()p FK(c)p FJ(\))208 1169 y FN(Checks)20 b(for)f(an)o(y)j FH(A)t(S)t(C)t(I)t(I)h FN(printable)c(character)g(including)g(space.)0 1316 y FD(ispunct)p FJ(\()p FK(c)p FJ(\))208 1415 y FN(Checks)h(for)f (an)o(y)h(printable)h FH(A)t(S)t(C)t(I)t(I)i FN(character)c(which)h(is) h(not)f(a)g(space)h(or)f(an)g(alphanumeric)d(character)-5 b(.)0 1562 y FD(isspace)p FJ(\()p FK(c)p FJ(\))208 1662 y FN(Checks)26 b(for)i FH(A)t(S)t(C)t(I)t(I)i FN(white-space)25 b(characters;)k(space,)f(line)f(feed,)g(carriage)e(return,)i(form)e (feed,)j(horizontal)c(tab,)k(v)o(ertical)208 1761 y(tab)m(.)0 1908 y FD(isupper)p FJ(\()p FK(c)p FJ(\))208 2008 y FN(Checks)20 b(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(uppercase)19 b(letter)-5 b(.)0 2155 y FD(isxdigit)p FJ(\()p FK(c)p FJ(\))208 2254 y FN(Checks)20 b(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(he)o(xadecimal)18 b(digit.)25 b(This)20 b(is)h(equi)n(v)n(alent)e(to)h(`)p FK(c)50 b FJ(in)f(string.hexdigits)p FN('.)0 2401 y FD(isctrl)p FJ(\()p FK(c)p FJ(\))208 2501 y FN(Checks)20 b(for)f(an)j FH(A)t(S)t(C)t(I)t(I)i FN(control)19 b(character)g(\(ordinal)g(v)n (alues)g(0)i(to)f(31\).)0 2648 y FD(ismeta)p FJ(\()p FK(c)p FJ(\))208 2747 y FN(Checks)g(for)f(a)i(non-)r FH(A)t(S)t(C)t(I)t(I)h FN(character)d(\(ordinal)f(v)n(alues)i(0x80)f (and)h(abo)o(v)o(e\).)0 2894 y(These)i(functions)g(accept)g(either)g (inte)o(gers)g(or)g(strings;)i(when)e(the)h(ar)o(gument)d(is)k(a)f (string,)g(it)g(is)h(\002rst)f(con)m(v)o(erted)d(using)i(the)h(b)n (uilt-in)0 2994 y(function)18 b FJ(ord\(\))p FN(.)0 3141 y(Note)j(that)f(all)h(these)g(functions)e(check)h(ordinal)f(bit)i(v)n (alues)f(deri)n(v)o(ed)f(from)g(the)i(\002rst)g(character)e(of)i(the)f (string)g(you)g(pass)h(in;)g(the)o(y)f(do)0 3240 y(not)h(actually)f (kno)n(w)g(an)o(ything)e(about)i(the)h(host)g(machine')-5 b(s)20 b(character)g(encoding.)k(F)o(or)d(functions)e(that)i(kno)n(w)f (about)g(the)h(character)0 3340 y(encoding)d(\(and)h(handle)g (internationalization)f(properly\))g(see)i(the)h FJ(string)e FN(module.)0 3487 y(The)h(follo)n(wing)f(tw)o(o)h(functions)f(tak)o(e)h (either)g(a)h(single-character)d(string)i(or)g(inte)o(ger)f(byte)h(v)n (alue;)g(the)o(y)g(return)f(a)h(v)n(alue)g(of)g(the)g(same)0 3586 y(type.)0 3733 y FD(ascii)p FJ(\()p FK(c)p FJ(\))208 3833 y FN(Return)f(the)i(ASCII)f(v)n(alue)g(corresponding)c(to)21 b(the)f(lo)n(w)g(7)g(bits)h(of)f FK(c)p FN(.)0 3980 y FD(ctrl)p FJ(\()p FK(c)p FJ(\))208 4079 y FN(Return)h(the)g(control)g (character)f(corresponding)e(to)k(the)f(gi)n(v)o(en)g(character)f (\(the)h(character)f(bit)i(v)n(alue)f(is)i(bitwise-anded)c(with)208 4179 y(0x1f\).)0 4326 y FD(alt)p FJ(\()p FK(c)p FJ(\))208 4425 y FN(Return)25 b(the)g(8-bit)g(character)f(corresponding)f(to)i (the)h(gi)n(v)o(en)e(ASCII)i(character)e(\(the)i(character)e(bit)i(v)n (alue)e(is)j(bitwise-ored)208 4525 y(with)20 b(0x80\).)0 4672 y(The)g(follo)n(wing)e(function)h(tak)o(es)h(either)g(a)h (single-character)d(string)i(or)g(inte)o(ger)f(v)n(alue;)g(it)i (returns)e(a)i(string.)0 4819 y FD(unctrl)p FJ(\()p FK(c)p FJ(\))208 4918 y FN(Return)g(a)h(string)g(representation)e(of)h(the)j FH(A)t(S)t(C)t(I)t(I)i FN(character)20 b FK(c)p FN(.)31 b(If)22 b FK(c)g FN(is)h(printable,)e(this)h(string)g(is)h(the)e (character)g(itself.)31 b(If)22 b(the)208 5018 y(character)i(is)j(a)f (control)f(character)f(\(0x00-0x1f\))e(the)j(string)h(consists)g(of)g (a)g(caret)g(\(`)p FJ(\210)p FN('\))e(follo)n(wed)h(by)g(the)h (corresponding)208 5118 y(uppercase)c(letter)-5 b(.)37 b(If)23 b(the)h(character)f(is)i(an)h FH(A)t(S)t(C)t(I)t(I)h FN(delete)d(\(0x7f\))e(the)i(string)f(is)i FJ('\210?')p FN(.)36 b(If)24 b(the)g(character)e(has)j(its)f(meta)g(bit)208 5217 y(\(0x80\))18 b(set,)i(the)h(meta)f(bit)g(is)h(stripped,)e(the)i (preceding)d(rules)i(applied,)f(and)g(`)p FJ(!)p FN(')25 b(prepended)18 b(to)i(the)g(result.)0 5364 y FD(controlnames)p 0 5549 3901 4 v 0 5649 a FI(490)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 491 503 TeXDict begin 491 502 bop 208 83 a FN(A)20 b(33-element)d(string)i (array)g(that)h(contains)f(the)i FH(A)t(S)t(C)t(I)t(I)i FN(mnemonics)18 b(for)h(the)h(thirty-tw)o(o)g FH(A)t(S)t(C)t(I)t(I)j FN(control)18 b(characters)h(from)f(0)208 183 y(\(NUL\))h(to)i(0x1f)d (\(US\),)i(in)h(order)m(,)d(plus)i(the)g(mnemonic)f(`)p FJ(SP)p FN(')g(for)h(the)g(space)g(character)-5 b(.)0 510 y FE(14.11)122 b Fx(curses.panel)30 b FE(\227)i(A)h(panel)i(stac)n (k)e(e)l(xtension)i(f)l(or)f(curses)n(.)0 743 y FN(P)o(anels)22 b(are)f(windo)n(ws)g(with)h(the)f(added)g(feature)f(of)h(depth,)g(so)h (the)o(y)f(can)g(be)h(stack)o(ed)f(on)g(top)g(of)h(each)f(other)m(,)f (and)h(only)g(the)h(visible)0 843 y(portions)d(of)h(each)g(windo)n(w)f (will)i(be)f(displayed.)k(P)o(anels)c(can)g(be)g(added,)f(mo)o(v)o(ed)f (up)i(or)g(do)n(wn)f(in)h(the)g(stack,)h(and)e(remo)o(v)o(ed.)0 1127 y Fv(14.11.1)101 b(Functions)0 1330 y FN(The)20 b(module)f FJ(curses.panel)f FN(de\002nes)i(the)g(follo)n(wing)f (functions:)0 1477 y FD(bottom_panel)p FJ(\(\))208 1577 y FN(Returns)h(the)g(bottom)f(panel)g(in)i(the)f(panel)g(stack.)0 1724 y FD(new_panel)p FJ(\()p FK(win)p FJ(\))208 1823 y FN(Returns)i(a)h(panel)f(object,)g(associating)g(it)i(with)e(the)h (gi)n(v)o(en)e(windo)n(w)h FK(win)p FN(.)32 b(Be)24 b(a)o(w)o(are)e (that)h(you)e(need)h(to)h(k)o(eep)f(the)g(returned)208 1923 y(panel)27 b(object)h(referenced)e(e)o(xplicitly)-5 b(.)48 b(If)28 b(you)g(don')o(t,)g(the)g(panel)g(object)g(is)h(garbage) d(collected)i(and)f(remo)o(v)o(ed)f(from)i(the)208 2023 y(panel)19 b(stack.)0 2169 y FD(top_panel)p FJ(\(\))208 2269 y FN(Returns)h(the)g(top)g(panel)f(in)i(the)f(panel)f(stack.)0 2416 y FD(update_panels)p FJ(\(\))208 2516 y FN(Updates)28 b(the)h(virtual)f(screen)h(after)f(changes)g(in)h(the)g(panel)f(stack.) 51 b(This)29 b(does)g(not)g(call)g FJ(curses.doupdate\(\))p FN(,)f(so)208 2615 y(you')o(ll)19 b(ha)n(v)o(e)g(to)i(do)f(this)g (yourself.)0 2900 y Fv(14.11.2)101 b(P)l(anel)29 b(Objects)0 3103 y FN(P)o(anel)c(objects,)i(as)f(returned)e(by)h FJ(new_panel\(\))f FN(abo)o(v)o(e,)h(are)g(windo)n(ws)g(with)h(a)g (stacking)e(order)-5 b(.)41 b(There')-5 b(s)25 b(al)o(w)o(ays)h(a)g (windo)n(w)0 3203 y(associated)19 b(with)g(a)g(panel)f(which)h (determines)e(the)i(content,)f(while)h(the)g(panel)f(methods)g(are)h (responsible)e(for)h(the)h(windo)n(w')-5 b(s)19 b(depth)0 3302 y(in)h(the)h(panel)e(stack.)0 3449 y(P)o(anel)h(objects)g(ha)n(v)o (e)g(the)g(follo)n(wing)e(methods:)0 3596 y FD(above)p FJ(\(\))208 3696 y FN(Returns)i(the)g(panel)f(abo)o(v)o(e)g(the)h (current)f(panel.)0 3842 y FD(below)p FJ(\(\))208 3942 y FN(Returns)h(the)g(panel)f(belo)n(w)h(the)g(current)f(panel.)0 4089 y FD(bottom)p FJ(\(\))208 4189 y FN(Push)h(the)g(panel)g(to)g(the) g(bottom)f(of)h(the)g(stack.)0 4335 y FD(hidden)p FJ(\(\))208 4435 y FN(Returns)g(true)f(if)i(the)f(panel)g(is)h(hidden)e(\(not)g (visible\),)h(f)o(alse)g(otherwise.)0 4582 y FD(hide)p FJ(\(\))208 4682 y FN(Hide)g(the)g(panel.)k(This)d(does)f(not)f(delete) h(the)h(object,)e(it)i(just)g(mak)o(es)f(the)g(windo)n(w)f(on)h(screen) g(in)m(visible.)0 4828 y FD(move)p FJ(\()p FK(y)-5 b(,)20 b(x)p FJ(\))208 4928 y FN(Mo)o(v)o(e)f(the)h(panel)f(to)i(the)f(screen) g(coordinates)e FJ(\()p FK(y)p FJ(,)49 b FK(x)p FJ(\))p FN(.)0 5075 y FD(replace)p FJ(\()p FK(win)p FJ(\))208 5175 y FN(Change)19 b(the)h(windo)n(w)f(associated)h(with)h(the)f (panel)f(to)i(the)f(windo)n(w)f FK(win)p FN(.)0 5321 y FD(set_userptr)p FJ(\()p FK(obj)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(14.11.)52 b FJ(curses.panel)21 b FI(\227)i(A)h(panel)g (stac)n(k)e(e)n(xtension)h(f)n(or)g(curses)o(.)1471 b(491)p eop end %%Page: 492 504 TeXDict begin 492 503 bop 208 83 a FN(Set)20 b(the)g(panel')-5 b(s)20 b(user)f(pointer)g(to)h FK(obj)p FN(.)25 b(This)20 b(is)h(used)e(to)h(associate)g(an)g(arbitrary)f(piece)g(of)h(data)g (with)g(the)g(panel,)f(and)g(can)h(be)208 183 y(an)o(y)f(Python)g (object.)0 330 y FD(show)p FJ(\(\))208 429 y FN(Display)h(the)g(panel)f (\(which)h(might)f(ha)n(v)o(e)h(been)f(hidden\).)0 576 y FD(top)p FJ(\(\))208 676 y FN(Push)h(panel)f(to)i(the)f(top)g(of)g (the)g(stack.)0 823 y FD(userptr)p FJ(\(\))208 922 y FN(Returns)g(the)g(user)g(pointer)f(for)g(the)i(panel.)j(This)c(might)g (be)g(an)o(y)f(Python)g(object.)0 1069 y FD(window)p FJ(\(\))208 1169 y FN(Returns)h(the)g(windo)n(w)f(object)h(associated)g (with)g(the)g(panel.)0 1490 y FE(14.12)122 b Fx(platform)31 b FE(\227)i(Access)f(to)i(under)r(lying)h(platf)l(or)s(m')-6 b(s)33 b(identifying)i(data.)0 1723 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.3.)0 1870 y FL(Note:)24 b FN(Speci\002c)d(platforms)e(listed)h (alphabetically)-5 b(,)18 b(with)i(Linux)g(included)e(in)j(the)h(U)t FH(N)t(I)t(X)h FN(section.)0 2149 y Fv(14.12.1)101 b(Cross)28 b(Platf)m(or)r(m)0 2332 y FD(architecture)p FJ(\()p FK(e)n (xecutable=sys.e)n(xecutable)o(,)15 b(bits=\224,)21 b(linka)o(g)o (e=\224)p FJ(\))208 2432 y FN(Queries)f(the)g(gi)n(v)o(en)f(e)o(x)o (ecutable)f(\(def)o(aults)h(to)i(the)f(Python)f(interpreter)f(binary\)) h(for)h(v)n(arious)f(architecture)f(information.)208 2558 y(Returns)31 b(a)g(tuple)g FJ(\(bits,)49 b(linkage\))30 b FN(which)h(contain)f(information)f(about)h(the)h(bit)h(architecture)e (and)g(the)i(linkage)208 2658 y(format)19 b(used)h(for)f(the)h(e)o(x)o (ecutable.)j(Both)e(v)n(alues)e(are)h(returned)f(as)i(strings.)208 2785 y(V)-9 b(alues)28 b(that)g(cannot)g(be)g(determined)f(are)h (returned)f(as)i(gi)n(v)o(en)e(by)h(the)g(parameter)f(presets.)50 b(If)28 b(bits)h(is)h(gi)n(v)o(en)d(as)i FJ('')p FN(,)i(the)208 2884 y FJ(sizeof\(pointer\))23 b FN(\(or)i FJ(sizeof\(long\))g FN(on)g(Python)g(v)o(ersion)g(\241)h(1.5.2\))e(is)j(used)e(as)i (indicator)d(for)i(the)g(supported)208 2984 y(pointer)19 b(size.)208 3111 y(The)25 b(function)e(relies)j(on)f(the)h(system')-5 b(s)26 b(`)p FO(\002le)p FN(')f(command)e(to)j(do)f(the)h(actual)f(w)o (ork.)40 b(This)26 b(is)g(a)n(v)n(ailable)f(on)g(most)h(if)g(not)f(all) 210 3210 y(U)t FH(N)t(I)t(X)e FN(platforms)d(and)g(some)g(non-)r(U)t FH(N)t(I)t(X)i FN(platforms)d(and)h(then)g(only)g(if)h(the)f(e)o(x)o (ecutable)f(points)h(to)h(the)g(Python)e(interpreter)-5 b(.)208 3310 y(Reasonable)19 b(def)o(aults)h(are)g(used)g(when)f(the)i (abo)o(v)o(e)d(needs)i(are)g(not)g(met.)0 3457 y FD(machine)p FJ(\(\))208 3556 y FN(Returns)g(the)g(machine)f(type,)g(e.g.)25 b FJ('i386')p FN(.)f(An)c(empty)g(string)g(is)h(returned)d(if)j(the)f (v)n(alue)f(cannot)g(be)i(determined.)0 3703 y FD(node)p FJ(\(\))208 3803 y FN(Returns)26 b(the)g(computer')-5 b(s)25 b(netw)o(ork)g(name)h(\(may)f(not)h(be)g(fully)g (quali\002ed!\).)42 b(An)26 b(empty)g(string)g(is)h(returned)d(if)j (the)f(v)n(alue)208 3902 y(cannot)19 b(be)h(determined.)0 4049 y FD(platform)p FJ(\()p FK(aliased=0,)d(ter)o(se=0)p FJ(\))208 4149 y FN(Returns)j(a)g(single)g(string)g(identifying)e(the)j (underlying)c(platform)i(with)h(as)h(much)e(useful)h(information)e(as)j (possible.)208 4275 y(The)h(output)f(is)j(intended)d(to)i(be)g FK(human)e(r)m(eadable)g FN(rather)h(than)g(machine)g(parseable.)31 b(It)23 b(may)f(look)g(dif)n(ferent)f(on)h(dif)n(ferent)208 4375 y(platforms)d(and)g(this)i(is)g(intended.)208 4502 y(If)f FK(aliased)i FN(is)g(true,)e(the)h(function)d(will)k(use)f (aliases)g(for)f(v)n(arious)g(platforms)f(that)i(report)e(system)i (names)f(which)g(dif)n(fer)g(from)208 4601 y(their)e(common)e(names,)i (for)g(e)o(xample)f(SunOS)h(will)h(be)f(reported)e(as)j(Solaris.)25 b(The)18 b FJ(system_alias\(\))e FN(function)h(is)i(used)208 4701 y(to)h(implement)f(this.)208 4828 y(Setting)g FK(ter)o(se)i FN(to)f(true)f(causes)h(the)g(function)e(to)i(return)e(only)h(the)h (absolute)f(minimum)f(information)g(needed)g(to)i(identify)f(the)208 4927 y(platform.)0 5074 y FD(processor)p FJ(\(\))208 5174 y FN(Returns)h(the)g(\(real\))f(processor)g(name,)h(e.g.)k FJ('amdk6')p FN(.)208 5300 y(An)h(empty)g(string)h(is)g(returned)e(if)i (the)g(v)n(alue)f(cannot)g(be)g(determined.)40 b(Note)26 b(that)g(man)o(y)e(platforms)h(do)g(not)g(pro)o(vide)f(this)208 5400 y(information)17 b(or)j(simply)g(return)f(the)h(same)h(v)n(alue)e (as)i(for)f FJ(machine\(\))p FN(.)j(NetBSD)f(does)d(this.)p 0 5549 3901 4 v 0 5649 a FI(492)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 493 505 TeXDict begin 493 504 bop 0 83 a FD(python_build)p FJ(\(\))208 183 y FN(Returns)20 b(a)g(tuple)g FJ(\()p FK(b)n(uildno)p FJ(,)47 b FK(b)n(uilddate)p FJ(\))19 b FN(stating)h(the)g(Python)f(b)n (uild)h(number)f(and)g(date)h(as)h(strings.)0 330 y FD(python_compiler) p FJ(\(\))208 429 y FN(Returns)f(a)g(string)g(identifying)e(the)i (compiler)f(used)h(for)g(compiling)e(Python.)0 576 y FD(python_version)p FJ(\(\))208 676 y FN(Returns)i(the)g(Python)f(v)o (ersion)g(as)i(string)f FJ('major.minor.patchlevel')208 808 y FN(Note)j(that)g(unlik)o(e)g(the)h(Python)e FJ(sys.version)p FN(,)g(the)i(returned)e(v)n(alue)g(will)j(al)o(w)o(ays)e(include)g(the) g(patchle)n(v)o(el)f(\(it)i(def)o(aults)208 908 y(to)c(0\).)0 1055 y FD(python_version_tuple)p FJ(\(\))208 1155 y FN(Returns)g(the)g (Python)f(v)o(ersion)g(as)i(tuple)e FJ(\()p FK(major)r FJ(,)49 b FK(minor)r FJ(,)g FK(patc)o(hle)o(vel)p FJ(\))18 b FN(of)i(strings.)208 1287 y(Note)j(that)g(unlik)o(e)g(the)h(Python)e FJ(sys.version)p FN(,)g(the)i(returned)e(v)n(alue)g(will)j(al)o(w)o (ays)e(include)g(the)g(patchle)n(v)o(el)f(\(it)i(def)o(aults)208 1387 y(to)c FJ('0')p FN(\).)0 1534 y FD(release)p FJ(\(\))208 1634 y FN(Returns)h(the)h(system')-5 b(s)22 b(release,)f(e.g.)29 b FJ('2.2.0')21 b FN(or)g FJ('NT')h FN(An)f(empty)g(string)g(is)i (returned)d(if)i(the)f(v)n(alue)g(cannot)g(be)g(deter)n(-)208 1733 y(mined.)0 1880 y FD(system)p FJ(\(\))208 1980 y FN(Returns)26 b(the)g(system/OS)h(name,)g(e.g.)43 b FJ('Linux')p FN(,)27 b FJ('Windows')p FN(,)f(or)g FJ('Java')p FN(.)43 b(An)27 b(empty)e(string)h(is)h(returned)e(if)i(the)208 2079 y(v)n(alue)19 b(cannot)g(be)h(determined.)0 2226 y FD(system_alias)p FJ(\()p FK(system,)e(r)m(elease)o(,)j(ver)o(sion)p FJ(\))208 2326 y FN(Returns)d FJ(\()p FK(system)p FJ(,)50 b FK(r)m(elease)p FJ(,)f FK(ver)o(sion)p FJ(\))19 b FN(aliased)f(to)h (common)e(mark)o(eting)g(names)h(used)h(for)f(some)g(systems.)25 b(It)19 b(also)g(does)208 2425 y(some)h(reordering)d(of)j(the)g (information)e(in)i(some)g(cases)h(where)f(it)h(w)o(ould)e(otherwise)h (cause)g(confusion.)0 2572 y FD(version)p FJ(\(\))208 2672 y FN(Returns)j(the)g(system')-5 b(s)24 b(release)g(v)o(ersion,)e (e.g.)34 b FJ('#3)50 b(on)f(degas')p FN(.)34 b(An)23 b(empty)g(string)g(is)h(returned)e(if)i(the)f(v)n(alue)g(cannot)208 2772 y(be)d(determined.)0 2918 y FD(uname)p FJ(\(\))208 3018 y FN(F)o(airly)29 b(portable)g(uname)f(interf)o(ace.)54 b(Returns)29 b(a)i(tuple)e(of)h(strings)g FJ(\()p FK(system)p FJ(,)50 b FK(node)p FJ(,)e FK(r)m(elease)p FJ(,)h FK(ver)o(sion)p FJ(,)g FK(mac)o(hine)p FJ(,)208 3118 y FK(pr)l(ocessor)r FJ(\))20 b FN(identifying)e(the)i(underlying)e(platform.)208 3251 y(Note)i(that)g(unlik)o(e)f(the)h FJ(os.uname\(\))f FN(function)g(this)h(also)h(returns)e(possible)h(processor)f (information)e(as)k(additional)e(tuple)208 3350 y(entry)-5 b(.)208 3483 y(Entries)20 b(which)f(cannot)g(be)h(determined)f(are)h (set)h(to)f FJ('')p FN(.)0 3768 y Fv(14.12.2)101 b(J)n(a)n(v)n(a)28 b(Platf)m(or)r(m)0 3957 y FD(java_ver)p FJ(\()p FK(r)m(elease=\224,)19 b(vendor=\224,)g(vminfo=\(\224,)-12 b(\224,)g(\224\),)20 b(osinfo=\(\224,)-12 b(\224,)g(\224\))p FJ(\))208 4056 y FN(V)j(ersion)19 b(interf)o(ace)g(for)h(JPython.)208 4189 y(Returns)33 b(a)g(tuple)g FJ(\()p FK(r)m(elease)p FJ(,)49 b FK(vendor)r FJ(,)f FK(vminfo)p FJ(,)h FK(osinfo)p FJ(\))33 b FN(with)g FK(vminfo)g FN(being)f(a)i(tuple)f FJ(\()p FK(vm)p 3183 4189 25 4 v 29 w(name)p FJ(,)49 b FK(vm)p 3589 4189 V 29 w(r)m(elease)p FJ(,)208 4289 y FK(vm)p 310 4289 V 29 w(vendor)r FJ(\))22 b FN(and)h FK(osinfo)g FN(being)f(a)i(tuple)f FJ(\()p FK(os)p 1599 4289 V 29 w(name)p FJ(,)49 b FK(os)p 1982 4289 V 30 w(ver)o(sion)p FJ(,)g FK(os)p 2429 4289 V 30 w(ar)m(c)o(h)p FJ(\))p FN(.)33 b(V)-9 b(alues)23 b(which)g(cannot)f(be)h(determined)208 4388 y(are)d(set)h(to)f(the)g(def)o(aults)g(gi)n(v)o(en)f(as)i (parameters)e(\(which)g(all)i(def)o(ault)e(to)i FJ('')p FN(\).)0 4673 y Fv(14.12.3)101 b(Windo)o(ws)28 b(Platf)m(or)r(m)0 4862 y FD(win32_ver)p FJ(\()p FK(r)m(elease=\224,)19 b(ver)o(sion=\224,)h(csd=\224,)g(ptype=\224)p FJ(\))208 4962 y FN(Get)32 b(additional)f(v)o(ersion)g(information)f(from)h(the)h (W)m(indo)n(ws)g(Re)o(gistry)g(and)f(return)g(a)i(tuple)f FJ(\()p FK(ver)o(sion)p FJ(,)49 b FK(csd)r FJ(,)g FK(ptype)p FJ(\))208 5061 y FN(referring)18 b(to)i(v)o(ersion)f(number)m(,)f(CSD)j (le)n(v)o(el)f(and)g(OS)g(type)g(\(multi/single)f(processor\).)208 5194 y(As)27 b(a)g(hint:)38 b FK(ptype)26 b FN(is)i FJ('Uniprocessor)47 b(Free')27 b FN(on)f(single)h(processor)e(NT)i(machines)f(and)g FJ('Multiprocessor)208 5294 y(Free')17 b FN(on)h(multi)g(processor)f (machines.)24 b(The)18 b FK('F)-5 b(r)m(ee')18 b FN(refers)f(to)i(the)f (OS)h(v)o(ersion)e(being)g(free)h(of)g(deb)n(ugging)d(code.)24 b(It)19 b(could)p 0 5549 3901 4 v 0 5649 a FI(14.12.)52 b FJ(platform)22 b FI(\227)h(Access)f(to)h(under)q(lying)h(platf)n(or)r (m')l(s)g(identifying)h(data.)1202 b(493)p eop end %%Page: 494 506 TeXDict begin 494 505 bop 208 83 a FN(also)19 b(state)h FK('Chec)n(k)o(ed')e FN(which)h(means)g(the)g(OS)h(v)o(ersion)e(uses)h (deb)n(ugging)e(code,)h(i.e.)25 b(code)19 b(that)g(checks)g(ar)o (guments,)e(ranges,)208 183 y(etc.)208 315 y FL(Note:)76 b FN(This)27 b(function)e(only)g(w)o(orks)i(if)g(Mark)f(Hammond')-5 b(s)25 b FJ(win32all)h FN(package)f(is)j(installed)e(and)h(\(ob)o (viously\))c(only)208 415 y(runs)c(on)h(W)m(in32)f(compatible)g (platforms.)0 683 y FI(Win95/98)25 b(speci\002c)0 872 y FD(popen)p FJ(\()p FK(cmd,)19 b(mode=')n(r',)g(b)n(ufsize=None)p FJ(\))208 972 y FN(Portable)k FJ(popen\(\))f FN(interf)o(ace.)35 b(Find)24 b(a)g(w)o(orking)e(popen)g(implementation)g(preferring)f FJ(win32pipe.popen\(\))p FN(.)33 b(On)208 1072 y(W)m(indo)n(ws)19 b(NT)-6 b(,)20 b FJ(win32pipe.popen\(\))e FN(should)h(w)o(ork;)h(on)f (W)m(indo)n(ws)h(9x)g(it)h(hangs)e(due)h(to)g(b)n(ugs)g(in)g(the)g(MS)h (C)g(library)-5 b(.)0 1356 y Fv(14.12.4)101 b(Mac)28 b(OS)g(Platf)m(or)r(m)0 1545 y FD(mac_ver)p FJ(\()p FK(r)m (elease=\224,)19 b(ver)o(sioninfo=\(\224,)-12 b(\224,)g(\224\),)19 b(mac)o(hine=\224)p FJ(\))208 1645 y FN(Get)31 b(Mac)g(OS)g(v)o(ersion) e(information)g(and)h(return)f(it)j(as)f(tuple)g FJ(\()p FK(r)m(elease)p FJ(,)49 b FK(ver)o(sioninfo)p FJ(,)f FK(mac)o(hine)p FJ(\))29 b FN(with)i FK(ver)o(sioninfo)208 1745 y FN(being)19 b(a)h(tuple)g FJ(\()p FK(ver)o(sion)p FJ(,)49 b FK(de)o(v)p 1170 1745 25 4 v 29 w(sta)o(g)o(e)p FJ(,)g FK(non)p 1598 1745 V 29 w(r)m(elease)p 1864 1745 V 29 w(ver)o(sion)p FJ(\))p FN(.)208 1877 y(Entries)20 b(which)f(cannot)g(be)h(determined)f(are)h(set)h(to)f FJ('')p FN(.)25 b(All)c(tuple)f(entries)g(are)g(strings.)208 2010 y(Documentation)d(for)j(the)g(underlying)d FJ(gestalt\(\))j FN(API)g(is)h(a)n(v)n(ailable)f(online)f(at)i FO(http://www)l(.rgaros)o (.nl/ge)o(stalt)o(/)-6 b FN(.)0 2295 y Fv(14.12.5)103 b FQ(U)t Fi(N)t(I)t(X)32 b Fv(Platf)m(or)r(ms)0 2484 y FD(dist)p FJ(\()p FK(distname=\224,)19 b(ver)o(sion=\224,)h(id=\224,) g(supported)p 1627 2484 V 28 w(dists=\('SuSE',)-12 b(')n(debian',)g(')n (r)m(edha)o(t',)g('ma)o(nd)o(r)o(ak)o(e')o(\))p FJ(\))208 2584 y FN(T)m(ries)30 b(to)h(determine)e(the)i(name)f(of)g(the)h(OS)g (distrib)n(ution)e(name)h(Returns)h(a)g(tuple)f FJ(\()p FK(distname)p FJ(,)48 b FK(ver)o(sion)p FJ(,)h FK(id)r FJ(\))31 b FN(which)208 2683 y(def)o(aults)19 b(to)i(the)f(ar)o(gs)f (gi)n(v)o(en)g(as)i(parameters.)0 2830 y FD(libc_ver)p FJ(\()p FK(e)n(xecutable=sys.e)n(xecutable)o(,)16 b(lib=\224,)k(ver)o (sion=\224,)h(c)o(hunksize=2048)p FJ(\))208 2930 y FN(T)m(ries)d(to)g (determine)e(the)i(libc)g(v)o(ersion)f(against)g(which)g(the)h(\002le)h (e)o(x)o(ecutable)d(\(def)o(aults)h(to)h(the)g(Python)f(interpreter\))f (is)j(link)o(ed.)208 3029 y(Returns)h(a)g(tuple)g(of)g(strings)g FJ(\()p FK(lib)p FJ(,)49 b FK(ver)o(sion)p FJ(\))20 b FN(which)g(def)o(ault)f(to)i(the)f(gi)n(v)o(en)f(parameters)g(in)h (case)h(the)f(lookup)e(f)o(ails.)208 3162 y(Note)23 b(that)g(this)g (function)e(has)j(intimate)e(kno)n(wledge)f(of)i(ho)n(w)f(dif)n(ferent) g(libc)h(v)o(ersions)f(add)g(symbols)g(to)i(the)f(e)o(x)o(ecutable)e (is)208 3262 y(probably)c(only)j(useable)g(for)f(e)o(x)o(ecutables)g (compiled)f(using)i FL(gcc)p FN(.)208 3395 y(The)f(\002le)i(is)g(read)f (and)g(scanned)f(in)h(chunks)f(of)h FK(c)o(hunksize)f FN(bytes.)0 3722 y FE(14.13)122 b Fx(errno)32 b FE(\227)g(Standard)k (err)s(no)e(system)f(symbols)0 3955 y FN(This)18 b(module)f(mak)o(es)h (a)n(v)n(ailable)f(standard)g FJ(errno)h FN(system)g(symbols.)24 b(The)17 b(v)n(alue)h(of)f(each)h(symbol)f(is)i(the)f(corresponding)d (inte)o(ger)0 4055 y(v)n(alue.)24 b(The)c(names)g(and)g(descriptions)f (are)h(borro)n(wed)e(from)h(`)p FO(lin)o(ux/include/err)r(no)m(.h)o FN(',)14 b(which)20 b(should)f(be)h(pretty)g(all-inclusi)n(v)o(e.)0 4201 y FD(errorcode)208 4301 y FN(Dictionary)e(pro)o(viding)f(a)k (mapping)d(from)h(the)g(errno)g(v)n(alue)g(to)h(the)g(string)g(name)f (in)h(the)g(underlying)e(system.)25 b(F)o(or)19 b(instance,)208 4401 y FJ(errno.errorcode[errno.EPERM])c FN(maps)20 b(to)g FJ('EPERM')p FN(.)0 4548 y(T)-7 b(o)20 b(translate)g(a)h(numeric)e (error)g(code)g(to)i(an)f(error)f(message,)h(use)g FJ(os.strerror\(\))p FN(.)0 4694 y(Of)f(the)g(follo)n(wing)e(list,)j(symbols)e(that)g(are)h (not)f(used)h(on)f(the)h(current)e(platform)g(are)i(not)f(de\002ned)g (by)g(the)h(module.)k(The)c(speci\002c)f(list)0 4794 y(of)i(de\002ned)f(symbols)h(is)h(a)n(v)n(ailable)e(as)i FJ(errno.errorcode.keys\(\))p FN(.)h(Symbols)d(a)n(v)n(ailable)h(can)g (include:)0 4941 y FD(EPERM)208 5041 y FN(Operation)e(not)i(permitted)0 5187 y FD(ENOENT)208 5287 y FN(No)g(such)g(\002le)h(or)e(directory)p 0 5549 3901 4 v 0 5649 a FI(494)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 495 507 TeXDict begin 495 506 bop 0 83 a FD(ESRCH)208 183 y FN(No)20 b(such)g(process)0 330 y FD(EINTR)208 429 y FN(Interrupted)d(system)k (call)0 576 y FD(EIO)208 676 y FN(I/O)f(error)0 823 y FD(ENXIO)208 922 y FN(No)g(such)g(de)n(vice)f(or)h(address)0 1069 y FD(E2BIG)208 1169 y FN(Ar)o(g)f(list)i(too)f(long)0 1316 y FD(ENOEXEC)208 1415 y FN(Ex)o(ec)f(format)g(error)0 1562 y FD(EBADF)208 1662 y FN(Bad)h(\002le)h(number)0 1808 y FD(ECHILD)208 1908 y FN(No)f(child)g(processes)0 2055 y FD(EAGAIN)208 2155 y FN(T)m(ry)f(again)0 2301 y FD(ENOMEM)208 2401 y FN(Out)h(of)g(memory)0 2548 y FD(EACCES)208 2648 y FN(Permission)f(denied)0 2794 y FD(EFAULT)208 2894 y FN(Bad)h(address)0 3041 y FD(ENOTBLK)208 3141 y FN(Block)g(de)n(vice)f(required)0 3287 y FD(EBUSY)208 3387 y FN(De)n(vice)g(or)h(resource)f(b)n(usy)0 3534 y FD(EEXIST)208 3634 y FN(File)h(e)o(xists)0 3780 y FD(EXDEV)208 3880 y FN(Cross-de)n(vice)f(link)0 4027 y FD(ENODEV)208 4127 y FN(No)h(such)g(de)n(vice)0 4273 y FD(ENOTDIR)208 4373 y FN(Not)g(a)g(directory)0 4520 y FD(EISDIR)208 4620 y FN(Is)g(a)h(directory)0 4766 y FD(EINVAL)208 4866 y FN(In)m(v)n(alid)d(ar)o(gument)0 5013 y FD(ENFILE)208 5113 y FN(File)i(table)h(o)o(v)o(er\003o)n(w)0 5259 y FD(EMFILE)208 5359 y FN(T)-7 b(oo)19 b(man)o(y)g(open)h(\002les)p 0 5549 3901 4 v 0 5649 a FI(14.13.)52 b FJ(errno)23 b FI(\227)g(Standard)h(err)r(no)f(system)f(symbols)1931 b(495)p eop end %%Page: 496 508 TeXDict begin 496 507 bop 0 83 a FD(ENOTTY)208 183 y FN(Not)20 b(a)g(type)n(writer)0 330 y FD(ETXTBSY)208 429 y FN(T)-6 b(e)o(xt)19 b(\002le)i(b)n(usy)0 576 y FD(EFBIG)208 676 y FN(File)f(too)g(lar)o(ge)0 823 y FD(ENOSPC)208 922 y FN(No)g(space)g(left)g(on)g(de)n(vice)0 1069 y FD(ESPIPE)208 1169 y FN(Ille)o(gal)f(seek)0 1316 y FD(EROFS)208 1415 y FN(Read-only)f(\002le)j(system)0 1562 y FD(EMLINK)208 1662 y FN(T)-7 b(oo)19 b(man)o(y)g(links)0 1808 y FD(EPIPE)208 1908 y FN(Brok)o(en)g(pipe)0 2055 y FD(EDOM)208 2155 y FN(Math)h(ar)o(gument)d(out)j(of)g(domain)f(of)h(func)0 2301 y FD(ERANGE)208 2401 y FN(Math)g(result)g(not)g(representable)0 2548 y FD(EDEADLK)208 2648 y FN(Resource)f(deadlock)g(w)o(ould)g(occur) 0 2794 y FD(ENAMETOOLONG)208 2894 y FN(File)h(name)g(too)g(long)0 3041 y FD(ENOLCK)208 3141 y FN(No)g(record)f(locks)h(a)n(v)n(ailable)0 3287 y FD(ENOSYS)208 3387 y FN(Function)f(not)g(implemented)0 3534 y FD(ENOTEMPTY)208 3634 y FN(Directory)f(not)i(empty)0 3780 y FD(ELOOP)208 3880 y FN(T)-7 b(oo)19 b(man)o(y)g(symbolic)h (links)g(encountered)0 4027 y FD(EWOULDBLOCK)208 4127 y FN(Operation)e(w)o(ould)i(block)0 4273 y FD(ENOMSG)208 4373 y FN(No)g(message)g(of)g(desired)f(type)0 4520 y FD(EIDRM)208 4620 y FN(Identi\002er)g(remo)o(v)o(ed)0 4766 y FD(ECHRNG)208 4866 y FN(Channel)g(number)f(out)i(of)g(range)0 5013 y FD(EL2NSYNC)208 5113 y FN(Le)n(v)o(el)f(2)h(not)g(synchronized)0 5259 y FD(EL3HLT)208 5359 y FN(Le)n(v)o(el)f(3)h(halted)p 0 5549 3901 4 v 0 5649 a FI(496)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 497 509 TeXDict begin 497 508 bop 0 83 a FD(EL3RST)208 183 y FN(Le)n(v)o(el)19 b(3)h(reset)0 330 y FD(ELNRNG)208 429 y FN(Link)f(number)g(out)g(of)h(range)0 576 y FD(EUNATCH)208 676 y FN(Protocol)f(dri)n(v)o(er)f(not)i(attached)0 823 y FD(ENOCSI)208 922 y FN(No)g(CSI)h(structure)e(a)n(v)n(ailable)0 1069 y FD(EL2HLT)208 1169 y FN(Le)n(v)o(el)g(2)h(halted)0 1316 y FD(EBADE)208 1415 y FN(In)m(v)n(alid)e(e)o(xchange)0 1562 y FD(EBADR)208 1662 y FN(In)m(v)n(alid)g(request)i(descriptor)0 1808 y FD(EXFULL)208 1908 y FN(Exchange)e(full)0 2055 y FD(ENOANO)208 2155 y FN(No)i(anode)0 2301 y FD(EBADRQC)208 2401 y FN(In)m(v)n(alid)e(request)i(code)0 2548 y FD(EBADSLT)208 2648 y FN(In)m(v)n(alid)e(slot)0 2794 y FD(EDEADLOCK)208 2894 y FN(File)i(locking)f(deadlock)g(error)0 3041 y FD(EBFONT)208 3141 y FN(Bad)h(font)g(\002le)g(format)0 3287 y FD(ENOSTR)208 3387 y FN(De)n(vice)f(not)h(a)h(stream)0 3534 y FD(ENODATA)208 3634 y FN(No)f(data)g(a)n(v)n(ailable)0 3780 y FD(ETIME)208 3880 y FN(T)m(imer)f(e)o(xpired)0 4027 y FD(ENOSR)208 4127 y FN(Out)h(of)g(streams)g(resources)0 4273 y FD(ENONET)208 4373 y FN(Machine)f(is)i(not)f(on)g(the)g(netw)o (ork)0 4520 y FD(ENOPKG)208 4620 y FN(P)o(ackage)f(not)h(installed)0 4766 y FD(EREMOTE)208 4866 y FN(Object)g(is)h(remote)0 5013 y FD(ENOLINK)208 5113 y FN(Link)e(has)i(been)e(se)n(v)o(ered)0 5259 y FD(EADV)208 5359 y FN(Adv)o(ertise)g(error)p 0 5549 3901 4 v 0 5649 a FI(14.13.)52 b FJ(errno)23 b FI(\227)g(Standard) h(err)r(no)f(system)f(symbols)1931 b(497)p eop end %%Page: 498 510 TeXDict begin 498 509 bop 0 83 a FD(ESRMNT)208 183 y FN(Srmount)18 b(error)0 330 y FD(ECOMM)208 429 y FN(Communication)f (error)i(on)h(send)0 576 y FD(EPROTO)208 676 y FN(Protocol)f(error)0 823 y FD(EMULTIHOP)208 922 y FN(Multihop)f(attempted)0 1069 y FD(EDOTDOT)208 1169 y FN(RFS)j(speci\002c)f(error)0 1316 y FD(EBADMSG)208 1415 y FN(Not)g(a)g(data)h(message)0 1562 y FD(EOVERFLOW)208 1662 y FN(V)-9 b(alue)19 b(too)h(lar)o(ge)f (for)h(de\002ned)f(data)h(type)0 1808 y FD(ENOTUNIQ)208 1908 y FN(Name)g(not)f(unique)g(on)h(netw)o(ork)0 2055 y FD(EBADFD)208 2155 y FN(File)g(descriptor)f(in)i(bad)e(state)0 2301 y FD(EREMCHG)208 2401 y FN(Remote)h(address)f(changed)0 2548 y FD(ELIBACC)208 2648 y FN(Can)h(not)g(access)h(a)f(needed)f (shared)h(library)0 2794 y FD(ELIBBAD)208 2894 y FN(Accessing)g(a)g (corrupted)e(shared)h(library)0 3041 y FD(ELIBSCN)208 3141 y FN(.lib)h(section)g(in)g(a.out)g(corrupted)0 3287 y FD(ELIBMAX)208 3387 y FN(Attempting)f(to)h(link)g(in)g(too)g(man)o(y) f(shared)g(libraries)0 3534 y FD(ELIBEXEC)208 3634 y FN(Cannot)g(e)o(x)o(ec)h(a)g(shared)g(library)f(directly)0 3780 y FD(EILSEQ)208 3880 y FN(Ille)o(gal)g(byte)g(sequence)0 4027 y FD(ERESTART)208 4127 y FN(Interrupted)e(system)k(call)f(should)f (be)h(restarted)0 4273 y FD(ESTRPIPE)208 4373 y FN(Streams)g(pipe)g (error)0 4520 y FD(EUSERS)208 4620 y FN(T)-7 b(oo)19 b(man)o(y)g(users)0 4766 y FD(ENOTSOCK)208 4866 y FN(Sock)o(et)g (operation)g(on)h(non-sock)o(et)0 5013 y FD(EDESTADDRREQ)208 5113 y FN(Destination)f(address)h(required)0 5259 y FD(EMSGSIZE)208 5359 y FN(Message)g(too)g(long)p 0 5549 3901 4 v 0 5649 a FI(498)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 499 511 TeXDict begin 499 510 bop 0 83 a FD(EPROTOTYPE)208 183 y FN(Protocol)19 b(wrong)g(type)g(for)h(sock)o(et)0 330 y FD(ENOPROTOOPT)208 429 y FN(Protocol)f(not)h(a)n(v)n(ailable)0 576 y FD(EPROTONOSUPPORT)208 676 y FN(Protocol)f(not)h(supported)0 823 y FD(ESOCKTNOSUPPORT)208 922 y FN(Sock)o(et)f(type)h(not)g (supported)0 1069 y FD(EOPNOTSUPP)208 1169 y FN(Operation)e(not)i (supported)e(on)i(transport)f(endpoint)0 1316 y FD(EPFNOSUPPORT)208 1415 y FN(Protocol)g(f)o(amily)g(not)h(supported)0 1562 y FD(EAFNOSUPPORT)208 1662 y FN(Address)f(f)o(amily)h(not)g(supported)e (by)i(protocol)0 1808 y FD(EADDRINUSE)208 1908 y FN(Address)f(already)g (in)i(use)0 2055 y FD(EADDRNOTAVAIL)208 2155 y FN(Cannot)e(assign)h (requested)f(address)0 2301 y FD(ENETDOWN)208 2401 y FN(Netw)o(ork)g(is)i(do)n(wn)0 2548 y FD(ENETUNREACH)208 2648 y FN(Netw)o(ork)e(is)i(unreachable)0 2794 y FD(ENETRESET)208 2894 y FN(Netw)o(ork)e(dropped)f(connection)g(because)h(of)h(reset)0 3041 y FD(ECONNABORTED)208 3141 y FN(Softw)o(are)f(caused)h(connection) e(abort)0 3287 y FD(ECONNRESET)208 3387 y FN(Connection)g(reset)j(by)e (peer)0 3534 y FD(ENOBUFS)208 3634 y FN(No)h(b)n(uf)n(fer)f(space)h(a)n (v)n(ailable)0 3780 y FD(EISCONN)208 3880 y FN(T)m(ransport)e(endpoint) h(is)i(already)e(connected)0 4027 y FD(ENOTCONN)208 4127 y FN(T)m(ransport)f(endpoint)h(is)i(not)f(connected)0 4273 y FD(ESHUTDOWN)208 4373 y FN(Cannot)f(send)h(after)g(transport)f (endpoint)f(shutdo)n(wn)0 4520 y FD(ETOOMANYREFS)208 4620 y FN(T)-7 b(oo)19 b(man)o(y)g(references:)24 b(cannot)19 b(splice)0 4766 y FD(ETIMEDOUT)208 4866 y FN(Connection)f(timed)i(out)0 5013 y FD(ECONNREFUSED)208 5113 y FN(Connection)e(refused)0 5259 y FD(EHOSTDOWN)208 5359 y FN(Host)i(is)h(do)n(wn)p 0 5549 3901 4 v 0 5649 a FI(14.13.)52 b FJ(errno)23 b FI(\227)g(Standard)h(err)r(no)f(system)f(symbols)1931 b(499)p eop end %%Page: 500 512 TeXDict begin 500 511 bop 0 83 a FD(EHOSTUNREACH)208 183 y FN(No)20 b(route)f(to)h(host)0 330 y FD(EALREADY)208 429 y FN(Operation)e(already)h(in)i(progress)0 576 y FD(EINPROGRESS)208 676 y FN(Operation)d(no)n(w)i(in)g(progress)0 823 y FD(ESTALE)208 922 y FN(Stale)g(NFS)h(\002le)g(handle)0 1069 y FD(EUCLEAN)208 1169 y FN(Structure)e(needs)g(cleaning)0 1316 y FD(ENOTNAM)208 1415 y FN(Not)h(a)g(XENIX)g(named)g(type)f (\002le)0 1562 y FD(ENAVAIL)208 1662 y FN(No)h(XENIX)g(semaphores)e(a)n (v)n(ailable)0 1808 y FD(EISNAM)208 1908 y FN(Is)i(a)h(named)e(type)h (\002le)0 2055 y FD(EREMOTEIO)208 2155 y FN(Remote)g(I/O)g(error)0 2301 y FD(EDQUOT)208 2401 y FN(Quota)f(e)o(xceeded)0 2729 y FE(14.14)122 b Fx(ctypes)31 b FE(\227)i(A)g(f)l(oreign)i (function)g(libr)o(ar)t(y)d(f)l(or)i(Python.)0 2961 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3108 y FJ(ctypes)i FN(is)i(a)f(foreign)e(function)g(library)h(for)g(Python.)28 b(It)22 b(pro)o(vides)e(C)j(compatible)d(data)h(types,)h(and)f(allo)n (ws)h(to)g(call)g(functions)e(in)0 3208 y(dlls/shared)f(libraries.)25 b(It)c(can)f(be)g(used)g(to)g(wrap)g(these)g(libraries)g(in)g(pure)f (Python.)0 3493 y Fv(14.14.1)101 b(ctypes)28 b(tutor)q(ial)0 3696 y FN(Note:)c(The)17 b(code)g(samples)h(in)g(this)g(tutorial)g (uses)g FJ(doctest)f FN(to)h(mak)o(e)f(sure)h(that)f(the)o(y)h (actually)f(w)o(ork.)23 b(Since)18 b(some)f(code)h(samples)0 3795 y(beha)n(v)o(e)h(dif)n(ferently)f(under)h(Linux,)g(W)m(indo)n(ws,) g(or)h(Mac)g(OS)h(X,)g(the)o(y)e(contain)g(doctest)h(directi)n(v)o(es)f (in)i(comments.)0 3942 y(Note:)k(Quite)18 b(some)h(code)f(samples)h (references)e(the)i(ctypes)f FJ(c_int)h FN(type.)24 b(This)19 b(type)f(is)i(an)f(alias)g(to)g(the)g FJ(c_long)f FN(type)g(on)h (32-bit)0 4042 y(systems.)44 b(So,)28 b(you)d(should)g(not)h(be)g (confused)f(if)i FJ(c_long)e FN(is)j(printed)d(if)h(you)g(w)o(ould)f(e) o(xpect)h FJ(c_int)g FN(-)g(the)o(y)g(are)g(actually)g(the)0 4141 y(same)20 b(type.)0 4410 y FI(Loading)k(dynamic)g(link)f(libr)o (ar)q(ies)0 4613 y FJ(ctypes)d FN(e)o(xports)f(the)h FK(cdll)p FN(,)g(and)g(on)f(W)m(indo)n(ws)h(also)g FK(windll)h FN(and)f FK(oledll)f FN(objects)h(to)h(load)e(dynamic)g(link)h (libraries.)0 4759 y(Y)-9 b(ou)24 b(load)g(libraries)g(by)g(accessing)g (them)g(as)h(attrib)n(utes)f(of)g(these)h(objects.)37 b FK(cdll)24 b FN(loads)h(libraries)f(which)f(e)o(xport)g(functions)g (using)0 4859 y(the)f(standard)g FJ(cdecl)g FN(calling)g(con)m(v)o (ention,)e(while)i FK(windll)h FN(libraries)f(call)h(functions)e(using) h(the)g FJ(stdcall)g FN(calling)g(con)m(v)o(ention.)0 4959 y FK(oledll)e FN(also)g(uses)h(the)f FJ(stdcall)f FN(calling)h(con)m(v)o(ention,)d(and)i(assumes)i(the)f(functions)e (return)h(a)i(W)m(indo)n(ws)e FJ(HRESULT)h FN(error)e(code.)0 5058 y(The)i(error)f(code)g(is)j(used)d(to)i(automatically)e(raise)h FJ(WindowsError)f FN(Python)g(e)o(xceptions)f(when)i(the)g(function)e (call)j(f)o(ails.)0 5205 y(Here)k(are)h(some)f(e)o(xamples)f(for)h(W)m (indo)n(ws,)h(note)f(that)h FJ(msvcrt)e FN(is)j(the)e(MS)h(standard)f (C)h(library)e(containing)g(most)h(standard)g(C)0 5305 y(functions,)19 b(and)g(uses)i(the)f(cdecl)g(calling)g(con)m(v)o (ention:)p 0 5549 3901 4 v 0 5649 a FI(500)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 501 513 TeXDict begin 501 512 bop 236 174 a FA(>>>)45 b(from)f(ctypes)g(import) 1267 187 y(*)236 266 y(>>>)h(print)f(windll.kernel32)e(#)j(doctest:)e (+WINDOWS)236 357 y(<WinDLL)h('kernel32',)f(handle)h(...)g(at)h(...>) 236 448 y(>>>)g(print)f(cdll.msvcrt)f(#)h(doctest:)g(+WINDOWS)236 540 y(<CDLL)g('msvcrt',)g(handle)f(...)i(at)f(...>)236 631 y(>>>)h(libc)f(=)g(cdll.msvcrt)f(#)i(doctest:)f(+WINDOWS)236 722 y(>>>)0 1009 y FN(W)m(indo)n(ws)20 b(appends)e(the)j(usual)f ('.dll')f(\002le)i(suf)n(\002x)f(automatically)-5 b(.)0 1156 y(On)23 b(Linux,)g(it)h(is)g(required)d(to)j(specify)e(the)i (\002lename)e FK(including)g FN(the)h(e)o(xtension)f(to)h(load)g(a)g (library)-5 b(,)23 b(so)g(attrib)n(ute)g(access)h(does)f(not)0 1255 y(w)o(ork.)i(Either)20 b(the)h FJ(LoadLibrary)e FN(method)g(of)h(the)h(dll)f(loaders)g(should)g(be)g(used,)g(or)g(you)g (should)g(load)g(the)g(library)f(by)i(creating)0 1355 y(an)f(instance)g(of)g(CDLL)g(by)g(calling)g(the)g(constructor:)236 1593 y FA(>>>)45 b(cdll.LoadLibrary\("libc.so.6"\))40 b(#)k(doctest:)g(+LINUX)236 1684 y(<CDLL)g('libc.so.6',)f(handle)h(...) g(at)h(...>)236 1776 y(>>>)g(libc)f(=)g(CDLL\("libc.so.6"\))222 b(#)44 b(doctest:)g(+LINUX)236 1867 y(>>>)h(libc)1120 b(#)44 b(doctest:)g(+LINUX)236 1958 y(<CDLL)g('libc.so.6',)f(handle)h (...)g(at)h(...>)236 2050 y(>>>)0 2462 y FI(Accessing)22 b(functions)i(from)f(loaded)h(dlls)0 2665 y FN(Functions)19 b(are)h(accessed)h(as)f(attrib)n(utes)h(of)e(dll)i(objects:)236 2903 y FA(>>>)45 b(from)f(ctypes)g(import)1267 2916 y(*)236 2994 y(>>>)h(libc.printf)236 3085 y(<_FuncPtr)f(object)f(at)i(0x...>) 236 3177 y(>>>)g(print)f(windll.kernel32.GetModuleHandleA)39 b(#)45 b(doctest:)e(+WINDOWS)236 3268 y(<_FuncPtr)h(object)f(at)i (0x...>)236 3359 y(>>>)g(print)f(windll.kernel32.MyOwnFunction)39 b(#)45 b(doctest:)f(+WINDOWS)236 3451 y(Traceback)g(\(most)g(recent)f (call)i(last\):)326 3542 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)326 3633 y(File)g("ctypes.py",)f(line)h(239,)g(in)h(__getattr__)416 3725 y(func)f(=)g(_StdcallFuncPtr\(name,)e(self\))236 3816 y(AttributeError:)h(function)g('MyOwnFunction')f(not)j(found)236 3907 y(>>>)0 4194 y FN(Note)27 b(that)h(win32)e(system)i(dlls)g(lik)o (e)g FJ(kernel32)e FN(and)h FJ(user32)g FN(often)f(e)o(xport)g(ANSI)i (as)g(well)g(as)g(UNICODE)g(v)o(ersions)e(of)h(a)0 4294 y(function.)39 b(The)25 b(UNICODE)g(v)o(ersion)g(is)h(e)o(xported)d (with)j(an)f FJ(W)h FN(appended)d(to)i(the)h(name,)g(while)f(the)h (ANSI)f(v)o(ersion)f(is)j(e)o(xported)0 4393 y(with)16 b(an)g FJ(A)g FN(appended)d(to)j(the)g(name.)23 b(The)15 b(win32)g FJ(GetModuleHandle)f FN(function,)g(which)h(returns)g(a)h FK(module)f(handle)g FN(for)g(a)h(gi)n(v)o(en)0 4493 y(module)25 b(name,)i(has)f(the)h(follo)n(wing)d(C)j(prototype,)f(and)f (a)i(macro)e(is)j(used)e(to)g(e)o(xpose)f(one)h(of)g(them)g(as)h FJ(GetModuleHandle)0 4592 y FN(depending)18 b(on)h(whether)h(UNICODE)g (is)h(de\002ned)e(or)h(not:)236 4831 y FA(/)281 4844 y(*)371 4831 y(ANSI)44 b(version)954 4844 y(*)999 4831 y(/)236 4922 y(HMODULE)g(GetModuleHandleA\(LPCSTR)d(lpModuleName\);)236 5013 y(/)281 5026 y(*)371 5013 y(UNICODE)i(version)1088 5026 y(*)1133 5013 y(/)236 5105 y(HMODULE)h(GetModuleHandleW\(LPCWSTR)d (lpModuleName\);)0 5391 y FK(windll)k FN(does)g(not)g(try)g(to)g (select)h(one)e(of)h(them)g(by)f(magic,)51 b(you)44 b(must)h(access)h (the)f(v)o(ersion)f(you)g(need)g(by)h(specifying)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e(Python.) 1736 b(501)p eop end %%Page: 502 514 TeXDict begin 502 513 bop 0 83 a FJ(GetModuleHandleA)19 b FN(or)i FJ(GetModuleHandleW)e FN(e)o(xplicitely)-5 b(,)20 b(and)h(then)g(call)g(it)i(with)e(normal)f(strings)i(or)f (unicode)f(strings)0 183 y(respecti)n(v)o(ely)-5 b(.)0 330 y(Sometimes,)22 b(dlls)h(e)o(xport)e(functions)g(with)i(names)f (which)g(aren')o(t)f(v)n(alid)h(Python)f(identi\002ers,)i(lik)o(e)f FJ("??2@YAPAXI@Z")p FN(.)30 b(In)22 b(this)0 429 y(case)f(you)e(ha)n(v) o(e)h(to)g(use)g FJ(getattr)g FN(to)g(retrie)n(v)o(e)f(the)h(function:) 236 667 y FA(>>>)45 b(getattr\(cdll.msvcrt,)c("??2@YAPAXI@Z"\))h(#)j (doctest:)e(+WINDOWS)236 759 y(<_FuncPtr)h(object)f(at)i(0x...>)236 850 y(>>>)0 1137 y FN(On)19 b(W)m(indo)n(ws,)f(some)g(dlls)i(e)o(xport) d(functions)g(not)h(by)h(name)f(b)n(ut)h(by)f(ordinal.)23 b(These)c(functions)e(can)h(be)h(accessed)g(by)f(inde)o(xing)f(the)0 1236 y(dll)j(object)g(with)g(the)h(ordinal)e(number:)236 1474 y FA(>>>)45 b(cdll.kernel32[1])d(#)i(doctest:)g(+WINDOWS)236 1566 y(<_FuncPtr)g(object)f(at)i(0x...>)236 1657 y(>>>)g (cdll.kernel32[0])d(#)i(doctest:)g(+WINDOWS)236 1748 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 1840 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)326 1931 y(File)g ("ctypes.py",)f(line)h(310,)g(in)h(__getitem__)416 2022 y(func)f(=)g(_StdcallFuncPtr\(name,)e(self\))236 2114 y(AttributeError:)h(function)g(ordinal)h(0)g(not)h(found)236 2205 y(>>>)0 2617 y FI(Calling)25 b(functions)0 2820 y FN(Y)-9 b(ou)23 b(can)g(call)h(these)g(functions)e(lik)o(e)i(an)o(y)f (other)f(Python)h(callable.)35 b(This)23 b(e)o(xample)f(uses)i(the)g FJ(time\(\))f FN(function,)f(which)h(returns)0 2920 y(system)k(time)g (in)g(seconds)g(since)g(the)i(U)t FH(N)t(I)t(X)h FN(epoch,)d(and)f(the) h FJ(GetModuleHandleA\(\))d FN(function,)j(which)f(returns)g(a)h(win32) 0 3020 y(module)19 b(handle.)0 3166 y(This)h(e)o(xample)f(calls)i(both) e(functions)g(with)i(a)f(NULL)g(pointer)f(\()p FJ(None)h FN(should)f(be)h(used)g(as)h(the)f(NULL)g(pointer\):)236 3405 y FA(>>>)45 b(print)f(libc.time\(None\))e(#)j(doctest:)e(+SKIP)236 3496 y(1150640792)236 3587 y(>>>)i(print)f (hex\(windll.kernel32.GetModuleHandleA)o(\(None\))o(\))39 b(#)45 b(doctest:)e(+WINDOWS)236 3679 y(0x1d000000)236 3770 y(>>>)0 4056 y FJ(ctypes)24 b FN(tries)i(to)f(protect)f(you)g (from)f(calling)i(functions)e(with)i(the)g(wrong)f(number)f(of)h(ar)o (guments)f(or)i(the)g(wrong)e(calling)h(con-)0 4156 y(v)o(ention.)h (Unfortunately)18 b(this)k(only)d(w)o(orks)i(on)f(W)m(indo)n(ws.)26 b(It)21 b(does)g(this)g(by)g(e)o(xamining)d(the)j(stack)g(after)g(the)f (function)f(returns,)h(so)0 4256 y(although)e(an)i(error)g(is)h(raised) f(the)g(function)e FK(has)i FN(been)g(called:)236 4494 y FA(>>>)45 b(windll.kernel32.GetModuleHandleA\(\))39 b(#)44 b(doctest:)g(+WINDOWS)236 4585 y(Traceback)g(\(most)g(recent)f (call)i(last\):)326 4677 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 4768 y(ValueError:)f(Procedure)h(probably)f(called)h(with)g(not)g (enough)g(arguments)f(\(4)i(bytes)f(missing\))236 4859 y(>>>)h(windll.kernel32.GetModuleHandleA\(0,)38 b(0\))45 b(#)g(doctest:)e(+WINDOWS)236 4951 y(Traceback)h(\(most)g(recent)f (call)i(last\):)326 5042 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 5133 y(ValueError:)f(Procedure)h(probably)f(called)h(with)g(too)g(many) g(arguments)g(\(4)g(bytes)g(in)h(excess\))236 5224 y(>>>)p 0 5549 3901 4 v 0 5649 a FI(502)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 503 515 TeXDict begin 503 514 bop 0 83 a FN(The)20 b(same)g(e)o(xception)f(is)i (raised)f(when)f(you)h(call)g(an)g FJ(stdcall)g FN(function)e(with)j (the)f FJ(cdecl)g FN(calling)f(con)m(v)o(ention,)e(or)j(vice)g(v)o (ersa:)236 321 y FA(>>>)45 b(cdll.kernel32.GetModuleHandleA\(None\))38 b(#)45 b(doctest:)e(+WINDOWS)236 413 y(Traceback)h(\(most)g(recent)f (call)i(last\):)326 504 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 595 y(ValueError:)f(Procedure)h(probably)f(called)h(with)g(not)g (enough)g(arguments)f(\(4)i(bytes)f(missing\))236 687 y(>>>)236 869 y(>>>)h(windll.msvcrt.printf\("spam"\))40 b(#)k(doctest:)g(+WINDOWS)236 960 y(Traceback)g(\(most)g(recent)f(call) i(last\):)326 1052 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 1143 y(ValueError:)f(Procedure)h(probably)f(called)h(with)g(too)g(many) g(arguments)g(\(4)g(bytes)g(in)h(excess\))236 1234 y(>>>)0 1521 y FN(T)-7 b(o)19 b(\002nd)g(out)g(the)g(correct)f(calling)h(con)m (v)o(ention)d(you)i(ha)n(v)o(e)h(to)g(look)g(into)f(the)i(C)g(header)e (\002le)h(or)g(the)g(documentation)e(for)h(the)h(function)0 1621 y(you)g(w)o(ant)i(to)f(call.)0 1767 y(On)27 b(W)m(indo)n(ws,)h FJ(ctypes)f FN(uses)h(win32)e(structured)g(e)o(xception)f(handling)h (to)h(pre)n(v)o(ent)e(crashes)j(from)e(general)g(protection)f(f)o (aults)0 1867 y(when)20 b(functions)e(are)i(called)g(with)h(in)m(v)n (alid)e(ar)o(gument)f(v)n(alues:)236 2105 y FA(>>>)45 b(windll.kernel32.GetModuleHandleA\(32\))38 b(#)45 b(doctest:)e (+WINDOWS)236 2197 y(Traceback)h(\(most)g(recent)f(call)i(last\):)326 2288 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 2379 y(WindowsError:)f(exception:)g(access)h(violation)f(reading)h (0x00000020)236 2471 y(>>>)0 2757 y FN(There)19 b(are,)h(ho)n(we)n(v)o (er)m(,)e(enough)g(w)o(ays)j(to)f(crash)g(Python)f(with)h FJ(ctypes)p FN(,)g(so)g(you)g(should)f(be)h(careful)f(an)o(yw)o(ay)-5 b(.)0 2904 y FJ(None)p FN(,)21 b(inte)o(gers,)f(longs,)h(byte)g (strings)g(and)g(unicode)e(strings)j(are)f(the)g(only)f(nati)n(v)o(e)h (Python)f(objects)h(that)g(can)g(directly)g(be)g(used)g(as)0 3004 y(parameters)h(in)i(these)g(function)e(calls.)35 b FJ(None)24 b FN(is)g(passed)g(as)g(a)g(C)g FJ(NULL)g FN(pointer)m(,)e(byte)h(strings)h(and)f(unicode)f(strings)h(are)h (passed)0 3103 y(as)d(pointer)d(to)i(the)g(memory)e(block)h(that)h (contains)f(their)h(data)g(\()p FJ(char)2104 3118 y(*)2174 3103 y FN(or)g FJ(wchar_t)2663 3118 y(*)2713 3103 y FN(\).)k(Python)19 b(inte)o(gers)g(and)g(Python)g(longs)0 3203 y(are)h(passed)g(as)h(the)f (platforms)f(def)o(ault)h(C)h FJ(int)f FN(type,)g(their)g(v)n(alue)f (is)i(mask)o(ed)f(to)g(\002t)h(into)f(the)g(C)h(type.)0 3350 y(Before)f(we)g(mo)o(v)o(e)f(on)h(calling)f(functions)g(with)i (other)e(parameter)g(types,)g(we)i(ha)n(v)o(e)f(to)g(learn)g(more)f (about)g FJ(ctypes)h FN(data)g(types.)0 3618 y FI(Fundamental)25 b(data)e(types)0 3821 y FJ(ctypes)d FN(de\002nes)g(a)g(number)f(of)h (primiti)n(v)o(e)e(C)k(compatible)c(data)i(types)g(:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(503)p eop end %%Page: 504 516 TeXDict begin 504 515 bop 278 161 a FL(ctypes)20 b(type)p 874 191 4 100 v 273 w(C)h(type)p 2778 191 V 1670 w(Python)f(type)p 208 194 3539 4 v 278 264 a FJ(c_char)p 874 294 4 100 v 348 w(char)p 2778 294 V 1704 w FN(1-character)e(string)278 364 y FJ(c_wchar)p 874 394 V 298 w(wchar_t)p 2778 394 V 1554 w FN(1-character)g(unicode)g(string)278 463 y FJ(c_byte)p 874 493 V 348 w(char)p 2778 493 V 1704 w FN(int/long)278 563 y FJ(c_ubyte)p 874 593 V 298 w(unsigned)48 b(char)p 2778 593 V 1256 w FN(int/long)278 663 y FJ(c_short)p 874 692 V 298 w(short)p 2778 692 V 1654 w FN(int/long)278 762 y FJ(c_ushort)p 874 792 V 248 w(unsigned)g(short)p 2778 792 V 1206 w FN(int/long)278 862 y FJ(c_int)p 874 892 V 398 w(int)p 2778 892 V 1754 w FN(int/long)278 961 y FJ(c_uint)p 874 991 V 348 w(unsigned)g(int)p 2778 991 V 1306 w FN(int/long)278 1061 y FJ(c_long)p 874 1091 V 348 w(long)p 2778 1091 V 1704 w FN(int/long)278 1161 y FJ(c_ulong)p 874 1191 V 298 w(unsigned)g(long)p 2778 1191 V 1256 w FN(int/long)278 1260 y FJ(c_longlong)p 874 1290 V 148 w(__int64)19 b FN(or)h FJ(long)49 b(long)p 2778 1290 V 996 w FN(int/long)278 1360 y FJ(c_ulonglong)p 874 1390 V 98 w(unsigned)f(__int64)19 b FN(or)h FJ(unsigned)49 b(long)g(long)p 2778 1390 V 99 w FN(int/long)278 1460 y FJ(c_float)p 874 1489 V 298 w(float)p 2778 1489 V 1654 w FN(\003oat)278 1559 y FJ(c_double)p 874 1589 V 248 w(double)p 2778 1589 V 1604 w FN(\003oat)278 1659 y FJ(c_char_p)p 874 1689 V 248 w(char)1175 1674 y(*)1245 1659 y FN(\(NUL)20 b(terminated\))p 2778 1689 V 981 w(string)g(or)f FJ(None)278 1758 y(c_wchar_p)p 874 1788 V 198 w(wchar_t)1324 1773 y(*)1395 1758 y FN(\(NUL)h(terminated\))p 2778 1788 V 831 w(unicode)e(or)i FJ(None)278 1858 y(c_void_p)p 874 1888 V 248 w(void)1175 1873 y(*)p 2778 1888 V 2830 1858 a FN(int/long)f(or)h FJ(None)0 2067 y FN(All)h(these)f(types)g(can)g (be)g(created)g(by)g(calling)f(them)h(with)g(an)h(optional)d (initializer)i(of)g(the)h(correct)e(type)h(and)f(v)n(alue:)236 2305 y FA(>>>)45 b(c_int\(\))236 2396 y(c_long\(0\))236 2487 y(>>>)g(c_char_p\("Hello,)d(World"\))236 2579 y(c_char_p\('Hello,) g(World'\))236 2670 y(>>>)j(c_ushort\(-3\))236 2761 y (c_ushort\(65533\))236 2853 y(>>>)0 3139 y FN(Since)20 b(these)h(types)f(are)g(mutable,)f(their)h(v)n(alue)f(can)h(also)h(be)f (changed)e(afterw)o(ards:)236 3377 y FA(>>>)45 b(i)f(=)h(c_int\(42\)) 236 3469 y(>>>)g(print)f(i)236 3560 y(c_long\(42\))236 3651 y(>>>)h(print)f(i.value)236 3743 y(42)236 3834 y(>>>)h(i.value)e (=)i(-99)236 3925 y(>>>)g(print)f(i.value)236 4017 y(-99)236 4108 y(>>>)0 4394 y FN(Assigning)31 b(a)h(ne)n(w)f(v)n(alue)g(to)h (instances)f(of)g(the)h(pointer)e(types)h FJ(c_char_p)p FN(,)j FJ(c_wchar_p)p FN(,)f(and)d FJ(c_void_p)h FN(changes)g(the)0 4494 y FK(memory)h(location)e FN(the)o(y)h(point)g(to,)j FK(not)e(the)f(contents)g FN(of)g(the)h(memory)e(block)h(\(of)g(course) g(not,)j(because)d(Python)f(strings)i(are)0 4594 y(immutable\):)p 0 5549 3901 4 v 0 5649 a FI(504)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 505 517 TeXDict begin 505 516 bop 236 174 a FA(>>>)45 b(s)f(=)h("Hello,)f (World")236 266 y(>>>)h(c_s)f(=)h(c_char_p\(s\))236 357 y(>>>)g(print)f(c_s)236 448 y(c_char_p\('Hello,)e(World'\))236 540 y(>>>)j(c_s.value)e(=)i("Hi,)f(there")236 631 y(>>>)h(print)f(c_s) 236 722 y(c_char_p\('Hi,)f(there'\))236 814 y(>>>)i(print)f(s)762 b(#)44 b(first)g(string)g(is)g(unchanged)236 905 y(Hello,)g(World)236 996 y(>>>)0 1283 y FN(Y)-9 b(ou)26 b(should)g(be)h(careful,)g(ho)n(we)n (v)o(er)m(,)f(not)g(to)h(pass)h(them)e(to)h(functions)e(e)o(xpecting)g (pointers)h(to)h(mutable)f(memory)-5 b(.)43 b(If)26 b(you)g(need)0 1382 y(mutable)i(memory)f(blocks,)j(ctypes)f(has)g(a)g FJ(create_string_buffer)d FN(function)h(which)h(creates)h(these)g(in)g (v)n(arious)e(w)o(ays.)0 1482 y(The)c(current)f(memory)g(block)h (contents)f(can)i(be)f(accessed)g(\(or)g(changed\))e(with)j(the)g FJ(raw)f FN(property;)g(if)h(you)e(w)o(ant)i(to)g(access)g(it)g(as)0 1582 y(NUL)c(terminated)f(string,)h(use)g(the)g FJ(value)g FN(property:)236 1820 y FA(>>>)45 b(from)f(ctypes)g(import)1267 1833 y(*)236 1911 y(>>>)h(p)f(=)h(create_string_buffer\(3\))265 b(#)45 b(create)e(a)i(3)g(byte)f(buffer,)g(initialized)f(to)h(NUL)g (bytes)236 2002 y(>>>)h(print)f(sizeof\(p\),)f(repr\(p.raw\))236 2094 y(3)i('\\x00\\x00\\x00')236 2185 y(>>>)g(p)f(=)h (create_string_buffer\("Hello"\))264 b(#)45 b(create)e(a)i(buffer)f (containing)f(a)i(NUL)f(terminated)f(string)236 2276 y(>>>)i(print)f(sizeof\(p\),)f(repr\(p.raw\))236 2368 y(6)i('Hello\\x00')236 2459 y(>>>)g(print)f(repr\(p.value\))236 2550 y('Hello')236 2642 y(>>>)h(p)f(=)h(create_string_buffer\("Hello",) 40 b(10\))89 b(#)45 b(create)e(a)i(10)g(byte)f(buffer)236 2733 y(>>>)h(print)f(sizeof\(p\),)f(repr\(p.raw\))236 2824 y(10)i('Hello\\x00\\x00\\x00\\x00\\x00')236 2916 y(>>>)g(p.value)e(=)i("Hi")236 3007 y(>>>)g(print)f(sizeof\(p\),)f (repr\(p.raw\))236 3098 y(10)i('Hi\\x00lo\\x00\\x00\\x00\\x00\\x00')236 3190 y(>>>)0 3476 y FN(The)22 b FJ(create_string_buffer)e FN(function)h(replaces)h(the)h FJ(c_buffer)e FN(function)g(\(which)h (is)i(still)f(a)n(v)n(ailable)g(as)g(an)f(alias\),)i(as)0 3576 y(well)f(as)g(the)g FJ(c_string)f FN(function)e(from)i(earlier)g (ctypes)g(releases.)33 b(T)-7 b(o)22 b(create)h(a)g(mutable)e(memory)g (block)h(containing)e(unicode)0 3675 y(characters)f(of)h(the)g(C)h (type)f FJ(wchar_t)g FN(use)g(the)g FJ(create_unicode_buffer)d FN(function.)0 3944 y FI(Calling)25 b(functions)o(,)e(contin)o(ued)0 4147 y FN(Note)f(that)g(printf)e(prints)i(to)g(the)f(real)h(standard)f (output)f(channel,)h FK(not)g FN(to)h FJ(sys.stdout)p FN(,)f(so)h(these)g(e)o(xamples)f(will)h(only)f(w)o(ork)g(at)0 4246 y(the)f(console)g(prompt,)e(not)i(from)f(within)h FK(IDLE)g FN(or)g FK(PythonW)-5 b(in)p FN(:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n (oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e(Python.)1736 b(505)p eop end %%Page: 506 518 TeXDict begin 506 517 bop 236 83 a FA(>>>)45 b(printf)e(=)i (libc.printf)236 174 y(>>>)g(printf\("Hello,)d(\045s\\n",)i("World!"\)) 236 266 y(Hello,)g(World!)236 357 y(14)236 448 y(>>>)h(printf\("Hello,) d(\045S",)i(u"World!"\))236 540 y(Hello,)g(World!)236 631 y(13)236 722 y(>>>)h(printf\("\045d)e(bottles)g(of)i(beer\\n",)e (42\))236 814 y(42)i(bottles)e(of)i(beer)236 905 y(19)236 996 y(>>>)g(printf\("\045f)e(bottles)g(of)i(beer\\n",)e(42.5\))236 1088 y(Traceback)h(\(most)g(recent)f(call)i(last\):)326 1179 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 1270 y(ArgumentError:)f(argument)g(2:)i(exceptions.TypeError:)c(Don't)j (know)g(how)g(to)h(convert)f(parameter)f(2)236 1362 y(>>>)0 1648 y FN(As)26 b(has)g(been)f(mentioned)e(before,)i(all)h(Python)f (types)g(e)o(xcept)f(inte)o(gers,)i(strings,)h(and)d(unicode)g(strings) i(ha)n(v)o(e)f(to)g(be)h(wrapped)d(in)0 1748 y(their)d(corresponding)d FJ(ctypes)i FN(type,)h(so)g(that)h(the)o(y)e(can)h(be)g(con)m(v)o (erted)e(to)i(the)g(required)f(C)i(data)f(type:)236 1986 y FA(>>>)45 b(printf\("An)e(int)h(\045d,)g(a)h(double)f(\045f\\n",)g (1234,)g(c_double\(3.14\)\))236 2077 y(Integer)g(1234,)g(double)g (3.1400001049)236 2169 y(31)236 2260 y(>>>)0 2672 y FI(Calling)25 b(functions)e(with)h(y)n(our)f(o)o(wn)g(custom)f(data)i(types)0 2875 y FN(Y)-9 b(ou)28 b(can)g(also)g(customize)g FJ(ctypes)f FN(ar)o(gument)f(con)m(v)o(ersion)g(to)i(allo)n(w)g(instances)g(of)g (your)f(o)n(wn)h(classes)h(be)f(used)g(as)h(function)0 2975 y(ar)o(guments.)f FJ(ctypes)21 b FN(looks)g(for)g(an)h FJ(_as_parameter_)e FN(attrib)n(ute)h(and)g(uses)i(this)f(as)h(the)e (function)f(ar)o(gument.)28 b(Of)22 b(course,)f(it)0 3075 y(must)f(be)g(one)g(of)g(inte)o(ger)m(,)e(string,)i(or)g(unicode:) 236 3313 y FA(>>>)45 b(class)f(Bottles\(object\):)236 3404 y(...)224 b(def)44 b(__init__\(self,)f(number\):)236 3495 y(...)403 b(self._as_parameter_)42 b(=)j(number)236 3587 y(...)236 3678 y(>>>)g(bottles)e(=)i(Bottles\(42\))236 3769 y(>>>)g(printf\("\045d)e(bottles)g(of)i(beer\\n",)e(bottles\))236 3861 y(42)i(bottles)e(of)i(beer)236 3952 y(19)236 4043 y(>>>)0 4330 y FN(If)36 b(you)f(don')o(t)f(w)o(ant)i(to)g(store)f(the)h (instance')-5 b(s)36 b(data)g(in)g(the)g FJ(_as_parameter_)d FN(instance)j(v)n(ariable,)i(you)d(could)g(de\002ne)g(a)0 4429 y FJ(property)19 b FN(which)h(mak)o(es)g(the)g(data)g(a)n(v)n (aiblable.)0 4698 y FI(Specifying)k(the)g(required)f(argument)h(types)e (\(function)i(prototypes\))0 4901 y FN(It)31 b(is)g(possible)f(to)g (specify)g(the)g(required)f(ar)o(gument)f(types)i(of)g(functions)f(e)o (xported)f(from)h(DLLs)i(by)f(setting)g(the)g FJ(argtypes)0 5000 y FN(attrib)n(ute.)0 5147 y FJ(argtypes)20 b FN(must)h(be)g(a)h (sequence)e(of)h(C)h(data)f(types)g(\(the)f FJ(printf)h FN(function)e(is)j(probably)d(not)i(a)g(good)f(e)o(xample)g(here,)g (because)0 5247 y(it)j(tak)o(es)g(a)g(v)n(ariable)f(number)e(and)i(dif) n(ferent)f(types)h(of)h(parameters)e(depending)f(on)i(the)h(format)e (string,)i(on)f(the)g(other)g(hand)g(this)h(is)0 5346 y(quite)d(handy)e(to)j(e)o(xperiment)d(with)i(this)h(feature\):)p 0 5549 3901 4 v 0 5649 a FI(506)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 507 519 TeXDict begin 507 518 bop 236 174 a FA(>>>)45 b(printf.argtypes)d(=)j ([c_char_p,)e(c_char_p,)g(c_int,)h(c_double])236 266 y(>>>)h(printf\("String)d('\045s',)i(Int)g(\045d,)h(Double)e (\045f\\n",)h("Hi",)g(10,)h(2.2\))236 357 y(String)f('Hi',)g(Int)g(10,) h(Double)f(2.200000)236 448 y(37)236 540 y(>>>)0 826 y FN(Specifying)23 b(a)h(format)g(protects)g(against)f(incompatible)g (ar)o(gument)f(types)i(\(just)h(as)g(a)g(prototype)d(for)h(a)i(C)h (function\),)d(and)g(tries)i(to)0 926 y(con)m(v)o(ert)18 b(the)i(ar)o(guments)f(to)h(v)n(alid)g(types:)236 1164 y FA(>>>)45 b(printf\("\045d)e(\045d)h(\045d",)g(1,)h(2,)f(3\))236 1255 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 1347 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 1438 y(ArgumentError:)f(argument)g(2:)i(exceptions.TypeError:)c(wrong)j (type)236 1529 y(>>>)h(printf\("\045s)e(\045d)h(\045f",)g("X",)h(2,)f (3\))236 1621 y(X)h(2)g(3.00000012)236 1712 y(12)236 1803 y(>>>)0 2090 y FN(If)21 b(you)g(ha)n(v)o(e)g(de\002ned)f(your)g(o) n(wn)h(classes)i(which)e(you)g(pass)h(to)f(function)f(calls,)i(you)f (ha)n(v)o(e)g(to)g(implement)g(a)g FJ(from_param)g FN(class)0 2189 y(method)i(for)h(them)h(to)f(be)h(able)g(to)f(use)h(them)g(in)f (the)h FJ(argtypes)f FN(sequence.)37 b(The)24 b FJ(from_param)g FN(class)h(method)f(recei)n(v)o(es)g(the)0 2289 y(Python)j(object)g (passed)g(to)h(the)g(function)e(call,)k(it)e(should)f(do)g(a)h (typecheck)e(or)i(whate)n(v)o(er)e(is)j(needed)d(to)i(mak)o(e)f(sure)h (this)g(object)0 2389 y(is)h(acceptable,)g(and)f(then)f(return)g(the)h (object)g(itself,)j(it')-5 b(s)29 b FJ(_as_parameter_)d FN(attrib)n(ute,)k(or)e(whate)n(v)o(er)e(you)h(w)o(ant)i(to)f(pass)h (as)0 2488 y(the)24 b(C)h(function)d(ar)o(gument)f(in)j(this)h(case.)36 b(Again,)24 b(the)g(result)f(should)g(be)h(an)g(inte)o(ger)m(,)f (string,)h(unicode,)f(a)h FJ(ctypes)g FN(instance,)g(or)0 2588 y(something)19 b(ha)n(ving)g(the)h FJ(_as_parameter_)e FN(attrib)n(ute.)0 2856 y FI(Retur)r(n)23 b(types)0 3059 y FN(By)16 b(def)o(ault)g(functions)e(are)i(assumed)g(to)g(return)e (the)i(C)h FJ(int)f FN(type.)23 b(Other)16 b(return)f(types)g(can)h(be) g(speci\002ed)g(by)f(setting)h(the)g FJ(restype)0 3159 y FN(attrib)n(ute)k(of)g(the)g(function)e(object.)0 3306 y(Here)h(is)h(a)g(more)f(adv)n(anced)e(e)o(xample,)h(it)i(uses)f(the)h FJ(strchr)e FN(function,)g(which)h(e)o(xpects)f(a)i(string)f(pointer)f (and)h(a)g(char)m(,)g(and)f(returns)0 3405 y(a)j(pointer)e(to)h(a)h (string:)236 3643 y FA(>>>)45 b(strchr)e(=)i(libc.strchr)236 3735 y(>>>)g(strchr\("abcdef",)d(ord\("d"\)\))h(#)i(doctest:)e(+SKIP) 236 3826 y(8059983)236 3917 y(>>>)i(strchr.restype)d(=)j(c_char_p)e(#)i (c_char_p)e(is)i(a)f(pointer)g(to)h(a)f(string)236 4009 y(>>>)h(strchr\("abcdef",)d(ord\("d"\)\))236 4100 y('def')236 4191 y(>>>)j(print)f(strchr\("abcdef",)e(ord\("x"\)\))236 4283 y(None)236 4374 y(>>>)0 4661 y FN(If)22 b(you)e(w)o(ant)i(to)g(a)n (v)n(oid)g(the)f FJ(ord\("x"\))g FN(calls)i(abo)o(v)o(e,)d(you)h(can)g (set)i(the)e FJ(argtypes)g FN(attrib)n(ute,)h(and)f(the)h(second)e(ar)o (gument)g(will)0 4760 y(be)g(con)m(v)o(erted)e(from)h(a)h(single)h (character)d(Python)i(string)f(into)h(a)h(C)g(char:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(507)p eop end %%Page: 508 520 TeXDict begin 508 519 bop 236 174 a FA(>>>)45 b(strchr.restype)d(=)j (c_char_p)236 266 y(>>>)g(strchr.argtypes)d(=)j([c_char_p,)e(c_char]) 236 357 y(>>>)i(strchr\("abcdef",)d("d"\))236 448 y('def')236 540 y(>>>)j(strchr\("abcdef",)d("def"\))236 631 y(Traceback)i(\(most)g (recent)f(call)i(last\):)326 722 y(File)f("<stdin>",)f(line)h(1,)h(in)f (?)236 814 y(ArgumentError:)f(argument)g(2:)i(exceptions.TypeError:)c (one)j(character)g(string)f(expected)236 905 y(>>>)i(print)f (strchr\("abcdef",)e("x"\))236 996 y(None)236 1088 y(>>>)j (strchr\("abcdef",)d("d"\))236 1179 y('def')236 1270 y(>>>)0 1557 y FN(Y)-9 b(ou)20 b(can)h(also)h(use)f(a)g(callable)g (Python)f(object)g(\(a)h(function)f(or)g(a)i(class)g(for)e(e)o (xample\))f(as)j(the)f FJ(restype)f FN(attrib)n(ute,)h(if)g(the)g (foreign)0 1656 y(function)c(returns)h(an)h(inte)o(ger)-5 b(.)24 b(The)19 b(callable)g(will)h(be)f(called)f(with)i(the)f FJ(integer)f FN(the)h(C)h(function)d(returns,)i(and)f(the)h(result)g (of)g(this)0 1756 y(call)24 b(will)h(be)f(used)f(as)i(the)f(result)f (of)h(your)e(function)h(call.)36 b(This)24 b(is)h(useful)e(to)h(check)f (for)g(error)g(return)f(v)n(alues)i(and)f(automatically)0 1856 y(raise)d(an)h(e)o(xception:)236 2094 y FA(>>>)45 b(GetModuleHandle)d(=)j(windll.kernel32.GetModuleHandleA)39 b(#)45 b(doctest:)e(+WINDOWS)236 2185 y(>>>)i(def)f (ValidHandle\(value\):)236 2276 y(...)224 b(if)44 b(value)g(==)h(0:)236 2368 y(...)403 b(raise)44 b(WinError\(\))236 2459 y(...)224 b(return)44 b(value)236 2550 y(...)236 2642 y(>>>)236 2733 y(>>>)h(GetModuleHandle.restype)c(=)j(ValidHandle)f(#)i(doctest:)e (+WINDOWS)236 2824 y(>>>)i(GetModuleHandle\(None\))c(#)k(doctest:)e (+WINDOWS)236 2916 y(486539264)236 3007 y(>>>)i (GetModuleHandle\("something)40 b(silly"\))k(#)g(doctest:)g(+WINDOWS) 236 3098 y(Traceback)g(\(most)g(recent)f(call)i(last\):)326 3190 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)326 3281 y(File)g("<stdin>",)f(line)h(3,)h(in)f(ValidHandle)236 3372 y(WindowsError:)f([Errno)h(126])g(The)g(specified)f(module)h (could)g(not)h(be)f(found.)236 3464 y(>>>)0 3750 y FJ(WinError)26 b FN(is)i(a)g(function)e(which)g(will)i(call)g(W)m(indo)n(ws)f FJ(FormatMessage\(\))e FN(api)i(to)g(get)g(the)h(string)f (representation)e(of)i(an)0 3850 y(error)d(code,)j(and)e FK(r)m(eturns)h FN(an)f(e)o(xception.)39 b FJ(WinError)25 b FN(tak)o(es)h(an)g(optional)e(error)g(code)h(parameter)m(,)g(if)h(no) f(one)g(is)i(used,)f(it)h(calls)0 3949 y FJ(GetLastError\(\))18 b FN(to)i(retrie)n(v)o(e)f(it.)0 4096 y(Please)24 b(note)e(that)h(a)h (much)e(more)g(po)n(werful)f(error)h(checking)f(mechanism)h(is)i(a)n(v) n(ailable)e(through)f(the)i FJ(errcheck)f FN(attrib)n(ute;)i(see)0 4196 y(the)c(reference)f(manual)g(for)g(details.)0 4464 y FI(P)m(assing)k(pointers)g(\(or)r(:)29 b(passing)23 b(par)o(ameters)g(b)n(y)g(ref)n(erence\))0 4667 y FN(Sometimes)i(a)h(C) h(api)e(function)f(e)o(xpects)h(a)h FK(pointer)f FN(to)h(a)g(data)g (type)f(as)h(parameter)m(,)f(probably)e(to)j(write)g(into)f(the)h (corresponding)0 4767 y(location,)19 b(or)h(if)g(the)h(data)f(is)h(too) f(lar)o(ge)f(to)h(be)g(passed)g(by)g(v)n(alue.)k(This)d(is)g(also)f (kno)n(wn)f(as)i FK(passing)f(par)o(ameter)o(s)f(by)h(r)m(efer)m(ence)p FN(.)0 4914 y FJ(ctypes)f FN(e)o(xports)f(the)h FJ(byref)g FN(function)f(which)h(is)h(used)f(to)h(pass)f(parameters)g(by)g (reference.)j(The)e(same)f(ef)n(fect)g(can)g(be)g(achie)n(v)o(ed)0 5013 y(with)h(the)f FJ(pointer)g FN(function,)e(although)h FJ(pointer)g FN(does)i(a)f(lot)h(more)f(w)o(ork)f(since)i(it)g (constructs)f(a)g(real)h(pointer)e(object,)h(so)h(it)g(is)0 5113 y(f)o(aster)g(to)h(use)f FJ(byref)g FN(if)g(you)g(don')o(t)e(need) i(the)g(pointer)f(object)h(in)g(Python)f(itself:)p 0 5549 3901 4 v 0 5649 a FI(508)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 509 521 TeXDict begin 509 520 bop 236 174 a FA(>>>)45 b(i)f(=)h(c_int\(\))236 266 y(>>>)g(f)f(=)h(c_float\(\))236 357 y(>>>)g(s)f(=)h (create_string_buffer\('\\000')1850 370 y(*)1940 357 y(32\))236 448 y(>>>)g(print)f(i.value,)f(f.value,)h(repr\(s.value\)) 236 540 y(0)h(0.0)f('')236 631 y(>>>)h(libc.sscanf\("1)d(3.14)i (Hello",)g("\045d)g(\045f)h(\045s",)236 722 y(...)583 b(byref\(i\),)43 b(byref\(f\),)g(s\))236 814 y(3)236 905 y(>>>)i(print)f(i.value,)f(f.value,)h(repr\(s.value\))236 996 y(1)h(3.1400001049)e('Hello')236 1088 y(>>>)0 1500 y FI(Str)q(uctures)23 b(and)g(unions)0 1703 y FN(Structures)e(and)h (unions)f(must)h(deri)n(v)o(e)f(from)g(the)h FJ(Structure)f FN(and)g FJ(Union)h FN(base)g(classes)h(which)f(are)g(de\002ned)f(in)h (the)g FJ(ctypes)0 1803 y FN(module.)33 b(Each)22 b(subclass)i(must)f (de\002ne)g(a)h FJ(_fields_)e FN(attrib)n(ute.)34 b FJ(_fields_)22 b FN(must)h(be)g(a)h(list)g(of)f FK(2-tuples)p FN(,)g(containing)e(a)j FK(\002eld)0 1902 y(name)c FN(and)f(a)i FK(\002eld)f(type)p FN(.)0 2049 y(The)d(\002eld)g(type)f(must)h(be)g(a)g FJ(ctypes)f FN(type)h(lik)o(e)g FJ(c_int)p FN(,)g(or)g(an)o(y)f(other)g (deri)n(v)o(ed)f FJ(ctypes)h FN(type:)23 b(structure,)17 b(union,)f(array)-5 b(,)16 b(pointer)-5 b(.)0 2196 y(Here)23 b(is)g(a)h(simple)e(e)o(xample)g(of)g(a)i(POINT)e(structure,)h(which)f (contains)g(tw)o(o)h(inte)o(gers)f(named)g FJ(x)h FN(and)f FJ(y)p FN(,)i(and)e(also)h(sho)n(ws)g(ho)n(w)f(to)0 2296 y(initialize)e(a)h(structure)e(in)i(the)f(constructor:)236 2442 y FA(>>>)45 b(from)f(ctypes)g(import)1267 2455 y(*)236 2534 y(>>>)h(class)f(POINT\(Structure\):)236 2625 y(...)224 b(_fields_)43 b(=)i([\("x",)f(c_int\),)236 2716 y(...)762 b(\("y",)44 b(c_int\)])236 2808 y(...)236 2899 y(>>>)h(point)f(=)g (POINT\(10,)g(20\))236 2990 y(>>>)h(print)f(point.x,)f(point.y)236 3082 y(10)i(20)236 3173 y(>>>)g(point)f(=)g(POINT\(y=5\))236 3264 y(>>>)h(print)f(point.x,)f(point.y)236 3356 y(0)i(5)236 3447 y(>>>)g(POINT\(1,)e(2,)i(3\))236 3538 y(Traceback)f(\(most)g (recent)f(call)i(last\):)326 3630 y(File)f("<stdin>",)f(line)h(1,)h(in) f(?)236 3721 y(ValueError:)f(too)i(many)f(initializers)236 3812 y(>>>)0 4099 y FN(Y)-9 b(ou)23 b(can,)h(ho)n(we)n(v)o(er)m(,)f(b)n (uild)g(much)g(more)g(complicated)f(structures.)35 b(Structures)23 b(can)g(itself)i(contain)d(other)h(structures)h(by)f(using)g(a)0 4198 y(structure)c(as)i(a)g(\002eld)f(type.)0 4345 y(Here)g(is)h(a)g (RECT)g(structure)e(which)h(contains)f(tw)o(o)i(POINTs)f(named)f FJ(upperleft)g FN(and)h FJ(lowerright)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f (function)h(libr)o(ar)r(y)g(f)n(or)e(Python.)1736 b(509)p eop end %%Page: 510 522 TeXDict begin 510 521 bop 236 174 a FA(>>>)45 b(class)f (RECT\(Structure\):)236 266 y(...)224 b(_fields_)43 b(=)i ([\("upperleft",)e(POINT\),)236 357 y(...)762 b(\("lowerright",)42 b(POINT\)])236 448 y(...)236 540 y(>>>)j(rc)f(=)h(RECT\(point\))236 631 y(>>>)g(print)f(rc.upperleft.x,)e(rc.upperleft.y)236 722 y(0)j(5)236 814 y(>>>)g(print)f(rc.lowerright.x,)e(rc.lowerright.y) 236 905 y(0)j(0)236 996 y(>>>)0 1283 y FN(Nested)20 b(structures)g(can) g(also)g(be)g(initialized)g(in)h(the)f(constructor)e(in)i(se)n(v)o (eral)g(w)o(ays:)236 1521 y FA(>>>)45 b(r)f(=)h(RECT\(POINT\(1,)e(2\),) h(POINT\(3,)f(4\)\))236 1612 y(>>>)i(r)f(=)h(RECT\(\(1,)e(2\),)i(\(3,)f (4\)\))0 1899 y FN(Fields)31 b(descriptors)e(can)i(be)f(retrie)n(v)o (ed)f(from)h(the)g FK(class)p FN(,)k(the)o(y)29 b(are)i(useful)f(for)g (deb)n(ugging)e(because)h(the)o(y)h(can)h(pro)o(vide)d(useful)0 1999 y(information:)236 2237 y FA(>>>)45 b(print)f(POINT.x)236 2328 y(<Field)g(type=c_long,)f(ofs=0,)h(size=4>)236 2419 y(>>>)h(print)f(POINT.y)236 2511 y(<Field)g(type=c_long,)f(ofs=4,)h (size=4>)236 2602 y(>>>)0 3015 y FI(Str)q(ucture/union)24 b(alignment)h(and)f(b)n(yte)f(order)0 3218 y FN(By)i(def)o(ault,)f (Structure)f(and)g(Union)h(\002elds)g(are)g(aligned)g(in)g(the)g(same)g (w)o(ay)h(the)f(C)h(compiler)e(does)h(it.)37 b(It)25 b(is)g(possible)f(to)g(o)o(v)o(erride)0 3317 y(this)d(beha)n(viour)d (be)i(specifying)f(a)i FJ(_pack_)e FN(class)j(attrib)n(ute)e(in)g(the)g (subclass)h(de\002nition.)j(This)c(must)h(be)f(set)h(to)g(a)f(positi)n (v)o(e)g(inte)o(ger)0 3417 y(and)g(speci\002es)g(the)h(maximum)d (alignment)h(for)g(the)i(\002elds.)k(This)20 b(is)i(what)e FJ(#pragma)48 b(pack\(n\))20 b FN(also)g(does)g(in)g(MSVC.)0 3564 y FJ(ctypes)26 b FN(uses)i(the)f(nati)n(v)o(e)f(byte)g(order)g (for)g(Structures)h(and)f(Unions.)45 b(T)-7 b(o)27 b(b)n(uild)f (structures)h(with)g(non-nati)n(v)o(e)d(byte)j(order)m(,)f(you)0 3663 y(can)21 b(use)g(one)g(of)f(the)h(BigEndianStructure,)d (LittleEndianStructure,)h(BigEndianUnion,)f(and)i(LittleEndianUnion)f (base)i(classes.)0 3763 y(These)f(classes)h(cannot)e(contain)h(pointer) f(\002elds.)0 4031 y FI(Bit)24 b(\002elds)f(in)g(str)q(uctures)f(and)i (unions)0 4234 y FN(It)d(is)h(possible)f(to)g(create)g(structures)f (and)g(unions)g(containing)f(bit)j(\002elds.)27 b(Bit)c(\002elds)e(are) g(only)f(possible)h(for)f(inte)o(ger)g(\002elds,)h(the)g(bit)0 4334 y(width)f(is)h(speci\002ed)f(as)h(the)f(third)g(item)g(in)g(the)h FJ(_fields_)e FN(tuples:)p 0 5549 3901 4 v 0 5649 a FI(510)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 511 523 TeXDict begin 511 522 bop 236 174 a FA(>>>)45 b(class)f (Int\(Structure\):)236 266 y(...)224 b(_fields_)43 b(=)i ([\("first_16",)e(c_int,)g(16\),)236 357 y(...)762 b(\("second_16",)43 b(c_int,)g(16\)])236 448 y(...)236 540 y(>>>)i(print)f(Int.first_16)236 631 y(<Field)g(type=c_long,)f(ofs=0:0,)g(bits=16>)236 722 y(>>>)i(print)f(Int.second_16)236 814 y(<Field)g(type=c_long,)f (ofs=0:16,)g(bits=16>)236 905 y(>>>)0 1316 y FI(Arr)o(a)n(ys)0 1519 y FN(Arrays)20 b(are)g(sequences,)f(containing)f(a)j(\002x)o(ed)e (number)g(of)h(instances)g(of)g(the)g(same)g(type.)0 1666 y(The)g(recommended)d(w)o(ay)j(to)h(create)e(array)h(types)g(is)h (by)f(multiplying)e(a)j(data)f(type)f(with)i(a)f(positi)n(v)o(e)g(inte) o(ger:)236 1904 y FA(TenPointsArrayType)42 b(=)j(POINT)1447 1917 y(*)1536 1904 y(10)0 2191 y FN(Here)20 b(is)h(an)f(e)o(xample)f (of)h(an)g(some)n(what)f(arti\002cal)i(data)f(type,)f(a)i(structure)e (containing)g(4)h(POINTs)g(among)f(other)g(stuf)n(f:)236 2429 y FA(>>>)45 b(from)f(ctypes)g(import)1267 2442 y(*)236 2520 y(>>>)h(class)f(POINT\(Structure\):)236 2612 y(...)179 b(_fields_)44 b(=)g(\("x",)g(c_int\),)g(\("y",)g(c_int\))236 2703 y(...)236 2794 y(>>>)h(class)f(MyStruct\(Structure\):)236 2886 y(...)179 b(_fields_)44 b(=)g([\("a",)g(c_int\),)236 2977 y(...)717 b(\("b",)44 b(c_float\),)236 3068 y(...)717 b(\("point_array",)42 b(POINT)2074 3081 y(*)2164 3068 y(4\)])236 3160 y(>>>)236 3251 y(>>>)j(print)f (len\(MyStruct\(\).point_array\))236 3342 y(4)236 3433 y(>>>)0 3720 y FN(Instances)20 b(are)g(created)f(in)i(the)f(usual)g(w)o (ay)-5 b(,)19 b(by)h(calling)g(the)g(class:)236 3958 y FA(arr)45 b(=)f(TenPointsArrayType\(\))236 4050 y(for)h(pt)f(in)h (arr:)416 4141 y(print)f(pt.x,)g(pt.y)0 4427 y FN(The)20 b(abo)o(v)o(e)e(code)i(print)f(a)i(series)g(of)f FJ(0)49 b(0)21 b FN(lines,)f(because)g(the)g(array)f(contents)h(is)h (initialized)f(to)g(zeros.)0 4574 y(Initializers)g(of)g(the)g(correct)f (type)h(can)g(also)g(be)h(speci\002ed:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f (function)h(libr)o(ar)r(y)g(f)n(or)e(Python.)1736 b(511)p eop end %%Page: 512 524 TeXDict begin 512 523 bop 236 174 a FA(>>>)45 b(from)f(ctypes)g(import) 1267 187 y(*)236 266 y(>>>)h(TenIntegers)e(=)h(c_int)1312 279 y(*)1402 266 y(10)236 357 y(>>>)h(ii)f(=)h(TenIntegers\(1,)d(2,)j (3,)f(4,)h(5,)f(6,)h(7,)f(8,)h(9,)f(10\))236 448 y(>>>)h(print)f(ii)236 540 y(<c_long_Array_10)e(object)i(at)h(0x...>)236 631 y(>>>)g(for)f(i)h(in)f(ii:)g(print)g(i,)236 722 y(...)236 814 y(1)h(2)g(3)f(4)h(5)g(6)f(7)h(8)g(9)f(10)236 905 y(>>>)0 1316 y FI(P)l(ointers)0 1519 y FN(Pointer)20 b(instances)g(are)g(created)f(by)h(calling)g(the)g FJ(pointer)f FN(function)g(on)h(a)g FJ(ctypes)g FN(type:)236 1757 y FA(>>>)45 b(from)f(ctypes)g(import)1267 1770 y(*)236 1849 y(>>>)h(i)f(=)h(c_int\(42\))236 1940 y(>>>)g(pi)f(=)h (pointer\(i\))236 2031 y(>>>)0 2318 y FN(Pointer)18 b(instances)h(ha)n (v)o(e)g(a)g FJ(contents)f FN(attrib)n(ute)h(which)f(returns)h(the)g (object)f(to)h(which)g(the)g(pointer)f(points,)g(the)h FJ(i)h FN(object)e(abo)o(v)o(e:)236 2556 y FA(>>>)45 b(pi.contents)236 2647 y(c_long\(42\))236 2739 y(>>>)0 3025 y FN(Note)24 b(that)h FJ(ctypes)f FN(does)g(not)g(ha)n(v)o(e)g (OOR)h(\(original)e(object)h(return\),)g(it)h(constructs)f(a)g(ne)n(w) -5 b(,)25 b(equi)n(v)n(alent)e(object)h(each)g(time)g(you)0 3125 y(retrie)n(v)o(e)19 b(an)h(attrib)n(ute:)236 3363 y FA(>>>)45 b(pi.contents)e(is)h(i)236 3454 y(False)236 3546 y(>>>)h(pi.contents)e(is)h(pi.contents)236 3637 y(False)236 3728 y(>>>)0 4015 y FN(Assigning)21 b(another)f FJ(c_int)i FN(instance)f(to)h(the)g(pointer')-5 b(s)21 b(contents)g(attrib)n(ute)g(w)o(ould)g(cause)h(the)f(pointer)g(to)h (point)f(to)h(the)f(memory)0 4114 y(location)e(where)h(this)h(is)g (stored:)236 4353 y FA(>>>)45 b(i)f(=)h(c_int\(99\))236 4444 y(>>>)g(pi.contents)e(=)h(i)236 4535 y(>>>)h(pi.contents)236 4627 y(c_long\(99\))236 4718 y(>>>)0 5004 y FN(Pointer)20 b(instances)g(can)g(also)g(be)g(inde)o(x)o(ed)e(with)j(inte)o(gers:)p 0 5549 3901 4 v 0 5649 a FI(512)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 513 525 TeXDict begin 513 524 bop 236 174 a FA(>>>)45 b(pi[0])236 266 y(99)236 357 y(>>>)0 644 y FN(Assigning)19 b(to)i(an)f(inte)o(ger)f (inde)o(x)g(changes)g(the)h(pointed)f(to)i(v)n(alue:)236 882 y FA(>>>)45 b(print)f(i)236 973 y(c_long\(99\))236 1064 y(>>>)h(pi[0])f(=)g(22)236 1156 y(>>>)h(print)f(i)236 1247 y(c_long\(22\))236 1338 y(>>>)0 1625 y FN(It)22 b(is)g(also)g(possible)f(to)g(use)h(inde)o(x)o(es)e(dif)n(ferent)f (from)i(0,)g(b)n(ut)g(you)g(must)g(kno)n(w)g(what)g(you')l(re)e(doing,) h(just)i(as)g(in)g(C:)g(Y)-9 b(ou)21 b(can)g(access)0 1724 y(or)g(change)e(arbitrary)h(memory)f(locations.)27 b(Generally)20 b(you)g(only)g(use)i(this)f(feature)f(if)i(you)e(recei)n (v)o(e)g(a)h(pointer)f(from)g(a)i(C)g(function,)0 1824 y(and)e(you)f FK(know)h FN(that)g(the)g(pointer)f(actually)h(points)g (to)g(an)g(array)f(instead)h(of)g(a)h(single)f(item.)0 1971 y(Behind)c(the)i(scenes,)f(the)g FJ(pointer)g FN(function)e(does)i (more)f(than)h(simply)f(create)h(pointer)f(instances,)h(it)h(has)g(to)f (create)g(pointer)e FK(types)0 2071 y FN(\002rst.)26 b(This)20 b(is)h(done)e(with)i(the)f FJ(POINTER)f FN(function,)g(which) g(accepts)h(an)o(y)g FJ(ctypes)f FN(type,)h(and)f(returns)h(a)g(ne)n(w) g(type:)236 2309 y FA(>>>)45 b(PI)f(=)h(POINTER\(c_int\))236 2400 y(>>>)g(PI)236 2491 y(<class)f('ctypes.LP_c_long'>)236 2583 y(>>>)h(PI\(42\))236 2674 y(Traceback)f(\(most)g(recent)f(call)i (last\):)326 2765 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 2857 y(TypeError:)f(expected)h(c_long)g(instead)f(of)i(int)236 2948 y(>>>)g(PI\(c_int\(42\)\))236 3039 y(<ctypes.LP_c_long)d(object)i (at)h(0x...>)236 3131 y(>>>)0 3417 y FN(Calling)20 b(the)g(pointer)f (type)h(without)g(an)g(ar)o(gument)e(creates)i(a)g FJ(NULL)g FN(pointer)-5 b(.)25 b FJ(NULL)20 b FN(pointers)f(ha)n(v)o(e)g(a)i FJ(False)f FN(boolean)e(v)n(alue:)236 3655 y FA(>>>)45 b(null_ptr)e(=)i(POINTER\(c_int\)\(\))236 3747 y(>>>)g(print)f (bool\(null_ptr\))236 3838 y(False)236 3929 y(>>>)0 4216 y FJ(ctypes)20 b FN(checks)f(for)h FJ(NULL)g FN(when)f(dereferencing)f (pointers)h(\(b)n(ut)h(dereferencing)d(non-)p FJ(NULL)h FN(pointers)h(w)o(ould)h(crash)g(Python\):)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f (function)h(libr)o(ar)r(y)g(f)n(or)e(Python.)1736 b(513)p eop end %%Page: 514 526 TeXDict begin 514 525 bop 236 174 a FA(>>>)45 b(null_ptr[0])236 266 y(Traceback)f(\(most)g(recent)f(call)i(last\):)416 357 y(....)236 448 y(ValueError:)e(NULL)h(pointer)g(access)236 540 y(>>>)236 722 y(>>>)h(null_ptr[0])e(=)h(1234)236 814 y(Traceback)g(\(most)g(recent)f(call)i(last\):)416 905 y(....)236 996 y(ValueError:)e(NULL)h(pointer)g(access)236 1088 y(>>>)0 1499 y FI(T)-10 b(ype)23 b(con)n(v)n(ersions)0 1702 y FN(Usually)-5 b(,)26 b(ctypes)e(does)h(strict)h(type)e (checking.)38 b(This)26 b(means,)f(if)h(you)e(ha)n(v)o(e)h FJ(POINTER\(c_int\))e FN(in)i(the)g FJ(argtypes)f FN(list)i(of)f(a)0 1801 y(function)17 b(or)h(as)h(the)f(type)g(of)g(a)h(member)d(\002eld)j (in)f(a)h(structure)f(de\002nition,)f(only)g(instances)i(of)f(e)o (xactly)f(the)h(same)h(type)f(are)g(accepted.)0 1901 y(There)26 b(are)h(some)g(e)o(xceptions)e(to)i(this)h(rule,)g(where)e (ctypes)h(accepts)f(other)g(objects.)45 b(F)o(or)27 b(e)o(xample,)g (you)f(can)h(pass)g(compatible)0 2001 y(array)19 b(instances)h(instead) g(of)g(pointer)f(types.)25 b(So,)20 b(for)g FJ(POINTER\(c_int\))p FN(,)e(ctypes)h(accepts)i(an)f(array)f(of)h(c)p 3246 2001 25 4 v 30 w(int:)236 2148 y FA(>>>)45 b(class)f(Bar\(Structure\):) 236 2239 y(...)224 b(_fields_)43 b(=)i([\("count",)e(c_int\),)h (\("values",)f(POINTER\(c_int\)\)])236 2330 y(...)236 2422 y(>>>)i(bar)f(=)h(Bar\(\))236 2513 y(>>>)g(bar.values)e(=)h (\(c_int)1312 2526 y(*)1402 2513 y(3\)\(1,)g(2,)g(3\))236 2604 y(>>>)h(bar.count)e(=)i(3)236 2695 y(>>>)g(for)f(i)h(in)f (range\(bar.count\):)236 2787 y(...)224 b(print)44 b(bar.values[i])236 2878 y(...)236 2969 y(1)236 3061 y(2)236 3152 y(3)236 3243 y(>>>)0 3530 y FN(T)-7 b(o)20 b(set)h(a)g(POINTER)f(type)g (\002eld)g(to)h FJ(NULL)p FN(,)e(you)h(can)g(assign)g FJ(None)p FN(:)236 3768 y FA(>>>)45 b(bar.values)e(=)h(None)236 3859 y(>>>)0 4146 y FN(XXX)21 b(list)g(other)e(con)m(v)o(ersions...)0 4293 y(Sometimes)f(you)f(ha)n(v)o(e)h(instances)g(of)g(incompatible)f (types.)24 b(In)18 b FJ(C)p FN(,)h(you)e(can)h(cast)h(one)f(type)g (into)g(another)f(type.)24 b FJ(ctypes)17 b FN(pro)o(vides)0 4392 y(a)23 b FJ(cast)f FN(function)e(which)i(can)g(be)h(used)f(in)g (the)g(same)h(w)o(ay)-5 b(.)31 b(The)22 b FJ(Bar)g FN(structure)f (de\002ned)h(abo)o(v)o(e)e(accepts)j FJ(POINTER\(c_int\))0 4492 y FN(pointers)c(or)h FJ(c_int)g FN(arrays)g(for)f(its)i FJ(values)f FN(\002eld,)g(b)n(ut)g(not)g(instances)g(of)g(other)g (types:)236 4730 y FA(>>>)45 b(bar.values)e(=)h(\(c_byte)1357 4743 y(*)1447 4730 y(4\)\(\))236 4822 y(Traceback)g(\(most)g(recent)f (call)i(last\):)326 4913 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 5004 y(TypeError:)f(incompatible)g(types,)h(c_byte_Array_4)e(instance)i (instead)g(of)g(LP_c_long)f(instance)236 5096 y(>>>)0 5382 y FN(F)o(or)20 b(these)g(cases,)h(the)f FJ(cast)g FN(function)f(is)i(handy)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(514)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 515 527 TeXDict begin 515 526 bop 0 83 a FN(The)19 b FJ(cast)g FN(function)e(can)i(be)h(used)f(to)g(cast)h(a)g(ctypes)e(instance)h (into)g(a)h(pointer)e(to)h(a)h(dif)n(ferent)e(ctypes)g(data)i(type.)k FJ(cast)19 b FN(tak)o(es)g(tw)o(o)0 183 y(parameters,)i(a)h(ctypes)f (object)g(that)h(is)h(or)e(can)h(be)g(con)m(v)o(erted)d(to)i(a)i (pointer)d(of)i(some)f(kind,)g(and)g(a)h(ctypes)g(pointer)e(type.)29 b(It)22 b(returns)0 282 y(an)e(instance)g(of)g(the)g(second)f(ar)o (gument,)f(which)i(references)e(the)j(same)f(memory)e(block)i(as)h(the) f(\002rst)h(ar)o(gument:)236 520 y FA(>>>)45 b(a)f(=)h(\(c_byte)954 533 y(*)1043 520 y(4\)\(\))236 612 y(>>>)g(cast\(a,)e (POINTER\(c_int\)\))236 703 y(<ctypes.LP_c_long)f(object)i(at)h(...>) 236 794 y(>>>)0 1081 y FN(So,)20 b FJ(cast)g FN(can)g(be)g(used)g(to)h (assign)f(to)g(the)g FJ(values)g FN(\002eld)g(of)g FJ(Bar)h FN(the)f(structure:)236 1319 y FA(>>>)45 b(bar)f(=)h(Bar\(\))236 1410 y(>>>)g(bar.values)e(=)h(cast\(\(c_byte)1581 1423 y(*)1671 1410 y(4\)\(\),)g(POINTER\(c_int\)\))236 1502 y(>>>)h(print)f(bar.values[0])236 1593 y(0)236 1684 y(>>>)0 2096 y FI(Incomplete)24 b(T)-10 b(ypes)0 2299 y FK(Incomplete)24 b(T)-6 b(ypes)27 b FN(are)f(structures,)g(unions)f(or)h(arrays)g(whose) f(members)g(are)h(not)g(yet)g(speci\002ed.)42 b(In)26 b(C,)h(the)o(y)e(are)h(speci\002ed)g(by)0 2398 y(forw)o(ard)19 b(declarations,)f(which)i(are)g(de\002ned)f(later:)236 2636 y FA(struct)44 b(cell;)g(/)864 2649 y(*)954 2636 y(forward)f(declaration)1850 2649 y(*)1895 2636 y(/)236 2819 y(struct)h({)416 2910 y(char)640 2923 y(*)685 2910 y(name;)416 3002 y(struct)f(cell)954 3015 y(*)999 3002 y(next;)236 3093 y(})i(cell;)0 3380 y FN(The)20 b(straightforw)o(ard)e (translation)h(into)h(ctypes)g(code)f(w)o(ould)h(be)g(this,)g(b)n(ut)g (it)h(does)f(not)g(w)o(ork:)236 3618 y FA(>>>)45 b(class)f (cell\(Structure\):)236 3709 y(...)224 b(_fields_)43 b(=)i([\("name",)e(c_char_p\),)236 3800 y(...)762 b(\("next",)43 b(POINTER\(cell\)\)])236 3892 y(...)236 3983 y(Traceback)h(\(most)g (recent)f(call)i(last\):)326 4074 y(File)f("<stdin>",)f(line)h(1,)h(in) f(?)326 4166 y(File)g("<stdin>",)f(line)h(2,)h(in)f(cell)236 4257 y(NameError:)f(name)i('cell')e(is)i(not)f(defined)236 4348 y(>>>)0 4635 y FN(because)26 b(the)g(ne)n(w)h FJ(class)49 b(cell)26 b FN(is)h(not)g(a)n(v)n(ailable)f(in)g(the)h(class)g (statement)g(itself.)44 b(In)27 b FJ(ctypes)p FN(,)g(we)g(can)f (de\002ne)g(the)h FJ(cell)0 4735 y FN(class)21 b(and)f(set)h(the)f FJ(_fields_)f FN(attrib)n(ute)h(later)m(,)g(after)g(the)g(class)h (statement:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f) n(or)e(Python.)1736 b(515)p eop end %%Page: 516 528 TeXDict begin 516 527 bop 236 174 a FA(>>>)45 b(from)f(ctypes)g(import) 1267 187 y(*)236 266 y(>>>)h(class)f(cell\(Structure\):)236 357 y(...)224 b(pass)236 448 y(...)236 540 y(>>>)45 b(cell._fields_)d (=)j([\("name",)e(c_char_p\),)236 631 y(...)807 b(\("next",)43 b(POINTER\(cell\)\)])236 722 y(>>>)0 1009 y FN(Lets)23 b(try)g(it.)34 b(W)-7 b(e)24 b(create)f(tw)o(o)g(instances)g(of)g FJ(cell)p FN(,)g(and)f(let)i(them)f(point)f(to)h(each)f(other)m(,)h (and)f(\002nally)h(follo)n(w)f(the)h(pointer)f(chain)g(a)0 1108 y(fe)n(w)e(times:)236 1255 y FA(>>>)45 b(c1)f(=)h(cell\(\))236 1347 y(>>>)g(c1.name)e(=)i("foo")236 1438 y(>>>)g(c2)f(=)h(cell\(\))236 1529 y(>>>)g(c2.name)e(=)i("bar")236 1621 y(>>>)g(c1.next)e(=)i (pointer\(c2\))236 1712 y(>>>)g(c2.next)e(=)i(pointer\(c1\))236 1803 y(>>>)g(p)f(=)h(c1)236 1895 y(>>>)g(for)f(i)h(in)f(range\(8\):)236 1986 y(...)224 b(print)44 b(p.name,)236 2077 y(...)224 b(p)45 b(=)f(p.next[0])236 2169 y(...)236 2260 y(foo)h(bar)f(foo)g(bar) h(foo)f(bar)g(foo)h(bar)236 2351 y(>>>)0 2764 y FI(Callbac)n(k)24 b(functions)0 2967 y FJ(ctypes)i FN(allo)n(ws)h(to)g(create)f(C)i (callable)e(function)f(pointers)g(from)h(Python)f(callables.)45 b(These)26 b(are)h(sometimes)f(called)g FK(callbac)n(k)0 3066 y(functions)p FN(.)0 3213 y(First,)20 b(you)e(must)i(create)f(a)g (class)i(for)d(the)i(callback)e(function,)f(the)j(class)g(kno)n(ws)e (the)i(calling)f(con)m(v)o(ention,)d(the)j(return)f(type,)h(and)g(the)0 3313 y(number)f(and)i(types)g(of)g(ar)o(guments)e(this)j(function)d (will)j(recei)n(v)o(e.)0 3460 y(The)27 b(CFUNCTYPE)g(f)o(actory)f (function)f(creates)i(types)g(for)f(callback)g(functions)g(using)g(the) h(normal)f(cdecl)g(calling)h(con)m(v)o(ention,)0 3559 y(and,)20 b(on)h(W)m(indo)n(ws,)f(the)h(WINFUNCTYPE)h(f)o(actory)d (function)h(creates)h(types)f(for)h(callback)f(functions)f(using)i(the) g(stdcall)g(calling)0 3659 y(con)m(v)o(ention.)0 3806 y(Both)j(of)g(these)h(f)o(actory)e(functions)g(are)h(called)g(with)g (the)g(result)h(type)e(as)i(\002rst)g(ar)o(gument,)e(and)h(the)g (callback)f(functions)g(e)o(xpected)0 3905 y(ar)o(gument)18 b(types)i(as)h(the)f(remaining)e(ar)o(guments.)0 4052 y(I)j(will)h(present)e(an)h(e)o(xample)e(here)h(which)g(uses)i(the)f (standard)e(C)j(library')-5 b(s)20 b FJ(qsort)h FN(function,)e(this)i (is)h(used)e(to)h(sort)g(items)h(with)f(the)0 4152 y(help)f(of)g(a)g (callback)g(function.)j FJ(qsort)d FN(will)h(be)f(used)g(to)g(sort)g (an)g(array)g(of)g(inte)o(gers:)236 4390 y FA(>>>)45 b(IntArray5)e(=)i(c_int)1223 4403 y(*)1312 4390 y(5)236 4481 y(>>>)g(ia)f(=)h(IntArray5\(5,)e(1,)h(7,)h(33,)f(99\))236 4573 y(>>>)h(qsort)f(=)g(libc.qsort)236 4664 y(>>>)h(qsort.restype)d(=) j(None)236 4755 y(>>>)0 5042 y FJ(qsort)18 b FN(must)h(be)f(called)g (with)h(a)g(pointer)e(to)i(the)f(data)g(to)h(sort,)g(the)f(number)f(of) h(items)h(in)g(the)f(data)g(array)-5 b(,)18 b(the)g(size)h(of)f(one)g (item,)h(and)0 5141 y(a)j(pointer)f(to)g(the)h(comparison)e(function,)g (the)h(callback.)29 b(The)21 b(callback)g(will)i(then)e(be)h(called)f (with)h(tw)o(o)g(pointers)f(to)g(items,)i(and)e(it)0 5241 y(must)e(return)f(a)i(ne)o(gati)n(v)o(e)d(inte)o(ger)h(if)h(the)g (\002rst)h(item)f(is)i(smaller)e(than)f(the)h(second,)g(a)g(zero)g(if)g (the)o(y)g(are)g(equal,)f(and)h(a)g(positi)n(v)o(e)g(inte)o(ger)0 5341 y(else.)p 0 5549 3901 4 v 0 5649 a FI(516)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 517 529 TeXDict begin 517 528 bop 0 83 a FN(So)26 b(our)f(callback)g(function)f (recei)n(v)o(es)g(pointers)h(to)h(inte)o(gers,)g(and)f(must)h(return)e (an)i(inte)o(ger)-5 b(.)40 b(First)27 b(we)f(create)f(the)h FJ(type)g FN(for)f(the)0 183 y(callback)19 b(function:)236 421 y FA(>>>)45 b(CMPFUNC)e(=)i(CFUNCTYPE\(c_int,)d(POINTER\(c_int\),)g (POINTER\(c_int\)\))236 512 y(>>>)0 799 y FN(F)o(or)19 b(the)h(\002rst)h(implementation)c(of)j(the)f(callback)g(function,)f (we)i(simply)g(print)f(the)g(ar)o(guments)f(we)i(get,)g(and)f(return)g (0)g(\(incremental)0 898 y(de)n(v)o(elopment)e(;-\):)236 1137 y FA(>>>)45 b(def)f(py_cmp_func\(a,)e(b\):)236 1228 y(...)224 b(print)44 b("py_cmp_func",)e(a,)j(b)236 1319 y(...)224 b(return)44 b(0)236 1410 y(...)236 1502 y(>>>)0 1788 y FN(Create)20 b(the)h(C)g(callable)f(callback:)236 2027 y FA(>>>)45 b(cmp_func)e(=)i(CMPFUNC\(py_cmp_func\))236 2118 y(>>>)0 2404 y FN(And)20 b(we')l(re)f(ready)g(to)i(go:)236 2643 y FA(>>>)45 b(qsort\(ia,)e(len\(ia\),)g(sizeof\(c_int\),)g (cmp_func\))g(#)i(doctest:)e(+WINDOWS)236 2734 y(py_cmp_func)g (<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g(<ctypes.LP_c_long)e (object)i(at)g(0x00...>)236 2825 y(py_cmp_func)f(<ctypes.LP_c_long)f (object)i(at)g(0x00...>)g(<ctypes.LP_c_long)e(object)i(at)g(0x00...>) 236 2917 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3008 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3099 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3190 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3282 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3373 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3464 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3556 y(py_cmp_func)f(<ctypes.LP_c_long)f(object)i(at)g(0x00...>)g (<ctypes.LP_c_long)e(object)i(at)g(0x00...>)236 3647 y(>>>)0 3934 y FN(W)-7 b(e)21 b(kno)n(w)f(ho)n(w)f(to)h(access)h(the)f (contents)g(of)g(a)g(pointer)m(,)f(so)h(lets)i(rede\002ne)d(our)g (callback:)236 4172 y FA(>>>)45 b(def)f(py_cmp_func\(a,)e(b\):)236 4263 y(...)224 b(print)44 b("py_cmp_func",)e(a[0],)i(b[0])236 4354 y(...)224 b(return)44 b(0)236 4446 y(...)236 4537 y(>>>)h(cmp_func)e(=)i(CMPFUNC\(py_cmp_func\))236 4628 y(>>>)0 4915 y FN(Here)20 b(is)h(what)f(we)h(get)f(on)g(W)m(indo)n(ws:) p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(517)p eop end %%Page: 518 530 TeXDict begin 518 529 bop 236 174 a FA(>>>)45 b(qsort\(ia,)e (len\(ia\),)g(sizeof\(c_int\),)g(cmp_func\))g(#)i(doctest:)e(+WINDOWS) 236 266 y(py_cmp_func)g(7)i(1)236 357 y(py_cmp_func)e(33)i(1)236 448 y(py_cmp_func)e(99)i(1)236 540 y(py_cmp_func)e(5)i(1)236 631 y(py_cmp_func)e(7)i(5)236 722 y(py_cmp_func)e(33)i(5)236 814 y(py_cmp_func)e(99)i(5)236 905 y(py_cmp_func)e(7)i(99)236 996 y(py_cmp_func)e(33)i(99)236 1088 y(py_cmp_func)e(7)i(33)236 1179 y(>>>)0 1465 y FN(It)20 b(is)i(funn)o(y)c(to)i(see)h(that)f(on)g (linux)f(the)i(sort)f(function)e(seems)j(to)f(w)o(ork)g(much)f(more)h (ef)n(\002cient,)f(it)i(is)g(doing)e(less)i(comparisons:)236 1704 y FA(>>>)45 b(qsort\(ia,)e(len\(ia\),)g(sizeof\(c_int\),)g (cmp_func\))g(#)i(doctest:)e(+LINUX)236 1795 y(py_cmp_func)g(5)i(1)236 1886 y(py_cmp_func)e(33)i(99)236 1978 y(py_cmp_func)e(7)i(33)236 2069 y(py_cmp_func)e(5)i(7)236 2160 y(py_cmp_func)e(1)i(7)236 2252 y(>>>)0 2538 y FN(Ah,)20 b(we')l(re)g(nearly)f(done!)24 b(The)19 b(last)i(step)g(is)g(to)f(actually)g(compare)f(the)h(tw)o(o)g (items)h(and)f(return)f(a)h(useful)g(result:)236 2776 y FA(>>>)45 b(def)f(py_cmp_func\(a,)e(b\):)236 2868 y(...)224 b(print)44 b("py_cmp_func",)e(a[0],)i(b[0])236 2959 y(...)224 b(return)44 b(a[0])g(-)h(b[0])236 3050 y(...)236 3142 y(>>>)0 3428 y FN(Final)20 b(run)g(on)g(W)m(indo)n(ws:)236 3666 y FA(>>>)45 b(qsort\(ia,)e(len\(ia\),)g(sizeof\(c_int\),)g (CMPFUNC\(py_cmp_func\)\))e(#)k(doctest:)e(+WINDOWS)236 3758 y(py_cmp_func)g(33)i(7)236 3849 y(py_cmp_func)e(99)i(33)236 3940 y(py_cmp_func)e(5)i(99)236 4032 y(py_cmp_func)e(1)i(99)236 4123 y(py_cmp_func)e(33)i(7)236 4214 y(py_cmp_func)e(1)i(33)236 4306 y(py_cmp_func)e(5)i(33)236 4397 y(py_cmp_func)e(5)i(7)236 4488 y(py_cmp_func)e(1)i(7)236 4580 y(py_cmp_func)e(5)i(1)236 4671 y(>>>)0 4957 y FN(and)20 b(on)f(Linux:)p 0 5549 3901 4 v 0 5649 a FI(518)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 519 531 TeXDict begin 519 530 bop 236 174 a FA(>>>)45 b(qsort\(ia,)e (len\(ia\),)g(sizeof\(c_int\),)g(CMPFUNC\(py_cmp_func\)\))e(#)k (doctest:)e(+LINUX)236 266 y(py_cmp_func)g(5)i(1)236 357 y(py_cmp_func)e(33)i(99)236 448 y(py_cmp_func)e(7)i(33)236 540 y(py_cmp_func)e(1)i(7)236 631 y(py_cmp_func)e(5)i(7)236 722 y(>>>)0 1009 y FN(It)20 b(is)i(quite)d(interesting)h(to)g(see)h (that)f(the)g(W)m(indo)n(ws)g FJ(qsort)g FN(function)e(needs)i(more)f (comparisons)g(than)g(the)i(linux)e(v)o(ersion!)0 1156 y(As)i(we)g(can)f(easily)g(check,)f(our)h(array)f(is)i(sorted)f(no)n (w:)236 1394 y FA(>>>)45 b(for)f(i)h(in)f(ia:)g(print)g(i,)236 1485 y(...)236 1577 y(1)h(5)g(7)f(33)h(99)236 1668 y(>>>)0 1955 y FL(Important)20 b(note)g(f)n(or)f(callback)h(functions:)0 2102 y FN(Mak)o(e)g(sure)h(you)f(k)o(eep)g(references)f(to)i(CFUNCTYPE) h(objects)e(as)i(long)d(as)j(the)o(y)e(are)g(used)h(from)f(C)h(code.)26 b FJ(ctypes)20 b FN(doesn')o(t,)f(and)0 2201 y(if)h(you)g(don')o(t,)e (the)o(y)i(may)f(be)h(garbage)e(collected,)i(crashing)f(your)g(program) f(when)h(a)i(callback)e(is)i(made.)0 2470 y FI(Accessing)h(v)n(alues)h (e)n(xpor)s(ted)g(from)g(dlls)0 2673 y FN(Sometimes,)i(a)g(dll)f(not)g (only)g(e)o(xports)f(functions,)h(it)h(also)g(e)o(xports)e(v)n (ariables.)37 b(An)24 b(e)o(xample)f(in)i(the)g(Python)e(library)g (itself)i(is)h(the)0 2772 y FJ(Py_OptimizeFlag)p FN(,)18 b(an)i(inte)o(ger)f(set)i(to)f(0,)g(1,)g(or)g(2,)g(depending)e(on)i (the)g FL(-O)g FN(or)g FL(-OO)f FN(\003ag)i(gi)n(v)o(en)e(on)g (startup.)0 2919 y FJ(ctypes)26 b FN(can)g(access)g(v)n(alues)g(lik)o (e)h(this)g(with)f(the)g FJ(in_dll)g FN(class)h(methods)e(of)h(the)g (type.)43 b FK(pythonapi)24 b FN(s)j(a)f(prede\002ned)f(symbol)0 3019 y(gi)n(ving)19 b(access)i(to)f(the)g(Python)f(C)i(api:)236 3257 y FA(>>>)45 b(opt_flag)e(=)i(c_int.in_dll\(pythonapi,)c ("Py_OptimizeFlag"\))236 3348 y(>>>)k(print)f(opt_flag)236 3440 y(c_long\(0\))236 3531 y(>>>)0 3818 y FN(If)24 b(the)h (interpreter)e(w)o(ould)h(ha)n(v)o(e)g(been)g(started)g(with)h FL(-O)p FN(,)f(the)h(sample)f(w)o(ould)g(ha)n(v)o(e)g(printed)f FJ(c_long\(1\))p FN(,)i(or)f FJ(c_long\(2\))f FN(if)0 3918 y FL(-OO)d FN(w)o(ould)f(ha)n(v)o(e)h(been)f(speci\002ed.)0 4065 y(An)34 b(e)o(xtended)f(e)o(xample)f(which)i(also)h(demonstrates)e (the)h(use)g(of)g(pointers)g(accesses)h(the)f FJ (PyImport_FrozenModules)0 4164 y FN(pointer)19 b(e)o(xported)f(by)i (Python.)0 4311 y(Quoting)d(the)i(Python)f(docs:)24 b FK(This)c(pointer)e(is)h(initialized)g(to)g(point)f(to)h(an)f(arr)o(ay) h(of)g(\223struct)p 2721 4311 25 4 v 49 w(fr)l(ozen\223)g(r)m(ecor)m (ds,)g(terminated)f(by)h(one)0 4411 y(whose)g(member)o(s)g(ar)m(e)f (all)h(NULL)h(or)f(zer)l(o.)25 b(When)18 b(a)g(fr)l(ozen)h(module)f(is) h(imported,)f(it)h(is)h(sear)m(c)o(hed)d(in)i(this)g(table)o(.)24 b(Thir)m(d-party)17 b(code)0 4510 y(could)i(play)h(tric)n(ks)i(with)e (this)h(to)f(pr)l(o)o(vide)g(a)g(dynamically)f(cr)m(eated)h(collection) f(of)h(fr)l(ozen)h(modules.)0 4657 y FN(So)j(manipulating)d(this)j (pointer)e(could)h(e)n(v)o(en)f(pro)o(v)o(e)f(useful.)35 b(T)-7 b(o)23 b(restrict)h(the)f(e)o(xample)f(size,)j(we)f(sho)n(w)f (only)g(ho)n(w)f(this)i(table)g(can)0 4757 y(be)c(read)g(with)g FJ(ctypes)p FN(:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g (f)n(or)e(Python.)1736 b(519)p eop end %%Page: 520 532 TeXDict begin 520 531 bop 236 174 a FA(>>>)45 b(from)f(ctypes)g(import) 1267 187 y(*)236 266 y(>>>)236 357 y(>>>)h(class)f (struct_frozen\(Structure\):)236 448 y(...)224 b(_fields_)43 b(=)i([\("name",)e(c_char_p\),)236 540 y(...)762 b(\("code",)43 b(POINTER\(c_ubyte\)\),)236 631 y(...)762 b(\("size",)43 b(c_int\)])236 722 y(...)236 814 y(>>>)0 1100 y FN(W)-7 b(e)21 b(ha)n(v)o(e)f(de\002ned)f(the)h FJ(struct)49 b(_frozen)19 b FN(data)i(type,)e(so)i(we)f(can)g(get)g(the)h(pointer)d (to)j(the)f(table:)236 1338 y FA(>>>)45 b(FrozenTable)e(=)h (POINTER\(struct_frozen\))236 1430 y(>>>)h(table)f(=)g (FrozenTable.in_dll\(pythonapi,)c("PyImport_FrozenModules"\))236 1521 y(>>>)0 1807 y FN(Since)26 b FJ(table)g FN(is)h(a)f FJ(pointer)g FN(to)g(the)g(array)f(of)h FJ(struct_frozen)e FN(records,)j(we)f(can)g(iterate)g(o)o(v)o(er)f(it,)j(b)n(ut)e(we)g (just)h(ha)n(v)o(e)e(to)0 1907 y(mak)o(e)g(sure)h(that)f(our)g(loop)g (terminates,)h(because)f(pointers)g(ha)n(v)o(e)g(no)g(size.)42 b(Sooner)25 b(or)g(later)h(it)g(w)o(ould)f(probably)e(crash)j(with)g (an)0 2007 y(access)21 b(violation)e(or)h(whate)n(v)o(er)m(,)e(so)i (it')-5 b(s)22 b(better)d(to)i(break)e(out)h(of)g(the)g(loop)f(when)h (we)g(hit)h(the)f(NULL)g(entry:)236 2245 y FA(>>>)45 b(for)f(item)g(in)h(table:)236 2336 y(...)179 b(print)44 b(item.name,)f(item.size)236 2428 y(...)179 b(if)45 b(item.name)e(is)h (None:)236 2519 y(...)358 b(break)236 2610 y(...)236 2702 y(__hello__)44 b(104)236 2793 y(__phello__)f(-104)236 2884 y(__phello__.spam)g(104)236 2976 y(None)h(0)236 3067 y(>>>)0 3353 y FN(The)24 b(f)o(act)h(that)g(standard)f(Python)f (has)i(a)g(frozen)e(module)h(and)g(a)h(frozen)e(package)h(\(indicated)f (by)h(the)h(ne)o(gati)n(v)o(e)d(size)k(member\))d(is)0 3453 y(not)d(wellkno)n(wn,)e(it)j(is)g(only)f(used)g(for)f(testing.)25 b(T)m(ry)20 b(it)h(out)f(with)g FJ(import)49 b(__hello__)19 b FN(for)g(e)o(xample.)0 3721 y FI(Sur)r(pr)q(ises)0 3924 y FN(There)g(are)h(some)g(edges)g(in)h FJ(ctypes)e FN(where)h(you)f(may)h(be)g(e)o(xpect)f(something)g(else)i(than)e(what) i(actually)e(happens.)0 4071 y(Consider)h(the)g(follo)n(wing)e(e)o (xample:)p 0 5549 3901 4 v 0 5649 a FI(520)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 521 533 TeXDict begin 521 532 bop 236 174 a FA(>>>)45 b(from)f(ctypes)g(import) 1267 187 y(*)236 266 y(>>>)h(class)f(POINT\(Structure\):)236 357 y(...)224 b(_fields_)43 b(=)i(\("x",)f(c_int\),)g(\("y",)g(c_int\)) 236 448 y(...)236 540 y(>>>)h(class)f(RECT\(Structure\):)236 631 y(...)224 b(_fields_)43 b(=)i(\("a",)f(POINT\),)g(\("b",)g(POINT\)) 236 722 y(...)236 814 y(>>>)h(p1)f(=)h(POINT\(1,)e(2\))236 905 y(>>>)i(p2)f(=)h(POINT\(3,)e(4\))236 996 y(>>>)i(rc)f(=)h (RECT\(p1,)e(p2\))236 1088 y(>>>)i(print)f(rc.a.x,)f(rc.a.y,)h(rc.b.x,) g(rc.b.y)236 1179 y(1)h(2)g(3)f(4)236 1270 y(>>>)h(#)f(now)h(swap)f (the)g(two)g(points)236 1362 y(>>>)h(rc.a,)f(rc.b)g(=)g(rc.b,)g(rc.a) 236 1453 y(>>>)h(print)f(rc.a.x,)f(rc.a.y,)h(rc.b.x,)g(rc.b.y)236 1544 y(3)h(4)g(3)f(4)236 1636 y(>>>)0 1922 y FN(Hm.)28 b(W)-7 b(e)22 b(certainly)e(e)o(xpected)f(the)j(last)g(statement)e(to)i (print)e FJ(3)50 b(4)f(1)h(2)p FN(.)28 b(What)21 b(happended?)k(Here)c (are)g(the)g(steps)h(of)f(the)g FJ(rc.a,)0 2022 y(rc.b)49 b(=)h(rc.b,)f(rc.a)20 b FN(line)g(abo)o(v)o(e:)236 2260 y FA(>>>)45 b(temp0,)e(temp1)h(=)h(rc.b,)f(rc.a)236 2351 y(>>>)h(rc.a)f(=)g(temp0)236 2443 y(>>>)h(rc.b)f(=)g(temp1)236 2534 y(>>>)0 2820 y FN(Note)20 b(that)h FJ(temp0)f FN(and)g FJ(temp1)g FN(are)g(objects)g(still)i(using)e(the)g(internal)g(b)n(uf)n (fer)f(of)h(the)h FJ(rc)f FN(object)g(abo)o(v)o(e.)k(So)d(e)o(x)o (ecuting)d FJ(rc.a)49 b(=)0 2920 y(temp0)21 b FN(copies)h(the)f(b)n(uf) n(fer)g(contents)g(of)g FJ(temp0)g FN(into)h FJ(rc)g FN(')-5 b(s)22 b(b)n(uf)n(fer)-5 b(.)29 b(This,)22 b(in)g(turn,)f (changes)f(the)i(contents)f(of)g FJ(temp1)p FN(.)30 b(So,)22 b(the)0 3020 y(last)f(assignment)e FJ(rc.b)49 b(=)h(temp1)p FN(,)20 b(doesn')o(t)e(ha)n(v)o(e)i(the)g(e)o(xpected)f(ef)n(fect.)0 3166 y(K)n(eep)29 b(in)g(mind)f(that)i(retrie)n(ving)d(subobjects)h (from)g(Structure,)i(Unions,)h(and)d(Arrays)h(doesn')o(t)f FK(copy)g FN(the)h(subobject,)h(instead)f(it)0 3266 y(retrie)n(v)o(es) 19 b(a)i(wrapper)e(object)g(accessing)h(the)g(root-object')-5 b(s)19 b(underlying)e(b)n(uf)n(fer)-5 b(.)0 3413 y(Another)19 b(e)o(xample)g(that)h(may)g(beha)n(v)o(e)f(dif)n(ferent)f(from)h(what)h (one)g(w)o(ould)g(e)o(xpect)f(is)i(this:)236 3560 y FA(>>>)45 b(s)f(=)h(c_char_p\(\))236 3651 y(>>>)g(s.value)e(=)i("abc)f(def)g (ghi")236 3742 y(>>>)h(s.value)236 3834 y('abc)f(def)h(ghi')236 3925 y(>>>)g(s.value)e(is)i(s.value)236 4016 y(False)236 4108 y(>>>)0 4394 y FN(Why)23 b(is)h(it)g(printing)d FJ(False)p FN(?)34 b(ctypes)23 b(instances)g(are)g(objects)g (containing)e(a)j(memory)d(block)i(plus)g(some)g(descriptors)f (accessing)0 4494 y(the)g(contents)g(of)g(the)g(memory)-5 b(.)29 b(Storing)21 b(a)i(Python)e(object)g(in)i(the)f(memory)e(block)i (does)g(not)f(store)i(the)f(object)g(itself,)h(instead)f(the)0 4594 y FJ(contents)d FN(of)h(the)g(object)g(is)h(stored.)k(Accessing)20 b(the)g(contents)f(again)g(constructs)h(a)g(ne)n(w)g(Python)f(each)h (time!)0 4862 y FI(V)-6 b(ar)q(iab)n(le-siz)o(ed)25 b(data)e(types)0 5065 y FJ(ctypes)d FN(pro)o(vides)e(some)i(support)f(for)g(v)n (ariable-sized)g(arrays)g(and)h(structures)g(\(this)g(w)o(as)h(added)e (in)h(v)o(ersion)f(0.9.9.7\).)0 5212 y(The)24 b FJ(resize)g FN(function)f(can)i(be)f(used)g(to)h(resize)g(the)g(memory)e(b)n(uf)n (fer)g(of)h(an)h(e)o(xisting)f(ctypes)g(object.)37 b(The)25 b(function)e(tak)o(es)i(the)0 5311 y(object)d(as)i(\002rst)f(ar)o (gument,)e(and)h(the)h(requested)e(size)j(in)f(bytes)f(as)i(the)f (second)e(ar)o(gument.)31 b(The)22 b(memory)f(block)h(cannot)f(be)i (made)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(521)p eop end %%Page: 522 534 TeXDict begin 522 533 bop 0 83 a FN(smaller)20 b(than)g(the)g(natural)f (memory)g(block)g(speci\002ed)h(by)g(the)g(objects)g(type,)f(a)i FJ(ValueError)e FN(is)i(raised)f(if)h(this)f(is)h(tried:)236 321 y FA(>>>)45 b(short_array)e(=)h(\(c_short)1447 334 y(*)1536 321 y(4\)\(\))236 413 y(>>>)h(print)f(sizeof\(short_array\)) 236 504 y(8)236 595 y(>>>)h(resize\(short_array,)c(4\))236 687 y(Traceback)j(\(most)g(recent)f(call)i(last\):)416 778 y(...)236 869 y(ValueError:)e(minimum)h(size)g(is)h(8)236 960 y(>>>)g(resize\(short_array,)c(32\))236 1052 y(>>>)k (sizeof\(short_array\))236 1143 y(32)236 1234 y(>>>)g (sizeof\(type\(short_array\)\))236 1326 y(8)236 1417 y(>>>)0 1704 y FN(This)25 b(is)g(nice)f(and)g(\002ne,)h(b)n(ut)f(ho)n (w)g(w)o(ould)g(one)g(access)h(the)f(additional)f(elements)h(contained) f(in)h(this)h(array?)37 b(Since)24 b(the)h(type)e(still)0 1803 y(only)c(kno)n(ws)h(about)f(4)h(elements,)g(we)h(get)f(errors)f (accessing)h(other)f(elements:)236 2041 y FA(>>>)45 b(short_array[:]) 236 2133 y([0,)g(0,)f(0,)h(0])236 2224 y(>>>)g(short_array[7])236 2315 y(Traceback)f(\(most)g(recent)f(call)i(last\):)416 2407 y(...)236 2498 y(IndexError:)e(invalid)h(index)236 2589 y(>>>)0 2876 y FN(Another)17 b(w)o(ay)i(to)g(use)g(v)n (ariable-sized)e(data)i(types)g(with)g FJ(ctypes)f FN(is)i(to)f(use)g (the)g(dynamic)e(nature)h(of)h(Python,)e(and)i(\(re-\)de\002ne)e(the)0 2976 y(data)j(type)g(after)g(the)g(required)e(size)j(is)g(already)e (kno)n(wn,)g(on)g(a)i(case)g(by)f(case)g(basis.)0 3244 y FI(Bugs)o(,)j(T)-10 b(oDo)23 b(and)h(non-implemented)h(things)0 3447 y FN(Enumeration)18 b(types)i(are)g(not)g(implemented.)j(Y)-9 b(ou)19 b(can)h(do)g(it)h(easily)f(yourself,)f(using)h FJ(c_int)f FN(as)i(the)g(base)f(class.)0 3594 y FJ(long)49 b(double)20 b FN(is)h(not)f(implemented.)0 3878 y Fv(14.14.2)101 b(ctypes)28 b(ref)m(erence)0 4081 y FI(Finding)c(shared)f(libr)o(ar)q (ies)0 4284 y FN(When)28 b(programming)c(in)29 b(a)f(compiled)f (language,)h(shared)f(libraries)h(are)g(accessed)g(when)f (compiling/linking)e(a)j(program,)g(and)0 4384 y(when)20 b(the)g(program)e(is)j(run.)0 4531 y(The)26 b(purpose)e(of)i(the)g FJ(find_library)e FN(function)g(is)j(to)g(locate)e(a)i(library)e(in)h (a)g(w)o(ay)g(similar)h(to)f(what)g(the)g(compiler)f(does)g(\(on)0 4630 y(platforms)20 b(with)h(se)n(v)o(eral)f(v)o(ersions)g(of)h(a)h (shared)e(library)g(the)h(most)g(recent)f(should)g(be)h(loaded\),)f (while)h(the)g(ctypes)f(library)g(loaders)0 4730 y(act)h(lik)o(e)f (when)g(a)g(program)e(is)j(run,)f(and)f(call)i(the)f(runtime)f(loader)g (directly)-5 b(.)0 4877 y(The)20 b FJ(ctypes.util)f FN(module)f(pro)o (vides)h(a)h(function)f(which)h(can)g(help)f(to)i(determine)d(the)j (library)e(to)h(load.)0 5024 y FD(find_library\(name\))208 5123 y FN(T)m(ry)e(to)g(\002nd)h(a)g(library)e(and)h(return)g(a)h (pathname.)j FK(name)c FN(is)i(the)e(library)g(name)g(without)g(an)o(y) f(pre\002x)h(lik)o(e)h FK(lib)p FN(,)g(suf)n(\002x)f(lik)o(e)h FJ(.so)p FN(,)208 5223 y FJ(.dylib)26 b FN(or)g(v)o(ersion)f(number)g (\(this)h(is)i(the)e(form)g(used)g(for)g(the)h(posix)f(link)o(er)g (option)f FL(-l)p FN(\).)44 b(If)26 b(no)g(library)g(can)g(be)h(found,) 208 5323 y(returns)19 b FJ(None)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(522)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 523 535 TeXDict begin 523 534 bop 0 83 a FN(The)20 b(e)o(xact)g(functionality)e (is)j(system)f(dependend.)0 230 y(On)i(Linux,)e FJ(find_library)g FN(tries)i(to)g(run)f(e)o(xternal)g(programs)e(\(/sbin/ldcon\002g,)h (gcc,)i(and)f(objdump\))e(to)j(\002nd)f(the)h(library)e(\002le.)0 330 y(It)g(returns)g(the)g(\002lename)g(of)g(the)g(library)f(\002le.)25 b(Here)c(are)f(sone)g(e)o(xamples:)236 568 y FA(>>>)45 b(from)f(ctypes.util)f(import)h(find_library)236 659 y(>>>)h(find_library\("m"\))236 750 y('libm.so.6')236 842 y(>>>)g(find_library\("c"\))236 933 y('libc.so.6')236 1024 y(>>>)g(find_library\("bz2"\))236 1116 y('libbz2.so.1.0')236 1207 y(>>>)0 1493 y FN(On)19 b(OS)i(X,)e FJ(find_library)f FN(tries)i(se)n(v)o(eral)f(prede\002ned)e(naming)h(schemes)h(and)g (paths)g(to)h(locate)f(the)h(library)-5 b(,)17 b(and)i(returns)g(a)h (full)0 1593 y(pathname)f(if)h(successfull:)236 1831 y FA(>>>)45 b(from)f(ctypes.util)f(import)h(find_library)236 1923 y(>>>)h(find_library\("c"\))236 2014 y('/usr/lib/libc.dylib')236 2105 y(>>>)g(find_library\("m"\))236 2197 y('/usr/lib/libm.dylib')236 2288 y(>>>)g(find_library\("bz2"\))236 2379 y('/usr/lib/libbz2.dylib') 236 2471 y(>>>)g(find_library\("AGL"\))236 2562 y ('/System/Library/Frameworks/AGL.framewor)o(k/AGL')236 2653 y(>>>)0 2940 y FN(On)21 b(W)m(indo)n(ws,)f FJ(find_library)f FN(searches)i(along)e(the)i(system)g(search)f(path,)h(and)f(returns)g (the)h(full)f(pathname,)f(b)n(ut)i(since)g(there)0 3039 y(is)g(no)f(prede\002ned)e(naming)h(scheme)h(a)g(call)h(lik)o(e)f FJ(find_library\("c"\))e FN(will)j(f)o(ail)f(and)g(return)f FJ(None)p FN(.)0 3186 y(If)g(wrapping)e(a)i(shared)g(library)f(with)h FJ(ctypes)p FN(,)f(it)i FK(may)f FN(be)g(better)f(to)i(determine)d(the) i(shared)f(library)g(name)h(at)g(de)n(v)o(elopment)d(type,)0 3286 y(and)k(hardcode)e(that)i(into)g(the)g(wrapper)f(module)g(instead) h(of)g(using)f FJ(find_library)g FN(to)h(locate)g(the)g(library)f(at)i (runtime.)0 3554 y FI(Loading)j(shared)f(libr)o(ar)q(ies)0 3757 y FN(There)15 b(are)i(se)n(v)o(eral)e(w)o(ays)i(to)f(loaded)g (shared)f(libraries)h(into)g(the)g(Python)g(process.)23 b(One)16 b(w)o(ay)g(is)i(to)e(instantiate)g(one)g(of)g(the)g(follo)n (wing)0 3857 y(classes:)0 4004 y FL(class)21 b FD(CDLL)p FJ(\()p FK(name)o(,)d(mode=DEF)-10 b(A)l(UL)n(T)p 1247 4004 25 4 v 29 w(MODE,)20 b(handle=None)p FJ(\))208 4103 y FN(Instances)i(of)h(this)g(class)h(represent)e(loaded)g(shared)h (libraries.)33 b(Functions)22 b(in)h(these)g(libraries)g(use)g(the)g (standard)f(C)i(calling)208 4203 y(con)m(v)o(ention,)16 b(and)k(are)g(assumed)g(to)g(return)f FJ(int)p FN(.)0 4350 y FL(class)i FD(OleDLL)p FJ(\()p FK(name)o(,)d(mode=DEF)-10 b(A)l(UL)n(T)p 1347 4350 V 29 w(MODE,)20 b(handle=None)p FJ(\))208 4449 y FN(W)m(indo)n(ws)30 b(only:)45 b(Instances)30 b(of)g(this)i(class)f(represent)f(loaded)f(shared)h(libraries,)j (functions)c(in)i(these)f(libraries)h(use)g(the)208 4549 y FJ(stdcall)f FN(calling)g(con)m(v)o(ention,)g(and)g(are)h(assumed)f (to)h(return)e(the)i(windo)n(ws)f(speci\002c)h FJ(HRESULT)f FN(code.)55 b FJ(HRESULT)208 4649 y FN(v)n(alues)26 b(contain)h (information)e(specifying)g(whether)h(the)i(function)d(call)j(f)o (ailed)f(or)g(succeeded,)h(together)d(with)j(additional)208 4748 y(error)19 b(code.)24 b(If)c(the)g(return)f(v)n(alue)h(signals)g (a)h(f)o(ailure,)e(an)h FJ(WindowsError)f FN(is)i(automatically)d (raised.)0 4895 y FL(class)j FD(WinDLL)p FJ(\()p FK(name)o(,)d (mode=DEF)-10 b(A)l(UL)n(T)p 1347 4895 V 29 w(MODE,)20 b(handle=None)p FJ(\))208 4995 y FN(W)m(indo)n(ws)30 b(only:)45 b(Instances)30 b(of)g(this)i(class)f(represent)f(loaded)f (shared)h(libraries,)j(functions)c(in)i(these)f(libraries)h(use)g(the) 208 5094 y FJ(stdcall)19 b FN(calling)h(con)m(v)o(ention,)d(and)i(are)h (assumed)g(to)g(return)f FJ(int)i FN(by)e(def)o(ault.)208 5227 y(On)k(W)m(indo)n(ws)g(CE)h(only)f(the)g(standard)g(calling)g(con) m(v)o(ention)d(is)25 b(used,)f(for)e(con)m(v)o(enience)f(the)i FJ(WinDLL)g FN(and)g FJ(OleDLL)g FN(use)208 5327 y(the)d(standard)f (calling)h(con)m(v)o(ention)d(on)i(this)i(platform.)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(523)p eop end %%Page: 524 536 TeXDict begin 524 535 bop 0 83 a FN(The)20 b(Python)f(GIL)h(is)h (released)f(before)f(calling)g(an)o(y)h(function)e(e)o(xported)g(by)i (these)g(libraries,)g(and)g(reaquired)e(afterw)o(ards.)0 230 y FL(class)j FD(PyDLL)p FJ(\()p FK(name)o(,)d(mode=DEF)-10 b(A)l(UL)n(T)p 1297 230 25 4 v 29 w(MODE,)20 b(handle=None)p FJ(\))208 330 y FN(Instances)c(of)g(this)h(class)h(beha)n(v)o(e)d(lik)o (e)i FJ(CDLL)f FN(instances,)h(e)o(xcept)f(that)g(the)h(Python)e(GIL)i (is)g FK(not)g FN(released)f(during)f(the)h(function)208 429 y(call,)j(and)g(after)g(the)h(function)e(e)o(x)o(ecution)f(the)j (Python)e(error)g(\003ag)i(is)g(check)o(ed.)k(If)19 b(the)h(error)e (\003ag)i(is)g(set,)g(a)g(Python)e(e)o(xception)208 529 y(is)j(raised.)208 662 y(Thus,)e(this)i(is)g(only)e(useful)h(to)g(call) h(Python)e(C)i(api)f(functions)f(directly)-5 b(.)0 808 y(All)25 b(these)g(classes)h(can)e(be)h(instantiated)f(by)g(calling)h (them)f(with)h(at)g(least)g(one)f(ar)o(gument,)g(the)g(pathname)f(of)i (the)f(shared)g(library)-5 b(.)0 908 y(If)23 b(you)g(ha)n(v)o(e)f(an)i (e)o(xisting)e(handle)g(to)i(an)f(already)f(loaded)h(shard)f(library)-5 b(,)23 b(it)h(can)f(be)g(passed)g(as)h(the)g FJ(handle)e FN(named)h(parameter)m(,)0 1008 y(otherwise)f(the)g(underlying)e (platforms)h FJ(dlopen)h FN(or)g FJ(LoadLibrary)f FN(function)f(is)k (used)e(to)g(load)g(the)h(library)e(into)h(the)g(process,)0 1107 y(and)e(to)g(get)g(a)h(handle)e(to)h(it.)0 1254 y(The)g FK(mode)g FN(parameter)f(can)i(be)f(used)g(to)h(specify)f(ho)n (w)g(the)h(library)e(is)j(loaded.)j(F)o(or)20 b(details,)h(consult)f (the)g FJ(dlopen\(3\))g FN(manpage,)0 1354 y(on)g(W)m(indo)n(ws,)f FK(mode)h FN(is)h(ignored.)0 1501 y FD(RTLD_GLOBAL)208 1600 y FN(Flag)f(to)g(use)h(as)g FK(mode)e FN(parameter)-5 b(.)24 b(On)c(platforms)f(where)h(this)h(\003ag)f(is)h(not)f(a)n(v)n (ailable,)f(it)i(is)g(de\002ned)e(as)i(the)g(inte)o(ger)e(zero.)0 1747 y FD(RTLD_LOCAL)208 1847 y FN(Flag)h(to)g(use)h(as)g FK(mode)e FN(parameter)-5 b(.)24 b(On)c(platforms)f(where)h(this)h(is)g (not)e(a)n(v)n(ailable,)h(it)h(is)g(the)f(same)h(as)f FK(RTLD)p 3377 1847 V 30 w(GLOB)n(AL)p FN(.)0 1994 y FD(DEFAULT_MODE)208 2093 y FN(The)i(def)o(ault)f(mode)h(which)g(is)h (used)f(to)h(load)e(shared)h(libraries.)31 b(On)23 b(OSX)g(10.3,)e (this)i(is)g FK(RTLD)p 3049 2093 V 30 w(GLOB)n(AL)p FN(,)g(otherwise)f (it)h(is)208 2193 y(the)d(same)g(as)h FK(RTLD)p 819 2193 V 30 w(LOCAL)p FN(.)0 2340 y(Instances)26 b(of)h(these)g(classes)h(ha)n (v)o(e)f(no)f(public)h(methods,)g(ho)n(we)n(v)o(er)e FJ(__getattr__)h FN(and)g FJ(__getitem__)f FN(ha)n(v)o(e)i(special)g (be-)0 2439 y(ha)n(viour:)41 b(functions)27 b(e)o(xported)f(by)i(the)h (shared)f(library)f(can)i(be)f(accessed)h(as)g(attrib)n(utes)g(of)f(by) g(inde)o(x.)49 b(Please)30 b(note)e(that)g(both)0 2539 y FJ(__getattr__)18 b FN(and)h FJ(__getitem__)f FN(cache)h(their)g (result,)g(so)h(calling)f(them)g(repeatedly)f(returns)h(the)g(same)h (object)f(each)g(time.)0 2686 y(The)i(follo)n(wing)e(public)h(attrib)n (utes)h(are)f(a)n(v)n(ailable,)h(their)f(name)h(starts)g(with)g(an)g (underscore)e(to)i(not)f(clash)i(with)f(e)o(xported)d(function)0 2786 y(names:)0 2932 y FD(_handle)208 3032 y FN(The)h(system)i(handle)e (used)h(to)g(access)h(the)f(library)-5 b(.)0 3179 y FD(_name)208 3279 y FN(The)19 b(name)h(of)g(the)g(library)f(passed)h(in)h(the)f (contructor)-5 b(.)0 3425 y(Shared)47 b(libraries)g(can)g(also)h(be)f (loaded)f(by)h(using)g(one)g(of)g(the)h(pref)o(abricated)d(objects,)54 b(which)47 b(are)g(instances)g(of)h(the)0 3525 y FJ(LibraryLoader)27 b FN(class,)k(either)e(by)f(calling)g(the)h FJ(LoadLibrary)e FN(method,)j(or)e(by)h(retrie)n(ving)e(the)h(library)g(as)h(attrib)n (ute)g(of)0 3625 y(the)20 b(loader)f(instance.)0 3772 y FL(class)i FD(LibraryLoader)p FJ(\()p FK(dlltype)p FJ(\))208 3871 y FN(Class)f(which)e(loads)g(shared)g(libraries.)24 b FJ(dlltype)18 b FN(should)f(be)i(one)f(of)g(the)h FJ(CDLL)p FN(,)f FJ(PyDLL)p FN(,)g FJ(WinDLL)p FN(,)g(or)g FJ(OleDLL)g FN(types.)208 4004 y FJ(__getattr__)g FN(has)j(special)g(beha)n(viour:) i(It)e(allo)n(ws)g(to)f(load)g(a)h(shared)f(library)f(by)h(accessing)g (it)h(as)h(attrib)n(ute)e(of)g(a)h(library)208 4104 y(loader)e (instance.)24 b(The)c(result)g(is)i(cached,)d(so)h(repeated)f(attrib)n (ute)h(accesses)h(return)e(the)h(same)g(library)f(each)h(time.)0 4251 y FD(LoadLibrary)p FJ(\()p FK(name)p FJ(\))208 4350 y FN(Load)f(a)i(shared)e(library)g(into)h(the)g(process)g(and)g(return) f(it.)25 b(This)c(method)d(al)o(w)o(ays)j(returns)e(a)i(ne)n(w)f (instance)g(of)g(the)g(library)-5 b(.)0 4497 y(These)20 b(pref)o(abricated)e(library)h(loaders)g(are)i(a)n(v)n(ailable:)0 4644 y FD(cdll)208 4744 y FN(Creates)f FJ(CDLL)g FN(instances.)0 4890 y FD(windll)208 4990 y FN(W)m(indo)n(ws)f(only:)25 b(Creates)20 b FJ(WinDLL)g FN(instances.)0 5137 y FD(oledll)208 5237 y FN(W)m(indo)n(ws)f(only:)25 b(Creates)20 b FJ(OleDLL)g FN(instances.)0 5383 y FD(pydll)p 0 5549 3901 4 v 0 5649 a FI(524)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h (System)f(Ser)r(vices)p eop end %%Page: 525 537 TeXDict begin 525 536 bop 208 83 a FN(Creates)20 b FJ(PyDLL)g FN(instances.)0 230 y(F)o(or)g(accessing)g(the)g(C)h(Python)e(api)h (directly)-5 b(,)19 b(a)i(ready-to-use)c(Python)i(shared)h(library)f (object)h(is)h(a)n(v)n(ailable:)0 377 y FD(pythonapi)208 476 y FN(An)31 b(instance)g(of)f FJ(PyDLL)h FN(that)g(e)o(xposes)g (Python)f(C)i(api)f(functions)f(as)i(attrib)n(utes.)57 b(Note)32 b(that)f(all)h(these)f(functions)f(are)208 576 y(assumed)21 b(to)h(return)f(C)j FJ(int)p FN(,)e(which)g(is)h(of)e (course)h(not)g(al)o(w)o(ays)g(the)g(truth,)g(so)h(you)e(ha)n(v)o(e)g (to)i(assign)f(the)g(correct)f FJ(restype)208 676 y FN(attrib)n(ute)e (to)i(use)f(these)g(functions.)0 940 y FI(F)n(oreign)j(functions)0 1143 y FN(As)i(e)o(xplained)e(in)i(the)f(pre)n(vious)f(section,)i (foreign)e(functions)h(can)g(be)g(accessed)h(as)g(attrib)n(utes)g(of)f (loaded)f(shared)h(libraries.)38 b(The)0 1243 y(function)22 b(objects)i(created)f(in)h(this)g(w)o(ay)g(by)g(def)o(ault)f(accept)g (an)o(y)g(number)f(of)i(ar)o(guments,)e(accept)i(an)o(y)f(ctypes)g (data)h(instances)g(as)0 1342 y(ar)o(guments,)18 b(and)i(return)f(the)h (def)o(ault)f(result)h(type)g(speci\002ed)g(by)g(the)g(library)f (loader)-5 b(.)25 b(The)o(y)19 b(are)h(instances)g(of)g(a)g(pri)n(v)n (ate)g(class:)0 1489 y FL(class)h FD(_FuncPtr)208 1589 y FN(Base)g(class)g(for)e(C)j(callable)d(foreign)g(functions.)0 1736 y(Instances)h(of)g(foreign)e(functions)h(are)h(also)g(C)i (compatible)c(data)i(types;)g(the)o(y)g(represent)f(C)i(function)e (pointers.)0 1883 y(This)h(beha)n(viour)e(can)i(be)h(customized)d(by)i (assigning)g(to)g(special)g(attrib)n(utes)g(of)g(the)h(foreign)d (function)h(object.)0 2030 y FD(restype)208 2129 y FN(Assign)29 b(a)g(ctypes)g(type)f(to)i(specify)e(the)h(result)g(type)g(of)f(the)h (foreign)f(function.)49 b(Use)30 b FJ(None)f FN(for)f FJ(void)h FN(a)h(function)d(not)208 2229 y(returning)18 b(an)o(ything.)208 2358 y(It)26 b(is)h(possible)f(to)g(assign)h(a)f (callable)g(Python)f(object)h(that)g(is)h(not)f(a)h(ctypes)f(type,)h (in)f(this)h(case)f(the)g(function)f(is)i(assumed)208 2457 y(to)e(return)f(a)i(C)g FJ(int)p FN(,)g(and)f(the)h(callable)f (will)h(be)f(called)g(with)g(this)h(inte)o(ger)m(,)f(allo)n(wing)g(to)g (do)g(further)f(processing)g(or)h(error)208 2557 y(checking.)g(Using)20 b(this)h(is)h(deprecated,)d(for)h(more)g(\003e)o(xible)g (postprocessing)f(or)i(error)e(checking)g(use)i(a)g(ctypes)g(data)g (type)f(as)208 2656 y FJ(restype)f FN(and)h(assign)g(a)h(callable)f(to) g(the)g FJ(errcheck)f FN(attrib)n(ute.)0 2803 y FD(argtypes)208 2903 y FN(Assign)29 b(a)h(tuple)f(of)g(ctypes)g(types)g(to)h(specify)f (the)g(ar)o(gument)e(types)i(that)h(the)f(function)f(accepts.)52 b(Functions)29 b(using)g(the)208 3003 y FJ(stdcall)19 b FN(calling)g(con)m(v)o(ention)e(can)j(only)f(be)h(called)g(with)g (the)g(same)h(number)d(of)i(ar)o(guments)e(as)i(the)g(length)g(of)f (this)i(tuple;)208 3102 y(functions)d(using)i(the)g(C)h(calling)f(con)m (v)o(ention)d(accept)j(additional,)f(unspeci\002ed)f(ar)o(guments)h(as) i(well.)208 3231 y(When)27 b(a)h(foreign)e(function)g(is)j(called,)g (each)e(actual)h(ar)o(gument)d(is)k(passed)e(to)h(the)g FJ(from_param)e FN(class)j(method)d(of)i(the)208 3331 y(items)g(in)f(the)h FJ(argtypes)f FN(tuple,)i(this)f(method)e(allo)n (ws)i(to)g(adapt)f(the)h(actual)f(ar)o(gument)e(to)j(an)g(object)f (that)h(the)f(foreign)208 3430 y(function)18 b(accepts.)25 b(F)o(or)20 b(e)o(xample,)f(a)h FJ(c_char_p)g FN(item)g(in)h(the)f FJ(argtypes)f FN(tuple)h(will)h(con)m(v)o(ert)d(a)j(unicode)e(string)h (passed)208 3530 y(as)g(ar)o(gument)e(into)i(an)g(byte)g(string)g (using)g(ctypes)f(con)m(v)o(ersion)f(rules.)208 3659 y(Ne)n(w:)25 b(It)19 b(is)i(no)n(w)e(possible)g(to)h(put)f(items)h(in)g (ar)o(gtypes)d(which)i(are)h(not)f(ctypes)g(types,)g(b)n(ut)h(each)f (item)h(must)f(ha)n(v)o(e)g(a)h FJ(from_-)208 3758 y(param)d FN(method)g(which)h(returns)f(a)h(v)n(alue)g(usable)g(as)h(ar)o(gument) c(\(inte)o(ger)m(,)i(string,)h(ctypes)g(instance\).)23 b(This)18 b(allo)n(ws)h(to)f(de\002ne)208 3858 y(adapters)h(that)h(can) g(adapt)g(custom)f(objects)h(as)h(function)e(parameters.)0 4005 y FD(errcheck)208 4104 y FN(Assign)27 b(a)g(Python)e(function)g (or)i(another)e(callable)i(to)g(this)g(attrib)n(ute.)44 b(The)26 b(callable)h(will)g(be)g(called)g(with)g(three)f(or)g(more)208 4204 y(ar)o(guments:)0 4351 y FD(callable)p FJ(\()p FK(r)m(esult,)19 b(func,)g(ar)m(guments)p FJ(\))208 4450 y(result)g FN(is)i(what)f(the)h (foreign)d(function)h(returns,)g(as)i(speci\002ed)f(by)f(the)i FJ(restype)e FN(attrib)n(ute.)208 4579 y FJ(func)i FN(is)i(the)g (foreign)d(function)g(object)i(itself,)h(this)f(allo)n(ws)h(to)f(reuse) g(the)g(same)g(callable)g(object)f(to)i(check)e(or)h(postprocess)208 4679 y(the)e(results)g(of)g(se)n(v)o(eral)g(functions.)208 4808 y FJ(arguments)e FN(is)i(a)f(tuple)g(containing)e(the)i (parameters)f(originally)g(passed)h(to)g(the)g(function)f(call,)h(this) h(allo)n(ws)f(to)h(specialize)208 4907 y(the)g(beha)n(viour)e(on)i(the) g(ar)o(guments)e(used.)208 5036 y(The)25 b(object)h(that)g(this)h (function)e(returns)g(will)i(be)f(returned)e(from)h(the)i(foreign)d (function)h(call,)j(b)n(ut)e(it)h(can)f(also)g(check)g(the)208 5136 y(result)20 b(v)n(alue)f(and)h(raise)g(an)h(e)o(xception)d(if)i (the)h(foreign)d(function)h(call)h(f)o(ailed.)0 5282 y FL(exception)f FD(ArgumentError\(\))208 5382 y FN(This)h(e)o (xception)e(is)j(raised)f(when)g(a)h(foreign)d(function)h(call)h (cannot)f(con)m(v)o(ert)f(one)i(of)g(the)g(passed)g(ar)o(guments.)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(525)p eop end %%Page: 526 538 TeXDict begin 526 537 bop 0 83 a FI(Function)23 b(prototypes)0 286 y FN(F)o(oreign)h(functions)g(can)i(also)g(be)f(created)g(by)g (instantiating)g(function)f(prototypes.)39 b(Function)24 b(prototypes)g(are)h(similar)h(to)g(func-)0 386 y(tion)g(prototypes)e (in)i(C;)g(the)o(y)g(describe)f(a)h(function)e(\(return)g(type,)j(ar)o (gument)c(types,)k(calling)f(con)m(v)o(ention\))c(without)j(de\002ning) g(an)0 485 y(implementation.)53 b(The)30 b(f)o(actory)g(functions)f (must)h(be)g(called)h(with)f(the)h(desired)e(result)i(type)f(and)g(the) g(ar)o(gument)e(types)i(of)h(the)0 585 y(function.)0 732 y FD(CFUNCTYPE)p FJ(\()p FK(r)m(estype)o(,)19 b(*ar)m(gtypes)p FJ(\))208 831 y FN(The)h(returned)g(function)f(prototype)g(creates)i (functions)f(that)h(use)h(the)f(standard)f(C)i(calling)f(con)m(v)o (ention.)k(The)20 b(function)g(will)208 931 y(release)g(the)g(GIL)g (during)f(the)h(call.)0 1078 y FD(WINFUNCTYPE)p FJ(\()p FK(r)m(estype)o(,)e(*ar)m(gtypes)p FJ(\))208 1177 y FN(W)m(indo)n(ws)26 b(only:)38 b(The)27 b(returned)f(function)f(prototype)g(creates)i (functions)f(that)h(use)h(the)f FJ(stdcall)f FN(calling)h(con)m(v)o (ention,)208 1277 y(e)o(xcept)20 b(on)h(W)m(indo)n(ws)g(CE)h(where)f FJ(WINFUNCTYPE)f FN(is)j(the)e(same)h(as)g FJ(CFUNCTYPE)p FN(.)e(The)i(function)d(will)k(release)e(the)h(GIL)208 1377 y(during)c(the)i(call.)0 1524 y FD(PYFUNCTYPE)p FJ(\()p FK(r)m(estype)o(,)e(*ar)m(gtypes)p FJ(\))208 1623 y FN(The)i(returned)f(function)g(prototype)g(creates)i(functions)e (that)i(use)h(the)e(Python)g(calling)h(con)m(v)o(ention.)j(The)c (function)f(will)j FK(not)208 1723 y FN(release)e(the)g(GIL)g(during)f (the)h(call.)0 1870 y(Function)g(prototypes)g(created)h(by)g(the)h(f)o (actory)f(functions)f(can)h(be)h(instantiated)f(in)h(dif)n(ferent)e(w)o (ays,)i(depending)d(on)i(the)h(type)f(and)0 1969 y(number)d(of)i(the)h (parameters)d(in)j(the)f(call.)0 2116 y FD(prototype)p FJ(\()p FK(addr)m(ess)p FJ(\))208 2216 y FN(Returns)g(a)g(foreign)f (function)f(at)j(the)f(speci\002ed)g(address.)0 2363 y FD(prototype)p FJ(\()p FK(callable)p FJ(\))208 2462 y FN(Create)g(a)h(C)g(callable)f(function)e(\(a)i(callback)g (function\))e(from)h(a)i(Python)e FJ(callable)p FN(.)0 2609 y FD(prototype)p FJ(\()p FK(func)p 649 2609 25 4 v 27 w(spec)p FC([)p FK(,)h(par)o(am\003a)o(gs)12 b FC(])p FJ(\))208 2709 y FN(Returns)36 b(a)h(foreign)e(function)g(e)o(xported)g (by)h(a)h(shared)f(library)-5 b(.)73 b FJ(func_spec)36 b FN(must)h(be)f(a)h(2-tuple)f FJ(\(name_or_-)208 2808 y(ordinal,)48 b(library\))p FN(.)d(The)26 b(\002rst)i(item)f(is)h(the)f (name)g(of)g(the)g(e)o(xported)e(function)g(as)j(string,)g(or)f(the)g (ordinal)f(of)h(the)208 2908 y(e)o(xported)18 b(function)g(as)j(small)g (inte)o(ger)-5 b(.)24 b(The)c(second)f(item)h(is)h(the)g(shared)e (library)g(instance.)0 3055 y FD(prototype)p FJ(\()p FK(vtbl)p 630 3055 V 28 w(inde)n(x,)g(name)p FC([)p FK(,)g(par)o (am\003a)o(gs)p FC([)p FK(,)f(iid)c FC(])e(])p FJ(\))208 3155 y FN(Returns)24 b(a)i(foreign)d(function)g(that)j(will)f(call)h(a) f(COM)h(method.)38 b FJ(vtbl_index)23 b FN(is)j(the)f(inde)o(x)f(into)h (the)g(virtual)f(function)208 3254 y(table,)c(a)h(small)g(nonne)o(gati) n(v)o(e)c(inte)o(ger)-5 b(.)26 b FK(name)20 b FN(is)i(name)e(of)g(the)h (COM)h(method.)j FK(iid)e FN(is)e(an)g(optional)e(pointer)h(to)h(the)f (interf)o(ace)208 3354 y(identi\002er)f(which)h(is)h(used)f(in)g(e)o (xtended)e(error)h(reporting.)208 3480 y(COM)j(methods)e(use)h(a)h (special)f(calling)g(con)m(v)o(ention:)k(The)o(y)20 b(require)g(a)i (pointer)e(to)h(the)h(COM)g(interf)o(ace)e(as)i(\002rst)g(ar)o(gument,) 208 3580 y(in)e(addition)f(to)h(those)g(parameters)f(that)h(are)h (speci\002ed)e(in)i(the)f FJ(argtypes)f FN(tuple.)0 3727 y(The)i(optional)g FK(par)o(am\003a)o(gs)e FN(parameter)h(creates)i (foreign)e(function)g(wrappers)g(with)i(much)e(more)h(functionality)f (than)h(the)g(features)0 3827 y(described)e(abo)o(v)o(e.)0 3973 y FK(par)o(am\003a)o(gs)f FN(must)j(be)f(a)g(tuple)g(of)g(the)g (same)h(length)e(as)i FJ(argtypes)p FN(.)0 4120 y(Each)f(item)g(in)g (this)h(tuple)f(contains)f(further)g(information)f(about)h(a)i (parameter)m(,)d(it)j(must)f(be)g(a)h(tuple)e(containing)g(1,)h(2,)g (or)g(3)g(items.)0 4267 y(The)g(\002rst)h(item)f(is)h(an)f(inte)o(ger)f (containing)g(\003ags)h(for)g(the)g(parameter:)0 4414 y FD(1)208 4514 y FN(Speci\002es)g(an)g(input)g(parameter)e(to)j(the)f (function.)0 4661 y FD(2)208 4760 y FN(Output)f(parameter)-5 b(.)24 b(The)c(foreign)e(function)h(\002lls)i(in)f(a)h(v)n(alue.)0 4907 y FD(4)208 5007 y FN(Input)e(parameter)f(which)i(def)o(aults)g(to) g(the)g(inte)o(ger)f(zero.)0 5154 y(The)j(optional)f(second)h(item)g (is)i(the)e(parameter)f(name)h(as)h(string.)31 b(If)22 b(this)h(is)g(speci\002ed,)g(the)f(foreign)f(function)g(can)h(be)g (called)g(with)0 5253 y(named)d(parameters.)0 5400 y(The)h(optional)f (third)g(item)i(is)g(the)f(def)o(ault)g(v)n(alue)f(for)h(this)g (parameter)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(526)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 527 539 TeXDict begin 527 538 bop 0 83 a FN(This)20 b(e)o(xample)e (demonstrates)h(ho)n(w)g(to)h(wrap)f(the)h(W)m(indo)n(ws)f FJ(MessageBoxA)f FN(function)g(so)i(that)g(it)g(supports)f(def)o(ault)g (parameters)0 183 y(and)h(named)f(ar)o(guments.)k(The)c(C)j (declaration)c(from)h(the)i(windo)n(ws)e(header)g(\002le)i(is)g(this:) 236 421 y FA(WINUSERAPI)43 b(int)i(WINAPI)236 512 y(MessageBoxA\()416 603 y(HWND)f(hWnd)g(,)416 695 y(LPCSTR)f(lpText,)416 786 y(LPCSTR)g(lpCaption,)416 877 y(UINT)h(uType\);)0 1164 y FN(Here)20 b(is)h(the)f(wrapping)f(with)h FJ(ctypes)p FN(:)208 1364 y FA(>>>)44 b(from)g(ctypes)g(import)g(c_int,)g (WINFUNCTYPE,)e(windll)208 1456 y(>>>)i(from)g(ctypes.wintypes)e (import)i(HWND,)g(LPCSTR,)g(UINT)208 1547 y(>>>)g(prototype)f(=)i (WINFUNCTYPE\(c_int,)d(HWND,)i(LPCSTR,)f(LPCSTR,)h(UINT\))208 1638 y(>>>)g(paramflags)f(=)i(\(1,)f("hwnd",)g(0\),)g(\(1,)g("text",)g ("Hi"\),)g(\(1,)g("caption",)f(None\),)h(\(1,)g("flags",)g(0\))208 1730 y(>>>)g(MessageBox)f(=)i(prototype\(\("MessageBoxA",)40 b(windll.user32\),)j(paramflags\))208 1821 y(>>>)0 2161 y FN(The)20 b(MessageBox)f(foreign)g(function)f(can)i(no)n(w)g(be)g (called)g(in)h(these)f(w)o(ays:)236 2399 y FA(>>>)45 b(MessageBox\(\))236 2490 y(>>>)g(MessageBox\(text="Spam,)c(spam,)j (spam"\))236 2582 y(>>>)h(MessageBox\(flags=2,)c(text="foo)j(bar"\))236 2673 y(>>>)0 2959 y FN(A)22 b(second)e(e)o(xample)g(demonstrates)h (output)f(parameters.)27 b(The)21 b(win32)g FJ(GetWindowRect)e FN(function)h(retrie)n(v)o(es)g(the)i(dimensions)0 3059 y(of)e(a)h(speci\002ed)e(windo)n(w)h(by)f(cop)o(ying)g(them)h(into)g FJ(RECT)g FN(structure)f(that)h(the)g(caller)g(has)h(to)f(supply)-5 b(.)24 b(Here)c(is)h(the)f(C)h(declaration:)236 3297 y FA(WINUSERAPI)43 b(BOOL)i(WINAPI)236 3389 y(GetWindowRect\()460 3480 y(HWND)g(hWnd,)460 3571 y(LPRECT)f(lpRect\);)0 3858 y FN(Here)20 b(is)h(the)f(wrapping)f(with)h FJ(ctypes)p FN(:)208 4058 y FA(>>>)44 b(from)g(ctypes)g(import)g(POINTER,)f (WINFUNCTYPE,)g(windll,)h(WinError)208 4149 y(>>>)g(from)g (ctypes.wintypes)e(import)i(BOOL,)g(HWND,)g(RECT)208 4241 y(>>>)g(prototype)f(=)i(WINFUNCTYPE\(BOOL,)d(HWND,)i (POINTER\(RECT\)\))208 4332 y(>>>)g(paramflags)f(=)i(\(1,)f("hwnd"\),)g (\(2,)g("lprect"\))208 4423 y(>>>)g(GetWindowRect)f(=)h (prototype\(\("GetWindowRect",)c(windll.user32\),)j(paramflags\))208 4515 y(>>>)0 4855 y FN(Functions)16 b(with)g(output)g(parameters)f (will)i(automatically)e(return)h(the)g(output)g(parameter)f(v)n(alue)g (if)i(there)f(is)i(a)f(single)f(one,)h(or)f(a)h(tuple)0 4954 y(containing)j(the)i(output)e(parameter)g(v)n(alues)i(when)f (there)g(are)h(more)f(than)g(one,)g(so)h(the)g(GetW)m(indo)n(wRect)f (function)f(no)n(w)h(returns)g(a)0 5054 y(RECT)g(instance,)f(when)f (called.)0 5201 y(Output)f(parameters)h(can)g(be)g(combined)e(with)j (the)f FJ(errcheck)f FN(protocol)g(to)h(do)g(further)f(output)g (processing)g(and)g(error)h(checking.)0 5300 y(The)j(win32)g FJ(GetWindowRect)e FN(api)j(function)d(returns)i(a)h FJ(BOOL)f FN(to)g(signal)h(success)g(or)f(f)o(ailure,)g(so)h(this)f (function)f(could)h(do)g(the)0 5400 y(error)d(checking,)f(and)i(raises) h(an)f(e)o(xception)e(when)i(the)g(api)g(call)h(f)o(ailed:)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(527)p eop end %%Page: 528 540 TeXDict begin 528 539 bop 236 174 a FA(>>>)45 b(def)f (errcheck\(result,)e(func,)i(args\):)236 266 y(...)224 b(if)44 b(not)h(result:)236 357 y(...)403 b(raise)44 b(WinError\(\))236 448 y(...)224 b(return)44 b(args)236 540 y(>>>)h(GetWindowRect.errcheck)c(=)j(errcheck)236 631 y(>>>)0 917 y FN(If)16 b(the)g FJ(errcheck)g FN(function)e(returns) i(the)g(ar)o(gument)e(tuple)i(it)h(recei)n(v)o(es)f(unchanged,)e FJ(ctypes)h FN(continues)h(the)g(normal)f(processing)0 1017 y(it)21 b(does)f(on)f(the)h(output)f(parameters.)24 b(If)c(you)f(w)o(ant)h(to)h(return)d(a)j(tuple)f(of)f(windo)n(w)h (coordinates)e(instead)i(of)g(a)g FJ(RECT)g FN(instance,)f(you)0 1117 y(can)h(retrie)n(v)o(e)f(the)h(\002elds)h(in)f(the)g(function)f (and)g(return)h(them)f(instead,)h(the)g(normal)f(processing)g(will)i (no)f(longer)f(tak)o(e)h(place:)236 1355 y FA(>>>)45 b(def)f(errcheck\(result,)e(func,)i(args\):)236 1446 y(...)224 b(if)44 b(not)h(result:)236 1538 y(...)403 b(raise)44 b(WinError\(\))236 1629 y(...)224 b(rc)44 b(=)h(args[1])236 1720 y(...)224 b(return)44 b(rc.left,)f(rc.top,)h (rc.bottom,)f(rc.right)236 1812 y(>>>)236 1903 y(>>>)i (GetWindowRect.errcheck)c(=)j(errcheck)236 1994 y(>>>)0 2406 y FI(Utility)24 b(functions)0 2595 y FD(addressof)p FJ(\()p FK(obj)p FJ(\))208 2695 y FN(Returns)c(the)g(address)g(of)f (the)i(memory)d(b)n(uf)n(fer)h(as)i(inte)o(ger)-5 b(.)24 b FJ(obj)c FN(must)h(be)f(an)g(instance)g(of)g(a)g(ctypes)g(type.)0 2842 y FD(alignment)p FJ(\()p FK(obj)p 612 2842 25 4 v 27 w(or)p 713 2842 V 30 w(type)p FJ(\))208 2941 y FN(Returns)g(the)g (alignment)f(requirements)f(of)i(a)g(ctypes)g(type.)25 b FJ(obj_or_type)18 b FN(must)j(be)f(a)g(ctypes)g(type)g(or)g (instance.)0 3088 y FD(byref)p FJ(\()p FK(obj)p FJ(\))208 3188 y FN(Returns)e(a)i(light-weight)d(pointer)g(to)i FJ(obj)p FN(,)g(which)g(must)f(be)h(an)g(instance)g(of)f(a)h(ctypes)g (type.)24 b(The)18 b(returned)f(object)i(can)f(only)208 3287 y(be)24 b(used)g(as)g(a)h(foreign)d(function)h(call)h(parameter)-5 b(.)36 b(It)25 b(beha)n(v)o(es)e(similar)h(to)g FJ(pointer\(obj\))p FN(,)g(b)n(ut)g(the)g(construction)e(is)j(a)208 3387 y(lot)20 b(f)o(aster)-5 b(.)0 3534 y FD(cast)p FJ(\()p FK(obj,)19 b(type)p FJ(\))208 3633 y FN(This)25 b(function)e(is)i (similar)g(to)g(the)g(cast)g(operator)e(in)i(C.)h(It)f(returns)f(a)h (ne)n(w)g(instance)f(of)g FJ(type)h FN(which)f(points)h(to)g(the)f (same)208 3733 y(memory)e(block)i(as)h FJ(obj)p FN(.)38 b FJ(type)25 b FN(must)f(be)h(a)g(pointer)e(type,)i(and)f FJ(obj)h FN(must)f(be)h(an)f(object)g(that)h(can)g(be)f(interpreted)f (as)i(a)208 3833 y(pointer)-5 b(.)0 3980 y FD(create_string_buffer)p FJ(\()p FK(init)p 1166 3980 V 26 w(or)p 1266 3980 V 29 w(size)p FC([)p FK(,)21 b(size)12 b FC(])p FJ(\))208 4079 y FN(This)20 b(function)e(creates)j(a)f(mutable)f(character)g(b)n (uf)n(fer)-5 b(.)24 b(The)c(returned)f(object)g(is)i(a)g(ctypes)f (array)f(of)h FJ(c_char)p FN(.)208 4212 y FJ(init_or_size)26 b FN(must)i(be)h(an)f(inte)o(ger)f(which)g(speci\002es)i(the)f(size)h (of)f(the)g(array)-5 b(,)29 b(or)f(a)h(string)f(which)f(will)i(be)f (used)g(to)208 4312 y(initialize)20 b(the)g(array)f(items.)208 4444 y(If)e(a)h(string)g(is)h(speci\002ed)e(as)i(\002rst)f(ar)o (gument,)e(the)i(b)n(uf)n(fer)e(is)j(made)e(one)g(item)h(lar)o(ger)f (than)g(the)h(length)f(of)g(the)h(string)g(so)g(that)g(the)208 4544 y(last)24 b(element)f(in)h(the)g(array)f(is)i(a)f(NUL)g (termination)e(character)-5 b(.)35 b(An)24 b(inte)o(ger)f(can)h(be)f (passed)h(as)h(second)e(ar)o(gument)e(which)208 4644 y(allo)n(ws)f(to)g(specify)g(the)g(size)h(of)f(the)g(array)f(if)i(the)f (length)f(of)h(the)g(string)g(should)f(not)h(be)g(used.)208 4777 y(If)f(the)h(\002rst)g(parameter)f(is)h(a)g(unicode)f(string,)g (it)h(is)h(con)m(v)o(erted)c(into)j(an)f(8-bit)g(string)h(according)d (to)j(ctypes)g(con)m(v)o(ersion)d(rules.)0 4923 y FD (create_unicode_buffer)p FJ(\()p FK(init)p 1216 4923 V 26 w(or)p 1316 4923 V 29 w(size)p FC([)p FK(,)k(size)12 b FC(])p FJ(\))208 5023 y FN(This)20 b(function)e(creates)j(a)f (mutable)f(unicode)g(character)g(b)n(uf)n(fer)-5 b(.)24 b(The)c(returned)e(object)i(is)h(a)g(ctypes)f(array)f(of)h FJ(c_wchar)p FN(.)208 5156 y FJ(init_or_size)c FN(must)i(be)f(an)h (inte)o(ger)f(which)g(speci\002es)i(the)f(size)g(of)g(the)g(array)-5 b(,)16 b(or)i(a)g(unicode)f(string)g(which)g(will)i(be)f(used)208 5255 y(to)i(initialize)g(the)g(array)g(items.)p 0 5549 3901 4 v 0 5649 a FI(528)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 529 541 TeXDict begin 529 540 bop 208 83 a FN(If)16 b(a)i(unicode)d(string)i (is)h(speci\002ed)e(as)i(\002rst)g(ar)o(gument,)d(the)i(b)n(uf)n(fer)e (is)j(made)e(one)h(item)g(lar)o(ger)e(than)i(the)g(length)f(of)h(the)g (string)f(so)208 183 y(that)21 b(the)h(last)g(element)f(in)h(the)g (array)e(is)j(a)f(NUL)f(termination)f(character)-5 b(.)29 b(An)21 b(inte)o(ger)g(can)g(be)g(passed)h(as)g(second)f(ar)o(gument) 208 282 y(which)e(allo)n(ws)i(to)f(specify)g(the)g(size)h(of)e(the)i (array)e(if)h(the)h(length)e(of)h(the)g(string)g(should)f(not)h(be)g (used.)208 415 y(If)f(the)h(\002rst)g(parameter)f(is)h(a)g(8-bit)g (string,)f(it)h(is)h(con)m(v)o(erted)c(into)j(an)f(unicode)f(string)i (according)d(to)j(ctypes)g(con)m(v)o(ersion)d(rules.)0 562 y FD(DllCanUnloadNow)p FJ(\(\))208 662 y FN(W)m(indo)n(ws)24 b(only:)35 b(This)26 b(function)d(is)j(a)g(hook)e(which)h(allo)n(ws)h (to)f(implement)f(inprocess)h(COM)h(serv)o(ers)e(with)i(ctypes.)40 b(It)26 b(is)208 761 y(called)20 b(from)f(the)h(DllCanUnloadNo)n(w)e (function)h(that)h(the)p 1965 761 25 4 v 50 w(ctypes)g(e)o(xtension)f (dll)h(e)o(xports.)0 908 y FD(DllGetClassObject)p FJ(\(\))208 1008 y FN(W)m(indo)n(ws)k(only:)35 b(This)26 b(function)d(is)j(a)g (hook)e(which)h(allo)n(ws)h(to)f(implement)f(inprocess)h(COM)h(serv)o (ers)e(with)i(ctypes.)40 b(It)26 b(is)208 1107 y(called)20 b(from)f(the)h(DllGetClassObject)h(function)d(that)j(the)f FJ(_ctypes)f FN(e)o(xtension)g(dll)h(e)o(xports.)0 1254 y FD(FormatError)p FJ(\()p FC([)p FK(code)12 b FC(])p FJ(\))208 1354 y FN(W)m(indo)n(ws)21 b(only:)28 b(Returns)22 b(a)h(te)o(xtual)f(description)e(of)i(the)g(error)f(code.)30 b(If)23 b(no)e(error)g(code)h(is)h(speci\002ed,)f(the)g(last)h(error)e (code)208 1453 y(is)g(used)f(by)f(calling)h(the)g(W)m(indo)n(ws)g(api)g (function)f(GetLastError)-5 b(.)0 1600 y FD(GetLastError)p FJ(\(\))208 1700 y FN(W)m(indo)n(ws)19 b(only:)25 b(Returns)20 b(the)g(last)h(error)e(code)g(set)i(by)f(W)m(indo)n(ws)g(in)g(the)g (calling)g(thread.)0 1847 y FD(memmove)p FJ(\()p FK(dst,)f(sr)m(c,)i (count)q FJ(\))208 1946 y FN(Same)h(as)h(the)g(standard)e(C)j(memmo)o (v)o(e)c(library)h(function:)29 b(copies)22 b FK(count)h FN(bytes)f(from)g FJ(src)g FN(to)h FK(dst)q FN(.)33 b FK(dst)24 b FN(and)e FJ(src)h FN(must)g(be)208 2046 y(inte)o(gers)c(or) h(ctypes)g(instances)g(that)g(can)g(be)g(con)m(v)o(erted)e(to)i (pointers.)0 2193 y FD(memset)p FJ(\()p FK(dst,)f(c,)h(count)q FJ(\))208 2293 y FN(Same)e(as)i(the)e(standard)g(C)h(memset)g(library)e (function:)23 b(\002lls)d(the)f(memory)e(block)g(at)j(address)e FK(dst)i FN(with)f FK(count)g FN(bytes)g(of)f(v)n(alue)208 2392 y FK(c)p FN(.)25 b FK(dst)d FN(must)e(be)g(an)h(inte)o(ger)e (specifying)f(an)i(address,)g(or)g(a)g(ctypes)g(instance.)0 2539 y FD(POINTER)p FJ(\()p FK(type)p FJ(\))208 2639 y FN(This)c(f)o(actory)f(function)g(creates)h(and)g(returns)f(a)i(ne)n (w)f(ctypes)f(pointer)g(type.)24 b(Pointer)15 b(types)h(are)g(cached)g (an)g(reused)f(internally)-5 b(,)208 2738 y(so)20 b(calling)g(this)h (function)d(repeatedly)h(is)i(cheap.)j(type)c(must)g(be)g(a)g(ctypes)g (type.)0 2885 y FD(pointer)p FJ(\()p FK(obj)p FJ(\))208 2985 y FN(This)48 b(function)e(creates)i(a)h(ne)n(w)f(pointer)f (instance,)54 b(pointing)47 b(to)h FJ(obj)p FN(.)109 b(The)48 b(returned)e(object)i(is)h(of)f(the)g(type)208 3084 y(POINTER\(type\(obj\)\).)208 3217 y(Note:)33 b(If)24 b(you)g(just)h(w)o(ant)f(to)h(pass)g(a)f(pointer)g(to)g(an)g(object)g (to)h(a)g(foreign)d(function)h(call,)i(you)f(should)f(use)i FJ(byref\(obj\))208 3317 y FN(which)19 b(is)i(much)f(f)o(aster)-5 b(.)0 3464 y FD(resize)p FJ(\()p FK(obj,)18 b(size)p FJ(\))208 3563 y FN(This)25 b(function)e(resizes)j(the)f(internal)f (memory)f(b)n(uf)n(fer)h(of)h(obj,)g(which)g(must)g(be)g(an)g(instance) g(of)f(a)i(ctypes)f(type.)39 b(It)25 b(is)h(not)208 3663 y(possible)21 b(to)h(mak)o(e)g(the)f(b)n(uf)n(fer)g(smaller)h(than)f (the)h(nati)n(v)o(e)f(size)h(of)g(the)g(objects)f(type,)h(as)h(gi)n(v)o (en)d(by)i(sizeof\(type\(obj\)\),)c(b)n(ut)k(it)208 3763 y(is)f(possible)f(to)g(enlar)o(ge)f(the)h(b)n(uf)n(fer)-5 b(.)0 3910 y FD(set_conversion_mode)p FJ(\()p FK(encoding)o(,)14 b(err)l(or)o(s)p FJ(\))208 4009 y FN(This)23 b(function)f(sets)j(the)f (rules)g(that)f(ctypes)h(objects)f(use)h(when)f(con)m(v)o(erting)e (between)i(8-bit)g(strings)h(and)f(unicode)f(strings.)208 4109 y(encoding)15 b(must)i(be)h(a)f(string)h(specifying)d(an)j (encoding,)d(lik)o(e)j FJ('utf-8')f FN(or)g FJ('mbcs')p FN(,)g(errors)f(must)i(be)f(a)h(string)f(specifying)208 4208 y(the)j(error)e(handling)h(on)g(encoding/decoding)c(errors.)24 b(Examples)19 b(of)h(possible)g(v)n(alues)f(are)h FJ("strict")p FN(,)f FJ("replace")p FN(,)g(or)208 4308 y FJ("ignore")p FN(.)208 4441 y FJ(set_conversion_mode)d FN(returns)j(a)i(2-tuple)d (containing)g(the)i(pre)n(vious)f(con)m(v)o(ersion)e(rules.)24 b(On)c(windo)n(ws,)f(the)h(initial)208 4541 y(con)m(v)o(ersion)d(rules) j(are)g FJ(\('mbcs',)49 b('ignore'\))p FN(,)18 b(on)i(other)g(systems)g FJ(\('ascii',)48 b('strict'\))p FN(.)0 4687 y FD(sizeof)p FJ(\()p FK(obj)p 462 4687 V 28 w(or)p 564 4687 V 29 w(type)p FJ(\))208 4787 y FN(Returns)29 b(the)h(size)h(in)f(bytes)f(of)h(a)g (ctypes)g(type)f(or)h(instance)f(memory)f(b)n(uf)n(fer)-5 b(.)53 b(Does)30 b(the)g(same)g(as)h(the)f(C)g FJ(sizeof\(\))208 4887 y FN(function.)0 5034 y FD(string_at)p FJ(\()p FK(addr)m(ess)p FC([)p FK(,)18 b(size)12 b FC(])p FJ(\))208 5133 y FN(This)32 b(function)e(returns)h(the)g(string)h(starting)f(at)i(memory)d(address) h(address.)60 b(If)31 b(size)i(is)g(speci\002ed,)h(it)e(is)h(used)f(as) g(size,)208 5233 y(otherwise)19 b(the)h(string)g(is)h(assumed)f(to)g (be)g(zero-terminated.)0 5380 y FD(WinError)p FJ(\()p FK(code=None)o(,)d(descr=None)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f (function)h(libr)o(ar)r(y)g(f)n(or)e(Python.)1736 b(529)p eop end %%Page: 530 542 TeXDict begin 530 541 bop 208 83 a FN(W)m(indo)n(ws)19 b(only:)25 b(this)20 b(function)f(is)i(probably)d(the)i(w)o(orst-named) e(thing)i(in)g(ctypes.)k(It)d(creates)f(an)g(instance)g(of)g(W)m(indo)n (wsEr)n(-)208 183 y(ror)-5 b(.)34 b(If)24 b FK(code)e FN(is)j(not)e(speci\002ed,)h FJ(GetLastError)d FN(is)k(called)e(to)h (determine)e(the)h(error)g(code.)34 b(If)23 b FJ(descr)g FN(is)i(not)e(spci\002ed,)208 282 y FJ(FormatError)18 b FN(is)j(called)f(to)h(get)f(a)h(te)o(xtual)e(description)g(of)h(the)g (error)-5 b(.)0 429 y FD(wstring_at)p FJ(\()p FK(addr)m(ess)p FJ(\))208 529 y FN(This)31 b(function)e(returns)h(the)h(wide)g (character)f(string)h(starting)g(at)g(memory)e(address)i FJ(address)f FN(as)i(unicode)e(string.)57 b(If)208 628 y FJ(size)27 b FN(is)h(speci\002ed,)g(it)g(is)h(used)e(as)h(the)f (number)e(of)i(characters)g(of)g(the)g(string,)h(otherwise)f(the)g (string)g(is)h(assumed)f(to)h(be)208 728 y(zero-terminated.)0 996 y FI(Data)23 b(types)0 1185 y FL(class)e FD(_CData)208 1285 y FN(This)k(non-public)e(class)k(is)f(the)g(common)d(base)j(class) h(of)e(all)h(ctypes)f(data)h(types.)41 b(Among)24 b(other)g(things,)j (all)f(ctypes)f(type)208 1384 y(instances)c(contain)f(a)h(memory)f (block)g(that)h(hold)f(C)i(compatible)e(data;)h(the)h(address)e(of)h (the)g(memory)e(block)i(is)h(returned)d(by)208 1484 y(the)24 b FJ(addressof\(\))f FN(helper)h(function.)37 b(Another)23 b(instance)h(v)n(ariable)g(is)i(e)o(xposed)d(as)i FJ(_objects)p FN(;)h(this)f(contains)f(other)208 1584 y(Python)19 b(objects)h(that)g (need)f(to)i(be)f(k)o(ept)g(ali)n(v)o(e)g(in)g(case)h(the)f(memory)e (block)h(contains)h(pointers.)0 1731 y(Common)f(methods)g(of)h(ctypes)g (data)g(types,)g(these)g(are)g(all)h(class)g(methods)e(\(to)h(be)g(e)o (xact,)g(the)o(y)f(are)h(methods)f(of)h(the)g(metaclass\):)0 1877 y FD(from_address)p FJ(\()p FK(addr)m(ess)p FJ(\))208 1977 y FN(This)g(method)f(returns)g(a)i(ctypes)f(type)f(instance)h (using)g(the)g(memory)e(speci\002ed)i(by)g(address)g(which)f(must)i(be) f(an)g(inte)o(ger)-5 b(.)0 2124 y FD(from_param)p FJ(\()p FK(obj)p FJ(\))208 2224 y FN(This)21 b(method)e(adapts)h(obj)h(to)g(a)g (ctypes)g(type.)26 b(It)21 b(is)h(called)e(with)h(the)g(actual)g (object)f(used)h(in)g(a)g(foreign)e(function)g(call,)i(when)208 2323 y(the)16 b(type)h(is)g(present)f(in)h(the)g(foreign)e(functions)g FJ(argtypes)h FN(tuple;)i(it)f(must)g(return)e(an)i(object)f(that)h (can)g(be)f(used)h(as)g(function)208 2423 y(call)j(parameter)-5 b(.)208 2556 y(All)25 b(ctypes)g(data)g(types)g(ha)n(v)o(e)g(a)g(def)o (ault)g(implementation)e(of)h(this)i(classmethod,)f(normally)f(it)i (returns)e FJ(obj)h FN(if)g(that)h(is)g(an)208 2655 y(instance)19 b(of)h(the)g(type.)25 b(Some)20 b(types)g(accept)g(other)f(objects)h (as)h(well.)0 2802 y FD(in_dll)p FJ(\()p FK(libr)o(ary)-5 b(,)19 b(name)p FJ(\))208 2902 y FN(This)24 b(method)f(returns)g(a)i (ctypes)e(type)h(instance)g(e)o(xported)e(by)i(a)g(shared)g(library)-5 b(.)35 b FK(name)23 b FN(is)i(the)g(name)e(of)h(the)g(symbol)f(that)208 3001 y(e)o(xports)18 b(the)j(data,)f FK(libr)o(ary)g FN(is)h(the)f(loaded)f(shared)h(library)-5 b(.)0 3148 y(Common)19 b(instance)h(v)n(ariables)f(of)h(ctypes)g(data)g(types:)0 3295 y FD(_b_base_)208 3395 y FN(Sometimes)29 b(ctypes)g(data)h (instances)g(do)f(not)g(o)n(wn)g(the)h(memory)e(block)h(the)o(y)g (contain,)i(instead)e(the)o(y)g(share)h(part)f(of)h(the)208 3494 y(memory)f(block)g(of)i(a)g(base)g(object.)56 b(The)31 b FJ(_b_base_)f FN(readonly)e(member)i(is)i(the)e(root)g(ctypes)h (object)f(that)h(o)n(wns)g(the)208 3594 y(memory)18 b(block.)0 3741 y FD(_b_needsfree_)208 3841 y FN(This)k(readonly)e(v)n(ariable)h (is)j(true)e(when)f(the)h(ctypes)g(data)h(instance)e(has)i(allocated)e (the)i(memory)d(block)i(itself,)h(f)o(alse)f(other)n(-)208 3940 y(wise.)0 4087 y FD(_objects)208 4187 y FN(This)28 b(member)e(is)j(either)f FJ(None)f FN(or)h(a)g(dictionary)e(containing) g(Python)h(objects)h(that)g(need)f(to)h(be)g(k)o(ept)g(ali)n(v)o(e)f (so)i(that)f(the)208 4286 y(memory)21 b(block)h(contents)g(is)i(k)o (ept)e(v)n(alid.)33 b(This)23 b(object)g(is)g(only)f(e)o(xposed)g(for)g (deb)n(ugging;)g(ne)n(v)o(er)f(modify)h(the)h(contents)f(of)208 4386 y(this)e(dictionary)-5 b(.)0 4654 y FI(Fundamental)25 b(data)e(types)0 4843 y FL(class)e FD(_SimpleCData)208 4943 y FN(This)28 b(non-public)d(class)k(is)g(the)f(base)g(class)h(of)f (all)h(fundamental)c(ctypes)j(data)g(types.)48 b(It)29 b(is)g(mentioned)d(here)h(because)h(it)208 5042 y(contains)f(the)h (common)e(attrib)n(utes)i(of)g(the)g(fundamental)d(ctypes)j(data)g (types.)48 b FJ(_SimpleCData)26 b FN(is)j(a)f(subclass)h(of)e FJ(_-)208 5142 y(CData)p FN(,)19 b(so)i(it)g(inherits)e(their)h (methods)f(and)h(attrib)n(utes.)0 5289 y(Instances)g(ha)n(v)o(e)f(a)i (single)f(attrib)n(ute:)p 0 5549 3901 4 v 0 5649 a FI(530)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r (vices)p eop end %%Page: 531 543 TeXDict begin 531 542 bop 0 83 a FD(value)208 183 y FN(This)16 b(attrib)n(ute)g(contains)g(the)g(actual)g(v)n(alue)g(of)g(the)g (instance.)23 b(F)o(or)16 b(inte)o(ger)g(and)f(pointer)g(types,)i(it)g (is)g(an)g(inte)o(ger)m(,)e(for)h(character)208 282 y(types,)j(it)i(is) g(a)g(single)f(character)f(string,)h(for)f(character)g(pointer)g(types) h(it)h(is)g(a)g(Python)e(string)h(or)g(unicode)e(string.)208 415 y(When)31 b(the)h FJ(value)f FN(attrib)n(ute)g(is)i(retrie)n(v)o (ed)d(from)g(a)i(ctypes)g(instance,)h(usually)e(a)h(ne)n(w)g(object)f (is)i(returned)c(each)j(time.)208 515 y FJ(ctypes)19 b FN(does)g FK(not)h FN(implement)e(original)h(object)g(return,)g(al)o (w)o(ays)h(a)g(ne)n(w)g(object)f(is)i(constructed.)i(The)d(same)g(is)g (true)g(for)f(all)208 614 y(other)g(ctypes)h(object)f(instances.)0 761 y(Fundamental)k(data)h(types,)h(when)f(returned)f(as)i(foreign)e (function)g(call)i(results,)h(or)m(,)f(for)f(e)o(xample,)g(by)g(retrie) n(ving)f(structure)g(\002eld)0 861 y(members)18 b(or)i(array)e(items,)i (are)g(transparently)d(con)m(v)o(erted)g(to)j(nati)n(v)o(e)f(Python)f (types.)25 b(In)19 b(other)g(w)o(ords,)g(if)h(a)g(foreign)e(function)f (has)j(a)0 960 y FJ(restype)f FN(of)h FJ(c_char_p)p FN(,)f(you)h(will)h (al)o(w)o(ays)f(recei)n(v)o(e)f(a)i(Python)e(string,)h FK(not)g FN(a)g FJ(c_char_p)f FN(instance.)0 1107 y(Subclasses)j(of)f (fundamental)e(data)j(types)f(do)h FK(not)f FN(inherit)g(this)h(beha)n (viour)-5 b(.)28 b(So,)22 b(if)g(a)g(foreign)e(functions)g FJ(restype)h FN(is)h(a)g(subclass)0 1207 y(of)h FJ(c_void_p)p FN(,)f(you)g(will)h(recei)n(v)o(e)f(an)h(instance)f(of)h(this)g (subclass)g(from)f(the)h(function)e(call.)33 b(Of)23 b(course,)g(you)f(can)h(get)f(the)h(v)n(alue)0 1307 y(of)d(the)g (pointer)f(by)h(accessing)g(the)g FJ(value)g FN(attrib)n(ute.)0 1453 y(These)g(are)g(the)g(fundamental)e(ctypes)i(data)g(types:)0 1600 y FL(class)h FD(c_byte)208 1700 y FN(Represents)27 b(the)h(C)h(signed)e(char)g(datatype,)i(and)e(interprets)g(the)h(v)n (alue)f(as)i(small)f(inte)o(ger)-5 b(.)47 b(The)28 b(constructor)e (accepts)i(an)208 1800 y(optional)18 b(inte)o(ger)i(initializer;)g(no)f (o)o(v)o(er\003o)n(w)g(checking)f(is)j(done.)0 1946 y FL(class)g FD(c_char)208 2046 y FN(Represents)15 b(the)i(C)g(char)e (datatype,)h(and)f(interprets)g(the)i(v)n(alue)e(as)i(a)f(single)g (character)-5 b(.)23 b(The)16 b(constructor)e(accepts)i(an)g(optional) 208 2146 y(string)j(initializer)m(,)h(the)g(length)f(of)h(the)g(string) g(must)h(be)f(e)o(xactly)f(one)h(character)-5 b(.)0 2293 y FL(class)21 b FD(c_char_p)208 2392 y FN(Represents)g(the)h(C)g(char)f (*)h(datatype,)f(which)g(must)h(be)f(a)h(pointer)f(to)h(a)g (zero-terminated)d(string.)29 b(The)21 b(constructor)f(accepts)208 2492 y(an)g(inte)o(ger)f(address,)g(or)h(a)h(string.)0 2639 y FL(class)g FD(c_double)208 2738 y FN(Represents)f(the)g(C)h (double)e(datatype.)k(The)d(constructor)f(accepts)h(an)g(optional)f (\003oat)h(initializer)-5 b(.)0 2885 y FL(class)21 b FD(c_float)208 2985 y FN(Represents)f(the)g(C)h(\003oat)f(datatype.)k (The)c(constructor)e(accepts)i(an)g(optional)f(\003oat)i(initializer)-5 b(.)0 3132 y FL(class)21 b FD(c_int)208 3231 y FN(Represents)e(the)g(C) h(signed)e(int)i(datatype.)j(The)c(constructor)e(accepts)i(an)g (optional)f(inte)o(ger)g(initializer;)i(no)e(o)o(v)o(er\003o)n(w)g (check-)208 3331 y(ing)h(is)j(done.)h(On)e(platforms)e(where)g FJ(sizeof\(int\))48 b(==)h(sizeof\(long\))19 b FN(it)i(is)g(an)f(alias) h(to)f FJ(c_long)p FN(.)0 3478 y FL(class)h FD(c_int8)208 3577 y FN(Represents)f(the)g(C)h(8-bit)f FJ(signed)48 b(int)20 b FN(datatype.)k(Usually)c(an)g(alias)h(for)f FJ(c_byte)p FN(.)0 3724 y FL(class)h FD(c_int16)208 3824 y FN(Represents)f(the)g(C)h(16-bit)e(signed)h(int)g(datatype.)k (Usually)c(an)g(alias)h(for)e FJ(c_short)p FN(.)0 3971 y FL(class)i FD(c_int32)208 4070 y FN(Represents)f(the)g(C)h(32-bit)e (signed)h(int)g(datatype.)k(Usually)c(an)g(alias)h(for)e FJ(c_int)p FN(.)0 4217 y FL(class)i FD(c_int64)208 4317 y FN(Represents)f(the)g(C)h(64-bit)e FJ(signed)49 b(int)20 b FN(datatype.)k(Usually)c(an)g(alias)h(for)e FJ(c_longlong)p FN(.)0 4464 y FL(class)i FD(c_long)208 4563 y FN(Represents)f(the)g(C)i FJ(signed)49 b(long)20 b FN(datatype.)25 b(The)20 b(constructor)e (accepts)j(an)f(optional)f(inte)o(ger)h(initializer;)g(no)g(o)o(v)o (er\003o)n(w)208 4663 y(checking)e(is)j(done.)0 4810 y FL(class)g FD(c_longlong)208 4910 y FN(Represents)j(the)h(C)h FJ(signed)49 b(long)g(long)24 b FN(datatype.)38 b(The)24 b(constructor)f(accepts)i(an)g(optional)e(inte)o(ger)h(initializer;)j (no)208 5009 y(o)o(v)o(er\003o)n(w)18 b(checking)g(is)j(done.)0 5156 y FL(class)g FD(c_short)208 5256 y FN(Represents)16 b(the)g(C)i FJ(signed)48 b(short)16 b FN(datatype.)23 b(The)16 b(constructor)f(accepts)h(an)g(optional)g(inte)o(ger)f (initializer;)i(no)f(o)o(v)o(er\003o)n(w)208 5355 y(checking)i(is)j (done.)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(531)p eop end %%Page: 532 544 TeXDict begin 532 543 bop 0 83 a FL(class)21 b FD(c_size_t)208 183 y FN(Represents)f(the)g(C)h FJ(size_t)f FN(datatype.)0 330 y FL(class)h FD(c_ubyte)208 429 y FN(Represents)h(the)h(C)h FJ(unsigned)49 b(char)23 b FN(datatype,)f(it)i(interprets)e(the)h(v)n (alue)f(as)i(small)f(inte)o(ger)-5 b(.)33 b(The)23 b(constructor)e (accepts)208 529 y(an)f(optional)f(inte)o(ger)g(initializer;)h(no)f(o)o (v)o(er\003o)n(w)g(checking)f(is)j(done.)0 676 y FL(class)g FD(c_uint)208 775 y FN(Represents)16 b(the)g(C)i FJ(unsigned)48 b(int)16 b FN(datatype.)23 b(The)16 b(constructor)f(accepts)h(an)g (optional)g(inte)o(ger)f(initializer;)i(no)f(o)o(v)o(er\003o)n(w)208 875 y(checking)i(is)j(done.)j(On)c(platforms)f(where)h FJ(sizeof\(int\))48 b(==)h(sizeof\(long\))19 b FN(it)h(is)i(an)e(alias) h(for)e FJ(c_ulong)p FN(.)0 1022 y FL(class)i FD(c_uint8)208 1121 y FN(Represents)f(the)g(C)h(8-bit)f(unsigned)e(int)i(datatype.)k (Usually)c(an)g(alias)h(for)f FJ(c_ubyte)p FN(.)0 1268 y FL(class)h FD(c_uint16)208 1368 y FN(Represents)f(the)g(C)h(16-bit)e (unsigned)g(int)h(datatype.)k(Usually)c(an)g(alias)h(for)e FJ(c_ushort)p FN(.)0 1515 y FL(class)i FD(c_uint32)208 1614 y FN(Represents)f(the)g(C)h(32-bit)e(unsigned)g(int)h(datatype.)k (Usually)c(an)g(alias)h(for)e FJ(c_uint)p FN(.)0 1761 y FL(class)i FD(c_uint64)208 1861 y FN(Represents)f(the)g(C)h(64-bit)e (unsigned)g(int)h(datatype.)k(Usually)c(an)g(alias)h(for)e FJ(c_ulonglong)p FN(.)0 2008 y FL(class)i FD(c_ulong)208 2107 y FN(Represents)g(the)h(C)h FJ(unsigned)48 b(long)22 b FN(datatype.)28 b(The)22 b(constructor)e(accepts)h(an)h(optional)e (inte)o(ger)h(initializer;)i(no)e(o)o(v)o(er)n(-)208 2207 y(\003o)n(w)f(checking)e(is)j(done.)0 2354 y FL(class)g FD(c_ulonglong)208 2454 y FN(Represents)k(the)h(C)g FJ(unsigned)49 b(long)g(long)25 b FN(datatype.)40 b(The)26 b(constructor)e(accepts)h (an)h(optional)e(inte)o(ger)h(initializer;)208 2553 y(no)19 b(o)o(v)o(er\003o)n(w)g(checking)f(is)j(done.)0 2700 y FL(class)g FD(c_ushort)208 2800 y FN(Represents)31 b(the)h(C)g FJ(unsigned)49 b(short)31 b FN(datatype.)58 b(The)32 b(constructor)d(accepts)j(an)g(optional)e(inte)o(ger)h (initializer;)37 b(no)208 2899 y(o)o(v)o(er\003o)n(w)18 b(checking)g(is)j(done.)0 3046 y FL(class)g FD(c_void_p)208 3146 y FN(Represents)d(the)h(C)h FJ(void)1036 3161 y(*)1105 3146 y FN(type.)k(The)19 b(v)n(alue)f(is)i(represented)d(as)i(inte)o (ger)-5 b(.)24 b(The)19 b(constructor)e(accepts)h(an)h(optional)f(inte) o(ger)208 3245 y(initializer)-5 b(.)0 3392 y FL(class)21 b FD(c_wchar)208 3492 y FN(Represents)26 b(the)g(C)i FJ(wchar_t)d FN(datatype,)i(and)f(interprets)f(the)h(v)n(alue)g(as)h(a) g(single)f(character)f(unicode)g(string.)43 b(The)26 b(con-)208 3591 y(structor)19 b(accepts)h(an)g(optional)f(string)h (initializer)m(,)f(the)i(length)e(of)h(the)g(string)g(must)g(be)g(e)o (xactly)f(one)h(character)-5 b(.)0 3738 y FL(class)21 b FD(c_wchar_p)208 3838 y FN(Represents)26 b(the)g(C)h FJ(wchar_t)1208 3853 y(*)1284 3838 y FN(datatype,)g(which)e(must)i(be)f (a)g(pointer)f(to)i(a)g(zero-terminated)c(wide)j(character)f(string.) 208 3938 y(The)19 b(constructor)g(accepts)h(an)g(inte)o(ger)f(address,) g(or)h(a)h(string.)0 4084 y FL(class)g FD(HRESULT)208 4184 y FN(W)m(indo)n(ws)26 b(only:)39 b(Represents)27 b(a)g FJ(HRESULT)g FN(v)n(alue,)h(which)e(contains)h(success)g(or)g (error)f(information)f(for)i(a)g(function)f(or)208 4284 y(method)18 b(call.)0 4431 y FL(class)j FD(py_object)208 4530 y FN(Represents)28 b(the)g(C)i FJ(PyObject)1264 4545 y(*)1343 4530 y FN(datatype.)48 b(Calling)28 b(this)h(without)f (an)g(ar)o(gument)e(creates)j(a)g FJ(NULL)f(PyObject)3850 4545 y(*)208 4630 y FN(pointer)-5 b(.)0 4777 y(The)36 b FJ(ctypes.wintypes)e FN(module)g(pro)o(vides)h(quite)g(some)h(other)g (W)m(indo)n(ws)f(speci\002c)h(data)g(types,)k(for)35 b(e)o(xample)g FJ(HWND)p FN(,)0 4876 y FJ(WPARAM)p FN(,)19 b(or)h FJ(DWORD)p FN(.)g(Some)g(useful)f(structures)h(lik)o(e)g FJ(MSG)h FN(or)f FJ(RECT)g FN(are)g(also)g(de\002ned.)p 0 5549 3901 4 v 0 5649 a FI(532)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 533 545 TeXDict begin 533 544 bop 0 83 a FI(Str)q(uctured)23 b(data)h(types)0 272 y FL(class)d FD(Union)p FJ(\()p FK(*ar)m(gs,)d(**kw)p FJ(\))208 372 y FN(Abstract)i(base)g(class)h(for) f(unions)f(in)h(nati)n(v)o(e)f(byte)h(order)-5 b(.)0 518 y FL(class)21 b FD(BigEndianStructure)p FJ(\()p FK(*ar)m(gs,)16 b(**kw)p FJ(\))208 618 y FN(Abstract)k(base)g(class)h(for)f(structures) f(in)h FK(big)g(endian)f FN(byte)h(order)-5 b(.)0 765 y FL(class)21 b FD(LittleEndianStructure)p FJ(\()p FK(*ar)m(gs,)15 b(**kw)p FJ(\))208 865 y FN(Abstract)20 b(base)g(class)h(for)f (structures)f(in)h FK(little)h(endian)e FN(byte)h(order)-5 b(.)0 1011 y(Structures)26 b(with)h(non-nati)n(v)o(e)e(byte)h(order)g (cannot)g(contain)g(pointer)g(type)h(\002elds,)i(or)d(an)o(y)h(other)f (data)h(types)g(containing)e(pointer)0 1111 y(type)20 b(\002elds.)0 1258 y FL(class)h FD(Structure)p FJ(\()p FK(*ar)m(gs,)c(**kw)p FJ(\))208 1358 y FN(Abstract)j(base)g(class)h (for)f(structures)f(in)h FK(native)g FN(byte)g(order)-5 b(.)0 1504 y(Concrete)15 b(structure)f(and)h(union)f(types)h(must)h(be) f(created)g(by)g(subclassing)g(one)f(of)i(these)f(types,)h(and)f(at)h (least)g(de\002ne)f(a)h FJ(_fields_-)0 1604 y FN(class)21 b(v)n(ariable.)j FJ(ctypes)c FN(will)h(create)f(descriptors)f(which)g (allo)n(w)i(reading)d(and)i(writing)g(the)g(\002elds)h(by)e(direct)h (attrib)n(ute)g(accesses.)0 1704 y(These)g(are)g(the)0 1851 y FD(_fields_)208 1950 y FN(A)j(sequence)g(de\002ning)f(the)h (structure)g(\002elds.)35 b(The)23 b(items)h(must)f(be)g(2-tuples)g(or) g(3-tuples.)34 b(The)23 b(\002rst)h(item)f(is)i(the)e(name)g(of)208 2050 y(the)d(\002eld,)g(the)g(second)f(item)i(speci\002es)f(the)h(type) e(of)h(the)g(\002eld;)h(it)g(can)f(be)g(an)o(y)f(ctypes)h(data)g(type.) 208 2183 y(F)o(or)c(inte)o(ger)g(type)g(\002elds)h(lik)o(e)g FJ(c_int)p FN(,)g(a)g(third)g(optional)e(item)i(can)g(be)f(gi)n(v)o (en.)23 b(It)17 b(must)g(be)g(a)g(small)g(positi)n(v)o(e)f(inte)o(ger)g (de\002ning)208 2282 y(the)k(bit)g(width)g(of)g(the)g(\002eld.)208 2415 y(Field)i(names)g(must)g(be)g(unique)f(within)h(one)g(structure)f (or)h(union.)29 b(This)23 b(is)g(not)f(check)o(ed,)f(only)g(one)h (\002eld)g(can)g(be)h(accessed)208 2515 y(when)c(names)h(are)g (repeated.)208 2648 y(It)e(is)h(possible)f(to)g(de\002ne)g(the)g FJ(_fields_)g FN(class)h(v)n(ariable)e FK(after)i FN(the)f(class)h (statement)f(that)g(de\002nes)g(the)g(Structure)g(subclass,)208 2747 y(this)i(allo)n(ws)h(to)f(create)g(data)g(types)g(that)g(directly) g(or)g(indirectly)f(reference)f(themselv)o(es:)444 2971 y FA(class)44 b(List\(Structure\):)623 3063 y(pass)444 3154 y(List._fields_)e(=)j([\("pnext",)e(POINTER\(List\)\),)1206 3245 y(...)1161 3337 y(])208 3526 y FN(The)25 b FJ(_fields_)g FN(class)h(v)n(ariable)f(must,)h(ho)n(we)n(v)o(er)m(,)f(be)h(de\002ned) e(before)g(the)i(type)f(is)i(\002rst)f(used)g(\(an)f(instance)g(is)i (created,)208 3626 y FJ(sizeof\(\))18 b FN(is)i(called)f(on)g(it,)h (and)f(so)g(on\).)24 b(Later)19 b(assignments)g(to)g(the)h FJ(_fields_)e FN(class)i(v)n(ariable)e(will)i(raise)g(an)f(Attrib)n(u-) 208 3725 y(teError)-5 b(.)208 3858 y(Structure)24 b(and)h(union)f (subclass)h(constructors)f(accept)h(both)g(positional)f(and)h(named)f (ar)o(guments.)39 b(Positional)25 b(ar)o(guments)208 3958 y(are)c(used)f(to)i(initialize)f(the)g(\002elds)g(in)g(the)h(same) f(order)f(as)h(the)o(y)g(appear)e(in)j(the)f FJ(_fields_)f FN(de\002nition,)g(named)g(ar)o(guments)208 4057 y(are)g(used)g(to)g (initialize)g(the)g(\002elds)h(with)g(the)f(corresponding)c(name.)208 4190 y(It)26 b(is)g(possible)g(to)g(de\002ned)f(sub-subclasses)g(of)g (structure)g(types,)i(the)o(y)e(inherit)g(the)h(\002elds)g(of)f(the)h (base)g(class)h(plus)f(the)f FJ(_-)208 4290 y(fields_)19 b FN(de\002ned)g(in)i(the)f(sub-subclass,)f(if)h(an)o(y)-5 b(.)0 4437 y FD(_pack_)208 4536 y FN(An)19 b(optional)e(small)j(inte)o (ger)e(that)h(allo)n(ws)g(to)h(o)o(v)o(erride)c(the)j(alignment)f(of)h (structure)f(\002elds)i(in)f(the)g(instance.)24 b FJ(_pack_)19 b FN(must)208 4636 y(already)g(be)h(de\002ned)f(when)h FJ(_fields_)f FN(is)i(assigned,)e(otherwise)h(it)h(will)g(ha)n(v)o(e)e (no)h(ef)n(fect.)0 4783 y FD(_anonymous_)208 4882 y FN(An)26 b(optional)g(sequence)f(that)i(lists)h(the)f(names)f(of)h(unnamed)d (\(anon)o(ymous\))f(\002elds.)45 b FJ(_anonymous_)25 b FN(must)i(be)g(already)208 4982 y(de\002ned)19 b(when)g FJ(_fields_)h FN(is)h(assigned,)e(otherwise)h(it)h(will)g(ha)n(v)o(e)e (no)h(ef)n(fect.)208 5115 y(The)k(\002elds)h(listed)g(in)f(this)h(v)n (ariable)f(must)g(be)h(structure)e(or)i(union)e(type)h(\002elds.)38 b FJ(ctypes)24 b FN(will)h(create)g(descriptors)e(in)i(the)208 5215 y(structure)e(type)i(that)f(allo)n(ws)h(to)g(access)g(the)g (nested)f(\002elds)i(directly)-5 b(,)24 b(without)g(the)h(need)f(to)h (create)f(the)h(structure)e(or)i(union)208 5314 y(\002eld.)p 0 5549 3901 4 v 0 5649 a FI(14.14.)52 b FJ(ctypes)22 b FI(\227)h(A)h(f)n(oreign)f(function)h(libr)o(ar)r(y)g(f)n(or)e (Python.)1736 b(533)p eop end %%Page: 534 546 TeXDict begin 534 545 bop 208 83 a FN(Here)20 b(is)h(an)f(e)o(xample)f (type)g(\(W)m(indo)n(ws\):)444 307 y FA(class)44 b(_U\(Union\):)623 399 y(_fields_)g(=)g([\("lptdesc",)f(POINTER\(TYPEDESC\)\),)1161 490 y(\("lpadesc",)g(POINTER\(ARRAYDESC\)\),)1161 581 y(\("hreftype",)g(HREFTYPE\)])444 764 y(class)h(TYPEDESC\(Structure\):) 623 855 y(_fields_)g(=)g([\("u",)g(_U\),)1161 946 y(\("vt",)g (VARTYPE\)])623 1129 y(_anonymous_)f(=)i(\("u",\))208 1319 y FN(The)26 b FJ(TYPEDESC)f FN(structure)g(describes)h(a)h(COM)g (data)f(type,)h(the)f FJ(vt)h FN(\002eld)f(speci\002es)h(which)f(one)g (of)g(the)g(union)f(\002elds)i(is)208 1418 y(v)n(alid.)i(Since)22 b(the)g FJ(u)g FN(\002eld)h(is)f(de\002ned)f(as)i(anon)o(ymous)c (\002eld,)j(it)h(is)g(no)n(w)e(possible)h(to)g(access)g(the)g(members)f (directly)g(of)n(f)h(the)208 1518 y(TYPEDESC)17 b(instance.)24 b FJ(td.lptdesc)16 b FN(and)h FJ(td.u.lptdesc)f FN(are)i(equi)n(v)n (alent,)e(b)n(ut)h(the)h(former)e(is)i(f)o(aster)g(since)g(it)g(does) 208 1617 y(not)h(need)h(to)g(create)g(a)h(temporary)d(union)h (instance:)444 1842 y FA(td)44 b(=)h(TYPEDESC\(\))444 1933 y(td.vt)f(=)g(VT_PTR)444 2024 y(td.lptdesc)f(=)i (POINTER\(some_type\))444 2116 y(td.u.lptdesc)e(=)h (POINTER\(some_type\))0 2319 y FN(It)21 b(is)h(possible)f(to)h (de\002ned)e(sub-subclasses)g(of)h(structures,)g(the)o(y)f(inherit)g (the)i(\002elds)f(of)g(the)g(base)g(class.)29 b(If)21 b(the)g(subclass)h(de\002nition)0 2419 y(has)e(a)h(separate)f FJ(_fields_)f FN(v)n(ariable,)g(the)h(\002elds)h(speci\002ed)f(in)g (this)h(are)f(appended)e(to)i(the)g(\002elds)h(of)f(the)g(base)g (class.)0 2566 y(Structure)27 b(and)h(union)f(constructors)g(accept)h (both)f(positional)h(and)g(k)o(e)o(yw)o(ord)e(ar)o(guments.)48 b(Positional)28 b(ar)o(guments)e(are)i(used)g(to)0 2665 y(initialize)18 b(member)e(\002elds)j(in)f(the)g(same)g(order)e(as)j (the)o(y)e(are)h(appear)f(in)h FJ(_fields_)p FN(.)23 b(K)n(e)o(yw)o(ord)16 b(ar)o(guments)g(in)i(the)g(constructor)e(are)0 2765 y(interpreted)23 b(as)i(attrib)n(ute)f(assignments,)h(so)g(the)o (y)f(will)h(initialize)g FJ(_fields_)f FN(with)g(the)h(same)g(name,)g (or)f(create)g(ne)n(w)h(attrib)n(utes)0 2864 y(for)20 b(names)f(not)h(present)g(in)g FJ(_fields_)p FN(.)0 3133 y FI(Arr)o(a)n(ys)i(and)h(pointers)0 3336 y FN(Not)d(yet)g(written)g(-) h(please)f(see)h(section)f(14.14.1,)d(pointers)j(and)f(section)h (14.14.1,)e(arrays)h(in)i(the)f(tutorial.)p 0 5549 3901 4 v 0 5649 a FI(534)1931 b(Chapter)23 b(14.)52 b(Gener)q(ic)23 b(Oper)o(ating)h(System)f(Ser)r(vices)p eop end %%Page: 535 547 TeXDict begin 535 546 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3402 427 y FG(FIFTEEN)p 0 515 V 567 978 a FT(Optional)56 b(Oper)n(ating)h (System)h(Ser)6 b(vices)0 1468 y FN(The)26 b(modules)f(described)f(in)i (this)h(chapter)e(pro)o(vide)f(interf)o(aces)h(to)h(operating)e(system) i(features)g(that)g(are)g(a)n(v)n(ailable)f(on)h(selected)0 1568 y(operating)19 b(systems)i(only)-5 b(.)26 b(The)21 b(interf)o(aces)f(are)h(generally)e(modeled)h(after)g(the)j(U)t FH(N)t(I)t(X)h FN(or)d(C)g(interf)o(aces)g(b)n(ut)g(the)o(y)f(are)h(a)n (v)n(ailable)f(on)0 1667 y(some)g(other)f(systems)i(as)g(well)g(\(e.g.) j(W)m(indo)n(ws)c(or)f(NT\).)h(Here')-5 b(s)21 b(an)f(o)o(v)o(ervie)n (w:)50 1810 y FD(select)547 b FN(W)-7 b(ait)21 b(for)f(I/O)g (completion)e(on)i(multiple)g(streams.)50 1910 y FD(thread)547 b FN(Create)20 b(multiple)g(threads)f(of)h(control)f(within)h(one)g (interpreter)-5 b(.)50 2010 y FD(threading)397 b FN(Higher)n(-le)n(v)o (el)18 b(threading)g(interf)o(ace.)50 2109 y FD(dummy_thread)247 b FN(Drop-in)18 b(replacement)h(for)g(the)h FJ(thread)g FN(module.)50 2209 y FD(dummy_threading)97 b FN(Drop-in)18 b(replacement)h(for)g(the)h FJ(threading)g FN(module.)50 2309 y FD(mmap)647 b FN(Interf)o(ace)19 b(to)h(memory-mapped)c(\002les) 21 b(for)h(U)t FH(N)t(I)t(X)h FN(and)c(W)m(indo)n(ws.)50 2408 y FD(readline)447 b FN(GNU)20 b(readline)f(support)g(for)h (Python.)50 2508 y FD(rlcompleter)297 b FN(Python)19 b(identi\002er)g(completion,)f(suitable)i(for)g(the)g(GNU)h(readline)e (library)-5 b(.)0 2812 y FE(15.1)121 b Fx(select)32 b FE(\227)h(W)-5 b(aiting)34 b(f)l(or)g(I/O)g(completion)0 3045 y FN(This)19 b(module)e(pro)o(vides)f(access)j(to)g(the)f FJ(select\(\))f FN(and)h FJ(poll\(\))g FN(functions)f(a)n(v)n(ailable)h (in)g(most)h(operating)d(systems.)25 b(Note)18 b(that)0 3145 y(on)j(W)m(indo)n(ws,)f(it)i(only)e(w)o(orks)g(for)h(sock)o(ets;)g (on)g(other)f(operating)f(systems,)i(it)h(also)f(w)o(orks)g(for)f (other)g(\002le)i(types)f(\(in)g(particular)m(,)e(on)2 3244 y(U)t FH(N)t(I)t(X)r FN(,)27 b(it)f(w)o(orks)f(on)g(pipes\).)39 b(It)26 b(cannot)e(be)h(used)g(on)g(re)o(gular)f(\002les)i(to)f (determine)f(whether)g(a)i(\002le)g(has)f(gro)n(wn)f(since)i(it)g(w)o (as)g(last)0 3344 y(read.)0 3491 y(The)20 b(module)f(de\002nes)h(the)g (follo)n(wing:)0 3638 y FL(exception)f FD(error)208 3737 y FN(The)f(e)o(xception)f(raised)h(when)g(an)h(error)f(occurs.)23 b(The)c(accompan)o(ying)c(v)n(alue)j(is)h(a)h(pair)e(containing)f(the)h (numeric)g(error)f(code)208 3837 y(from)i FJ(errno)h FN(and)f(the)h(corresponding)d(string,)j(as)h(w)o(ould)e(be)h(printed)f (by)h(the)g(C)h(function)e FJ(perror\(\))p FN(.)0 3984 y FD(poll)p FJ(\(\))208 4083 y FN(\(Not)f(supported)e(by)i(all)h (operating)e(systems.\))24 b(Returns)19 b(a)g(polling)e(object,)h (which)g(supports)f(re)o(gistering)g(and)h(unre)o(gistering)208 4183 y(\002le)26 b(descriptors,)h(and)e(then)h(polling)f(them)g(for)h (I/O)g(e)n(v)o(ents;)j(see)e(section)e(15.1.1)g(belo)n(w)g(for)h(the)g (methods)f(supported)f(by)208 4283 y(polling)19 b(objects.)0 4429 y FD(select)p FJ(\()p FK(iwtd,)g(owtd,)h(e)o(wtd)r FC([)p FK(,)g(timeout)13 b FC(])p FJ(\))208 4529 y FN(This)18 b(is)i(a)f(straightforw)o(ard)e(interf)o(ace)h(to)h(the)h(U)t FH(N)t(I)t(X)i FJ(select\(\))c FN(system)h(call.)25 b(The)18 b(\002rst)i(three)e(ar)o(guments)f(are)h(sequences)208 4629 y(of)g(`w)o(aitable)h(objects':)24 b(either)19 b(inte)o(gers)g (representing)e(\002le)j(descriptors)e(or)h(objects)g(with)g(a)h (parameterless)e(method)g(named)208 4728 y FJ(fileno\(\))25 b FN(returning)f(such)h(an)h(inte)o(ger)-5 b(.)42 b(The)26 b(three)f(sequences)g(of)h(w)o(aitable)g(objects)g(are)g(for)f(input,)h (output)f(and)h(`e)o(x-)208 4828 y(ceptional)d(conditions',)g(respecti) n(v)o(ely)-5 b(.)35 b(Empty)23 b(sequences)g(are)h(allo)n(wed,)g(b)n (ut)h(acceptance)d(of)i(three)g(empty)f(sequences)h(is)208 4928 y(platform-dependent.)c(\(It)f(is)h(kno)n(wn)e(to)i(w)o(ork)e(on)j (U)t FH(N)t(I)t(X)i FN(b)n(ut)c(not)g(on)g(W)m(indo)n(ws.\))24 b(The)19 b(optional)f FK(timeout)j FN(ar)o(gument)c(speci-)208 5027 y(\002es)j(a)f(time-out)f(as)i(a)g(\003oating)e(point)g(number)g (in)h(seconds.)24 b(When)19 b(the)g FK(timeout)h FN(ar)o(gument)d(is)j (omitted)f(the)g(function)e(blocks)208 5127 y(until)j(at)g(least)h(one) f(\002le)h(descriptor)d(is)k(ready)-5 b(.)23 b(A)e(time-out)e(v)n(alue) g(of)h(zero)g(speci\002es)h(a)f(poll)g(and)g(ne)n(v)o(er)f(blocks.)208 5260 y(The)27 b(return)g(v)n(alue)h(is)h(a)g(triple)f(of)f(lists)j(of)e (objects)g(that)g(are)g(ready:)40 b(subsets)29 b(of)f(the)g(\002rst)h (three)f(ar)o(guments.)47 b(When)28 b(the)208 5359 y(time-out)19 b(is)i(reached)e(without)g(a)i(\002le)g(descriptor)d(becoming)h(ready) -5 b(,)18 b(three)i(empty)f(lists)j(are)e(returned.)p 0 5549 3901 4 v 3762 5649 a FI(535)p eop end %%Page: 536 548 TeXDict begin 536 547 bop 208 83 a FN(Among)30 b(the)h(acceptable)g (object)g(types)g(in)h(the)f(sequences)g(are)g(Python)g(\002le)h (objects)f(\(e.g.)59 b FJ(sys.stdin)p FN(,)33 b(or)e(objects)208 183 y(returned)c(by)i FJ(open\(\))f FN(or)h FJ(os.popen\(\))p FN(\),)g(sock)o(et)g(objects)g(returned)e(by)i FJ(socket.socket\(\))p FN(.)102 b(Y)-9 b(ou)29 b(may)f(also)208 282 y(de\002ne)c(a)h FK(wr)o(apper)f FN(class)i(yourself,)e(as)i(long)e(as)h(it)h(has)f(an)f (appropriate)f FJ(fileno\(\))h FN(method)f(\(that)h(really)h(returns)f (a)h(\002le)208 382 y(descriptor)m(,)d(not)h(just)h(a)g(random)e(inte)o (ger\).)34 b FL(Note:)d FN(File)25 b(objects)e(on)g(W)m(indo)n(ws)g (are)h(not)f(acceptable,)g(b)n(ut)h(sock)o(ets)f(are.)36 b(On)208 482 y(W)m(indo)n(ws,)29 b(the)g(underlying)d FJ(select\(\))h FN(function)g(is)j(pro)o(vided)c(by)i(the)g(W)m(inSock) g(library)-5 b(,)29 b(and)f(does)g(not)g(handle)g(\002le)208 581 y(descriptors)19 b(that)h(don')o(t)e(originate)h(from)g(W)m (inSock.)0 866 y Fv(15.1.1)101 b(P)-5 b(olling)29 b(Objects)0 1069 y FN(The)16 b FJ(poll\(\))g FN(system)h(call,)g(supported)e(on)h (most)i(U)t FH(N)t(I)t(X)i FN(systems,)d(pro)o(vides)e(better)h (scalability)g(for)g(netw)o(ork)f(serv)o(ers)h(that)h(service)0 1169 y(man)o(y)-5 b(,)30 b(man)o(y)f(clients)h(at)g(the)f(same)h(time.) 54 b FJ(poll\(\))29 b FN(scales)h(better)f(because)g(the)h(system)g (call)g(only)f(requires)f(listing)i(the)g(\002le)0 1268 y(descriptors)22 b(of)g(interest,)h(while)g FJ(select\(\))f FN(b)n(uilds)g(a)h(bitmap,)g(turns)f(on)g(bits)i(for)e(the)g(fds)h(of)g (interest,)g(and)f(then)g(afterw)o(ard)g(the)0 1368 y(whole)e(bitmap)g (has)h(to)f(be)h(linearly)f(scanned)f(again.)25 b FJ(select\(\))20 b FN(is)h(O\(highest)f(\002le)h(descriptor\),)e(while)h FJ(poll\(\))g FN(is)i(O\(number)0 1467 y(of)e(\002le)h(descriptors\).)0 1614 y FD(register)p FJ(\()p FK(fd)r FC([)p FK(,)d(e)o(ventmask)13 b FC(])p FJ(\))208 1714 y FN(Re)o(gister)23 b(a)h(\002le)g(descriptor)e (with)h(the)h(polling)e(object.)34 b(Future)22 b(calls)i(to)g(the)f FJ(poll\(\))g FN(method)f(will)i(then)f(check)g(whether)208 1814 y(the)17 b(\002le)g(descriptor)f(has)h(an)o(y)f(pending)f(I/O)i(e) n(v)o(ents.)24 b FK(fd)19 b FN(can)e(be)g(either)f(an)h(inte)o(ger)m(,) f(or)h(an)g(object)f(with)h(a)h FJ(fileno\(\))e FN(method)208 1913 y(that)k(returns)f(an)h(inte)o(ger)-5 b(.)25 b(File)20 b(objects)g(implement)f FJ(fileno\(\))p FN(,)g(so)i(the)o(y)e(can)h (also)h(be)f(used)g(as)h(the)f(ar)o(gument.)208 2046 y FK(e)o(ventmask)g FN(is)h(an)e(optional)g(bitmask)g(describing)f(the) i(type)f(of)h(e)n(v)o(ents)f(you)g(w)o(ant)h(to)g(check)f(for)m(,)f (and)h(can)h(be)g(a)g(combination)208 2146 y(of)h(the)h(constants)f FJ(POLLIN)p FN(,)g FJ(POLLPRI)p FN(,)f(and)i FJ(POLLOUT)p FN(,)e(described)h(in)g(the)h(table)g(belo)n(w)-5 b(.)28 b(If)22 b(not)f(speci\002ed,)h(the)f(def)o(ault)208 2245 y(v)n(alue)e(used)h(will)h(check)e(for)h(all)h(3)f(types)g(of)g(e)n(v)o (ents.)1138 2375 y FL(Constant)p 1585 2404 4 100 v 174 w(Meaning)p 1088 2408 1932 4 v 1138 2477 a FJ(POLLIN)p 1585 2507 4 100 v 198 w FN(There)g(is)h(data)f(to)g(read)1138 2577 y FJ(POLLPRI)p 1585 2607 V 148 w FN(There)g(is)h(ur)o(gent)d(data) i(to)g(read)1138 2677 y FJ(POLLOUT)p 1585 2707 V 148 w FN(Ready)g(for)g(output:)k(writing)19 b(will)i(not)f(block)1138 2776 y FJ(POLLERR)p 1585 2806 V 148 w FN(Error)f(condition)g(of)g(some) h(sort)1138 2876 y FJ(POLLHUP)p 1585 2906 V 148 w FN(Hung)f(up)1138 2976 y FJ(POLLNVAL)p 1585 3005 V 98 w FN(In)m(v)n(alid)g(request:)24 b(descriptor)19 b(not)h(open)208 3104 y(Re)o(gistering)j(a)i(\002le)g (descriptor)f(that')-5 b(s)25 b(already)e(re)o(gistered)g(is)j(not)e (an)g(error)m(,)g(and)g(has)h(the)g(same)f(ef)n(fect)g(as)i(re)o (gistering)d(the)208 3203 y(descriptor)18 b(e)o(xactly)i(once.)0 3350 y FD(unregister)p FJ(\()p FK(fd)r FJ(\))208 3450 y FN(Remo)o(v)o(e)j(a)j(\002le)f(descriptor)f(being)g(track)o(ed)g(by)g (a)i(polling)e(object.)38 b(Just)26 b(lik)o(e)f(the)g FJ(register\(\))f FN(method,)h FK(fd)i FN(can)e(be)g(an)208 3549 y(inte)o(ger)19 b(or)h(an)g(object)f(with)i(a)f FJ(fileno\(\))g FN(method)e(that)j(returns)e(an)h(inte)o(ger)-5 b(.)208 3682 y(Attempting)19 b(to)h(remo)o(v)o(e)e(a)j(\002le)g (descriptor)d(that)j(w)o(as)g(ne)n(v)o(er)e(re)o(gistered)f(causes)j(a) f FJ(KeyError)g FN(e)o(xception)e(to)i(be)g(raised.)0 3829 y FD(poll)p FJ(\()p FC([)p FK(timeout)13 b FC(])p FJ(\))208 3929 y FN(Polls)19 b(the)g(set)g(of)g(re)o(gistered)e(\002le) i(descriptors,)f(and)g(returns)g(a)h(possibly-empty)d(list)k (containing)d FJ(\()p FK(fd)r FJ(,)49 b FK(e)o(vent)q FJ(\))18 b FN(2-tuples)g(for)208 4028 y(the)f(descriptors)g(that)g(ha)n (v)o(e)g(e)n(v)o(ents)g(or)h(errors)e(to)i(report.)23 b FK(fd)d FN(is)f(the)e(\002le)h(descriptor)m(,)f(and)g FK(e)o(vent)h FN(is)h(a)f(bitmask)f(with)h(bits)g(set)g(for)208 4128 y(the)24 b(reported)e(e)n(v)o(ents)i(for)g(that)g(descriptor)f (\227)i FJ(POLLIN)f FN(for)g(w)o(aiting)g(input,)g FJ(POLLOUT)g FN(to)g(indicate)g(that)h(the)f(descriptor)208 4228 y(can)g(be)h (written)f(to,)i(and)e(so)h(forth.)37 b(An)24 b(empty)g(list)i (indicates)e(that)h(the)g(call)g(timed)f(out)g(and)g(no)h(\002le)g (descriptors)e(had)h(an)o(y)208 4327 y(e)n(v)o(ents)18 b(to)g(report.)24 b(If)18 b FK(timeout)i FN(is)g(gi)n(v)o(en,)d(it)j (speci\002es)f(the)g(length)e(of)i(time)g(in)g(milliseconds)f(which)g (the)g(system)h(will)h(w)o(ait)f(for)208 4427 y(e)n(v)o(ents)j(before)g (returning.)32 b(If)23 b FK(timeout)h FN(is)g(omitted,)f(ne)o(gati)n(v) o(e,)f(or)h FJ(None)p FN(,)g(the)g(call)h(will)g(block)e(until)h(there) g(is)h(an)f(e)n(v)o(ent)f(for)208 4526 y(this)e(poll)g(object.)0 4854 y FE(15.2)121 b Fx(thread)32 b FE(\227)h(Multiple)g(threads)i(of)f (control)0 5087 y FN(This)25 b(module)e(pro)o(vides)g(lo)n(w-le)n(v)o (el)g(primiti)n(v)o(es)h(for)g(w)o(orking)f(with)h(multiple)g(threads)g (\(a.k.a.)f FK(light-weight)h(pr)l(ocesses)h FN(or)f FK(tasks)p FN(\))0 5186 y(\227)j(multiple)e(threads)h(of)g(control)f (sharing)g(their)h(global)f(data)h(space.)43 b(F)o(or)26 b(synchronization,)e(simple)i(locks)g(\(a.k.a.)f FK(mute)n(xes)i FN(or)0 5286 y FK(binary)20 b(semaphor)m(es)p FN(\))e(are)j(pro)o (vided.)p 0 5549 3901 4 v 0 5649 a FI(536)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 537 549 TeXDict begin 537 548 bop 0 83 a FN(The)24 b(module)f(is)j(optional.)36 b(It)25 b(is)h(supported)c(on)i(W)m(indo)n(ws,)h(Linux,)f(SGI)h(IRIX,)g (Solaris)f(2.x,)h(as)g(well)g(as)g(on)g(systems)g(that)f(ha)n(v)o(e)0 183 y(a)f(POSIX)h(thread)e(\(a.k.a.)32 b(\223pthread\224\))21 b(implementation.)31 b(F)o(or)22 b(systems)i(lacking)e(the)h FJ(thread)f FN(module,)g(the)h FJ(dummy_thread)0 282 y FN(module)c(is)i(a)n(v)n(ailable.)j(It)d(duplicates)e(this)i(module') -5 b(s)19 b(interf)o(ace)h(and)f(can)h(be)g(used)g(as)h(a)g(drop-in)d (replacement.)0 429 y(It)i(de\002nes)g(the)h(follo)n(wing)d(constant)i (and)f(functions:)0 576 y FL(exception)g FD(error)208 676 y FN(Raised)h(on)g(thread-speci\002c)f(errors.)0 823 y FD(LockType)208 922 y FN(This)h(is)h(the)f(type)g(of)g(lock)g (objects.)0 1069 y FD(start_new_thread)p FJ(\()p FK(function,)15 b(ar)m(gs)p FC([)p FK(,)20 b(kwar)m(gs)12 b FC(])p FJ(\))208 1169 y FN(Start)19 b(a)h(ne)n(w)f(thread)g(and)g(return)f(its)i (identi\002er)-5 b(.)25 b(The)19 b(thread)f(e)o(x)o(ecutes)h(the)g (function)f FK(function)g FN(with)h(the)h(ar)o(gument)d(list)j FK(ar)m(gs)208 1268 y FN(\(which)f(must)h(be)g(a)g(tuple\).)k(The)c (optional)f FK(kwar)m(gs)h FN(ar)o(gument)e(speci\002es)i(a)h (dictionary)d(of)i(k)o(e)o(yw)o(ord)e(ar)o(guments.)23 b(When)d(the)208 1368 y(function)i(returns,)j(the)f(thread)g(silently)g (e)o(xits.)38 b(When)24 b(the)h(function)d(terminates)i(with)h(an)f (unhandled)e(e)o(xception,)i(a)g(stack)208 1468 y(trace)c(is)h(printed) e(and)g(then)h(the)g(thread)f(e)o(xits)i(\(b)n(ut)f(other)f(threads)h (continue)e(to)j(run\).)0 1614 y FD(interrupt_main)p FJ(\(\))208 1714 y FN(Raise)k(a)g FJ(KeyboardInterrupt)c FN(e)o(xception)i(in)h(the)h(main)f(thread.)36 b(A)25 b(subthread)d(can)j(use)f(this)h(function)e(to)h(interrupt)208 1814 y(the)c(main)g(thread.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1961 y FD(exit)p FJ(\(\))208 2060 y FN(Raise)i(the)f FJ(SystemExit)f FN(e)o(xception.)k(When)d(not)g(caught,)f(this)h(will)h (cause)f(the)h(thread)e(to)h(e)o(xit)g(silently)-5 b(.)0 2207 y FD(allocate_lock)p FJ(\(\))208 2307 y FN(Return)19 b(a)i(ne)n(w)f(lock)g(object.)k(Methods)19 b(of)h(locks)g(are)g (described)f(belo)n(w)-5 b(.)24 b(The)c(lock)g(is)h(initially)f(unlock) o(ed.)0 2454 y FD(get_ident)p FJ(\(\))208 2553 y FN(Return)j(the)h (`thread)e(identi\002er')h(of)h(the)f(current)g(thread.)35 b(This)24 b(is)g(a)h(nonzero)d(inte)o(ger)-5 b(.)35 b(Its)24 b(v)n(alue)f(has)h(no)g(direct)f(meaning;)208 2653 y(it)g(is)g (intended)e(as)i(a)g(magic)e(cookie)h(to)g(be)h(used)f(e.g.)31 b(to)22 b(inde)o(x)f(a)i(dictionary)e(of)h(thread-speci\002c)f(data.)31 b(Thread)21 b(identi\002ers)208 2752 y(may)e(be)h(rec)o(ycled)f(when)h (a)g(thread)g(e)o(xits)g(and)g(another)e(thread)h(is)j(created.)0 2899 y FD(stack_size)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 2999 y FN(Return)18 b(the)h(thread)f(stack)h(size)g(used)g (when)f(creating)g(ne)n(w)h(threads.)24 b(The)18 b(optional)g FK(size)i FN(ar)o(gument)d(speci\002es)i(the)g(stack)g(size)208 3099 y(to)27 b(be)f(used)h(for)f(subsequently)f(created)h(threads,)h (and)g(must)f(be)h(0)g(\(use)g(platform)e(or)i(con\002gured)d(def)o (ault\))i(or)g(a)h(positi)n(v)o(e)208 3198 y(inte)o(ger)h(v)n(alue)g (of)h(at)h(least)g(32,768)d(\(32kB\).)h(If)h(changing)f(the)h(thread)f (stack)i(size)g(is)g(unsupported,)e(a)i FJ(ThreadError)208 3298 y FN(is)i(raised.)57 b(If)31 b(the)h(speci\002ed)e(stack)i(size)g (is)g(in)m(v)n(alid,)g(a)g FJ(ValueError)e FN(is)i(raised)f(and)f(the)i (stack)f(size)h(is)g(unmodi\002ed.)208 3397 y(32kB)19 b(is)j(currently)c(the)j(minimum)e(supported)f(stack)j(size)g(v)n(alue) e(to)i(guarantee)d(suf)n(\002cient)i(stack)h(space)f(for)g(the)g (interpreter)208 3497 y(itself.)32 b(Note)23 b(that)g(some)f(platforms) g(may)g(ha)n(v)o(e)g(particular)f(restrictions)h(on)h(v)n(alues)f(for)g (the)g(stack)h(size,)h(such)e(as)i(requiring)208 3597 y(a)h(minimum)f(stack)h(size)h(\277)g(32kB)f(or)g(requiring)e (allocation)h(in)h(multiples)g(of)g(the)g(system)h(memory)d(page)i (size)h(-)f(platform)208 3696 y(documentation)16 b(should)j(be)g (referred)f(to)h(for)g(more)g(information)e(\(4kB)i(pages)g(are)h (common;)e(using)h(multiples)g(of)g(4096)f(for)208 3796 y(the)24 b(stack)g(size)h(is)g(the)g(suggested)e(approach)f(in)j(the)f (absence)g(of)g(more)f(speci\002c)i(information\).)34 b(A)-6 b(v)n(ailability:)32 b(W)m(indo)n(ws,)208 3896 y(systems)20 b(with)h(POSIX)f(threads.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 4042 y(Lock)g(objects)h(ha)n(v)o(e)g(the)g (follo)n(wing)f(methods:)0 4189 y FD(acquire)p FJ(\()p FC([)p FK(wait\003a)o(g)12 b FC(])p FJ(\))208 4289 y FN(W)m(ithout)26 b(the)h(optional)e(ar)o(gument,)h(this)i(method)d (acquires)h(the)h(lock)g(unconditionally)-5 b(,)24 b(if)j(necessary)g (w)o(aiting)f(until)h(it)h(is)208 4389 y(released)21 b(by)g(another)g(thread)f(\(only)h(one)g(thread)g(at)h(a)g(time)g(can)g (acquire)e(a)j(lock)e(\227)h(that')-5 b(s)23 b(their)e(reason)g(for)g (e)o(xistence\).)29 b(If)208 4488 y(the)23 b(inte)o(ger)e FK(wait\003a)o(g)i FN(ar)o(gument)d(is)k(present,)f(the)g(action)f (depends)g(on)g(its)i(v)n(alue:)30 b(if)23 b(it)h(is)g(zero,)f(the)g (lock)f(is)i(only)e(acquired)208 4588 y(if)e(it)h(can)g(be)f(acquired)f (immediately)g(without)g(w)o(aiting,)h(while)h(if)g(it)g(is)g(nonzero,) d(the)j(lock)f(is)h(acquired)e(unconditionally)e(as)208 4687 y(before.)23 b(The)d(return)f(v)n(alue)g(is)j FJ(True)e FN(if)g(the)g(lock)g(is)h(acquired)e(successfully)-5 b(,)19 b FJ(False)g FN(if)i(not.)0 4834 y FD(release)p FJ(\(\))208 4934 y FN(Releases)g(the)f(lock.)k(The)c(lock)g(must)g(ha)n (v)o(e)g(been)f(acquired)g(earlier)m(,)g(b)n(ut)h(not)g(necessarily)g (by)g(the)g(same)g(thread.)0 5081 y FD(locked)p FJ(\(\))208 5180 y FN(Return)f(the)i(status)f(of)g(the)g(lock:)g FJ(True)g FN(if)h(it)g(has)f(been)g(acquired)e(by)i(some)g(thread,)f FJ(False)h FN(if)g(not.)0 5327 y(In)g(addition)f(to)h(these)h(methods,) d(lock)i(objects)g(can)g(also)h(be)f(used)g(via)g(the)g FJ(with)g FN(statement,)g(e.g.:)p 0 5549 3901 4 v 0 5649 a FI(15.2.)52 b FJ(thread)22 b FI(\227)h(Multiple)i(threads)e(of)h (control)2147 b(537)p eop end %%Page: 538 550 TeXDict begin 538 549 bop 236 174 a FA(from)44 b(__future__)g(import)f (with_statement)236 266 y(import)h(thread)236 448 y(a_lock)g(=)h (thread.allocate_lock\(\))236 631 y(with)f(a_lock:)416 722 y(print)g("a_lock)f(is)i(locked)f(while)g(this)g(executes")0 1009 y FL(Ca)n(v)o(eats:)125 1239 y FM(\017)d FN(Threads)21 b(interact)h(strangely)g(with)h(interrupts:)29 b(the)22 b FJ(KeyboardInterrupt)f FN(e)o(xception)f(will)k(be)e(recei)n(v)o(ed)f (by)i(an)f(arbi-)208 1339 y(trary)d(thread.)24 b(\(When)c(the)g FJ(signal)g FN(module)e(is)j(a)n(v)n(ailable,)f(interrupts)f(al)o(w)o (ays)i(go)e(to)i(the)f(main)g(thread.\))125 1505 y FM(\017)41 b FN(Calling)20 b FJ(sys.exit\(\))f FN(or)h(raising)f(the)i FJ(SystemExit)d FN(e)o(xception)h(is)i(equi)n(v)n(alent)d(to)j(calling) e FJ(exit\(\))p FN(.)125 1671 y FM(\017)41 b FN(Not)27 b(all)g(b)n(uilt-in)f(functions)g(that)h(may)f(block)g(w)o(aiting)h (for)f(I/O)h(allo)n(w)g(other)f(threads)g(to)h(run.)45 b(\(The)26 b(most)h(popular)e(ones)208 1771 y(\()p FJ(time.sleep\(\))p FN(,)17 b FK(\002le)p FJ(.read\(\))p FN(,)i FJ(select.select\(\))p FN(\))f(w)o(ork)h(as)i(e)o(xpected.\))125 1937 y FM(\017)41 b FN(It)19 b(is)h(not)f(possible)f(to)i(interrupt)d(the)i FJ(acquire\(\))f FN(method)g(on)g(a)i(lock)f(\227)g(the)g FJ(KeyboardInterrupt)e FN(e)o(xception)g(will)208 2036 y(happen)h(after)i(the)g(lock)g(has)g(been)g(acquired.)125 2202 y FM(\017)41 b FN(When)27 b(the)i(main)e(thread)g(e)o(xits,)j(it)f (is)g(system)f(de\002ned)f(whether)g(the)h(other)g(threads)f(survi)n(v) o(e.)47 b(On)28 b(SGI)h(IRIX)f(using)g(the)208 2302 y(nati)n(v)o(e)c (thread)g(implementation,)g(the)o(y)h(survi)n(v)o(e.)39 b(On)25 b(most)g(other)f(systems,)j(the)o(y)e(are)g(killed)g(without)f (e)o(x)o(ecuting)f FJ(try)j FN(...)208 2402 y FJ(finally)19 b FN(clauses)i(or)e(e)o(x)o(ecuting)f(object)i(destructors.)125 2568 y FM(\017)41 b FN(When)23 b(the)g(main)g(thread)f(e)o(xits,)i(it)f (does)g(not)g(do)g(an)o(y)f(of)h(its)h(usual)f(cleanup)f(\(e)o(xcept)g (that)i FJ(try)f FN(...)34 b FJ(finally)22 b FN(clauses)i(are)208 2667 y(honored\),)17 b(and)i(the)i(standard)e(I/O)h(\002les)h(are)f (not)g(\003ushed.)0 3078 y FE(15.3)121 b Fx(threading)31 b FE(\227)i(Higher-le)l(v)m(el)h(threading)i(interf)l(ace)0 3311 y FN(This)20 b(module)f(constructs)h(higher)n(-le)n(v)o(el)e (threading)g(interf)o(aces)h(on)h(top)g(of)g(the)g(lo)n(wer)g(le)n(v)o (el)g FJ(thread)f FN(module.)0 3457 y(The)h FJ(dummy_threading)e FN(module)h(is)i(pro)o(vided)c(for)j(situations)g(where)f FJ(threading)g FN(cannot)h(be)g(used)g(because)f FJ(thread)h FN(is)0 3557 y(missing.)0 3704 y(This)g(module)f(de\002nes)h(the)g (follo)n(wing)f(functions)g(and)g(objects:)0 3851 y FD(activeCount)p FJ(\(\))208 3950 y FN(Return)28 b(the)h(number)f(of)h FJ(Thread)f FN(objects)h(currently)f(ali)n(v)o(e.)51 b(The)29 b(returned)f(count)g(is)i(equal)f(to)g(the)g(length)f(of)h (the)g(list)208 4050 y(returned)18 b(by)i FJ(enumerate\(\))p FN(.)0 4197 y FD(Condition)p FJ(\(\))208 4297 y FN(A)f(f)o(actory)f (function)f(that)i(returns)f(a)i(ne)n(w)e(condition)f(v)n(ariable)h (object.)24 b(A)c(condition)d(v)n(ariable)h(allo)n(ws)h(one)f(or)h (more)f(threads)208 4396 y(to)i(w)o(ait)h(until)f(the)o(y)f(are)h (noti\002ed)g(by)g(another)e(thread.)0 4543 y FD(currentThread)p FJ(\(\))208 4643 y FN(Return)29 b(the)i(current)e FJ(Thread)g FN(object,)j(corresponding)27 b(to)k(the)f(caller')-5 b(s)30 b(thread)g(of)g(control.)54 b(If)30 b(the)g(caller')-5 b(s)31 b(thread)e(of)208 4742 y(control)21 b(w)o(as)i(not)e(created)h (through)e(the)i FJ(threading)f FN(module,)g(a)i(dummy)d(thread)i (object)f(with)i(limited)f(functionality)e(is)208 4842 y(returned.)0 4989 y FD(enumerate)p FJ(\(\))208 5088 y FN(Return)h(a)i(list)h(of)e(all)h FJ(Thread)e FN(objects)i(currently) d(ali)n(v)o(e.)31 b(The)22 b(list)i(includes)d(daemonic)g(threads,)h (dummy)e(thread)i(objects)208 5188 y(created)c(by)h FJ (currentThread\(\))p FN(,)f(and)h(the)g(main)g(thread.)24 b(It)c(e)o(xcludes)e(terminated)h(threads)f(and)h(threads)g(that)h(ha)n (v)o(e)f(not)208 5288 y(yet)h(been)f(started.)p 0 5549 3901 4 v 0 5649 a FI(538)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 539 551 TeXDict begin 539 550 bop 0 83 a FD(Event)p FJ(\(\))208 183 y FN(A)28 b(f)o(actory)e(function)g(that)h(returns)g(a)h(ne)n(w)f (e)n(v)o(ent)g(object.)47 b(An)27 b(e)n(v)o(ent)g(manages)f(a)i(\003ag) g(that)g(can)f(be)h(set)g(to)g(true)f(with)h(the)208 282 y FJ(set\(\))18 b FN(method)f(and)h(reset)h(to)g(f)o(alse)g(with)g (the)g FJ(clear\(\))f FN(method.)23 b(The)18 b FJ(wait\(\))g FN(method)g(blocks)g(until)g(the)h(\003ag)g(is)g(true.)0 429 y FL(class)i FD(local)208 529 y FN(A)d(class)g(that)g(represents)e (thread-local)g(data.)24 b(Thread-local)15 b(data)j(are)f(data)g(whose) h(v)n(alues)f(are)g(thread)g(speci\002c.)24 b(T)-7 b(o)18 b(manage)208 628 y(thread-local)g(data,)i(just)g(create)g(an)g (instance)g(of)g FJ(local)g FN(\(or)g(a)g(subclass\))g(and)g(store)g (attrib)n(utes)g(on)g(it:)444 850 y FA(mydata)44 b(=)g (threading.local\(\))444 941 y(mydata.x)f(=)i(1)208 1128 y FN(The)19 b(instance')-5 b(s)21 b(v)n(alues)e(will)i(be)f(dif)n (ferent)f(for)h(separate)f(threads.)208 1258 y(F)o(or)g(more)h(details) g(and)g(e)o(xtensi)n(v)o(e)f(e)o(xamples,)g(see)h(the)g(documentation)e (string)i(of)g(the)g FJ(_threading_local)d FN(module.)208 1388 y(Ne)n(w)j(in)g(v)o(ersion)f(2.4.)0 1535 y FD(Lock)p FJ(\(\))208 1635 y FN(A)j(f)o(actory)f(function)f(that)i(returns)f(a)i (ne)n(w)f(primiti)n(v)o(e)e(lock)i(object.)29 b(Once)22 b(a)h(thread)e(has)h(acquired)e(it,)j(subsequent)e(attempts)208 1734 y(to)f(acquire)f(it)i(block,)e(until)h(it)h(is)g(released;)f(an)o (y)f(thread)g(may)h(release)g(it.)0 1881 y FD(RLock)p FJ(\(\))208 1981 y FN(A)h(f)o(actory)e(function)g(that)h(returns)g(a)h (ne)n(w)f(reentrant)f(lock)h(object.)25 b(A)c(reentrant)e(lock)h(must)h (be)f(released)g(by)g(the)h(thread)e(that)208 2081 y(acquired)f(it.)25 b(Once)19 b(a)h(thread)f(has)h(acquired)e(a)i(reentrant)e(lock,)h(the)h (same)f(thread)g(may)g(acquire)g(it)h(again)e(without)h(blocking;)208 2180 y(the)h(thread)f(must)h(release)g(it)h(once)f(for)f(each)h(time)h (it)g(has)f(acquired)f(it.)0 2327 y FD(Semaphore)p FJ(\()p FC([)p FK(value)12 b FC(])p FJ(\))208 2427 y FN(A)31 b(f)o(actory)f(function)g(that)h(returns)f(a)i(ne)n(w)f(semaphore)e (object.)57 b(A)32 b(semaphore)d(manages)h(a)i(counter)d(representing)h (the)208 2526 y(number)19 b(of)i FJ(release\(\))f FN(calls)i(minus)f (the)g(number)e(of)i FJ(acquire\(\))g FN(calls,)h(plus)f(an)g(initial)g (v)n(alue.)28 b(The)21 b FJ(acquire\(\))208 2626 y FN(method)f(blocks)h (if)h(necessary)f(until)g(it)i(can)e(return)f(without)h(making)g(the)g (counter)f(ne)o(gati)n(v)o(e.)28 b(If)21 b(not)g(gi)n(v)o(en,)g FK(value)g FN(def)o(aults)208 2726 y(to)f(1.)0 2872 y FD(BoundedSemaphore)p FJ(\()p FC([)p FK(value)12 b FC(])p FJ(\))208 2972 y FN(A)19 b(f)o(actory)e(function)g(that)i(returns)f(a)h (ne)n(w)f(bounded)e(semaphore)h(object.)24 b(A)19 b(bounded)d (semaphore)h(checks)h(to)h(mak)o(e)f(sure)h(its)208 3072 y(current)g(v)n(alue)h(doesn')o(t)f(e)o(xceed)g(its)i(initial)g(v)n (alue.)26 b(If)20 b(it)h(does,)f FJ(ValueError)g FN(is)h(raised.)26 b(In)20 b(most)h(situations)f(semaphores)208 3171 y(are)j(used)h(to)g (guard)e(resources)h(with)h(limited)g(capacity)-5 b(.)35 b(If)24 b(the)g(semaphore)e(is)i(released)g(too)f(man)o(y)g(times)h (it')-5 b(s)25 b(a)g(sign)f(of)f(a)208 3271 y(b)n(ug.)h(If)c(not)g(gi)n (v)o(en,)e FK(value)i FN(def)o(aults)g(to)g(1.)0 3418 y FL(class)h FD(Thread)208 3517 y FN(A)f(class)h(that)g(represents)e(a) i(thread)e(of)h(control.)j(This)e(class)g(can)f(be)g(safely)g (subclassed)g(in)g(a)h(limited)f(f)o(ashion.)0 3664 y FL(class)h FD(Timer)208 3764 y FN(A)f(thread)f(that)i(e)o(x)o(ecutes)e (a)h(function)f(after)h(a)g(speci\002ed)g(interv)n(al)g(has)g(passed.)0 3911 y FD(settrace)p FJ(\()p FK(func)p FJ(\))208 4010 y FN(Set)40 b(a)g(trace)f(function)f(for)g(all)j(threads)d(started)i (from)e(the)i FJ(threading)e FN(module.)81 b(The)39 b FK(func)g FN(will)i(be)e(passed)g(to)208 4110 y FJ(sys.settrace\(\))18 b FN(for)h(each)h(thread,)f(before)g(its)i FJ(run\(\))f FN(method)f(is)i(called.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4257 y FD(setprofile)p FJ(\()p FK(func)p FJ(\))208 4356 y FN(Set)37 b(a)g(pro\002le)f(function)e(for)i(all)h(threads)f(started) h(from)e(the)i FJ(threading)e FN(module.)73 b(The)36 b FK(func)g FN(will)h(be)g(passed)f(to)208 4456 y FJ (sys.setprofile\(\))17 b FN(for)j(each)g(thread,)f(before)g(its)i FJ(run\(\))f FN(method)e(is)j(called.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4603 y FD(stack_size)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 4703 y FN(Return)18 b(the)h(thread)f(stack)h(size)g(used)g(when)f(creating)g(ne)n(w)h (threads.)24 b(The)18 b(optional)g FK(size)i FN(ar)o(gument)d (speci\002es)i(the)g(stack)g(size)208 4802 y(to)27 b(be)f(used)h(for)f (subsequently)f(created)h(threads,)h(and)g(must)f(be)h(0)g(\(use)g (platform)e(or)i(con\002gured)d(def)o(ault\))i(or)g(a)h(positi)n(v)o(e) 208 4902 y(inte)o(ger)h(v)n(alue)g(of)h(at)h(least)g(32,768)d (\(32kB\).)h(If)h(changing)f(the)h(thread)f(stack)i(size)g(is)g (unsupported,)e(a)i FJ(ThreadError)208 5001 y FN(is)i(raised.)57 b(If)31 b(the)h(speci\002ed)e(stack)i(size)g(is)g(in)m(v)n(alid,)g(a)g FJ(ValueError)e FN(is)i(raised)f(and)f(the)i(stack)f(size)h(is)g (unmodi\002ed.)208 5101 y(32kB)19 b(is)j(currently)c(the)j(minimum)e (supported)f(stack)j(size)g(v)n(alue)e(to)i(guarantee)d(suf)n (\002cient)i(stack)h(space)f(for)g(the)g(interpreter)208 5201 y(itself.)32 b(Note)23 b(that)g(some)f(platforms)g(may)g(ha)n(v)o (e)g(particular)f(restrictions)h(on)h(v)n(alues)f(for)g(the)g(stack)h (size,)h(such)e(as)i(requiring)208 5300 y(a)h(minimum)f(stack)h(size)h (\277)g(32kB)f(or)g(requiring)e(allocation)h(in)h(multiples)g(of)g(the) g(system)h(memory)d(page)i(size)h(-)f(platform)208 5400 y(documentation)16 b(should)j(be)g(referred)f(to)h(for)g(more)g (information)e(\(4kB)i(pages)g(are)h(common;)e(using)h(multiples)g(of)g (4096)f(for)p 0 5549 3901 4 v 0 5649 a FI(15.3.)52 b FJ(threading)22 b FI(\227)h(Higher-le)n(v)n(el)g(threading)h(interf)n (ace)1802 b(539)p eop end %%Page: 540 552 TeXDict begin 540 551 bop 208 83 a FN(the)24 b(stack)g(size)h(is)g(the) g(suggested)e(approach)f(in)j(the)f(absence)g(of)g(more)f(speci\002c)i (information\).)34 b(A)-6 b(v)n(ailability:)32 b(W)m(indo)n(ws,)208 183 y(systems)20 b(with)h(POSIX)f(threads.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 330 y(Detailed)h(interf)o(aces)g(for)f(the)h (objects)g(are)g(documented)e(belo)n(w)-5 b(.)0 476 y(The)17 b(design)f(of)h(this)g(module)f(is)i(loosely)f(based)f(on)h(Ja)n(v)n (a')-5 b(s)18 b(threading)d(model.)23 b(Ho)n(we)n(v)o(er)m(,)15 b(where)i(Ja)n(v)n(a)g(mak)o(es)g(locks)g(and)f(condition)0 576 y(v)n(ariables)h(basic)h(beha)n(vior)f(of)g(e)n(v)o(ery)g(object,)g (the)o(y)h(are)g(separate)f(objects)h(in)g(Python.)23 b(Python')-5 b(s)17 b FJ(Thread)g FN(class)i(supports)e(a)h(subset)0 676 y(of)30 b(the)h(beha)n(vior)d(of)i(Ja)n(v)n(a')-5 b(s)32 b(Thread)d(class;)36 b(currently)-5 b(,)31 b(there)f(are)g(no)g (priorities,)i(no)e(thread)f(groups,)j(and)e(threads)f(cannot)h(be)0 775 y(destro)o(yed,)16 b(stopped,)f(suspended,)h(resumed,)g(or)g (interrupted.)21 b(The)c(static)g(methods)e(of)h(Ja)n(v)n(a')-5 b(s)18 b(Thread)d(class,)j(when)e(implemented,)0 875 y(are)k(mapped)f(to)h(module-le)n(v)o(el)e(functions.)0 1022 y(All)j(of)f(the)g(methods)f(described)g(belo)n(w)h(are)g(e)o(x)o (ecuted)e(atomically)-5 b(.)0 1307 y Fv(15.3.1)101 b(Loc)n(k)28 b(Objects)0 1510 y FN(A)23 b(primiti)n(v)o(e)e(lock)i(is)g(a)g (synchronization)d(primiti)n(v)o(e)h(that)i(is)g(not)f(o)n(wned)g(by)g (a)h(particular)e(thread)h(when)g(lock)o(ed.)31 b(In)22 b(Python,)g(it)i(is)0 1609 y(currently)15 b(the)h(lo)n(west)h(le)n(v)o (el)f(synchronization)d(primiti)n(v)o(e)i(a)n(v)n(ailable,)h (implemented)f(directly)g(by)h(the)h FJ(thread)e FN(e)o(xtension)g (module.)0 1756 y(A)24 b(primiti)n(v)o(e)e(lock)h(is)i(in)e(one)g(of)g (tw)o(o)h(states,)h(\223lock)o(ed\224)d(or)i(\223unlock)o(ed\224.)32 b(It)24 b(is)g(created)f(in)h(the)f(unlock)o(ed)f(state.)35 b(It)24 b(has)g(tw)o(o)f(basic)0 1856 y(methods,)f FJ(acquire\(\))f FN(and)h FJ(release\(\))p FN(.)30 b(When)22 b(the)h(state)g(is)g (unlock)o(ed,)e FJ(acquire\(\))g FN(changes)h(the)g(state)h(to)g(lock)o (ed)e(and)0 1955 y(returns)27 b(immediately)-5 b(.)47 b(When)28 b(the)h(state)f(is)i(lock)o(ed,)e FJ(acquire\(\))g FN(blocks)f(until)h(a)h(call)f(to)g FJ(release\(\))g FN(in)g(another)f(thread)0 2055 y(changes)d(it)h(to)g(unlock)o(ed,)f (then)g(the)h FJ(acquire\(\))f FN(call)h(resets)g(it)h(to)e(lock)o(ed)g (and)g(returns.)38 b(The)25 b FJ(release\(\))e FN(method)h(should)0 2155 y(only)16 b(be)h(called)g(in)g(the)g(lock)o(ed)f(state;)j(it)e (changes)f(the)h(state)h(to)f(unlock)o(ed)e(and)i(returns)f (immediately)-5 b(.)22 b(When)17 b(more)f(than)g(one)h(thread)0 2254 y(is)25 b(block)o(ed)e(in)i FJ(acquire\(\))e FN(w)o(aiting)h(for)g (the)g(state)h(to)f(turn)g(to)h(unlock)o(ed,)e(only)g(one)h(thread)f (proceeds)g(when)h(a)h FJ(release\(\))0 2354 y FN(call)32 b(resets)h(the)f(state)h(to)f(unlock)o(ed;)k(which)31 b(one)h(of)g(the)g(w)o(aiting)f(threads)h(proceeds)e(is)j(not)f (de\002ned,)i(and)d(may)h(v)n(ary)f(across)0 2453 y(implementations.)0 2600 y(All)21 b(methods)e(are)h(e)o(x)o(ecuted)e(atomically)-5 b(.)0 2747 y FD(acquire)p FJ(\()p FC([)p FK(bloc)n(king)46 b Fn(=)k(1)12 b FC(])p FJ(\))208 2847 y FN(Acquire)19 b(a)h(lock,)g(blocking)e(or)i(non-blocking.)208 2980 y(When)g(in)m(v)n(ok)o(ed)e(without)h(ar)o(guments,)f(block)i(until)g (the)g(lock)g(is)h(unlock)o(ed,)d(then)h(set)i(it)g(to)g(lock)o(ed,)e (and)g(return)g(true.)208 3112 y(When)g(in)m(v)n(ok)o(ed)f(with)j(the)e FK(bloc)n(king)g FN(ar)o(gument)f(set)i(to)h(true,)e(do)g(the)h(same)g (thing)g(as)g(when)g(called)f(without)g(ar)o(guments,)f(and)208 3212 y(return)h(true.)208 3345 y(When)g(in)m(v)n(ok)o(ed)f(with)i(the)g FK(bloc)n(king)e FN(ar)o(gument)g(set)i(to)g(f)o(alse,)g(do)g(not)f (block.)24 b(If)19 b(a)h(call)h(without)e(an)g(ar)o(gument)f(w)o(ould)h (block,)208 3445 y(return)g(f)o(alse)h(immediately;)f(otherwise,)g(do)h (the)g(same)h(thing)e(as)i(when)f(called)g(without)f(ar)o(guments,)f (and)i(return)f(true.)0 3591 y FD(release)p FJ(\(\))208 3691 y FN(Release)i(a)f(lock.)208 3824 y(When)f(the)g(lock)f(is)j(lock) o(ed,)d(reset)h(it)h(to)g(unlock)o(ed,)d(and)h(return.)24 b(If)19 b(an)o(y)f(other)h(threads)f(are)h(block)o(ed)f(w)o(aiting)h (for)g(the)g(lock)f(to)208 3924 y(become)h(unlock)o(ed,)f(allo)n(w)i(e) o(xactly)f(one)h(of)g(them)f(to)i(proceed.)208 4056 y(Do)f(not)g(call)g (this)h(method)e(when)g(the)i(lock)e(is)i(unlock)o(ed.)208 4189 y(There)e(is)i(no)f(return)f(v)n(alue.)0 4474 y Fv(15.3.2)101 b(RLoc)n(k)28 b(Objects)0 4677 y FN(A)23 b(reentrant)e(lock)h(is)h(a)g(synchronization)c(primiti)n(v)o(e)i(that) i(may)e(be)i(acquired)d(multiple)i(times)h(by)f(the)g(same)h(thread.)30 b(Internally)-5 b(,)21 b(it)0 4777 y(uses)h(the)f(concepts)f(of)h (\223o)n(wning)e(thread\224)h(and)h(\223recursion)e(le)n(v)o(el\224)i (in)g(addition)f(to)h(the)h(lock)o(ed/unlock)o(ed)17 b(state)22 b(used)f(by)g(primiti)n(v)o(e)0 4876 y(locks.)k(In)20 b(the)g(lock)o(ed)f(state,)i(some)f(thread)f(o)n(wns)h(the)g(lock;)g (in)g(the)h(unlock)o(ed)d(state,)j(no)e(thread)h(o)n(wns)f(it.)0 5023 y(T)-7 b(o)26 b(lock)f(the)h(lock,)g(a)g(thread)e(calls)j(its)f FJ(acquire\(\))f FN(method;)i(this)f(returns)f(once)g(the)g(thread)g(o) n(wns)g(the)h(lock.)41 b(T)-7 b(o)25 b(unlock)g(the)0 5123 y(lock,)32 b(a)e(thread)f(calls)i(its)g FJ(release\(\))d FN(method.)53 b FJ(acquire\(\))p FN(/)p FJ(release\(\))27 b FN(call)k(pairs)f(may)f(be)h(nested;)k(only)29 b(the)h(\002nal)0 5222 y FJ(release\(\))21 b FN(\(the)g FJ(release\(\))g FN(of)h(the)g(outermost)f(pair\))g(resets)h(the)g(lock)g(to)g(unlock)o (ed)e(and)h(allo)n(ws)i(another)d(thread)h(block)o(ed)0 5322 y(in)f FJ(acquire\(\))f FN(to)i(proceed.)p 0 5549 3901 4 v 0 5649 a FI(540)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 541 553 TeXDict begin 541 552 bop 0 83 a FD(acquire)p FJ(\()p FC([)p FK(bloc)n(king)46 b Fn(=)k(1)12 b FC(])p FJ(\))208 183 y FN(Acquire)19 b(a)h(lock,)g(blocking)e(or)i(non-blocking.)208 315 y(When)c(in)m(v)n(ok)o(ed)g(without)g(ar)o(guments:)22 b(if)17 b(this)g(thread)f(already)g(o)n(wns)h(the)g(lock,)g(increment)f (the)h(recursion)e(le)n(v)o(el)i(by)f(one,)h(and)208 415 y(return)i(immediately)-5 b(.)25 b(Otherwise,)c(if)g(another)e (thread)h(o)n(wns)g(the)h(lock,)g(block)e(until)i(the)g(lock)f(is)i (unlock)o(ed.)j(Once)20 b(the)h(lock)208 515 y(is)h(unlock)o(ed)e (\(not)i(o)n(wned)e(by)i(an)o(y)f(thread\),)g(then)g(grab)g(o)n (wnership,)g(set)i(the)f(recursion)e(le)n(v)o(el)i(to)g(one,)f(and)h (return.)29 b(If)21 b(more)208 614 y(than)g(one)g(thread)f(is)j(block)o (ed)d(w)o(aiting)i(until)f(the)h(lock)f(is)i(unlock)o(ed,)c(only)i(one) g(at)h(a)g(time)g(will)h(be)e(able)h(to)f(grab)g(o)n(wnership)208 714 y(of)e(the)i(lock.)j(There)19 b(is)j(no)d(return)g(v)n(alue)h(in)g (this)h(case.)208 847 y(When)e(in)m(v)n(ok)o(ed)f(with)j(the)e FK(bloc)n(king)g FN(ar)o(gument)f(set)i(to)h(true,)e(do)g(the)h(same)g (thing)g(as)g(when)g(called)f(without)g(ar)o(guments,)f(and)208 946 y(return)h(true.)208 1079 y(When)g(in)m(v)n(ok)o(ed)f(with)i(the)g FK(bloc)n(king)e FN(ar)o(gument)g(set)i(to)g(f)o(alse,)g(do)g(not)f (block.)24 b(If)19 b(a)h(call)h(without)e(an)g(ar)o(gument)f(w)o(ould)h (block,)208 1179 y(return)g(f)o(alse)h(immediately;)f(otherwise,)g(do)h (the)g(same)h(thing)e(as)i(when)f(called)g(without)f(ar)o(guments,)f (and)i(return)f(true.)0 1326 y FD(release)p FJ(\(\))208 1425 y FN(Release)27 b(a)f(lock,)h(decrementing)d(the)i(recursion)f(le) n(v)o(el.)43 b(If)26 b(after)g(the)g(decrement)f(it)i(is)g(zero,)g (reset)g(the)f(lock)g(to)g(unlock)o(ed)208 1525 y(\(not)19 b(o)n(wned)h(by)g(an)o(y)f(thread\),)g(and)h(if)h(an)o(y)f(other)f (threads)h(are)h(block)o(ed)e(w)o(aiting)h(for)g(the)g(lock)g(to)h (become)e(unlock)o(ed,)g(allo)n(w)208 1625 y(e)o(xactly)27 b(one)i(of)f(them)g(to)h(proceed.)49 b(If)29 b(after)f(the)h(decrement) e(the)i(recursion)e(le)n(v)o(el)i(is)g(still)h(nonzero,)f(the)g(lock)f (remains)208 1724 y(lock)o(ed)19 b(and)g(o)n(wned)g(by)h(the)g(calling) g(thread.)208 1857 y(Only)d(call)i(this)g(method)e(when)h(the)g (calling)g(thread)f(o)n(wns)h(the)h(lock.)24 b(Do)18 b(not)g(call)h(this)g(method)e(when)g(the)i(lock)e(is)j(unlock)o(ed.) 208 1990 y(There)f(is)i(no)f(return)f(v)n(alue.)0 2275 y Fv(15.3.3)101 b(Condition)29 b(Objects)0 2478 y FN(A)g(condition)d(v) n(ariable)i(is)h(al)o(w)o(ays)g(associated)f(with)g(some)h(kind)e(of)h (lock;)k(this)d(can)f(be)g(passed)h(in)f(or)g(one)g(will)h(be)f (created)g(by)0 2577 y(def)o(ault.)c(\(P)o(assing)c(one)g(in)g(is)h (useful)f(when)f(se)n(v)o(eral)h(condition)e(v)n(ariables)i(must)g (share)g(the)g(same)h(lock.\))0 2724 y(A)16 b(condition)d(v)n(ariable)i (has)g FJ(acquire\(\))f FN(and)h FJ(release\(\))f FN(methods)h(that)g (call)h(the)f(corresponding)d(methods)i(of)h(the)h(associated)0 2824 y(lock.)29 b(It)22 b(also)h(has)f(a)g FJ(wait\(\))f FN(method,)g(and)g FJ(notify\(\))g FN(and)g FJ(notifyAll\(\))f FN(methods.)29 b(These)22 b(three)f(must)h(only)f(be)h(called)0 2924 y(when)e(the)g(calling)g(thread)f(has)h(acquired)f(the)h(lock.)0 3070 y(The)28 b FJ(wait\(\))g FN(method)f(releases)i(the)g(lock,)h(and) e(then)g(blocks)g(until)g(it)h(is)h(a)o(w)o(ak)o(ened)d(by)h(a)h FJ(notify\(\))f FN(or)g FJ(notifyAll\(\))0 3170 y FN(call)d(for)e(the)h (same)g(condition)f(v)n(ariable)g(in)h(another)f(thread.)35 b(Once)24 b(a)o(w)o(ak)o(ened,)g(it)g(re-acquires)f(the)h(lock)g(and)f (returns.)36 b(It)24 b(is)h(also)0 3270 y(possible)20 b(to)g(specify)g(a)g(timeout.)0 3417 y(The)30 b FJ(notify\(\))g FN(method)f(w)o(ak)o(es)i(up)f(one)g(of)h(the)f(threads)g(w)o(aiting)h (for)f(the)g(condition)f(v)n(ariable,)j(if)f(an)o(y)e(are)i(w)o (aiting.)56 b(The)0 3516 y FJ(notifyAll\(\))19 b FN(method)g(w)o(ak)o (es)h(up)g(all)h(threads)e(w)o(aiting)h(for)g(the)g(condition)e(v)n (ariable.)0 3663 y(Note:)46 b(the)31 b FJ(notify\(\))f FN(and)g FJ(notifyAll\(\))f FN(methods)g(don')o(t)g(release)i(the)g (lock;)k(this)c(means)g(that)f(the)h(thread)f(or)g(threads)0 3763 y(a)o(w)o(ak)o(ened)24 b(will)i(not)f(return)g(from)f(their)h FJ(wait\(\))g FN(call)h(immediately)-5 b(,)25 b(b)n(ut)g(only)g(when)g (the)g(thread)g(that)g(called)g FJ(notify\(\))g FN(or)0 3862 y FJ(notifyAll\(\))19 b FN(\002nally)h(relinquishes)f(o)n (wnership)f(of)i(the)g(lock.)0 4009 y(T)m(ip:)25 b(the)19 b(typical)f(programming)e(style)k(using)e(condition)g(v)n(ariables)g (uses)i(the)f(lock)f(to)i(synchronize)c(access)k(to)f(some)g(shared)g (state;)0 4109 y(threads)f(that)h(are)g(interested)g(in)g(a)g (particular)f(change)g(of)h(state)g(call)h FJ(wait\(\))e FN(repeatedly)g(until)g(the)o(y)h(see)g(the)g(desired)g(state,)h(while) 0 4208 y(threads)c(that)h(modify)f(the)h(state)g(call)h FJ(notify\(\))e FN(or)g FJ(notifyAll\(\))g FN(when)g(the)o(y)g(change)g (the)h(state)h(in)f(such)f(a)i(w)o(ay)f(that)g(it)h(could)0 4308 y(possibly)25 b(be)h(a)h(desired)e(state)h(for)g(one)f(of)h(the)g (w)o(aiters.)42 b(F)o(or)26 b(e)o(xample,)g(the)g(follo)n(wing)e(code)h (is)i(a)f(generic)f(producer)n(-consumer)0 4408 y(situation)20 b(with)g(unlimited)f(b)n(uf)n(fer)g(capacity:)p 0 5549 3901 4 v 0 5649 a FI(15.3.)52 b FJ(threading)22 b FI(\227)h(Higher-le)n (v)n(el)g(threading)h(interf)n(ace)1802 b(541)p eop end %%Page: 542 554 TeXDict begin 542 553 bop 236 174 a FA(#)45 b(Consume)f(one)g(item)236 266 y(cv.acquire\(\))236 357 y(while)g(not)h(an_item_is_available\(\):) 416 448 y(cv.wait\(\))236 540 y(get_an_available_item\(\))236 631 y(cv.release\(\))236 814 y(#)g(Produce)f(one)g(item)236 905 y(cv.acquire\(\))236 996 y(make_an_item_available\(\))236 1088 y(cv.notify\(\))236 1179 y(cv.release\(\))0 1465 y FN(T)-7 b(o)25 b(choose)e(between)h FJ(notify\(\))f FN(and)h FJ(notifyAll\(\))p FN(,)g(consider)f(whether)g(one)h(state)h (change)f(can)g(be)g(interesting)g(for)f(only)0 1565 y(one)18 b(or)h(se)n(v)o(eral)f(w)o(aiting)h(threads.)24 b(E.g.)g(in)19 b(a)h(typical)e(producer)n(-consumer)c(situation,)19 b(adding)f(one)g(item)h(to)g(the)g(b)n(uf)n(fer)f(only)g(needs)0 1665 y(to)i(w)o(ak)o(e)h(up)e(one)h(consumer)f(thread.)0 1812 y FL(class)i FD(Condition)p FJ(\()p FC([)p FK(loc)n(k)13 b FC(])p FJ(\))208 1911 y FN(If)18 b(the)g FK(loc)n(k)i FN(ar)o(gument)c(is)j(gi)n(v)o(en)e(and)h(not)g FJ(None)p FN(,)g(it)h(must)g(be)f(a)h FJ(Lock)f FN(or)g FJ(RLock)g FN(object,)g(and)g(it)h(is)g(used)f(as)h(the)f(underlying)208 2011 y(lock.)24 b(Otherwise,)c(a)g(ne)n(w)g FJ(RLock)g FN(object)g(is)h(created)e(and)h(used)g(as)h(the)f(underlying)e(lock.)0 2158 y FD(acquire)p FJ(\()p FK(*ar)m(gs)p FJ(\))208 2257 y FN(Acquire)24 b(the)i(underlying)d(lock.)42 b(This)26 b(method)f(calls)h(the)g(corresponding)c(method)j(on)g(the)h (underlying)e(lock;)k(the)e(return)208 2357 y(v)n(alue)19 b(is)i(whate)n(v)o(er)e(that)h(method)f(returns.)0 2504 y FD(release)p FJ(\(\))208 2603 y FN(Release)25 b(the)g(underlying)d (lock.)38 b(This)25 b(method)e(calls)i(the)g(corresponding)c(method)j (on)g(the)h(underlying)d(lock;)k(there)e(is)i(no)208 2703 y(return)19 b(v)n(alue.)0 2850 y FD(wait)p FJ(\()p FC([)p FK(timeout)13 b FC(])p FJ(\))208 2950 y FN(W)-7 b(ait)23 b(until)f(noti\002ed)f(or)g(until)h(a)h(timeout)e(occurs.)29 b(This)22 b(must)g(only)g(be)f(called)h(when)g(the)g(calling)f(thread)g (has)h(acquired)f(the)208 3049 y(lock.)208 3176 y(This)46 b(method)f(releases)i(the)f(underlying)e(lock,)52 b(and)46 b(then)g(blocks)g(until)g(it)h(is)h(a)o(w)o(ak)o(ened)d(by)h(a)g FJ(notify\(\))g FN(or)208 3276 y FJ(notifyAll\(\))27 b FN(call)j(for)e(the)i(same)f(condition)f(v)n(ariable)g(in)h(another)f (thread,)i(or)f(until)g(the)g(optional)f(timeout)h(occurs.)208 3375 y(Once)19 b(a)o(w)o(ak)o(ened)g(or)h(timed)g(out,)g(it)h (re-acquires)d(the)i(lock)g(and)g(returns.)208 3502 y(When)h(the)g FK(timeout)h FN(ar)o(gument)d(is)j(present)f(and)f(not)h FJ(None)p FN(,)g(it)h(should)e(be)h(a)h(\003oating)e(point)h(number)e (specifying)h(a)h(timeout)208 3602 y(for)e(the)h(operation)f(in)h (seconds)g(\(or)f(fractions)g(thereof\).)208 3729 y(When)26 b(the)g(underlying)e(lock)i(is)i(an)e FJ(RLock)p FN(,)i(it)f(is)g(not)g (released)f(using)g(its)h FJ(release\(\))f FN(method,)g(since)h(this)g (may)f(not)208 3828 y(actually)e(unlock)g(the)h(lock)g(when)g(it)g(w)o (as)i(acquired)c(multiple)i(times)g(recursi)n(v)o(ely)-5 b(.)38 b(Instead,)26 b(an)f(internal)f(interf)o(ace)h(of)g(the)208 3928 y FJ(RLock)19 b FN(class)i(is)g(used,)f(which)f(really)h(unlocks)e (it)j(e)n(v)o(en)e(when)h(it)g(has)g(been)g(recursi)n(v)o(ely)e (acquired)g(se)n(v)o(eral)i(times.)25 b(Another)208 4027 y(internal)19 b(interf)o(ace)g(is)i(then)f(used)g(to)g(restore)g(the)g (recursion)f(le)n(v)o(el)h(when)f(the)i(lock)e(is)i(reacquired.)0 4174 y FD(notify)p FJ(\(\))208 4274 y FN(W)-7 b(ak)o(e)18 b(up)e(a)i(thread)e(w)o(aiting)h(on)g(this)h(condition,)e(if)h(an)o(y) -5 b(.)23 b(This)18 b(must)f(only)f(be)i(called)f(when)f(the)i(calling) e(thread)h(has)g(acquired)208 4374 y(the)j(lock.)208 4500 y(This)j(method)f(w)o(ak)o(es)i(up)f(one)g(of)g(the)g(threads)g(w) o(aiting)g(for)g(the)g(condition)f(v)n(ariable,)h(if)h(an)o(y)e(are)h (w)o(aiting;)i(it)f(is)h(a)f(no-op)d(if)208 4600 y(no)e(threads)h(are)g (w)o(aiting.)208 4727 y(The)j(current)g(implementation)f(w)o(ak)o(es)i (up)g(e)o(xactly)f(one)g(thread,)h(if)h(an)o(y)e(are)h(w)o(aiting.)36 b(Ho)n(we)n(v)o(er)m(,)23 b(it')-5 b(s)25 b(not)f(safe)g(to)g(rely)g (on)208 4826 y(this)c(beha)n(vior)-5 b(.)24 b(A)d(future,)d(optimized)h (implementation)f(may)i(occasionally)f(w)o(ak)o(e)h(up)g(more)f(than)h (one)g(thread.)208 4953 y(Note:)28 b(the)22 b(a)o(w)o(ak)o(ened)f (thread)g(does)g(not)h(actually)f(return)g(from)g(its)i FJ(wait\(\))e FN(call)i(until)e(it)i(can)f(reacquire)e(the)i(lock.)30 b(Since)208 5053 y FJ(notify\(\))19 b FN(does)h(not)g(release)g(the)g (lock,)g(its)h(caller)f(should.)0 5200 y FD(notifyAll)p FJ(\(\))208 5299 y FN(W)-7 b(ak)o(e)29 b(up)f(all)i(threads)e(w)o (aiting)g(on)g(this)i(condition.)48 b(This)29 b(method)e(acts)j(lik)o (e)f FJ(notify\(\))p FN(,)g(b)n(ut)g(w)o(ak)o(es)g(up)f(all)i(w)o (aiting)208 5399 y(threads)19 b(instead)h(of)g(one.)p 0 5549 3901 4 v 0 5649 a FI(542)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 543 555 TeXDict begin 543 554 bop 0 83 a Fv(15.3.4)101 b(Semaphore)30 b(Objects)0 286 y FN(This)25 b(is)i(one)d(of)h(the)g(oldest)g (synchronization)e(primiti)n(v)o(es)h(in)h(the)g(history)g(of)g (computer)e(science,)j(in)m(v)o(ented)d(by)i(the)g(early)g(Dutch)0 386 y(computer)18 b(scientist)j(Edsger)f(W)-8 b(.)21 b(Dijkstra)f(\(he)g(used)g FJ(P\(\))g FN(and)g FJ(V\(\))g FN(instead)g(of)g FJ(acquire\(\))f FN(and)g FJ(release\(\))p FN(\).)0 532 y(A)j(semaphore)e(manages)h(an)h(internal)f(counter)f (which)i(is)g(decremented)e(by)h(each)h FJ(acquire\(\))e FN(call)j(and)e(incremented)f(by)h(each)0 632 y FJ(release\(\))j FN(call.)39 b(The)24 b(counter)g(can)g(ne)n(v)o(er)g(go)g(belo)n(w)g (zero;)j(when)d FJ(acquire\(\))g FN(\002nds)h(that)g(it)g(is)h(zero,)f (it)h(blocks,)f(w)o(aiting)0 732 y(until)20 b(some)g(other)f(thread)h (calls)h FJ(release\(\))p FN(.)0 879 y FL(class)g FD(Semaphore)p FJ(\()p FC([)p FK(value)12 b FC(])p FJ(\))208 978 y FN(The)19 b(optional)g(ar)o(gument)f(gi)n(v)o(es)i(the)g(initial)h(v)n(alue)e (for)h(the)g(internal)f(counter;)g(it)i(def)o(aults)f(to)g FJ(1)p FN(.)0 1125 y FD(acquire)p FJ(\()p FC([)p FK(bloc)n(king)12 b FC(])p FJ(\))208 1225 y FN(Acquire)19 b(a)h(semaphore.)208 1358 y(When)31 b(in)m(v)n(ok)o(ed)e(without)i(ar)o(guments:)45 b(if)31 b(the)h(internal)e(counter)g(is)i(lar)o(ger)e(than)h(zero)f(on) h(entry)-5 b(,)33 b(decrement)c(it)j(by)f(one)208 1457 y(and)20 b(return)g(immediately)-5 b(.)25 b(If)c(it)h(is)g(zero)e(on)h (entry)-5 b(,)19 b(block,)h(w)o(aiting)h(until)g(some)f(other)h(thread) f(has)h(called)g FJ(release\(\))e FN(to)208 1557 y(mak)o(e)d(it)i(lar)o (ger)e(than)h(zero.)24 b(This)17 b(is)h(done)e(with)i(proper)d (interlocking)h(so)h(that)h(if)f(multiple)g FJ(acquire\(\))f FN(calls)i(are)f(block)o(ed,)208 1656 y FJ(release\(\))22 b FN(will)h(w)o(ak)o(e)h(e)o(xactly)e(one)h(of)f(them)h(up.)34 b(The)22 b(implementation)f(may)i(pick)g(one)f(at)i(random,)e(so)h(the) h(order)d(in)208 1756 y(which)e(block)o(ed)g(threads)h(are)g(a)o(w)o (ak)o(ened)e(should)i(not)f(be)i(relied)e(on.)25 b(There)19 b(is)i(no)f(return)f(v)n(alue)h(in)g(this)h(case.)208 1889 y(When)f(in)m(v)n(ok)o(ed)e(with)i FK(bloc)n(king)f FN(set)i(to)g(true,)e(do)h(the)g(same)h(thing)e(as)i(when)f(called)g (without)f(ar)o(guments,)f(and)i(return)f(true.)208 2022 y(When)j(in)m(v)n(ok)o(ed)f(with)i FK(bloc)n(king)e FN(set)i(to)g(f)o (alse,)g(do)g(not)f(block.)31 b(If)22 b(a)h(call)g(without)f(an)h(ar)o (gument)d(w)o(ould)i(block,)g(return)f(f)o(alse)208 2121 y(immediately;)d(otherwise,)i(do)g(the)g(same)g(thing)g(as)g(when)g (called)g(without)g(ar)o(guments,)d(and)j(return)f(true.)0 2268 y FD(release)p FJ(\(\))208 2368 y FN(Release)k(a)g(semaphore,)e (incrementing)g(the)h(internal)g(counter)f(by)i(one.)32 b(When)22 b(it)h(w)o(as)h(zero)e(on)g(entry)g(and)g(another)g(thread) 208 2467 y(is)f(w)o(aiting)f(for)f(it)i(to)f(become)f(lar)o(ger)g(than) h(zero)g(again,)f(w)o(ak)o(e)h(up)g(that)g(thread.)0 2736 y FJ(Semaphore)h FI(Example)0 2939 y FN(Semaphores)h(are)h(often)f (used)h(to)g(guard)f(resources)g(with)i(limited)f(capacity)-5 b(,)22 b(for)h(e)o(xample,)f(a)i(database)e(serv)o(er)-5 b(.)34 b(In)23 b(an)o(y)f(situation)0 3038 y(where)16 b(the)g(size)h(of)f(the)g(resource)g(size)h(is)g(\002x)o(ed,)f(you)g (should)f(use)h(a)h(bounded)d(semaphore.)22 b(Before)16 b(spa)o(wning)f(an)o(y)g(w)o(ork)o(er)g(threads,)0 3138 y(your)k(main)h(thread)f(w)o(ould)g(initialize)i(the)f(semaphore:)236 3285 y FA(maxconnections)43 b(=)h(5)236 3376 y(...)236 3467 y(pool_sema)g(=)g(BoundedSemaphore\(value=maxconnections\))0 3754 y FN(Once)26 b(spa)o(wned,)h(w)o(ork)o(er)e(threads)h(call)h(the)g (semaphore')-5 b(s)25 b(acquire)g(and)h(release)h(methods)e(when)h(the) o(y)g(need)g(to)h(connect)e(to)i(the)0 3854 y(serv)o(er:)236 4000 y FA(pool_sema.acquire\(\))236 4092 y(conn)44 b(=)h(connectdb\(\)) 236 4183 y(...)g(use)f(connection)f(...)236 4274 y(conn.close\(\))236 4366 y(pool_sema.release\(\))0 4652 y FN(The)28 b(use)h(of)f(a)h (bounded)e(semaphore)f(reduces)i(the)h(chance)e(that)i(a)g(programming) c(error)j(which)g(causes)g(the)h(semaphore)e(to)i(be)0 4752 y(released)20 b(more)f(than)h(it')-5 b(s)21 b(acquired)e(will)i (go)e(undetected.)0 5037 y Fv(15.3.5)101 b(Ev)n(ent)28 b(Objects)0 5240 y FN(This)e(is)h(one)f(of)f(the)h(simplest)h (mechanisms)e(for)g(communication)f(between)h(threads:)36 b(one)26 b(thread)f(signals)h(an)g(e)n(v)o(ent)f(and)g(other)0 5339 y(threads)20 b(w)o(ait)g(for)g(it.)p 0 5549 3901 4 v 0 5649 a FI(15.3.)52 b FJ(threading)22 b FI(\227)h(Higher-le)n(v)n (el)g(threading)h(interf)n(ace)1802 b(543)p eop end %%Page: 544 556 TeXDict begin 544 555 bop 0 83 a FN(An)26 b(e)n(v)o(ent)e(object)h (manages)g(an)g(internal)g(\003ag)h(that)f(can)h(be)f(set)i(to)e(true)h (with)f(the)h FJ(set\(\))f FN(method)f(and)h(reset)h(to)g(f)o(alse)g (with)g(the)0 183 y FJ(clear\(\))19 b FN(method.)24 b(The)c FJ(wait\(\))f FN(method)g(blocks)h(until)g(the)g(\003ag)g(is)h(true.)0 330 y FL(class)g FD(Event)p FJ(\(\))208 429 y FN(The)e(internal)h (\003ag)g(is)h(initially)f(f)o(alse.)0 576 y FD(isSet)p FJ(\(\))208 676 y FN(Return)f(true)h(if)h(and)e(only)h(if)g(the)g (internal)g(\003ag)g(is)h(true.)0 823 y FD(set)p FJ(\(\))208 922 y FN(Set)h(the)g(internal)f(\003ag)h(to)g(true.)29 b(All)23 b(threads)e(w)o(aiting)g(for)h(it)g(to)g(become)f(true)g(are)h (a)o(w)o(ak)o(ened.)28 b(Threads)21 b(that)h(call)g FJ(wait\(\))208 1022 y FN(once)d(the)h(\003ag)h(is)g(true)f(will)g(not)g(block)g(at)g (all.)0 1169 y FD(clear)p FJ(\(\))208 1268 y FN(Reset)25 b(the)f(internal)f(\003ag)i(to)f(f)o(alse.)37 b(Subsequently)-5 b(,)23 b(threads)g(calling)h FJ(wait\(\))f FN(will)i(block)f(until)g FJ(set\(\))f FN(is)i(called)f(to)h(set)208 1368 y(the)20 b(internal)f(\003ag)h(to)h(true)f(again.)0 1515 y FD(wait)p FJ(\()p FC([)p FK(timeout)13 b FC(])p FJ(\))208 1614 y FN(Block)25 b(until)f(the)i(internal)e(\003ag)h(is)h(true.)39 b(If)25 b(the)g(internal)g(\003ag)g(is)h(true)e(on)h(entry)-5 b(,)25 b(return)f(immediately)-5 b(.)38 b(Otherwise,)26 b(block)208 1714 y(until)20 b(another)e(thread)i(calls)g FJ(set\(\))g FN(to)h(set)g(the)f(\003ag)g(to)g(true,)g(or)g(until)g (the)g(optional)f(timeout)h(occurs.)208 1847 y(When)g(the)h(timeout)g (ar)o(gument)d(is)k(present)f(and)f(not)h FJ(None)p FN(,)g(it)g(should) f(be)h(a)h(\003oating)e(point)g(number)f(specifying)h(a)h(timeout)208 1946 y(for)e(the)h(operation)f(in)h(seconds)g(\(or)f(fractions)g (thereof\).)0 2231 y Fv(15.3.6)101 b(Thread)29 b(Objects)0 2434 y FN(This)22 b(class)g(represents)e(an)i(acti)n(vity)f(that)g(is)h (run)f(in)h(a)f(separate)g(thread)g(of)g(control.)27 b(There)21 b(are)g(tw)o(o)h(w)o(ays)f(to)h(specify)f(the)g(acti)n (vity:)0 2534 y(by)i(passing)g(a)h(callable)f(object)f(to)i(the)f (constructor)m(,)f(or)h(by)g(o)o(v)o(erriding)d(the)j FJ(run\(\))g FN(method)f(in)i(a)f(subclass.)35 b(No)23 b(other)g(methods)0 2634 y(\(e)o(xcept)e(for)h(the)h(constructor\))d (should)h(be)i(o)o(v)o(erridden)c(in)k(a)g(subclass.)32 b(In)22 b(other)g(w)o(ords,)g FK(only)g FN(o)o(v)o(erride)e(the)j FJ(__init__\(\))e FN(and)0 2733 y FJ(run\(\))f FN(methods)f(of)h(this)h (class.)0 2880 y(Once)e(a)h(thread)e(object)h(is)h(created,)e(its)i (acti)n(vity)f(must)g(be)h(started)f(by)g(calling)f(the)i(thread')-5 b(s)18 b FJ(start\(\))h FN(method.)k(This)c(in)m(v)n(ok)o(es)g(the)0 2980 y FJ(run\(\))h FN(method)f(in)h(a)h(separate)e(thread)h(of)f (control.)0 3127 y(Once)28 b(the)g(thread')-5 b(s)27 b(acti)n(vity)h(is)h(started,)h(the)e(thread)f(is)i(considered)d('ali)n (v)o(e'.)47 b(It)29 b(stops)f(being)f(ali)n(v)o(e)h(when)f(its)i FJ(run\(\))f FN(method)0 3226 y(terminates)18 b(\226)h(either)f (normally)-5 b(,)17 b(or)h(by)g(raising)g(an)h(unhandled)d(e)o (xception.)22 b(The)d FJ(isAlive\(\))e FN(method)h(tests)h(whether)f (the)h(thread)0 3326 y(is)i(ali)n(v)o(e.)0 3473 y(Other)27 b(threads)g(can)g(call)h(a)g(thread')-5 b(s)27 b FJ(join\(\))g FN(method.)45 b(This)28 b(blocks)f(the)g(calling)g(thread)g(until)g (the)g(thread)g(whose)g FJ(join\(\))0 3572 y FN(method)19 b(is)i(called)f(is)h(terminated.)0 3719 y(A)e(thread)e(has)i(a)g(name.) k(The)18 b(name)g(can)g(be)g(passed)h(to)f(the)g(constructor)m(,)f(set) i(with)f(the)h FJ(setName\(\))e FN(method,)g(and)h(retrie)n(v)o(ed)e (with)0 3819 y(the)k FJ(getName\(\))f FN(method.)0 3966 y(A)26 b(thread)f(can)h(be)f(\003agged)g(as)h(a)g(\223daemon)e (thread\224.)41 b(The)25 b(signi\002cance)g(of)h(this)g(\003ag)g(is)g (that)g(the)g(entire)f(Python)g(program)e(e)o(xits)0 4065 y(when)c(only)g(daemon)g(threads)g(are)g(left.)26 b(The)19 b(initial)h(v)n(alue)f(is)i(inherited)e(from)f(the)i(creating) f(thread.)24 b(The)c(\003ag)f(can)h(be)g(set)h(with)f(the)0 4165 y FJ(setDaemon\(\))f FN(method)g(and)g(retrie)n(v)o(ed)g(with)h (the)g FJ(isDaemon\(\))f FN(method.)0 4312 y(There)26 b(is)i(a)f(\223main)f(thread\224)g(object;)j(this)f(corresponds)c(to)j (the)g(initial)g(thread)f(of)g(control)g(in)h(the)g(Python)e(program.) 43 b(It)27 b(is)h(not)e(a)0 4411 y(daemon)19 b(thread.)0 4558 y(There)27 b(is)h(the)f(possibility)g(that)h(\223dummy)d(thread)i (objects\224)g(are)g(created.)46 b(These)27 b(are)h(thread)e(objects)h (corresponding)d(to)k(\223alien)0 4658 y(threads\224,)e(which)f(are)h (threads)f(of)h(control)e(started)i(outside)f(the)h(threading)e (module,)h(such)h(as)g(directly)f(from)g(C)i(code.)41 b(Dummy)0 4758 y(thread)22 b(objects)g(ha)n(v)o(e)g(limited)h (functionality;)e(the)o(y)h(are)h(al)o(w)o(ays)g(considered)e(ali)n(v)o (e)h(and)g(daemonic,)g(and)g(cannot)f(be)i FJ(join\(\))p FN(ed.)0 4857 y(The)o(y)c(are)h(ne)n(v)o(er)f(deleted,)g(since)i(it)g (is)g(impossible)e(to)i(detect)f(the)g(termination)e(of)i(alien)h (threads.)0 5004 y FL(class)g FD(Thread)p FJ(\()p FK(gr)l(oup=None)o(,) c(tar)m(g)o(et=None)o(,)i(name=None)o(,)g(ar)m(gs=\(\),)h(kwar)m(gs=)p FM(fg)p FJ(\))208 5104 y FN(This)g(constructor)e(should)h(al)o(w)o(ays) i(be)f(called)g(with)h(k)o(e)o(yw)o(ord)d(ar)o(guments.)23 b(Ar)o(guments)18 b(are:)208 5236 y FK(gr)l(oup)h FN(should)g(be)h FJ(None)p FN(;)g(reserv)o(ed)f(for)h(future)f(e)o(xtension)f(when)i(a)h FJ(ThreadGroup)d FN(class)j(is)g(implemented.)208 5369 y FK(tar)m(g)o(et)g FN(is)g(the)g(callable)f(object)f(to)i(be)f(in)m(v) n(ok)o(ed)e(by)i(the)g FJ(run\(\))g FN(method.)j(Def)o(aults)e(to)f FJ(None)p FN(,)g(meaning)e(nothing)h(is)i(called.)p 0 5549 3901 4 v 0 5649 a FI(544)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 545 557 TeXDict begin 545 556 bop 208 83 a FK(name)21 b FN(is)h(the)g(thread)f (name.)29 b(By)22 b(def)o(ault,)g(a)g(unique)e(name)h(is)i(constructed) d(of)i(the)f(form)g(\223Thread-)p FK(N)5 b FN(\224)20 b(where)h FK(N)28 b FN(is)23 b(a)f(small)208 183 y(decimal)d(number)-5 b(.)208 309 y FK(ar)m(gs)20 b FN(is)h(the)f(ar)o(gument)e(tuple)i(for)f (the)i(tar)o(get)e(in)m(v)n(ocation.)k(Def)o(aults)d(to)g FJ(\(\))p FN(.)208 435 y FK(kwar)m(gs)g FN(is)h(a)g(dictionary)d(of)i (k)o(e)o(yw)o(ord)e(ar)o(guments)h(for)g(the)h(tar)o(get)g(in)m(v)n (ocation.)j(Def)o(aults)d(to)g FJ({})p FN(.)208 561 y(If)g(the)h (subclass)g(o)o(v)o(errides)e(the)h(constructor)m(,)f(it)i(must)g(mak)o (e)f(sure)h(to)g(in)m(v)n(ok)o(e)e(the)i(base)g(class)g(constructor)e (\()p FJ(Thread.__-)208 661 y(init__\(\))p FN(\))f(before)h(doing)g(an) o(ything)f(else)j(to)f(the)h(thread.)0 808 y FD(start)p FJ(\(\))208 907 y FN(Start)f(the)g(thread')-5 b(s)20 b(acti)n(vity)-5 b(.)208 1034 y(This)21 b(must)g(be)f(called)h(at)h (most)e(once)h(per)f(thread)g(object.)27 b(It)21 b(arranges)e(for)i (the)g(object')-5 b(s)20 b FJ(run\(\))h FN(method)e(to)i(be)g(in)m(v)n (ok)o(ed)e(in)208 1133 y(a)h(separate)g(thread)f(of)h(control.)0 1280 y FD(run)p FJ(\(\))208 1380 y FN(Method)f(representing)f(the)i (thread')-5 b(s)20 b(acti)n(vity)-5 b(.)208 1506 y(Y)c(ou)19 b(may)i(o)o(v)o(erride)d(this)j(method)e(in)i(a)g(subclass.)26 b(The)20 b(standard)f FJ(run\(\))h FN(method)g(in)m(v)n(ok)o(es)f(the)i (callable)f(object)g(passed)g(to)208 1606 y(the)k(object')-5 b(s)24 b(constructor)e(as)j(the)f FK(tar)m(g)o(et)i FN(ar)o(gument,)c (if)i(an)o(y)-5 b(,)24 b(with)g(sequential)g(and)f(k)o(e)o(yw)o(ord)g (ar)o(guments)f(tak)o(en)h(from)h(the)208 1705 y FK(ar)m(gs)c FN(and)f FK(kwar)m(gs)i FN(ar)o(guments,)d(respecti)n(v)o(ely)-5 b(.)0 1852 y FD(join)p FJ(\()p FC([)p FK(timeout)13 b FC(])p FJ(\))208 1952 y FN(W)-7 b(ait)20 b(until)e(the)h(thread)f (terminates.)24 b(This)19 b(blocks)f(the)h(calling)f(thread)g(until)h (the)g(thread)f(whose)g FJ(join\(\))h FN(method)e(is)j(called)208 2051 y(terminates)f(\226)h(either)g(normally)f(or)h(through)e(an)i (unhandled)d(e)o(xception)i(\226)h(or)g(until)g(the)g(optional)f (timeout)h(occurs.)208 2178 y(When)25 b(the)g FK(timeout)i FN(ar)o(gument)c(is)j(present)f(and)g(not)g FJ(None)p FN(,)i(it)f(should)e(be)i(a)g(\003oating)f(point)f(number)g(specifying) g(a)i(time-)208 2277 y(out)34 b(for)g(the)g(operation)f(in)i(seconds)f (\(or)g(fractions)f(thereof\).)67 b(As)35 b FJ(join\(\))f FN(al)o(w)o(ays)h(returns)f FJ(None)p FN(,)k(you)33 b(must)i(call)208 2377 y FJ(isAlive\(\))19 b FN(to)h(decide)f(whether)h(a)g(timeout)g (happened.)208 2503 y(When)g(the)g FK(timeout)h FN(ar)o(gument)d(is)j (not)f(present)f(or)h FJ(None)p FN(,)g(the)g(operation)f(will)i(block)e (until)h(the)g(thread)f(terminates.)208 2629 y(A)h(thread)f(can)h(be)h FJ(join\(\))p FN(ed)e(man)o(y)g(times.)208 2756 y(A)h(thread)f(cannot)h (join)g(itself)g(because)g(this)h(w)o(ould)e(cause)h(a)h(deadlock.)208 2882 y(It)f(is)h(an)f(error)f(to)i(attempt)f(to)g FJ(join\(\))g FN(a)g(thread)f(before)g(it)i(has)f(been)g(started.)0 3029 y FD(getName)p FJ(\(\))208 3128 y FN(Return)f(the)i(thread')-5 b(s)19 b(name.)0 3275 y FD(setName)p FJ(\()p FK(name)p FJ(\))208 3375 y FN(Set)h(the)h(thread')-5 b(s)19 b(name.)208 3501 y(The)j(name)g(is)h(a)g(string)g(used)f(for)g(identi\002cation)f (purposes)g(only)-5 b(.)31 b(It)23 b(has)g(no)f(semantics.)32 b(Multiple)22 b(threads)g(may)g(be)h(gi)n(v)o(en)208 3601 y(the)d(same)g(name.)k(The)c(initial)h(name)e(is)j(set)f(by)e(the) i(constructor)-5 b(.)0 3748 y FD(isAlive)p FJ(\(\))208 3847 y FN(Return)19 b(whether)g(the)i(thread)e(is)i(ali)n(v)o(e.)208 3973 y(Roughly)-5 b(,)21 b(a)i(thread)f(is)h(ali)n(v)o(e)g(from)e(the)i (moment)f(the)g FJ(start\(\))g FN(method)g(returns)f(until)i(its)h FJ(run\(\))e FN(method)f(terminates.)208 4073 y(The)e(module)g (function)g FJ(enumerate\(\))f FN(returns)i(a)g(list)i(of)e(all)g(ali)n (v)o(e)g(threads.)0 4220 y FD(isDaemon)p FJ(\(\))208 4320 y FN(Return)f(the)i(thread')-5 b(s)19 b(daemon)g(\003ag.)0 4466 y FD(setDaemon)p FJ(\()p FK(daemonic)p FJ(\))208 4566 y FN(Set)h(the)h(thread')-5 b(s)19 b(daemon)g(\003ag)h(to)g(the)h (Boolean)e(v)n(alue)h FK(daemonic)p FN(.)j(This)d(must)h(be)f(called)g (before)e FJ(start\(\))i FN(is)h(called.)208 4692 y(The)e(initial)i(v)n (alue)e(is)j(inherited)c(from)i(the)g(creating)f(thread.)208 4819 y(The)g(entire)h(Python)f(program)f(e)o(xits)j(when)e(no)h(ali)n (v)o(e)g(non-daemon)d(threads)i(are)h(left.)0 5097 y Fv(15.3.7)101 b(Timer)28 b(Objects)0 5300 y FN(This)20 b(class)i(represents)d(an)h(action)g(that)g(should)f(be)h(run)g(only)f (after)h(a)h(certain)e(amount)g(of)h(time)h(has)f(passed)g(\227)h(a)g (timer)-5 b(.)25 b FJ(Timer)20 b FN(is)0 5400 y(a)h(subclass)f(of)g FJ(Thread)g FN(and)f(as)i(such)f(also)h(functions)d(as)j(an)f(e)o (xample)f(of)h(creating)f(custom)h(threads.)p 0 5549 3901 4 v 0 5649 a FI(15.3.)52 b FJ(threading)22 b FI(\227)h(Higher-le)n (v)n(el)g(threading)h(interf)n(ace)1802 b(545)p eop end %%Page: 546 558 TeXDict begin 546 557 bop 0 83 a FN(T)m(imers)25 b(are)h(started,)h(as) f(with)g(threads,)g(by)f(calling)g(their)h FJ(start\(\))f FN(method.)39 b(The)26 b(timer)f(can)h(be)f(stopped)g(\(before)e(its)k (action)0 183 y(has)21 b(be)o(gun\))e(by)h(calling)g(the)h FJ(cancel\(\))f FN(method.)25 b(The)c(interv)n(al)f(the)g(timer)h(will) g(w)o(ait)h(before)d(e)o(x)o(ecuting)g(its)j(action)e(may)g(not)h(be)0 282 y(e)o(xactly)e(the)h(same)h(as)g(the)f(interv)n(al)f(speci\002ed)h (by)g(the)g(user)-5 b(.)0 429 y(F)o(or)20 b(e)o(xample:)236 667 y FA(def)45 b(hello\(\):)416 759 y(print)f("hello,)f(world")236 941 y(t)i(=)g(Timer\(30.0,)e(hello\))236 1033 y(t.start\(\))h(#)g (after)g(30)h(seconds,)e("hello,)h(world")g(will)g(be)g(printed)0 1325 y FL(class)21 b FD(Timer)p FJ(\()p FK(interval,)d(function,)h(ar)m (gs=[],)i(kwar)m(gs=)p FM(fg)p FJ(\))208 1424 y FN(Create)d(a)i(timer)e (that)h(will)g(run)f FK(function)f FN(with)i(ar)o(guments)e FK(ar)m(gs)i FN(and)f(k)o(e)o(yw)o(ord)f(ar)o(guments)f FK(kwar)m(gs)p FN(,)j(after)g FK(interval)f FN(seconds)208 1524 y(ha)n(v)o(e)h(passed.)0 1671 y FD(cancel)p FJ(\(\))208 1771 y FN(Stop)27 b(the)h(timer)m(,)i(and)d(cancel)h(the)g(e)o(x)o (ecution)e(of)h(the)h(timer')-5 b(s)29 b(action.)48 b(This)28 b(will)g(only)g(w)o(ork)f(if)h(the)g(timer)g(is)h(still)g(in)g(its)208 1870 y(w)o(aiting)20 b(stage.)0 2155 y Fv(15.3.8)101 b(Using)28 b(loc)n(ks)o(,)f(conditions)o(,)h(and)h(semaphores)h(in)e (the)g Fm(with)f Fv(statement)0 2358 y FN(All)c(of)f(the)g(objects)g (pro)o(vided)d(by)j(this)g(module)f(that)h(ha)n(v)o(e)g FJ(acquire\(\))f FN(and)g FJ(release\(\))g FN(methods)g(can)h(be)g (used)g(as)h(conte)o(xt)0 2458 y(managers)17 b(for)g(a)i FJ(with)f FN(statement.)24 b(The)17 b FJ(acquire\(\))g FN(method)g(will)i(be)f(called)f(when)h(the)g(block)f(is)i(entered,)e (and)h FJ(release\(\))0 2557 y FN(will)j(be)f(called)g(when)g(the)g (block)f(is)i(e)o(xited.)0 2704 y(Currently)-5 b(,)27 b FJ(Lock)p FN(,)i FJ(RLock)p FN(,)g FJ(Condition)p FN(,)e FJ(Semaphore)p FN(,)h(and)f FJ(BoundedSemaphore)e FN(objects)i(may)g (be)h(used)f(as)h FJ(with)0 2804 y FN(statement)20 b(conte)o(xt)f (managers.)24 b(F)o(or)19 b(e)o(xample:)236 3042 y FA(from)44 b(__future__)g(import)f(with_statement)236 3133 y(import)h(threading) 236 3316 y(some_rlock)f(=)i(threading.RLock\(\))236 3499 y(with)f(some_rlock:)416 3590 y(print)g("some_rlock)f(is)h(locked)g (while)g(this)g(executes")0 4038 y FE(15.4)121 b Fx(dummy_thread)30 b FE(\227)j(Drop-in)h(replacement)h(f)l(or)f(the)h Fx(thread)c FE(module)0 4271 y FN(This)c(module)f(pro)o(vides)g(a)i(duplicate)e (interf)o(ace)g(to)i(the)f FJ(thread)g FN(module.)45 b(It)28 b(is)g(meant)f(to)g(be)g(imported)f(when)h(the)g FJ(thread)0 4370 y FN(module)19 b(is)i(not)f(pro)o(vided)d(on)j(a)h (platform.)0 4517 y(Suggested)e(usage)h(is:)236 4755 y FA(try:)416 4847 y(import)43 b(thread)h(as)h(_thread)236 4938 y(except)f(ImportError:)416 5029 y(import)f(dummy_thread)g(as)i (_thread)0 5316 y FN(Be)28 b(careful)e(to)i(not)f(use)h(this)f(module)f (where)h(deadlock)f(might)g(occur)h(from)f(a)i(thread)e(being)g (created)h(that)g(blocks)g(w)o(aiting)g(for)p 0 5549 3901 4 v 0 5649 a FI(546)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 547 559 TeXDict begin 547 558 bop 0 83 a FN(another)19 b(thread)g(to)h(be)g (created.)25 b(This)20 b(often)f(occurs)h(with)g(blocking)e(I/O.)0 407 y FE(15.5)121 b Fx(dummy_threading)55 b FE(\227)k(Drop-in)h (replacement)h(f)l(or)f(the)g Fx(threading)352 557 y FE(module)0 790 y FN(This)20 b(module)e(pro)o(vides)g(a)j(duplicate)d (interf)o(ace)h(to)h(the)g FJ(threading)f FN(module.)k(It)d(is)h(meant) e(to)h(be)g(imported)e(when)h(the)h FJ(thread)0 889 y FN(module)f(is)i(not)f(pro)o(vided)d(on)j(a)h(platform.)0 1036 y(Suggested)e(usage)h(is:)236 1274 y FA(try:)416 1366 y(import)43 b(threading)h(as)g(_threading)236 1457 y(except)g(ImportError:)416 1548 y(import)f(dummy_threading)g(as)h (_threading)0 1835 y FN(Be)28 b(careful)e(to)i(not)f(use)h(this)f (module)f(where)h(deadlock)f(might)g(occur)h(from)f(a)i(thread)e(being) g(created)h(that)g(blocks)g(w)o(aiting)g(for)0 1934 y(another)19 b(thread)g(to)h(be)g(created.)25 b(This)20 b(often)f(occurs)h(with)g (blocking)e(I/O.)0 2259 y FE(15.6)121 b Fx(mmap)32 b FE(\227)h(Memor)t(y-mapped)h(\002le)f(suppor)5 b(t)0 2491 y FN(Memory-mapped)24 b(\002le)k(objects)g(beha)n(v)o(e)f(lik)o(e) h(both)f(strings)h(and)f(lik)o(e)h(\002le)g(objects.)48 b(Unlik)o(e)28 b(normal)e(string)i(objects,)h(ho)n(we)n(v)o(er)m(,)0 2591 y(these)d(are)f(mutable.)40 b(Y)-9 b(ou)24 b(can)i(use)f(mmap)g (objects)g(in)h(most)f(places)h(where)e(strings)i(are)f(e)o(xpected;)i (for)d(e)o(xample,)i(you)e(can)h(use)0 2691 y(the)h FJ(re)g FN(module)e(to)j(search)e(through)f(a)i(memory-mapped)c(\002le.)42 b(Since)26 b(the)o(y')l(re)e(mutable,)j(you)d(can)i(change)f(a)h (single)g(character)0 2790 y(by)20 b(doing)g FJ(obj[)p FK(inde)n(x)p FJ(])48 b(=)i('a')p FN(,)20 b(or)h(change)e(a)i (substring)f(by)h(assigning)f(to)g(a)i(slice:)27 b FJ(obj[)p FK(i1)p FJ(:)p FK(i2)p FJ(])48 b(=)h('...')p FN(.)27 b(Y)-9 b(ou)20 b(can)g(also)0 2890 y(read)g(and)f(write)i(data)f (starting)g(at)g(the)g(current)f(\002le)i(position,)e(and)h FJ(seek\(\))g FN(through)e(the)i(\002le)h(to)f(dif)n(ferent)e (positions.)0 3037 y(A)26 b(memory-mapped)20 b(\002le)26 b(is)g(created)e(by)h(the)g FJ(mmap\(\))f FN(function,)h(which)f(is)i (dif)n(ferent)e(on)i(U)t FH(N)t(I)t(X)i FN(and)d(on)f(W)m(indo)n(ws.)39 b(In)25 b(either)0 3136 y(case)c(you)f(must)h(pro)o(vide)e(a)i(\002le)g (descriptor)f(for)g(a)h(\002le)h(opened)d(for)h(update.)25 b(If)c(you)f(wish)h(to)g(map)f(an)h(e)o(xisting)f(Python)g(\002le)h (object,)0 3236 y(use)f(its)i FJ(fileno\(\))d FN(method)g(to)h(obtain)g (the)g(correct)f(v)n(alue)h(for)f(the)h FK(\002leno)g FN(parameter)-5 b(.)24 b(Otherwise,)19 b(you)h(can)g(open)f(the)h (\002le)h(using)0 3336 y(the)f FJ(os.open\(\))f FN(function,)g(which)g (returns)g(a)i(\002le)g(descriptor)e(directly)g(\(the)h(\002le)h(still) g(needs)f(to)g(be)g(closed)g(when)g(done\).)0 3483 y(F)o(or)g(both)g (the)i(U)t FH(N)t(I)t(X)h FN(and)d(W)m(indo)n(ws)g(v)o(ersions)g(of)g (the)g(function,)f FK(access)h FN(may)g(be)h(speci\002ed)f(as)h(an)f (optional)f(k)o(e)o(yw)o(ord)g(parameter)-5 b(.)0 3582 y FK(access)17 b FN(accepts)h(one)e(of)h(three)g(v)n(alues:)23 b FJ(ACCESS_READ)p FN(,)16 b FJ(ACCESS_WRITE)p FN(,)f(or)i FJ(ACCESS_COPY)f FN(to)h(specify)g(readonly)-5 b(,)15 b(write-)0 3682 y(through)26 b(or)j(cop)o(y-on-write)c(memory)i (respecti)n(v)o(ely)-5 b(.)48 b FK(access)29 b FN(can)f(be)h(used)f(on) g(both)i(U)t FH(N)t(I)t(X)i FN(and)c(W)m(indo)n(ws.)49 b(If)29 b FK(access)f FN(is)i(not)0 3781 y(speci\002ed,)i(W)m(indo)n (ws)d(mmap)g(returns)h(a)g(write-through)d(mapping.)53 b(The)29 b(initial)i(memory)d(v)n(alues)i(for)f(all)i(three)e(access)i (types)0 3881 y(are)26 b(tak)o(en)f(from)g(the)h(speci\002ed)f(\002le.) 42 b(Assignment)25 b(to)h(an)g FJ(ACCESS_READ)e FN(memory)g(map)i (raises)g(a)g FJ(TypeError)f FN(e)o(xception.)0 3981 y(Assignment)i(to)i(an)f FJ(ACCESS_WRITE)e FN(memory)h(map)g(af)n (fects)h(both)g(memory)e(and)i(the)g(underlying)d(\002le.)50 b(Assignment)27 b(to)i(an)0 4080 y FJ(ACCESS_COPY)23 b FN(memory)f(map)i(af)n(fects)g(memory)f(b)n(ut)h(does)g(not)g(update) f(the)i(underlying)c(\002le.)76 b(Changed)23 b(in)i(v)o(ersion)e(2.5:)g (T)-7 b(o)0 4180 y(map)20 b(anon)o(ymous)d(memory)-5 b(,)18 b(-1)i(should)f(be)h(passed)g(as)h(the)f(\002leno)g(along)f (with)i(the)f(length.)0 4327 y FD(mmap)p FJ(\()p FK(\002leno,)e(length) p FC([)p FK(,)h(ta)o(gname)p FC([)p FK(,)f(access)12 b FC(])g(])p FJ(\))208 4426 y FL(\(W)o(indo)o(ws)29 b(v)o(ersion\))f FN(Maps)i FK(length)e FN(bytes)h(from)f(the)h(\002le)h(speci\002ed)e (by)h(the)g(\002le)h(handle)e FK(\002leno)p FN(,)i(and)f(returns)f(a)h (mmap)208 4526 y(object.)24 b(If)c FK(length)f FN(is)h(lar)o(ger)f (than)g(the)h(current)f(size)h(of)g(the)g(\002le,)g(the)g(\002le)h(is)f (e)o(xtended)e(to)i(contain)f FK(length)g FN(bytes.)25 b(If)20 b FK(length)f FN(is)208 4626 y FJ(0)p FN(,)i(the)h(maximum)d (length)h(of)h(the)h(map)f(is)h(the)f(current)f(size)i(of)f(the)g (\002le,)h(e)o(xcept)f(that)g(if)g(the)h(\002le)g(is)g(empty)e(W)m (indo)n(ws)h(raises)208 4725 y(an)f(e)o(xception)e(\(you)h(cannot)g (create)h(an)g(empty)f(mapping)g(on)g(W)m(indo)n(ws\).)208 4855 y FK(ta)o(gname)p FN(,)f(if)h(speci\002ed)g(and)g(not)g FJ(None)p FN(,)g(is)i(a)f(string)f(gi)n(ving)f(a)h(tag)h(name)f(for)f (the)i(mapping.)j(W)m(indo)n(ws)18 b(allo)n(ws)i(you)f(to)g(ha)n(v)o(e) 208 4954 y(man)o(y)k(dif)n(ferent)g(mappings)g(against)h(the)h(same)g (\002le.)39 b(If)24 b(you)g(specify)g(the)h(name)f(of)g(an)h(e)o (xisting)f(tag,)h(that)g(tag)g(is)g(opened,)208 5054 y(otherwise)k(a)i(ne)n(w)g(tag)f(of)g(this)h(name)f(is)i(created.)55 b(If)30 b(this)h(parameter)e(is)i(omitted)f(or)g FJ(None)p FN(,)j(the)d(mapping)f(is)i(created)208 5154 y(without)20 b(a)h(name.)26 b(A)-6 b(v)n(oiding)19 b(the)i(use)g(of)g(the)g(tag)g (parameter)e(will)j(assist)g(in)f(k)o(eeping)e(your)h(code)g(portable)g (between)i(U)t FH(N)t(I)t(X)208 5253 y FN(and)d(W)m(indo)n(ws.)0 5400 y FD(mmap)p FJ(\()p FK(\002leno,)f(length)p FC([)p FK(,)h(\003a)o(gs)p FC([)p FK(,)g(pr)l(ot)q FC([)p FK(,)i(access)12 b FC(])g(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(15.5.)52 b FJ(dummy_threading)21 b FI(\227)i(Drop-in)g(replacement)h(f)n(or)e (the)i FJ(threading)d FI(module)876 b(547)p eop end %%Page: 548 560 TeXDict begin 548 559 bop 208 83 a FL(\()r FN(U)t FH(N)t(I)t(X)19 b FL(v)o(ersion\))d FN(Maps)g FK(length)g FN(bytes)g(from)g(the)g (\002le)h(speci\002ed)g(by)f(the)g(\002le)h(descriptor)e FK(\002leno)p FN(,)h(and)g(returns)g(a)h(mmap)e(object.)208 183 y(If)20 b FK(length)f FN(is)i FJ(0)p FN(,)f(the)h(maximum)d(length) h(of)h(the)g(map)g(will)h(be)f(the)g(current)f(size)i(of)f(the)g (\002le)h(when)f FJ(mmap\(\))f FN(is)j(called.)208 315 y FK(\003a)o(gs)d FN(speci\002es)i(the)f(nature)g(of)f(the)i(mapping.)i FJ(MAP_PRIVATE)c FN(creates)h(a)g(pri)n(v)n(ate)g(cop)o(y-on-write)d (mapping,)h(so)j(changes)208 415 y(to)i(the)g(contents)f(of)h(the)g (mmap)f(object)g(will)i(be)f(pri)n(v)n(ate)f(to)h(this)g(process,)g (and)g FJ(MAP_SHARED)f FN(creates)h(a)g(mapping)e(that')-5 b(s)208 515 y(shared)19 b(with)h(all)h(other)f(processes)f(mapping)g (the)h(same)g(areas)h(of)e(the)i(\002le.)k(The)20 b(def)o(ault)g(v)n (alue)f(is)i FJ(MAP_SHARED)p FN(.)208 648 y FK(pr)l(ot)q FN(,)39 b(if)c(speci\002ed,)k(gi)n(v)o(es)34 b(the)h(desired)g(memory)e (protection;)41 b(the)35 b(tw)o(o)h(most)f(useful)f(v)n(alues)h(are)g FJ(PROT_READ)f FN(and)208 747 y FJ(PROT_WRITE)p FN(,)25 b(to)i(specify)g(that)g(the)g(pages)g(may)f(be)h(read)g(or)f(written.) 46 b FK(pr)l(ot)29 b FN(def)o(aults)d(to)h FJ(PROT_READ)48 b(|)i(PROT_-)208 847 y(WRITE)p FN(.)208 980 y FK(access)20 b FN(may)f(be)h(speci\002ed)g(in)g(lieu)g(of)g FK(\003a)o(gs)f FN(and)g FK(pr)l(ot)j FN(as)f(an)f(optional)e(k)o(e)o(yw)o(ord)g (parameter)-5 b(.)24 b(It)c(is)h(an)f(error)f(to)h(specify)f(both)208 1079 y FK(\003a)o(gs)p FN(,)g FK(pr)l(ot)j FN(and)e FK(access)p FN(.)25 b(See)20 b(the)h(description)d(of)i FK(access)h FN(abo)o(v)o(e)d(for)i(information)e(on)h(ho)n(w)h(to)g(use)h(this)f (parameter)-5 b(.)0 1226 y(Memory-mapped)16 b(\002le)21 b(objects)f(support)f(the)h(follo)n(wing)f(methods:)0 1373 y FD(close)p FJ(\(\))208 1473 y FN(Close)h(the)h(\002le.)k (Subsequent)19 b(calls)i(to)f(other)f(methods)h(of)f(the)i(object)e (will)i(result)f(in)h(an)f(e)o(xception)e(being)h(raised.)0 1620 y FD(find)p FJ(\()p FK(string)p FC([)p FK(,)g(start)13 b FC(])p FJ(\))208 1719 y FN(Returns)24 b(the)h(lo)n(west)f(inde)o(x)g (in)h(the)f(object)g(where)g(the)h(substring)e FK(string)i FN(is)h(found.)36 b(Returns)25 b FJ(-1)f FN(on)h(f)o(ailure.)37 b FK(start)27 b FN(is)f(the)208 1819 y(inde)o(x)19 b(at)h(which)g(the)g (search)g(be)o(gins,)f(and)h(def)o(aults)f(to)i(zero.)0 1966 y FD(flush)p FJ(\()p FC([)p FK(of)o(fset,)e(size)12 b FC(])p FJ(\))208 2065 y FN(Flushes)17 b(changes)g(made)g(to)h(the)f (in-memory)e(cop)o(y)i(of)g(a)h(\002le)h(back)e(to)g(disk.)24 b(W)m(ithout)17 b(use)h(of)f(this)h(call)h(there)e(is)h(no)f(guarantee) 208 2165 y(that)k(changes)e(are)i(written)g(back)f(before)g(the)h (object)f(is)i(destro)o(yed.)k(If)20 b FK(of)o(fset)j FN(and)d FK(size)i FN(are)f(speci\002ed,)f(only)h(changes)e(to)j(the) 208 2265 y(gi)n(v)o(en)c(range)i(of)g(bytes)g(will)g(be)h(\003ushed)e (to)i(disk;)f(otherwise,)f(the)h(whole)g(e)o(xtent)f(of)h(the)g (mapping)f(is)i(\003ushed.)0 2411 y FD(move)p FJ(\()p FK(dest)q(,)f(sr)m(c,)h(count)q FJ(\))208 2511 y FN(Cop)o(y)14 b(the)i FK(count)f FN(bytes)g(starting)g(at)h(of)n(fset)f FK(sr)m(c)h FN(to)f(the)h(destination)e(inde)o(x)g FK(dest)q FN(.)24 b(If)15 b(the)g(mmap)g(w)o(as)h(created)e(with)h FJ(ACCESS_-)208 2611 y(READ)p FN(,)k(then)h(calls)h(to)f(mo)o(v)o(e)f (will)i(thro)n(w)e(a)i FJ(TypeError)e FN(e)o(xception.)0 2758 y FD(read)p FJ(\()p FK(num)p FJ(\))208 2857 y FN(Return)i(a)h (string)f(containing)f(up)h(to)h FK(num)f FN(bytes)g(starting)h(from)e (the)i(current)e(\002le)j(position;)e(the)h(\002le)g(position)f(is)h (updated)e(to)208 2957 y(point)f(after)h(the)g(bytes)g(that)g(were)g (returned.)0 3104 y FD(read_byte)p FJ(\(\))208 3203 y FN(Returns)k(a)g(string)g(of)g(length)f(1)h(containing)e(the)j (character)e(at)h(the)g(current)f(\002le)i(position,)f(and)g(adv)n (ances)e(the)j(\002le)f(position)208 3303 y(by)19 b(1.)0 3450 y FD(readline)p FJ(\(\))208 3549 y FN(Returns)h(a)g(single)g (line,)g(starting)g(at)h(the)f(current)f(\002le)i(position)e(and)h(up)g (to)g(the)g(ne)o(xt)g(ne)n(wline.)0 3696 y FD(resize)p FJ(\()p FK(ne)o(wsize)p FJ(\))208 3796 y FN(Resizes)j(the)g(map)f(and)h (the)f(underlying)e(\002le,)k(if)f(an)o(y)-5 b(.)31 b(If)23 b(the)g(mmap)e(w)o(as)j(created)e(with)h FJ(ACCESS_READ)e FN(or)h FJ(ACCESS_-)208 3896 y(COPY)p FN(,)d(resizing)h(the)g(map)g (will)h(thro)n(w)e(a)i FJ(TypeError)e FN(e)o(xception.)0 4042 y FD(seek)p FJ(\()p FK(pos)p FC([)p FK(,)g(whence)12 b FC(])p FJ(\))208 4142 y FN(Set)23 b(the)g(\002le')-5 b(s)24 b(current)e(position.)32 b FK(whence)23 b FN(ar)o(gument)e(is)j (optional)d(and)i(def)o(aults)f(to)h FJ(os.SEEK_SET)f FN(or)h FJ(0)g FN(\(absolute)f(\002le)208 4242 y(positioning\);)g (other)h(v)n(alues)f(are)h FJ(os.SEEK_CUR)f FN(or)h FJ(1)h FN(\(seek)f(relati)n(v)o(e)f(to)h(the)h(current)d(position\))h(and)h FJ(os.SEEK_END)208 4341 y FN(or)c FJ(2)i FN(\(seek)f(relati)n(v)o(e)f (to)i(the)f(\002le')-5 b(s)21 b(end\).)0 4488 y FD(size)p FJ(\(\))208 4588 y FN(Return)e(the)i(length)e(of)h(the)g(\002le,)h (which)e(can)h(be)g(lar)o(ger)f(than)h(the)g(size)h(of)f(the)g (memory-mapped)c(area.)0 4735 y FD(tell)p FJ(\(\))208 4834 y FN(Returns)k(the)g(current)f(position)g(of)h(the)g(\002le)h (pointer)-5 b(.)0 4981 y FD(write)p FJ(\()p FK(string)p FJ(\))208 5081 y FN(Write)25 b(the)f(bytes)h(in)g FK(string)f FN(into)h(memory)e(at)i(the)f(current)g(position)f(of)i(the)f(\002le)i (pointer;)f(the)g(\002le)g(position)f(is)h(updated)e(to)208 5180 y(point)h(after)h(the)g(bytes)g(that)h(were)f(written.)40 b(If)25 b(the)g(mmap)f(w)o(as)j(created)d(with)h FJ(ACCESS_READ)p FN(,)f(then)h(writing)f(to)i(it)g(will)208 5280 y(thro)n(w)19 b(a)i FJ(TypeError)e FN(e)o(xception.)p 0 5549 3901 4 v 0 5649 a FI(548)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r(vices)p eop end %%Page: 549 561 TeXDict begin 549 560 bop 0 83 a FD(write_byte)p FJ(\()p FK(byte)p FJ(\))208 183 y FN(Write)22 b(the)g(single-character)e (string)i FK(byte)g FN(into)g(memory)e(at)j(the)f(current)f(position)g (of)h(the)g(\002le)h(pointer;)f(the)g(\002le)g(position)g(is)208 282 y(adv)n(anced)i(by)i FJ(1)p FN(.)45 b(If)26 b(the)h(mmap)f(w)o(as)h (created)f(with)h FJ(ACCESS_READ)p FN(,)d(then)j(writing)f(to)g(it)i (will)f(thro)n(w)f(a)h FJ(TypeError)208 382 y FN(e)o(xception.)0 709 y FE(15.7)121 b Fx(readline)31 b FE(\227)i(GNU)h(readline)g(interf) l(ace)0 942 y FN(The)27 b FJ(readline)g FN(module)f(de\002nes)h(a)h (number)e(of)h(functions)f(to)i(f)o(acilitate)g(completion)e(and)h (reading/writing)e(of)i(history)g(\002les)0 1042 y(from)g(the)i(Python) e(interpreter)-5 b(.)48 b(This)29 b(module)e(can)h(be)h(used)f (directly)f(or)i(via)f(the)g FJ(rlcompleter)f FN(module.)49 b(Settings)28 b(made)0 1141 y(using)h(this)h(module)e(af)n(fect)h(the)g (beha)n(viour)f(of)h(both)g(the)g(interpreter')-5 b(s)28 b(interacti)n(v)o(e)g(prompt)g(and)h(the)h(prompts)e(of)n(fered)f(by)j (the)0 1241 y FJ(raw_input\(\))19 b FN(and)g FJ(input\(\))h FN(b)n(uilt-in)f(functions.)0 1388 y(The)h FJ(readline)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f(functions:)0 1535 y FD(parse_and_bind)p FJ(\()p FK(string)p FJ(\))208 1634 y FN(P)o(arse)h(and)g(e)o(x)o(ecute)e(single)i(line)h(of)f(a)g (readline)f(init)i(\002le.)0 1781 y FD(get_line_buffer)p FJ(\(\))208 1881 y FN(Return)e(the)i(current)d(contents)i(of)g(the)g (line)g(b)n(uf)n(fer)-5 b(.)0 2028 y FD(insert_text)p FJ(\()p FK(string)p FJ(\))208 2127 y FN(Insert)19 b(te)o(xt)h(into)g (the)h(command)d(line.)0 2274 y FD(read_init_file)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 2374 y FN(P)o(arse)20 b(a)h(readline)e(initialization)g(\002le.)26 b(The)20 b(def)o(ault)f(\002lename)h(is)h(the)f(last)h(\002lename)f(used.)0 2521 y FD(read_history_file)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 2620 y FN(Load)19 b(a)i(readline)e(history)g (\002le.)26 b(The)20 b(def)o(ault)f(\002lename)h(is)h(`)p FO(\230/.histor)r(y)p FN('.)0 2767 y FD(write_history_file)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 2867 y FN(Sa)n(v)o(e)20 b(a)g(readline)g(history)f(\002le.)26 b(The)19 b(def)o(ault)h(\002lename)g(is)h(`)p FO(\230/.histor)r(y)p FN('.)0 3014 y FD(clear_history)p FJ(\(\))208 3113 y FN(Clear)i(the)h(current)e(history)-5 b(.)33 b(\(Note:)f(this)24 b(function)d(is)k(not)e(a)n(v)n(ailable)g(if)h(the)f(installed)g(v)o (ersion)g(of)g(GNU)h(readline)e(doesn')o(t)208 3213 y(support)c(it.\)) 51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 3360 y FD(get_history_length) p FJ(\(\))208 3459 y FN(Return)g(the)i(desired)e(length)g(of)h(the)g (history)g(\002le.)25 b(Ne)o(gati)n(v)o(e)19 b(v)n(alues)h(imply)f (unlimited)g(history)h(\002le)h(size.)0 3606 y FD(set_history_length)p FJ(\()p FK(length)p FJ(\))208 3706 y FN(Set)i(the)f(number)f(of)h (lines)h(to)g(sa)n(v)o(e)g(in)f(the)h(history)e(\002le.)33 b FJ(write_history_file\(\))19 b FN(uses)k(this)h(v)n(alue)d(to)i (truncate)f(the)208 3806 y(history)d(\002le)i(when)e(sa)n(ving.)25 b(Ne)o(gati)n(v)o(e)18 b(v)n(alues)i(imply)g(unlimited)f(history)g (\002le)i(size.)0 3952 y FD(get_current_history_length)p FJ(\(\))208 4052 y FN(Return)d(the)h(number)e(of)h(lines)i(currently)d (in)i(the)g(history)-5 b(.)23 b(\(This)c(is)g(dif)n(ferent)f(from)f FJ(get_history_length\(\))p FN(,)f(which)208 4152 y(returns)j(the)h (maximum)f(number)f(of)i(lines)g(that)h(will)g(be)f(written)g(to)g(a)h (history)e(\002le.\))51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4299 y FD(get_history_item)p FJ(\()p FK(inde)n(x)p FJ(\))208 4398 y FN(Return)g(the)i(current)d(contents)i(of)g(history)f(item)i(at) f FK(inde)n(x)p FN(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4545 y FD(remove_history_item)p FJ(\()p FK(pos)p FJ(\))208 4645 y FN(Remo)o(v)o(e)g(history)g(item)h(speci\002ed)g(by)g(its)h (position)e(from)h(the)g(history)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 4792 y FD(replace_history_item)p FJ(\()p FK(pos,)d(line)p FJ(\))208 4891 y FN(Replace)k(history)f(item)h (speci\002ed)g(by)g(its)h(position)f(with)g(the)g(gi)n(v)o(en)f(line.) 51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 5038 y FD(redisplay)p FJ(\(\))208 5138 y FN(Change)g(what')-5 b(s)20 b(displayed)f(on)h(the)g (screen)g(to)h(re\003ect)f(the)g(current)f(contents)g(of)h(the)g(line)h (b)n(uf)n(fer)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 5285 y FD(set_startup_hook)p FJ(\()p FC([)p FK(function)12 b FC(])p FJ(\))208 5384 y FN(Set)17 b(or)f(remo)o(v)o(e)f(the)h (startup)p 1031 5384 25 4 v 29 w(hook)f(function.)22 b(If)17 b FK(function)e FN(is)j(speci\002ed,)e(it)i(will)f(be)g(used)f (as)h(the)g(ne)n(w)f(startup)p 3393 5384 V 29 w(hook)f(function;)p 0 5549 3901 4 v 0 5649 a FI(15.7.)52 b FJ(readline)22 b FI(\227)h(GNU)g(readline)h(interf)n(ace)2156 b(549)p eop end %%Page: 550 562 TeXDict begin 550 561 bop 208 83 a FN(if)19 b(omitted)f(or)g FJ(None)p FN(,)h(an)o(y)f(hook)f(function)g(already)h(installed)h(is)h (remo)o(v)o(ed.)i(The)c(startup)p 2852 83 25 4 v 29 w(hook)g(function)f (is)i(called)g(with)g(no)208 183 y(ar)o(guments)f(just)i(before)f (readline)g(prints)h(the)g(\002rst)h(prompt.)0 330 y FD(set_pre_input_hook)p FJ(\()p FC([)p FK(function)12 b FC(])p FJ(\))208 429 y FN(Set)25 b(or)g(remo)o(v)o(e)f(the)h(pre)p 946 429 V 29 w(input)p 1147 429 V 29 w(hook)e(function.)39 b(If)25 b FK(function)f FN(is)i(speci\002ed,)g(it)g(will)g(be)f(used)g (as)h(the)f(ne)n(w)g(pre)p 3509 429 V 29 w(input)p 3710 429 V 29 w(hook)208 529 y(function;)f(if)g(omitted)f(or)h FJ(None)p FN(,)h(an)o(y)e(hook)g(function)f(already)h(installed)h(is)h (remo)o(v)o(ed.)34 b(The)23 b(pre)p 3128 529 V 29 w(input)p 3329 529 V 29 w(hook)f(function)h(is)208 628 y(called)k(with)h(no)f(ar) o(guments)f(after)h(the)h(\002rst)g(prompt)e(has)i(been)f(printed)f (and)i(just)g(before)e(readline)h(starts)h(reading)e(input)208 728 y(characters.)0 875 y FD(set_completer)p FJ(\()p FC([)p FK(function)12 b FC(])p FJ(\))208 975 y FN(Set)26 b(or)g(remo)o(v)o(e)e(the)i(completer)f(function.)40 b(If)26 b FK(function)f FN(is)i(speci\002ed,)g(it)g(will)f(be)g(used)g (as)h(the)f(ne)n(w)g(completer)e(function;)208 1074 y(if)h(omitted)f (or)g FJ(None)p FN(,)i(an)o(y)e(completer)f(function)g(already)h (installed)h(is)g(remo)o(v)o(ed.)37 b(The)24 b(completer)f(function)g (is)j(called)f(as)208 1174 y FK(function)p FJ(\()p FK(te)n(xt)q FJ(,)48 b FK(state)p FJ(\))p FN(,)33 b(for)c FK(state)i FN(in)f FJ(0)p FN(,)j FJ(1)p FN(,)g FJ(2)p FN(,)g(...,)f(until)e(it)h (returns)e(a)i(non-string)d(v)n(alue.)54 b(It)31 b(should)e(return)g (the)h(ne)o(xt)208 1273 y(possible)19 b(completion)g(starting)h(with)g FK(te)n(xt)q FN(.)0 1420 y FD(get_completer)p FJ(\(\))208 1520 y FN(Get)g(the)g(completer)f(function,)f(or)i FJ(None)g FN(if)h(no)f(completer)e(function)h(has)h(been)g(set.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1667 y FD(get_begidx)p FJ(\(\))208 1766 y FN(Get)h(the)g(be)o(ginning)e(inde)o(x)h(of)h(the)g (readline)f(tab-completion)f(scope.)0 1913 y FD(get_endidx)p FJ(\(\))208 2013 y FN(Get)i(the)g(ending)f(inde)o(x)g(of)h(the)g (readline)f(tab-completion)f(scope.)0 2160 y FD(set_completer_delims)p FJ(\()p FK(string)p FJ(\))208 2259 y FN(Set)i(the)h(readline)e(w)o(ord) g(delimiters)h(for)g(tab-completion.)0 2406 y FD(get_completer_delims)p FJ(\(\))208 2506 y FN(Get)g(the)g(readline)g(w)o(ord)f(delimiters)h (for)f(tab-completion.)0 2653 y FD(add_history)p FJ(\()p FK(line)p FJ(\))208 2752 y FN(Append)f(a)j(line)f(to)g(the)h(history)e (b)n(uf)n(fer)m(,)f(as)j(if)g(it)g(w)o(as)g(the)f(last)h(line)f(typed.) 0 2899 y FL(See)h(Also:)0 3046 y FN(Module)e FJ(rlcompleter)g FN(\(section)g(15.8\):)208 3146 y(Completion)f(of)i(Python)f (identi\002ers)h(at)h(the)f(interacti)n(v)o(e)f(prompt.)0 3431 y Fv(15.7.1)101 b(Example)0 3634 y FN(The)26 b(follo)n(wing)e(e)o (xample)h(demonstrates)f(ho)n(w)i(to)g(use)g(the)g FJ(readline)f FN(module')-5 b(s)25 b(history)g(reading)g(and)g(writing)h(functions)e (to)0 3733 y(automatically)k(load)g(and)h(sa)n(v)o(e)g(a)h(history)e (\002le)i(named)e(`)p FO(.p)n(yhist)p FN(')f(from)h(the)i(user')-5 b(s)29 b(home)f(directory)-5 b(.)50 b(The)28 b(code)h(belo)n(w)f(w)o (ould)0 3833 y(normally)19 b(be)h(e)o(x)o(ecuted)e(automatically)h (during)f(interacti)n(v)o(e)h(sessions)i(from)e(the)h(user')-5 b(s)21 b(PYTHONST)-8 b(AR)j(TUP)21 b(\002le.)236 4071 y FA(import)44 b(os)236 4162 y(histfile)g(=)g (os.path.join\(os.environ["HOME"],)c(".pyhist"\))236 4254 y(try:)416 4345 y(readline.read_history_file\(histfile\))236 4436 y(except)k(IOError:)416 4528 y(pass)236 4619 y(import)g(atexit)236 4710 y(atexit.register\(readline.write_history_f)o(ile,)39 b(histfile\))236 4802 y(del)45 b(os,)f(histfile)0 5088 y FN(The)20 b(follo)n(wing)e(e)o(xample)h(e)o(xtends)g(the)i FJ(code.InteractiveConsole)16 b FN(class)21 b(to)f(support)f(history)h (sa)n(v)o(e/restore.)p 0 5549 3901 4 v 0 5649 a FI(550)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e(System)g(Ser)r (vices)p eop end %%Page: 551 563 TeXDict begin 551 562 bop 236 174 a FA(import)44 b(code)236 266 y(import)g(readline)236 357 y(import)g(atexit)236 448 y(import)g(os)236 631 y(class)g (HistoryConsole\(code.InteractiveConsole\):)416 722 y(def)g (__init__\(self,)e(locals=None,)h(filename="<console>",)998 814 y(histfile=os.path.expanduser\("\230/.console-h)o(istory)o("\)\):) 595 905 y(code.InteractiveConsole.__init__\(self\))595 996 y(self.init_history\(histfile\))416 1179 y(def)h (init_history\(self,)e(histfile\):)595 1270 y (readline.parse_and_bind\("tab:)e(complete"\))595 1362 y(if)k(hasattr\(readline,)e("read_history_file"\):)774 1453 y(try:)954 1544 y(readline.read_history_file\(histfile\))774 1636 y(except)i(IOError:)954 1727 y(pass)774 1818 y (atexit.register\(self.save_history,)39 b(histfile\))416 2001 y(def)44 b(save_history\(self,)e(histfile\):)595 2092 y(readline.write_history_file\(histfile\))0 2602 y FE(15.8)121 b Fx(rlcompleter)30 b FE(\227)j(Completion)i(function)g (f)l(or)f(GNU)g(readline)0 2835 y FN(The)22 b FJ(rlcompleter)g FN(module)f(de\002nes)i(a)g(completion)e(function)g(suitable)i(for)f (the)g FJ(readline)g FN(module)g(by)g(completing)f(v)n(alid)0 2935 y(Python)e(identi\002ers)h(and)g(k)o(e)o(yw)o(ords.)0 3082 y(When)37 b(this)g(module)f(is)i(imported)d(on)i(a)i(U)t FH(N)t(I)t(X)h FN(platform)c(with)h(the)g FJ(readline)f FN(module)g(a)n(v)n(ailable,)k(an)d(instance)g(of)g(the)0 3181 y FJ(Completer)19 b FN(class)i(is)g(automatically)e(created)h(and) f(its)i FJ(complete)f FN(method)e(is)k(set)f(as)f(the)h FJ(readline)e FN(completer)-5 b(.)0 3328 y(Example:)236 3566 y FA(>>>)45 b(import)e(rlcompleter)236 3658 y(>>>)i(import)e (readline)236 3749 y(>>>)i(readline.parse_and_bind\("tab:)40 b(complete"\))236 3840 y(>>>)45 b(readline.)e(<TAB)h(PRESSED>)236 3932 y(readline.__doc__)446 b(readline.get_line_buffer)85 b(readline.read_init_file)236 4023 y(readline.__file__)401 b(readline.insert_text)265 b(readline.set_completer)236 4114 y(readline.__name__)401 b(readline.parse_and_bind)236 4206 y(>>>)45 b(readline.)0 4492 y FN(The)23 b FJ(rlcompleter)e FN(module)h(is)i(designed)e(for)g(use)i(with)f(Python')-5 b(s)22 b(interacti)n(v)o(e)g(mode.)33 b(A)23 b(user)g(can)g(add)g(the)g (follo)n(wing)e(lines)0 4592 y(to)31 b(his)g(or)f(her)g(initialization) g(\002le)h(\(identi\002ed)f(by)g(the)g(PYTHONST)-8 b(AR)j(TUP)31 b(en)m(vironment)d(v)n(ariable\))h(to)h(get)h(automatic)f FJ(Tab)0 4691 y FN(completion:)p 0 5549 3901 4 v 0 5649 a FI(15.8.)52 b FJ(rlcompleter)21 b FI(\227)i(Completion)i(function)f (f)n(or)f(GNU)f(readline)1473 b(551)p eop end %%Page: 552 564 TeXDict begin 552 563 bop 236 174 a FA(try:)416 266 y(import)43 b(readline)236 357 y(except)h(ImportError:)416 448 y(print)g("Module)f (readline)h(not)g(available.")236 540 y(else:)416 631 y(import)f(rlcompleter)416 722 y(readline.parse_and_bind\("tab:)d (complete"\))0 1009 y FN(On)16 b(platforms)e(without)h FJ(readline)p FN(,)g(the)h FJ(Completer)f FN(class)h(de\002ned)f(by)g (this)h(module)f(can)g(still)i(be)f(used)f(for)g(custom)g(purposes.)0 1294 y Fv(15.8.1)101 b(Completer)29 b(Objects)0 1497 y FN(Completer)19 b(objects)h(ha)n(v)o(e)g(the)g(follo)n(wing)f (method:)0 1643 y FD(complete)p FJ(\()p FK(te)n(xt,)g(state)p FJ(\))208 1743 y FN(Return)g(the)i FK(state)p FN(th)f(completion)e(for) i FK(te)n(xt)q FN(.)208 1876 y(If)i(called)g(for)g FK(te)n(xt)j FN(that)d(doesn')o(t)f(include)g(a)i(period)e(character)g(\(`)p FJ(.)p FN('\),)h(it)h(will)g(complete)f(from)f(names)h(currently)f (de\002ned)g(in)208 1976 y FJ(__main__)p FN(,)e FJ(__builtin__)f FN(and)i(k)o(e)o(yw)o(ords)f(\(as)h(de\002ned)f(by)h(the)g FJ(keyword)g FN(module\).)208 2108 y(If)k(called)h(for)f(a)h(dotted)f (name,)h(it)g(will)h(try)e(to)h(e)n(v)n(aluate)f(an)o(ything)f(without) h(ob)o(vious)f(side-ef)n(fects)h(\(functions)f(will)i(not)g(be)208 2208 y(e)n(v)n(aluated,)e(b)n(ut)g(it)i(can)e(generate)g(calls)h(to)g FJ(__getattr__\(\))p FN(\))e(up)h(to)h(the)g(last)g(part,)g(and)g (\002nd)f(matches)g(for)h(the)f(rest)i(via)208 2308 y(the)20 b FJ(dir\(\))g FN(function.)p 0 5549 3901 4 v 0 5649 a FI(552)1937 b(Chapter)23 b(15.)52 b(Optional)25 b(Oper)o(ating)e (System)g(Ser)r(vices)p eop end %%Page: 553 565 TeXDict begin 553 564 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3388 427 y FG(SIXTEEN)p 0 515 V 1851 978 a FT(Unix)57 b(Speci\002c)h(Ser)6 b(vices)0 1465 y FN(The)21 b(modules)f(described)g(in)i(this)g(chapter) e(pro)o(vide)f(interf)o(aces)i(to)g(features)g(that)g(are)h(unique)e (to)h(the)i(U)t FH(N)t(I)t(X)i FN(operating)19 b(system,)j(or)0 1565 y(in)e(some)g(cases)h(to)g(some)f(or)g(man)o(y)f(v)n(ariants)g(of) h(it.)26 b(Here')-5 b(s)20 b(an)g(o)o(v)o(ervie)n(w:)50 1708 y FD(posix)298 b FN(The)20 b(most)g(common)e(POSIX)j(system)f (calls)h(\(normally)d(used)i(via)g(module)f FJ(os)p FN(\).)50 1808 y FD(pwd)398 b FN(The)20 b(passw)o(ord)f(database)h(\()p FJ(getpwnam\(\))e FN(and)i(friends\).)50 1907 y FD(spwd)348 b FN(The)20 b(shado)n(w)f(passw)o(ord)g(database)h(\()p FJ(getspnam\(\))f FN(and)g(friends\).)50 2007 y FD(grp)398 b FN(The)20 b(group)e(database)i(\()p FJ(getgrnam\(\))e FN(and)i(friends\).)50 2106 y FD(crypt)298 b FN(The)20 b FJ(crypt\(\))f FN(function)g(used)g(to)i(check)g(U)t FH(N)t(I)t(X)i FN(passw)o(ords.)50 2206 y FD(dl)448 b FN(Call)21 b(C)g(functions)e(in)h(shared)g(objects.)50 2306 y FD(termios)198 b FN(POSIX)20 b(style)h(tty)f(control.)50 2405 y FD(tty)398 b FN(Utility)20 b(functions)f(that)h(perform)f (common)f(terminal)h(control)g(operations.)50 2505 y FD(pty)398 b FN(Pseudo-T)-6 b(erminal)18 b(Handling)g(for)i(SGI)g(and)g (Linux.)50 2605 y FD(fcntl)298 b FN(The)20 b FJ(fcntl\(\))f FN(and)h FJ(ioctl\(\))f FN(system)i(calls.)50 2704 y FD(pipes)298 b FN(A)20 b(Python)f(interf)o(ace)h(to)i(U)t FH(N)t(I)t(X)h FN(shell)e(pipelines.)50 2804 y FD(posixfile)98 b FN(A)20 b(\002le-lik)o(e)h(object)e(with)i(support)e(for)g(locking.) 50 2903 y FD(resource)148 b FN(An)20 b(interf)o(ace)f(to)i(pro)o(vide)d (resource)h(usage)h(information)d(on)j(the)g(current)f(process.)50 3003 y FD(nis)398 b FN(Interf)o(ace)19 b(to)h(Sun')-5 b(s)20 b(NIS)h(\(Y)-8 b(ello)n(w)19 b(P)o(ages\))h(library)-5 b(.)50 3103 y FD(syslog)248 b FN(An)20 b(interf)o(ace)f(to)i(the)h(U)t FH(N)t(I)t(X)h FN(syslog)d(library)f(routines.)50 3202 y FD(commands)148 b FN(Utility)20 b(functions)f(for)h(running)e(e)o (xternal)h(commands.)0 3507 y FE(16.1)121 b Fx(posix)32 b FE(\227)h(The)h(most)f(common)h(POSIX)f(system)g(calls)0 3739 y FN(This)22 b(module)e(pro)o(vides)g(access)i(to)g(operating)e (system)i(functionality)d(that)j(is)h(standardized)c(by)j(the)f(C)i (Standard)d(and)h(the)h(POSIX)0 3839 y(standard)d(\(a)h(thinly)g (disguised)h(U)t FH(N)t(I)t(X)i FN(interf)o(ace\).)0 3986 y FL(Do)31 b(not)g(import)g(this)h(module)g(dir)o(ectly)-6 b(.)56 b FN(Instead,)33 b(import)d(the)i(module)d FJ(os)p FN(,)34 b(which)d(pro)o(vides)e(a)i FK(portable)f FN(v)o(ersion)g(of)h (this)0 4086 y(interf)o(ace.)26 b(On)c(U)t FH(N)t(I)t(X)r FN(,)g(the)f FJ(os)f FN(module)g(pro)o(vides)f(a)i(superset)f(of)g(the) h FJ(posix)f FN(interf)o(ace.)26 b(On)21 b(non-)r(U)t FH(N)t(I)t(X)h FN(operating)c(systems)k(the)0 4185 y FJ(posix)e FN(module)f(is)j(not)e(a)n(v)n(ailable,)g(b)n(ut)h(a)g (subset)g(is)g(al)o(w)o(ays)g(a)n(v)n(ailable)f(through)f(the)h FJ(os)h FN(interf)o(ace.)26 b(Once)20 b FJ(os)h FN(is)g(imported,)e (there)0 4285 y(is)k FK(no)e FN(performance)e(penalty)h(in)i(using)f (it)i(instead)e(of)h FJ(posix)p FN(.)29 b(In)21 b(addition,)g FJ(os)h FN(pro)o(vides)e(some)h(additional)f(functionality)-5 b(,)20 b(such)0 4384 y(as)h(automatically)e(calling)g FJ(putenv\(\))h FN(when)f(an)h(entry)g(in)g FJ(os.environ)f FN(is)i(changed.)0 4531 y(The)i(descriptions)f(belo)n(w)g(are)h(v)o (ery)f(terse;)j(refer)d(to)h(the)h(corresponding)d(U)t FH(N)t(I)t(X)26 b FN(manual)c(\(or)h(POSIX)g(documentation\))d(entry)i (for)0 4631 y(more)d(information.)k(Ar)o(guments)18 b(called)i FK(path)f FN(refer)h(to)g(a)h(pathname)d(gi)n(v)o(en)h(as)i(a)g (string.)0 4778 y(Errors)h(are)i(reported)d(as)j(e)o(xceptions;)f(the)h (usual)f(e)o(xceptions)e(are)j(gi)n(v)o(en)e(for)g(type)h(errors,)g (while)g(errors)g(reported)e(by)i(the)g(system)0 4877 y(calls)e(raise)f FJ(error)g FN(\(a)h(synon)o(ym)c(for)j(the)g (standard)f(e)o(xception)g FJ(OSError)p FN(\),)f(described)h(belo)n(w) -5 b(.)p 0 5549 3901 4 v 3762 5649 a FI(553)p eop end %%Page: 554 566 TeXDict begin 554 565 bop 0 83 a Fv(16.1.1)101 b(Large)29 b(File)f(Suppor)t(t)0 286 y FN(Se)n(v)o(eral)20 b(operating)f(systems)i (\(including)e(AIX,)h(HPUX,)h(Irix)f(and)g(Solaris\))h(pro)o(vide)e (support)g(for)h(\002les)i(that)f(are)f(lar)o(ger)g(than)g(2)h(Gb)0 386 y(from)e(a)i(C)g(programming)c(model)i(where)g FJ(int)i FN(and)e FJ(long)h FN(are)g(32-bit)f(v)n(alues.)25 b(This)20 b(is)h(typically)f(accomplished)e(by)i(de\002ning)f(the)0 485 y(rele)n(v)n(ant)g(size)i(and)f(of)n(fset)f(types)h(as)h(64-bit)e (v)n(alues.)25 b(Such)20 b(\002les)h(are)f(sometimes)g(referred)e(to)j (as)f FK(lar)m(g)o(e)h(\002les)p FN(.)0 632 y(Lar)o(ge)h(\002le)h (support)f(is)i(enabled)d(in)i(Python)f(when)g(the)h(size)h(of)f(an)f FJ(off_t)h FN(is)h(lar)o(ger)d(than)i(a)g FJ(long)g FN(and)f(the)h FJ(long)49 b(long)23 b FN(type)0 732 y(is)h(a)n(v)n(ailable)f(and)f(is) i(at)g(least)g(as)f(lar)o(ge)g(as)g(an)g FJ(off_t)p FN(.)34 b(Python)22 b(longs)g(are)h(then)g(used)g(to)g(represent)f(\002le)h (sizes,)i(of)n(fsets)e(and)f(other)0 831 y(v)n(alues)i(that)h(can)f(e)o (xceed)g(the)g(range)g(of)g(a)h(Python)e(int.)39 b(It)24 b(may)h(be)f(necessary)g(to)h(con\002gure)d(and)i(compile)g(Python)f (with)i(certain)0 931 y(compiler)20 b(\003ags)h(to)g(enable)f(this)h (mode.)27 b(F)o(or)20 b(e)o(xample,)g(it)h(is)h(enabled)e(by)g(def)o (ault)g(with)h(recent)g(v)o(ersions)f(of)g(Irix,)g(b)n(ut)h(with)g (Solaris)0 1031 y(2.6)f(and)f(2.7)h(you)f(need)g(to)i(do)f(something)e (lik)o(e:)236 1177 y FA(CFLAGS="`getconf)42 b(LFS_CFLAGS`")h(OPT="-g)h (-O2)g($CFLAGS")g(\\)595 1269 y(./configure)0 1555 y FN(On)20 b(lar)o(ge-\002le-capable)d(Linux)i(systems,)i(this)g(might)e (w)o(ork:)236 1702 y FA(CFLAGS='-D_LARGEFILE64_SOURCE)40 b(-D_FILE_OFFSET_BITS=64')h(OPT="-g)j(-O2)g($CFLAGS")g(\\)595 1793 y(./configure)0 2218 y Fv(16.1.2)101 b(Module)29 b(Contents)0 2421 y FN(Module)19 b FJ(posix)h FN(de\002nes)g(the)g (follo)n(wing)f(data)h(item:)0 2568 y FD(environ)208 2668 y FN(A)42 b(dictionary)d(representing)h(the)h(string)h(en)m (vironment)c(at)k(the)g(time)f(the)h(interpreter)e(w)o(as)i(started.)89 b(F)o(or)41 b(e)o(xample,)208 2767 y FJ(environ['HOME'])18 b FN(is)j(the)f(pathname)e(of)i(your)f(home)g(directory)-5 b(,)18 b(equi)n(v)n(alent)h(to)h FJ(getenv\("HOME"\))e FN(in)j(C.)208 2900 y(Modifying)36 b(this)j(dictionary)e(does)h(not)h (af)n(fect)f(the)h(string)f(en)m(vironment)e(passed)i(on)g(by)h FJ(execv\(\))p FN(,)j FJ(popen\(\))c FN(or)208 3000 y FJ(system\(\))p FN(;)33 b(if)c(you)g(need)g(to)g(change)f(the)i(en)m (vironment,)e(pass)i FJ(environ)f FN(to)g FJ(execve\(\))g FN(or)g(add)g(v)n(ariable)f(assign-)208 3099 y(ments)20 b(and)f(e)o(xport)g(statements)h(to)h(the)f(command)e(string)i(for)f FJ(system\(\))h FN(or)g FJ(popen\(\))p FN(.)208 3232 y FL(Note:)35 b FN(The)25 b FJ(os)h FN(module)e(pro)o(vides)f(an)j (alternate)f(implementation)e(of)i FJ(environ)g FN(which)g(updates)g (the)h(en)m(vironment)c(on)208 3332 y(modi\002cation.)g(Note)d(also)g (that)g(updating)d FJ(os.environ)i FN(will)h(render)e(this)i (dictionary)e(obsolete.)24 b(Use)19 b(of)f(the)h FJ(os)g FN(module)208 3431 y(v)o(ersion)f(of)i(this)h(is)g(recommended)c(o)o(v) o(er)i(direct)h(access)h(to)f(the)g FJ(posix)g FN(module.)0 3578 y(Additional)25 b(contents)g(of)h(this)g(module)f(should)f(only)i (be)f(accessed)h(via)g(the)g FJ(os)g FN(module;)i(refer)d(to)h(the)g (documentation)d(for)i(that)0 3678 y(module)19 b(for)g(further)g (information.)0 4005 y FE(16.2)121 b Fx(pwd)33 b FE(\227)f(The)j(pass)l (w)o(ord)g(database)0 4238 y FN(This)20 b(module)f(pro)o(vides)g (access)h(to)h(the)h(U)t FH(N)t(I)t(X)h FN(user)d(account)f(and)h (passw)o(ord)f(database.)25 b(It)20 b(is)h(a)n(v)n(ailable)f(on)g(all)j (U)t FH(N)t(I)t(X)g FN(v)o(ersions.)0 4385 y(P)o(assw)o(ord)32 b(database)f(entries)h(are)g(reported)e(as)i(a)h(tuple-lik)o(e)d (object,)k(whose)e(attrib)n(utes)g(correspond)d(to)j(the)g(members)f (of)h(the)0 4485 y FJ(passwd)20 b FN(structure)f(\(Attrib)n(ute)g (\002eld)i(belo)n(w)-5 b(,)19 b(see)h FJ(<pwd.h>)p FN(\):)1039 4708 y FL(Index)p 1290 4738 4 100 v 99 w(Attrib)n(ute)p 1838 4738 V 217 w(Meaning)p 989 4741 1923 4 v 1200 4811 a FN(0)p 1290 4841 4 100 v 99 w FJ(pw_name)p 1838 4841 V 198 w FN(Login)f(name)1200 4910 y(1)p 1290 4940 V 99 w FJ(pw_passwd)p 1838 4940 V 98 w FN(Optional)h(encrypted)e(passw)o (ord)1200 5010 y(2)p 1290 5040 V 99 w FJ(pw_uid)p 1838 5040 V 248 w FN(Numerical)h(user)h(ID)1200 5110 y(3)p 1290 5139 V 99 w FJ(pw_gid)p 1838 5139 V 248 w FN(Numerical)f(group)g (ID)1200 5209 y(4)p 1290 5239 V 99 w FJ(pw_gecos)p 1838 5239 V 148 w FN(User)i(name)e(or)h(comment)f(\002eld)1200 5309 y(5)p 1290 5339 V 99 w FJ(pw_dir)p 1838 5339 V 248 w FN(User)i(home)e(directory)1200 5408 y(6)p 1290 5438 V 99 w FJ(pw_shell)p 1838 5438 V 148 w FN(User)i(command)d(interpreter) p 0 5549 3901 4 v 0 5649 a FI(554)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 555 567 TeXDict begin 555 566 bop 0 83 a FN(The)20 b(uid)g(and)f(gid)h(items)h (are)f(inte)o(gers,)f(all)i(others)f(are)g(strings.)25 b FJ(KeyError)19 b FN(is)i(raised)f(if)g(the)h(entry)e(ask)o(ed)h(for)g (cannot)f(be)h(found.)0 230 y FL(Note:)j FN(In)18 b(traditional)g(U)t FH(N)t(I)t(X)j FN(the)d(\002eld)g FJ(pw_passwd)f FN(usually)g(contains) g(a)i(passw)o(ord)e(encrypted)f(with)i(a)g(DES)g(deri)n(v)o(ed)e (algorithm)0 330 y(\(see)32 b(module)e FJ(crypt)p FN(\).)58 b(Ho)n(we)n(v)o(er)30 b(most)i(modern)e(unices)h(use)h(a)g(so-called)e FK(shadow)h(passwor)m(d)h FN(system.)59 b(On)31 b(those)h(unices)0 429 y(the)22 b FK(pw)p 226 429 25 4 v 30 w(passwd)j FN(\002eld)e(only)e (contains)h(an)g(asterisk)h(\()p FJ(')1618 444 y(*)1668 429 y(')p FN(\))f(or)g(the)g(letter)h(`)p FJ(x)p FN(')f(where)g(the)g (encrypted)e(passw)o(ord)i(is)i(stored)d(in)i(a)g(\002le)0 529 y(`)p FO(/etc/shado)o(w)p FN(')13 b(which)i(is)i(not)e(w)o(orld)g (readable.)22 b(Whether)15 b(the)h FK(pw)p 1939 529 V 30 w(passwd)i FN(\002eld)e(contains)f(an)o(ything)e(useful)i(is)i (system-dependent.)0 628 y(If)j(a)n(v)n(ailable,)g(the)g FJ(spwd)g FN(module)f(should)g(be)h(used)g(where)f(access)i(to)g(the)f (encrypted)e(passw)o(ord)h(is)i(required.)0 775 y(It)f(de\002nes)g(the) h(follo)n(wing)d(items:)0 922 y FD(getpwuid)p FJ(\()p FK(uid)r FJ(\))208 1022 y FN(Return)h(the)i(passw)o(ord)e(database)h (entry)f(for)h(the)g(gi)n(v)o(en)f(numeric)f(user)j(ID.)0 1169 y FD(getpwnam)p FJ(\()p FK(name)p FJ(\))208 1268 y FN(Return)e(the)i(passw)o(ord)e(database)h(entry)f(for)h(the)g(gi)n (v)o(en)f(user)h(name.)0 1415 y FD(getpwall)p FJ(\(\))208 1515 y FN(Return)f(a)i(list)g(of)f(all)h(a)n(v)n(ailable)f(passw)o(ord) f(database)h(entries,)g(in)g(arbitrary)e(order)-5 b(.)0 1662 y FL(See)21 b(Also:)0 1808 y FN(Module)e FJ(grp)h FN(\(section)g(16.4\):)208 1908 y(An)g(interf)o(ace)f(to)h(the)h(group) d(database,)h(similar)i(to)f(this.)0 2055 y(Module)f FJ(spwd)h FN(\(section)g(16.3\):)208 2155 y(An)g(interf)o(ace)f(to)h (the)h(shado)n(w)e(passw)o(ord)g(database,)h(similar)g(to)h(this.)0 2482 y FE(16.3)121 b Fx(spwd)32 b FE(\227)h(The)h(shado)n(w)i(pass)l(w) o(ord)f(database)0 2715 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2862 y(This)h(module)f(pro)o(vides)g(access)h(to)h(the)h(U)t FH(N)t(I)t(X)h FN(shado)n(w)c(passw)o(ord)h(database.)k(It)d(is)g(a)n (v)n(ailable)f(on)f(v)n(arious)j(U)t FH(N)t(I)t(X)h FN(v)o(ersions.)0 3009 y(Y)-9 b(ou)20 b(must)g(ha)n(v)o(e)f(enough)g(pri)n(vile)o(ges)f (to)j(access)g(the)f(shado)n(w)f(passw)o(ord)h(database)f(\(this)i (usually)e(means)h(you)f(ha)n(v)o(e)h(to)g(be)g(root\).)0 3155 y(Shado)n(w)h(passw)o(ord)g(database)h(entries)g(are)g(reported)e (as)j(a)f(tuple-lik)o(e)f(object,)h(whose)f(attrib)n(utes)h(correspond) e(to)i(the)g(members)f(of)0 3255 y(the)f FJ(spwd)g FN(structure)f (\(Attrib)n(ute)h(\002eld)g(belo)n(w)-5 b(,)19 b(see)i FJ(<shadow.h>)p FN(\):)469 3478 y FL(Index)p 720 3508 4 100 v 100 w(Attrib)n(ute)p 1268 3508 V 217 w(Meaning)p 419 3511 3062 4 v 630 3581 a FN(0)p 720 3611 4 100 v 100 w FJ(sp_nam)p 1268 3611 V 248 w FN(Login)e(name)630 3681 y(1)p 720 3711 V 100 w FJ(sp_pwd)p 1268 3711 V 248 w FN(Encrypted)f(passw)o(ord)630 3780 y(2)p 720 3810 V 100 w FJ(sp_lstchg)p 1268 3810 V 98 w FN(Date)i(of)g(last)h(change) 630 3880 y(3)p 720 3910 V 100 w FJ(sp_min)p 1268 3910 V 248 w FN(Minimal)e(number)g(of)h(days)g(between)f(changes)630 3980 y(4)p 720 4009 V 100 w FJ(sp_max)p 1268 4009 V 248 w FN(Maximum)f(number)h(of)h(days)g(between)f(changes)630 4079 y(5)p 720 4109 V 100 w FJ(sp_warn)p 1268 4109 V 198 w FN(Number)f(of)i(days)g(before)f(passw)o(ord)h(e)o(xpires)f(to)h (w)o(arn)g(user)g(about)f(it)630 4179 y(6)p 720 4209 V 100 w FJ(sp_inact)p 1268 4209 V 148 w FN(Number)f(of)i(days)g(after)g (passw)o(ord)g(e)o(xpires)f(until)h(account)f(is)i(block)o(ed)630 4278 y(7)p 720 4308 V 100 w FJ(sp_expire)p 1268 4308 V 98 w FN(Number)d(of)i(days)g(since)h(1970-01-01)16 b(until)k(account)f(is)i(disabled)630 4378 y(8)p 720 4408 V 100 w FJ(sp_flag)p 1268 4408 V 198 w FN(Reserv)o(ed)0 4603 y(The)e(sp)p 228 4603 25 4 v 30 w(nam)g(and)g(sp)p 635 4603 V 29 w(pwd)g(items)h(are)f(strings,)h(all)g(others)f(are)g (inte)o(gers.)24 b FJ(KeyError)18 b FN(is)i(raised)g(if)f(the)h(entry)e (ask)o(ed)i(for)e(cannot)h(be)0 4703 y(found.)0 4850 y(It)h(de\002nes)g(the)h(follo)n(wing)d(items:)0 4997 y FD(getspnam)p FJ(\()p FK(name)p FJ(\))208 5096 y FN(Return)h(the)i (shado)n(w)e(passw)o(ord)g(database)h(entry)f(for)h(the)g(gi)n(v)o(en)f (user)h(name.)0 5243 y FD(getspall)p FJ(\(\))208 5343 y FN(Return)f(a)i(list)g(of)f(all)h(a)n(v)n(ailable)f(shado)n(w)f (passw)o(ord)g(database)h(entries,)g(in)g(arbitrary)f(order)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(16.3.)52 b FJ(spwd)23 b FI(\227)g(The)g(shado)o(w)g(pass)n(w)o(ord)f(database)2007 b(555)p eop end %%Page: 556 568 TeXDict begin 556 567 bop 0 83 a FL(See)21 b(Also:)0 230 y FN(Module)e FJ(grp)h FN(\(section)g(16.4\):)208 330 y(An)g(interf)o(ace)f(to)h(the)h(group)d(database,)h(similar)i(to)f (this.)0 476 y(Module)f FJ(pwd)h FN(\(section)g(16.2\):)208 576 y(An)g(interf)o(ace)f(to)h(the)h(normal)e(passw)o(ord)g(database,)g (similar)i(to)f(this.)0 903 y FE(16.4)121 b Fx(grp)33 b FE(\227)f(The)j(g)o(roup)f(database)0 1136 y FN(This)20 b(module)f(pro)o(vides)g(access)h(to)h(the)h(U)t FH(N)t(I)t(X)h FN(group)c(database.)24 b(It)c(is)i(a)n(v)n(ailable)d(on)h(all)j(U)t FH(N)t(I)t(X)g FN(v)o(ersions.)0 1283 y(Group)d(database)h(entries)h (are)f(reported)f(as)i(a)g(tuple-lik)o(e)f(object,)g(whose)h(attrib)n (utes)f(correspond)e(to)j(the)f(members)g(of)g(the)h FJ(group)0 1383 y FN(structure)d(\(Attrib)n(ute)h(\002eld)g(belo)n(w)-5 b(,)19 b(see)i FJ(<pwd.h>)p FN(\):)829 1606 y FL(Index)p 1081 1636 4 100 v 100 w(Attrib)n(ute)p 1524 1636 V 112 w(Meaning)p 780 1639 2341 4 v 991 1709 a FN(0)p 1081 1739 4 100 v 99 w(gr)p 1207 1709 25 4 v 29 w(name)p 1524 1739 4 100 v 163 w(the)f(name)g(of)g(the)g(group)991 1808 y(1)p 1081 1838 V 99 w(gr)p 1207 1808 25 4 v 29 w(passwd)p 1524 1838 4 100 v 99 w(the)g(\(encrypted\))e(group)g(passw)o (ord;)i(often)f(empty)991 1908 y(2)p 1081 1938 V 99 w(gr)p 1207 1908 25 4 v 29 w(gid)p 1524 1938 4 100 v 237 w(the)h(numerical)f (group)f(ID)991 2008 y(3)p 1081 2038 V 99 w(gr)p 1207 2008 25 4 v 29 w(mem)p 1524 2038 4 100 v 177 w(all)j(the)f(group)f (member')-5 b(s)19 b(user)h(names)0 2233 y(The)g(gid)g(is)h(an)f(inte)o (ger)m(,)e(name)i(and)f(passw)o(ord)h(are)g(strings,)g(and)f(the)i (member)d(list)k(is)f(a)f(list)h(of)f(strings.)25 b(\(Note)20 b(that)g(most)g(users)h(are)0 2332 y(not)f(e)o(xplicitly)f(listed)i(as) g(members)e(of)h(the)g(group)f(the)o(y)g(are)i(in)f(according)e(to)j (the)f(passw)o(ord)f(database.)25 b(Check)20 b(both)f(databases)h(to)0 2432 y(get)g(complete)f(membership)g(information.\))0 2579 y(It)h(de\002nes)g(the)h(follo)n(wing)d(items:)0 2726 y FD(getgrgid)p FJ(\()p FK(gid)r FJ(\))208 2825 y FN(Return)26 b(the)i(group)d(database)i(entry)f(for)h(the)g(gi)n(v)o (en)f(numeric)g(group)g(ID.)h FJ(KeyError)f FN(is)j(raised)e(if)g(the)h (entry)e(ask)o(ed)h(for)208 2925 y(cannot)19 b(be)h(found.)0 3072 y FD(getgrnam)p FJ(\()p FK(name)p FJ(\))208 3171 y FN(Return)e(the)i(group)d(database)i(entry)f(for)h(the)g(gi)n(v)o(en) f(group)f(name.)24 b FJ(KeyError)19 b FN(is)h(raised)f(if)g(the)h (entry)e(ask)o(ed)h(for)g(cannot)f(be)208 3271 y(found.)0 3418 y FD(getgrall)p FJ(\(\))208 3518 y FN(Return)h(a)i(list)g(of)f (all)h(a)n(v)n(ailable)f(group)e(entries,)i(in)g(arbitrary)f(order)-5 b(.)0 3664 y FL(See)21 b(Also:)0 3811 y FN(Module)e FJ(pwd)h FN(\(section)g(16.2\):)208 3911 y(An)g(interf)o(ace)f(to)h(the)h(user)f (database,)f(similar)h(to)h(this.)0 4058 y(Module)e FJ(spwd)h FN(\(section)g(16.3\):)208 4157 y(An)g(interf)o(ace)f(to)h(the)h(shado) n(w)e(passw)o(ord)g(database,)h(similar)g(to)h(this.)0 4485 y FE(16.5)121 b Fx(crypt)32 b FE(\227)h(Function)i(to)f(chec)n(k)i FC(U)6 b Fl(N)g(I)g(X)36 b FE(pass)l(w)o(ords)0 4718 y FN(This)20 b(module)e(implements)g(an)i(interf)o(ace)f(to)g(the)h FK(crypt)p FN(\(3\))f(routine,)f(which)h(is)h(a)g(one-w)o(ay)e(hash)i (function)d(based)j(upon)e(a)i(modi\002ed)0 4817 y(DES)26 b(algorithm;)g(see)f(the)i(U)t FH(N)t(I)t(X)i FN(man)24 b(page)h(for)f(further)g(details.)40 b(Possible)25 b(uses)h(include)e (allo)n(wing)g(Python)g(scripts)i(to)f(accept)0 4917 y(typed)19 b(passw)o(ords)h(from)f(the)h(user)m(,)g(or)g(attempting)f (to)h(crack)i(U)t FH(N)t(I)t(X)h FN(passw)o(ords)d(with)g(a)h (dictionary)-5 b(.)0 5064 y(Notice)24 b(that)h(the)g(beha)n(vior)e(of)h (this)h(module)e(depends)g(on)h(the)h(actual)f(implementation)f(of)h (the)h FK(crypt)p FN(\(3\))e(routine)g(in)i(the)g(running)0 5163 y(system.)g(Therefore,)18 b(an)o(y)h(e)o(xtensions)g(a)n(v)n (ailable)h(on)g(the)g(current)f(implementation)f(will)j(also)f(be)g(a)n (v)n(ailable)g(on)g(this)h(module.)0 5263 y FD(crypt)p FJ(\()p FK(wor)m(d,)e(salt)q FJ(\))208 5363 y FK(wor)m(d)j FN(will)f(usually)f(be)g(a)h(user')-5 b(s)21 b(passw)o(ord)f(as)h (typed)e(at)i(a)g(prompt)d(or)i(in)h(a)g(graphical)e(interf)o(ace.)24 b FK(salt)f FN(is)e(usually)f(a)g(random)p 0 5549 3901 4 v 0 5649 a FI(556)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 557 569 TeXDict begin 557 568 bop 208 83 a FN(tw)o(o-character)22 b(string)i(which)f(will)i(be)g(used)f(to)g(perturb)f(the)h(DES)g (algorithm)f(in)h(one)g(of)g(4096)f(w)o(ays.)37 b(The)24 b(characters)f(in)208 183 y FK(salt)i FN(must)e(be)g(in)g(the)h(set)970 149 y Fp(d)985 183 y FJ([./a-zA-Z0-9])-10 b Fp(c)g FN(.)32 b(Returns)23 b(the)g(hashed)f(passw)o(ord)h(as)h(a)f(string,)h(which)e (will)i(be)f(composed)208 282 y(of)c(characters)h(from)f(the)h(same)g (alphabet)f(as)i(the)g(salt)g(\(the)e(\002rst)i(tw)o(o)g(characters)e (represent)g(the)h(salt)h(itself\).)208 415 y(Since)g(a)g(fe)n(w)g FK(crypt)p FN(\(3\))f(e)o(xtensions)f(allo)n(w)i(dif)n(ferent)e(v)n (alues,)i(with)g(dif)n(ferent)e(sizes)j(in)f(the)g FK(salt)q FN(,)h(it)g(is)f(recommended)d(to)j(use)208 515 y(the)f(full)g(crypted) f(passw)o(ord)g(as)i(salt)g(when)f(checking)e(for)i(a)g(passw)o(ord.)0 614 y(A)h(simple)f(e)o(xample)f(illustrating)g(typical)h(use:)236 853 y FA(import)44 b(crypt,)g(getpass,)f(pwd)236 1035 y(def)i(login\(\):)416 1127 y(username)e(=)i(raw_input\('Python)d (login:'\))416 1218 y(cryptedpasswd)g(=)j(pwd.getpwnam\(username\)[1]) 416 1309 y(if)f(cryptedpasswd:)595 1401 y(if)g(cryptedpasswd)f(==)i ('x')f(or)g(cryptedpasswd)f(==)h(')2612 1414 y(*)2657 1401 y(':)774 1492 y(raise)g("Sorry,)g(currently)f(no)i(support)e(for)i (shadow)e(passwords")595 1583 y(cleartext)g(=)i(getpass.getpass\(\))595 1674 y(return)f(crypt.crypt\(cleartext,)d(cryptedpasswd\))h(==)j (cryptedpasswd)416 1766 y(else:)595 1857 y(return)f(1)0 2367 y FE(16.6)121 b Fx(dl)33 b FE(\227)g(Call)g(C)g(functions)i(in)e (shared)i(objects)0 2600 y FN(The)23 b FJ(dl)g FN(module)f(de\002nes)h (an)g(interf)o(ace)f(to)h(the)g FJ(dlopen\(\))f FN(function,)g(which)h (is)h(the)f(most)g(common)e(interf)o(ace)h(on)j(U)t FH(N)t(I)t(X)h FN(plat-)0 2700 y(forms)19 b(for)h(handling)e(dynamically)h(link)o(ed)g (libraries.)25 b(It)20 b(allo)n(ws)g(the)h(program)d(to)i(call)h (arbitrary)d(functions)h(in)h(such)g(a)h(library)-5 b(.)0 2847 y FL(W)g(ar)o(ning:)42 b FN(The)29 b FJ(dl)h FN(module)d(bypasses) i(the)h(Python)e(type)h(system)g(and)g(error)f(handling.)50 b(If)29 b(used)g(incorrectly)f(it)i(may)f(cause)0 2946 y(se)o(gmentation)18 b(f)o(aults,)i(crashes)g(or)g(other)g(incorrect)f (beha)n(viour)-5 b(.)0 3093 y FL(Note:)27 b FN(This)21 b(module)f(will)i(not)f(w)o(ork)g(unless)g FJ(sizeof\(int\))48 b(==)h(sizeof\(long\))f(==)h(sizeof\(char)3504 3108 y(*)3554 3093 y(\))22 b FN(If)f(this)h(is)0 3193 y(not)e(the)g(case,)g FJ(SystemError)f FN(will)i(be)f(raised)g(on)g(import.)0 3340 y(The)g FJ(dl)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (function:)0 3486 y FD(open)p FJ(\()p FK(name)p FC([)p FK(,)f(mode)49 b Fn(=)g(RTLD_LAZY)18 b FC(])p FJ(\))208 3586 y FN(Open)f(a)i(shared)f(object)g(\002le,)h(and)f(return)f(a)i (handle.)24 b(Mode)17 b(signi\002es)i(late)g(binding)e(\()p FJ(RTLD_LAZY)p FN(\))g(or)h(immediate)f(binding)208 3686 y(\()p FJ(RTLD_NOW)p FN(\).)h(Def)o(ault)i(is)h FJ(RTLD_LAZY)p FN(.)e(Note)h(that)g(some)g(systems)h(do)f(not)f(support)g FJ(RTLD_NOW)p FN(.)208 3818 y(Return)g(v)n(alue)h(is)h(a)g FJ(dlobject)p FN(.)0 3965 y(The)f FJ(dl)g FN(module)f(de\002nes)h(the)g (follo)n(wing)f(constants:)0 4112 y FD(RTLD_LAZY)208 4212 y FN(Useful)h(as)h(an)f(ar)o(gument)e(to)i FJ(open\(\))p FN(.)0 4359 y FD(RTLD_NOW)208 4458 y FN(Useful)e(as)h(an)g(ar)o(gument) d(to)j FJ(open\(\))p FN(.)24 b(Note)19 b(that)f(on)g(systems)i(which)e (do)g(not)g(support)f(immediate)h(binding,)f(this)i(constant)208 4558 y(will)j(not)g(appear)e(in)j(the)e(module.)29 b(F)o(or)22 b(maximum)e(portability)-5 b(,)20 b(use)i FJ(hasattr\(\))f FN(to)h(determine)e(if)j(the)f(system)g(supports)208 4658 y(immediate)d(binding.)0 4804 y(The)h FJ(dl)g FN(module)f (de\002nes)h(the)g(follo)n(wing)f(e)o(xception:)0 4951 y FL(exception)g FD(error)208 5051 y FN(Exception)f(raised)i(when)g(an) g(error)f(has)h(occurred)e(inside)i(the)h(dynamic)d(loading)h(and)h (linking)f(routines.)0 5198 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(16.6.)52 b FJ(dl)23 b FI(\227)g(Call)h(C)f(functions)g (in)h(shared)f(objects)2065 b(557)p eop end %%Page: 558 570 TeXDict begin 558 569 bop 236 174 a FA(>>>)45 b(import)e(dl,)i(time)236 266 y(>>>)g(a=dl.open\('/lib/libc.so.6'\))236 357 y(>>>)g (a.call\('time'\),)d(time.time\(\))236 448 y(\(929723914,)h (929723914.498\))0 735 y FN(This)23 b(e)o(xample)f(w)o(as)i(tried)f(on) g(a)g(Debian)g(GNU/Linux)f(system,)h(and)g(is)h(a)g(good)d(e)o(xample)h (of)h(the)g(f)o(act)g(that)h(using)e(this)i(module)e(is)0 834 y(usually)e(a)g(bad)g(alternati)n(v)o(e.)0 1113 y Fv(16.6.1)101 b(Dl)27 b(Objects)0 1316 y FN(Dl)21 b(objects,)e(as)i (returned)e(by)h FJ(open\(\))f FN(abo)o(v)o(e,)f(ha)n(v)o(e)i(the)g (follo)n(wing)f(methods:)0 1463 y FD(close)p FJ(\(\))208 1563 y FN(Free)h(all)h(resources,)e(e)o(xcept)g(the)h(memory)-5 b(.)0 1709 y FD(sym)p FJ(\()p FK(name)p FJ(\))208 1809 y FN(Return)20 b(the)i(pointer)e(for)h(the)g(function)f(named)g FK(name)p FN(,)h(as)h(a)g(number)m(,)d(if)j(it)g(e)o(xists)g(in)f(the)h (referenced)d(shared)i(object,)f(other)n(-)208 1909 y(wise)g FJ(None)p FN(.)25 b(This)c(is)g(useful)e(in)i(code)e(lik)o(e:)444 2035 y FA(>>>)44 b(if)h(a.sym\('time'\):)444 2126 y(...)223 b(a.call\('time'\))444 2217 y(...)44 b(else:)444 2309 y(...)223 b(time.time\(\))208 2491 y FN(\(Note)19 b(that)i(this)f (function)f(will)i(return)e(a)h(non-zero)e(number)m(,)g(as)j(zero)f(is) h(the)f FJ(NULL)g FN(pointer\))0 2638 y FD(call)p FJ(\()p FK(name)p FC([)p FK(,)e(ar)m(g1)p FC([)p FK(,)h(ar)m(g2.)12 b(.)g(.)23 b FC(])12 b(])p FJ(\))208 2738 y FN(Call)24 b(the)g(function)e(named)g FK(name)h FN(in)h(the)f(referenced)f(shared) h(object.)34 b(The)23 b(ar)o(guments)f(must)i(be)f(either)g(Python)g (inte)o(gers,)208 2837 y(which)d(will)i(be)f(passed)h(as)f(is,)i (Python)d(strings,)h(to)g(which)g(a)h(pointer)e(will)i(be)f(passed,)g (or)g FJ(None)p FN(,)g(which)g(will)h(be)f(passed)g(as)208 2937 y FJ(NULL)p FN(.)d(Note)h(that)g(strings)h(should)e(only)g(be)h (passed)g(to)g(functions)f(as)i FJ(const)48 b(char)2761 2952 y(*)2811 2937 y FN(,)19 b(as)h(Python)e(will)i(not)e(lik)o(e)i (its)g(string)208 3037 y(mutated.)208 3163 y(There)j(must)h(be)g(at)g (most)g(10)g(ar)o(guments,)f(and)g(ar)o(guments)f(not)i(gi)n(v)o(en)e (will)j(be)f(treated)f(as)i FJ(None)p FN(.)36 b(The)24 b(function')-5 b(s)23 b(return)208 3262 y(v)n(alue)c(must)h(be)g(a)h(C) g FJ(long)p FN(,)f(which)g(is)h(a)f(Python)f(inte)o(ger)-5 b(.)0 3583 y FE(16.7)121 b Fx(termios)32 b FE(\227)g(POSIX)h(style)g (tty)h(control)0 3816 y FN(This)19 b(module)f(pro)o(vides)f(an)i (interf)o(ace)f(to)i(the)f(POSIX)g(calls)h(for)e(tty)i(I/O)f(control.)k (F)o(or)c(a)h(complete)e(description)f(of)i(these)g(calls,)h(see)0 3916 y(the)i(POSIX)h(or)h(U)t FH(N)t(I)t(X)h FN(manual)c(pages.)31 b(It)22 b(is)i(only)d(a)n(v)n(ailable)h(for)f(those)k(U)t FH(N)t(I)t(X)g FN(v)o(ersions)c(that)h(support)f(POSIX)i FK(termios)g FN(style)f(tty)0 4016 y(I/O)e(control)f(\(and)h(then)f (only)h(if)g(con\002gured)e(at)j(installation)f(time\).)0 4162 y(All)g(functions)f(in)h(this)g(module)e(tak)o(e)i(a)g(\002le)h (descriptor)d FK(fd)k FN(as)f(their)e(\002rst)i(ar)o(gument.)h(This)e (can)g(be)f(an)h(inte)o(ger)f(\002le)h(descriptor)m(,)e(such)0 4262 y(as)j(returned)d(by)i FJ(sys.stdin.fileno\(\))p FN(,)d(or)j(a)h(\002le)g(object,)e(such)h(as)h FJ(sys.stdin)e FN(itself.)0 4409 y(This)g(module)f(also)i(de\002nes)f(all)h(the)f (constants)g(needed)f(to)h(w)o(ork)g(with)g(the)h(functions)d(pro)o (vided)g(here;)i(these)h(ha)n(v)o(e)e(the)i(same)f(name)0 4509 y(as)27 b(their)e(counterparts)f(in)i(C.)g(Please)h(refer)e(to)h (your)e(system)i(documentation)d(for)i(more)g(information)f(on)h(using) g(these)h(terminal)0 4608 y(control)19 b(interf)o(aces.)0 4755 y(The)h(module)f(de\002nes)h(the)g(follo)n(wing)e(functions:)0 4902 y FD(tcgetattr)p FJ(\()p FK(fd)r FJ(\))208 5001 y FN(Return)28 b(a)i(list)g(containing)e(the)h(tty)g(attrib)n(utes)h (for)e(\002le)i(descriptor)e FK(fd)r FN(,)k(as)e(follo)n(ws:)42 b FJ([)p FK(i\003a)o(g)p FN(,)31 b FK(o\003a)o(g)p FN(,)f FK(c\003a)o(g)p FN(,)g FK(l\003a)o(g)p FN(,)h FK(ispeed)r FN(,)208 5101 y FK(ospeed)r FN(,)f FK(cc)p FJ(])g FN(where)e FK(cc)i FN(is)g(a)g(list)g(of)f(the)g(tty)h(special)f(characters)f (\(each)h(a)h(string)e(of)h(length)g(1,)i(e)o(xcept)d(the)i(items)f (with)208 5201 y(indices)e FJ(VMIN)h FN(and)f FJ(VTIME)p FN(,)g(which)g(are)h(inte)o(gers)f(when)g(these)h(\002elds)h(are)e (de\002ned\).)47 b(The)27 b(interpretation)f(of)h(the)h(\003ags)208 5300 y(and)20 b(the)i(speeds)f(as)h(well)g(as)g(the)g(inde)o(xing)d(in) i(the)h FK(cc)f FN(array)g(must)g(be)h(done)e(using)h(the)g(symbolic)g (constants)g(de\002ned)f(in)i(the)208 5400 y FJ(termios)d FN(module.)p 0 5549 3901 4 v 0 5649 a FI(558)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 559 571 TeXDict begin 559 570 bop 0 83 a FD(tcsetattr)p FJ(\()p FK(fd,)18 b(when,)i(attrib)n(utes)p FJ(\))208 183 y FN(Set)41 b(the)f(tty)h(attrib)n(utes)g(for)f(\002le)h(descriptor)e FK(fd)k FN(from)c(the)i FK(attrib)n(utes)p FN(,)46 b(which)40 b(is)h(a)g(list)h(lik)o(e)f(the)f(one)g(returned)f(by)208 282 y FJ(tcgetattr\(\))p FN(.)44 b(The)26 b FK(when)h FN(ar)o(gument)e(determines)h(when)g(the)h(attrib)n(utes)g(are)g (changed:)37 b FJ(TCSANOW)27 b FN(to)g(change)f(im-)208 382 y(mediately)-5 b(,)22 b FJ(TCSADRAIN)g FN(to)h(change)f(after)h (transmitting)f(all)i(queued)d(output,)i(or)g FJ(TCSAFLUSH)f FN(to)h(change)f(after)h(trans-)208 482 y(mitting)c(all)i(queued)e (output)f(and)i(discarding)f(all)i(queued)d(input.)0 628 y FD(tcsendbreak)p FJ(\()p FK(fd,)g(dur)o(ation)p FJ(\))208 728 y FN(Send)j(a)h(break)e(on)i(\002le)g(descriptor)e FK(fd)r FN(.)30 b(A)22 b(zero)f FK(dur)o(ation)f FN(sends)i(a)g(break)e (for)h(0.25\2260.5)e(seconds;)j(a)g(nonzero)d FK(dur)o(ation)h FN(has)208 828 y(a)g(system)h(dependent)d(meaning.)0 975 y FD(tcdrain)p FJ(\()p FK(fd)r FJ(\))208 1074 y FN(W)-7 b(ait)21 b(until)f(all)h(output)e(written)h(to)g(\002le)h(descriptor)e FK(fd)j FN(has)f(been)e(transmitted.)0 1221 y FD(tcflush)p FJ(\()p FK(fd,)g(queue)p FJ(\))208 1321 y FN(Discard)j(queued)e(data)j (on)f(\002le)h(descriptor)e FK(fd)r FN(.)32 b(The)22 b FK(queue)f FN(selector)h(speci\002es)h(which)f(queue:)29 b FJ(TCIFLUSH)21 b FN(for)h(the)g(input)208 1420 y(queue,)c FJ(TCOFLUSH)i FN(for)f(the)h(output)f(queue,)g(or)h FJ(TCIOFLUSH)f FN(for)h(both)f(queues.)0 1567 y FD(tcflow)p FJ(\()p FK(fd,)g(action)p FJ(\))208 1667 y FN(Suspend)d(or)i(resume)f(input)g (or)g(output)f(on)i(\002le)g(descriptor)e FK(fd)r FN(.)25 b(The)17 b FK(action)g FN(ar)o(gument)e(can)j(be)f FJ(TCOOFF)g FN(to)h(suspend)f(output,)208 1766 y FJ(TCOON)i FN(to)i(restart)f (output,)f FJ(TCIOFF)g FN(to)i(suspend)e(input,)g(or)h FJ(TCION)g FN(to)g(restart)g(input.)0 1913 y FL(See)h(Also:)0 2060 y FN(Module)e FJ(tty)h FN(\(section)g(16.8\):)208 2160 y(Con)m(v)o(enience)d(functions)i(for)h(common)e(terminal)h (control)g(operations.)0 2445 y Fv(16.7.1)101 b(Example)0 2648 y FN(Here')-5 b(s)39 b(a)h(function)d(that)i(prompts)e(for)i(a)g (passw)o(ord)f(with)i(echoing)d(turned)h(of)n(f.)80 b(Note)39 b(the)g(technique)e(using)i(a)g(separate)0 2747 y FJ(tcgetattr\(\))30 b FN(call)j(and)e(a)i FJ(try)f FN(...)60 b FJ(finally)31 b FN(statement)h(to)g(ensure)f(that)h(the)g(old)g(tty)g(attrib)n(utes)g (are)g(restored)e(e)o(xactly)0 2847 y(no)20 b(matter)g(what)g(happens:) 236 3085 y FA(def)45 b(getpass\(prompt)d(=)j("Password:)e("\):)416 3176 y(import)g(termios,)h(sys)416 3268 y(fd)g(=)h (sys.stdin.fileno\(\))416 3359 y(old)f(=)h(termios.tcgetattr\(fd\))416 3450 y(new)f(=)h(termios.tcgetattr\(fd\))416 3542 y(new[3])e(=)i (new[3])f(&)h(\230termios.ECHO)446 b(#)44 b(lflags)416 3633 y(try:)595 3724 y(termios.tcsetattr\(fd,)d(termios.TCSADRAIN,)h (new\))595 3816 y(passwd)i(=)g(raw_input\(prompt\))416 3907 y(finally:)595 3998 y(termios.tcsetattr\(fd,)d(termios.TCSADRAIN,) h(old\))416 4090 y(return)h(passwd)0 4600 y FE(16.8)121 b Fx(tty)33 b FE(\227)f(T)-14 b(er)s(minal)33 b(control)h(functions)0 4832 y FN(The)20 b FJ(tty)g FN(module)f(de\002nes)h(functions)f(for)g (putting)g(the)h(tty)h(into)f(cbreak)f(and)g(ra)o(w)h(modes.)0 4979 y(Because)g(it)h(requires)e(the)i FJ(termios)e FN(module,)g(it)i (will)g(w)o(ork)e(only)g(on)j(U)t FH(N)t(I)t(X)r FN(.)0 5126 y(The)e FJ(tty)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (functions:)0 5273 y FD(setraw)p FJ(\()p FK(fd)r FC([)p FK(,)g(when)12 b FC(])p FJ(\))208 5373 y FN(Change)17 b(the)i(mode)f(of)g(the)h(\002le)h(descriptor)d FK(fd)k FN(to)e(ra)o(w)-5 b(.)24 b(If)18 b FK(when)h FN(is)h(omitted,)e(it)h (def)o(aults)f(to)h FJ(termios.TCSAFLUSH)p FN(,)d(and)p 0 5549 3901 4 v 0 5649 a FI(16.8.)52 b FJ(tty)23 b FI(\227)g(T)-10 b(er)r(minal)24 b(control)f(functions)2305 b(559)p eop end %%Page: 560 572 TeXDict begin 560 571 bop 208 83 a FN(is)21 b(passed)f(to)g FJ(termios.tcsetattr\(\))p FN(.)0 230 y FD(setcbreak)p FJ(\()p FK(fd)r FC([)p FK(,)e(when)12 b FC(])p FJ(\))208 330 y FN(Change)19 b(the)g(mode)g(of)h(\002le)g(descriptor)f FK(fd)j FN(to)e(cbreak.)j(If)d FK(when)g FN(is)g(omitted,)f(it)i(def)o (aults)e(to)h FJ(termios.TCSAFLUSH)p FN(,)d(and)208 429 y(is)k(passed)f(to)g FJ(termios.tcsetattr\(\))p FN(.)0 576 y FL(See)h(Also:)0 723 y FN(Module)e FJ(termios)g FN(\(section)h(16.7\):)208 823 y(Lo)n(w-le)n(v)o(el)e(terminal)i (control)f(interf)o(ace.)0 1150 y FE(16.9)121 b Fx(pty)33 b FE(\227)f(Pseudo-ter)s(minal)j(utilities)0 1383 y FN(The)18 b FJ(pty)h FN(module)e(de\002nes)h(operations)f(for)h(handling)f(the)h (pseudo-terminal)e(concept:)23 b(starting)18 b(another)f(process)h(and) g(being)g(able)0 1482 y(to)i(write)h(to)f(and)g(read)f(from)g(its)j (controlling)c(terminal)h(programmatically)-5 b(.)0 1629 y(Because)23 b(pseudo-terminal)d(handling)h(is)j(highly)d(platform)h (dependant,)f(there)h(is)i(code)e(to)h(do)f(it)i(only)e(for)g(SGI)h (and)g(Linux.)31 b(\(The)0 1729 y(Linux)19 b(code)h(is)h(supposed)d(to) j(w)o(ork)e(on)h(other)g(platforms,)e(b)n(ut)i(hasn')o(t)g(been)f (tested)i(yet.\))0 1876 y(The)f FJ(pty)g FN(module)f(de\002nes)h(the)g (follo)n(wing)f(functions:)0 2023 y FD(fork)p FJ(\(\))208 2122 y FN(F)o(ork.)30 b(Connect)22 b(the)g(child')-5 b(s)23 b(controlling)d(terminal)h(to)i(a)g(pseudo-terminal.)28 b(Return)22 b(v)n(alue)g(is)h FJ(\()p FK(pid)r FJ(,)49 b FK(fd)r FJ(\))p FN(.)32 b(Note)22 b(that)h(the)208 2222 y(child)d(gets)h FK(pid)i FN(0,)e(and)g(the)f FK(fd)k FN(is)e FK(in)m(valid)p FN(.)k(The)20 b(parent')-5 b(s)21 b(return)e(v)n(alue)i(is)h(the)f FK(pid)h FN(of)f(the)g(child,)f(and)h FK(fd)i FN(is)f(a)f(\002le)h(descriptor)208 2321 y(connected)c(to)i (the)g(child')-5 b(s)21 b(controlling)d(terminal)h(\(and)g(also)i(to)f (the)h(child')-5 b(s)20 b(standard)f(input)g(and)h(output\).)0 2468 y FD(openpty)p FJ(\(\))208 2568 y FN(Open)k(a)h(ne)n(w)f (pseudo-terminal)e(pair)m(,)i(using)g FJ(os.openpty\(\))f FN(if)i(possible,)g(or)g(emulation)e(code)h(for)g(SGI)h(and)f(generic) 210 2668 y(U)t FH(N)t(I)t(X)c FN(systems.)25 b(Return)17 b(a)i(pair)e(of)h(\002le)g(descriptors)f FJ(\()p FK(master)r FJ(,)49 b FK(slave)p FJ(\))p FN(,)18 b(for)f(the)h(master)g(and)f(the)h (sla)n(v)o(e)g(end,)g(respecti)n(v)o(ely)-5 b(.)0 2814 y FD(spawn)p FJ(\()p FK(ar)m(gv)p FC([)p FK(,)18 b(master)p 760 2814 25 4 v 30 w(r)m(ead)r FC([)p FK(,)i(stdin)p 1185 2814 V 29 w(r)m(ead)13 b FC(])f(])p FJ(\))208 2914 y FN(Spa)o(wn)20 b(a)i(process,)f(and)g(connect)f(its)j(controlling)c (terminal)i(with)h(the)f(current)f(process')-5 b(s)22 b(standard)e(io.)29 b(This)22 b(is)g(often)f(used)208 3014 y(to)f(baf)n(\003e)g(programs)e(which)i(insist)h(on)e(reading)g (from)g(the)i(controlling)d(terminal.)208 3147 y(The)23 b(functions)g FK(master)p 926 3147 V 30 w(r)m(ead)j FN(and)e FK(stdin)p 1439 3147 V 29 w(r)m(ead)i FN(should)d(be)h(functions)f (which)g(read)h(from)f(a)i(\002le-descriptor)-5 b(.)35 b(The)24 b(def)o(aults)208 3246 y(try)c(to)g(read)g(1024)e(bytes)i (each)g(time)h(the)o(y)e(are)h(called.)0 3574 y FE(16.10)122 b Fx(fcntl)32 b FE(\227)g(The)j Fx(fcntl\(\))c FE(and)k Fx(ioctl\(\))c FE(system)i(calls)0 3806 y FN(This)18 b(module)f(performs)g(\002le)i(control)e(and)h(I/O)g(control)g(on)f (\002le)i(descriptors.)24 b(It)18 b(is)h(an)g(interf)o(ace)e(to)i(the)f FJ(fcntl\(\))g FN(and)f FJ(ioctl\(\))2 3906 y FN(U)t FH(N)t(I)t(X)23 b FN(routines.)0 4053 y(All)d(functions)f(in)h(this)g (module)e(tak)o(e)i(a)g(\002le)h(descriptor)d FK(fd)k FN(as)f(their)e(\002rst)i(ar)o(gument.)h(This)e(can)g(be)f(an)h(inte)o (ger)f(\002le)h(descriptor)m(,)e(such)0 4153 y(as)23 b(returned)d(by)h FJ(sys.stdin.fileno\(\))p FN(,)f(or)h(a)i(\002le)f (object,)g(such)f(as)i FJ(sys.stdin)e FN(itself,)i(which)e(pro)o(vides) f(a)i FJ(fileno\(\))0 4252 y FN(which)e(returns)f(a)i(genuine)d(\002le) j(descriptor)-5 b(.)0 4399 y(The)20 b(module)f(de\002nes)h(the)g(follo) n(wing)e(functions:)0 4546 y FD(fcntl)p FJ(\()p FK(fd,)h(op)p FC([)p FK(,)g(ar)m(g)12 b FC(])p FJ(\))208 4646 y FN(Perform)20 b(the)h(requested)g(operation)e(on)j(\002le)g(descriptor)e FK(fd)k FN(\(\002le)e(objects)f(pro)o(viding)e(a)j FJ(fileno\(\))f FN(method)f(are)i(accepted)208 4745 y(as)29 b(well\).)49 b(The)28 b(operation)e(is)j(de\002ned)f(by)g FK(op)f FN(and)h(is)h(operating)e(system)h(dependent.)47 b(These)28 b(codes)g(are)g(also)h(found)d(in)208 4845 y(the)g FJ(fcntl)g FN(module.)43 b(The)26 b(ar)o(gument)e FK(ar)m(g)i FN(is)h(optional,)g (and)f(def)o(aults)g(to)g(the)h(inte)o(ger)e(v)n(alue)h FJ(0)p FN(.)44 b(When)26 b(present,)i(it)f(can)208 4944 y(either)d(be)h(an)g(inte)o(ger)f(v)n(alue,)h(or)f(a)i(string.)39 b(W)m(ith)25 b(the)g(ar)o(gument)d(missing)j(or)g(an)g(inte)o(ger)e(v)n (alue,)i(the)g(return)f(v)n(alue)g(of)h(this)208 5044 y(function)18 b(is)i(the)g(inte)o(ger)f(return)g(v)n(alue)g(of)g(the)h (C)h FJ(fcntl\(\))e FN(call.)25 b(When)20 b(the)g(ar)o(gument)d(is)k(a) g(string)e(it)i(represents)e(a)h(binary)208 5144 y(structure,)i(e.g.)g (created)h(by)f FJ(struct.pack\(\))p FN(.)32 b(The)22 b(binary)g(data)h(is)h(copied)d(to)j(a)f(b)n(uf)n(fer)f(whose)g (address)h(is)h(passed)e(to)208 5243 y(the)f(C)i FJ(fcntl\(\))e FN(call.)31 b(The)21 b(return)g(v)n(alue)g(after)h(a)g(successful)f (call)i(is)g(the)e(contents)h(of)f(the)h(b)n(uf)n(fer)m(,)e(con)m(v)o (erted)g(to)i(a)g(string)208 5343 y(object.)33 b(The)23 b(length)f(of)h(the)g(returned)e(string)i(will)h(be)f(the)g(same)g(as)h (the)f(length)g(of)g(the)g FK(ar)m(g)g FN(ar)o(gument.)31 b(This)23 b(is)h(limited)f(to)p 0 5549 3901 4 v 0 5649 a FI(560)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r (vices)p eop end %%Page: 561 573 TeXDict begin 561 572 bop 208 83 a FN(1024)22 b(bytes.)37 b(If)24 b(the)g(information)e(returned)g(in)i(the)h(b)n(uf)n(fer)d(by)i (the)g(operating)f(system)h(is)h(lar)o(ger)e(than)g(1024)g(bytes,)i (this)g(is)208 183 y(most)20 b(lik)o(ely)g(to)g(result)g(in)h(a)f(se)o (gmentation)f(violation)g(or)h(a)g(more)f(subtle)i(data)f(corruption.) 208 310 y(If)g(the)g FJ(fcntl\(\))f FN(f)o(ails,)i(an)f FJ(IOError)f FN(is)j(raised.)0 456 y FD(ioctl)p FJ(\()p FK(fd,)d(op)p FC([)p FK(,)g(ar)m(g)p FC([)p FK(,)h(mutate)p 995 456 25 4 v 29 w(\003a)o(g)12 b FC(])g(])p FJ(\))208 556 y FN(This)17 b(function)f(is)i(identical)e(to)i(the)f FJ(fcntl\(\))g FN(function,)f(e)o(xcept)g(that)h(the)g(operations)f (are)h(typically)g(de\002ned)f(in)h(the)h(library)208 656 y(module)g FJ(termios)i FN(and)f(the)i(ar)o(gument)d(handling)g(is) j(e)n(v)o(en)e(more)h(complicated.)208 783 y(The)k(parameter)g FK(ar)m(g)h FN(can)g(be)g(one)g(of)f(an)i(inte)o(ger)m(,)e(absent)h (\(treated)f(identically)h(to)g(the)g(inte)o(ger)f FJ(0)p FN(\),)i(an)f(object)g(supporting)208 882 y(the)f(read-only)f(b)n(uf)n (fer)g(interf)o(ace)h(\(most)g(lik)o(ely)h(a)g(plain)f(Python)g (string\))g(or)g(an)h(object)f(supporting)f(the)h(read-write)g(b)n(uf)n (fer)208 982 y(interf)o(ace.)208 1109 y(In)19 b(all)i(b)n(ut)f(the)h (last)g(case,)f(beha)n(viour)e(is)j(as)g(for)f(the)g FJ(fcntl\(\))f FN(function.)208 1236 y(If)h(a)g(mutable)f(b)n(uf)n(fer) g(is)i(passed,)f(then)g(the)g(beha)n(viour)e(is)j(determined)e(by)g (the)i(v)n(alue)e(of)h(the)g FK(mutate)p 3164 1236 V 29 w(\003a)o(g)g FN(parameter)-5 b(.)208 1363 y(If)24 b(it)h(is)g(f)o(alse,)h(the)f(b)n(uf)n(fer')-5 b(s)23 b(mutability)g(is)j(ignored)c(and)i(beha)n(viour)f(is)i(as)g(for)f(a)h (read-only)d(b)n(uf)n(fer)m(,)i(e)o(xcept)f(that)i(the)f(1024)208 1462 y(byte)d(limit)h(mentioned)e(abo)o(v)o(e)g(is)j(a)n(v)n(oided)e (\226)h(so)g(long)f(as)h(the)g(b)n(uf)n(fer)f(you)g(pass)h(is)h(as)f (least)h(as)f(long)f(as)i(what)f(the)f(operating)208 1562 y(system)f(w)o(ants)h(to)f(put)g(there,)f(things)h(should)f(w)o (ork.)208 1689 y(If)24 b FK(mutate)p 520 1689 V 29 w(\003a)o(g)f FN(is)j(true,)f(then)f(the)g(b)n(uf)n(fer)f(is)j(\(in)e(ef)n(fect\))f (passed)i(to)f(the)h(underlying)d FJ(ioctl\(\))h FN(system)i(call,)h (the)e(latter')-5 b(s)208 1788 y(return)14 b(code)i(is)h(passed)e(back) h(to)g(the)g(calling)f(Python,)h(and)f(the)h(b)n(uf)n(fer')-5 b(s)15 b(ne)n(w)h(contents)f(re\003ect)h(the)g(action)g(of)g(the)g FJ(ioctl\(\))p FN(.)208 1888 y(This)21 b(is)i(a)f(slight)g (simpli\002cation,)e(because)h(if)h(the)g(supplied)e(b)n(uf)n(fer)h(is) h(less)h(than)e(1024)f(bytes)h(long)g(it)h(is)h(\002rst)f(copied)f (into)g(a)208 1988 y(static)g(b)n(uf)n(fer)d(1024)h(bytes)h(long)g (which)f(is)i(then)f(passed)g(to)h FJ(ioctl\(\))e FN(and)h(copied)f (back)g(into)h(the)g(supplied)f(b)n(uf)n(fer)-5 b(.)208 2114 y(If)21 b FK(mutate)p 517 2114 V 29 w(\003a)o(g)f FN(is)i(not)f(supplied,)f(then)h(from)f(Python)h(2.5)f(it)i(def)o (aults)f(to)g(true,)g(which)g(is)h(a)g(change)e(from)g(v)o(ersions)h (2.3)f(and)208 2214 y(2.4.)k(Supply)19 b(the)h(ar)o(gument)e(e)o (xplicitly)h(if)i(v)o(ersion)d(portability)h(is)i(a)g(priority)-5 b(.)208 2341 y(An)20 b(e)o(xample:)444 2559 y FA(>>>)44 b(import)g(array,)g(fcntl,)g(struct,)f(termios,)h(os)444 2651 y(>>>)g(os.getpgrp\(\))444 2742 y(13341)444 2833 y(>>>)g(struct.unpack\('h',)e(fcntl.ioctl\(0,)g(termios.TIOCGPGRP,)g(") 90 b("\)\)[0])444 2925 y(13341)444 3016 y(>>>)44 b(buf)g(=)h (array.array\('h',)d([0]\))444 3107 y(>>>)i(fcntl.ioctl\(0,)f (termios.TIOCGPGRP,)e(buf,)k(1\))444 3198 y(0)444 3290 y(>>>)f(buf)444 3381 y(array\('h',)f([13341]\))0 3585 y FD(flock)p FJ(\()p FK(fd,)19 b(op)p FJ(\))208 3684 y FN(Perform)g(the)h(lock)g(operation)e FK(op)i FN(on)g(\002le)h (descriptor)e FK(fd)k FN(\(\002le)d(objects)h(pro)o(viding)c(a)k FJ(fileno\(\))e FN(method)g(are)i(accepted)e(as)208 3784 y(well\).)24 b(See)c(the)i(U)t FH(N)t(I)t(X)h FN(manual)18 b FK(\003oc)n(k)p FN(\(3\))g(for)h(details.)25 b(\(On)20 b(some)f(systems,)h(this)g(function)e(is)i(emulated)f(using)g FJ(fcntl\(\))p FN(.\))0 3931 y FD(lockf)p FJ(\()p FK(fd,)g(oper)o (ation,)f FC([)p FK(length,)h FC([)p FK(start,)i FC([)p FK(whence)12 b FC(])g(])g(])p FJ(\))208 4031 y FN(This)24 b(is)h(essentially)g(a)g(wrapper)e(around)f(the)j FJ(fcntl\(\))e FN(locking)g(calls.)38 b FK(fd)27 b FN(is)e(the)g(\002le)g(descriptor)e (of)h(the)g(\002le)h(to)g(lock)f(or)208 4130 y(unlock,)18 b(and)i FK(oper)o(ation)e FN(is)j(one)f(of)g(the)g(follo)n(wing)f(v)n (alues:)349 4332 y FM(\017)o FJ(LOCK_UN)h FN(\226)g(unlock)349 4453 y FM(\017)o FJ(LOCK_SH)g FN(\226)g(acquire)f(a)i(shared)e(lock)349 4574 y FM(\017)o FJ(LOCK_EX)h FN(\226)g(acquire)f(an)h(e)o(xclusi)n(v)o (e)f(lock)208 4775 y(When)29 b FK(oper)o(ation)e FN(is)j FJ(LOCK_SH)e FN(or)h FJ(LOCK_EX)p FN(,)g(it)g(can)g(also)h(be)f (bit-wise)g(OR')l(d)g(with)h FJ(LOCK_NB)e FN(to)i(a)n(v)n(oid)e (blocking)208 4875 y(on)g(lock)g(acquisition.)48 b(If)29 b FJ(LOCK_NB)e FN(is)j(used)e(and)g(the)h(lock)f(cannot)f(be)h (acquired,)h(an)f FJ(IOError)g FN(will)h(be)g(raised)f(and)208 4974 y(the)23 b(e)o(xception)e(will)j(ha)n(v)o(e)e(an)h FK(errno)g FN(attrib)n(ute)g(set)h(to)f FJ(EACCES)f FN(or)h FJ(EAGAIN)f FN(\(depending)f(on)h(the)h(operating)e(system;)k(for)208 5074 y(portability)-5 b(,)21 b(check)h(for)g(both)g(v)n(alues\).)31 b(On)23 b(at)g(least)h(some)e(systems,)i FJ(LOCK_EX)e FN(can)g(only)g(be)h(used)f(if)h(the)g(\002le)g(descriptor)208 5173 y(refers)c(to)i(a)f(\002le)h(opened)e(for)g(writing.)208 5300 y FK(length)24 b FN(is)j(the)f(number)e(of)i(bytes)f(to)h(lock,)h FK(start)h FN(is)f(the)e(byte)h(of)n(fset)f(at)h(which)g(the)f(lock)h (starts,)i(relati)n(v)o(e)d(to)h FK(whence)p FN(,)g(and)208 5400 y FK(whence)19 b FN(is)i(as)g(with)g FJ(fileobj.seek\(\))p FN(,)d(speci\002cally:)p 0 5549 3901 4 v 0 5649 a FI(16.10.)52 b FJ(fcntl)23 b FI(\227)g(The)g FJ(fcntl\(\))f FI(and)h FJ(ioctl\(\))f FI(system)g(calls)1578 b(561)p eop end %%Page: 562 574 TeXDict begin 562 573 bop 349 83 a FM(\017)o FJ(0)21 b FN(\226)f(relati)n(v)o(e)f(to)i(the)f(start)h(of)f(the)g(\002le)h(\() p FJ(SEEK_SET)p FN(\))349 216 y FM(\017)o FJ(1)g FN(\226)f(relati)n(v)o (e)f(to)i(the)f(current)f(b)n(uf)n(fer)g(position)g(\()p FJ(SEEK_CUR)p FN(\))349 349 y FM(\017)o FJ(2)i FN(\226)f(relati)n(v)o (e)f(to)i(the)f(end)g(of)g(the)g(\002le)h(\()p FJ(SEEK_END)p FN(\))208 562 y(The)k(def)o(ault)f(for)h FK(start)j FN(is)f(0,)f(which) f(means)g(to)h(start)g(at)g(the)g(be)o(ginning)c(of)k(the)f(\002le.)42 b(The)25 b(def)o(ault)g(for)f FK(length)h FN(is)i(0)e(which)208 662 y(means)19 b(to)i(lock)e(to)i(the)f(end)g(of)g(the)g(\002le.)25 b(The)20 b(def)o(ault)g(for)f FK(whence)h FN(is)h(also)g(0.)0 808 y(Examples)e(\(all)i(on)e(a)i(SVR4)g(compliant)e(system\):)236 1047 y FA(import)44 b(struct,)g(fcntl,)g(os)236 1229 y(f)h(=)g(open\(...\))236 1321 y(rv)g(=)f(fcntl.fcntl\(f,)f (fcntl.F_SETFL,)f(os.O_NDELAY\))236 1503 y(lockdata)i(=)g (struct.pack\('hhllhh',)e(fcntl.F_WRLCK,)g(0,)j(0,)f(0,)h(0,)f(0\))236 1595 y(rv)h(=)f(fcntl.fcntl\(f,)f(fcntl.F_SETLKW,)f(lockdata\))0 1881 y FN(Note)19 b(that)h(in)g(the)f(\002rst)i(e)o(xample)d(the)h (return)g(v)n(alue)f(v)n(ariable)h FK(rv)h FN(will)g(hold)f(an)g(inte)o (ger)g(v)n(alue;)g(in)h(the)f(second)g(e)o(xample)f(it)i(will)g(hold)0 1981 y(a)25 b(string)e(v)n(alue.)37 b(The)23 b(structure)h(lay-out)e (for)i(the)g FK(loc)n(kdata)f FN(v)n(ariable)g(is)i(system)g(dependent) c(\227)k(therefore)e(using)g(the)h FJ(flock\(\))0 2080 y FN(call)d(may)e(be)h(better)-5 b(.)0 2227 y FL(See)21 b(Also:)0 2374 y FN(Module)e FJ(os)h FN(\(section)g(14.1\):)208 2474 y(If)i(the)h(locking)e(\003ags)i FJ(O_SHLOCK)f FN(and)g FJ(O_EXLOCK)f FN(are)i(present)f(in)h(the)f FJ(os)h FN(module,)f(the)g FJ(os.open\(\))g FN(function)f(pro-)208 2573 y(vides)f(a)g(more)g (platform-independent)15 b(alternati)n(v)o(e)k(to)h(the)g FJ(lockf\(\))g FN(and)f FJ(flock\(\))h FN(functions.)0 2901 y FE(16.11)122 b Fx(pipes)32 b FE(\227)g(Interf)l(ace)k(to)e (shell)f(pipelines)0 3134 y FN(The)23 b FJ(pipes)f FN(module)g (de\002nes)h(a)h(class)g(to)f(abstract)g(the)g(concept)f(of)h(a)g FK(pipeline)f FN(\227)i(a)f(sequence)f(of)h(con)m(v)o(erters)e(from)h (one)h(\002le)g(to)0 3233 y(another)-5 b(.)0 3380 y(Because)16 b(the)g(module)f(uses)i FL(/bin/sh)g FN(command)d(lines,)j(a)g(POSIX)f (or)g(compatible)f(shell)h(for)g FJ(os.system\(\))e FN(and)i FJ(os.popen\(\))0 3480 y FN(is)21 b(required.)0 3627 y(The)f FJ(pipes)g FN(module)e(de\002nes)i(the)h(follo)n(wing)d(class:) 0 3773 y FL(class)j FD(Template)p FJ(\(\))208 3873 y FN(An)f(abstraction)f(of)h(a)g(pipeline.)0 4020 y(Example:)236 4258 y FA(>>>)45 b(import)e(pipes)236 4349 y(>>>)i (t=pipes.Template\(\))236 4441 y(>>>)g(t.append\('tr)d(a-z)j(A-Z',)f ('--'\))236 4532 y(>>>)h(f=t.open\('/tmp/1',)c('w'\))236 4623 y(>>>)k(f.write\('hello)d(world'\))236 4715 y(>>>)j(f.close\(\)) 236 4806 y(>>>)g(open\('/tmp/1'\).read\(\))236 4897 y('HELLO)f(WORLD')p 0 5549 3901 4 v 0 5649 a FI(562)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 563 575 TeXDict begin 563 574 bop 0 83 a Fv(16.11.1)101 b(T)-12 b(emplate)29 b(Objects)0 286 y FN(T)-6 b(emplate)20 b(objects)f(follo)n (wing)g(methods:)0 433 y FD(reset)p FJ(\(\))208 532 y FN(Restore)h(a)h(pipeline)e(template)g(to)i(its)g(initial)g(state.)0 679 y FD(clone)p FJ(\(\))208 779 y FN(Return)e(a)i(ne)n(w)-5 b(,)19 b(equi)n(v)n(alent,)f(pipeline)i(template.)0 926 y FD(debug)p FJ(\()p FK(\003a)o(g)p FJ(\))208 1025 y FN(If)28 b FK(\003a)o(g)h FN(is)g(true,)i(turn)d(deb)n(ugging)f(on.)50 b(Otherwise,)31 b(turn)d(deb)n(ugging)e(of)n(f.)51 b(When)29 b(deb)n(ugging)d(is)k(on,)g(commands)e(to)h(be)208 1125 y(e)o(x)o(ecuted)18 b(are)i(printed,)f(and)g(the)i(shell)f(is)h(gi)n(v) o(en)e FJ(set)49 b(-x)21 b FN(command)d(to)i(be)g(more)g(v)o(erbose.)0 1272 y FD(append)p FJ(\()p FK(cmd,)f(kind)r FJ(\))208 1372 y FN(Append)j(a)j(ne)n(w)f(action)g(at)h(the)f(end.)37 b(The)24 b FK(cmd)j FN(v)n(ariable)c(must)i(be)f(a)h(v)n(alid)f(bourne) e(shell)j(command.)35 b(The)25 b FK(kind)h FN(v)n(ariable)208 1471 y(consists)20 b(of)g(tw)o(o)h(letters.)208 1604 y(The)i(\002rst)i(letter)f(can)g(be)g(either)g(of)g FJ('-')g FN(\(which)f(means)h(the)g(command)e(reads)i(its)h(standard)e(input\),) h FJ('f')g FN(\(which)f(means)208 1704 y(the)18 b(commands)g(reads)g(a) i(gi)n(v)o(en)d(\002le)j(on)e(the)h(command)e(line\))i(or)f FJ('.')25 b FN(\(which)18 b(means)h(the)g(commands)e(reads)h(no)h (input,)f(and)208 1803 y(hence)h(must)h(be)g(\002rst.\))208 1936 y(Similarly)-5 b(,)25 b(the)f(second)g(letter)h(can)g(be)g(either) f(of)h FJ('-')f FN(\(which)g(means)h(the)g(command)e(writes)i(to)g (standard)e(output\),)i FJ('f')208 2036 y FN(\(which)e(means)h(the)h (command)d(writes)j(a)g(\002le)g(on)f(the)g(command)e(line\))j(or)f FJ('.')37 b FN(\(which)24 b(means)g(the)g(command)f(does)h(not)208 2135 y(write)c(an)o(ything,)e(and)h(hence)h(must)g(be)g(last.\))0 2282 y FD(prepend)p FJ(\()p FK(cmd,)e(kind)r FJ(\))208 2382 y FN(Add)h(a)i(ne)n(w)f(action)g(at)g(the)g(be)o(ginning.)j(See)d FJ(append\(\))g FN(for)f(e)o(xplanations)f(of)i(the)h(ar)o(guments.)0 2529 y FD(open)p FJ(\()p FK(\002le)o(,)e(mode)p FJ(\))208 2628 y FN(Return)24 b(a)i(\002le-lik)o(e)f(object,)h(open)e(to)h FK(\002le)p FN(,)h(b)n(ut)f(read)g(from)f(or)h(written)g(to)g(by)g(the) g(pipeline.)39 b(Note)25 b(that)g(only)f(one)h(of)g FJ('r')p FN(,)208 2728 y FJ('w')20 b FN(may)f(be)i(gi)n(v)o(en.)0 2875 y FD(copy)p FJ(\()p FK(in\002le)o(,)e(out\002le)p FJ(\))208 2974 y FN(Cop)o(y)g FK(in\002le)h FN(to)h FK(out\002le)e FN(through)f(the)i(pipe.)0 3302 y FE(16.12)122 b Fx(posixfile)30 b FE(\227)j(File-lik)n(e)f(objects)i(with)g(loc)n(king)e(suppor)5 b(t)0 3535 y FL(Depr)o(ecated)23 b(since)h(r)o(elease)g(1.5.)35 b FN(The)23 b(locking)g(operation)f(that)i(this)g(module)e(pro)o(vides) h(is)h(done)f(better)h(and)f(more)g(portably)f(by)0 3634 y(the)e FJ(fcntl.lockf\(\))f FN(call.)0 3781 y(This)25 b(module)e(implements)g(some)h(additional)f(functionality)f(o)o(v)o(er) h(the)i(b)n(uilt-in)f(\002le)h(objects.)37 b(In)24 b(particular)m(,)f (it)j(implements)d(\002le)0 3881 y(locking,)i(control)f(o)o(v)o(er)g (the)i(\002le)g(\003ags,)g(and)f(an)h(easy)f(interf)o(ace)g(to)g (duplicate)f(the)i(\002le)g(object.)40 b(The)25 b(module)f(de\002nes)h (a)h(ne)n(w)f(\002le)0 3980 y(object,)i(the)e(posix\002le)h(object.)42 b(It)26 b(has)g(all)g(the)g(standard)f(\002le)i(object)e(methods)g(and) g(adds)h(the)g(methods)f(described)f(belo)n(w)-5 b(.)41 b(This)0 4080 y(module)19 b(only)g(w)o(orks)h(for)g(certain)f(\003a)n (v)n(ors)i(of)h(U)t FH(N)t(I)t(X)r FN(,)f(since)f(it)h(uses)g FJ(fcntl.fcntl\(\))d FN(for)h(\002le)i(locking.)0 4227 y(T)-7 b(o)19 b(instantiate)f(a)h(posix\002le)f(object,)h(use)f(the)h FJ(open\(\))f FN(function)f(in)i(the)f FJ(posixfile)g FN(module.)23 b(The)18 b(resulting)g(object)g(looks)g(and)0 4327 y(feels)i(roughly)f(the)h(same)g(as)h(a)g(standard)e(\002le)i (object.)0 4473 y(The)f FJ(posixfile)f FN(module)g(de\002nes)h(the)g (follo)n(wing)e(constants:)0 4620 y FD(SEEK_SET)208 4720 y FN(Of)n(fset)i(is)h(calculated)e(from)g(the)i(start)f(of)g(the)g (\002le.)0 4867 y FD(SEEK_CUR)208 4966 y FN(Of)n(fset)g(is)h (calculated)e(from)g(the)i(current)d(position)i(in)g(the)g(\002le.)0 5113 y FD(SEEK_END)208 5213 y FN(Of)n(fset)g(is)h(calculated)e(from)g (the)i(end)e(of)h(the)g(\002le.)0 5360 y(The)g FJ(posixfile)f FN(module)g(de\002nes)h(the)g(follo)n(wing)e(functions:)p 0 5549 3901 4 v 0 5649 a FI(16.12.)52 b FJ(posixfile)22 b FI(\227)h(File-lik)n(e)h(objects)f(with)h(loc)n(king)g(suppor)s(t) 1578 b(563)p eop end %%Page: 564 576 TeXDict begin 564 575 bop 0 83 a FD(open)p FJ(\()p FK(\002lename)p FC([)p FK(,)18 b(mode)p FC([)p FK(,)h(b)n(ufsize)12 b FC(])g(])p FJ(\))208 183 y FN(Create)20 b(a)i(ne)n(w)e(posix\002le)g (object)g(with)h(the)g(gi)n(v)o(en)e(\002lename)h(and)h(mode.)k(The)20 b FK(\002lename)p FN(,)g FK(mode)g FN(and)g FK(b)n(ufsize)h FN(ar)o(guments)e(are)208 282 y(interpreted)f(the)i(same)h(w)o(ay)f(as) h(by)e(the)i(b)n(uilt-in)e FJ(open\(\))h FN(function.)0 429 y FD(fileopen)p FJ(\()p FK(\002leobject)q FJ(\))208 529 y FN(Create)f(a)h(ne)n(w)f(posix\002le)f(object)h(with)g(the)h(gi)n (v)o(en)e(standard)g(\002le)h(object.)25 b(The)18 b(resulting)h(object) f(has)i(the)f(same)g(\002lename)g(and)208 628 y(mode)g(as)i(the)f (original)f(\002le)i(object.)0 775 y(The)f(posix\002le)g(object)f (de\002nes)h(the)g(follo)n(wing)f(additional)g(methods:)0 922 y FD(lock)p FJ(\()p FK(fmt,)h FC([)p FK(len)p FC([)p FK(,)f(start)q FC([)p FK(,)i(whence)12 b FC(])g(])g(])p FJ(\))208 1022 y FN(Lock)19 b(the)h(speci\002ed)f(section)h(of)g(the)g (\002le)g(that)g(the)g(\002le)h(object)e(is)i(referring)d(to.)25 b(The)19 b(format)g(is)i(e)o(xplained)d(belo)n(w)h(in)i(a)f(table.)208 1121 y(The)i FK(len)g FN(ar)o(gument)e(speci\002es)j(the)g(length)f(of) g(the)g(section)h(that)f(should)g(be)g(lock)o(ed.)31 b(The)22 b(def)o(ault)g(is)h FJ(0)p FN(.)33 b FK(start)25 b FN(speci\002es)e(the)208 1221 y(starting)e(of)n(fset)f(of)h(the)h (section,)f(where)g(the)g(def)o(ault)g(is)h FJ(0)p FN(.)29 b(The)21 b FK(whence)f FN(ar)o(gument)f(speci\002es)j(where)f(the)g(of) n(fset)g(is)h(relati)n(v)o(e)208 1321 y(to.)i(It)17 b(accepts)g(one)f (of)h(the)g(constants)g FJ(SEEK_SET)p FN(,)e FJ(SEEK_CUR)h FN(or)h FJ(SEEK_END)p FN(.)f(The)h(def)o(ault)f(is)i FJ(SEEK_SET)p FN(.)e(F)o(or)g(more)208 1420 y(information)h(about)j (the)g(ar)o(guments)e(refer)h(to)i(the)f FK(fcntl)p FN(\(2\))f(manual)g (page)h(on)f(your)g(system.)0 1567 y FD(flags)p FJ(\()p FC([)p FK(\003a)o(gs)12 b FC(])p FJ(\))208 1667 y FN(Set)31 b(the)g(speci\002ed)g(\003ags)g(for)g(the)g(\002le)h(that)f(the)g (\002le)g(object)g(is)h(referring)d(to.)57 b(The)31 b(ne)n(w)g(\003ags) g(are)g(ORed)h(with)f(the)g(old)208 1766 y(\003ags,)22 b(unless)f(speci\002ed)h(otherwise.)28 b(The)21 b(format)g(is)h(e)o (xplained)e(belo)n(w)h(in)h(a)g(table.)29 b(W)m(ithout)21 b(the)g FK(\003a)o(gs)h FN(ar)o(gument)d(a)j(string)208 1866 y(indicating)h(the)i(current)f(\003ags)i(is)g(returned)d(\(this)i (is)h(the)g(same)f(as)h(the)f(`)p FJ(?)p FN(')39 b(modi\002er\).)g(F)o (or)24 b(more)h(information)d(about)j(the)208 1966 y(\003ags)20 b(refer)g(to)g(the)g FK(fcntl)p FN(\(2\))f(manual)g(page)h(on)g(your)f (system.)0 2113 y FD(dup)p FJ(\(\))208 2212 y FN(Duplicate)i(the)g (\002le)i(object)e(and)g(the)h(underlying)d(\002le)j(pointer)f(and)g (\002le)h(descriptor)-5 b(.)29 b(The)21 b(resulting)g(object)h(beha)n (v)o(es)e(as)j(if)f(it)208 2312 y(were)e(ne)n(wly)f(opened.)0 2459 y FD(dup2)p FJ(\()p FK(fd)r FJ(\))208 2558 y FN(Duplicate)j(the)g (\002le)i(object)e(and)g(the)h(underlying)d(\002le)j(pointer)f(and)g (\002le)h(descriptor)-5 b(.)32 b(The)22 b(ne)n(w)g(object)h(will)g(ha)n (v)o(e)f(the)h(gi)n(v)o(en)208 2658 y(\002le)d(descriptor)-5 b(.)24 b(Otherwise)c(the)h(resulting)e(object)h(beha)n(v)o(es)f(as)i (if)f(it)h(were)f(ne)n(wly)g(opened.)0 2805 y FD(file)p FJ(\(\))208 2904 y FN(Return)j(the)h(standard)e(\002le)j(object)e(that) h(the)f(posix\002le)h(object)f(is)h(based)g(on.)35 b(This)24 b(is)g(sometimes)g(necessary)f(for)g(functions)208 3004 y(that)d(insist)h(on)f(a)g(standard)f(\002le)i(object.)0 3151 y(All)g(methods)e(raise)h FJ(IOError)g FN(when)f(the)i(request)e (f)o(ails.)0 3298 y(F)o(ormat)g(characters)h(for)f(the)h FJ(lock\(\))g FN(method)f(ha)n(v)o(e)g(the)i(follo)n(wing)d(meaning:) 1035 3524 y FL(F)n(ormat)p 1349 3554 4 100 v 98 w(Meaning)p 986 3557 1929 4 v 1116 3627 a FN(`)p FJ(u)p FN(')p 1349 3657 4 100 v 178 w(unlock)h(the)h(speci\002ed)g(re)o(gion)1116 3727 y(`)p FJ(r)p FN(')p 1349 3756 V 178 w(request)g(a)h(read)e(lock)h (for)f(the)i(speci\002ed)f(section)1116 3826 y(`)p FJ(w)p FN(')p 1349 3856 V 178 w(request)g(a)h(write)f(lock)g(for)f(the)h (speci\002ed)g(section)0 4051 y(In)g(addition)f(the)h(follo)n(wing)f (modi\002ers)g(can)h(be)g(added)f(to)h(the)h(format:)165 4278 y FL(Modi\002er)p 523 4307 V 100 w(Meaning)p 3485 4307 V 2648 w(Notes)p 116 4311 3669 4 v 267 4381 a FN(`)p FJ(|)p FN(')p 523 4410 4 100 v 201 w(w)o(ait)g(until)f(the)g(lock)g (has)g(been)g(granted)p 3485 4410 V 267 4480 a(`)p FJ(?)p FN(')p 523 4510 V 201 w(return)f(the)h(\002rst)h(lock)f(con\003icting)f (with)h(the)g(requested)f(lock,)h(or)g FJ(None)g FN(if)g(there)g(is)h (no)f(con\003ict.)p 3485 4510 V 149 w(\(1\))0 4704 y(Note:)0 4934 y FL(\(1\))40 b FN(The)22 b(lock)f(returned)f(is)j(in)f(the)f (format)g FJ(\()p FK(mode)p FJ(,)48 b FK(len)p FJ(,)h FK(start)q FJ(,)i FK(whence)p FJ(,)d FK(pid)r FJ(\))22 b FN(where)f FK(mode)g FN(is)i(a)f(character)f(representing)208 5034 y(the)f(type)f(of)h(lock)g(\(')l(r')f(or)h('w'\).)25 b(This)20 b(modi\002er)f(pre)n(v)o(ents)g(a)h(request)g(from)f(being)g (granted;)g(it)i(is)g(for)f(query)f(purposes)f(only)-5 b(.)0 5263 y(F)o(ormat)19 b(characters)h(for)f(the)h FJ(flags\(\))g FN(method)f(ha)n(v)o(e)g(the)h(follo)n(wing)f(meanings:) p 0 5549 3901 4 v 0 5649 a FI(564)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 565 577 TeXDict begin 565 576 bop 1034 70 a FL(F)n(ormat)p 1348 100 4 100 v 98 w(Meaning)p 984 103 1932 4 v 1114 173 a FN(`)p FJ(a)p FN(')p 1348 203 4 100 v 179 w(append)19 b(only)g(\003ag)1114 272 y(`)p FJ(c)p FN(')p 1348 302 V 179 w(close)i(on)e(e)o(x)o(ec)h(\003ag)1114 372 y(`)p FJ(n)p FN(')p 1348 402 V 179 w(no)g(delay)g(\003ag)g(\(also)g(called)g (non-blocking)d(\003ag\))1114 472 y(`)p FJ(s)p FN(')p 1348 501 V 179 w(synchronization)g(\003ag)0 697 y(In)j(addition)f(the)h (follo)n(wing)f(modi\002ers)g(can)h(be)g(added)f(to)h(the)h(format:)457 923 y FL(Modi\002er)p 814 953 V 99 w(Meaning)p 3194 953 V 2066 w(Notes)p 407 956 3087 4 v 559 1026 a FN(`)p FJ(!)p FN(')p 814 1056 4 100 v 200 w(turn)f(the)g(speci\002ed)g(\003ags)g('of) n(f)5 b(',)19 b(instead)h(of)f(the)i(def)o(ault)e('on')p 3194 1056 V 606 w(\(1\))559 1125 y(`)p FJ(=)p FN(')p 814 1155 V 200 w(replace)h(the)g(\003ags,)g(instead)g(of)g(the)g(def)o (ault)g('OR')g(operation)p 3194 1155 V 624 w(\(1\))559 1225 y(`)p FJ(?)p FN(')p 814 1255 V 200 w(return)f(a)i(string)f(in)g (which)g(the)g(characters)f(represent)g(the)h(\003ags)h(that)f(are)g (set.)p 3194 1255 V 151 w(\(2\))0 1449 y(Notes:)0 1679 y FL(\(1\))40 b FN(The)20 b(`)p FJ(!)p FN(')25 b(and)20 b(`)p FJ(=)p FN(')g(modi\002ers)f(are)h(mutually)f(e)o(xclusi)n(v)o(e.) 0 1845 y FL(\(2\))40 b FN(This)21 b(string)f(represents)f(the)h (\003ags)h(after)f(the)o(y)f(may)h(ha)n(v)o(e)f(been)h(altered)f(by)h (the)g(same)h(call.)0 2075 y(Examples:)236 2313 y FA(import)44 b(posixfile)236 2496 y(file)g(=)h(posixfile.open\('/tmp/test',)40 b('w'\))236 2587 y(file.lock\('w|'\))236 2678 y(...)236 2770 y(file.lock\('u'\))236 2861 y(file.close\(\))0 3371 y FE(16.13)122 b Fx(resource)31 b FE(\227)i(Resource)h(usage)h(inf)l (or)s(mation)0 3604 y FN(This)20 b(module)f(pro)o(vides)g(basic)h (mechanisms)f(for)h(measuring)e(and)i(controlling)e(system)j(resources) e(utilized)h(by)f(a)i(program.)0 3751 y(Symbolic)h(constants)g(are)g (used)h(to)g(specify)f(particular)f(system)i(resources)f(and)g(to)h (request)f(usage)g(information)f(about)g(either)i(the)0 3850 y(current)c(process)h(or)g(its)h(children.)0 3997 y(A)g(single)f(e)o(xception)e(is)j(de\002ned)e(for)h(errors:)0 4144 y FL(exception)f FD(error)208 4244 y FN(The)g(functions)g (described)g(belo)n(w)h(may)f(raise)i(this)g(error)e(if)h(the)g (underlying)e(system)i(call)h(f)o(ailures)f(une)o(xpectedly)-5 b(.)0 4529 y Fv(16.13.1)101 b(Resource)29 b(Limits)0 4732 y FN(Resources)24 b(usage)f(can)h(be)f(limited)h(using)f(the)h FJ(setrlimit\(\))f FN(function)f(described)g(belo)n(w)-5 b(.)35 b(Each)24 b(resource)e(is)j(controlled)d(by)0 4831 y(a)k(pair)f(of)g(limits:)37 b(a)26 b(soft)f(limit)h(and)f(a)h (hard)f(limit.)41 b(The)25 b(soft)h(limit)g(is)g(the)g(current)e (limit,)j(and)e(may)g(be)g(lo)n(wered)g(or)g(raised)g(by)g(a)0 4931 y(process)d(o)o(v)o(er)e(time.)31 b(The)21 b(soft)h(limit)h(can)f (ne)n(v)o(er)e(e)o(xceed)h(the)h(hard)f(limit.)31 b(The)22 b(hard)f(limit)h(can)g(be)g(lo)n(wered)f(to)h(an)o(y)f(v)n(alue)h (greater)0 5030 y(than)e(the)g(soft)g(limit,)h(b)n(ut)f(not)g(raised.)k (\(Only)c(processes)g(with)g(the)g(ef)n(fecti)n(v)o(e)f(UID)h(of)g(the) h(super)n(-user)d(can)i(raise)h(a)f(hard)g(limit.\))0 5177 y(The)f(speci\002c)h(resources)e(that)h(can)h(be)f(limited)g(are)h (system)f(dependent.)k(The)o(y)18 b(are)h(described)f(in)i(the)f FK(g)o(etrlimit)p FN(\(2\))g(man)g(page.)24 b(The)0 5277 y(resources)19 b(listed)h(belo)n(w)f(are)h(supported)e(when)h(the)h (underlying)d(operating)h(system)i(supports)e(them;)i(resources)f (which)g(cannot)g(be)0 5377 y(check)o(ed)g(or)h(controlled)e(by)i(the)g (operating)f(system)h(are)g(not)g(de\002ned)f(in)h(this)h(module)e(for) h(those)g(platforms.)p 0 5549 3901 4 v 0 5649 a FI(16.13.)52 b FJ(resource)22 b FI(\227)h(Resource)f(usage)i(inf)n(or)r(mation)1915 b(565)p eop end %%Page: 566 578 TeXDict begin 566 577 bop 0 83 a FD(getrlimit)p FJ(\()p FK(r)m(esour)m(ce)p FJ(\))208 183 y FN(Returns)27 b(a)h(tuple)f FJ(\()p FK(soft)q FJ(,)50 b FK(har)m(d)r FJ(\))27 b FN(with)h(the)g (current)e(soft)i(and)f(hard)g(limits)h(of)f FK(r)m(esour)m(ce)p FN(.)47 b(Raises)29 b FJ(ValueError)e FN(if)h(an)208 282 y(in)m(v)n(alid)19 b(resource)f(is)k(speci\002ed,)d(or)h FJ(error)g FN(if)g(the)h(underlying)c(system)k(call)f(f)o(ails)h(une)o (xpectedly)-5 b(.)0 429 y FD(setrlimit)p FJ(\()p FK(r)m(esour)m(ce)o(,) 18 b(limits)p FJ(\))208 529 y FN(Sets)j(ne)n(w)f(limits)g(of)g (consumption)e(of)i FK(r)m(esour)m(ce)p FN(.)25 b(The)19 b FK(limits)j FN(ar)o(gument)17 b(must)j(be)h(a)f(tuple)g FJ(\()p FK(soft)q FJ(,)50 b FK(har)m(d)r FJ(\))19 b FN(of)h(tw)o(o)g (inte)o(gers)208 628 y(describing)e(the)i(ne)n(w)g(limits.)26 b(A)21 b(v)n(alue)e(of)h FJ(-1)h FN(can)f(be)g(used)g(to)g(specify)f (the)i(maximum)d(possible)i(upper)f(limit.)208 761 y(Raises)29 b FJ(ValueError)f FN(if)g(an)h(in)m(v)n(alid)e(resource)g(is)j (speci\002ed,)g(if)e(the)h(ne)n(w)f(soft)h(limit)g(e)o(xceeds)e(the)i (hard)e(limit,)k(or)d(if)h(a)208 861 y(process)17 b(tries)h(to)g(raise) g(its)h(hard)e(limit)h(\(unless)f(the)h(process)f(has)h(an)g(ef)n (fecti)n(v)o(e)e(UID)i(of)f(super)n(-user\).)23 b(Can)18 b(also)g(raise)g FJ(error)208 960 y FN(if)i(the)g(underlying)e(system)i (call)h(f)o(ails.)0 1107 y(These)d(symbols)f(de\002ne)g(resources)g (whose)h(consumption)d(can)j(be)g(controlled)e(using)h(the)h FJ(setrlimit\(\))f FN(and)g FJ(getrlimit\(\))0 1207 y FN(functions)i(described)g(belo)n(w)-5 b(.)24 b(The)19 b(v)n(alues)h(of)g(these)h(symbols)e(are)h(e)o(xactly)f(the)i (constants)e(used)h(by)g(C)h(programs.)0 1354 y(The)27 b(U)t FH(N)t(I)t(X)g FN(man)e(page)f(for)g FK(g)o(etrlimit)p FN(\(2\))h(lists)h(the)f(a)n(v)n(ailable)f(resources.)39 b(Note)24 b(that)h(not)g(all)g(systems)h(use)f(the)g(same)g(symbol)f (or)0 1453 y(same)f(v)n(alue)f(to)h(denote)e(the)i(same)g(resource.)31 b(This)23 b(module)f(does)g(not)h(attempt)f(to)h(mask)f(platform)g(dif) n(ferences)f(\227)i(symbols)f(not)0 1553 y(de\002ned)d(for)h(a)g (platform)f(will)i(not)f(be)g(a)n(v)n(ailable)g(from)f(this)i(module)d (on)i(that)g(platform.)0 1700 y FD(RLIMIT_CORE)208 1800 y FN(The)f(maximum)e(size)j(\(in)g(bytes\))f(of)g(a)h(core)f(\002le)h (that)f(the)h(current)e(process)h(can)g(create.)24 b(This)c(may)f (result)g(in)h(the)f(creation)g(of)208 1899 y(a)h(partial)g(core)g (\002le)h(if)f(a)h(lar)o(ger)d(core)i(w)o(ould)g(be)g(required)e(to)i (contain)g(the)g(entire)g(process)f(image.)0 2046 y FD(RLIMIT_CPU)208 2146 y FN(The)33 b(maximum)f(amount)g(of)h(processor)g(time)g(\(in)h (seconds\))e(that)i(a)g(process)f(can)h(use.)65 b(If)34 b(this)g(limit)g(is)g(e)o(xceeded,)h(a)208 2245 y FJ(SIGXCPU)20 b FN(signal)h(is)h(sent)f(to)g(the)g(process.)27 b(\(See)21 b(the)g FJ(signal)f FN(module)g(documentation)e(for)i(information)f (about)h(ho)n(w)g(to)208 2345 y(catch)f(this)i(signal)f(and)g(do)g (something)e(useful,)i(e.g.)k(\003ush)d(open)e(\002les)i(to)f(disk.\))0 2492 y FD(RLIMIT_FSIZE)208 2591 y FN(The)k(maximum)e(size)j(of)g(a)f (\002le)i(which)d(the)i(process)f(may)g(create.)37 b(This)25 b(only)e(af)n(fects)h(the)h(stack)f(of)h(the)f(main)g(thread)g(in)g(a) 208 2691 y(multi-threaded)17 b(process.)0 2838 y FD(RLIMIT_DATA)208 2938 y FN(The)i(maximum)g(size)i(\(in)f(bytes\))f(of)h(the)h(process') -5 b(s)20 b(heap.)0 3084 y FD(RLIMIT_STACK)208 3184 y FN(The)f(maximum)g(size)i(\(in)f(bytes\))f(of)h(the)h(call)f(stack)h (for)e(the)h(current)f(process.)0 3331 y FD(RLIMIT_RSS)208 3431 y FN(The)g(maximum)g(resident)g(set)i(size)g(that)g(should)e(be)h (made)g(a)n(v)n(ailable)f(to)i(the)f(process.)0 3577 y FD(RLIMIT_NPROC)208 3677 y FN(The)f(maximum)g(number)f(of)i (processes)g(the)g(current)f(process)h(may)g(create.)0 3824 y FD(RLIMIT_NOFILE)208 3924 y FN(The)f(maximum)g(number)f(of)i (open)f(\002le)i(descriptors)e(for)h(the)g(current)f(process.)0 4070 y FD(RLIMIT_OFILE)208 4170 y FN(The)g(BSD)j(name)d(for)h FJ(RLIMIT_NOFILE)p FN(.)0 4317 y FD(RLIMIT_MEMLOCK)208 4417 y FN(The)f(maximum)g(address)h(space)g(which)f(may)h(be)g(lock)o (ed)g(in)g(memory)-5 b(.)0 4563 y FD(RLIMIT_VMEM)208 4663 y FN(The)19 b(lar)o(gest)h(area)g(of)g(mapped)f(memory)f(which)i (the)g(process)g(may)f(occup)o(y)-5 b(.)0 4810 y FD(RLIMIT_AS)208 4910 y FN(The)19 b(maximum)g(area)h(\(in)g(bytes\))g(of)f(address)h (space)g(which)g(may)g(be)g(tak)o(en)g(by)f(the)i(process.)0 5194 y Fv(16.13.2)101 b(Resource)29 b(Usage)0 5397 y FN(These)20 b(functions)f(are)h(used)g(to)g(retrie)n(v)o(e)f(resource)g (usage)h(information:)p 0 5549 3901 4 v 0 5649 a FI(566)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 567 579 TeXDict begin 567 578 bop 0 83 a FD(getrusage)p FJ(\()p FK(who)p FJ(\))208 183 y FN(This)15 b(function)f(returns)h(an)g(object) g(that)h(describes)f(the)g(resources)g(consumed)e(by)j(either)f(the)g (current)f(process)h(or)h(its)g(children,)208 282 y(as)g(speci\002ed)f (by)h(the)f FK(who)h FN(parameter)-5 b(.)23 b(The)15 b FK(who)h FN(parameter)e(should)h(be)g(speci\002ed)h(using)f(one)g(of) g(the)h FJ(RUSAGE_)3526 297 y(*)3591 282 y FN(constants)208 382 y(described)i(belo)n(w)-5 b(.)208 515 y(The)18 b(\002elds)h(of)g (the)g(return)e(v)n(alue)h(each)h(describe)f(ho)n(w)g(a)h(particular)f (system)h(resource)f(has)h(been)f(used,)g(e.g.)24 b(amount)18 b(of)g(time)208 614 y(spent)i(running)e(is)k(user)e(mode)g(or)g(number) f(of)h(times)h(the)g(process)f(w)o(as)h(sw)o(apped)f(out)g(of)g(main)g (memory)-5 b(.)24 b(Some)c(v)n(alues)h(are)208 714 y(dependent)d(on)h (the)i(clock)e(tick)h(internal,)g(e.g.)k(the)c(amount)f(of)h(memory)f (the)h(process)f(is)j(using.)208 847 y(F)o(or)d(backw)o(ard)g (compatibility)-5 b(,)18 b(the)i(return)f(v)n(alue)h(is)h(also)f (accessible)h(as)g(a)f(tuple)g(of)g(16)g(elements.)208 980 y(The)h(\002elds)h FJ(ru_utime)e FN(and)h FJ(ru_stime)g FN(of)g(the)h(return)e(v)n(alue)h(are)h(\003oating)f(point)f(v)n(alues) i(representing)d(the)j(amount)e(of)208 1079 y(time)k(spent)g(e)o(x)o (ecuting)e(in)j(user)f(mode)f(and)h(the)g(amount)f(of)h(time)g(spent)h (e)o(x)o(ecuting)d(in)i(system)h(mode,)f(respecti)n(v)o(ely)-5 b(.)35 b(The)208 1179 y(remaining)21 b(v)n(alues)i(are)g(inte)o(gers.) 33 b(Consult)23 b(the)g FK(g)o(etrusa)o(g)o(e)p FN(\(2\))f(man)g(page)h (for)f(detailed)h(information)e(about)h(these)h(v)n(alues.)208 1279 y(A)d(brief)g(summary)f(is)i(presented)e(here:)1104 1408 y FL(Index)p 1356 1438 4 100 v 100 w(Field)p 2003 1438 V 468 w(Resour)o(ce)p 1055 1441 1999 4 v 1258 1511 a FJ(0)p 1356 1541 4 100 v 99 w(ru_utime)p 2003 1541 V 248 w FN(time)h(in)g(user)g(mode)g(\(\003oat\))1258 1610 y FJ(1)p 1356 1640 V 99 w(ru_stime)p 2003 1640 V 248 w FN(time)g(in)g(system)h(mode)e(\(\003oat\))1258 1710 y FJ(2)p 1356 1740 V 99 w(ru_maxrss)p 2003 1740 V 198 w FN(maximum)f(resident)i(set)h(size)1258 1810 y FJ(3)p 1356 1839 V 99 w(ru_ixrss)p 2003 1839 V 248 w FN(shared)e(memory)g(size)1258 1909 y FJ(4)p 1356 1939 V 99 w(ru_idrss)p 2003 1939 V 248 w FN(unshared)f(memory)h(size)1258 2009 y FJ(5)p 1356 2039 V 99 w(ru_isrss)p 2003 2039 V 248 w FN(unshared)f(stack)i(size)1258 2108 y FJ(6)p 1356 2138 V 99 w(ru_minflt)p 2003 2138 V 198 w FN(page)f(f)o(aults)i(not)e (requiring)g(I/O)1258 2208 y FJ(7)p 1356 2238 V 99 w(ru_majflt)p 2003 2238 V 198 w FN(page)g(f)o(aults)i(requiring)d(I/O)1258 2308 y FJ(8)p 1356 2338 V 99 w(ru_nswap)p 2003 2338 V 248 w FN(number)g(of)i(sw)o(ap)g(outs)1258 2407 y FJ(9)p 1356 2437 V 99 w(ru_inblock)p 2003 2437 V 148 w FN(block)f(input)g (operations)1208 2507 y FJ(10)p 1356 2537 V 99 w(ru_oublock)p 2003 2537 V 148 w FN(block)g(output)g(operations)1208 2607 y FJ(11)p 1356 2636 V 99 w(ru_msgsnd)p 2003 2636 V 198 w FN(messages)h(sent)1208 2706 y FJ(12)p 1356 2736 V 99 w(ru_msgrcv)p 2003 2736 V 198 w FN(messages)g(recei)n(v)o(ed)1208 2806 y FJ(13)p 1356 2836 V 99 w(ru_nsignals)p 2003 2836 V 98 w FN(signals)g(recei)n(v)o(ed)1208 2905 y FJ(14)p 1356 2935 V 99 w(ru_nvcsw)p 2003 2935 V 248 w FN(v)n(oluntary)e(conte)o (xt)h(switches)1208 3005 y FJ(15)p 1356 3035 V 99 w(ru_nivcsw)p 2003 3035 V 198 w FN(in)m(v)n(oluntary)e(conte)o(xt)i(switches)208 3133 y(This)28 b(function)f(will)j(raise)f(a)g FJ(ValueError)e FN(if)i(an)f(in)m(v)n(alid)g FK(who)g FN(parameter)g(is)h(speci\002ed.) 50 b(It)29 b(may)f(also)h(raise)g FJ(error)208 3233 y FN(e)o(xception)18 b(in)i(unusual)f(circumstances.)208 3366 y(Changed)f(in)j(v)o(ersion)e(2.3:)g(Added)g(access)i(to)g(v)n (alues)e(as)i(attrib)n(utes)f(of)g(the)g(returned)f(object.)0 3513 y FD(getpagesize)p FJ(\(\))208 3612 y FN(Returns)26 b(the)g(number)f(of)h(bytes)h(in)f(a)h(system)g(page.)43 b(\(This)26 b(need)g(not)g(be)h(the)f(same)h(as)g(the)f(hardw)o(are)f (page)h(size.\))44 b(This)208 3712 y(function)21 b(is)i(useful)f(for)h (determining)d(the)j(number)e(of)h(bytes)h(of)f(memory)f(a)i(process)g (is)g(using.)32 b(The)23 b(third)f(element)g(of)h(the)208 3812 y(tuple)17 b(returned)f(by)h FJ(getrusage\(\))g FN(describes)g(memory)f(usage)h(in)h(pages;)h(multiplying)c(by)j(page)f (size)h(produces)e(number)208 3911 y(of)j(bytes.)0 4058 y(The)e(follo)n(wing)e FJ(RUSAGE_)835 4073 y(*)901 4058 y FN(symbols)h(are)h(passed)f(to)h(the)g FJ(getrusage\(\))f FN(function)f(to)i(specify)f(which)g(processes)h(information)0 4158 y(should)i(be)h(pro)o(vided)e(for)-5 b(.)0 4305 y FD(RUSAGE_SELF)208 4404 y FJ(RUSAGE_SELF)18 b FN(should)h(be)i(used)e (to)i(request)e(information)f(pertaining)h(only)g(to)h(the)g(process)g (itself.)0 4551 y FD(RUSAGE_CHILDREN)208 4651 y FN(P)o(ass)h(to)f FJ(getrusage\(\))f FN(to)h(request)g(resource)f(information)e(for)j (child)g(processes)g(of)f(the)i(calling)e(process.)0 4798 y FD(RUSAGE_BOTH)208 4897 y FN(P)o(ass)25 b(to)f FJ(getrusage\(\))f FN(to)h(request)g(resources)f(consumed)g(by)h(both)f (the)i(current)d(process)i(and)g(child)g(processes.)37 b(May)208 4997 y(not)19 b(be)i(a)n(v)n(ailable)e(on)h(all)h(systems.)p 0 5549 3901 4 v 0 5649 a FI(16.13.)52 b FJ(resource)22 b FI(\227)h(Resource)f(usage)i(inf)n(or)r(mation)1915 b(567)p eop end %%Page: 568 580 TeXDict begin 568 579 bop 0 88 a FE(16.14)122 b Fx(nis)32 b FE(\227)h(Interf)l(ace)j(to)e(Sun')-6 b(s)33 b(NIS)g(\(Y)-17 b(ello)n(w)34 b(P)-5 b(ages\))0 321 y FN(The)20 b FJ(nis)g FN(module)f(gi)n(v)o(es)h(a)g(thin)g(wrapper)f(around)f(the)i(NIS)h (library)-5 b(,)18 b(useful)i(for)g(central)f(administration)g(of)h(se) n(v)o(eral)f(hosts.)0 468 y(Because)h(NIS)h(e)o(xists)g(only)e(on)j(U)t FH(N)t(I)t(X)h FN(systems,)d(this)h(module)e(is)i(only)e(a)n(v)n (ailable)h(for)i(U)t FH(N)t(I)t(X)r FN(.)0 615 y(The)e FJ(nis)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f(functions:)0 762 y FD(match)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(mapname[,)g (domain=default)p 1384 762 25 4 v 26 w(domain])p FJ(\))208 861 y FN(Return)25 b(the)h(match)g(for)f FK(k)o(e)n(y)h FN(in)g(map)f FK(mapname)p FN(,)h(or)g(raise)g(an)g(error)f(\()p FJ(nis.error)p FN(\))f(if)i(there)f(is)i(none.)42 b(Both)26 b(should)f(be)208 961 y(strings,)19 b FK(k)o(e)n(y)i FN(is)g(8-bit)e(clean.)25 b(Return)20 b(v)n(alue)f(is)i(an)f(arbitrary) f(array)g(of)h(bytes)g(\(may)g(contain)f FJ(NULL)h FN(and)f(other)h(jo) o(ys\).)208 1092 y(Note)g(that)g FK(mapname)f FN(is)i(\002rst)g(check)o (ed)e(if)h(it)h(is)g(an)f(alias)h(to)f(another)f(name.)208 1223 y(Changed)30 b(in)i(v)o(ersion)e(2.5:)i(The)f FK(domain)f FN(ar)o(gument)g(allo)n(ws)i(to)g(o)o(v)o(erride)d(the)j(NIS)g(domain)e (used)i(for)f(the)h(lookup.)58 b(If)208 1323 y(unspeci\002ed,)18 b(lookup)h(is)i(in)f(the)g(def)o(ault)g(NIS)g(domain.)0 1470 y FD(cat)p FJ(\()p FK(mapname[,)e(domain=default)p 1140 1470 V 26 w(domain])p FJ(\))208 1569 y FN(Return)h(a)h(dictionary) e(mapping)h FK(k)o(e)n(y)g FN(to)h FK(value)g FN(such)f(that)h FJ(match\()p FK(k)o(e)n(y)p FJ(,)48 b FK(mapname)p FJ(\)==)p FK(value)p FN(.)22 b(Note)d(that)h(both)g(k)o(e)o(ys)f(and)208 1669 y(v)n(alues)g(of)h(the)g(dictionary)f(are)h(arbitrary)f(arrays)g (of)h(bytes.)208 1800 y(Note)g(that)g FK(mapname)f FN(is)i(\002rst)g (check)o(ed)e(if)h(it)h(is)g(an)f(alias)h(to)f(another)f(name.)208 1932 y(Changed)30 b(in)i(v)o(ersion)e(2.5:)i(The)f FK(domain)f FN(ar)o(gument)g(allo)n(ws)i(to)g(o)o(v)o(erride)d(the)j(NIS)g(domain)e (used)i(for)f(the)h(lookup.)58 b(If)208 2031 y(unspeci\002ed,)18 b(lookup)h(is)i(in)f(the)g(def)o(ault)g(NIS)g(domain.)0 2178 y FD(maps)p FJ(\()p FK([domain=default)p 826 2178 V 26 w(domain])p FJ(\))208 2278 y FN(Return)f(a)i(list)g(of)f(all)h(v)n (alid)f(maps.)208 2409 y(Changed)30 b(in)i(v)o(ersion)e(2.5:)i(The)f FK(domain)f FN(ar)o(gument)g(allo)n(ws)i(to)g(o)o(v)o(erride)d(the)j (NIS)g(domain)e(used)i(for)f(the)h(lookup.)58 b(If)208 2509 y(unspeci\002ed,)18 b(lookup)h(is)i(in)f(the)g(def)o(ault)g(NIS)g (domain.)0 2656 y FD(get_default_domain)p FJ(\(\))208 2755 y FN(Return)f(the)i(system)f(def)o(ault)f(NIS)i(domain.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 2902 y(The)h FJ(nis)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f(e)o(xception:)0 3049 y FL(exception)g FD(error)208 3149 y FN(An)h(error)f(raised)h (when)f(a)i(NIS)g(function)d(returns)h(an)h(error)g(code.)0 3475 y FE(16.15)122 b Fx(syslog)31 b FE(\227)36 b FC(U)6 b Fl(N)g(I)g(X)36 b FE(syslog)d(libr)o(ar)t(y)f(routines)0 3707 y FN(This)e(module)e(pro)o(vides)g(an)i(interf)o(ace)f(to)h(the)i (U)t FH(N)t(I)t(X)g FJ(syslog)d FN(library)g(routines.)53 b(Refer)30 b(to)f(the)j(U)t FH(N)t(I)t(X)h FN(manual)c(pages)g(for)g(a) 0 3807 y(detailed)20 b(description)e(of)i(the)g FJ(syslog)g FN(f)o(acility)-5 b(.)0 3954 y(The)20 b(module)f(de\002nes)h(the)g (follo)n(wing)e(functions:)0 4101 y FD(syslog)p FJ(\()p FC([)p FK(priority)-5 b(,)12 b FC(])19 b FK(messa)o(g)o(e)p FJ(\))208 4200 y FN(Send)h(the)h(string)g FK(messa)o(g)o(e)h FN(to)f(the)g(system)g(logger)-5 b(.)27 b(A)22 b(trailing)e(ne)n(wline) h(is)h(added)e(if)h(necessary)-5 b(.)27 b(Each)21 b(message)g(is)h (tagged)208 4300 y(with)27 b(a)g(priority)e(composed)g(of)i(a)g FK(facility)g FN(and)g(a)g FK(le)o(vel)p FN(.)45 b(The)27 b(optional)e FK(priority)i FN(ar)o(gument,)f(which)g(def)o(aults)h(to)g FJ(LOG_-)208 4400 y(INFO)p FN(,)c(determines)g(the)i(message)f (priority)-5 b(.)35 b(If)24 b(the)g(f)o(acility)g(is)h(not)f(encoded)f (in)h FK(priority)h FN(using)e(logical-or)g(\()p FJ(LOG_INFO)208 4499 y(|)49 b(LOG_USER)p FN(\),)19 b(the)h(v)n(alue)g(gi)n(v)o(en)e(in) j(the)f FJ(openlog\(\))f FN(call)i(is)g(used.)0 4655 y FD(openlog)p FJ(\()p FK(ident)q FC([)p FK(,)d(lo)o(gopt)q FC([)p FK(,)i(facility)12 b FC(])g(])p FJ(\))208 4755 y FN(Logging)25 b(options)h(other)g(than)h(the)g(def)o(aults)f(can)h (be)g(set)h(by)f(e)o(xplicitly)f(opening)f(the)i(log)g(\002le)g(with)h FJ(openlog\(\))e FN(prior)208 4855 y(to)e(calling)f FJ(syslog\(\))p FN(.)35 b(The)24 b(def)o(aults)f(are)h(\(usually\))e FK(ident)j FN(=)g FJ('syslog')p FN(,)e FK(lo)o(gopt)i FN(=)f FJ(0)p FN(,)h FK(facility)f FN(=)g FJ(LOG_USER)p FN(.)f(The)208 4954 y FK(ident)j FN(ar)o(gument)c(is)k(a)f(string)g (which)f(is)i(prepended)c(to)j(e)n(v)o(ery)f(message.)39 b(The)24 b(optional)g FK(lo)o(gopt)h FN(ar)o(gument)e(is)j(a)f(bit)g (\002eld)g(-)208 5054 y(see)e(belo)n(w)g(for)f(possible)h(v)n(alues)g (to)g(combine.)33 b(The)23 b(optional)f FK(facility)h FN(ar)o(gument)e(sets)j(the)f(def)o(ault)g(f)o(acility)g(for)f (messages)208 5154 y(which)d(do)h(not)g(ha)n(v)o(e)f(a)i(f)o(acility)f (e)o(xplicitly)f(encoded.)0 5300 y FD(closelog)p FJ(\(\))208 5400 y FN(Close)h(the)h(log)e(\002le.)p 0 5549 3901 4 v 0 5649 a FI(568)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 569 581 TeXDict begin 569 580 bop 0 83 a FD(setlogmask)p FJ(\()p FK(maskpri)p FJ(\))208 183 y FN(Set)23 b(the)f(priority)g(mask)g(to)h FK(maskpri)f FN(and)g(return)g(the)g(pre)n(vious)f(mask)i(v)n(alue.)31 b(Calls)24 b(to)e FJ(syslog\(\))g FN(with)h(a)g(priority)e(le)n(v)o(el) 208 282 y(not)f(set)h(in)g FK(maskpri)f FN(are)g(ignored.)k(The)c(def)o (ault)g(is)i(to)e(log)g(all)h(priorities.)k(The)20 b(function)f FJ(LOG_MASK\()p FK(pri)p FJ(\))g FN(calculates)i(the)208 382 y(mask)h(for)h(the)f(indi)n(vidual)g(priority)f FK(pri)p FN(.)33 b(The)23 b(function)e FJ(LOG_UPTO\()p FK(pri)p FJ(\))h FN(calculates)g(the)h(mask)g(for)f(all)i(priorities)e(up)g(to) 208 482 y(and)d(including)g FK(pri)p FN(.)0 628 y(The)h(module)f (de\002nes)h(the)g(follo)n(wing)e(constants:)0 842 y FL(Priority)h(le)o(v)o(els)h(\(high)h(to)f(lo)o(w\):)40 b FJ(LOG_EMERG)p FN(,)63 b FJ(LOG_ALERT)p FN(,)g FJ(LOG_CRIT)p FN(,)h FJ(LOG_ERR)p FN(,)f FJ(LOG_WARNING)p FN(,)g FJ(LOG_-)208 942 y(NOTICE)p FN(,)19 b FJ(LOG_INFO)p FN(,)g FJ(LOG_DEBUG)p FN(.)0 1101 y FL(F)n(acilities:)40 b FJ(LOG_KERN)p FN(,)14 b FJ(LOG_USER)p FN(,)g FJ(LOG_MAIL)p FN(,)h FJ(LOG_DAEMON)p FN(,)e FJ(LOG_AUTH)p FN(,)h FJ(LOG_LPR)p FN(,)h FJ(LOG_NEWS)p FN(,)f FJ(LOG_UUCP)p FN(,)208 1201 y FJ(LOG_CRON)19 b FN(and)g FJ(LOG_LOCAL0)g FN(to)i FJ(LOG_LOCAL7)p FN(.)0 1360 y FL(Log)f(options:)41 b FJ(LOG_PID)p FN(,)77 b FJ(LOG_CONS)p FN(,)g FJ(LOG_NDELAY)p FN(,)g FJ(LOG_NOWAIT)f FN(and)i FJ(LOG_PERROR)f FN(if)h(de\002ned)f(in)208 1460 y FJ(<syslog.h>)p FN(.)0 1851 y FE(16.16)122 b Fx(commands)31 b FE(\227)i(Utilities)f(f)l(or)i(r)r(unning)h(commands)0 2084 y FN(The)19 b FJ(commands)g FN(module)f(contains)g(wrapper)g (functions)g(for)h FJ(os.popen\(\))f FN(which)h(tak)o(e)h(a)g(system)f (command)f(as)i(a)g(string)f(and)0 2184 y(return)g(an)o(y)g(output)g (generated)g(by)h(the)g(command)e(and,)h(optionally)-5 b(,)18 b(the)i(e)o(xit)g(status.)0 2330 y(The)g FJ(subprocess)e FN(module)h(pro)o(vides)f(more)h(po)n(werful)f(f)o(acilities)j(for)e (spa)o(wning)g(ne)n(w)h(processes)f(and)h(retrie)n(ving)e(their)h (results.)0 2430 y(Using)h(the)g FJ(subprocess)f FN(module)g(is)i (preferable)d(to)j(using)e(the)i FJ(commands)e FN(module.)0 2577 y(The)h FJ(commands)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 2724 y FD(getstatusoutput)p FJ(\()p FK(cmd)r FJ(\))208 2823 y FN(Ex)o(ecute)k(the)h(string)g FK(cmd)j FN(in)e(a)g(shell)g(with)f FJ(os.popen\(\))f FN(and)h(return)g(a)h (2-tuple)e FJ(\()p FK(status)p FJ(,)49 b FK(output)q FJ(\))p FN(.)37 b FK(cmd)27 b FN(is)e(actually)208 2923 y(run)e(as)h FJ({)p FK(cmd)51 b FJ(;)f(}2>&1)p FN(,)24 b(so)g(that)g(the)g(returned)e(output)h(will)h(contain)f(output)g(or)g (error)g(messages.)36 b(A)24 b(trailing)f(ne)n(wline)208 3023 y(is)f(stripped)e(from)g(the)i(output.)27 b(The)21 b(e)o(xit)g(status)h(for)f(the)g(command)e(can)i(be)h(interpreted)d (according)h(to)h(the)g(rules)h(for)e(the)i(C)208 3122 y(function)c FJ(wait\(\))p FN(.)0 3269 y FD(getoutput)p FJ(\()p FK(cmd)r FJ(\))208 3369 y FN(Lik)o(e)24 b FJ (getstatusoutput\(\))p FN(,)f(e)o(xcept)h(the)g(e)o(xit)h(status)g(is)h (ignored)d(and)h(the)g(return)g(v)n(alue)g(is)h(a)g(string)g (containing)e(the)208 3468 y(command')-5 b(s)18 b(output.)0 3615 y FD(getstatus)p FJ(\()p FK(\002le)p FJ(\))208 3715 y FN(Return)j(the)h(output)f(of)g(`)p FJ(ls)50 b(-ld)f FK(\002le)p FN(')21 b(as)i(a)g(string.)30 b(This)22 b(function)e(uses)i (the)g FJ(getoutput\(\))f FN(function,)f(and)i(properly)208 3815 y(escapes)e(backslashes)g(and)f(dollar)h(signs)g(in)g(the)h(ar)o (gument.)0 3961 y(Example:)236 4200 y FA(>>>)45 b(import)e(commands)236 4291 y(>>>)i(commands.getstatusoutput\('ls)40 b(/bin/ls'\))236 4382 y(\(0,)45 b('/bin/ls'\))236 4474 y(>>>)g (commands.getstatusoutput\('cat)40 b(/bin/junk'\))236 4565 y(\(256,)k('cat:)g(/bin/junk:)f(No)i(such)f(file)g(or)h (directory'\))236 4656 y(>>>)g(commands.getstatusoutput\('/bin/junk')o (\))236 4748 y(\(256,)f('sh:)g(/bin/junk:)g(not)g(found'\))236 4839 y(>>>)h(commands.getoutput\('ls)c(/bin/ls'\))236 4930 y('/bin/ls')236 5022 y(>>>)k(commands.getstatus\('/bin/ls'\))236 5113 y('-rwxr-xr-x)88 b(1)45 b(root)358 b(13352)44 b(Oct)g(14)89 b(1994)44 b(/bin/ls')0 5400 y FL(See)21 b(Also:)p 0 5549 3901 4 v 0 5649 a FI(16.16.)52 b FJ(commands)22 b FI(\227)h(Utilities)i (f)n(or)d(r)q(unning)i(commands)1837 b(569)p eop end %%Page: 570 582 TeXDict begin 570 581 bop 0 83 a FN(Module)19 b FJ(subprocess)g FN(\(section)h(17.1\):)208 183 y(Module)f(for)g(spa)o(wning)g(and)h (managing)e(subprocesses.)p 0 5549 3901 4 v 0 5649 a FI(570)2453 b(Chapter)23 b(16.)52 b(Unix)23 b(Speci\002c)g(Ser)r(vices) p eop end %%Page: 571 583 TeXDict begin 571 582 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3176 427 y FG(SEVENTEEN)p 0 515 V 865 978 a FT(Inter)6 b(process)58 b(Comm)n(unication)f(and)2866 1227 y(Netw)n(or)s(king)0 1717 y FN(The)20 b(modules)f(described)g(in)h(this)h(chapter)e(pro)o (vide)f(mechanisms)h(for)h(dif)n(ferent)e(processes)i(to)h (communicate.)0 1864 y(Some)j(modules)f(only)g(w)o(ork)g(for)h(tw)o(o)g (processes)g(that)g(are)g(on)f(the)h(same)g(machine,)g(e.g.)36 b FJ(signal)23 b FN(and)h FJ(subprocess)p FN(.)35 b(Other)0 1963 y(modules)19 b(support)g(netw)o(orking)f(protocols)h(that)h(tw)o (o)h(or)e(more)h(processes)g(can)g(used)g(to)g(communicate)e(across)i (machines.)0 2110 y(The)g(list)h(of)f(modules)f(described)g(in)h(this)h (chapter)e(is:)50 2254 y FD(subprocess)98 b FN(Subprocess)18 b(management.)50 2353 y FD(socket)298 b FN(Lo)n(w-le)n(v)o(el)18 b(netw)o(orking)g(interf)o(ace.)50 2453 y FD(signal)298 b FN(Set)20 b(handlers)f(for)h(asynchronous)d(e)n(v)o(ents.)50 2552 y FD(popen2)298 b FN(Subprocesses)19 b(with)h(accessible)g (standard)f(I/O)i(streams.)50 2652 y FD(asyncore)198 b FN(A)20 b(base)h(class)g(for)e(de)n(v)o(eloping)f(asynchronous)f (sock)o(et)j(handling)e(services.)50 2752 y FD(asynchat)198 b FN(Support)18 b(for)i(asynchronous)d(command/response)g(protocols.)0 3056 y FE(17.1)121 b Fx(subprocess)31 b FE(\227)i(Subprocess)h (management)0 3289 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 3436 y(The)j FJ(subprocess)f FN(module)g(allo)n(ws)i(you)e(to)i(spa)o (wn)f(ne)n(w)g(processes,)g(connect)f(to)i(their)f(input/output/error)c (pipes,)23 b(and)e(obtain)0 3535 y(their)f(return)f(codes.)24 b(This)d(module)e(intends)g(to)i(replace)e(se)n(v)o(eral)h(other)m(,)e (older)i(modules)f(and)h(functions,)e(such)i(as:)236 3774 y FA(os.system)236 3865 y(os.spawn)596 3878 y(*)236 3956 y(os.popen)596 3969 y(*)236 4047 y(popen2.)551 4060 y(*)236 4139 y(commands.)641 4152 y(*)0 4425 y FN(Information)h(about)h (ho)n(w)i(the)f FJ(subprocess)f FN(module)h(can)g(be)h(used)f(to)h (replace)f(these)h(modules)e(and)h(functions)f(can)i(be)f(found)0 4525 y(in)d(the)h(follo)n(wing)d(sections.)0 4810 y Fv(17.1.1)101 b(Using)28 b(the)g(subprocess)h(Module)0 5013 y FN(This)20 b(module)f(de\002nes)h(one)g(class)h(called)f FJ(Popen)p FN(:)0 5160 y FL(class)h FD(Popen)p FJ(\()p FK(ar)m(gs,)f(b)n (ufsize=0,)h(e)n(xecutable=None)o(,)f(stdin=None)o(,)g(stdout=None)o(,) g(stderr=None)o(,)i(pr)m(ee)n(xec)p 3310 5160 25 4 v 29 w(fn=None)o(,)f(close)p 3848 5160 V 29 w(-)487 5259 y(fds=F)-6 b(alse)o(,)15 b(shell=F)-6 b(alse)o(,)17 b(cwd=None)o(,)g (en)m(v=None)o(,)e(univer)o(sal)p 2380 5259 V 29 w(ne)o(wlines=F)-6 b(alse)o(,)16 b(startupinfo=None)o(,)g(cr)m(eation-)487 5359 y(\003a)o(gs=0)p FJ(\))p 0 5549 3901 4 v 3762 5649 a FI(571)p eop end %%Page: 572 584 TeXDict begin 572 583 bop 208 83 a FN(Ar)o(guments)18 b(are:)208 216 y FK(ar)m(gs)j FN(should)f(be)h(a)g(string,)g(or)f(a)i (sequence)d(of)i(program)e(ar)o(guments.)25 b(The)c(program)e(to)i(e)o (x)o(ecute)e(is)j(normally)e(the)h(\002rst)g(item)208 315 y(in)f(the)g(ar)o(gs)g(sequence)f(or)h(string,)f(b)n(ut)h(can)g(be) h(e)o(xplicitly)e(set)i(by)e(using)h(the)g(e)o(x)o(ecutable)f(ar)o (gument.)208 448 y(On)27 b(U)t FH(N)t(I)t(X)r FN(,)h(with)e FK(shell=F)-6 b(alse)25 b FN(\(def)o(ault\):)35 b(In)25 b(this)h(case,)h(the)f(Popen)f(class)h(uses)g FJ(os.execvp\(\))e FN(to)i(e)o(x)o(ecute)e(the)i(child)208 548 y(program.)e FK(ar)m(gs)c FN(should)g(normally)f(be)h(a)h(sequence.)k(A)d(string)e (will)h(be)g(treated)f(as)h(a)g(sequence)f(with)g(the)h(string)f(as)i (the)e(only)208 648 y(item)g(\(the)g(program)e(to)i(e)o(x)o(ecute\).) 208 780 y(On)30 b(U)t FH(N)t(I)t(X)r FN(,)i(with)c FK(shell=T)-5 b(rue)p FN(:)43 b(If)29 b(ar)o(gs)f(is)h(a)g(string,)h(it)g (speci\002es)f(the)f(command)f(string)h(to)h(e)o(x)o(ecute)e(through)g (the)h(shell.)208 880 y(If)e FK(ar)m(gs)h FN(is)g(a)g(sequence,)g(the)g (\002rst)g(item)g(speci\002es)g(the)f(command)f(string,)j(and)e(an)o(y) g(additional)f(items)i(will)g(be)g(treated)f(as)208 980 y(additional)18 b(shell)j(ar)o(guments.)208 1112 y(On)j(W)m(indo)n(ws:) 33 b(the)24 b FJ(Popen)g FN(class)i(uses)f(CreateProcess\(\))e(to)i(e)o (x)o(ecute)e(the)h(child)g(program,)f(which)h(operates)g(on)g(strings.) 208 1212 y(If)30 b FK(ar)m(gs)g FN(is)h(a)f(sequence,)i(it)e(will)h(be) f(con)m(v)o(erted)e(to)i(a)h(string)e(using)h(the)g FJ(list2cmdline)f FN(method.)53 b(Please)31 b(note)e(that)208 1312 y(not)22 b(all)h(MS)h(W)m(indo)n(ws)e(applications)f(interpret)h(the)g(command)f (line)i(the)g(same)g(w)o(ay:)30 b FJ(list2cmdline)21 b FN(is)j(designed)d(for)208 1411 y(applications)e(using)g(the)h(same)h (rules)f(as)h(the)f(MS)h(C)g(runtime.)208 1544 y FK(b)n(ufsize)p FN(,)g(if)h(gi)n(v)o(en,)e(has)h(the)g(same)h(meaning)d(as)j(the)g (corresponding)17 b(ar)o(gument)i(to)i(the)h(b)n(uilt-in)e(open\(\))g (function:)25 b FJ(0)d FN(means)208 1644 y(unb)n(uf)n(fered,)d FJ(1)k FN(means)f(line)h(b)n(uf)n(fered,)e(an)o(y)h(other)f(positi)n(v) o(e)h(v)n(alue)g(means)g(use)h(a)g(b)n(uf)n(fer)e(of)h (\(approximately\))d(that)k(size.)32 b(A)208 1743 y(ne)o(gati)n(v)o(e) 25 b FK(b)n(ufsize)j FN(means)g(to)g(use)f(the)h(system)g(def)o(ault,)h (which)e(usually)g(means)g(fully)g(b)n(uf)n(fered.)46 b(The)27 b(def)o(ault)g(v)n(alue)g(for)208 1843 y FK(b)n(ufsize)20 b FN(is)h FJ(0)g FN(\(unb)n(uf)n(fered\).)208 1976 y(The)28 b FK(e)n(xecutable)h FN(ar)o(gument)d(speci\002es)k(the)f(program)e(to) j(e)o(x)o(ecute.)50 b(It)30 b(is)g(v)o(ery)e(seldom)h(needed:)42 b(Usually)-5 b(,)30 b(the)g(program)208 2076 y(to)c(e)o(x)o(ecute)g(is) h(de\002ned)f(by)g(the)h FK(ar)m(gs)g FN(ar)o(gument.)42 b(If)26 b FJ(shell=True)p FN(,)h(the)g FK(e)n(xecutable)e FN(ar)o(gument)g(speci\002es)i(which)f(shell)208 2175 y(to)f(use.)40 b(On)27 b(U)t FH(N)t(I)t(X)r FN(,)g(the)e(def)o(ault)g (shell)g(is)h(`)p FO(/bin/sh)p FN('.)38 b(On)25 b(W)m(indo)n(ws,)h(the) f(def)o(ault)f(shell)i(is)g(speci\002ed)f(by)f(the)h(COMSPEC)208 2275 y(en)m(vironment)17 b(v)n(ariable.)208 2408 y FK(stdin)p FN(,)25 b FK(stdout)g FN(and)f FK(stderr)j FN(specify)d(the)g(e)o(x)o (ecuted)f(programs')f(standard)h(input,)h(standard)g(output)f(and)g (standard)h(error)f(\002le)208 2507 y(handles,)30 b(respecti)n(v)o(ely) -5 b(.)49 b(V)-9 b(alid)29 b(v)n(alues)g(are)g FJ(PIPE)p FN(,)g(an)g(e)o(xisting)f(\002le)i(descriptor)e(\(a)h(positi)n(v)o(e)f (inte)o(ger\),)i(an)f(e)o(xisting)f(\002le)208 2607 y(object,)c(and)g FJ(None)p FN(.)37 b FJ(PIPE)24 b FN(indicates)g(that)h(a)f(ne)n(w)g (pipe)g(to)h(the)f(child)g(should)f(be)h(created.)37 b(W)m(ith)25 b FJ(None)p FN(,)f(no)g(redirection)208 2707 y(will)19 b(occur;)f(the)g(child')-5 b(s)18 b(\002le)h(handles)f (will)h(be)f(inherited)f(from)g(the)h(parent.)24 b(Additionally)-5 b(,)16 b FK(stderr)21 b FN(can)d(be)h FJ(STDOUT)p FN(,)e(which)208 2806 y(indicates)i(that)i(the)f(stderr)g(data)g(from)f(the)h (applications)f(should)g(be)h(captured)f(into)h(the)g(same)h(\002le)f (handle)g(as)g(for)g(stdout.)208 2939 y(If)27 b FK(pr)m(ee)n(xec)p 550 2939 25 4 v 29 w(fn)h FN(is)h(set)f(to)g(a)g(callable)f(object,)i (this)f(object)f(will)i(be)e(called)h(in)f(the)h(child)f(process)g (just)i(before)d(the)h(child)h(is)208 3039 y(e)o(x)o(ecuted.)23 b(\()r(U)t FH(N)t(I)t(X)f FN(only\))208 3171 y(If)27 b FK(close)p 467 3171 V 29 w(fds)h FN(is)g(true,)g(all)g(\002le)g (descriptors)e(e)o(xcept)g FJ(0)p FN(,)j FJ(1)f FN(and)e FJ(2)i FN(will)g(be)f(closed)g(before)f(the)h(child)g(process)g(is)h(e) o(x)o(ecuted.)208 3271 y(\()r(U)t FH(N)t(I)t(X)22 b FN(only\))208 3404 y(If)e FK(shell)g FN(is)h FJ(True)p FN(,)f(the)g(speci\002ed)g (command)e(will)j(be)g(e)o(x)o(ecuted)d(through)g(the)i(shell.)208 3537 y(If)25 b FK(cwd)k FN(is)d(not)g FJ(None)p FN(,)g(the)g(child')-5 b(s)26 b(current)e(directory)h(will)h(be)g(changed)e(to)i FK(cwd)i FN(before)c(it)j(is)g(e)o(x)o(ecuted.)39 b(Note)26 b(that)g(this)208 3636 y(directory)d(is)i(not)f(considered)f(when)h (searching)g(the)h(e)o(x)o(ecutable,)e(so)i(you)f(can')o(t)g(specify)g (the)g(program')-5 b(s)23 b(path)i(relati)n(v)o(e)e(to)208 3736 y FK(cwd)r FN(.)208 3869 y(If)d FK(en)m(v)f FN(is)i(not)f FJ(None)p FN(,)g(it)h(de\002nes)f(the)g(en)m(vironment)d(v)n(ariables)j (for)f(the)h(ne)n(w)g(process.)208 4002 y(If)32 b FK(univer)o(sal)p 610 4002 V 29 w(ne)o(wlines)h FN(is)g FJ(True)p FN(,)j(the)c(\002le)i (objects)e(stdout)g(and)g(stderr)h(are)f(opened)f(as)j(te)o(xt)e (\002les,)37 b(b)n(ut)32 b(lines)h(may)g(be)208 4101 y(terminated)24 b(by)h(an)o(y)g(of)g FJ('\\n')p FN(,)i(the)h(U)t FH(N)t(I)t(X)g FN(end-of-line)c(con)m(v)o(ention,)f FJ('\\r')p FN(,)k(the)f(Macintosh)e(con)m(v)o(ention)f(or)i FJ('\\r\\n')p FN(,)208 4201 y(the)20 b(W)m(indo)n(ws)g(con)m(v)o(ention.)i(All)f(of)f (these)h(e)o(xternal)e(representations)f(are)j(seen)f(as)h FJ('\\n')g FN(by)e(the)i(Python)e(program.)k FL(Note:)208 4301 y FN(This)e(feature)g(is)i(only)d(a)n(v)n(ailable)i(if)g(Python)e (is)j(b)n(uilt)e(with)h(uni)n(v)o(ersal)e(ne)n(wline)h(support)g(\(the) g(def)o(ault\).)28 b(Also,)22 b(the)g(ne)n(wlines)208 4400 y(attrib)n(ute)d(of)h(the)g(\002le)h(objects)f FJ(stdout)p FN(,)g FJ(stdin)f FN(and)h FJ(stderr)g FN(are)g(not)g(updated)e(by)i (the)g(communicate\(\))e(method.)208 4533 y(The)h FK(startupinfo)g FN(and)h FK(cr)m(eation\003a)o(gs)p FN(,)e(if)i(gi)n(v)o(en,)e(will)j (be)f(passed)g(to)g(the)g(underlying)e(CreateProcess\(\))h(function.)k (The)o(y)c(can)208 4633 y(specify)g(things)h(such)g(as)h(appearance)d (of)i(the)g(main)g(windo)n(w)f(and)g(priority)g(for)h(the)g(ne)n(w)g (process.)25 b(\(W)m(indo)n(ws)19 b(only\))0 4901 y FI(Con)n(v)n (enience)24 b(Functions)0 5104 y FN(This)c(module)f(also)i(de\002nes)f (tw)o(o)g(shortcut)f(functions:)0 5251 y FD(call)p FJ(\()p FK(*popenar)m(gs,)e(**kwar)m(gs)p FJ(\))208 5350 y FN(Run)j(command)e (with)i(ar)o(guments.)j(W)-7 b(ait)22 b(for)d(command)f(to)j(complete,) e(then)g(return)g(the)i FJ(returncode)d FN(attrib)n(ute.)p 0 5549 3901 4 v 0 5649 a FI(572)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 573 585 TeXDict begin 573 584 bop 208 83 a FN(The)19 b(ar)o(guments)g(are)h (the)g(same)g(as)h(for)f(the)g(Popen)f(constructor)-5 b(.)24 b(Example:)623 307 y FA(retcode)44 b(=)g(call\(["ls",)f("-l"]\)) 0 511 y FD(check_call)p FJ(\()p FK(*popenar)m(gs,)15 b(**kwar)m(gs)p FJ(\))208 611 y FN(Run)25 b(command)f(with)i(ar)o (guments.)39 b(W)-7 b(ait)27 b(for)e(command)e(to)j(complete.)40 b(If)26 b(the)g(e)o(xit)f(code)g(w)o(as)i(zero)e(then)g(return,)g (other)n(-)208 710 y(wise)f(raise)g FJ(CalledProcessError.)33 b FN(The)23 b FJ(CalledProcessError)e FN(object)i(will)h(ha)n(v)o(e)g (the)f(return)g(code)g(in)h(the)208 810 y FJ(returncode)18 b FN(attrib)n(ute.)208 943 y(The)h(ar)o(guments)g(are)h(the)g(same)g (as)h(for)f(the)g(Popen)f(constructor)-5 b(.)24 b(Example:)623 1167 y FA(check_call\(["ls",)42 b("-l"]\))208 1356 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 1624 y FI(Exceptions)0 1827 y FN(Exceptions)26 b(raised)h(in)h(the)f(child)g(process,)i (before)d(the)h(ne)n(w)h(program)d(has)i(started)h(to)f(e)o(x)o(ecute,) h(will)g(be)g(re-raised)e(in)i(the)f(par)n(-)0 1927 y(ent.)43 b(Additionally)-5 b(,)26 b(the)g(e)o(xception)f(object)g(will)j(ha)n(v) o(e)d(one)h(e)o(xtra)g(attrib)n(ute)g(called)g FJ(child_traceback)p FN(,)f(which)h(is)h(a)g(string)0 2027 y(containing)18 b(traceback)h(information)f(from)h(the)h(childs)g(point)g(of)g(vie)n(w) -5 b(.)0 2174 y(The)18 b(most)g(common)e(e)o(xception)g(raised)i(is)h FJ(OSError)p FN(.)24 b(This)18 b(occurs,)g(for)f(e)o(xample,)g(when)h (trying)f(to)h(e)o(x)o(ecute)f(a)h(non-e)o(xistent)e(\002le.)0 2273 y(Applications)j(should)g(prepare)g(for)g FJ(OSError)h FN(e)o(xceptions.)0 2420 y(A)h FJ(ValueError)e FN(will)i(be)f(raised)g (if)g FJ(Popen)g FN(is)h(called)f(with)g(in)m(v)n(alid)f(ar)o(guments.) 0 2567 y(check)p 200 2567 25 4 v 28 w(call\(\))h(will)h(raise)g FJ(CalledProcessError)p FN(,)c(if)j(the)h(called)f(process)f(returns)h (a)g(non-zero)e(return)h(code.)0 2835 y FI(Secur)q(ity)0 3038 y FN(Unlik)o(e)i(some)f(other)g(popen)g(functions,)f(this)i (implementation)e(will)j(ne)n(v)o(er)d(call)i(/bin/sh)g(implicitly)-5 b(.)26 b(This)21 b(means)f(that)h(all)h(charac-)0 3138 y(ters,)e(including)f(shell)h(metacharacters,)f(can)h(safely)g(be)g (passed)g(to)g(child)g(processes.)0 3423 y Fv(17.1.2)101 b(P)-5 b(open)29 b(Objects)0 3626 y FN(Instances)20 b(of)g(the)g FJ(Popen)g FN(class)h(ha)n(v)o(e)e(the)i(follo)n(wing)d(methods:)0 3772 y FD(poll)p FJ(\(\))208 3872 y FN(Check)h(if)i(child)f(process)f (has)i(terminated.)i(Returns)d(returncode)e(attrib)n(ute.)0 4019 y FD(wait)p FJ(\(\))208 4119 y FN(W)-7 b(ait)21 b(for)f(child)f(process)h(to)g(terminate.)25 b(Returns)20 b(returncode)d(attrib)n(ute.)0 4265 y FD(communicate)p FJ(\()p FK(input=None)p FJ(\))208 4365 y FN(Interact)h(with)i(process:) 25 b(Send)19 b(data)g(to)h(stdin.)25 b(Read)20 b(data)f(from)g(stdout)g (and)g(stderr)m(,)g(until)h(end-of-\002le)d(is)k(reached.)i(W)-7 b(ait)21 b(for)208 4465 y(process)e(to)h(terminate.)k(The)c(optional)e FK(input)j FN(ar)o(gument)c(should)i(be)h(a)h(string)e(to)h(be)g(sent)g (to)g(the)g(child)g(process,)f(or)h FJ(None)p FN(,)f(if)208 4564 y(no)g(data)h(should)g(be)g(sent)g(to)h(the)f(child.)208 4697 y(communicate\(\))d(returns)i(a)i(tuple)f(\(stdout,)f(stderr\).) 208 4830 y FL(Note:)24 b FN(The)c(data)g(read)f(is)j(b)n(uf)n(fered)c (in)i(memory)-5 b(,)18 b(so)j(do)e(not)h(use)h(this)f(method)f(if)i (the)f(data)g(size)h(is)g(lar)o(ge)e(or)h(unlimited.)0 4977 y(The)g(follo)n(wing)e(attrib)n(utes)j(are)f(also)g(a)n(v)n (ailable:)0 5124 y FD(stdin)208 5223 y FN(If)f(the)g FK(stdin)g FN(ar)o(gument)e(is)j FJ(PIPE)p FN(,)f(this)g(attrib)n(ute)g (is)h(a)g(\002le)g(object)e(that)i(pro)o(vides)d(input)h(to)i(the)f (child)g(process.)24 b(Otherwise,)19 b(it)208 5323 y(is)i FJ(None)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(17.1.)52 b FJ(subprocess)21 b FI(\227)j(Subprocess)e(management)1954 b(573)p eop end %%Page: 574 586 TeXDict begin 574 585 bop 0 83 a FD(stdout)208 183 y FN(If)20 b(the)h FK(stdout)h FN(ar)o(gument)c(is)k FJ(PIPE)p FN(,)f(this)g(attrib)n(ute)f(is)i(a)f(\002le)h(object)e(that)h(pro)o (vides)e(output)h(from)f(the)i(child)g(process.)26 b(Other)n(-)208 282 y(wise,)20 b(it)h(is)g FJ(None)p FN(.)0 429 y FD(stderr)208 529 y FN(If)27 b(the)h FK(stderr)i FN(ar)o(gument)25 b(is)k FJ(PIPE)p FN(,)e(this)h(attrib)n(ute)f(is)i(\002le)f(object)f (that)h(pro)o(vides)e(error)g(output)h(from)f(the)i(child)f(process.) 208 628 y(Otherwise,)19 b(it)i(is)g FJ(None)p FN(.)0 775 y FD(pid)208 875 y FN(The)e(process)h(ID)g(of)g(the)h(child)e (process.)0 1022 y FD(returncode)208 1121 y FN(The)28 b(child)g(return)f(code.)48 b(A)29 b FJ(None)f FN(v)n(alue)g(indicates) g(that)h(the)f(process)g(hasn')o(t)f(terminated)g(yet.)50 b(A)29 b(ne)o(gati)n(v)o(e)d(v)n(alue)h(-N)208 1221 y(indicates)19 b(that)i(the)f(child)g(w)o(as)h(terminated)e(by)g(signal)h(N)h(\()r(U)t FH(N)t(I)t(X)i FN(only\).)0 1504 y Fv(17.1.3)101 b(Replacing)29 b(Older)f(Functions)h(with)f(the)g(subprocess)h(Module)0 1707 y FN(In)20 b(this)h(section,)e(\224a)i(==\277)f(b\224)g(means)g (that)g(b)h(can)f(be)g(used)g(as)h(a)f(replacement)f(for)g(a.)0 1854 y FL(Note:)33 b FN(All)25 b(functions)e(in)h(this)h(section)g(f)o (ail)f(\(more)g(or)g(less\))h(silently)f(if)h(the)g(e)o(x)o(ecuted)d (program)g(cannot)i(be)g(found;)h(this)g(module)0 1954 y(raises)c(an)f FJ(OSError)f FN(e)o(xception.)0 2101 y(In)h(the)g(follo)n(wing)f(e)o(xamples,)g(we)h(assume)g(that)h(the)f (subprocess)f(module)g(is)i(imported)d(with)j(\224from)e(subprocess)g (import)g(*\224.)0 2368 y FI(Replacing)24 b(/bin/sh)g(shell)g(bac)n (kquote)0 2662 y FA(output=`mycmd)43 b(myarg`)0 2753 y(==>)0 2845 y(output)h(=)g(Popen\(["mycmd",)f("myarg"],)g (stdout=PIPE\).communicate\(\)[0])0 3254 y FI(Replacing)24 b(shell)g(pipe)g(line)0 3549 y FA(output=`dmesg)43 b(|)h(grep)g(hda`)0 3640 y(==>)0 3731 y(p1)g(=)h(Popen\(["dmesg"],)d(stdout=PIPE\))0 3823 y(p2)i(=)h(Popen\(["grep",)e("hda"],)g(stdin=p1.stdout,)f (stdout=PIPE\))0 3914 y(output)i(=)g(p2.communicate\(\)[0])0 4324 y FI(Replacing)24 b(os)o(.system\(\))0 4619 y FA(sts)44 b(=)h(os.system\("mycmd")d(+)j(")f(myarg"\))0 4710 y(==>)0 4801 y(p)h(=)f(Popen\("mycmd")f(+)i(")f(myarg",)g(shell=True\))0 4893 y(sts)g(=)h(os.waitpid\(p.pid,)d(0\))0 5178 y FN(Notes:)125 5400 y FM(\017)f FN(Calling)20 b(the)g(program)e(through)g(the)i(shell) h(is)g(usually)f(not)f(required.)p 0 5549 3901 4 v 0 5649 a FI(574)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 575 587 TeXDict begin 575 586 bop 125 83 a FM(\017)41 b FN(It')-5 b(s)20 b(easier)h(to)f(look)f(at)i(the)f FJ(returncode)f FN(attrib)n(ute)h(than)g(the)g(e)o(xit)g(status.)0 313 y(A)h(more)e(realistic)i(e)o(xample)d(w)o(ould)i(look)f(lik)o(e)i (this:)236 551 y FA(try:)416 642 y(retcode)43 b(=)i(call\("mycmd")e(+)h (")h(myarg",)f(shell=True\))416 734 y(if)g(retcode)g(<)g(0:)595 825 y(print)g(>>sys.stderr,)f("Child)g(was)i(terminated)e(by)h (signal",)g(-retcode)416 916 y(else:)595 1008 y(print)g(>>sys.stderr,)f ("Child)g(returned",)g(retcode)236 1099 y(except)h(OSError,)g(e:)416 1190 y(print)g(>>sys.stderr,)e("Execution)h(failed:",)h(e)0 1602 y FI(Replacing)24 b(os)o(.spa)n(wn*)0 1805 y FN(P)p 51 1805 25 4 v 30 w(NO)m(W)-10 b(AIT)21 b(e)o(xample:)236 2043 y FA(pid)45 b(=)f(os.spawnlp\(os.P_NOWAIT,)d("/bin/mycmd",)i ("mycmd",)g("myarg"\))236 2134 y(==>)236 2225 y(pid)i(=)f (Popen\(["/bin/mycmd",)e("myarg"]\).pid)0 2512 y FN(P)p 51 2512 V 30 w(W)-10 b(AIT)21 b(e)o(xample:)236 2750 y FA(retcode)44 b(=)h(os.spawnlp\(os.P_WAIT,)c("/bin/mycmd",)h ("mycmd",)i("myarg"\))236 2841 y(==>)236 2933 y(retcode)g(=)h (call\(["/bin/mycmd",)c("myarg"]\))0 3219 y FN(V)-9 b(ector)19 b(e)o(xample:)236 3457 y FA(os.spawnvp\(os.P_NOWAIT,)41 b(path,)j(args\))236 3549 y(==>)236 3640 y(Popen\([path])f(+)i (args[1:]\))0 3927 y FN(En)m(vironment)17 b(e)o(xample:)236 4165 y FA(os.spawnlpe\(os.P_NOWAIT,)41 b("/bin/mycmd",)i("mycmd",)g ("myarg",)h(env\))236 4256 y(==>)236 4347 y(Popen\(["/bin/mycmd",)e ("myarg"],)h(env={"PATH":)g("/usr/bin"}\))0 4759 y FI(Replacing)24 b(os)o(.popen*)0 5053 y FA(pipe)44 b(=)h(os.popen\(cmd,)d(mode='r',)i (bufsize\))0 5144 y(==>)0 5236 y(pipe)g(=)h(Popen\(cmd,)e(shell=True,)g (bufsize=bufsize,)f(stdout=PIPE\).stdout)p 0 5549 3901 4 v 0 5649 a FI(17.1.)52 b FJ(subprocess)21 b FI(\227)j(Subprocess)e (management)1954 b(575)p eop end %%Page: 576 588 TeXDict begin 576 587 bop 236 174 a FA(pipe)44 b(=)h(os.popen\(cmd,)e (mode='w',)g(bufsize\))236 266 y(==>)236 357 y(pipe)h(=)h(Popen\(cmd,)e (shell=True,)g(bufsize=bufsize,)f(stdin=PIPE\).stdin)236 678 y(\(child_stdin,)h(child_stdout\))g(=)h(os.popen2\(cmd,)f(mode,)h (bufsize\))236 770 y(==>)236 861 y(p)h(=)g(Popen\(cmd,)e(shell=True,)g (bufsize=bufsize,)685 952 y(stdin=PIPE,)g(stdout=PIPE,)f (close_fds=True\))236 1044 y(\(child_stdin,)h(child_stdout\))g(=)h (\(p.stdin,)f(p.stdout\))236 1365 y(\(child_stdin,)281 1456 y(child_stdout,)281 1547 y(child_stderr\))g(=)h(os.popen3\(cmd,)f (mode,)h(bufsize\))236 1639 y(==>)236 1730 y(p)h(=)g(Popen\(cmd,)e (shell=True,)g(bufsize=bufsize,)685 1821 y(stdin=PIPE,)g(stdout=PIPE,)f (stderr=PIPE,)h(close_fds=True\))236 1913 y(\(child_stdin,)281 2004 y(child_stdout,)281 2095 y(child_stderr\))g(=)h(\(p.stdin,)g (p.stdout,)f(p.stderr\))236 2417 y(\(child_stdin,)g (child_stdout_and_stderr\))e(=)j(os.popen4\(cmd,)f(mode,)h(bufsize\)) 236 2508 y(==>)236 2599 y(p)h(=)g(Popen\(cmd,)e(shell=True,)g (bufsize=bufsize,)685 2691 y(stdin=PIPE,)g(stdout=PIPE,)f (stderr=STDOUT,)h(close_fds=True\))236 2782 y(\(child_stdin,)g (child_stdout_and_stderr\))e(=)j(\(p.stdin,)g(p.stdout\))0 3193 y FI(Replacing)24 b(popen2.*)0 3396 y FL(Note:)h FN(If)20 b(the)h(cmd)f(ar)o(gument)e(to)j(popen2)d(functions)h(is)j(a)f (string,)f(the)g(command)f(is)i(e)o(x)o(ecuted)e(through)f(/bin/sh.)26 b(If)20 b(it)i(is)f(a)g(list,)h(the)0 3496 y(command)c(is)j(directly)f (e)o(x)o(ecuted.)236 3734 y FA(\(child_stdout,)43 b(child_stdin\))g(=)h (popen2.popen2\("somestring",)c(bufsize,)k(mode\))236 3825 y(==>)236 3917 y(p)h(=)g(Popen\(["somestring"],)c(shell=True,)i (bufsize=bufsize,)685 4008 y(stdin=PIPE,)g(stdout=PIPE,)f (close_fds=True\))236 4099 y(\(child_stdout,)h(child_stdin\))g(=)h (\(p.stdout,)f(p.stdin\))236 4420 y(\(child_stdout,)g(child_stdin\))g (=)h(popen2.popen2\(["mycmd",)d("myarg"],)i(bufsize,)h(mode\))236 4512 y(==>)236 4603 y(p)h(=)g(Popen\(["mycmd",)d("myarg"],)h (bufsize=bufsize,)685 4694 y(stdin=PIPE,)g(stdout=PIPE,)f (close_fds=True\))236 4786 y(\(child_stdout,)h(child_stdin\))g(=)h (\(p.stdout,)f(p.stdin\))0 5072 y FN(The)20 b(popen2.Popen3)c(and)j (popen2.Popen4)d(basically)k(w)o(orks)g(as)h(subprocess.Popen,)c(e)o (xcept)i(that:)125 5302 y FM(\017)41 b FN(subprocess.Popen)17 b(raises)k(an)f(e)o(xception)e(if)j(the)f(e)o(x)o(ecution)e(f)o(ails)p 0 5549 3901 4 v 0 5649 a FI(576)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 577 589 TeXDict begin 577 588 bop 125 83 a FM(\017)41 b FN(the)20 b FK(captur)m(estderr)h FN(ar)o(gument)d(is)j(replaced)e(with)i(the)f FK(stderr)j FN(ar)o(gument.)125 246 y FM(\017)41 b FN(stdin=PIPE)19 b(and)h(stdout=PIPE)f(must)h(be)h(speci\002ed.)125 409 y FM(\017)41 b FN(popen2)18 b(closes)i(all)h(\002le)g(descriptors)e(by) h(def)o(ault,)f(b)n(ut)h(you)g(ha)n(v)o(e)f(to)i(specify)e(close)p 2654 409 25 4 v 30 w(fds=T)m(rue)f(with)j(subprocess.Popen.)0 809 y FE(17.2)121 b Fx(socket)32 b FE(\227)h(Lo)n(w-le)l(v)m(el)h(netw) o(or)r(king)h(interf)l(ace)0 1042 y FN(This)29 b(module)f(pro)o(vides)g (access)h(to)h(the)f(BSD)h FK(soc)n(k)o(et)g FN(interf)o(ace.)51 b(It)29 b(is)h(a)n(v)n(ailable)f(on)g(all)g(modern)h(U)t FH(N)t(I)t(X)i FN(systems,)f(W)m(indo)n(ws,)0 1142 y(MacOS,)c(BeOS,)g (OS/2,)i(and)d(probably)f(additional)g(platforms.)44 b FL(Note:)38 b FN(Some)26 b(beha)n(vior)g(may)g(be)h(platform)e (dependent,)h(since)0 1241 y(calls)21 b(are)f(made)g(to)g(the)g (operating)f(system)h(sock)o(et)g(APIs.)0 1388 y(F)o(or)27 b(an)h(introduction)d(to)i(sock)o(et)h(programming)c(\(in)j(C\),)h(see) g(the)g(follo)n(wing)e(papers:)39 b FK(An)28 b(Intr)l(oductory)e (4.3BSD)g(Interpr)l(ocess)0 1488 y(Communication)31 b(T)-5 b(utorial)p FN(,)36 b(by)d(Stuart)g(Sechrest)g(and)f FK(An)h(Advanced)e(4.3BSD)h(Interpr)l(ocess)h(Communication)e(T)-5 b(utorial)p FN(,)36 b(by)0 1588 y(Samuel)26 b(J.)i(Lef)n(\003er)e(et)h (al,)i(both)d(in)h(the)h(U)t FH(N)t(I)t(X)i FK(Pr)l(o)o(gr)o(ammer')m (s)c(Manual,)h(Supplementary)d(Documents)i(1)h FN(\(sections)f(PS1:7)h (and)0 1687 y(PS1:8\).)e(The)20 b(platform-speci\002c)e(reference)h (material)h(for)g(the)g(v)n(arious)g(sock)o(et-related)f(system)h (calls)h(are)g(also)f(a)h(v)n(aluable)e(source)0 1787 y(of)f(information)d(on)i(the)h(details)g(of)g(sock)o(et)f(semantics.) 24 b(F)o(or)c(U)t FH(N)t(I)t(X)r FN(,)f(refer)e(to)h(the)g(manual)e (pages;)j(for)e(W)m(indo)n(ws,)g(see)i(the)e(W)m(inSock)0 1886 y(\(or)f(W)m(insock)f(2\))h(speci\002cation.)23 b(F)o(or)16 b(IPv6-ready)e(APIs,)j(readers)f(may)f(w)o(ant)i(to)f (refer)g(to)g(RFC)i(2553)d(titled)h FK(Basic)g(Soc)n(k)o(et)g (Interface)0 1986 y(Extensions)j(for)i(IPv6)p FN(.)0 2133 y(The)30 b(Python)f(interf)o(ace)h(is)h(a)g(straightforw)o(ard)d (transliteration)h(of)h(the)i(U)t FH(N)t(I)t(X)i FN(system)c(call)h (and)f(library)f(interf)o(ace)h(for)f(sock)o(ets)0 2233 y(to)i(Python')-5 b(s)31 b(object-oriented)d(style:)48 b(the)31 b FJ(socket\(\))f FN(function)g(returns)g(a)h FK(soc)n(k)o(et)h(object)f FN(whose)g(methods)f(implement)g(the)0 2332 y(v)n(arious)20 b(sock)o(et)i(system)f(calls.)30 b(P)o(arameter)20 b(types)h(are)h(some)n(what)e(higher)n(-le)n(v)o(el)f (than)i(in)h(the)f(C)i(interf)o(ace:)j(as)d(with)e FJ(read\(\))g FN(and)0 2432 y FJ(write\(\))c FN(operations)f(on)h(Python)g(\002les,)i (b)n(uf)n(fer)d(allocation)h(on)g(recei)n(v)o(e)f(operations)g(is)j (automatic,)e(and)g(b)n(uf)n(fer)f(length)h(is)i(implicit)0 2531 y(on)h(send)g(operations.)0 2678 y(Sock)o(et)i(addresses)g(are)g (represented)e(as)j(follo)n(ws:)28 b(A)23 b(single)f(string)f(is)i (used)f(for)g(the)g FJ(AF_UNIX)f FN(address)h(f)o(amily)-5 b(.)29 b(A)23 b(pair)e FJ(\()p FK(host)q FJ(,)0 2778 y FK(port)q FJ(\))31 b FN(is)i(used)d(for)h(the)g FJ(AF_INET)g FN(address)f(f)o(amily)-5 b(,)33 b(where)e FK(host)h FN(is)h(a)e(string)g(representing)e(either)i(a)h(hostname)d(in)j (Internet)0 2878 y(domain)20 b(notation)h(lik)o(e)g FJ('daring.cwi.nl') f FN(or)h(an)h(IPv4)f(address)g(lik)o(e)h FJ('100.50.200.5')p FN(,)d(and)j FK(port)h FN(is)f(an)g(inte)o(gral)e(port)0 2977 y(number)-5 b(.)54 b(F)o(or)30 b FJ(AF_INET6)f FN(address)h(f)o (amily)-5 b(,)32 b(a)e(four)n(-tuple)f FJ(\()p FK(host)q FJ(,)49 b FK(port)q FJ(,)g FK(\003owinfo)p FJ(,)g FK(scopeid)r FJ(\))29 b FN(is)i(used,)i(where)c FK(\003owinfo)0 3077 y FN(and)20 b FK(scopeid)i FN(represents)e FJ(sin6_flowinfo)f FN(and)h FJ(sin6_scope_id)f FN(member)h(in)h FJ(struct)48 b(sockaddr_in6)20 b FN(in)g(C.)i(F)o(or)0 3176 y FJ(socket)31 b FN(module)f(methods,)j FK(\003owinfo)e FN(and)g FK(scopeid)i FN(can)e(be)g(omitted)g(just)h(for)f(backw)o(ard)f(compatibility)-5 b(.)57 b(Note,)34 b(ho)n(we)n(v)o(er)m(,)0 3276 y(omission)21 b(of)f FK(scopeid)j FN(can)e(cause)g(problems)e(in)j(manipulating)d (scoped)h(IPv6)g(addresses.)28 b(Other)20 b(address)h(f)o(amilies)g (are)g(currently)0 3376 y(not)d(supported.)k(The)17 b(address)h(format) e(required)h(by)g(a)h(particular)f(sock)o(et)h(object)f(is)i (automatically)d(selected)i(based)g(on)f(the)h(address)0 3475 y(f)o(amily)i(speci\002ed)g(when)f(the)h(sock)o(et)g(object)g(w)o (as)h(created.)0 3622 y(F)o(or)f(IPv4)g(addresses,)g(tw)o(o)h(special)g (forms)f(are)g(accepted)g(instead)g(of)h(a)g(host)f(address:)26 b(the)21 b(empty)e(string)i(represents)e FJ(INADDR_-)0 3722 y(ANY)p FN(,)29 b(and)g(the)g(string)g FJ('<broadcast>')f FN(represents)g FJ(INADDR_BROADCAST)p FN(.)f(The)i(beha)n(vior)e(is)k (not)e(a)n(v)n(ailable)f(for)h(IPv6)0 3821 y(for)c(backw)o(ard)f (compatibility)-5 b(,)24 b(therefore,)h(you)f(may)h(w)o(ant)h(to)f(a)n (v)n(oid)g(these)h(if)g(you)e(intend)h(to)g(support)f(IPv6)h(with)h (your)e(Python)0 3921 y(programs.)0 4068 y(If)19 b(you)g(use)g(a)h (hostname)e(in)h(the)h FK(host)g FN(portion)e(of)h(IPv4/v6)f(sock)o(et) h(address,)g(the)g(program)e(may)i(sho)n(w)g(a)h(nondeterministic)d (beha)n(v-)0 4168 y(ior)m(,)i(as)i(Python)f(uses)g(the)h(\002rst)g (address)e(returned)g(from)g(the)h(DNS)h(resolution.)j(The)c(sock)o(et) g(address)g(will)h(be)f(resolv)o(ed)f(dif)n(ferently)0 4267 y(into)30 b(an)h(actual)f(IPv4/v6)f(address,)j(depending)c(on)i (the)h(results)g(from)e(DNS)i(resolution)f(and/or)f(the)h(host)h (con\002guration.)53 b(F)o(or)0 4367 y(deterministic)19 b(beha)n(vior)g(use)h(a)h(numeric)e(address)g(in)i FK(host)g FN(portion.)0 4514 y(Ne)n(w)f(in)h(v)o(ersion)e(2.5:)g(AF)p 783 4514 V 30 w(NETLINK)h(sock)o(ets)g(are)g(represented)f(as)h(pairs)h FK(pid)r FJ(,)49 b FK(gr)l(oups)p FN(.)0 4661 y(All)24 b(errors)f(raise)h(e)o(xceptions.)34 b(The)23 b(normal)f(e)o(xceptions) g(for)h(in)m(v)n(alid)g(ar)o(gument)e(types)j(and)f(out-of-memory)c (conditions)j(can)i(be)0 4760 y(raised;)c(errors)f(related)h(to)g(sock) o(et)g(or)g(address)g(semantics)g(raise)h(the)f(error)f FJ(socket.error)p FN(.)0 4907 y(Non-blocking)d(mode)j(is)h(supported)d (through)g FJ(setblocking\(\))p FN(.)23 b(A)d(generalization)d(of)i (this)h(based)f(on)g(timeouts)g(is)i(supported)0 5007 y(through)d FJ(settimeout\(\))p FN(.)0 5154 y(The)i(module)f FJ(socket)g FN(e)o(xports)g(the)h(follo)n(wing)f(constants)h(and)f (functions:)0 5300 y FL(exception)g FD(error)208 5400 y FN(This)k(e)o(xception)f(is)j(raised)e(for)g(sock)o(et-related)f (errors.)34 b(The)24 b(accompan)o(ying)c(v)n(alue)j(is)h(either)f(a)h (string)g(telling)f(what)h(went)p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v)n(el)g(netw)o (or)q(king)h(interf)n(ace)1989 b(577)p eop end %%Page: 578 590 TeXDict begin 578 589 bop 208 83 a FN(wrong)18 b(or)i(a)h(pair)f FJ(\()p FK(errno)p FJ(,)49 b FK(string)p FJ(\))20 b FN(representing)e (an)i(error)f(returned)g(by)g(a)i(system)f(call,)h(similar)f(to)h(the)f (v)n(alue)f(accompa-)208 183 y(n)o(ying)e FJ(os.error)p FN(.)23 b(See)d(the)e(module)g FJ(errno)p FN(,)g(which)h(contains)f (names)g(for)g(the)h(error)f(codes)g(de\002ned)g(by)g(the)h(underlying) 208 282 y(operating)f(system.)0 429 y FL(exception)h FD(herror)208 529 y FN(This)26 b(e)o(xception)e(is)j(raised)e(for)h (address-related)e(errors,)i(i.e.)42 b(for)25 b(functions)g(that)h(use) g FK(h)p 2869 529 25 4 v 30 w(errno)g FN(in)g(the)g(C)g(API,)g (including)208 628 y FJ(gethostbyname_ex\(\))17 b FN(and)j FJ(gethostbyaddr\(\))p FN(.)208 761 y(The)26 b(accompan)o(ying)d(v)n (alue)k(is)h(a)f(pair)f FJ(\()p FK(h)p 1480 761 V 30 w(errno)p FJ(,)49 b FK(string)p FJ(\))27 b FN(representing)e(an)h (error)g(returned)f(by)i(a)g(library)f(call.)45 b FK(string)208 861 y FN(represents)19 b(the)h(description)f(of)h FK(h)p 1214 861 V 29 w(errno)p FN(,)g(as)h(returned)d(by)i(the)g FJ(hstrerror\(\))f FN(C)i(function.)0 1008 y FL(exception)e FD(gaierror)208 1107 y FN(This)h(e)o(xception)d(is)k(raised)f(for)f (address-related)f(errors,)h(for)g FJ(getaddrinfo\(\))f FN(and)h FJ(getnameinfo\(\))p FN(.)k(The)d(accom-)208 1207 y(pan)o(ying)i(v)n(alue)i(is)i(a)f(pair)g FJ(\()p FK(err)l(or)r FJ(,)50 b FK(string)p FJ(\))25 b FN(representing)d(an)j (error)f(returned)f(by)h(a)h(library)f(call.)39 b FK(string)26 b FN(represents)e(the)208 1307 y(description)19 b(of)i FK(err)l(or)r FN(,)h(as)g(returned)e(by)g(the)i FJ(gai_strerror\(\))d FN(C)j(function.)k(The)21 b FK(err)l(or)j FN(v)n(alue)c(will)i(match)f (one)g(of)g(the)208 1406 y FJ(EAI_)408 1421 y(*)477 1406 y FN(constants)f(de\002ned)f(in)i(this)f(module.)0 1553 y FL(exception)f FD(timeout)208 1653 y FN(This)24 b(e)o(xception)e(is)j (raised)e(when)h(a)g(timeout)f(occurs)g(on)h(a)g(sock)o(et)g(which)f (has)h(had)g(timeouts)f(enabled)g(via)h(a)g(prior)f(call)h(to)208 1752 y FJ(settimeout\(\))p FN(.)33 b(The)23 b(accompan)o(ying)d(v)n (alue)j(is)h(a)g(string)f(whose)h(v)n(alue)e(is)j(currently)d(al)o(w)o (ays)i(\223timed)f(out\224.)70 b(Ne)n(w)23 b(in)208 1852 y(v)o(ersion)18 b(2.3.)0 1999 y FD(AF_UNIX)0 2098 y(AF_INET)0 2198 y(AF_INET6)208 2298 y FN(These)j(constants)g(represent)f(the)h (address)g(\(and)g(protocol\))e(f)o(amilies,)j(used)f(for)g(the)g (\002rst)h(ar)o(gument)d(to)j FJ(socket\(\))p FN(.)27 b(If)22 b(the)208 2397 y FJ(AF_UNIX)d FN(constant)g(is)j(not)d (de\002ned)h(then)f(this)i(protocol)e(is)i(unsupported.)0 2544 y FD(SOCK_STREAM)0 2644 y(SOCK_DGRAM)0 2743 y(SOCK_RAW)0 2843 y(SOCK_RDM)0 2943 y(SOCK_SEQPACKET)208 3042 y FN(These)16 b(constants)h(represent)f(the)h(sock)o(et)g(types,)g(used)g(for)f(the)h (second)f(ar)o(gument)f(to)i FJ(socket\(\))p FN(.)23 b(\(Only)16 b FJ(SOCK_STREAM)208 3142 y FN(and)j FJ(SOCK_DGRAM)g FN(appear)g(to)h(be)h(generally)d(useful.\))0 3289 y FD(SO_)150 3302 y(*)0 3388 y(SOMAXCONN)0 3488 y(MSG_)200 3501 y(*)0 3588 y(SOL_)200 3601 y(*)0 3687 y(IPPROTO_)400 3700 y(*)0 3787 y(IPPORT_)350 3800 y(*)0 3887 y(INADDR_)350 3900 y(*)0 3986 y(IP_)150 3999 y(*)0 4086 y(IPV6_)250 4099 y(*)0 4185 y(EAI_)200 4198 y(*)0 4285 y(AI_)150 4298 y(*)0 4385 y(NI_)150 4398 y(*)0 4484 y(TCP_)200 4497 y(*)208 4584 y FN(Man)o(y)29 b(constants)h(of)g(these)g(forms,)i (documented)c(in)i(the)j(U)t FH(N)t(I)t(X)g FN(documentation)27 b(on)j(sock)o(ets)h(and/or)e(the)h(IP)h(protocol,)208 4684 y(are)g(also)h(de\002ned)e(in)i(the)g(sock)o(et)f(module.)58 b(The)o(y)30 b(are)i(generally)e(used)h(in)h(ar)o(guments)d(to)j(the)f FJ(setsockopt\(\))f FN(and)208 4783 y FJ(getsockopt\(\))23 b FN(methods)g(of)i(sock)o(et)f(objects.)39 b(In)24 b(most)h(cases,)h (only)e(those)h(symbols)f(that)h(are)f(de\002ned)g(in)h(the)i(U)t FH(N)t(I)t(X)208 4883 y FN(header)19 b(\002les)i(are)f(de\002ned;)f (for)h(a)g(fe)n(w)g(symbols,)g(def)o(ault)f(v)n(alues)h(are)g(pro)o (vided.)0 5030 y FD(has_ipv6)208 5129 y FN(This)j(constant)g(contains)f (a)i(boolean)e(v)n(alue)h(which)f(indicates)i(if)f(IPv6)g(is)h (supported)e(on)h(this)g(platform.)69 b(Ne)n(w)23 b(in)h(v)o(ersion)208 5229 y(2.3.)0 5376 y FD(getaddrinfo)p FJ(\()p FK(host,)18 b(port)q FC([)p FK(,)i(family)p FC([)p FK(,)g(soc)n(ktype)p FC([)p FK(,)f(pr)l(oto)p FC([)p FK(,)h(\003a)o(gs)12 b FC(])g(])g(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(578)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 579 591 TeXDict begin 579 590 bop 208 83 a FN(Resolv)o(es)28 b(the)g FK(host)q FN(/)p FK(port)i FN(ar)o(gument,)e(into)g(a)g (sequence)f(of)h(5-tuples)g(that)g(contain)f(all)i(the)f(necessary)g (ar)o(gument)e(for)i(the)208 183 y(sock)o(ets)f(manipulation.)43 b FK(host)29 b FN(is)f(a)f(domain)f(name,)i(a)f(string)g (representation)e(of)i(IPv4/v6)f(address)g(or)h FJ(None)p FN(.)46 b FK(port)28 b FN(is)g(a)208 282 y(string)19 b(service)h(name)g(\(lik)o(e)g FJ('http')p FN(\),)f(a)i(numeric)d(port) i(number)e(or)i FJ(None)p FN(.)208 415 y(The)k(rest)i(of)e(the)h(ar)o (guments)e(are)i(optional)f(and)g(must)h(be)g(numeric)f(if)h (speci\002ed.)39 b(F)o(or)25 b FK(host)h FN(and)e FK(port)q FN(,)j(by)d(passing)h(either)208 515 y(an)f(empty)g(string)g(or)g FJ(None)p FN(,)i(you)d(can)i(pass)g FJ(NULL)f FN(to)h(the)f(C)i(API.)f (The)f FJ(getaddrinfo\(\))f FN(function)f(returns)i(a)h(list)h(of)208 614 y(5-tuples)19 b(with)h(the)g(follo)n(wing)f(structure:)208 747 y FJ(\()p FK(family)p FJ(,)49 b FK(soc)n(ktype)p FJ(,)f FK(pr)l(oto)p FJ(,)h FK(canonname)p FJ(,)e FK(soc)n(kaddr)r FJ(\))208 880 y FK(family)p FN(,)24 b FK(soc)n(ktype)p FN(,)f FK(pr)l(oto)g FN(are)h(all)g(inte)o(ger)e(and)h(are)g(meant)g (to)g(be)h(passed)f(to)h(the)f FJ(socket\(\))f FN(function.)33 b FK(canonname)21 b FN(is)j(a)208 980 y(string)18 b(representing)f(the) i(canonical)f(name)h(of)f(the)h FK(host)q FN(.)25 b(It)20 b(can)f(be)g(a)g(numeric)f(IPv4/v6)f(address)i(when)f FJ(AI_CANONNAME)208 1079 y FN(is)27 b(speci\002ed)f(for)g(a)h(numeric)e FK(host)q FN(.)44 b FK(soc)n(kaddr)28 b FN(is)f(a)g(tuple)f(describing) f(a)i(sock)o(et)g(address,)g(as)g(described)e(abo)o(v)o(e.)43 b(See)27 b(the)208 1179 y(source)19 b(for)h(the)g FJ(httplib)f FN(and)h(other)f(library)g(modules)g(for)h(a)h(typical)e(usage)h(of)g (the)g(function.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 1326 y FD(getfqdn)p FJ(\()p FC([)p FK(name)12 b FC(])p FJ(\))208 1425 y FN(Return)21 b(a)i(fully)f(quali\002ed)f(domain)g (name)h(for)g FK(name)p FN(.)30 b(If)22 b FK(name)g FN(is)h(omitted)f (or)g(empty)-5 b(,)21 b(it)i(is)h(interpreted)c(as)j(the)g(local)f (host.)208 1525 y(T)-7 b(o)25 b(\002nd)g(the)h(fully)f(quali\002ed)f (name,)i(the)g(hostname)e(returned)g(by)h FJ(gethostbyaddr\(\))e FN(is)k(check)o(ed,)e(then)g(aliases)h(for)208 1625 y(the)19 b(host,)f(if)i(a)n(v)n(ailable.)k(The)18 b(\002rst)i(name)e(which)h (includes)f(a)h(period)f(is)i(selected.)25 b(In)18 b(case)i(no)e(fully) g(quali\002ed)h(domain)e(name)208 1724 y(is)k(a)n(v)n(ailable,)e(the)h (hostname)f(as)i(returned)e(by)g FJ(gethostname\(\))g FN(is)i(returned.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.0.)0 1871 y FD(gethostbyname)p FJ(\()p FK(hostname)p FJ(\))208 1971 y FN(T)m(ranslate)48 b(a)i(host)f(name)f(to)i(IPv4)e(address)h (format.)110 b(The)49 b(IPv4)g(address)f(is)i(returned)e(as)i(a)f (string,)56 b(such)49 b(as)208 2070 y FJ('100.50.200.5')p FN(.)125 b(If)54 b(the)g(host)h(name)e(is)j(an)e(IPv4)g(address)g (itself)h(it)g(is)g(returned)e(unchanged.)124 b(See)208 2170 y FJ(gethostbyname_ex\(\))21 b FN(for)j(a)g(more)g(complete)f (interf)o(ace.)36 b FJ(gethostbyname\(\))22 b FN(does)i(not)g(support)f (IPv6)g(name)208 2270 y(resolution,)18 b(and)i FJ(getaddrinfo\(\))e FN(should)h(be)h(used)g(instead)g(for)g(IPv4/v6)f(dual)g(stack)i (support.)0 2417 y FD(gethostbyname_ex)p FJ(\()p FK(hostname)p FJ(\))208 2516 y FN(T)m(ranslate)e(a)g(host)h(name)e(to)i(IPv4)f (address)g(format,)f(e)o(xtended)f(interf)o(ace.)24 b(Return)19 b(a)h(triple)f FJ(\()p FK(hostname)p FJ(,)48 b FK(aliaslist)q FJ(,)i FK(ipad-)208 2616 y(drlist)q FJ(\))29 b FN(where)e FK(hostname)g FN(is)i(the)f(primary)e(host)i(name)g(responding)d(to)j (the)g(gi)n(v)o(en)f FK(ip)p 2822 2616 25 4 v 30 w(addr)m(ess)p FN(,)i FK(aliaslist)h FN(is)f(a)g(\(possibly)208 2715 y(empty\))18 b(list)i(of)f(alternati)n(v)o(e)f(host)i(names)f(for)g (the)g(same)h(address,)e(and)h FK(ipaddrlist)i FN(is)f(a)g(list)g(of)f (IPv4)g(addresses)g(for)g(the)g(same)208 2815 y(interf)o(ace)h(on)h (the)g(same)h(host)f(\(often)f(b)n(ut)h(not)g(al)o(w)o(ays)h(a)g (single)f(address\).)27 b FJ(gethostbyname_ex\(\))19 b FN(does)i(not)g(support)208 2915 y(IPv6)e(name)h(resolution,)e(and)i FJ(getaddrinfo\(\))e FN(should)h(be)i(used)f(instead)f(for)h(IPv4/v6)f (dual)g(stack)i(support.)0 3062 y FD(gethostname)p FJ(\(\))208 3161 y FN(Return)66 b(a)h(string)g(containing)e(the)i(hostname)f(of)h (the)g(machine)f(where)g(the)h(Python)f(interpreter)f(is)j(cur)n(-)208 3261 y(rently)53 b(e)o(x)o(ecuting.)123 b(If)54 b(you)f(w)o(ant)h(to)g (kno)n(w)e(the)i(current)f(machine')-5 b(s)53 b(IP)h(address,)61 b(you)53 b(may)g(w)o(ant)h(to)g(use)208 3360 y FJ (gethostbyname\(gethostname\(\)\))p FN(.)45 b(This)29 b(operation)e(assumes)i(that)g(there)f(is)i(a)f(v)n(alid)f (address-to-host)e(map-)208 3460 y(ping)18 b(for)h(the)g(host,)g(and)g (the)g(assumption)f(does)h(not)g(al)o(w)o(ays)h(hold.)k(Note:)h FJ(gethostname\(\))17 b FN(doesn')o(t)h(al)o(w)o(ays)h(return)g(the)208 3560 y(fully)g(quali\002ed)g(domain)g(name;)h(use)g FJ(getfqdn\(\))f FN(\(see)i(abo)o(v)o(e\).)0 3707 y FD(gethostbyaddr)p FJ(\()p FK(ip)p 770 3707 V 27 w(addr)m(ess)p FJ(\))208 3806 y FN(Return)28 b(a)i(triple)f FJ(\()p FK(hostname)p FJ(,)47 b FK(aliaslist)q FJ(,)j FK(ipaddrlist)q FJ(\))29 b FN(where)g FK(hostname)f FN(is)i(the)f(primary)e(host)i(name)g (responding)d(to)208 3906 y(the)j(gi)n(v)o(en)f FK(ip)p 620 3906 V 30 w(addr)m(ess)p FN(,)j FK(aliaslist)h FN(is)e(a)g (\(possibly)f(empty\))f(list)j(of)e(alternati)n(v)o(e)f(host)i(names)f (for)g(the)g(same)h(address,)h(and)208 4005 y FK(ipaddrlist)24 b FN(is)h(a)f(list)h(of)e(IPv4/v6)f(addresses)h(for)g(the)h(same)g (interf)o(ace)f(on)g(the)g(same)h(host)g(\(most)f(lik)o(ely)h (containing)d(only)i(a)208 4105 y(single)i(address\).)42 b(T)-7 b(o)26 b(\002nd)f(the)h(fully)f(quali\002ed)g(domain)g(name,)h (use)g(the)g(function)f FJ(getfqdn\(\))p FN(.)40 b FJ(gethostbyaddr)208 4205 y FN(supports)19 b(both)g(IPv4)h(and)f(IPv6.)0 4352 y FD(getnameinfo)p FJ(\()p FK(soc)n(kaddr)-9 b(,)17 b(\003a)o(gs)p FJ(\))208 4451 y FN(T)m(ranslate)j(a)h(sock)o(et)g(address)f FK(soc)n(kaddr)i FN(into)f(a)g(2-tuple)f FJ(\()p FK(host)q FJ(,)49 b FK(port)q FJ(\))p FN(.)28 b(Depending)18 b(on)j(the)g (settings)g(of)f FK(\003a)o(gs)p FN(,)h(the)g(result)208 4551 y(can)c(contain)g(a)h(fully-quali\002ed)d(domain)i(name)g(or)h (numeric)e(address)h(representation)f(in)i FK(host)q FN(.)24 b(Similarly)-5 b(,)18 b FK(port)h FN(can)f(contain)208 4650 y(a)i(string)g(port)g(name)f(or)h(a)h(numeric)d(port)i(number)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 4797 y FD(getprotobyname)p FJ(\()p FK(pr)l(otocolname)p FJ(\))208 4897 y FN(T)m(ranslate)i(an)h(Internet)f(protocol)f(name)h(\(for)g(e)o (xample,)g FJ('icmp')p FN(\))g(to)h(a)h(constant)e(suitable)h(for)f (passing)h(as)h(the)f(\(optional\))208 4997 y(third)29 b(ar)o(gument)e(to)j(the)g FJ(socket\(\))f FN(function.)52 b(This)30 b(is)g(usually)g(only)f(needed)f(for)h(sock)o(ets)h(opened)e (in)i(\223ra)o(w\224)g(mode)208 5096 y(\()p FJ(SOCK_RAW)p FN(\);)18 b(for)h(the)g(normal)g(sock)o(et)g(modes,)g(the)g(correct)g (protocol)f(is)i(chosen)f(automatically)f(if)i(the)g(protocol)e(is)i (omit-)208 5196 y(ted)g(or)g(zero.)0 5343 y FD(getservbyname)p FJ(\()p FK(servicename)p FC([)p FK(,)d(pr)l(otocolname)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v)n(el)g(netw)o(or)q(king)h (interf)n(ace)1989 b(579)p eop end %%Page: 580 592 TeXDict begin 580 591 bop 208 83 a FN(T)m(ranslate)22 b(an)h(Internet)f(service)h(name)g(and)f(protocol)g(name)g(to)i(a)f (port)g(number)e(for)i(that)g(service.)34 b(The)22 b(optional)g (protocol)208 183 y(name,)d(if)h(gi)n(v)o(en,)f(should)g(be)h FJ('tcp')g FN(or)g FJ('udp')p FN(,)g(otherwise)f(an)o(y)h(protocol)e (will)j(match.)0 330 y FD(getservbyport)p FJ(\()p FK(port)q FC([)p FK(,)d(pr)l(otocolname)12 b FC(])p FJ(\))208 429 y FN(T)m(ranslate)22 b(an)h(Internet)f(port)h(number)e(and)i(protocol)e (name)i(to)g(a)h(service)f(name)f(for)h(that)g(service.)34 b(The)22 b(optional)g(protocol)208 529 y(name,)d(if)h(gi)n(v)o(en,)f (should)g(be)h FJ('tcp')g FN(or)g FJ('udp')p FN(,)g(otherwise)f(an)o(y) h(protocol)e(will)j(match.)0 676 y FD(socket)p FJ(\()p FC([)p FK(family)p FC([)p FK(,)d(type)p FC([)p FK(,)i(pr)l(oto)12 b FC(])g(])g(])p FJ(\))208 775 y FN(Create)17 b(a)h(ne)n(w)f(sock)o(et) g(using)g(the)h(gi)n(v)o(en)e(address)h(f)o(amily)-5 b(,)16 b(sock)o(et)i(type)f(and)f(protocol)g(number)-5 b(.)23 b(The)17 b(address)g(f)o(amily)g(should)208 875 y(be)i FJ(AF_INET)g FN(\(the)g(def)o(ault\),)g FJ(AF_INET6)f FN(or)i FJ(AF_UNIX)p FN(.)e(The)i(sock)o(et)f(type)g(should)g(be)g FJ(SOCK_STREAM)g FN(\(the)g(def)o(ault\),)208 975 y FJ(SOCK_DGRAM)e FN(or)h(perhaps)g(one)g(of)g(the)h(other)f(`)p FJ(SOCK_)p FN(')f(constants.)24 b(The)19 b(protocol)e(number)g(is)i(usually)f (zero)g(and)g(may)h(be)208 1074 y(omitted)g(in)h(that)h(case.)0 1221 y FD(ssl)p FJ(\()p FK(soc)n(k)q FC([)p FK(,)f(k)o(e)n(y\002le)o(,) f(cert\002le)12 b FC(])p FJ(\))208 1321 y FN(Initiate)23 b(a)i(SSL)g(connection)d(o)o(v)o(er)h(the)h(sock)o(et)g FK(soc)n(k)q FN(.)38 b FK(k)o(e)n(y\002le)23 b FN(is)i(the)f(name)g(of) g(a)g(PEM)h(formatted)d(\002le)j(that)f(contains)g(your)208 1420 y(pri)n(v)n(ate)19 b(k)o(e)o(y)-5 b(.)24 b FK(cert\002le)c FN(is)h(a)g(PEM)f(formatted)f(certi\002cate)h(chain)f(\002le.)26 b(On)20 b(success,)h(a)f(ne)n(w)g FJ(SSLObject)f FN(is)i(returned.)208 1553 y FL(W)-5 b(ar)o(ning:)24 b FN(This)c(does)g(not)g(do)g(an)o(y)f (certi\002cate)h(v)o(eri\002cation!)0 1700 y FD(socketpair)p FJ(\()p FC([)p FK(family)p FC([)p FK(,)e(type)p FC([)p FK(,)h(pr)l(oto)12 b FC(])g(])g(])p FJ(\))208 1800 y FN(Build)30 b(a)i(pair)e(of)g(connected)f(sock)o(et)i(objects)f(using)g (the)h(gi)n(v)o(en)e(address)i(f)o(amily)-5 b(,)32 b(sock)o(et)e(type,) j(and)d(protocol)f(number)-5 b(.)208 1899 y(Address)19 b(f)o(amily)-5 b(,)18 b(sock)o(et)i(type,)f(and)g(protocol)f(number)g (are)h(as)i(for)e(the)g FJ(socket\(\))g FN(function)f(abo)o(v)o(e.)23 b(The)c(def)o(ault)g(f)o(amily)208 1999 y(is)30 b FJ(AF_UNIX)f FN(if)h(de\002ned)f(on)g(the)h(platform;)j(otherwise,)e(the)f(def)o (ault)f(is)i FJ(AF_INET)p FN(.)d(A)-6 b(v)n(ailability:)46 b(U)t FH(N)t(I)t(X)r FN(.)108 b(Ne)n(w)30 b(in)208 2098 y(v)o(ersion)18 b(2.4.)0 2245 y FD(fromfd)p FJ(\()p FK(fd,)h(family)-5 b(,)20 b(type)p FC([)p FK(,)g(pr)l(oto)12 b FC(])p FJ(\))208 2345 y FN(Duplicate)20 b(the)h(\002le)g(descriptor)f FK(fd)j FN(\(an)d(inte)o(ger)g(as)i(returned)d(by)h(a)h(\002le)h (object')-5 b(s)21 b FJ(fileno\(\))f FN(method\))f(and)h(b)n(uild)g(a)i (sock)o(et)208 2445 y(object)k(from)h(the)g(result.)47 b(Address)27 b(f)o(amily)-5 b(,)28 b(sock)o(et)g(type)f(and)g(protocol) e(number)h(are)h(as)h(for)f(the)h FJ(socket\(\))e FN(function)208 2544 y(abo)o(v)o(e.)c(The)17 b(\002le)i(descriptor)d(should)h(refer)g (to)h(a)g(sock)o(et,)g(b)n(ut)f(this)i(is)f(not)g(check)o(ed)e(\227)j (subsequent)d(operations)g(on)h(the)h(object)208 2644 y(may)27 b(f)o(ail)i(if)g(the)f(\002le)h(descriptor)e(is)i(in)m(v)n (alid.)48 b(This)29 b(function)d(is)k(rarely)d(needed,)i(b)n(ut)f(can)g (be)h(used)f(to)g(get)h(or)f(set)h(sock)o(et)208 2743 y(options)22 b(on)h(a)g(sock)o(et)g(passed)g(to)g(a)h(program)d(as)j (standard)e(input)g(or)h(output)f(\(such)h(as)g(a)h(serv)o(er)e (started)h(by)g(the)i(U)t FH(N)t(I)t(X)h FN(inet)208 2843 y(daemon\).)d(The)c(sock)o(et)h(is)i(assumed)d(to)i(be)f(in)g (blocking)e(mode.)24 b(A)-6 b(v)n(ailability:)27 b(U)t FH(N)t(I)t(X)r FN(.)0 2990 y FD(ntohl)p FJ(\()p FK(x)p FJ(\))208 3090 y FN(Con)m(v)o(ert)20 b(32-bit)g(inte)o(gers)h(from)f (netw)o(ork)g(to)i(host)g(byte)f(order)-5 b(.)28 b(On)21 b(machines)g(where)g(the)g(host)h(byte)f(order)f(is)j(the)e(same)h(as) 208 3189 y(netw)o(ork)d(byte)g(order)m(,)g(this)h(is)h(a)g(no-op;)e (otherwise,)g(it)i(performs)d(a)j(4-byte)e(sw)o(ap)h(operation.)0 3336 y FD(ntohs)p FJ(\()p FK(x)p FJ(\))208 3436 y FN(Con)m(v)o(ert)g (16-bit)g(inte)o(gers)h(from)f(netw)o(ork)g(to)i(host)g(byte)f(order)-5 b(.)28 b(On)21 b(machines)g(where)g(the)g(host)h(byte)f(order)f(is)j (the)e(same)h(as)208 3535 y(netw)o(ork)d(byte)g(order)m(,)g(this)h(is)h (a)g(no-op;)e(otherwise,)g(it)i(performs)d(a)j(2-byte)e(sw)o(ap)h (operation.)0 3682 y FD(htonl)p FJ(\()p FK(x)p FJ(\))208 3782 y FN(Con)m(v)o(ert)g(32-bit)g(inte)o(gers)h(from)f(host)i(to)f (netw)o(ork)g(byte)g(order)-5 b(.)28 b(On)21 b(machines)g(where)g(the)g (host)h(byte)f(order)f(is)j(the)e(same)h(as)208 3881 y(netw)o(ork)d(byte)g(order)m(,)g(this)h(is)h(a)g(no-op;)e(otherwise,)g (it)i(performs)d(a)j(4-byte)e(sw)o(ap)h(operation.)0 4028 y FD(htons)p FJ(\()p FK(x)p FJ(\))208 4128 y FN(Con)m(v)o(ert)g (16-bit)g(inte)o(gers)h(from)f(host)i(to)f(netw)o(ork)g(byte)g(order)-5 b(.)28 b(On)21 b(machines)g(where)g(the)g(host)h(byte)f(order)f(is)j (the)e(same)h(as)208 4228 y(netw)o(ork)d(byte)g(order)m(,)g(this)h(is)h (a)g(no-op;)e(otherwise,)g(it)i(performs)d(a)j(2-byte)e(sw)o(ap)h (operation.)0 4374 y FD(inet_aton)p FJ(\()p FK(ip)p 570 4374 25 4 v 28 w(string)p FJ(\))208 4474 y FN(Con)m(v)o(ert)h(an)h (IPv4)g(address)g(from)f(dotted-quad)f(string)i(format)g(\(for)f(e)o (xample,)h('123.45.67.89'\))16 b(to)23 b(32-bit)f(pack)o(ed)f(binary) 208 4574 y(format,)15 b(as)i(a)g(string)e(four)g(characters)h(in)g (length.)23 b(This)16 b(is)h(useful)f(when)f(con)m(v)o(ersing)f(with)i (a)h(program)d(that)i(uses)h(the)f(standard)208 4673 y(C)23 b(library)f(and)g(needs)g(objects)h(of)f(type)h FJ(struct)48 b(in_addr)p FN(,)23 b(which)f(is)i(the)e(C)i(type)e(for)h (the)f(32-bit)g(pack)o(ed)g(binary)f(this)208 4773 y(function)d (returns.)208 4906 y(If)k(the)h(IPv4)f(address)h(string)f(passed)h(to)g (this)g(function)e(is)j(in)m(v)n(alid,)e FJ(socket.error)f FN(will)j(be)e(raised.)33 b(Note)23 b(that)f(e)o(xactly)208 5005 y(what)e(is)h(v)n(alid)f(depends)e(on)i(the)g(underlying)e(C)j (implementation)d(of)i FJ(inet_aton\(\))p FN(.)208 5138 y FJ(inet_aton\(\))h FN(does)i(not)g(support)e(IPv6,)i(and)g FJ(getnameinfo\(\))e FN(should)h(be)h(used)g(instead)g(for)f(IPv4/v6)g (dual)g(stack)208 5238 y(support.)0 5385 y FD(inet_ntoa)p FJ(\()p FK(pac)n(k)o(ed)p 739 5385 V 27 w(ip)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(580)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 581 593 TeXDict begin 581 592 bop 208 83 a FN(Con)m(v)o(ert)30 b(a)i(32-bit)e(pack)o(ed)h(IPv4)g(address)g(\(a)h(string)f(four)g (characters)g(in)h(length\))e(to)i(its)h(standard)d(dotted-quad)f (string)208 183 y(representation)g(\(for)h(e)o(xample,)j ('123.45.67.89'\).)53 b(This)31 b(is)h(useful)f(when)g(con)m(v)o (ersing)e(with)i(a)h(program)d(that)j(uses)g(the)208 282 y(standard)25 b(C)j(library)e(and)h(needs)g(objects)f(of)h(type)g FJ(struct)48 b(in_addr)p FN(,)28 b(which)f(is)h(the)f(C)h(type)e(for)h (the)g(32-bit)f(pack)o(ed)208 382 y(binary)18 b(data)i(this)h(function) e(tak)o(es)h(as)h(an)f(ar)o(gument.)208 515 y(If)i(the)h(string)f (passed)h(to)g(this)g(function)e(is)j(not)f(e)o(xactly)f(4)g(bytes)h (in)g(length,)f FJ(socket.error)f FN(will)j(be)f(raised.)32 b FJ(inet_-)208 614 y(ntoa\(\))19 b FN(does)h(not)g(support)f(IPv6,)g (and)h FJ(getnameinfo\(\))e FN(should)h(be)h(used)g(instead)g(for)g (IPv4/v6)e(dual)i(stack)g(support.)0 761 y FD(inet_pton)p FJ(\()p FK(addr)m(ess)p 761 761 25 4 v 27 w(family)-5 b(,)21 b(ip)p 1098 761 V 29 w(string)p FJ(\))208 861 y FN(Con)m(v)o(ert)27 b(an)i(IP)g(address)g(from)e(its)j(f)o (amily-speci\002c)e(string)h(format)e(to)j(a)f(pack)o(ed,)h(binary)d (format.)50 b FJ(inet_pton\(\))28 b FN(is)208 960 y(useful)22 b(when)g(a)h(library)f(or)g(netw)o(ork)g(protocol)f(calls)i(for)f(an)h (object)f(of)h(type)f FJ(struct)49 b(in_addr)22 b FN(\(similar)g(to)h FJ(inet_-)208 1060 y(aton\(\))p FN(\))c(or)h FJ(struct)48 b(in6_addr)p FN(.)208 1193 y(Supported)29 b(v)n(alues)h(for)h FK(addr)m(ess)p 1212 1193 V 29 w(family)g FN(are)h(currently)d FJ(AF_INET)i FN(and)f FJ(AF_INET6)p FN(.)57 b(If)31 b(the)h(IP)f (address)g(string)g FK(ip)p 3848 1193 V 29 w(-)208 1293 y(string)22 b FN(is)h(in)m(v)n(alid,)e FJ(socket.error)f FN(will)j(be)f(raised.)31 b(Note)22 b(that)g(e)o(xactly)f(what)h(is)h (v)n(alid)f(depends)e(on)i(both)f(the)h(v)n(alue)g(of)208 1392 y FK(addr)m(ess)p 469 1392 V 29 w(family)e FN(and)g(the)g (underlying)d(implementation)h(of)i FJ(inet_pton\(\))p FN(.)208 1525 y(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)d FN(\(maybe)c(not)h(all)g(platforms\).)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1672 y FD(inet_ntop)p FJ(\()p FK(addr)m(ess)p 761 1672 V 27 w(family)-5 b(,)21 b(pac)n(k)o(ed)p 1267 1672 V 28 w(ip)p FJ(\))208 1772 y FN(Con)m(v)o(ert)30 b(a)i(pack)o(ed)e(IP)j(address)e(\(a)h(string)f(of)g(some)h(number)e (of)h(characters\))g(to)g(its)i(standard,)g(f)o(amily-speci\002c)e (string)208 1871 y(representation)e(\(for)i(e)o(xample,)i FJ('7.10.0.5')e FN(or)h FJ('5aef:2b::8')p FN(\))d FJ(inet_ntop\(\))i FN(is)i(useful)e(when)g(a)i(library)208 1971 y(or)c(netw)o(ork)f (protocol)f(returns)h(an)i(object)e(of)h(type)g FJ(struct)49 b(in_addr)28 b FN(\(similar)h(to)h FJ(inet_ntoa\(\))p FN(\))d(or)i FJ(struct)208 2070 y(in6_addr)p FN(.)208 2203 y(Supported)18 b(v)n(alues)j(for)f FK(addr)m(ess)p 1181 2203 V 29 w(family)h FN(are)g(currently)e FJ(AF_INET)h FN(and)g FJ(AF_INET6)p FN(.)26 b(If)21 b(the)f(string)h FK(pac)n(k)o(ed)p 3485 2203 V 28 w(ip)g FN(is)h(not)f(the)208 2303 y(correct)g(length)g(for)g(the)h(speci\002ed)g(address)f(f)o (amily)-5 b(,)22 b FJ(ValueError)f FN(will)h(be)g(raised.)31 b(A)22 b FJ(socket.error)e FN(is)j(raised)f(for)208 2402 y(errors)d(from)g(the)h(call)h(to)f FJ(inet_ntop\(\))p FN(.)208 2535 y(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)d FN(\(maybe)c(not)h(all)g(platforms\).)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 2682 y FD(getdefaulttimeout)p FJ(\(\))208 2782 y FN(Return)d(the)i(def)o(ault)e(timeout)h(in)g (\003oating)f(seconds)h(for)g(ne)n(w)g(sock)o(et)g(objects.)23 b(A)18 b(v)n(alue)f(of)f FJ(None)h FN(indicates)g(that)h(ne)n(w)f(sock) o(et)208 2881 y(objects)j(ha)n(v)o(e)f(no)h(timeout.)k(When)c(the)g (sock)o(et)g(module)f(is)i(\002rst)g(imported,)e(the)h(def)o(ault)f(is) i FJ(None)p FN(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3028 y FD(setdefaulttimeout)p FJ(\()p FK(timeout)q FJ(\))208 3128 y FN(Set)24 b(the)f(def)o(ault)g(timeout)g(in)h(\003oating)f (seconds)g(for)g(ne)n(w)g(sock)o(et)h(objects.)35 b(A)24 b(v)n(alue)f(of)g FJ(None)g FN(indicates)h(that)f(ne)n(w)h(sock)o(et) 208 3228 y(objects)c(ha)n(v)o(e)f(no)h(timeout.)k(When)c(the)g(sock)o (et)g(module)f(is)i(\002rst)g(imported,)e(the)h(def)o(ault)f(is)i FJ(None)p FN(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3374 y FD(SocketType)208 3474 y FN(This)h(is)h(a)g(Python)e(type)g (object)h(that)g(represents)g(the)g(sock)o(et)g(object)g(type.)k(It)d (is)g(the)f(same)g(as)h FJ(type\(socket\(...\)\))p FN(.)0 3621 y FL(See)g(Also:)0 3768 y FN(Module)e FJ(SocketServer)g FN(\(section)g(18.18\):)208 3867 y(Classes)i(that)g(simplify)e(writing) h(netw)o(ork)f(serv)o(ers.)0 4152 y Fv(17.2.1)101 b(Soc)n(k)n(et)28 b(Objects)0 4355 y FN(Sock)o(et)23 b(objects)f(ha)n(v)o(e)g(the)h (follo)n(wing)e(methods.)32 b(Except)22 b(for)g FJ(makefile\(\))g FN(these)h(correspond)d(to)25 b(U)t FH(N)t(I)t(X)h FN(system)d(calls)g (appli-)0 4455 y(cable)d(to)g(sock)o(ets.)0 4602 y FD(accept)p FJ(\(\))208 4701 y FN(Accept)f(a)h(connection.)j(The)c(sock)o(et)h (must)f(be)h(bound)e(to)i(an)f(address)g(and)h(listening)f(for)g (connections.)k(The)c(return)g(v)n(alue)g(is)208 4801 y(a)j(pair)h FJ(\()p FK(conn)p FJ(,)47 b FK(addr)m(ess)p FJ(\))22 b FN(where)g FK(conn)g FN(is)h(a)g FK(ne)o(w)g FN(sock)o(et)f(object)g(usable)g(to)h(send)f(and)g(recei)n(v)o(e)f (data)h(on)g(the)h(connection,)208 4901 y(and)c FK(addr)m(ess)h FN(is)h(the)f(address)g(bound)f(to)h(the)g(sock)o(et)g(on)g(the)g (other)f(end)h(of)g(the)g(connection.)0 5047 y FD(bind)p FJ(\()p FK(addr)m(ess)p FJ(\))208 5147 y FN(Bind)28 b(the)g(sock)o(et)g (to)g FK(addr)m(ess)p FN(.)49 b(The)28 b(sock)o(et)g(must)g(not)g (already)f(be)h(bound.)47 b(\(The)28 b(format)f(of)h FK(addr)m(ess)g FN(depends)f(on)h(the)208 5247 y(address)22 b(f)o(amily)f(\227)i(see)g(abo)o(v)o(e.\))30 b FL(Note:)f FN(This)23 b(method)e(has)h(historically)g(accepted)f(a)i(pair)f(of)g (parameters)g(for)f FJ(AF_INET)208 5346 y FN(addresses)e(instead)h(of)g (only)g(a)g(tuple.)25 b(This)20 b(w)o(as)h(ne)n(v)o(er)e(intentional)g (and)h(is)h(no)f(longer)e(a)n(v)n(ailable)i(in)g(Python)f(2.0)h(and)g (later)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v)n(el)g(netw)o(or)q(king)h (interf)n(ace)1989 b(581)p eop end %%Page: 582 594 TeXDict begin 582 593 bop 0 83 a FD(close)p FJ(\(\))208 183 y FN(Close)21 b(the)g(sock)o(et.)28 b(All)21 b(future)f(operations) g(on)g(the)i(sock)o(et)e(object)h(will)h(f)o(ail.)28 b(The)20 b(remote)h(end)f(will)i(recei)n(v)o(e)e(no)g(more)h(data)208 282 y(\(after)e(queued)g(data)h(is)h(\003ushed\).)j(Sock)o(ets)c(are)g (automatically)f(closed)h(when)f(the)o(y)h(are)g(garbage-collected.)0 429 y FD(connect)p FJ(\()p FK(addr)m(ess)p FJ(\))208 529 y FN(Connect)k(to)h(a)h(remote)e(sock)o(et)i(at)f FK(addr)m(ess)p FN(.)40 b(\(The)25 b(format)f(of)h FK(addr)m(ess)g FN(depends)f(on)g(the)i(address)e(f)o(amily)h(\227)h(see)g(abo)o(v)o (e.\))208 628 y FL(Note:)40 b FN(This)29 b(method)e(has)h(historically) g(accepted)f(a)i(pair)f(of)g(parameters)f(for)h FJ(AF_INET)f FN(addresses)h(instead)h(of)f(only)f(a)208 728 y(tuple.)d(This)c(w)o (as)h(ne)n(v)o(er)e(intentional)g(and)h(is)h(no)f(longer)f(a)n(v)n (ailable)g(in)i(Python)e(2.0)g(and)h(later)-5 b(.)0 875 y FD(connect_ex)p FJ(\()p FK(addr)m(ess)p FJ(\))208 975 y FN(Lik)o(e)25 b FJ(connect\()p FK(addr)m(ess)p FJ(\))p FN(,)h(b)n(ut)g(return)e(an)i(error)f(indicator)g(instead)g(of)h (raising)g(an)f(e)o(xception)f(for)i(errors)f(returned)f(by)208 1074 y(the)g(C-le)n(v)o(el)g FJ(connect\(\))g FN(call)g(\(other)g (problems,)g(such)g(as)h(\223host)f(not)g(found,)-6 b(\224)24 b(can)g(still)i(raise)f(e)o(xceptions\).)36 b(The)24 b(error)208 1174 y(indicator)c(is)j FJ(0)g FN(if)f(the)g(operation)e (succeeded,)h(otherwise)h(the)g(v)n(alue)f(of)h(the)g FJ(errno)g FN(v)n(ariable.)29 b(This)22 b(is)h(useful)f(to)g(support,) 208 1273 y(for)29 b(e)o(xample,)h(asynchronous)d(connects.)53 b FL(Note:)43 b FN(This)30 b(method)f(has)h(historically)f(accepted)f (a)j(pair)e(of)h(parameters)e(for)208 1373 y FJ(AF_INET)18 b FN(addresses)i(instead)f(of)g(only)g(a)h(tuple.)k(This)c(w)o(as)h(ne) n(v)o(er)d(intentional)g(and)h(is)i(no)e(longer)f(a)n(v)n(ailable)h(in) h(Python)e(2.0)208 1473 y(and)h(later)-5 b(.)0 1620 y FD(fileno)p FJ(\(\))208 1719 y FN(Return)19 b(the)i(sock)o(et')-5 b(s)20 b(\002le)h(descriptor)e(\(a)h(small)g(inte)o(ger\).)k(This)c(is) h(useful)f(with)g FJ(select.select\(\))p FN(.)208 1852 y(Under)j(W)m(indo)n(ws)i(the)g(small)g(inte)o(ger)f(returned)f(by)h (this)h(method)f(cannot)g(be)g(used)h(where)f(a)h(\002le)h(descriptor)d (can)i(be)g(used)208 1952 y(\(such)19 b(as)i FJ(os.fdopen\(\))p FN(\).)k(U)t FH(N)t(I)t(X)e FN(does)d(not)g(ha)n(v)o(e)g(this)g (limitation.)0 2098 y FD(getpeername)p FJ(\(\))208 2198 y FN(Return)27 b(the)h(remote)f(address)h(to)g(which)f(the)h(sock)o(et) g(is)h(connected.)47 b(This)28 b(is)h(useful)e(to)h(\002nd)g(out)g(the) g(port)f(number)f(of)i(a)208 2298 y(remote)21 b(IPv4/v6)f(sock)o(et,)i (for)g(instance.)30 b(\(The)21 b(format)g(of)g(the)h(address)g (returned)e(depends)h(on)g(the)h(address)g(f)o(amily)f(\227)i(see)208 2397 y(abo)o(v)o(e.\))f(On)f(some)f(systems)g(this)h(function)e(is)i (not)f(supported.)0 2544 y FD(getsockname)p FJ(\(\))208 2644 y FN(Return)i(the)h(sock)o(et')-5 b(s)24 b(o)n(wn)e(address.)33 b(This)24 b(is)g(useful)e(to)h(\002nd)g(out)g(the)g(port)g(number)e(of) i(an)g(IPv4/v6)e(sock)o(et,)j(for)e(instance.)208 2743 y(\(The)d(format)g(of)h(the)g(address)g(returned)e(depends)h(on)h(the)g (address)g(f)o(amily)g(\227)g(see)h(abo)o(v)o(e.\))0 2890 y FD(getsockopt)p FJ(\()p FK(le)o(vel,)d(optname)p FC([)p FK(,)g(b)n(u\003en)12 b FC(])p FJ(\))208 2990 y FN(Return)29 b(the)i(v)n(alue)e(of)h(the)g(gi)n(v)o(en)f(sock)o(et)h (option)f(\(see)h(the)j(U)t FH(N)t(I)t(X)g FN(man)d(page)f FK(g)o(etsoc)n(k)o(opt)p FN(\(2\)\).)53 b(The)30 b(needed)f(symbolic) 208 3090 y(constants)18 b(\()p FJ(SO_)714 3105 y(*)782 3090 y FN(etc.\))24 b(are)19 b(de\002ned)f(in)g(this)i(module.)j(If)18 b FK(b)n(u\003en)g FN(is)h(absent,)g(an)f(inte)o(ger)g(option)f(is)j (assumed)e(and)g(its)i(inte)o(ger)208 3189 y(v)n(alue)27 b(is)i(returned)d(by)h(the)h(function.)47 b(If)28 b FK(b)n(u\003en)e FN(is)j(present,)g(it)g(speci\002es)f(the)g(maximum)e(length)i(of)f (the)h(b)n(uf)n(fer)f(used)g(to)208 3289 y(recei)n(v)o(e)c(the)h (option)f(in,)i(and)e(this)i(b)n(uf)n(fer)e(is)i(returned)d(as)j(a)g (string.)36 b(It)25 b(is)g(up)e(to)i(the)f(caller)g(to)g(decode)f(the)h (contents)g(of)g(the)208 3388 y(b)n(uf)n(fer)18 b(\(see)j(the)f (optional)f(b)n(uilt-in)h(module)e FJ(struct)i FN(for)g(a)g(w)o(ay)g (to)h(decode)e(C)i(structures)e(encoded)g(as)i(strings\).)0 3535 y FD(listen)p FJ(\()p FK(bac)n(klo)o(g)p FJ(\))208 3635 y FN(Listen)26 b(for)g(connections)f(made)h(to)h(the)f(sock)o(et.) 44 b(The)27 b FK(bac)n(klo)o(g)e FN(ar)o(gument)f(speci\002es)k(the)e (maximum)f(number)g(of)h(queued)208 3735 y(connections)18 b(and)i(should)f(be)h(at)h(least)f(1;)h(the)f(maximum)f(v)n(alue)g(is)i (system-dependent)c(\(usually)j(5\).)0 3881 y FD(makefile)p FJ(\()p FC([)p FK(mode)p FC([)p FK(,)d(b)n(ufsize)12 b FC(])g(])p FJ(\))208 3981 y FN(Return)18 b(a)i FK(\002le)f(object)f FN(associated)h(with)g(the)g(sock)o(et.)25 b(\(File)19 b(objects)g(are)g(described)f(in)h(3.9,)g(\223File)g(Objects.)-6 b(\224\))25 b(The)18 b(\002le)i(object)208 4081 y(references)h(a)h FJ(dup\(\))p FN(ped)f(v)o(ersion)g(of)h(the)h(sock)o(et)f(\002le)h (descriptor)m(,)e(so)i(the)f(\002le)h(object)f(and)g(sock)o(et)g (object)g(may)g(be)g(closed)208 4180 y(or)29 b(garbage-collected)e (independently)-5 b(.)51 b(The)29 b(sock)o(et)h(must)g(be)g(in)g (blocking)e(mode.)54 b(The)29 b(optional)g FK(mode)h FN(and)f FK(b)n(ufsize)208 4280 y FN(ar)o(guments)20 b(are)j(interpreted)e(the)i(same)h(w)o(ay)f(as)g(by)g(the)g(b)n (uilt-in)f FJ(file\(\))g FN(function;)h(see)h(\223Built-in)e (Functions\224)g(\(section)208 4380 y(2.1\))d(for)g(more)h (information.)0 4526 y FD(recv)p FJ(\()p FK(b)n(ufsize)p FC([)p FK(,)f(\003a)o(gs)12 b FC(])p FJ(\))208 4626 y FN(Recei)n(v)o(e)18 b(data)h(from)f(the)h(sock)o(et.)25 b(The)18 b(return)g(v)n(alue)h(is)h(a)f(string)g(representing)e(the)i (data)g(recei)n(v)o(ed.)k(The)c(maximum)e(amount)208 4726 y(of)j(data)h(to)g(be)g(recei)n(v)o(ed)e(at)i(once)f(is)i (speci\002ed)f(by)f FK(b)n(ufsize)p FN(.)28 b(See)21 b(the)i(U)t FH(N)t(I)t(X)h FN(manual)19 b(page)i FK(r)m(ecv)p FN(\(2\))f(for)g(the)h(meaning)e(of)i(the)208 4825 y(optional)c(ar)o (gument)f FK(\003a)o(gs)p FN(;)j(it)g(def)o(aults)g(to)f(zero.)24 b FL(Note:)g FN(F)o(or)18 b(best)h(match)f(with)h(hardw)o(are)e(and)h (netw)o(ork)g(realities,)h(the)f(v)n(alue)208 4925 y(of)h FK(b)n(ufsize)i FN(should)e(be)h(a)h(relati)n(v)o(ely)e(small)i(po)n (wer)e(of)h(2,)g(for)f(e)o(xample,)g(4096.)0 5072 y FD(recvfrom)p FJ(\()p FK(b)n(ufsize)p FC([)p FK(,)g(\003a)o(gs)12 b FC(])p FJ(\))208 5171 y FN(Recei)n(v)o(e)18 b(data)g(from)g(the)h(sock) o(et.)24 b(The)18 b(return)g(v)n(alue)f(is)j(a)f(pair)f FJ(\()p FK(string)p FJ(,)50 b FK(addr)m(ess)p FJ(\))18 b FN(where)g FK(string)h FN(is)g(a)g(string)g(representing)208 5271 y(the)h(data)h(recei)n(v)o(ed)e(and)h FK(addr)m(ess)h FN(is)h(the)f(address)f(of)g(the)h(sock)o(et)g(sending)e(the)i(data.)27 b(The)20 b(optional)g FK(\003a)o(gs)g FN(ar)o(gument)f(has)i(the)208 5371 y(same)f(meaning)f(as)i(for)e FJ(recv\(\))h FN(abo)o(v)o(e.)j (\(The)c(format)h(of)f FK(addr)m(ess)h FN(depends)f(on)h(the)g(address) g(f)o(amily)g(\227)g(see)h(abo)o(v)o(e.\))p 0 5549 3901 4 v 0 5649 a FI(582)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 583 595 TeXDict begin 583 594 bop 0 83 a FD(recvfrom_into)p FJ(\()p FK(b)n(uf)o(fer)r FC([)p FK(,)17 b(nbytes)p FC([)p FK(,)i(\003a)o(gs)12 b FC(])g(])p FJ(\))208 183 y FN(Recei)n(v)o(e)30 b(data)h(from)f(the)h (sock)o(et,)j(writing)c(it)i(into)f FK(b)n(uf)o(fer)i FN(instead)e(of)f(creating)g(a)i(ne)n(w)f(string.)57 b(The)31 b(return)f(v)n(alue)g(is)i(a)208 282 y(pair)21 b FJ(\()p FK(nbytes)p FJ(,)49 b FK(addr)m(ess)p FJ(\))22 b FN(where)f FK(nbytes)h FN(is)h(the)f(number)f(of)h(bytes)g(recei)n(v) o(ed)e(and)i FK(addr)m(ess)g FN(is)h(the)f(address)g(of)g(the)g(sock)o (et)208 382 y(sending)d(the)i(data.)27 b(See)22 b(the)h(U)t FH(N)t(I)t(X)h FN(manual)c(page)g FK(r)m(ecv)p FN(\(2\))g(for)g(the)h (meaning)f(of)g(the)h(optional)f(ar)o(gument)e FK(\003a)o(gs)p FN(;)j(it)h(def)o(aults)208 482 y(to)e(zero.)k(\(The)c(format)f(of)h FK(addr)m(ess)g FN(depends)f(on)g(the)i(address)e(f)o(amily)h(\227)h (see)g(abo)o(v)o(e.\))48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 628 y FD(recv_into)p FJ(\()p FK(b)n(uf)o(fer)r FC([)p FK(,)f(nbytes)p FC([)p FK(,)h(\003a)o(gs)12 b FC(])g(])p FJ(\))208 728 y FN(Recei)n(v)o(e)24 b(up)g(to)h FK(nbytes)f FN(bytes)h(from)f(the)g(sock)o(et,)i(storing)e(the)h(data)f(into)h(a)g (b)n(uf)n(fer)e(rather)h(than)g(creating)g(a)h(ne)n(w)g(string.)38 b(If)208 828 y FK(nbytes)25 b FN(is)i(not)f(speci\002ed)f(\(or)g(0\),)i (recei)n(v)o(e)e(up)h(to)g(the)f(size)i(a)n(v)n(ailable)e(in)i(the)e (gi)n(v)o(en)g(b)n(uf)n(fer)-5 b(.)41 b(See)27 b(the)g(U)t FH(N)t(I)t(X)i FN(manual)c(page)208 927 y FK(r)m(ecv)p FN(\(2\))19 b(for)g(the)i(meaning)d(of)i(the)g(optional)f(ar)o(gument)f FK(\003a)o(gs)p FN(;)i(it)h(def)o(aults)f(to)g(zero.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1074 y FD(send)p FJ(\()p FK(string)p FC([)p FK(,)g(\003a)o(gs)12 b FC(])p FJ(\))208 1174 y FN(Send)26 b(data)h(to)g(the)f(sock)o(et.)45 b(The)27 b(sock)o(et)f(must)h(be)g(connected)e(to)i(a)g(remote)f(sock)o (et.)45 b(The)26 b(optional)g FK(\003a)o(gs)g FN(ar)o(gument)e(has)208 1273 y(the)h(same)g(meaning)f(as)h(for)g FJ(recv\(\))f FN(abo)o(v)o(e.)38 b(Returns)25 b(the)g(number)f(of)g(bytes)h(sent.)40 b(Applications)24 b(are)h(responsible)f(for)208 1373 y(checking)d(that)h(all)i(data)e(has)h(been)f(sent;)j(if)e(only)f(some) g(of)h(the)f(data)h(w)o(as)g(transmitted,)g(the)f(application)g(needs)g (to)h(attempt)208 1473 y(deli)n(v)o(ery)18 b(of)i(the)g(remaining)f (data.)0 1620 y FD(sendall)p FJ(\()p FK(string)p FC([)p FK(,)g(\003a)o(gs)12 b FC(])p FJ(\))208 1719 y FN(Send)26 b(data)h(to)g(the)f(sock)o(et.)45 b(The)27 b(sock)o(et)f(must)h(be)g (connected)e(to)i(a)g(remote)f(sock)o(et.)45 b(The)26 b(optional)g FK(\003a)o(gs)g FN(ar)o(gument)e(has)208 1819 y(the)c(same)g(meaning)f(as)i(for)e FJ(recv\(\))h FN(abo)o(v)o(e.)k(Unlik)o(e)19 b FJ(send\(\))p FN(,)h(this)h(method)e (continues)g(to)h(send)g(data)g(from)f FK(string)i FN(until)208 1918 y(either)h(all)i(data)f(has)g(been)g(sent)g(or)g(an)g(error)f (occurs.)33 b FJ(None)23 b FN(is)h(returned)d(on)i(success.)34 b(On)23 b(error)m(,)g(an)g(e)o(xception)e(is)j(raised,)208 2018 y(and)19 b(there)h(is)h(no)f(w)o(ay)g(to)g(determine)f(ho)n(w)h (much)f(data,)h(if)g(an)o(y)-5 b(,)19 b(w)o(as)i(successfully)f(sent.)0 2165 y FD(sendto)p FJ(\()p FK(string)p FC([)p FK(,)f(\003a)o(gs)12 b FC(])p FK(,)19 b(addr)m(ess)p FJ(\))208 2265 y FN(Send)25 b(data)h(to)g(the)g(sock)o(et.)42 b(The)26 b(sock)o(et)g(should)f(not)g (be)h(connected)e(to)i(a)h(remote)e(sock)o(et,)i(since)f(the)g (destination)f(sock)o(et)208 2364 y(is)f(speci\002ed)g(by)f FK(addr)m(ess)p FN(.)35 b(The)23 b(optional)g FK(\003a)o(gs)g FN(ar)o(gument)e(has)j(the)g(same)g(meaning)e(as)i(for)f FJ(recv\(\))h FN(abo)o(v)o(e.)33 b(Return)24 b(the)208 2464 y(number)18 b(of)i(bytes)g(sent.)25 b(\(The)20 b(format)f(of)h FK(addr)m(ess)g FN(depends)e(on)i(the)g(address)g(f)o(amily)g(\227)h (see)f(abo)o(v)o(e.\))0 2611 y FD(setblocking)p FJ(\()p FK(\003a)o(g)p FJ(\))208 2710 y FN(Set)h(blocking)e(or)h(non-blocking)d (mode)j(of)g(the)h(sock)o(et:)26 b(if)21 b FK(\003a)o(g)e FN(is)j(0,)f(the)f(sock)o(et)h(is)g(set)h(to)f(non-blocking,)16 b(else)22 b(to)e(blocking)208 2810 y(mode.)46 b(Initially)27 b(all)h(sock)o(ets)g(are)g(in)g(blocking)d(mode.)47 b(In)27 b(non-blocking)d(mode,)29 b(if)e(a)i FJ(recv\(\))e FN(call)h(doesn')o (t)e(\002nd)h(an)o(y)208 2910 y(data,)32 b(or)d(if)i(a)f FJ(send\(\))g FN(call)g(can')o(t)f(immediately)g(dispose)g(of)h(the)g (data,)i(a)f FJ(error)e FN(e)o(xception)f(is)j(raised;)k(in)30 b(blocking)208 3009 y(mode,)25 b(the)g(calls)h(block)f(until)g(the)o(y) g(can)g(proceed.)38 b FJ(s.setblocking\(0\))23 b FN(is)k(equi)n(v)n (alent)c(to)j FJ(s.settimeout\(0\))p FN(;)208 3109 y FJ(s.setblocking\(1\))17 b FN(is)k(equi)n(v)n(alent)e(to)h FJ(s.settimeout\(None\))p FN(.)0 3256 y FD(settimeout)p FJ(\()p FK(value)p FJ(\))208 3355 y FN(Set)e(a)h(timeout)f(on)f (blocking)g(sock)o(et)h(operations.)23 b(The)17 b FK(value)h FN(ar)o(gument)e(can)i(be)g(a)h(nonne)o(gati)n(v)o(e)14 b(\003oat)19 b(e)o(xpressing)d(seconds,)208 3455 y(or)g FJ(None)p FN(.)24 b(If)17 b(a)h(\003oat)f(is)i(gi)n(v)o(en,)d (subsequent)g(sock)o(et)h(operations)e(will)j(raise)g(an)f FJ(timeout)f FN(e)o(xception)g(if)h(the)g(timeout)g(period)208 3555 y FK(value)23 b FN(has)h(elapsed)g(before)f(the)h(operation)e(has) i(completed.)35 b(Setting)24 b(a)g(timeout)g(of)f FJ(None)h FN(disables)g(timeouts)g(on)g(sock)o(et)208 3654 y(operations.)53 b FJ(s.settimeout\(0.0\))27 b FN(is)32 b(equi)n(v)n(alent)c(to)i FJ(s.setblocking\(0\))p FN(;)j FJ(s.settimeout\(None\))28 b FN(is)208 3754 y(equi)n(v)n(alent)18 b(to)i FJ(s.setblocking\(1\))p FN(.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3901 y FD(gettimeout)p FJ(\(\))208 4000 y FN(Return)26 b(the)h(timeout)g(in)g (\003oating)g(seconds)f(associated)h(with)g(sock)o(et)g(operations,)g (or)g FJ(None)g FN(if)h(no)e(timeout)h(is)h(set.)46 b(This)208 4100 y(re\003ects)20 b(the)g(last)h(call)g(to)f FJ(setblocking\(\))f FN(or)h FJ(settimeout\(\))p FN(.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.3.)0 4247 y(Some)j(notes)f(on)h(sock)o(et)g(blocking)e(and)h (timeouts:)29 b(A)22 b(sock)o(et)g(object)g(can)f(be)h(in)g(one)g(of)g (three)f(modes:)28 b(blocking,)20 b(non-blocking,)0 4346 y(or)28 b(timeout.)48 b(Sock)o(ets)29 b(are)f(al)o(w)o(ays)h(created)e (in)i(blocking)d(mode.)48 b(In)28 b(blocking)f(mode,)i(operations)d (block)i(until)g(complete.)48 b(In)0 4446 y(non-blocking)15 b(mode,)j(operations)f(f)o(ail)i(\(with)f(an)h(error)f(that)g(is)i (unfortunately)c(system-dependent\))f(if)k(the)o(y)f(cannot)g(be)g (completed)0 4546 y(immediately)-5 b(.)23 b(In)d(timeout)f(mode,)g (operations)f(f)o(ail)j(if)f(the)o(y)f(cannot)g(be)h(completed)f (within)h(the)g(timeout)f(speci\002ed)h(for)f(the)h(sock)o(et.)0 4645 y(The)g FJ(setblocking\(\))e FN(method)h(is)i(simply)f(a)h (shorthand)d(for)h(certain)h FJ(settimeout\(\))e FN(calls.)0 4792 y(T)m(imeout)j(mode)f(internally)h(sets)i(the)e(sock)o(et)h(in)g (non-blocking)c(mode.)28 b(The)22 b(blocking)e(and)h(timeout)g(modes)g (are)g(shared)g(between)0 4892 y(\002le)j(descriptors)e(and)h(sock)o (et)h(objects)f(that)h(refer)e(to)i(the)f(same)h(netw)o(ork)e (endpoint.)33 b(A)24 b(consequence)d(of)j(this)g(is)g(that)g(\002le)g (objects)0 4991 y(returned)g(by)h(the)h FJ(makefile\(\))e FN(method)h(must)g(only)g(be)h(used)f(when)g(the)h(sock)o(et)g(is)g(in) g(blocking)e(mode;)k(in)d(timeout)g(or)h(non-)0 5091 y(blocking)18 b(mode)i(\002le)g(operations)f(that)h(cannot)f(be)i (completed)d(immediately)h(will)i(f)o(ail.)0 5238 y(Note)33 b(that)h(the)f FJ(connect\(\))f FN(operation)g(is)i(subject)f(to)g(the) h(timeout)e(setting,)37 b(and)32 b(in)i(general)e(it)i(is)g (recommended)d(to)i(call)0 5338 y FJ(settimeout\(\))19 b FN(before)f(calling)i FJ(connect\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v) n(el)g(netw)o(or)q(king)h(interf)n(ace)1989 b(583)p eop end %%Page: 584 596 TeXDict begin 584 595 bop 0 83 a FD(setsockopt)p FJ(\()p FK(le)o(vel,)18 b(optname)o(,)h(value)p FJ(\))208 183 y FN(Set)32 b(the)g(v)n(alue)f(of)g(the)h(gi)n(v)o(en)e(sock)o(et)i (option)e(\(see)i(the)i(U)t FH(N)t(I)t(X)g FN(manual)d(page)g FK(setsoc)n(k)o(opt)p FN(\(2\)\).)58 b(The)31 b(needed)g(symbolic)208 282 y(constants)21 b(are)h(de\002ned)f(in)i(the)f FJ(socket)f FN(module)g(\()p FJ(SO_)1913 297 y(*)1985 282 y FN(etc.\).)30 b(The)22 b(v)n(alue)f(can)h(be)g(an)g(inte)o(ger)f(or)h(a)h(string)f (representing)208 382 y(a)f(b)n(uf)n(fer)-5 b(.)26 b(In)21 b(the)g(latter)g(case)h(it)g(is)g(up)e(to)h(the)g(caller)g(to)g(ensure) g(that)g(the)g(string)f(contains)h(the)g(proper)e(bits)j(\(see)f(the)g (optional)208 482 y(b)n(uilt-in)e(module)g FJ(struct)h FN(for)f(a)i(w)o(ay)f(to)g(encode)f(C)i(structures)f(as)h(strings\).)0 628 y FD(shutdown)p FJ(\()p FK(how)p FJ(\))208 728 y FN(Shut)f(do)n(wn)f(one)h(or)h(both)e(halv)o(es)h(of)h(the)f (connection.)k(If)d FK(how)f FN(is)i FJ(SHUT_RD)p FN(,)d(further)g (recei)n(v)o(es)h(are)g(disallo)n(wed.)26 b(If)20 b FK(how)h FN(is)208 828 y FJ(SHUT_WR)p FN(,)e(further)f(sends)j(are)f(disallo)n (wed.)k(If)c FK(how)g FN(is)h FJ(SHUT_RDWR)p FN(,)e(further)g(sends)h (and)g(recei)n(v)o(es)f(are)h(disallo)n(wed.)0 975 y(Note)g(that)g (there)g(are)g(no)g(methods)f FJ(read\(\))h FN(or)g FJ(write\(\))p FN(;)f(use)i FJ(recv\(\))e FN(and)h FJ(send\(\))g FN(without)f FK(\003a)o(gs)h FN(ar)o(gument)e(instead.)0 1121 y(Sock)o(et)i(objects) g(also)g(ha)n(v)o(e)g(these)g(\(read-only\))e(attrib)n(utes)i(that)g (correspond)e(to)i(the)g(v)n(alues)g(gi)n(v)o(en)f(to)h(the)g FJ(socket)g FN(constructor)-5 b(.)0 1268 y FD(family)208 1368 y FN(The)19 b(sock)o(et)h(f)o(amily)-5 b(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1515 y FD(type)208 1614 y FN(The)g(sock)o(et)h(type.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 1761 y FD(proto)208 1861 y FN(The)g(sock)o(et)h(protocol.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 2146 y Fv(17.2.2)101 b(SSL)29 b(Objects)0 2349 y FN(SSL)21 b(objects)f(ha)n(v)o(e)f(the)i (follo)n(wing)d(methods.)0 2496 y FD(write)p FJ(\()p FK(s)p FJ(\))208 2595 y FN(Writes)j(the)f(string)g FK(s)h FN(to)f(the)g(on)g(the)g(object')-5 b(s)20 b(SSL)h(connection.)i(The)d (return)f(v)n(alue)g(is)i(the)g(number)d(of)i(bytes)g(written.)0 2742 y FD(read)p FJ(\()p FC([)p FK(n)12 b FC(])p FJ(\))208 2842 y FN(If)19 b FK(n)h FN(is)h(pro)o(vided,)c(read)j FK(n)g FN(bytes)g(from)e(the)i(SSL)h(connection,)d(otherwise)h(read)g (until)h(EOF)-7 b(.)20 b(The)g(return)f(v)n(alue)g(is)i(a)f(string)g (of)208 2941 y(the)g(bytes)g(read.)0 3088 y FD(server)p FJ(\(\))208 3188 y FN(Returns)j(a)g(string)g(describing)e(the)j(serv)o (er')-5 b(s)22 b(certi\002cate.)34 b(Useful)23 b(for)f(deb)n(ugging)f (purposes;)i(do)g(not)g(parse)g(the)g(content)f(of)208 3287 y(this)e(string)g(because)g(its)h(format)e(can')o(t)g(be)h(parsed) g(unambiguously)-5 b(.)0 3434 y FD(issuer)p FJ(\(\))208 3534 y FN(Returns)19 b(a)g(string)g(describing)e(the)j(issuer)f(of)g (the)g(serv)o(er')-5 b(s)18 b(certi\002cate.)25 b(Useful)19 b(for)f(deb)n(ugging)f(purposes;)h(do)h(not)g(parse)g(the)208 3634 y(content)g(of)h(this)g(string)g(because)g(its)h(format)e(can')o (t)g(be)h(parsed)g(unambiguously)-5 b(.)0 3918 y Fv(17.2.3)101 b(Example)0 4121 y FN(Here)20 b(are)g(four)f(minimal)g(e)o(xample)g (programs)f(using)i(the)g(TCP/IP)h(protocol:)d(a)j(serv)o(er)e(that)h (echoes)f(all)i(data)f(that)g(it)h(recei)n(v)o(es)e(back)0 4221 y(\(servicing)g(only)g(one)h(client\),)g(and)g(a)h(client)f(using) g(it.)26 b(Note)20 b(that)h(a)f(serv)o(er)g(must)g(perform)f(the)h (sequence)f FJ(socket\(\))p FN(,)g FJ(bind\(\))p FN(,)0 4321 y FJ(listen\(\))p FN(,)30 b FJ(accept\(\))e FN(\(possibly)g (repeating)g(the)h FJ(accept\(\))f FN(to)i(service)e(more)h(than)f(one) h(client\),)i(while)e(a)g(client)g(only)0 4420 y(needs)22 b(the)f(sequence)g FJ(socket\(\))p FN(,)g FJ(connect\(\))p FN(.)29 b(Also)23 b(note)e(that)h(the)g(serv)o(er)f(does)h(not)f FJ(send\(\))p FN(/)p FJ(recv\(\))g FN(on)g(the)h(sock)o(et)g(it)0 4520 y(is)f(listening)f(on)g(b)n(ut)g(on)g(the)g(ne)n(w)g(sock)o(et)g (returned)e(by)i FJ(accept\(\))p FN(.)0 4667 y(The)g(\002rst)h(tw)o(o)f (e)o(xamples)f(support)g(IPv4)h(only)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(584)1618 b(Chapter)24 b(17.)52 b(Inter)r(process) 22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 585 597 TeXDict begin 585 596 bop 236 83 a FA(#)45 b(Echo)f(server)g(program) 236 174 y(import)g(socket)236 357 y(HOST)g(=)h('')762 b(#)45 b(Symbolic)e(name)h(meaning)g(the)g(local)g(host)236 448 y(PORT)g(=)h(50007)627 b(#)45 b(Arbitrary)e(non-privileged)f(port) 236 540 y(s)j(=)g(socket.socket\(socket.AF_INET,)40 b (socket.SOCK_STREAM\))236 631 y(s.bind\(\(HOST,)j(PORT\)\))236 722 y(s.listen\(1\))236 814 y(conn,)h(addr)g(=)h(s.accept\(\))236 905 y(print)f('Connected)f(by',)i(addr)236 996 y(while)f(1:)416 1088 y(data)g(=)g(conn.recv\(1024\))416 1179 y(if)g(not)g(data:)g (break)416 1270 y(conn.send\(data\))236 1362 y(conn.close\(\))236 1641 y(#)h(Echo)f(client)g(program)236 1732 y(import)g(socket)236 1915 y(HOST)g(=)h('daring.cwi.nl')177 b(#)45 b(The)f(remote)g(host)236 2006 y(PORT)g(=)h(50007)627 b(#)45 b(The)f(same)g(port)g(as)h(used)f (by)g(the)h(server)236 2098 y(s)g(=)g(socket.socket\(socket.AF_INET,)40 b(socket.SOCK_STREAM\))236 2189 y(s.connect\(\(HOST,)i(PORT\)\))236 2280 y(s.send\('Hello,)h(world'\))236 2372 y(data)h(=)h(s.recv\(1024\)) 236 2463 y(s.close\(\))236 2554 y(print)f('Received',)f(repr\(data\))0 2841 y FN(The)27 b(ne)o(xt)f(tw)o(o)h(e)o(xamples)f(are)h(identical)f (to)h(the)g(abo)o(v)o(e)f(tw)o(o,)i(b)n(ut)f(support)f(both)g(IPv4)g (and)h(IPv6.)44 b(The)27 b(serv)o(er)f(side)h(will)h(listen)0 2940 y(to)23 b(the)h(\002rst)g(address)f(f)o(amily)f(a)n(v)n(ailable)h (\(it)h(should)e(listen)i(to)f(both)g(instead\).)33 b(On)24 b(most)f(of)g(IPv6-ready)e(systems,)j(IPv6)e(will)j(tak)o(e)0 3040 y(precedence)19 b(and)h(the)h(serv)o(er)f(may)g(not)h(accept)f (IPv4)g(traf)n(\002c.)27 b(The)20 b(client)h(side)g(will)h(try)e(to)h (connect)f(to)h(the)f(all)i(addresses)e(returned)0 3140 y(as)h(a)g(result)f(of)g(the)g(name)f(resolution,)g(and)h(sends)g(traf) n(\002c)g(to)g(the)g(\002rst)h(one)f(connected)e(successfully)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v)n(el)g(netw)o(or)q(king)h(interf)n(ace)1989 b(585)p eop end %%Page: 586 598 TeXDict begin 586 597 bop 236 83 a FA(#)45 b(Echo)f(server)g(program) 236 174 y(import)g(socket)236 266 y(import)g(sys)236 448 y(HOST)g(=)h('')762 b(#)45 b(Symbolic)e(name)h(meaning)g(the)g (local)g(host)236 540 y(PORT)g(=)h(50007)627 b(#)45 b(Arbitrary)e (non-privileged)f(port)236 631 y(s)j(=)g(None)236 722 y(for)g(res)f(in)g(socket.getaddrinfo\(HOST,)d(PORT,)j (socket.AF_UNSPEC,)e(socket.SOCK_STREAM,)g(0,)i(socket.AI_PASSIVE\):) 416 814 y(af,)g(socktype,)f(proto,)h(canonname,)f(sa)i(=)f(res)416 905 y(try:)236 996 y(s)h(=)g(socket.socket\(af,)d(socktype,)h(proto\)) 416 1088 y(except)g(socket.error,)g(msg:)236 1179 y(s)i(=)g(None)236 1270 y(continue)416 1362 y(try:)236 1453 y(s.bind\(sa\))236 1544 y(s.listen\(1\))416 1636 y(except)e(socket.error,)g(msg:)236 1727 y(s.close\(\))236 1818 y(s)i(=)g(None)236 1910 y(continue)416 2001 y(break)236 2092 y(if)g(s)f(is)h(None:)416 2183 y(print)f('could)f(not)i(open)f(socket')416 2275 y(sys.exit\(1\))236 2366 y(conn,)g(addr)g(=)h(s.accept\(\))236 2457 y(print)f('Connected)f (by',)i(addr)236 2549 y(while)f(1:)416 2640 y(data)g(=)g (conn.recv\(1024\))416 2731 y(if)g(not)g(data:)g(break)416 2823 y(conn.send\(data\))236 2914 y(conn.close\(\))p 0 5549 3901 4 v 0 5649 a FI(586)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 587 599 TeXDict begin 587 598 bop 236 83 a FA(#)45 b(Echo)f(client)g(program) 236 174 y(import)g(socket)236 266 y(import)g(sys)236 448 y(HOST)g(=)h('daring.cwi.nl')177 b(#)45 b(The)f(remote)g(host)236 540 y(PORT)g(=)h(50007)627 b(#)45 b(The)f(same)g(port)g(as)h(used)f(by) g(the)h(server)236 631 y(s)g(=)g(None)236 722 y(for)g(res)f(in)g (socket.getaddrinfo\(HOST,)d(PORT,)j(socket.AF_UNSPEC,)e (socket.SOCK_STREAM\):)416 814 y(af,)i(socktype,)f(proto,)h(canonname,) f(sa)i(=)f(res)416 905 y(try:)236 996 y(s)h(=)g(socket.socket\(af,)d (socktype,)h(proto\))416 1088 y(except)g(socket.error,)g(msg:)236 1179 y(s)i(=)g(None)236 1270 y(continue)416 1362 y(try:)236 1453 y(s.connect\(sa\))416 1544 y(except)e(socket.error,)g(msg:)236 1636 y(s.close\(\))236 1727 y(s)i(=)g(None)236 1818 y(continue)416 1910 y(break)236 2001 y(if)g(s)f(is)h(None:)416 2092 y(print)f('could)f(not)i(open)f(socket')416 2183 y(sys.exit\(1\))236 2275 y(s.send\('Hello,)f(world'\))236 2366 y(data)h(=)h(s.recv\(1024\)) 236 2457 y(s.close\(\))236 2549 y(print)f('Received',)f(repr\(data\))0 2835 y FN(This)27 b(e)o(xample)e(connects)g(to)i(an)f(SSL)h(serv)o(er)m (,)g(prints)f(the)h(serv)o(er)e(and)h(issuer')-5 b(s)27 b(distinguished)e(names,)j(sends)e(some)g(bytes,)i(and)0 2935 y(reads)20 b(part)g(of)g(the)g(response:)236 3082 y FA(import)44 b(socket)236 3264 y(s)h(=)g (socket.socket\(socket.AF_INET,)40 b(socket.SOCK_STREAM\))236 3356 y(s.connect\(\('www.verisign.com',)g(443\)\))236 3538 y(ssl_sock)k(=)g(socket.ssl\(s\))236 3721 y(print)g (repr\(ssl_sock.server\(\)\))236 3812 y(print)g (repr\(ssl_sock.issuer\(\)\))236 3995 y(#)h(Set)f(a)h(simple)f(HTTP)g (request)g(--)g(use)g(httplib)g(in)g(actual)g(code.)236 4086 y(ssl_sock.write\("""GET)e(/)i(HTTP/1.0\\r)236 4178 y(Host:)g(www.verisign.com\\r\\n\\r\\n"""\))236 4360 y(#)h(Read)f(a)h(chunk)f(of)g(data.)89 b(Will)44 b(not)h(necessarily) 236 4452 y(#)g(read)f(all)g(the)h(data)f(returned)f(by)i(the)f(server.) 236 4543 y(data)g(=)h(ssl_sock.read\(\))236 4726 y(#)g(Note)f(that)g (you)h(need)f(to)g(close)g(the)h(underlying)e(socket,)g(not)i(the)f (SSL)g(object.)236 4817 y(del)h(ssl_sock)236 4908 y(s.close\(\))0 5195 y FN(At)21 b(this)f(writing,)g(this)h(SSL)f(e)o(xample)f(prints)h (the)g(follo)n(wing)f(output)g(\(line)h(breaks)f(inserted)h(for)f (readability\):)p 0 5549 3901 4 v 0 5649 a FI(17.2.)52 b FJ(socket)22 b FI(\227)h(Lo)o(w-le)n(v)n(el)g(netw)o(or)q(king)h (interf)n(ace)1989 b(587)p eop end %%Page: 588 600 TeXDict begin 588 599 bop 236 83 a FA('/C=US/ST=California/L=Mountain) 40 b(View/)281 174 y(O=VeriSign,)j(Inc./OU=Production)f(Services/)281 266 y(OU=Terms)i(of)g(use)g(at)h(www.verisign.com/rpa)c(\(c\)00/)281 357 y(CN=www.verisign.com')236 448 y('/O=VeriSign)i(Trust)h (Network/OU=VeriSign,)d(Inc./)281 540 y(OU=VeriSign)i(International)g (Server)h(CA)g(-)h(Class)f(3/)281 631 y(OU=www.verisign.com/CPS)d (Incorp.by)i(Ref.)h(LIABILITY)g(LTD.\(c\)97)f(VeriSign')0 1141 y FE(17.3)121 b Fx(signal)32 b FE(\227)h(Set)g(handlers)i(f)l(or)f (asynchronous)i(e)l(v)m(ents)0 1374 y FN(This)21 b(module)e(pro)o (vides)g(mechanisms)h(to)h(use)g(signal)f(handlers)g(in)g(Python.)26 b(Some)20 b(general)g(rules)g(for)g(w)o(orking)f(with)i(signals)g(and)0 1473 y(their)f(handlers:)125 1703 y FM(\017)41 b FN(A)19 b(handler)f(for)g(a)i(particular)e(signal,)h(once)f(set,)i(remains)f (installed)g(until)g(it)g(is)h(e)o(xplicitly)f(reset)g(\(Python)f (emulates)g(the)i(BSD)208 1803 y(style)25 b(interf)o(ace)e(re)o (gardless)h(of)g(the)h(underlying)d(implementation\),)h(with)i(the)f(e) o(xception)f(of)i(the)f(handler)f(for)i FJ(SIGCHLD)p FN(,)208 1903 y(which)19 b(follo)n(ws)h(the)g(underlying)e (implementation.)125 2069 y FM(\017)41 b FN(There)23 b(is)j(no)e(w)o(ay)h(to)g(\223block\224)f(signals)g(temporarily)f(from) h(critical)h(sections)f(\(since)h(this)g(is)h(not)e(supported)f(by)h (all)k(U)t FH(N)t(I)t(X)208 2168 y FN(\003a)n(v)n(ors\).)125 2334 y FM(\017)41 b FN(Although)26 b(Python)h(signal)h(handlers)g(are)g (called)g(asynchronously)d(as)k(f)o(ar)f(as)h(the)g(Python)e(user)h(is) h(concerned,)f(the)o(y)g(can)208 2434 y(only)20 b(occur)g(between)h (the)g(\223atomic\224)g(instructions)f(of)h(the)g(Python)f(interpreter) -5 b(.)27 b(This)22 b(means)f(that)g(signals)h(arri)n(ving)d(during)208 2534 y(long)h(calculations)g(implemented)f(purely)h(in)h(C)h(\(such)f (as)h(re)o(gular)d(e)o(xpression)h(matches)g(on)h(lar)o(ge)f(bodies)h (of)f(te)o(xt\))h(may)g(be)208 2633 y(delayed)e(for)g(an)h(arbitrary)f (amount)g(of)h(time.)125 2799 y FM(\017)41 b FN(When)28 b(a)h(signal)g(arri)n(v)o(es)f(during)f(an)i(I/O)g(operation,)g(it)h (is)f(possible)g(that)g(the)g(I/O)g(operation)e(raises)i(an)g(e)o (xception)e(after)208 2899 y(the)21 b(signal)g(handler)f(returns.)28 b(This)22 b(is)g(dependent)d(on)i(the)h(underlying)e(U)t FH(N)t(I)t(X)25 b FN(system')-5 b(s)22 b(semantics)f(re)o(garding)e (interrupted)208 2999 y(system)h(calls.)125 3165 y FM(\017)41 b FN(Because)23 b(the)f(C)i(signal)f(handler)e(al)o(w)o(ays)i(returns,) f(it)i(mak)o(es)f(little)g(sense)g(to)g(catch)g(synchronous)d(errors)i (lik)o(e)h FJ(SIGFPE)f FN(or)208 3264 y FJ(SIGSEGV)p FN(.)125 3430 y FM(\017)41 b FN(Python)k(installs)j(a)f(small)h(number) d(of)h(signal)h(handlers)f(by)g(def)o(ault:)78 b FJ(SIGPIPE)46 b FN(is)i(ignored)d(\(so)i(write)g(errors)208 3530 y(on)40 b(pipes)i(and)e(sock)o(ets)i(can)f(be)g(reported)f(as)i(ordinary)d (Python)h(e)o(xceptions\))g(and)g FJ(SIGINT)h FN(is)h(translated)f (into)g(a)208 3629 y FJ(KeyboardInterrupt)17 b FN(e)o(xception.)23 b(All)e(of)f(these)g(can)g(be)g(o)o(v)o(erridden.)125 3796 y FM(\017)41 b FN(Some)24 b(care)g(must)g(be)g(tak)o(en)g(if)h (both)e(signals)i(and)f(threads)f(are)h(used)h(in)f(the)g(same)h (program.)35 b(The)24 b(fundamental)e(thing)h(to)208 3895 y(remember)g(in)j(using)f(signals)h(and)f(threads)g (simultaneously)f(is:)j(al)o(w)o(ays)f(perform)e FJ(signal\(\))g FN(operations)g(in)i(the)g(main)208 3995 y(thread)15 b(of)h(e)o(x)o(ecution.)21 b(An)o(y)16 b(thread)f(can)h(perform)e(an)j FJ(alarm\(\))p FN(,)f FJ(getsignal\(\))p FN(,)f(or)h FJ(pause\(\))p FN(;)h(only)e(the)i(main)f(thread)208 4094 y(can)k(set)h(a)g(ne)n(w)g(signal)f(handler)m(,)f(and)h(the)h (main)f(thread)g(will)h(be)g(the)f(only)g(one)g(to)h(recei)n(v)o(e)f (signals)g(\(this)h(is)h(enforced)c(by)j(the)208 4194 y(Python)i FJ(signal)h FN(module,)f(e)n(v)o(en)h(if)g(the)h(underlying) c(thread)j(implementation)e(supports)h(sending)g(signals)i(to)f(indi)n (vidual)208 4294 y(threads\).)f(This)e(means)f(that)g(signals)g(can')o (t)g(be)g(used)g(as)h(a)f(means)g(of)g(inter)n(-thread)e (communication.)k(Use)f(locks)f(instead.)0 4524 y(The)g(v)n(ariables)f (de\002ned)g(in)i(the)f FJ(signal)g FN(module)e(are:)0 4670 y FD(SIG_DFL)208 4770 y FN(This)24 b(is)h(one)e(of)h(tw)o(o)g (standard)f(signal)h(handling)e(options;)j(it)g(will)g(simply)f (perform)e(the)i(def)o(ault)f(function)f(for)i(the)g(signal.)208 4870 y(F)o(or)17 b(e)o(xample,)g(on)h(most)g(systems)h(the)f(def)o (ault)f(action)h(for)f FJ(SIGQUIT)h FN(is)h(to)f(dump)f(core)h(and)f(e) o(xit,)h(while)h(the)f(def)o(ault)f(action)208 4969 y(for)i FJ(SIGCLD)h FN(is)h(to)f(simply)g(ignore)f(it.)0 5116 y FD(SIG_IGN)208 5216 y FN(This)h(is)h(another)e(standard)g(signal)h (handler)m(,)e(which)i(will)h(simply)e(ignore)g(the)i(gi)n(v)o(en)d (signal.)p 0 5549 3901 4 v 0 5649 a FI(588)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q (king)p eop end %%Page: 589 601 TeXDict begin 589 600 bop 0 83 a FD(SIG)150 96 y(*)208 183 y FN(All)57 b(the)f(signal)g(numbers)f(are)h(de\002ned)f (symbolically)-5 b(.)132 b(F)o(or)56 b(e)o(xample,)63 b(the)57 b(hangup)d(signal)i(is)i(de\002ned)d(as)208 282 y FJ(signal.SIGHUP)p FN(;)46 b(the)j(v)n(ariable)e(names)i(are)f (identical)g(to)h(the)f(names)g(used)h(in)f(C)i(programs,)j(as)d(found) c(in)208 382 y FJ(<signal.h>)p FN(.)38 b(The)26 b(U)t FH(N)t(I)t(X)i FN(man)d(page)f(for)g(`)p FJ(signal\(\))p FN(')g(lists)i(the)f(e)o(xisting)f(signals)i(\(on)e(some)h(systems)g (this)h(is)f FK(sig-)208 482 y(nal)p FN(\(2\),)g(on)h(others)g(the)g (list)h(is)g(in)g FK(signal)p FN(\(7\)\).)41 b(Note)26 b(that)g(not)g(all)h(systems)f(de\002ne)g(the)g(same)h(set)f(of)g (signal)g(names;)j(only)208 581 y(those)20 b(names)f(de\002ned)h(by)f (the)i(system)f(are)g(de\002ned)f(by)h(this)h(module.)0 728 y FD(NSIG)208 828 y FN(One)f(more)f(than)h(the)g(number)e(of)i(the) g(highest)g(signal)g(number)-5 b(.)0 975 y(The)20 b FJ(signal)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f(functions:)0 1121 y FD(alarm)p FJ(\()p FK(time)p FJ(\))208 1221 y FN(If)24 b FK(time)g FN(is)i(non-zero,)c(this)j(function)e(requests)h (that)g(a)h FJ(SIGALRM)e FN(signal)h(be)g(sent)h(to)f(the)h(process)f (in)g FK(time)h FN(seconds.)36 b(An)o(y)208 1321 y(pre)n(viously)23 b(scheduled)h(alarm)g(is)j(canceled)d(\(only)g(one)h(alarm)g(can)g(be)g (scheduled)f(at)h(an)o(y)g(time\).)40 b(The)25 b(returned)e(v)n(alue)i (is)208 1420 y(then)17 b(the)i(number)d(of)i(seconds)g(before)f(an)o(y) g(pre)n(viously)f(set)j(alarm)f(w)o(as)h(to)g(ha)n(v)o(e)e(been)h(deli) n(v)o(ered.)k(If)c FK(time)h FN(is)g(zero,)f(no)g(alarm)208 1520 y(is)23 b(scheduled,)e(and)h(an)o(y)g(scheduled)f(alarm)h(is)i (canceled.)31 b(If)22 b(the)h(return)e(v)n(alue)h(is)h(zero,)g(no)f (alarm)g(is)h(currently)e(scheduled.)208 1620 y(\(See)f(the)i(U)t FH(N)t(I)t(X)h FN(man)d(page)f FK(alarm)p FN(\(2\).\))24 b(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)0 1766 y FD(getsignal)p FJ(\()p FK(signalnum)p FJ(\))208 1866 y FN(Return)19 b(the)i(current)e(signal)h(handler)f(for)h(the)g (signal)g FK(signalnum)p FN(.)k(The)c(returned)f(v)n(alue)g(may)h(be)g (a)h(callable)f(Python)f(object,)208 1966 y(or)25 b(one)g(of)h(the)g (special)g(v)n(alues)f FJ(signal.SIG_IGN)p FN(,)f FJ(signal.SIG_DFL)g FN(or)h FJ(None)p FN(.)42 b(Here,)27 b FJ(signal.SIG_IGN)208 2065 y FN(means)21 b(that)i(the)f(signal)g(w)o(as)h(pre)n(viously)d (ignored,)g FJ(signal.SIG_DFL)h FN(means)g(that)i(the)f(def)o(ault)f(w) o(ay)h(of)g(handling)f(the)208 2165 y(signal)f(w)o(as)h(pre)n(viously)d (in)i(use,)g(and)g FJ(None)g FN(means)g(that)g(the)g(pre)n(vious)f (signal)h(handler)f(w)o(as)i(not)f(installed)g(from)f(Python.)0 2312 y FD(pause)p FJ(\(\))208 2411 y FN(Cause)e(the)h(process)e(to)i (sleep)f(until)h(a)f(signal)g(is)i(recei)n(v)o(ed;)d(the)i(appropriate) d(handler)h(will)i(then)e(be)i(called.)23 b(Returns)18 b(nothing.)208 2511 y(Not)i(on)g(W)m(indo)n(ws.)k(\(See)c(the)i(U)t FH(N)t(I)t(X)i FN(man)19 b(page)h FK(signal)p FN(\(2\).\))0 2658 y FD(signal)p FJ(\()p FK(signalnum,)d(handler)r FJ(\))208 2758 y FN(Set)27 b(the)f(handler)f(for)h(signal)g FK(signalnum)f FN(to)i(the)f(function)f FK(handler)r FN(.)42 b FK(handler)28 b FN(can)e(be)g(a)h(callable)f(Python)g(object) f(taking)208 2857 y(tw)o(o)32 b(ar)o(guments)e(\(see)i(belo)n(w\),)i (or)e(one)f(of)h(the)g(special)h(v)n(alues)e FJ(signal.SIG_IGN)f FN(or)i FJ(signal.SIG_DFL)p FN(.)e(The)208 2957 y(pre)n(vious)25 b(signal)h(handler)f(will)j(be)e(returned)f(\(see)i(the)f(description)g (of)g FJ(getsignal\(\))f FN(abo)o(v)o(e\).)42 b(\(See)27 b(the)h(U)t FH(N)t(I)t(X)i FN(man)208 3056 y(page)19 b FK(signal)p FN(\(2\).\))208 3189 y(When)f(threads)f(are)i(enabled,)e (this)i(function)e(can)h(only)f(be)i(called)f(from)f(the)h(main)g (thread;)h(attempting)e(to)h(call)h(it)g(from)e(other)208 3289 y(threads)i(will)i(cause)f(a)h FJ(ValueError)e FN(e)o(xception)f (to)i(be)g(raised.)208 3422 y(The)26 b FK(handler)i FN(is)g(called)f (with)g(tw)o(o)h(ar)o(guments:)37 b(the)27 b(signal)g(number)e(and)i (the)g(current)f(stack)h(frame)f(\()p FJ(None)h FN(or)g(a)g(frame)208 3521 y(object;)18 b(for)h(a)g(description)f(of)g(frame)h(objects,)f (see)i(the)f(reference)e(manual)h(section)h(on)f(the)h(standard)f(type) h(hierarchy)d(or)j(see)208 3621 y(the)h(attrib)n(ute)g(descriptions)f (in)h(the)g FJ(inspect)g FN(module\).)0 3906 y Fv(17.3.1)101 b(Example)0 4109 y FN(Here)21 b(is)h(a)f(minimal)g(e)o(xample)e (program.)26 b(It)21 b(uses)h(the)f FJ(alarm\(\))f FN(function)f(to)j (limit)f(the)g(time)g(spent)g(w)o(aiting)g(to)g(open)f(a)i(\002le;)g (this)0 4208 y(is)i(useful)f(if)g(the)h(\002le)f(is)i(for)d(a)i(serial) f(de)n(vice)g(that)g(may)g(not)g(be)g(turned)f(on,)h(which)g(w)o(ould)f (normally)g(cause)h(the)g FJ(os.open\(\))f FN(to)0 4308 y(hang)g(inde\002nitely)-5 b(.)33 b(The)22 b(solution)h(is)h(to)f(set)h (a)g(5-second)d(alarm)i(before)f(opening)f(the)j(\002le;)h(if)f(the)f (operation)e(tak)o(es)j(too)f(long,)g(the)0 4408 y(alarm)d(signal)g (will)h(be)f(sent,)g(and)g(the)g(handler)f(raises)i(an)f(e)o(xception.) p 0 5549 3901 4 v 0 5649 a FI(17.3.)52 b FJ(signal)22 b FI(\227)h(Set)h(handlers)f(f)n(or)g(asynchronous)f(e)n(v)n(ents)1710 b(589)p eop end %%Page: 590 602 TeXDict begin 590 601 bop 236 174 a FA(import)44 b(signal,)g(os)236 357 y(def)h(handler\(signum,)d(frame\):)416 448 y(print)i('Signal)f (handler)h(called)g(with)g(signal',)f(signum)416 540 y(raise)h(IOError,)f("Couldn't)g(open)i(device!")236 722 y(#)g(Set)f(the)h(signal)e(handler)h(and)g(a)h(5-second)e(alarm)236 814 y(signal.signal\(signal.SIGALRM,)d(handler\))236 905 y(signal.alarm\(5\))236 1088 y(#)45 b(This)f(open\(\))g(may)g(hang) g(indefinitely)236 1179 y(fd)h(=)f(os.open\('/dev/ttyS0',)e (os.O_RDWR\))236 1362 y(signal.alarm\(0\))446 b(#)45 b(Disable)e(the)i(alarm)0 1872 y FE(17.4)121 b Fx(popen2)32 b FE(\227)h(Subprocesses)h(with)g(accessib)n(le)f(I/O)h(streams)0 2104 y FN(This)20 b(module)e(allo)n(ws)i(you)f(to)g(spa)o(wn)g (processes)h(and)f(connect)f(to)i(their)f(input/output/error)d(pipes)j (and)g(obtain)g(their)h(return)e(codes)0 2204 y(under)j(U)t FH(N)t(I)t(X)i FN(and)d(W)m(indo)n(ws.)0 2351 y(The)g FJ(subprocess)e FN(module)h(pro)o(vides)f(more)h(po)n(werful)f(f)o (acilities)j(for)e(spa)o(wning)g(ne)n(w)h(processes)f(and)h(retrie)n (ving)e(their)h(results.)0 2451 y(Using)h(the)g FJ(subprocess)f FN(module)g(is)i(preferable)d(to)j(using)e(the)i FJ(popen2)e FN(module.)0 2597 y(The)24 b(primary)f(interf)o(ace)g(of)n(fered)f(by)i (this)h(module)e(is)i(a)g(trio)f(of)g(f)o(actory)f(functions.)36 b(F)o(or)24 b(each)f(of)h(these,)i(if)e FK(b)n(ufsize)h FN(is)g(speci\002ed,)0 2697 y(it)e(speci\002es)g(the)f(b)n(uf)n(fer)f (size)i(for)f(the)g(I/O)h(pipes.)31 b FK(mode)p FN(,)22 b(if)g(pro)o(vided,)e(should)i(be)g(the)g(string)g FJ('b')h FN(or)f FJ('t')p FN(;)h(on)f(W)m(indo)n(ws)g(this)h(is)0 2797 y(needed)e(to)i(determine)f(whether)f(the)i(\002le)g(objects)g (should)f(be)g(opened)f(in)i(binary)e(or)i(te)o(xt)f(mode.)32 b(The)22 b(def)o(ault)g(v)n(alue)g(for)h FK(mode)f FN(is)0 2896 y FJ('t')p FN(.)0 3043 y(On)31 b(U)t FH(N)t(I)t(X)r FN(,)h FK(cmd)f FN(may)d(be)h(a)g(sequence,)h(in)f(which)g(case)g(ar)o (guments)e(will)i(be)g(passed)g(directly)f(to)h(the)g(program)e (without)h(shell)0 3143 y(interv)o(ention)18 b(\(as)i(with)h FJ(os.spawnv\(\))p FN(\).)i(If)d FK(cmd)i FN(is)f(a)g(string)f(it)h (will)g(be)f(passed)g(to)g(the)g(shell)h(\(as)f(with)h FJ(os.system\(\))p FN(\).)0 3290 y(The)27 b(only)f(w)o(ay)h(to)g (retrie)n(v)o(e)e(the)i(return)f(codes)g(for)h(the)f(child)h(processes) f(is)i(by)f(using)f(the)h FJ(poll\(\))f FN(or)h FJ(wait\(\))f FN(methods)g(on)0 3389 y(the)f FJ(Popen3)g FN(and)g FJ(Popen4)f FN(classes;)29 b(these)d(are)f(only)f(a)n(v)n(ailable)h(on)i(U)t FH(N)t(I)t(X)r FN(.)41 b(This)26 b(information)d(is)j(not)f(a)n(v)n (ailable)f(when)h(using)0 3489 y(the)20 b FJ(popen2\(\))p FN(,)g FJ(popen3\(\))p FN(,)f(and)h FJ(popen4\(\))f FN(functions,)g(or) h(the)g(equi)n(v)n(alent)f(functions)g(in)h(the)h FJ(os)f FN(module.)k(\(Note)c(that)h(the)0 3589 y(tuples)f(returned)e(by)i(the) g FJ(os)h FN(module')-5 b(s)19 b(functions)f(are)i(in)h(a)f(dif)n (ferent)f(order)g(from)g(the)h(ones)g(returned)e(by)i(the)g FJ(popen2)g FN(module.\))0 3735 y FD(popen2)p FJ(\()p FK(cmd)r FC([)p FK(,)f(b)n(ufsize)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 3835 y FN(Ex)o(ecutes)19 b FK(cmd)j FN(as)f(a)g(sub-process.)i(Returns)d(the)g(\002le)h(objects)f FJ(\()p FK(c)o(hild)p 2279 3835 25 4 v 29 w(stdout)q FJ(,)49 b FK(c)o(hild)p 2778 3835 V 28 w(stdin)p FJ(\))p FN(.)0 3982 y FD(popen3)p FJ(\()p FK(cmd)r FC([)p FK(,)19 b(b)n(ufsize)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 4082 y FN(Ex)o(ecutes)19 b FK(cmd)j FN(as)f(a)g(sub-process.)i(Returns) d(the)g(\002le)h(objects)f FJ(\()p FK(c)o(hild)p 2279 4082 V 29 w(stdout)q FJ(,)49 b FK(c)o(hild)p 2778 4082 V 28 w(stdin)p FJ(,)g FK(c)o(hild)p 3233 4082 V 29 w(stderr)r FJ(\))p FN(.)0 4228 y FD(popen4)p FJ(\()p FK(cmd)r FC([)p FK(,)19 b(b)n(ufsize)p FC([)p FK(,)h(mode)12 b FC(])g(])p FJ(\))208 4328 y FN(Ex)o(ecutes)29 b FK(cmd)k FN(as)f(a)f(sub-process.) 56 b(Returns)30 b(the)h(\002le)h(objects)e FJ(\()p FK(c)o(hild)p 2396 4328 V 29 w(stdout)p 2629 4328 V 29 w(and)p 2784 4328 V 28 w(stderr)r FJ(,)50 b FK(c)o(hild)p 3278 4328 V 29 w(stdin)p FJ(\))p FN(.)114 b(Ne)n(w)31 b(in)208 4428 y(v)o(ersion)18 b(2.0.)0 4575 y(On)26 b(U)t FH(N)t(I)t(X)r FN(,)g(a)f(class)g(de\002ning)e(the)h(objects)g(returned)f(by)g(the)i (f)o(actory)e(functions)g(is)i(also)f(a)n(v)n(ailable.)37 b(These)24 b(are)g(not)g(used)g(for)g(the)0 4674 y(W)m(indo)n(ws)c (implementation,)d(and)j(are)g(not)g(a)n(v)n(ailable)g(on)f(that)i (platform.)0 4821 y FL(class)g FD(Popen3)p FJ(\()p FK(cmd)r FC([)p FK(,)d(captur)m(estderr)r FC([)p FK(,)h(b)n(ufsize)12 b FC(])g(])p FJ(\))208 4921 y FN(This)32 b(class)i(represents)e(a)h (child)f(process.)61 b(Normally)-5 b(,)34 b FJ(Popen3)e FN(instances)h(are)f(created)g(using)g(the)g FJ(popen2\(\))g FN(and)208 5020 y FJ(popen3\(\))19 b FN(f)o(actory)g(functions)g (described)g(abo)o(v)o(e.)208 5153 y(If)j(not)h(using)f(one)h(of)f(the) h(helper)f(functions)g(to)h(create)f FJ(Popen3)h FN(objects,)g(the)g (parameter)e FK(cmd)k FN(is)f(the)f(shell)g(command)e(to)208 5253 y(e)o(x)o(ecute)g(in)h(a)h(sub-process.)30 b(The)22 b FK(captur)m(estderr)i FN(\003ag,)f(if)g(true,)f(speci\002es)h(that)f (the)h(object)f(should)f(capture)g(standard)h(error)208 5352 y(output)e(of)h(the)h(child)f(process.)29 b(The)22 b(def)o(ault)f(is)h(f)o(alse.)30 b(If)21 b(the)h FK(b)n(ufsize)g FN(parameter)f(is)h(speci\002ed,)g(it)g(speci\002es)g(the)g(size)g(of)g (the)p 0 5549 3901 4 v 0 5649 a FI(590)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q (king)p eop end %%Page: 591 603 TeXDict begin 591 602 bop 208 83 a FN(I/O)20 b(b)n(uf)n(fers)f(to/from) g(the)h(child)g(process.)0 230 y FL(class)h FD(Popen4)p FJ(\()p FK(cmd)r FC([)p FK(,)d(b)n(ufsize)12 b FC(])p FJ(\))208 330 y FN(Similar)23 b(to)g FJ(Popen3)p FN(,)h(b)n(ut)f(al)o (w)o(ays)h(captures)e(standard)g(error)h(into)g(the)g(same)g(\002le)h (object)f(as)h(standard)e(output.)33 b(These)24 b(are)208 429 y(typically)19 b(created)g(using)h FJ(popen4\(\))p FN(.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 714 y Fv(17.4.1)101 b(P)-5 b(open3)30 b(and)f(P)-5 b(open4)30 b(Objects)0 917 y FN(Instances)20 b(of)g(the)g FJ(Popen3)f FN(and)h FJ(Popen4)g FN(classes)h(ha)n(v)o(e)f(the)g(follo)n(wing)e (methods:)0 1064 y FD(poll)p FJ(\(\))208 1163 y FN(Returns)i FJ(-1)g FN(if)g(child)g(process)g(hasn')o(t)f(completed)g(yet,)h(or)g (its)h(status)g(code)e(\(see)i FJ(wait\(\))p FN(\))e(otherwise.)0 1310 y FD(wait)p FJ(\(\))208 1410 y FN(W)-7 b(aits)30 b(for)f(and)g(returns)f(the)h(status)h(code)f(of)g(the)g(child)g (process.)51 b(The)29 b(status)h(code)e(encodes)h(both)f(the)h(return)f (code)h(of)208 1510 y(the)g(process)h(and)f(information)e(about)i (whether)g(it)i(e)o(xited)e(using)g(the)h FJ(exit\(\))f FN(system)h(call)g(or)g(died)f(due)h(to)g(a)g(signal.)208 1609 y(Functions)19 b(to)h(help)f(interpret)g(the)h(status)h(code)e (are)h(de\002ned)f(in)h(the)h FJ(os)f FN(module;)f(see)h(section)g (14.1.5)e(for)h(the)i FJ(W)p FK(*)p FJ(\(\))e FN(f)o(amily)208 1709 y(of)g(functions.)0 1856 y(The)h(follo)n(wing)e(attrib)n(utes)j (are)f(also)g(a)n(v)n(ailable:)0 2003 y FD(fromchild)208 2102 y FN(A)28 b(\002le)h(object)f(that)h(pro)o(vides)d(output)h(from)h (the)g(child)g(process.)49 b(F)o(or)28 b FJ(Popen4)g FN(instances,)i(this)f(will)g(pro)o(vide)d(both)i(the)208 2202 y(standard)19 b(output)g(and)g(standard)g(error)g(streams.)0 2349 y FD(tochild)208 2448 y FN(A)h(\002le)h(object)f(that)g(pro)o (vides)e(input)i(to)g(the)g(child)g(process.)0 2595 y FD(childerr)208 2695 y FN(A)28 b(\002le)h(object)f(that)h(pro)o(vides)d (error)i(output)f(from)g(the)i(child)f(process,)h(if)g FK(captur)m(estderr)h FN(w)o(as)f(true)f(for)g(the)g(constructor)m(,) 208 2794 y(otherwise)19 b FJ(None)p FN(.)25 b(This)20 b(will)h(al)o(w)o(ays)g(be)f FJ(None)g FN(for)f FJ(Popen4)h FN(instances.)0 2941 y FD(pid)208 3041 y FN(The)f(process)h(ID)g(of)g (the)h(child)e(process.)0 3326 y Fv(17.4.2)101 b(Flo)o(w)27 b(Control)i(Issues)0 3529 y FN(An)o(y)21 b(time)i(you)e(are)h(w)o (orking)f(with)h(an)o(y)f(form)g(of)h(inter)n(-process)f (communication,)e(control)i(\003o)n(w)h(needs)g(to)g(be)h(carefully)d (thought)0 3628 y(out.)25 b(This)20 b(remains)g(the)g(case)g(with)h (the)f(\002le)h(objects)f(pro)o(vided)d(by)j(this)h(module)e(\(or)g (the)i FJ(os)f FN(module)f(equi)n(v)n(alents\).)0 3775 y(When)k(reading)f(output)g(from)g(a)i(child)f(process)g(that)g(writes) h(a)g(lot)f(of)g(data)h(to)f(standard)f(error)g(while)i(the)f(parent)f (is)j(reading)d(from)0 3875 y(the)f(child')-5 b(s)22 b(standard)e(output,)h(a)g(deadlock)f(can)h(occur)-5 b(.)29 b(A)22 b(similar)f(situation)g(can)h(occur)e(with)i(other)e (combinations)g(of)h(reads)g(and)0 3974 y(writes.)k(The)19 b(essential)g(f)o(actors)g(are)g(that)g(more)f(than)h FJ(_PC_PIPE_BUF)e FN(bytes)i(are)g(being)f(written)h(by)g(one)f (process)h(in)g(a)g(blocking)0 4074 y(f)o(ashion,)g(while)h(the)h (other)e(process)h(is)h(reading)d(from)i(the)g(other)f(process,)h(also) g(in)h(a)f(blocking)e(f)o(ashion.)0 4221 y(There)h(are)h(se)n(v)o(eral) g(w)o(ays)h(to)f(deal)g(with)g(this)h(situation.)0 4368 y(The)f(simplest)g(application)f(change,)g(in)h(man)o(y)f(cases,)i (will)g(be)f(to)g(follo)n(w)g(this)g(model)g(in)g(the)g(parent)f (process:)236 4606 y FA(import)44 b(popen2)236 4789 y(r,)h(w,)f(e)h(=)g (popen2.popen3\('python)c(slave.py'\))236 4880 y(e.readlines\(\))236 4971 y(r.readlines\(\))236 5063 y(r.close\(\))236 5154 y(e.close\(\))236 5245 y(w.close\(\))p 0 5549 3901 4 v 0 5649 a FI(17.4.)52 b FJ(popen2)22 b FI(\227)h(Subprocesses)f(with)i (accessib)n(le)f(I/O)g(streams)1539 b(591)p eop end %%Page: 592 604 TeXDict begin 592 603 bop 0 83 a FN(with)20 b(code)g(lik)o(e)g(this)h (in)f(the)h(child:)236 321 y FA(import)44 b(os)236 413 y(import)g(sys)236 595 y(#)h(note)f(that)g(each)g(of)h(these)f(print)g (statements)236 687 y(#)h(writes)f(a)g(single)g(long)g(string)236 869 y(print)g(>>sys.stderr,)f(400)1312 882 y(*)1402 869 y('this)h(is)g(a)h(test\\n')236 960 y (os.close\(sys.stderr.fileno\(\)\))236 1052 y(print)f(>>sys.stdout,)f (400)1312 1065 y(*)1402 1052 y('this)h(is)g(another)g(test\\n')0 1338 y FN(In)27 b(particular)m(,)f(note)g(that)h FJ(sys.stderr)f FN(must)h(be)f(closed)h(after)f(writing)h(all)g(data,)h(or)f FJ(readlines\(\))e FN(w)o(on')o(t)h(return.)43 b(Also)0 1438 y(note)27 b(that)h FJ(os.close\(\))e FN(must)h(be)h(used,)g(as)h FJ(sys.stderr.close\(\))24 b FN(w)o(on')o(t)j(close)g FJ(stderr)g FN(\(otherwise)g(assigning)f(to)0 1538 y FJ(sys.stderr)19 b FN(will)i(silently)f(close)g(it,)h(so)g(no)e (further)g(errors)g(can)h(be)h(printed\).)0 1684 y(Applications)j (which)g(need)g(to)h(support)f(a)h(more)f(general)g(approach)e(should)i (inte)o(grate)g(I/O)h(o)o(v)o(er)e(pipes)i(with)g(their)f FJ(select\(\))0 1784 y FN(loops,)33 b(or)e(use)g(separate)g(threads)f (to)h(read)g(each)g(of)g(the)g(indi)n(vidual)e(\002les)j(pro)o(vided)d (by)h(whiche)n(v)o(er)f FJ(popen)3342 1799 y(*)3392 1784 y(\(\))h FN(function)g(or)0 1884 y FJ(Popen)250 1899 y(*)320 1884 y FN(class)21 b(w)o(as)g(used.)0 2031 y FL(See)g(Also:)0 2177 y FN(Module)e FJ(subprocess)g FN(\(section)h (17.1\):)208 2277 y(Module)f(for)g(spa)o(wning)g(and)h(managing)e (subprocesses.)0 2605 y FE(17.5)121 b Fx(asyncore)31 b FE(\227)i(Asynchronous)i(soc)n(k)n(et)e(handler)0 2837 y FN(This)20 b(module)f(pro)o(vides)g(the)h(basic)g(infrastructure)e (for)i(writing)f(asynchronous)f(sock)o(et)i(service)g(clients)g(and)g (serv)o(ers.)0 2984 y(There)h(are)g(only)g(tw)o(o)h(w)o(ays)g(to)g(ha)n (v)o(e)e(a)i(program)e(on)h(a)h(single)g(processor)e(do)h(\223more)g (than)g(one)g(thing)g(at)h(a)g(time.)-6 b(\224)29 b(Multi-threaded)0 3084 y(programming)17 b(is)k(the)f(simplest)h(and)e(most)h(popular)f(w) o(ay)h(to)g(do)g(it,)h(b)n(ut)f(there)g(is)h(another)d(v)o(ery)h(dif)n (ferent)g(technique,)f(that)i(lets)h(you)0 3183 y(ha)n(v)o(e)26 b(nearly)f(all)h(the)h(adv)n(antages)d(of)i(multi-threading,)e(without) i(actually)f(using)h(multiple)f(threads.)42 b(It')-5 b(s)27 b(really)f(only)f(practical)0 3283 y(if)i(your)f(program)f(is)j (lar)o(gely)d(I/O)i(bound.)44 b(If)26 b(your)g(program)f(is)j (processor)d(bound,)i(then)f(pre-empti)n(v)o(e)f(scheduled)g(threads)i (are)0 3383 y(probably)18 b(what)i(you)f(really)h(need.)k(Netw)o(ork)c (serv)o(ers)f(are)i(rarely)e(processor)g(bound,)f(ho)n(we)n(v)o(er)-5 b(.)0 3530 y(If)16 b(your)f(operating)f(system)i(supports)f(the)i FJ(select\(\))e FN(system)h(call)h(in)f(its)h(I/O)f(library)f(\(and)h (nearly)f(all)i(do\),)e(then)h(you)f(can)h(use)h(it)f(to)0 3629 y(juggle)h(multiple)f(communication)f(channels)h(at)i(once;)g (doing)e(other)h(w)o(ork)g(while)g(your)f(I/O)i(is)h(taking)d(place)h (in)h(the)f(\223background.)-6 b(\224)0 3729 y(Although)21 b(this)j(strate)o(gy)e(can)h(seem)g(strange)g(and)f(comple)o(x,)g (especially)h(at)g(\002rst,)h(it)g(is)g(in)f(man)o(y)f(w)o(ays)i (easier)f(to)g(understand)e(and)0 3828 y(control)26 b(than)h (multi-threaded)e(programming.)43 b(The)27 b FJ(asyncore)g FN(module)f(solv)o(es)h(man)o(y)f(of)i(the)f(dif)n(\002cult)g(problems) f(for)h(you,)0 3928 y(making)21 b(the)h(task)g(of)g(b)n(uilding)e (sophisticated)h(high-performance)d(netw)o(ork)i(serv)o(ers)i(and)f (clients)i(a)f(snap.)30 b(F)o(or)22 b(\223con)m(v)o(ersational\224)0 4028 y(applications)d(and)h(protocols)e(the)j(companion)c FJ(asynchat)j FN(module)e(is)k(in)m(v)n(aluable.)0 4175 y(The)61 b(basic)h(idea)g(behind)f(both)g(modules)f(is)j(to)f(create)g (one)f(or)g(more)g(netw)o(ork)g FK(c)o(hannels)p FN(,)70 b(instances)62 b(of)g(class)0 4274 y FJ(asyncore.dispatcher)16 b FN(and)j FJ(asynchat.async_chat)p FN(.)j(Creating)d(the)g(channels)g (adds)g(them)g(to)h(a)f(global)g(map,)g(used)0 4374 y(by)h(the)g FJ(loop\(\))g FN(function)e(if)j(you)e(do)h(not)f(pro)o(vide)g(it)i (with)f(your)f(o)n(wn)g FK(map)p FN(.)0 4521 y(Once)27 b(the)f(initial)i(channel\(s\))d(is\(are\))h(created,)i(calling)e(the)h FJ(loop\(\))f FN(function)f(acti)n(v)n(ates)i(channel)f(service,)h (which)g(continues)0 4620 y(until)20 b(the)g(last)h(channel)e (\(including)f(an)o(y)i(that)g(ha)n(v)o(e)g(been)f(added)g(to)h(the)h (map)e(during)g(asynchronous)e(service\))j(is)h(closed.)0 4767 y FD(loop)p FJ(\()p FC([)p FK(timeout)q FC([)p FK(,)e(use)p 737 4767 25 4 v 29 w(poll)p FC([)p FK(,)h(map)p FC([)p FK(,count)13 b FC(])f(])g(])g(])p FJ(\))208 4867 y FN(Enter)19 b(a)h(polling)f(loop)g(that)h(terminates)g(after)f(count)g(passes)i(or) f(all)g(open)f(channels)g(ha)n(v)o(e)g(been)h(closed.)k(All)d(ar)o (guments)d(are)208 4966 y(optional.)23 b(The)c FK(\()p FN(count\))f(parameter)h(def)o(aults)g(to)h(None,)f(resulting)g(in)g (the)h(loop)f(terminating)f(only)h(when)g(all)h(channels)f(ha)n(v)o(e) 208 5066 y(been)g(closed.)25 b(The)19 b FK(timeout)j FN(ar)o(gument)c(sets)j(the)f(timeout)f(parameter)g(for)h(the)g (appropriate)e FJ(select\(\))h FN(or)h FJ(poll\(\))f FN(call,)208 5166 y(measured)i(in)i(seconds;)g(the)f(def)o(ault)g(is)i (30)e(seconds.)31 b(The)22 b FK(use)p 2093 5166 V 30 w(poll)g FN(parameter)m(,)f(if)i(true,)g(indicates)f(that)h FJ(poll\(\))f FN(should)208 5265 y(be)e(used)g(in)g(preference)e(to)i FJ(select\(\))g FN(\(the)f(def)o(ault)h(is)h FJ(False)p FN(\).)208 5398 y(The)15 b FK(map)g FN(parameter)f(is)i(a)g(dictionary) e(whose)h(items)h(are)f(the)g(channels)g(to)h(w)o(atch.)23 b(As)16 b(channels)f(are)g(closed)g(the)o(y)g(are)g(deleted)p 0 5549 3901 4 v 0 5649 a FI(592)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 593 605 TeXDict begin 593 604 bop 208 83 a FN(from)22 b(their)i(map.)36 b(If)24 b FK(map)f FN(is)i(omitted,)f(a)h(global)e(map)g(is)i(used.)36 b(Channels)24 b(\(instances)f(of)h FJ(asyncore.dispatcher)p FN(,)208 183 y FJ(asynchat.async_chat)17 b FN(and)i(subclasses)i (thereof\))e(can)h(freely)f(be)h(mix)o(ed)f(in)h(the)h(map.)0 330 y FL(class)g FD(dispatcher)p FJ(\(\))208 429 y FN(The)j FJ(dispatcher)g FN(class)i(is)g(a)f(thin)g(wrapper)e(around)h(a)h(lo)n (w-le)n(v)o(el)f(sock)o(et)g(object.)39 b(T)-7 b(o)25 b(mak)o(e)g(it)h(more)e(useful,)h(it)h(has)f(a)208 529 y(fe)n(w)20 b(methods)g(for)h(e)n(v)o(ent-handling)c(which)k(are)f (called)h(from)f(the)h(asynchronous)d(loop.)27 b(Otherwise,)21 b(it)g(can)g(be)g(treated)f(as)i(a)208 628 y(normal)d(non-blocking)d (sock)o(et)k(object.)208 761 y(The)25 b(\002ring)h(of)g(lo)n(w-le)n(v)o (el)f(e)n(v)o(ents)g(at)i(certain)f(times)g(or)g(in)h(certain)e (connection)f(states)k(tells)f(the)f(asynchronous)d(loop)i(that)208 861 y(certain)e(higher)n(-le)n(v)o(el)e(e)n(v)o(ents)i(ha)n(v)o(e)g (tak)o(en)g(place.)35 b(F)o(or)23 b(e)o(xample,)g(if)h(we)g(ha)n(v)o(e) f(ask)o(ed)g(for)g(a)h(sock)o(et)f(to)h(connect)e(to)i(another)208 960 y(host,)h(we)g(kno)n(w)e(that)i(the)g(connection)d(has)j(been)f (made)g(when)g(the)g(sock)o(et)h(becomes)e(writable)i(for)f(the)g (\002rst)i(time)e(\(at)h(this)208 1060 y(point)19 b(you)g(kno)n(w)g (that)i(you)e(may)h(write)g(to)g(it)h(with)g(the)f(e)o(xpectation)e(of) i(success\).)25 b(The)20 b(implied)g(higher)n(-le)n(v)o(el)d(e)n(v)o (ents)j(are:)841 1189 y FL(Ev)o(ent)p 1686 1219 4 100 v 690 w(Description)p 791 1223 2525 4 v 841 1292 a FJ (handle_connect\(\))p 1686 1322 4 100 v 97 w FN(Implied)f(by)h(the)g (\002rst)h(write)f(e)n(v)o(ent)841 1392 y FJ(handle_close\(\))p 1686 1422 V 197 w FN(Implied)f(by)h(a)g(read)g(e)n(v)o(ent)f(with)i(no) e(data)h(a)n(v)n(ailable)841 1492 y FJ(handle_accept\(\))p 1686 1521 V 147 w FN(Implied)f(by)h(a)g(read)g(e)n(v)o(ent)f(on)h(a)h (listening)e(sock)o(et)208 1620 y(During)h(asynchronous)f(processing,)h (each)i(mapped)e(channel')-5 b(s)21 b FJ(readable\(\))f FN(and)h FJ(writable\(\))g FN(methods)f(are)i(used)208 1719 y(to)f(determine)f(whether)h(the)g(channel')-5 b(s)21 b(sock)o(et)g(should)g(be)g(added)g(to)g(the)h(list)h(of)e(channels)g FJ(select\(\))p FN(ed)e(or)j FJ(poll\(\))p FN(ed)208 1819 y(for)d(read)h(and)f(write)i(e)n(v)o(ents.)0 1966 y(Thus,)e(the)h(set)h(of)e(channel)g(e)n(v)o(ents)g(is)i(lar)o(ger)d (than)h(the)h(basic)g(sock)o(et)g(e)n(v)o(ents.)k(The)19 b(full)h(set)h(of)e(methods)g(that)h(can)f(be)h(o)o(v)o(erridden)c(in)0 2065 y(your)j(subclass)h(follo)n(ws:)0 2212 y FD(handle_read)p FJ(\(\))208 2312 y FN(Called)g(when)g(the)g(asynchronous)d(loop)j (detects)g(that)g(a)h FJ(read\(\))e FN(call)i(on)f(the)g(channel')-5 b(s)19 b(sock)o(et)h(will)h(succeed.)0 2459 y FD(handle_write)p FJ(\(\))208 2558 y FN(Called)f(when)g(the)g(asynchronous)e(loop)h (detects)i(that)f(a)h(writable)f(sock)o(et)g(can)h(be)f(written.)25 b(Often)20 b(this)h(method)e(will)i(imple-)208 2658 y(ment)e(the)i (necessary)e(b)n(uf)n(fering)f(for)i(performance.)i(F)o(or)d(e)o (xample:)444 2882 y FA(def)44 b(handle_write\(self\):)623 2973 y(sent)g(=)h(self.send\(self.buffer\))623 3065 y(self.buffer)e(=)i (self.buffer[sent:])0 3264 y FD(handle_expt)p FJ(\(\))208 3364 y FN(Called)19 b(when)f(there)h(is)h(out)f(of)g(band)f(\(OOB\))h (data)g(for)g(a)g(sock)o(et)g(connection.)j(This)e(will)g(almost)f(ne)n (v)o(er)e(happen,)h(as)i(OOB)g(is)208 3463 y(tenuously)e(supported)g (and)i(rarely)f(used.)0 3610 y FD(handle_connect)p FJ(\(\))208 3710 y FN(Called)f(when)f(the)h(acti)n(v)o(e)f(opener')-5 b(s)17 b(sock)o(et)h(actually)f(mak)o(es)h(a)g(connection.)k(Might)c (send)f(a)i(\223welcome\224)e(banner)m(,)f(or)h(initiate)208 3809 y(a)j(protocol)f(ne)o(gotiation)f(with)i(the)g(remote)g(endpoint,) e(for)h(e)o(xample.)0 3956 y FD(handle_close)p FJ(\(\))208 4056 y FN(Called)h(when)g(the)g(sock)o(et)g(is)h(closed.)0 4203 y FD(handle_error)p FJ(\(\))208 4302 y FN(Called)c(when)g(an)g(e)o (xception)f(is)i(raised)f(and)g(not)g(otherwise)f(handled.)23 b(The)17 b(def)o(ault)f(v)o(ersion)g(prints)h(a)h(condensed)d (traceback.)0 4449 y FD(handle_accept)p FJ(\(\))208 4549 y FN(Called)i(on)f(listening)g(channels)g(\(passi)n(v)o(e)g(openers\))f (when)h(a)h(connection)e(can)h(be)h(established)f(with)h(a)g(ne)n(w)g (remote)e(endpoint)208 4648 y(that)20 b(has)g(issued)h(a)f FJ(connect\(\))f FN(call)i(for)e(the)i(local)f(endpoint.)0 4795 y FD(readable)p FJ(\(\))208 4895 y FN(Called)g(each)g(time)g (around)e(the)i(asynchronous)d(loop)i(to)h(determine)f(whether)g(a)i (channel')-5 b(s)19 b(sock)o(et)h(should)f(be)h(added)e(to)j(the)208 4995 y(list)27 b(on)f(which)g(read)g(e)n(v)o(ents)g(can)g(occur)-5 b(.)43 b(The)26 b(def)o(ault)g(method)f(simply)h(returns)g FJ(True)p FN(,)h(indicating)e(that)i(by)f(def)o(ault,)h(all)208 5094 y(channels)19 b(will)i(be)f(interested)f(in)i(read)e(e)n(v)o (ents.)0 5241 y FD(writable)p FJ(\(\))208 5341 y FN(Called)h(each)g (time)g(around)e(the)i(asynchronous)d(loop)i(to)h(determine)f(whether)g (a)i(channel')-5 b(s)19 b(sock)o(et)h(should)f(be)h(added)e(to)j(the)p 0 5549 3901 4 v 0 5649 a FI(17.5.)52 b FJ(asyncore)22 b FI(\227)h(Asynchronous)f(soc)n(k)n(et)h(handler)1913 b(593)p eop end %%Page: 594 606 TeXDict begin 594 605 bop 208 83 a FN(list)26 b(on)e(which)h(write)g(e) n(v)o(ents)f(can)h(occur)-5 b(.)39 b(The)25 b(def)o(ault)f(method)g (simply)g(returns)g FJ(True)p FN(,)i(indicating)e(that)h(by)g(def)o (ault,)g(all)208 183 y(channels)19 b(will)i(be)f(interested)f(in)i (write)f(e)n(v)o(ents.)0 330 y(In)g(addition,)g(each)g(channel)f(dele)o (gates)h(or)g(e)o(xtends)g(man)o(y)f(of)i(the)g(sock)o(et)f(methods.)25 b(Most)c(of)g(these)g(are)f(nearly)g(identical)g(to)h(their)0 429 y(sock)o(et)f(partners.)0 576 y FD(create_socket)p FJ(\()p FK(family)-5 b(,)18 b(type)p FJ(\))208 676 y FN(This)27 b(is)i(identical)e(to)h(the)f(creation)g(of)g(a)h(normal)f (sock)o(et,)i(and)e(will)h(use)g(the)g(same)f(options)g(for)g (creation.)46 b(Refer)28 b(to)g(the)208 775 y FJ(socket)19 b FN(documentation)e(for)j(information)e(on)i(creating)f(sock)o(ets.)0 922 y FD(connect)p FJ(\()p FK(addr)m(ess)p FJ(\))208 1022 y FN(As)h(with)g(the)g(normal)e(sock)o(et)i(object,)f FK(addr)m(ess)g FN(is)i(a)f(tuple)g(with)g(the)f(\002rst)i(element)e (the)h(host)f(to)h(connect)f(to,)h(and)f(the)g(second)208 1121 y(the)h(port)f(number)-5 b(.)0 1268 y FD(send)p FJ(\()p FK(data)p FJ(\))208 1368 y FN(Send)19 b FK(data)h FN(to)g(the)g(remote)g(end-point)e(of)h(the)i(sock)o(et.)0 1515 y FD(recv)p FJ(\()p FK(b)n(uf)o(fer)p 451 1515 25 4 v 28 w(size)p FJ(\))208 1614 y FN(Read)e(at)g(most)g FK(b)n(uf)o(fer)p 859 1614 V 29 w(size)i FN(bytes)d(from)g(the)i(sock)o (et')-5 b(s)19 b(remote)f(end-point.)k(An)d(empty)g(string)f(implies)h (that)g(the)h(channel)d(has)208 1714 y(been)i(closed)h(from)f(the)h (other)g(end.)0 1861 y FD(listen)p FJ(\()p FK(bac)n(klo)o(g)p FJ(\))208 1961 y FN(Listen)26 b(for)g(connections)f(made)h(to)h(the)f (sock)o(et.)44 b(The)27 b FK(bac)n(klo)o(g)e FN(ar)o(gument)f (speci\002es)k(the)e(maximum)f(number)g(of)h(queued)208 2060 y(connections)18 b(and)i(should)f(be)h(at)h(least)f(1;)h(the)f (maximum)f(v)n(alue)g(is)i(system-dependent)c(\(usually)j(5\).)0 2207 y FD(bind)p FJ(\()p FK(addr)m(ess)p FJ(\))208 2307 y FN(Bind)28 b(the)g(sock)o(et)g(to)g FK(addr)m(ess)p FN(.)49 b(The)28 b(sock)o(et)g(must)g(not)g(already)f(be)h(bound.)47 b(\(The)28 b(format)f(of)h FK(addr)m(ess)g FN(depends)f(on)h(the)208 2406 y(address)c(f)o(amily)g(\227)i(see)f(abo)o(v)o(e.\))37 b(T)-7 b(o)25 b(mark)f(the)h(sock)o(et)f(as)i(re-usable)e(\(setting)g (the)h FJ(SO_REUSEADDR)e FN(option\),)h(call)i(the)208 2506 y FJ(dispatcher)18 b FN(object')-5 b(s)20 b FJ(set_reuse_addr\(\)) e FN(method.)0 2653 y FD(accept)p FJ(\(\))208 2752 y FN(Accept)h(a)h(connection.)j(The)c(sock)o(et)h(must)f(be)h(bound)e(to) i(an)f(address)g(and)h(listening)f(for)g(connections.)k(The)c(return)g (v)n(alue)g(is)208 2852 y(a)j(pair)h FJ(\()p FK(conn)p FJ(,)47 b FK(addr)m(ess)p FJ(\))22 b FN(where)g FK(conn)g FN(is)h(a)g FK(ne)o(w)g FN(sock)o(et)f(object)g(usable)g(to)h(send)f (and)g(recei)n(v)o(e)f(data)h(on)g(the)h(connection,)208 2952 y(and)c FK(addr)m(ess)h FN(is)h(the)f(address)g(bound)f(to)h(the)g (sock)o(et)g(on)g(the)g(other)f(end)h(of)g(the)g(connection.)0 3099 y FD(close)p FJ(\(\))208 3198 y FN(Close)f(the)g(sock)o(et.)25 b(All)19 b(future)f(operations)g(on)g(the)h(sock)o(et)g(object)g(will)g (f)o(ail.)25 b(The)19 b(remote)f(end-point)f(will)j(recei)n(v)o(e)e(no) g(more)208 3298 y(data)i(\(after)f(queued)g(data)h(is)h(\003ushed\).)j (Sock)o(ets)c(are)g(automatically)f(closed)h(when)f(the)o(y)h(are)g (garbage-collected.)0 3583 y Fv(17.5.1)101 b(asyncore)28 b(Example)i(basic)e(HTTP)g(client)0 3786 y FN(Here)20 b(is)h(a)g(v)o(ery)e(basic)h(HTTP)h(client)f(that)g(uses)h(the)f FJ(dispatcher)f FN(class)i(to)f(implement)f(its)i(sock)o(et)g (handling:)p 0 5549 3901 4 v 0 5649 a FI(594)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q (king)p eop end %%Page: 595 607 TeXDict begin 595 606 bop 236 174 a FA(import)44 b(asyncore,)f(socket) 236 357 y(class)h(http_client\(asyncore.dispatcher\):)416 540 y(def)g(__init__\(self,)e(host,)i(path\):)595 631 y(asyncore.dispatcher.__init__\(self\))595 722 y (self.create_socket\(socket.AF_INET,)39 b(socket.SOCK_STREAM\))595 814 y(self.connect\()k(\(host,)g(80\))i(\))595 905 y(self.buffer)e(=)i ('GET)f(\045s)g(HTTP/1.0\\r\\n\\r\\n')e(\045)j(path)416 1088 y(def)f(handle_connect\(self\):)595 1179 y(pass)416 1362 y(def)g(handle_close\(self\):)595 1453 y(self.close\(\))416 1636 y(def)g(handle_read\(self\):)595 1727 y(print)g(self.recv\(8192\)) 416 1910 y(def)g(writable\(self\):)595 2001 y(return)g (\(len\(self.buffer\))e(>)i(0\))416 2183 y(def)g(handle_write\(self\):) 595 2275 y(sent)g(=)h(self.send\(self.buffer\))595 2366 y(self.buffer)e(=)i(self.buffer[sent:])236 2549 y(c)g(=)g (http_client\('www.python.org',)40 b('/'\))236 2731 y (asyncore.loop\(\))0 3242 y FE(17.6)121 b Fx(asynchat)31 b FE(\227)i(Asynchronous)i(soc)n(k)n(et)e(command/response)j(handler)0 3474 y FN(This)19 b(module)f(b)n(uilds)g(on)h(the)g FJ(asyncore)f FN(infrastructure,)f(simplifying)g(asynchronous)f(clients)j(and)f(serv) o(ers)h(and)f(making)g(it)h(eas-)0 3574 y(ier)k(to)g(handle)e (protocols)g(whose)i(elements)f(are)h(terminated)e(by)h(arbitrary)f (strings,)i(or)f(are)h(of)f(v)n(ariable)g(length.)31 b FJ(asynchat)22 b FN(de-)0 3674 y(\002nes)d(the)g(abstract)g(class)h FJ(async_chat)e FN(that)h(you)f(subclass,)h(pro)o(viding)e (implementations)g(of)h(the)h FJ(collect_incoming_-)0 3773 y(data\(\))25 b FN(and)g FJ(found_terminator\(\))d FN(methods.)39 b(It)26 b(uses)g(the)f(same)h(asynchronous)c(loop)j(as)h FJ(asyncore)p FN(,)f(and)g(the)g(tw)o(o)0 3873 y(types)h(of)g(channel,) g FJ(asyncore.dispatcher)e FN(and)i FJ(asynchat.async_chat)p FN(,)e(can)i(freely)g(be)g(mix)o(ed)f(in)h(the)h(channel)0 3972 y(map.)50 b(T)-7 b(ypically)28 b(an)h FJ(asyncore.dispatcher)c FN(serv)o(er)j(channel)g(generates)g(ne)n(w)g FJ(asynchat.async_chat)e FN(channel)0 4072 y(objects)20 b(as)h(it)g(recei)n(v)o(es)e(incoming)g (connection)f(requests.)0 4219 y FL(class)j FD(async_chat)p FJ(\(\))208 4319 y FN(This)45 b(class)g(is)h(an)f(abstract)g(subclass)g (of)f FJ(asyncore.dispatcher)p FN(.)96 b(T)-7 b(o)45 b(mak)o(e)g(practical)f(use)h(of)f(the)h(code)208 4418 y(you)35 b(must)h(subclass)g FJ(async_chat)p FN(,)j(pro)o(viding)33 b(meaningful)h FJ(collect_incoming_data\(\))e FN(and)j FJ(found_-)208 4518 y(terminator\(\))16 b FN(methods.)23 b(The)18 b FJ(asyncore.dispatcher)d FN(methods)i(can)h(be)g(used,)g (although)e(not)i(all)h(mak)o(e)e(sense)208 4617 y(in)j(a)h (message/response)d(conte)o(xt.)208 4750 y(Lik)o(e)26 b FJ(asyncore.dispatcher)p FN(,)g FJ(async_chat)f FN(de\002nes)i(a)h (set)f(of)g(e)n(v)o(ents)f(that)h(are)g(generated)e(by)i(an)g(analysis) g(of)208 4850 y(sock)o(et)e(conditions)e(after)i(a)h FJ(select\(\))e FN(call.)40 b(Once)25 b(the)g(polling)f(loop)h(has)g (been)g(started)g(the)g FJ(async_chat)f FN(object')-5 b(s)208 4950 y(methods)19 b(are)h(called)g(by)g(the)g(e)n(v)o (ent-processing)d(frame)n(w)o(ork)h(with)i(no)g(action)g(on)f(the)i (part)e(of)h(the)h(programmer)-5 b(.)208 5082 y(T)e(w)o(o)20 b(class)h(attrib)n(utes)f(can)g(be)g(modi\002ed,)f(to)h(impro)o(v)o(e)e (performance,)f(or)j(possibly)g(e)n(v)o(en)f(to)h(conserv)o(e)f(memory) -5 b(.)208 5215 y FD(ac_in_buffer_size)390 5315 y FN(The)20 b(asynchronous)d(input)j(b)n(uf)n(fer)f(size)h(\(def)o(ault)g FJ(4096)p FN(\).)p 0 5549 3901 4 v 0 5649 a FI(17.6.)52 b FJ(asynchat)22 b FI(\227)h(Asynchronous)f(soc)n(k)n(et)h (command/response)g(handler)1161 b(595)p eop end %%Page: 596 608 TeXDict begin 596 607 bop 208 83 a FD(ac_out_buffer_size)390 183 y FN(The)20 b(asynchronous)d(output)i(b)n(uf)n(fer)g(size)i(\(def)o (ault)e FJ(4096)p FN(\).)208 315 y(Unlik)o(e)i FJ(asyncore.dispatcher)p FN(,)e FJ(async_chat)i FN(allo)n(ws)h(you)f(to)h(de\002ne)f(a)h (\002rst-in-\002rst-out)f(queue)f(\(\002fo\))h(of)h FK(pr)l(o-)208 415 y(ducer)o(s)p FN(.)41 b(A)27 b(producer)c(need)i(ha)n(v)o(e)g(only) g(one)g(method,)h FJ(more\(\))p FN(,)g(which)g(should)e(return)h(data)h (to)g(be)f(transmitted)g(on)h(the)208 515 y(channel.)33 b(The)23 b(producer)e(indicates)i(e)o(xhaustion)f(\()p FK(i.e)o(.)34 b FN(that)24 b(it)g(contains)f(no)g(more)f(data\))h(by)g (ha)n(ving)g(its)h FJ(more\(\))f FN(method)208 614 y(return)g(the)j (empty)e(string.)39 b(At)26 b(this)f(point)g(the)g FJ(async_chat)e FN(object)i(remo)o(v)o(es)e(the)i(producer)e(from)h(the)h(\002fo)g(and) g(starts)208 714 y(using)18 b(the)i(ne)o(xt)e(producer)m(,)f(if)j(an)o (y)-5 b(.)23 b(When)c(the)h(producer)d(\002fo)i(is)h(empty)f(the)g FJ(handle_write\(\))e FN(method)h(does)i(nothing.)208 814 y(Y)-9 b(ou)27 b(use)h(the)g(channel)e(object')-5 b(s)28 b FJ(set_terminator\(\))d FN(method)i(to)h(describe)f(ho)n(w)g (to)h(recognize)e(the)i(end)f(of,)i(or)f(an)208 913 y(important)18 b(breakpoint)g(in,)i(an)g(incoming)f(transmission)g(from)g(the)i (remote)e(endpoint.)208 1046 y(T)-7 b(o)37 b(b)n(uild)f(a)h (functioning)d FJ(async_chat)i FN(subclass)h(your)e(input)h(methods)g FJ(collect_incoming_data\(\))d FN(and)208 1146 y FJ (found_terminator\(\))25 b FN(must)k(handle)f(the)g(data)h(that)f(the)h (channel)e(recei)n(v)o(es)h(asynchronously)-5 b(.)47 b(The)28 b(methods)g(are)208 1245 y(described)18 b(belo)n(w)-5 b(.)0 1392 y FD(close_when_done)p FJ(\(\))208 1492 y FN(Pushes)25 b(a)h FJ(None)f FN(on)f(to)i(the)f(producer)e(\002fo.)39 b(When)25 b(this)h(producer)d(is)j(popped)d(of)n(f)i(the)g(\002fo)g(it) h(causes)f(the)g(channel)f(to)i(be)208 1591 y(closed.)0 1738 y FD(collect_incoming_data)p FJ(\()p FK(data)p FJ(\))208 1838 y FN(Called)21 b(with)h FK(data)e FN(holding)g(an)h(arbitrary)f (amount)g(of)h(recei)n(v)o(ed)f(data.)28 b(The)21 b(def)o(ault)g (method,)f(which)g(must)i(be)f(o)o(v)o(erridden,)208 1938 y(raises)f(a)h FJ(NotImplementedError)c FN(e)o(xception.)0 2084 y FD(discard_buffers)p FJ(\(\))208 2184 y FN(In)i(emer)o(gencies)g (this)h(method)f(will)i(discard)f(an)o(y)f(data)h(held)g(in)g(the)g (input)g(and/or)f(output)g(b)n(uf)n(fers)g(and)g(the)i(producer)c (\002fo.)0 2331 y FD(found_terminator)p FJ(\(\))208 2431 y FN(Called)30 b(when)g(the)h(incoming)d(data)j(stream)f(matches)g(the) g(termination)f(condition)g(set)i(by)f FJ(set_terminator)p FN(.)54 b(The)208 2530 y(def)o(ault)21 b(method,)g(which)g(must)h(be)g (o)o(v)o(erridden,)d(raises)k(a)f FJ(NotImplementedError)d FN(e)o(xception.)29 b(The)21 b(b)n(uf)n(fered)f(input)208 2630 y(data)g(should)f(be)h(a)n(v)n(ailable)g(via)g(an)g(instance)g (attrib)n(ute.)0 2777 y FD(get_terminator)p FJ(\(\))208 2876 y FN(Returns)g(the)g(current)f(terminator)f(for)i(the)g(channel.)0 3023 y FD(handle_close)p FJ(\(\))208 3123 y FN(Called)g(when)g(the)g (channel)f(is)i(closed.)k(The)19 b(def)o(ault)h(method)f(silently)h (closes)h(the)f(channel')-5 b(s)19 b(sock)o(et.)0 3270 y FD(handle_read)p FJ(\(\))208 3369 y FN(Called)26 b(when)f(a)h(read)f (e)n(v)o(ent)g(\002res)h(on)f(the)h(channel')-5 b(s)25 b(sock)o(et)g(in)h(the)g(asynchronous)d(loop.)40 b(The)26 b(def)o(ault)f(method)f(checks)208 3469 y(for)g(the)h(termination)f (condition)f(established)i(by)g FJ(set_terminator\(\))p FN(,)e(which)i(can)g(be)g(either)g(the)g(appearance)e(of)i(a)208 3569 y(particular)g(string)h(in)h(the)g(input)f(stream)g(or)h(the)f (receipt)g(of)h(a)g(particular)e(number)g(of)i(characters.)43 b(When)26 b(the)h(terminator)208 3668 y(is)22 b(found,)e FJ(handle_read)g FN(calls)j(the)f FJ(found_terminator\(\))c FN(method)j(after)g(calling)g FJ(collect_incoming_-)208 3768 y(data\(\))e FN(with)i(an)o(y)e(data)h(preceding)e(the)i (terminating)f(condition.)0 3915 y FD(handle_write)p FJ(\(\))208 4014 y FN(Called)h(when)g(the)g(application)f(may)h(write)h (data)f(to)h(the)f(channel.)k(The)d(def)o(ault)e(method)g(calls)i(the)g FJ(initiate_send\(\))208 4114 y FN(method,)e(which)h(in)g(turn)g(will)h (call)g FJ(refill_buffer\(\))e FN(to)h(collect)h(data)f(from)f(the)i (producer)d(\002fo)j(associated)f(with)h(the)208 4214 y(channel.)0 4360 y FD(push)p FJ(\()p FK(data)p FJ(\))208 4460 y FN(Creates)36 b(a)h FJ(simple_producer)d FN(object)i(\()p FK(see)g(below)p FN(\))g(containing)e(the)i(data)h(and)e(pushes)h(it)h (on)f(to)g(the)g(channel')-5 b(s)208 4560 y FJ(producer_fifo)26 b FN(to)i(ensure)g(its)h(transmission.)49 b(This)29 b(is)g(all)g(you)e (need)h(to)g(do)g(to)h(ha)n(v)o(e)e(the)i(channel)e(write)h(the)h(data) 208 4659 y(out)23 b(to)i(the)f(netw)o(ork,)g(although)e(it)j(is)g (possible)f(to)h(use)f(your)f(o)n(wn)h(producers)e(in)i(more)g(comple)o (x)e(schemes)i(to)h(implement)208 4759 y(encryption)17 b(and)j(chunking,)e(for)h(e)o(xample.)0 4906 y FD(push_with_producer)p FJ(\()p FK(pr)l(oducer)r FJ(\))208 5005 y FN(T)-7 b(ak)o(es)20 b(a)h(producer)d(object)h(and)h(adds)g(it)h(to)g(the)f(producer)e (\002fo)i(associated)g(with)g(the)h(channel.)j(When)c(all)g (currently-pushed)208 5105 y(producers)j(ha)n(v)o(e)j(been)f(e)o (xhausted)f(the)i(channel)e(will)j(consume)d(this)j(producer')-5 b(s)23 b(data)j(by)f(calling)h(its)h FJ(more\(\))e FN(method)208 5205 y(and)19 b(send)h(the)g(data)g(to)h(the)f(remote)f(endpoint.)0 5352 y FD(readable)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(596)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 597 609 TeXDict begin 597 608 bop 208 83 a FN(Should)26 b(return)g FJ(True)i FN(for)f(the)g(channel)g(to)h(be)f(included)f(in)i(the)g(set) g(of)f(channels)g(tested)h(by)f(the)h FJ(select\(\))e FN(loop)h(for)208 183 y(readability)-5 b(.)0 330 y FD(refill_buffer)p FJ(\(\))208 429 y FN(Re\002lls)20 b(the)g(output)e(b)n(uf)n(fer)g(by)h (calling)g(the)h FJ(more\(\))f FN(method)f(of)h(the)h(producer)d(at)j (the)f(head)g(of)g(the)h(\002fo.)k(If)c(it)g(is)g(e)o(xhausted)208 529 y(then)d(the)g(producer)e(is)k(popped)c(of)n(f)i(the)g(\002fo)h (and)f(the)g(ne)o(xt)g(producer)e(is)k(acti)n(v)n(ated.)k(If)17 b(the)h(current)e(producer)f(is,)k(or)e(becomes,)208 628 y FJ(None)j FN(then)f(the)h(channel)f(is)j(closed.)0 775 y FD(set_terminator)p FJ(\()p FK(term)p FJ(\))208 875 y FN(Sets)30 b(the)g(terminating)f(condition)f(to)i(be)g (recognised)e(on)h(the)h(channel.)53 b FJ(term)30 b FN(may)f(be)h(an)o (y)f(of)h(three)f(types)h(of)f(v)n(alue,)208 975 y(corresponding)16 b(to)21 b(three)e(dif)n(ferent)g(w)o(ays)h(to)h(handle)e(incoming)f (protocol)h(data.)277 1104 y FL(term)p 556 1134 4 100 v 160 w(Description)p 227 1137 3653 4 v 277 1207 a FK(string)p 556 1237 4 100 v 137 w FN(W)m(ill)i(call)g FJ(found_terminator\(\))c FN(when)j(the)g(string)g(is)h(found)d(in)j(the)f(input)f(stream)277 1306 y FK(inte)m(g)o(er)p 556 1336 V 99 w FN(W)m(ill)i(call)g FJ(found_terminator\(\))c FN(when)j(the)g(indicated)f(number)f(of)i (characters)f(ha)n(v)o(e)h(been)f(recei)n(v)o(ed)277 1406 y FJ(None)p 556 1436 V 131 w FN(The)h(channel)f(continues)g(to)h (collect)g(data)g(fore)n(v)o(er)208 1534 y(Note)36 b(that)g(an)o(y)f (data)i(follo)n(wing)d(the)i(terminator)f(will)i(be)f(a)n(v)n(ailable)g (for)g(reading)e(by)i(the)g(channel)f(after)h FJ(found_-)208 1634 y(terminator\(\))18 b FN(is)j(called.)0 1780 y FD(writable)p FJ(\(\))208 1880 y FN(Should)d(return)h FJ(True)h FN(as)h(long)e(as)i (items)g(remain)e(on)g(the)i(producer)c(\002fo,)j(or)g(the)g(channel)f (is)i(connected)d(and)h(the)h(channel')-5 b(s)208 1980 y(output)19 b(b)n(uf)n(fer)f(is)j(non-empty)-5 b(.)0 2265 y Fv(17.6.1)101 b(asynchat)28 b(-)g(A)m(uxiliar)s(y)h(Classes)f (and)h(Functions)0 2463 y FL(class)21 b FD(simple_producer)p FJ(\()p FK(data)p FC([)p FK(,)16 b(b)n(uf)o(fer)p 1414 2463 25 4 v 29 w(size=512)c FC(])p FJ(\))208 2563 y FN(A)17 b FJ(simple_producer)d FN(tak)o(es)j(a)f(chunk)f(of)i(data)f(and)g(an)g (optional)f(b)n(uf)n(fer)g(size.)25 b(Repeated)16 b(calls)h(to)g(its)g FJ(more\(\))f FN(method)208 2663 y(yield)j(successi)n(v)o(e)h(chunks)f (of)h(the)g(data)g(no)g(lar)o(ger)f(than)h FK(b)n(uf)o(fer)p 2071 2663 V 29 w(size)p FN(.)0 2809 y FD(more)p FJ(\(\))208 2909 y FN(Produces)f(the)h(ne)o(xt)f(chunk)g(of)h(information)e(from)h (the)h(producer)m(,)d(or)j(returns)g(the)g(empty)f(string.)0 3056 y FL(class)i FD(fifo)p FJ(\()p FC([)p FK(list=None)12 b FC(])p FJ(\))208 3156 y FN(Each)21 b(channel)g(maintains)g(a)h FJ(fifo)g FN(holding)e(data)i(which)g(has)g(been)f(pushed)g(by)g(the)h (application)f(b)n(ut)h(not)f(yet)h(popped)e(for)208 3255 y(writing)k(to)h(the)g(channel.)37 b(A)25 b FJ(fifo)g FN(is)h(a)f(list)h(used)f(to)g(hold)f(data)g(and/or)g(producers)e (until)j(the)o(y)f(are)h(required.)37 b(If)25 b(the)f FK(list)208 3355 y FN(ar)o(gument)17 b(is)22 b(pro)o(vided)17 b(then)j(it)h(should)e(contain)g(producers)f(or)i(data)g(items)h(to)f (be)g(written)g(to)h(the)f(channel.)0 3502 y FD(is_empty)p FJ(\(\))208 3601 y FN(Returns)g FJ(True)g FN(if)n(f)g(the)g(\002fo)g (is)h(empty)-5 b(.)0 3748 y FD(first)p FJ(\(\))208 3848 y FN(Returns)20 b(the)g(least-recently)f FJ(push\(\))p FN(ed)g(item)h(from)f(the)i(\002fo.)0 3995 y FD(push)p FJ(\()p FK(data)p FJ(\))208 4094 y FN(Adds)f(the)g(gi)n(v)o(en)f(data)h (\(which)f(may)h(be)g(a)h(string)e(or)h(a)h(producer)d(object\))h(to)h (the)h(producer)c(\002fo.)0 4241 y FD(pop)p FJ(\(\))208 4341 y FN(If)23 b(the)g(\002fo)h(is)g(not)f(empty)-5 b(,)23 b(returns)g FJ(True,)49 b(first\(\))p FN(,)23 b(deleting)f(the)i(popped)d(item.)35 b(Returns)24 b FJ(False,)48 b(None)24 b FN(for)f(an)208 4440 y(empty)c(\002fo.)0 4587 y(The)h FJ(asynchat)f FN(module)g(also)i(de\002nes)f(one)f (utility)i(function,)d(which)i(may)f(be)i(of)f(use)g(in)g(netw)o(ork)f (and)h(te)o(xtual)g(analysis)g(opera-)0 4687 y(tions.)0 4834 y FD(find_prefix_at_end)p FJ(\()p FK(haystac)n(k,)c(needle)p FJ(\))208 4933 y FN(Returns)k FJ(True)g FN(if)g(string)g FK(haystac)n(k)h FN(ends)f(with)g(an)o(y)g(non-empty)d(pre\002x)j(of)f (string)h FK(needle)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(17.6.)52 b FJ(asynchat)22 b FI(\227)h(Asynchronous)f(soc)n(k)n(et)h (command/response)g(handler)1161 b(597)p eop end %%Page: 598 610 TeXDict begin 598 609 bop 0 83 a Fv(17.6.2)101 b(asynchat)28 b(Example)0 286 y FN(The)j(follo)n(wing)e(partial)i(e)o(xample)f(sho)n (ws)h(ho)n(w)g(HTTP)g(requests)g(can)g(be)g(read)g(with)g FJ(async_chat)p FN(.)57 b(A)32 b(web)f(serv)o(er)f(might)0 386 y(create)23 b(an)h FJ(http_request_handler)d FN(object)i(for)g (each)h(incoming)e(client)h(connection.)34 b(Notice)23 b(that)h(initially)g(the)g(channel)0 485 y(terminator)18 b(is)i(set)g(to)f(match)f(the)i(blank)e(line)h(at)h(the)f(end)f(of)h (the)g(HTTP)h(headers,)e(and)g(a)i(\003ag)f(indicates)g(that)g(the)g (headers)f(are)i(being)0 585 y(read.)0 732 y(Once)j(the)h(headers)e(ha) n(v)o(e)h(been)g(read,)h(if)g(the)f(request)g(is)i(of)e(type)g(POST)h (\(indicating)e(that)h(further)f(data)i(are)f(present)g(in)h(the)f (input)0 831 y(stream\))j(then)g(the)g FJ(Content-Length:)36 b FN(header)25 b(is)i(used)f(to)h(set)g(a)g(numeric)e(terminator)g(to)h (read)g(the)h(right)f(amount)f(of)h(data)0 931 y(from)19 b(the)h(channel.)0 1078 y(The)26 b FJ(handle_request\(\))f FN(method)g(is)j(called)f(once)f(all)h(rele)n(v)n(ant)f(input)g(has)h (been)f(marshalled,)h(after)f(setting)h(the)g(channel)0 1177 y(terminator)19 b(to)h FJ(None)g FN(to)g(ensure)g(that)g(an)o(y)f (e)o(xtraneous)g(data)h(sent)g(by)g(the)g(web)g(client)g(are)h (ignored.)236 1416 y FA(class)44 b (http_request_handler\(asynchat.async_chat)o(\):)416 1598 y(def)g(__init__\(self,)e(conn,)i(addr,)g(sessions,)g(log\):)595 1690 y(asynchat.async_chat.__init__\(self,)39 b(conn=conn\))595 1781 y(self.addr)k(=)i(addr)595 1872 y(self.sessions)e(=)h(sessions)595 1964 y(self.ibuffer)f(=)h([])595 2055 y(self.obuffer)f(=)h("")595 2146 y(self.set_terminator\("\\r\\n\\r\\n"\))595 2238 y(self.reading_headers)d(=)k(True)595 2329 y(self.handling)e(=)h(False) 595 2420 y(self.cgi_data)f(=)h(None)595 2512 y(self.log)f(=)i(log)416 2694 y(def)f(collect_incoming_data\(self,)c(data\):)595 2785 y("""Buffer)j(the)i(data""")595 2877 y (self.ibuffer.append\(data\))416 3059 y(def)f (found_terminator\(self\):)595 3151 y(if)g(self.reading_headers:)774 3242 y(self.reading_headers)e(=)i(False)774 3333 y (self.parse_headers\("".join\(self.ibuffer\))o(\))774 3425 y(self.ibuffer)f(=)i([])774 3516 y(if)g(self.op.upper\(\))d(==)j ("POST":)954 3607 y(clen)f(=)g (self.headers.getheader\("content-length"\))954 3699 y(self.set_terminator\(int\(clen\)\))774 3790 y(else:)954 3881 y(self.handling)e(=)j(True)954 3973 y(self.set_terminator\(None\)) 954 4064 y(self.handle_request\(\))595 4155 y(elif)f(not)g (self.handling:)774 4247 y(self.set_terminator\(None\))d(#)j(browsers)g (sometimes)f(over-send)774 4338 y(self.cgi_data)g(=)i (parse\(self.headers,)c("".join\(self.ibuffer\)\))774 4429 y(self.handling)i(=)i(True)774 4521 y(self.ibuffer)e(=)i([])774 4612 y(self.handle_request\(\))p 0 5549 3901 4 v 0 5649 a FI(598)1618 b(Chapter)24 b(17.)52 b(Inter)r(process)22 b(Comm)o(unication)j(and)e(Netw)o(or)q(king)p eop end %%Page: 599 611 TeXDict begin 599 610 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3289 427 y FG(EIGHTEEN)p 0 515 V 1028 978 a FT(Inter)5 b(net)58 b(Protocols)f(and)g(Suppor)8 b(t)0 1465 y FN(The)23 b(modules)f (described)g(in)h(this)h(chapter)e(implement)g(Internet)g(protocols)f (and)i(support)f(for)g(related)h(technology)-5 b(.)31 b(The)o(y)22 b(are)h(all)0 1565 y(implemented)16 b(in)i(Python.)23 b(Most)c(of)e(these)h(modules)f(require)g(the)h(presence)f(of)h(the)g (system-dependent)d(module)h FJ(socket)p FN(,)i(which)0 1664 y(is)j(currently)e(supported)f(on)i(most)g(popular)e(platforms.)24 b(Here)c(is)h(an)f(o)o(v)o(ervie)n(w:)50 1808 y FD(webbrowser)496 b FN(Easy-to-use)19 b(controller)f(for)i(W)-7 b(eb)21 b(bro)n(wsers.)50 1907 y FD(cgi)846 b FN(Common)19 b(Gate)n(w)o(ay)h (Interf)o(ace)f(support,)f(used)i(to)h(interpret)e(forms)g(in)h(serv)o (er)n(-side)f(scripts.)50 2007 y FD(cgitb)746 b FN(Con\002gurable)18 b(traceback)h(handler)g(for)g(CGI)i(scripts.)50 2106 y FD(wsgiref.handlers)196 b FN(WSGI)21 b(Utilities)g(and)f(Reference)f (Implementation)50 2206 y FD(urllib)696 b FN(Open)20 b(an)g(arbitrary)e(netw)o(ork)h(resource)g(by)h(URL)h(\(requires)e (sock)o(ets\).)50 2306 y FD(urllib2)646 b FN(An)20 b(e)o(xtensible)f (library)h(for)f(opening)f(URLs)j(using)f(a)h(v)n(ariety)e(of)h (protocols)50 2405 y FD(httplib)646 b FN(HTTP)20 b(and)g(HTTPS)g (protocol)f(client)h(\(requires)f(sock)o(ets\).)50 2505 y FD(ftplib)696 b FN(FTP)21 b(protocol)d(client)j(\(requires)d(sock)o (ets\).)50 2605 y FD(gopherlib)546 b FN(Gopher)19 b(protocol)f(client)j (\(requires)d(sock)o(ets\).)50 2704 y FD(poplib)696 b FN(POP3)21 b(protocol)d(client)i(\(requires)f(sock)o(ets\).)50 2804 y FD(imaplib)646 b FN(IMAP4)20 b(protocol)e(client)j(\(requires)d (sock)o(ets\).)50 2903 y FD(nntplib)646 b FN(NNTP)21 b(protocol)d(client)i(\(requires)f(sock)o(ets\).)50 3003 y FD(smtplib)646 b FN(SMTP)21 b(protocol)d(client)i(\(requires)f(sock)o (ets\).)50 3103 y FD(smtpd)746 b FN(Implement)19 b(a)h(\003e)o(xible)g (SMTP)g(serv)o(er)50 3202 y FD(telnetlib)546 b FN(T)-6 b(elnet)20 b(client)g(class.)50 3302 y FD(uuid)796 b FN(UUID)20 b(objects)g(\(uni)n(v)o(ersally)e(unique)h(identi\002ers\))h (according)e(to)i(RFC)i(4122)50 3402 y FD(urlparse)596 b FN(P)o(arse)20 b(URLs)i(into)d(components.)50 3501 y FD(SocketServer)396 b FN(A)21 b(frame)n(w)o(ork)d(for)h(netw)o(ork)g (serv)o(ers.)50 3601 y FD(BaseHTTPServer)296 b FN(Basic)21 b(HTTP)g(serv)o(er)e(\(base)h(class)h(for)f FJ(SimpleHTTPServer)d FN(and)j FJ(CGIHTTPServer)p FN(\).)50 3700 y FD(SimpleHTTPServer)196 b FN(This)20 b(module)f(pro)o(vides)g(a)h(basic)h(request)e(handler)g (for)g(HTTP)i(serv)o(ers.)50 3800 y FD(CGIHTTPServer)346 b FN(This)20 b(module)f(pro)o(vides)g(a)h(request)g(handler)f(for)g (HTTP)h(serv)o(ers)g(which)g(can)g(run)f(CGI)i(scripts.)50 3900 y FD(cookielib)546 b FN(Cookie)20 b(handling)e(for)i(HTTP)g (clients)50 3999 y FD(Cookie)696 b FN(Support)19 b(for)g(HTTP)i(state)g (management)d(\(cookies\).)50 4099 y FD(xmlrpclib)546 b FN(XML-RPC)21 b(client)f(access.)50 4199 y FD(SimpleXMLRPCServer)96 b FN(Basic)21 b(XML-RPC)g(serv)o(er)e(implementation.)50 4298 y FD(DocXMLRPCServer)246 b FN(Self-documenting)17 b(XML-RPC)k(serv)o(er)e(implementation.)0 4664 y FE(18.1)121 b Fx(webbrowser)31 b FE(\227)i(Con)n(v)m(enient)i(W)l(eb-bro)n(wser)h (controller)0 4897 y FN(The)20 b FJ(webbrowser)f FN(module)g(pro)o (vides)f(a)j(high-le)n(v)o(el)d(interf)o(ace)h(to)i(allo)n(w)f (displaying)f(W)-7 b(eb-based)19 b(documents)g(to)h(users.)26 b(Under)0 4996 y(most)20 b(circumstances,)f(simply)h(calling)g(the)g FJ(open\(\))f FN(function)g(from)g(this)i(module)e(will)i(do)e(the)i (right)e(thing.)0 5143 y(Under)k(U)t FH(N)t(I)t(X)r FN(,)g(graphical)d (bro)n(wsers)h(are)h(preferred)d(under)h(X11,)i(b)n(ut)g(te)o(xt-mode)d (bro)n(wsers)i(will)i(be)f(used)f(if)h(graphical)e(bro)n(wsers)0 5243 y(are)g(not)g(a)n(v)n(ailable)g(or)f(an)h(X11)g(display)g(isn')o (t)g(a)n(v)n(ailable.)k(If)c(te)o(xt-mode)e(bro)n(wsers)h(are)h(used,)g (the)g(calling)g(process)g(will)h(block)e(until)0 5342 y(the)h(user)g(e)o(xits)h(the)f(bro)n(wser)-5 b(.)p 0 5549 3901 4 v 3762 5649 a FI(599)p eop end %%Page: 600 612 TeXDict begin 600 611 bop 0 83 a FN(If)24 b(the)g(en)m(vironment)d(v)n (ariable)i(BR)m(O)m(WSER)j(e)o(xists,)f(it)g(is)g(interpreted)d(to)i(o) o(v)o(erride)e(the)i(platform)f(def)o(ault)g(list)i(of)f(bro)n(wsers,)g (as)h(a)0 183 y(os.pathsep-separated)e(list)28 b(of)e(bro)n(wsers)f(to) i(try)f(in)g(order)-5 b(.)43 b(When)26 b(the)g(v)n(alue)g(of)g(a)h (list)g(part)f(contains)g(the)g(string)g FJ(\045s)p FN(,)i(then)e(it)h (is)0 282 y(interpreted)22 b(as)i(a)h(literal)f(bro)n(wser)e(command)g (line)i(to)g(be)g(used)f(with)h(the)g(ar)o(gument)d(URL)k(substituted)e (for)g FJ(\045s)p FN(;)j(if)e(the)f(part)h(does)0 382 y(not)c(contain)f FJ(\045s)p FN(,)h(it)h(is)g(simply)f(interpreted)e (as)j(the)g(name)e(of)h(the)g(bro)n(wser)f(to)i(launch.)0 529 y(F)o(or)e(non-)r(U)t FH(N)t(I)t(X)i FN(platforms,)d(or)h(when)f(a) i(remote)f(bro)n(wser)f(is)i(a)n(v)n(ailable)f(on)i(U)t FH(N)t(I)t(X)r FN(,)f(the)g(controlling)d(process)i(will)h(not)f(w)o (ait)h(for)f(the)0 628 y(user)24 b(to)f(\002nish)h(with)g(the)g(bro)n (wser)m(,)f(b)n(ut)h(allo)n(w)f(the)h(remote)f(bro)n(wser)g(to)g (maintain)g(its)i(o)n(wn)e(windo)n(ws)g(on)h(the)f(display)-5 b(.)35 b(If)23 b(remote)0 728 y(bro)n(wsers)c(are)i(not)e(a)n(v)n (ailable)h(on)i(U)t FH(N)t(I)t(X)r FN(,)f(the)f(controlling)e(process)i (will)h(launch)e(a)i(ne)n(w)f(bro)n(wser)f(and)g(w)o(ait.)0 875 y(The)i(script)g FL(web)o(br)o(o)o(wser)h FN(can)f(be)g(used)g(as)h (a)g(command-line)d(interf)o(ace)h(for)h(the)g(module.)27 b(It)22 b(accepts)f(an)h(URL)g(as)g(the)f(ar)o(gument.)0 975 y(It)26 b(accepts)f(the)g(follo)n(wing)f(optional)g(parameters:)35 b FL(-n)26 b FN(opens)e(the)i(URL)g(in)f(a)h(ne)n(w)g(bro)n(wser)e (windo)n(w)-5 b(,)25 b(if)h(possible;)i FL(-t)d FN(opens)g(the)0 1074 y(URL)c(in)f(a)h(ne)n(w)f(bro)n(wser)f(page)g(\(\224tab\224\).)24 b(The)c(options)f(are,)h(naturally)-5 b(,)19 b(mutually)g(e)o(xclusi)n (v)o(e.)0 1221 y(The)h(follo)n(wing)e(e)o(xception)h(is)i(de\002ned:)0 1368 y FL(exception)e FD(Error)208 1468 y FN(Exception)f(raised)i(when) g(a)g(bro)n(wser)f(control)g(error)g(occurs.)0 1614 y(The)h(follo)n (wing)e(functions)h(are)h(de\002ned:)0 1761 y FD(open)p FJ(\()p FK(url)p FC([)p FK(,)f(ne)o(w=0)p FC([)p FK(,)h(autor)o(aise=1) 12 b FC(])g(])p FJ(\))208 1861 y FN(Display)25 b FK(url)h FN(using)e(the)i(def)o(ault)e(bro)n(wser)-5 b(.)40 b(If)25 b FK(ne)o(w)h FN(is)g(0,)g(the)g FK(url)g FN(is)g(opened)e(in)h(the)g (same)h(bro)n(wser)e(windo)n(w)g(if)i(possible.)208 1961 y(If)d FK(ne)o(w)h FN(is)g(1,)g(a)g(ne)n(w)f(bro)n(wser)g(windo)n(w)f (is)j(opened)d(if)i(possible.)34 b(If)24 b FK(ne)o(w)f FN(is)i(2,)f(a)g(ne)n(w)f(bro)n(wser)g(page)f(\(\224tab\224\))h(is)h (opened)e(if)208 2060 y(possible.)j(If)20 b FK(autor)o(aise)g FN(is)h(true,)f(the)g(windo)n(w)g(is)h(raised)f(if)h(possible)f(\(note) g(that)g(under)f(man)o(y)g(windo)n(w)h(managers)f(this)i(will)208 2160 y(occur)e(re)o(gardless)f(of)i(the)g(setting)h(of)f(this)g(v)n (ariable\).)49 b(Changed)19 b(in)i(v)o(ersion)e(2.5:)g FK(ne)o(w)i FN(can)f(no)n(w)f(be)h(2.)0 2307 y FD(open_new)p FJ(\()p FK(url)p FJ(\))208 2406 y FN(Open)f FK(url)i FN(in)f(a)h(ne)n(w)f(windo)n(w)f(of)h(the)g(def)o(ault)g(bro)n(wser)m (,)e(if)j(possible,)e(otherwise,)h(open)f FK(url)h FN(in)h(the)f(only)f (bro)n(wser)g(windo)n(w)-5 b(.)0 2553 y FD(open_new_tab)p FJ(\()p FK(url)p FJ(\))208 2653 y FN(Open)19 b FK(url)h FN(in)g(a)g(ne)n(w)g(page)f(\(\224tab\224\))f(of)i(the)g(def)o(ault)f (bro)n(wser)m(,)f(if)i(possible,)f(otherwise)g(equi)n(v)n(alent)f(to)i FJ(open_new)p FN(.)49 b(Ne)n(w)20 b(in)208 2752 y(v)o(ersion)e(2.5.)0 2899 y FD(get)p FJ(\()p FC([)p FK(name)12 b FC(])p FJ(\))208 2999 y FN(Return)19 b(a)i(controller)d(object)i(for)f(the)h(bro)n(wser) f(type)h FK(name)p FN(.)k(If)c FK(name)f FN(is)i(empty)-5 b(,)19 b(return)g(a)h(controller)e(for)i(a)g(def)o(ault)g(bro)n(wser) 208 3099 y(appropriate)d(to)k(the)f(caller')-5 b(s)20 b(en)m(vironment.)0 3245 y FD(register)p FJ(\()p FK(name)o(,)e (constructor)r FC([)p FK(,)h(instance)12 b FC(])p FJ(\))208 3345 y FN(Re)o(gister)21 b(the)h(bro)n(wser)e(type)h FK(name)p FN(.)29 b(Once)21 b(a)h(bro)n(wser)e(type)h(is)i(re)o (gistered,)d(the)i FJ(get\(\))f FN(function)f(can)h(return)f(a)i (controller)208 3445 y(for)f(that)h(bro)n(wser)f(type.)30 b(If)22 b FK(instance)f FN(is)i(not)f(pro)o(vided,)e(or)h(is)i FJ(None)p FN(,)f FK(constructor)i FN(will)e(be)g(called)g(without)g (parameters)e(to)208 3544 y(create)f(an)i(instance)e(when)h(needed.)k (If)c FK(instance)f FN(is)i(pro)o(vided,)d FK(constructor)j FN(will)g(ne)n(v)o(er)e(be)h(called,)g(and)f(may)h(be)g FJ(None)p FN(.)208 3677 y(This)25 b(entry)f(point)h(is)h(only)f(useful) f(if)i(you)e(plan)h(to)g(either)g(set)h(the)g(BR)m(O)m(WSER)h(v)n (ariable)d(or)h(call)h FJ(get)f FN(with)g(a)h(nonempty)208 3777 y(ar)o(gument)17 b(matching)i(the)h(name)g(of)g(a)g(handler)f(you) g(declare.)0 3924 y(A)h(number)e(of)h(bro)n(wser)g(types)g(are)g (prede\002ned.)k(This)d(table)f(gi)n(v)o(es)g(the)h(type)f(names)g (that)h(may)f(be)g(passed)h(to)g(the)f FJ(get\(\))g FN(function)0 4023 y(and)h(the)g(corresponding)d(instantiations)i(for)h(the)g (controller)e(classes,)k(all)e(de\002ned)f(in)i(this)g(module.)p 0 5549 3901 4 v 0 5649 a FI(600)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 601 613 TeXDict begin 601 612 bop 581 70 a FL(T)-6 b(ype)20 b(Name)p 1476 100 4 100 v 544 w(Class)h(Name)p 3070 100 V 1176 w(Notes)p 531 103 2839 4 v 581 173 a FJ('mozilla')p 1476 203 4 100 v 496 w(Mozilla\('mozilla'\))p 3070 203 V 581 272 a('firefox')p 1476 302 V 496 w(Mozilla\('mozilla'\))p 3070 302 V 581 372 a('netscape')p 1476 402 V 446 w (Mozilla\('netscape'\))p 3070 402 V 581 472 a('galeon')p 1476 501 V 546 w(Galeon\('galeon'\))p 3070 501 V 581 571 a('epiphany')p 1476 601 V 446 w(Galeon\('epiphany'\))p 3070 601 V 581 671 a('skipstone')p 1476 701 V 396 w (BackgroundBrowser\('skipstone'\))p 3070 701 V 581 770 a('kfmclient')p 1476 800 V 396 w(Konqueror\(\))p 3070 800 V 1095 w FN(\(1\))581 870 y FJ('konqueror')p 1476 900 V 396 w(Konqueror\(\))p 3070 900 V 1095 w FN(\(1\))581 970 y FJ('kfm')p 1476 1000 V 696 w(Konqueror\(\))p 3070 1000 V 1095 w FN(\(1\))581 1069 y FJ('mosaic')p 1476 1099 V 546 w(BackgroundBrowser\('mosaic'\))p 3070 1099 V 581 1169 a('opera')p 1476 1199 V 596 w(Opera\(\))p 3070 1199 V 581 1269 a('grail')p 1476 1298 V 596 w(Grail\(\))p 3070 1298 V 581 1368 a('links')p 1476 1398 V 596 w (GenericBrowser\('links'\))p 3070 1398 V 581 1468 a('elinks')p 1476 1498 V 546 w(Elinks\('elinks'\))p 3070 1498 V 581 1567 a('lynx')p 1476 1597 V 646 w(GenericBrowser\('lynx'\))p 3070 1597 V 581 1667 a('w3m')p 1476 1697 V 696 w (GenericBrowser\('w3m'\))p 3070 1697 V 581 1767 a('windows-default')p 1476 1797 V 96 w(WindowsDefault)p 3070 1797 V 945 w FN(\(2\))581 1866 y FJ('internet-config')p 1476 1896 V 96 w(InternetConfig)p 3070 1896 V 945 w FN(\(3\))581 1966 y FJ('macosx')p 1476 1996 V 546 w(MacOSX\('default'\))p 3070 1996 V 795 w FN(\(4\))0 2190 y(Notes:)0 2420 y FL(\(1\))40 b FN(\223K)m (onqueror\224)16 b(is)k(the)f(\002le)h(manager)d(for)i(the)g(KDE)g (desktop)f(en)m(vironment)e(for)k(U)t FH(N)t(I)t(X)r FN(,)g(and)e(only)h(mak)o(es)f(sense)i(to)f(use)g(if)g(KDE)208 2519 y(is)25 b(running.)36 b(Some)24 b(w)o(ay)h(of)f(reliably)g (detecting)f(KDE)i(w)o(ould)f(be)g(nice;)j(the)d(KDEDIR)h(v)n(ariable)e (is)j(not)e(suf)n(\002cient.)38 b(Note)208 2619 y(also)19 b(that)g(the)g(name)g(\223kfm\224)f(is)i(used)f(e)n(v)o(en)f(when)h (using)f(the)i FL(k)o(onquer)o(or)e FN(command)f(with)i(KDE)h(2)f(\227) h(the)f(implementation)208 2719 y(selects)i(the)f(best)g(strate)o(gy)g (for)f(running)f(K)m(onqueror)-5 b(.)0 2885 y FL(\(2\))40 b FN(Only)20 b(on)g(W)m(indo)n(ws)f(platforms.)0 3051 y FL(\(3\))40 b FN(Only)29 b(on)h(MacOS)f(platforms;)k(requires)c(the)g (standard)g(MacPython)f FJ(ic)h FN(module,)i(described)d(in)h(the)h FK(Macintosh)f(Libr)o(ary)208 3150 y(Modules)19 b FN(manual.)0 3316 y FL(\(4\))40 b FN(Only)20 b(on)g(MacOS)g(X)h(platform.)0 3546 y(Here)f(are)g(some)g(simple)g(e)o(xamples:)236 3784 y FA(url)45 b(=)f('http://www.python.org')236 3967 y(#)h(Open)f(URL)g(in)h(a)g(new)f(tab,)g(if)h(a)f(browser)g(window)g (is)g(already)g(open.)236 4058 y(webbrowser.open_new_tab\(url)d(+)j ('/doc'\))236 4241 y(#)h(Open)f(URL)g(in)h(new)f(window,)g(raising)g (the)g(window)g(if)g(possible.)236 4332 y(webbrowser.open_new\(url\))0 4757 y Fv(18.1.1)101 b(Bro)o(wser)28 b(Controller)i(Objects)0 4960 y FN(Bro)n(wser)20 b(controllers)f(pro)o(vide)f(tw)o(o)i(methods)g (which)f(parallel)h(tw)o(o)g(of)g(the)g(module-le)n(v)o(el)e(con)m(v)o (enience)f(functions:)0 5107 y FD(open)p FJ(\()p FK(url)p FC([)p FK(,)i(ne)o(w)p FC([)p FK(,)h(autor)o(aise=1)12 b FC(])g(])p FJ(\))208 5207 y FN(Display)j FK(url)i FN(using)e(the)h (bro)n(wser)f(handled)f(by)h(this)i(controller)-5 b(.)22 b(If)16 b FK(ne)o(w)g FN(is)h(1,)f(a)h(ne)n(w)e(bro)n(wser)g(windo)n(w) g(is)i(opened)d(if)i(possible.)208 5306 y(If)k FK(ne)o(w)g FN(is)h(2,)f(a)h(ne)n(w)f(bro)n(wser)f(page)g(\(\224tab\224\))g(is)j (opened)c(if)j(possible.)p 0 5549 3901 4 v 0 5649 a FI(18.1.)52 b FJ(webbrowser)21 b FI(\227)j(Con)n(v)n(enient)g(W)n(eb-bro)o(wser)e (controller)1605 b(601)p eop end %%Page: 602 614 TeXDict begin 602 613 bop 0 83 a FD(open_new)p FJ(\()p FK(url)p FJ(\))208 183 y FN(Open)19 b FK(url)h FN(in)h(a)f(ne)n(w)g (windo)n(w)f(of)h(the)g(bro)n(wser)e(handled)h(by)g(this)i(controller)m (,)d(if)i(possible,)g(otherwise,)f(open)g FK(url)h FN(in)g(the)g(only) 208 282 y(bro)n(wser)f(windo)n(w)-5 b(.)23 b(Alias)e FJ(open_new)p FN(.)0 429 y FD(open_new_tab)p FJ(\()p FK(url)p FJ(\))208 529 y FN(Open)k FK(url)h FN(in)g(a)g(ne)n(w)g(page)f (\(\224tab\224\))f(of)i(the)f(bro)n(wser)g(handled)f(by)i(this)g (controller)m(,)f(if)h(possible,)g(otherwise)f(equi)n(v)n(alent)f(to) 208 628 y FJ(open_new)p FN(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 956 y FE(18.2)121 b Fx(cgi)33 b FE(\227)f(Common)j(Gate)n(w)n(a)l(y)g (Interf)l(ace)h(suppor)5 b(t.)0 1189 y FN(Support)19 b(module)g(for)g(Common)g(Gate)n(w)o(ay)h(Interf)o(ace)f(\(CGI\))h (scripts.)0 1336 y(This)g(module)f(de\002nes)h(a)h(number)d(of)i (utilities)h(for)f(use)g(by)g(CGI)g(scripts)h(written)f(in)g(Python.)0 1620 y Fv(18.2.1)101 b(Introduction)0 1823 y FN(A)25 b(CGI)g(script)g(is)g(in)m(v)n(ok)o(ed)e(by)h(an)g(HTTP)h(serv)o(er)m (,)f(usually)g(to)h(process)f(user)g(input)g(submitted)g(through)e(an)j (HTML)f FJ(<FORM>)g FN(or)0 1923 y FJ(<ISINDEX>)19 b FN(element.)0 2070 y(Most)h(often,)e(CGI)i(scripts)g(li)n(v)o(e)f(in)h (the)f(serv)o(er')-5 b(s)19 b(special)h(`)p FO(cgi-bin)p FN(')d(directory)-5 b(.)23 b(The)c(HTTP)h(serv)o(er)e(places)i(all)g (sorts)g(of)f(information)0 2169 y(about)g(the)h(request)f(\(such)g(as) h(the)g(client')-5 b(s)20 b(hostname,)f(the)g(requested)g(URL,)h(the)g (query)e(string,)h(and)h(lots)g(of)f(other)g(goodies\))g(in)h(the)0 2269 y(script')-5 b(s)21 b(shell)f(en)m(vironment,)d(e)o(x)o(ecutes)i (the)h(script,)g(and)g(sends)g(the)g(script')-5 b(s)21 b(output)e(back)g(to)i(the)f(client.)0 2416 y(The)g(script')-5 b(s)21 b(input)f(is)h(connected)e(to)h(the)h(client)f(too,)g(and)g (sometimes)g(the)h(form)e(data)i(is)g(read)f(this)h(w)o(ay;)g(at)g (other)e(times)i(the)g(form)0 2516 y(data)i(is)h(passed)e(via)h(the)g (\223query)f(string\224)g(part)h(of)f(the)h(URL.)g(This)g(module)f(is)i (intended)d(to)i(tak)o(e)g(care)g(of)f(the)h(dif)n(ferent)e(cases)j (and)0 2615 y(pro)o(vide)d(a)j(simpler)g(interf)o(ace)e(to)i(the)f (Python)g(script.)35 b(It)24 b(also)f(pro)o(vides)f(a)i(number)e(of)h (utilities)h(that)g(help)f(in)h(deb)n(ugging)c(scripts,)0 2715 y(and)g(the)g(latest)h(addition)e(is)i(support)e(for)g(\002le)i (uploads)e(from)g(a)i(form)e(\(if)h(your)f(bro)n(wser)g(supports)g (it\).)0 2862 y(The)d(output)g(of)g(a)h(CGI)g(script)g(should)e (consist)i(of)f(tw)o(o)h(sections,)g(separated)f(by)g(a)h(blank)f (line.)24 b(The)16 b(\002rst)h(section)f(contains)g(a)h(number)0 2961 y(of)23 b(headers,)f(telling)h(the)g(client)g(what)g(kind)f(of)g (data)h(is)h(follo)n(wing.)31 b(Python)22 b(code)g(to)h(generate)f(a)h (minimal)g(header)e(section)i(looks)0 3061 y(lik)o(e)d(this:)236 3299 y FA(print)44 b("Content-Type:)f(text/html")222 b(#)45 b(HTML)f(is)g(following)236 3390 y(print)1389 b(#)45 b(blank)f(line,)g(end)g(of)h(headers)0 3677 y FN(The)24 b(second)g(section)g(is)h(usually)f(HTML,)g(which)g(allo)n (ws)h(the)f(client)h(softw)o(are)f(to)h(display)f(nicely)g(formatted)e (te)o(xt)j(with)f(header)m(,)0 3777 y(in-line)c(images,)f(etc.)26 b(Here')-5 b(s)20 b(Python)f(code)h(that)g(prints)g(a)g(simple)g(piece) g(of)g(HTML:)236 4015 y FA(print)44 b("<TITLE>CGI)f(script)h (output</TITLE>")236 4106 y(print)g("<H1>This)g(is)g(my)h(first)f(CGI)g (script</H1>")236 4197 y(print)g("Hello,)g(world!")0 4621 y Fv(18.2.2)101 b(Using)28 b(the)g(cgi)g(module)0 4824 y FN(Be)o(gin)d(by)f(writing)g(`)p FJ(import)49 b(cgi)p FN('.)38 b(Do)25 b(not)g(use)g(`)p FJ(from)48 b(cgi)i(import)2429 4839 y(*)2479 4824 y FN(')25 b(\227)h(the)f(module) e(de\002nes)i(all)g(sorts)g(of)g(names)0 4923 y(for)20 b(its)h(o)n(wn)e(use)i(or)f(for)f(backw)o(ard)g(compatibility)g(that)h (you)f(don')o(t)g(w)o(ant)h(in)g(your)f(namespace.)0 5070 y(When)h(you)f(write)i(a)f(ne)n(w)g(script,)g(consider)f(adding)g (the)h(line:)p 0 5549 3901 4 v 0 5649 a FI(602)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 603 615 TeXDict begin 603 614 bop 236 174 a FA(import)44 b(cgitb;)g (cgitb.enable\(\))0 461 y FN(This)22 b(acti)n(v)n(ates)g(a)h(special)f (e)o(xception)f(handler)f(that)j(will)f(display)g(detailed)g(reports)f (in)h(the)g(W)-7 b(eb)23 b(bro)n(wser)e(if)i(an)o(y)e(errors)g(occur)-5 b(.)31 b(If)0 560 y(you')l(d)19 b(rather)g(not)h(sho)n(w)h(the)f(guts)g (of)h(your)e(program)f(to)j(users)f(of)h(your)e(script,)h(you)g(can)g (ha)n(v)o(e)g(the)g(reports)g(sa)n(v)o(ed)g(to)h(\002les)g(instead,)0 660 y(with)f(a)h(line)f(lik)o(e)h(this:)236 898 y FA(import)44 b(cgitb;)g(cgitb.enable\(display=0,)d(logdir="/tmp"\))0 1185 y FN(It')-5 b(s)24 b(v)o(ery)e(helpful)g(to)i(use)f(this)h (feature)f(during)e(script)j(de)n(v)o(elopment.)31 b(The)23 b(reports)g(produced)e(by)i FJ(cgitb)g FN(pro)o(vide)e(information)0 1284 y(that)j(can)g(sa)n(v)o(e)g(you)f(a)h(lot)g(of)g(time)g(in)g (tracking)e(do)n(wn)h(b)n(ugs.)36 b(Y)-9 b(ou)23 b(can)g(al)o(w)o(ays)i (remo)o(v)o(e)d(the)i FJ(cgitb)f FN(line)h(later)g(when)f(you)g(ha)n(v) o(e)0 1384 y(tested)d(your)f(script)i(and)e(are)h(con\002dent)f(that)h (it)h(w)o(orks)f(correctly)-5 b(.)0 1531 y(T)e(o)19 b(get)h(at)g (submitted)e(form)g(data,)h(it')-5 b(s)21 b(best)f(to)f(use)h(the)f FJ(FieldStorage)f FN(class.)25 b(The)19 b(other)g(classes)h(de\002ned)e (in)i(this)g(module)e(are)0 1631 y(pro)o(vided)h(mostly)i(for)f(backw)o (ard)g(compatibility)-5 b(.)27 b(Instantiate)20 b(it)i(e)o(xactly)f (once,)f(without)h(ar)o(guments.)26 b(This)c(reads)f(the)g(form)f(con-) 0 1730 y(tents)i(from)f(standard)g(input)h(or)f(the)i(en)m(vironment)c (\(depending)g(on)i(the)h(v)n(alue)g(of)g(v)n(arious)f(en)m(vironment)e (v)n(ariables)i(set)i(according)0 1830 y(to)d(the)h(CGI)f(standard\).)k (Since)c(it)h(may)f(consume)e(standard)h(input,)h(it)h(should)e(be)h (instantiated)f(only)h(once.)0 1977 y(The)29 b FJ(FieldStorage)e FN(instance)h(can)h(be)g(inde)o(x)o(ed)e(lik)o(e)i(a)h(Python)d (dictionary)-5 b(,)29 b(and)f(also)i(supports)e(the)h(standard)e (dictionary)0 2076 y(methods)20 b FJ(has_key\(\))f FN(and)i FJ(keys\(\))p FN(.)26 b(The)20 b(b)n(uilt-in)h FJ(len\(\))f FN(is)i(also)f(supported.)k(F)o(orm)20 b(\002elds)h(containing)e(empty) h(strings)h(are)0 2176 y(ignored)14 b(and)h(do)h(not)f(appear)g(in)g (the)h(dictionary;)g(to)g(k)o(eep)f(such)h(v)n(alues,)g(pro)o(vide)d(a) j(true)g(v)n(alue)f(for)g(the)h(optional)e FK(k)o(eep)p 3449 2176 25 4 v 30 w(blank)p 3665 2176 V 28 w(values)0 2276 y FN(k)o(e)o(yw)o(ord)k(parameter)h(when)h(creating)f(the)h FJ(FieldStorage)e FN(instance.)0 2422 y(F)o(or)30 b(instance,)i(the)e (follo)n(wing)f(code)h(\(which)f(assumes)i(that)f(the)g FO(Content-T)-9 b(ype:)43 b FN(header)29 b(and)h(blank)f(line)h(ha)n(v) o(e)g(already)f(been)0 2522 y(printed\))19 b(checks)g(that)i(the)f (\002elds)g FJ(name)g FN(and)g FJ(addr)g FN(are)g(both)g(set)h(to)f(a)h (non-empty)c(string:)236 2760 y FA(form)44 b(=)h(cgi.FieldStorage\(\)) 236 2852 y(if)g(not)f(\(form.has_key\("name"\))d(and)k (form.has_key\("addr"\)\):)416 2943 y(print)f("<H1>Error</H1>")416 3034 y(print)g("Please)f(fill)h(in)h(the)f(name)g(and)h(addr)f (fields.")416 3126 y(return)236 3217 y(print)g("<p>name:",)f (form["name"].value)236 3308 y(print)h("<p>addr:",)f (form["addr"].value)236 3400 y(...further)g(form)i(processing)e (here...)0 3686 y FN(Here)76 b(the)g(\002elds,)90 b(accessed)75 b(through)f(`)p FJ(form[)p FK(k)o(e)n(y)p FJ(])p FN(',)88 b(are)76 b(themselv)o(es)f(instances)g(of)h FJ(FieldStorage)e FN(\(or)0 3786 y FJ(MiniFieldStorage)p FN(,)48 b(depending)41 b(on)j(the)g(form)g(encoding\).)94 b(The)44 b FJ(value)g FN(attrib)n(ute)g(of)g(the)g(instance)g(yields)h(the)0 3886 y(string)30 b(v)n(alue)f(of)h(the)g(\002eld.)54 b(The)30 b FJ(getvalue\(\))f FN(method)f(returns)h(this)i(string)f(v)n (alue)f(directly;)34 b(it)d(also)f(accepts)g(an)g(optional)0 3985 y(second)19 b(ar)o(gument)f(as)j(a)g(def)o(ault)e(to)h(return)f (if)i(the)f(requested)f(k)o(e)o(y)h(is)h(not)f(present.)0 4132 y(If)j(the)f(submitted)g(form)g(data)g(contains)g(more)g(than)g (one)g(\002eld)h(with)g(the)g(same)f(name,)h(the)g(object)f(retrie)n(v) o(ed)f(by)h(`)p FJ(form[)p FK(k)o(e)n(y)p FJ(])p FN(')f(is)0 4232 y(not)26 b(a)g FJ(FieldStorage)e FN(or)i FJ(MiniFieldStorage)e FN(instance)h(b)n(ut)h(a)h(list)g(of)e(such)h(instances.)42 b(Similarly)-5 b(,)27 b(in)f(this)g(situation,)0 4331 y(`)p FJ(form.getvalue\()p FK(k)o(e)n(y)p FJ(\))p FN(')i(w)o(ould)k (return)f(a)h(list)h(of)f(strings.)61 b(If)31 b(you)h(e)o(xpect)f(this) h(possibility)g(\(when)f(your)g(HTML)h(form)0 4431 y(contains)27 b(multiple)g(\002elds)h(with)f(the)h(same)g(name\),)g(use)f(the)h FJ(getlist\(\))e FN(function,)i(which)f(al)o(w)o(ays)h(returns)e(a)i (list)h(of)e(v)n(alues)0 4531 y(\(so)g(that)g(you)f(do)g(not)h(need)f (to)h(special-case)g(the)g(single)g(item)g(case\).)45 b(F)o(or)26 b(e)o(xample,)h(this)h(code)e(concatenates)g(an)o(y)g (number)f(of)0 4630 y(username)19 b(\002elds,)h(separated)g(by)f (commas:)236 4868 y FA(value)44 b(=)h(form.getlist\("username"\))236 4960 y(usernames)f(=)g(",".join\(value\))0 5246 y FN(If)21 b(a)h(\002eld)g(represents)e(an)i(uploaded)d(\002le,)j(accessing)g(the) f(v)n(alue)g(via)g(the)h FJ(value)f FN(attrib)n(ute)g(or)g(the)h FJ(getvalue\(\))e FN(method)g(reads)0 5346 y(the)e(entire)g(\002le)h (in)f(memory)e(as)j(a)f(string.)24 b(This)19 b(may)e(not)h(be)g(what)g (you)f(w)o(ant.)25 b(Y)-9 b(ou)17 b(can)h(test)h(for)e(an)h(uploaded)e (\002le)j(by)f(testing)g(either)p 0 5549 3901 4 v 0 5649 a FI(18.2.)52 b FJ(cgi)23 b FI(\227)g(Common)h(Gate)n(w)o(a)n(y)e (Interf)n(ace)h(suppor)s(t.)1895 b(603)p eop end %%Page: 604 616 TeXDict begin 604 615 bop 0 83 a FN(the)20 b FJ(filename)f FN(attrib)n(ute)h(or)g(the)g FJ(file)g FN(attrib)n(ute.)25 b(Y)-9 b(ou)20 b(can)g(then)f(read)h(the)g(data)g(at)h(leisure)f(from)f (the)h FJ(file)g FN(attrib)n(ute:)236 321 y FA(fileitem)44 b(=)g(form["userfile"])236 413 y(if)h(fileitem.file:)416 504 y(#)f(It's)g(an)h(uploaded)e(file;)h(count)g(lines)416 595 y(linecount)f(=)i(0)416 687 y(while)f(1:)595 778 y(line)g(=)h(fileitem.file.readline\(\))595 869 y(if)f(not)h(line:)f (break)595 960 y(linecount)f(=)i(linecount)e(+)i(1)0 1247 y FN(If)23 b(an)g(error)f(is)i(encountered)c(when)j(obtaining)e (the)i(contents)f(of)h(an)g(uploaded)e(\002le)j(\(for)e(e)o(xample,)g (when)h(the)g(user)g(interrupts)f(the)0 1347 y(form)g(submission)h(by)g (clicking)f(on)h(a)h(Back)g(or)f(Cancel)g(b)n(utton\))f(the)i FJ(done)f FN(attrib)n(ute)g(of)g(the)g(object)g(for)g(the)g(\002eld)h (will)g(be)f(set)h(to)0 1446 y(the)c(v)n(alue)g(-1.)0 1593 y(The)25 b(\002le)h(upload)e(draft)g(standard)h(entertains)f(the)i (possibility)e(of)h(uploading)e(multiple)i(\002les)h(from)f(one)f (\002eld)i(\(using)e(a)i(recursi)n(v)o(e)0 1693 y FO(m)o(ultipar)s(t/*) 20 b FN(encoding\).)27 b(When)21 b(this)h(occurs,)g(the)f(item)h(will)h (be)e(a)h(dictionary-lik)o(e)e FJ(FieldStorage)g FN(item.)29 b(This)22 b(can)f(be)h(deter)n(-)0 1792 y(mined)j(by)h(testing)g(its)h FJ(type)f FN(attrib)n(ute,)h(which)e(should)g(be)h FO(m)o(ultipar)s (t/f)n(or)r(m-data)c FN(\(or)j(perhaps)g(another)g(MIME)g(type)h (matching)0 1892 y FO(m)o(ultipar)s(t/*)p FN(\).)d(In)d(this)g(case,)h (it)g(can)f(be)g(iterated)f(o)o(v)o(er)g(recursi)n(v)o(ely)g(just)h (lik)o(e)h(the)f(top-le)n(v)o(el)f(form)g(object.)0 2039 y(When)k(a)g(form)g(is)h(submitted)e(in)h(the)g(\223old\224)g(format)f (\(as)h(the)g(query)f(string)h(or)g(as)g(a)h(single)f(data)g(part)g(of) f(type)h FO(application/x-www-)0 2138 y(f)n(or)r(m-ur)q(lencoded)p FN(\),)h(the)i(items)h(will)g(actually)f(be)h(instances)f(of)g(the)h (class)g FJ(MiniFieldStorage)p FN(.)42 b(In)26 b(this)h(case,)h(the)f FJ(list)p FN(,)0 2238 y FJ(file)p FN(,)20 b(and)f FJ(filename)h FN(attrib)n(utes)g(are)g(al)o(w)o(ays)h FJ(None)p FN(.)0 2523 y Fv(18.2.3)101 b(Higher)29 b(Le)m(v)n(el)f(Interf)m(ace)0 2726 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 2873 y(The)j(pre)n (vious)e(section)i(e)o(xplains)g(ho)n(w)f(to)i(read)e(CGI)i(form)e (data)h(using)g(the)g FJ(FieldStorage)e FN(class.)32 b(This)23 b(section)e(describes)h(a)0 2972 y(higher)i(le)n(v)o(el)g (interf)o(ace)g(which)h(w)o(as)g(added)f(to)h(this)h(class)g(to)f(allo) n(w)g(one)f(to)h(do)g(it)g(in)h(a)f(more)f(readable)g(and)g(intuiti)n (v)o(e)g(w)o(ay)-5 b(.)39 b(The)0 3072 y(interf)o(ace)25 b(doesn')o(t)f(mak)o(e)i(the)f(techniques)g(described)f(in)i(pre)n (vious)e(sections)i(obsolete)f(\227)i(the)o(y)e(are)g(still)i(useful)f (to)g(process)f(\002le)0 3172 y(uploads)19 b(ef)n(\002ciently)-5 b(,)19 b(for)g(e)o(xample.)0 3319 y(The)g(interf)o(ace)f(consists)i(of) f(tw)o(o)g(simple)g(methods.)24 b(Using)19 b(the)g(methods)f(you)g(can) h(process)g(form)f(data)h(in)g(a)h(generic)e(w)o(ay)-5 b(,)18 b(without)0 3418 y(the)i(need)g(to)g(w)o(orry)f(whether)g(only)h (one)f(or)h(more)g(v)n(alues)f(were)i(posted)e(under)g(one)h(name.)0 3565 y(In)h(the)g(pre)n(vious)f(section,)g(you)h(learned)f(to)h(write)g (follo)n(wing)f(code)g(an)o(ytime)g(you)g(e)o(xpected)g(a)h(user)g(to)h (post)f(more)f(than)h(one)f(v)n(alue)0 3665 y(under)f(one)g(name:)236 3903 y FA(item)44 b(=)h(form.getvalue\("item"\))236 3994 y(if)g(isinstance\(item,)d(list\):)416 4086 y(#)i(The)h(user)f(is)g (requesting)f(more)i(than)f(one)g(item.)236 4177 y(else:)416 4268 y(#)g(The)h(user)f(is)g(requesting)f(only)i(one)f(item.)0 4555 y FN(This)20 b(situation)g(is)h(common)e(for)g(e)o(xample)g(when)h (a)g(form)f(contains)h(a)g(group)f(of)h(multiple)f(checkbox)o(es)f (with)i(the)h(same)f(name:)236 4793 y FA(<input)44 b(type="checkbox")e (name="item")h(value="1")h(/>)236 4884 y(<input)g(type="checkbox")e (name="item")h(value="2")h(/>)0 5171 y FN(In)23 b(most)g(situations,)h (ho)n(we)n(v)o(er)m(,)e(there')-5 b(s)23 b(only)f(one)h(form)f(control) g(with)i(a)g(particular)e(name)g(in)i(a)g(form)e(and)h(then)f(you)h(e)o (xpect)f(and)0 5270 y(need)e(only)f(one)h(v)n(alue)f(associated)h(with) g(this)h(name.)j(So)d(you)e(write)h(a)h(script)f(containing)f(for)g(e)o (xample)g(this)i(code:)p 0 5549 3901 4 v 0 5649 a FI(604)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 605 617 TeXDict begin 605 616 bop 236 174 a FA(user)44 b(=)h (form.getvalue\("user"\).upper\(\))0 461 y FN(The)24 b(problem)f(with)h(the)g(code)g(is)h(that)g(you)e(should)g(ne)n(v)o(er) g(e)o(xpect)h(that)g(a)h(client)f(will)h(pro)o(vide)d(v)n(alid)i(input) g(to)g(your)f(scripts.)38 b(F)o(or)0 560 y(e)o(xample,)18 b(if)i(a)g(curious)f(user)h(appends)e(another)g(`)p FJ(user=foo)p FN(')g(pair)i(to)g(the)f(query)g(string,)g(then)g(the)h(script)g(w)o (ould)f(crash,)g(because)0 660 y(in)26 b(this)h(situation)f(the)h FJ(getvalue\("user"\))d FN(method)h(call)h(returns)g(a)h(list)g (instead)f(of)g(a)h(string.)43 b(Calling)26 b(the)h FJ(toupper\(\))0 760 y FN(method)e(on)h(a)h(list)h(is)f(not)g(v)n(alid)f(\(since)g (lists)i(do)e(not)g(ha)n(v)o(e)g(a)h(method)f(of)g(this)h(name\))f(and) g(results)g(in)h(an)g FJ(AttributeError)0 859 y FN(e)o(xception.)0 1006 y(Therefore,)16 b(the)h(appropriate)e(w)o(ay)j(to)f(read)g(form)g (data)g(v)n(alues)g(w)o(as)i(to)e(al)o(w)o(ays)h(use)g(the)f(code)g (which)g(checks)g(whether)g(the)g(obtained)0 1106 y(v)n(alue)j(is)h(a)f (single)g(v)n(alue)g(or)g(a)g(list)i(of)e(v)n(alues.)k(That')-5 b(s)20 b(anno)o(ying)e(and)i(leads)g(to)h(less)g(readable)e(scripts.)0 1253 y(A)29 b(more)e(con)m(v)o(enient)e(approach)h(is)j(to)f(use)h(the) f(methods)f FJ(getfirst\(\))g FN(and)g FJ(getlist\(\))g FN(pro)o(vided)f(by)i(this)g(higher)f(le)n(v)o(el)0 1352 y(interf)o(ace.)0 1499 y FD(getfirst)p FJ(\()p FK(name)p FC([)p FK(,)17 b(default)c FC(])p FJ(\))208 1599 y FN(This)22 b(method)g(al)o(w)o(ays)h(returns)f(only)g(one)g(v)n(alue)g(associated) g(with)h(form)f(\002eld)h FK(name)p FN(.)32 b(The)22 b(method)f(returns)h(only)g(the)h(\002rst)208 1698 y(v)n(alue)d(in)i (case)g(that)f(more)f(v)n(alues)h(were)h(posted)e(under)g(such)h(name.) 28 b(Please)22 b(note)f(that)h(the)f(order)f(in)h(which)g(the)h(v)n (alues)f(are)208 1798 y(recei)n(v)o(ed)d(may)h(v)n(ary)f(from)h(bro)n (wser)g(to)g(bro)n(wser)g(and)g(should)g(not)g(be)h(counted)e(on.)2667 1768 y FF(1)2724 1798 y FN(If)i(no)f(such)g(form)g(\002eld)h(or)f(v)n (alue)g(e)o(xists)208 1898 y(then)h(the)h(method)e(returns)h(the)h(v)n (alue)f(speci\002ed)g(by)h(the)f(optional)g(parameter)f FK(default)q FN(.)26 b(This)21 b(parameter)e(def)o(aults)i(to)g FJ(None)208 1997 y FN(if)f(not)g(speci\002ed.)0 2144 y FD(getlist)p FJ(\()p FK(name)p FJ(\))208 2244 y FN(This)f(method)e (al)o(w)o(ays)i(returns)f(a)h(list)h(of)f(v)n(alues)f(associated)h (with)g(form)e(\002eld)i FK(name)p FN(.)24 b(The)18 b(method)g(returns) g(an)h(empty)e(list)j(if)208 2343 y(no)f(such)h(form)f(\002eld)i(or)f (v)n(alue)f(e)o(xists)i(for)e FK(name)p FN(.)25 b(It)20 b(returns)f(a)i(list)g(consisting)f(of)g(one)f(item)i(if)f(only)g(one)f (such)h(v)n(alue)g(e)o(xists.)0 2490 y(Using)g(these)g(methods)g(you)f (can)h(write)g(nice)g(compact)f(code:)236 2729 y FA(import)44 b(cgi)236 2820 y(form)g(=)h(cgi.FieldStorage\(\))236 2911 y(user)f(=)h(form.getfirst\("user",)c(""\).upper\(\))178 b(#)44 b(This)h(way)f(it's)g(safe.)236 3003 y(for)h(item)f(in)g (form.getlist\("item"\):)416 3094 y(do_something\(item\))0 3519 y Fv(18.2.4)101 b(Old)27 b(classes)0 3721 y FN(These)h(classes,)j (present)c(in)i(earlier)e(v)o(ersions)h(of)f(the)h FJ(cgi)h FN(module,)f(are)g(still)h(supported)e(for)g(backw)o(ard)g (compatibility)-5 b(.)46 b(Ne)n(w)0 3821 y(applications)19 b(should)g(use)i(the)f FJ(FieldStorage)e FN(class.)0 3968 y FJ(SvFormContentDict)e FN(stores)i(single)g(v)n(alue)g(form)f (content)g(as)i(dictionary;)f(it)h(assumes)f(each)g(\002eld)h(name)e (occurs)h(in)g(the)h(form)0 4068 y(only)g(once.)0 4214 y FJ(FormContentDict)f FN(stores)i(multiple)f(v)n(alue)g(form)f (content)h(as)i(a)f(dictionary)e(\(the)h(form)g(items)h(are)g(lists)h (of)f(v)n(alues\).)k(Useful)19 b(if)0 4314 y(your)g(form)g(contains)h (multiple)f(\002elds)i(with)f(the)g(same)h(name.)0 4461 y(Other)i(classes)h(\()p FJ(FormContent)p FN(,)e FJ (InterpFormContentDict)p FN(\))e(are)j(present)f(for)h(backw)o(ards)f (compatibility)g(with)h(really)0 4561 y(old)f(applications)f(only)-5 b(.)30 b(If)22 b(you)g(still)h(use)g(these)f(and)g(w)o(ould)g(be)g (incon)m(v)o(enienced)c(when)k(the)o(y)g(disappeared)e(from)h(a)i(ne)o (xt)f(v)o(ersion)0 4660 y(of)e(this)h(module,)d(drop)h(me)h(a)h(note.)p 0 4731 1560 4 v 90 4787 a FB(1)120 4810 y FH(Note)f(that)i(some)d (recent)j(v)o(ersions)f(of)f(the)h(HTML)e(speci\002cation)k(do)d(state) i(what)f(order)f(the)h(\002eld)g(v)n(alues)h(should)e(be)h(supplied)h (in,)e(b)o(ut)g(kno)n(wing)i(whether)g(a)0 4889 y(request)c(w)o(as)g (recei)n(v)o(ed)i(from)c(a)h(conforming)i(bro)n(wser)m(,)f(or)f(e)n(v)o (en)h(from)f(a)g(bro)n(wser)h(at)f(all,)h(is)f(tedious)h(and)g(error)o (-prone.)p 0 5549 3901 4 v 0 5649 a FI(18.2.)52 b FJ(cgi)23 b FI(\227)g(Common)h(Gate)n(w)o(a)n(y)e(Interf)n(ace)h(suppor)s(t.)1895 b(605)p eop end %%Page: 606 618 TeXDict begin 606 617 bop 0 83 a Fv(18.2.5)101 b(Functions)0 286 y FN(These)29 b(are)g(useful)g(if)g(you)g(w)o(ant)g(more)g (control,)h(or)e(if)i(you)e(w)o(ant)i(to)f(emplo)o(y)f(some)h(of)g(the) g(algorithms)f(implemented)g(in)h(this)0 386 y(module)19 b(in)h(other)g(circumstances.)0 532 y FD(parse)p FJ(\()p FK(fp)p FC([)p FK(,)f(k)o(eep)p 602 532 25 4 v 29 w(blank)p 817 532 V 28 w(values)p FC([)p FK(,)h(strict)p 1309 532 V 30 w(par)o(sing)12 b FC(])g(])p FJ(\))208 632 y FN(P)o(arse)23 b(a)h(query)e(in)h(the)g(en)m(vironment)e(or)i(from)f(a)i(\002le)g (\(the)f(\002le)h(def)o(aults)e(to)i FJ(sys.stdin)p FN(\).)33 b(The)23 b FK(k)o(eep)p 3306 632 V 29 w(blank)p 3521 632 V 28 w(values)g FN(and)208 732 y FK(strict)p 383 732 V 30 w(par)o(sing)d FN(parameters)f(are)h(passed)g(to)g FJ(parse_qs\(\))f FN(unchanged.)0 879 y FD(parse_qs)p FJ(\()p FK(qs)p FC([)p FK(,)f(k)o(eep)p 760 879 V 30 w(blank)p 976 879 V 28 w(values)p FC([)p FK(,)h(strict)p 1467 879 V 31 w(par)o(sing)12 b FC(])g(])p FJ(\))208 978 y FN(P)o(arse)30 b(a)g(query)f(string)h(gi)n(v)o(en)f(as)i(a)f (string)g(ar)o(gument)e(\(data)h(of)h(type)g FO(application/x-www-f)n (or)r(m-ur)q(le)o(ncod)o(ed)o FN(\).)49 b(Data)31 b(are)208 1078 y(returned)25 b(as)i(a)g(dictionary)-5 b(.)43 b(The)26 b(dictionary)f(k)o(e)o(ys)i(are)g(the)f(unique)g(query)f(v)n(ariable)h (names)g(and)h(the)f(v)n(alues)h(are)g(lists)h(of)208 1177 y(v)n(alues)19 b(for)h(each)g(name.)208 1310 y(The)28 b(optional)g(ar)o(gument)f FK(k)o(eep)p 1167 1310 V 29 w(blank)p 1382 1310 V 28 w(values)i FN(is)h(a)f(\003ag)g(indicating)f (whether)g(blank)g(v)n(alues)g(in)h(URL)h(encoded)d(queries)208 1410 y(should)c(be)h(treated)g(as)h(blank)f(strings.)37 b(A)25 b(true)f(v)n(alue)g(indicates)g(that)g(blanks)g(should)f(be)i (retained)e(as)i(blank)e(strings.)38 b(The)208 1510 y(def)o(ault)19 b(f)o(alse)i(v)n(alue)e(indicates)h(that)g(blank)g(v)n(alues)f(are)i (to)f(be)g(ignored)e(and)i(treated)g(as)h(if)f(the)o(y)g(were)g(not)f (included.)208 1642 y(The)24 b(optional)f(ar)o(gument)g FK(strict)p 1172 1642 V 30 w(par)o(sing)h FN(is)i(a)f(\003ag)g (indicating)e(what)i(to)g(do)f(with)h(parsing)e(errors.)38 b(If)24 b(f)o(alse)i(\(the)e(def)o(ault\),)208 1742 y(errors)19 b(are)h(silently)g(ignored.)j(If)d(true,)g(errors)f(raise)i(a)g FJ(ValueError)d FN(e)o(xception.)208 1875 y(Use)i(the)h FJ(urllib.urlencode\(\))c FN(function)h(to)j(con)m(v)o(ert)d(such)i (dictionaries)f(into)h(query)f(strings.)0 2022 y FD(parse_qsl)p FJ(\()p FK(qs)p FC([)p FK(,)f(k)o(eep)p 810 2022 V 29 w(blank)p 1025 2022 V 29 w(values)p FC([)p FK(,)h(strict)p 1517 2022 V 31 w(par)o(sing)12 b FC(])g(])p FJ(\))208 2121 y FN(P)o(arse)30 b(a)g(query)f(string)h(gi)n(v)o(en)f(as)i(a)f (string)g(ar)o(gument)e(\(data)h(of)h(type)g FO(application/x-www-f)n (or)r(m-ur)q(le)o(ncod)o(ed)o FN(\).)49 b(Data)31 b(are)208 2221 y(returned)18 b(as)j(a)f(list)i(of)e(name,)f(v)n(alue)h(pairs.)208 2354 y(The)28 b(optional)g(ar)o(gument)f FK(k)o(eep)p 1167 2354 V 29 w(blank)p 1382 2354 V 28 w(values)i FN(is)h(a)f(\003ag)g (indicating)f(whether)g(blank)g(v)n(alues)g(in)h(URL)h(encoded)d (queries)208 2453 y(should)c(be)h(treated)g(as)h(blank)f(strings.)37 b(A)25 b(true)f(v)n(alue)g(indicates)g(that)g(blanks)g(should)f(be)i (retained)e(as)i(blank)e(strings.)38 b(The)208 2553 y(def)o(ault)19 b(f)o(alse)i(v)n(alue)e(indicates)h(that)g(blank)g(v)n(alues)f(are)i (to)f(be)g(ignored)e(and)i(treated)g(as)h(if)f(the)o(y)g(were)g(not)f (included.)208 2686 y(The)24 b(optional)f(ar)o(gument)g FK(strict)p 1172 2686 V 30 w(par)o(sing)h FN(is)i(a)f(\003ag)g (indicating)e(what)i(to)g(do)f(with)h(parsing)e(errors.)38 b(If)24 b(f)o(alse)i(\(the)e(def)o(ault\),)208 2785 y(errors)19 b(are)h(silently)g(ignored.)j(If)d(true,)g(errors)f(raise)i(a)g FJ(ValueError)d FN(e)o(xception.)208 2918 y(Use)i(the)h FJ(urllib.urlencode\(\))c FN(function)h(to)j(con)m(v)o(ert)d(such)i (lists)i(of)d(pairs)i(into)f(query)e(strings.)0 3065 y FD(parse_multipart)p FJ(\()p FK(fp,)f(pdict)q FJ(\))208 3165 y FN(P)o(arse)28 b(input)f(of)h(type)f FO(m)o(ultipar)s(t/f)n(or)r (m-data)d FN(\(for)j(\002le)i(uploads\).)46 b(Ar)o(guments)27 b(are)g FK(fp)i FN(for)e(the)h(input)f(\002le)i(and)f FK(pdict)h FN(for)e(a)208 3264 y(dictionary)18 b(containing)g(other)i (parameters)f(in)h(the)g FO(Content-T)-9 b(ype:)22 b FN(header)-5 b(.)208 3397 y(Returns)18 b(a)i(dictionary)d(just)j(lik)o (e)f FJ(parse_qs\(\))f FN(k)o(e)o(ys)h(are)g(the)g(\002eld)g(names,)g (each)f(v)n(alue)h(is)h(a)f(list)i(of)d(v)n(alues)h(for)f(that)i (\002eld.)208 3497 y(This)25 b(is)g(easy)g(to)g(use)g(b)n(ut)g(not)f (much)g(good)g(if)h(you)e(are)i(e)o(xpecting)e(me)o(gabytes)g(to)i(be)g (uploaded)d(\227)k(in)f(that)f(case,)j(use)e(the)208 3597 y FJ(FieldStorage)18 b FN(class)j(instead)f(which)g(is)h(much)e (more)h(\003e)o(xible.)208 3729 y(Note)g(that)g(this)h(does)f(not)f (parse)h(nested)g(multipart)f(parts)i(\227)f(use)h FJ(FieldStorage)d FN(for)i(that.)0 3876 y FD(parse_header)p FJ(\()p FK(string)p FJ(\))208 3976 y FN(P)o(arse)g(a)h(MIME)e(header)g(\(such)h(as)h FO(Content-T)-9 b(ype:)p FN(\))22 b(into)e(a)g(main)g(v)n(alue)f(and)h (a)h(dictionary)d(of)i(parameters.)0 4123 y FD(test)p FJ(\(\))208 4222 y FN(Rob)n(ust)27 b(test)h(CGI)g(script,)h(usable)e (as)h(main)f(program.)43 b(Writes)29 b(minimal)d(HTTP)i(headers)e(and)h (formats)f(all)i(information)208 4322 y(pro)o(vided)17 b(to)k(the)f(script)g(in)g(HTML)g(form.)0 4469 y FD(print_environ)p FJ(\(\))208 4568 y FN(F)o(ormat)f(the)h(shell)h(en)m(vironment)c(in)j (HTML.)0 4715 y FD(print_form)p FJ(\()p FK(form)p FJ(\))208 4815 y FN(F)o(ormat)f(a)i(form)e(in)h(HTML.)0 4962 y FD(print_directory)p FJ(\(\))208 5061 y FN(F)o(ormat)f(the)h(current)f (directory)f(in)j(HTML.)0 5208 y FD(print_environ_usage)p FJ(\(\))208 5308 y FN(Print)f(a)g(list)i(of)e(useful)f(\(used)h(by)g (CGI\))g(en)m(vironment)d(v)n(ariables)i(in)i(HTML.)p 0 5549 3901 4 v 0 5649 a FI(606)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 607 619 TeXDict begin 607 618 bop 0 83 a FD(escape)p FJ(\()p FK(s)p FC([)p FK(,)19 b(quote)12 b FC(])p FJ(\))208 183 y FN(Con)m(v)o(ert)25 b(the)i(characters)f(`)p FJ(&)p FN(',)j(`)p FJ(<)p FN(')d(and)h(`)p FJ(>)p FN(')g(in)g(string)g FK(s)h FN(to)f(HTML-safe)f(sequences.)45 b(Use)27 b(this)h(if)f(you)g (need)f(to)h(display)208 282 y(te)o(xt)19 b(that)h(might)f(contain)f (such)i(characters)f(in)g(HTML.)h(If)f(the)h(optional)e(\003ag)i FK(quote)f FN(is)h(true,)f(the)h(quotation)e(mark)h(character)208 382 y(\(`)p FJ(")p FN('\))k(is)i(also)g(translated;)h(this)f(helps)f (for)g(inclusion)f(in)h(an)h(HTML)f(attrib)n(ute)g(v)n(alue,)g(as)h(in) g FJ(<A)49 b(HREF="...">)p FN(.)36 b(If)25 b(the)208 482 y(v)n(alue)16 b(to)i(be)f(quoted)f(might)g(include)h(single-)f(or)h (double-quote)d(characters,)j(or)g(both,)g(consider)f(using)h(the)g FJ(quoteattr\(\))208 581 y FN(function)h(in)i(the)h FJ (xml.sax.saxutils)c FN(module)i(instead.)0 866 y Fv(18.2.6)101 b(Car)q(ing)29 b(about)g(secur)q(ity)0 1069 y FN(There')-5 b(s)22 b(one)h(important)e(rule:)30 b(if)24 b(you)d(in)m(v)n(ok)o(e)h (an)h(e)o(xternal)f(program)e(\(via)j(the)g FJ(os.system\(\))e FN(or)i FJ(os.popen\(\))e FN(functions.)0 1169 y(or)k(others)h(with)f (similar)h(functionality\),)f(mak)o(e)g(v)o(ery)f(sure)i(you)f(don')o (t)f(pass)i(arbitrary)e(strings)i(recei)n(v)o(ed)e(from)g(the)i(client) g(to)g(the)0 1268 y(shell.)45 b(This)27 b(is)h(a)f(well-kno)n(wn)e (security)h(hole)g(whereby)f(cle)n(v)o(er)h(hack)o(ers)g(an)o(ywhere)f (on)h(the)h(W)-7 b(eb)28 b(can)e(e)o(xploit)g(a)h(gullible)f(CGI)0 1368 y(script)d(to)g(in)m(v)n(ok)o(e)e(arbitrary)g(shell)i(commands.)31 b(Ev)o(en)22 b(parts)g(of)h(the)g(URL)g(or)f(\002eld)h(names)g(cannot)e (be)i(trusted,)g(since)g(the)f(request)0 1467 y(doesn')o(t)d(ha)n(v)o (e)g(to)i(come)e(from)g(your)g(form!)0 1614 y(T)-7 b(o)25 b(be)g(on)g(the)g(safe)h(side,)g(if)f(you)g(must)g(pass)h(a)f(string)g (gotten)f(from)g(a)i(form)e(to)h(a)h(shell)f(command,)f(you)h(should)f (mak)o(e)h(sure)g(the)0 1714 y(string)20 b(contains)f(only)h (alphanumeric)d(characters,)i(dashes,)h(underscores,)e(and)i(periods.)0 1999 y Fv(18.2.7)101 b(Installing)28 b(y)n(our)h(CGI)e(scr)q(ipt)h(on)g (a)i FQ(U)t Fi(N)t(I)t(X)i Fv(system)0 2202 y FN(Read)25 b(the)g(documentation)d(for)i(your)g(HTTP)h(serv)o(er)f(and)g(check)h (with)g(your)e(local)i(system)g(administrator)f(to)h(\002nd)f(the)h (directory)0 2301 y(where)20 b(CGI)g(scripts)h(should)e(be)h (installed;)g(usually)g(this)h(is)g(in)f(a)h(directory)d(`)p FO(cgi-bin)p FN(')g(in)j(the)f(serv)o(er)f(tree.)0 2448 y(Mak)o(e)27 b(sure)g(that)h(your)e(script)i(is)g(readable)e(and)h(e)o (x)o(ecutable)f(by)h(\223others\224;)j(the)f(U)t FH(N)t(I)t(X)i FN(\002le)d(mode)e(should)h(be)g FJ(0755)g FN(octal)h(\(use)0 2548 y(`)p FJ(chmod)49 b(0755)g FK(\002lename)p FN('\).)35 b(Mak)o(e)24 b(sure)g(that)h(the)f(\002rst)h(line)f(of)g(the)h(script)f (contains)g FJ(#!)37 b FN(starting)24 b(in)h(column)e(1)h(follo)n(wed)f (by)0 2648 y(the)d(pathname)f(of)h(the)g(Python)f(interpreter)m(,)f (for)h(instance:)236 2886 y FA(#!/usr/local/bin/python)0 3172 y FN(Mak)o(e)h(sure)g(the)g(Python)f(interpreter)g(e)o(xists)h (and)g(is)h(e)o(x)o(ecutable)d(by)i(\223others\224.)0 3319 y(Mak)o(e)31 b(sure)h(that)g(an)o(y)f(\002les)h(your)f(script)h (needs)f(to)h(read)f(or)g(write)h(are)g(readable)e(or)i(writable,)h (respecti)n(v)o(ely)-5 b(,)33 b(by)e(\223others\224)g(\227)0 3419 y(their)d(mode)g(should)g(be)g FJ(0644)h FN(for)f(readable)f(and)i FJ(0666)f FN(for)g(writable.)50 b(This)29 b(is)h(because,)f(for)g (security)f(reasons,)i(the)e(HTTP)0 3518 y(serv)o(er)e(e)o(x)o(ecutes)g (your)f(script)i(as)h(user)e(\223nobody\224,)g(without)g(an)o(y)g (special)h(pri)n(vile)o(ges.)43 b(It)28 b(can)e(only)g(read)g(\(write,) j(e)o(x)o(ecute\))c(\002les)0 3618 y(that)i(e)n(v)o(erybody)d(can)j (read)f(\(write,)i(e)o(x)o(ecute\).)44 b(The)27 b(current)e(directory)h (at)h(e)o(x)o(ecution)e(time)i(is)h(also)f(dif)n(ferent)f(\(it)h(is)h (usually)f(the)0 3718 y(serv)o(er')-5 b(s)30 b(cgi-bin)e(directory\))g (and)i(the)g(set)h(of)f(en)m(vironment)d(v)n(ariables)i(is)i(also)f (dif)n(ferent)f(from)g(what)h(you)f(get)h(when)g(you)f(log)0 3817 y(in.)51 b(In)28 b(particular)m(,)i(don')o(t)d(count)h(on)g(the)h (shell')-5 b(s)29 b(search)g(path)f(for)g(e)o(x)o(ecutables)g(\(P)-8 b(A)f(TH\))28 b(or)h(the)g(Python)e(module)h(search)g(path)0 3917 y(\(PYTHONP)-8 b(A)f(TH\))20 b(to)g(be)g(set)h(to)f(an)o(ything)f (interesting.)0 4064 y(If)g(you)f(need)g(to)h(load)f(modules)g(from)g (a)h(directory)e(which)h(is)i(not)f(on)f(Python')-5 b(s)18 b(def)o(ault)g(module)g(search)g(path,)g(you)g(can)h(change)f(the)0 4163 y(path)i(in)g(your)f(script,)h(before)f(importing)f(other)h (modules.)24 b(F)o(or)c(e)o(xample:)236 4402 y FA(import)44 b(sys)236 4493 y(sys.path.insert\(0,)e("/usr/home/joe/lib/python"\))236 4584 y(sys.path.insert\(0,)g("/usr/local/lib/python"\))0 4871 y FN(\(This)20 b(w)o(ay)-5 b(,)20 b(the)g(directory)e(inserted)i (last)h(will)g(be)f(searched)f(\002rst!\))0 5018 y(Instructions)g(for)g (non-)r(U)t FH(N)t(I)t(X)j FN(systems)e(will)h(v)n(ary;)e(check)h(your) f(HTTP)h(serv)o(er')-5 b(s)20 b(documentation)d(\(it)j(will)h(usually)f (ha)n(v)o(e)f(a)i(section)0 5117 y(on)f(CGI)g(scripts\).)p 0 5549 3901 4 v 0 5649 a FI(18.2.)52 b FJ(cgi)23 b FI(\227)g(Common)h (Gate)n(w)o(a)n(y)e(Interf)n(ace)h(suppor)s(t.)1895 b(607)p eop end %%Page: 608 620 TeXDict begin 608 619 bop 0 83 a Fv(18.2.8)101 b(T)-12 b(esting)28 b(y)n(our)g(CGI)f(scr)q(ipt)0 286 y FN(Unfortunately)-5 b(,)25 b(a)j(CGI)f(script)g(will)h(generally)d(not)i(run)f(when)g(you)g (try)h(it)h(from)e(the)h(command)e(line,)j(and)f(a)g(script)g(that)g(w) o(orks)0 386 y(perfectly)18 b(from)g(the)i(command)d(line)i(may)g(f)o (ail)h(mysteriously)e(when)g(run)h(from)f(the)h(serv)o(er)-5 b(.)25 b(There')-5 b(s)18 b(one)h(reason)g(why)f(you)h(should)0 485 y(still)j(test)f(your)e(script)h(from)g(the)g(command)e(line:)26 b(if)21 b(it)g(contains)e(a)i(syntax)f(error)m(,)f(the)h(Python)f (interpreter)g(w)o(on')o(t)g(e)o(x)o(ecute)g(it)i(at)g(all,)0 585 y(and)f(the)g(HTTP)g(serv)o(er)f(will)i(most)g(lik)o(ely)f(send)g (a)g(cryptic)g(error)f(to)h(the)g(client.)0 732 y(Assuming)f(your)g (script)i(has)f(no)g(syntax)f(errors,)g(yet)i(it)g(does)f(not)f(w)o (ork,)h(you)f(ha)n(v)o(e)h(no)f(choice)h(b)n(ut)g(to)g(read)g(the)g(ne) o(xt)g(section.)0 1017 y Fv(18.2.9)101 b(Deb)n(ugging)30 b(CGI)d(scr)q(ipts)0 1219 y FN(First)20 b(of)f(all,)h(check)f(for)f (tri)n(vial)i(installation)f(errors)f(\227)i(reading)e(the)h(section)h (abo)o(v)o(e)d(on)i(installing)g(your)f(CGI)i(script)g(carefully)e(can) 0 1319 y(sa)n(v)o(e)h(you)f(a)h(lot)g(of)g(time.)25 b(If)18 b(you)g(w)o(onder)g(whether)g(you)g(ha)n(v)o(e)g(understood)e(the)j (installation)g(procedure)d(correctly)-5 b(,)17 b(try)i(installing)f(a) 0 1419 y(cop)o(y)g(of)g(this)h(module)e(\002le)i(\(`)p FO(cgi.p)n(y)p FN('\))d(as)j(a)g(CGI)g(script.)25 b(When)18 b(in)m(v)n(ok)o(ed)f(as)i(a)g(script,)f(the)h(\002le)g(will)g(dump)e (its)i(en)m(vironment)d(and)i(the)0 1518 y(contents)k(of)g(the)g(form)f (in)h(HTML)g(form.)31 b(Gi)n(v)o(e)21 b(it)i(the)g(right)e(mode)h(etc,) h(and)e(send)h(it)h(a)g(request.)30 b(If)22 b(it')-5 b(s)24 b(installed)e(in)g(the)h(standard)0 1618 y(`)p FO(cgi-bin)p FN(')18 b(directory)-5 b(,)18 b(it)j(should)e(be)h (possible)g(to)g(send)g(it)h(a)g(request)e(by)h(entering)f(a)i(URL)f (into)g(your)f(bro)n(wser)g(of)h(the)g(form:)236 1856 y FA(http://yourhostname/cgi-bin/cgi.py?name=)o(Joe+Bl)o(ow&add)o (r=At+H)o(ome)0 2143 y FN(If)d(this)g(gi)n(v)o(es)g(an)g(error)f(of)g (type)h(404,)f(the)h(serv)o(er)f(cannot)g(\002nd)h(the)g(script)g(\226) g(perhaps)f(you)g(need)g(to)h(install)g(it)h(in)f(a)h(dif)n(ferent)d (directory)-5 b(.)0 2242 y(If)20 b(it)h(gi)n(v)o(es)e(another)g(error)m (,)f(there')-5 b(s)20 b(an)g(installation)g(problem)e(that)i(you)f (should)g(\002x)i(before)d(trying)h(to)h(go)g(an)o(y)f(further)-5 b(.)24 b(If)c(you)f(get)h(a)0 2342 y(nicely)d(formatted)f(listing)h(of) g(the)h(en)m(vironment)c(and)j(form)f(content)h(\(in)g(this)h(e)o (xample,)e(the)i(\002elds)f(should)g(be)g(listed)h(as)g(\223addr\224)e (with)0 2442 y(v)n(alue)i(\223)-7 b(At)19 b(Home\224)f(and)g (\223name\224)g(with)h(v)n(alue)f(\223Joe)g(Blo)n(w\224\),)h(the)g(`)p FO(cgi.p)n(y)p FN(')e(script)i(has)f(been)g(installed)h(correctly)-5 b(.)23 b(If)18 b(you)g(follo)n(w)g(the)0 2541 y(same)i(procedure)e(for) i(your)f(o)n(wn)g(script,)h(you)f(should)h(no)n(w)f(be)h(able)g(to)h (deb)n(ug)e(it.)0 2688 y(The)24 b(ne)o(xt)g(step)g(could)f(be)i(to)f (call)h(the)f FJ(cgi)g FN(module')-5 b(s)24 b FJ(test\(\))f FN(function)g(from)g(your)g(script:)34 b(replace)23 b(its)j(main)d (code)h(with)h(the)0 2788 y(single)20 b(statement)236 3026 y FA(cgi.test\(\))0 3312 y FN(This)g(should)g(produce)e(the)i (same)g(results)h(as)g(those)f(gotten)f(from)g(installing)h(the)g(`)p FO(cgi.p)n(y)p FN(')f(\002le)i(itself.)0 3459 y(When)j(an)g(ordinary)e (Python)h(script)i(raises)f(an)h(unhandled)c(e)o(xception)h(\(for)i (whate)n(v)o(er)e(reason:)33 b(of)24 b(a)h(typo)e(in)h(a)h(module)e (name,)h(a)0 3559 y(\002le)h(that)e(can')o(t)g(be)h(opened,)f(etc.\),)h (the)g(Python)f(interpreter)f(prints)i(a)g(nice)g(traceback)e(and)h(e)o (xits.)36 b(While)25 b(the)f(Python)e(interpreter)0 3659 y(will)h(still)h(do)e(this)h(when)f(your)g(CGI)h(script)f(raises)i(an)e (e)o(xception,)f(most)i(lik)o(ely)f(the)h(traceback)e(will)j(end)e(up)g (in)g(one)h(of)f(the)g(HTTP)0 3758 y(serv)o(er')-5 b(s)20 b(log)g(\002les,)g(or)g(be)h(discarded)d(altogether)-5 b(.)0 3905 y(F)o(ortunately)g(,)24 b(once)h(you)g(ha)n(v)o(e)g(managed) f(to)i(get)f(your)g(script)g(to)h(e)o(x)o(ecute)e FK(some)i FN(code,)g(you)f(can)g(easily)h(send)f(tracebacks)g(to)h(the)0 4005 y(W)-7 b(eb)21 b(bro)n(wser)e(using)h(the)g FJ(cgitb)g FN(module.)j(If)d(you)g(ha)n(v)o(en')o(t)e(done)h(so)i(already)-5 b(,)18 b(just)j(add)e(the)i(line:)236 4243 y FA(import)44 b(cgitb;)g(cgitb.enable\(\))0 4529 y FN(to)22 b(the)f(top)h(of)f(your)f (script.)30 b(Then)20 b(try)i(running)d(it)k(again;)e(when)g(a)h (problem)e(occurs,)h(you)g(should)f(see)j(a)f(detailed)f(report)f(that) i(will)0 4629 y(lik)o(ely)e(mak)o(e)g(apparent)e(the)j(cause)f(of)g (the)g(crash.)0 4776 y(If)d(you)f(suspect)i(that)f(there)g(may)g(be)g (a)h(problem)d(in)i(importing)f(the)h FJ(cgitb)g FN(module,)f(you)h (can)g(use)g(an)g(e)n(v)o(en)g(more)f(rob)n(ust)h(approach)0 4875 y(\(which)i(only)h(uses)g(b)n(uilt-in)g(modules\):)p 0 5549 3901 4 v 0 5649 a FI(608)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 609 621 TeXDict begin 609 620 bop 236 174 a FA(import)44 b(sys)236 266 y(sys.stderr)f(=)i(sys.stdout)236 357 y(print)f("Content-Type:)f (text/plain")236 448 y(print)236 540 y(...your)h(code)g(here...)0 826 y FN(This)24 b(relies)g(on)f(the)h(Python)e(interpreter)g(to)i (print)f(the)h(traceback.)33 b(The)24 b(content)e(type)i(of)f(the)h (output)e(is)j(set)f(to)g(plain)f(te)o(xt,)h(which)0 926 y(disables)h(all)g(HTML)f(processing.)36 b(If)25 b(your)e(script)h(w)o(orks,)h(the)g(ra)o(w)f(HTML)g(will)h(be)g (displayed)e(by)h(your)f(client.)38 b(If)24 b(it)i(raises)f(an)0 1025 y(e)o(xception,)f(most)i(lik)o(ely)f(after)g(the)g(\002rst)h(tw)o (o)f(lines)h(ha)n(v)o(e)f(been)f(printed,)h(a)h(traceback)e(will)i(be)f (displayed.)39 b(Because)25 b(no)g(HTML)0 1125 y(interpretation)18 b(is)j(going)e(on,)h(the)g(traceback)f(will)i(be)f(readable.)0 1409 y Fv(18.2.10)101 b(Common)29 b(prob)n(lems)g(and)g(solutions)125 1597 y FM(\017)41 b FN(Most)25 b(HTTP)f(serv)o(ers)h(b)n(uf)n(fer)e (the)i(output)e(from)h(CGI)h(scripts)g(until)g(the)f(script)h(is)h (completed.)37 b(This)25 b(means)f(that)h(it)g(is)h(not)208 1697 y(possible)19 b(to)i(display)e(a)i(progress)e(report)g(on)h(the)g (client')-5 b(s)21 b(display)e(while)h(the)h(script)f(is)h(running.)125 1861 y FM(\017)41 b FN(Check)19 b(the)i(installation)e(instructions)h (abo)o(v)o(e.)125 2026 y FM(\017)41 b FN(Check)19 b(the)i(HTTP)f(serv)o (er')-5 b(s)20 b(log)g(\002les.)25 b(\(`)p FJ(tail)49 b(-f)g(logfile)p FN(')19 b(in)i(a)f(separate)g(windo)n(w)f(may)h(be)g (useful!\))125 2190 y FM(\017)41 b FN(Al)o(w)o(ays)20 b(check)g(a)g(script)g(for)g(syntax)g(errors)f(\002rst,)i(by)e(doing)g (something)g(lik)o(e)h(`)p FJ(python)49 b(script.py)p FN('.)125 2354 y FM(\017)41 b FN(If)20 b(your)g(script)g(does)h(not)f (ha)n(v)o(e)g(an)o(y)g(syntax)g(errors,)g(try)h(adding)e(`)p FJ(import)48 b(cgitb;)h(cgitb.enable\(\))p FN(')18 b(to)j(the)g(top)208 2454 y(of)e(the)i(script.)125 2618 y FM(\017)41 b FN(When)18 b(in)m(v)n(oking)f(e)o(xternal)h(programs,)f(mak)o(e)h(sure)h(the)o(y)g (can)f(be)h(found.)k(Usually)-5 b(,)19 b(this)g(means)g(using)f (absolute)g(path)h(names)208 2718 y(\227)h(P)-8 b(A)f(TH)21 b(is)g(usually)f(not)g(set)h(to)f(a)h(v)o(ery)e(useful)g(v)n(alue)h(in) g(a)h(CGI)f(script.)125 2882 y FM(\017)41 b FN(When)24 b(reading)f(or)h(writing)h(e)o(xternal)e(\002les,)j(mak)o(e)e(sure)h (the)o(y)f(can)g(be)h(read)f(or)g(written)h(by)f(the)g(userid)h(under)e (which)h(your)208 2982 y(CGI)19 b(script)h(will)f(be)h(running:)i(this) e(is)g(typically)e(the)i(userid)e(under)g(which)h(the)g(web)g(serv)o (er)f(is)j(running,)c(or)i(some)g(e)o(xplicitly)208 3082 y(speci\002ed)g(userid)h(for)g(a)g(web)g(serv)o(er')-5 b(s)20 b(`)p FJ(suexec)p FN(')f(feature.)125 3246 y FM(\017)41 b FN(Don')o(t)20 b(try)i(to)g(gi)n(v)o(e)f(a)h(CGI)h(script)f(a)g (set-uid)f(mode.)30 b(This)22 b(doesn')o(t)e(w)o(ork)h(on)h(most)g (systems,)g(and)g(is)g(a)h(security)e(liability)h(as)208 3345 y(well.)0 3751 y FE(18.3)121 b Fx(cgitb)32 b FE(\227)h(T)-14 b(r)o(acebac)n(k)33 b(manager)i(f)l(or)f(CGI)g(scr)r(ipts)0 3984 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 4131 y(The)27 b FJ(cgitb)g FN(module)g(pro)o(vides)e(a)j(special)g(e)o(xception)e (handler)g(for)h(Python)f(scripts.)48 b(\(Its)28 b(name)f(is)h(a)g(bit) g(misleading.)46 b(It)28 b(w)o(as)0 4230 y(originally)23 b(designed)f(to)j(display)e(e)o(xtensi)n(v)o(e)g(traceback)g (information)e(in)k(HTML)e(for)h(CGI)h(scripts.)37 b(It)24 b(w)o(as)h(later)f(generalized)e(to)0 4330 y(also)f(display)f(this)h (information)d(in)i(plain)g(te)o(xt.\))25 b(After)20 b(this)h(module)e(is)j(acti)n(v)n(ated,)d(if)i(an)f(uncaught)f(e)o (xception)f(occurs,)i(a)g(detailed,)0 4430 y(formatted)27 b(report)h(will)i(be)f(displayed.)50 b(The)29 b(report)f(includes)g(a)i (traceback)d(sho)n(wing)h(e)o(xcerpts)g(of)h(the)g(source)f(code)h(for) f(each)0 4529 y(le)n(v)o(el,)22 b(as)g(well)g(as)h(the)f(v)n(alues)f (of)g(the)h(ar)o(guments)e(and)h(local)h(v)n(ariables)f(to)h(currently) e(running)f(functions,)i(to)h(help)f(you)g(deb)n(ug)g(the)0 4629 y(problem.)i(Optionally)-5 b(,)18 b(you)i(can)g(sa)n(v)o(e)g(this) h(information)d(to)i(a)h(\002le)f(instead)g(of)g(sending)f(it)i(to)g (the)f(bro)n(wser)-5 b(.)0 4776 y(T)e(o)20 b(enable)g(this)h(feature,)d (simply)i(add)g(one)g(line)g(to)g(the)g(top)g(of)g(your)f(CGI)i (script:)236 5014 y FA(import)44 b(cgitb;)g(cgitb.enable\(\))0 5300 y FN(The)21 b(options)f(to)h(the)g FJ(enable\(\))g FN(function)e(control)h(whether)g(the)h(report)f(is)i(displayed)e(in)i (the)f(bro)n(wser)f(and)g(whether)h(the)g(report)0 5400 y(is)g(logged)e(to)h(a)h(\002le)g(for)e(later)i(analysis.)p 0 5549 3901 4 v 0 5649 a FI(18.3.)52 b FJ(cgitb)22 b FI(\227)i(T)-10 b(r)o(acebac)n(k)22 b(manager)h(f)n(or)g(CGI)g(scr)q (ipts)1868 b(609)p eop end %%Page: 610 622 TeXDict begin 610 621 bop 0 83 a FD(enable)p FJ(\()p FC([)p FK(display)p FC([)p FK(,)18 b(lo)o(gdir)r FC([)p FK(,)h(conte)n(xt)q FC([)p FK(,)h(format)13 b FC(])f(])g(])g(])p FJ(\))208 183 y FN(This)20 b(function)e(causes)i(the)g FJ(cgitb)f FN(module)g(to)h(tak)o(e)g(o)o(v)o(er)e(the)i(interpreter') -5 b(s)19 b(def)o(ault)g(handling)f(for)h(e)o(xceptions)f(by)i(setting) 208 282 y(the)g(v)n(alue)f(of)h FJ(sys.excepthook)p FN(.)208 415 y(The)d(optional)f(ar)o(gument)g FK(display)h FN(def)o(aults)g(to)h FJ(1)h FN(and)e(can)g(be)h(set)h(to)f FJ(0)g FN(to)g(suppress)f (sending)g(the)g(traceback)g(to)h(the)f(bro)n(wser)-5 b(.)208 515 y(If)28 b(the)g(ar)o(gument)f FK(lo)o(gdir)j FN(is)f(present,)h(the)f(traceback)e(reports)g(are)i(written)f(to)h (\002les.)51 b(The)28 b(v)n(alue)g(of)g FK(lo)o(gdir)i FN(should)e(be)g(a)208 614 y(directory)23 b(where)h(these)h(\002les)g (will)h(be)e(placed.)38 b(The)25 b(optional)e(ar)o(gument)g FK(conte)n(xt)i FN(is)h(the)f(number)e(of)h(lines)h(of)g(conte)o(xt)e (to)208 714 y(display)28 b(around)e(the)j(current)f(line)g(of)h(source) f(code)g(in)h(the)f(traceback;)k(this)d(def)o(aults)g(to)f FJ(5)p FN(.)51 b(If)29 b(the)g(optional)e(ar)o(gument)208 814 y FK(format)i FN(is)f FJ("html")p FN(,)h(the)f(output)f(is)h (formatted)e(as)j(HTML.)e(An)o(y)g(other)g(v)n(alue)g(forces)g(plain)h (te)o(xt)f(output.)47 b(The)27 b(def)o(ault)208 913 y(v)n(alue)19 b(is)i FJ("html")p FN(.)0 1060 y FD(handler)p FJ(\()p FC([)p FK(info)12 b FC(])p FJ(\))208 1160 y FN(This)19 b(function)f(handles)g(an)i(e)o(xception)d(using)i(the)h(def)o(ault)e (settings)i(\(that)f(is,)i(sho)n(w)e(a)h(report)e(in)h(the)h(bro)n (wser)m(,)e(b)n(ut)h(don')o(t)f(log)208 1259 y(to)k(a)h(\002le\).)31 b(This)23 b(can)f(be)g(used)g(when)g(you')l(v)o(e)e(caught)h(an)i(e)o (xception)d(and)i(w)o(ant)g(to)h(report)e(it)i(using)f FJ(cgitb)p FN(.)31 b(The)22 b(optional)208 1359 y FK(info)g FN(ar)o(gument)e(should)h(be)h(a)h(3-tuple)e(containing)f(an)j(e)o (xception)d(type,)i(e)o(xception)f(v)n(alue,)h(and)f(traceback)g (object,)h(e)o(xactly)208 1459 y(lik)o(e)k(the)g(tuple)g(returned)f(by) h FJ(sys.exc_info\(\))p FN(.)41 b(If)26 b(the)g FK(info)g FN(ar)o(gument)e(is)k(not)d(supplied,)i(the)f(current)f(e)o(xception)g (is)208 1558 y(obtained)18 b(from)h FJ(sys.exc_info\(\))p FN(.)0 1886 y FE(18.4)121 b Fx(wsgiref)32 b FE(\227)g(WSGI)h(Utilities) g(and)h(Ref)l(erence)j(Implementation)0 2118 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2265 y(The)h(W)-7 b(eb)20 b(Serv)o(er)f(Gate)n(w)o(ay)h(Interf)o(ace)e(\(WSGI\))i(is)h(a)f (standard)f(interf)o(ace)g(between)g(web)h(serv)o(er)f(softw)o(are)h (and)f(web)h(applications)0 2365 y(written)g(in)h(Python.)26 b(Ha)n(ving)20 b(a)h(standard)e(interf)o(ace)h(mak)o(es)h(it)g(easy)g (to)g(use)g(an)f(application)g(that)g(supports)g(WSGI)h(with)g(a)g (number)0 2465 y(of)f(dif)n(ferent)e(web)j(serv)o(ers.)0 2611 y(Only)j(authors)g(of)h(web)f(serv)o(ers)g(and)h(programming)c (frame)n(w)o(orks)i(need)h(to)h(kno)n(w)f(e)n(v)o(ery)f(detail)i(and)f (corner)f(case)j(of)e(the)h(WSGI)0 2711 y(design.)54 b(Y)-9 b(ou)29 b(don')o(t)g(need)g(to)h(understand)e(e)n(v)o(ery)h (detail)h(of)g(WSGI)h(just)f(to)g(install)h(a)g(WSGI)f(application)f (or)h(to)g(write)g(a)h(web)0 2811 y(application)19 b(using)g(an)h(e)o (xisting)g(frame)n(w)o(ork.)0 2958 y FJ(wsgiref)j FN(is)j(a)e (reference)f(implementation)f(of)i(the)g(WSGI)h(speci\002cation)e(that) i(can)f(be)g(used)g(to)g(add)g(WSGI)h(support)e(to)h(a)h(web)0 3057 y(serv)o(er)f(or)g(frame)n(w)o(ork.)37 b(It)25 b(pro)o(vides)e (utilities)i(for)f(manipulating)f(WSGI)i(en)m(vironment)d(v)n(ariables) i(and)g(response)g(headers,)g(base)0 3157 y(classes)j(for)f (implementing)e(WSGI)j(serv)o(ers,)g(a)g(demo)e(HTTP)i(serv)o(er)e (that)i(serv)o(es)f(WSGI)h(applications,)f(and)g(a)h(v)n(alidation)e (tool)0 3256 y(that)20 b(checks)g(WSGI)h(serv)o(ers)e(and)h (applications)f(for)h(conformance)d(to)j(the)g(WSGI)h(speci\002cation)f (\(PEP)g(333\).)0 3403 y(See)h FO(http://www)l(.wsgi.org)16 b FN(for)j(more)h(information)d(about)j(WSGI,)g(and)g(links)g(to)g (tutorials)g(and)g(other)f(resources.)0 3688 y Fv(18.4.1)101 b Fm(wsgiref.util)25 b Fv(\226)j(WSGI)f(en)n(vironment)j(utilities)0 3891 y FN(This)g(module)f(pro)o(vides)g(a)h(v)n(ariety)g(of)f(utility)i (functions)d(for)i(w)o(orking)f(with)h(WSGI)h(en)m(vironments.)52 b(A)31 b(WSGI)g(en)m(vironment)0 3991 y(is)d(a)g(dictionary)d (containing)g(HTTP)i(request)g(v)n(ariables)f(as)i(described)e(in)h (PEP)h(333.)45 b(All)27 b(of)g(the)g(functions)f(taking)g(an)h FK(en)m(vir)l(on)0 4090 y FN(parameter)19 b(e)o(xpect)g(a)h (WSGI-compliant)f(dictionary)f(to)j(be)f(supplied;)f(please)h(see)h (PEP)g(333)e(for)h(a)g(detailed)g(speci\002cation.)0 4237 y FD(guess_scheme)p FJ(\()p FK(en)m(vir)l(on)p FJ(\))208 4337 y FN(Return)i(a)h(guess)g(for)f(whether)g FJ(wsgi.url_scheme)e FN(should)i(be)g(\223http\224)h(or)f(\223https\224,)h(by)f(checking)f (for)h(a)h FJ(HTTPS)g FN(en)m(vi-)208 4437 y(ronment)18 b(v)n(ariable)h(in)h(the)h FK(en)m(vir)l(on)e FN(dictionary)-5 b(.)23 b(The)d(return)f(v)n(alue)g(is)i(a)g(string.)208 4569 y(This)h(function)e(is)k(useful)d(when)h(creating)f(a)i(gate)n(w)o (ay)e(that)h(wraps)g(CGI)h(or)f(a)g(CGI-lik)o(e)g(protocol)f(such)h(as) h(F)o(astCGI.)f(T)-7 b(ypi-)208 4669 y(cally)i(,)18 b(serv)o(ers)h(pro) o(viding)e(such)i(protocols)f(will)i(include)f(a)g FJ(HTTPS)g FN(v)n(ariable)g(with)g(a)h(v)n(alue)f(of)g(\2231\224)g(\223yes\224,)g (or)h(\223on\224)e(when)h(a)208 4769 y(request)g(is)i(recei)n(v)o(ed)e (via)h(SSL.)h(So,)f(this)g(function)f(returns)g(\223https\224)h(if)h (such)f(a)g(v)n(alue)g(is)h(found,)d(and)i(\223http\224)f(otherwise.)0 4915 y FD(request_uri)p FJ(\()p FK(en)m(vir)l(on)e FC([)p FK(,)j(include)p 1197 4915 25 4 v 29 w(query=1)12 b FC(])p FJ(\))208 5015 y FN(Return)31 b(the)i(full)f(request)f(URI,)i (optionally)e(including)f(the)i(query)f(string,)k(using)d(the)g (algorithm)f(found)f(in)j(the)f(\223URL)208 5115 y(Reconstruction\224) 21 b(section)j(of)f(PEP)i(333.)34 b(If)24 b FK(include)p 1804 5115 V 28 w(query)g FN(is)g(f)o(alse,)h(the)f(query)e(string)i(is) g(not)g(included)e(in)i(the)f(resulting)208 5214 y(URI.)0 5361 y FD(application_uri)p FJ(\()p FK(en)m(vir)l(on)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(610)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 611 623 TeXDict begin 611 622 bop 208 83 a FN(Similar)30 b(to)h FJ(request_uri)p FN(,)h(e)o(xcept)e(that)h(the)f FJ(PATH_INFO)g FN(and)g FJ(QUERY_STRING)f FN(v)n(ariables)h(are)h(ignored.)55 b(The)208 183 y(result)20 b(is)h(the)f(base)g(URI)h(of)f(the)g (application)f(object)h(addressed)f(by)g(the)i(request.)0 330 y FD(shift_path_info)p FJ(\()p FK(en)m(vir)l(on)p FJ(\))208 429 y FN(Shift)31 b(a)h(single)f(name)g(from)f FJ(PATH_INFO)g FN(to)i FJ(SCRIPT_NAME)e FN(and)g(return)g(the)i(name.) 58 b(The)31 b FK(en)m(vir)l(on)f FN(dictionary)g(is)208 529 y FK(modi\002ed)18 b FN(in-place;)h(use)i(a)g(cop)o(y)e(if)h(you)g (need)f(to)h(k)o(eep)g(the)g(original)f FJ(PATH_INFO)g FN(or)h FJ(SCRIPT_NAME)f FN(intact.)208 662 y(If)h(there)f(are)h(no)g (remaining)f(path)g(se)o(gments)h(in)g FJ(PATH_INFO)p FN(,)f FJ(None)h FN(is)h(returned.)208 794 y(T)-7 b(ypically)i(,)32 b(this)g(routine)e(is)i(used)f(to)h(process)f(each)g(portion)f(of)h(a)g (request)g(URI)h(path,)h(for)e(e)o(xample)f(to)h(treat)h(the)f(path)208 894 y(as)22 b(a)g(series)g(of)g(dictionary)d(k)o(e)o(ys.)29 b(This)22 b(routine)f(modi\002es)g(the)h(passed-in)e(en)m(vironment)f (to)j(mak)o(e)f(it)h(suitable)g(for)f(in)m(v)n(oking)208 994 y(another)16 b(WSGI)i(application)e(that)i(is)g(located)f(at)h(the) g(tar)o(get)f(URI.)g(F)o(or)h(e)o(xample,)e(if)i(there)f(is)i(a)f(WSGI) g(application)e(at)i FJ(/foo)p FN(,)208 1093 y(and)h(the)h(request)g (URI)g(path)g(is)h FJ(/foo/bar/baz)p FN(,)d(and)i(the)g(WSGI)h (application)e(at)h FJ(/foo)g FN(calls)h FJ(shift_path_info)p FN(,)208 1193 y(it)32 b(will)h(recei)n(v)o(e)e(the)h(string)f (\223bar\224,)j(and)e(the)g(en)m(vironment)d(will)j(be)g(updated)f(to)h (be)g(suitable)f(for)h(passing)f(to)h(a)h(WSGI)208 1293 y(application)19 b(at)j FJ(/foo/bar)p FN(.)27 b(That)21 b(is,)h FJ(SCRIPT_NAME)e FN(will)i(change)e(from)g FJ(/foo)h FN(to)h FJ(/foo/bar)p FN(,)e(and)h FJ(PATH_INFO)208 1392 y FN(will)f(change)f(from)h FJ(/bar/baz)f FN(to)h FJ(/baz)p FN(.)208 1525 y(When)f FJ(PATH_INFO)f FN(is)i(just)g(a)g(\223/\224,)f (this)h(routine)e(returns)g(an)i(empty)e(string)h(and)g(appends)f(a)h (trailing)g(slash)h(to)f FJ(SCRIPT_-)208 1625 y(NAME)p FN(,)h(e)n(v)o(en)g(though)f(empty)h(path)h(se)o(gments)f(are)h (normally)e(ignored,)g(and)i FJ(SCRIPT_NAME)e FN(doesn')o(t)g(normally) h(end)g(in)h(a)208 1724 y(slash.)30 b(This)22 b(is)h(intentional)d (beha)n(vior)m(,)g(to)i(ensure)f(that)h(an)g(application)e(can)i(tell)g (the)g(dif)n(ference)e(between)g(URIs)j(ending)d(in)208 1824 y FJ(/x)g FN(from)f(ones)h(ending)f(in)h FJ(/x/)g FN(when)g(using)g(this)g(routine)f(to)i(do)e(object)h(tra)n(v)o(ersal.) 0 1971 y FD(setup_testing_defaults)p FJ(\()p FK(en)m(vir)l(on)p FJ(\))208 2070 y FN(Update)f FK(en)m(vir)l(on)g FN(with)i(tri)n(vial)f (def)o(aults)g(for)f(testing)h(purposes.)208 2203 y(This)d(routine)f (adds)h(v)n(arious)f(parameters)g(required)f(for)h(WSGI,)i(including)d FJ(HTTP_HOST)p FN(,)h FJ(SERVER_NAME)p FN(,)f FJ(SERVER_-)208 2303 y(PORT)p FN(,)g FJ(REQUEST_METHOD)p FN(,)g FJ(SCRIPT_NAME)p FN(,)f FJ(PATH_INFO)p FN(,)h(and)h(all)h(of)f(the)g(PEP)h (333-de\002ned)d FJ(wsgi.)3516 2318 y(*)3582 2303 y FN(v)n(ariables.) 208 2402 y(It)20 b(only)f(supplies)h(def)o(ault)g(v)n(alues,)f(and)h (does)g(not)g(replace)f(an)o(y)h(e)o(xisting)f(settings)h(for)g(these)g (v)n(ariables.)208 2535 y(This)30 b(routine)f(is)i(intended)d(to)i(mak) o(e)g(it)h(easier)f(for)f(unit)h(tests)h(of)f(WSGI)h(serv)o(ers)e(and)h (applications)f(to)h(set)h(up)e(dummy)208 2635 y(en)m(vironments.)22 b(It)e(should)f(NO)m(T)h(be)h(used)e(by)h(actual)g(WSGI)h(serv)o(ers)f (or)g(applications,)e(since)j(the)f(data)g(is)h(f)o(ak)o(e!)0 2782 y(In)e(addition)g(to)g(the)h(en)m(vironment)c(functions)i(abo)o(v) o(e,)g(the)i FJ(wsgiref.util)e FN(module)g(also)i(pro)o(vides)d(these)j (miscellaneous)f(utili-)0 2881 y(ties:)0 3028 y FD(is_hop_by_hop)p FJ(\()p FK(header)p 937 3028 25 4 v 26 w(name)p FJ(\))208 3128 y FN(Return)g(true)h(if)h('header)p 932 3128 V 27 w(name')f(is)h(an)f(HTTP/1.1)f(\223Hop-by-Hop\224)e(header)m(,)h(as)j (de\002ned)e(by)h(RFC)i(2616.)0 3275 y FL(class)f FD(FileWrapper)p FJ(\()p FK(\002lelik)o(e)d FC([)p FK(,)i(blksize=8192)12 b FC(])p FJ(\))208 3374 y FN(A)26 b(wrapper)e(to)i(con)m(v)o(ert)d(a)k (\002le-lik)o(e)e(object)g(to)h(an)g(iterator)-5 b(.)41 b(The)25 b(resulting)g(objects)h(support)e(both)h FJ(__getitem__)f FN(and)208 3474 y FJ(__iter__)h FN(iteration)h(styles,)i(for)e (compatibility)f(with)i(Python)e(2.1)h(and)g(Jython.)43 b(As)27 b(the)g(object)f(is)h(iterated)f(o)o(v)o(er)m(,)h(the)208 3574 y(optional)19 b FK(blksize)i FN(parameter)e(will)i(be)f (repeatedly)f(passed)i(to)f(the)h FK(\002lelik)o(e)f FN(object')-5 b(s)21 b FJ(read\(\))f FN(method)f(to)h(obtain)g(strings) g(to)208 3673 y(yield.)k(When)c FJ(read\(\))g FN(returns)f(an)h(empty)f (string,)h(iteration)g(is)h(ended)e(and)g(is)i(not)f(resumable.)208 3806 y(If)f FK(\002lelik)o(e)g FN(has)h(a)g FJ(close\(\))f FN(method,)f(the)h(returned)f(object)h(will)h(also)g(ha)n(v)o(e)f(a)g FJ(close\(\))g FN(method,)f(and)h(it)h(will)g(in)m(v)n(ok)o(e)f(the)208 3906 y FK(\002lelik)o(e)h FN(object')-5 b(s)20 b FJ(close\(\))f FN(method)g(when)h(called.)0 4191 y Fv(18.4.2)101 b Fm(wsgiref.headers) 24 b Fv(\226)k(WSGI)f(response)j(header)g(tools)0 4394 y FN(This)i(module)f(pro)o(vides)f(a)j(single)f(class,)j FJ(Headers)p FN(,)f(for)e(con)m(v)o(enient)d(manipulation)h(of)i(WSGI)g (response)f(headers)h(using)f(a)0 4493 y(mapping-lik)o(e)18 b(interf)o(ace.)0 4640 y FL(class)j FD(Headers)p FJ(\()p FK(header)o(s)p FJ(\))208 4740 y FN(Create)h(a)g(mapping-lik)o(e)d (object)j(wrapping)e FK(header)o(s)p FN(,)h(which)h(must)g(be)g(a)g (list)h(of)f(header)e(name/v)n(alue)g(tuples)i(as)h(described)208 4839 y(in)e(PEP)g(333.)26 b(An)o(y)20 b(changes)g(made)g(to)h(the)g(ne) n(w)g FJ(Headers)f FN(object)g(will)i(directly)e(update)g(the)h FK(header)o(s)f FN(list)i(it)g(w)o(as)f(created)208 4939 y(with.)208 5072 y FJ(Headers)36 b FN(objects)h(support)e(typical)i (mapping)e(operations)g(including)h FJ(__getitem__)p FN(,)j FJ(get)p FN(,)i FJ(__setitem__-)208 5171 y FN(,)31 b FJ(setdefault)p FN(,)f FJ(__delitem__)p FN(,)f FJ(__contains__)e FN(and)h FJ(has_key)p FN(.)51 b(F)o(or)28 b(each)h(of)g(these)g (methods,)g(the)g(k)o(e)o(y)g(is)208 5271 y(the)24 b(header)f(name)h (\(treated)g(case-insensiti)n(v)o(ely\),)g(and)g(the)g(v)n(alue)g(is)i (the)e(\002rst)h(v)n(alue)f(associated)h(with)f(that)h(header)e(name.) 208 5371 y(Setting)i(a)i(header)e(deletes)h(an)o(y)f(e)o(xisting)h(v)n (alues)f(for)h(that)g(header)m(,)g(then)f(adds)h(a)h(ne)n(w)f(v)n(alue) f(at)i(the)f(end)f(of)h(the)g(wrapped)p 0 5549 3901 4 v 0 5649 a FI(18.4.)52 b FJ(wsgiref)22 b FI(\227)h(WSGI)h(Utilities)g (and)g(Ref)n(erence)e(Implementation)1383 b(611)p eop end %%Page: 612 624 TeXDict begin 612 623 bop 208 83 a FN(header)20 b(list.)29 b(Headers')21 b(e)o(xisting)f(order)h(is)h(generally)e(maintained,)g (with)h(ne)n(w)g(headers)g(added)f(to)i(the)f(end)g(of)g(the)g(wrapped) 208 183 y(list.)208 315 y(Unlik)o(e)g(a)h(dictionary)-5 b(,)19 b FJ(Headers)i FN(objects)h(do)f(not)g(raise)h(an)f(error)g (when)g(you)f(try)i(to)g(get)f(or)h(delete)f(a)h(k)o(e)o(y)f(that)h (isn')o(t)f(in)h(the)208 415 y(wrapped)i(header)i(list.)45 b(Getting)26 b(a)h(none)o(xistent)d(header)h(just)i(returns)f FJ(None)p FN(,)i(and)e(deleting)f(a)i(none)o(xistent)e(header)g(does) 208 515 y(nothing.)208 648 y FJ(Headers)20 b FN(objects)i(also)f (support)f FJ(keys\(\))p FN(,)h FJ(values\(\))p FN(,)g(and)g FJ(items\(\))g FN(methods.)27 b(The)22 b(lists)g(returned)e(by)h FJ(keys\(\))208 747 y FN(and)26 b FJ(items\(\))h FN(can)g(include)g (the)g(same)h(k)o(e)o(y)f(more)f(than)h(once)g(if)h(there)f(is)h(a)g (multi-v)n(alued)d(header)-5 b(.)46 b(The)27 b FJ(len\(\))g FN(of)g(a)208 847 y FJ(Headers)f FN(object)g(is)i(the)f(same)g(as)h (the)f(length)f(of)h(its)h FJ(items\(\))p FN(,)g(which)e(is)i(the)f (same)h(as)f(the)g(length)f(of)h(the)g(wrapped)208 946 y(header)19 b(list.)26 b(In)19 b(f)o(act,)i(the)f FJ(items\(\))f FN(method)g(just)i(returns)e(a)i(cop)o(y)e(of)h(the)g(wrapped)f(header) g(list.)208 1079 y(Calling)26 b FJ(str\(\))g FN(on)g(a)h FJ(Headers)f FN(object)g(returns)g(a)h(formatted)d(string)j(suitable)f (for)g(transmission)g(as)h(HTTP)g(response)208 1179 y(headers.)c(Each) 18 b(header)f(is)i(placed)f(on)g(a)g(line)h(with)f(its)i(v)n(alue,)d (separated)h(by)g(a)g(colon)g(and)f(a)i(space.)24 b(Each)18 b(line)h(is)g(terminated)208 1279 y(by)g(a)i(carriage)e(return)g(and)h (line)g(feed,)f(and)h(the)g(string)g(is)h(terminated)e(with)h(a)h (blank)e(line.)208 1411 y(In)h(addition)f(to)h(their)g(mapping)e (interf)o(ace)i(and)g(formatting)e(features,)h FJ(Headers)h FN(objects)g(also)h(ha)n(v)o(e)e(the)i(follo)n(wing)d(meth-)208 1511 y(ods)i(for)f(querying)f(and)i(adding)e(multi-v)n(alued)g (headers,)i(and)f(for)h(adding)e(headers)i(with)g(MIME)g(parameters:) 208 1644 y FD(get_all)p FJ(\()p FK(name)p FJ(\))390 1743 y FN(Return)g(a)h(list)g(of)f(all)h(the)f(v)n(alues)g(for)f(the)h (named)f(header)-5 b(.)390 1860 y(The)22 b(returned)e(list)j(will)f(be) g(sorted)g(in)g(the)g(order)e(the)o(y)h(appeared)g(in)h(the)f(original) g(header)g(list)i(or)f(were)f(added)g(to)h(this)390 1959 y(instance,)c(and)f(may)g(contain)g(duplicates.)23 b(An)o(y)17 b(\002elds)h(deleted)f(and)g(re-inserted)f(are)i(al)o(w)o(ays)g (appended)d(to)j(the)g(header)390 2059 y(list.)26 b(If)20 b(no)g(\002elds)h(e)o(xist)f(with)g(the)h(gi)n(v)o(en)e(name,)g (returns)g(an)h(empty)g(list.)208 2192 y FD(add_header)p FJ(\()p FK(name)o(,)d(value)o(,)j(**)p 1286 2192 25 4 v 28 w(par)o(ams)p FJ(\))390 2291 y FN(Add)g(a)h(\(possibly)e(multi-v)n (alued\))e(header)m(,)i(with)h(optional)f(MIME)h(parameters)f (speci\002ed)h(via)g(k)o(e)o(yw)o(ord)e(ar)o(guments.)390 2408 y FK(name)23 b FN(is)h(the)f(header)f(\002eld)h(to)h(add.)33 b(K)n(e)o(yw)o(ord)21 b(ar)o(guments)g(can)i(be)g(used)g(to)h(set)f (MIME)g(parameters)f(for)h(the)g(header)390 2507 y(\002eld.)i(Each)19 b(parameter)f(must)i(be)g(a)g(string)f(or)h FJ(None)p FN(.)k(Underscores)18 b(in)i(parameter)e(names)i(are)f(con)m(v)o(erted) e(to)j(dashes,)390 2607 y(since)29 b(dashes)f(are)g(ille)o(gal)g(in)h (Python)e(identi\002ers,)j(b)n(ut)e(man)o(y)f(MIME)h(parameter)f(names) h(include)f(dashes.)49 b(If)29 b(the)390 2707 y(parameter)17 b(v)n(alue)h(is)h(a)g(string,)f(it)h(is)g(added)f(to)g(the)g(header)g (v)n(alue)f(parameters)g(in)i(the)f(form)g FJ(name="value")p FN(.)k(If)d(it)g(is)390 2806 y FJ(None)p FN(,)j(only)f(the)g(parameter) g(name)g(is)h(added.)29 b(\(This)21 b(is)i(used)e(for)h(MIME)f (parameters)f(without)h(a)h(v)n(alue.\))29 b(Example)390 2906 y(usage:)626 3022 y FA(h.add_header\('content-disposition',)39 b('attachment',)k(filename='bud.gif'\))390 3195 y FN(The)20 b(abo)o(v)o(e)f(will)i(add)e(a)i(header)e(that)h(looks)g(lik)o(e)g (this:)626 3311 y FA(Content-Disposition:)42 b(attachment;)h (filename="bud.gif")0 3653 y Fv(18.4.3)101 b Fm(wsgiref.simple_server) 23 b Fv(\226)28 b(a)g(simple)g(WSGI)g(HTTP)f(ser)s(v)n(er)0 3856 y FN(This)20 b(module)f(implements)g(a)h(simple)g(HTTP)g(serv)o (er)f(\(based)h(on)f FJ(BaseHTTPServer)p FN(\))f(that)i(serv)o(es)g (WSGI)g(applications.)k(Each)0 3955 y(serv)o(er)d(instance)g(serv)o(es) h(a)g(single)g(WSGI)g(application)f(on)g(a)h(gi)n(v)o(en)f(host)h(and)f (port.)29 b(If)22 b(you)e(w)o(ant)i(to)g(serv)o(e)g(multiple)f (applications)0 4055 y(on)g(a)h(single)g(host)g(and)f(port,)g(you)g (should)f(create)i(a)g(WSGI)g(application)f(that)g(parses)h FJ(PATH_INFO)f FN(to)h(select)g(which)f(application)0 4155 y(to)f(in)m(v)n(ok)o(e)f(for)h(each)g(request.)k(\(E.g.,)19 b(using)h(the)g FJ(shift_path_info\(\))d FN(function)i(from)g FJ(wsgiref.util)p FN(.\))0 4301 y FD(make_server)p FJ(\()p FK(host,)f(port,)i(app)f FC([)p FK(,)h(server)p 1396 4301 V 31 w(class=)p Fn(WSGIServer)h FC([)p FK(,)g(handler)p 2512 4301 V 28 w(class=)p Fn(WSGIRequestHandler)12 b FC(])g(])p FJ(\))208 4401 y FN(Create)26 b(a)h(ne)n(w)f(WSGI)h(serv)o (er)f(listening)g(on)g FK(host)h FN(and)f FK(port)q FN(,)i(accepting)e (connections)e(for)i FK(app)p FN(.)42 b(The)26 b(return)g(v)n(alue)f (is)j(an)208 4501 y(instance)18 b(of)h(the)g(supplied)f FK(server)p 1222 4501 V 31 w(class)p FN(,)i(and)e(will)i(process)f (requests)g(using)f(the)h(speci\002ed)g FK(handler)p 3204 4501 V 28 w(class)p FN(.)26 b FK(app)18 b FN(must)h(be)g(a)208 4600 y(WSGI)h(application)f(object,)h(as)g(de\002ned)g(by)f(PEP)i(333.) 208 4733 y(Example)d(usage:)p 0 5549 3901 4 v 0 5649 a FI(612)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 613 625 TeXDict begin 613 624 bop 444 83 a FA(from)44 b(wsgiref.simple_server)d (import)j(make_server,)f(demo_app)444 266 y(httpd)h(=)g (make_server\('',)f(8000,)h(demo_app\))444 357 y(print)g("Serving)f (HTTP)h(on)h(port)f(8000...")444 540 y(#)g(Respond)g(to)h(requests)e (until)h(process)g(is)g(killed)444 631 y(httpd.serve_forever\(\))444 814 y(#)g(Alternative:)f(serve)h(one)h(request,)e(then)h(exit)444 905 y(##httpd.handle_request\(\))0 1106 y FD(demo_app)p FJ(\()p FK(en)m(vir)l(on,)17 b(start)p 893 1106 25 4 v 31 w(r)m(esponse)p FJ(\))208 1206 y FN(This)k(function)g(is)h(a)g (small)h(b)n(ut)e(complete)g(WSGI)i(application)d(that)i(returns)f(a)h (te)o(xt)f(page)g(containing)f(the)i(message)g(\223Hello)208 1306 y(w)o(orld!\224)h(and)c(a)h(list)g(of)f(the)h(k)o(e)o(y/v)n(alue)d (pairs)j(pro)o(vided)c(in)k(the)f FK(en)m(vir)l(on)g FN(parameter)-5 b(.)23 b(It')-5 b(s)20 b(useful)f(for)g(v)o(erifying)e (that)i(a)h(WSGI)208 1405 y(serv)o(er)f(\(such)g(as)i FJ(wsgiref.simple_server)p FN(\))c(is)k(able)f(to)g(run)g(a)g(simple)h (WSGI)f(application)f(correctly)-5 b(.)0 1552 y FL(class)21 b FD(WSGIServer)p FJ(\()p FK(server)p 949 1552 V 28 w(addr)m(ess,)f (RequestHandlerClass)p FJ(\))208 1652 y FN(Create)h(a)g FJ(WSGIServer)e FN(instance.)26 b FK(server)p 1555 1652 V 30 w(addr)m(ess)21 b FN(should)f(be)g(a)h FJ(\(host,port\))f FN(tuple,)g(and)g FK(RequestHandlerClass)208 1751 y FN(should)26 b(be)h(the)g(subclass)g(of)g FJ(BaseHTTPServer.BaseHTTPRequestHandl)o (er)22 b FN(that)27 b(will)h(be)f(used)g(to)g(process)208 1851 y(requests.)208 1984 y(Y)-9 b(ou)21 b(do)h(not)f(normally)g(need)g (to)h(call)h(this)f(constructor)m(,)e(as)j(the)f FJ(make_server\(\))e FN(function)h(can)h(handle)f(all)h(the)g(details)208 2083 y(for)d(you.)208 2216 y FJ(WSGIServer)i FN(is)j(a)g(subclass)f(of) f FJ(BaseHTTPServer.HTTPServer)p FN(,)e(so)j(all)h(of)e(its)i(methods)e (\(such)h(as)g FJ(serve_-)208 2316 y(forever\(\))29 b FN(and)g FJ(handle_request\(\))p FN(\))e(are)j(a)n(v)n(ailable.)55 b FJ(WSGIServer)29 b FN(also)h(pro)o(vides)e(these)j(WSGI-speci\002c) 208 2415 y(methods:)208 2548 y FD(set_app)p FJ(\()p FK(application)p FJ(\))390 2648 y FN(Sets)21 b(the)g(callable)f FK(application)e FN(as)i(the)h(WSGI)g(application)d(that)i(will)h(recei)n(v)o(e)f (requests.)208 2781 y FD(get_app)p FJ(\(\))390 2880 y FN(Returns)g(the)g(currently-set)f(application)f(callable.)208 3013 y(Normally)-5 b(,)27 b(ho)n(we)n(v)o(er)m(,)g(you)g(do)g(not)g (need)g(to)h(use)g(these)g(additional)e(methods,)i(as)g FJ(set_app\(\))f FN(is)i(normally)d(called)h(by)208 3113 y FJ(make_server\(\))p FN(,)18 b(and)h(the)h FJ(get_app\(\))g FN(e)o(xists)g(mainly)g(for)f(the)h(bene\002t)g(of)g(request)g(handler) e(instances.)0 3260 y FL(class)j FD(WSGIRequestHandler)p FJ(\()p FK(r)m(equest,)16 b(client)p 1606 3260 V 29 w(addr)m(ess,)k (server)r FJ(\))208 3359 y FN(Create)j(an)g(HTTP)g(handler)e(for)h(the) h(gi)n(v)o(en)f FK(r)m(equest)i FN(\(i.e.)33 b(a)24 b(sock)o(et\),)f FK(client)p 2467 3359 V 29 w(addr)m(ess)g FN(\(a)g FJ(\()p FK(host)q FJ(,)p FK(port)q FJ(\))g FN(tuple\),)f(and)h FK(server)208 3459 y FN(\()p FJ(WSGIServer)18 b FN(instance\).)208 3592 y(Y)-9 b(ou)39 b(do)g(not)h(need)f(to)h(create)f(instances)h(of)g (this)g(class)h(directly;)49 b(the)o(y)39 b(are)h(automatically)e (created)h(as)h(needed)f(by)208 3691 y FJ(WSGIServer)22 b FN(objects.)35 b(Y)-9 b(ou)23 b(can,)h(ho)n(we)n(v)o(er)m(,)e (subclass)h(this)i(class)f(and)f(supply)g(it)h(as)g(a)g FK(handler)p 3173 3691 V 29 w(class)g FN(to)g(the)f FJ(make_-)208 3791 y(server\(\))c FN(function.)k(Some)d(possibly)f(rele)n(v)n(ant)g (methods)h(for)f(o)o(v)o(erriding)e(in)k(subclasses:)208 3924 y FD(get_environ)p FJ(\(\))390 4024 y FN(Returns)i(a)g(dictionary) e(containing)f(the)j(WSGI)g(en)m(vironment)d(for)i(a)h(request.)31 b(The)23 b(def)o(ault)e(implementation)g(copies)390 4123 y(the)28 b(contents)f(of)g(the)h FJ(WSGIServer)e FN(object')-5 b(s)27 b FJ(base_environ)f FN(dictionary)g(attrib)n(ute)h(and)g(then)g (adds)h(v)n(arious)390 4223 y(headers)16 b(deri)n(v)o(ed)f(from)g(the)h (HTTP)h(request.)23 b(Each)16 b(call)h(to)g(this)g(method)e(should)g (return)h(a)g(ne)n(w)h(dictionary)d(containing)390 4322 y(all)21 b(of)f(the)g(rele)n(v)n(ant)f(CGI)i(en)m(vironment)c(v)n (ariables)i(as)i(speci\002ed)f(in)g(PEP)h(333.)208 4455 y FD(get_stderr)p FJ(\(\))390 4555 y FN(Return)29 b(the)g(object)g (that)h(should)e(be)h(used)h(as)g(the)f FJ(wsgi.errors)f FN(stream.)52 b(The)29 b(def)o(ault)g(implementation)e(just)390 4655 y(returns)20 b FJ(sys.stderr)p FN(.)208 4787 y FD(handle)p FJ(\(\))390 4887 y FN(Process)60 b(the)f(HTTP)g(request.)142 b(The)59 b(def)o(ault)f(implementation)g(creates)h(a)h(handler)d (instance)i(using)g(a)390 4987 y FJ(wsgiref.handlers)18 b FN(class)j(to)f(implement)f(the)i(actual)f(WSGI)g(application)f (interf)o(ace.)p 0 5549 3901 4 v 0 5649 a FI(18.4.)52 b FJ(wsgiref)22 b FI(\227)h(WSGI)h(Utilities)g(and)g(Ref)n(erence)e (Implementation)1383 b(613)p eop end %%Page: 614 626 TeXDict begin 614 625 bop 0 83 a Fv(18.4.4)101 b Fm(wsgiref.validate)24 b Fv(\226)k(WSGI)f(conf)m(or)r(mance)j(chec)n(k)n(er)0 286 y FN(When)17 b(creating)g(ne)n(w)g(WSGI)h(application)e(objects,)h (frame)n(w)o(orks,)f(serv)o(ers,)h(or)g(middle)n(w)o(are,)g(it)h(can)f (be)g(useful)g(to)h(v)n(alidate)e(the)i(ne)n(w)0 386 y(code')-5 b(s)25 b(conformance)d(using)j FJ(wsgiref.validate)p FN(.)38 b(This)25 b(module)f(pro)o(vides)g(a)i(function)d(that)j (creates)f(WSGI)h(application)0 485 y(objects)h(that)g(v)n(alidate)f (communications)e(between)i(a)i(WSGI)f(serv)o(er)f(or)h(gate)n(w)o(ay)f (and)g(a)h(WSGI)h(application)e(object,)h(to)g(check)0 585 y(both)19 b(sides)i(for)f(protocol)e(conformance.)0 732 y(Note)24 b(that)h(this)g(utility)f(does)g(not)g(guarantee)f (complete)g(PEP)i(333)e(compliance;)i(an)f(absence)g(of)g(errors)g (from)f(this)i(module)e(does)0 831 y(not)c(necessarily)f(mean)g(that)h (errors)g(do)f(not)h(e)o(xist.)24 b(Ho)n(we)n(v)o(er)m(,)18 b(if)h(this)g(module)f(does)h(produce)e(an)i(error)m(,)e(then)i(it)g (is)h(virtually)e(certain)0 931 y(that)i(either)g(the)g(serv)o(er)g(or) g(application)e(is)j(not)f(100\045)g(compliant.)0 1078 y(This)g(module)f(is)i(based)f(on)g(the)g FJ(paste.lint)f FN(module)g(from)g(Ian)h(Bicking')-5 b(s)20 b(\223Python)f(P)o (aste\224)h(library)-5 b(.)0 1225 y FD(validator)p FJ(\()p FK(application)p FJ(\))208 1324 y FN(Wrap)19 b FK(application)f FN(and)i(return)e(a)j(ne)n(w)f(WSGI)g(application)f(object.)24 b(The)c(returned)e(application)g(will)j(forw)o(ard)d(all)j(requests)208 1424 y(to)e(the)h(original)e FK(application)p FN(,)f(and)i(will)i (check)d(that)i(both)f(the)g FK(application)f FN(and)h(the)g(serv)o(er) g(in)m(v)n(oking)e(it)j(are)g(conforming)c(to)208 1524 y(the)k(WSGI)h(speci\002cation)e(and)h(to)g(RFC)i(2616.)208 1655 y(An)o(y)j(detected)h(nonconformance)21 b(results)27 b(in)g(an)f FJ(AssertionError)e FN(being)h(raised;)30 b(note,)d(ho)n(we)n(v)o(er)m(,)e(that)i(ho)n(w)e(these)208 1755 y(errors)17 b(are)h(handled)f(is)i(serv)o(er)n(-dependent.)i(F)o (or)c(e)o(xample,)g FJ(wsgiref.simple_server)e FN(and)j(other)f(serv)o (ers)h(based)g(on)208 1854 y FJ(wsgiref.handlers)c FN(\(that)i(don')o (t)g(o)o(v)o(erride)e(the)j(error)f(handling)e(methods)i(to)h(do)f (something)g(else\))h(will)g(simply)g(output)208 1954 y(a)j(message)g(that)g(an)h(error)e(has)h(occurred,)e(and)i(dump)f(the) h(traceback)f(to)h FJ(sys.stderr)f FN(or)h(some)g(other)f(error)g (stream.)208 2086 y(This)f(wrapper)e(may)i(also)g(generate)f(output)g (using)h(the)g FJ(warnings)f FN(module)g(to)h(indicate)f(beha)n(viors)g (that)h(are)g(questionable)208 2185 y(b)n(ut)28 b(which)f(may)h(not)f (actually)h(be)g(prohibited)e(by)h(PEP)i(333.)48 b(Unless)28 b(the)o(y)g(are)g(suppressed)e(using)i(Python)f(command-)208 2285 y(line)20 b(options)g(or)g(the)g FJ(warnings)g FN(API,)h(an)o(y)e (such)i(w)o(arnings)e(will)i(be)g(written)f(to)h FJ(sys.stderr)e FN(\()p FK(not)i FJ(wsgi.errors)p FN(,)208 2384 y(unless)f(the)o(y)f (happen)g(to)h(be)g(the)h(same)f(object\).)0 2668 y Fv(18.4.5)101 b Fm(wsgiref.handlers)24 b Fv(\226)k(ser)s(v)n(er/gate)n(w)o(a)m(y)g (base)h(classes)0 2871 y FN(This)22 b(module)e(pro)o(vides)g(base)i (handler)f(classes)i(for)e(implementing)e(WSGI)k(serv)o(ers)e(and)g (gate)n(w)o(ays.)29 b(These)22 b(base)g(classes)h(handle)0 2971 y(most)c(of)f(the)g(w)o(ork)g(of)g(communicating)e(with)j(a)g (WSGI)g(application,)e(as)i(long)f(as)h(the)o(y)f(are)g(gi)n(v)o(en)g (a)h(CGI-lik)o(e)f(en)m(vironment,)e(along)0 3070 y(with)k(input,)g (output,)e(and)i(error)f(streams.)0 3217 y FL(class)i FD(CGIHandler)p FJ(\(\))208 3317 y FN(CGI-based)51 b(in)m(v)n(ocation)f (via)i FJ(sys.stdin)p FN(,)59 b FJ(sys.stdout)p FN(,)f FJ(sys.stderr)51 b FN(and)g FJ(os.environ)p FN(.)119 b(This)53 b(is)208 3416 y(useful)g(when)g(you)g(ha)n(v)o(e)g(a)i(WSGI)f (application)e(and)i(w)o(ant)g(to)g(run)f(it)h(as)h(a)f(CGI)h(script.) 125 b(Simply)54 b(in)m(v)n(ok)o(e)208 3516 y FJ (CGIHandler\(\).run\(app\))p FN(,)16 b(where)k FJ(app)g FN(is)h(the)f(WSGI)h(application)e(object)g(you)h(wish)g(to)h(in)m(v)n (ok)o(e.)208 3648 y(This)f(class)i(is)f(a)g(subclass)g(of)g FJ(BaseCGIHandler)d FN(that)j(sets)h FJ(wsgi.run_once)c FN(to)j(true,)f FJ(wsgi.multithread)e FN(to)208 3747 y(f)o(alse,)24 b(and)e FJ(wsgi.multiprocess)f FN(to)i(true,)g(and)g(al) o(w)o(ays)h(uses)f FJ(sys)h FN(and)e FJ(os)h FN(to)h(obtain)e(the)h (necessary)g(CGI)g(streams)208 3847 y(and)c(en)m(vironment.)0 3994 y FL(class)i FD(BaseCGIHandler)p FJ(\()p FK(stdin,)c(stdout,)i (stderr)-9 b(,)21 b(en)m(vir)l(on)e FC([)p FK(,)i(multithr)m(ead=T)-5 b(rue)19 b FC([)p FK(,)i(multipr)l(ocess=F)-6 b(alse)12 b FC(])g(])p FJ(\))208 4093 y FN(Similar)20 b(to)h FJ(CGIHandler)p FN(,)e(b)n(ut)h(instead)h(of)f(using)g(the)g FJ(sys)h FN(and)f FJ(os)g FN(modules,)g(the)g(CGI)h(en)m(vironment)d(and)i(I/O)g (streams)208 4193 y(are)e(speci\002ed)g(e)o(xplicitly)-5 b(.)23 b(The)18 b FK(multithr)m(ead)i FN(and)e FK(multipr)l(ocess)h FN(v)n(alues)f(are)g(used)h(to)f(set)h(the)g FJ(wsgi.multithread)d FN(and)208 4293 y FJ(wsgi.multiprocess)h FN(\003ags)k(for)e(an)o(y)h (applications)f(run)g(by)h(the)g(handler)f(instance.)208 4424 y(This)g(class)i(is)g(a)f(subclass)g(of)f FJ(SimpleHandler)f FN(intended)g(for)h(use)h(with)g(softw)o(are)f(other)g(than)g(HTTP)h (\223origin)f(serv)o(ers\224.)208 4524 y(If)g(you)f(are)h(writing)g(a)g (gate)n(w)o(ay)f(protocol)g(implementation)f(\(such)h(as)i(CGI,)g(F)o (astCGI,)f(SCGI,)h(etc.\))25 b(that)19 b(uses)h(a)f FJ(Status:)208 4623 y FN(header)g(to)h(send)g(an)g(HTTP)g(status,)h(you)e(probably)f (w)o(ant)i(to)h(subclass)f(this)h(instead)f(of)g FJ(SimpleHandler)p FN(.)0 4770 y FL(class)h FD(SimpleHandler)p FJ(\()p FK(stdin,)c (stdout,)j(stderr)-9 b(,)20 b(en)m(vir)l(on)g FC([)p FK(,multithr)m(ead=T)-5 b(rue)19 b FC([)p FK(,)h(multipr)l(ocess=F)-6 b(alse)12 b FC(])g(])p FJ(\))208 4870 y FN(Similar)26 b(to)g FJ(BaseCGIHandler)p FN(,)f(b)n(ut)h(designed)f(for)g(use)h(with) g(HTTP)h(origin)d(serv)o(ers.)42 b(If)26 b(you)f(are)h(writing)g(an)f (HTTP)208 4970 y(serv)o(er)19 b(implementation,)f(you)h(will)i (probably)d(w)o(ant)i(to)g(subclass)h(this)g(instead)f(of)f FJ(BaseCGIHandler)208 5101 y FN(This)d(class)h(is)h(a)e(subclass)h(of)f FJ(BaseHandler)p FN(.)22 b(It)17 b(o)o(v)o(errides)d(the)j FJ(__init__\(\))p FN(,)e FJ(get_stdin\(\))p FN(,)g FJ(get_stderr\(\))p FN(,)208 5201 y FJ(add_cgi_vars\(\))p FN(,)22 b FJ(_write\(\))p FN(,)i(and)f FJ(_flush\(\))g FN(methods)f(to)i(support)f(e)o(xplicitly) g(setting)h(the)f(en)m(vironment)e(and)208 5300 y(streams)16 b(via)h(the)g(constructor)-5 b(.)22 b(The)16 b(supplied)g(en)m (vironment)d(and)j(streams)h(are)g(stored)f(in)g(the)h FJ(stdin)p FN(,)g FJ(stdout)p FN(,)f FJ(stderr)p FN(,)208 5400 y(and)j FJ(environ)h FN(attrib)n(utes.)p 0 5549 3901 4 v 0 5649 a FI(614)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 615 627 TeXDict begin 615 626 bop 0 83 a FL(class)21 b FD(BaseHandler)p FJ(\(\))208 183 y FN(This)f(is)i(an)e(abstract)g(base)h(class)g(for)f (running)e(WSGI)j(applications.)k(Each)20 b(instance)g(will)h(handle)f (a)h(single)f(HTTP)g(request,)208 282 y(although)e(in)i(principle)f (you)g(could)h(create)g(a)g(subclass)h(that)f(w)o(as)h(reusable)e(for)h (multiple)f(requests.)208 408 y FJ(BaseHandler)f FN(instances)i(ha)n(v) o(e)g(only)f(one)h(method)f(intended)f(for)i(e)o(xternal)f(use:)208 533 y FD(run)p FJ(\()p FK(app)p FJ(\))390 632 y FN(Run)h(the)h (speci\002ed)e(WSGI)i(application,)e FK(app)p FN(.)208 758 y(All)i(of)g(the)g(other)f FJ(BaseHandler)g FN(methods)g(are)h(in)m (v)n(ok)o(ed)e(by)i(this)g(method)f(in)h(the)g(process)g(of)f(running)f (the)i(application,)208 857 y(and)e(thus)h(e)o(xist)h(primarily)d(to)j (allo)n(w)f(customizing)f(the)h(process.)208 982 y(The)f(follo)n(wing)g (methods)g(MUST)h(be)h(o)o(v)o(erridden)c(in)j(a)g(subclass:)208 1108 y FD(_write)p FJ(\()p FK(data)p FJ(\))390 1207 y FN(Buf)n(fer)25 b(the)g(string)f FK(data)h FN(for)f(transmission)h(to)g (the)g(client.)40 b(It')-5 b(s)26 b(okay)e(if)h(this)h(method)e (actually)g(transmits)h(the)h(data;)390 1307 y FJ(BaseHandler)15 b FN(just)h(separates)g(write)h(and)e(\003ush)h(operations)f(for)g (greater)h(ef)n(\002cienc)o(y)e(when)i(the)g(underlying)d(system)390 1407 y(actually)20 b(has)g(such)g(a)h(distinction.)208 1532 y FD(_flush)p FJ(\(\))390 1631 y FN(F)o(orce)h(b)n(uf)n(fered)e (data)j(to)f(be)h(transmitted)e(to)i(the)f(client.)32 b(It')-5 b(s)23 b(okay)e(if)i(this)g(method)e(is)i(a)g(no-op)d(\(i.e.,) j(if)f FJ(_write\(\))390 1731 y FN(actually)e(sends)g(the)g(data\).)208 1856 y FD(get_stdin)p FJ(\(\))390 1956 y FN(Return)27 b(an)g(input)f(stream)h(object)g(suitable)g(for)f(use)i(as)g(the)f FJ(wsgi.input)f FN(of)h(the)g(request)f(currently)g(being)g(pro-)390 2056 y(cessed.)208 2181 y FD(get_stderr)p FJ(\(\))390 2280 y FN(Return)32 b(an)g(output)f(stream)h(object)f(suitable)h(for)g (use)g(as)h(the)f FJ(wsgi.errors)f FN(of)h(the)g(request)f(currently)g (being)390 2380 y(processed.)208 2505 y FD(add_cgi_vars)p FJ(\(\))390 2605 y FN(Insert)20 b(CGI)h(v)n(ariables)e(for)h(the)g (current)f(request)g(into)h(the)g FJ(environ)g FN(attrib)n(ute.)208 2730 y(Here)25 b(are)g(some)g(other)f(methods)g(and)h(attrib)n(utes)g (you)f(may)h(wish)h(to)f(o)o(v)o(erride.)38 b(This)25 b(list)i(is)f(only)e(a)i(summary)-5 b(,)24 b(ho)n(we)n(v)o(er)m(,)208 2830 y(and)e(does)h(not)g(include)f(e)n(v)o(ery)f(method)h(that)h(can)g (be)g(o)o(v)o(erridden.)30 b(Y)-9 b(ou)23 b(should)f(consult)g(the)h (docstrings)f(and)h(source)f(code)208 2929 y(for)d(additional)g (information)f(before)h(attempting)f(to)j(create)f(a)g(customized)f FJ(BaseHandler)g FN(subclass.)208 3055 y(Attrib)n(utes)h(and)f(methods) g(for)h(customizing)f(the)h(WSGI)h(en)m(vironment:)208 3180 y FD(wsgi_multithread)390 3279 y FN(The)42 b(v)n(alue)f(to)g(be)h (used)f(for)g(the)h FJ(wsgi.multithread)d FN(en)m(vironment)g(v)n (ariable.)88 b(It)42 b(def)o(aults)f(to)h(true)f(in)390 3379 y FJ(BaseHandler)p FN(,)19 b(b)n(ut)h(may)g(ha)n(v)o(e)f(a)i(dif)n (ferent)d(def)o(ault)i(\(or)f(be)h(set)h(by)f(the)g(constructor\))e(in) j(the)f(other)f(subclasses.)208 3504 y FD(wsgi_multiprocess)390 3604 y FN(The)38 b(v)n(alue)g(to)h(be)f(used)h(for)f(the)g FJ(wsgi.multiprocess)e FN(en)m(vironment)g(v)n(ariable.)79 b(It)38 b(def)o(aults)g(to)h(true)f(in)390 3704 y FJ(BaseHandler)p FN(,)19 b(b)n(ut)h(may)g(ha)n(v)o(e)f(a)i(dif)n(ferent)d(def)o(ault)i (\(or)f(be)h(set)h(by)f(the)g(constructor\))e(in)j(the)f(other)f (subclasses.)208 3829 y FD(wsgi_run_once)390 3928 y FN(The)49 b(v)n(alue)g(to)g(be)h(used)f(for)f(the)i FJ(wsgi.run_once)d FN(en)m(vironment)f(v)n(ariable.)112 b(It)49 b(def)o(aults)g(to)h(f)o (alse)f(in)390 4028 y FJ(BaseHandler)p FN(,)19 b(b)n(ut)h FJ(CGIHandler)f FN(sets)i(it)g(to)f(true)g(by)g(def)o(ault.)208 4153 y FD(os_environ)390 4253 y FN(The)f(def)o(ault)f(en)m(vironment)d (v)n(ariables)j(to)h(be)g(included)e(in)i(e)n(v)o(ery)e(request')-5 b(s)18 b(WSGI)i(en)m(vironment.)h(By)e(def)o(ault,)f(this)i(is)390 4353 y(a)i(cop)o(y)f(of)g FJ(os.environ)g FN(at)h(the)g(time)f(that)h FJ(wsgiref.handlers)d FN(w)o(as)k(imported,)d(b)n(ut)h(subclasses)i (can)e(either)390 4452 y(create)27 b(their)g(o)n(wn)f(at)h(the)g(class) h(or)f(instance)g(le)n(v)o(el.)44 b(Note)27 b(that)g(the)g(dictionary)f (should)f(be)i(considered)f(read-only)-5 b(,)390 4552 y(since)21 b(the)f(def)o(ault)f(v)n(alue)h(is)h(shared)e(between)h (multiple)f(classes)j(and)d(instances.)208 4677 y FD(server_software) 390 4777 y FN(If)35 b(the)g FJ(origin_server)f FN(attrib)n(ute)h(is)h (set,)j(this)d(attrib)n(ute')-5 b(s)35 b(v)n(alue)f(is)j(used)e(to)g (set)h(the)f(def)o(ault)f FJ(SERVER_-)390 4876 y(SOFTWARE)17 b FN(WSGI)h(en)m(vironment)c(v)n(ariable,)j(and)g(also)g(to)h(set)g(a)g (def)o(ault)f FJ(Server:)23 b FN(header)16 b(in)h(HTTP)h(responses.)23 b(It)390 4976 y(is)18 b(ignored)c(for)i(handlers)f(\(such)h(as)h FJ(BaseCGIHandler)e FN(and)h FJ(CGIHandler)p FN(\))e(that)j(are)f(not)g (HTTP)h(origin)e(serv)o(ers.)208 5101 y FD(get_scheme)p FJ(\(\))390 5201 y FN(Return)h(the)h(URL)g(scheme)f(being)g(used)g(for) g(the)g(current)f(request.)23 b(The)17 b(def)o(ault)e(implementation)g (uses)i(the)f FJ(guess_-)390 5300 y(scheme\(\))28 b FN(function)f(from) h FJ(wsgiref.util)f FN(to)i(guess)f(whether)g(the)h(scheme)f(should)g (be)g(\223http\224)h(or)f(\223https\224,)390 5400 y(based)20 b(on)g(the)g(current)f(request')-5 b(s)20 b FJ(environ)f FN(v)n(ariables.)p 0 5549 3901 4 v 0 5649 a FI(18.4.)52 b FJ(wsgiref)22 b FI(\227)h(WSGI)h(Utilities)g(and)g(Ref)n(erence)e (Implementation)1383 b(615)p eop end %%Page: 616 628 TeXDict begin 616 627 bop 208 83 a FD(setup_environ)p FJ(\(\))390 183 y FN(Set)31 b(the)f FJ(environ)f FN(attrib)n(ute)h(to)g (a)h(fully-populated)c(WSGI)j(en)m(vironment.)52 b(The)30 b(def)o(ault)f(implementation)f(uses)390 282 y(all)g(of)e(the)i(abo)o (v)o(e)d(methods)h(and)g(attrib)n(utes,)j(plus)d(the)i FJ(get_stdin\(\))p FN(,)e FJ(get_stderr\(\))p FN(,)h(and)g FJ(add_cgi_-)390 382 y(vars\(\))22 b FN(methods)f(and)h(the)h FJ(wsgi_file_wrapper)d FN(attrib)n(ute.)31 b(It)23 b(also)f(inserts)h (a)g FJ(SERVER_SOFTWARE)d FN(k)o(e)o(y)390 482 y(if)27 b(not)g(present,)h(as)g(long)e(as)h(the)g FJ(origin_server)f FN(attrib)n(ute)g(is)i(a)f(true)g(v)n(alue)f(and)h(the)g FJ(server_software)390 581 y FN(attrib)n(ute)20 b(is)h(set.)208 712 y(Methods)e(and)h(attrib)n(utes)g(for)f(customizing)g(e)o(xception) f(handling:)208 843 y FD(log_exception)p FJ(\()p FK(e)n(xc)p 1022 843 25 4 v 27 w(info)p FJ(\))390 943 y FN(Log)f(the)g FK(e)n(xc)p 775 943 V 30 w(info)g FN(tuple)g(in)g(the)g(serv)o(er)g (log.)23 b FK(e)n(xc)p 1817 943 V 30 w(info)17 b FN(is)h(a)g FJ(\()p FK(type)p FJ(,)48 b FK(value)p FJ(,)h FK(tr)o(acebac)n(k)q FJ(\))16 b FN(tuple.)24 b(The)17 b(def)o(ault)f(imple-)390 1042 y(mentation)22 b(simply)h(writes)h(the)f(traceback)f(to)i(the)f (request')-5 b(s)23 b FJ(wsgi.errors)f FN(stream)h(and)g(\003ushes)g (it.)35 b(Subclasses)390 1142 y(can)17 b(o)o(v)o(erride)e(this)j (method)e(to)h(change)f(the)h(format)f(or)h(retar)o(get)f(the)h (output,)g(mail)g(the)g(traceback)f(to)i(an)f(administrator)m(,)390 1241 y(or)j(whate)n(v)o(er)f(other)g(action)h(may)g(be)g(deemed)f (suitable.)208 1372 y FD(traceback_limit)390 1472 y FN(The)30 b(maximum)e(number)g(of)i(frames)g(to)g(include)f(in)h(tracebacks)f (output)g(by)g(the)h(def)o(ault)g FJ(log_exception\(\))390 1572 y FN(method.)24 b(If)c FJ(None)p FN(,)g(all)g(frames)g(are)g (included.)208 1702 y FD(error_output)p FJ(\()p FK(en)m(vir)l(on,)c (start)p 1300 1702 V 30 w(r)m(esponse)p FJ(\))390 1802 y FN(This)26 b(method)e(is)j(a)f(WSGI)g(application)e(to)i(generate)e (an)i(error)e(page)h(for)g(the)h(user)-5 b(.)41 b(It)26 b(is)h(only)d(in)m(v)n(ok)o(ed)g(if)i(an)g(error)390 1902 y(occurs)20 b(before)e(headers)i(are)g(sent)g(to)h(the)f(client.) 390 2016 y(This)30 b(method)d(can)i(access)h(the)f(current)f(error)g (information)f(using)i FJ(sys.exc_info\(\))p FN(,)g(and)g(should)f (pass)h(that)390 2116 y(information)18 b(to)i FK(start)p 1045 2116 V 30 w(r)m(esponse)g FN(when)g(calling)g(it)h(\(as)f (described)f(in)h(the)h(\223Error)d(Handling\224)h(section)h(of)g(PEP)h (333\).)390 2230 y(The)26 b(def)o(ault)g(implementation)e(just)j(uses)g (the)g FJ(error_status)p FN(,)f FJ(error_headers)p FN(,)f(and)h FJ(error_body)f FN(at-)390 2330 y(trib)n(utes)20 b(to)h(generate)e(an)h (output)f(page.)24 b(Subclasses)c(can)g(o)o(v)o(erride)e(this)j(to)f (produce)f(more)g(dynamic)g(error)g(output.)390 2444 y(Note,)28 b(ho)n(we)n(v)o(er)m(,)e(that)g(it')-5 b(s)28 b(not)e(recommended)e(from)h(a)i(security)g(perspecti)n(v)o(e)d(to)j (spit)g(out)g(diagnostics)e(to)i(an)o(y)f(old)390 2543 y(user;)37 b(ideally)-5 b(,)34 b(you)c(should)h(ha)n(v)o(e)g(to)h(do)f (something)f(special)h(to)h(enable)f(diagnostic)f(output,)j(which)e(is) i(why)e(the)390 2643 y(def)o(ault)20 b(implementation)e(doesn')o(t)g (include)h(an)o(y)-5 b(.)208 2774 y FD(error_status)390 2874 y FN(The)20 b(HTTP)f(status)i(used)e(for)g(error)g(responses.)24 b(This)c(should)f(be)g(a)h(status)h(string)e(as)i(de\002ned)d(in)i(PEP) h(333;)e(it)h(def)o(aults)390 2973 y(to)h(a)f(500)f(code)h(and)g (message.)208 3104 y FD(error_headers)390 3204 y FN(The)26 b(HTTP)h(headers)e(used)h(for)g(error)f(responses.)43 b(This)26 b(should)g(be)g(a)h(list)g(of)f(WSGI)h(response)e(headers)h (\()p FJ(\()p FK(name)p FJ(,)390 3303 y FK(value)p FJ(\))20 b FN(tuples\),)f(as)i(described)e(in)h(PEP)h(333.)j(The)c(def)o(ault)f (list)j(just)e(sets)i(the)e(content)f(type)h(to)g FJ(text/plain)p FN(.)208 3434 y FD(error_body)390 3534 y FN(The)k(error)f(response)g (body)-5 b(.)34 b(This)25 b(should)e(be)h(an)g(HTTP)g(response)f(body)f (string.)37 b(It)24 b(def)o(aults)f(to)i(the)f(plain)f(te)o(xt,)i(\223) -7 b(A)390 3633 y(serv)o(er)20 b(error)f(occurred.)k(Please)d(contact)g (the)g(administrator)-5 b(.)f(\224)208 3764 y(Methods)19 b(and)h(attrib)n(utes)g(for)f(PEP)i(333')-5 b(s)20 b(\223Optional)f (Platform-Speci\002c)f(File)j(Handling\224)e(feature:)208 3895 y FD(wsgi_file_wrapper)390 3995 y FN(A)26 b FJ(wsgi.file_wrapper)d FN(f)o(actory)-5 b(,)26 b(or)f FJ(None)p FN(.)41 b(The)26 b(def)o(ault)f(v)n(alue)g(of)g(this)h(attrib)n(ute)g(is)g(the)g FJ(FileWrapper)390 4094 y FN(class)21 b(from)e FJ(wsgiref.util)p FN(.)208 4225 y FD(sendfile)p FJ(\(\))390 4325 y FN(Ov)o(erride)i(to)i (implement)e(platform-speci\002c)f(\002le)j(transmission.)31 b(This)22 b(method)f(is)j(called)e(only)g(if)g(the)h(application')-5 b(s)390 4425 y(return)18 b(v)n(alue)h(is)h(an)f(instance)g(of)g(the)h (class)g(speci\002ed)f(by)g(the)g FJ(wsgi_file_wrapper)e FN(attrib)n(ute.)24 b(It)19 b(should)g(return)390 4524 y(a)i(true)e(v)n(alue)h(if)g(it)h(w)o(as)g(able)f(to)g(successfully)f (transmit)h(the)g(\002le,)h(so)f(that)g(the)g(def)o(ault)f (transmission)h(code)f(will)i(not)f(be)390 4624 y(e)o(x)o(ecuted.)j (The)d(def)o(ault)g(implementation)e(of)h(this)i(method)e(just)i (returns)e(a)i(f)o(alse)f(v)n(alue.)208 4755 y(Miscellaneous)f(methods) g(and)h(attrib)n(utes:)208 4886 y FD(origin_server)390 4985 y FN(This)j(attrib)n(ute)f(should)f(be)h(set)h(to)f(a)h(true)f(v)n (alue)g(if)g(the)g(handler')-5 b(s)22 b FJ(_write\(\))f FN(and)h FJ(_flush\(\))f FN(are)h(being)f(used)h(to)390 5085 y(communicate)16 b(directly)i(to)g(the)h(client,)f(rather)g(than)g (via)g(a)h(CGI-lik)o(e)f(gate)n(w)o(ay)f(protocol)g(that)h(w)o(ants)h (the)f(HTTP)h(status)390 5185 y(in)i(a)f(special)g FJ(Status:)25 b FN(header)-5 b(.)390 5299 y(This)54 b(attrib)n(ute')-5 b(s)55 b(def)o(ault)e(v)n(alue)g(is)i(true)f(in)g FJ(BaseHandler)p FN(,)61 b(b)n(ut)54 b(f)o(alse)h(in)f FJ(BaseCGIHandler)e FN(and)390 5398 y FJ(CGIHandler)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(616)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 617 629 TeXDict begin 617 628 bop 208 83 a FD(http_version)390 183 y FN(If)20 b FJ(origin_server)d FN(is)k(true,)e(this)h(string)f (attrib)n(ute)g(is)i(used)e(to)g(set)i(the)e(HTTP)h(v)o(ersion)e(of)h (the)h(response)f(set)h(to)g(the)390 282 y(client.)25 b(It)c(def)o(aults)e(to)i FJ("1.0")p FN(.)0 610 y FE(18.5)121 b Fx(urllib)32 b FE(\227)h(Open)h(arbitr)o(ar)t(y)f(resources)h(b)n(y)f (URL)0 843 y FN(This)40 b(module)e(pro)o(vides)f(a)j(high-le)n(v)o(el)d (interf)o(ace)i(for)f(fetching)g(data)i(across)f(the)g(W)-7 b(orld)40 b(W)m(ide)f(W)-7 b(eb)m(.)83 b(In)39 b(particular)m(,)k(the)0 942 y FJ(urlopen\(\))24 b FN(function)g(is)i(similar)f(to)h(the)f(b)n (uilt-in)g(function)e FJ(open\(\))p FN(,)j(b)n(ut)f(accepts)g(Uni)n(v)o (ersal)f(Resource)h(Locators)f(\(URLs\))0 1042 y(instead)31 b(of)g(\002lenames.)57 b(Some)31 b(restrictions)f(apply)g(\227)i(it)g (can)e(only)h(open)f(URLs)h(for)g(reading,)h(and)e(no)h(seek)g (operations)f(are)0 1141 y(a)n(v)n(ailable.)0 1288 y(It)20 b(de\002nes)g(the)h(follo)n(wing)d(public)h(functions:)0 1435 y FD(urlopen)p FJ(\()p FK(url)p FC([)p FK(,)g(data)p FC([)p FK(,)g(pr)l(oxies)12 b FC(])g(])p FJ(\))208 1535 y FN(Open)20 b(a)h(netw)o(ork)e(object)h(denoted)f(by)h(a)h(URL)h(for)d (reading.)25 b(If)c(the)f(URL)h(does)g(not)f(ha)n(v)o(e)g(a)h(scheme)f (identi\002er)m(,)g(or)g(if)h(it)g(has)208 1634 y(`)p FO(\002le:)p FN(')34 b(as)26 b(its)g(scheme)f(identi\002er)m(,)g(this)h (opens)e(a)i(local)f(\002le)h(\(without)e(uni)n(v)o(ersal)g(ne)n (wlines\);)j(otherwise)e(it)h(opens)e(a)i(sock)o(et)208 1734 y(to)h(a)g(serv)o(er)g(some)n(where)e(on)i(the)g(netw)o(ork.)45 b(If)27 b(the)g(connection)e(cannot)h(be)h(made)g(the)g FJ(IOError)g FN(e)o(xception)e(is)j(raised.)208 1834 y(If)23 b(all)h(went)g(well,)h(a)f(\002le-lik)o(e)f(object)g(is)i (returned.)33 b(This)24 b(supports)f(the)g(follo)n(wing)f(methods:)31 b FJ(read\(\))p FN(,)24 b FJ(readline\(\))p FN(,)208 1933 y FJ(readlines\(\))p FN(,)c FJ(fileno\(\))p FN(,)h FJ(close\(\))p FN(,)g FJ(info\(\))g FN(and)g FJ(geturl\(\))p FN(.)28 b(It)22 b(also)g(has)g(proper)e(support)h(for)g(the)g(iterator) 208 2033 y(protocol.)31 b(One)22 b(ca)n(v)o(eat:)31 b(the)22 b FJ(read\(\))h FN(method,)e(if)j(the)e(size)i(ar)o(gument)c(is)k (omitted)e(or)h(ne)o(gati)n(v)o(e,)e(may)h(not)h(read)f(until)h(the)208 2133 y(end)e(of)g(the)h(data)g(stream;)h(there)e(is)i(no)e(good)g(w)o (ay)h(to)g(determine)e(that)i(the)g(entire)f(stream)h(from)f(a)h(sock)o (et)g(has)g(been)f(read)g(in)208 2232 y(the)f(general)f(case.)208 2365 y(Except)i(for)g(the)h FJ(info\(\))g FN(and)g FJ(geturl\(\))f FN(methods,)g(these)i(methods)e(ha)n(v)o(e)g(the)h(same)h(interf)o(ace) e(as)i(for)e(\002le)i(objects)f(\227)208 2465 y(see)j(section)f(3.9)g (in)h(this)g(manual.)37 b(\(It)25 b(is)g(not)g(a)g(b)n(uilt-in)f (\002le)h(object,)g(ho)n(we)n(v)o(er)m(,)e(so)i(it)h(can')o(t)d(be)i (used)f(at)h(those)g(fe)n(w)g(places)208 2564 y(where)19 b(a)i(true)f(b)n(uilt-in)f(\002le)i(object)f(is)h(required.\))208 2697 y(The)28 b FJ(info\(\))g FN(method)g(returns)g(an)h(instance)f(of) h(the)g(class)h FJ(mimetools.Message)c FN(containing)h (meta-information)208 2797 y(associated)j(with)h(the)g(URL.)h(When)e (the)h(method)f(is)i(HTTP)-9 b(,)31 b(these)g(headers)f(are)h(those)f (returned)f(by)i(the)g(serv)o(er)f(at)i(the)208 2896 y(head)24 b(of)g(the)h(retrie)n(v)o(ed)e(HTML)i(page)f(\(including)f (Content-Length)f(and)i(Content-T)-7 b(ype\).)37 b(When)25 b(the)g(method)e(is)j(FTP)-9 b(,)25 b(a)208 2996 y(Content-Length)e (header)h(will)j(be)e(present)h(if)g(\(as)g(is)g(no)n(w)g(usual\))f (the)h(serv)o(er)e(passed)i(back)f(a)h(\002le)h(length)e(in)h(response) e(to)208 3096 y(the)e(FTP)h(retrie)n(v)n(al)f(request.)31 b(A)23 b(Content-T)-7 b(ype)20 b(header)i(will)h(be)f(present)g(if)h (the)f(MIME)g(type)g(can)h(be)f(guessed.)31 b(When)23 b(the)208 3195 y(method)f(is)j(local-\002le,)f(returned)e(headers)h (will)h(include)f(a)h(Date)h(representing)c(the)j(\002le')-5 b(s)25 b(last-modi\002ed)e(time,)h(a)g(Content-)208 3295 y(Length)c(gi)n(ving)g(\002le)i(size,)g(and)f(a)h(Content-T)-7 b(ype)20 b(containing)f(a)j(guess)g(at)g(the)f(\002le')-5 b(s)23 b(type.)28 b(See)22 b(also)g(the)f(description)f(of)i(the)208 3394 y FJ(mimetools)d FN(module.)208 3527 y(The)h FJ(geturl\(\))h FN(method)f(returns)g(the)h(real)h(URL)g(of)f(the)g(page.)27 b(In)21 b(some)h(cases,)g(the)f(HTTP)g(serv)o(er)g(redirects)f(a)i (client)f(to)208 3627 y(another)e(URL.)i(The)f FJ(urlopen\(\))f FN(function)g(handles)h(this)h(transparently)-5 b(,)18 b(b)n(ut)j(in)g(some)f(cases)h(the)g(caller)g(needs)f(to)h(kno)n(w)208 3727 y(which)e(URL)i(the)f(client)g(w)o(as)h(redirected)e(to.)25 b(The)20 b FJ(geturl\(\))f FN(method)g(can)h(be)g(used)g(to)h(get)f(at) g(this)h(redirected)e(URL.)208 3859 y(If)h(the)h FK(url)g FN(uses)h(the)e(`)p FO(http:)p FN(')25 b(scheme)20 b(identi\002er)m(,)g (the)h(optional)e FK(data)h FN(ar)o(gument)f(may)h(be)h(gi)n(v)o(en)e (to)i(specify)f(a)i FJ(POST)e FN(request)208 3959 y(\(normally)f(the)i (request)f(type)h(is)h FJ(GET)p FN(\).)e(The)h FK(data)f FN(ar)o(gument)f(must)i(be)g(in)g(standard)f FO(application/x-www-f)n (or)r(m-ur)q(len)o(code)o(d)208 4059 y FN(format;)f(see)h(the)h FJ(urlencode\(\))d FN(function)h(belo)n(w)-5 b(.)208 4191 y(The)25 b FJ(urlopen\(\))h FN(function)e(w)o(orks)i (transparently)e(with)j(proxies)e(which)g(do)h(not)g(require)f (authentication.)41 b(In)26 b(a)j(U)t FH(N)t(I)t(X)208 4291 y FN(or)24 b(W)m(indo)n(ws)h(en)m(vironment,)e(set)j(the)f(http)p 1485 4291 25 4 v 29 w(proxy,)f(ftp)p 1848 4291 V 29 w(proxy)f(or)i (gopher)p 2424 4291 V 28 w(proxy)e(en)m(vironment)f(v)n(ariables)i(to)h (a)h(URL)f(that)208 4391 y(identi\002es)19 b(the)h(proxy)e(serv)o(er)g (before)h(starting)g(the)h(Python)e(interpreter)-5 b(.)24 b(F)o(or)19 b(e)o(xample)f(\(the)h(`)p FJ(\045)p FN(')h(is)g(the)g (command)d(prompt\):)444 4615 y FA(\045)44 b (http_proxy="http://www.someproxy.com:3128")444 4706 y(\045)g(export)g(http_proxy)444 4798 y(\045)g(python)444 4889 y(...)208 5078 y FN(In)29 b(a)g(W)m(indo)n(ws)g(en)m(vironment,)f (if)i(no)f(proxy)f(en)m(vironment)e(v)n(ariables)i(are)i(set,)i(proxy)c (settings)h(are)g(obtained)f(from)h(the)208 5178 y(re)o(gistry')-5 b(s)19 b(Internet)g(Settings)h(section.)208 5311 y(In)f(a)i(Macintosh)e (en)m(vironment,)e FJ(urlopen\(\))i FN(will)i(retrie)n(v)o(e)e(proxy)g (information)e(from)j(Internet)f(Con\002g.)p 0 5549 3901 4 v 0 5649 a FI(18.5.)52 b FJ(urllib)22 b FI(\227)h(Open)g(arbitr)o(ar) r(y)h(resources)d(b)n(y)i(URL)1880 b(617)p eop end %%Page: 618 630 TeXDict begin 618 629 bop 208 83 a FN(Alternati)n(v)o(ely)-5 b(,)22 b(the)h(optional)f FK(pr)l(oxies)i FN(ar)o(gument)d(may)i(be)g (used)g(to)h(e)o(xplicitly)e(specify)h(proxies.)34 b(It)24 b(must)f(be)g(a)h(dictionary)208 183 y(mapping)g(scheme)i(names)g(to)g (proxy)f(URLs,)j(where)e(an)g(empty)f(dictionary)g(causes)h(no)g (proxies)f(to)i(be)f(used,)h(and)f FJ(None)208 282 y FN(\(the)19 b(def)o(ault)h(v)n(alue\))f(causes)h(en)m(vironmental)e (proxy)g(settings)i(to)h(be)f(used)g(as)h(discussed)f(abo)o(v)o(e.)j(F) o(or)d(e)o(xample:)444 506 y FA(#)44 b(Use)h (http://www.someproxy.com:3128)40 b(for)k(http)g(proxying)444 598 y(proxies)f(=)i({'http':)f('http://www.someproxy.com:3128'})444 689 y(filehandle)f(=)i(urllib.urlopen\(some_url,)40 b (proxies=proxies\))444 780 y(#)k(Don't)g(use)h(any)f(proxies)444 872 y(filehandle)f(=)i(urllib.urlopen\(some_url,)40 b(proxies={}\))444 963 y(#)k(Use)h(proxies)e(from)i(environment)e(-)h(both)g(versions)g (are)g(equivalent)444 1054 y(filehandle)f(=)i (urllib.urlopen\(some_url,)40 b(proxies=None\))444 1146 y(filehandle)j(=)i(urllib.urlopen\(some_url\))208 1335 y FN(The)20 b FJ(urlopen\(\))f FN(function)f(does)i(not)g(support)f(e)o (xplicit)h(proxy)f(speci\002cation.)24 b(If)c(you)g(need)f(to)i(o)o(v)o (erride)d(en)m(vironmental)208 1435 y(proxy)g(settings,)i(use)h FJ(URLopener)p FN(,)d(or)i(a)h(subclass)f(such)g(as)h FJ(FancyURLopener)p FN(.)208 1568 y(Proxies)h(which)h(require)f (authentication)f(for)i(use)h(are)f(not)g(currently)e(supported;)i (this)h(is)g(considered)e(an)h(implementation)208 1667 y(limitation.)208 1800 y(Changed)18 b(in)j(v)o(ersion)e(2.3:)g(Added)g (the)i FK(pr)l(oxies)f FN(support.)0 1947 y FD(urlretrieve)p FJ(\()p FK(url)p FC([)p FK(,)e(\002lename)p FC([)p FK(,)h(r)m (eporthook)q FC([)p FK(,)f(data)12 b FC(])g(])g(])p FJ(\))208 2047 y FN(Cop)o(y)19 b(a)h(netw)o(ork)e(object)h(denoted)f(by)i(a)g (URL)g(to)g(a)g(local)f(\002le,)h(if)g(necessary)-5 b(.)24 b(If)19 b(the)h(URL)g(points)f(to)h(a)g(local)g(\002le,)g(or)f(a)h(v)n (alid)208 2146 y(cached)g(cop)o(y)g(of)h(the)g(object)g(e)o(xists,)h (the)f(object)g(is)h(not)f(copied.)27 b(Return)20 b(a)i(tuple)f FJ(\()p FK(\002lename)p FJ(,)48 b FK(header)o(s)p FJ(\))20 b FN(where)h FK(\002lename)208 2246 y FN(is)g(the)g(local)g(\002le)g (name)f(under)f(which)i(the)f(object)h(can)f(be)h(found,)e(and)h FK(header)o(s)g FN(is)i(whate)n(v)o(er)d(the)i FJ(info\(\))f FN(method)f(of)i(the)208 2345 y(object)d(returned)g(by)h FJ(urlopen\(\))f FN(returned)g(\(for)g(a)i(remote)f(object,)g(possibly) f(cached\).)24 b(Exceptions)18 b(are)h(the)g(same)h(as)g(for)208 2445 y FJ(urlopen\(\))p FN(.)208 2578 y(The)i(second)f(ar)o(gument,)g (if)i(present,)f(speci\002es)h(the)g(\002le)g(location)f(to)g(cop)o(y)g (to)h(\(if)f(absent,)h(the)f(location)g(will)h(be)g(a)g(temp\002le)208 2678 y(with)j(a)g(generated)e(name\).)42 b(The)25 b(third)h(ar)o (gument,)e(if)j(present,)f(is)h(a)g(hook)d(function)g(that)i(will)h(be) f(called)g(once)f(on)h(estab-)208 2777 y(lishment)f(of)h(the)g(netw)o (ork)f(connection)e(and)j(once)f(after)h(each)f(block)g(read)h (thereafter)-5 b(.)41 b(The)26 b(hook)f(will)h(be)g(passed)g(three)208 2877 y(ar)o(guments;)h(a)f(count)f(of)h(blocks)g(transferred)e(so)i(f)o (ar)m(,)h(a)g(block)e(size)i(in)f(bytes,)h(and)f(the)g(total)g(size)h (of)f(the)g(\002le.)43 b(The)26 b(third)208 2976 y(ar)o(gument)17 b(may)j(be)g FJ(-1)h FN(on)e(older)h(FTP)h(serv)o(ers)e(which)h(do)g (not)f(return)g(a)i(\002le)g(size)g(in)f(response)f(to)i(a)f(retrie)n (v)n(al)g(request.)208 3109 y(If)g(the)h FK(url)g FN(uses)h(the)e(`)p FO(http:)p FN(')25 b(scheme)20 b(identi\002er)m(,)g(the)h(optional)e FK(data)h FN(ar)o(gument)f(may)h(be)h(gi)n(v)o(en)e(to)i(specify)f(a)i FJ(POST)e FN(request)208 3209 y(\(normally)27 b(the)i(request)g(type)g (is)h FJ(GET)p FN(\).)f(The)g FK(data)g FN(ar)o(gument)e(must)j(in)f (standard)f FO(application/x-www-f)n(or)r(m-ur)q(len)o(code)o(d)208 3309 y FN(format;)19 b(see)h(the)h FJ(urlencode\(\))d FN(function)h(belo)n(w)-5 b(.)208 3441 y(Changed)24 b(in)i(v)o(ersion)e (2.5:)61 b FJ(urlretrieve\(\))24 b FN(will)j(raise)e FJ(ContentTooShortError)e FN(when)i(it)h(detects)g(that)g(the)208 3541 y(amount)f(of)i(data)f(a)n(v)n(ailable)h(w)o(as)g(less)h(than)f (the)f(e)o(xpected)g(amount)f(\(which)h(is)i(the)f(size)g(reported)e (by)i(a)g FK(Content-Length)208 3641 y FN(header\).)c(This)d(can)g (occur)m(,)f(for)g(e)o(xample,)g(when)h(the)g(do)n(wnload)e(is)j (interrupted.)208 3773 y(The)g FK(Content-Length)e FN(is)j(treated)f (as)h(a)g(lo)n(wer)f(bound:)26 b(if)c(there')-5 b(s)21 b(more)g(data)g(to)h(read,)f(urlretrie)n(v)o(e)f(reads)h(more)f(data,)i (b)n(ut)f(if)208 3873 y(less)g(data)f(is)h(a)n(v)n(ailable,)f(it)g (raises)h(the)f(e)o(xception.)208 4006 y(Y)-9 b(ou)24 b(can)h(still)h(retrie)n(v)o(e)e(the)i(do)n(wnloaded)c(data)j(in)h (this)f(case,)i(it)f(is)g(stored)f(in)g(the)g FJ(content)g FN(attrib)n(ute)f(of)h(the)g(e)o(xception)208 4106 y(instance.)208 4238 y(If)20 b(no)g FK(Content-Length)f FN(header)g(w)o(as)j(supplied,) d(urlretrie)n(v)o(e)g(can)i(not)f(check)g(the)h(size)g(of)g(the)f(data) h(it)g(has)g(do)n(wnloaded,)d(and)208 4338 y(just)i(returns)g(it.)25 b(In)20 b(this)h(case)f(you)g(just)h(ha)n(v)o(e)e(to)h(assume)h(that)f (the)g(do)n(wnload)e(w)o(as)j(successful.)0 4485 y FD(_urlopener)208 4584 y FN(The)f(public)f(functions)g FJ(urlopen\(\))h FN(and)g FJ(urlretrieve\(\))e FN(create)j(an)f(instance)g(of)h(the)f FJ(FancyURLopener)f FN(class)208 4684 y(and)i(use)h(it)h(to)f(perform)e (their)h(requested)g(actions.)30 b(T)-7 b(o)22 b(o)o(v)o(erride)d(this) k(functionality)-5 b(,)19 b(programmers)h(can)h(create)h(a)g(subclass) 208 4784 y(of)h FJ(URLopener)g FN(or)h FJ(FancyURLopener)p FN(,)e(then)h(assign)h(an)g(instance)g(of)f(that)h(class)h(to)f(the)g FJ(urllib._urlopener)208 4883 y FN(v)n(ariable)h(before)g(calling)h (the)g(desired)g(function.)42 b(F)o(or)26 b(e)o(xample,)g(applications) f(may)h(w)o(ant)h(to)f(specify)g(a)h(dif)n(ferent)d FO(User-)208 4983 y(Agent:)f FN(header)c(than)h FJ(URLopener)f FN(de\002nes.)25 b(This)20 b(can)g(be)g(accomplished)f(with)h(the)g(follo)n(wing)f (code:)p 0 5549 3901 4 v 0 5649 a FI(618)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 619 631 TeXDict begin 619 630 bop 444 174 a FA(import)44 b(urllib)444 357 y(class)g(AppURLopener\(urllib.FancyURLopener\):)623 448 y(version)g(=)g("App/1.7")444 631 y(urllib._urlopener)e(=)i (AppURLopener\(\))0 830 y FD(urlcleanup)p FJ(\(\))208 930 y FN(Clear)20 b(the)g(cache)g(that)g(may)g(ha)n(v)o(e)g(been)f(b)n (uilt)i(up)e(by)h(pre)n(vious)f(calls)i(to)f FJ(urlretrieve\(\))p FN(.)0 1077 y FD(quote)p FJ(\()p FK(string)p FC([)p FK(,)f(safe)12 b FC(])p FJ(\))208 1176 y FN(Replace)21 b(special)i(characters)e(in)h FK(string)g FN(using)f(the)h(`)p FJ(\045xx)p FN(')g(escape.)30 b(Letters,)22 b(digits,)g(and)g(the)g(characters)f(`)p FJ(_.-)p FN(')g(are)h(ne)n(v)o(er)208 1276 y(quoted.)g(The)c(optional)e FK(safe)i FN(parameter)e(speci\002es)i(additional)f(characters)f(that)i (should)f(not)g(be)h(quoted)e(\227)j(its)f(def)o(ault)f(v)n(alue)208 1376 y(is)k FJ('/')p FN(.)208 1508 y(Example:)j FJ (quote\('/\230connolly/'\))17 b FN(yields)j FJ('/\0457econnolly/')p FN(.)0 1655 y FD(quote_plus)p FJ(\()p FK(string)p FC([)p FK(,)e(safe)12 b FC(])p FJ(\))208 1755 y FN(Lik)o(e)22 b FJ(quote\(\))p FN(,)f(b)n(ut)h(also)h(replaces)e(spaces)h(by)g(plus)g (signs,)h(as)g(required)d(for)h(quoting)g(HTML)g(form)g(v)n(alues.)31 b(Plus)22 b(signs)208 1855 y(in)e(the)g(original)f(string)h(are)g (escaped)g(unless)g(the)o(y)f(are)i(included)d(in)j FK(safe)p FN(.)k(It)20 b(also)h(does)f(not)g(ha)n(v)o(e)f FK(safe)i FN(def)o(ault)e(to)i FJ('/')p FN(.)0 2001 y FD(unquote)p FJ(\()p FK(string)p FJ(\))208 2101 y FN(Replace)f(`)p FJ(\045xx)p FN(')f(escapes)i(by)e(their)h(single-character)e(equi)n(v)n (alent.)208 2234 y(Example:)24 b FJ(unquote\('/\0457Econnolly/'\))16 b FN(yields)k FJ('/\230connolly/')p FN(.)0 2381 y FD(unquote_plus)p FJ(\()p FK(string)p FJ(\))208 2480 y FN(Lik)o(e)g FJ(unquote\(\))p FN(,)e(b)n(ut)j(also)f(replaces)g(plus)g(signs)h(by)e(spaces,)h(as)h (required)e(for)g(unquoting)f(HTML)i(form)f(v)n(alues.)0 2627 y FD(urlencode)p FJ(\()p FK(query)p FC([)p FK(,)e(doseq)12 b FC(])p FJ(\))208 2727 y FN(Con)m(v)o(ert)26 b(a)j(mapping)e(object)h (or)g(a)h(sequence)e(of)h(tw)o(o-element)g(tuples)g(to)g(a)h (\223url-encoded\224)d(string,)k(suitable)e(to)g(pass)h(to)208 2826 y FJ(urlopen\(\))20 b FN(abo)o(v)o(e)g(as)i(the)g(optional)e FK(data)g FN(ar)o(gument.)27 b(This)22 b(is)g(useful)f(to)h(pass)g(a)g (dictionary)d(of)j(form)e(\002elds)i(to)g(a)g FJ(POST)208 2926 y FN(request.)52 b(The)29 b(resulting)g(string)g(is)i(a)e(series)i (of)e FK(k)o(e)n(y)p FJ(=)p FK(value)f FN(pairs)h(separated)g(by)g(`)p FJ(&)p FN(')g(characters,)i(where)e(both)g FK(k)o(e)n(y)g FN(and)208 3026 y FK(value)17 b FN(are)h(quoted)e(using)i FJ(quote_plus\(\))e FN(abo)o(v)o(e.)22 b(If)c(the)g(optional)f (parameter)f FK(doseq)h FN(is)i(present)e(and)h(e)n(v)n(aluates)f(to)h (true,)208 3125 y(indi)n(vidual)23 b FK(k)o(e)n(y)p FJ(=)p FK(value)h FN(pairs)h(are)h(generated)e(for)g(each)h(element)g(of)g (the)h(sequence.)39 b(When)26 b(a)f(sequence)g(of)g(tw)o(o-element)208 3225 y(tuples)18 b(is)i(used)f(as)h(the)f FK(query)g FN(ar)o(gument,)d(the)j(\002rst)h(element)e(of)h(each)g(tuple)f(is)i(a) g(k)o(e)o(y)e(and)h(the)g(second)f(is)i(a)f(v)n(alue.)24 b(The)19 b(order)208 3325 y(of)i(parameters)f(in)h(the)g(encoded)f (string)h(will)h(match)f(the)g(order)f(of)h(parameter)f(tuples)h(in)g (the)h(sequence.)27 b(The)21 b FJ(cgi)g FN(module)208 3424 y(pro)o(vides)i(the)i(functions)f FJ(parse_qs\(\))g FN(and)g FJ(parse_qsl\(\))g FN(which)h(are)g(used)g(to)g(parse)g(query) f(strings)h(into)g(Python)208 3524 y(data)20 b(structures.)0 3671 y FD(pathname2url)p FJ(\()p FK(path)p FJ(\))208 3770 y FN(Con)m(v)o(ert)h(the)i(pathname)e FK(path)h FN(from)f(the)i(local)g(syntax)f(for)g(a)h(path)f(to)h(the)g(form)f (used)g(in)h(the)g(path)f(component)f(of)h(a)h(URL.)208 3870 y(This)d(does)g(not)g(produce)e(a)i(complete)g(URL.)g(The)g (return)f(v)n(alue)h(will)g(already)g(be)g(quoted)e(using)i(the)g FJ(quote\(\))g FN(function.)0 4017 y FD(url2pathname)p FJ(\()p FK(path)p FJ(\))208 4116 y FN(Con)m(v)o(ert)h(the)j(path)f (component)e FK(path)h FN(from)g(an)i(encoded)d(URL)j(to)g(the)f(local) g(syntax)g(for)g(a)h(path.)34 b(This)23 b(does)g(not)g(accept)g(a)208 4216 y(complete)c(URL.)h(This)h(function)d(uses)j FJ(unquote\(\))e FN(to)h(decode)f FK(path)p FN(.)0 4363 y FL(class)i FD(URLopener)p FJ(\()p FC([)p FK(pr)l(oxies)p FC([)p FK(,)d(**x509)12 b FC(])g(])p FJ(\))208 4463 y FN(Base)18 b(class)h(for)e(opening)f(and) h(reading)g(URLs.)25 b(Unless)18 b(you)f(need)g(to)h(support)f(opening) f(objects)h(using)g(schemes)h(other)f(than)208 4562 y(`)p FO(http:)p FN(',)h(`)p FO(ftp:)p FN(',)g(`)p FO(gopher)r(:)p FN(')23 b(or)d(`)p FO(\002le:)p FN(',)f(you)g(probably)f(w)o(ant)j(to)f (use)g FJ(FancyURLopener)p FN(.)208 4695 y(By)h(def)o(ault,)e(the)i FJ(URLopener)e FN(class)j(sends)f(a)g FO(User-Agent:)j FN(header)19 b(of)i(`)p FJ(urllib/)p FK(VVV)6 b FN(',)18 b(where)i FK(VVV)27 b FN(is)21 b(the)g FJ(urllib)208 4795 y FN(v)o(ersion)37 b(number)-5 b(.)80 b(Applications)38 b(can)h(de\002ne)f(their)h(o)n(wn)f FO(User-Agent:)61 b FN(header)38 b(by)h(subclassing)f FJ(URLopener)g FN(or)208 4894 y FJ(FancyURLopener)28 b FN(and)i(setting)h(the)f(class)i(attrib)n (ute)e FJ(version)g FN(to)h(an)f(appropriate)f(string)h(v)n(alue)g(in)h (the)f(subclass)208 4994 y(de\002nition.)208 5127 y(The)19 b(optional)g FK(pr)l(oxies)h FN(parameter)e(should)h(be)h(a)g (dictionary)e(mapping)g(scheme)i(names)f(to)i(proxy)d(URLs,)i(where)g (an)f(empty)208 5226 y(dictionary)i(turns)i(proxies)f(of)n(f)g (completely)-5 b(.)32 b(Its)23 b(def)o(ault)g(v)n(alue)f(is)i FJ(None)p FN(,)g(in)f(which)f(case)i(en)m(vironmental)c(proxy)h (settings)208 5326 y(will)f(be)h(used)f(if)g(present,)f(as)i(discussed) f(in)h(the)f(de\002nition)f(of)h FJ(urlopen\(\))p FN(,)f(abo)o(v)o(e.)p 0 5549 3901 4 v 0 5649 a FI(18.5.)52 b FJ(urllib)22 b FI(\227)h(Open)g(arbitr)o(ar)r(y)h(resources)d(b)n(y)i(URL)1880 b(619)p eop end %%Page: 620 632 TeXDict begin 620 631 bop 208 83 a FN(Additional)20 b(k)o(e)o(yw)o(ord) g(parameters,)h(collected)h(in)g FK(x509)p FN(,)f(may)g(be)h(used)g (for)f(authentication)f(of)i(the)g(client)g(when)f(using)h(the)208 183 y(`)p FO(https:)p FN(')31 b(scheme.)k(The)24 b(k)o(e)o(yw)o(ords)e FK(k)o(e)n(y)p 1396 183 25 4 v 29 w(\002le)i FN(and)f FK(cert)p 1824 183 V 30 w(\002le)h FN(are)g(supported)e(to)i(pro)o (vide)e(an)i(SSL)g(k)o(e)o(y)f(and)h(certi\002cate;)h(both)208 282 y(are)20 b(needed)f(to)h(support)f(client)h(authentication.)208 415 y FJ(URLopener)f FN(objects)h(will)h(raise)f(an)g FJ(IOError)g FN(e)o(xception)e(if)i(the)h(serv)o(er)e(returns)g(an)h (error)f(code.)0 562 y FL(class)i FD(FancyURLopener)p FJ(\()p FK(...)p FJ(\))208 661 y(FancyURLopener)31 b FN(subclasses)j FJ(URLopener)f FN(pro)o(viding)d(def)o(ault)j(handling) f(for)h(the)h(follo)n(wing)e(HTTP)i(response)208 761 y(codes:)43 b(301,)31 b(302,)g(303,)g(307)d(and)i(401.)52 b(F)o(or)29 b(the)h(30x)e(response)h(codes)g(listed)h(abo)o(v)o(e,)g (the)g FO(Location:)42 b FN(header)28 b(is)j(used)208 861 y(to)26 b(fetch)f(the)h(actual)g(URL.)g(F)o(or)f(401)g(response)g (codes)h(\(authentication)d(required\),)i(basic)h(HTTP)g (authentication)e(is)j(per)n(-)208 960 y(formed.)c(F)o(or)d(the)h(30x)e (response)h(codes,)g(recursion)f(is)i(bounded)d(by)i(the)g(v)n(alue)g (of)g(the)g FK(maxtries)h FN(attrib)n(ute,)f(which)g(def)o(aults)208 1060 y(to)g(10.)208 1193 y(F)o(or)30 b(all)i(other)e(response)f(codes,) k(the)e(method)f FJ(http_error_default\(\))d FN(is)32 b(called)f(which)f(you)g(can)h(o)o(v)o(erride)d(in)208 1292 y(subclasses)20 b(to)h(handle)e(the)h(error)f(appropriately)-5 b(.)208 1425 y FL(Note:)37 b FN(According)25 b(to)h(the)h(letter)g(of)f (RFC)i(2616,)f(301)f(and)g(302)g(responses)g(to)h(POST)g(requests)f (must)h(not)f(be)h(automati-)208 1525 y(cally)d(redirected)g(without)g (con\002rmation)e(by)j(the)f(user)-5 b(.)40 b(In)24 b(reality)-5 b(,)25 b(bro)n(wsers)f(do)g(allo)n(w)h(automatic)f(redirection)f(of)h (these)208 1624 y(responses,)19 b(changing)f(the)i(POST)h(to)f(a)h(GET) -6 b(,)20 b(and)f FJ(urllib)h FN(reproduces)e(this)j(beha)n(viour)-5 b(.)208 1757 y(The)19 b(parameters)g(to)i(the)f(constructor)e(are)i (the)h(same)f(as)h(those)f(for)f FJ(URLopener)p FN(.)208 1890 y FL(Note:)54 b FN(When)35 b(performing)d(basic)j(authentication,) i(a)f FJ(FancyURLopener)d FN(instance)h(calls)i(its)g FJ(prompt_user_-)208 1989 y(passwd\(\))20 b FN(method.)27 b(The)21 b(def)o(ault)f(implementation)f(asks)j(the)g(users)f(for)g (the)g(required)f(information)e(on)j(the)h(controlling)208 2089 y(terminal.)i(A)c(subclass)h(may)f(o)o(v)o(erride)e(this)i(method) f(to)h(support)f(more)h(appropriate)d(beha)n(vior)i(if)h(needed.)0 2236 y FL(exception)f FD(ContentTooShortError)p FJ(\()p FK(msg)p FC([)p FK(,)e(content)c FC(])p FJ(\))208 2335 y FN(This)22 b(e)o(xception)f(is)i(raised)g(when)e(the)i FJ(urlretrieve\(\))e FN(function)f(detects)j(that)g(the)f(amount)f(of)h (the)h(do)n(wnloaded)d(data)208 2435 y(is)31 b(less)h(than)e(the)h(e)o (xpected)d(amount)i(\(gi)n(v)o(en)f(by)h(the)g FK(Content-Length)f FN(header\).)54 b(The)31 b FJ(content)f FN(attrib)n(ute)g(stores)h(the) 208 2535 y(do)n(wnloaded)17 b(\(and)i(supposedly)g(truncated\))f(data.) 51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 2682 y(Restrictions:)125 2911 y FM(\017)41 b FN(Currently)-5 b(,)15 b(only)i(the)g(follo)n(wing) e(protocols)h(are)h(supported:)22 b(HTTP)-9 b(,)16 b(\(v)o(ersions)g (0.9)h(and)f(1.0\),)h(Gopher)e(\(b)n(ut)i(not)g(Gopher)n(-+\),)208 3010 y(FTP)-9 b(,)20 b(and)g(local)g(\002les.)125 3176 y FM(\017)41 b FN(The)22 b(caching)f(feature)h(of)g FJ(urlretrieve\(\)) f FN(has)i(been)e(disabled)h(until)h(I)f(\002nd)h(the)f(time)h(to)g (hack)f(proper)f(processing)g(of)208 3276 y(Expiration)d(time)i (headers.)125 3442 y FM(\017)41 b FN(There)19 b(should)g(be)h(a)h (function)d(to)j(query)d(whether)i(a)g(particular)f(URL)i(is)g(in)f (the)h(cache.)125 3607 y FM(\017)41 b FN(F)o(or)25 b(backw)o(ard)f (compatibility)-5 b(,)24 b(if)i(a)g(URL)g(appears)e(to)i(point)e(to)i (a)g(local)f(\002le)h(b)n(ut)g(the)f(\002le)h(can')o(t)f(be)g(opened,)g (the)h(URL)g(is)208 3707 y(re-interpreted)17 b(using)j(the)g(FTP)h (protocol.)i(This)d(can)g(sometimes)g(cause)g(confusing)f(error)g (messages.)125 3873 y FM(\017)41 b FN(The)24 b FJ(urlopen\(\))f FN(and)h FJ(urlretrieve\(\))f FN(functions)g(can)h(cause)h(arbitrarily) e(long)h(delays)g(while)h(w)o(aiting)f(for)g(a)h(net-)208 3973 y(w)o(ork)30 b(connection)f(to)i(be)g(set)h(up.)57 b(This)32 b(means)f(that)g(it)h(is)g(dif)n(\002cult)e(to)h(b)n(uild)g (an)g(interacti)n(v)o(e)f(W)-7 b(eb)32 b(client)f(using)f(these)208 4072 y(functions)18 b(without)i(using)f(threads.)125 4238 y FM(\017)41 b FN(The)23 b(data)i(returned)d(by)i FJ(urlopen\(\))f FN(or)h FJ(urlretrieve\(\))e FN(is)j(the)f(ra)o(w)g (data)h(returned)d(by)i(the)g(serv)o(er)-5 b(.)37 b(This)24 b(may)g(be)208 4338 y(binary)14 b(data)i(\(such)g(as)h(an)f(image\),)f (plain)h(te)o(xt)g(or)g(\(for)f(e)o(xample\))f(HTML.)i(The)f(HTTP)i (protocol)d(pro)o(vides)g(type)i(information)208 4437 y(in)24 b(the)g(reply)g(header)m(,)f(which)h(can)g(be)g(inspected)g(by) f(looking)g(at)i(the)f FO(Content-T)-9 b(ype:)30 b FN(header)-5 b(.)37 b(F)o(or)23 b(the)i(Gopher)e(protocol,)208 4537 y(type)k(information)f(is)j(encoded)e(in)h(the)h(URL;)g(there)e(is)j (currently)c(no)i(easy)g(w)o(ay)h(to)f(e)o(xtract)g(it.)50 b(If)28 b(the)g(returned)e(data)j(is)208 4636 y(HTML,)19 b(you)h(can)g(use)g(the)g(module)f FJ(htmllib)g FN(to)i(parse)f(it.)125 4802 y FM(\017)41 b FN(The)26 b(code)f(handling)g(the)h(FTP)h(protocol) e(cannot)g(dif)n(ferentiate)g(between)g(a)i(\002le)g(and)f(a)h (directory)-5 b(.)41 b(This)26 b(can)h(lead)f(to)g(un-)208 4902 y(e)o(xpected)c(beha)n(vior)h(when)h(attempting)f(to)h(read)g(a)h (URL)g(that)f(points)g(to)g(a)h(\002le)g(that)g(is)g(not)f(accessible.) 37 b(If)25 b(the)f(URL)h(ends)208 5001 y(in)i(a)h FJ(/)p FN(,)h(it)f(is)h(assumed)e(to)g(refer)g(to)g(a)h(directory)e(and)h (will)h(be)f(handled)f(accordingly)-5 b(.)44 b(But)28 b(if)f(an)h(attempt)f(to)g(read)g(a)h(\002le)208 5101 y(leads)20 b(to)h(a)g(550)e(error)h(\(meaning)e(the)j(URL)g(cannot)e (be)i(found)d(or)j(is)g(not)f(accessible,)h(often)e(for)h(permission)g (reasons\),)f(then)208 5201 y(the)28 b(path)f(is)j(treated)d(as)i(a)g (directory)d(in)i(order)f(to)i(handle)e(the)h(case)h(when)e(a)i (directory)d(is)j(speci\002ed)f(by)g(a)h(URL)f(b)n(ut)h(the)208 5300 y(trailing)23 b FJ(/)h FN(has)g(been)g(left)g(of)n(f.)35 b(This)24 b(can)g(cause)g(misleading)f(results)h(when)f(you)g(try)h(to) g(fetch)f(a)i(\002le)f(whose)g(read)f(permis-)208 5400 y(sions)g(mak)o(e)h(it)g(inaccessible;)h(the)f(FTP)g(code)f(will)h(try) f(to)h(read)f(it,)i(f)o(ail)f(with)g(a)g(550)f(error)m(,)g(and)g(then)g (perform)e(a)j(directory)p 0 5549 3901 4 v 0 5649 a FI(620)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 621 633 TeXDict begin 621 632 bop 208 83 a FN(listing)17 b(for)g(the)h (unreadable)d(\002le.)24 b(If)18 b(\002ne-grained)d(control)h(is)j (needed,)d(consider)g(using)h(the)h FJ(ftplib)f FN(module,)f (subclassing)208 183 y FJ(FancyURLOpener)p FN(,)h(or)j(changing)p 1366 183 25 4 v 48 w FK(urlopener)h FN(to)g(meet)f(your)f(needs.)125 349 y FM(\017)41 b FN(This)20 b(module)g(does)g(not)g(support)f(the)i (use)g(of)f(proxies)f(which)i(require)e(authentication.)24 b(This)d(may)f(be)g(implemented)f(in)i(the)208 448 y(future.)125 614 y FM(\017)41 b FN(Although)17 b(the)i FJ(urllib)g FN(module)f(contains)h(\(undocumented\))c(routines)j(to)i(parse)f(and)f (unparse)g(URL)i(strings,)g(the)f(recom-)208 714 y(mended)f(interf)o (ace)h(for)h(URL)h(manipulation)d(is)j(in)f(module)f FJ(urlparse)p FN(.)0 999 y Fv(18.5.1)101 b(URLopener)30 b(Objects)0 1202 y FJ(URLopener)19 b FN(and)h FJ(FancyURLopener)e FN(objects)i(ha)n(v)o(e)f(the)i(follo)n(wing)d(attrib)n(utes.)0 1349 y FD(open)p FJ(\()p FK(fullurl)p FC([)p FK(,)h(data)12 b FC(])p FJ(\))208 1448 y FN(Open)24 b FK(fullurl)i FN(using)f(the)g (appropriate)e(protocol.)39 b(This)26 b(method)e(sets)i(up)f(cache)g (and)g(proxy)e(information,)i(then)f(calls)j(the)208 1548 y(appropriate)f(open)i(method)f(with)j(its)f(input)g(ar)o (guments.)49 b(If)28 b(the)h(scheme)g(is)h(not)e(recognized,)h FJ(open_unknown\(\))e FN(is)208 1648 y(called.)d(The)c FK(data)g FN(ar)o(gument)d(has)k(the)f(same)g(meaning)f(as)i(the)f FK(data)g FN(ar)o(gument)d(of)j FJ(urlopen\(\))p FN(.)0 1794 y FD(open_unknown)p FJ(\()p FK(fullurl)p FC([)p FK(,)e(data)12 b FC(])p FJ(\))208 1894 y FN(Ov)o(erridable)18 b(interf)o(ace)h(to)h(open)f(unkno)n(wn)f(URL)j(types.)0 2041 y FD(retrieve)p FJ(\()p FK(url)p FC([)p FK(,)e(\002lename)p FC([)p FK(,)f(r)m(eporthook)q FC([)p FK(,)h(data)12 b FC(])g(])g(])p FJ(\))208 2141 y FN(Retrie)n(v)o(es)21 b(the)g(contents)g(of)g FK(url)g FN(and)g(places)g(it)h(in)g FK(\002lename)p FN(.)27 b(The)21 b(return)f(v)n(alue)h(is)h(a)g(tuple)f (consisting)f(of)h(a)h(local)f(\002lename)208 2240 y(and)h(either)g(a)h FJ(mimetools.Message)e FN(object)h(containing)f(the)i(response)e (headers)h(\(for)g(remote)g(URLs\))h(or)g FJ(None)g FN(\(for)208 2340 y(local)d(URLs\).)25 b(The)20 b(caller)g(must)h(then)f(open)f(and) g(read)h(the)g(contents)g(of)g FK(\002lename)p FN(.)k(If)c FK(\002lename)f FN(is)i(not)f(gi)n(v)o(en)f(and)h(the)g(URL)208 2439 y(refers)15 b(to)h(a)h(local)f(\002le,)h(the)f(input)g(\002lename) f(is)i(returned.)22 b(If)16 b(the)g(URL)h(is)g(non-local)d(and)i FK(\002lename)f FN(is)i(not)f(gi)n(v)o(en,)f(the)h(\002lename)208 2539 y(is)21 b(the)g(output)e(of)i FJ(tempfile.mktemp\(\))d FN(with)j(a)g(suf)n(\002x)f(that)h(matches)f(the)h(suf)n(\002x)f(of)g (the)h(last)h(path)e(component)e(of)j(the)208 2639 y(input)i(URL.)h(If) g FK(r)m(eporthook)g FN(is)h(gi)n(v)o(en,)f(it)h(must)f(be)g(a)g (function)f(accepting)g(three)g(numeric)g(parameters.)35 b(It)25 b(will)g(be)f(called)208 2738 y(after)19 b(each)h(chunk)f(of)h (data)g(is)h(read)f(from)f(the)h(netw)o(ork.)k FK(r)m(eporthook)c FN(is)h(ignored)d(for)i(local)g(URLs.)208 2871 y(If)g(the)h FK(url)g FN(uses)h(the)e(`)p FO(http:)p FN(')25 b(scheme)20 b(identi\002er)m(,)g(the)h(optional)e FK(data)h FN(ar)o(gument)f(may)h (be)h(gi)n(v)o(en)e(to)i(specify)f(a)i FJ(POST)e FN(request)208 2971 y(\(normally)27 b(the)i(request)g(type)g(is)h FJ(GET)p FN(\).)f(The)g FK(data)g FN(ar)o(gument)e(must)j(in)f(standard)f FO(application/x-www-f)n(or)r(m-ur)q(len)o(code)o(d)208 3070 y FN(format;)19 b(see)h(the)h FJ(urlencode\(\))d FN(function)h(belo)n(w)-5 b(.)0 3217 y FD(version)208 3317 y FN(V)c(ariable)22 b(that)i(speci\002es)g(the)g(user)f(agent)g (of)g(the)h(opener)e(object.)34 b(T)-7 b(o)24 b(get)g FJ(urllib)f FN(to)g(tell)h(serv)o(ers)f(that)h(it)g(is)h(a)f (particular)208 3417 y(user)c(agent,)f(set)i(this)g(in)f(a)h(subclass)f (as)h(a)g(class)g(v)n(ariable)e(or)h(in)g(the)g(constructor)f(before)f (calling)i(the)g(base)h(constructor)-5 b(.)0 3563 y(The)30 b FJ(FancyURLopener)e FN(class)k(of)n(fers)d(one)h(additional)f(method) g(that)h(should)f(be)i(o)o(v)o(erloaded)c(to)j(pro)o(vide)f(the)h (appropriate)0 3663 y(beha)n(vior:)0 3810 y FD(prompt_user_passwd)p FJ(\()p FK(host,)16 b(r)m(ealm)p FJ(\))208 3909 y FN(Return)21 b(information)f(needed)g(to)i(authenticate)f(the)h(user)g(at)g(the)g (gi)n(v)o(en)f(host)h(in)g(the)g(speci\002ed)g(security)f(realm.)30 b(The)22 b(return)208 4009 y(v)n(alue)d(should)g(be)h(a)h(tuple,)f FJ(\()p FK(user)r FJ(,)49 b FK(passwor)m(d)r FJ(\))p FN(,)20 b(which)f(can)h(be)g(used)g(for)g(basic)g(authentication.)208 4142 y(The)f(implementation)e(prompts)h(for)h(this)h(information)d(on)i (the)g(terminal;)g(an)h(application)e(should)g(o)o(v)o(erride)f(this)j (method)e(to)208 4242 y(use)i(an)g(appropriate)e(interaction)h(model)g (in)h(the)h(local)f(en)m(vironment.)0 4526 y Fv(18.5.2)101 b(Examples)0 4729 y FN(Here)20 b(is)h(an)f(e)o(xample)f(session)i(that) f(uses)h(the)f(`)p FJ(GET)p FN(')f(method)g(to)i(retrie)n(v)o(e)e(a)h (URL)h(containing)d(parameters:)236 4968 y FA(>>>)45 b(import)e(urllib)236 5059 y(>>>)i(params)e(=)i (urllib.urlencode\({'spam':)c(1,)j('eggs':)g(2,)g('bacon':)g(0}\))236 5150 y(>>>)h(f)f(=)h(urllib.urlopen\("http://www.musi-cal.co)o(m/cgi-)o (bin/qu)o(ery?\045s)o(")39 b(\045)45 b(params\))236 5242 y(>>>)g(print)f(f.read\(\))p 0 5549 3901 4 v 0 5649 a FI(18.5.)52 b FJ(urllib)22 b FI(\227)h(Open)g(arbitr)o(ar)r(y)h (resources)d(b)n(y)i(URL)1880 b(621)p eop end %%Page: 622 634 TeXDict begin 622 633 bop 0 83 a FN(The)20 b(follo)n(wing)e(e)o(xample) h(uses)i(the)f(`)p FJ(POST)p FN(')f(method)g(instead:)236 321 y FA(>>>)45 b(import)e(urllib)236 413 y(>>>)i(params)e(=)i (urllib.urlencode\({'spam':)c(1,)j('eggs':)g(2,)g('bacon':)g(0}\))236 504 y(>>>)h(f)f(=)h(urllib.urlopen\("http://www.musi-cal.co)o(m/cgi-)o (bin/qu)o(ery",)38 b(params\))236 595 y(>>>)45 b(print)f(f.read\(\))0 882 y FN(The)20 b(follo)n(wing)e(e)o(xample)h(uses)i(an)f(e)o (xplicitly)f(speci\002ed)h(HTTP)g(proxy)-5 b(,)18 b(o)o(v)o(erriding)f (en)m(vironment)g(settings:)236 1120 y FA(>>>)45 b(import)e(urllib)236 1211 y(>>>)i(proxies)e(=)i({'http':)e ('http://proxy.example.com:8080/'})236 1303 y(>>>)i(opener)e(=)i (urllib.FancyURLopener\(proxies\))236 1394 y(>>>)g(f)f(=)h (opener.open\("http://www.python.org"\))236 1485 y(>>>)g(f.read\(\))0 1772 y FN(The)20 b(follo)n(wing)e(e)o(xample)h(uses)i(no)f(proxies)f (at)i(all,)f(o)o(v)o(erriding)d(en)m(vironment)g(settings:)236 2010 y FA(>>>)45 b(import)e(urllib)236 2101 y(>>>)i(opener)e(=)i (urllib.FancyURLopener\({}\))236 2193 y(>>>)g(f)f(=)h (opener.open\("http://www.python.org/"\))236 2284 y(>>>)g(f.read\(\))0 2792 y FE(18.6)121 b Fx(urllib2)32 b FE(\227)g(e)l(xtensib)n(le)j(libr) o(ar)t(y)d(f)l(or)i(opening)i(URLs)0 3025 y FN(The)19 b FJ(urllib2)f FN(module)g(de\002nes)h(functions)e(and)i(classes)h (which)f(help)f(in)i(opening)d(URLs)j(\(mostly)e(HTTP\))h(in)g(a)h (comple)o(x)d(w)o(orld)0 3124 y(\227)k(basic)f(and)g(digest)g (authentication,)e(redirections,)g(cookies)i(and)f(more.)0 3271 y(The)h FJ(urllib2)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 3418 y FD(urlopen)p FJ(\()p FK(url)p FC([)p FK(,)g(data)12 b FC(])p FJ(\))208 3518 y FN(Open)19 b(the)h(URL)h FK(url)p FN(,)g(which)e(can)h(be)g(either)g(a)h(string)f(or)g(a)g FJ(Request)g FN(object.)208 3648 y FK(data)15 b FN(may)g(be)h(a)h (string)f(specifying)e(additional)h(data)h(to)g(send)g(to)g(the)g(serv) o(er)m(,)f(or)h FJ(None)g FN(if)g(no)g(such)g(data)g(is)h(needed.)22 b(Currently)208 3748 y(HTTP)i(requests)g(are)g(the)g(only)g(ones)g (that)g(use)h FK(data)p FN(;)h(the)e(HTTP)g(request)g(will)h(be)f(a)h (POST)g(instead)f(of)g(a)h(GET)f(when)g(the)208 3848 y FK(data)d FN(parameter)f(is)i(pro)o(vided.)28 b FK(data)21 b FN(should)f(be)i(a)g(b)n(uf)n(fer)f(in)h(the)f(standard)g FO(application/x-www-f)n(or)r(m-ur)q(le)o(ncod)o(ed)16 b FN(format.)208 3947 y(The)27 b FJ(urllib.urlencode\(\))e FN(function)g(tak)o(es)j(a)g(mapping)e(or)h(sequence)g(of)g(2-tuples)f (and)h(returns)g(a)h(string)f(in)h(this)208 4047 y(format.)208 4178 y(This)20 b(function)e(returns)i(a)g(\002le-lik)o(e)h(object)e (with)i(tw)o(o)f(additional)f(methods:)349 4387 y FM(\017)o FJ(geturl\(\))g FN(\227)i(return)e(the)h(URL)h(of)f(the)g(resource)f (retrie)n(v)o(ed)349 4515 y FM(\017)o FJ(info\(\))h FN(\227)h(return)e (the)h(meta-information)d(of)j(the)g(page,)f(as)i(a)g(dictionary-lik)o (e)c(object)208 4724 y(Raises)k FJ(URLError)e FN(on)h(errors.)208 4855 y(Note)40 b(that)g FJ(None)g FN(may)g(be)g(returned)f(if)h(no)g (handler)f(handles)g(the)i(request)e(\(though)f(the)j(def)o(ault)e (installed)h(global)208 4954 y FJ(OpenerDirector)18 b FN(uses)i FJ(UnknownHandler)f FN(to)h(ensure)f(this)i(ne)n(v)o(er)e (happens\).)0 5101 y FD(install_opener)p FJ(\()p FK(opener)r FJ(\))208 5201 y FN(Install)c(an)h FJ(OpenerDirector)e FN(instance)h(as)h(the)g(def)o(ault)f(global)g(opener)-5 b(.)22 b(Installing)15 b(an)h(opener)e(is)j(only)e(necessary)f(if)i (you)208 5300 y(w)o(ant)h(urlopen)f(to)i(use)g(that)g(opener;)f (otherwise,)g(simply)h(call)g FJ(OpenerDirector.open\(\))c FN(instead)k(of)f FJ(urlopen\(\))p FN(.)208 5400 y(The)i(code)g(does)g (not)g(check)g(for)g(a)h(real)f FJ(OpenerDirector)p FN(,)f(and)h(an)o (y)f(class)j(with)f(the)f(appropriate)e(interf)o(ace)i(will)h(w)o(ork.) p 0 5549 3901 4 v 0 5649 a FI(622)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 623 635 TeXDict begin 623 634 bop 0 83 a FD(build_opener)p FJ(\()p FC([)p FK(handler)-9 b(,)16 b(...)c FC(])p FJ(\))208 183 y FN(Return)55 b(an)h FJ(OpenerDirector)e FN(instance,)64 b(which)56 b(chains)g(the)g(handlers)e(in)j(the)f(order)e(gi)n(v)o(en.) 132 b FK(handler)r FN(s)208 282 y(can)48 b(be)g(either)g(instances)g (of)g FJ(BaseHandler)p FN(,)53 b(or)48 b(subclasses)h(of)f FJ(BaseHandler)e FN(\(in)i(which)g(case)h(it)g(must)208 382 y(be)e(possible)h(to)g(call)g(the)g(constructor)e(without)h(an)o(y) g(parameters\).)106 b(Instances)47 b(of)h(the)g(follo)n(wing)e(classes) j(will)208 482 y(be)59 b(in)g(front)f(of)h(the)h FK(handler)r FN(s,)68 b(unless)59 b(the)g FK(handler)r FN(s)f(contain)h(them,)68 b(instances)59 b(of)g(them)g(or)g(subclasses)208 581 y(of)e(them:)100 b FJ(ProxyHandler)p FN(,)65 b FJ(UnknownHandler)p FN(,)g FJ(HTTPHandler)p FN(,)h FJ(HTTPDefaultErrorHandler)p FN(,)208 681 y FJ(HTTPRedirectHandler)p FN(,)17 b FJ(FTPHandler)p FN(,)h FJ(FileHandler)p FN(,)h FJ(HTTPErrorProcessor)p FN(.)208 814 y(If)h(the)g(Python)f(installation)h(has)g(SSL)h(support)e (\()p FJ(socket.ssl\(\))f FN(e)o(xists\),)i FJ(HTTPSHandler)e FN(will)j(also)g(be)f(added.)208 946 y(Be)o(ginning)f(in)j(Python)e (2.3,)h(a)h FJ(BaseHandler)e FN(subclass)i(may)f(also)g(change)g(its)h FJ(handler_order)e FN(member)g(v)n(ariable)208 1046 y(to)g(modify)f (its)i(position)e(in)h(the)h(handlers)e(list.)0 1193 y(The)h(follo)n(wing)e(e)o(xceptions)h(are)h(raised)g(as)h (appropriate:)0 1340 y FL(exception)e FD(URLError)208 1439 y FN(The)29 b(handlers)g(raise)h(this)h(e)o(xception)d(\(or)i (deri)n(v)o(ed)e(e)o(xceptions\))g(when)h(the)o(y)h(run)f(into)h(a)g (problem.)53 b(It)30 b(is)h(a)g(subclass)f(of)208 1539 y FJ(IOError)p FN(.)0 1686 y FL(exception)19 b FD(HTTPError)208 1786 y FN(A)25 b(subclass)f(of)h FJ(URLError)p FN(,)f(it)h(can)g(also)f (function)f(as)i(a)g(non-e)o(xceptional)c(\002le-lik)o(e)k(return)e(v)n (alue)h(\(the)g(same)h(thing)e(that)208 1885 y FJ(urlopen\(\))c FN(returns\).)k(This)e(is)g(useful)e(when)h(handling)e(e)o(xotic)i (HTTP)g(errors,)f(such)h(as)h(requests)f(for)f(authentication.)0 2032 y FL(exception)g FD(GopherError)208 2132 y FN(A)h(subclass)h(of)f FJ(URLError)p FN(,)f(this)h(is)h(the)g(error)e(raised)h(by)g(the)g (Gopher)e(handler)-5 b(.)0 2279 y(The)20 b(follo)n(wing)e(classes)k (are)e(pro)o(vided:)0 2425 y FL(class)h FD(Request)p FJ(\()p FK(url)p FC([)p FK(,)e(data)12 b FC(][)p FK(,)18 b(header)o(s)12 b FC(])20 b([)p FK(,)g(origin)p 1669 2425 25 4 v 29 w(r)m(eq)p 1806 2425 V 29 w(host)13 b FC(][)p FK(,)20 b(un)m(veri\002able)12 b FC(])p FJ(\))208 2525 y FN(This)20 b(class)h(is)g(an)f(abstraction)f(of)h(a)h(URL)g (request.)208 2658 y FK(url)f FN(should)f(be)i(a)f(string)g(containing) e(a)j(v)n(alid)f(URL.)208 2791 y FK(data)15 b FN(may)g(be)h(a)h(string) f(specifying)e(additional)h(data)h(to)g(send)g(to)g(the)g(serv)o(er)m (,)f(or)h FJ(None)g FN(if)g(no)g(such)g(data)g(is)h(needed.)22 b(Currently)208 2890 y(HTTP)i(requests)g(are)g(the)g(only)g(ones)g (that)g(use)h FK(data)p FN(;)h(the)e(HTTP)g(request)g(will)h(be)f(a)h (POST)g(instead)f(of)g(a)h(GET)f(when)g(the)208 2990 y FK(data)d FN(parameter)f(is)i(pro)o(vided.)28 b FK(data)21 b FN(should)f(be)i(a)g(b)n(uf)n(fer)f(in)h(the)f(standard)g FO(application/x-www-f)n(or)r(m-ur)q(le)o(ncod)o(ed)16 b FN(format.)208 3090 y(The)27 b FJ(urllib.urlencode\(\))e FN(function)g(tak)o(es)j(a)g(mapping)e(or)h(sequence)g(of)g(2-tuples)f (and)h(returns)g(a)h(string)f(in)h(this)208 3189 y(format.)208 3322 y FK(header)o(s)22 b FN(should)h(be)g(a)g(dictionary)-5 b(,)22 b(and)h(will)h(be)f(treated)g(as)g(if)h FJ(add_header\(\))e FN(w)o(as)i(called)f(with)g(each)g(k)o(e)o(y)g(and)f(v)n(alue)208 3422 y(as)e(ar)o(guments.)208 3555 y(The)f(\002nal)i(tw)o(o)f(ar)o (guments)e(are)i(only)g(of)g(interest)g(for)f(correct)h(handling)e(of)i (third-party)e(HTTP)i(cookies:)208 3687 y FK(origin)p 417 3687 V 28 w(r)m(eq)p 553 3687 V 30 w(host)31 b FN(should)d(be)h (the)h(request-host)d(of)i(the)h(origin)e(transaction,)i(as)g (de\002ned)e(by)h(RFC)i(2965.)51 b(It)30 b(def)o(aults)e(to)208 3787 y FJ(cookielib.request_host\(self\))p FN(.)g(This)c(is)f(the)h (host)e(name)h(or)g(IP)g(address)g(of)f(the)h(original)f(request)h (that)g(w)o(as)208 3887 y(initiated)k(by)h(the)g(user)-5 b(.)48 b(F)o(or)27 b(e)o(xample,)i(if)f(the)g(request)f(is)i(for)e(an)h (image)f(in)h(an)g(HTML)g(document,)f(this)i(should)e(be)h(the)208 3986 y(request-host)18 b(of)i(the)g(request)g(for)f(the)i(page)e (containing)f(the)i(image.)208 4119 y FK(un)m(veri\002able)15 b FN(should)i(indicate)g(whether)g(the)g(request)g(is)i(un)m(v)o (eri\002able,)c(as)k(de\002ned)e(by)g(RFC)i(2965.)k(It)18 b(def)o(aults)f(to)h(F)o(alse.)25 b(An)208 4219 y(un)m(v)o(eri\002able) 15 b(request)i(is)i(one)e(whose)h(URL)g(the)g(user)g(did)f(not)h(ha)n (v)o(e)f(the)h(option)f(to)h(appro)o(v)o(e.)j(F)o(or)d(e)o(xample,)e (if)j(the)e(request)h(is)208 4318 y(for)g(an)h(image)f(in)h(an)g(HTML)f (document,)f(and)h(the)h(user)g(had)f(no)h(option)e(to)i(appro)o(v)o(e) e(the)i(automatic)e(fetching)h(of)g(the)h(image,)208 4418 y(this)h(should)f(be)i(true.)0 4565 y FL(class)g FD(OpenerDirector)p FJ(\(\))208 4664 y FN(The)f FJ(OpenerDirector)f FN(class)j(opens)e(URLs)i(via)f FJ(BaseHandler)p FN(s)f(chained)g (together)-5 b(.)26 b(It)21 b(manages)f(the)h(chaining)f(of)208 4764 y(handlers,)e(and)i(reco)o(v)o(ery)e(from)h(errors.)0 4911 y FL(class)i FD(BaseHandler)p FJ(\(\))208 5011 y FN(This)f(is)h(the)f(base)h(class)g(for)e(all)i(re)o(gistered)e (handlers)g(\227)i(and)e(handles)h(only)f(the)h(simple)g(mechanics)g (of)g(re)o(gistration.)0 5157 y FL(class)h FD(HTTPDefaultErrorHandler)p FJ(\(\))208 5257 y FN(A)k(class)h(which)e(de\002nes)h(a)g(def)o(ault)f (handler)g(for)g(HTTP)h(error)e(responses;)k(all)f(responses)e(are)h (turned)e(into)i FJ(HTTPError)208 5357 y FN(e)o(xceptions.)p 0 5549 3901 4 v 0 5649 a FI(18.6.)52 b FJ(urllib2)22 b FI(\227)h(e)n(xtensib)n(le)h(libr)o(ar)r(y)g(f)n(or)e(opening)j(URLs) 1760 b(623)p eop end %%Page: 624 636 TeXDict begin 624 635 bop 0 83 a FL(class)21 b FD(HTTPRedirectHandler)p FJ(\(\))208 183 y FN(A)f(class)h(to)g(handle)e(redirections.)0 330 y FL(class)i FD(HTTPCookieProcessor)p FJ(\()p FC([)p FK(cookiejar)14 b FC(])p FJ(\))208 429 y FN(A)20 b(class)h(to)g(handle) e(HTTP)h(Cookies.)0 576 y FL(class)h FD(ProxyHandler)p FJ(\()p FC([)p FK(pr)l(oxies)12 b FC(])p FJ(\))208 676 y FN(Cause)25 b(requests)g(to)h(go)f(through)e(a)j(proxy)-5 b(.)38 b(If)25 b FK(pr)l(oxies)h FN(is)g(gi)n(v)o(en,)f(it)h(must)g(be) f(a)h(dictionary)d(mapping)h(protocol)f(names)i(to)208 775 y(URLs)c(of)f(proxies.)j(The)d(def)o(ault)g(is)h(to)f(read)g(the)g (list)h(of)f(proxies)f(from)h(the)g(en)m(vironment)d(v)n(ariables)i (\241protocol\277)p 3541 775 25 4 v 27 w(proxy.)0 922 y FL(class)i FD(HTTPPasswordMgr)p FJ(\(\))208 1022 y FN(K)n(eep)e(a)i(database)f(of)g FJ(\()p FK(r)m(ealm)p FJ(,)49 b FK(uri)p FJ(\))g(->)h(\()p FK(user)r FJ(,)f FK(passwor)m(d)r FJ(\))20 b FN(mappings.)0 1169 y FL(class)h FD(HTTPPasswordMgrWithDefaultRealm)p FJ(\(\))208 1268 y FN(K)n(eep)e(a)g(database)g(of)g FJ(\()p FK(r)m(ealm)p FJ(,)49 b FK(uri)p FJ(\))h(->)f(\()p FK(user)r FJ(,)g FK(passwor)m(d)r FJ(\))20 b FN(mappings.)j(A)c(realm)g(of)g FJ(None)h FN(is)g(considered)d(a)j(catch-)208 1368 y(all)g(realm,)g (which)g(is)h(searched)e(if)h(no)g(other)f(realm)h(\002ts.)0 1515 y FL(class)h FD(AbstractBasicAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1798 1515 V 24 w(mgr)14 b FC(])p FJ(\))208 1614 y FN(This)23 b(is)h(a)g(mixin)f(class)h(that)f(helps)g (with)h(HTTP)f(authentication,)f(both)h(to)g(the)g(remote)g(host)g(and) g(to)g(a)h(proxy)-5 b(.)32 b FK(passwor)m(d)p 3848 1614 V 29 w(-)208 1714 y(mgr)r FN(,)27 b(if)g(gi)n(v)o(en,)f(should)g(be)g (something)f(that)h(is)i(compatible)d(with)h FJ(HTTPPasswordMgr)p FN(;)h(refer)f(to)h(section)f(18.6.7)e(for)208 1814 y(information)17 b(on)j(the)g(interf)o(ace)g(that)g(must)g(be)g(supported.)0 1961 y FL(class)h FD(HTTPBasicAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1598 1961 V 25 w(mgr)14 b FC(])p FJ(\))208 2060 y FN(Handle)25 b(authentication)f(with)j(the)f(remote)f(host.)43 b FK(passwor)m(d)p 2055 2060 V 29 w(mgr)r FN(,)28 b(if)e(gi)n(v)o(en,)h (should)e(be)h(something)f(that)h(is)h(compatible)208 2160 y(with)20 b FJ(HTTPPasswordMgr)p FN(;)e(refer)h(to)i(section)f (18.6.7)e(for)i(information)d(on)j(the)g(interf)o(ace)g(that)g(must)g (be)g(supported.)0 2307 y FL(class)h FD(ProxyBasicAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1648 2307 V 25 w(mgr)14 b FC(])p FJ(\))208 2406 y FN(Handle)27 b(authentication)f(with)j(the)f (proxy)-5 b(.)47 b FK(passwor)m(d)p 1862 2406 V 29 w(mgr)r FN(,)30 b(if)e(gi)n(v)o(en,)h(should)e(be)i(something)d(that)j(is)g (compatible)d(with)208 2506 y FJ(HTTPPasswordMgr)p FN(;)18 b(refer)h(to)h(section)g(18.6.7)f(for)g(information)f(on)i(the)g (interf)o(ace)f(that)i(must)f(be)g(supported.)0 2653 y FL(class)h FD(AbstractDigestAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1848 2653 V 24 w(mgr)14 b FC(])p FJ(\))208 2752 y FN(This)23 b(is)h(a)g(mixin)f(class)h(that)f(helps)g(with)h (HTTP)f(authentication,)f(both)h(to)g(the)g(remote)g(host)g(and)g(to)g (a)h(proxy)-5 b(.)32 b FK(passwor)m(d)p 3848 2752 V 29 w(-)208 2852 y(mgr)r FN(,)27 b(if)g(gi)n(v)o(en,)f(should)g(be)g (something)f(that)h(is)i(compatible)d(with)h FJ(HTTPPasswordMgr)p FN(;)h(refer)f(to)h(section)f(18.6.7)e(for)208 2952 y(information)17 b(on)j(the)g(interf)o(ace)g(that)g(must)g(be)g(supported.)0 3099 y FL(class)h FD(HTTPDigestAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1648 3099 V 25 w(mgr)14 b FC(])p FJ(\))208 3198 y FN(Handle)25 b(authentication)f(with)j(the)f(remote)f (host.)43 b FK(passwor)m(d)p 2055 3198 V 29 w(mgr)r FN(,)28 b(if)e(gi)n(v)o(en,)h(should)e(be)h(something)f(that)h(is)h(compatible) 208 3298 y(with)20 b FJ(HTTPPasswordMgr)p FN(;)e(refer)h(to)i(section)f (18.6.7)e(for)i(information)d(on)j(the)g(interf)o(ace)g(that)g(must)g (be)g(supported.)0 3445 y FL(class)h FD(ProxyDigestAuthHandler)p FJ(\()p FC([)p FK(passwor)m(d)p 1698 3445 V 24 w(mgr)14 b FC(])p FJ(\))208 3544 y FN(Handle)27 b(authentication)f(with)j(the)f (proxy)-5 b(.)47 b FK(passwor)m(d)p 1862 3544 V 29 w(mgr)r FN(,)30 b(if)e(gi)n(v)o(en,)h(should)e(be)i(something)d(that)j(is)g (compatible)d(with)208 3644 y FJ(HTTPPasswordMgr)p FN(;)18 b(refer)h(to)h(section)g(18.6.7)f(for)g(information)f(on)i(the)g (interf)o(ace)f(that)i(must)f(be)g(supported.)0 3791 y FL(class)h FD(HTTPHandler)p FJ(\(\))208 3890 y FN(A)f(class)h(to)g (handle)e(opening)f(of)i(HTTP)g(URLs.)0 4037 y FL(class)h FD(HTTPSHandler)p FJ(\(\))208 4137 y FN(A)f(class)h(to)g(handle)e (opening)f(of)i(HTTPS)g(URLs.)0 4284 y FL(class)h FD(FileHandler)p FJ(\(\))208 4383 y FN(Open)e(local)h(\002les.)0 4530 y FL(class)h FD(FTPHandler)p FJ(\(\))208 4630 y FN(Open)e(FTP)i(URLs.)0 4777 y FL(class)g FD(CacheFTPHandler)p FJ(\(\))208 4876 y FN(Open)e(FTP)i(URLs,)g(k)o(eeping)e(a)h(cache)g(of)g(open)f(FTP)i (connections)d(to)i(minimize)g(delays.)0 5023 y FL(class)h FD(GopherHandler)p FJ(\(\))208 5123 y FN(Open)e(gopher)f(URLs.)0 5270 y FL(class)j FD(UnknownHandler)p FJ(\(\))208 5369 y FN(A)f(catch-all)g(class)h(to)f(handle)f(unkno)n(wn)f(URLs.)p 0 5549 3901 4 v 0 5649 a FI(624)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 625 637 TeXDict begin 625 636 bop 0 83 a Fv(18.6.1)101 b(Request)28 b(Objects)0 286 y FN(The)20 b(follo)n(wing)e(methods)i(describe)f(all)i (of)f FJ(Request)p FN(')-5 b(s)19 b(public)h(interf)o(ace,)f(and)g(so)i (all)g(must)f(be)g(o)o(v)o(erridden)d(in)j(subclasses.)0 433 y FD(add_data)p FJ(\()p FK(data)p FJ(\))208 532 y FN(Set)h(the)h FJ(Request)e FN(data)h(to)g FK(data)p FN(.)28 b(This)21 b(is)h(ignored)d(by)i(all)h(handlers)e(e)o(xcept)g (HTTP)h(handlers)f(\227)i(and)f(there)g(it)g(should)g(be)208 632 y(a)f(byte)g(string,)g(and)f(will)i(change)e(the)h(request)g(to)g (be)g FJ(POST)g FN(rather)g(than)f FJ(GET)p FN(.)0 779 y FD(get_method)p FJ(\(\))208 879 y FN(Return)h(a)h(string)f (indicating)f(the)i(HTTP)g(request)e(method.)25 b(This)c(is)g(only)f (meaningful)f(for)g(HTTP)i(requests,)f(and)g(currently)208 978 y(al)o(w)o(ays)g(returns)g FJ('GET')f FN(or)h FJ('POST')p FN(.)0 1125 y FD(has_data)p FJ(\(\))208 1225 y FN(Return)f(whether)g (the)i(instance)e(has)i(a)g(non-)p FJ(None)d FN(data.)0 1372 y FD(get_data)p FJ(\(\))208 1471 y FN(Return)h(the)i(instance')-5 b(s)20 b(data.)0 1618 y FD(add_header)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(val)p FJ(\))208 1718 y FN(Add)i(another)g(header)f(to)i(the)g (request.)27 b(Headers)20 b(are)h(currently)e(ignored)h(by)g(all)i (handlers)d(e)o(xcept)h(HTTP)h(handlers,)f(where)208 1817 y(the)o(y)g(are)h(added)f(to)i(the)f(list)i(of)e(headers)f(sent)i (to)f(the)g(serv)o(er)-5 b(.)28 b(Note)21 b(that)h(there)f(cannot)f(be) h(more)f(than)h(one)g(header)f(with)i(the)208 1917 y(same)k(name,)h (and)f(later)h(calls)g(will)h(o)o(v)o(erwrite)c(pre)n(vious)h(calls)i (in)g(case)g(the)g FK(k)o(e)n(y)f FN(collides.)44 b(Currently)-5 b(,)26 b(this)h(is)g(no)g(loss)g(of)208 2017 y(HTTP)22 b(functionality)-5 b(,)20 b(since)j(all)g(headers)f(which)g(ha)n(v)o(e) g(meaning)f(when)g(used)i(more)e(than)h(once)g(ha)n(v)o(e)g(a)h (\(header)n(-speci\002c\))208 2116 y(w)o(ay)d(of)g(gaining)e(the)i (same)h(functionality)d(using)h(only)h(one)f(header)-5 b(.)0 2263 y FD(add_unredirected_header)p FJ(\()p FK(k)o(e)n(y)g(,)16 b(header)r FJ(\))208 2363 y FN(Add)j(a)i(header)e(that)h(will)h(not)f (be)g(added)f(to)h(a)h(redirected)e(request.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 2510 y FD(has_header)p FJ(\()p FK(header)r FJ(\))208 2609 y FN(Return)h(whether)g(the)i(instance)e (has)i(the)f(named)f(header)g(\(checks)h(both)f(re)o(gular)g(and)g (unredirected\).)48 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 2756 y FD(get_full_url)p FJ(\(\))208 2856 y FN(Return)g(the)i(URL)f(gi) n(v)o(en)f(in)i(the)f(constructor)-5 b(.)0 3003 y FD(get_type)p FJ(\(\))208 3102 y FN(Return)19 b(the)i(type)e(of)h(the)g(URL)h(\227)g (also)f(kno)n(wn)f(as)i(the)f(scheme.)0 3249 y FD(get_host)p FJ(\(\))208 3349 y FN(Return)f(the)i(host)f(to)g(which)g(a)g (connection)e(will)j(be)f(made.)0 3496 y FD(get_selector)p FJ(\(\))208 3595 y FN(Return)f(the)i(selector)e(\227)i(the)f(part)g(of) g(the)g(URL)h(that)f(is)i(sent)e(to)g(the)h(serv)o(er)-5 b(.)0 3742 y FD(set_proxy)p FJ(\()p FK(host,)18 b(type)p FJ(\))208 3842 y FN(Prepare)23 b(the)h(request)f(by)h(connecting)e(to)i (a)h(proxy)d(serv)o(er)-5 b(.)37 b(The)23 b FK(host)j FN(and)d FK(type)h FN(will)h(replace)f(those)g(of)f(the)i(instance,)f (and)208 3941 y(the)c(instance')-5 b(s)20 b(selector)g(will)h(be)f(the) g(original)f(URL)i(gi)n(v)o(en)e(in)h(the)g(constructor)-5 b(.)0 4088 y FD(get_origin_req_host)p FJ(\(\))208 4188 y FN(Return)31 b(the)h(request-host)e(of)i(the)g(origin)f(transaction,) i(as)g(de\002ned)e(by)h(RFC)h(2965.)59 b(See)32 b(the)g(documentation)d (for)j(the)208 4287 y FJ(Request)19 b FN(constructor)-5 b(.)0 4434 y FD(is_unverifiable)p FJ(\(\))208 4534 y FN(Return)22 b(whether)g(the)h(request)f(is)i(un)m(v)o(eri\002able,)d (as)j(de\002ned)e(by)g(RFC)j(2965.)32 b(See)23 b(the)g(documentation)d (for)i(the)h FJ(Request)208 4634 y FN(constructor)-5 b(.)0 4918 y Fv(18.6.2)101 b(OpenerDirector)29 b(Objects)0 5121 y FJ(OpenerDirector)18 b FN(instances)i(ha)n(v)o(e)g(the)g(follo)n (wing)f(methods:)0 5268 y FD(add_handler)p FJ(\()p FK(handler)r FJ(\))208 5368 y FK(handler)32 b FN(should)f(be)h(an)f(instance)h(of)f FJ(BaseHandler)p FN(.)58 b(The)32 b(follo)n(wing)e(methods)h(are)g (searched,)j(and)d(added)g(to)h(the)p 0 5549 3901 4 v 0 5649 a FI(18.6.)52 b FJ(urllib2)22 b FI(\227)h(e)n(xtensib)n(le)h (libr)o(ar)r(y)g(f)n(or)e(opening)j(URLs)1760 b(625)p eop end %%Page: 626 638 TeXDict begin 626 637 bop 208 83 a FN(possible)19 b(chains)h(\(note)g (that)g(HTTP)g(errors)g(are)g(a)g(special)h(case\).)349 296 y FM(\017)o FK(pr)l(otocol)p FJ(_open\(\))d FN(\227)j(signal)f (that)h(the)f(handler)e(kno)n(ws)i(ho)n(w)g(to)g(open)f FK(pr)l(otocol)h FN(URLs.)349 429 y FM(\017)o FJ(http_error_)p FK(type)p FJ(\(\))26 b FN(\227)j(signal)g(that)g(the)f(handler)f(kno)n (ws)h(ho)n(w)g(to)h(handle)f(HTTP)g(errors)g(with)h(HTTP)g(error)390 529 y(code)20 b FK(type)p FN(.)349 662 y FM(\017)o FK(pr)l(otocol)p FJ(_error\(\))e FN(\227)j(signal)f(that)g(the)h(handler)d(kno)n(ws)i (ho)n(w)f(to)i(handle)e(errors)g(from)g(\(non-)p FJ(http)p FN(\))f FK(pr)l(otocol)p FN(.)349 794 y FM(\017)o FK(pr)l(otocol)p FJ(_request\(\))g FN(\227)j(signal)f(that)g(the)g(handler)f(kno)n(ws)g (ho)n(w)h(to)g(pre-process)f FK(pr)l(otocol)g FN(requests.)349 927 y FM(\017)o FK(pr)l(otocol)p FJ(_response\(\))f FN(\227)i(signal)g (that)h(the)f(handler)f(kno)n(ws)g(ho)n(w)h(to)g(post-process)f FK(pr)l(otocol)g FN(responses.)0 1093 y FD(open)p FJ(\()p FK(url)p FC([)p FK(,)g(data)12 b FC(])p FJ(\))208 1193 y FN(Open)23 b(the)h(gi)n(v)o(en)f FK(url)i FN(\(which)f(can)g(be)g(a)h (request)e(object)h(or)g(a)g(string\),)h(optionally)d(passing)i(the)h (gi)n(v)o(en)e FK(data)p FN(.)36 b(Ar)o(guments,)208 1293 y(return)27 b(v)n(alues)h(and)g(e)o(xceptions)g(raised)g(are)h (the)f(same)h(as)h(those)e(of)g FJ(urlopen\(\))g FN(\(which)g(simply)g (calls)h(the)g FJ(open\(\))208 1392 y FN(method)18 b(on)i(the)g (currently)f(installed)h(global)f FJ(OpenerDirector)p FN(\).)0 1539 y FD(error)p FJ(\()p FK(pr)l(oto)p FC([)p FK(,)f(ar)m(g)p FC([)p FK(,)i(...)12 b FC(])g(])p FJ(\))208 1639 y FN(Handle)25 b(an)h(error)e(of)i(the)g(gi)n(v)o(en)f(protocol.) 40 b(This)26 b(will)h(call)f(the)g(re)o(gistered)f(error)g(handlers)f (for)i(the)g(gi)n(v)o(en)e(protocol)g(with)208 1738 y(the)f(gi)n(v)o (en)f(ar)o(guments)g(\(which)g(are)i(protocol)e(speci\002c\).)34 b(The)24 b(HTTP)f(protocol)f(is)i(a)g(special)g(case)g(which)f(uses)h (the)f(HTTP)208 1838 y(response)e(code)g(to)h(determine)f(the)h (speci\002c)g(error)f(handler;)g(refer)g(to)h(the)g FJ(http_error_)2961 1853 y(*)3011 1838 y(\(\))e FN(methods)h(of)h(the)g(handler)208 1938 y(classes.)208 2070 y(Return)d(v)n(alues)h(and)g(e)o(xceptions)e (raised)i(are)g(the)h(same)f(as)h(those)f(of)g FJ(urlopen\(\))p FN(.)0 2217 y(OpenerDirector)e(objects)i(open)f(URLs)i(in)f(three)g (stages:)0 2364 y(The)g(order)f(in)h(which)g(these)g(methods)f(are)h (called)g(within)g(each)g(stage)h(is)g(determined)d(by)i(sorting)f(the) h(handler)f(instances.)104 2594 y(1.)41 b(Ev)o(ery)30 b(handler)h(with)i(a)g(method)e(named)g(lik)o(e)i FK(pr)l(otocol)p FJ(_request\(\))c FN(has)k(that)f(method)f(called)h(to)h(pre-process)e (the)208 2694 y(request.)104 2860 y(2.)41 b(Handlers)19 b(with)h(a)g(method)f(named)f(lik)o(e)j FK(pr)l(otocol)p FJ(_open\(\))d FN(are)h(called)h(to)g(handle)f(the)h(request.)k(This)c (stage)g(ends)g(when)f(a)208 2959 y(handler)i(either)h(returns)f(a)i (non-)p FJ(None)e FN(v)n(alue)h(\(ie.)32 b(a)23 b(response\),)e(or)h (raises)i(an)e(e)o(xception)f(\(usually)g FJ(URLError)p FN(\).)31 b(Excep-)208 3059 y(tions)20 b(are)g(allo)n(wed)f(to)i (propagate.)208 3192 y(In)30 b(f)o(act,)k(the)d(abo)o(v)o(e)e (algorithm)h(is)i(\002rst)f(tried)g(for)f(methods)g(named)g FJ(default_open)p FN(.)56 b(If)31 b(all)g(such)g(methods)f(return)208 3291 y FJ(None)p FN(,)22 b(the)g(algorithm)f(is)i(repeated)e(for)g (methods)h(named)f(lik)o(e)h FK(pr)l(otocol)p FJ(_open\(\))p FN(.)29 b(If)22 b(all)h(such)f(methods)f(return)g FJ(None)p FN(,)208 3391 y(the)f(algorithm)e(is)k(repeated)c(for)i(methods)f (named)g FJ(unknown_open\(\))p FN(.)208 3524 y(Note)j(that)g(the)h (implementation)d(of)i(these)h(methods)e(may)h(in)m(v)n(olv)o(e)f (calls)i(of)f(the)h(parent)e FJ(OpenerDirector)g FN(instance')-5 b(s)208 3624 y FJ(.open\(\))19 b FN(and)h FJ(.error\(\))f FN(methods.)104 3790 y(3.)41 b(Ev)o(ery)25 b(handler)g(with)h(a)h (method)e(named)h(lik)o(e)g FK(pr)l(otocol)p FJ(_response\(\))e FN(has)j(that)f(method)g(called)g(to)g(post-process)g(the)208 3889 y(response.)0 4174 y Fv(18.6.3)101 b(BaseHandler)30 b(Objects)0 4377 y FJ(BaseHandler)20 b FN(objects)i(pro)o(vide)d(a)j (couple)f(of)g(methods)g(that)h(are)f(directly)g(useful,)g(and)g (others)h(that)f(are)h(meant)f(to)h(be)g(used)f(by)0 4477 y(deri)n(v)o(ed)d(classes.)26 b(These)20 b(are)h(intended)d(for)i (direct)g(use:)0 4623 y FD(add_parent)p FJ(\()p FK(dir)m(ector)r FJ(\))208 4723 y FN(Add)f(a)i(director)e(as)i(parent.)0 4870 y FD(close)p FJ(\(\))208 4970 y FN(Remo)o(v)o(e)e(an)o(y)g (parents.)0 5116 y(The)32 b(follo)n(wing)e(members)h(and)g(methods)g (should)g(only)g(be)h(used)g(by)f(classes)i(deri)n(v)o(ed)d(from)h FJ(BaseHandler)p FN(.)59 b FL(Note:)48 b FN(The)0 5216 y(con)m(v)o(ention)15 b(has)k(been)f(adopted)f(that)h(subclasses)h (de\002ning)e FK(pr)l(otocol)p FJ(_request\(\))f FN(or)j FK(pr)l(otocol)p FJ(_response\(\))c FN(methods)j(are)0 5316 y(named)242 5331 y FJ(*)292 5316 y(Processor)p FN(;)h(all)i (others)e(are)i(named)1476 5331 y FJ(*)1526 5316 y(Handler)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(626)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 627 639 TeXDict begin 627 638 bop 0 83 a FD(parent)208 183 y FN(A)20 b(v)n(alid)g FJ(OpenerDirector)p FN(,)e(which)i(can)g(be)g (used)g(to)g(open)f(using)h(a)g(dif)n(ferent)f(protocol,)f(or)i(handle) f(errors.)0 330 y FD(default_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 429 y FN(This)h(method)f(is)i FK(not)f FN(de\002ned)f(in)h FJ(BaseHandler)p FN(,)f(b)n(ut)h(subclasses)h(should)e(de\002ne)g(it)i (if)g(the)o(y)e(w)o(ant)i(to)f(catch)g(all)h(URLs.)208 560 y(This)c(method,)e(if)i(implemented,)f(will)h(be)g(called)g(by)f (the)h(parent)f FJ(OpenerDirector)p FN(.)22 b(It)17 b(should)e(return)h (a)h(\002le-lik)o(e)g(object)208 660 y(as)22 b(described)f(in)h(the)g (return)f(v)n(alue)g(of)h(the)g FJ(open\(\))f FN(of)h FJ(OpenerDirector)p FN(,)e(or)h FJ(None)p FN(.)30 b(It)23 b(should)d(raise)j FJ(URLError)p FN(,)208 760 y(unless)d(a)g(truly)g(e) o(xceptional)e(thing)i(happens)f(\(for)g(e)o(xample,)f FJ(MemoryError)h FN(should)g(not)h(be)g(mapped)f(to)h FJ(URLError)p FN(\).)208 891 y(This)g(method)f(will)i(be)f(called)g (before)f(an)o(y)g(protocol-speci\002c)f(open)h(method.)0 1038 y Fo(protocol)q FD(_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 1137 y FN(This)g(method)e(is)j FK(not)f FN(de\002ned)f(in)h FJ(BaseHandler)p FN(,)e(b)n(ut)i(subclasses)g(should)f(de\002ne)h(it)g (if)g(the)o(y)g(w)o(ant)g(to)g(handle)f(URLs)h(with)208 1237 y(the)h(gi)n(v)o(en)f(protocol.)208 1368 y(This)h(method,)f(if)i (de\002ned,)f(will)h(be)g(called)f(by)g(the)h(parent)f FJ(OpenerDirector)p FN(.)k(Return)c(v)n(alues)g(should)g(be)g(the)h (same)g(as)208 1468 y(for)e FJ(default_open\(\))p FN(.)0 1615 y FD(unknown_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 1714 y FN(This)25 b(method)e(is)j FK(not)g FN(de\002ned)e(in)h FJ(BaseHandler)p FN(,)g(b)n(ut)g(subclasses)g(should)f(de\002ne)g(it)i (if)f(the)o(y)f(w)o(ant)h(to)g(catch)g(all)h(URLs)208 1814 y(with)20 b(no)g(speci\002c)g(re)o(gistered)f(handler)g(to)h(open) f(it.)208 1945 y(This)h(method,)g(if)h(implemented,)d(will)k(be)e (called)h(by)f(the)h FJ(parent)f(OpenerDirector)p FN(.)25 b(Return)20 b(v)n(alues)g(should)g(be)h(the)208 2045 y(same)f(as)h(for)e FJ(default_open\(\))p FN(.)0 2192 y FD(http_error_default)p FJ(\()p FK(r)m(eq,)e(fp,)j(code)o(,)f(msg)o (,)i(hdr)o(s)p FJ(\))208 2291 y FN(This)16 b(method)f(is)j FK(not)e FN(de\002ned)f(in)i FJ(BaseHandler)p FN(,)f(b)n(ut)g (subclasses)h(should)f(o)o(v)o(erride)e(it)j(if)g(the)o(y)f(intend)f (to)i(pro)o(vide)d(a)j(catch-)208 2391 y(all)i(for)g(otherwise)f (unhandled)e(HTTP)k(errors.)j(It)d(will)f(be)g(called)g(automatically)f (by)g(the)h FJ(OpenerDirector)e FN(getting)i(the)208 2490 y(error)m(,)f(and)i(should)f(not)h(normally)e(be)i(called)g(in)h (other)e(circumstances.)208 2622 y FK(r)m(eq)f FN(will)g(be)g(a)g FJ(Request)f FN(object,)h FK(fp)g FN(will)h(be)e(a)i(\002le-lik)o(e)e (object)h(with)g(the)g(HTTP)g(error)e(body)-5 b(,)17 b FK(code)g FN(will)h(be)g(the)g(three-digit)208 2721 y(code)23 b(of)h(the)g(error)m(,)f FK(msg)h FN(will)h(be)f(the)g(user)n (-visible)f(e)o(xplanation)f(of)i(the)g(code)f(and)g FK(hdr)o(s)i FN(will)f(be)g(a)h(mapping)d(object)h(with)208 2821 y(the)d(headers)f(of)h(the)g(error)-5 b(.)208 2952 y(Return)19 b(v)n(alues)h(and)g(e)o(xceptions)e(raised)i(should)g(be)g (the)g(same)g(as)h(those)f(of)g FJ(urlopen\(\))p FN(.)0 3099 y FD(http_error_)p Fo(nnn)p FJ(\()p FK(r)m(eq,)e(fp,)i(code)o(,)g (msg)o(,)g(hdr)o(s)p FJ(\))208 3199 y FK(nnn)j FN(should)g(be)h(a)g (three-digit)f(HTTP)h(error)f(code.)36 b(This)24 b(method)f(is)i(also)f (not)g(de\002ned)f(in)h FJ(BaseHandler)p FN(,)g(b)n(ut)g(will)h(be)208 3298 y(called,)19 b(if)i(it)g(e)o(xists,)f(on)g(an)g(instance)g(of)g(a) g(subclass,)h(when)e(an)h(HTTP)h(error)e(with)h(code)g FK(nnn)f FN(occurs.)208 3429 y(Subclasses)h(should)f(o)o(v)o(erride)f (this)j(method)e(to)h(handle)f(speci\002c)h(HTTP)h(errors.)208 3561 y(Ar)o(guments,)d(return)h(v)n(alues)g(and)h(e)o(xceptions)f (raised)h(should)f(be)h(the)g(same)g(as)h(for)f FJ (http_error_default\(\))p FN(.)0 3707 y Fo(protocol)q FD(_request)p FJ(\()p FK(r)m(eq)p FJ(\))208 3807 y FN(This)25 b(method)f(is)j FK(not)e FN(de\002ned)f(in)i FJ(BaseHandler)p FN(,)f(b)n(ut)g(subclasses)h(should)f(de\002ne)f(it)j(if)e(the)o(y)g(w) o(ant)h(to)f(pre-process)f(re-)208 3907 y(quests)c(of)g(the)g(gi)n(v)o (en)f(protocol.)208 4038 y(This)i(method,)f(if)i(de\002ned,)f(will)h (be)f(called)g(by)g(the)h(parent)e FJ(OpenerDirector)p FN(.)27 b FK(r)m(eq)22 b FN(will)g(be)f(a)h FJ(Request)f FN(object.)28 b(The)208 4137 y(return)19 b(v)n(alue)g(should)g(be)h(a)h FJ(Request)e FN(object.)0 4284 y Fo(protocol)q FD(_response)p FJ(\()p FK(r)m(eq,)e(r)m(esponse)p FJ(\))208 4384 y FN(This)30 b(method)g(is)h FK(not)g FN(de\002ned)f(in)g FJ(BaseHandler)p FN(,)i(b)n(ut)f(subclasses)g(should)f(de\002ne)g(it)h(if)g(the)o(y)f(w) o(ant)h(to)g(post-process)208 4484 y(responses)19 b(of)h(the)g(gi)n(v)o (en)f(protocol.)208 4615 y(This)30 b(method,)h(if)f(de\002ned,)h(will)g (be)f(called)g(by)f(the)h(parent)f FJ(OpenerDirector)p FN(.)53 b FK(r)m(eq)30 b FN(will)h(be)f(a)g FJ(Request)f FN(object.)208 4714 y FK(r)m(esponse)e FN(will)i(be)f(an)g(object)f (implementing)f(the)i(same)g(interf)o(ace)f(as)h(the)g(return)f(v)n (alue)g(of)h FJ(urlopen\(\))p FN(.)47 b(The)28 b(return)208 4814 y(v)n(alue)19 b(should)g(implement)g(the)h(same)h(interf)o(ace)e (as)i(the)f(return)f(v)n(alue)h(of)g FJ(urlopen\(\))p FN(.)0 5097 y Fv(18.6.4)101 b(HTTPRedirectHandler)30 b(Objects)0 5300 y FL(Note:)41 b FN(Some)28 b(HTTP)h(redirections)e (require)g(action)h(from)g(this)h(module')-5 b(s)28 b(client)g(code.)50 b(If)28 b(this)h(is)h(the)e(case,)j FJ(HTTPError)d FN(is)0 5400 y(raised.)d(See)20 b(RFC)i(2616)d(for)g(details)i(of)f(the)g (precise)g(meanings)f(of)h(the)g(v)n(arious)f(redirection)g(codes.)p 0 5549 3901 4 v 0 5649 a FI(18.6.)52 b FJ(urllib2)22 b FI(\227)h(e)n(xtensib)n(le)h(libr)o(ar)r(y)g(f)n(or)e(opening)j(URLs) 1760 b(627)p eop end %%Page: 628 640 TeXDict begin 628 639 bop 0 83 a FD(redirect_request)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)f(msg)o(,)i(hdr)o(s)p FJ(\))208 183 y FN(Return)27 b(a)i FJ(Request)f FN(or)g FJ(None)g FN(in)h(response)e(to)i(a)f(redirect.)49 b(This)29 b(is)g(called)f(by)g(the)g(def)o(ault)g(implementations)e(of)j(the)208 282 y FJ(http_error_30)858 297 y(*)908 282 y(\(\))c FN(methods)h(when)h (a)h(redirection)e(is)i(recei)n(v)o(ed)e(from)h(the)g(serv)o(er)-5 b(.)47 b(If)27 b(a)h(redirection)e(should)h(tak)o(e)208 382 y(place,)38 b(return)c(a)h(ne)n(w)g FJ(Request)g FN(to)g(allo)n(w)g FJ(http_error_30)2274 397 y(*)2324 382 y(\(\))e FN(to)i(perform)e(the)i(redirect.)69 b(Otherwise,)38 b(raise)208 482 y FJ(HTTPError)18 b FN(if)h(no)g(other)f(handler)g (should)g(try)h(to)h(handle)e(this)h(URL,)h(or)f(return)f FJ(None)h FN(if)h(you)e(can')o(t)g(b)n(ut)h(another)f(handler)208 581 y(might.)208 714 y FL(Note:)47 b FN(The)32 b(def)o(ault)f (implementation)f(of)h(this)i(method)d(does)i(not)f(strictly)h(follo)n (w)f(RFC)j(2616,)f(which)e(says)i(that)e(301)208 814 y(and)21 b(302)h(responses)f(to)h FJ(POST)g FN(requests)g(must)h(not)e (be)i(automatically)d(redirected)h(without)g(con\002rmation)g(by)g(the) i(user)-5 b(.)31 b(In)208 913 y(reality)-5 b(,)16 b(bro)n(wsers)g(do)h (allo)n(w)g(automatic)f(redirection)f(of)i(these)g(responses,)g (changing)e(the)i(POST)g(to)h(a)f FJ(GET)p FN(,)g(and)f(the)h(def)o (ault)208 1013 y(implementation)h(reproduces)f(this)k(beha)n(vior)-5 b(.)0 1160 y FD(http_error_301)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 1259 y FN(Redirect)k(to)g(the)g FJ(Location:)33 b FN(URL.)24 b(This)h(method)e(is)i(called)f(by)g(the)g(parent)f FJ(OpenerDirector)g FN(when)g(getting)h(an)208 1359 y(HTTP)c(`mo)o(v)o(ed)e(permanently')f (response.)0 1506 y FD(http_error_302)p FJ(\()p FK(r)m(eq,)g(fp,)j (code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 1605 y FN(The)f(same)i(as)g FJ(http_error_301\(\))p FN(,)c(b)n(ut)j(called)g(for)g(the)g(`found')e (response.)0 1752 y FD(http_error_303)p FJ(\()p FK(r)m(eq,)f(fp,)j (code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 1852 y FN(The)f(same)i(as)g FJ(http_error_301\(\))p FN(,)c(b)n(ut)j(called)g(for)g(the)g(`see)h (other')e(response.)0 1999 y FD(http_error_307)p FJ(\()p FK(r)m(eq,)e(fp,)j(code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 2098 y FN(The)f(same)i(as)g FJ(http_error_301\(\))p FN(,)c(b)n(ut)j (called)g(for)g(the)g(`temporary)e(redirect')h(response.)0 2383 y Fv(18.6.5)101 b(HTTPCookieProcessor)30 b(Objects)0 2586 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 2733 y FJ(HTTPCookieProcessor)e FN(instances)j(ha)n(v)o(e)g(one)g(attrib)n (ute:)0 2880 y FD(cookiejar)208 2980 y FN(The)f FJ(cookielib.CookieJar) f FN(in)i(which)g(cookies)f(are)h(stored.)0 3265 y Fv(18.6.6)101 b(Pro)m(xyHandler)30 b(Objects)0 3453 y Fo(protocol)q FD(_open)p FJ(\()p FK(r)m(equest)q FJ(\))208 3553 y FN(The)19 b FJ(ProxyHandler)f FN(will)j(ha)n(v)o(e)f(a)g(method)f FK(pr)l(otocol)p FJ(_open\(\))e FN(for)j(e)n(v)o(ery)e FK(pr)l(otocol)i FN(which)f(has)h(a)h(proxy)d(in)i(the)g FK(pr)l(ox-)208 3653 y(ies)27 b FN(dictionary)e(gi)n(v)o(en)g(in)i(the) g(constructor)-5 b(.)42 b(The)27 b(method)e(will)i(modify)e(requests)i (to)g(go)f(through)e(the)j(proxy)-5 b(,)26 b(by)g(calling)208 3752 y FJ(request.set_proxy\(\))p FN(,)17 b(and)i(call)i(the)f(ne)o(xt) f(handler)g(in)i(the)f(chain)f(to)i(actually)e(e)o(x)o(ecute)g(the)h (protocol.)0 4037 y Fv(18.6.7)101 b(HTTPP)l(ass)m(w)o(ordMg)o(r)29 b(Objects)0 4240 y FN(These)20 b(methods)f(are)h(a)n(v)n(ailable)g(on)g FJ(HTTPPasswordMgr)e FN(and)h FJ(HTTPPasswordMgrWithDefaultRealm)c FN(objects.)0 4387 y FD(add_password)p FJ(\()p FK(r)m(ealm,)j(uri,)i (user)-9 b(,)20 b(passwd)r FJ(\))208 4487 y FK(uri)26 b FN(can)g(be)g(either)g(a)g(single)h(URI,)f(or)g(a)g(sequence)f(of)h (URIs.)44 b FK(r)m(ealm)p FN(,)27 b FK(user)i FN(and)d FK(passwd)i FN(must)e(be)g(strings.)43 b(This)26 b(causes)208 4586 y FJ(\()p FK(user)r FJ(,)49 b FK(passwd)r FJ(\))21 b FN(to)h(be)f(used)g(as)h(authentication)e(tok)o(ens)h(when)f (authentication)g(for)g FK(r)m(ealm)i FN(and)f(a)g(super)n(-URI)g(of)g (an)o(y)g(of)208 4686 y(the)f(gi)n(v)o(en)f(URIs)i(is)g(gi)n(v)o(en.)0 4833 y FD(find_user_password)p FJ(\()p FK(r)m(ealm,)c(authuri)p FJ(\))208 4932 y FN(Get)27 b(user/passw)o(ord)f(for)g(gi)n(v)o(en)g (realm)g(and)h(URI,)g(if)g(an)o(y)-5 b(.)44 b(This)27 b(method)f(will)h(return)f FJ(\(None,)49 b(None\))26 b FN(if)i(there)e(is)i(no)208 5032 y(matching)18 b(user/passw)o(ord.) 208 5165 y(F)o(or)j FJ(HTTPPasswordMgrWithDefaultRealm)16 b FN(objects,)22 b(the)f(realm)h FJ(None)f FN(will)h(be)g(searched)f (if)g(the)h(gi)n(v)o(en)e FK(r)m(ealm)208 5264 y FN(has)g(no)g (matching)f(user/passw)o(ord.)p 0 5549 3901 4 v 0 5649 a FI(628)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 629 641 TeXDict begin 629 640 bop 0 83 a Fv(18.6.8)101 b(Abstr)o(actBasicA)m (uthHandler)31 b(Objects)0 272 y FD(http_error_auth_reqed)p FJ(\()p FK(authr)m(eq,)15 b(host,)20 b(r)m(eq,)g(header)o(s)p FJ(\))208 372 y FN(Handle)28 b(an)h(authentication)f(request)g(by)h (getting)g(a)h(user/passw)o(ord)e(pair)m(,)i(and)f(re-trying)e(the)j (request.)51 b FK(authr)m(eq)29 b FN(should)208 471 y(be)24 b(the)g(name)g(of)g(the)g(header)g(where)f(the)i(information)d(about)h (the)h(realm)g(is)i(included)d(in)h(the)g(request,)h FK(host)h FN(speci\002es)f(the)208 571 y(URL)e(and)e(path)h(to)h (authenticate)e(for)m(,)h FK(r)m(eq)g FN(should)g(be)g(the)g(\(f)o (ailed\))g FJ(Request)g FN(object,)g(and)g FK(header)o(s)g FN(should)f(be)h(the)h(error)208 670 y(headers.)208 803 y FK(host)43 b FN(is)f(either)g(an)f(authority)f(\(e.g.)89 b FJ("python.org")p FN(\))40 b(or)h(a)h(URL)h(containing)d(an)h (authority)f(component)f(\(e.g.)208 903 y FJ("http://python.org/")p FN(\).)75 b(In)38 b(either)g(case,)43 b(the)c(authority)e(must)h(not)g (contain)f(a)i(userinfo)e(component)f(\(so,)208 1002 y FJ("python.org")18 b FN(and)i FJ("python.org:80")e FN(are)i(\002ne,)g FJ("joe:password@python.org")c FN(is)21 b(not\).)0 1287 y Fv(18.6.9)101 b(HTTPBasicA)m(uthHandler)31 b(Objects)0 1476 y FD(http_error_401)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 1576 y FN(Retry)g(the)g(request)g(with)g(authentication)e(information,)g(if) i(a)n(v)n(ailable.)0 1861 y Fv(18.6.10)101 b(Pro)m(xyBasicA)m (uthHandler)32 b(Objects)0 2050 y FD(http_error_407)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 2149 y FN(Retry)g(the)g(request)g(with)g(authentication)e (information,)g(if)i(a)n(v)n(ailable.)0 2434 y Fv(18.6.11)101 b(Abstr)o(actDigestA)m(uthHandler)31 b(Objects)0 2623 y FD(http_error_auth_reqed)p FJ(\()p FK(authr)m(eq,)15 b(host,)20 b(r)m(eq,)g(header)o(s)p FJ(\))208 2723 y FK(authr)m(eq)e FN(should)h(be)h(the)f(name)h(of)f(the)h(header)f (where)g(the)g(information)f(about)h(the)h(realm)f(is)i(included)d(in)i (the)g(request,)f FK(host)208 2822 y FN(should)25 b(be)i(the)g(host)f (to)h(authenticate)e(to,)k FK(r)m(eq)e FN(should)e(be)i(the)g(\(f)o (ailed\))e FJ(Request)h FN(object,)i(and)e FK(header)o(s)g FN(should)g(be)h(the)208 2922 y(error)19 b(headers.)0 3207 y Fv(18.6.12)101 b(HTTPDigestA)m(uthHandler)31 b(Objects)0 3396 y FD(http_error_401)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)g (msg)o(,)g(hdr)o(s)p FJ(\))208 3495 y FN(Retry)g(the)g(request)g(with)g (authentication)e(information,)g(if)i(a)n(v)n(ailable.)0 3780 y Fv(18.6.13)101 b(Pro)m(xyDigestA)m(uthHandler)31 b(Objects)0 3969 y FD(http_error_407)p FJ(\()p FK(r)m(eq,)17 b(fp,)j(code)o(,)g(msg)o(,)g(hdr)o(s)p FJ(\))208 4069 y FN(Retry)g(the)g(request)g(with)g(authentication)e(information,)g(if) i(a)n(v)n(ailable.)0 4354 y Fv(18.6.14)101 b(HTTPHandler)30 b(Objects)0 4542 y FD(http_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 4642 y FN(Send)19 b(an)h(HTTP)h(request,)e(which)h(can)g(be)g (either)g(GET)g(or)g(POST)-6 b(,)20 b(depending)e(on)h FK(r)m(eq)p FJ(.has_data\(\))p FN(.)0 4927 y Fv(18.6.15)101 b(HTTPSHandler)30 b(Objects)0 5116 y FD(https_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 5216 y FN(Send)19 b(an)h(HTTPS)h (request,)e(which)h(can)g(be)g(either)g(GET)g(or)g(POST)-6 b(,)20 b(depending)e(on)i FK(r)m(eq)p FJ(.has_data\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(18.6.)52 b FJ(urllib2)22 b FI(\227)h(e)n(xtensib)n(le)h(libr)o(ar)r(y)g(f)n(or)e(opening)j(URLs) 1760 b(629)p eop end %%Page: 630 642 TeXDict begin 630 641 bop 0 83 a Fv(18.6.16)101 b(FileHandler)30 b(Objects)0 272 y FD(file_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 372 y FN(Open)19 b(the)g(\002le)i(locally)-5 b(,)18 b(if)i(there)g(is)g(no)g(host)f(name,)g(or)h(the)f(host)h(name)f (is)i FJ('localhost')p FN(.)i(Change)c(the)h(protocol)e(to)i FJ(ftp)208 471 y FN(otherwise,)f(and)g(retry)h(opening)e(it)j(using)f FJ(parent)p FN(.)0 756 y Fv(18.6.17)101 b(FTPHandler)30 b(Objects)0 945 y FD(ftp_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 1045 y FN(Open)19 b(the)h(FTP)h(\002le)g(indicated)e(by)h FK(r)m(eq)p FN(.)25 b(The)20 b(login)f(is)i(al)o(w)o(ays)g(done)e(with) i(empty)e(username)g(and)g(passw)o(ord.)0 1329 y Fv(18.6.18)101 b(CacheFTPHandler)31 b(Objects)0 1532 y FJ(CacheFTPHandler)18 b FN(objects)i(are)g FJ(FTPHandler)f FN(objects)h(with)g(the)g(follo)n (wing)f(additional)g(methods:)0 1679 y FD(setTimeout)p FJ(\()p FK(t)q FJ(\))208 1779 y FN(Set)h(timeout)g(of)g(connections)e (to)i FK(t)j FN(seconds.)0 1926 y FD(setMaxConns)p FJ(\()p FK(m)p FJ(\))208 2025 y FN(Set)d(maximum)f(number)f(of)i(cached)f (connections)g(to)h FK(m)p FN(.)0 2310 y Fv(18.6.19)101 b(GopherHandler)31 b(Objects)0 2499 y FD(gopher_open)p FJ(\()p FK(r)m(eq)p FJ(\))208 2599 y FN(Open)19 b(the)h(gopher)f (resource)g(indicated)g(by)g FK(r)m(eq)p FN(.)0 2884 y Fv(18.6.20)101 b(Unkno)o(wnHandler)30 b(Objects)0 3073 y FD(unknown_open)p FJ(\(\))208 3172 y FN(Raise)21 b(a)f FJ(URLError)g FN(e)o(xception.)0 3457 y Fv(18.6.21)101 b(HTTPErrorProcessor)31 b(Objects)0 3660 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 3807 y FD(unknown_open)p FJ(\(\))208 3906 y FN(Process)h(HTTP)g(error)f(responses.)208 4039 y(F)o(or)g(200)h(error)f(codes,)g(the)h(response)g(object)f(is)j (returned)c(immediately)-5 b(.)208 4172 y(F)o(or)33 b(non-200)e(error)h (codes,)37 b(this)d(simply)f(passes)h(the)g(job)f(on)g(to)h(the)g FK(pr)l(otocol)p FJ(_error_)p FK(code)p FJ(\(\))c FN(handler)i (methods,)208 4272 y(via)27 b FJ(OpenerDirector.error\(\))p FN(.)44 b(Ev)o(entually)-5 b(,)28 b FJ(urllib2.HTTPDefaultErrorHandler) 22 b FN(will)29 b(raise)f(an)208 4371 y FJ(HTTPError)19 b FN(if)h(no)g(other)f(handler)g(handles)g(the)i(error)-5 b(.)0 4656 y Fv(18.6.22)101 b(Examples)0 4859 y FN(This)20 b(e)o(xample)f(gets)i(the)f(p)o(ython.or)o(g)c(main)k(page)g(and)f (displays)h(the)g(\002rst)h(100)f(bytes)g(of)g(it:)p 0 5549 3901 4 v 0 5649 a FI(630)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 631 643 TeXDict begin 631 642 bop 236 174 a FA(>>>)45 b(import)e(urllib2)236 266 y(>>>)i(f)f(=)h(urllib2.urlopen\('http://www.python.org)o(/'\))236 357 y(>>>)g(print)f(f.read\(100\))236 448 y(<!DOCTYPE)g(html)g(PUBLIC)g ("-//W3C//DTD)e(HTML)i(4.01)h(Transitional//EN">)236 540 y(<?xml-stylesheet)d(href="./css/ht2html)0 826 y FN(Here)23 b(we)g(are)g(sending)f(a)h(data-stream)f(to)h(the)g(stdin)g (of)g(a)g(CGI)h(and)e(reading)f(the)i(data)g(it)h(returns)e(to)h(us.)34 b(Note)22 b(that)h(this)h(e)o(xample)0 926 y(will)d(only)e(w)o(ork)h (when)f(the)i(Python)e(installation)g(supports)h(SSL.)236 1164 y FA(>>>)45 b(import)e(urllib2)236 1255 y(>>>)i(req)f(=)h (urllib2.Request\(url='https://localho)o(st/cgi)o(-bin/t)o(est.cg)o (i',)236 1347 y(...)1031 b(data='This)43 b(data)h(is)h(passed)e(to)i (stdin)f(of)g(the)h(CGI'\))236 1438 y(>>>)g(f)f(=)h (urllib2.urlopen\(req\))236 1529 y(>>>)g(print)f(f.read\(\))236 1621 y(Got)h(Data:)f("This)g(data)g(is)g(passed)g(to)h(stdin)e(of)i (the)f(CGI")0 1907 y FN(The)20 b(code)f(for)h(the)g(sample)g(CGI)h (used)f(in)g(the)g(abo)o(v)o(e)f(e)o(xample)g(is:)236 2145 y FA(#!/usr/bin/env)43 b(python)236 2237 y(import)h(sys)236 2328 y(data)g(=)h(sys.stdin.read\(\))236 2419 y(print)f('Content-type:) f(text-plain\\n\\nGot)f(Data:)i("\045s"')g(\045)g(data)0 2706 y FN(Use)21 b(of)f(Basic)h(HTTP)f(Authentication:)236 2944 y FA(import)44 b(urllib2)236 3035 y(#)h(Create)f(an)g (OpenerDirector)f(with)h(support)f(for)i(Basic)f(HTTP)g (Authentication...)236 3127 y(auth_handler)f(=)i (urllib2.HTTPBasicAuthHandler\(\))236 3218 y (auth_handler.add_password\(realm='PDQ)39 b(Application',)1402 3309 y(uri='https://mahler:8092/site-updates.)o(py',)1402 3401 y(user='klem',)1402 3492 y(passwd='kadidd!ehopper'\))236 3583 y(opener)44 b(=)h(urllib2.build_opener\(auth_handler\))236 3675 y(#)g(...and)f(install)f(it)i(globally)e(so)i(it)f(can)h(be)f (used)g(with)g(urlopen.)236 3766 y(urllib2.install_opener\(opener\))236 3857 y(urllib2.urlopen\('http://www.example.com/)o(login.)o(html'\))0 4144 y FJ(build_opener\(\))15 b FN(pro)o(vides)h(man)o(y)g(handlers)h (by)g(def)o(ault,)g(including)e(a)j FJ(ProxyHandler)p FN(.)k(By)c(def)o(ault,)f FJ(ProxyHandler)0 4243 y FN(uses)30 b(the)f(en)m(vironment)d(v)n(ariables)i(named)g FJ(<scheme>_proxy)p FN(,)h(where)f FJ(<scheme>)g FN(is)i(the)f(URL)h(scheme)f(in)m(v)n(olv) o(ed.)49 b(F)o(or)0 4343 y(e)o(xample,)19 b(the)h(http)p 579 4343 25 4 v 29 w(proxy)e(en)m(vironment)f(v)n(ariable)i(is)j(read)d (to)i(obtain)e(the)h(HTTP)g(proxy')-5 b(s)19 b(URL.)0 4490 y(This)28 b(e)o(xample)e(replaces)h(the)h(def)o(ault)f FJ(ProxyHandler)f FN(with)i(one)f(that)h(uses)g (programatically-supplied)23 b(proxy)j(URLs,)k(and)0 4589 y(adds)20 b(proxy)e(authorization)g(support)h(with)h FJ(ProxyBasicAuthHandler)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(18.6.)52 b FJ(urllib2)22 b FI(\227)h(e)n(xtensib)n(le)h(libr)o(ar) r(y)g(f)n(or)e(opening)j(URLs)1760 b(631)p eop end %%Page: 632 644 TeXDict begin 632 643 bop 236 83 a FA(proxy_handler)43 b(=)i(urllib2.ProxyHandler\({'http':)39 b ('http://www.example.com:3128/'}\))236 174 y(proxy_auth_handler)j(=)j (urllib2.HTTPBasicAuthHandler\(\))236 266 y (proxy_auth_handler.add_password\('realm',)38 b('host',)44 b('username',)f('password'\))236 448 y(opener)h(=)h (build_opener\(proxy_handler,)40 b(proxy_auth_handler\))236 540 y(#)45 b(This)f(time,)g(rather)g(than)g(install)g(the)g (OpenerDirector,)e(we)j(use)f(it)h(directly:)236 631 y(opener.open\('http://www.example.com/logi)o(n.html)o('\))0 917 y FN(Adding)19 b(HTTP)h(headers:)0 1064 y(Use)h(the)f FK(header)o(s)g FN(ar)o(gument)e(to)i(the)g FJ(Request)g FN(constructor)m(,)d(or:)236 1303 y FA(import)44 b(urllib2)236 1394 y(req)h(=)f(urllib2.Request\('http://www.example.com/)o('\))236 1485 y(req.add_header\('Referer',)d('http://www.python.org/'\))236 1577 y(r)k(=)g(urllib2.urlopen\(req\))0 1863 y FJ(OpenerDirector)18 b FN(automatically)h(adds)h(a)g FO(User-Agent:)k FN(header)19 b(to)h(e)n(v)o(ery)f FJ(Request)p FN(.)24 b(T)-7 b(o)20 b(change)f(this:)236 2010 y FA(import)44 b(urllib2)236 2101 y(opener)g(=)h(urllib2.build_opener\(\))236 2193 y(opener.addheaders)d(=)j([\('User-agent',)d('Mozilla/5.0'\)])236 2284 y(opener.open\('http://www.example.com/'\))0 2570 y FN(Also,)17 b(remember)d(that)j(a)f(fe)n(w)h(standard)e(headers)g(\() p FO(Content-Length:)p FN(,)d FO(Content-T)-9 b(ype:)20 b FN(and)c FO(Host:)p FN(\))22 b(are)16 b(added)f(when)h(the)g FJ(Request)0 2670 y FN(is)21 b(passed)f(to)h FJ(urlopen\(\))e FN(\(or)g FJ(OpenerDirector.open\(\))p FN(\).)0 2997 y FE(18.7)121 b Fx(httplib)32 b FE(\227)g(HTTP)i(protocol)g(client)0 3230 y FN(This)25 b(module)e(de\002nes)h(classes)i(which)e(implement)f (the)i(client)g(side)f(of)h(the)f(HTTP)h(and)f(HTTPS)h(protocols.)37 b(It)24 b(is)i(normally)d(not)0 3330 y(used)d(directly)f(\227)i(the)f (module)f FJ(urllib)h FN(uses)g(it)h(to)g(handle)e(URLs)i(that)f(use)h (HTTP)f(and)g(HTTPS.)0 3477 y FL(Note:)k FN(HTTPS)d(support)e(is)i (only)e(a)n(v)n(ailable)h(if)g(the)h FJ(socket)e FN(module)g(w)o(as)i (compiled)e(with)h(SSL)h(support.)0 3624 y FL(Note:)29 b FN(The)23 b(public)f(interf)o(ace)f(for)i(this)g(module)e(changed)g (substantially)h(in)h(Python)f(2.0.)31 b(The)23 b FJ(HTTP)f FN(class)i(is)g(retained)d(only)h(for)0 3723 y(backw)o(ard)d (compatibility)f(with)j(1.5.2.)i(It)e(should)e(not)h(be)g(used)g(in)g (ne)n(w)g(code.)k(Refer)c(to)h(the)f(online)f(docstrings)g(for)h (usage.)0 3870 y(The)g(module)f(pro)o(vides)f(the)i(follo)n(wing)f (classes:)0 4017 y FL(class)i FD(HTTPConnection)p FJ(\()p FK(host)q FC([)p FK(,)c(port)q FC([)p FK(,)j(strict)13 b FC(])f(])p FJ(\))208 4117 y FN(An)29 b FJ(HTTPConnection)f FN(instance)h(represents)g(one)g(transaction)f(with)i(an)g(HTTP)f(serv) o(er)-5 b(.)53 b(It)30 b(should)f(be)g(instantiated)208 4216 y(passing)18 b(it)i(a)g(host)f(and)f(optional)g(port)h(number)-5 b(.)23 b(If)c(no)f(port)h(number)e(is)j(passed,)f(the)g(port)g(is)h(e)o (xtracted)e(from)g(the)h(host)g(string)208 4316 y(if)k(it)g(has)g(the)g (form)f FK(host)q FJ(:)p FK(port)q FN(,)h(else)g(the)g(def)o(ault)f (HTTP)h(port)f(\(80\))g(is)h(used.)33 b(When)22 b(T)m(rue,)h(the)g (optional)e(parameter)g FK(strict)208 4415 y FN(causes)f FJ(BadStatusLine)e FN(to)j(be)f(raised)g(if)g(the)g(status)h(line)g (can')o(t)e(be)h(parsed)f(as)i(a)g(v)n(alid)f(HTTP/1.0)f(or)h(1.1)f (status)i(line.)208 4548 y(F)o(or)e(e)o(xample,)g(the)h(follo)n(wing)f (calls)i(all)f(create)g(instances)g(that)h(connect)e(to)h(the)g(serv)o (er)g(at)g(the)g(same)h(host)f(and)g(port:)444 4772 y FA(>>>)44 b(h1)h(=)f(httplib.HTTPConnection\('www.cwi.nl'\))444 4864 y(>>>)g(h2)h(=)f(httplib.HTTPConnection\('www.cwi.nl:80'\))444 4955 y(>>>)g(h3)h(=)f(httplib.HTTPConnection\('www.cwi.nl',)39 b(80\))208 5111 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 5258 y FL(class)i FD(HTTPSConnection)p FJ(\()p FK(host)q FC([)p FK(,)c(port)q FC([)p FK(,)j(k)o(e)n(y)p 1539 5258 25 4 v 29 w(\002le)p FC([)p FK(,)g(cert)p 1880 5258 V 30 w(\002le)p FC([)p FK(,)g(strict)13 b FC(])f(])g(])g(])p FJ(\))208 5358 y FN(A)22 b(subclass)g(of)f FJ(HTTPConnection)f FN(that)i(uses)g(SSL)h(for)e(communication)e(with)j(secure)f(serv)o (ers.)29 b(Def)o(ault)22 b(port)f(is)i FJ(443)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(632)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 633 645 TeXDict begin 633 644 bop 208 83 a FK(k)o(e)n(y)p 321 83 25 4 v 29 w(\002le)16 b FN(is)h(the)f(name)g(of)g(a)g(PEM)g (formatted)f(\002le)i(that)f(contains)f(your)g(pri)n(v)n(ate)g(k)o(e)o (y)-5 b(.)23 b FK(cert)p 2777 83 V 30 w(\002le)16 b FN(is)h(a)g(PEM)f (formatted)f(certi\002cate)208 183 y(chain)k(\002le.)208 315 y FL(W)-5 b(ar)o(ning:)24 b FN(This)c(does)g(not)g(do)g(an)o(y)f (certi\002cate)h(v)o(eri\002cation!)208 448 y(Ne)n(w)g(in)g(v)o(ersion) f(2.0.)0 595 y FL(class)i FD(HTTPResponse)p FJ(\()p FK(soc)n(k)q FC([)p FK(,)d(deb)n(ugle)o(vel=0)12 b FC(][)p FK(,)17 b(strict=0)12 b FC(])p FJ(\))208 695 y FN(Class)30 b(whose)e(instances) h(are)g(returned)e(upon)g(successful)i(connection.)49 b(Not)29 b(instantiated)f(directly)g(by)g(user)-5 b(.)103 b(Ne)n(w)29 b(in)208 794 y(v)o(ersion)18 b(2.0.)0 941 y(The)i(follo)n(wing)e(e)o(xceptions)h(are)h(raised)g(as)h (appropriate:)0 1088 y FL(exception)e FD(HTTPException)208 1188 y FN(The)g(base)i(class)g(of)f(the)g(other)f(e)o(xceptions)g(in)h (this)h(module.)j(It)c(is)h(a)g(subclass)f(of)g FJ(Exception)p FN(.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 1335 y FL(exception)g FD(NotConnected)208 1434 y FN(A)h(subclass)h(of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 1581 y FL(exception)g FD(InvalidURL)208 1681 y FN(A)i(subclass)g(of)g FJ(HTTPException)p FN(,)d(raised)j(if)g(a)g(port)g(is)g(gi)n(v)o(en)f (and)g(is)i(either)e(non-numeric)e(or)j(empty)-5 b(.)53 b(Ne)n(w)21 b(in)g(v)o(ersion)208 1780 y(2.3.)0 1927 y FL(exception)e FD(UnknownProtocol)208 2027 y FN(A)h(subclass)h(of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 2174 y FL(exception)g FD(UnknownTransferEncoding)208 2273 y FN(A)h(subclass)h(of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 2420 y FL(exception)g FD(UnimplementedFileMode)208 2520 y FN(A)h(subclass)h(of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 2667 y FL(exception)g FD(IncompleteRead)208 2766 y FN(A)h(subclass)h (of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 2913 y FL(exception)g FD(ImproperConnectionState)208 3013 y FN(A)h(subclass)h(of)f FJ(HTTPException)p FN(.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.0.)0 3160 y FL(exception)g FD(CannotSendRequest)208 3259 y FN(A)h(subclass)h(of)f FJ(ImproperConnectionState)p FN(.)47 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.0.)0 3406 y FL(exception)g FD(CannotSendHeader)208 3506 y FN(A)h(subclass)h(of)f FJ(ImproperConnectionState)p FN(.)47 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 3653 y FL(exception)g FD(ResponseNotReady)208 3752 y FN(A)h(subclass)h(of)f FJ(ImproperConnectionState)p FN(.)47 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.0.)0 3899 y FL(exception)g FD(BadStatusLine)208 3999 y FN(A)d(subclass)g(of)g FJ(HTTPException)p FN(.)22 b(Raised)16 b(if)h(a)f(serv)o(er)f(responds)g(with)h(a)h(HTTP)f(status)h(code)e (that)h(we)h(don')o(t)d(understand.)208 4099 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 4245 y(The)h(constants)g(de\002ned)f(in)h (this)h(module)e(are:)0 4392 y FD(HTTP_PORT)208 4492 y FN(The)g(def)o(ault)h(port)f(for)h(the)g(HTTP)g(protocol)f(\(al)o(w)o (ays)h FJ(80)p FN(\).)0 4639 y FD(HTTPS_PORT)208 4738 y FN(The)f(def)o(ault)h(port)f(for)h(the)g(HTTPS)h(protocol)d(\(al)o(w) o(ays)i FJ(443)p FN(\).)0 4885 y(and)g(also)g(the)g(follo)n(wing)f (constants)h(for)f(inte)o(ger)g(status)i(codes:)p 0 5549 3901 4 v 0 5649 a FI(18.7.)52 b FJ(httplib)22 b FI(\227)h(HTTP)g (protocol)g(client)2297 b(633)p eop end %%Page: 634 646 TeXDict begin 634 645 bop 68 70 a FL(Constant)p 1660 100 4 100 v 1320 w(V)-8 b(alue)p 1960 100 V 99 w(De\002nition)p 18 103 3865 4 v 68 173 a FJ(CONTINUE)p 1660 203 4 100 v 1269 w(100)p 1960 203 V 124 w FN(HTTP/1.1,)19 b(RFC)j(2616,)c (Section)i(10.1.1)68 272 y FJ(SWITCHING_PROTOCOLS)p 1660 302 V 719 w(101)p 1960 302 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.1.2)68 372 y FJ(PROCESSING)p 1660 402 V 1169 w(102)p 1960 402 V 124 w FN(WEBD)m(A)-11 b(V)g(,)21 b(RFC)g(2518,)e(Section)h(10.1)68 472 y FJ(OK)p 1660 501 V 1569 w(200)p 1960 501 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.2.1)68 571 y FJ(CREATED)p 1660 601 V 1319 w(201)p 1960 601 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.2) 68 671 y FJ(ACCEPTED)p 1660 701 V 1269 w(202)p 1960 701 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.3)68 770 y FJ(NON_AUTHORITATIVE_INFORMATION)p 1660 800 V 219 w(203)p 1960 800 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.4) 68 870 y FJ(NO_CONTENT)p 1660 900 V 1169 w(204)p 1960 900 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.5)68 970 y FJ(RESET_CONTENT)p 1660 1000 V 1019 w(205)p 1960 1000 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.6)68 1069 y FJ(PARTIAL_CONTENT)p 1660 1099 V 919 w(206)p 1960 1099 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.2.7)68 1169 y FJ(MULTI_STATUS)p 1660 1199 V 1069 w(207)p 1960 1199 V 124 w FN(WEBD)m(A)-11 b(V)21 b(RFC)g(2518,)e(Section)h(10.2)68 1269 y FJ(IM_USED)p 1660 1298 V 1319 w(226)p 1960 1298 V 124 w FN(Delta)h(encoding)d(in)i(HTTP)-9 b(,)20 b(RFC)i(3229,)c (Section)i(10.4.1)68 1368 y FJ(MULTIPLE_CHOICES)p 1660 1398 V 869 w(300)p 1960 1398 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.3.1)68 1468 y FJ(MOVED_PERMANENTLY)p 1660 1498 V 819 w(301)p 1960 1498 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.3.2)68 1567 y FJ(FOUND)p 1660 1597 V 1419 w(302)p 1960 1597 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.3.3)68 1667 y FJ(SEE_OTHER)p 1660 1697 V 1219 w(303)p 1960 1697 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.3.4)68 1767 y FJ(NOT_MODIFIED)p 1660 1797 V 1069 w(304)p 1960 1797 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.3.5)68 1866 y FJ(USE_PROXY)p 1660 1896 V 1219 w(305)p 1960 1896 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.3.6)68 1966 y FJ(TEMPORARY_REDIRECT)p 1660 1996 V 769 w(307)p 1960 1996 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.3.8)68 2066 y FJ(BAD_REQUEST)p 1660 2095 V 1119 w(400)p 1960 2095 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.1)68 2165 y FJ(UNAUTHORIZED)p 1660 2195 V 1069 w(401)p 1960 2195 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.2)68 2265 y FJ(PAYMENT_REQUIRED)p 1660 2295 V 869 w(402)p 1960 2295 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.3)68 2364 y FJ(FORBIDDEN)p 1660 2394 V 1219 w(403)p 1960 2394 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.4)68 2464 y FJ(NOT_FOUND)p 1660 2494 V 1219 w(404)p 1960 2494 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.5)68 2564 y FJ(METHOD_NOT_ALLOWED)p 1660 2594 V 769 w(405)p 1960 2594 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.6)68 2663 y FJ(NOT_ACCEPTABLE)p 1660 2693 V 969 w(406)p 1960 2693 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.7)68 2763 y FJ(PROXY_AUTHENTICATION_REQUIRED)p 1660 2793 V 219 w(407)p 1960 2793 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.4.8)68 2863 y FJ(REQUEST_TIMEOUT)p 1660 2892 V 919 w(408)p 1960 2892 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.4.9)68 2962 y FJ(CONFLICT)p 1660 2992 V 1269 w(409)p 1960 2992 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.10)68 3062 y FJ(GONE)p 1660 3092 V 1469 w(410)p 1960 3092 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.11)68 3161 y FJ(LENGTH_REQUIRED)p 1660 3191 V 919 w(411)p 1960 3191 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.12)68 3261 y FJ(PRECONDITION_FAILED)p 1660 3291 V 719 w(412)p 1960 3291 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.4.13)68 3361 y FJ(REQUEST_ENTITY_TOO_LARGE)p 1660 3391 V 469 w(413)p 1960 3391 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.4.14)68 3460 y FJ(REQUEST_URI_TOO_LONG)p 1660 3490 V 669 w(414)p 1960 3490 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.4.15)68 3560 y FJ(UNSUPPORTED_MEDIA_TYPE)p 1660 3590 V 569 w(415)p 1960 3590 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.4.16)68 3660 y FJ(REQUESTED_RANGE_NOT_SATISFIABLE)p 1660 3689 V 119 w(416)p 1960 3689 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.4.17)68 3759 y FJ(EXPECTATION_FAILED)p 1660 3789 V 769 w(417)p 1960 3789 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c (Section)i(10.4.18)68 3859 y FJ(UNPROCESSABLE_ENTITY)p 1660 3889 V 669 w(422)p 1960 3889 V 124 w FN(WEBD)m(A)-11 b(V)g(,)21 b(RFC)g(2518,)e(Section)h(10.3)68 3958 y FJ(LOCKED)p 1660 3988 V 1369 w(423)p 1960 3988 V 124 w FN(WEBD)m(A)-11 b(V)21 b(RFC)g(2518,)e(Section)h(10.4)68 4058 y FJ(FAILED_DEPENDENCY)p 1660 4088 V 819 w(424)p 1960 4088 V 124 w FN(WEBD)m(A)-11 b(V)g(,)21 b(RFC)g(2518,)e(Section)h(10.5)68 4158 y FJ (UPGRADE_REQUIRED)p 1660 4188 V 869 w(426)p 1960 4188 V 124 w FN(HTTP)g(Upgrade)f(to)h(TLS,)g(RFC)i(2817,)d(Section)g(6)68 4257 y FJ(INTERNAL_SERVER_ERROR)p 1660 4287 V 619 w(500)p 1960 4287 V 124 w FN(HTTP/1.1,)g(RFC)j(2616,)c(Section)i(10.5.1)68 4357 y FJ(NOT_IMPLEMENTED)p 1660 4387 V 919 w(501)p 1960 4387 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.5.2)68 4457 y FJ(BAD_GATEWAY)p 1660 4487 V 1119 w(502)p 1960 4487 V 124 w FN(HTTP/1.1)f(RFC)j(2616,)c(Section)i(10.5.3)68 4556 y FJ(SERVICE_UNAVAILABLE)p 1660 4586 V 719 w(503)p 1960 4586 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i(10.5.4)68 4656 y FJ(GATEWAY_TIMEOUT)p 1660 4686 V 919 w(504)p 1960 4686 V 124 w FN(HTTP/1.1)f(RFC)j(2616,)c(Section)i(10.5.5)68 4755 y FJ(HTTP_VERSION_NOT_SUPPORTED)p 1660 4785 V 369 w(505)p 1960 4785 V 124 w FN(HTTP/1.1,)f(RFC)j(2616,)c(Section)i (10.5.6)68 4855 y FJ(INSUFFICIENT_STORAGE)p 1660 4885 V 669 w(507)p 1960 4885 V 124 w FN(WEBD)m(A)-11 b(V)g(,)21 b(RFC)g(2518,)e(Section)h(10.6)68 4955 y FJ(NOT_EXTENDED)p 1660 4985 V 1069 w(510)p 1960 4985 V 124 w FN(An)g(HTTP)h(Extension)d (Frame)n(w)o(ork,)h(RFC)i(2774,)e(Section)h(7)0 5114 y FD(responses)208 5213 y FN(This)g(dictionary)e(maps)i(the)h(HTTP)f (1.1)f(status)i(codes)f(to)g(the)h(W3C)g(names.)208 5346 y(Example:)j FJ(httplib.responses[httplib.NOT_FOU)o(ND])15 b FN(is)21 b FJ('Not)49 b(Found')p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)e (2.5.)p 0 5549 3901 4 v 0 5649 a FI(634)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 635 647 TeXDict begin 635 646 bop 0 83 a Fv(18.7.1)101 b(HTTPConnection)29 b(Objects)0 286 y FJ(HTTPConnection)18 b FN(instances)i(ha)n(v)o(e)g (the)g(follo)n(wing)f(methods:)0 433 y FD(request)p FJ(\()p FK(method,)e(url)p FC([)p FK(,)k(body)p FC([)p FK(,)d(header)o(s)12 b FC(])g(])p FJ(\))208 532 y FN(This)23 b(will)g(send)g(a)g(request)f (to)h(the)g(serv)o(er)f(using)h(the)g(HTTP)g(request)f(method)f FK(method)k FN(and)d(the)h(selector)f FK(url)p FN(.)34 b(If)23 b(the)g FK(body)208 632 y FN(ar)o(gument)h(is)j(present,)h(it)f (should)e(be)i(a)g(string)f(of)h(data)f(to)h(send)f(after)g(the)h (headers)f(are)g(\002nished.)44 b(The)26 b(header)f(Content-)208 732 y(Length)h(is)i(automatically)d(set)j(to)g(the)f(correct)f(v)n (alue.)45 b(The)27 b FK(header)o(s)g FN(ar)o(gument)e(should)h(be)h(a)h (mapping)d(of)i(e)o(xtra)f(HTTP)208 831 y(headers)19 b(to)h(send)g(with)h(the)f(request.)0 978 y FD(getresponse)p FJ(\(\))208 1078 y FN(Should)14 b(be)h(called)h(after)f(a)h(request)e (is)j(sent)f(to)f(get)h(the)f(response)g(from)f(the)i(serv)o(er)-5 b(.)23 b(Returns)15 b(an)g FJ(HTTPResponse)f FN(instance.)208 1177 y FL(Note:)24 b FN(Note)c(that)g(you)g(must)g(ha)n(v)o(e)f(read)h (the)g(whole)g(response)f(before)g(you)g(can)h(send)g(a)h(ne)n(w)f (request)f(to)i(the)f(serv)o(er)-5 b(.)0 1324 y FD(set_debuglevel)p FJ(\()p FK(le)o(vel)p FJ(\))208 1424 y FN(Set)26 b(the)h(deb)n(ugging)c (le)n(v)o(el)j(\(the)g(amount)f(of)h(deb)n(ugging)d(output)i (printed\).)41 b(The)26 b(def)o(ault)g(deb)n(ug)f(le)n(v)o(el)g(is)j FJ(0)p FN(,)f(meaning)e(no)208 1524 y(deb)n(ugging)17 b(output)i(is)i(printed.)0 1670 y FD(connect)p FJ(\(\))208 1770 y FN(Connect)e(to)h(the)h(serv)o(er)e(speci\002ed)h(when)f(the)i (object)e(w)o(as)i(created.)0 1917 y FD(close)p FJ(\(\))208 2017 y FN(Close)f(the)h(connection)d(to)i(the)g(serv)o(er)-5 b(.)0 2163 y(As)23 b(an)f(alternati)n(v)o(e)f(to)h(using)g(the)g FJ(request\(\))f FN(method)g(described)g(abo)o(v)o(e,)f(you)h(can)h (also)h(send)f(your)f(request)g(step)i(by)e(step,)i(by)0 2263 y(using)d(the)g(four)f(functions)g(belo)n(w)-5 b(.)0 2410 y FD(putrequest)p FJ(\()p FK(r)m(equest,)18 b(selector)r FC([)p FK(,)i(skip)p 1316 2410 25 4 v 30 w(host)q FC([)p FK(,)g(skip)p 1701 2410 V 29 w(accept)p 1948 2410 V 29 w(encoding)12 b FC(])g(])p FJ(\))208 2510 y FN(This)30 b(should)g(be)g(the)g(\002rst)i(call)f(after)f(the)g(connection)e(to)j (the)g(serv)o(er)e(has)i(been)f(made.)55 b(It)30 b(sends)h(a)g(line)f (to)h(the)f(serv)o(er)208 2609 y(consisting)22 b(of)g(the)h FK(r)m(equest)h FN(string,)f(the)g FK(selector)i FN(string,)e(and)f (the)h(HTTP)g(v)o(ersion)e(\()p FJ(HTTP/1.1)p FN(\).)31 b(T)-7 b(o)23 b(disable)g(automatic)208 2709 y(sending)i(of)i FJ(Host:)38 b FN(or)27 b FJ(Accept-Encoding:)36 b FN(headers)26 b(\(for)g(e)o(xample)g(to)h(accept)f(additional)g(content)g (encodings\),)208 2808 y(specify)15 b FK(skip)p 603 2808 V 30 w(host)i FN(or)f FK(skip)p 1009 2808 V 30 w(accept)p 1257 2808 V 29 w(encoding)e FN(with)i(non-F)o(alse)f(v)n(alues.)48 b(Changed)15 b(in)h(v)o(ersion)f(2.4:)g FK(skip)p 3324 2808 V 30 w(accept)p 3572 2808 V 29 w(encoding)208 2908 y FN(ar)o(gument)i(added.)0 3055 y FD(putheader)p FJ(\()p FK(header)-9 b(,)17 b(ar)m(gument)q FC([)p FK(,)i(...)12 b FC(])p FJ(\))208 3155 y FN(Send)20 b(an)i(RFC)h(822-style)c(header)i (to)g(the)g(serv)o(er)-5 b(.)28 b(It)22 b(sends)f(a)h(line)f(to)h(the)f (serv)o(er)f(consisting)h(of)g(the)g(header)m(,)f(a)i(colon)e(and)h(a) 208 3254 y(space,)g(and)g(the)h(\002rst)g(ar)o(gument.)k(If)c(more)f (ar)o(guments)e(are)j(gi)n(v)o(en,)e(continuation)f(lines)j(are)f (sent,)h(each)g(consisting)e(of)i(a)g(tab)208 3354 y(and)d(an)h(ar)o (gument.)0 3501 y FD(endheaders)p FJ(\(\))208 3600 y FN(Send)f(a)i(blank)e(line)h(to)h(the)f(serv)o(er)m(,)f(signalling)g (the)h(end)g(of)g(the)g(headers.)0 3747 y FD(send)p FJ(\()p FK(data)p FJ(\))208 3847 y FN(Send)k(data)g(to)g(the)h(serv)o(er)-5 b(.)37 b(This)24 b(should)g(be)g(used)g(directly)g(only)f(after)h(the)h FJ(endheaders\(\))d FN(method)h(has)i(been)f(called)208 3946 y(and)19 b(before)g FJ(getresponse\(\))f FN(is)j(called.)0 4231 y Fv(18.7.2)101 b(HTTPResponse)29 b(Objects)0 4434 y FJ(HTTPResponse)19 b FN(instances)h(ha)n(v)o(e)f(the)h(follo)n(wing)f (methods)g(and)h(attrib)n(utes:)0 4581 y FD(read)p FJ(\()p FC([)p FK(amt)13 b FC(])p FJ(\))208 4681 y FN(Reads)20 b(and)g(returns)f(the)h(response)g(body)-5 b(,)18 b(or)i(up)f(to)i(the) f(ne)o(xt)f FK(amt)j FN(bytes.)0 4828 y FD(getheader)p FJ(\()p FK(name)p FC([)p FK(,)17 b(default)c FC(])p FJ(\))208 4927 y FN(Get)20 b(the)g(contents)g(of)g(the)g(header)f FK(name)p FN(,)g(or)h FK(default)h FN(if)g(there)e(is)i(no)f(matching)f (header)-5 b(.)0 5074 y FD(getheaders)p FJ(\(\))208 5174 y FN(Return)19 b(a)i(list)g(of)f(\(header)m(,)e(v)n(alue\))h(tuples.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 5321 y FD(msg)p 0 5549 3901 4 v 0 5649 a FI(18.7.)52 b FJ(httplib)22 b FI(\227)h(HTTP)g(protocol)g(client)2297 b(635)p eop end %%Page: 636 648 TeXDict begin 636 647 bop 208 83 a FN(A)20 b FJ(mimetools.Message)e FN(instance)i(containing)e(the)i(response)f(headers.)0 230 y FD(version)208 330 y FN(HTTP)h(protocol)e(v)o(ersion)h(used)h(by) g(serv)o(er)-5 b(.)24 b(10)c(for)g(HTTP/1.0,)f(11)h(for)f(HTTP/1.1.)0 476 y FD(status)208 576 y FN(Status)h(code)g(returned)e(by)i(serv)o(er) -5 b(.)0 723 y FD(reason)208 823 y FN(Reason)20 b(phrase)f(returned)g (by)g(serv)o(er)-5 b(.)0 1107 y Fv(18.7.3)101 b(Examples)0 1310 y FN(Here)20 b(is)h(an)f(e)o(xample)f(session)i(that)f(uses)h(the) f(`)p FJ(GET)p FN(')f(method:)236 1549 y FA(>>>)45 b(import)e(httplib) 236 1640 y(>>>)i(conn)f(=)g(httplib.HTTPConnection\("www.python.org"\)) 236 1731 y(>>>)h(conn.request\("GET",)c("/index.html"\))236 1822 y(>>>)k(r1)f(=)h(conn.getresponse\(\))236 1914 y(>>>)g(print)f (r1.status,)f(r1.reason)236 2005 y(200)i(OK)236 2096 y(>>>)g(data1)f(=)g(r1.read\(\))236 2188 y(>>>)h(conn.request\("GET",)c ("/parrot.spam"\))236 2279 y(>>>)k(r2)f(=)h(conn.getresponse\(\))236 2370 y(>>>)g(print)f(r2.status,)f(r2.reason)236 2462 y(404)i(Not)f(Found)236 2553 y(>>>)h(data2)f(=)g(r2.read\(\))236 2644 y(>>>)h(conn.close\(\))0 2931 y FN(Here)20 b(is)h(an)f(e)o(xample) f(session)i(that)f(sho)n(ws)g(ho)n(w)g(to)g(`)p FJ(POST)p FN(')g(requests:)236 3169 y FA(>>>)45 b(import)e(httplib,)h(urllib)236 3260 y(>>>)h(params)e(=)i(urllib.urlencode\({'spam':)c(1,)j('eggs':)g (2,)g('bacon':)g(0}\))236 3352 y(>>>)h(headers)e(=)i({"Content-type":)d ("application/x-www-form-urlencoded",)236 3443 y(...)538 b("Accept":)43 b("text/plain"})236 3534 y(>>>)i(conn)f(=)g (httplib.HTTPConnection\("musi-cal.mojam.co)o(m:80"\))236 3626 y(>>>)h(conn.request\("POST",)c("/cgi-bin/query",)h(params,)i (headers\))236 3717 y(>>>)h(response)e(=)i(conn.getresponse\(\))236 3808 y(>>>)g(print)f(response.status,)e(response.reason)236 3900 y(200)j(OK)236 3991 y(>>>)g(data)f(=)g(response.read\(\))236 4082 y(>>>)h(conn.close\(\))0 4592 y FE(18.8)121 b Fx(ftplib)32 b FE(\227)h(FTP)g(protocol)h(client)0 4825 y FN(This)28 b(module)f(de\002nes)g(the)h(class)h FJ(FTP)f FN(and)f(a)i(fe)n(w)e (related)h(items.)48 b(The)28 b FJ(FTP)g FN(class)g(implements)f(the)h (client)g(side)g(of)g(the)g(FTP)0 4925 y(protocol.)f(Y)-9 b(ou)21 b(can)g(use)g(this)h(to)g(write)f(Python)g(programs)e(that)j (perform)d(a)j(v)n(ariety)e(of)h(automated)f(FTP)i(jobs,)g(such)f(as)h (mirroring)0 5024 y(other)f(ftp)h(serv)o(ers.)30 b(It)22 b(is)h(also)f(used)g(by)f(the)h(module)f FJ(urllib)g FN(to)h(handle)f(URLs)i(that)f(use)g(FTP)-9 b(.)22 b(F)o(or)g(more)f (information)e(on)j(FTP)0 5124 y(\(File)f(T)m(ransfer)e(Protocol\),)f (see)j(Internet)e(RFC)j(959.)0 5271 y(Here')-5 b(s)20 b(a)h(sample)f(session)h(using)e(the)h FJ(ftplib)g FN(module:)p 0 5549 3901 4 v 0 5649 a FI(636)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 637 649 TeXDict begin 637 648 bop 236 174 a FA(>>>)45 b(from)f(ftplib)g(import) f(FTP)236 266 y(>>>)i(ftp)f(=)h(FTP\('ftp.cwi.nl'\))131 b(#)45 b(connect)e(to)i(host,)f(default)g(port)236 357 y(>>>)h(ftp.login\(\))670 b(#)45 b(user)f(anonymous,)f(passwd)h (anonymous@)236 448 y(>>>)h(ftp.retrlines\('LIST'\))220 b(#)45 b(list)f(directory)f(contents)236 540 y(total)h(24418)236 631 y(drwxrwsr-x)133 b(5)45 b(ftp-usr)88 b(pdmaint)223 b(1536)44 b(Mar)h(20)f(09:48)g(.)236 722 y(dr-xr-srwt)f(105)i(ftp-usr) 88 b(pdmaint)223 b(1536)44 b(Mar)h(21)f(14:32)g(..)236 814 y(-rw-r--r--)133 b(1)45 b(ftp-usr)88 b(pdmaint)223 b(5305)44 b(Mar)h(20)f(09:48)g(INDEX)281 905 y(.)281 996 y(.)281 1088 y(.)236 1179 y(>>>)h(ftp.retrbinary\('RETR)c(README',) j(open\('README',)e('wb'\).write\))236 1270 y('226)i(Transfer)g (complete.')236 1362 y(>>>)h(ftp.quit\(\))0 1648 y FN(The)20 b(module)f(de\002nes)h(the)g(follo)n(wing)e(items:)0 1795 y FL(class)j FD(FTP)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)e(user)r FC([)p FK(,)h(passwd)r FC([)p FK(,)g(acct)13 b FC(])f(])g(])g(])p FJ(\))208 1895 y FN(Return)21 b(a)g(ne)n(w)h (instance)f(of)g(the)g FJ(FTP)h FN(class.)29 b(When)21 b FK(host)i FN(is)g(gi)n(v)o(en,)d(the)h(method)f(call)i FJ(connect\()p FK(host)q FJ(\))e FN(is)j(made.)28 b(When)208 1994 y FK(user)i FN(is)f(gi)n(v)o(en,)f(additionally)f(the)h(method)e (call)j FJ(login\()p FK(user)r FJ(,)48 b FK(passwd)r FJ(,)h FK(acct)q FJ(\))29 b FN(is)g(made)e(\(where)g FK(passwd)j FN(and)e FK(acct)208 2094 y FN(def)o(ault)19 b(to)h(the)h(empty)e(string)h(when)f(not)h(gi)n(v)o(en\).)0 2241 y FD(all_errors)208 2340 y FN(The)i(set)i(of)e(all)i(e)o (xceptions)d(\(as)i(a)g(tuple\))f(that)h(methods)f(of)h FJ(FTP)g FN(instances)f(may)h(raise)g(as)g(a)h(result)f(of)f(problems)g (with)h(the)208 2440 y(FTP)h(connection)d(\(as)i(opposed)f(to)i (programming)c(errors)i(made)h(by)g(the)g(caller\).)34 b(This)24 b(set)g(includes)f(the)g(four)f(e)o(xceptions)208 2540 y(listed)e(belo)n(w)g(as)h(well)f(as)h FJ(socket.error)e FN(and)g FJ(IOError)p FN(.)0 2686 y FL(exception)g FD(error_reply)208 2786 y FN(Exception)f(raised)i(when)g(an)g(une)o(xpected)d(reply)j(is)h (recei)n(v)o(ed)d(from)i(the)g(serv)o(er)-5 b(.)0 2933 y FL(exception)19 b FD(error_temp)208 3033 y FN(Exception)f(raised)i (when)g(an)g(error)f(code)g(in)i(the)f(range)f(400\226499)e(is)k(recei) n(v)o(ed.)0 3179 y FL(exception)e FD(error_perm)208 3279 y FN(Exception)f(raised)i(when)g(an)g(error)f(code)g(in)i(the)f(range)f (500\226599)e(is)k(recei)n(v)o(ed.)0 3426 y FL(exception)e FD(error_proto)208 3526 y FN(Exception)f(raised)i(when)g(a)g(reply)g (is)h(recei)n(v)o(ed)d(from)h(the)i(serv)o(er)e(that)h(does)g(not)g(be) o(gin)f(with)h(a)h(digit)f(in)g(the)h(range)e(1\2265.)0 3672 y FL(See)i(Also:)0 3819 y FN(Module)e FJ(netrc)h FN(\(section)f(9.4\):)208 3919 y(P)o(arser)24 b(for)g(the)g(`)p FO(.netrc)p FN(')f(\002le)i(format.)37 b(The)24 b(\002le)h(`)p FO(.netrc)p FN(')e(is)i(typically)f(used)g(by)g(FTP)h(clients)g(to)f (load)g(user)h(authentication)208 4019 y(information)17 b(before)i(prompting)f(the)i(user)-5 b(.)0 4165 y(The)24 b(\002le)h(`)p FO(T)-9 b(ools/scr)q(ipts/ftpmirror)l(.p)n(y)p FN(')20 b(in)25 b(the)f(Python)f(source)h(distrib)n(ution)f(is)j(a)e (script)h(that)f(can)g(mirror)f(FTP)i(sites,)i(or)d(portions)0 4265 y(thereof,)19 b(using)g(the)h FJ(ftplib)g FN(module.)k(It)c(can)g (be)g(used)g(as)h(an)f(e)o(xtended)e(e)o(xample)h(that)i(applies)f (this)g(module.)0 4550 y Fv(18.8.1)101 b(FTP)27 b(Objects)0 4753 y FN(Se)n(v)o(eral)20 b(methods)f(are)i(a)n(v)n(ailable)f(in)h(tw) o(o)g(\003a)n(v)n(ors:)26 b(one)21 b(for)f(handling)e(te)o(xt)j (\002les)h(and)e(another)f(for)h(binary)f(\002les.)28 b(These)20 b(are)h(named)0 4852 y(for)f(the)g(command)e(which)i(is)h (used)f(follo)n(wed)e(by)i(`)p FJ(lines)p FN(')f(for)h(the)g(te)o(xt)g (v)o(ersion)f(or)h(`)p FJ(binary)p FN(')f(for)h(the)g(binary)f(v)o (ersion.)0 4999 y FJ(FTP)h FN(instances)g(ha)n(v)o(e)g(the)g(follo)n (wing)f(methods:)0 5146 y FD(set_debuglevel)p FJ(\()p FK(le)o(vel)p FJ(\))208 5246 y FN(Set)31 b(the)g(instance')-5 b(s)31 b(deb)n(ugging)d(le)n(v)o(el.)57 b(This)31 b(controls)f(the)h (amount)f(of)g(deb)n(ugging)f(output)g(printed.)56 b(The)31 b(def)o(ault,)h FJ(0)p FN(,)208 5345 y(produces)26 b(no)h(deb)n(ugging) f(output.)47 b(A)29 b(v)n(alue)e(of)h FJ(1)g FN(produces)e(a)j (moderate)d(amount)h(of)h(deb)n(ugging)d(output,)k(generally)d(a)p 0 5549 3901 4 v 0 5649 a FI(18.8.)52 b FJ(ftplib)22 b FI(\227)h(FTP)g(protocol)h(client)2406 b(637)p eop end %%Page: 638 650 TeXDict begin 638 649 bop 208 83 a FN(single)26 b(line)g(per)g (request.)42 b(A)27 b(v)n(alue)e(of)h FJ(2)h FN(or)f(higher)f(produces) f(the)i(maximum)f(amount)g(of)g(deb)n(ugging)f(output,)i(logging)208 183 y(each)19 b(line)i(sent)f(and)g(recei)n(v)o(ed)e(on)i(the)g (control)f(connection.)0 330 y FD(connect)p FJ(\()p FK(host)q FC([)p FK(,)g(port)13 b FC(])p FJ(\))208 429 y FN(Connect)i(to)h(the)g (gi)n(v)o(en)f(host)h(and)g(port.)23 b(The)15 b(def)o(ault)h(port)f (number)f(is)j FJ(21)p FN(,)g(as)g(speci\002ed)f(by)f(the)i(FTP)f (protocol)f(speci\002cation.)208 529 y(It)j(is)h(rarely)e(needed)f(to)j (specify)e(a)h(dif)n(ferent)f(port)g(number)-5 b(.)23 b(This)18 b(function)e(should)h(be)h(called)g(only)f(once)g(for)g(each) h(instance;)208 628 y(it)23 b(should)f(not)g(be)h(called)f(at)i(all)f (if)g(a)g(host)g(w)o(as)g(gi)n(v)o(en)f(when)g(the)h(instance)f(w)o(as) h(created.)32 b(All)24 b(other)e(methods)f(can)i(only)f(be)208 728 y(used)d(after)h(a)h(connection)d(has)i(been)g(made.)0 875 y FD(getwelcome)p FJ(\(\))208 975 y FN(Return)27 b(the)h(welcome)f(message)g(sent)h(by)f(the)h(serv)o(er)f(in)h(reply)f (to)h(the)f(initial)h(connection.)46 b(\(This)27 b(message)h(sometimes) 208 1074 y(contains)19 b(disclaimers)h(or)g(help)g(information)d(that)k (may)e(be)h(rele)n(v)n(ant)f(to)i(the)f(user)-5 b(.\))0 1221 y FD(login)p FJ(\()p FC([)p FK(user)r FC([)p FK(,)19 b(passwd)r FC([)p FK(,)h(acct)13 b FC(])f(])g(])p FJ(\))208 1321 y FN(Log)k(in)i(as)g(the)f(gi)n(v)o(en)f FK(user)r FN(.)24 b(The)17 b FK(passwd)j FN(and)d FK(acct)h FN(parameters)f(are)g (optional)f(and)h(def)o(ault)f(to)i(the)f(empty)f(string.)24 b(If)17 b(no)g FK(user)208 1420 y FN(is)k(speci\002ed,)f(it)i(def)o (aults)e(to)h FJ('anonymous')p FN(.)k(If)20 b FK(user)k FN(is)d FJ('anonymous')p FN(,)e(the)i(def)o(ault)f FK(passwd)j FN(is)e FJ('anonymous@')p FN(.)208 1520 y(This)k(function)f(should)g (be)h(called)g(only)g(once)f(for)h(each)g(instance,)h(after)f(a)h (connection)d(has)i(been)g(established;)j(it)e(should)208 1620 y(not)21 b(be)h(called)f(at)h(all)h(if)f(a)g(host)f(and)h(user)f (were)h(gi)n(v)o(en)e(when)h(the)h(instance)f(w)o(as)i(created.)28 b(Most)22 b(FTP)h(commands)d(are)h(only)208 1719 y(allo)n(wed)e(after)h (the)g(client)g(has)h(logged)e(in.)0 1866 y FD(abort)p FJ(\(\))208 1966 y FN(Abort)g(a)i(\002le)f(transfer)g(that)g(is)h(in)g (progress.)i(Using)d(this)h(does)f(not)g(al)o(w)o(ays)h(w)o(ork,)e(b)n (ut)h(it')-5 b(s)21 b(w)o(orth)f(a)h(try)-5 b(.)0 2113 y FD(sendcmd)p FJ(\()p FK(command)r FJ(\))208 2212 y FN(Send)19 b(a)i(simple)f(command)e(string)i(to)h(the)f(serv)o(er)f (and)h(return)f(the)h(response)f(string.)0 2359 y FD(voidcmd)p FJ(\()p FK(command)r FJ(\))208 2459 y FN(Send)j(a)h(simple)f(command)f (string)h(to)h(the)f(serv)o(er)g(and)g(handle)g(the)g(response.)31 b(Return)23 b(nothing)d(if)j(a)g(response)f(code)g(in)h(the)208 2558 y(range)c(200\226299)e(is)k(recei)n(v)o(ed.)j(Raise)d(an)f(e)o (xception)e(otherwise.)0 2705 y FD(retrbinary)p FJ(\()p FK(command,)e(callbac)n(k)q FC([)p FK(,)k(maxbloc)n(ksize)p FC([)p FK(,)f(r)m(est)13 b FC(])f(])p FJ(\))208 2805 y FN(Retrie)n(v)o(e)26 b(a)i(\002le)g(in)g(binary)e(transfer)g(mode.)45 b FK(command)28 b FN(should)f(be)g(an)g(appropriate)e(`)p FJ(RETR)p FN(')i(command:)37 b FJ('RETR)49 b FK(\002le-)208 2904 y(name)p FJ(')p FN(.)41 b(The)25 b FK(callbac)n(k)i FN(function)d(is)j(called)f(for)f(each)h(block)f(of)g(data)h(recei)n(v) o(ed,)f(with)i(a)f(single)g(string)f(ar)o(gument)f(gi)n(ving)208 3004 y(the)c(data)g(block.)k(The)c(optional)f FK(maxbloc)n(ksize)g FN(ar)o(gument)f(speci\002es)j(the)f(maximum)e(chunk)h(size)i(to)f (read)g(on)g(the)g(lo)n(w-le)n(v)o(el)208 3104 y(sock)o(et)k(object)g (created)g(to)h(do)f(the)h(actual)f(transfer)g(\(which)g(will)h(also)g (be)f(the)h(lar)o(gest)f(size)h(of)g(the)f(data)h(blocks)f(passed)g(to) 208 3203 y FK(callbac)n(k)q FN(\).)g(A)c(reasonable)f(def)o(ault)h(is)h (chosen.)j FK(r)m(est)f FN(means)c(the)i(same)f(thing)f(as)i(in)g(the)f FJ(transfercmd\(\))e FN(method.)0 3350 y FD(retrlines)p FJ(\()p FK(command)r FC([)p FK(,)e(callbac)n(k)d FC(])p FJ(\))208 3450 y FN(Retrie)n(v)o(e)18 b(a)h(\002le)g(or)g(directory)e (listing)i(in)i FH(A)t(S)t(C)t(I)t(I)h FN(transfer)c(mode.)23 b FK(command)c FN(should)f(be)h(an)f(appropriate)f(`)p FJ(RETR)p FN(')h(command)208 3549 y(\(see)g FJ(retrbinary\(\))p FN(\))e(or)i(a)g(`)p FJ(LIST)p FN(')f(command)f(\(usually)i(just)g(the) g(string)g FJ('LIST')p FN(\).)f(The)h FK(callbac)n(k)g FN(function)f(is)i(called)208 3649 y(for)g(each)h(line,)g(with)g(the)h (trailing)e(CRLF)j(stripped.)i(The)19 b(def)o(ault)h FK(callbac)n(k)h FN(prints)f(the)g(line)g(to)g FJ(sys.stdout)p FN(.)0 3796 y FD(set_pasv)p FJ(\()p FK(boolean)p FJ(\))208 3896 y FN(Enable)g(\223passi)n(v)o(e\224)g(mode)g(if)h FK(boolean)e FN(is)j(true,)f(other)f(disable)h(passi)n(v)o(e)f(mode.)27 b(\(In)20 b(Python)g(2.0)g(and)g(before,)g(passi)n(v)o(e)h(mode)208 3995 y(w)o(as)g(of)n(f)e(by)h(def)o(ault;)f(in)i(Python)e(2.1)g(and)h (later)m(,)g(it)h(is)g(on)e(by)h(def)o(ault.\))0 4142 y FD(storbinary)p FJ(\()p FK(command,)c(\002le)p FC([)p FK(,)k(bloc)n(ksize)12 b FC(])p FJ(\))208 4242 y FN(Store)20 b(a)g(\002le)h(in)g(binary)e(transfer)g(mode.)24 b FK(command)d FN(should)e(be)h(an)h(appropriate)d(`)p FJ(STOR)p FN(')h(command:)k FJ("STOR)49 b FK(\002lename)p FJ(")p FN(.)208 4341 y FK(\002le)18 b FN(is)h(an)e(open)g(\002le)i(object)f(which)f(is)i(read) f(until)h FH(E)t(O)t(F)i FN(using)c(its)i FJ(read\(\))f FN(method)e(in)i(blocks)g(of)g(size)g FK(bloc)n(ksize)g FN(to)h(pro)o(vide)208 4441 y(the)k(data)h(to)f(be)h(stored.)34 b(The)24 b FK(bloc)n(ksize)f FN(ar)o(gument)f(def)o(aults)h(to)h(8192.) 69 b(Changed)22 b(in)i(v)o(ersion)f(2.1:)g(def)o(ault)f(for)h FK(bloc)n(ksize)208 4541 y FN(added.)0 4687 y FD(storlines)p FJ(\()p FK(command,)16 b(\002le)p FJ(\))208 4787 y FN(Store)55 b(a)h(\002le)g(in)i FH(A)t(S)t(C)t(I)t(I)g FN(transfer)d(mode.)130 b FK(command)56 b FN(should)e(be)i(an)f(appropriate)e(`)p FJ(STOR)p FN(')i(command)e(\(see)208 4887 y FJ(storbinary\(\))p FN(\).)g(Lines)30 b(are)g(read)g(until)i FH(E)t(O)t(F)g FN(from)e(the)g(open)f(\002le)i(object)f FK(\002le)g FN(using)g(its)h FJ(readline\(\))e FN(method)208 4986 y(to)20 b(pro)o(vide)e(the)i(data)g(to)h(be)f(stored.)0 5133 y FD(transfercmd)p FJ(\()p FK(cmd)r FC([)p FK(,)e(r)m(est)13 b FC(])p FJ(\))208 5233 y FN(Initiate)20 b(a)g(transfer)f(o)o(v)o(er)g (the)h(data)h(connection.)h(If)e(the)h(transfer)e(is)i(acti)n(v)o(e,)f (send)g(a)g(`)p FJ(EPRT)p FN(')f(or)h(`)p FJ(PORT)p FN(')g(command)e (and)i(the)208 5332 y(transfer)15 b(command)f(speci\002ed)i(by)g FK(cmd)r FN(,)h(and)e(accept)h(the)g(connection.)22 b(If)16 b(the)g(serv)o(er)f(is)i(passi)n(v)o(e,)g(send)f(a)g(`)p FJ(EPSV)p FN(')g(or)f(`)p FJ(PASV)p FN(')p 0 5549 3901 4 v 0 5649 a FI(638)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 639 651 TeXDict begin 639 650 bop 208 83 a FN(command,)18 b(connect)g(to)j(it,) f(and)g(start)h(the)f(transfer)f(command.)k(Either)d(w)o(ay)-5 b(,)20 b(return)f(the)h(sock)o(et)g(for)f(the)i(connection.)208 216 y(If)j(optional)f FK(r)m(est)28 b FN(is)d(gi)n(v)o(en,)g(a)g(`)p FJ(REST)p FN(')e(command)g(is)j(sent)f(to)g(the)f(serv)o(er)m(,)h (passing)f FK(r)m(est)j FN(as)f(an)e(ar)o(gument.)36 b FK(r)m(est)28 b FN(is)d(usually)208 315 y(a)g(byte)f(of)n(fset)g (into)g(the)h(requested)e(\002le,)j(telling)f(the)f(serv)o(er)g(to)h (restart)f(sending)g(the)g(\002le')-5 b(s)26 b(bytes)e(at)h(the)g (requested)e(of)n(fset,)208 415 y(skipping)17 b(o)o(v)o(er)h(the)h (initial)h(bytes.)k(Note)19 b(ho)n(we)n(v)o(er)e(that)j(RFC)g(959)f (requires)f(only)g(that)h FK(r)m(est)j FN(be)d(a)h(string)f(containing) e(charac-)208 515 y(ters)k(in)h(the)f(printable)f(range)h(from)f(ASCII) i(code)e(33)h(to)h(ASCII)g(code)e(126.)28 b(The)21 b FJ(transfercmd\(\))f FN(method,)g(therefore,)208 614 y(con)m(v)o(erts)f FK(r)m(est)k FN(to)e(a)g(string,)f(b)n(ut)h(no)f (check)g(is)i(performed)c(on)i(the)h(string')-5 b(s)21 b(contents.)k(If)c(the)g(serv)o(er)f(does)g(not)h(recognize)e(the)208 714 y(`)p FJ(REST)p FN(')e(command,)g(an)h FJ(error_reply)f FN(e)o(xception)f(will)k(be)e(raised.)24 b(If)18 b(this)h(happens,)f (simply)g(call)g FJ(transfercmd\(\))208 814 y FN(without)h(a)i FK(r)m(est)h FN(ar)o(gument.)0 960 y FD(ntransfercmd)p FJ(\()p FK(cmd)r FC([)p FK(,)17 b(r)m(est)c FC(])p FJ(\))208 1060 y FN(Lik)o(e)27 b FJ(transfercmd\(\))p FN(,)h(b)n(ut)f(returns)g (a)h(tuple)g(of)f(the)h(data)f(connection)f(and)h(the)h(e)o(xpected)e (size)i(of)g(the)g(data.)47 b(If)28 b(the)208 1160 y(e)o(xpected)17 b(size)k(could)d(not)h(be)h(computed,)d FJ(None)j FN(will)g(be)f (returned)f(as)i(the)g(e)o(xpected)e(size.)25 b FK(cmd)d FN(and)d FK(r)m(est)j FN(means)d(the)g(same)208 1259 y(thing)g(as)i(in)f FJ(transfercmd\(\))p FN(.)0 1406 y FD(nlst)p FJ(\()p FK(ar)m(gument)q FC([)p FK(,)e(.)12 b(.)g(.)24 b FC(])p FJ(\))208 1506 y FN(Return)e(a)h(list)h(of)f (\002les)g(as)h(returned)d(by)h(the)h(`)p FJ(NLST)p FN(')f(command.)31 b(The)22 b(optional)g FK(ar)m(gument)h FN(is)g(a)h(directory)d(to)i (list)h(\(def)o(ault)208 1605 y(is)k(the)g(current)e(serv)o(er)g (directory\).)45 b(Multiple)27 b(ar)o(guments)f(can)h(be)g(used)h(to)f (pass)h(non-standard)d(options)h(to)i(the)f(`)p FJ(NLST)p FN(')208 1705 y(command.)0 1852 y FD(dir)p FJ(\()p FK(ar)m(gument)q FC([)p FK(,)18 b(.)12 b(.)g(.)25 b FC(])p FJ(\))208 1952 y FN(Produce)g(a)i(directory)e(listing)h(as)i(returned)d(by)h(the)g(`)p FJ(LIST)p FN(')g(command,)g(printing)f(it)i(to)g(standard)f(output.)43 b(The)26 b(optional)208 2051 y FK(ar)m(gument)d FN(is)h(a)f(directory)e (to)j(list)g(\(def)o(ault)e(is)i(the)f(current)e(serv)o(er)i (directory\).)31 b(Multiple)22 b(ar)o(guments)f(can)i(be)g(used)g(to)g (pass)208 2151 y(non-standard)14 b(options)j(to)h(the)g(`)p FJ(LIST)p FN(')e(command.)23 b(If)17 b(the)h(last)g(ar)o(gument)e(is)i (a)h(function,)d(it)i(is)h(used)e(as)i(a)f FK(callbac)n(k)g FN(function)208 2250 y(as)i(for)g FJ(retrlines\(\))p FN(;)f(the)h(def)o(ault)f(prints)h(to)h FJ(sys.stdout)p FN(.)i(This)e(method)e(returns)g FJ(None)p FN(.)0 2397 y FD(rename)p FJ(\()p FK(fr)l(omname)o(,)f(toname)p FJ(\))208 2497 y FN(Rename)h(\002le)i FK(fr)l(omname)f FN(on)g(the)g(serv)o(er)f (to)i FK(toname)p FN(.)0 2644 y FD(delete)p FJ(\()p FK(\002lename)p FJ(\))208 2743 y FN(Remo)o(v)o(e)e(the)h(\002le)h(named)e FK(\002lename)h FN(from)f(the)h(serv)o(er)-5 b(.)25 b(If)c(successful,) e(returns)h(the)g(te)o(xt)h(of)f(the)g(response,)f(otherwise)h(raises) 208 2843 y FJ(error_perm)e FN(on)i(permission)f(errors)h(or)g FJ(error_reply)e FN(on)i(other)f(errors.)0 2990 y FD(cwd)p FJ(\()p FK(pathname)p FJ(\))208 3090 y FN(Set)h(the)h(current)d (directory)h(on)h(the)g(serv)o(er)-5 b(.)0 3236 y FD(mkd)p FJ(\()p FK(pathname)p FJ(\))208 3336 y FN(Create)20 b(a)h(ne)n(w)f (directory)e(on)i(the)g(serv)o(er)-5 b(.)0 3483 y FD(pwd)p FJ(\(\))208 3583 y FN(Return)19 b(the)i(pathname)d(of)i(the)g(current)f (directory)f(on)i(the)g(serv)o(er)-5 b(.)0 3729 y FD(rmd)p FJ(\()p FK(dirname)p FJ(\))208 3829 y FN(Remo)o(v)o(e)19 b(the)h(directory)e(named)h FK(dirname)h FN(on)g(the)g(serv)o(er)-5 b(.)0 3976 y FD(size)p FJ(\()p FK(\002lename)p FJ(\))208 4076 y FN(Request)29 b(the)g(size)h(of)g(the)f(\002le)h(named)e FK(\002lename)h FN(on)g(the)g(serv)o(er)-5 b(.)52 b(On)30 b(success,)i(the)d(size)h(of)f(the)h(\002le)g(is)g(returned)e(as)i(an) 208 4175 y(inte)o(ger)m(,)24 b(otherwise)h FJ(None)g FN(is)h(returned.)38 b(Note)25 b(that)g(the)h(`)p FJ(SIZE)p FN(')e(command)f(is)j(not)f(standardized,)f(b)n(ut)i(is)g(supported)d (by)208 4275 y(man)o(y)c(common)f(serv)o(er)h(implementations.)0 4422 y FD(quit)p FJ(\(\))208 4521 y FN(Send)g(a)i(`)p FJ(QUIT)p FN(')f(command)e(to)i(the)h(serv)o(er)e(and)h(close)g(the)g (connection.)j(This)e(is)g(the)f(\223polite\224)g(w)o(ay)g(to)h(close)f (a)h(connection,)208 4621 y(b)n(ut)f(it)g(may)g(raise)g(an)g(e)o (xception)e(of)i(the)g(serv)o(er)f(reponds)g(with)h(an)g(error)f(to)h (the)g(`)p FJ(QUIT)p FN(')f(command.)k(This)d(implies)g(a)h(call)f(to) 208 4721 y(the)g FJ(close\(\))f FN(method)g(which)h(renders)f(the)h FJ(FTP)g FN(instance)g(useless)h(for)f(subsequent)e(calls)j(\(see)g (belo)n(w\).)0 4867 y FD(close)p FJ(\(\))208 4967 y FN(Close)30 b(the)g(connection)d(unilaterally)-5 b(.)52 b(This)30 b(should)f(not)g(be)h(applied)f(to)h(an)f(already)g(closed)g (connection)f(such)h(as)i(after)208 5067 y(a)e(successful)h(call)g(to)f FJ(quit\(\))p FN(.)52 b(After)30 b(this)g(call)f(the)h FJ(FTP)f FN(instance)g(should)g(not)g(be)g(used)h(an)o(y)e(more)h (\(after)g(a)h(call)f(to)208 5166 y FJ(close\(\))19 b FN(or)h FJ(quit\(\))g FN(you)f(cannot)g(reopen)g(the)h(connection)e(by) i(issuing)g(another)e FJ(login\(\))i FN(method\).)p 0 5549 3901 4 v 0 5649 a FI(18.8.)52 b FJ(ftplib)22 b FI(\227)h(FTP)g (protocol)h(client)2406 b(639)p eop end %%Page: 640 652 TeXDict begin 640 651 bop 0 88 a FE(18.9)121 b Fx(gopherlib)31 b FE(\227)i(Gopher)i(protocol)f(client)0 321 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)f(2.5.)k FN(The)c FJ(gopher)f FN(protocol)g(is)i (not)f(in)g(acti)n(v)o(e)g(use)g(an)o(ymore.)0 468 y(This)31 b(module)e(pro)o(vides)g(a)i(minimal)f(implementation)e(of)j(client)f (side)h(of)g(the)f(Gopher)g(protocol.)54 b(It)31 b(is)h(used)e(by)g (the)h(module)0 567 y FJ(urllib)20 b FN(to)g(handle)f(URLs)i(that)f (use)h(the)f(Gopher)f(protocol.)0 714 y(The)h(module)f(de\002nes)h(the) g(follo)n(wing)e(functions:)0 861 y FD(send_selector)p FJ(\()p FK(selector)-9 b(,)18 b(host)q FC([)p FK(,)i(port)13 b FC(])p FJ(\))208 961 y FN(Send)18 b(a)i FK(selector)i FN(string)c(to)i(the)f(gopher)e(serv)o(er)i(at)g FK(host)i FN(and)e FK(port)h FN(\(def)o(ault)f FJ(70)p FN(\).)24 b(Returns)19 b(an)g(open)f(\002le)i(object)f(from)f(which)208 1060 y(the)i(returned)e(document)g(can)i(be)g(read.)0 1207 y FD(send_query)p FJ(\()p FK(selector)-9 b(,)18 b(query)-5 b(,)20 b(host)q FC([)p FK(,)g(port)13 b FC(])p FJ(\))208 1307 y FN(Send)22 b(a)h FK(selector)i FN(string)d(and)g(a)i FK(query)e FN(string)g(to)h(a)g(gopher)e(serv)o(er)h(at)h FK(host)h FN(and)e FK(port)i FN(\(def)o(ault)e FJ(70)p FN(\).)32 b(Returns)23 b(an)f(open)g(\002le)208 1407 y(object)d(from)g(which)h(the)g(returned)f(document)f(can)i(be)g(read.) 0 1553 y(Note)k(that)h(the)f(data)g(returned)f(by)h(the)g(Gopher)f (serv)o(er)h(can)g(be)g(of)h(an)o(y)e(type,)i(depending)d(on)i(the)g (\002rst)h(character)e(of)h(the)h(selector)0 1653 y(string.)f(If)19 b(the)f(data)h(is)g(te)o(xt)g(\(\002rst)g(character)f(of)g(the)h (selector)f(is)i(`)p FJ(0)p FN('\),)e(lines)h(are)f(terminated)g(by)g (CRLF)-7 b(,)20 b(and)e(the)h(data)f(is)i(terminated)0 1753 y(by)k(a)g(line)h(consisting)e(of)h(a)h(single)f(`)p FJ(.)p FN(',)h(and)e(a)i(leading)e(`)p FJ(.)p FN(')37 b(should)23 b(be)i(stripped)e(from)g(lines)i(that)f(be)o(gin)f(with)h (`)p FJ(..)p FN('.)37 b(Directory)0 1852 y(listings)21 b(\(\002rst)f(character)f(of)h(the)g(selector)g(is)h(`)p FJ(1)p FN('\))f(are)g(transferred)e(using)i(the)g(same)h(protocol.)0 2180 y FE(18.10)122 b Fx(poplib)31 b FE(\227)i(POP3)g(protocol)i (client)0 2413 y FN(This)24 b(module)f(de\002nes)h(a)h(class,)h FJ(POP3)p FN(,)f(which)e(encapsulates)h(a)g(connection)e(to)j(a)f(POP3) h(serv)o(er)e(and)h(implements)f(the)h(protocol)0 2512 y(as)i(de\002ned)d(in)i(RFC)i(1725.)37 b(The)25 b FJ(POP3)f FN(class)i(supports)e(both)g(the)h(minimal)f(and)g(optional)g(command)e (sets.)40 b(Additionally)-5 b(,)24 b(this)0 2612 y(module)29 b(pro)o(vides)g(a)j(class)f FJ(POP3_SSL)p FN(,)f(which)g(pro)o(vides)f (support)h(for)g(connecting)f(to)h(POP3)i(serv)o(ers)e(that)h(use)g (SSL)g(as)h(an)0 2711 y(underlying)17 b(protocol)i(layer)-5 b(.)0 2858 y(Note)20 b(that)g(POP3,)h(though)d(widely)i(supported,)e (is)j(obsolescent.)j(The)19 b(implementation)f(quality)i(of)g(POP3)g (serv)o(ers)g(v)n(aries)g(widely)-5 b(,)0 2958 y(and)19 b(too)h(man)o(y)f(are)h(quite)g(poor)-5 b(.)24 b(If)19 b(your)g(mailserv)o(er)g(supports)g(IMAP)-9 b(,)20 b(you)f(w)o(ould)g (be)h(better)g(of)n(f)f(using)g(the)h FJ(imaplib.IMAP4)0 3058 y FN(class,)h(as)g(IMAP)f(serv)o(ers)g(tend)f(to)i(be)f(better)g (implemented.)0 3204 y(A)h(single)f(class)h(is)g(pro)o(vided)d(by)h (the)i FJ(poplib)e FN(module:)0 3351 y FL(class)i FD(POP3)p FJ(\()p FK(host)q FC([)p FK(,)e(port)13 b FC(])p FJ(\))208 3451 y FN(This)23 b(class)h(implements)e(the)h(actual)g(POP3)g (protocol.)32 b(The)23 b(connection)e(is)j(created)e(when)h(the)g (instance)f(is)i(initialized.)34 b(If)208 3551 y FK(port)21 b FN(is)g(omitted,)f(the)g(standard)f(POP3)h(port)g(\(110\))e(is)k (used.)0 3697 y FL(class)f FD(POP3_SSL)p FJ(\()p FK(host)q FC([)p FK(,)d(port)q FC([)p FK(,)j(k)o(e)n(y\002le)p FC([)p FK(,)e(cert\002le)12 b FC(])g(])g(])p FJ(\))208 3797 y FN(This)25 b(is)h(a)f(subclass)g(of)g FJ(POP3)g FN(that)g(connects)f(to)h(the)g(serv)o(er)g(o)o(v)o(er)e(an)i(SSL)h (encrypted)d(sock)o(et.)39 b(If)25 b FK(port)h FN(is)g(not)f (speci\002ed,)208 3897 y(995,)f(the)g(standard)g(POP3-o)o(v)o(er)n (-SSL)e(port)i(is)h(used.)37 b FK(k)o(e)n(y\002le)24 b FN(and)g FK(cert\002le)g FN(are)h(also)f(optional)g(-)g(the)o(y)g (can)g(contain)f(a)i(PEM)208 3996 y(formatted)18 b(pri)n(v)n(ate)h(k)o (e)o(y)h(and)f(certi\002cate)i(chain)e(\002le)i(for)f(the)g(SSL)h (connection.)208 4129 y(Ne)n(w)f(in)g(v)o(ersion)f(2.4.)0 4276 y(One)h(e)o(xception)e(is)j(de\002ned)f(as)h(an)f(attrib)n(ute)g (of)f(the)i FJ(poplib)e FN(module:)0 4423 y FL(exception)g FD(error_proto)208 4522 y FN(Exception)f(raised)i(on)g(an)o(y)f (errors.)24 b(The)c(reason)g(for)f(the)h(e)o(xception)f(is)i(passed)f (to)g(the)g(constructor)f(as)i(a)f(string.)0 4669 y FL(See)h(Also:)0 4816 y FN(Module)e FJ(imaplib)g FN(\(section)h(18.11\):)208 4916 y(The)f(standard)g(Python)g(IMAP)i(module.)0 5063 y FK(F)-5 b(r)m(equently)19 b(Ask)o(ed)i(Questions)e(About)h(F)-6 b(etc)o(hmail)0 5162 y Fy(\()p FO(http://www)l(.catb)m(.org/\230esr/f)n (e)o(tchmai)o(l/f)m(et)o(chmail)o(-F)g(A)m(Q.html)g Fy(\))208 5262 y FN(The)18 b(F)-6 b(A)h(Q)20 b(for)e(the)g FL(fetchmail)h FN(POP/IMAP)g(client)g(collects)f(information)f(on)h(POP3)h(serv)o(er)f (v)n(ariations)g(and)g(RFC)i(noncom-)208 5362 y(pliance)f(that)h(may)g (be)g(useful)g(if)g(you)g(need)f(to)h(write)h(an)f(application)f(based) g(on)h(the)g(POP)h(protocol.)p 0 5549 3901 4 v 0 5649 a FI(640)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 641 653 TeXDict begin 641 652 bop 0 83 a Fv(18.10.1)101 b(POP3)28 b(Objects)0 286 y FN(All)22 b(POP3)g(commands)e(are)h(represented)f(by) h(methods)f(of)i(the)f(same)h(name,)f(in)g(lo)n(wer)n(-case;)h(most)g (return)e(the)h(response)g(te)o(xt)g(sent)0 386 y(by)f(the)g(serv)o(er) -5 b(.)0 532 y(An)20 b FJ(POP3)g FN(instance)g(has)g(the)h(follo)n (wing)d(methods:)0 679 y FD(set_debuglevel)p FJ(\()p FK(le)o(vel)p FJ(\))208 779 y FN(Set)31 b(the)g(instance')-5 b(s)31 b(deb)n(ugging)d(le)n(v)o(el.)57 b(This)31 b(controls)f(the)h (amount)f(of)g(deb)n(ugging)f(output)g(printed.)56 b(The)31 b(def)o(ault,)h FJ(0)p FN(,)208 879 y(produces)26 b(no)h(deb)n(ugging)f (output.)47 b(A)29 b(v)n(alue)e(of)h FJ(1)g FN(produces)e(a)j(moderate) d(amount)h(of)h(deb)n(ugging)d(output,)k(generally)d(a)208 978 y(single)g(line)g(per)g(request.)42 b(A)27 b(v)n(alue)e(of)h FJ(2)h FN(or)f(higher)f(produces)f(the)i(maximum)f(amount)g(of)g(deb)n (ugging)f(output,)i(logging)208 1078 y(each)19 b(line)i(sent)f(and)g (recei)n(v)o(ed)e(on)i(the)g(control)f(connection.)0 1225 y FD(getwelcome)p FJ(\(\))208 1324 y FN(Returns)h(the)g(greeting)f (string)g(sent)i(by)f(the)g(POP3)h(serv)o(er)-5 b(.)0 1471 y FD(user)p FJ(\()p FK(username)p FJ(\))208 1571 y FN(Send)19 b(user)h(command,)e(response)i(should)f(indicate)g(that)i (a)f(passw)o(ord)g(is)h(required.)0 1718 y FD(pass_)p FJ(\()p FK(passwor)m(d)r FJ(\))208 1817 y FN(Send)h(passw)o(ord,)h (response)f(includes)h(message)g(count)f(and)g(mailbox)g(size.)34 b(Note:)d(the)24 b(mailbox)d(on)i(the)g(serv)o(er)f(is)i(lock)o(ed)208 1917 y(until)c FJ(quit\(\))f FN(is)i(called.)0 2064 y FD(apop)p FJ(\()p FK(user)-9 b(,)19 b(secr)m(et)q FJ(\))208 2163 y FN(Use)h(the)h(more)e(secure)h(APOP)h(authentication)d(to)i(log) g(into)g(the)g(POP3)h(serv)o(er)-5 b(.)0 2310 y FD(rpop)p FJ(\()p FK(user)r FJ(\))208 2410 y FN(Use)20 b(RPOP)i(authentication)c (\(similar)i(to)g(UNIX)h(r)n(-commands\))c(to)k(log)f(into)f(POP3)i (serv)o(er)-5 b(.)0 2557 y FD(stat)p FJ(\(\))208 2656 y FN(Get)20 b(mailbox)f(status.)26 b(The)20 b(result)g(is)h(a)g(tuple)e (of)h(2)h(inte)o(gers:)j FJ(\()p FK(messa)o(g)o(e)c(count)q FJ(,)49 b FK(mailbox)19 b(size)p FJ(\))p FN(.)0 2803 y FD(list)p FJ(\()p FC([)p FK(whic)o(h)12 b FC(])p FJ(\))208 2903 y FN(Request)19 b(message)f(list,)i(result)f(is)h(in)f(the)g(form) f FJ(\()p FK(r)m(esponse)p FJ(,)48 b(['mesg_num)g(octets',)h(...],)g FK(octets)p FJ(\))p FN(.)24 b(If)19 b FK(whic)o(h)208 3003 y FN(is)i(set,)f(it)h(is)g(the)g(message)f(to)g(list.)0 3149 y FD(retr)p FJ(\()p FK(whic)o(h)p FJ(\))208 3249 y FN(Retrie)n(v)o(e)15 b(whole)h(message)g(number)e FK(whic)o(h)p FN(,)j(and)e(set)i(its)h(seen)e(\003ag.)24 b(Result)16 b(is)i(in)e(form)f FJ(\()p FK(r)m(esponse)p FJ(,)49 b(['line',)f(...],) 208 3349 y FK(octets)p FJ(\))p FN(.)0 3496 y FD(dele)p FJ(\()p FK(whic)o(h)p FJ(\))208 3595 y FN(Flag)29 b(message)f(number)g FK(whic)o(h)g FN(for)h(deletion.)50 b(On)29 b(most)g(serv)o(ers)f (deletions)h(are)f(not)h(actually)f(performed)f(until)i(Q)o(UIT)208 3695 y(\(the)c(major)f(e)o(xception)f(is)k(Eudora)c(QPOP)-9 b(,)26 b(which)f(deliberately)e(violates)j(the)f(RFCs)i(by)e(doing)f (pending)f(deletes)i(on)g(an)o(y)208 3794 y(disconnect\).)0 3941 y FD(rset)p FJ(\(\))208 4041 y FN(Remo)o(v)o(e)19 b(an)o(y)g(deletion)g(marks)h(for)f(the)i(mailbox.)0 4188 y FD(noop)p FJ(\(\))208 4287 y FN(Do)f(nothing.)j(Might)d(be)g (used)g(as)h(a)f(k)o(eep-ali)n(v)o(e.)0 4434 y FD(quit)p FJ(\(\))208 4534 y FN(Signof)n(f:)j(commit)d(changes,)f(unlock)f (mailbox,)h(drop)g(connection.)0 4681 y FD(top)p FJ(\()p FK(whic)o(h,)g(howmuc)o(h)p FJ(\))208 4780 y FN(Retrie)n(v)o(es)25 b(the)g(message)h(header)e(plus)i FK(howmuc)o(h)e FN(lines)i(of)f(the)g (message)h(after)f(the)g(header)g(of)g(message)g(number)f FK(whic)o(h)p FN(.)208 4880 y(Result)d(is)g(in)f(form)f FJ(\()p FK(r)m(esponse)p FJ(,)49 b(['line',)f(...],)h FK(octets)p FJ(\))p FN(.)208 5013 y(The)25 b(POP3)g(T)o(OP)g(command)f (this)i(method)e(uses,)j(unlik)o(e)d(the)i(RETR)g(command,)e(doesn')o (t)g(set)i(the)f(message')-5 b(s)26 b(seen)f(\003ag;)208 5112 y(unfortunately)-5 b(,)28 b(T)o(OP)i(is)h(poorly)e(speci\002ed)h (in)g(the)g(RFCs)i(and)d(is)j(frequently)27 b(brok)o(en)i(in)h(of)n (f-brand)d(serv)o(ers.)54 b(T)-6 b(est)31 b(this)208 5212 y(method)18 b(by)i(hand)f(against)h(the)g(POP3)h(serv)o(ers)e(you) g(will)i(use)g(before)e(trusting)g(it.)0 5359 y FD(uidl)p FJ(\()p FC([)p FK(whic)o(h)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(18.10.)52 b FJ(poplib)22 b FI(\227)h(POP3)h (protocol)f(client)2296 b(641)p eop end %%Page: 642 654 TeXDict begin 642 653 bop 208 83 a FN(Return)18 b(message)g(digest)h (\(unique)e(id\))i(list.)25 b(If)19 b FK(whic)o(h)f FN(is)i (speci\002ed,)e(result)h(contains)f(the)h(unique)e(id)i(for)f(that)h (message)g(in)g(the)208 183 y(form)g FJ(')p FK(r)m(esponse)48 b(mesgnum)h(uid)r FN(,)20 b(otherwise)f(result)h(is)i(list)f FJ(\()p FK(r)m(esponse)p FJ(,)48 b(['mesgnum)g(uid',)h(...],)g FK(octets)p FJ(\))p FN(.)0 330 y(Instances)20 b(of)g FJ(POP3_SSL)f FN(ha)n(v)o(e)g(no)h(additional)f(methods.)24 b(The)c(interf)o(ace)f(of)h(this)h(subclass)f(is)h(identical)f(to)g (its)i(parent.)0 614 y Fv(18.10.2)101 b(POP3)28 b(Example)0 817 y FN(Here)20 b(is)h(a)g(minimal)e(e)o(xample)g(\(without)g(error)g (checking\))f(that)j(opens)e(a)i(mailbox)e(and)g(retrie)n(v)o(es)h(and) f(prints)h(all)h(messages:)236 1056 y FA(import)44 b(getpass,)g(poplib) 236 1238 y(M)h(=)g(poplib.POP3\('localhost'\))236 1329 y(M.user\(getpass.getuser\(\)\))236 1421 y (M.pass_\(getpass.getpass\(\)\))236 1512 y(numMessages)e(=)i (len\(M.list\(\)[1]\))236 1603 y(for)g(i)f(in)h(range\(numMessages\):) 416 1695 y(for)f(j)h(in)f(M.retr\(i+1\)[1]:)595 1786 y(print)g(j)0 2073 y FN(At)21 b(the)f(end)g(of)g(the)g(module,)e(there) i(is)h(a)g(test)g(section)f(that)g(contains)g(a)g(more)g(e)o(xtensi)n (v)o(e)e(e)o(xample)h(of)h(usage.)0 2400 y FE(18.11)122 b Fx(imaplib)31 b FE(\227)i(IMAP4)g(protocol)h(client)0 2633 y FN(This)18 b(module)f(de\002nes)g(three)h(classes,)h FJ(IMAP4)p FN(,)f FJ(IMAP4_SSL)f FN(and)g FJ(IMAP4_stream)p FN(,)f(which)i(encapsulate)e(a)j(connection)d(to)i(an)0 2732 y(IMAP4)h(serv)o(er)g(and)g(implement)g(a)h(lar)o(ge)e(subset)i (of)f(the)h(IMAP4re)n(v1)e(client)h(protocol)f(as)j(de\002ned)d(in)i (RFC)h(2060.)j(It)c(is)g(backw)o(ard)0 2832 y(compatible)f(with)h (IMAP4)g(\(RFC)h(1730\))e(serv)o(ers,)g(b)n(ut)h(note)g(that)g(the)g(`) p FJ(STATUS)p FN(')f(command)g(is)i(not)f(supported)e(in)i(IMAP4.)0 2979 y(Three)f(classes)j(are)e(pro)o(vided)d(by)j(the)g FJ(imaplib)g FN(module,)e FJ(IMAP4)i FN(is)h(the)g(base)f(class:)0 3126 y FL(class)h FD(IMAP4)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)e(port)13 b FC(])f(])p FJ(\))208 3225 y FN(This)23 b(class)i(implements)e(the)g(actual)h(IMAP4)f(protocol.)34 b(The)23 b(connection)f(is)i(created)f(and)h(protocol)d(v)o(ersion)i (\(IMAP4)g(or)208 3325 y(IMAP4re)n(v1\))d(is)j(determined)d(when)i(the) g(instance)g(is)i(initialized.)31 b(If)22 b FK(host)i FN(is)f(not)f(speci\002ed,)g FJ('')i FN(\(the)e(local)g(host\))g(is)h (used.)208 3425 y(If)d FK(port)h FN(is)g(omitted,)f(the)g(standard)f (IMAP4)h(port)f(\(143\))g(is)i(used.)0 3572 y(Three)e(e)o(xceptions)g (are)h(de\002ned)f(as)i(attrib)n(utes)f(of)g(the)g FJ(IMAP4)g FN(class:)0 3718 y FL(exception)f FD(IMAP4.error)208 3818 y FN(Exception)f(raised)i(on)g(an)o(y)f(errors.)24 b(The)c(reason)g(for)f(the)h(e)o(xception)f(is)i(passed)f(to)g(the)g (constructor)f(as)i(a)f(string.)0 3965 y FL(exception)f FD(IMAP4.abort)208 4065 y FN(IMAP4)g(serv)o(er)f(errors)h(cause)h(this) g(e)o(xception)d(to)j(be)f(raised.)25 b(This)20 b(is)g(a)g(sub-class)g (of)f FJ(IMAP4.error)p FN(.)k(Note)d(that)f(closing)208 4164 y(the)h(instance)g(and)f(instantiating)h(a)g(ne)n(w)g(one)g(will)h (usually)e(allo)n(w)h(reco)o(v)o(ery)e(from)h(this)i(e)o(xception.)0 4311 y FL(exception)e FD(IMAP4.readonly)208 4411 y FN(This)27 b(e)o(xception)d(is)k(raised)f(when)f(a)h(writable)g(mailbox)e(has)i (its)h(status)g(changed)d(by)h(the)h(serv)o(er)-5 b(.)44 b(This)27 b(is)h(a)f(sub-class)g(of)208 4510 y FJ(IMAP4.error)p FN(.)42 b(Some)26 b(other)g(client)h(no)n(w)f(has)h(write)f (permission,)h(and)f(the)h(mailbox)e(will)i(need)f(to)h(be)f(re-opened) e(to)208 4610 y(re-obtain)18 b(write)i(permission.)0 4757 y(There')-5 b(s)20 b(also)g(a)h(subclass)f(for)g(secure)g (connections:)0 4904 y FL(class)h FD(IMAP4_SSL)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)d(port)q FC([)p FK(,)i(k)o(e)n(y\002le)p FC([)p FK(,)f(cert\002le)12 b FC(])g(])g(])g(])p FJ(\))208 5003 y FN(This)22 b(is)h(a)g(subclass)g(deri)n(v)o(ed)d(from)h FJ(IMAP4)h FN(that)h(connects)e(o)o(v)o(er)g(an)h(SSL)h(encrypted)d (sock)o(et)i(\(to)g(use)h(this)g(class)g(you)e(need)208 5103 y(a)k(sock)o(et)f(module)f(that)i(w)o(as)g(compiled)f(with)g(SSL)i (support\).)36 b(If)24 b FK(host)i FN(is)g(not)e(speci\002ed,)h FJ('')h FN(\(the)f(local)f(host\))g(is)i(used.)38 b(If)208 5203 y FK(port)20 b FN(is)g(omitted,)e(the)h(standard)f(IMAP4-o)o(v)o (er)n(-SSL)e(port)i(\(993\))f(is)j(used.)k FK(k)o(e)n(y\002le)19 b FN(and)f FK(cert\002le)h FN(are)g(also)g(optional)e(-)j(the)o(y)e (can)208 5302 y(contain)h(a)h(PEM)h(formatted)d(pri)n(v)n(ate)h(k)o(e)o (y)h(and)g(certi\002cate)g(chain)f(\002le)i(for)f(the)g(SSL)h (connection.)p 0 5549 3901 4 v 0 5649 a FI(642)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 643 655 TeXDict begin 643 654 bop 0 83 a FN(The)20 b(second)f(subclass)i(allo)n (ws)f(for)g(connections)e(created)h(by)h(a)h(child)f(process:)0 230 y FL(class)h FD(IMAP4_stream)p FJ(\()p FK(command)r FJ(\))208 330 y FN(This)d(is)h(a)f(subclass)h(deri)n(v)o(ed)d(from)h FJ(IMAP4)h FN(that)g(connects)f(to)i(the)f FJ(stdin/stdout)e FN(\002le)j(descriptors)e(created)g(by)h(passing)208 429 y FK(command)i FN(to)h FJ(os.popen2\(\))p FN(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 576 y(The)h(follo)n(wing)e (utility)j(functions)d(are)i(de\002ned:)0 723 y FD(Internaldate2tuple)p FJ(\()p FK(datestr)r FJ(\))208 823 y FN(Con)m(v)o(erts)f(an)h(IMAP4)f (INTERN)m(ALD)m(A)-9 b(TE)19 b(string)h(to)g(Coordinated)f(Uni)n(v)o (ersal)g(T)m(ime.)25 b(Returns)20 b(a)g FJ(time)g FN(module)f(tuple.)0 969 y FD(Int2AP)p FJ(\()p FK(num)p FJ(\))208 1069 y FN(Con)m(v)o(erts)g (an)h(inte)o(ger)f(into)h(a)g(string)g(representation)e(using)i (characters)f(from)g(the)h(set)h([)p FJ(A)g FN(..)k FJ(P)p FN(].)0 1216 y FD(ParseFlags)p FJ(\()p FK(\003a)o(gstr)r FJ(\))208 1316 y FN(Con)m(v)o(erts)19 b(an)h(IMAP4)f(`)p FJ(FLAGS)p FN(')h(response)f(to)h(a)h(tuple)f(of)g(indi)n(vidual)e (\003ags.)0 1462 y FD(Time2Internaldate)p FJ(\()p FK(date)p 1049 1462 25 4 v 25 w(time)p FJ(\))208 1562 y FN(Con)m(v)o(erts)k(a)i FJ(time)g FN(module)e(tuple)h(to)h(an)f(IMAP4)h(`)p FJ(INTERNALDATE)p FN(')d(representation.)33 b(Returns)24 b(a)g(string)f(in)h(the)g(form:) 208 1662 y FJ("DD-Mmm-YYYY)47 b(HH:MM:SS)h(+HHMM")20 b FN(\(including)e(double-quotes\).)0 1808 y(Note)30 b(that)g(IMAP4)g(message)g(numbers)f(change)f(as)j(the)f(mailbox)f (changes;)34 b(in)c(particular)m(,)h(after)f(an)g(`)p FJ(EXPUNGE)p FN(')f(command)0 1908 y(performs)24 b(deletions)g(the)h (remaining)f(messages)h(are)g(renumbered.)38 b(So)25 b(it)h(is)g(highly)e(advisable)h(to)g(use)g(UIDs)h(instead,)g(with)g (the)0 2008 y(UID)20 b(command.)0 2155 y(At)h(the)f(end)g(of)g(the)g (module,)e(there)i(is)h(a)g(test)g(section)f(that)g(contains)g(a)g (more)g(e)o(xtensi)n(v)o(e)e(e)o(xample)h(of)h(usage.)0 2301 y FL(See)h(Also:)0 2448 y FN(Documents)29 b(describing)g(the)i (protocol,)g(and)f(sources)g(and)g(binaries)g(for)g(serv)o(ers)g (implementing)f(it,)k(can)e(all)g(be)g(found)d(at)k(the)0 2548 y(Uni)n(v)o(ersity)19 b(of)h(W)-7 b(ashington')i(s)20 b FK(IMAP)g(Information)e(Center)j FN(\()p FO(http://www)l(.cac.w)o (ashington)o(.ed)o(u/i)o(map)o(/)-6 b FN(\).)0 2833 y Fv(18.11.1)101 b(IMAP4)29 b(Objects)0 3036 y FN(All)21 b(IMAP4re)n(v1)d(commands)h(are)h(represented)e(by)i(methods)f(of)h (the)g(same)h(name,)e(either)h(upper)n(-case)e(or)i(lo)n(wer)n(-case.)0 3183 y(All)39 b(ar)o(guments)e(to)i(commands)e(are)i(con)m(v)o(erted)d (to)j(strings,)k(e)o(xcept)38 b(for)g(`)p FJ(AUTHENTICATE)p FN(',)e(and)j(the)f(last)i(ar)o(gument)c(to)0 3282 y(`)p FJ(APPEND)p FN(')28 b(which)h(is)h(passed)g(as)g(an)f(IMAP4)g(literal.) 53 b(If)29 b(necessary)g(\(the)g(string)g(contains)g(IMAP4)g (protocol-sensiti)n(v)o(e)d(char)n(-)0 3382 y(acters)k(and)f(isn')o(t)g (enclosed)g(with)h(either)f(parentheses)g(or)g(double)f(quotes\))h (each)g(string)h(is)g(quoted.)52 b(Ho)n(we)n(v)o(er)m(,)30 b(the)g FK(passwor)m(d)0 3482 y FN(ar)o(gument)18 b(to)j(the)g(`)p FJ(LOGIN)p FN(')e(command)g(is)i(al)o(w)o(ays)g(quoted.)k(If)c(you)e(w) o(ant)i(to)g(a)n(v)n(oid)f(ha)n(ving)g(an)g(ar)o(gument)f(string)h (quoted)f(\(e)o(g:)26 b(the)0 3581 y FK(\003a)o(gs)20 b FN(ar)o(gument)e(to)i(`)p FJ(STORE)p FN('\))f(then)g(enclose)h(the)g (string)g(in)h(parentheses)e(\(e)o(g:)24 b FJ(r'\(\\Deleted\)')p FN(\).)0 3728 y(Each)c(command)f(returns)i(a)g(tuple:)26 b FJ(\()p FK(type)p FJ(,)49 b([)p FK(data)p FJ(,)f(...]\))27 b FN(where)21 b FK(type)f FN(is)i(usually)f FJ('OK')f FN(or)h FJ('NO')p FN(,)g(and)f FK(data)g FN(is)i(either)f(the)0 3828 y(te)o(xt)g(from)f(the)h(command)e(response,)h(or)g(mandated)g (results)h(from)f(the)h(command.)k(Each)c FK(data)f FN(is)i(either)e(a) i(string,)e(or)h(a)g(tuple.)27 b(If)21 b(a)0 3927 y(tuple,)f(then)f (the)h(\002rst)h(part)f(is)h(the)g(header)e(of)h(the)g(response,)f(and) g(the)i(second)e(part)h(contains)f(the)h(data)g(\(ie:)26 b(')o(literal')20 b(v)n(alue\).)0 4074 y(The)d FK(messa)o(g)o(e)p 432 4074 V 30 w(set)i FN(options)e(to)g(commands)f(belo)n(w)h(is)h(a)g (string)f(specifying)f(one)g(or)i(more)e(messages)i(to)f(be)h(acted)f (upon.)22 b(It)c(may)f(be)g(a)0 4174 y(simple)i(message)h(number)d(\()p FJ('1')p FN(\),)i(a)h(range)e(of)h(message)g(numbers)f(\()p FJ('2:4')p FN(\),)h(or)g(a)h(group)d(of)i(non-contiguous)d(ranges)j (separated)0 4273 y(by)h(commas)f(\()p FJ('1:3,6:9')p FN(\).)k(A)e(range)e(can)h(contain)f(an)h(asterisk)h(to)f(indicate)g (an)g(in\002nite)g(upper)f(bound)f(\()p FJ('3:)3352 4288 y(*)3402 4273 y(')p FN(\).)0 4420 y(An)i FJ(IMAP4)g FN(instance)g(has)g (the)g(follo)n(wing)f(methods:)0 4567 y FD(append)p FJ(\()p FK(mailbox,)f(\003a)o(gs,)h(date)p 1004 4567 V 29 w(time)o(,)i(messa)o (g)o(e)p FJ(\))208 4667 y FN(Append)d FK(messa)o(g)o(e)j FN(to)f(named)f(mailbox.)0 4814 y FD(authenticate)p FJ(\()p FK(mec)o(hanism,)d(authobject)q FJ(\))208 4913 y FN(Authenticate)j (command)f(\227)j(requires)e(response)g(processing.)208 5046 y FK(mec)o(hanism)24 b FN(speci\002es)h(which)g(authentication)e (mechanism)h(is)i(to)g(be)f(used)g(-)g(it)h(should)e(appear)g(in)i(the) f(instance)g(v)n(ariable)208 5146 y FJ(capabilities)18 b FN(in)i(the)h(form)e FJ(AUTH=mechanism)p FN(.)208 5279 y FK(authobject)g FN(must)i(be)f(a)g(callable)g(object:)p 0 5549 3901 4 v 0 5649 a FI(18.11.)52 b FJ(imaplib)22 b FI(\227)h(IMAP4)i(protocol)e(client)2218 b(643)p eop end %%Page: 644 656 TeXDict begin 644 655 bop 444 174 a FA(data)44 b(=)h (authobject\(response\))208 364 y FN(It)23 b(will)g(be)g(called)f(to)h (process)g(serv)o(er)f(continuation)e(responses.)32 b(It)23 b(should)f(return)f FJ(data)i FN(that)g(will)g(be)g(encoded)e(and)h (sent)208 463 y(to)e(serv)o(er)-5 b(.)24 b(It)d(should)e(return)g FJ(None)h FN(if)h(the)f(client)g(abort)f(response)h(`)2219 478 y FJ(*)2269 463 y FN(')f(should)h(be)g(sent)g(instead.)0 610 y FD(check)p FJ(\(\))208 710 y FN(Checkpoint)e(mailbox)h(on)h(serv) o(er)-5 b(.)0 857 y FD(close)p FJ(\(\))208 956 y FN(Close)27 b(currently)e(selected)h(mailbox.)43 b(Deleted)27 b(messages)f(are)h (remo)o(v)o(ed)d(from)i(writable)g(mailbox.)43 b(This)27 b(is)g(the)g(recom-)208 1056 y(mended)18 b(command)g(before)h(`)p FJ(LOGOUT)p FN('.)0 1203 y FD(copy)p FJ(\()p FK(messa)o(g)o(e)p 535 1203 25 4 v 29 w(set,)h(ne)o(w)p 830 1203 V 30 w(mailbox)p FJ(\))208 1303 y FN(Cop)o(y)f FK(messa)o(g)o(e)p 692 1303 V 30 w(set)j FN(messages)f(onto)e(end)h(of)g FK(ne)o(w)p 1703 1303 V 29 w(mailbox)p FN(.)0 1449 y FD(create)p FJ(\()p FK(mailbox)p FJ(\))208 1549 y FN(Create)g(ne)n(w)g(mailbox)f (named)g FK(mailbox)p FN(.)0 1696 y FD(delete)p FJ(\()p FK(mailbox)p FJ(\))208 1796 y FN(Delete)h(old)g(mailbox)f(named)g FK(mailbox)p FN(.)0 1942 y FD(deleteacl)p FJ(\()p FK(mailbox,)e(who)p FJ(\))208 2042 y FN(Delete)j(the)g(A)m(CLs)h(\(remo)o(v)o(e)d(an)o(y)h (rights\))h(set)h(for)e(who)h(on)g(mailbox.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 2189 y FD(expunge)p FJ(\(\))208 2289 y FN(Permanently)g(remo)o(v)o(e)g(deleted)i(items)h(from)e (selected)h(mailbox.)27 b(Generates)21 b(an)g(`)p FJ(EXPUNGE)p FN(')f(response)h(for)f(each)h(deleted)208 2388 y(message.)j(Returned) 19 b(data)i(contains)e(a)i(list)g(of)f(`)p FJ(EXPUNGE)p FN(')f(message)h(numbers)e(in)j(order)e(recei)n(v)o(ed.)0 2535 y FD(fetch)p FJ(\()p FK(messa)o(g)o(e)p 585 2535 V 28 w(set,)i(messa)o(g)o(e)p 1027 2535 V 30 w(parts)p FJ(\))208 2635 y FN(Fetch)c(\(parts)g(of\))g(messages.)25 b FK(messa)o(g)o(e)p 1377 2635 V 29 w(parts)18 b FN(should)f(be)g(a)h (string)g(of)f(message)g(part)h(names)f(enclosed)g(within)g (parentheses,)208 2734 y(e)o(g:)24 b(`)p FJ("\(UID)49 b(BODY[TEXT]\)")p FN('.)23 b(Returned)c(data)h(are)g(tuples)g(of)g (message)g(part)g(en)m(v)o(elope)e(and)i(data.)0 2881 y FD(getacl)p FJ(\()p FK(mailbox)p FJ(\))208 2981 y FN(Get)g(the)g(`)p FJ(ACL)p FN(')-5 b(s)21 b(for)e FK(mailbox)p FN(.)24 b(The)c(method)f(is)i(non-standard,)c(b)n(ut)j(is)i(supported)c(by)h (the)i(`)p FJ(Cyrus)p FN(')e(serv)o(er)-5 b(.)0 3128 y FD(getannotation)p FJ(\()p FK(mailbox,)16 b(entry)-5 b(,)21 b(attrib)n(ute)p FJ(\))208 3227 y FN(Retrie)n(v)o(e)31 b(the)i(speci\002ed)f(`)p FJ(ANNOTATION)p FN(')-5 b(s)31 b(for)g FK(mailbox)p FN(.)61 b(The)32 b(method)f(is)i(non-standard,)f (b)n(ut)g(is)h(supported)e(by)h(the)208 3327 y(`)p FJ(Cyrus)p FN(')19 b(serv)o(er)-5 b(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3474 y FD(getquota)p FJ(\()p FK(r)l(oot)q FJ(\))208 3573 y FN(Get)g(the)g(`)p FJ(quota)p FN(')e FK(r)l(oot)q FN(')-5 b(s)20 b(resource)e(usage)g(and)g(limits.)25 b(This)19 b(method)f(is)h(part)g(of)f(the)h(IMAP4)f(Q)o(UO)m(T)-8 b(A)19 b(e)o(xtension)f(de\002ned)208 3673 y(in)i(rfc2087.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3820 y FD(getquotaroot)p FJ(\()p FK(mailbox)p FJ(\))208 3920 y FN(Get)i(the)f(list)i(of)e(`)p FJ(quota)p FN(')g(`)p FJ(roots)p FN(')f(for)h(the)h(named)f FK(mailbox)p FN(.)25 b(This)c(method)e(is)j(part)e(of)g(the)h(IMAP4)f (Q)o(UO)m(T)-8 b(A)21 b(e)o(xtension)208 4019 y(de\002ned)e(in)h (rfc2087.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4166 y FD(list)p FJ(\()p FC([)p FK(dir)m(ectory)p FC([)p FK(,)f(pattern)12 b FC(])g(])p FJ(\))208 4266 y FN(List)25 b(mailbox)f(names)h(in)g FK(dir)m(ectory)g FN(matching)e FK(pattern)p FN(.)39 b FK(dir)m(ectory)25 b FN(def)o(aults)f(to)i(the)f(top-le)n(v)o(el)e (mail)i(folder)m(,)g(and)f FK(pattern)208 4365 y FN(def)o(aults)19 b(to)i(match)e(an)o(ything.)k(Returned)c(data)h(contains)g(a)g(list)i (of)e(`)p FJ(LIST)p FN(')f(responses.)0 4512 y FD(login)p FJ(\()p FK(user)-9 b(,)19 b(passwor)m(d)r FJ(\))208 4612 y FN(Identify)f(the)i(client)h(using)e(a)i(plainte)o(xt)e(passw)o(ord.) 24 b(The)c FK(passwor)m(d)i FN(will)f(be)f(quoted.)0 4759 y FD(login_cram_md5)p FJ(\()p FK(user)-9 b(,)17 b(passwor)m(d)r FJ(\))208 4858 y FN(F)o(orce)i(use)g(of)h(`)p FJ(CRAM-MD5)p FN(')e(authentication)f(when)i(identifying)f(the)h (client)h(to)g(protect)e(the)i(passw)o(ord.)k(W)m(ill)d(only)d(w)o(ork) h(if)208 4958 y(the)h(serv)o(er)f(`)p FJ(CAPABILITY)p FN(')f(response)i(includes)f(the)h(phrase)g(`)p FJ(AUTH=CRAM-MD5)p FN('.)48 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 5105 y FD(logout)p FJ(\(\))208 5204 y FN(Shutdo)n(wn)f(connection)g(to)i (serv)o(er)-5 b(.)25 b(Returns)20 b(serv)o(er)f(`)p FJ(BYE)p FN(')h(response.)0 5351 y FD(lsub)p FJ(\()p FC([)p FK(dir)m(ectory)p FC([)p FK(,)e(pattern)12 b FC(])g(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(644)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 645 657 TeXDict begin 645 656 bop 208 83 a FN(List)25 b(subscribed)e(mailbox)g (names)h(in)g(directory)f(matching)f(pattern.)37 b FK(dir)m(ectory)24 b FN(def)o(aults)g(to)g(the)h(top)f(le)n(v)o(el)g(directory)e(and)208 183 y FK(pattern)d FN(def)o(aults)h(to)g(match)g(an)o(y)f(mailbox.)24 b(Returned)19 b(data)h(are)g(tuples)g(of)g(message)g(part)g(en)m(v)o (elope)e(and)i(data.)0 330 y FD(myrights)p FJ(\()p FK(mailbox)p FJ(\))208 429 y FN(Sho)n(w)f(my)h(A)m(CLs)h(for)f(a)g(mailbox)f(\(i.e.) 25 b(the)20 b(rights)g(that)g(I)h(ha)n(v)o(e)e(on)h(mailbox\).)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 576 y FD(namespace)p FJ(\(\))208 676 y FN(Returns)h(IMAP)g(namespaces)f(as)i(de\002ned)e(in) i(RFC2342.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.3.)0 823 y FD(noop)p FJ(\(\))208 922 y FN(Send)h(`)p FJ(NOOP)p FN(')h(to)g(serv)o(er)-5 b(.)0 1069 y FD(open)p FJ(\()p FK(host,)19 b(port)q FJ(\))208 1169 y FN(Opens)28 b(sock)o(et)g(to)h FK(port)h FN(at)g FK(host)q FN(.)51 b(The)28 b(connection)e(objects)j (established)f(by)g(this)i(method)d(will)i(be)g(used)f(in)h(the)g FJ(read)p FN(,)208 1268 y FJ(readline)p FN(,)19 b FJ(send)p FN(,)g(and)h FJ(shutdown)f FN(methods.)24 b(Y)-9 b(ou)20 b(may)f(o)o(v)o(erride)f(this)j(method.)0 1415 y FD(partial)p FJ(\()p FK(messa)o(g)o(e)p 685 1415 25 4 v 28 w(num,)e(messa)o(g)o(e)p 1177 1415 V 30 w(part,)h(start,)h(length)p FJ(\))208 1515 y FN(Fetch)f(truncated)e(part)i(of)g(a)h(message.)k(Returned)19 b(data)h(is)h(a)g(tuple)e(of)h(message)g(part)g(en)m(v)o(elope)e(and)i (data.)0 1662 y FD(proxyauth)p FJ(\()p FK(user)r FJ(\))208 1761 y FN(Assume)i(authentication)f(as)j FK(user)r FN(.)33 b(Allo)n(ws)23 b(an)f(authorised)f(administrator)g(to)i(proxy)e(into)i (an)o(y)f(user')-5 b(s)23 b(mailbox.)64 b(Ne)n(w)23 b(in)208 1861 y(v)o(ersion)18 b(2.3.)0 2008 y FD(read)p FJ(\()p FK(size)p FJ(\))208 2107 y FN(Reads)i FK(size)h FN(bytes)g(from)e(the)h (remote)f(serv)o(er)-5 b(.)25 b(Y)-9 b(ou)19 b(may)h(o)o(v)o(erride)e (this)j(method.)0 2254 y FD(readline)p FJ(\(\))208 2354 y FN(Reads)f(one)g(line)g(from)f(the)h(remote)g(serv)o(er)-5 b(.)24 b(Y)-9 b(ou)20 b(may)g(o)o(v)o(erride)d(this)k(method.)0 2501 y FD(recent)p FJ(\(\))208 2600 y FN(Prompt)e(serv)o(er)g(for)h(an) g(update.)k(Returned)19 b(data)h(is)h FJ(None)f FN(if)g(no)g(ne)n(w)g (messages,)g(else)h(v)n(alue)f(of)g(`)p FJ(RECENT)p FN(')e(response.)0 2747 y FD(rename)p FJ(\()p FK(oldmailbox,)f(ne)o(wmailbox)p FJ(\))208 2847 y FN(Rename)i(mailbox)g(named)g FK(oldmailbox)g FN(to)h FK(ne)o(wmailbox)p FN(.)0 2994 y FD(response)p FJ(\()p FK(code)p FJ(\))208 3093 y FN(Return)f(data)h(for)g(response)f FK(code)h FN(if)g(recei)n(v)o(ed,)f(or)g FJ(None)p FN(.)25 b(Returns)20 b(the)g(gi)n(v)o(en)f(code,)h(instead)g(of)f(the)i(usual)f (type.)0 3240 y FD(search)p FJ(\()p FK(c)o(har)o(set,)f(criterion)p FC([)p FK(,)g(...)12 b FC(])p FJ(\))208 3340 y FN(Search)21 b(mailbox)g(for)g(matching)f(messages.)31 b FK(c)o(har)o(set)23 b FN(may)f(be)f FJ(None)p FN(,)h(in)g(which)g(case)g(no)g(`)p FJ(CHARSET)p FN(')e(will)j(be)f(speci\002ed)208 3439 y(in)j(the)h(request)f(to)g(the)h(serv)o(er)-5 b(.)40 b(The)25 b(IMAP)h(protocol)e(requires)g(that)i(at)g(least)g(one)f (criterion)g(be)g(speci\002ed;)j(an)d(e)o(xception)208 3539 y(will)20 b(be)h(raised)f(when)f(the)h(serv)o(er)g(returns)f(an)h (error)-5 b(.)208 3672 y(Example:)444 3896 y FA(#)44 b(M)h(is)g(a)f(connected)g(IMAP4)g(instance...)444 3987 y(typ,)g(msgnums)g(=)g(M.search\(None,)f('FROM',)g('"LDJ"'\))444 4170 y(#)h(or:)444 4261 y(typ,)g(msgnums)g(=)g(M.search\(None,)f ('\(FROM)h("LDJ"\)'\))0 4488 y FD(select)p FJ(\()p FC([)p FK(mailbox)p FC([)p FK(,)18 b(r)m(eadonly)12 b FC(])g(])p FJ(\))208 4588 y FN(Select)18 b(a)h(mailbox.)k(Returned)17 b(data)h(is)h(the)g(count)e(of)h(messages)g(in)h FK(mailbox)e FN(\(`)p FJ(EXISTS)p FN(')g(response\).)23 b(The)18 b(def)o(ault)g FK(mailbox)208 4687 y FN(is)j FJ('INBOX')p FN(.)e(If)h(the)g FK(r)m(eadonly)f FN(\003ag)h(is)h(set,)g(modi\002cations)e(to)h(the)g (mailbox)f(are)i(not)e(allo)n(wed.)0 4834 y FD(send)p FJ(\()p FK(data)p FJ(\))208 4934 y FN(Sends)h FJ(data)g FN(to)g(the)g(remote)g(serv)o(er)-5 b(.)24 b(Y)-9 b(ou)20 b(may)f(o)o(v)o(erride)f(this)j(method.)0 5081 y FD(setacl)p FJ(\()p FK(mailbox,)d(who,)i(what)q FJ(\))208 5180 y FN(Set)g(an)h(`)p FJ(ACL)p FN(')e(for)h FK(mailbox)p FN(.)k(The)c(method)e(is)k(non-standard,)17 b(b)n(ut)j(is)h(supported)d (by)i(the)g(`)p FJ(Cyrus)p FN(')f(serv)o(er)-5 b(.)0 5327 y FD(setannotation)p FJ(\()p FK(mailbox,)16 b(entry)-5 b(,)21 b(attrib)n(ute)p FC([)p FK(,)f(...)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(18.11.)52 b FJ(imaplib)22 b FI(\227)h(IMAP4)i(protocol)e(client)2218 b(645)p eop end %%Page: 646 658 TeXDict begin 646 657 bop 208 83 a FN(Set)22 b(`)p FJ(ANNOTATION)p FN(')-5 b(s)21 b(for)g FK(mailbox)p FN(.)29 b(The)21 b(method)g(is)i(non-standard,)c(b)n(ut)j(is)g(supported)e(by)i(the)f(`) p FJ(Cyrus)p FN(')g(serv)o(er)-5 b(.)60 b(Ne)n(w)208 183 y(in)20 b(v)o(ersion)f(2.5.)0 330 y FD(setquota)p FJ(\()p FK(r)l(oot,)f(limits)p FJ(\))208 429 y FN(Set)g(the)g(`)p FJ(quota)p FN(')e FK(r)l(oot)q FN(')-5 b(s)19 b(resource)e FK(limits)p FN(.)25 b(This)18 b(method)e(is)j(part)e(of)h(the)g(IMAP4)f (Q)o(UO)m(T)-8 b(A)18 b(e)o(xtension)e(de\002ned)h(in)h(rfc2087.)208 529 y(Ne)n(w)i(in)g(v)o(ersion)f(2.3.)0 676 y FD(shutdown)p FJ(\(\))208 775 y FN(Close)h(connection)e(established)i(in)h FJ(open)p FN(.)j(Y)-9 b(ou)20 b(may)g(o)o(v)o(erride)d(this)k(method.)0 922 y FD(socket)p FJ(\(\))208 1022 y FN(Returns)f(sock)o(et)g(instance) f(used)h(to)h(connect)e(to)h(serv)o(er)-5 b(.)0 1169 y FD(sort)p FJ(\()p FK(sort)p 384 1169 25 4 v 29 w(criteria,)21 b(c)o(har)o(set,)f(sear)m(c)o(h)p 1206 1169 V 28 w(criterion)p FC([)p FK(,)g(...)12 b FC(])p FJ(\))208 1268 y FN(The)24 b FJ(sort)h FN(command)e(is)j(a)g(v)n(ariant)e(of)h FJ(search)f FN(with)h(sorting)g(semantics)g(for)f(the)h(results.)40 b(Returned)24 b(data)h(contains)f(a)208 1368 y(space)c(separated)f (list)i(of)f(matching)f(message)h(numbers.)208 1494 y(Sort)26 b(has)h(tw)o(o)g(ar)o(guments)e(before)g(the)i FK(sear)m(c)o(h)p 1625 1494 V 29 w(criterion)g FN(ar)o(gument\(s\);)g(a)g(parenthesized)e (list)j(of)f FK(sort)p 3328 1494 V 30 w(criteria)p FN(,)h(and)f(the)208 1594 y(searching)17 b FK(c)o(har)o(set)q FN(.)25 b(Note)20 b(that)f(unlik)o(e)f FJ(search)p FN(,)h(the)g(searching)f FK(c)o(har)o(set)i FN(ar)o(gument)d(is)j(mandatory)-5 b(.)22 b(There)c(is)j(also)e(a)h FJ(uid)208 1693 y(sort)h FN(command)f(which)h(corresponds)f(to)i FJ(sort)g FN(the)g(w)o(ay)g (that)g FJ(uid)49 b(search)21 b FN(corresponds)f(to)i FJ(search)p FN(.)29 b(The)22 b FJ(sort)208 1793 y FN(command)30 b(\002rst)j(searches)f(the)g(mailbox)f(for)g(messages)h(that)h(match)e (the)h(gi)n(v)o(en)f(searching)g(criteria)h(using)g(the)g(charset)208 1893 y(ar)o(gument)27 b(for)j(the)g(interpretation)e(of)h(strings)h(in) h(the)f(searching)e(criteria.)55 b(It)30 b(then)f(returns)h(the)g (numbers)e(of)i(matching)208 1992 y(messages.)208 2118 y(This)20 b(is)h(an)f(`)p FJ(IMAP4rev1)p FN(')f(e)o(xtension)f (command.)0 2265 y FD(status)p FJ(\()p FK(mailbox,)g(names)p FJ(\))208 2365 y FN(Request)i(named)f(status)i(conditions)d(for)i FK(mailbox)p FN(.)0 2512 y FD(store)p FJ(\()p FK(messa)o(g)o(e)p 585 2512 V 28 w(set,)h(command,)d(\003a)o(g)p 1236 2512 V 29 w(list)q FJ(\))208 2611 y FN(Alters)k(\003ag)g(dispositions)g(for) f(messages)i(in)f(mailbox.)29 b FK(command)23 b FN(is)g(speci\002ed)f (by)g(section)g(6.4.6)e(of)i(RFC)i(2060)d(as)i(being)208 2711 y(one)c(of)h(\224FLA)m(GS\224,)g(\224+FLA)m(GS\224,)g(or)g (\224-FLA)m(GS\224,)f(optionally)g(with)h(a)g(suf)n(\002x)g(of)g (\224.SILENT\224.)208 2837 y(F)o(or)f(e)o(xample,)g(to)h(set)h(the)f (delete)g(\003ag)h(on)f(all)g(messages:)444 3055 y FA(typ,)44 b(data)g(=)h(M.search\(None,)d('ALL'\))444 3146 y(for)i(num)g(in)h (data[0].split\(\):)578 3237 y(M.store\(num,)e('+FLAGS',)g ('\\\\Deleted'\))444 3329 y(M.expunge\(\))0 3532 y FD(subscribe)p FJ(\()p FK(mailbox)p FJ(\))208 3632 y FN(Subscribe)19 b(to)h(ne)n(w)g(mailbox.)0 3779 y FD(thread)p FJ(\()p FK(thr)m(eading)p 677 3779 V 26 w(algorithm,)f(c)o(har)o(set,)h(sear)m (c)o(h)p 1574 3779 V 29 w(criterion)p FC([)p FK(,)g(...)12 b FC(])p FJ(\))208 3878 y FN(The)17 b FJ(thread)h FN(command)e(is)j(a)f (v)n(ariant)f(of)h FJ(search)g FN(with)g(threading)e(semantics)i(for)g (the)g(results.)24 b(Returned)17 b(data)h(contains)208 3978 y(a)i(space)g(separated)g(list)h(of)f(thread)f(members.)208 4104 y(Thread)i(members)h(consist)h(of)g(zero)f(or)g(more)h(messages)g (numbers,)e(delimited)h(by)h(spaces,)g(indicating)f(successi)n(v)o(e)h (parent)208 4204 y(and)c(child.)208 4330 y(Thread)25 b(has)i(tw)o(o)f(ar)o(guments)f(before)g(the)i FK(sear)m(c)o(h)p 1721 4330 V 29 w(criterion)f FN(ar)o(gument\(s\);)i(a)f FK(thr)m(eading)p 2907 4330 V 27 w(algorithm)p FN(,)g(and)f(the)h (searching)208 4430 y FK(c)o(har)o(set)q FN(.)d(Note)19 b(that)f(unlik)o(e)g FJ(search)p FN(,)g(the)g(searching)f FK(c)o(har)o(set)j FN(ar)o(gument)c(is)j(mandatory)-5 b(.)22 b(There)17 b(is)i(also)g(a)g FJ(uid)49 b(thread)208 4529 y FN(command)21 b(which)i(corresponds)e(to)i FJ(thread)g FN(the)h(w)o(ay)f(that)g FJ(uid)50 b(search)23 b FN(corresponds)e(to)i FJ(search)p FN(.)34 b(The)23 b FJ(thread)208 4629 y FN(command)30 b(\002rst)j(searches)f(the)g(mailbox)f(for)g(messages)h(that)h(match)e (the)h(gi)n(v)o(en)f(searching)g(criteria)h(using)g(the)g(charset)208 4728 y(ar)o(gument)13 b(for)i(the)h(interpretation)e(of)h(strings)h(in) g(the)g(searching)e(criteria.)24 b(It)16 b(then)f(returns)g(the)h (matching)e(messages)i(threaded)208 4828 y(according)i(to)i(the)g (speci\002ed)g(threading)e(algorithm.)208 4954 y(This)i(is)h(an)f(`)p FJ(IMAP4rev1)p FN(')f(e)o(xtension)f(command.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 5101 y FD(uid)p FJ(\()p FK(command,)f(ar)m (g)p FC([)p FK(,)h(...)12 b FC(])p FJ(\))208 5201 y FN(Ex)o(ecute)18 b(command)f(ar)o(gs)h(with)i(messages)f(identi\002ed)g(by)f(UID,)h (rather)g(than)g(message)g(number)-5 b(.)23 b(Returns)c(response)f (appro-)208 5300 y(priate)g(to)i(command.)i(At)e(least)g(one)e(ar)o (gument)f(must)i(be)h(supplied;)e(if)h(none)g(are)g(pro)o(vided,)d(the) j(serv)o(er)g(will)h(return)e(an)h(error)208 5400 y(and)g(an)h(e)o (xception)f(will)i(be)f(raised.)p 0 5549 3901 4 v 0 5649 a FI(646)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 647 659 TeXDict begin 647 658 bop 0 83 a FD(unsubscribe)p FJ(\()p FK(mailbox)p FJ(\))208 183 y FN(Unsubscribe)18 b(from)h(old)h(mailbox.) 0 330 y FD(xatom)p FJ(\()p FK(name)p FC([)p FK(,)e(ar)m(g)p FC([)p FK(,)i(...)12 b FC(])g(])p FJ(\))208 429 y FN(Allo)n(w)20 b(simple)g(e)o(xtension)f(commands)f(noti\002ed)i(by)f(serv)o(er)h(in)g (`)p FJ(CAPABILITY)p FN(')e(response.)0 576 y(Instances)i(of)g FJ(IMAP4_SSL)f FN(ha)n(v)o(e)g(just)i(one)f(additional)e(method:)0 723 y FD(ssl)p FJ(\(\))208 823 y FN(Returns)i(SSLObject)g(instance)g (used)f(for)h(the)g(secure)g(connection)e(with)i(the)h(serv)o(er)-5 b(.)0 969 y(The)20 b(follo)n(wing)e(attrib)n(utes)j(are)f(de\002ned)f (on)h(instances)g(of)g FJ(IMAP4)p FN(:)0 1116 y FD(PROTOCOL_VERSION)208 1216 y FN(The)f(most)i(recent)e(supported)f(protocol)h(in)h(the)g(`)p FJ(CAPABILITY)p FN(')f(response)g(from)g(the)h(serv)o(er)-5 b(.)0 1363 y FD(debug)208 1462 y FN(Inte)o(ger)15 b(v)n(alue)i(to)g (control)f(deb)n(ugging)f(output.)23 b(The)17 b(initialize)g(v)n(alue)g (is)h(tak)o(en)f(from)f(the)h(module)f(v)n(ariable)g FJ(Debug)p FN(.)24 b(V)-9 b(alues)208 1562 y(greater)19 b(than)g(three)h(trace)g(each)g(command.)0 1847 y Fv(18.11.2)101 b(IMAP4)29 b(Example)0 2050 y FN(Here)20 b(is)h(a)g(minimal)e(e)o (xample)g(\(without)g(error)g(checking\))f(that)j(opens)e(a)i(mailbox)e (and)g(retrie)n(v)o(es)h(and)f(prints)h(all)h(messages:)236 2288 y FA(import)44 b(getpass,)g(imaplib)236 2471 y(M)h(=)g (imaplib.IMAP4\(\))236 2562 y(M.login\(getpass.getuser\(\),)c (getpass.getpass\(\)\))236 2653 y(M.select\(\))236 2745 y(typ,)j(data)h(=)f(M.search\(None,)f('ALL'\))236 2836 y(for)i(num)f(in)g(data[0].split\(\):)416 2927 y(typ,)g(data)g(=)h (M.fetch\(num,)d('\(RFC822\)'\))416 3019 y(print)i('Message)f (\045s\\n\045s\\n')g(\045)i(\(num,)f(data[0][1]\))236 3110 y(M.close\(\))236 3201 y(M.logout\(\))0 3711 y FE(18.12)122 b Fx(nntplib)31 b FE(\227)i(NNTP)g(protocol)i(client)0 3944 y FN(This)d(module)f(de\002nes)h(the)g(class)h FJ(NNTP)f FN(which)g(implements)f(the)h(client)g(side)h(of)e(the)i(NNTP)f (protocol.)59 b(It)33 b(can)e(be)i(used)e(to)0 4044 y(implement)23 b(a)h(ne)n(ws)g(reader)f(or)h(poster)m(,)g(or)g(automated)e(ne)n(ws)i (processors.)36 b(F)o(or)23 b(more)h(information)d(on)j(NNTP)g(\(Netw)o (ork)f(Ne)n(ws)0 4143 y(T)m(ransfer)c(Protocol\),)g(see)h(Internet)f (RFC)j(977.)0 4290 y(Here)e(are)f(tw)o(o)h(small)g(e)o(xamples)f(of)h (ho)n(w)f(it)h(can)g(be)f(used.)25 b(T)-7 b(o)20 b(list)h(some)e (statistics)j(about)c(a)i(ne)n(wsgroup)e(and)h(print)g(the)h(subjects)g (of)0 4390 y(the)g(last)h(10)f(articles:)p 0 5549 3901 4 v 0 5649 a FI(18.12.)52 b FJ(nntplib)22 b FI(\227)h(NNTP)g(protocol)h (client)2241 b(647)p eop end %%Page: 648 660 TeXDict begin 648 659 bop 236 174 a FA(>>>)45 b(s)f(=)h (NNTP\('news.cwi.nl'\))236 266 y(>>>)g(resp,)f(count,)f(first,)h(last,) g(name)g(=)h(s.group\('comp.lang.python'\))236 357 y(>>>)g(print)f ('Group',)f(name,)h('has',)g(count,)g('articles,)f(range',)g(first,)h ('to',)g(last)236 448 y(Group)g(comp.lang.python)e(has)j(59)f (articles,)f(range)h(3742)h(to)f(3803)236 540 y(>>>)h(resp,)f(subs)g(=) g(s.xhdr\('subject',)e(first)i(+)h('-')f(+)h(last\))236 631 y(>>>)g(for)f(id,)g(sub)h(in)f(subs[-10:]:)f(print)h(id,)g(sub)236 722 y(...)236 814 y(3792)g(Re:)h(Removing)e(elements)h(from)g(a)h(list) f(while)g(iterating...)236 905 y(3793)g(Re:)h(Who)f(likes)g(Info)g (files?)236 996 y(3794)g(Emacs)g(and)h(doc)f(strings)236 1088 y(3795)g(a)h(few)f(questions)g(about)g(the)g(Mac)g(implementation) 236 1179 y(3796)g(Re:)h(executable)e(python)h(scripts)236 1270 y(3797)g(Re:)h(executable)e(python)h(scripts)236 1362 y(3798)g(Re:)h(a)f(few)h(questions)e(about)h(the)g(Mac)h (implementation)236 1453 y(3799)f(Re:)h(PROPOSAL:)e(A)i(Generic)e (Python)h(Object)g(Interface)f(for)i(Python)e(C)i(Modules)236 1544 y(3802)f(Re:)h(executable)e(python)h(scripts)236 1636 y(3803)g(Re:)h(\\POSIX{})e(wait)h(and)h(SIGCHLD)236 1727 y(>>>)g(s.quit\(\))236 1818 y('205)f(news.cwi.nl)f(closing)h (connection.)88 b(Goodbye.')0 2105 y FN(T)-7 b(o)20 b(post)h(an)f (article)g(from)f(a)i(\002le)f(\(this)h(assumes)f(that)h(the)f(article) g(has)g(v)n(alid)g(headers\):)236 2343 y FA(>>>)45 b(s)f(=)h (NNTP\('news.cwi.nl'\))236 2434 y(>>>)g(f)f(=)h(open\('/tmp/article'\)) 236 2526 y(>>>)g(s.post\(f\))236 2617 y('240)f(Article)g(posted)g (successfully.')236 2708 y(>>>)h(s.quit\(\))236 2800 y('205)f(news.cwi.nl)f(closing)h(connection.)88 b(Goodbye.')0 3086 y FN(The)20 b(module)f(itself)h(de\002nes)g(the)h(follo)n(wing)d (items:)0 3233 y FL(class)j FD(NNTP)p FJ(\()p FK(host)q FC([)p FK(,)e(port)j FC([)p FK(,)e(user)r FC([)p FK(,)g(passwor)m(d)i FC([)p FK(,)f(r)m(eadermode)12 b FC(])18 b([)p FK(,)j(usenetr)m(c)12 b FC(])g(])g(])g(])p FJ(\))208 3333 y FN(Return)23 b(a)g(ne)n(w)h (instance)f(of)g(the)g FJ(NNTP)h FN(class,)h(representing)c(a)j (connection)d(to)j(the)f(NNTP)h(serv)o(er)f(running)e(on)i(host)g FK(host)q FN(,)208 3432 y(listening)i(at)i(port)f FK(port)q FN(.)44 b(The)26 b(def)o(ault)f FK(port)j FN(is)g(119.)42 b(If)26 b(the)h(optional)e FK(user)j FN(and)e FK(passwor)m(d)j FN(are)d(pro)o(vided,)f(or)h(if)h(suitable)208 3532 y(credentials)21 b(are)i(present)f(in)h(`)g FO(/.netrc)p FN(')e(and)h(the)h(optional)e (\003ag)i FK(usenetr)m(c)f FN(is)i(true)e(\(the)h(def)o(ault\),)e(the)i (`)p FJ(AUTHINFO)48 b(USER)p FN(')208 3631 y(and)20 b(`)p FJ(AUTHINFO)48 b(PASS)p FN(')21 b(commands)f(are)i(used)f(to)g (identify)g(and)g(authenticate)f(the)h(user)h(to)f(the)h(serv)o(er)-5 b(.)28 b(If)21 b(the)h(optional)208 3731 y(\003ag)g FK(r)m(eadermode)e FN(is)j(true,)f(then)g(a)g(`)p FJ(mode)49 b(reader)p FN(')21 b(command)f(is)j(sent)f(before)f(authentication)f(is)j (performed.)28 b(Reader)208 3831 y(mode)21 b(is)i(sometimes)f (necessary)g(if)g(you)f(are)i(connecting)d(to)i(an)g(NNTP)h(serv)o(er)e (on)h(the)g(local)h(machine)e(and)g(intend)h(to)g(call)208 3930 y(reader)n(-speci\002c)27 b(commands,)i(such)g(as)h(`)p FJ(group)p FN('.)50 b(If)29 b(you)f(get)h(une)o(xpected)e FJ(NNTPPermanentError)p FN(s,)h(you)g(might)208 4030 y(need)19 b(to)h(set)h FK(r)m(eadermode)p FN(.)j FK(r)m(eadermode)19 b FN(def)o(aults)h(to)g FJ(None)p FN(.)25 b FK(usenetr)m(c)20 b FN(def)o(aults)f(to)i FJ(True)p FN(.)208 4163 y(Changed)d(in)j(v)o (ersion)e(2.4:)g FK(usenetr)m(c)h FN(ar)o(gument)e(added.)0 4310 y FL(exception)h FD(NNTPError)208 4409 y FN(Deri)n(v)o(ed)34 b(from)h(the)i(standard)e(e)o(xception)f FJ(Exception)p FN(,)39 b(this)d(is)h(the)g(base)f(class)h(for)f(all)g(e)o(xceptions)f (raised)h(by)g(the)208 4509 y FJ(nntplib)19 b FN(module.)0 4656 y FL(exception)g FD(NNTPReplyError)208 4755 y FN(Exception)d (raised)i(when)g(an)g(une)o(xpected)e(reply)i(is)h(recei)n(v)o(ed)e (from)g(the)h(serv)o(er)-5 b(.)24 b(F)o(or)18 b(backw)o(ards)f (compatibility)-5 b(,)17 b(the)h(e)o(xcep-)208 4855 y(tion)h FJ(error_reply)g FN(is)i(equi)n(v)n(alent)e(to)h(this)h(class.)0 5002 y FL(exception)e FD(NNTPTemporaryError)208 5101 y FN(Exception)f(raised)i(when)g(an)g(error)f(code)h(in)g(the)g(range)g (400\226499)d(is)k(recei)n(v)o(ed.)j(F)o(or)c(backw)o(ards)f (compatibility)-5 b(,)18 b(the)i(e)o(xcep-)208 5201 y(tion)f FJ(error_temp)g FN(is)j(equi)n(v)n(alent)c(to)i(this)h(class.)0 5348 y FL(exception)e FD(NNTPPermanentError)p 0 5549 3901 4 v 0 5649 a FI(648)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 649 661 TeXDict begin 649 660 bop 208 83 a FN(Exception)18 b(raised)i(when)g (an)g(error)f(code)h(in)g(the)g(range)g(500\226599)d(is)k(recei)n(v)o (ed.)j(F)o(or)c(backw)o(ards)f(compatibility)-5 b(,)18 b(the)i(e)o(xcep-)208 183 y(tion)f FJ(error_perm)g FN(is)j(equi)n(v)n (alent)c(to)i(this)h(class.)0 330 y FL(exception)e FD (NNTPProtocolError)208 429 y FN(Exception)g(raised)i(when)f(a)i(reply)e (is)i(recei)n(v)o(ed)d(from)h(the)h(serv)o(er)f(that)h(does)g(not)g(be) o(gin)f(with)h(a)g(digit)g(in)g(the)g(range)f(1\2265.)27 b(F)o(or)208 529 y(backw)o(ards)18 b(compatibility)-5 b(,)18 b(the)j(e)o(xception)d FJ(error_proto)h FN(is)i(equi)n(v)n (alent)d(to)j(this)f(class.)0 676 y FL(exception)f FD(NNTPDataError)208 775 y FN(Exception)26 b(raised)i(when)g(there)f(is)j(some)e(error)f(in) h(the)g(response)g(data.)48 b(F)o(or)28 b(backw)o(ards)f(compatibility) -5 b(,)28 b(the)g(e)o(xception)208 875 y FJ(error_data)18 b FN(is)k(equi)n(v)n(alent)c(to)i(this)h(class.)0 1160 y Fv(18.12.1)101 b(NNTP)28 b(Objects)0 1363 y FN(NNTP)17 b(instances)g(ha)n(v)o(e)f(the)h(follo)n(wing)e(methods.)23 b(The)16 b FK(r)m(esponse)h FN(that)g(is)g(returned)e(as)j(the)f (\002rst)g(item)g(in)g(the)g(return)f(tuple)g(of)h(almost)0 1462 y(all)25 b(methods)e(is)i(the)f(serv)o(er')-5 b(s)24 b(response:)32 b(a)24 b(string)g(be)o(ginning)e(with)i(a)g(three-digit) f(code.)36 b(If)24 b(the)g(serv)o(er')-5 b(s)24 b(response)f(indicates) h(an)0 1562 y(error)m(,)19 b(the)h(method)f(raises)h(one)g(of)g(the)g (abo)o(v)o(e)f(e)o(xceptions.)0 1709 y FD(getwelcome)p FJ(\(\))208 1808 y FN(Return)27 b(the)h(welcome)f(message)g(sent)h(by)f (the)h(serv)o(er)f(in)h(reply)f(to)h(the)f(initial)h(connection.)46 b(\(This)27 b(message)h(sometimes)208 1908 y(contains)19 b(disclaimers)h(or)g(help)g(information)d(that)k(may)e(be)h(rele)n(v)n (ant)f(to)i(the)f(user)-5 b(.\))0 2055 y FD(set_debuglevel)p FJ(\()p FK(le)o(vel)p FJ(\))208 2155 y FN(Set)31 b(the)g(instance')-5 b(s)31 b(deb)n(ugging)d(le)n(v)o(el.)57 b(This)31 b(controls)f(the)h (amount)f(of)g(deb)n(ugging)f(output)g(printed.)56 b(The)31 b(def)o(ault,)h FJ(0)p FN(,)208 2254 y(produces)26 b(no)h(deb)n(ugging) f(output.)47 b(A)29 b(v)n(alue)e(of)h FJ(1)g FN(produces)e(a)j (moderate)d(amount)h(of)h(deb)n(ugging)d(output,)k(generally)d(a)208 2354 y(single)19 b(line)h(per)f(request)g(or)g(response.)24 b(A)c(v)n(alue)f(of)g FJ(2)h FN(or)f(higher)f(produces)g(the)i(maximum) e(amount)g(of)h(deb)n(ugging)e(output,)208 2453 y(logging)h(each)i (line)g(sent)h(and)e(recei)n(v)o(ed)g(on)h(the)g(connection)e (\(including)g(message)i(te)o(xt\).)0 2600 y FD(newgroups)p FJ(\()p FK(date)o(,)e(time)o(,)i FC([)p FK(\002le)12 b FC(])p FJ(\))208 2700 y FN(Send)22 b(a)h(`)p FJ(NEWGROUPS)p FN(')e(command.)31 b(The)22 b FK(date)h FN(ar)o(gument)d(should)i(be)h (a)g(string)f(of)h(the)g(form)e FJ(')p FK(yymmdd)r FJ(')h FN(indicating)g(the)208 2800 y(date,)c(and)g FK(time)i FN(should)d(be)i(a)g(string)f(of)h(the)f(form)g FJ(')p FK(hhmmss)p FJ(')g FN(indicating)g(the)g(time.)25 b(Return)18 b(a)h(pair)g FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(gr)l(oups)p FJ(\))208 2899 y FN(where)16 b FK(gr)l(oups)h FN(is)i(a)f(list)g(of)g (group)d(names)j(that)f(are)h(ne)n(w)f(since)h(the)f(gi)n(v)o(en)f (date)i(and)f(time.)24 b(If)17 b(the)h FK(\002le)f FN(parameter)f(is)j (supplied,)208 2999 y(then)h(the)g(output)f(of)h(the)h(`)p FJ(NEWGROUPS)p FN(')d(command)h(is)i(stored)f(in)h(a)g(\002le.)26 b(If)20 b FK(\002le)h FN(is)g(a)g(string,)f(then)g(the)g(method)g(will) h(open)e(a)208 3098 y(\002le)h(object)g(with)h(that)f(name,)f(write)i (to)f(it)h(then)f(close)h(it.)k(If)20 b FK(\002le)h FN(is)g(a)g(\002le) g(object,)e(then)h(it)h(will)g(start)g(calling)e FJ(write\(\))h FN(on)g(it)208 3198 y(to)g(store)g(the)g(lines)h(of)f(the)g(command)e (output.)24 b(If)c FK(\002le)g FN(is)h(supplied,)e(then)h(the)g (returned)e FK(list)23 b FN(is)e(an)f(empty)g(list.)0 3345 y FD(newnews)p FJ(\()p FK(gr)l(oup,)e(date)o(,)h(time)o(,)i FC([)p FK(\002le)12 b FC(])p FJ(\))208 3445 y FN(Send)20 b(a)i(`)p FJ(NEWNEWS)p FN(')d(command.)26 b(Here,)21 b FK(gr)l(oup)f FN(is)i(a)g(group)d(name)h(or)h FJ(')2369 3460 y(*)2419 3445 y(')p FN(,)g(and)g FK(date)f FN(and)h FK(time)g FN(ha)n(v)o(e)g(the)g(same)g(meaning)208 3544 y(as)k(for)f FJ(newgroups\(\))p FN(.)36 b(Return)24 b(a)h(pair)f FJ(\()p FK(r)m(esponse)p FJ(,)49 b FK(articles)p FJ(\))25 b FN(where)f FK(articles)h FN(is)g(a)g(list)h(of)e(message)g(ids.)39 b(If)24 b(the)h FK(\002le)208 3644 y FN(parameter)19 b(is)j(supplied,)d(then)h(the)h(output)f(of)g(the)h(`)p FJ(NEWNEWS)p FN(')e(command)g(is)j(stored)e(in)h(a)g(\002le.)28 b(If)20 b FK(\002le)h FN(is)h(a)f(string,)f(then)h(the)208 3743 y(method)i(will)j(open)e(a)i(\002le)f(object)g(with)g(that)g (name,)h(write)f(to)g(it)h(then)f(close)g(it.)40 b(If)25 b FK(\002le)g FN(is)h(a)g(\002le)f(object,)h(then)e(it)i(will)g(start) 208 3843 y(calling)c FJ(write\(\))g FN(on)g(it)i(to)f(store)g(the)f (lines)i(of)e(the)h(command)e(output.)31 b(If)23 b FK(\002le)g FN(is)g(supplied,)f(then)h(the)g(returned)e FK(list)k FN(is)f(an)208 3943 y(empty)19 b(list.)0 4090 y FD(list)p FJ(\()p FC([)p FK(\002le)12 b FC(])p FJ(\))208 4189 y FN(Send)19 b(a)i(`)p FJ(LIST)p FN(')f(command.)j(Return)d(a)h(pair)f FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(list)q FJ(\))22 b FN(where)d FK(list)k FN(is)f(a)e(list)i(of)e(tuples.)25 b(Each)20 b(tuple)g(has)g(the)h(form)208 4289 y FJ(\()p FK(gr)l(oup)p FJ(,)48 b FK(last)q FJ(,)i FK(\002r)o(st)q FJ(,)g FK(\003a)o(g)p FJ(\))p FN(,)23 b(where)g FK(gr)l(oup)g FN(is)i(a)f(group)d(name,)j FK(last)i FN(and)d FK(\002r)o(st)j FN(are)d(the)h(last)g(and)f(\002rst)h(article)g(numbers)208 4388 y(\(as)19 b(strings\),)g(and)f FK(\003a)o(g)g FN(is)i FJ('y')f FN(if)h(posting)e(is)i(allo)n(wed,)e FJ('n')h FN(if)g(not,)g(and)f FJ('m')h FN(if)h(the)f(ne)n(wsgroup)d(is)k (moderated.)j(\(Note)c(the)208 4488 y(ordering:)k FK(last)q FN(,)e FK(\002r)o(st)q FN(.\))26 b(If)20 b(the)g FK(\002le)g FN(parameter)e(is)k(supplied,)c(then)i(the)g(output)f(of)h(the)g(`)p FJ(LIST)p FN(')f(command)g(is)i(stored)e(in)i(a)f(\002le.)208 4588 y(If)i FK(\002le)h FN(is)g(a)g(string,)g(then)f(the)h(method)e (will)i(open)f(a)h(\002le)g(object)f(with)h(that)g(name,)f(write)h(to)g (it)g(then)f(close)h(it.)33 b(If)23 b FK(\002le)f FN(is)i(a)f(\002le) 208 4687 y(object,)c(then)g(it)h(will)h(start)f(calling)f FJ(write\(\))g FN(on)g(it)i(to)f(store)f(the)h(lines)g(of)g(the)f (command)f(output.)24 b(If)19 b FK(\002le)h FN(is)h(supplied,)d(then) 208 4787 y(the)i(returned)e FK(list)23 b FN(is)e(an)f(empty)f(list.)0 4934 y FD(descriptions)p FJ(\()p FK(gr)l(ouppattern)p FJ(\))208 5033 y FN(Send)f(a)h(`)p FJ(LIST)48 b(NEWSGROUPS)p FN(')17 b(command,)g(where)h FK(gr)l(ouppattern)e FN(is)j(a)g(wildmat)g (string)f(as)h(speci\002ed)f(in)h(RFC2980)f(\(it')-5 b(s)208 5133 y(essentially)24 b(the)g(same)h(as)g(DOS)f(or)g(UNIX)h (shell)f(wildcard)g(strings\).)36 b(Return)24 b(a)h(pair)f FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(list)q FJ(\))p FN(,)26 b(where)e FK(list)j FN(is)e(a)208 5233 y(list)c(of)f(tuples)g (containing)e FJ(\()p FK(name)p FJ(,)48 b FK(title)p FJ(\))p FN(.)208 5366 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)p 0 5549 3901 4 v 0 5649 a FI(18.12.)52 b FJ(nntplib)22 b FI(\227)h(NNTP)g(protocol)h(client)2241 b(649)p eop end %%Page: 650 662 TeXDict begin 650 661 bop 0 83 a FD(description)p FJ(\()p FK(gr)l(oup)p FJ(\))208 183 y FN(Get)20 b(a)h(description)d(for)i(a)g (single)g(group)e FK(gr)l(oup)p FN(.)24 b(If)c(more)f(than)h(one)g (group)e(matches)i(\(if)g('group')d(is)k(a)g(real)f(wildmat)f (string\),)208 282 y(return)g(the)h(\002rst)h(match.)j(If)c(no)g(group) e(matches,)i(return)f(an)h(empty)f(string.)208 415 y(This)h(elides)g (the)h(response)e(code)g(from)g(the)i(serv)o(er)-5 b(.)24 b(If)c(the)g(response)g(code)f(is)i(needed,)e(use)h FJ (descriptions\(\))p FN(.)208 548 y(Ne)n(w)g(in)g(v)o(ersion)f(2.4.)0 695 y FD(group)p FJ(\()p FK(name)p FJ(\))208 794 y FN(Send)24 b(a)h(`)p FJ(GROUP)p FN(')f(command,)g(where)g FK(name)h FN(is)g(the)g(group)e(name.)39 b(Return)24 b(a)i(tuple)e FJ(\()p FK(r)m(esponse)p FJ(,)49 b FK(count)q FJ(,)f FK(\002r)o(st)q FJ(,)j FK(last)q FJ(,)208 894 y FK(name)p FJ(\))27 b FN(where)h FK(count)i FN(is)f(the)g(\(estimated\))f(number)f (of)h(articles)h(in)g(the)g(group,)f FK(\002r)o(st)j FN(is)f(the)f(\002rst)g(article)g(number)e(in)i(the)208 994 y(group,)24 b FK(last)j FN(is)f(the)f(last)h(article)f(number)e(in) j(the)f(group,)f(and)g FK(name)h FN(is)h(the)f(group)e(name.)39 b(The)25 b(numbers)f(are)h(returned)e(as)208 1093 y(strings.)0 1240 y FD(help)p FJ(\()p FC([)p FK(\002le)12 b FC(])p FJ(\))208 1340 y FN(Send)17 b(a)h(`)p FJ(HELP)p FN(')e(command.)22 b(Return)17 b(a)h(pair)f FJ(\()p FK(r)m(esponse)p FJ(,)49 b FK(list)q FJ(\))19 b FN(where)e FK(list)j FN(is)e(a)g(list)h(of)e (help)g(strings.)24 b(If)17 b(the)h FK(\002le)f FN(parameter)208 1439 y(is)25 b(supplied,)e(then)h(the)g(output)f(of)h(the)g(`)p FJ(HELP)p FN(')f(command)f(is)j(stored)f(in)g(a)h(\002le.)37 b(If)24 b FK(\002le)g FN(is)h(a)g(string,)f(then)g(the)g(method)f(will) 208 1539 y(open)16 b(a)h(\002le)h(object)f(with)h(that)f(name,)g(write) g(to)h(it)g(then)f(close)g(it.)25 b(If)17 b FK(\002le)g FN(is)h(a)g(\002le)g(object,)f(then)g(it)h(will)g(start)f(calling)g FJ(write\(\))208 1639 y FN(on)i(it)i(to)g(store)f(the)g(lines)h(of)e (the)i(command)d(output.)24 b(If)c FK(\002le)g FN(is)h(supplied,)e (then)h(the)g(returned)e FK(list)23 b FN(is)e(an)f(empty)f(list.)0 1786 y FD(stat)p FJ(\()p FK(id)r FJ(\))208 1885 y FN(Send)e(a)i(`)p FJ(STAT)p FN(')e(command,)g(where)g FK(id)k FN(is)e(the)f(message)g(id) g(\(enclosed)f(in)i(`)p FJ(<)p FN(')f(and)f(`)p FJ(>)p FN('\))h(or)g(an)g(article)g(number)e(\(as)j(a)f(string\).)208 1985 y(Return)e(a)g(triple)h FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(number)r FJ(,)g FK(id)r FJ(\))17 b FN(where)f FK(number)i FN(is)f(the)f(article)h(number)e(\(as)h(a)h(string\))f(and) g FK(id)j FN(is)e(the)g(message)208 2084 y(id)j(\(enclosed)f(in)h(`)p FJ(<)p FN(')g(and)g(`)p FJ(>)p FN('\).)0 2231 y FD(next)p FJ(\(\))208 2331 y FN(Send)f(a)i(`)p FJ(NEXT)p FN(')e(command.)k (Return)d(as)h(for)e FJ(stat\(\))p FN(.)0 2478 y FD(last)p FJ(\(\))208 2577 y FN(Send)g(a)i(`)p FJ(LAST)p FN(')e(command.)k (Return)d(as)h(for)e FJ(stat\(\))p FN(.)0 2724 y FD(head)p FJ(\()p FK(id)r FJ(\))208 2824 y FN(Send)24 b(a)h(`)p FJ(HEAD)p FN(')f(command,)g(where)g FK(id)j FN(has)f(the)e(same)h (meaning)f(as)h(for)f FJ(stat\(\))p FN(.)39 b(Return)24 b(a)h(tuple)g FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(num-)208 2924 y(ber)r FJ(,)h FK(id)r FJ(,)g FK(list)q FJ(\))26 b FN(where)d(the)h(\002rst)h(three)e(are)h(the)g(same)h(as)f(for)g FJ(stat\(\))p FN(,)g(and)f FK(list)k FN(is)e(a)f(list)i(of)d(the)h (article')-5 b(s)25 b(headers)e(\(an)208 3023 y(uninterpreted)17 b(list)k(of)f(lines,)h(without)e(trailing)h(ne)n(wlines\).)0 3170 y FD(body)p FJ(\()p FK(id,)p FC([)p FK(\002le)12 b FC(])p FJ(\))208 3270 y FN(Send)18 b(a)h(`)p FJ(BODY)p FN(')f(command,)e(where)j FK(id)i FN(has)e(the)f(same)h(meaning)e(as)j (for)e FJ(stat\(\))p FN(.)24 b(If)18 b(the)h FK(\002le)g FN(parameter)e(is)i(supplied,)f(then)208 3369 y(the)k(body)g(is)i (stored)e(in)h(a)g(\002le.)33 b(If)23 b FK(\002le)g FN(is)h(a)f (string,)g(then)f(the)h(method)e(will)j(open)e(a)h(\002le)g(object)f (with)h(that)g(name,)g(write)g(to)g(it)208 3469 y(then)c(close)h(it.)26 b(If)20 b FK(\002le)g FN(is)h(a)g(\002le)f(object,)g(then)f(it)i(will)g (start)g(calling)e FJ(write\(\))h FN(on)f(it)i(to)f(store)g(the)h (lines)f(of)g(the)g(body)-5 b(.)23 b(Return)208 3569 y(as)d(for)g FJ(head\(\))p FN(.)k(If)c FK(\002le)h FN(is)g(supplied,)e (then)g(the)i(returned)d FK(list)23 b FN(is)e(an)f(empty)f(list.)0 3715 y FD(article)p FJ(\()p FK(id)r FJ(\))208 3815 y FN(Send)g(an)h(`)p FJ(ARTICLE)p FN(')f(command,)f(where)i FK(id)i FN(has)f(the)f(same)g(meaning)f(as)i(for)e FJ(stat\(\))p FN(.)25 b(Return)20 b(as)g(for)g FJ(head\(\))p FN(.)0 3962 y FD(slave)p FJ(\(\))208 4062 y FN(Send)f(a)i(`)p FJ(SLAVE)p FN(')e(command.)k(Return)d(the)g(serv)o(er')-5 b(s)20 b FK(r)m(esponse)p FN(.)0 4208 y FD(xhdr)p FJ(\()p FK(header)-9 b(,)18 b(string)o(,)i FC([)p FK(\002le)12 b FC(])p FJ(\))208 4308 y FN(Send)23 b(an)g(`)p FJ(XHDR)p FN(')g(command.)33 b(This)23 b(command)f(is)i(not)g(de\002ned)e(in)i (the)f(RFC)i(b)n(ut)f(is)g(a)g(common)e(e)o(xtension.)33 b(The)23 b FK(header)208 4408 y FN(ar)o(gument)15 b(is)k(a)g(header)e (k)o(e)o(yw)o(ord,)f(e.g.)24 b FJ('subject')p FN(.)f(The)18 b FK(string)g FN(ar)o(gument)e(should)h(ha)n(v)o(e)h(the)g(form)f FJ(')p FK(\002r)o(st)q FJ(-)p FK(last)q FJ(')i FN(where)208 4507 y FK(\002r)o(st)24 b FN(and)d FK(last)j FN(are)e(the)g(\002rst)g (and)f(last)i(article)f(numbers)e(to)i(search.)30 b(Return)21 b(a)h(pair)g FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(list)q FJ(\))p FN(,)24 b(where)d FK(list)j FN(is)f(a)f(list)208 4607 y(of)h(pairs)h FJ(\()p FK(id)r FJ(,)49 b FK(te)n(xt)q FJ(\))p FN(,)26 b(where)d FK(id)j FN(is)f(an)f(article)g(number)e(\(as) i(a)g(string\))g(and)f FK(te)n(xt)j FN(is)f(the)f(te)o(xt)f(of)h(the)g (requested)f(header)f(for)208 4707 y(that)c(article.)24 b(If)18 b(the)h FK(\002le)f FN(parameter)f(is)i(supplied,)f(then)f(the) i(output)e(of)h(the)g(`)p FJ(XHDR)p FN(')g(command)e(is)j(stored)f(in)h (a)f(\002le.)25 b(If)19 b FK(\002le)f FN(is)h(a)208 4806 y(string,)g(then)g(the)h(method)f(will)h(open)f(a)i(\002le)f(object)g (with)g(that)g(name,)f(write)h(to)g(it)g(then)g(close)g(it.)25 b(If)20 b FK(\002le)g FN(is)h(a)f(\002le)h(object,)e(then)208 4906 y(it)g(will)h(start)g(calling)f FJ(write\(\))f FN(on)h(it)h(to)f (store)g(the)g(lines)h(of)f(the)g(command)e(output.)23 b(If)c FK(\002le)g FN(is)i(supplied,)d(then)g(the)h(returned)208 5005 y FK(list)j FN(is)f(an)g(empty)e(list.)0 5152 y FD(post)p FJ(\()p FK(\002le)p FJ(\))208 5252 y FN(Post)26 b(an)g(article)g(using)g(the)g(`)p FJ(POST)p FN(')f(command.)41 b(The)25 b FK(\002le)h FN(ar)o(gument)e(is)j(an)f(open)f(\002le)i (object)e(which)h(is)h(read)e(until)h(EOF)208 5352 y(using)c(its)i FJ(readline\(\))e FN(method.)32 b(It)23 b(should)f(be)h(a)h (well-formed)d(ne)n(ws)i(article,)h(including)d(the)i(required)e (headers.)33 b(The)p 0 5549 3901 4 v 0 5649 a FI(650)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 651 663 TeXDict begin 651 662 bop 208 83 a FJ(post\(\))19 b FN(method)g (automatically)g(escapes)h(lines)h(be)o(ginning)c(with)k(`)p FJ(.)p FN('.)0 230 y FD(ihave)p FJ(\()p FK(id,)e(\002le)p FJ(\))208 330 y FN(Send)j(an)h(`)p FJ(IHAVE)p FN(')f(command.)31 b FK(id)26 b FN(is)d(a)h(message)f(id)g(\(enclosed)e(in)j(`)p FJ(<)p FN(')e(and)h(`)p FJ(>)p FN('\).)32 b(If)23 b(the)g(response)f (is)i(not)f(an)f(error)m(,)g(treat)208 429 y FK(\002le)e FN(e)o(xactly)f(as)i(for)f(the)g FJ(post\(\))f FN(method.)0 576 y FD(date)p FJ(\(\))208 676 y FN(Return)35 b(a)g(triple)h FJ(\()p FK(r)m(esponse)p FJ(,)48 b FK(date)p FJ(,)h FK(time)p FJ(\))p FN(,)39 b(containing)34 b(the)h(current)f(date)i(and)f(time)g (in)h(a)g(form)e(suitable)i(for)f(the)208 775 y FJ(newnews\(\))18 b FN(and)h FJ(newgroups\(\))f FN(methods.)24 b(This)c(is)g(an)g (optional)e(NNTP)i(e)o(xtension,)e(and)h(may)g(not)h(be)f(supported)f (by)208 875 y(all)i(serv)o(ers.)0 1022 y FD(xgtitle)p FJ(\()p FK(name)o(,)e FC([)p FK(\002le)12 b FC(])p FJ(\))208 1121 y FN(Process)26 b(an)g(`)p FJ(XGTITLE)p FN(')f(command,)g (returning)g(a)h(pair)g FJ(\()p FK(r)m(esponse)p FJ(,)49 b FK(list)q FJ(\))p FN(,)29 b(where)c FK(list)k FN(is)e(a)g(list)g(of)f (tuples)g(containing)208 1221 y FJ(\()p FK(name)p FJ(,)48 b FK(title)p FJ(\))p FN(.)25 b(If)20 b(the)f FK(\002le)h FN(parameter)e(is)j(supplied,)e(then)g(the)h(output)e(of)i(the)f(`)p FJ(XGTITLE)p FN(')g(command)e(is)k(stored)e(in)h(a)g(\002le.)208 1321 y(If)i FK(\002le)h FN(is)g(a)g(string,)g(then)f(the)h(method)e (will)i(open)f(a)h(\002le)g(object)f(with)h(that)g(name,)f(write)h(to)g (it)g(then)f(close)h(it.)33 b(If)23 b FK(\002le)f FN(is)i(a)f(\002le) 208 1420 y(object,)c(then)g(it)h(will)h(start)f(calling)f FJ(write\(\))g FN(on)g(it)i(to)f(store)f(the)h(lines)g(of)g(the)f (command)f(output.)24 b(If)19 b FK(\002le)h FN(is)h(supplied,)d(then) 208 1520 y(the)i(returned)e FK(list)23 b FN(is)e(an)f(empty)f(list.)27 b(This)20 b(is)h(an)f(optional)f(NNTP)i(e)o(xtension,)d(and)i(may)f (not)h(be)g(supported)f(by)g(all)i(serv)o(ers.)208 1653 y(RFC2980)59 b(says)g(\223It)h(is)g(suggested)f(that)g(this)h(e)o (xtension)e(be)i(deprecated\224.)140 b(Use)60 b FJ(descriptions\(\))e FN(or)208 1752 y FJ(description\(\))18 b FN(instead.)0 1899 y FD(xover)p FJ(\()p FK(start,)i(end,)f FC([)p FK(\002le)12 b FC(])p FJ(\))208 1999 y FN(Return)24 b(a)i(pair)e FJ(\()p FK(r)m(esp)p FJ(,)50 b FK(list)q FJ(\))p FN(.)41 b FK(list)27 b FN(is)f(a)g(list)g(of)f(tuples,)h(one)e(for)h(each)f(article)h(in)h (the)f(range)f(delimited)g(by)h(the)g FK(start)i FN(and)208 2098 y FK(end)f FN(article)f(numbers.)38 b(Each)25 b(tuple)g(is)h(of)f (the)g(form)f FJ(\()p FK(article)h(number)r FJ(,)48 b FK(subject)q FJ(,)h FK(poster)r FJ(,)h FK(date)p FJ(,)e FK(id)r FJ(,)i FK(r)m(efer)m(ences)p FJ(,)208 2198 y FK(size)p FJ(,)g FK(lines)p FJ(\))p FN(.)24 b(If)18 b(the)h FK(\002le)f FN(parameter)f(is)i(supplied,)f(then)g(the)g(output)f(of)h (the)g(`)p FJ(XOVER)p FN(')g(command)e(is)j(stored)f(in)h(a)f(\002le.) 25 b(If)19 b FK(\002le)208 2298 y FN(is)j(a)f(string,)g(then)f(the)h (method)f(will)i(open)e(a)h(\002le)h(object)e(with)i(that)f(name,)f (write)h(to)h(it)f(then)g(close)g(it.)28 b(If)21 b FK(\002le)g FN(is)h(a)g(\002le)f(object,)208 2397 y(then)j(it)i(will)g(start)f (calling)g FJ(write\(\))f FN(on)h(it)g(to)h(store)f(the)g(lines)g(of)g (the)g(command)e(output.)38 b(If)25 b FK(\002le)g FN(is)h(supplied,)f (then)g(the)208 2497 y(returned)18 b FK(list)23 b FN(is)e(an)f(empty)f (list.)26 b(This)21 b(is)g(an)f(optional)f(NNTP)h(e)o(xtension,)f(and)g (may)h(not)g(be)g(supported)e(by)i(all)h(serv)o(ers.)0 2644 y FD(xpath)p FJ(\()p FK(id)r FJ(\))208 2743 y FN(Return)28 b(a)h(pair)g FJ(\()p FK(r)m(esp)p FJ(,)49 b FK(path)p FJ(\))p FN(,)30 b(where)e FK(path)g FN(is)i(the)f(directory)e(path)i (to)g(the)g(article)g(with)g(message)f(ID)h FK(id)r FN(.)52 b(This)29 b(is)h(an)208 2843 y(optional)18 b(NNTP)j(e)o(xtension,)d (and)i(may)g(not)g(be)g(supported)e(by)i(all)h(serv)o(ers.)0 2990 y FD(quit)p FJ(\(\))208 3090 y FN(Send)f(a)i(`)p FJ(QUIT)p FN(')e(command)f(and)h(close)h(the)g(connection.)k(Once)c (this)g(method)f(has)h(been)g(called,)f(no)h(other)f(methods)g(of)h (the)208 3189 y(NNTP)f(object)g(should)f(be)h(called.)0 3517 y FE(18.13)122 b Fx(smtplib)31 b FE(\227)i(SMTP)f(protocol)j (client)0 3749 y FN(The)23 b FJ(smtplib)g FN(module)f(de\002nes)h(an)h (SMTP)g(client)g(session)f(object)g(that)h(can)f(be)h(used)f(to)h(send) f(mail)h(to)g(an)o(y)e(Internet)h(machine)0 3849 y(with)k(an)f(SMTP)h (or)f(ESMTP)h(listener)f(daemon.)42 b(F)o(or)27 b(details)f(of)h(SMTP)f (and)g(ESMTP)h(operation,)f(consult)g(RFC)i(821)d(\()p FK(Simple)0 3949 y(Mail)c(T)-5 b(r)o(ansfer)21 b(Pr)l(otocol)p FN(\))e(and)g(RFC)j(1869)d(\()p FK(SMTP)h(Service)g(Extensions)p FN(\).)0 4096 y FL(class)h FD(SMTP)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)e(port)q FC([)p FK(,)h(local)p 1090 4096 25 4 v 29 w(hostname)12 b FC(])g(])g(])p FJ(\))208 4195 y FN(A)21 b FJ(SMTP)f FN(instance)g(encapsulates)g(an)g(SMTP)h (connection.)j(It)d(has)g(methods)e(that)i(support)e(a)i(full)f (repertoire)f(of)h(SMTP)h(and)208 4295 y(ESMTP)c(operations.)23 b(If)18 b(the)f(optional)g(host)h(and)f(port)g(parameters)g(are)g(gi)n (v)o(en,)g(the)h(SMTP)g FJ(connect\(\))f FN(method)f(is)j(called)208 4394 y(with)26 b(those)g(parameters)f(during)g(initialization.)43 b(An)26 b FJ(SMTPConnectError)e FN(is)j(raised)g(if)f(the)h (speci\002ed)f(host)g(doesn')o(t)208 4494 y(respond)18 b(correctly)-5 b(.)208 4627 y(F)o(or)22 b(normal)g(use,)i(you)e(should) g(only)g(require)f(the)i(initialization/connect,)e FJ(sendmail\(\))p FN(,)i(and)f FJ(quit\(\))g FN(methods.)33 b(An)208 4727 y(e)o(xample)18 b(is)j(included)e(belo)n(w)-5 b(.)0 4873 y(A)21 b(nice)f(selection)g(of)g(e)o(xceptions)e(is)j(de\002ned)e(as)i (well:)0 5020 y FL(exception)e FD(SMTPException)208 5120 y FN(Base)i(e)o(xception)d(class)j(for)f(all)g(e)o(xceptions)f(raised)h (by)g(this)h(module.)0 5267 y FL(exception)e FD(SMTPServerDisconnected) 208 5366 y FN(This)g(e)o(xception)e(is)i(raised)g(when)f(the)h(serv)o (er)f(une)o(xpectedly)e(disconnects,)i(or)g(when)h(an)f(attempt)h(is)h (made)e(to)h(use)g(the)g FJ(SMTP)p 0 5549 3901 4 v 0 5649 a FI(18.13.)52 b FJ(smtplib)22 b FI(\227)h(SMTP)h(protocol)f (client)2237 b(651)p eop end %%Page: 652 664 TeXDict begin 652 663 bop 208 83 a FN(instance)19 b(before)g (connecting)f(it)j(to)f(a)h(serv)o(er)-5 b(.)0 230 y FL(exception)19 b FD(SMTPResponseException)208 330 y FN(Base)f(class)g(for)f(all)h(e)o(xceptions)e(that)h(include)g(an)g (SMTP)h(error)e(code.)24 b(These)17 b(e)o(xceptions)f(are)h(generated)f (in)h(some)h(instances)208 429 y(when)h(the)h(SMTP)h(serv)o(er)f (returns)f(an)h(error)f(code.)25 b(The)20 b(error)f(code)g(is)j(stored) d(in)i(the)f FJ(smtp_code)f FN(attrib)n(ute)h(of)g(the)g(error)m(,)208 529 y(and)f(the)h FJ(smtp_error)f FN(attrib)n(ute)h(is)h(set)g(to)g (the)f(error)f(message.)0 676 y FL(exception)g FD(SMTPSenderRefused)208 775 y FN(Sender)25 b(address)h(refused.)44 b(In)26 b(addition)f(to)i (the)g(attrib)n(utes)f(set)i(by)e(on)g(all)h FJ(SMTPResponseException)c FN(e)o(xceptions,)208 875 y(this)d(sets)i(`sender')c(to)j(the)f(string) g(that)g(the)g(SMTP)h(serv)o(er)e(refused.)0 1022 y FL(exception)g FD(SMTPRecipientsRefused)208 1121 y FN(All)f(recipient)e(addresses)h (refused.)23 b(The)17 b(errors)g(for)g(each)g(recipient)f(are)i (accessible)f(through)f(the)h(attrib)n(ute)g FJ(recipients)p FN(,)208 1221 y(which)i(is)i(a)g(dictionary)d(of)i(e)o(xactly)g(the)g (same)g(sort)g(as)h FJ(SMTP.sendmail\(\))d FN(returns.)0 1368 y FL(exception)h FD(SMTPDataError)208 1468 y FN(The)g(SMTP)i(serv) o(er)e(refused)g(to)i(accept)f(the)g(message)g(data.)0 1614 y FL(exception)f FD(SMTPConnectError)208 1714 y FN(Error)f(occurred)h(during)f(establishment)i(of)f(a)i(connection)d (with)i(the)h(serv)o(er)-5 b(.)0 1861 y FL(exception)19 b FD(SMTPHeloError)208 1961 y FN(The)g(serv)o(er)h(refused)f(our)g(`)p FJ(HELO)p FN(')h(message.)0 2107 y FL(exception)f FD (SMTPAuthenticationError)208 2207 y FN(SMTP)i(authentication)e(went)h (wrong.)26 b(Most)21 b(probably)d(the)j(serv)o(er)f(didn')o(t)f(accept) i(the)g(username/passw)o(ord)d(combination)208 2307 y(pro)o(vided.)0 2454 y FL(See)j(Also:)0 2600 y FN(RFC)h(821,)d(\223)p FK(Simple)g(Mail)i(T)-5 b(r)o(ansfer)21 b(Pr)l(otocol)p FN(\224)208 2700 y(Protocol)j(de\002nition)h(for)g(SMTP)-9 b(.)26 b(This)g(document)e(co)o(v)o(ers)g(the)i(model,)g(operating)e (procedure,)h(and)g(protocol)f(details)i(for)208 2800 y(SMTP)-9 b(.)0 2946 y(RFC)22 b(1869,)c(\223)p FK(SMTP)i(Service)g (Extensions)p FN(\224)208 3046 y(De\002nition)29 b(of)h(the)h(ESMTP)f (e)o(xtensions)g(for)f(SMTP)-9 b(.)31 b(This)f(describes)g(a)h(frame)n (w)o(ork)d(for)i(e)o(xtending)e(SMTP)j(with)g(ne)n(w)208 3146 y(commands,)16 b(supporting)f(dynamic)i(disco)o(v)o(ery)e(of)j (the)g(commands)e(pro)o(vided)f(by)i(the)h(serv)o(er)m(,)f(and)g (de\002nes)h(a)g(fe)n(w)g(additional)208 3245 y(commands.)0 3530 y Fv(18.13.1)101 b(SMTP)28 b(Objects)0 3733 y FN(An)20 b FJ(SMTP)g FN(instance)g(has)g(the)h(follo)n(wing)d(methods:)0 3880 y FD(set_debuglevel)p FJ(\()p FK(le)o(vel)p FJ(\))208 3980 y FN(Set)j(the)f(deb)n(ug)f(output)g(le)n(v)o(el.)25 b(A)c(true)f(v)n(alue)g(for)g FK(le)o(vel)g FN(results)h(in)f(deb)n(ug) g(messages)g(for)g(connection)e(and)i(for)f(all)i(messages)208 4079 y(sent)f(to)g(and)g(recei)n(v)o(ed)f(from)g(the)h(serv)o(er)-5 b(.)0 4226 y FD(connect)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)19 b(port)13 b FC(])f(])p FJ(\))208 4326 y FN(Connect)28 b(to)h(a)h(host)f(on)g(a)g(gi)n(v)o(en)f(port.)51 b(The)29 b(def)o(aults)f(are)h(to)h(connect)e(to)h(the)g(local)g(host)g(at)h (the)f(standard)f(SMTP)h(port)208 4425 y(\(25\).)45 b(If)27 b(the)g(hostname)f(ends)h(with)h(a)f(colon)g(\(`)p FJ(:)p FN('\))38 b(follo)n(wed)26 b(by)h(a)h(number)m(,)e(that)i(suf)n(\002x)f (will)h(be)f(stripped)f(of)n(f)h(and)g(the)208 4525 y(number)18 b(interpreted)g(as)j(the)f(port)f(number)f(to)i(use.)26 b(This)20 b(method)e(is)j(automatically)e(in)m(v)n(ok)o(ed)f(by)i(the)g (constructor)e(if)i(a)h(host)208 4625 y(is)g(speci\002ed)f(during)e (instantiation.)0 4772 y FD(docmd)p FJ(\()p FK(cmd,)h FC([)p FK(,)h(ar)m(gstring)12 b FC(])p FJ(\))208 4871 y FN(Send)22 b(a)i(command)d FK(cmd)k FN(to)e(the)g(serv)o(er)-5 b(.)34 b(The)22 b(optional)g(ar)o(gument)f FK(ar)m(gstring)i FN(is)h(simply)e(concatenated)f(to)j(the)f(command,)208 4971 y(separated)c(by)h(a)g(space.)208 5104 y(This)k(returns)f(a)i (2-tuple)e(composed)f(of)i(a)g(numeric)f(response)g(code)h(and)f(the)i (actual)f(response)f(line)h(\(multiline)f(responses)208 5203 y(are)d(joined)f(into)h(one)g(long)f(line.\))208 5336 y(In)29 b(normal)g(operation)e(it)k(should)e(not)g(be)h(necessary) f(to)h(call)g(this)g(method)f(e)o(xplicitly)-5 b(.)52 b(It)30 b(is)h(used)e(to)h(implement)e(other)p 0 5549 3901 4 v 0 5649 a FI(652)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 653 665 TeXDict begin 653 664 bop 208 83 a FN(methods)19 b(and)g(may)h(be)g (useful)g(for)f(testing)i(pri)n(v)n(ate)e(e)o(xtensions.)208 212 y(If)e(the)g(connection)f(to)h(the)h(serv)o(er)e(is)j(lost)f(while) f(w)o(aiting)h(for)e(the)i(reply)-5 b(,)16 b FJ(SMTPServerDisconnected) e FN(will)19 b(be)e(raised.)0 359 y FD(helo)p FJ(\()p FC([)p FK(hostname)12 b FC(])p FJ(\))208 459 y FN(Identify)30 b(yourself)g(to)i(the)f(SMTP)h(serv)o(er)f(using)g(`)p FJ(HELO)p FN('.)g(The)g(hostname)f(ar)o(gument)g(def)o(aults)h(to)h (the)f(fully)g(quali\002ed)208 558 y(domain)18 b(name)i(of)g(the)g (local)g(host.)208 687 y(In)i(normal)g(operation)f(it)i(should)f(not)g (be)h(necessary)f(to)h(call)h(this)f(method)e(e)o(xplicitly)-5 b(.)32 b(It)23 b(will)g(be)g(implicitly)g(called)f(by)h(the)208 787 y FJ(sendmail\(\))18 b FN(when)i(necessary)-5 b(.)0 934 y FD(ehlo)p FJ(\()p FC([)p FK(hostname)12 b FC(])p FJ(\))208 1033 y FN(Identify)28 b(yourself)g(to)i(an)g(ESMTP)g(serv)o (er)f(using)g(`)p FJ(EHLO)p FN('.)g(The)g(hostname)g(ar)o(gument)e(def) o(aults)i(to)h(the)g(fully)f(quali\002ed)208 1133 y(domain)d(name)g(of) h(the)h(local)f(host.)46 b(Examine)26 b(the)i(response)e(for)h(ESMTP)g (option)g(and)f(store)i(them)f(for)f(use)i(by)f FJ(has_-)208 1233 y(extn\(\))p FN(.)208 1362 y(Unless)k(you)g(wish)h(to)f(use)h FJ(has_extn\(\))e FN(before)f(sending)i(mail,)j(it)e(should)e(not)h(be) g(necessary)g(to)g(call)h(this)g(method)208 1461 y(e)o(xplicitly)-5 b(.)23 b(It)e(will)f(be)h(implicitly)e(called)h(by)g FJ(sendmail\(\))f FN(when)h(necessary)-5 b(.)0 1608 y FD(has_extn)p FJ(\()p FK(name)p FJ(\))208 1708 y FN(Return)21 b FJ(True)h FN(if)h FK(name)e FN(is)i(in)g(the)f(set)h(of)f(SMTP)g (service)g(e)o(xtensions)f(returned)f(by)i(the)g(serv)o(er)m(,)g FJ(False)f FN(otherwise.)31 b(Case)208 1807 y(is)21 b(ignored.)0 1954 y FD(verify)p FJ(\()p FK(addr)m(ess)p FJ(\))208 2054 y FN(Check)e(the)h(v)n(alidity)f(of)g(an)h(address)f(on)g(this)i (serv)o(er)e(using)g(SMTP)h(`)p FJ(VRFY)p FN('.)f(Returns)g(a)h(tuple)g (consisting)f(of)g(code)g(250)g(and)208 2153 y(a)k(full)f(RFC)i(822)e (address)g(\(including)f(human)g(name\))g(if)i(the)g(user)f(address)h (is)g(v)n(alid.)32 b(Otherwise)22 b(returns)g(an)h(SMTP)g(error)208 2253 y(code)c(of)h(400)f(or)h(greater)f(and)h(an)g(error)f(string.)208 2382 y FL(Note:)24 b FN(Man)o(y)19 b(sites)i(disable)f(SMTP)h(`)p FJ(VRFY)p FN(')e(in)i(order)e(to)h(foil)g(spammers.)0 2529 y FD(login)p FJ(\()p FK(user)-9 b(,)19 b(passwor)m(d)r FJ(\))208 2628 y FN(Log)k(in)i(on)f(an)g(SMTP)h(serv)o(er)f(that)g (requires)f(authentication.)36 b(The)24 b(ar)o(guments)e(are)j(the)f (username)f(and)h(the)h(passw)o(ord)e(to)208 2728 y(authenticate)j (with.)47 b(If)27 b(there)g(has)g(been)g(no)g(pre)n(vious)f(`)p FJ(EHLO)p FN(')h(or)g(`)p FJ(HELO)p FN(')f(command)g(this)i(session,)h (this)f(method)e(tries)208 2828 y(ESMTP)e(`)p FJ(EHLO)p FN(')g(\002rst.)38 b(This)24 b(method)f(will)i(return)f(normally)e(if)j (the)f(authentication)f(w)o(as)i(successful,)g(or)f(may)g(raise)h(the) 208 2927 y(follo)n(wing)18 b(e)o(xceptions:)208 3133 y FD(SMTPHeloError)m FN(The)i(serv)o(er)f(didn')o(t)g(reply)g(properly) f(to)j(the)f(`)p FJ(HELO)p FN(')f(greeting.)208 3258 y FD(SMTPAuthenticationError)-5 b FN(The)20 b(serv)o(er)f(didn')o(t)g (accept)h(the)g(username/passw)o(ord)e(combination.)208 3383 y FD(SMTPException)m FN(No)i(suitable)g(authentication)f(method)f (w)o(as)j(found.)0 3542 y FD(starttls)p FJ(\()p FC([)p FK(k)o(e)n(y\002le)p FC([)p FK(,)c(cert\002le)12 b FC(])g(])p FJ(\))208 3641 y FN(Put)24 b(the)g(SMTP)g(connection)e(in)j(TLS)f(\(T)m (ransport)e(Layer)h(Security\))g(mode.)36 b(All)25 b(SMTP)f(commands)e (that)j(follo)n(w)e(will)i(be)208 3741 y(encrypted.)d(Y)-9 b(ou)20 b(should)f(then)h(call)h FJ(ehlo\(\))e FN(again.)208 3870 y(If)h FK(k)o(e)n(y\002le)f FN(and)h FK(cert\002le)g FN(are)g(pro)o(vided,)e(these)i(are)g(passed)g(to)g(the)h FJ(socket)e FN(module')-5 b(s)20 b FJ(ssl\(\))f FN(function.)0 4017 y FD(sendmail)p FJ(\()p FK(fr)l(om)p 608 4017 25 4 v 28 w(addr)-9 b(,)19 b(to)p 890 4017 V 30 w(addr)o(s,)h(msg)p FC([)p FK(,)g(mail)p 1513 4017 V 29 w(options,)f(r)m(cpt)p 1959 4017 V 30 w(options)12 b FC(])p FJ(\))208 4116 y FN(Send)20 b(mail.)25 b(The)20 b(required)f(ar)o(guments)f(are)j(an)f (RFC)i(822)d(from-address)f(string,)i(a)h(list)g(of)g(RFC)g(822)f (to-address)f(strings)h(\(a)208 4216 y(bare)h(string)h(will)h(be)f (treated)g(as)h(a)f(list)i(with)e(1)g(address\),)g(and)g(a)g(message)g (string.)31 b(The)22 b(caller)g(may)g(pass)h(a)f(list)h(of)f(ESMTP)208 4316 y(options)c(\(such)i(as)g(`)p FJ(8bitmime)p FN('\))e(to)i(be)g (used)f(in)h(`)p FJ(MAIL)49 b(FROM)p FN(')19 b(commands)f(as)j FK(mail)p 2852 4316 V 29 w(options)p FN(.)j(ESMTP)c(options)f(\(such) 208 4415 y(as)f(`)p FJ(DSN)p FN(')f(commands\))f(that)h(should)g(be)h (used)f(with)h(all)g(`)p FJ(RCPT)p FN(')f(commands)f(can)i(be)f(passed) h(as)h FK(r)m(cpt)p 3185 4415 V 29 w(options)p FN(.)k(\(If)17 b(you)g(need)208 4515 y(to)26 b(use)h(dif)n(ferent)f(ESMTP)g(options)g (to)h(dif)n(ferent)e(recipients)h(you)g(ha)n(v)o(e)g(to)h(use)g(the)g (lo)n(w-le)n(v)o(el)e(methods)h(such)h(as)g FJ(mail)p FN(,)208 4615 y FJ(rcpt)20 b FN(and)f FJ(data)h FN(to)h(send)e(the)i (message.\))208 4744 y FL(Note:)j FN(The)19 b FK(fr)l(om)p 734 4744 V 30 w(addr)i FN(and)e FK(to)p 1148 4744 V 30 w(addr)o(s)g FN(parameters)f(are)i(used)g(to)f(construct)g(the)h (message)f(en)m(v)o(elope)f(used)h(by)g(the)h(transport)208 4843 y(agents.)k(The)c FJ(SMTP)g FN(does)g(not)g(modify)e(the)j (message)f(headers)f(in)h(an)o(y)g(w)o(ay)-5 b(.)208 4972 y(If)20 b(there)h(has)g(been)f(no)h(pre)n(vious)e(`)p FJ(EHLO)p FN(')i(or)f(`)p FJ(HELO)p FN(')g(command)f(this)j(session,)f (this)h(method)d(tries)j(ESMTP)f(`)p FJ(EHLO)p FN(')f(\002rst.)208 5072 y(If)g(the)g(serv)o(er)f(does)h(ESMTP)-9 b(,)20 b(message)h(size)f(and)g(each)g(of)g(the)g(speci\002ed)g(options)g (will)h(be)f(passed)g(to)h(it)g(\(if)f(the)g(option)f(is)i(in)208 5171 y(the)f(feature)f(set)i(the)f(serv)o(er)g(adv)o(ertises\).)j(If)d (`)p FJ(EHLO)p FN(')g(f)o(ails,)g(`)p FJ(HELO)p FN(')g(will)h(be)f (tried)g(and)f(ESMTP)i(options)e(suppressed.)208 5300 y(This)25 b(method)e(will)j(return)d(normally)g(if)i(the)g(mail)g(is)h (accepted)e(for)g(at)h(least)h(one)e(recipient.)38 b(Otherwise)25 b(it)g(will)h(thro)n(w)e(an)208 5400 y(e)o(xception.)48 b(That)29 b(is,)i(if)e(this)g(method)f(does)g(not)g(thro)n(w)g(an)h(e)o (xception,)f(then)h(someone)e(should)h(get)g(your)g(mail.)50 b(If)29 b(this)p 0 5549 3901 4 v 0 5649 a FI(18.13.)52 b FJ(smtplib)22 b FI(\227)h(SMTP)h(protocol)f(client)2237 b(653)p eop end %%Page: 654 666 TeXDict begin 654 665 bop 208 83 a FN(method)20 b(does)i(not)g(thro)n (w)g(an)g(e)o(xception,)f(it)i(returns)e(a)i(dictionary)-5 b(,)20 b(with)i(one)g(entry)g(for)f(each)h(recipient)f(that)i(w)o(as)g (refused.)208 183 y(Each)c(entry)h(contains)f(a)i(tuple)f(of)f(the)i (SMTP)f(error)f(code)h(and)f(the)i(accompan)o(ying)16 b(error)j(message)h(sent)h(by)f(the)g(serv)o(er)-5 b(.)208 315 y(This)20 b(method)f(may)g(raise)i(the)f(follo)n(wing)f(e)o (xceptions:)208 529 y FD(SMTPRecipientsRefused)l FN(All)j(recipients)g (were)g(refused.)30 b(Nobody)20 b(got)i(the)g(mail.)31 b(The)22 b FJ(recipients)f FN(attrib)n(ute)390 628 y(of)g(the)g(e)o (xception)e(object)h(is)i(a)f(dictionary)f(with)h(information)d(about)i (the)h(refused)f(recipients)g(\(lik)o(e)h(the)g(one)f(returned)390 728 y(when)g(at)g(least)h(one)f(recipient)f(w)o(as)i(accepted\).)208 861 y FD(SMTPHeloError)m FN(The)f(serv)o(er)f(didn')o(t)g(reply)g (properly)f(to)j(the)f(`)p FJ(HELO)p FN(')f(greeting.)208 994 y FD(SMTPSenderRefused)l FN(The)h(serv)o(er)g(didn')o(t)e(accept)i (the)g FK(fr)l(om)p 2157 994 25 4 v 30 w(addr)r FN(.)208 1127 y FD(SMTPDataError)m FN(The)g(serv)o(er)f(replied)h(with)g(an)g (une)o(xpected)e(error)h(code)g(\(other)g(than)h(a)h(refusal)e(of)h(a)h (recipient\).)208 1340 y(Unless)f(otherwise)g(noted,)f(the)h (connection)e(will)j(be)f(open)f(e)n(v)o(en)g(after)h(an)g(e)o (xception)f(is)i(raised.)0 1487 y FD(quit)p FJ(\(\))208 1586 y FN(T)-6 b(erminate)19 b(the)h(SMTP)h(session)f(and)g(close)g (the)g(connection.)0 1733 y(Lo)n(w-le)n(v)o(el)33 b(methods)h (corresponding)e(to)j(the)g(standard)f(SMTP/ESMTP)h(commands)f(`)p FJ(HELP)p FN(',)g(`)p FJ(RSET)p FN(',)g(`)p FJ(NOOP)p FN(',)g(`)p FJ(MAIL)p FN(',)0 1833 y(`)p FJ(RCPT)p FN(',)19 b(and)g(`)p FJ(DATA)p FN(')g(are)h(also)g(supported.)j(Normally)18 b(these)i(do)g(not)f(need)h(to)g(be)f(called)h(directly)-5 b(,)19 b(so)h(the)o(y)f(are)h(not)f(documented)0 1932 y(here.)24 b(F)o(or)c(details,)g(consult)g(the)g(module)f(code.)0 2217 y Fv(18.13.2)101 b(SMTP)28 b(Example)0 2420 y FN(This)e(e)o (xample)f(prompts)g(the)h(user)g(for)g(addresses)g(needed)f(in)h(the)g (message)g(en)m(v)o(elope)e(\(`T)-7 b(o')25 b(and)h(`From')f (addresses\),)i(and)f(the)0 2520 y(message)e(to)g(be)g(deli)n(v)o (ered.)35 b(Note)24 b(that)h(the)f(headers)f(to)h(be)g(included)f(with) h(the)h(message)f(must)g(be)g(included)e(in)j(the)f(message)g(as)0 2619 y(entered;)c(this)h(e)o(xample)e(doesn')o(t)g(do)h(an)o(y)g (processing)f(of)h(the)h(RFC)h(822)e(headers.)25 b(In)20 b(particular)m(,)f(the)i(`T)-7 b(o')20 b(and)g(`From')f(addresses)0 2719 y(must)h(be)g(included)f(in)h(the)h(message)f(headers)f(e)o (xplicitly)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(654)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 655 667 TeXDict begin 655 666 bop 236 174 a FA(import)44 b(smtplib)236 357 y(def)h(prompt\(prompt\):)416 448 y(return)e (raw_input\(prompt\).strip\(\))236 631 y(fromaddr)h(=)g(prompt\("From:) f("\))236 722 y(toaddrs)89 b(=)44 b(prompt\("To:)f("\).split\(\))236 814 y(print)h("Enter)g(message,)g(end)g(with)g(\210D)h(\(Unix\))e(or)i (\210Z)f(\(Windows\):")236 996 y(#)h(Add)f(the)h(From:)f(and)g(To:)g (headers)g(at)g(the)h(start!)236 1088 y(msg)g(=)f(\("From:)g (\045s\\r\\nTo:)f(\045s\\r\\n\\r\\n")550 1179 y(\045)i(\(fromaddr,)e (",)h(".join\(toaddrs\)\)\))236 1270 y(while)g(1:)416 1362 y(try:)595 1453 y(line)g(=)h(raw_input\(\))416 1544 y(except)e(EOFError:)595 1636 y(break)416 1727 y(if)h(not)g(line:)595 1818 y(break)416 1910 y(msg)g(=)h(msg)f(+)h(line)236 2092 y(print)f("Message)g(length)g(is)g(")h(+)f(repr\(len\(msg\)\))236 2275 y(server)g(=)h(smtplib.SMTP\('localhost'\))236 2366 y(server.set_debuglevel\(1\))236 2457 y(server.sendmail\(fromaddr,)c (toaddrs,)i(msg\))236 2549 y(server.quit\(\))0 3059 y FE(18.14)122 b Fx(smtpd)32 b FE(\227)g(SMTP)h(Ser)t(v)m(er)0 3292 y FN(This)24 b(module)e(of)n(fers)h(se)n(v)o(eral)f(classes)j(to)f (implement)e(SMTP)i(serv)o(ers.)34 b(One)24 b(is)g(a)g(generic)f (do-nothing)d(implementation,)i(which)0 3391 y(can)e(be)g(o)o(v)o (erridden,)d(while)j(the)g(other)g(tw)o(o)g(of)n(fer)f(speci\002c)h (mail-sending)f(strate)o(gies.)0 3676 y Fv(18.14.1)101 b(SMTPSer)s(v)n(er)29 b(Objects)0 3865 y FL(class)21 b FD(SMTPServer)p FJ(\()p FK(localaddr)-9 b(,)16 b(r)m(emoteaddr)r FJ(\))208 3965 y FN(Create)30 b(a)g(ne)n(w)g FJ(SMTPServer)f FN(object,)i(which)f(binds)f(to)i(local)f(address)f FK(localaddr)r FN(.)53 b(It)30 b(will)h(treat)f FK(r)m(emoteaddr)h FN(as)g(an)208 4064 y(upstream)16 b(SMTP)h(relayer)-5 b(.)24 b(It)18 b(inherits)e(from)h FJ(asyncore.dispatcher)p FN(,)d(and)j(so)h(will)g (insert)f(itself)h(into)f FJ(asyncore)p FN(')-5 b(s)208 4164 y(e)n(v)o(ent)19 b(loop)g(on)h(instantiation.)0 4311 y FD(process_message)p FJ(\()p FK(peer)-9 b(,)17 b(mailfr)l(om,)j(r)m(cpttos,)g(data)p FJ(\))208 4410 y FN(Raise)g FJ(NotImplementedError)d FN(e)o(xception.)23 b(Ov)o(erride)18 b(this)i(in)g(subclasses)h(to)f(do)f(something)f (useful)h(with)h(this)h(mes-)208 4510 y(sage.)29 b(Whate)n(v)o(er)21 b(w)o(as)h(passed)g(in)g(the)g(constructor)d(as)k FK(r)m(emoteaddr)f FN(will)h(be)f(a)n(v)n(ailable)f(as)h(the)g FJ(_remoteaddr)e FN(attrib)n(ute.)208 4610 y FK(peer)27 b FN(is)g(the)f(remote)f(host') -5 b(s)26 b(address,)h FK(mailfr)l(om)f FN(is)h(the)f(en)m(v)o(elope)e (originator)m(,)g FK(r)m(cpttos)i FN(are)g(the)g(en)m(v)o(elope)e (recipients)h(and)208 4709 y FK(data)19 b FN(is)i(a)g(string)f (containing)e(the)i(contents)f(of)h(the)h(e-mail)e(\(which)h(should)f (be)h(in)g(RFC)i(2822)d(format\).)0 4994 y Fv(18.14.2)101 b(Deb)n(uggingSer)s(v)n(er)31 b(Objects)0 5183 y FL(class)21 b FD(DebuggingServer)p FJ(\()p FK(localaddr)-9 b(,)15 b(r)m(emoteaddr)r FJ(\))208 5283 y FN(Create)21 b(a)h(ne)n(w)g(deb)n (ugging)d(serv)o(er)-5 b(.)29 b(Ar)o(guments)19 b(are)j(as)g(per)f FJ(SMTPServer)p FN(.)28 b(Messages)22 b(will)h(be)e(discarded,)g(and)g (printed)208 5382 y(on)e(stdout.)p 0 5549 3901 4 v 0 5649 a FI(18.14.)52 b FJ(smtpd)23 b FI(\227)g(SMTP)g(Ser)r(v)n(er)2603 b(655)p eop end %%Page: 656 668 TeXDict begin 656 667 bop 0 83 a Fv(18.14.3)101 b(PurePro)m(xy)30 b(Objects)0 272 y FL(class)21 b FD(PureProxy)p FJ(\()p FK(localaddr)-9 b(,)16 b(r)m(emoteaddr)r FJ(\))208 372 y FN(Create)g(a)h(ne)n(w)g(pure)f(proxy)e(serv)o(er)-5 b(.)24 b(Ar)o(guments)14 b(are)j(as)g(per)g FJ(SMTPServer)p FN(.)22 b(Ev)o(erything)14 b(will)j(be)g(relayed)e(to)i FK(r)m(emoteaddr)r FN(.)208 471 y(Note)j(that)g(running)e(this)j(has)f (a)h(good)e(chance)g(to)h(mak)o(e)g(you)f(into)h(an)g(open)f(relay)-5 b(,)19 b(so)i(please)f(be)g(careful.)0 756 y Fv(18.14.4)101 b(MailmanPro)m(xy)30 b(Objects)0 945 y FL(class)21 b FD(MailmanProxy)p FJ(\()p FK(localaddr)-9 b(,)16 b(r)m(emoteaddr)r FJ(\))208 1045 y FN(Create)g(a)h(ne)n(w)g(pure)f(proxy)e(serv)o(er)-5 b(.)24 b(Ar)o(guments)14 b(are)j(as)g(per)g FJ(SMTPServer)p FN(.)22 b(Ev)o(erything)14 b(will)j(be)g(relayed)e(to)i FK(r)m(emoteaddr)r FN(,)208 1144 y(unless)g(local)g(mailman)f (con\002gurations)f(kno)n(ws)i(about)f(an)h(address,)g(in)g(which)g (case)h(it)g(will)g(be)f(handled)e(via)j(mailman.)23 b(Note)208 1244 y(that)d(running)e(this)j(has)f(a)h(good)d(chance)i(to) g(mak)o(e)g(you)f(into)h(an)g(open)f(relay)-5 b(,)19 b(so)i(please)f(be)g(careful.)0 1571 y FE(18.15)122 b Fx(telnetlib)30 b FE(\227)j(T)-14 b(elnet)34 b(client)0 1804 y FN(The)27 b FJ(telnetlib)f FN(module)f(pro)o(vides)g(a)j FJ(Telnet)e FN(class)i(that)f(implements)f(the)h(T)-6 b(elnet)27 b(protocol.)44 b(See)27 b(RFC)i(854)d(for)g(details)0 1904 y(about)g(the)i(protocol.)45 b(In)27 b(addition,)g(it)h(pro)o (vides)e(symbolic)g(constants)h(for)g(the)g(protocol)f(characters)g (\(see)i(belo)n(w\),)g(and)f(for)g(the)0 2003 y(telnet)19 b(options.)k(The)18 b(symbolic)g(names)g(of)g(the)h(telnet)f(options)g (follo)n(w)g(the)g(de\002nitions)g(in)h FJ(arpa/telnet.h)p FN(,)d(with)j(the)g(leading)0 2103 y FJ(TELOPT_)k FN(remo)o(v)o(ed.)34 b(F)o(or)24 b(symbolic)f(names)g(of)h(options)f(which)h(are)f (traditionally)g(not)h(included)e(in)i FJ(arpa/telnet.h)p FN(,)f(see)0 2203 y(the)d(module)f(source)g(itself.)0 2349 y(The)d(symbolic)f(constants)h(for)g(the)h(telnet)f(commands)f (are:)23 b(IA)m(C,)16 b(DONT)-6 b(,)17 b(DO,)f(W)o(ONT)-6 b(,)17 b(WILL,)f(SE)h(\(Subne)o(gotiation)c(End\),)j(NOP)0 2449 y(\(No)25 b(Operation\),)g(DM)h(\(Data)f(Mark\),)h(BRK)g (\(Break\),)g(IP)g(\(Interrupt)d(process\),)j(A)-5 b(O)26 b(\(Abort)e(output\),)h(A)-9 b(YT)26 b(\(Are)f(Y)-9 b(ou)25 b(There\),)0 2549 y(EC)c(\(Erase)f(Character\),)f(EL)h(\(Erase)g (Line\),)f(GA)h(\(Go)g(Ahead\),)f(SB)i(\(Subne)o(gotiation)c(Be)o (gin\).)0 2696 y FL(class)k FD(Telnet)p FJ(\()p FC([)p FK(host)q FC([)p FK(,)e(port)13 b FC(])f(])p FJ(\))208 2795 y(Telnet)30 b FN(represents)g(a)h(connection)e(to)i(a)g(T)-6 b(elnet)31 b(serv)o(er)-5 b(.)57 b(The)31 b(instance)f(is)i(initially)f (not)f(connected)f(by)i(def)o(ault;)36 b(the)208 2895 y FJ(open\(\))18 b FN(method)h(must)g(be)g(used)h(to)f(establish)h(a)g (connection.)i(Alternati)n(v)o(ely)-5 b(,)18 b(the)h(host)h(name)e(and) h(optional)g(port)f(number)208 2994 y(can)25 b(be)h(passed)f(to)h(the)g (constructor)m(,)e(to,)j(in)f(which)f(case)h(the)g(connection)e(to)i (the)f(serv)o(er)g(will)h(be)g(established)f(before)g(the)208 3094 y(constructor)18 b(returns.)208 3227 y(Do)i(not)g(reopen)e(an)i (already)f(connected)g(instance.)208 3360 y(This)31 b(class)h(has)f (man)o(y)f FJ(read_)1187 3375 y(*)1237 3360 y(\(\))g FN(methods.)57 b(Note)31 b(that)g(some)g(of)g(them)g(raise)g FJ(EOFError)f FN(when)h(the)g(end)g(of)g(the)208 3459 y(connection)22 b(is)k(read,)f(because)f(the)o(y)g(can)h(return)f(an)h (empty)e(string)i(for)f(other)g(reasons.)39 b(See)25 b(the)g(indi)n(vidual)e(descriptions)208 3559 y(belo)n(w)-5 b(.)0 3706 y FL(See)21 b(Also:)0 3853 y FN(RFC)h(854,)d(\223)p FK(T)-8 b(elnet)20 b(Pr)l(otocol)g(Speci\002cation)p FN(\224)208 3952 y(De\002nition)f(of)h(the)g(T)-6 b(elnet)20 b(protocol.)0 4237 y Fv(18.15.1)101 b(T)-12 b(elnet)29 b(Objects)0 4440 y FJ(Telnet)20 b FN(instances)g(ha)n(v)o(e)f(the)i (follo)n(wing)d(methods:)0 4587 y FD(read_until)p FJ(\()p FK(e)n(xpected)r FC([)p FK(,)f(timeout)c FC(])p FJ(\))208 4687 y FN(Read)20 b(until)g(a)h(gi)n(v)o(en)d(string,)i FK(e)n(xpected)r FN(,)g(is)h(encountered)c(or)j(until)g FK(timeout)h FN(seconds)f(ha)n(v)o(e)g(passed.)208 4819 y(When)j(no)g(match)h(is)g(found,)f(return)f(whate)n(v)o(er)h(is)h(a)n (v)n(ailable)g(instead,)g(possibly)f(the)h(empty)e(string.)36 b(Raise)24 b FJ(EOFError)f FN(if)208 4919 y(the)d(connection)e(is)j (closed)f(and)f(no)h(cook)o(ed)f(data)h(is)h(a)n(v)n(ailable.)0 5066 y FD(read_all)p FJ(\(\))208 5166 y FN(Read)f(all)h(data)f(until)i FH(E)t(O)t(F)r FN(;)e(block)g(until)g(connection)e(closed.)p 0 5549 3901 4 v 0 5649 a FI(656)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 657 669 TeXDict begin 657 668 bop 0 83 a FD(read_some)p FJ(\(\))208 183 y FN(Read)19 b(at)h(least)h(one)d(byte)i(of)f(cook)o(ed)f(data)h (unless)j FH(E)t(O)t(F)g FN(is)e(hit.)25 b(Return)19 b FJ('')h FN(if)i FH(E)t(O)t(F)f FN(is)g(hit.)k(Block)19 b(if)h(no)f(data)g(is)i(immediately)208 282 y(a)n(v)n(ailable.)0 429 y FD(read_very_eager)p FJ(\(\))208 529 y FN(Read)f(e)n(v)o (erything)d(that)k(can)f(be)g(without)f(blocking)g(in)h(I/O)g (\(eager\).)208 662 y(Raise)27 b FJ(EOFError)f FN(if)h(connection)d (closed)j(and)f(no)g(cook)o(ed)f(data)i(a)n(v)n(ailable.)43 b(Return)26 b FJ('')h FN(if)g(no)f(cook)o(ed)g(data)g(a)n(v)n(ailable) 208 761 y(otherwise.)e(Do)c(not)g(block)f(unless)h(in)h(the)f(midst)g (of)g(an)g(IA)m(C)h(sequence.)0 908 y FD(read_eager)p FJ(\(\))208 1008 y FN(Read)f(readily)f(a)n(v)n(ailable)h(data.)208 1141 y(Raise)27 b FJ(EOFError)f FN(if)h(connection)d(closed)j(and)f(no) g(cook)o(ed)f(data)i(a)n(v)n(ailable.)43 b(Return)26 b FJ('')h FN(if)g(no)f(cook)o(ed)g(data)g(a)n(v)n(ailable)208 1240 y(otherwise.)e(Do)c(not)g(block)f(unless)h(in)h(the)f(midst)g(of)g (an)g(IA)m(C)h(sequence.)0 1387 y FD(read_lazy)p FJ(\(\))208 1487 y FN(Process)f(and)g(return)f(data)h(already)f(in)h(the)g(queues)g (\(lazy\).)208 1620 y(Raise)h FJ(EOFError)f FN(if)h(connection)e (closed)i(and)f(no)g(data)h(a)n(v)n(ailable.)26 b(Return)21 b FJ('')g FN(if)g(no)f(cook)o(ed)f(data)i(a)n(v)n(ailable)f(otherwise.) 208 1719 y(Do)g(not)g(block)f(unless)h(in)h(the)f(midst)g(of)g(an)g(IA) m(C)g(sequence.)0 1866 y FD(read_very_lazy)p FJ(\(\))208 1966 y FN(Return)f(an)o(y)h(data)g(a)n(v)n(ailable)f(in)i(the)f(cook)o (ed)f(queue)g(\(v)o(ery)f(lazy\).)208 2098 y(Raise)j FJ(EOFError)f FN(if)h(connection)e(closed)i(and)f(no)g(data)h(a)n(v)n (ailable.)26 b(Return)21 b FJ('')g FN(if)g(no)f(cook)o(ed)f(data)i(a)n (v)n(ailable)f(otherwise.)208 2198 y(This)g(method)f(ne)n(v)o(er)g (blocks.)0 2345 y FD(read_sb_data)p FJ(\(\))208 2445 y FN(Return)k(the)i(data)f(collected)f(between)h(a)g(SB/SE)i(pair)d (\(suboption)f(be)o(gin/end\).)35 b(The)24 b(callback)f(should)g (access)i(these)g(data)208 2544 y(when)19 b(it)i(w)o(as)g(in)m(v)n(ok)o (ed)e(with)h(a)g FJ(SE)h FN(command.)i(This)d(method)f(ne)n(v)o(er)g (blocks.)208 2677 y(Ne)n(w)h(in)g(v)o(ersion)f(2.3.)0 2824 y FD(open)p FJ(\()p FK(host)q FC([)p FK(,)g(port)13 b FC(])p FJ(\))208 2924 y FN(Connect)20 b(to)h(a)h(host.)27 b(The)21 b(optional)f(second)g(ar)o(gument)f(is)j(the)f(port)g(number)m (,)e(which)h(def)o(aults)h(to)g(the)g(standard)f(T)-6 b(elnet)21 b(port)208 3023 y(\(23\).)208 3156 y(Do)f(not)g(try)g(to)g (reopen)f(an)h(already)f(connected)f(instance.)0 3303 y FD(msg)p FJ(\()p FK(msg)p FC([)p FK(,)h(*ar)m(gs)12 b FC(])p FJ(\))208 3403 y FN(Print)24 b(a)g(deb)n(ug)f(message)h(when)g (the)g(deb)n(ug)f(le)n(v)o(el)h(is)h FJ(>)f FN(0.)37 b(If)24 b(e)o(xtra)g(ar)o(guments)e(are)i(present,)g(the)o(y)g(are)g (substituted)f(in)i(the)208 3502 y(message)20 b(using)f(the)h(standard) f(string)h(formatting)f(operator)-5 b(.)0 3649 y FD(set_debuglevel)p FJ(\()p FK(deb)n(ugle)o(vel)p FJ(\))208 3749 y FN(Set)20 b(the)h(deb)n(ug)e(le)n(v)o(el.)24 b(The)c(higher)f(the)h(v)n(alue)g (of)g FK(deb)n(ugle)o(vel)p FN(,)e(the)i(more)f(deb)n(ug)g(output)g (you)h(get)g(\(on)f FJ(sys.stdout)p FN(\).)0 3896 y FD(close)p FJ(\(\))208 3995 y FN(Close)h(the)h(connection.)0 4142 y FD(get_socket)p FJ(\(\))208 4242 y FN(Return)e(the)i(sock)o(et)f (object)f(used)h(internally)-5 b(.)0 4389 y FD(fileno)p FJ(\(\))208 4488 y FN(Return)19 b(the)i(\002le)f(descriptor)f(of)h(the) g(sock)o(et)g(object)g(used)g(internally)-5 b(.)0 4635 y FD(write)p FJ(\()p FK(b)n(uf)o(fer)r FJ(\))208 4735 y FN(Write)26 b(a)h(string)e(to)i(the)f(sock)o(et,)h(doubling)d(an)o(y) h(IA)m(C)h(characters.)42 b(This)26 b(can)g(block)f(if)i(the)f (connection)e(is)j(block)o(ed.)41 b(May)208 4834 y(raise)20 b FJ(socket.error)f FN(if)h(the)g(connection)e(is)j(closed.)0 4981 y FD(interact)p FJ(\(\))208 5081 y FN(Interaction)d(function,)g (emulates)i(a)h(v)o(ery)e(dumb)g(T)-6 b(elnet)20 b(client.)0 5228 y FD(mt_interact)p FJ(\(\))208 5327 y FN(Multithreaded)e(v)o (ersion)h(of)h FJ(interact\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(18.15.)52 b FJ(telnetlib)22 b FI(\227)h(T)-10 b(elnet)24 b(client)2465 b(657)p eop end %%Page: 658 670 TeXDict begin 658 669 bop 0 83 a FD(expect)p FJ(\()p FK(list)q FC([)p FK(,)20 b(timeout)13 b FC(])p FJ(\))208 183 y FN(Read)20 b(until)g(one)g(from)f(a)h(list)i(of)e(a)g(re)o(gular) f(e)o(xpressions)g(matches.)208 315 y(The)k(\002rst)h(ar)o(gument)e(is) i(a)g(list)h(of)f(re)o(gular)e(e)o(xpressions,)h(either)g(compiled)f (\()p FJ(re.RegexObject)g FN(instances\))h(or)g(uncom-)208 415 y(piled)c(\(strings\).)25 b(The)19 b(optional)g(second)h(ar)o (gument)d(is)22 b(a)e(timeout,)f(in)i(seconds;)e(the)i(def)o(ault)e(is) i(to)g(block)e(inde\002nitely)-5 b(.)208 548 y(Return)21 b(a)i(tuple)e(of)h(three)f(items:)30 b(the)22 b(inde)o(x)e(in)j(the)f (list)h(of)e(the)h(\002rst)h(re)o(gular)e(e)o(xpression)f(that)i (matches;)h(the)f(match)f(object)208 648 y(returned;)d(and)i(the)g(te)o (xt)g(read)g(up)f(till)i(and)f(including)e(the)j(match.)208 780 y(If)g(end)h(of)f(\002le)i(is)f(found)f(and)g(no)g(te)o(xt)h(w)o (as)h(read,)e(raise)h FJ(EOFError)p FN(.)29 b(Otherwise,)22 b(when)f(nothing)f(matches,)i(return)f FJ(\(-1,)208 880 y(None,)48 b FK(te)n(xt)q FJ(\))22 b FN(where)d FK(te)n(xt)k FN(is)e(the)f(te)o(xt)g(recei)n(v)o(ed)f(so)h(f)o(ar)g(\(may)g(be)g (the)g(empty)f(string)h(if)h(a)f(timeout)g(happened\).)208 1013 y(If)25 b(a)h(re)o(gular)e(e)o(xpression)g(ends)h(with)h(a)f (greedy)f(match)h(\(such)g(as)2189 979 y Fp(d)2204 1013 y FJ(.)2254 1028 y(*)2294 1013 y Fp(c)-10 b FN(\))25 b(or)g(if)h(more)e(than)h(one)g(e)o(xpression)f(can)i(match)f(the)208 1112 y(same)20 b(input,)f(the)h(results)h(are)f(indeterministic,)f(and) g(may)h(depend)e(on)i(the)g(I/O)h(timing.)0 1259 y FD (set_option_negotiation_callback)p FJ(\()p FK(ca)o(llbac)m(k)q FJ(\))208 1359 y FN(Each)g(time)g(a)i(telnet)e(option)g(is)h(read)f(on) g(the)h(input)f(\003o)n(w)-5 b(,)21 b(this)i FK(callbac)n(k)f FN(\(if)f(set\))h(is)h(called)e(with)h(the)g(follo)n(wing)e(parameters) 208 1459 y(:)29 b(callback\(telnet)20 b(sock)o(et,)i(command)e (\(DO/DONT/WILL/W)o(ONT\),)h(option\).)28 b(No)22 b(other)f(action)g (is)i(done)e(afterw)o(ards)g(by)208 1558 y(telnetlib)m(.)0 1843 y Fv(18.15.2)101 b(T)-12 b(elnet)29 b(Example)0 2046 y FN(A)21 b(simple)f(e)o(xample)f(illustrating)g(typical)h(use:) 236 2284 y FA(import)44 b(getpass)236 2376 y(import)g(sys)236 2467 y(import)g(telnetlib)236 2650 y(HOST)g(=)h("localhost")236 2741 y(user)f(=)h(raw_input\("Enter)d(your)i(remote)g(account:)g("\)) 236 2832 y(password)g(=)g(getpass.getpass\(\))236 3015 y(tn)h(=)f(telnetlib.Telnet\(HOST\))236 3197 y(tn.read_until\("login:)e ("\))236 3289 y(tn.write\(user)h(+)i("\\n"\))236 3380 y(if)g(password:)416 3471 y(tn.read_until\("Password:)40 b("\))416 3563 y(tn.write\(password)i(+)i("\\n"\))236 3745 y(tn.write\("ls\\n"\))236 3837 y(tn.write\("exit\\n"\))236 4019 y(print)g(tn.read_all\(\))0 4529 y FE(18.16)122 b Fx(uuid)32 b FE(\227)h(UUID)h(objects)g(according)g(to)g(RFC)g(4122)0 4762 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 4909 y(This)g(module)f (pro)o(vides)f(immutable)g FJ(UUID)i FN(objects)g(\(the)f FJ(UUID)h FN(class\))g(and)g(the)g(functions)e FJ(uuid1\(\))p FN(,)h FJ(uuid3\(\))p FN(,)h FJ(uuid4\(\))p FN(,)0 5009 y FJ(uuid5\(\))g FN(for)h(generating)e(v)o(ersion)h(1,)h(3,)g(4,)g(and) g(5)g(UUIDs)h(as)g(speci\002ed)e(in)i(RFC)g(4122.)0 5156 y(If)15 b(all)h(you)f(w)o(ant)h(is)g(a)g(unique)e(ID,)i(you)e(should)h (probably)e(call)j FJ(uuid1\(\))f FN(or)g FJ(uuid4\(\))p FN(.)23 b(Note)15 b(that)h FJ(uuid1\(\))e FN(may)i(compromise)0 5255 y(pri)n(v)n(ac)o(y)i(since)j(it)g(creates)f(a)g(UUID)h(containing) d(the)i(computer')-5 b(s)19 b(netw)o(ork)g(address.)24 b FJ(uuid4\(\))c FN(creates)g(a)h(random)d(UUID.)p 0 5549 3901 4 v 0 5649 a FI(658)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 659 671 TeXDict begin 659 670 bop 0 83 a FL(class)21 b FD(UUID)p FJ(\()p FC([)p FK(he)n(x)p FC([)p FK(,)e(bytes)p FC([)p FK(,)h(bytes)p 1099 83 25 4 v 29 w(le)p FC([)p FK(,)h(\002elds)p FC([)p FK(,)e(int)q FC([)p FK(,)i(ver)o(sion)12 b FC(])g(])g(])g(])g(]) g(])p FJ(\))208 183 y FN(Create)20 b(a)g(UUID)f(from)g(either)g(a)h (string)g(of)f(32)h(he)o(xadecimal)d(digits,)j(a)g(string)f(of)h(16)f (bytes)h(as)g(the)g FK(bytes)g FN(ar)o(gument,)d(a)j(string)208 282 y(of)g(16)h(bytes)g(in)g(little-endian)f(order)g(as)i(the)f FK(bytes)p 1696 282 V 30 w(le)g FN(ar)o(gument,)e(a)j(tuple)e(of)h(six) h(inte)o(gers)e(\(32-bit)g FK(time)p 3292 282 V 30 w(low)p FN(,)h(16-bit)g FK(time)p 3848 282 V 29 w(-)208 382 y(mid)r FN(,)f(16-bit)f FK(time)p 743 382 V 30 w(hi)p 838 382 V 29 w(ver)o(sion)p FN(,)i(8-bit)e FK(cloc)n(k)p 1504 382 V 30 w(seq)p 1645 382 V 29 w(hi)p 1739 382 V 30 w(variant)q FN(,)h(8-bit)f FK(cloc)n(k)p 2403 382 V 30 w(seq)p 2544 382 V 29 w(low)p FN(,)i(48-bit)e FK(node)p FN(\))g(as)i(the)f FK(\002elds)g FN(ar)o(gument,)208 482 y(or)h(a)h(single)f(128-bit)f (inte)o(ger)h(as)h(the)g FK(int)h FN(ar)o(gument.)k(When)21 b(a)h(string)g(of)f(he)o(x)g(digits)h(is)g(gi)n(v)o(en,)e(curly)h (braces,)h(hyphens,)d(and)208 581 y(a)h(URN)h(pre\002x)f(are)g(all)h (optional.)i(F)o(or)d(e)o(xample,)f(these)h(e)o(xpressions)f(all)i (yield)e(the)i(same)f(UUID:)444 805 y FA (UUID\('{12345678-1234-5678-1234-5678123)o(45678})o('\))444 897 y(UUID\('12345678123456781234567812345678)o('\))444 988 y(UUID\('urn:uuid:12345678-1234-5678-1234)o(-56781)o(234567)o(8'\)) 444 1079 y(UUID\(bytes='\\x12\\x34\\x56\\x78')1749 1092 y(*)1794 1079 y(4\))444 1171 y (UUID\(bytes_le='\\x78\\x56\\x34\\x12\\x34\\x1)o(2\\x78\\)o(x56')39 b(+)1071 1262 y('\\x12\\x34\\x56\\x78\\x12\\x34\\x56\\x78'\))444 1353 y(UUID\(fields=\(0x12345678,)i(0x1234,)i(0x5678,)h(0x12,)g(0x34,)g (0x567812345678\)\))444 1445 y(UUID\(int=0x123456781234567812345678123) o(45678\))208 1634 y FN(Exactly)21 b(one)i(of)f FK(he)n(x)p FN(,)i FK(bytes)p FN(,)f FK(bytes)p 1270 1634 V 29 w(le)p FN(,)h FK(\002elds)p FN(,)f(or)f FK(int)j FN(must)e(be)f(gi)n(v)o(en.) 32 b(The)22 b FK(ver)o(sion)h FN(ar)o(gument)d(is)k(optional;)f(if)g (gi)n(v)o(en,)f(the)208 1734 y(resulting)c(UUID)g(will)i(ha)n(v)o(e)e (its)i(v)n(ariant)e(and)g(v)o(ersion)g(number)f(set)i(according)e(to)i (RFC)h(4122,)e(o)o(v)o(erriding)e(bits)j(in)g(the)g(gi)n(v)o(en)208 1833 y FK(he)n(x)p FN(,)h FK(bytes)p FN(,)g FK(bytes)p 751 1833 V 30 w(le)p FN(,)g FK(\002elds)p FN(,)g(or)g FK(int)q FN(.)0 1980 y FJ(UUID)g FN(instances)g(ha)n(v)o(e)g(these)g (read-only)e(attrib)n(utes:)0 2127 y FD(bytes)208 2227 y FN(The)h(UUID)i(as)g(a)f(16-byte)f(string)g(\(containing)f(the)j(six) f(inte)o(ger)f(\002elds)i(in)f(big-endian)e(byte)i(order\).)0 2374 y FD(bytes_le)208 2473 y FN(The)f(UUID)i(as)g(a)f(16-byte)f (string)g(\(with)h FK(time)p 1561 2473 V 30 w(low)p FN(,)h FK(time)p 1896 2473 V 30 w(mid)r FN(,)f(and)g FK(time)p 2378 2473 V 29 w(hi)p 2472 2473 V 30 w(ver)o(sion)g FN(in)h (little-endian)e(byte)g(order\).)0 2620 y FD(fields)208 2720 y FN(A)e(tuple)h(of)f(the)g(six)h(inte)o(ger)e(\002elds)i(of)f (the)h(UUID,)f(which)g(are)g(also)h(a)n(v)n(ailable)f(as)h(six)g(indi)n (vidual)d(attrib)n(utes)j(and)f(tw)o(o)g(deri)n(v)o(ed)208 2819 y(attrib)n(utes:)1031 2932 y FL(Field)p 2076 2962 4 100 v 916 w(Meaning)p 982 2965 2145 4 v 1031 3035 a FJ(time_low)p 2076 3065 4 100 v 696 w FN(the)k(\002rst)f(32)g(bits)h (of)f(the)g(UUID)1031 3134 y FJ(time_mid)p 2076 3164 V 696 w FN(the)h(ne)o(xt)e(16)h(bits)h(of)e(the)i(UUID)1031 3234 y FJ(time_hi_version)p 2076 3264 V 346 w FN(the)g(ne)o(xt)e(16)h (bits)h(of)e(the)i(UUID)1031 3334 y FJ(clock_seq_hi_variant)p 2076 3363 V 96 w FN(the)g(ne)o(xt)e(8)h(bits)h(of)f(the)g(UUID)1031 3433 y FJ(clock_seq_low)p 2076 3463 V 446 w FN(the)h(ne)o(xt)e(8)h (bits)h(of)f(the)g(UUID)1031 3533 y FJ(node)p 2076 3563 V 896 w FN(the)h(last)g(48)e(bits)i(of)f(the)g(UUID)1031 3632 y FJ(time)p 2076 3662 V 896 w FN(the)h(60-bit)e(timestamp)1031 3732 y FJ(clock_seq)p 2076 3762 V 646 w FN(the)i(14-bit)e(sequence)g (number)0 3870 y FD(hex)208 3969 y FN(The)g(UUID)i(as)g(a)f (32-character)e(he)o(xadecimal)g(string.)0 4116 y FD(int)208 4216 y FN(The)h(UUID)i(as)g(a)f(128-bit)f(inte)o(ger)-5 b(.)0 4363 y FD(urn)208 4462 y FN(The)19 b(UUID)i(as)g(a)f(URN)h(as)g (speci\002ed)f(in)g(RFC)i(4122.)0 4609 y FD(variant)208 4709 y FN(The)f(UUID)g(v)n(ariant,)f(which)h(determines)f(the)i (internal)e(layout)g(of)h(the)h(UUID.)f(This)g(will)h(be)g(one)e(of)h (the)h(inte)o(ger)e(constants)208 4809 y FJ(RESERVED_NCS)p FN(,)e FJ(RFC_4122)p FN(,)h FJ(RESERVED_MICROSOFT)p FN(,)e(or)j FJ(RESERVED_FUTURE)p FN(.)0 4955 y FD(version)208 5055 y FN(The)f(UUID)i(v)o(ersion)e(number)f(\(1)i(through)e(5,)i (meaningful)e(only)h(when)h(the)g(v)n(ariant)f(is)i FJ(RFC_4122)p FN(\).)0 5202 y(The)f FJ(uuid)g FN(module)f(de\002nes)h(the)g(follo)n (wing)e(functions:)0 5349 y FD(getnode)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(18.16.)52 b FJ(uuid)23 b FI(\227)g(UUID)g (objects)g(according)g(to)g(RFC)g(4122)1786 b(659)p eop end %%Page: 660 672 TeXDict begin 660 671 bop 208 83 a FN(Get)20 b(the)g(hardw)o(are)e (address)i(as)g(a)h(48-bit)d(positi)n(v)o(e)h(inte)o(ger)-5 b(.)25 b(The)19 b(\002rst)i(time)f(this)g(runs,)f(it)i(may)e(launch)g (a)i(separate)e(program,)208 183 y(which)d(could)g(be)h(quite)f(slo)n (w)-5 b(.)24 b(If)17 b(all)g(attempts)g(to)g(obtain)f(the)h(hardw)o (are)f(address)g(f)o(ail,)i(we)f(choose)f(a)h(random)f(48-bit)f(number) 208 282 y(with)26 b(its)h(eighth)e(bit)h(set)h(to)f(1)g(as)h (recommended)c(in)j(RFC)h(4122.)41 b(\224Hardw)o(are)25 b(address\224)h(means)f(the)h(MA)m(C)h(address)e(of)h(a)208 382 y(netw)o(ork)17 b(interf)o(ace,)h(and)h(on)f(a)h(machine)f(with)h (multiple)f(netw)o(ork)g(interf)o(aces)g(the)h(MA)m(C)h(address)e(of)h (an)o(y)f(one)g(of)h(them)f(may)208 482 y(be)i(returned.)0 628 y FD(uuid1)p FJ(\()p FC([)p FK(node)p FC([)p FK(,)d(cloc)n(k)p 760 628 25 4 v 30 w(seq)12 b FC(])g(])p FJ(\))208 728 y FN(Generate)24 b(a)h(UUID)g(from)f(a)h(host)g(ID,)g(sequence)e (number)m(,)h(and)g(the)h(current)f(time.)39 b(If)25 b FK(node)f FN(is)i(not)e(gi)n(v)o(en,)h FJ(getnode\(\))208 828 y FN(is)i(used)g(to)g(obtain)f(the)g(hardw)o(are)g(address.)44 b(If)26 b FK(cloc)n(k)p 1837 828 V 30 w(seq)h FN(is)g(gi)n(v)o(en,)g (it)h(is)f(used)g(as)g(the)g(sequence)f(number;)i(otherwise)e(a)208 927 y(random)18 b(14-bit)h(sequence)g(number)f(is)k(chosen.)0 1074 y FD(uuid3)p FJ(\()p FK(namespace)o(,)17 b(name)p FJ(\))208 1174 y FN(Generate)j(a)i(UUID)f(based)g(on)g(the)h(MD5)f (hash)g(of)g(a)h(namespace)e(identi\002er)g(\(which)h(is)h(a)g(UUID\))f (and)g(a)h(name)e(\(which)h(is)h(a)208 1273 y(string\).)0 1420 y FD(uuid4)p FJ(\(\))208 1520 y FN(Generate)d(a)i(random)d(UUID.)0 1667 y FD(uuid5)p FJ(\()p FK(namespace)o(,)f(name)p FJ(\))208 1766 y FN(Generate)j(a)i(UUID)f(based)g(on)g(the)g(SHA-1)g(hash)g(of)g (a)h(namespace)e(identi\002er)h(\(which)f(is)i(a)g(UUID\))f(and)g(a)h (name)e(\(which)h(is)208 1866 y(a)f(string\).)0 2013 y(The)g FJ(uuid)g FN(module)f(de\002nes)h(the)g(follo)n(wing)e (namespace)h(identi\002ers)h(for)g(use)g(with)h FJ(uuid3\(\))e FN(or)h FJ(uuid5\(\))p FN(.)0 2160 y FD(NAMESPACE_DNS)208 2259 y FN(When)g(this)g(namespace)f(is)i(speci\002ed,)f(the)g FK(name)g FN(string)g(is)h(a)f(fully-quali\002ed)e(domain)h(name.)0 2406 y FD(NAMESPACE_URL)208 2506 y FN(When)h(this)g(namespace)f(is)i (speci\002ed,)f(the)g FK(name)g FN(string)g(is)h(a)f(URL.)0 2653 y FD(NAMESPACE_OID)208 2752 y FN(When)g(this)g(namespace)f(is)i (speci\002ed,)f(the)g FK(name)g FN(string)g(is)h(an)f(ISO)g(OID.)0 2899 y FD(NAMESPACE_X500)208 2999 y FN(When)g(this)g(namespace)f(is)i (speci\002ed,)f(the)g FK(name)g FN(string)g(is)h(an)f(X.500)f(DN)i(in)f (DER)h(or)f(a)g(te)o(xt)g(output)f(format.)0 3146 y(The)h FJ(uuid)g FN(module)f(de\002nes)h(the)g(follo)n(wing)e(constants)i(for) g(the)g(possible)g(v)n(alues)g(of)g(the)g FJ(variant)f FN(attrib)n(ute:)0 3293 y FD(RESERVED_NCS)208 3392 y FN(Reserv)o(ed)g(for)h(NCS)h(compatibility)-5 b(.)0 3539 y FD(RFC_4122)208 3639 y FN(Speci\002es)20 b(the)g(UUID)h(layout)e(gi)n (v)o(en)g(in)h(RFC)i(4122.)0 3786 y FD(RESERVED_MICROSOFT)208 3885 y FN(Reserv)o(ed)d(for)h(Microsoft)f(compatibility)-5 b(.)0 4032 y FD(RESERVED_FUTURE)208 4132 y FN(Reserv)o(ed)19 b(for)h(future)f(de\002nition.)0 4279 y FL(See)i(Also:)0 4425 y FN(RFC)h(4122,)c(\223)p FK(A)j(Univer)o(sally)f(Unique)f (IDenti\002er)h(\(UUID\))f(URN)i(Namespace)p FN(\224)208 4525 y(This)f(speci\002cation)f(de\002nes)i(a)f(Uniform)f(Resource)h (Name)g(namespace)f(for)g(UUIDs,)i(the)f(internal)g(format)f(of)h (UUIDs,)g(and)208 4625 y(methods)f(of)h(generating)e(UUIDs.)0 4910 y Fv(18.16.1)101 b(Example)0 5113 y FN(Here)20 b(are)g(some)g(e)o (xamples)f(of)h(typical)g(usage)g(of)g(the)g FJ(uuid)g FN(module:)p 0 5549 3901 4 v 0 5649 a FI(660)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 661 673 TeXDict begin 661 672 bop 236 174 a FA(>>>)45 b(import)e(uuid)236 357 y(#)i(make)f(a)h(UUID)f(based)g(on)g(the)h(host)f(ID)g(and)h (current)e(time)236 448 y(>>>)i(uuid.uuid1\(\))236 540 y(UUID\('a8098c1a-f86e-11da-bd1a-00112444be)o(1e'\))236 722 y(#)g(make)f(a)h(UUID)f(using)g(an)g(MD5)h(hash)f(of)g(a)h (namespace)e(UUID)h(and)h(a)f(name)236 814 y(>>>)h (uuid.uuid3\(uuid.NAMESPACE_DNS,)39 b('python.org'\))236 905 y(UUID\('6fa459ea-ee8a-3ca4-894e-db77e16035)o(5e'\))236 1088 y(#)45 b(make)f(a)h(random)f(UUID)236 1179 y(>>>)h(uuid.uuid4\(\)) 236 1270 y(UUID\('16fd2706-8baf-433b-82eb-8c7fada847)o(da'\))236 1453 y(#)g(make)f(a)h(UUID)f(using)g(a)h(SHA-1)f(hash)g(of)g(a)h (namespace)e(UUID)h(and)h(a)f(name)236 1544 y(>>>)h (uuid.uuid5\(uuid.NAMESPACE_DNS,)39 b('python.org'\))236 1636 y(UUID\('886313e1-3b8a-5372-9b90-0c9aee199e)o(5d'\))236 1818 y(#)45 b(make)f(a)h(UUID)f(from)g(a)h(string)f(of)g(hex)g(digits)g (\(braces)g(and)g(hyphens)g(ignored\))236 1910 y(>>>)h(x)f(=)h (uuid.UUID\('{00010203-0405-0607-0809-0a)o(0b0c0d)o(0e0f}')o(\))236 2092 y(#)g(convert)f(a)g(UUID)g(to)h(a)g(string)e(of)i(hex)f(digits)g (in)g(standard)g(form)236 2183 y(>>>)h(str\(x\))236 2275 y('00010203-0405-0607-0809-0a0b0c0d0e0f')236 2457 y(#)g(get)f(the)h (raw)f(16)g(bytes)g(of)h(the)f(UUID)236 2549 y(>>>)h(x.bytes)236 2640 y('\\x00\\x01\\x02\\x03\\x04\\x05\\x06\\x07\\x08\\t\\)o(n\\x0b\\)o (x0c\\r\\)o(x0e\\x0)o(f')236 2823 y(#)g(make)f(a)h(UUID)f(from)g(a)h (16-byte)e(string)236 2914 y(>>>)i(uuid.UUID\(bytes=x.bytes\))236 3005 y(UUID\('00010203-0405-0607-0809-0a0b0c0d0e)o(0f'\))0 3515 y FE(18.17)122 b Fx(urlparse)31 b FE(\227)i(P)-5 b(arse)33 b(URLs)h(into)g(components)0 3748 y FN(This)27 b(module)e(de\002nes)h(a)h(standard)e(interf)o(ace)h(to)h(break)e (Uniform)g(Resource)h(Locator)f(\(URL\))i(strings)f(up)g(in)h (components)d(\(ad-)0 3848 y(dressing)g(scheme,)i(netw)o(ork)e (location,)h(path)g(etc.\),)h(to)f(combine)f(the)h(components)e(back)h (into)h(a)h(URL)f(string,)h(and)f(to)g(con)m(v)o(ert)e(a)0 3948 y(\223relati)n(v)o(e)c(URL)-8 b(\224)21 b(to)g(an)f(absolute)f (URL)i(gi)n(v)o(en)e(a)i(\223base)f(URL.)-6 b(\224)0 4094 y(The)26 b(module)f(has)h(been)g(designed)f(to)h(match)g(the)g (Internet)f(RFC)j(on)e(Relati)n(v)o(e)g(Uniform)e(Resource)i(Locators)g (\(and)f(disco)o(v)o(ered)0 4194 y(a)30 b(b)n(ug)f(in)g(an)g(earlier)g (draft!\).)51 b(It)30 b(supports)e(the)i(follo)n(wing)e(URL)i(schemes:) 43 b FJ(file)p FN(,)31 b FJ(ftp)p FN(,)h FJ(gopher)p FN(,)f FJ(hdl)p FN(,)g FJ(http)p FN(,)g FJ(https)p FN(,)0 4294 y FJ(imap)p FN(,)g FJ(mailto)p FN(,)g FJ(mms)p FN(,)h FJ(news)p FN(,)g FJ(nntp)p FN(,)f FJ(prospero)p FN(,)g FJ(rsync)p FN(,)g FJ(rtsp)p FN(,)g FJ(rtspu)p FN(,)g FJ(sftp)p FN(,)h FJ(shttp)p FN(,)f FJ(sip)p FN(,)h FJ(sips)p FN(,)f FJ(snews)p FN(,)0 4393 y FJ(svn)p FN(,)20 b FJ(svn+ssh)p FN(,)f FJ(telnet)p FN(,)h FJ(wais)p FN(.)0 4540 y(Ne)n(w)g(in)h(v)o (ersion)e(2.5:)g(Support)g(for)h(the)g FJ(sftp)g FN(and)f FJ(sips)h FN(schemes.)0 4687 y(The)g FJ(urlparse)f FN(module)g (de\002nes)h(the)g(follo)n(wing)f(functions:)0 4834 y FD(urlparse)p FJ(\()p FK(urlstring)p FC([)p FK(,)f(default)p 1057 4834 25 4 v 29 w(sc)o(heme)p FC([)p FK(,)h(allow)p 1595 4834 V 30 w(fr)o(a)o(gments)12 b FC(])g(])p FJ(\))208 4934 y FN(P)o(arse)28 b(a)h(URL)h(into)e(six)h(components,)g(returning) d(a)j(6-tuple.)49 b(This)29 b(corresponds)e(to)h(the)h(general)f (structure)f(of)i(a)g(URL:)208 5033 y FK(sc)o(heme)p FJ(://)p FK(netloc)p FJ(/)p FK(path)p FJ(;)p FK(par)o(ameter)o(s)p FJ(?)p FK(qu)o(ery)p FJ(#)p FK(fr)o(a)o(g)o(ment)q FN(.)34 b(Each)24 b(tuple)g(item)i(is)f(a)h(string,)f(possibly)f(empty)-5 b(.)38 b(The)24 b(com-)208 5133 y(ponents)19 b(are)i(not)g(brok)o(en)e (up)h(in)h(smaller)g(parts)g(\(for)f(e)o(xample,)f(the)i(netw)o(ork)f (location)g(is)h(a)h(single)e(string\),)h(and)f(\045)h(escapes)208 5232 y(are)e(not)g(e)o(xpanded.)j(The)c(delimiters)h(as)h(sho)n(wn)f (abo)o(v)o(e)e(are)i(not)g(part)g(of)g(the)g(result,)g(e)o(xcept)g(for) f(a)i(leading)e(slash)i(in)f(the)g FK(path)208 5332 y FN(component,)e(which)j(is)h(retained)e(if)h(present.)25 b(F)o(or)20 b(e)o(xample:)p 0 5549 3901 4 v 0 5649 a FI(18.17.)52 b FJ(urlparse)22 b FI(\227)h(P)m(arse)g(URLs)f(into)i (components)1876 b(661)p eop end %%Page: 662 674 TeXDict begin 662 673 bop 444 174 a FA(>>>)44 b(from)g(urlparse)g (import)g(urlparse)444 266 y(>>>)g(o)h(=)f (urlparse\('http://www.cwi.nl:80/\0457Eguido/Py)o(thon.h)o(tml'\))444 357 y(>>>)g(o)444 448 y(\('http',)f('www.cwi.nl:80',)f ('/\0457Eguido/Python.html',)f('',)k('',)f(''\))444 540 y(>>>)g(o.scheme)444 631 y('http')444 722 y(>>>)g(o.port)444 814 y(80)444 905 y(>>>)g(o.geturl\(\))444 996 y ('http://www.cwi.nl:80/\0457Eguido/Python.)o(html')208 1180 y FN(If)22 b(the)g FK(default)p 647 1180 25 4 v 29 w(sc)o(heme)g FN(ar)o(gument)e(is)j(speci\002ed,)f(it)h(gi)n(v)o(es) f(the)h(def)o(ault)e(addressing)g(scheme,)h(to)h(be)f(used)g(only)g(if) h(the)f(URL)208 1280 y(does)d(not)h(specify)g(one.)k(The)c(def)o(ault)g (v)n(alue)f(for)h(this)g(ar)o(gument)e(is)j(the)g(empty)e(string.)208 1407 y(If)29 b(the)g FK(allow)p 614 1407 V 29 w(fr)o(a)o(gments)g FN(ar)o(gument)e(is)j(f)o(alse,)i(fragment)c(identi\002ers)h(are)g(not) g(allo)n(wed,)h(e)n(v)o(en)e(if)i(the)f(URL)-8 b(')j(s)31 b(addressing)208 1506 y(scheme)19 b(normally)g(does)h(support)f(them.) 24 b(The)c(def)o(ault)f(v)n(alue)h(for)g(this)g(ar)o(gument)e(is)j FJ(True)p FN(.)208 1633 y(The)f(return)f(v)n(alue)h(is)i(actually)e(an) h(instance)f(of)g(a)h(subclass)g(of)g(tuple.)26 b(This)20 b(class)i(has)f(the)g(follo)n(wing)e(additional)g(read-only)208 1733 y(con)m(v)o(enience)e(attrib)n(utes:)708 1839 y FL(Attrib)n(ute)p 1154 1869 4 100 v 167 w(Index)p 1457 1869 V 99 w(V)-8 b(alue)p 2659 1869 V 1002 w(V)g(alue)21 b(if)f(not)g(pr)o(esent)p 658 1872 2792 4 v 708 1942 a FJ(scheme)p 1154 1972 4 100 v 279 w FN(0)p 1457 1972 V 179 w(URL)h(scheme)f(speci\002er)p 2659 1972 V 599 w(empty)g(string)708 2042 y FJ(netloc)p 1154 2072 V 279 w FN(1)p 1457 2072 V 179 w(Netw)o(ork)g(location)f(part)p 2659 2072 V 609 w(empty)h(string)708 2141 y FJ(path)p 1154 2171 V 379 w FN(2)p 1457 2171 V 179 w(Hierarchical)f(path)p 2659 2171 V 763 w(empty)h(string)708 2241 y FJ(params)p 1154 2271 V 279 w FN(3)p 1457 2271 V 179 w(P)o(arameters)g(for)f(last)i (path)f(element)p 2659 2271 V 268 w(empty)g(string)708 2341 y FJ(query)p 1154 2371 V 329 w FN(4)p 1457 2371 V 179 w(Query)g(component)p 2659 2371 V 737 w(empty)g(string)708 2440 y FJ(fragment)p 1154 2470 V 179 w FN(5)p 1457 2470 V 179 w(Fragment)f(identi\002er)p 2659 2470 V 698 w(empty)h(string)708 2540 y FJ(username)p 1154 2570 V 1457 2570 V 400 w FN(User)h(name)p 2659 2570 V 1088 w FJ(None)708 2640 y(password)p 1154 2669 V 1457 2669 V 400 w FN(P)o(assw)o(ord)p 2659 2669 V 1130 w FJ(None)708 2739 y(hostname)p 1154 2769 V 1457 2769 V 400 w FN(Host)g(name)f(\(lo)n(wer)f(case\))p 2659 2769 V 662 w FJ(None)708 2839 y(port)p 1154 2869 V 1457 2869 V 600 w FN(Port)i(number)d(as)j(inte)o(ger)m(,)d(if)j(present)p 2659 2869 V 343 w FJ(None)208 2961 y FN(See)f(section)g(18.17.1,)e (\223Results)j(of)f FJ(urlparse\(\))f FN(and)g FJ(urlsplit\(\))p FN(,)-6 b(\224)19 b(for)h(more)f(information)f(on)h(the)i(result)f (object.)208 3088 y(Changed)e(in)j(v)o(ersion)e(2.5:)g(Added)g(attrib)n (utes)i(to)f(return)f(v)n(alue.)0 3235 y FD(urlunparse)p FJ(\()p FK(parts)p FJ(\))208 3334 y FN(Construct)i(a)h(URL)g(from)f(a)h (tuple)g(as)g(returned)e(by)i FJ(urlparse\(\))p FN(.)28 b(The)22 b FK(parts)g FN(ar)o(gument)d(can)j(be)g(an)o(y)f(six-item)g (iterable.)208 3434 y(This)15 b(may)h(result)f(in)h(a)g(slightly)g(dif) n(ferent,)e(b)n(ut)i(equi)n(v)n(alent)e(URL,)i(if)g(the)g(URL)g(that)g (w)o(as)g(parsed)f(originally)f(had)h(unnecessary)208 3534 y(delimiters)k(\(for)h(e)o(xample,)e(a)j(?)k(with)c(an)f(empty)f (query;)g(the)h(RFC)i(states)f(that)f(these)h(are)f(equi)n(v)n (alent\).)0 3680 y FD(urlsplit)p FJ(\()p FK(urlstring)p FC([)p FK(,)e(default)p 1057 3680 25 4 v 29 w(sc)o(heme)p FC([)p FK(,)h(allow)p 1595 3680 V 30 w(fr)o(a)o(gments)12 b FC(])g(])p FJ(\))208 3780 y FN(This)25 b(is)i(similar)e(to)h FJ(urlparse\(\))p FN(,)f(b)n(ut)h(does)f(not)g(split)h(the)g(params)f (from)f(the)h(URL.)h(This)g(should)e(generally)g(be)i(used)208 3880 y(instead)h(of)g FJ(urlparse\(\))f FN(if)i(the)g(more)e(recent)h (URL)h(syntax)f(allo)n(wing)g(parameters)f(to)i(be)f(applied)g(to)g (each)h(se)o(gment)208 3979 y(of)c(the)h FK(path)e FN(portion)h(of)g (the)h(URL)g(\(see)g(RFC)h(2396\))d(is)i(w)o(anted.)38 b(A)25 b(separate)f(function)f(is)j(needed)d(to)i(separate)f(the)h (path)208 4079 y(se)o(gments)e(and)h(parameters.)36 b(This)25 b(function)d(returns)i(a)h(5-tuple:)32 b(\(addressing)23 b(scheme,)i(netw)o(ork)e(location,)h(path,)h(query)-5 b(,)208 4179 y(fragment)18 b(identi\002er\).)208 4306 y(The)i(return)f(v)n(alue)h(is)i(actually)e(an)h(instance)f(of)g(a)h (subclass)g(of)g(tuple.)26 b(This)20 b(class)i(has)f(the)g(follo)n (wing)e(additional)g(read-only)208 4405 y(con)m(v)o(enience)e(attrib)n (utes:)708 4512 y FL(Attrib)n(ute)p 1154 4542 4 100 v 167 w(Index)p 1457 4542 V 99 w(V)-8 b(alue)p 2659 4542 V 1002 w(V)g(alue)21 b(if)f(not)g(pr)o(esent)p 658 4545 2792 4 v 708 4615 a FJ(scheme)p 1154 4644 4 100 v 279 w FN(0)p 1457 4644 V 179 w(URL)h(scheme)f(speci\002er)p 2659 4644 V 599 w(empty)g(string)708 4714 y FJ(netloc)p 1154 4744 V 279 w FN(1)p 1457 4744 V 179 w(Netw)o(ork)g(location)f (part)p 2659 4744 V 609 w(empty)h(string)708 4814 y FJ(path)p 1154 4844 V 379 w FN(2)p 1457 4844 V 179 w(Hierarchical)f(path)p 2659 4844 V 763 w(empty)h(string)708 4913 y FJ(query)p 1154 4943 V 329 w FN(3)p 1457 4943 V 179 w(Query)g(component)p 2659 4943 V 737 w(empty)g(string)708 5013 y FJ(fragment)p 1154 5043 V 179 w FN(4)p 1457 5043 V 179 w(Fragment)f(identi\002er)p 2659 5043 V 698 w(empty)h(string)708 5113 y FJ(username)p 1154 5143 V 1457 5143 V 400 w FN(User)h(name)p 2659 5143 V 1088 w FJ(None)708 5212 y(password)p 1154 5242 V 1457 5242 V 400 w FN(P)o(assw)o(ord)p 2659 5242 V 1130 w FJ(None)708 5312 y(hostname)p 1154 5342 V 1457 5342 V 400 w FN(Host)g(name)f(\(lo)n (wer)f(case\))p 2659 5342 V 662 w FJ(None)708 5412 y(port)p 1154 5442 V 1457 5442 V 600 w FN(Port)i(number)d(as)j(inte)o(ger)m(,)d (if)j(present)p 2659 5442 V 343 w FJ(None)p 0 5549 3901 4 v 0 5649 a FI(662)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 663 675 TeXDict begin 663 674 bop 208 83 a FN(See)20 b(section)g(18.17.1,)e (\223Results)j(of)f FJ(urlparse\(\))f FN(and)g FJ(urlsplit\(\))p FN(,)-6 b(\224)19 b(for)h(more)f(information)f(on)h(the)i(result)f (object.)208 212 y(Ne)n(w)g(in)g(v)o(ersion)f(2.2.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.5:)h(Added)f(attrib)n(utes)h(to)g (return)f(v)n(alue.)0 359 y FD(urlunsplit)p FJ(\()p FK(parts)p FJ(\))208 459 y FN(Combine)27 b(the)h(elements)g(of)g(a)h(tuple)f(as)h (returned)d(by)i FJ(urlsplit\(\))f FN(into)h(a)h(complete)e(URL)i(as)g (a)f(string.)49 b(The)28 b FK(parts)208 558 y FN(ar)o(gument)19 b(can)k(be)f(an)o(y)f(\002)n(v)o(e-item)g(iterable.)31 b(This)23 b(may)e(result)i(in)f(a)h(slightly)f(dif)n(ferent,)f(b)n(ut)h (equi)n(v)n(alent)e(URL,)j(if)g(the)f(URL)208 658 y(that)j(w)o(as)h (parsed)e(originally)g(had)g(unnecessary)g(delimiters)g(\(for)g(e)o (xample,)h(a)h(?)40 b(with)25 b(an)g(empty)g(query;)h(the)f(RFC)i (states)208 758 y(that)20 b(these)g(are)g(equi)n(v)n(alent\).)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 904 y FD(urljoin)p FJ(\()p FK(base)o(,)f(url)p FC([)p FK(,)j(allow)p 960 904 25 4 v 29 w(fr)o(a)o(gments)12 b FC(])p FJ(\))208 1004 y FN(Construct)20 b(a)i(full)f(\(\223absolute\224\))f(URL)i(by)f (combining)e(a)i(\223base)h(URL)-8 b(\224)22 b(\()p FK(base)p FN(\))e(with)i(another)d(URL)j(\()p FK(url)p FN(\).)28 b(Informally)-5 b(,)19 b(this)208 1104 y(uses)24 b(components)e(of)i (the)g(base)g(URL,)g(in)h(particular)d(the)i(addressing)f(scheme,)h (the)g(netw)o(ork)f(location)g(and)h(\(part)f(of\))h(the)208 1203 y(path,)19 b(to)h(pro)o(vide)f(missing)h(components)e(in)i(the)g (relati)n(v)o(e)g(URL.)g(F)o(or)g(e)o(xample:)444 1424 y FA(>>>)44 b(from)g(urlparse)g(import)g(urljoin)444 1515 y(>>>)g(urljoin\('http://www.cwi.nl/\0457Eguido/Pyth)o(on.htm)o (l',)39 b('FAQ.html'\))444 1606 y ('http://www.cwi.nl/\0457Eguido/FAQ.html')208 1792 y FN(The)19 b FK(allow)p 547 1792 V 30 w(fr)o(a)o(gments)h FN(ar)o(gument)d(has)k(the)f(same)g(meaning)f(and)h(def)o(ault)f(as)i (for)f FJ(urlparse\(\))p FN(.)208 1921 y FL(Note:)31 b FN(If)24 b FK(url)g FN(is)h(an)f(absolute)f(URL)h(\(that)g(is,)h (starting)f(with)g FJ(//)g FN(or)f FJ(scheme://)p FN(,)h(the)g FK(url)p FN(')-5 b(s)24 b(host)g(name)f(and/or)g(scheme)208 2021 y(will)d(be)h(present)e(in)h(the)h(result.)k(F)o(or)19 b(e)o(xample:)444 2241 y FA(>>>)44 b (urljoin\('http://www.cwi.nl/\0457Eguido/Pyth)o(on.htm)o(l',)444 2333 y(...)403 b('//www.python.org/\0457Eguido'\))444 2424 y('http://www.python.org/\0457Eguido')208 2610 y FN(If)21 b(you)g(do)g(not)h(w)o(ant)f(that)h(beha)n(vior)m(,)e (preprocess)g(the)i FK(url)g FN(with)g FJ(urlsplit\(\))f FN(and)g FJ(urlunsplit\(\))p FN(,)f(remo)o(ving)f(pos-)208 2710 y(sible)h FK(sc)o(heme)g FN(and)g FK(netloc)f FN(parts.)0 2857 y FD(urldefrag)p FJ(\()p FK(url)p FJ(\))208 2956 y FN(If)32 b FK(url)h FN(contains)f(a)h(fragment)e(identi\002er)m(,)j (returns)e(a)h(modi\002ed)e(v)o(ersion)g(of)h FK(url)i FN(with)e(no)g(fragment)f(identi\002er)m(,)k(and)d(the)208 3056 y(fragment)22 b(identi\002er)i(as)g(a)h(separate)f(string.)36 b(If)24 b(there)g(is)h(no)f(fragment)f(identi\002er)g(in)h FK(url)p FN(,)i(returns)d FK(url)i FN(unmodi\002ed)d(and)i(an)208 3155 y(empty)19 b(string.)0 3302 y FL(See)i(Also:)0 3449 y FN(RFC)h(1738,)c(\223)p FK(Uniform)i(Resour)m(ce)g(Locator)o(s)g (\(URL\))p FN(\224)208 3549 y(This)g(speci\002es)h(the)f(formal)f (syntax)g(and)h(semantics)g(of)g(absolute)g(URLs.)0 3696 y(RFC)i(1808,)c(\223)p FK(Relative)i(Uniform)g(Resour)m(ce)g(Locator)o (s)p FN(\224)208 3795 y(This)30 b(Request)g(F)o(or)g(Comments)g (includes)f(the)h(rules)g(for)g(joining)f(an)h(absolute)f(and)h(a)h (relati)n(v)o(e)e(URL,)i(including)d(a)j(f)o(air)208 3895 y(number)18 b(of)i(\223)-7 b(Abnormal)18 b(Examples\224)i(which)f (go)o(v)o(ern)f(the)i(treatment)g(of)f(border)g(cases.)0 4042 y(RFC)j(2396,)c(\223)p FK(Uniform)i(Resour)m(ce)g(Identi\002er)o (s)f(\(URI\):)g(Generic)i(Syntax)p FN(\224)208 4141 y(Document)h (describing)h(the)h(generic)f(syntactic)h(requirements)e(for)i(both)f (Uniform)g(Resource)g(Names)i(\(URNs\))f(and)g(Uni-)208 4241 y(form)19 b(Resource)g(Locators)h(\(URLs\).)0 4523 y Fv(18.17.1)101 b(Results)28 b(of)g Fm(urlparse\(\))d Fv(and)k Fm(urlsplit\(\))0 4726 y FN(The)j(result)g(objects)g(from)e (the)j FJ(urlparse\(\))d FN(and)i FJ(urlsplit\(\))e FN(functions)h(are) h(subclasses)g(of)g(the)g(tuple)g(type.)60 b(These)0 4825 y(subclasses)21 b(add)e(the)h(attrib)n(utes)h(described)d(in)j (those)f(functions,)e(as)j(well)g(as)g(pro)o(vide)d(an)i(additional)f (method:)0 4972 y FD(geturl)p FJ(\(\))208 5072 y FN(Return)i(the)i (re-combined)c(v)o(ersion)i(of)h(the)g(original)f(URL)i(as)g(a)g (string.)30 b(This)23 b(may)f(dif)n(fer)f(from)g(the)h(original)f(URL)i (in)f(that)208 5171 y(the)16 b(scheme)g(will)h(al)o(w)o(ays)g(be)f (normalized)f(to)h(lo)n(wer)g(case)h(and)f(empty)g(components)e(may)i (be)g(dropped.)21 b(Speci\002cally)-5 b(,)16 b(empty)208 5271 y(parameters,)i(queries,)i(and)f(fragment)g(identi\002ers)g(will)i (be)g(remo)o(v)o(ed.)208 5400 y(The)e(result)i(of)f(this)g(method)f(is) i(a)g(\002xpoint)e(if)h(passed)h(back)e(through)f(the)i(original)f (parsing)g(function:)p 0 5549 3901 4 v 0 5649 a FI(18.17.)52 b FJ(urlparse)22 b FI(\227)h(P)m(arse)g(URLs)f(into)i(components)1876 b(663)p eop end %%Page: 664 676 TeXDict begin 664 675 bop 444 174 a FA(>>>)44 b(import)g(urlparse)444 266 y(>>>)g(url)g(=)h('HTTP://www.Python.org/doc/#')444 448 y(>>>)f(r1)h(=)f(urlparse.urlsplit\(url\))444 540 y(>>>)g(r1.geturl\(\))444 631 y('http://www.Python.org/doc/')444 814 y(>>>)g(r2)h(=)f(urlparse.urlsplit\(r1.geturl\(\)\))444 905 y(>>>)g(r2.geturl\(\))444 996 y('http://www.Python.org/doc/')208 1186 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)0 1333 y(The)h(follo)n (wing)e(classes)k(pro)o(vide)c(the)i(implementations)e(of)i(the)g (parse)g(results::)0 1479 y FL(class)h FD(BaseResult)208 1579 y FN(Base)26 b(class)h(for)e(the)h(concrete)f(result)h(classes.)43 b(This)26 b(pro)o(vides)e(most)i(of)g(the)g(attrib)n(ute)f (de\002nitions.)41 b(It)26 b(does)g(not)g(pro)o(vide)208 1679 y(a)i FJ(geturl\(\))f FN(method.)47 b(It)28 b(is)h(deri)n(v)o(ed)d (from)h FJ(tuple)p FN(,)i(b)n(ut)f(does)g(not)g(o)o(v)o(erride)d(the)j FJ(__init__\(\))f FN(or)h FJ(__new__\(\))208 1778 y FN(methods.)0 1925 y FL(class)21 b FD(ParseResult)p FJ(\()p FK(sc)o(heme)o(,)c (netloc,)j(path,)f(par)o(ams,)g(query)-5 b(,)20 b(fr)o(a)o(gment)q FJ(\))208 2025 y FN(Concrete)h(class)h(for)f FJ(urlparse\(\))g FN(results.)30 b(The)21 b FJ(__new__\(\))g FN(method)f(is)j(o)o(v)o (erridden)18 b(to)k(support)f(checking)f(that)i(the)208 2124 y(right)d(number)g(of)g(ar)o(guments)g(are)h(passed.)0 2271 y FL(class)h FD(SplitResult)p FJ(\()p FK(sc)o(heme)o(,)c(netloc,)j (path,)f(query)-5 b(,)20 b(fr)o(a)o(gment)q FJ(\))208 2371 y FN(Concrete)h(class)h(for)f FJ(urlsplit\(\))g FN(results.)30 b(The)21 b FJ(__new__\(\))g FN(method)f(is)j(o)o(v)o (erridden)18 b(to)k(support)f(checking)f(that)i(the)208 2471 y(right)d(number)g(of)g(ar)o(guments)g(are)h(passed.)0 2798 y FE(18.18)122 b Fx(SocketServer)30 b FE(\227)i(A)h(fr)o(ame)n(w)o (or)r(k)h(f)l(or)g(netw)o(or)r(k)g(ser)t(v)m(ers)0 3031 y FN(The)20 b FJ(SocketServer)e FN(module)h(simpli\002es)i(the)f(task)h (of)f(writing)f(netw)o(ork)g(serv)o(ers.)0 3178 y(There)30 b(are)h(four)f(basic)h(serv)o(er)f(classes:)48 b FJ(TCPServer)30 b FN(uses)h(the)g(Internet)f(TCP)i(protocol,)g(which)e(pro)o(vides)f (for)i(continuous)0 3277 y(streams)19 b(of)f(data)h(between)f(the)g (client)h(and)f(serv)o(er)-5 b(.)24 b FJ(UDPServer)18 b FN(uses)h(datagrams,)e(which)h(are)h(discrete)f(pack)o(ets)h(of)f (information)0 3377 y(that)32 b(may)f(arri)n(v)o(e)f(out)h(of)g(order)f (or)i(be)f(lost)h(while)g(in)f(transit.)59 b(The)31 b(more)g (infrequently)e(used)i FJ(UnixStreamServer)e FN(and)0 3477 y FJ(UnixDatagramServer)h FN(classes)j(are)f(similar)m(,)j(b)n(ut) e(use)h(U)t FH(N)t(I)t(X)h FN(domain)c(sock)o(ets;)39 b(the)o(y')l(re)31 b(not)h(a)n(v)n(ailable)f(on)h(non-)r(U)t FH(N)t(I)t(X)0 3576 y FN(platforms.)44 b(F)o(or)27 b(more)f(details)h (on)g(netw)o(ork)f(programming,)f(consult)h(a)h(book)f(such)h(as)g(W)-8 b(.)28 b(Richard)f(Ste)n(v)o(en')-5 b(s)26 b FK(UNIX)i(Network)0 3676 y(Pr)l(o)o(gr)o(amming)19 b FN(or)h(Ralph)g(Da)n(vis')-5 b(s)21 b FK(W)-5 b(in32)20 b(Network)h(Pr)l(o)o(gr)o(amming)p FN(.)0 3823 y(These)27 b(four)f(classes)i(process)f(requests)g FK(sync)o(hr)l(onously)p FN(;)i(each)e(request)f(must)i(be)f(completed) f(before)f(the)j(ne)o(xt)e(request)h(can)g(be)0 3922 y(started.)48 b(This)29 b(isn')o(t)e(suitable)h(if)g(each)g(request)f (tak)o(es)i(a)f(long)g(time)g(to)g(complete,)h(because)e(it)i(requires) e(a)h(lot)g(of)g(computation,)0 4022 y(or)c(because)g(it)h(returns)e(a) i(lot)f(of)g(data)g(which)g(the)g(client)h(is)g(slo)n(w)f(to)h (process.)37 b(The)23 b(solution)h(is)h(to)g(create)f(a)g(separate)g (process)g(or)0 4122 y(thread)f(to)g(handle)g(each)g(request;)i(the)e FJ(ForkingMixIn)f FN(and)h FJ(ThreadingMixIn)f FN(mix-in)g(classes)j (can)e(be)h(used)f(to)h(support)0 4221 y(asynchronous)17 b(beha)n(viour)-5 b(.)0 4368 y(Creating)44 b(a)h(serv)o(er)e(requires)g (se)n(v)o(eral)h(steps.)98 b(First,)51 b(you)44 b(must)g(create)g(a)h (request)f(handler)f(class)i(by)f(subclassing)g(the)0 4468 y FJ(BaseRequestHandler)20 b FN(class)j(and)f(o)o(v)o(erriding)d (its)k FJ(handle\(\))f FN(method;)g(this)h(method)e(will)i(process)f (incoming)e(requests.)0 4567 y(Second,)25 b(you)g(must)g(instantiate)g (one)g(of)g(the)h(serv)o(er)e(classes,)k(passing)d(it)h(the)f(serv)o (er')-5 b(s)25 b(address)g(and)g(the)g(request)g(handler)f(class.)0 4667 y(Finally)-5 b(,)19 b(call)h(the)g FJ(handle_request\(\))d FN(or)j FJ(serve_forever\(\))d FN(method)i(of)g(the)h(serv)o(er)f (object)g(to)h(process)f(one)g(or)h(man)o(y)0 4767 y(requests.)0 4913 y(When)j(inheriting)e(from)g FJ(ThreadingMixIn)g FN(for)h(threaded)f(connection)g(beha)n(vior)m(,)g(you)h(should)g(e)o (xplicitly)f(declare)h(ho)n(w)g(you)0 5013 y(w)o(ant)28 b(your)e(threads)g(to)i(beha)n(v)o(e)e(on)h(an)g(abrupt)f(shutdo)n(wn.) 45 b(The)27 b FJ(ThreadingMixIn)f FN(class)i(de\002nes)f(an)h(attrib)n (ute)f FK(daemon)p 3850 5013 25 4 v 27 w(-)0 5113 y(thr)m(eads)p FN(,)17 b(which)g(indicates)g(whether)g(or)g(not)g(the)h(serv)o(er)e (should)h(w)o(ait)h(for)f(thread)f(termination.)23 b(Y)-9 b(ou)17 b(should)f(set)j(the)e(\003ag)h(e)o(xplicitly)0 5212 y(if)24 b(you)f(w)o(ould)g(lik)o(e)i(threads)e(to)h(beha)n(v)o(e)f (autonomously;)g(the)h(def)o(ault)f(is)i FJ(False)p FN(,)f(meaning)e (that)i(Python)f(will)i(not)e(e)o(xit)h(until)g(all)0 5312 y(threads)c(created)f(by)h FJ(ThreadingMixIn)e FN(ha)n(v)o(e)h(e)o (xited.)p 0 5549 3901 4 v 0 5649 a FI(664)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 665 677 TeXDict begin 665 676 bop 0 83 a FN(Serv)o(er)19 b(classes)i(ha)n(v)o (e)f(the)g(same)h(e)o(xternal)e(methods)g(and)g(attrib)n(utes,)h(no)g (matter)g(what)g(netw)o(ork)f(protocol)f(the)o(y)i(use:)0 368 y Fv(18.18.1)101 b(Ser)s(v)n(er)29 b(Creation)g(Notes)0 571 y FN(There)19 b(are)h(\002)n(v)o(e)g(classes)i(in)e(an)g (inheritance)f(diagram,)f(four)h(of)h(which)g(represent)f(synchronous)f (serv)o(ers)h(of)h(four)f(types:)595 809 y FA(+------------+)595 900 y(|)45 b(BaseServer)e(|)595 992 y(+------------+)864 1083 y(|)864 1174 y(v)595 1266 y(+-----------+)356 b (+------------------+)595 1357 y(|)45 b(TCPServer)e(|------->|)g (UnixStreamServer)f(|)595 1448 y(+-----------+)356 b (+------------------+)864 1540 y(|)864 1631 y(v)595 1722 y(+-----------+)g(+--------------------+)595 1814 y(|)45 b(UDPServer)e(|------->|)g(UnixDatagramServer)f(|)595 1905 y(+-----------+)356 b(+--------------------+)0 2191 y FN(Note)20 b(that)g FJ(UnixDatagramServer)d FN(deri)n(v)o(es)i(from)g FJ(UDPServer)p FN(,)f(not)i(from)f FJ(UnixStreamServer)e FN(\227)k(the)f(only)f(dif)n(fer)n(-)0 2291 y(ence)26 b(between)f(an)h(IP)g(and)g(a)i(U)t FH(N)t(I)t(X)i FN(stream)25 b(serv)o(er)h(is)h(the)f(address)f(f)o(amily)-5 b(,)27 b(which)e(is)i(simply)f(repeated)f(in)h(both)h(U)t FH(N)t(I)t(X)i FN(serv)o(er)0 2391 y(classes.)0 2538 y(F)o(orking)55 b(and)i(threading)e(v)o(ersions)h(of)g(each)h(type)f(of)h(serv)o(er)f (can)h(be)f(created)h(using)f(the)h FJ(ForkingMixIn)e FN(and)0 2637 y FJ(ThreadingMixIn)18 b FN(mix-in)h(classes.)26 b(F)o(or)20 b(instance,)g(a)g(threading)f(UDP)h(serv)o(er)g(class)h(is) g(created)f(as)g(follo)n(ws:)416 2875 y FA(class)44 b (ThreadingUDPServer\(ThreadingMixIn,)39 b(UDPServer\):)k(pass)0 3162 y FN(The)25 b(mix-in)f(class)j(must)e(come)g(\002rst,)i(since)f (it)g(o)o(v)o(errides)e(a)h(method)f(de\002ned)h(in)g FJ(UDPServer)p FN(.)40 b(Setting)25 b(the)h(v)n(arious)e(member)0 3262 y(v)n(ariables)19 b(also)i(changes)e(the)h(beha)n(vior)f(of)h(the) g(underlying)d(serv)o(er)j(mechanism.)0 3408 y(T)-7 b(o)19 b(implement)e(a)i(service,)f(you)g(must)g(deri)n(v)o(e)f(a)i(class)h (from)d FJ(BaseRequestHandler)f FN(and)i(rede\002ne)f(its)j FJ(handle\(\))d FN(method.)0 3508 y(Y)-9 b(ou)26 b(can)h(then)g(run)f (v)n(arious)g(v)o(ersions)g(of)h(the)g(service)g(by)f(combining)f(one)i (of)f(the)h(serv)o(er)g(classes)h(with)f(your)f(request)g(handler)0 3608 y(class.)38 b(The)24 b(request)g(handler)f(class)i(must)f(be)h (dif)n(ferent)d(for)i(datagram)f(or)h(stream)g(services.)37 b(This)25 b(can)f(be)g(hidden)f(by)h(using)g(the)0 3707 y(handler)19 b(subclasses)h FJ(StreamRequestHandler)d FN(or)j FJ(DatagramRequestHandler)p FN(.)0 3854 y(Of)d(course,)g(you)f (still)i(ha)n(v)o(e)e(to)h(use)g(your)f(head!)23 b(F)o(or)17 b(instance,)g(it)g(mak)o(es)g(no)g(sense)g(to)g(use)g(a)h(forking)c (serv)o(er)j(if)g(the)g(service)f(contains)0 3954 y(state)25 b(in)f(memory)e(that)i(can)f(be)h(modi\002ed)f(by)g(dif)n(ferent)f (requests,)j(since)f(the)g(modi\002cations)e(in)i(the)g(child)f (process)h(w)o(ould)f(ne)n(v)o(er)0 4053 y(reach)e(the)g(initial)h (state)g(k)o(ept)f(in)h(the)f(parent)f(process)h(and)g(passed)h(to)f (each)g(child.)28 b(In)21 b(this)h(case,)g(you)f(can)g(use)h(a)f (threading)f(serv)o(er)m(,)0 4153 y(b)n(ut)g(you)f(will)i(probably)d (ha)n(v)o(e)i(to)g(use)h(locks)f(to)g(protect)f(the)i(inte)o(grity)d (of)i(the)h(shared)e(data.)0 4300 y(On)28 b(the)g(other)f(hand,)i(if)f (you)f(are)h(b)n(uilding)e(an)i(HTTP)g(serv)o(er)f(where)h(all)g(data)g (is)h(stored)e(e)o(xternally)g(\(for)g(instance,)i(in)f(the)g(\002le)0 4400 y(system\),)g(a)f(synchronous)d(class)k(will)g(essentially)f (render)e(the)i(service)f(\224deaf\224)g(while)h(one)f(request)g(is)i (being)e(handled)f(\226)i(which)0 4499 y(may)18 b(be)g(for)f(a)i(v)o (ery)e(long)g(time)i(if)f(a)h(client)f(is)h(slo)n(w)g(to)f(recei)n(v)o (e)f(all)i(the)f(data)g(it)h(has)f(requested.)23 b(Here)18 b(a)h(threading)d(or)i(forking)e(serv)o(er)0 4599 y(is)21 b(appropriate.)0 4746 y(In)j(some)g(cases,)i(it)f(may)f(be)g (appropriate)e(to)j(process)f(part)g(of)g(a)g(request)g(synchronously) -5 b(,)22 b(b)n(ut)i(to)g(\002nish)h(processing)e(in)h(a)h(fork)o(ed)0 4845 y(child)g(depending)d(on)i(the)h(request)g(data.)39 b(This)25 b(can)g(be)g(implemented)e(by)h(using)h(a)g(synchronous)d (serv)o(er)i(and)h(doing)e(an)i(e)o(xplicit)0 4945 y(fork)19 b(in)h(the)h(request)e(handler)g(class)i FJ(handle\(\))e FN(method.)0 5092 y(Another)29 b(approach)g(to)h(handling)f(multiple)h (simultaneous)f(requests)h(in)h(an)f(en)m(vironment)e(that)i(supports)g (neither)f(threads)h(nor)0 5191 y FJ(fork\(\))19 b FN(\(or)g(where)f (these)i(are)f(too)g(e)o(xpensi)n(v)o(e)f(or)h(inappropriate)d(for)j (the)h(service\))e(is)j(to)e(maintain)g(an)g(e)o(xplicit)g(table)g(of)g (partially)0 5291 y(\002nished)d(requests)h(and)g(to)g(use)g FJ(select\(\))f FN(to)h(decide)f(which)h(request)f(to)h(w)o(ork)g(on)f (ne)o(xt)h(\(or)f(whether)g(to)h(handle)f(a)i(ne)n(w)e(incoming)0 5391 y(request\).)32 b(This)24 b(is)g(particularly)d(important)g(for)i (stream)g(services)g(where)f(each)h(client)g(can)g(potentially)e(be)i (connected)f(for)g(a)h(long)p 0 5549 3901 4 v 0 5649 a FI(18.18.)52 b FJ(SocketServer)21 b FI(\227)i(A)h(fr)o(ame)n(w)o(or)q (k)f(f)n(or)g(netw)o(or)q(k)g(ser)r(v)n(ers)1560 b(665)p eop end %%Page: 666 678 TeXDict begin 666 677 bop 0 83 a FN(time)20 b(\(if)g(threads)g(or)g (subprocesses)f(cannot)g(be)h(used\).)0 368 y Fv(18.18.2)101 b(Ser)s(v)n(er)29 b(Objects)0 557 y FD(fileno)p FJ(\(\))208 656 y FN(Return)18 b(an)i(inte)o(ger)e(\002le)i(descriptor)e(for)h(the) g(sock)o(et)g(on)g(which)g(the)g(serv)o(er)g(is)h(listening.)k(This)c (function)d(is)j(most)g(commonly)208 756 y(passed)g(to)g FJ(select.select\(\))p FN(,)e(to)i(allo)n(w)g(monitoring)e(multiple)i (serv)o(ers)f(in)h(the)h(same)f(process.)0 903 y FD(handle_request)p FJ(\(\))208 1003 y FN(Process)j(a)h(single)g(request.)34 b(This)23 b(function)f(calls)i(the)g(follo)n(wing)e(methods)g(in)i (order:)30 b FJ(get_request\(\))p FN(,)22 b FJ(verify_-)208 1102 y(request\(\))p FN(,)15 b(and)g FJ(process_request\(\))p FN(.)21 b(If)15 b(the)h(user)n(-pro)o(vided)c FJ(handle\(\))j FN(method)f(of)i(the)f(handler)f(class)j(raises)208 1202 y(an)j(e)o(xception,)e(the)i(serv)o(er')-5 b(s)20 b FJ (handle_error\(\))e FN(method)h(will)i(be)f(called.)0 1349 y FD(serve_forever)p FJ(\(\))208 1448 y FN(Handle)f(an)h (in\002nite)g(number)f(of)h(requests.)k(This)c(simply)g(calls)h FJ(handle_request\(\))d FN(inside)i(an)g(in\002nite)g(loop.)0 1595 y FD(address_family)208 1695 y FN(The)25 b(f)o(amily)h(of)g (protocols)f(to)h(which)g(the)g(serv)o(er')-5 b(s)26 b(sock)o(et)g(belongs.)42 b FJ(socket.AF_INET)24 b FN(and)i FJ(socket.AF_UNIX)208 1794 y FN(are)20 b(tw)o(o)g(possible)g(v)n (alues.)0 1941 y FD(RequestHandlerClass)208 2041 y FN(The)f(user)n (-pro)o(vided)e(request)j(handler)f(class;)i(an)f(instance)g(of)g(this) g(class)i(is)f(created)e(for)h(each)g(request.)0 2188 y FD(server_address)208 2287 y FN(The)h(address)g(on)g(which)g(the)g (serv)o(er)g(is)i(listening.)28 b(The)21 b(format)g(of)g(addresses)g(v) n(aries)h(depending)d(on)i(the)g(protocol)f(f)o(amily;)208 2387 y(see)e(the)g(documentation)d(for)j(the)g(sock)o(et)g(module)e (for)i(details.)24 b(F)o(or)18 b(Internet)f(protocols,)g(this)h(is)h(a) g(tuple)e(containing)f(a)j(string)208 2487 y(gi)n(ving)f(the)j (address,)e(and)h(an)g(inte)o(ger)f(port)g(number:)24 b FJ(\('127.0.0.1',)47 b(80\))p FN(,)20 b(for)g(e)o(xample.)0 2634 y FD(socket)208 2733 y FN(The)f(sock)o(et)h(object)g(on)g(which)g (the)g(serv)o(er)f(will)i(listen)g(for)e(incoming)g(requests.)0 2880 y(The)h(serv)o(er)f(classes)i(support)e(the)i(follo)n(wing)d (class)j(v)n(ariables:)0 3027 y FD(allow_reuse_address)208 3127 y FN(Whether)h(the)g(serv)o(er)g(will)h(allo)n(w)g(the)f(reuse)h (of)f(an)g(address.)32 b(This)23 b(def)o(aults)f(to)h FJ(False)p FN(,)f(and)g(can)h(be)f(set)i(in)e(subclasses)h(to)208 3226 y(change)18 b(the)j(polic)o(y)-5 b(.)0 3373 y FD (request_queue_size)208 3473 y FN(The)22 b(size)i(of)e(the)h(request)f (queue.)32 b(If)22 b(it)i(tak)o(es)f(a)g(long)f(time)h(to)g(process)g (a)g(single)g(request,)f(an)o(y)g(requests)h(that)g(arri)n(v)o(e)f (while)208 3572 y(the)k(serv)o(er)f(is)i(b)n(usy)f(are)g(placed)f(into) h(a)h(queue,)f(up)g(to)g FJ(request_queue_size)d FN(requests.)43 b(Once)26 b(the)g(queue)f(is)i(full,)208 3672 y(further)17 b(requests)i(from)f(clients)i(will)g(get)f(a)h(\223Connection)d (denied\224)h(error)-5 b(.)24 b(The)19 b(def)o(ault)f(v)n(alue)h(is)h (usually)e(5,)i(b)n(ut)f(this)h(can)f(be)208 3772 y(o)o(v)o(erridden)d (by)k(subclasses.)0 3918 y FD(socket_type)208 4018 y FN(The)15 b(type)h(of)g(sock)o(et)g(used)g(by)f(the)h(serv)o(er;)h FJ(socket.SOCK_STREAM)c FN(and)j FJ(socket.SOCK_DGRAM)d FN(are)j(tw)o(o)h(possible)208 4118 y(v)n(alues.)0 4265 y(There)j(are)g(v)n(arious)g(serv)o(er)g(methods)f(that)i(can)g(be)f(o) o(v)o(erridden)e(by)i(subclasses)h(of)f(base)h(serv)o(er)f(classes)i (lik)o(e)f FJ(TCPServer)p FN(;)e(these)0 4364 y(methods)g(aren')o(t)g (useful)h(to)g(e)o(xternal)f(users)h(of)g(the)g(serv)o(er)g(object.)0 4511 y FD(finish_request)p FJ(\(\))208 4611 y FN(Actually)e(processes)h (the)g(request)f(by)g(instantiating)g FJ(RequestHandlerClass)e FN(and)j(calling)f(its)i FJ(handle\(\))e FN(method.)0 4758 y FD(get_request)p FJ(\(\))208 4857 y FN(Must)30 b(accept)g(a)h(request)f(from)f(the)h(sock)o(et,)j(and)c(return)h(a)g (2-tuple)f(containing)g(the)h FK(ne)o(w)h FN(sock)o(et)f(object)g(to)g (be)g(used)g(to)208 4957 y(communicate)18 b(with)i(the)g(client,)g(and) g(the)g(client')-5 b(s)21 b(address.)0 5104 y FD(handle_error)p FJ(\()p FK(r)m(equest,)c(client)p 1120 5104 25 4 v 30 w(addr)m(ess)p FJ(\))208 5203 y FN(This)g(function)f(is)j(called)f(if)g (the)f FJ(RequestHandlerClass)p FN(')-5 b(s)16 b FJ(handle\(\))g FN(method)h(raises)h(an)g(e)o(xception.)k(The)17 b(def)o(ault)208 5303 y(action)i(is)i(to)g(print)e(the)h(traceback)f(to)i(standard)e (output)g(and)g(continue)g(handling)f(further)h(requests.)p 0 5549 3901 4 v 0 5649 a FI(666)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 667 679 TeXDict begin 667 678 bop 0 83 a FD(process_request)p FJ(\()p FK(r)m(equest,)17 b(client)p 1270 83 25 4 v 29 w(addr)m(ess)p FJ(\))208 183 y FN(Calls)22 b FJ(finish_request\(\))c FN(to)j(create)f(an)h(instance)f(of)g(the)h FJ(RequestHandlerClass)p FN(.)j(If)c(desired,)g(this)h(function)208 282 y(can)d(create)g(a)g(ne) n(w)g(process)g(or)g(thread)f(to)i(handle)e(the)h(request;)h(the)f FJ(ForkingMixIn)f FN(and)g FJ(ThreadingMixIn)f FN(classes)208 382 y(do)j(this.)0 529 y FD(server_activate)p FJ(\(\))208 628 y FN(Called)29 b(by)g(the)g(serv)o(er')-5 b(s)29 b(constructor)f(to)h(acti)n(v)n(ate)g(the)g(serv)o(er)-5 b(.)52 b(The)29 b(def)o(ault)g(beha)n(vior)e(just)j FJ(listen)p FN(s)f(to)h(the)f(serv)o(er')-5 b(s)208 728 y(sock)o(et.)24 b(May)c(be)g(o)o(v)o(erridden.)0 875 y FD(server_bind)p FJ(\(\))208 975 y FN(Called)g(by)g(the)g(serv)o(er')-5 b(s)20 b(constructor)e(to)i(bind)g(the)g(sock)o(et)g(to)g(the)h (desired)e(address.)25 b(May)19 b(be)i(o)o(v)o(erridden.)0 1121 y FD(verify_request)p FJ(\()p FK(r)m(equest,)c(client)p 1220 1121 V 29 w(addr)m(ess)p FJ(\))208 1221 y FN(Must)27 b(return)g(a)h(Boolean)f(v)n(alue;)j(if)e(the)g(v)n(alue)e(is)j FJ(True)p FN(,)g(the)e(request)g(will)i(be)e(processed,)h(and)f(if)h (it')-5 b(s)29 b FJ(False)p FN(,)f(the)g(re-)208 1321 y(quest)d(will)i(be)f(denied.)41 b(This)26 b(function)e(can)i(be)g(o)o (v)o(erridden)c(to)k(implement)f(access)h(controls)f(for)h(a)g(serv)o (er)-5 b(.)42 b(The)25 b(def)o(ault)208 1420 y(implementation)18 b(al)o(w)o(ays)i(returns)f FJ(True)p FN(.)0 1705 y Fv(18.18.3)101 b(RequestHandler)30 b(Objects)0 1908 y FN(The)23 b(request)f(handler)f (class)j(must)f(de\002ne)f(a)i(ne)n(w)e FJ(handle\(\))g FN(method,)g(and)h(can)g(o)o(v)o(erride)d(an)o(y)i(of)h(the)g(follo)n (wing)e(methods.)32 b(A)0 2008 y(ne)n(w)20 b(instance)g(is)h(created)e (for)h(each)g(request.)0 2155 y FD(finish)p FJ(\(\))208 2254 y FN(Called)e(after)h(the)f FJ(handle\(\))g FN(method)f(to)i (perform)d(an)o(y)i(clean-up)f(actions)h(required.)23 b(The)18 b(def)o(ault)g(implementation)e(does)208 2354 y(nothing.)23 b(If)d FJ(setup\(\))f FN(or)h FJ(handle\(\))f FN(raise)i(an)f(e)o(xception,)e(this)j(function)d(will)j(not)f(be)g (called.)0 2501 y FD(handle)p FJ(\(\))208 2600 y FN(This)28 b(function)f(must)i(do)f(all)h(the)g(w)o(ork)f(required)f(to)i(service) f(a)h(request.)50 b(The)28 b(def)o(ault)g(implementation)e(does)j (nothing.)208 2700 y(Se)n(v)o(eral)20 b(instance)h(attrib)n(utes)g(are) g(a)n(v)n(ailable)g(to)g(it;)i(the)e(request)g(is)h(a)n(v)n(ailable)f (as)g FJ(self.request)p FN(;)g(the)g(client)g(address)g(as)208 2800 y FJ(self.client_address)p FN(;)j(and)h(the)g(serv)o(er)f (instance)h(as)h FJ(self.server)p FN(,)e(in)h(case)h(it)g(needs)e (access)i(to)f(per)n(-serv)o(er)208 2899 y(information.)208 3032 y(The)55 b(type)g(of)g FJ(self.request)f FN(is)j(dif)n(ferent)d (for)h(datagram)f(or)h(stream)h(services.)131 b(F)o(or)55 b(stream)h(services,)208 3132 y FJ(self.request)e FN(is)j(a)g(sock)o (et)f(object;)73 b(for)56 b(datagram)f(services,)64 b FJ(self.request)55 b FN(is)i(a)g(string.)132 b(Ho)n(w-)208 3231 y(e)n(v)o(er)m(,)68 b(this)60 b(can)f(be)h(hidden)e(by)h(using)g (the)g(request)g(handler)f(subclasses)i FJ(StreamRequestHandler)d FN(or)208 3331 y FJ(DatagramRequestHandler)p FN(,)51 b(which)d(o)o(v)o(erride)f(the)h FJ(setup\(\))g FN(and)g FJ(finish\(\))f FN(methods,)55 b(and)48 b(pro)o(vide)208 3431 y FJ(self.rfile)27 b FN(and)i FJ(self.wfile)e FN(attrib)n(utes.)51 b FJ(self.rfile)28 b FN(and)g FJ(self.wfile)g FN(can)g(be)h(read)g(or)f (written,)j(re-)208 3530 y(specti)n(v)o(ely)-5 b(,)18 b(to)i(get)h(the)f(request)f(data)h(or)g(return)f(data)h(to)h(the)f (client.)0 3677 y FD(setup)p FJ(\(\))208 3777 y FN(Called)d(before)e (the)i FJ(handle\(\))e FN(method)h(to)g(perform)f(an)o(y)h (initialization)g(actions)h(required.)k(The)c(def)o(ault)f (implementation)208 3876 y(does)j(nothing.)0 4204 y FE(18.19)122 b Fx(BaseHTTPServer)29 b FE(\227)k(Basic)f(HTTP)i(ser)t(v)m(er)0 4437 y FN(This)43 b(module)f(de\002nes)g(tw)o(o)i(classes)g(for)e (implementing)f(HTTP)i(serv)o(ers)f(\(W)-7 b(eb)44 b(serv)o(ers\).)92 b(Usually)-5 b(,)48 b(this)43 b(module)f(isn')o(t)0 4536 y(used)34 b(directly)-5 b(,)37 b(b)n(ut)d(is)i(used)e(as)h(a)g(basis)g (for)f(b)n(uilding)f(functioning)f(W)-7 b(eb)35 b(serv)o(ers.)67 b(See)35 b(the)f FJ(SimpleHTTPServer)e FN(and)0 4636 y FJ(CGIHTTPServer)18 b FN(modules.)0 4783 y(The)31 b(\002rst)g(class,) k FJ(HTTPServer)p FN(,)d(is)g(a)f FJ(SocketServer.TCPServer)c FN(subclass.)58 b(It)31 b(creates)g(and)f(listens)i(at)f(the)g(HTTP)0 4882 y(sock)o(et,)20 b(dispatching)e(the)j(requests)e(to)i(a)f(handler) -5 b(.)24 b(Code)c(to)h(create)f(and)f(run)h(the)g(serv)o(er)f(looks)h (lik)o(e)g(this:)p 0 5549 3901 4 v 0 5649 a FI(18.19.)52 b FJ(BaseHTTPServer)21 b FI(\227)i(Basic)g(HTTP)g(ser)r(v)n(er)1955 b(667)p eop end %%Page: 668 680 TeXDict begin 668 679 bop 236 174 a FA(def)45 b (run\(server_class=BaseHTTPServer.HTTP)o(Server)o(,)595 266 y(handler_class=BaseHTTPServer.BaseHTTPR)o(equest)o(Handle)o(r\):) 416 357 y(server_address)d(=)j(\('',)f(8000\))416 448 y(httpd)g(=)g(server_class\(server_address,)c(handler_class\))416 540 y(httpd.serve_forever\(\))0 826 y FL(class)21 b FD(HTTPServer)p FJ(\()p FK(server)p 949 826 25 4 v 28 w(addr)m(ess,)f (RequestHandlerClass)p FJ(\))208 926 y FN(This)c(class)h(b)n(uilds)e (on)h(the)g FJ(TCPServer)f FN(class)h(by)g(storing)f(the)h(serv)o(er)f (address)g(as)i(instance)f(v)n(ariables)f(named)f FJ(server_-)208 1026 y(name)25 b FN(and)f FJ(server_port)p FN(.)39 b(The)25 b(serv)o(er)f(is)i(accessible)g(by)f(the)g(handler)m(,)f(typically)h (through)e(the)i(handler')-5 b(s)24 b FJ(server)208 1125 y FN(instance)19 b(v)n(ariable.)0 1272 y FL(class)i FD (BaseHTTPRequestHandler)p FJ(\()p FK(r)m(equest,)15 b(client)p 1805 1272 V 30 w(addr)m(ess,)k(server)r FJ(\))208 1372 y FN(This)36 b(class)h(is)g(used)f(to)g(handle)f(the)h(HTTP)g(requests) g(that)g(arri)n(v)o(e)f(at)h(the)g(serv)o(er)-5 b(.)72 b(By)37 b(itself,)j(it)d(cannot)e(respond)f(to)208 1471 y(an)o(y)j(actual)i(HTTP)f(requests;)47 b(it)40 b(must)e(be)h (subclassed)f(to)g(handle)g(each)g(request)g(method)f(\(e.g.)79 b(GET)38 b(or)h(POST\).)208 1571 y FJ(BaseHTTPRequestHandler)25 b FN(pro)o(vides)j(a)h(number)f(of)g(class)j(and)d(instance)h(v)n (ariables,)h(and)f(methods)f(for)h(use)g(by)208 1671 y(subclasses.)208 1803 y(The)21 b(handler)e(will)j(parse)f(the)h (request)e(and)h(the)h(headers,)e(then)h(call)h(a)f(method)f (speci\002c)i(to)f(the)h(request)e(type.)28 b(The)21 b(method)208 1903 y(name)i(is)h(constructed)e(from)h(the)g(request.)35 b(F)o(or)23 b(e)o(xample,)g(for)g(the)g(request)g(method)f(`)p FJ(SPAM)p FN(',)h(the)g FJ(do_SPAM\(\))g FN(method)208 2003 y(will)g(be)g(called)f(with)h(no)g(ar)o(guments.)30 b(All)24 b(of)e(the)h(rele)n(v)n(ant)f(information)e(is)k(stored)e(in)h (instance)g(v)n(ariables)f(of)g(the)h(handler)-5 b(.)208 2102 y(Subclasses)20 b(should)f(not)h(need)g(to)g(o)o(v)o(erride)e(or)i (e)o(xtend)f(the)h FJ(__init__\(\))f FN(method.)0 2249 y FJ(BaseHTTPRequestHandler)e FN(has)j(the)g(follo)n(wing)f(instance)h (v)n(ariables:)0 2396 y FD(client_address)208 2496 y FN(Contains)g(a)g(tuple)g(of)g(the)g(form)f FJ(\()p FK(host)q FJ(,)50 b FK(port)q FJ(\))20 b FN(referring)e(to)j(the)f(client')-5 b(s)20 b(address.)0 2643 y FD(command)208 2742 y FN(Contains)g(the)g (command)e(\(request)h(type\).)24 b(F)o(or)c(e)o(xample,)f FJ('GET')p FN(.)0 2889 y FD(path)208 2989 y FN(Contains)h(the)g (request)f(path.)0 3136 y FD(request_version)208 3235 y FN(Contains)h(the)g(v)o(ersion)f(string)h(from)f(the)h(request.)k(F)o (or)c(e)o(xample,)f FJ('HTTP/1.0')p FN(.)0 3382 y FD(headers)208 3482 y FN(Holds)i(an)h(instance)g(of)g(the)g(class)h(speci\002ed)e(by)h (the)g FJ(MessageClass)e FN(class)j(v)n(ariable.)29 b(This)22 b(instance)g(parses)g(and)f(man-)208 3581 y(ages)f(the)g(headers)f(in)i (the)f(HTTP)g(request.)0 3728 y FD(rfile)208 3828 y FN(Contains)g(an)g (input)f(stream,)h(positioned)f(at)h(the)h(start)f(of)g(the)g(optional) f(input)h(data.)0 3975 y FD(wfile)208 4074 y FN(Contains)25 b(the)h(output)e(stream)i(for)f(writing)g(a)h(response)f(back)g(to)h (the)f(client.)42 b(Proper)24 b(adherence)g(to)i(the)f(HTTP)h(protocol) 208 4174 y(must)20 b(be)g(used)g(when)f(writing)h(to)g(this)h(stream.)0 4321 y FJ(BaseHTTPRequestHandler)c FN(has)j(the)g(follo)n(wing)f(class) i(v)n(ariables:)0 4468 y FD(server_version)208 4567 y FN(Speci\002es)32 b(the)g(serv)o(er)f(softw)o(are)g(v)o(ersion.)59 b(Y)-9 b(ou)32 b(may)f(w)o(ant)h(to)g(o)o(v)o(erride)e(this.)61 b(The)31 b(format)g(is)i(multiple)e(whitespace-)208 4667 y(separated)19 b(strings,)h(where)f(each)h(string)g(is)h(of)f(the)g (form)f(name[/v)o(ersion].)j(F)o(or)e(e)o(xample,)f FJ('BaseHTTP/0.2')p FN(.)0 4814 y FD(sys_version)208 4913 y FN(Contains)i(the)i(Python)d (system)j(v)o(ersion,)e(in)h(a)h(form)e(usable)g(by)h(the)g FJ(version_string)e FN(method)h(and)g(the)h FJ(server_-)208 5013 y(version)d FN(class)i(v)n(ariable.)j(F)o(or)c(e)o(xample,)e FJ('Python/1.4')p FN(.)0 5160 y FD(error_message_format)208 5260 y FN(Speci\002es)23 b(a)g(format)f(string)g(for)g(b)n(uilding)g (an)h(error)e(response)h(to)h(the)g(client.)33 b(It)23 b(uses)g(parenthesized,)f(k)o(e)o(yed)f(format)h(spec-)208 5359 y(i\002ers,)j(so)g(the)g(format)e(operand)f(must)j(be)f(a)h (dictionary)-5 b(.)35 b(The)24 b FK(code)g FN(k)o(e)o(y)g(should)f(be)i (an)f(inte)o(ger)m(,)g(specifying)f(the)h(numeric)p 0 5549 3901 4 v 0 5649 a FI(668)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 669 681 TeXDict begin 669 680 bop 208 83 a FN(HTTP)20 b(error)e(code)i(v)n (alue.)k FK(messa)o(g)o(e)c FN(should)f(be)h(a)g(string)f(containing)f (a)j(\(detailed\))d(error)h(message)h(of)g(what)f(occurred,)f(and)208 183 y FK(e)n(xplain)g FN(should)f(be)i(an)f(e)o(xplanation)f(of)h(the)h (error)e(code)h(number)-5 b(.)23 b(Def)o(ault)18 b FK(messa)o(g)o(e)h FN(and)f FK(e)n(xplain)g FN(v)n(alues)g(can)h(found)e(in)i(the)208 282 y FK(r)m(esponses)h FN(class)h(v)n(ariable.)0 429 y FD(protocol_version)208 529 y FN(This)28 b(speci\002es)h(the)g(HTTP)g (protocol)d(v)o(ersion)i(used)g(in)h(responses.)49 b(If)28 b(set)i(to)f FJ('HTTP/1.1')p FN(,)g(the)f(serv)o(er)g(will)h(permit)208 628 y(HTTP)22 b(persistent)g(connections;)g(ho)n(we)n(v)o(er)m(,)f (your)g(serv)o(er)g FK(must)i FN(then)f(include)f(an)i(accurate)e FJ(Content-Length)g FN(header)208 728 y(\(using)e FJ(send_header\(\))p FN(\))e(in)k(all)f(of)g(its)h(responses)e(to)h(clients.)26 b(F)o(or)19 b(backw)o(ards)g(compatibility)-5 b(,)18 b(the)i(setting)g(def)o(aults)f(to)208 828 y FJ('HTTP/1.0')p FN(.)0 975 y FD(MessageClass)208 1074 y FN(Speci\002es)31 b(a)g FJ(rfc822.Message)p FN(-lik)o(e)d(class)k(to)f(parse)g(HTTP)g (headers.)56 b(T)-7 b(ypically)i(,)32 b(this)f(is)h(not)f(o)o(v)o (erridden,)f(and)g(it)208 1174 y(def)o(aults)19 b(to)i FJ(mimetools.Message)p FN(.)0 1321 y FD(responses)208 1420 y FN(This)32 b(v)n(ariable)g(contains)f(a)i(mapping)e(of)h(error)f (code)h(inte)o(gers)g(to)g(tw)o(o-element)g(tuples)g(containing)f(a)h (short)g(and)g(long)208 1520 y(message.)k(F)o(or)24 b(e)o(xample,)g FJ({)p FK(code)p FJ(:)98 b(\()p FK(shortmessa)o(g)o(e)p FJ(,)49 b FK(longmessa)o(g)o(e)p FJ(\)})p FN(.)35 b(The)24 b FK(shortmessa)o(g)o(e)g FN(is)h(usually)f(used)g(as)h(the)208 1620 y FK(messa)o(g)o(e)g FN(k)o(e)o(y)h(in)g(an)f(error)g(response,)h (and)f FK(longmessa)o(g)o(e)g FN(as)h(the)g FK(e)n(xplain)f FN(k)o(e)o(y)g(\(see)h(the)g FJ(error_message_format)208 1719 y FN(class)21 b(v)n(ariable\).)0 1866 y(A)g FJ (BaseHTTPRequestHandler)16 b FN(instance)k(has)h(the)f(follo)n(wing)e (methods:)0 2013 y FD(handle)p FJ(\(\))208 2113 y FN(Calls)28 b FJ(handle_one_request\(\))c FN(once)j(\(or)m(,)h(if)g(persistent)f (connections)e(are)i(enabled,)h(multiple)f(times\))g(to)h(handle)208 2212 y(incoming)18 b(HTTP)i(requests.)25 b(Y)-9 b(ou)19 b(should)h(ne)n(v)o(er)e(need)i(to)g(o)o(v)o(erride)e(it;)j(instead,)f (implement)f(appropriate)f FJ(do_)3537 2227 y(*)3587 2212 y(\(\))h FN(meth-)208 2312 y(ods.)0 2459 y FD(handle_one_request)p FJ(\(\))208 2558 y FN(This)i(method)f(will)j(parse)e(and)g(dispatch)g (the)g(request)g(to)h(the)f(appropriate)e FJ(do_)2583 2573 y(*)2633 2558 y(\(\))i FN(method.)28 b(Y)-9 b(ou)21 b(should)f(ne)n(v)o(er)h(need)f(to)208 2658 y(o)o(v)o(erride)d(it.)0 2805 y FD(send_error)p FJ(\()p FK(code)p FC([)p FK(,)g(messa)o(g)o(e)12 b FC(])p FJ(\))208 2904 y FN(Sends)28 b(and)g(logs)h(a)g(complete)f (error)g(reply)g(to)h(the)f(client.)51 b(The)28 b(numeric)g FK(code)g FN(speci\002es)h(the)g(HTTP)g(error)e(code,)j(with)208 3004 y FK(messa)o(g)o(e)20 b FN(as)h(optional,)d(more)h(speci\002c)i (te)o(xt.)j(A)d(complete)e(set)i(of)e(headers)g(is)i(sent,)g(follo)n (wed)d(by)i(te)o(xt)g(composed)e(using)i(the)208 3104 y FJ(error_message_format)d FN(class)k(v)n(ariable.)0 3251 y FD(send_response)p FJ(\()p FK(code)p FC([)p FK(,)16 b(messa)o(g)o(e)c FC(])p FJ(\))208 3350 y FN(Sends)19 b(a)g(response)f(header)g(and)h(logs)g(the)g(accepted)f(request.)24 b(The)19 b(HTTP)g(response)f(line)i(is)g(sent,)f(follo)n(wed)f(by)h FK(Server)g FN(and)208 3450 y FK(Date)24 b FN(headers.)37 b(The)24 b(v)n(alues)g(for)g(these)h(tw)o(o)f(headers)g(are)h(pick)o (ed)e(up)h(from)g(the)g FJ(version_string\(\))e FN(and)i FJ(date_-)208 3549 y(time_string\(\))18 b FN(methods,)h(respecti)n(v)o (ely)-5 b(.)0 3696 y FD(send_header)p FJ(\()p FK(k)o(e)n(ywor)m(d,)17 b(value)p FJ(\))208 3796 y FN(Writes)26 b(a)g(speci\002c)g(HTTP)f (header)g(to)g(the)h(output)e(stream.)41 b FK(k)o(e)n(ywor)m(d)27 b FN(should)e(specify)g(the)g(header)g(k)o(e)o(yw)o(ord,)f(with)i FK(value)208 3896 y FN(specifying)18 b(its)j(v)n(alue.)0 4042 y FD(end_headers)p FJ(\(\))208 4142 y FN(Sends)f(a)g(blank)f (line,)i(indicating)d(the)j(end)e(of)h(the)g(HTTP)h(headers)e(in)h(the) h(response.)0 4289 y FD(log_request)p FJ(\()p FC([)p FK(code)p FC([)p FK(,)c(size)12 b FC(])g(])p FJ(\))208 4389 y FN(Logs)28 b(an)h(accepted)e(\(successful\))h(request.)50 b FK(code)28 b FN(should)g(specify)g(the)h(numeric)f(HTTP)g(code)h (associated)f(with)h(the)g(re-)208 4488 y(sponse.)24 b(If)c(a)h(size)g(of)e(the)i(response)e(is)i(a)n(v)n(ailable,)f(then)f (it)i(should)e(be)h(passed)h(as)f(the)h FK(size)g FN(parameter)-5 b(.)0 4635 y FD(log_error)p FJ(\()p FK(...)p FJ(\))208 4735 y FN(Logs)21 b(an)g(error)g(when)f(a)i(request)f(cannot)g(be)g (ful\002lled.)28 b(By)22 b(def)o(ault,)f(it)h(passes)h(the)e(message)h (to)f FJ(log_message\(\))p FN(,)f(so)i(it)208 4834 y(tak)o(es)e(the)g (same)h(ar)o(guments)d(\()p FK(format)j FN(and)f(additional)f(v)n (alues\).)0 4981 y FD(log_message)p FJ(\()p FK(format,)f(...)p FJ(\))208 5081 y FN(Logs)i(an)g(arbitrary)f(message)h(to)h FJ(sys.stderr)p FN(.)k(This)20 b(is)i(typically)d(o)o(v)o(erridden)f (to)i(create)g(custom)g(error)g(logging)f(mech-)208 5180 y(anisms.)25 b(The)19 b FK(format)i FN(ar)o(gument)c(is)k(a)f(standard) e(printf-style)h(format)f(string,)h(where)h(the)f(additional)g(ar)o (guments)e(to)j FJ(log_-)208 5280 y(message\(\))g FN(are)i(applied)g (as)g(inputs)g(to)g(the)g(formatting.)29 b(The)22 b(client)g(address)f (and)h(current)f(date)g(and)h(time)g(are)g(pre\002x)o(ed)208 5380 y(to)e(e)n(v)o(ery)f(message)h(logged.)p 0 5549 3901 4 v 0 5649 a FI(18.19.)52 b FJ(BaseHTTPServer)21 b FI(\227)i(Basic)g(HTTP)g(ser)r(v)n(er)1955 b(669)p eop end %%Page: 670 682 TeXDict begin 670 681 bop 0 83 a FD(version_string)p FJ(\(\))208 183 y FN(Returns)29 b(the)h(serv)o(er)e(softw)o(are')-5 b(s)30 b(v)o(ersion)e(string.)53 b(This)30 b(is)g(a)g(combination)d(of) j(the)f FJ(server_version)f FN(and)h FJ(sys_-)208 282 y(version)19 b FN(class)i(v)n(ariables.)0 429 y FD(date_time_string)p FJ(\()p FC([)p FK(timestamp)12 b FC(])p FJ(\))208 529 y FN(Returns)31 b(the)g(date)g(and)f(time)i(gi)n(v)o(en)e(by)g FK(timestamp)h FN(\(which)g(must)g(be)g(in)g(the)g(format)g(returned)e (by)i FJ(time.time\(\))p FN(\),)208 628 y(formatted)18 b(for)i(a)g(message)g(header)-5 b(.)24 b(If)d FK(timestamp)f FN(is)h(omitted,)e(it)i(uses)g(the)f(current)f(date)h(and)f(time.)208 761 y(The)e(result)g(looks)g(lik)o(e)h FJ('Sun,)48 b(06)i(Nov)f(1994)g (08:49:37)g(GMT')p FN(.)34 b(Ne)n(w)18 b(in)g(v)o(ersion)e(2.5:)h(The)g FK(timestamp)g FN(param-)208 861 y(eter)-5 b(.)0 1008 y FD(log_date_time_string)p FJ(\(\))208 1107 y FN(Returns)20 b(the)g(current)f(date)h(and)f(time,)h(formatted)f(for)h(logging.)0 1254 y FD(address_string)p FJ(\(\))208 1354 y FN(Returns)g(the)g (client)g(address,)g(formatted)e(for)i(logging.)j(A)e(name)e(lookup)f (is)k(performed)17 b(on)j(the)g(client')-5 b(s)21 b(IP)f(address.)0 1501 y FL(See)h(Also:)0 1648 y FN(Module)e FJ(CGIHTTPServer)f FN(\(section)i(18.21\):)208 1747 y(Extended)e(request)h(handler)g(that) h(supports)g(CGI)g(scripts.)0 1894 y(Module)f FJ(SimpleHTTPServer)f FN(\(section)h(18.20\):)208 1994 y(Basic)i(request)e(handler)g(that)h (limits)h(response)f(to)g(\002les)h(actually)f(under)e(the)j(document)d (root.)0 2321 y FE(18.20)122 b Fx(SimpleHTTPServer)29 b FE(\227)j(Simple)h(HTTP)g(request)i(handler)0 2554 y FN(The)111 b FJ(SimpleHTTPServer)f FN(module)g(de\002nes)h(a)h (request-handler)d(class,)135 b(interf)o(ace-compatible)108 b(with)0 2654 y FJ(BaseHTTPServer.BaseHTTPRequestHandl)o(er)p FN(,)15 b(that)20 b(serv)o(es)g(\002les)h(only)e(from)h(a)g(base)g (directory)-5 b(.)0 2800 y(The)20 b FJ(SimpleHTTPServer)e FN(module)g(de\002nes)i(the)h(follo)n(wing)d(class:)0 2947 y FL(class)j FD(SimpleHTTPRequestHandler)p FJ(\()p FK(r)m(equest,)15 b(client)p 1905 2947 25 4 v 29 w(addr)m(ess,)20 b(server)r FJ(\))208 3047 y FN(This)f(class)i(is)g(used)e(to)h(serv)o (e)f(\002les)i(from)e(the)g(current)g(directory)f(and)h(belo)n(w)-5 b(,)18 b(directly)h(mapping)f(the)i(directory)e(structure)g(to)208 3147 y(HTTP)i(requests.)208 3279 y(A)106 b(lot)h(of)f(the)g(w)o(ork,) 127 b(such)106 b(as)h(parsing)e(the)i(request,)127 b(is)107 b(done)e(by)h(the)g(base)h(class)208 3379 y FJ (BaseHTTPServer.BaseHTTPRequestHan)o(dler)p FN(.)73 b(This)39 b(class)g(implements)e(the)i FJ(do_GET\(\))e FN(and)h FJ(do_-)208 3479 y(HEAD\(\))19 b FN(functions.)0 3626 y(The)h FJ(SimpleHTTPRequestHandler)c FN(de\002nes)k(the)g(follo)n (wing)f(member)g(v)n(ariables:)0 3772 y FD(server_version)208 3872 y FN(This)h(will)h(be)f FJ("SimpleHTTP/")47 b(+)j(__version__)p FN(,)18 b(where)i FJ(__version__)f FN(is)i(de\002ned)e(in)h(the)h (module.)0 4019 y FD(extensions_map)208 4119 y FN(A)h(dictionary)e (mapping)f(suf)n(\002x)o(es)i(into)h(MIME)f(types.)29 b(The)21 b(def)o(ault)g(is)i(signi\002ed)e(by)g(an)h(empty)e(string,)i (and)f(is)h(considered)208 4218 y(to)h(be)g FJ (application/octet-stream)p FN(.)30 b(The)23 b(mapping)e(is)j(used)f (case-insensiti)n(v)o(ely)-5 b(,)22 b(and)h(so)g(should)f(contain)g (only)208 4318 y(lo)n(wer)n(-cased)d(k)o(e)o(ys.)0 4465 y(The)h FJ(SimpleHTTPRequestHandler)c FN(de\002nes)k(the)g(follo)n (wing)f(methods:)0 4612 y FD(do_HEAD)p FJ(\(\))208 4711 y FN(This)f(method)f(serv)o(es)h(the)g FJ('HEAD')f FN(request)h(type:) 24 b(it)18 b(sends)h(the)f(headers)f(it)i(w)o(ould)e(send)h(for)g(the)g (equi)n(v)n(alent)e FJ(GET)i FN(request.)208 4811 y(See)i(the)g FJ(do_GET\(\))g FN(method)e(for)i(a)h(more)e(complete)g(e)o(xplanation) f(of)i(the)g(possible)g(headers.)0 4958 y FD(do_GET)p FJ(\(\))208 5057 y FN(The)c(request)f(is)j(mapped)c(to)j(a)g(local)f (\002le)h(by)f(interpreting)e(the)i(request)g(as)h(a)g(path)f(relati)n (v)o(e)f(to)i(the)f(current)f(w)o(orking)g(directory)-5 b(.)208 5190 y(If)42 b(the)g(request)f(w)o(as)i(mapped)e(to)h(a)h (directory)-5 b(,)45 b(the)d(directory)f(is)i(check)o(ed)e(for)g(a)i (\002le)g(named)e FJ(index.html)g FN(or)208 5290 y FJ(index.htm)25 b FN(\(in)i(that)g(order\).)43 b(If)26 b(found,)h(the)g(\002le')-5 b(s)27 b(contents)f(are)h(returned;)i(otherwise)d(a)h(directory)e (listing)i(is)h(gener)n(-)208 5389 y(ated)22 b(by)g(calling)g(the)h FJ(list_directory\(\))d FN(method.)31 b(This)23 b(method)e(uses)i FJ(os.listdir\(\))e FN(to)i(scan)f(the)h(directory)-5 b(,)p 0 5549 3901 4 v 0 5649 a FI(670)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 671 683 TeXDict begin 671 682 bop 208 83 a FN(and)19 b(returns)g(a)i FJ(404)f FN(error)f(response)h(if)g(the)g FJ(listdir\(\))f FN(f)o(ails.)208 216 y(If)27 b(the)h(request)f(w)o(as)i(mapped)d(to)i (a)g(\002le,)j(it)d(is)h(opened)d(and)h(the)h(contents)f(are)h (returned.)46 b(An)o(y)27 b FJ(IOError)g FN(e)o(xception)f(in)208 315 y(opening)e(the)j(requested)e(\002le)i(is)h(mapped)d(to)i(a)g FJ(404)p FN(,)h FJ('File)49 b(not)g(found')26 b FN(error)-5 b(.)44 b(Otherwise,)27 b(the)g(content)e(type)i(is)208 415 y(guessed)19 b(by)h(calling)g(the)g FJ(guess_type\(\))e FN(method,)h(which)h(in)g(turn)f(uses)i(the)f FK(e)n(xtensions)p 2972 415 25 4 v 29 w(map)g FN(v)n(ariable.)208 548 y(A)c FJ('Content-type:')k FN(header)14 b(with)i(the)f(guessed)g(content)g (type)g(is)h(output,)f(follo)n(wed)f(by)h(a)h FJ('Content-Length:')208 648 y FN(header)j(with)h(the)g(\002le')-5 b(s)21 b(size)g(and)f(a)g FJ('Last-Modified:')j FN(header)c(with)i(the)f(\002le')-5 b(s)21 b(modi\002cation)e(time.)208 780 y(Then)j(follo)n(ws)h(a)h (blank)f(line)g(signifying)f(the)h(end)g(of)h(the)f(headers,)g(and)g (then)g(the)h(contents)e(of)i(the)f(\002le)h(are)g(output.)33 b(If)24 b(the)208 880 y(\002le')-5 b(s)21 b(MIME)f(type)f(starts)i (with)g FJ(text/)e FN(the)i(\002le)g(is)g(opened)d(in)j(te)o(xt)f (mode;)f(otherwise)g(binary)g(mode)g(is)j(used.)208 1013 y(F)o(or)48 b(e)o(xample)g(usage,)55 b(see)50 b(the)f(implementation)d (of)j(the)g FJ(test\(\))f FN(function.)222 b(Ne)n(w)49 b(in)g(v)o(ersion)f(2.5:)g(The)208 1112 y FJ('Last-Modified')18 b FN(header)-5 b(.)0 1259 y FL(See)21 b(Also:)0 1406 y FN(Module)e FJ(BaseHTTPServer)f FN(\(section)i(18.19\):)208 1506 y(Base)h(class)g(implementation)d(for)h(W)-7 b(eb)21 b(serv)o(er)f(and)f(request)h(handler)-5 b(.)0 1833 y FE(18.21)122 b Fx(CGIHTTPServer)29 b FE(\227)k(CGI-capab)n(le)i(HTTP)e (request)i(handler)0 2066 y FN(The)160 b FJ(CGIHTTPServer)e FN(module)g(de\002nes)i(a)g(request-handler)d(class,)196 b(interf)o(ace)159 b(compati-)0 2166 y(ble)164 b(with)h FJ(BaseHTTPServer.BaseHTTPRequestHan)o(dler)158 b FN(and)164 b(inherits)g(beha)n(vior)f(from)0 2265 y FJ (SimpleHTTPServer.SimpleHTTPRequestH)o(andler)14 b FN(b)n(ut)20 b(can)g(also)h(run)e(CGI)i(scripts.)0 2412 y FL(Note:)j FN(This)19 b(module)f(can)h(run)g(CGI)g(scripts)h(on)h(U)t FH(N)t(I)t(X)h FN(and)d(W)m(indo)n(ws)f(systems;)i(on)f(Mac)g(OS)h(it)g (will)g(only)f(be)g(able)g(to)g(run)g(Python)0 2512 y(scripts)i(within) e(the)i(same)f(process)g(as)h(itself.)0 2659 y FL(Note:)i FN(CGI)18 b(scripts)g(run)e(by)h(the)h FJ(CGIHTTPRequestHandler)c FN(class)k(cannot)e(e)o(x)o(ecute)g(redirects)h(\(HTTP)g(code)g(302\),) f(because)0 2758 y(code)k(200)f(\(script)h(output)f(follo)n(ws\))g(is)i (sent)g(prior)e(to)h(e)o(x)o(ecution)e(of)i(the)g(CGI)h(script.)k(This) 20 b(pre-empts)f(the)h(status)h(code.)0 2905 y(The)f FJ(CGIHTTPServer)e FN(module)h(de\002nes)h(the)g(follo)n(wing)f(class:) 0 3052 y FL(class)i FD(CGIHTTPRequestHandler)p FJ(\()p FK(r)m(equest,)16 b(client)p 1756 3052 V 29 w(addr)m(ess,)k(server)r FJ(\))208 3152 y FN(This)48 b(class)h(is)g(used)f(to)g(serv)o(e)g (either)f(\002les)i(or)f(output)f(of)h(CGI)h(scripts)f(from)f(the)h (current)f(directory)f(and)i(be-)208 3251 y(lo)n(w)-5 b(.)138 b(Note)58 b(that)h(mapping)d(HTTP)j(hierarchic)d(structure)i (to)g(local)g(directory)f(structure)g(is)i(e)o(xactly)e(as)i(in)208 3351 y FJ(SimpleHTTPServer.SimpleHTTPReques)o(tHand)o(ler)p FN(.)208 3484 y(The)19 b(class)i(will)g(ho)n(we)n(v)o(er)m(,)c(run)i (the)h(CGI)g(script,)g(instead)g(of)f(serving)g(it)i(as)f(a)h(\002le,)f (if)g(it)h(guesses)f(it)h(to)f(be)f(a)i(CGI)f(script.)25 b(Only)208 3583 y(directory-based)14 b(CGI)j(are)g(used)g(\227)h(the)f (other)f(common)f(serv)o(er)i(con\002guration)d(is)k(to)f(treat)g (special)h(e)o(xtensions)e(as)h(denoting)208 3683 y(CGI)j(scripts.)208 3816 y(The)25 b FJ(do_GET\(\))g FN(and)g FJ(do_HEAD\(\))g FN(functions)f(are)i(modi\002ed)f(to)h(run)f(CGI)h(scripts)g(and)f (serv)o(e)h(the)g(output,)f(instead)h(of)208 3916 y(serving)19 b(\002les,)i(if)f(the)g(request)g(leads)g(to)h(some)n(where)d(belo)n(w) i(the)g FJ(cgi_directories)e FN(path.)0 4062 y(The)i FJ(CGIHTTPRequestHandler)d FN(de\002nes)j(the)g(follo)n(wing)e(data)i (member:)0 4209 y FD(cgi_directories)208 4309 y FN(This)g(def)o(aults)g (to)g FJ(['/cgi-bin',)48 b('/htbin'])19 b FN(and)g(describes)h (directories)f(to)i(treat)f(as)h(containing)d(CGI)j(scripts.)0 4456 y(The)f FJ(CGIHTTPRequestHandler)d FN(de\002nes)j(the)g(follo)n (wing)e(methods:)0 4603 y FD(do_POST)p FJ(\(\))208 4702 y FN(This)g(method)f(serv)o(es)i(the)f FJ('POST')g FN(request)g(type,)g (only)g(allo)n(wed)g(for)g(CGI)h(scripts.)25 b(Error)17 b(501,)h(\224Can)g(only)g(POST)h(to)g(CGI)208 4802 y(scripts\224,)h(is) h(output)e(when)g(trying)g(to)i(POST)g(to)f(a)h(non-CGI)d(url.)0 4949 y(Note)i(that)h(CGI)f(scripts)h(will)g(be)f(run)g(with)g(UID)g(of) g(user)g(nobody)-5 b(,)18 b(for)h(security)h(reasons.)k(Problems)c (with)g(the)h(CGI)f(script)h(will)g(be)0 5048 y(translated)f(to)g (error)f(403.)0 5195 y(F)o(or)h(e)o(xample)f(usage,)g(see)i(the)f (implementation)e(of)i(the)g FJ(test\(\))g FN(function.)0 5342 y FL(See)h(Also:)p 0 5549 3901 4 v 0 5649 a FI(18.21.)52 b FJ(CGIHTTPServer)21 b FI(\227)i(CGI-capab)n(le)h(HTTP)e(request)h (handler)1400 b(671)p eop end %%Page: 672 684 TeXDict begin 672 683 bop 0 83 a FN(Module)19 b FJ(BaseHTTPServer)f FN(\(section)i(18.19\):)208 183 y(Base)h(class)g(implementation)d(for)h (W)-7 b(eb)21 b(serv)o(er)f(and)f(request)h(handler)-5 b(.)0 510 y FE(18.22)122 b Fx(cookielib)30 b FE(\227)j(Cookie)i (handling)g(f)l(or)f(HTTP)f(clients)0 743 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 890 y(The)f FJ(cookielib)g FN(module)f(de\002nes)h(classes)i(for)e(automatic)g(handling)e(of)j (HTTP)f(cookies.)24 b(It)19 b(is)h(useful)e(for)g(accessing)g(web)g (sites)0 989 y(that)k(require)e(small)i(pieces)g(of)g(data)f(\226)h FK(cookies)f FN(\226)h(to)g(be)g(set)g(on)g(the)f(client)h(machine)f (by)g(an)h(HTTP)g(response)e(from)h(a)h(web)g(serv)o(er)m(,)0 1089 y(and)e(then)f(returned)g(to)h(the)g(serv)o(er)g(in)g(later)g (HTTP)h(requests.)0 1236 y(Both)g(the)g(re)o(gular)f(Netscape)h(cookie) f(protocol)g(and)g(the)h(protocol)f(de\002ned)g(by)h(RFC)i(2965)c(are)i (handled.)27 b(RFC)22 b(2965)e(handling)g(is)0 1336 y(switched)d(of)n (f)g(by)g(def)o(ault.)23 b(RFC)c(2109)d(cookies)h(are)g(parsed)g(as)h (Netscape)f(cookies)g(and)g(subsequently)f(treated)g(either)i(as)g (Netscape)0 1435 y(or)25 b(RFC)h(2965)e(cookies)g(according)f(to)i(the) g('polic)o(y')e(in)i(ef)n(fect.)39 b(Note)25 b(that)g(the)g(great)g (majority)e(of)i(cookies)f(on)h(the)g(Internet)f(are)0 1535 y(Netscape)c(cookies.)k FJ(cookielib)19 b FN(attempts)h(to)g (follo)n(w)f(the)h(de-f)o(acto)f(Netscape)h(cookie)f(protocol)f (\(which)h(dif)n(fers)g(substantially)0 1634 y(from)26 b(that)h(set)g(out)g(in)g(the)g(original)e(Netscape)i (speci\002cation\),)g(including)e(taking)h(note)h(of)f(the)h FJ(max-age)f FN(and)g FJ(port)h FN(cookie-)0 1734 y(attrib)n(utes)e (introduced)e(with)i(RFC)i(2965.)38 b FL(Note:)d FN(The)25 b(v)n(arious)f(named)g(parameters)g(found)f(in)i FO(Set-Cookie:)33 b FN(and)25 b FO(Set-Cookie2:)0 1834 y FN(headers)e(\(e)o(g.)35 b FJ(domain)23 b FN(and)g FJ(expires)p FN(\))g(are)h(con)m(v)o (entionally)c(referred)i(to)i(as)g FK(attrib)n(utes)p FN(.)36 b(T)-7 b(o)24 b(distinguish)f(them)g(from)g(Python)0 1933 y(attrib)n(utes,)d(the)g(documentation)d(for)j(this)h(module)d (uses)j(the)f(term)g FK(cookie-attrib)n(ute)f FN(instead.)0 2080 y(The)h(module)f(de\002nes)h(the)g(follo)n(wing)e(e)o(xception:)0 2227 y FL(exception)h FD(LoadError)208 2327 y FN(Instances)d(of)h FJ(FileCookieJar)e FN(raise)i(this)g(e)o(xception)f(on)g(f)o(ailure)g (to)h(load)g(cookies)f(from)g(a)h(\002le.)25 b FL(Note:)e FN(F)o(or)16 b(backw)o(ards-)208 2426 y(compatibility)i(with)j(Python)e (2.4)g(\(which)g(raised)h(an)h FJ(IOError)p FN(\),)d FJ(LoadError)h FN(is)j(a)e(subclass)h(of)f FJ(IOError)p FN(.)0 2573 y(The)g(follo)n(wing)e(classes)k(are)e(pro)o(vided:)0 2720 y FL(class)h FD(CookieJar)p FJ(\()p FK(policy=)p Fn(None)p FJ(\))208 2820 y FK(policy)e FN(is)i(an)f(object)g (implementing)e(the)i FJ(CookiePolicy)f FN(interf)o(ace.)208 2952 y(The)29 b FJ(CookieJar)f FN(class)i(stores)g(HTTP)f(cookies.)52 b(It)29 b(e)o(xtracts)g(cookies)g(from)f(HTTP)h(requests,)i(and)e (returns)f(them)h(in)208 3052 y(HTTP)24 b(responses.)37 b FJ(CookieJar)23 b FN(instances)i(automatically)e(e)o(xpire)g (contained)f(cookies)i(when)g(necessary)-5 b(.)36 b(Subclasses)208 3152 y(are)20 b(also)g(responsible)f(for)h(storing)f(and)h(retrie)n (ving)e(cookies)i(from)f(a)h(\002le)h(or)f(database.)0 3299 y FL(class)h FD(FileCookieJar)p FJ(\()p FK(\002lename)o(,)16 b(delayload=)p Fn(None)p FK(,)h(policy=)p Fn(None)p FJ(\))208 3398 y FK(policy)k FN(is)j(an)e(object)g(implementing)e(the)j FJ(CookiePolicy)d FN(interf)o(ace.)31 b(F)o(or)22 b(the)g(other)g(ar)o (guments,)f(see)i(the)f(documenta-)208 3498 y(tion)d(for)h(the)g (corresponding)d(attrib)n(utes.)208 3631 y(A)26 b FJ(CookieJar)e FN(which)h(can)h(load)f(cookies)g(from,)h(and)f(perhaps)f(sa)n(v)o(e)i (cookies)f(to,)i(a)f(\002le)g(on)f(disk.)41 b(Cookies)26 b(are)f FL(NO)m(T)208 3730 y FN(loaded)e(from)g(the)i(named)e(\002le)i (until)f(either)g(the)h FJ(load\(\))f FN(or)g FJ(revert\(\))f FN(method)g(is)i(called.)38 b(Subclasses)25 b(of)f(this)h(class)208 3830 y(are)20 b(documented)d(in)k(section)f(18.22.2.)0 3977 y FL(class)h FD(CookiePolicy)p FJ(\(\))208 4076 y FN(This)f(class)h(is)g(responsible)e(for)h(deciding)e(whether)i(each) f(cookie)g(should)h(be)g(accepted)f(from)g(/)i(returned)d(to)j(the)f (serv)o(er)-5 b(.)0 4223 y FL(class)21 b FD(DefaultCookiePolicy)p FJ(\()130 b FK(bloc)n(k)o(ed)p 1579 4223 25 4 v 28 w(domains=)p Fn(None)p FK(,)159 b(allowed)p 2590 4223 V 29 w(domains=)p Fn(None)p FK(,)g(netscape=)p Fn(True)p FK(,)1187 4323 y(rfc2965=)p Fn(False)o FK(,)30 b(rfc2109)p 2068 4323 V 28 w(as)p 2170 4323 V 29 w(netscape=)p Fn(None)p FK(,)j(hide)p 2945 4323 V 29 w(cookie2=)p Fn(False)p FK(,)g(strict)p 3764 4323 V 30 w(do-)1187 4423 y(main=)p Fn(False)p FK(,)16 b(strict)p 1872 4423 V 30 w(rfc2965)p 2162 4423 V 28 w(un)m(veri\002able=)p Fn(True)p FK(,)j(strict)p 3052 4423 V 30 w(ns)p 3156 4423 V 30 w(un)m(veri\002able=)p Fn(False)p FK(,)1187 4522 y(strict)p 1362 4522 V 27 w(ns)p 1463 4522 V 29 w(domain=)p Fn(DefaultCookiePolicy.DomainL)o(ibera)o(l)p FK(,)105 b(strict)p 3743 4522 V 31 w(ns)p 3848 4522 V 29 w(-)1187 4622 y(set)p 1284 4622 V 26 w(initial)p 1509 4622 V 29 w(dollar=)p Fn(False)p FK(,)19 b(strict)p 2258 4622 V 31 w(ns)p 2363 4622 V 29 w(set)p 2484 4622 V 30 w(path=)p Fn(False)g FJ(\))208 4704 y FN(Constructor)f(ar)o(guments)g (should)g(be)i(passed)f(as)i(k)o(e)o(yw)o(ord)d(ar)o(guments)f(only)-5 b(.)24 b FK(bloc)n(k)o(ed)p 2779 4704 V 29 w(domains)18 b FN(is)j(a)f(sequence)f(of)g(domain)208 4804 y(names)d(that)g(we)h(ne) n(v)o(er)e(accept)h(cookies)g(from,)g(nor)f(return)g(cookies)h(to.)24 b FK(allowed)p 2582 4804 V 29 w(domains)15 b FN(if)i(not)f FJ(None)p FN(,)h(this)g(is)g(a)g(sequence)208 4903 y(of)h(the)i(only)e (domains)g(for)h(which)f(we)i(accept)f(and)f(return)g(cookies.)24 b(F)o(or)19 b(all)h(other)e(ar)o(guments,)f(see)j(the)f(documentation)d (for)208 5003 y FJ(CookiePolicy)i FN(and)i FJ(DefaultCookiePolicy)d FN(objects.)208 5136 y FJ(DefaultCookiePolicy)g FN(implements)j(the)h (standard)e(accept)i(/)g(reject)g(rules)f(for)g(Netscape)h(and)f(RFC)i (2965)e(cookies.)208 5235 y(By)e(def)o(ault,)f(RFC)i(2109)e(cookies)g (\(ie.)24 b(cookies)17 b(recei)n(v)o(ed)f(in)i(a)h FO(Set-Cookie:)i FN(header)c(with)h(a)g(v)o(ersion)f(cookie-attrib)n(ute)e(of)j(1\))208 5335 y(are)i(treated)f(according)f(to)j(the)f(RFC)h(2965)e(rules.)25 b(Ho)n(we)n(v)o(er)m(,)18 b(if)i(RFC)i(2965)d(handling)f(is)j(turned)e (of)n(f)g(or)h FJ(rfc2109_as_-)p 0 5549 3901 4 v 0 5649 a FI(672)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 673 685 TeXDict begin 673 684 bop 208 83 a FJ(netscape)18 b FN(is)i(T)m(rue,)e (RFC)j(2109)d(cookies)g(are)h(')l(do)n(wngraded')c(by)k(the)g FJ(CookieJar)f FN(instance)h(to)g(Netscape)g(cookies,)f(by)208 183 y(setting)24 b(the)g FJ(version)g FN(attrib)n(ute)g(of)g(the)g FJ(Cookie)g FN(instance)g(to)h(0.)37 b FJ(DefaultCookiePolicy)21 b FN(also)k(pro)o(vides)e(some)208 282 y(parameters)c(to)h(allo)n(w)g (some)g(\002ne-tuning)e(of)i(polic)o(y)-5 b(.)0 429 y FL(class)21 b FD(Cookie)p FJ(\(\))208 529 y FN(This)f(class)i (represents)d(Netscape,)h(RFC)i(2109)d(and)h(RFC)i(2965)d(cookies.)25 b(It)c(is)g(not)f(e)o(xpected)f(that)i(users)f(of)h FJ(cookielib)208 628 y FN(construct)i(their)i(o)n(wn)f FJ(Cookie)g FN(instances.)38 b(Instead,)25 b(if)g(necessary)-5 b(,)24 b(call)h FJ(make_cookies\(\))e FN(on)h(a)h FJ(CookieJar)f FN(in-)208 728 y(stance.)0 875 y FL(See)d(Also:)0 1022 y FN(Module)e FJ(urllib2)g FN(\(section)h(18.6\):)208 1121 y(URL)g(opening)f(with)h(automatic)f (cookie)g(handling.)0 1268 y(Module)g FJ(Cookie)h FN(\(section)f (18.23\):)208 1368 y(HTTP)k(cookie)f(classes,)j(principally)d(useful)h (for)g(serv)o(er)n(-side)f(code.)34 b(The)23 b FJ(cookielib)f FN(and)h FJ(Cookie)g FN(modules)f(do)h(not)208 1468 y(depend)18 b(on)i(each)g(other)-5 b(.)0 1614 y FO(http://wwwsearch.sf)n (.net/Clien)o(tCoo)o(kie/)208 1714 y FN(Extensions)19 b(to)h(this)h(module,)d(including)h(a)h(class)i(for)d(reading)g (Microsoft)g(Internet)g(Explorer)f(cookies)i(on)f(W)m(indo)n(ws.)0 1861 y FO(http://www)l(.netscape)o(.com/ne)n(wsref/std)o(/cookie)p 1477 1861 23 4 v 20 w(spec.html)208 1961 y FN(The)31 b(speci\002cation)g(of)h(the)g(original)f(Netscape)h(cookie)f (protocol.)58 b(Though)30 b(this)i(is)h(still)g(the)f(dominant)f (protocol,)i(the)208 2060 y('Netscape)28 b(cookie)f(protocol')g (implemented)g(by)h(all)i(the)e(major)g(bro)n(wsers)g(\(and)g FJ(cookielib)p FN(\))f(only)h(bears)h(a)g(passing)208 2160 y(resemblance)18 b(to)j(the)f(one)f(sk)o(etched)h(out)g(in)g FJ(cookie_spec.html)p FN(.)0 2307 y(RFC)i(2109,)c(\223)p FK(HTTP)j(State)f(Mana)o(g)o(ement)e(Mec)o(hanism)p FN(\224)208 2406 y(Obsoleted)h(by)h(RFC)h(2965.)j(Uses)d FO(Set-Cookie:)i FN(with)e(v)o(ersion=1.)0 2553 y(RFC)h(2965,)c(\223)p FK(HTTP)j(State)f(Mana)o(g)o(ement)e(Mec)o(hanism)p FN(\224)208 2653 y(The)h(Netscape)h(protocol)f(with)h(the)g(b)n(ugs)g(\002x)o(ed.) 25 b(Uses)c FO(Set-Cookie2:)h FN(in)f(place)f(of)g FO(Set-Cookie:)p FN(.)i(Not)f(widely)e(used.)0 2800 y FO(http://kr)q (istol.org/cookie/err)o(a)o(ta.h)o(tml)208 2899 y FN(Un\002nished)g (errata)g(to)i(RFC)g(2965.)0 3046 y(RFC)h(2964,)c(\223)p FK(Use)j(of)f(HTTP)h(State)f(Mana)o(g)o(ement)p FN(\224)0 3331 y Fv(18.22.1)101 b(CookieJ)n(ar)29 b(and)g(FileCookieJ)n(ar)h (Objects)0 3533 y FJ(CookieJar)19 b FN(objects)h(support)f(the)h (iterator)g(protocol)e(for)i(iterating)f(o)o(v)o(er)g(contained)f FJ(Cookie)i FN(objects.)0 3680 y FJ(CookieJar)f FN(has)h(the)h(follo)n (wing)d(methods:)0 3827 y FD(add_cookie_header)p FJ(\()p FK(r)m(equest)q FJ(\))208 3927 y FN(Add)h(correct)g FO(Cookie:)25 b FN(header)19 b(to)h FK(r)m(equest)q FN(.)208 4059 y(If)27 b(polic)o(y)g(allo)n(ws)h(\(ie.)48 b(the)28 b FJ(rfc2965)f FN(and)g FJ(hide_cookie2)f FN(attrib)n(utes)i(of)f(the)h FJ(CookieJar)p FN(')-5 b(s)27 b FJ(CookiePolicy)208 4159 y FN(instance)19 b(are)h(true)g(and)g(f)o(alse)h(respecti)n(v)o(ely\),) d(the)i FO(Cookie2:)j FN(header)c(is)j(also)e(added)f(when)h (appropriate.)208 4291 y(The)42 b FK(r)m(equest)i FN(object)e (\(usually)g(a)h FJ(urllib2.Request)d FN(instance\))i(must)g(support)g (the)g(methods)g FJ(get_full_-)208 4391 y(url\(\))p FN(,)69 b FJ(get_host\(\))p FN(,)f FJ(get_type\(\))p FN(,)g FJ (unverifiable\(\))p FN(,)f FJ(get_origin_req_host\(\))p FN(,)f FJ(has_-)208 4490 y(header\(\))p FN(,)60 b FJ(get_header\(\))p FN(,)f FJ(header_items\(\))p FN(,)g(and)52 b FJ (add_unredirected_header\(\))p FN(,as)d(docu-)208 4590 y(mented)19 b(by)h FJ(urllib2)p FN(.)0 4737 y FD(extract_cookies)p FJ(\()p FK(r)m(esponse)o(,)d(r)m(equest)q FJ(\))208 4836 y FN(Extract)i(cookies)g(from)h(HTTP)g FK(r)m(esponse)g FN(and)f(store)i(them)e(in)i(the)f FJ(CookieJar)p FN(,)f(where)g(allo)n (wed)h(by)g(polic)o(y)-5 b(.)208 4969 y(The)20 b FJ(CookieJar)g FN(will)i(look)e(for)h(allo)n(w)o(able)f FO(Set-Cookie:)25 b FN(and)c FO(Set-Cookie2:)j FN(headers)c(in)i(the)f FK(r)m(esponse)f FN(ar)o(gument,)f(and)208 5068 y(store)h(cookies)f(as) i(appropriate)d(\(subject)h(to)i(the)f FJ(CookiePolicy.set_ok\(\))d FN(method')-5 b(s)19 b(appro)o(v)n(al\).)208 5201 y(The)38 b FK(r)m(esponse)h FN(object)f(\(usually)g(the)i(result)f(of)f(a)i (call)f(to)g FJ(urllib2.urlopen\(\))p FN(,)i(or)e(similar\))g(should)f (support)208 5300 y(an)e FJ(info\(\))g FN(method,)i(which)e(returns)g (an)g(object)g(with)g(a)h FJ(getallmatchingheaders\(\))c FN(method)i(\(usually)g(a)208 5400 y FJ(mimetools.Message)17 b FN(instance\).)p 0 5549 3901 4 v 0 5649 a FI(18.22.)52 b FJ(cookielib)22 b FI(\227)h(Cookie)g(handling)i(f)n(or)e(HTTP)g (clients)1691 b(673)p eop end %%Page: 674 686 TeXDict begin 674 685 bop 208 83 a FN(The)22 b FK(r)m(equest)i FN(object)e(\(usually)g(a)h FJ(urllib2.Request)d FN(instance\))i(must)g (support)g(the)g(methods)g FJ(get_full_url\(\))p FN(,)208 183 y FJ(get_host\(\))p FN(,)h FJ(unverifiable\(\))p FN(,)g(and)g FJ(get_origin_req_host\(\))p FN(,)f(as)i(documented)e(by)h FJ(urllib2)p FN(.)36 b(The)208 282 y(request)19 b(is)i(used)f(to)g(set) g(def)o(ault)g(v)n(alues)f(for)h(cookie-attrib)n(utes)e(as)i(well)h(as) g(for)e(checking)f(that)i(the)g(cookie)f(is)i(allo)n(wed)e(to)i(be)208 382 y(set.)0 529 y FD(set_policy)p FJ(\()p FK(policy)p FJ(\))208 628 y FN(Set)f(the)h FJ(CookiePolicy)d FN(instance)i(to)g(be) g(used.)0 775 y FD(make_cookies)p FJ(\()p FK(r)m(esponse)o(,)d(r)m (equest)q FJ(\))208 875 y FN(Return)i(sequence)g(of)h FJ(Cookie)g FN(objects)g(e)o(xtracted)f(from)g FK(r)m(esponse)h FN(object.)208 1005 y(See)k(the)f(documentation)e(for)i FJ(extract_cookies)e FN(for)i(the)h(interf)o(aces)f(required)e(of)j (the)f FK(r)m(esponse)g FN(and)g FK(r)m(equest)i FN(ar)o(gu-)208 1104 y(ments.)0 1251 y FD(set_cookie_if_ok)p FJ(\()p FK(cookie)o(,)16 b(r)m(equest)q FJ(\))208 1351 y FN(Set)k(a)h FJ(Cookie)f FN(if)g(polic)o(y)f(says)i(it')-5 b(s)21 b(OK)g(to)f(do)g(so.)0 1498 y FD(set_cookie)p FJ(\()p FK(cookie)p FJ(\))208 1597 y FN(Set)g(a)h FJ(Cookie)p FN(,)e(without)h(checking)e(with)j(polic)o(y)e(to)h(see)h(whether)e(or) h(not)g(it)h(should)e(be)h(set.)0 1744 y FD(clear)p FJ(\()p FC([)p FK(domain)p FC([)p FK(,)d(path)p FC([)p FK(,)i(name)12 b FC(])g(])g(])p FJ(\))208 1844 y FN(Clear)20 b(some)g(cookies.)208 1973 y(If)29 b(in)m(v)n(ok)o(ed)f(without)h(ar)o(guments,)g(clear)h (all)g(cookies.)52 b(If)30 b(gi)n(v)o(en)e(a)i(single)g(ar)o(gument,)f (only)g(cookies)f(belonging)g(to)h(that)208 2073 y FK(domain)19 b FN(will)j(be)e(remo)o(v)o(ed.)25 b(If)c(gi)n(v)o(en)e(tw)o(o)i(ar)o (guments,)e(cookies)h(belonging)f(to)i(the)g(speci\002ed)f FK(domain)g FN(and)g(URL)i FK(path)e FN(are)208 2173 y(remo)o(v)o(ed.)i(If)e(gi)n(v)o(en)f(three)h(ar)o(guments,)e(then)h (the)i(cookie)e(with)h(the)g(speci\002ed)g FK(domain)p FN(,)f FK(path)g FN(and)h FK(name)f FN(is)i(remo)o(v)o(ed.)208 2302 y(Raises)g FJ(KeyError)e FN(if)i(no)f(matching)e(cookie)h(e)o (xists.)0 2449 y FD(clear_session_cookies)p FJ(\(\))208 2549 y FN(Discard)h(all)g(session)h(cookies.)208 2679 y(Discards)15 b(all)i(contained)d(cookies)h(that)h(ha)n(v)o(e)f(a)h (true)g FJ(discard)f FN(attrib)n(ute)g(\(usually)g(because)g(the)o(y)g (had)h(either)f(no)g FJ(max-age)208 2778 y FN(or)20 b FJ(expires)g FN(cookie-attrib)n(ute,)f(or)h(an)h(e)o(xplicit)f FJ(discard)g FN(cookie-attrib)n(ute\).)k(F)o(or)d(interacti)n(v)o(e)e (bro)n(wsers,)h(the)h(end)g(of)f(a)208 2878 y(session)g(usually)g (corresponds)e(to)i(closing)g(the)g(bro)n(wser)f(windo)n(w)-5 b(.)208 3008 y(Note)22 b(that)h(the)f FJ(save\(\))g FN(method)f(w)o (on')o(t)h(sa)n(v)o(e)g(session)h(cookies)f(an)o(yw)o(ay)-5 b(,)21 b(unless)i(you)e(ask)i(otherwise)f(by)g(passing)g(a)h(true)208 3107 y FK(ignor)m(e)p 428 3107 25 4 v 28 w(discar)m(d)f FN(ar)o(gument.)0 3254 y FJ(FileCookieJar)c FN(implements)i(the)g (follo)n(wing)e(additional)h(methods:)0 3401 y FD(save)p FJ(\()p FK(\002lename=)p Fn(None)p FK(,)e(ignor)m(e)p 1047 3401 V 29 w(discar)m(d=)p Fn(False)p FK(,)h(ignor)m(e)p 1883 3401 V 29 w(e)n(xpir)m(es=)p Fn(False)p FJ(\))208 3501 y FN(Sa)n(v)o(e)i(cookies)f(to)i(a)f(\002le.)208 3630 y(This)g(base)g(class)h(raises)g FJ(NotImplementedError)p FN(.)h(Subclasses)f(may)e(lea)n(v)o(e)h(this)h(method)e(unimplemented.) 208 3760 y FK(\002lename)24 b FN(is)i(the)f(name)f(of)h(\002le)h(in)f (which)g(to)g(sa)n(v)o(e)h(cookies.)39 b(If)25 b FK(\002lename)f FN(is)i(not)f(speci\002ed,)g FJ(self.filename)f FN(is)i(used)208 3860 y(\(whose)21 b(def)o(ault)g(is)i(the)f(v)n(alue)f(passed)h(to)g (the)g(constructor)m(,)e(if)j(an)o(y\);)f(if)g FJ(self.filename)e FN(is)j FJ(None)p FN(,)f FJ(ValueError)f FN(is)208 3959 y(raised.)208 4089 y FK(ignor)m(e)p 428 4089 V 28 w(discar)m(d)r FN(:)k(sa)n(v)o(e)c(e)n(v)o(en)e(cookies)g(set)i(to)f(be)h(discarded.)i FK(ignor)m(e)p 2244 4089 V 29 w(e)n(xpir)m(es)p FN(:)j(sa)n(v)o(e)20 b(e)n(v)o(en)f(cookies)h(that)g(ha)n(v)o(e)f(e)o(xpired)208 4219 y(The)h(\002le)h(is)g(o)o(v)o(erwritten)e(if)i(it)g(already)e(e)o (xists,)i(thus)f(wiping)g(all)h(the)g(cookies)f(it)h(contains.)k(Sa)n (v)o(ed)20 b(cookies)g(can)g(be)h(restored)208 4319 y(later)f(using)g (the)g FJ(load\(\))f FN(or)h FJ(revert\(\))g FN(methods.)0 4465 y FD(load)p FJ(\()p FK(\002lename=)p Fn(None)p FK(,)d(ignor)m(e)p 1047 4465 V 29 w(discar)m(d=)p Fn(False)p FK(,)h(ignor)m(e)p 1883 4465 V 29 w(e)n(xpir)m(es=)p Fn(False)p FJ(\))208 4565 y FN(Load)h(cookies)g(from)g(a)i(\002le.)208 4695 y(Old)f(cookies)f(are)h(k)o(ept)g(unless)h(o)o(v)o(erwritten)d(by)h(ne) n(wly)h(loaded)f(ones.)208 4825 y(Ar)o(guments)f(are)i(as)h(for)e FJ(save\(\))p FN(.)208 4954 y(The)i(named)f(\002le)i(must)f(be)h(in)f (the)h(format)e(understood)f(by)i(the)g(class,)h(or)g FJ(LoadError)e FN(will)i(be)f(raised.)28 b(Also,)22 b FJ(IOError)208 5054 y FN(may)17 b(be)i(raised,)f(for)f(e)o(xample)g(if) i(the)f(\002le)h(does)f(not)g(e)o(xist.)24 b FL(Note:)g FN(F)o(or)18 b(backw)o(ards-compatibility)c(with)19 b(Python)e(2.4)g (\(which)208 5154 y(raised)j(an)g FJ(IOError)p FN(\),)f FJ(LoadError)g FN(is)i(a)f(subclass)h(of)f FJ(IOError)p FN(.)0 5300 y FD(revert)p FJ(\()p FK(\002lename=)p Fn(None)p FK(,)d(ignor)m(e)p 1147 5300 V 28 w(discar)m(d=)p Fn(False)p FK(,)i(ignor)m(e)p 1983 5300 V 29 w(e)n(xpir)m(es=)p Fn(False)p FJ(\))208 5400 y FN(Clear)h(all)h(cookies)e(and)h(reload)f (cookies)h(from)f(a)h(sa)n(v)o(ed)g(\002le.)p 0 5549 3901 4 v 0 5649 a FI(674)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 675 687 TeXDict begin 675 686 bop 208 83 a FJ(revert\(\))18 b FN(can)h(raise)h(the)f(same)h(e)o(xceptions)e(as)i FJ(load\(\))p FN(.)k(If)19 b(there)g(is)h(a)g(f)o(ailure,)f(the)g(object')-5 b(s)20 b(state)g(will)g(not)f(be)g(altered.)0 230 y FJ(FileCookieJar)f FN(instances)i(ha)n(v)o(e)g(the)g(follo)n(wing)f(public)g(attrib)n (utes:)0 377 y FD(filename)208 476 y FN(Filename)g(of)h(def)o(ault)g (\002le)h(in)f(which)g(to)g(k)o(eep)g(cookies.)k(This)c(attrib)n(ute)g (may)g(be)g(assigned)f(to.)0 623 y FD(delayload)208 723 y FN(If)25 b(true,)h(load)g(cookies)e(lazily)i(from)f(disk.)41 b(This)26 b(attrib)n(ute)f(should)f(not)i(be)f(assigned)g(to.)42 b(This)25 b(is)i(only)e(a)h(hint,)g(since)g(this)208 823 y(only)20 b(af)n(fects)g(performance,)e(not)j(beha)n(viour)e (\(unless)h(the)h(cookies)f(on)h(disk)g(are)g(changing\).)j(A)e FJ(CookieJar)e FN(object)g(may)208 922 y(ignore)e(it.)26 b(None)20 b(of)g(the)g FJ(FileCookieJar)e FN(classes)j(included)e(in)h (the)h(standard)e(library)g(lazily)h(loads)g(cookies.)0 1201 y Fv(18.22.2)101 b(FileCookieJ)n(ar)30 b(subclasses)e(and)h (co-oper)o(ation)h(with)e(w)o(eb)h(bro)o(wsers)0 1404 y FN(The)c(follo)n(wing)f FJ(CookieJar)h FN(subclasses)h(are)f(pro)o (vided)e(for)i(reading)f(and)h(writing)g(.)42 b(Further)24 b FJ(CookieJar)h FN(subclasses,)i(in-)0 1504 y(cluding)19 b(one)g(that)i(reads)f(Microsoft)f(Internet)g(Explorer)f(cookies,)h (are)h(a)n(v)n(ailable)g(at)h FO(http://wwwsearch.sf)n(.net/Clie)o (ntCo)o(okie)o(/)-6 b FN(.)0 1651 y FL(class)21 b FD(MozillaCookieJar)p FJ(\()p FK(\002lename)o(,)16 b(delayload=)p Fn(None)p FK(,)h(policy=)p Fn(None)p FJ(\))208 1750 y FN(A)26 b FJ(FileCookieJar)e FN(that)h(can)h(load)f(from)g(and)g(sa)n(v)o(e)h (cookies)f(to)g(disk)h(in)g(the)g(Mozilla)f FJ(cookies.txt)f FN(\002le)j(format)208 1850 y(\(which)16 b(is)i(also)f(used)g(by)g(the) g(L)-5 b(ynx)16 b(and)h(Netscape)g(bro)n(wsers\).)23 b FL(Note:)f FN(This)c(loses)f(information)e(about)h(RFC)j(2965)d (cookies,)208 1950 y(and)j(also)i(about)e(ne)n(wer)g(or)h(non-standard) e(cookie-attrib)n(utes)g(such)i(as)g FJ(port)p FN(.)208 2076 y FL(W)-5 b(ar)o(ning:)29 b FN(Back)22 b(up)h(your)e(cookies)h (before)f(sa)n(ving)i(if)g(you)e(ha)n(v)o(e)h(cookies)g(whose)h(loss)g (/)g(corruption)d(w)o(ould)i(be)h(incon)m(v)o(e-)208 2176 y(nient)c(\(there)h(are)g(some)g(subtleties)g(which)g(may)g(lead)g (to)g(slight)g(changes)g(in)g(the)g(\002le)h(o)o(v)o(er)e(a)h(load)g(/) h(sa)n(v)o(e)f(round-trip\).)208 2303 y(Also)g(note)g(that)g(cookies)g (sa)n(v)o(ed)f(while)i(Mozilla)f(is)h(running)d(will)j(get)f(clobbered) e(by)i(Mozilla.)0 2449 y FL(class)h FD(LWPCookieJar)p FJ(\()p FK(\002lename)o(,)16 b(delayload=)p Fn(None)p FK(,)i(policy=)p Fn(None)p FJ(\))208 2549 y FN(A)24 b FJ(FileCookieJar)e FN(that)i(can)g(load)f(from)g(and)g(sa)n(v)o(e)h (cookies)g(to)g(disk)f(in)i(format)d(compatible)h(with)h(the)g (libwww-perl)208 2649 y(library')-5 b(s)19 b FJ(Set-Cookie3)g FN(\002le)i(format.)i(This)e(is)g(con)m(v)o(enient)c(if)k(you)e(w)o (ant)h(to)h(store)f(cookies)f(in)i(a)f(human-readable)d(\002le.)0 2928 y Fv(18.22.3)101 b(CookieP)-5 b(olicy)29 b(Objects)0 3131 y FN(Objects)20 b(implementing)e(the)j FJ(CookiePolicy)d FN(interf)o(ace)h(ha)n(v)o(e)h(the)g(follo)n(wing)f(methods:)0 3278 y FD(set_ok)p FJ(\()p FK(cookie)o(,)f(r)m(equest)q FJ(\))208 3377 y FN(Return)h(boolean)g(v)n(alue)g(indicating)g(whether) g(cookie)g(should)h(be)g(accepted)f(from)g(serv)o(er)-5 b(.)208 3504 y FK(cookie)28 b FN(is)h(a)h FJ(cookielib.Cookie)c FN(instance.)50 b FK(r)m(equest)30 b FN(is)g(an)f(object)f (implementing)f(the)h(interf)o(ace)g(de\002ned)g(by)h(the)208 3604 y(documentation)17 b(for)i FJ(CookieJar.extract_cookies\(\))p FN(.)0 3750 y FD(return_ok)p FJ(\()p FK(cookie)o(,)e(r)m(equest)q FJ(\))208 3850 y FN(Return)i(boolean)g(v)n(alue)g(indicating)g(whether) g(cookie)g(should)h(be)g(returned)e(to)j(serv)o(er)-5 b(.)208 3977 y FK(cookie)28 b FN(is)h(a)h FJ(cookielib.Cookie)c FN(instance.)50 b FK(r)m(equest)30 b FN(is)g(an)f(object)f (implementing)f(the)h(interf)o(ace)g(de\002ned)g(by)h(the)208 4076 y(documentation)17 b(for)i FJ(CookieJar.add_cookie_header\(\))p FN(.)0 4223 y FD(domain_return_ok)p FJ(\()p FK(domain,)c(r)m(equest)q FJ(\))208 4323 y FN(Return)k(f)o(alse)i(if)f(cookies)g(should)f(not)h (be)g(returned,)e(gi)n(v)o(en)h(cookie)g(domain.)208 4449 y(This)h(method)e(is)j(an)f(optimization.)j(It)d(remo)o(v)o(es)e (the)i(need)f(for)h(checking)e(e)n(v)o(ery)g(cookie)h(with)h(a)g (particular)f(domain)f(\(which)208 4549 y(might)g(in)m(v)n(olv)o(e)f (reading)h(man)o(y)f(\002les\).)25 b(Returning)18 b(true)h(from)e FJ(domain_return_ok\(\))g FN(and)h FJ(path_return_ok\(\))208 4649 y FN(lea)n(v)o(es)i(all)h(the)f(w)o(ork)f(to)i FJ(return_ok\(\))p FN(.)208 4775 y(If)16 b FJ(domain_return_ok\(\))d FN(returns)j(true)g (for)g(the)g(cookie)f(domain,)h FJ(path_return_ok\(\))e FN(is)j(called)f(for)g(the)h(cookie)208 4875 y(path.)60 b(Otherwise,)35 b FJ(path_return_ok\(\))29 b FN(and)j FJ(return_ok\(\))f FN(are)h(ne)n(v)o(er)e(called)i(for)g(that)g(cookie) f(domain.)60 b(If)208 4975 y FJ(path_return_ok\(\))20 b FN(returns)j(true,)g FJ(return_ok\(\))f FN(is)i(called)f(with)g(the)g FJ(Cookie)g FN(object)g(itself)g(for)g(a)h(full)f(check.)208 5074 y(Otherwise,)c FJ(return_ok\(\))g FN(is)i(ne)n(v)o(er)e(called)h (for)g(that)g(cookie)f(path.)208 5201 y(Note)h(that)g FJ(domain_return_ok\(\))d FN(is)22 b(called)e(for)f(e)n(v)o(ery)g FK(cookie)h FN(domain,)e(not)i(just)h(for)e(the)i FK(r)m(equest)f FN(domain.)j(F)o(or)d(e)o(x-)208 5300 y(ample,)f(the)h(function)e (might)i(be)g(called)g(with)g(both)g FJ(".example.com")e FN(and)h FJ("www.example.com")f FN(if)i(the)g(request)208 5400 y(domain)e(is)k FJ("www.example.com")p FN(.)g(The)e(same)g(goes)g (for)g FJ(path_return_ok\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(18.22.)52 b FJ(cookielib)22 b FI(\227)h(Cookie)g(handling)i (f)n(or)e(HTTP)g(clients)1691 b(675)p eop end %%Page: 676 688 TeXDict begin 676 687 bop 208 83 a FN(The)19 b FK(r)m(equest)j FN(ar)o(gument)c(is)j(as)g(documented)c(for)j FJ(return_ok\(\))p FN(.)0 230 y FD(path_return_ok)p FJ(\()p FK(path,)c(r)m(equest)q FJ(\))208 330 y FN(Return)j(f)o(alse)i(if)f(cookies)g(should)f(not)h (be)g(returned,)e(gi)n(v)o(en)h(cookie)g(path.)208 462 y(See)h(the)g(documentation)e(for)h FJ(domain_return_ok\(\))p FN(.)0 609 y(In)i(addition)f(to)h(implementing)e(the)j(methods)e(abo)o (v)o(e,)f(implementations)h(of)h(the)g FJ(CookiePolicy)e FN(interf)o(ace)i(must)g(also)h(supply)0 709 y(the)g(follo)n(wing)f (attrib)n(utes,)h(indicating)f(which)g(protocols)g(should)g(be)h(used,) h(and)e(ho)n(w)-5 b(.)30 b(All)23 b(of)f(these)g(attrib)n(utes)g(may)g (be)g(assigned)0 808 y(to.)0 955 y FD(netscape)208 1055 y FN(Implement)c(Netscape)i(protocol.)0 1202 y FD(rfc2965)208 1301 y FN(Implement)e(RFC)k(2965)d(protocol.)0 1448 y FD(hide_cookie2)208 1548 y FN(Don')o(t)24 b(add)g FO(Cookie2:)34 b FN(header)24 b(to)i(requests)e(\(the)h(presence)g(of)g(this)g(header) g(indicates)g(to)g(the)g(serv)o(er)g(that)g(we)h(understand)208 1648 y(RFC)21 b(2965)e(cookies\).)0 1794 y(The)32 b(most)g(useful)f(w)o (ay)h(to)h(de\002ne)e(a)i FJ(CookiePolicy)d FN(class)j(is)g(by)f (subclassing)f(from)g FJ(DefaultCookiePolicy)e FN(and)0 1894 y(o)o(v)o(erriding)20 b(some)j(or)f(all)i(of)f(the)g(methods)f (abo)o(v)o(e.)31 b FJ(CookiePolicy)22 b FN(itself)h(may)g(be)g(used)f (as)i(a)g('null)e(polic)o(y')f(to)j(allo)n(w)f(setting)0 1994 y(and)d(recei)n(ving)e(an)o(y)i(and)f(all)i(cookies)e(\(this)i(is) g(unlik)o(ely)e(to)h(be)g(useful\).)0 2279 y Fv(18.22.4)101 b(Def)m(aultCookieP)-5 b(olicy)30 b(Objects)0 2482 y FN(Implements)19 b(the)h(standard)f(rules)h(for)g(accepting)f(and)g (returning)f(cookies.)0 2628 y(Both)i(RFC)i(2965)d(and)g(Netscape)h (cookies)g(are)g(co)o(v)o(ered.)j(RFC)e(2965)e(handling)f(is)k (switched)d(of)n(f)h(by)g(def)o(ault.)0 2775 y(The)e(easiest)i(w)o(ay)f (to)g(pro)o(vide)e(your)g(o)n(wn)h(polic)o(y)g(is)i(to)f(o)o(v)o (erride)d(this)k(class)f(and)g(call)g(its)h(methods)d(in)i(your)f(o)o (v)o(erridden)d(implemen-)0 2875 y(tations)20 b(before)f(adding)g(your) g(o)n(wn)g(additional)g(checks:)236 3113 y FA(import)44 b(cookielib)236 3204 y(class)g (MyCookiePolicy\(cookielib.DefaultCookiePo)o(licy\):)416 3296 y(def)g(set_ok\(self,)f(cookie,)g(request\):)595 3387 y(if)h(not)h(cookielib.DefaultCookiePolicy.set_ok\()o(self,)38 b(cookie,)44 b(request\):)774 3478 y(return)g(False)595 3570 y(if)g(i_dont_want_to_store_this_cookie\(cookie\):)774 3661 y(return)g(False)595 3752 y(return)g(True)0 4039 y FN(In)25 b(addition)e(to)i(the)g(features)g(required)e(to)i (implement)e(the)i FJ(CookiePolicy)f FN(interf)o(ace,)h(this)g(class)h (allo)n(ws)f(you)f(to)h(block)f(and)0 4138 y(allo)n(w)g(domains)f(from) f(setting)i(and)f(recei)n(ving)g(cookies.)35 b(There)23 b(are)g(also)h(some)g(strictness)g(switches)h(that)f(allo)n(w)f(you)g (to)h(tighten)0 4238 y(up)c(the)g(rather)f(loose)h(Netscape)g(protocol) f(rules)h(a)h(little)g(bit)f(\(at)g(the)h(cost)f(of)g(blocking)e(some)i (benign)f(cookies\).)0 4385 y(A)g(domain)f(blacklist)h(and)f(whitelist) i(is)g(pro)o(vided)c(\(both)i(of)n(f)g(by)h(def)o(ault\).)k(Only)c (domains)f(not)h(in)g(the)g(blacklist)g(and)f(present)g(in)i(the)0 4485 y(whitelist)f(\(if)f(the)g(whitelist)h(is)g(acti)n(v)o(e\))e (participate)g(in)i(cookie)e(setting)h(and)f(returning.)23 b(Use)18 b(the)h FK(bloc)n(k)o(ed)p 3094 4485 25 4 v 28 w(domains)e FN(constructor)g(ar)n(-)0 4584 y(gument,)h(and)h FJ(blocked_domains\(\))e FN(and)i FJ(set_blocked_domains\(\))d FN(methods)i(\(and)h(the)g(corresponding)d(ar)o(gument)0 4684 y(and)k(methods)f(for)g FK(allowed)p 829 4684 V 29 w(domains)p FN(\).)24 b(If)c(you)f(set)i(a)g(whitelist,)f(you)f(can) h(turn)g(it)h(of)n(f)e(again)g(by)h(setting)g(it)h(to)g FJ(None)p FN(.)0 4831 y(Domains)e(in)g(block)g(or)g(allo)n(w)g(lists)i (that)f(do)f(not)g(start)h(with)g(a)f(dot)g(must)h(equal)f(the)g (cookie)g(domain)f(to)h(be)h(matched.)j(F)o(or)c(e)o(xample,)0 4930 y FJ("example.com")e FN(matches)i(a)h(blacklist)f(entry)g(of)g FJ("example.com")p FN(,)e(b)n(ut)i FJ("www.example.com")e FN(does)i(not.)24 b(Domains)0 5030 y(that)32 b(do)g(start)g(with)g(a)h (dot)e(are)h(matched)f(by)g(more)g(speci\002c)i(domains)d(too.)60 b(F)o(or)32 b(e)o(xample,)h(both)e FJ("www.example.com")0 5130 y FN(and)23 b FJ("www.coyote.example.com")d FN(match)i FJ(".example.com")g FN(\(b)n(ut)h FJ("example.com")f FN(itself)i(does)f(not\).)34 b(IP)24 b(ad-)0 5229 y(dresses)e(are)f(an) h(e)o(xception,)d(and)i(must)h(match)f(e)o(xactly)-5 b(.)27 b(F)o(or)21 b(e)o(xample,)g(if)g(block)o(ed)p 2485 5229 V 28 w(domains)g(contains)f FJ("192.168.1.2")g FN(and)0 5329 y FJ(".168.1.2")p FN(,)f(192.168.1.2)d(is)21 b(block)o(ed,)d(b)n(ut)j(193.168.1.2)16 b(is)21 b(not.)p 0 5549 3901 4 v 0 5649 a FI(676)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 677 689 TeXDict begin 677 688 bop 0 83 a FJ(DefaultCookiePolicy)17 b FN(implements)i(the)i(follo)n(wing)d(additional)h(methods:)0 230 y FD(blocked_domains)p FJ(\(\))208 330 y FN(Return)g(the)i (sequence)e(of)g(block)o(ed)g(domains)g(\(as)i(a)g(tuple\).)0 476 y FD(set_blocked_domains)p FJ(\()p FK(bloc)n(k)o(ed)p 1262 476 25 4 v 25 w(domains)p FJ(\))208 576 y FN(Set)f(the)h(sequence) e(of)h(block)o(ed)e(domains.)0 723 y FD(is_blocked)p FJ(\()p FK(domain)p FJ(\))208 823 y FN(Return)h(whether)g FK(domain)g FN(is)i(on)f(the)g(blacklist)h(for)e(setting)h(or)g(recei)n (ving)f(cookies.)0 969 y FD(allowed_domains)p FJ(\(\))208 1069 y FN(Return)g FJ(None)p FN(,)h(or)g(the)g(sequence)f(of)h(allo)n (wed)g(domains)f(\(as)h(a)h(tuple\).)0 1216 y FD(set_allowed_domains)p FJ(\()p FK(allowed)p 1269 1216 V 25 w(domains)p FJ(\))208 1316 y FN(Set)f(the)h(sequence)e(of)h(allo)n(wed)f(domains,)g(or)h FJ(None)p FN(.)0 1462 y FD(is_not_allowed)p FJ(\()p FK(domain)p FJ(\))208 1562 y FN(Return)f(whether)g FK(domain)g FN(is)i(not)f(on)g (the)g(whitelist)h(for)f(setting)g(or)g(recei)n(ving)e(cookies.)0 1709 y FJ(DefaultCookiePolicy)29 b FN(instances)j(ha)n(v)o(e)f(the)h (follo)n(wing)f(attrib)n(utes,)j(which)e(are)g(all)g(initialised)g (from)f(the)h(constructor)0 1808 y(ar)o(guments)18 b(of)i(the)g(same)h (name,)e(and)h(which)f(may)h(all)h(be)f(assigned)g(to.)0 1955 y FD(rfc2109_as_netscape)208 2055 y FN(If)27 b(true,)j(request)d (that)h(the)g FJ(CookieJar)f FN(instance)h(do)n(wngrade)d(RFC)k(2109)e (cookies)g(\(ie.)49 b(cookies)27 b(recei)n(v)o(ed)f(in)j(a)f FO(Set-)208 2155 y(Cookie:)h FN(header)22 b(with)i(a)f(v)o(ersion)f (cookie-attrib)n(ute)f(of)i(1\))g(to)g(Netscape)g(cookies)f(by)h (setting)g(the)g(v)o(ersion)f(attrib)n(ute)h(of)g(the)208 2254 y FJ(Cookie)17 b FN(instance)i(to)f(0.)25 b(The)18 b(def)o(ault)f(v)n(alue)h(is)i FJ(None)p FN(,)e(in)h(which)e(case)i (RFC)h(2109)d(cookies)h(are)g(do)n(wngraded)e(if)i(and)g(only)208 2354 y(if)j(RFC)i(2965)d(handling)f(is)j(turned)e(of)n(f.)28 b(Therefore,)19 b(RFC)k(2109)d(cookies)g(are)h(do)n(wngraded)e(by)h (def)o(ault.)57 b(Ne)n(w)21 b(in)h(v)o(ersion)208 2454 y(2.5.)0 2600 y(General)e(strictness)g(switches:)0 2747 y FD(strict_domain)208 2847 y FN(Don')o(t)c(allo)n(w)i(sites)h(to)f (set)h(tw)o(o-component)c(domains)h(with)i(country-code)d(top-le)n(v)o (el)h(domains)h(lik)o(e)h FJ(.co.uk)p FN(,)g FJ(.gov.uk)p FN(,)208 2946 y FJ(.co.nz)p FN(.etc.)23 b(This)e(is)g(f)o(ar)f(from)f (perfect)g(and)h(isn')o(t)g(guaranteed)e(to)i(w)o(ork!)0 3093 y(RFC)i(2965)c(protocol)h(strictness)i(switches:)0 3240 y FD(strict_rfc2965_unverifiable)208 3340 y FN(F)o(ollo)n(w)f(RFC) i(2965)e(rules)h(on)f(un)m(v)o(eri\002able)f(transactions)h(\(usually) -5 b(,)20 b(an)h(un)m(v)o(eri\002able)d(transaction)i(is)i(one)e (resulting)g(from)g(a)208 3439 y(redirect)f(or)h(a)h(request)f(for)f (an)i(image)e(hosted)h(on)g(another)f(site\).)26 b(If)20 b(this)h(is)g(f)o(alse,)g(cookies)e(are)i FK(ne)o(ver)f FN(block)o(ed)f(on)h(the)g(basis)208 3539 y(of)f(v)o(eri\002ability)0 3686 y(Netscape)h(protocol)e(strictness)j(switches:)0 3833 y FD(strict_ns_unverifiable)208 3932 y FN(apply)e(RFC)i(2965)e (rules)h(on)g(un)m(v)o(eri\002able)e(transactions)h(e)n(v)o(en)g(to)i (Netscape)f(cookies)0 4079 y FD(strict_ns_domain)208 4179 y FN(Flags)25 b(indicating)e(ho)n(w)h(strict)h(to)g(be)g(with)g (domain-matching)c(rules)j(for)g(Netscape)h(cookies.)37 b(See)26 b(belo)n(w)e(for)g(acceptable)208 4279 y(v)n(alues.)0 4425 y FD(strict_ns_set_initial_dollar)208 4525 y FN(Ignore)18 b(cookies)h(in)i(Set-Cookie:)j(headers)19 b(that)i(ha)n(v)o(e)e(names)h (starting)g(with)g FJ('$')p FN(.)0 4672 y FD(strict_ns_set_path)208 4772 y FN(Don')o(t)f(allo)n(w)h(setting)g(cookies)f(whose)h(path)g (doesn')o(t)e(path-match)h(request)g(URI.)0 4918 y FJ(strict_ns_domain) 47 b FN(is)i(a)h(collection)e(of)h(\003ags.)111 b(Its)50 b(v)n(alue)e(is)i(constructed)d(by)i(or)n(-ing)f(together)f(\(for)h(e)o (xample,)0 5018 y FJ(DomainStrictNoDots|DomainStrictNonD)o(omain)14 b FN(means)20 b(both)g(\003ags)g(are)g(set\).)0 5165 y FD(DomainStrictNoDots)208 5265 y FN(When)g(setting)h(cookies,)f(the)h ('host)f(pre\002x')g(must)h(not)f(contain)g(a)h(dot)g(\(e)o(g.)26 b FJ(www.foo.bar.com)19 b FN(can')o(t)h(set)h(a)g(cookie)f(for)208 5364 y FJ(.bar.com)p FN(,)f(because)g FJ(www.foo)h FN(contains)f(a)i (dot\).)p 0 5549 3901 4 v 0 5649 a FI(18.22.)52 b FJ(cookielib)22 b FI(\227)h(Cookie)g(handling)i(f)n(or)e(HTTP)g(clients)1691 b(677)p eop end %%Page: 678 690 TeXDict begin 678 689 bop 0 83 a FD(DomainStrictNonDomain)208 183 y FN(Cookies)19 b(that)g(did)g(not)g(e)o(xplicitly)f(specify)h(a)g FJ(domain)g FN(cookie-attrib)n(ute)e(can)i(only)g(be)g(returned)e(to)j (a)g(domain)d(equal)i(to)h(the)208 282 y(domain)j(that)i(set)h(the)f (cookie)f(\(e)o(g.)39 b FJ(spam.example.com)23 b FN(w)o(on')o(t)h(be)g (returned)g(cookies)g(from)g FJ(example.com)f FN(that)208 382 y(had)c(no)h FJ(domain)g FN(cookie-attrib)n(ute\).)0 529 y FD(DomainRFC2965Match)208 628 y FN(When)g(setting)g(cookies,)f (require)g(a)h(full)g(RFC)i(2965)d(domain-match.)0 775 y(The)h(follo)n(wing)e(attrib)n(utes)j(are)f(pro)o(vided)d(for)j(con)m (v)o(enience,)d(and)i(are)h(the)h(most)f(useful)g(combinations)e(of)i (the)g(abo)o(v)o(e)e(\003ags:)0 922 y FD(DomainLiberal)208 1022 y FN(Equi)n(v)n(alent)g(to)i(0)h(\(ie.)k(all)20 b(of)g(the)g(abo)o(v)o(e)f(Netscape)h(domain)f(strictness)i(\003ags)f (switched)g(of)n(f\).)0 1169 y FD(DomainStrict)208 1268 y FN(Equi)n(v)n(alent)e(to)i FJ(DomainStrictNoDots|DomainStrictNonDom)o (ain)p FN(.)0 1553 y Fv(18.22.5)101 b(Cookie)29 b(Objects)0 1756 y FJ(Cookie)h FN(instances)g(ha)n(v)o(e)g(Python)f(attrib)n(utes)h (roughly)f(corresponding)e(to)j(the)g(standard)g(cookie-attrib)n(utes)e (speci\002ed)i(in)h(the)0 1856 y(v)n(arious)26 b(cookie)f(standards.)44 b(The)27 b(correspondence)c(is)28 b(not)e(one-to-one,)f(because)h (there)h(are)f(complicated)g(rules)g(for)g(assigning)0 1955 y(def)o(ault)f(v)n(alues,)i(because)e(the)h FJ(max-age)f FN(and)g FJ(expires)h FN(cookie-attrib)n(utes)d(contain)i(equi)n(v)n (alent)f(information,)h(and)g(because)0 2055 y(RFC)d(2109)c(cookies)i (may)g(be)g(')l(do)n(wngraded')c(by)k FJ(cookielib)f FN(from)g(v)o(ersion)g(1)h(to)g(v)o(ersion)f(0)i(\(Netscape\))e (cookies.)0 2202 y(Assignment)e(to)g(these)g(attrib)n(utes)h(should)e (not)h(be)g(necessary)g(other)f(than)h(in)g(rare)g(circumstances)f(in)i (a)g FJ(CookiePolicy)d FN(method.)0 2301 y(The)20 b(class)h(does)f(not) g(enforce)e(internal)i(consistenc)o(y)-5 b(,)18 b(so)j(you)e(should)g (kno)n(w)g(what)h(you')l(re)f(doing)g(if)h(you)f(do)h(that.)0 2448 y FD(version)208 2548 y FN(Inte)o(ger)25 b(or)j FJ(None)p FN(.)46 b(Netscape)28 b(cookies)e(ha)n(v)o(e)h FJ(version)g FN(0.)47 b(RFC)29 b(2965)d(and)h(RFC)i(2109)d(cookies)h (ha)n(v)o(e)f(a)i FJ(version)208 2648 y FN(cookie-attrib)n(ute)18 b(of)j(1.)28 b(Ho)n(we)n(v)o(er)m(,)19 b(note)h(that)h FJ(cookielib)f FN(may)h(')l(do)n(wngrade')c(RFC)23 b(2109)d(cookies)g (to)h(Netscape)g(cook-)208 2747 y(ies,)f(in)h(which)e(case)i FJ(version)e FN(is)j(0.)0 2894 y FD(name)208 2994 y FN(Cookie)d(name)h (\(a)g(string\).)0 3141 y FD(value)208 3240 y FN(Cookie)f(v)n(alue)h (\(a)g(string\),)f(or)h FJ(None)p FN(.)0 3387 y FD(port)208 3487 y FN(String)f(representing)f(a)j(port)f(or)f(a)i(set)g(of)f(ports) g(\(e)o(g.)k('80',)19 b(or)h('80,8080'\),)c(or)k FJ(None)p FN(.)0 3634 y FD(path)208 3733 y FN(Cookie)f(path)h(\(a)g(string,)g(e)o (g.)k FJ('/acme/rocket_launchers')p FN(\).)0 3880 y FD(secure)208 3980 y FN(T)m(rue)19 b(if)i(cookie)e(should)g(only)g(be)h(returned)f(o) o(v)o(er)g(a)h(secure)g(connection.)0 4127 y FD(expires)208 4226 y FN(Inte)o(ger)e(e)o(xpiry)h(date)h(in)g(seconds)g(since)g (epoch,)f(or)h FJ(None)p FN(.)25 b(See)20 b(also)h(the)f FJ(is_expired\(\))e FN(method.)0 4373 y FD(discard)208 4473 y FN(T)m(rue)h(if)i(this)f(is)h(a)g(session)g(cookie.)0 4620 y FD(comment)208 4719 y FN(String)e(comment)g(from)g(the)h(serv)o (er)g(e)o(xplaining)e(the)i(function)e(of)i(this)h(cookie,)e(or)h FJ(None)p FN(.)0 4866 y FD(comment_url)208 4966 y FN(URL)g(linking)f (to)i(a)f(comment)f(from)g(the)h(serv)o(er)g(e)o(xplaining)e(the)i (function)e(of)i(this)h(cookie,)e(or)h FJ(None)p FN(.)0 5113 y FD(rfc2109)208 5212 y FN(T)m(rue)g(if)g(this)h(cookie)f(w)o(as)h (recei)n(v)o(ed)e(as)j(an)e(RFC)i(2109)d(cookie)h(\(ie.)26 b(the)21 b(cookie)e(arri)n(v)o(ed)g(in)i(a)g FO(Set-Cookie:)j FN(header)m(,)19 b(and)h(the)208 5312 y(v)n(alue)d(of)i(the)f(V)-9 b(ersion)18 b(cookie-attrib)n(ute)e(in)j(that)f(header)g(w)o(as)h(1\).) 24 b(This)19 b(attrib)n(ute)f(is)i(pro)o(vided)c(because)i FJ(cookielib)f FN(may)p 0 5549 3901 4 v 0 5649 a FI(678)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 679 691 TeXDict begin 679 690 bop 208 83 a FN(')l(do)n(wngrade')16 b(RFC)22 b(2109)d(cookies)g(to)h(Netscape)g(cookies,)g(in)g(which)g (case)g FJ(version)g FN(is)h(0.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.5.)0 230 y FD(port_specified)208 330 y FN(T)m(rue)g(if)i(a)f(port)g (or)g(set)h(of)f(ports)f(w)o(as)i(e)o(xplicitly)f(speci\002ed)f(by)h (the)g(serv)o(er)g(\(in)g(the)g FO(Set-Cookie:)j FN(/)e FO(Set-Cookie2:)h FN(header\).)0 476 y FD(domain_specified)208 576 y FN(T)m(rue)d(if)i(a)f(domain)f(w)o(as)i(e)o(xplicitly)e (speci\002ed)h(by)g(the)g(serv)o(er)-5 b(.)0 723 y FD (domain_initial_dot)208 823 y FN(T)m(rue)19 b(if)i(the)f(domain)f(e)o (xplicitly)g(speci\002ed)h(by)f(the)i(serv)o(er)e(be)o(gan)f(with)j(a)f (dot)g(\()p FJ('.')p FN(\).)0 969 y(Cookies)g(may)g(ha)n(v)o(e)f (additional)g(non-standard)e(cookie-attrib)n(utes.)23 b(These)d(may)g(be)g(accessed)g(using)g(the)g(follo)n(wing)f(methods:)0 1116 y FD(has_nonstandard_attr)p FJ(\()p FK(name)p FJ(\))208 1216 y FN(Return)g(true)h(if)h(cookie)e(has)h(the)g(named)f (cookie-attrib)n(ute.)0 1363 y FD(get_nonstandard_attr)p FJ(\()p FK(name)o(,)d(default=)p Fn(None)p FJ(\))208 1462 y FN(If)k(cookie)f(has)h(the)g(named)f(cookie-attrib)n(ute,)f (return)h(its)i(v)n(alue.)j(Otherwise,)c(return)f FK(default)q FN(.)0 1609 y FD(set_nonstandard_attr)p FJ(\()p FK(name)o(,)d(value)p FJ(\))208 1709 y FN(Set)k(the)h(v)n(alue)e(of)h(the)g(named)f (cookie-attrib)n(ute.)0 1856 y(The)h FJ(Cookie)f FN(class)j(also)e (de\002nes)g(the)g(follo)n(wing)f(method:)0 2003 y FD(is_expired)p FJ(\()p FC([)p FK(now=)p Fn(None)12 b FC(])p FJ(\))208 2102 y FN(T)m(rue)24 b(if)h(cookie)f(has)h(passed)f(the)h(time)g(at)g (which)g(the)g(serv)o(er)e(requested)h(it)h(should)f(e)o(xpire.)38 b(If)25 b FK(now)f FN(is)i(gi)n(v)o(en)e(\(in)g(seconds)208 2202 y(since)c(the)g(epoch\),)f(return)g(whether)g(the)h(cookie)f(has)h (e)o(xpired)f(at)i(the)f(speci\002ed)g(time.)0 2487 y Fv(18.22.6)101 b(Examples)0 2690 y FN(The)20 b(\002rst)h(e)o(xample)e (sho)n(ws)h(the)g(most)g(common)f(usage)g(of)h FJ(cookielib)p FN(:)236 2928 y FA(import)44 b(cookielib,)f(urllib2)236 3019 y(cj)i(=)f(cookielib.CookieJar\(\))236 3111 y(opener)g(=)h (urllib2.build_opener\(urllib2.HTTPCook)o(ieProc)o(essor\()o(cj\)\))236 3202 y(r)g(=)g(opener.open\("http://example.com/"\))0 3488 y FN(This)20 b(e)o(xample)e(illustrates)i(ho)n(w)f(to)h(open)f(a)h (URL)g(using)f(your)g(Netscape,)g(Mozilla,)g(or)h(L)-5 b(ynx)19 b(cookies)g(\(assumes)i(U)t FH(N)t(I)t(X)r FN(/Netscape)0 3588 y(con)m(v)o(ention)c(for)j(location)f(of)h(the)g(cookies)f (\002le\):)236 3826 y FA(import)44 b(os,)g(cookielib,)g(urllib2)236 3917 y(cj)h(=)f(cookielib.MozillaCookieJar\(\))236 4009 y(cj.load\(os.path.join\(os.environ["HOME"],)38 b (".netscape/cookies.txt"\)\))236 4100 y(opener)44 b(=)h (urllib2.build_opener\(urllib2.HTTPCook)o(ieProc)o(essor\()o(cj\)\))236 4191 y(r)g(=)g(opener.open\("http://example.com/"\))0 4478 y FN(The)20 b(ne)o(xt)g(e)o(xample)f(illustrates)h(the)h(use)f(of) h FJ(DefaultCookiePolicy)p FN(.)h(T)l(urn)e(on)g(RFC)h(2965)e(cookies,) h(be)g(more)g(strict)h(about)0 4578 y(domains)g(when)g(setting)h(and)f (returning)e(Netscape)j(cookies,)f(and)g(block)g(some)h(domains)e(from) h(setting)h(cookies)f(or)g(ha)n(ving)g(them)0 4677 y(returned:)p 0 5549 3901 4 v 0 5649 a FI(18.22.)52 b FJ(cookielib)22 b FI(\227)h(Cookie)g(handling)i(f)n(or)e(HTTP)g(clients)1691 b(679)p eop end %%Page: 680 692 TeXDict begin 680 691 bop 236 83 a FA(import)44 b(urllib2)236 174 y(from)g(cookielib)g(import)g(CookieJar,)f(DefaultCookiePolicy)236 266 y(policy)h(=)h(DefaultCookiePolicy\()416 357 y(rfc2965=True,)d (strict_ns_domain=Policy.DomainStrict,)416 448 y (blocked_domains=["ads.net",)e(".ads.net"]\))236 540 y(cj)45 b(=)f(CookieJar\(policy\))236 631 y(opener)g(=)h (urllib2.build_opener\(urllib2.HTTPCook)o(ieProc)o(essor\()o(cj\)\))236 722 y(r)g(=)g(opener.open\("http://example.com/"\))0 1227 y FE(18.23)122 b Fx(Cookie)31 b FE(\227)i(HTTP)g(state)i (management)0 1460 y FN(The)21 b FJ(Cookie)g FN(module)f(de\002nes)i (classes)g(for)f(abstracting)g(the)g(concept)f(of)i(cookies,)e(an)i (HTTP)f(state)i(management)c(mechanism.)0 1559 y(It)f(supports)f(both)g (simple)h(string-only)e(cookies,)h(and)g(pro)o(vides)f(an)i (abstraction)f(for)g(ha)n(ving)g(an)o(y)g(serializable)h(data-type)e (as)j(cookie)0 1659 y(v)n(alue.)0 1806 y(The)26 b(module)f(formerly)g (strictly)h(applied)f(the)i(parsing)e(rules)i(described)e(in)h(the)h (RFC)h(2109)d(and)g(RFC)j(2068)d(speci\002cations.)43 b(It)0 1905 y(has)23 b(since)h(been)e(disco)o(v)o(ered)f(that)j(MSIE)f (3.0x)f(doesn')o(t)g(follo)n(w)g(the)h(character)f(rules)h(outlined)f (in)i(those)f(specs.)34 b(As)24 b(a)g(result,)g(the)0 2005 y(parsing)19 b(rules)h(used)g(are)g(a)h(bit)f(less)i(strict.)0 2152 y FL(exception)d FD(CookieError)208 2251 y FN(Exception)f(f)o (ailing)i(because)f(of)h(RFC)i(2109)d(in)m(v)n(alidity:)k(incorrect)c (attrib)n(utes,)h(incorrect)f FO(Set-Cookie:)k FN(header)m(,)18 b(etc.)0 2398 y FL(class)j FD(BaseCookie)p FJ(\()p FC([)p FK(input)13 b FC(])p FJ(\))208 2498 y FN(This)20 b(class)i(is)f(a)g (dictionary-lik)o(e)d(object)i(whose)g(k)o(e)o(ys)g(are)g(strings)g (and)g(whose)g(v)n(alues)g(are)h FJ(Morsel)f FN(instances.)25 b(Note)20 b(that)208 2598 y(upon)e(setting)j(a)f(k)o(e)o(y)g(to)g(a)h (v)n(alue,)e(the)h(v)n(alue)g(is)h(\002rst)g(con)m(v)o(erted)c(to)k(a)f FJ(Morsel)g FN(containing)e(the)i(k)o(e)o(y)g(and)g(the)g(v)n(alue.)208 2724 y(If)g FK(input)h FN(is)g(gi)n(v)o(en,)d(it)j(is)g(passed)f(to)h (the)f FJ(load\(\))g FN(method.)0 2871 y FL(class)h FD(SimpleCookie)p FJ(\()p FC([)p FK(input)13 b FC(])p FJ(\))208 2971 y FN(This)24 b(class)i(deri)n(v)o(es)e(from)f FJ(BaseCookie)g FN(and)h(o)o(v)o(errides)f FJ(value_decode\(\))g FN(and)h FJ(value_encode\(\))e FN(to)j(be)g(the)208 3070 y(identity)19 b(and)h FJ(str\(\))f FN(respecti)n(v)o(ely)-5 b(.)0 3217 y FL(class)21 b FD(SerialCookie)p FJ(\()p FC([)p FK(input)13 b FC(])p FJ(\))208 3317 y FN(This)24 b(class)i(deri)n(v)o(es)e(from)f FJ(BaseCookie)g FN(and)h(o)o(v)o(errides)f FJ(value_decode\(\))g FN(and)h FJ(value_encode\(\))e FN(to)j(be)g(the)208 3416 y FJ(pickle.loads\(\))18 b FN(and)h FJ(pickle.dumps\(\))p FN(.)208 3543 y FL(Depr)o(ecated)24 b(since)i(r)o(elease)f(2.3.)41 b FN(Reading)24 b(pickled)h(v)n(alues)g(from)g(untrusted)f(cookie)g (data)i(is)g(a)g(huge)f(security)g(hole,)h(as)208 3642 y(pickle)f(strings)h(can)g(be)h(crafted)e(to)h(cause)g(arbitrary)f (code)h(to)g(e)o(x)o(ecute)f(on)h(your)f(serv)o(er)-5 b(.)42 b(It)27 b(is)g(supported)d(for)i(backw)o(ards)208 3742 y(compatibility)18 b(only)-5 b(,)19 b(and)h(may)f(e)n(v)o (entually)g(go)g(a)o(w)o(ay)-5 b(.)0 3889 y FL(class)21 b FD(SmartCookie)p FJ(\()p FC([)p FK(input)13 b FC(])p FJ(\))208 3989 y FN(This)25 b(class)i(deri)n(v)o(es)e(from)f FJ(BaseCookie)p FN(.)40 b(It)26 b(o)o(v)o(errides)e FJ (value_decode\(\))f FN(to)j(be)g FJ(pickle.loads\(\))d FN(if)j(it)h(is)f(a)208 4088 y(v)n(alid)21 b(pickle,)f(and)h(otherwise) g(the)h(v)n(alue)e(itself.)30 b(It)21 b(o)o(v)o(errides)f FJ(value_encode\(\))f FN(to)j(be)f FJ(pickle.dumps\(\))e FN(unless)208 4188 y(it)h(is)i(a)e(string,)g(in)g(which)g(case)g(it)h (returns)f(the)g(v)n(alue)f(itself.)208 4314 y FL(Depr)o(ecated)g (since)i(r)o(elease)e(2.3.)24 b FN(The)c(same)h(security)e(w)o(arning)g (from)g FJ(SerialCookie)g FN(applies)h(here.)0 4461 y(A)c(further)e (security)g(note)h(is)i(w)o(arranted.)22 b(F)o(or)14 b(backw)o(ards)h(compatibility)-5 b(,)14 b(the)h FJ(Cookie)g FN(module)f(e)o(xports)g(a)i(class)g(named)e FJ(Cookie)0 4561 y FN(which)28 b(is)h(just)g(an)f(alias)h(for)f FJ(SmartCookie)p FN(.)48 b(This)28 b(is)i(probably)c(a)i(mistak)o(e)h(and)e(will)j(lik)o (ely)e(be)g(remo)o(v)o(ed)e(in)i(a)h(future)e(v)o(er)n(-)0 4661 y(sion.)46 b(Y)-9 b(ou)27 b(should)f(not)h(use)g(the)g FJ(Cookie)g FN(class)h(in)f(your)f(applications,)i(for)e(the)i(same)f (reason)f(why)h(you)f(should)g(not)h(use)h(the)0 4760 y FJ(SerialCookie)19 b FN(class.)0 4907 y FL(See)i(Also:)0 5054 y FN(Module)e FJ(cookielib)g FN(\(section)h(18.22\):)208 5154 y(HTTP)g(cookie)f(handling)f(for)i(web)g FK(clients)p FN(.)25 b(The)20 b FJ(cookielib)f FN(and)h FJ(Cookie)f FN(modules)g(do)h(not)g(depend)f(on)g(each)h(other)-5 b(.)0 5300 y(RFC)22 b(2109,)c(\223)p FK(HTTP)j(State)f(Mana)o(g)o (ement)e(Mec)o(hanism)p FN(\224)208 5400 y(This)i(is)h(the)f(state)h (management)d(speci\002cation)i(implemented)e(by)i(this)g(module.)p 0 5549 3901 4 v 0 5649 a FI(680)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 681 693 TeXDict begin 681 692 bop 0 83 a Fv(18.23.1)101 b(Cookie)29 b(Objects)0 272 y FD(value_decode)p FJ(\()p FK(val)p FJ(\))208 372 y FN(Return)22 b(a)h(decoded)e(v)n(alue)h(from)f(a)i (string)g(representation.)30 b(Return)22 b(v)n(alue)g(can)g(be)h(an)o (y)f(type.)32 b(This)23 b(method)e(does)h(nothing)208 471 y(in)e FJ(BaseCookie)f FN(\227)i(it)f(e)o(xists)h(so)g(it)g(can)f (be)g(o)o(v)o(erridden.)0 618 y FD(value_encode)p FJ(\()p FK(val)p FJ(\))208 718 y FN(Return)i(an)i(encoded)d(v)n(alue.)34 b FK(val)23 b FN(can)g(be)h(an)o(y)e(type,)i(b)n(ut)f(return)f(v)n (alue)h(must)g(be)g(a)h(string.)34 b(This)24 b(method)e(does)h(nothing) e(in)208 817 y FJ(BaseCookie)d FN(\227)j(it)g(e)o(xists)g(so)f(it)h (can)f(be)g(o)o(v)o(erridden)208 950 y(In)f(general,)f(it)i(should)f (be)g(the)h(case)g(that)g FJ(value_encode\(\))d FN(and)i FJ(value_decode\(\))f FN(are)h(in)m(v)o(erses)g(on)g(the)g(range)g(of) 208 1050 y FK(value)p 394 1050 25 4 v 28 w(decode)p FN(.)0 1197 y FD(output)p FJ(\()p FC([)p FK(attr)o(s)p FC([)p FK(,)g(header)r FC([)p FK(,)g(sep)12 b FC(])g(])g(])p FJ(\))208 1296 y FN(Return)19 b(a)h(string)g(representation)e(suitable) i(to)g(be)g(sent)g(as)h(HTTP)f(headers.)k FK(attr)o(s)d FN(and)e FK(header)i FN(are)f(sent)g(to)g(each)g FJ(Morsel)p FN(')-5 b(s)208 1396 y FJ(output\(\))14 b FN(method.)22 b FK(sep)16 b FN(is)g(used)f(to)h(join)f(the)g(headers)g(together)m(,)f (and)h(is)h(by)f(def)o(ault)g(the)g(combination)e FJ('\\r\\n')i FN(\(CRLF\).)208 1495 y(Changed)j(in)j(v)o(ersion)e(2.5:)g(The)h(def)o (ault)g(separator)f(has)h(been)g(changed)e(from)h FJ('\\n')h FN(to)g(match)g(the)g(cookie)f(speci\002cation.)0 1642 y FD(js_output)p FJ(\()p FC([)p FK(attr)o(s)12 b FC(])p FJ(\))208 1742 y FN(Return)26 b(an)g(embeddable)f(Ja)n(v)n(aScript)h (snippet,)h(which,)h(if)f(run)e(on)i(a)g(bro)n(wser)e(which)h(supports) g(Ja)n(v)n(aScript,)h(will)h(act)f(the)208 1842 y(same)20 b(as)h(if)f(the)h(HTTP)f(headers)f(w)o(as)i(sent.)208 1974 y(The)e(meaning)g(for)h FK(attr)o(s)h FN(is)g(the)f(same)h(as)f (in)h FJ(output\(\))p FN(.)0 2121 y FD(load)p FJ(\()p FK(r)o(awdata)p FJ(\))208 2221 y FN(If)27 b FK(r)o(awdata)g FN(is)i(a)f(string,)h(parse)f(it)g(as)h(an)e FJ(HTTP_COOKIE)g FN(and)g(add)g(the)h(v)n(alues)f(found)f(there)h(as)i FJ(Morsel)p FN(s.)47 b(If)28 b(it)g(is)h(a)208 2321 y(dictionary)-5 b(,)17 b(it)k(is)g(equi)n(v)n(alent)e(to:)444 2545 y FA(for)44 b(k,)h(v)f(in)h(rawdata.items\(\):)623 2636 y(cookie[k])e(=)i(v)0 2978 y Fv(18.23.2)101 b(Morsel)29 b(Objects)0 3167 y FL(class)21 b FD(Morsel)p FJ(\(\))208 3266 y FN(Abstract)f(a)g(k)o(e)o(y/v)n(alue)f(pair)m(,)g(which)h(has)g (some)g(RFC)i(2109)c(attrib)n(utes.)208 3399 y(Morsels)i(are)g (dictionary-lik)o(e)e(objects,)h(whose)h(set)h(of)f(k)o(e)o(ys)g(is)h (constant)f(\227)g(the)h(v)n(alid)e(RFC)j(2109)d(attrib)n(utes,)h (which)f(are)349 3612 y FM(\017)o FJ(expires)349 3745 y FM(\017)o FJ(path)349 3878 y FM(\017)o FJ(comment)349 4011 y FM(\017)o FJ(domain)349 4144 y FM(\017)o FJ(max-age)349 4277 y FM(\017)o FJ(secure)349 4409 y FM(\017)o FJ(version)208 4623 y FN(The)g(k)o(e)o(ys)h(are)g(case-insensiti)n(v)o(e.)0 4770 y FD(value)208 4869 y FN(The)f(v)n(alue)h(of)g(the)g(cookie.)0 5016 y FD(coded_value)208 5116 y FN(The)f(encoded)g(v)n(alue)g(of)h (the)g(cookie)g(\227)g(this)h(is)g(what)f(should)f(be)i(sent.)0 5263 y FD(key)208 5362 y FN(The)e(name)h(of)g(the)g(cookie.)p 0 5549 3901 4 v 0 5649 a FI(18.23.)52 b FJ(Cookie)22 b FI(\227)h(HTTP)g(state)g(management)2126 b(681)p eop end %%Page: 682 694 TeXDict begin 682 693 bop 0 83 a FD(set)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(value)o(,)h(coded)p 769 83 25 4 v 28 w(value)p FJ(\))208 183 y FN(Set)g(the)h FK(k)o(e)n(y)p FN(,)e FK(value)h FN(and)g FK(coded)p 1152 183 V 28 w(value)f FN(members.)0 330 y FD(isReservedKey)p FJ(\()p FK(K)5 b FJ(\))208 429 y FN(Whether)19 b FK(K)26 b FN(is)21 b(a)g(member)d(of)i(the)h(set)g(of)e(k)o(e)o(ys)h(of)g(a)h FJ(Morsel)p FN(.)0 576 y FD(output)p FJ(\()p FC([)p FK(attr)o(s)p FC([)p FK(,)e(header)14 b FC(])e(])p FJ(\))208 676 y FN(Return)18 b(a)h(string)g(representation)e(of)i(the)f(Morsel,)h (suitable)g(to)g(be)g(sent)g(as)h(an)f(HTTP)g(header)-5 b(.)24 b(By)19 b(def)o(ault,)f(all)i(the)f(attrib)n(utes)208 775 y(are)26 b(included,)h(unless)g FK(attr)o(s)h FN(is)g(gi)n(v)o(en,) g(in)f(which)f(case)i(it)f(should)f(be)h(a)g(list)i(of)d(attrib)n(utes) h(to)g(use.)46 b FK(header)28 b FN(is)g(by)e(def)o(ault)208 875 y FJ("Set-Cookie:")p FN(.)0 1022 y FD(js_output)p FJ(\()p FC([)p FK(attr)o(s)12 b FC(])p FJ(\))208 1121 y FN(Return)26 b(an)g(embeddable)f(Ja)n(v)n(aScript)h(snippet,)h (which,)h(if)f(run)e(on)i(a)g(bro)n(wser)e(which)h(supports)g(Ja)n(v)n (aScript,)h(will)h(act)f(the)208 1221 y(same)20 b(as)h(if)f(the)h(HTTP) f(header)f(w)o(as)i(sent.)208 1354 y(The)e(meaning)g(for)h FK(attr)o(s)h FN(is)g(the)f(same)h(as)f(in)h FJ(output\(\))p FN(.)0 1501 y FD(OutputString)p FJ(\()p FC([)p FK(attr)o(s)12 b FC(])p FJ(\))208 1600 y FN(Return)19 b(a)i(string)f(representing)e (the)i(Morsel,)g(without)f(an)o(y)h(surrounding)d(HTTP)j(or)g(Ja)n(v)n (aScript.)208 1733 y(The)f(meaning)g(for)h FK(attr)o(s)h FN(is)g(the)f(same)h(as)f(in)h FJ(output\(\))p FN(.)0 2018 y Fv(18.23.3)101 b(Example)0 2221 y FN(The)20 b(follo)n(wing)e(e)o (xample)h(demonstrates)g(ho)n(w)h(to)g(use)g(the)h FJ(Cookie)e FN(module.)p 0 5549 3901 4 v 0 5649 a FI(682)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 683 695 TeXDict begin 683 694 bop 236 174 a FA(>>>)45 b(import)e(Cookie)236 266 y(>>>)i(C)f(=)h(Cookie.SimpleCookie\(\))236 357 y(>>>)g(C)f(=)h (Cookie.SerialCookie\(\))236 448 y(>>>)g(C)f(=)h (Cookie.SmartCookie\(\))236 540 y(>>>)g(C["fig"])e(=)i("newton")236 631 y(>>>)g(C["sugar"])e(=)h("wafer")236 722 y(>>>)h(print)f(C)g(#)h (generate)e(HTTP)i(headers)236 814 y(Set-Cookie:)e(sugar=wafer)236 905 y(Set-Cookie:)g(fig=newton)236 996 y(>>>)i(print)f(C.output\(\))f (#)h(same)h(thing)236 1088 y(Set-Cookie:)e(sugar=wafer)236 1179 y(Set-Cookie:)g(fig=newton)236 1270 y(>>>)i(C)f(=)h (Cookie.SmartCookie\(\))236 1362 y(>>>)g(C["rocky"])e(=)h("road")236 1453 y(>>>)h(C["rocky"]["path"])c(=)k("/cookie")236 1544 y(>>>)g(print)f(C.output\(header="Cookie:"\))236 1636 y(Cookie:)g(rocky=road;)f(Path=/cookie)236 1727 y(>>>)i(print)f (C.output\(attrs=[],)d(header="Cookie:"\))236 1818 y(Cookie:)j (rocky=road)236 1910 y(>>>)h(C)f(=)h(Cookie.SmartCookie\(\))236 2001 y(>>>)g(C.load\("chips=ahoy;)c(vienna=finger"\))h(#)j(load)f(from) g(a)h(string)f(\(HTTP)g(header\))236 2092 y(>>>)h(print)f(C)236 2183 y(Set-Cookie:)f(vienna=finger)236 2275 y(Set-Cookie:)g(chips=ahoy) 236 2366 y(>>>)i(C)f(=)h(Cookie.SmartCookie\(\))236 2457 y(>>>)g(C.load\('keebler="E=everybody;)40 b(L=\\\\"Loves\\\\";)i (fudge=\\\\012;";'\))236 2549 y(>>>)j(print)f(C)236 2640 y(Set-Cookie:)f(keebler="E=everybody;)f(L=\\"Loves\\";)g(fudge=\\012;") 236 2731 y(>>>)j(C)f(=)h(Cookie.SmartCookie\(\))236 2823 y(>>>)g(C["oreo"])e(=)i("doublestuff")236 2914 y(>>>)g (C["oreo"]["path"])d(=)i("/")236 3005 y(>>>)h(print)f(C)236 3097 y(Set-Cookie:)f(oreo=doublestuff;)f(Path=/)236 3188 y(>>>)j(C)f(=)h(Cookie.SmartCookie\(\))236 3279 y(>>>)g(C["twix"])e(=)i ("none)f(for)g(you")236 3371 y(>>>)h(C["twix"].value)236 3462 y('none)f(for)h(you')236 3553 y(>>>)g(C)f(=)h (Cookie.SimpleCookie\(\))236 3645 y(>>>)g(C["number"])e(=)h(7)h(#)g (equivalent)e(to)h(C["number"])f(=)i(str\(7\))236 3736 y(>>>)g(C["string"])e(=)h("seven")236 3827 y(>>>)h(C["number"].value) 236 3919 y('7')236 4010 y(>>>)g(C["string"].value)236 4101 y('seven')236 4193 y(>>>)g(print)f(C)236 4284 y(Set-Cookie:)f (number=7)236 4375 y(Set-Cookie:)g(string=seven)236 4467 y(>>>)i(C)f(=)h(Cookie.SerialCookie\(\))236 4558 y(>>>)g(C["number"])e (=)h(7)236 4649 y(>>>)h(C["string"])e(=)h("seven")236 4741 y(>>>)h(C["number"].value)236 4832 y(7)236 4923 y(>>>)g(C["string"].value)236 5015 y('seven')236 5106 y(>>>)g(print)f(C)236 5197 y(Set-Cookie:)f(number="I7\\012.")236 5289 y(Set-Cookie:)g(string="S'seven'\\012p1\\012.")236 5380 y(>>>)i(C)f(=)h(Cookie.SmartCookie\(\))236 5471 y(>>>)g(C["number"])e(=)h(7)236 5562 y(>>>)h(C["string"])e(=)h("seven") 236 5654 y(>>>)h(C["number"].value)236 5745 y(7)236 5836 y(>>>)g(C["string"].value)236 5928 y('seven')236 6019 y(>>>)g(print)f(C)236 6110 y(Set-Cookie:)f(number="I7\\012.")236 6202 y(Set-Cookie:)g(string=seven)p 0 5549 3901 4 v 0 5649 a FI(18.23.)52 b FJ(Cookie)22 b FI(\227)h(HTTP)g(state)g (management)2126 b(683)p eop end %%Page: 684 696 TeXDict begin 684 695 bop 0 88 a FE(18.24)122 b Fx(xmlrpclib)30 b FE(\227)j(XML-RPC)g(client)h(access)0 321 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 468 y(XML-RPC)24 b(is)g(a)f(Remote)g (Procedure)f(Call)i(method)e(that)h(uses)h(XML)f(passed)g(via)g(HTTP)g (as)h(a)g(transport.)32 b(W)m(ith)24 b(it,)g(a)g(client)f(can)0 567 y(call)i(methods)f(with)h(parameters)e(on)i(a)g(remote)f(serv)o(er) g(\(the)g(serv)o(er)g(is)i(named)d(by)i(a)g(URI\))g(and)f(get)h(back)f (structured)f(data.)38 b(This)0 667 y(module)21 b(supports)g(writing)h (XML-RPC)h(client)f(code;)h(it)g(handles)e(all)i(the)g(details)f(of)g (translating)g(between)f(conformable)f(Python)0 767 y(objects)g(and)g (XML)g(on)g(the)g(wire.)0 914 y FL(class)h FD(ServerProxy)p FJ(\()p FK(uri)p FC([)p FK(,)d(tr)o(ansport)q FC([)p FK(,)h(encoding)p FC([)p FK(,)f(verbose)p FC([)p FK(,)i(allow)p 2269 914 25 4 v 29 w(none)p FC([)p FK(,)f(use)p 2652 914 V 29 w(datetime)12 b FC(])g(])g(])g(])g(])p FJ(\))208 1013 y FN(A)28 b FJ(ServerProxy)e FN(instance)h(is)h(an)g(object)f (that)h(manages)e(communication)f(with)j(a)g(remote)e(XML-RPC)i(serv)o (er)-5 b(.)47 b(The)208 1113 y(required)26 b(\002rst)i(ar)o(gument)e (is)j(a)f(URI)g(\(Uniform)e(Resource)i(Indicator\),)f(and)h(will)g (normally)e(be)i(the)g(URL)h(of)e(the)h(serv)o(er)-5 b(.)208 1212 y(The)28 b(optional)f(second)g(ar)o(gument)f(is)j(a)g (transport)e(f)o(actory)g(instance;)33 b(by)28 b(def)o(ault)f(it)i(is)h (an)e(internal)f FJ(SafeTransport)208 1312 y FN(instance)j(for)h (https:)47 b(URLs)32 b(and)e(an)h(internal)g(HTTP)g FJ(Transport)f FN(instance)g(otherwise.)57 b(The)31 b(optional)f(third)g(ar)o(gu-)208 1412 y(ment)h(is)h(an)g(encoding,)g(by)f(def)o(ault)g(UTF-8.)59 b(The)32 b(optional)e(fourth)g(ar)o(gument)f(is)k(a)f(deb)n(ugging)d (\003ag.)60 b(If)31 b FK(allow)p 3714 1412 V 30 w(none)208 1511 y FN(is)h(true,)h(the)e(Python)f(constant)g FJ(None)h FN(will)h(be)f(translated)g(into)g(XML;)g(the)g(def)o(ault)f(beha)n (viour)f(is)k(for)d FJ(None)h FN(to)g(raise)208 1611 y(a)f FJ(TypeError)p FN(.)54 b(This)30 b(is)i(a)e(commonly-used)d(e)o (xtension)i(to)h(the)g(XML-RPC)h(speci\002cation,)h(b)n(ut)e(isn')o(t)g (supported)e(by)208 1711 y(all)e(clients)h(and)e(serv)o(ers;)k(see)e FO(http://ontosys)o(.com/xml-r)r(pc/e)n(xtensions)o(.ph)o(p)20 b FN(for)26 b(a)g(description.)42 b(The)25 b FK(use)p 3438 1711 V 30 w(datetime)g FN(\003ag)208 1810 y(can)f(be)g(used)g(to)g (cause)g(date/time)g(v)n(alues)g(to)g(be)g(presented)f(as)i FJ(datetime.datetime)d FN(objects;)k(this)e(is)i(f)o(alse)e(by)g(de-) 208 1910 y(f)o(ault.)51 b FJ(datetime.datetime)p FN(,)29 b FJ(datetime.date)e FN(and)i FJ(datetime.time)e FN(objects)i(may)g(be) g(passed)g(to)g(calls.)208 2009 y FJ(datetime.date)20 b FN(objects)j(are)f(con)m(v)o(erted)e(with)j(a)g(time)g(of)f (\22300:00:00\224.)30 b FJ(datetime.time)20 b FN(objects)j(are)f(con)m (v)o(erted)208 2109 y(using)d(today')-5 b(s)20 b(date.)208 2242 y(Both)32 b(the)h(HTTP)g(and)f(HTTPS)h(transports)e(support)h(the) g(URL)i(syntax)e(e)o(xtension)f(for)h(HTTP)h(Basic)g(Authentication:) 208 2342 y FJ(http://user:pass@host:port/path)p FN(.)25 b(The)d FJ(user:pass)f FN(portion)f(will)j(be)f(base64-encoded)d(as)j (an)g(HTTP)208 2441 y(`)-7 b(Authorization')17 b(header)m(,)h(and)i (sent)g(to)g(the)g(remote)f(serv)o(er)g(as)i(part)f(of)f(the)h (connection)e(process)i(when)f(in)m(v)n(oking)f(an)i(XML-)208 2541 y(RPC)h(method.)i(Y)-9 b(ou)20 b(only)f(need)g(to)h(use)g(this)h (if)f(the)g(remote)f(serv)o(er)g(requires)g(a)h(Basic)h(Authentication) d(user)i(and)g(passw)o(ord.)208 2674 y(The)25 b(returned)f(instance)h (is)i(a)f(proxy)f(object)g(with)h(methods)e(that)i(can)g(be)g(used)f (to)h(in)m(v)n(ok)o(e)f(corresponding)d(RPC)27 b(calls)g(on)208 2773 y(the)22 b(remote)g(serv)o(er)-5 b(.)32 b(If)23 b(the)g(remote)f(serv)o(er)g(supports)f(the)i(introspection)e(API,)i (the)f(proxy)f(can)i(also)g(be)g(used)f(to)h(query)f(the)208 2873 y(remote)d(serv)o(er)g(for)h(the)g(methods)f(it)i(supports)e (\(service)h(disco)o(v)o(ery\))d(and)j(fetch)g(other)f(serv)o(er)n (-associated)g(metadata.)208 3006 y FJ(ServerProxy)25 b FN(instance)h(methods)f(tak)o(e)i(Python)e(basic)i(types)f(and)g (objects)h(as)g(ar)o(guments)e(and)h(return)f(Python)g(basic)208 3105 y(types)18 b(and)g(classes.)25 b(T)-7 b(ypes)18 b(that)h(are)f(conformable)e(\(e.g.)24 b(that)18 b(can)g(be)h (marshalled)e(through)f(XML\),)i(include)g(the)g(follo)n(wing)208 3205 y(\(and)h(e)o(xcept)g(where)h(noted,)f(the)o(y)g(are)h (unmarshalled)e(as)j(the)f(same)h(Python)e(type\):)257 3416 y FL(Name)p 1401 3446 4 100 v 988 w(Meaning)p 208 3449 6441 4 v 257 3519 a FJ(boolean)p 1401 3549 4 100 v 846 w FN(The)h FJ(True)g FN(and)f FJ(False)h FN(constants)257 3618 y FJ(integers)p 1401 3648 V 796 w FN(P)o(ass)h(in)f(directly)257 3718 y FJ(floating-point)48 b(numbers)p 1401 3748 V 98 w FN(P)o(ass)21 b(in)f(directly)257 3818 y FJ(strings)p 1401 3848 V 846 w FN(P)o(ass)h(in)f(directly)257 3917 y FJ(arrays)p 1401 3947 V 896 w FN(An)o(y)f(Python)g(sequence)g(type)h (containing)e(conformable)g(elements.)24 b(Arrays)c(are)g(returned)f (as)h(lists)257 4017 y FJ(structures)p 1401 4047 V 696 w FN(A)h(Python)e(dictionary)-5 b(.)22 b(K)n(e)o(ys)e(must)h(be)f (strings,)g(v)n(alues)f(may)h(be)g(an)o(y)g(conformable)d(type.)257 4117 y FJ(dates)p 1401 4146 V 946 w FN(in)j(seconds)g(since)g(the)g (epoch)f(\(pass)i(in)f(an)g(instance)g(of)g(the)g FJ(DateTime)f FN(class\))i(or)f(a)h FJ(datetime.datetime)p FN(,)c FJ(datetime.date)h FN(or)i FJ(datetime.time)f FN(instance)257 4216 y FJ(binary)49 b(data)p 1401 4246 V 647 w FN(pass)21 b(in)f(an)g(instance)g(of)g(the)g FJ(Binary)g FN(wrapper)e(class)208 4344 y(This)f(is)i(the)e(full)h(set) g(of)f(data)h(types)f(supported)f(by)h(XML-RPC.)h(Method)e(calls)j(may) e(also)g(raise)h(a)g(special)g FJ(Fault)f FN(instance,)208 4444 y(used)30 b(to)h(signal)f(XML-RPC)h(serv)o(er)f(errors,)i(or)f FJ(ProtocolError)d FN(used)j(to)g(signal)f(an)h(error)e(in)i(the)g (HTTP/HTTPS)208 4543 y(transport)24 b(layer)-5 b(.)40 b(Both)25 b FJ(Fault)g FN(and)g FJ(ProtocolError)e FN(deri)n(v)o(e)h (from)h(a)g(base)h(class)g(called)f FJ(Error)p FN(.)40 b(Note)25 b(that)h(e)n(v)o(en)208 4643 y(though)16 b(starting)i(with)h (Python)e(2.2)h(you)f(can)i(subclass)f(b)n(uiltin)g(types,)h(the)f (xmlrpclib)f(module)g(currently)g(does)h(not)g(marshal)208 4743 y(instances)i(of)g(such)g(subclasses.)208 4876 y(When)g(passing)f (strings,)h(characters)g(special)g(to)h(XML)f(such)g(as)h(`)p FJ(<)p FN(',)e(`)p FJ(>)p FN(',)h(and)g(`)p FJ(&)p FN(')g(will)h(be)f (automatically)f(escaped.)24 b(Ho)n(w-)208 4975 y(e)n(v)o(er)m(,)j(it') -5 b(s)29 b(the)f(caller')-5 b(s)27 b(responsibility)g(to)g(ensure)g (that)h(the)f(string)g(is)i(free)e(of)g(characters)g(that)g(aren')o(t)f (allo)n(wed)h(in)h(XML,)208 5075 y(such)19 b(as)h(the)g(control)e (characters)g(with)i(ASCII)g(v)n(alues)f(between)g(0)g(and)g(31)g(\(e)o (xcept,)g(of)g(course,)f(tab,)i(ne)n(wline)f(and)g(carriage)208 5174 y(return\);)24 b(f)o(ailing)f(to)h(do)g(this)g(will)h(result)f(in) g(an)g(XML-RPC)g(request)g(that)g(isn')o(t)f(well-formed)f(XML.)i(If)g (you)f(ha)n(v)o(e)g(to)h(pass)208 5274 y(arbitrary)18 b(strings)i(via)h(XML-RPC,)f(use)g(the)h FJ(Binary)e FN(wrapper)g(class)i(described)e(belo)n(w)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(684)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 685 697 TeXDict begin 685 696 bop 208 83 a FJ(Server)37 b FN(is)h(retained)f (as)h(an)f(alias)i(for)e FJ(ServerProxy)f FN(for)h(backw)o(ards)f (compatibility)-5 b(.)75 b(Ne)n(w)38 b(code)f(should)f(use)208 183 y FJ(ServerProxy)p FN(.)208 315 y(Changed)18 b(in)j(v)o(ersion)e (2.5:)g(The)h FK(use)p 1286 315 25 4 v 30 w(datetime)f FN(\003ag)i(w)o(as)g(added.)0 462 y FL(See)g(Also:)0 609 y FK(XML-RPC)f(HO)l(WT)o(O)0 708 y Fy(\()p FO(http://www)l(.tldp)m (.org/HO)n(WT)l(O/XML-RPC)o(-HO)n(WT)l(O/in)o(de)m(x.html)-6 b Fy(\))208 808 y FN(A)17 b(good)e(description)g(of)i(XML)g(operation)d (and)j(client)f(softw)o(are)h(in)g(se)n(v)o(eral)f(languages.)22 b(Contains)16 b(pretty)g(much)g(e)n(v)o(erything)208 908 y(an)k(XML-RPC)g(client)h(de)n(v)o(eloper)c(needs)j(to)h(kno)n(w)-5 b(.)0 1055 y FK(XML-RPC)20 b(Hac)n(ks)h(pa)o(g)o(e)0 1154 y Fy(\()p FO(http://xmlr)r(pc-c.sourcef)n(orge)o(.net/h)o(ac)o(ks) o(.p)o(hp)-6 b Fy(\))208 1254 y FN(Extensions)19 b(for)g(v)n(arious)g (open-source)f(libraries)i(to)g(support)f(introspection)f(and)i (multicall.)0 1538 y Fv(18.24.1)101 b(Ser)s(v)n(erPro)m(xy)29 b(Objects)0 1741 y FN(A)e FJ(ServerProxy)e FN(instance)h(has)h(a)g (method)e(corresponding)e(to)j(each)h(remote)e(procedure)f(call)j (accepted)e(by)h(the)h(XML-RPC)0 1841 y(serv)o(er)-5 b(.)24 b(Calling)d(the)f(method)e(performs)h(an)h(RPC,)h(dispatched)e (by)g(both)h(name)f(and)h(ar)o(gument)d(signature)i(\(e.g.)25 b(the)20 b(same)g(method)0 1940 y(name)k(can)h(be)g(o)o(v)o(erloaded)d (with)k(multiple)e(ar)o(gument)f(signatures\).)38 b(The)25 b(RPC)i(\002nishes)e(by)g(returning)e(a)i(v)n(alue,)g(which)g(may)g(be) 0 2040 y(either)20 b(returned)e(data)i(in)h(a)f(conformant)e(type)h(or) h(a)h FJ(Fault)f FN(or)g FJ(ProtocolError)e FN(object)i(indicating)e (an)j(error)-5 b(.)0 2187 y(Serv)o(ers)18 b(that)h(support)e(the)i(XML) f(introspection)f(API)i(support)e(some)i(common)d(methods)i(grouped)e (under)h(the)i(reserv)o(ed)e FJ(system)0 2287 y FN(member:)0 2433 y FD(system.listMethods)p FJ(\(\))208 2533 y FN(This)j(method)f (returns)g(a)i(list)g(of)f(strings,)g(one)f(for)h(each)g (\(non-system\))e(method)h(supported)f(by)h(the)i(XML-RPC)f(serv)o(er) -5 b(.)0 2680 y FD(system.methodSignature)p FJ(\()p FK(name)p FJ(\))208 2780 y FN(This)28 b(method)e(tak)o(es)i(one)f(parameter)m(,)h (the)g(name)f(of)h(a)g(method)e(implemented)g(by)i(the)f(XML-RPC)i (serv)o(er)-5 b(.It)27 b(returns)g(an)208 2879 y(array)f(of)h(possible) g(signatures)f(for)h(this)g(method.)45 b(A)28 b(signature)e(is)i(an)f (array)f(of)h(types.)46 b(The)27 b(\002rst)h(of)f(these)g(types)g(is)i (the)208 2979 y(return)19 b(type)g(of)h(the)g(method,)f(the)h(rest)h (are)f(parameters.)208 3111 y(Because)h(multiple)g(signatures)g(\(ie.) 29 b(o)o(v)o(erloading\))18 b(is)k(permitted,)e(this)i(method)e (returns)h(a)h(list)h(of)e(signatures)f(rather)h(than)g(a)208 3211 y(singleton.)208 3343 y(Signatures)e(themselv)o(es)h(are)g (restricted)g(to)h(the)f(top)g(le)n(v)o(el)h(parameters)e(e)o(xpected)g (by)h(a)h(method.)j(F)o(or)c(instance)g(if)h(a)g(method)208 3443 y(e)o(xpects)j(one)g(array)g(of)h(structs)g(as)h(a)f(parameter)m (,)g(and)f(it)i(returns)e(a)h(string,)h(its)g(signature)e(is)i(simply)e (\224string,)i(array\224.)38 b(If)25 b(it)208 3543 y(e)o(xpects)19 b(three)h(inte)o(gers)f(and)h(returns)f(a)i(string,)e(its)j(signature)d (is)i(\224string,)e(int,)h(int,)h(int\224.)208 3675 y(If)d(no)h (signature)f(is)i(de\002ned)e(for)g(the)h(method,)e(a)j(non-array)c(v)n (alue)i(is)i(returned.)j(In)c(Python)e(this)j(means)e(that)h(the)g (type)g(of)g(the)208 3775 y(returned)f(v)n(alue)h(will)i(be)g (something)d(other)i(that)g(list.)0 3921 y FD(system.methodHelp)p FJ(\()p FK(name)p FJ(\))208 4021 y FN(This)31 b(method)e(tak)o(es)j (one)e(parameter)m(,)i(the)f(name)f(of)h(a)g(method)f(implemented)f(by) i(the)g(XML-RPC)g(serv)o(er)-5 b(.)57 b(It)31 b(returns)208 4121 y(a)f(documentation)c(string)k(describing)e(the)h(use)h(of)f(that) h(method.)52 b(If)29 b(no)h(such)f(string)g(is)i(a)n(v)n(ailable,)g(an) f(empty)e(string)i(is)208 4220 y(returned.)23 b(The)d(documentation)d (string)j(may)f(contain)h(HTML)f(markup.)0 4367 y(Introspection)g (methods)h(are)g(currently)g(supported)f(by)h(serv)o(ers)h(written)f (in)h(PHP)-9 b(,)22 b(C)g(and)e(Microsoft)g(.NET)-6 b(.)20 b(P)o(artial)h(introspection)0 4467 y(support)c(is)i(included)d(in)j (recent)e(updates)g(to)i(UserLand)e(Frontier)-5 b(.)23 b(Introspection)16 b(support)h(for)g(Perl,)i(Python)e(and)h(Ja)n(v)n(a) g(is)h(a)n(v)n(ailable)0 4566 y(at)i(the)f(XML-RPC)h(Hacks)f(page.)0 4851 y Fv(18.24.2)101 b(Boolean)30 b(Objects)0 5054 y FN(This)21 b(class)g(may)f(be)g(initialized)g(from)f(an)o(y)h(Python)f (v)n(alue;)h(the)g(instance)g(returned)f(depends)g(only)g(on)h(its)i (truth)d(v)n(alue.)25 b(It)c(supports)0 5154 y(v)n(arious)i(Python)f (operators)g(through)g FJ(__cmp__\(\))p FN(,)h FJ(__repr__\(\))p FN(,)g FJ(__int__\(\))p FN(,)g(and)g FJ(__nonzero__\(\))f FN(methods,)h(all)0 5253 y(implemented)18 b(in)j(the)f(ob)o(vious)e(w)o (ays.)0 5400 y(It)i(also)h(has)f(the)h(follo)n(wing)d(method,)h (supported)f(mainly)h(for)h(internal)f(use)i(by)e(the)i(unmarshalling)c (code:)p 0 5549 3901 4 v 0 5649 a FI(18.24.)52 b FJ(xmlrpclib)22 b FI(\227)h(XML-RPC)h(client)f(access)2029 b(685)p eop end %%Page: 686 698 TeXDict begin 686 697 bop 0 83 a FD(encode)p FJ(\()p FK(out)q FJ(\))208 183 y FN(Write)20 b(the)h(XML-RPC)f(encoding)e(of)i (this)h(Boolean)f(item)g(to)g(the)g(out)g(stream)g(object.)0 468 y Fv(18.24.3)101 b(DateTime)28 b(Objects)0 670 y FN(This)39 b(class)h(may)e(be)h(initialized)f(with)h(seconds)f(since)h (the)g(epoch,)j(a)d(time)g(tuple,)k(an)c(ISO)g(8601)e(time/date)i (string,)k(or)38 b(a)0 770 y FJ(datetime.datetime)p FN(,)31 b FJ(datetime.date)e FN(or)h FJ(datetime.time)f FN(instance.)57 b(It)31 b(has)h(the)e(follo)n(wing)g(methods,)i(sup-)0 870 y(ported)19 b(mainly)g(for)h(internal)f(use)i(by)e(the)i (marshalling/unmarshalling)16 b(code:)0 1017 y FD(decode)p FJ(\()p FK(string)p FJ(\))208 1116 y FN(Accept)j(a)i(string)f(as)h(the) f(instance')-5 b(s)20 b(ne)n(w)g(time)h(v)n(alue.)0 1263 y FD(encode)p FJ(\()p FK(out)q FJ(\))208 1363 y FN(Write)f(the)h (XML-RPC)f(encoding)e(of)i(this)h FJ(DateTime)e FN(item)i(to)f(the)g FK(out)i FN(stream)e(object.)0 1510 y(It)g(also)h(supports)e(certain)h (of)g(Python')-5 b(s)19 b(b)n(uilt-in)h(operators)e(through)g FJ(__cmp__\(\))h FN(and)h FJ(__repr__\(\))f FN(methods.)0 1794 y Fv(18.24.4)101 b(Binar)s(y)29 b(Objects)0 1997 y FN(This)f(class)h(may)e(be)h(initialized)f(from)g(string)g(data)h (\(which)f(may)g(include)g(NULs\).)48 b(The)27 b(primary)g(access)h(to) g(the)g(content)f(of)g(a)0 2097 y FJ(Binary)20 b FN(object)f(is)i(pro)o (vided)d(by)i(an)g(attrib)n(ute:)0 2244 y FD(data)208 2343 y FN(The)f(binary)g(data)h(encapsulated)f(by)h(the)g FJ(Binary)g FN(instance.)k(The)c(data)g(is)h(pro)o(vided)d(as)j(an)f (8-bit)f(string.)0 2490 y FJ(Binary)29 b FN(objects)g(ha)n(v)o(e)g(the) h(follo)n(wing)e(methods,)i(supported)e(mainly)h(for)g(internal)f(use)i (by)f(the)h(marshalling/unmarshalling)0 2590 y(code:)0 2737 y FD(decode)p FJ(\()p FK(string)p FJ(\))208 2836 y FN(Accept)19 b(a)i(base64)e(string)h(and)g(decode)f(it)i(as)g(the)f (instance')-5 b(s)20 b(ne)n(w)g(data.)0 2983 y FD(encode)p FJ(\()p FK(out)q FJ(\))208 3083 y FN(Write)g(the)h(XML-RPC)f(base)h(64) e(encoding)g(of)g(this)i(binary)e(item)h(to)h(the)f(out)g(stream)g (object.)0 3230 y(It)g(also)h(supports)e(certain)h(of)g(Python')-5 b(s)19 b(b)n(uilt-in)h(operators)e(through)g(a)j FJ(__cmp__\(\))e FN(method.)0 3515 y Fv(18.24.5)101 b(F)-5 b(ault)28 b(Objects)0 3718 y FN(A)21 b FJ(Fault)f FN(object)f(encapsulates)h(the)g(content)f (of)h(an)g(XML-RPC)h(f)o(ault)f(tag.)25 b(F)o(ault)20 b(objects)g(ha)n(v)o(e)g(the)g(follo)n(wing)e(members:)0 3865 y FD(faultCode)208 3964 y FN(A)i(string)g(indicating)f(the)h(f)o (ault)g(type.)0 4111 y FD(faultString)208 4211 y FN(A)g(string)g (containing)e(a)j(diagnostic)e(message)h(associated)g(with)g(the)h(f)o (ault.)0 4496 y Fv(18.24.6)101 b(ProtocolError)30 b(Objects)0 4698 y FN(A)d FJ(ProtocolError)d FN(object)h(describes)h(a)h(protocol)d (error)h(in)h(the)g(underlying)e(transport)h(layer)g(\(such)h(as)h(a)f (404)f(`not)h(found')0 4798 y(error)19 b(if)i(the)f(serv)o(er)f(named)g (by)h(the)g(URI)h(does)f(not)g(e)o(xist\).)k(It)d(has)f(the)g(follo)n (wing)f(members:)0 4945 y FD(url)208 5045 y FN(The)g(URI)i(or)f(URL)h (that)f(triggered)f(the)h(error)-5 b(.)0 5191 y FD(errcode)208 5291 y FN(The)19 b(error)g(code.)p 0 5549 3901 4 v 0 5649 a FI(686)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 687 699 TeXDict begin 687 698 bop 0 83 a FD(errmsg)208 183 y FN(The)19 b(error)g(message)i(or)e(diagnostic)g(string.)0 330 y FD(headers)208 429 y FN(A)h(string)g(containing)e(the)j(headers)e (of)h(the)g(HTTP/HTTPS)g(request)g(that)g(triggered)e(the)j(error)-5 b(.)0 714 y Fv(18.24.7)101 b(MultiCall)29 b(Objects)0 917 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.4.)0 1064 y(In)29 b FO(http://www)l(.xmlr)r(pc.com/discuss/msgReader\04524120)o(8)-6 b FN(,)31 b(an)f(approach)d(is)j(presented)e(to)h(encapsulate)f (multiple)h(calls)h(to)f(a)0 1163 y(remote)19 b(serv)o(er)h(into)g(a)g (single)g(request.)0 1310 y FL(class)h FD(MultiCall)p FJ(\()p FK(server)r FJ(\))208 1410 y FN(Create)30 b(an)h(object)f(used) g(to)h(boxcar)e(method)g(calls.)57 b FK(server)33 b FN(is)f(the)e(e)n (v)o(entual)g(tar)o(get)f(of)h(the)h(call.)57 b(Calls)31 b(can)g(be)f(made)208 1510 y(to)k(the)g(result)g(object,)j(b)n(ut)d (the)o(y)f(will)i(immediately)e(return)f FJ(None)p FN(,)38 b(and)33 b(only)g(store)h(the)g(call)h(name)e(and)h(parameters)208 1609 y(in)i(the)g FJ(MultiCall)g FN(object.)72 b(Calling)37 b(the)f(object)g(itself)h(causes)f(all)h(stored)f(calls)h(to)f(be)g (transmitted)g(as)h(a)g(single)208 1709 y FJ(system.multicall)24 b FN(request.)43 b(The)27 b(result)f(of)g(this)i(call)f(is)g(a)g (generator;)h(iterating)e(o)o(v)o(er)f(this)i(generator)e(yields)i(the) 208 1808 y(indi)n(vidual)18 b(results.)0 1955 y(A)j(usage)e(e)o(xample) g(of)h(this)h(class)g(is)236 2194 y FA(multicall)44 b(=)g (MultiCall\(server_proxy\))236 2285 y(multicall.add\(2,3\))236 2376 y(multicall.get_address\("Guido"\))236 2467 y(add_result,)f (address)h(=)h(multicall\(\))0 2892 y Fv(18.24.8)101 b(Con)n(v)n(enience)30 b(Functions)0 3081 y FD(boolean)p FJ(\()p FK(value)p FJ(\))208 3181 y FN(Con)m(v)o(ert)18 b(an)o(y)i(Python)f(v)n(alue)g(to)i(one)e(of)h(the)g(XML-RPC)h(Boolean) f(constants,)f FJ(True)h FN(or)g FJ(False)p FN(.)0 3328 y FD(dumps)p FJ(\()p FK(par)o(ams)p FC([)p FK(,)e(methodname)p FC([)p FK(,)g(methodr)m(esponse)p FC([)p FK(,)f(encoding)p FC([)p FK(,)h(allow)p 2327 3328 25 4 v 30 w(none)12 b FC(])g(])g(])g(])p FJ(\))208 3427 y FN(Con)m(v)o(ert)20 b FK(par)o(ams)h FN(into)g(an)h(XML-RPC)h(request.)29 b(or)21 b(into)h(a)g(response)f(if)h FK(methodr)m(esponse)d FN(is)k(true.)30 b FK(par)o(ams)21 b FN(can)g(be)h(either)208 3527 y(a)d(tuple)f(of)h(ar)o(guments)e(or)h(an)h(instance)g(of)f(the)h FJ(Fault)g FN(e)o(xception)e(class.)25 b(If)19 b FK(methodr)m(esponse)e FN(is)j(true,)e(only)g(a)h(single)g(v)n(alue)208 3626 y(can)j(be)h(returned,)f(meaning)f(that)j FK(par)o(ams)e FN(must)h(be)g(of)g(length)f(1.)33 b FK(encoding)p FN(,)21 b(if)j(supplied,)e(is)i(the)f(encoding)e(to)i(use)g(in)h(the)208 3726 y(generated)f(XML;)i(the)g(def)o(ault)f(is)i(UTF-8.)39 b(Python')-5 b(s)25 b FJ(None)g FN(v)n(alue)f(cannot)g(be)h(used)g(in)g (standard)f(XML-RPC;)h(to)h(allo)n(w)208 3826 y(using)19 b(it)i(via)f(an)g(e)o(xtension,)f(pro)o(vide)f(a)j(true)f(v)n(alue)f (for)h FK(allow)p 2042 3826 V 29 w(none)p FN(.)0 3973 y FD(loads)p FJ(\()p FK(data)p FC([)p FK(,)e(use)p 644 3973 V 29 w(datetime)12 b FC(])p FJ(\))208 4072 y FN(Con)m(v)o(ert)20 b(an)i(XML-RPC)h(request)e(or)h(response)g(into)f(Python)g(objects,)i (a)f FJ(\()p FK(par)o(ams)p FJ(,)48 b FK(methodname)p FJ(\))p FN(.)29 b FK(par)o(ams)21 b FN(is)i(a)g(tuple)208 4172 y(of)h(ar)o(gument;)i FK(methodname)d FN(is)j(a)f(string,)h(or)f FJ(None)g FN(if)g(no)g(method)f(name)h(is)h(present)e(in)h(the)h(pack)o (et.)39 b(If)25 b(the)g(XML-RPC)208 4271 y(pack)o(et)f(represents)h(a)h (f)o(ault)f(condition,)g(this)h(function)e(will)i(raise)g(a)f FJ(Fault)g FN(e)o(xception.)39 b(The)25 b FK(use)p 3193 4271 V 30 w(datetime)g FN(\003ag)g(can)h(be)208 4371 y(used)18 b(to)g(cause)h(date/time)f(v)n(alues)g(to)g(be)h(presented)e (as)i FJ(datetime.datetime)d FN(objects;)j(this)g(is)g(f)o(alse)g(by)f (def)o(ault.)24 b(Note)208 4471 y(that)k(e)n(v)o(en)g(if)h(you)f(call)h (an)g(XML-RPC)g(method)e(with)i FJ(datetime.date)e FN(or)h FJ(datetime.time)f FN(objects,)k(the)o(y)d(are)208 4570 y(con)m(v)o(erted)17 b(to)j FJ(DateTime)g FN(objects)g(internally)-5 b(,)18 b(so)j(only)e FJ(datetime.datetime)f FN(objects)h(will)i(be)g (returned.)208 4703 y(Changed)d(in)j(v)o(ersion)e(2.5:)g(The)h FK(use)p 1286 4703 V 30 w(datetime)f FN(\003ag)i(w)o(as)g(added.)p 0 5549 3901 4 v 0 5649 a FI(18.24.)52 b FJ(xmlrpclib)22 b FI(\227)h(XML-RPC)h(client)f(access)2029 b(687)p eop end %%Page: 688 700 TeXDict begin 688 699 bop 0 83 a Fv(18.24.9)101 b(Example)29 b(of)f(Client)g(Usage)0 377 y FA(#)45 b(simple)e(test)i(program)e (\(from)h(the)h(XML-RPC)e(specification\))0 469 y(from)h(xmlrpclib)f (import)h(ServerProxy,)f(Error)0 651 y(#)i(server)e(=)i (ServerProxy\("http://localhost:8000"\))39 b(#)45 b(local)f(server)0 743 y(server)g(=)g(ServerProxy\("http://betty.userland.com"\))0 925 y(print)g(server)0 1108 y(try:)179 1199 y(print)g (server.examples.getStateName\(41\))0 1290 y(except)g(Error,)g(v:)179 1382 y(print)g("ERROR",)g(v)0 1668 y FN(T)-7 b(o)17 b(access)g(an)g (XML-RPC)h(serv)o(er)e(through)e(a)k(proxy)-5 b(,)15 b(you)h(need)g(to)h(de\002ne)f(a)h(custom)g(transport.)22 b(The)17 b(follo)n(wing)e(e)o(xample,)h(written)0 1768 y(by)k(NoboNobo,)d(sho)n(ws)j(ho)n(w:)236 2006 y FA(import)44 b(xmlrpclib,)f(httplib)236 2189 y(class)h (ProxiedTransport\(xmlrpclib.Transport\):)416 2280 y(def)g (set_proxy\(self,)e(proxy\):)595 2371 y(self.proxy)h(=)i(proxy)416 2463 y(def)f(make_connection\(self,)d(host\):)595 2554 y(self.realhost)i(=)h(host)236 2645 y(h)h(=)g (httplib.HTTP\(self.proxy\))236 2737 y(return)f(h)416 2828 y(def)g(send_request\(self,)e(connection,)h(handler,)g (request_body\):)595 2919 y(connection.putrequest\("POST",)d ('http://\045s\045s')i(\045)j(\(self.realhost,)d(handler\)\))416 3011 y(def)i(send_host\(self,)e(connection,)h(host\):)595 3102 y(connection.putheader\('Host',)d(self.realhost\))236 3285 y(p)45 b(=)g(ProxiedTransport\(\))236 3376 y (p.set_proxy\('proxy-server:8080'\))236 3467 y(server)f(=)h (xmlrpclib.Server\('http://time.xmlrpc.)o(com/RP)o(C2',)39 b(transport=p\))236 3559 y(print)44 b (server.currentTime.getCurrentTime\(\))0 4069 y FE(18.25)122 b Fx(SimpleXMLRPCServer)28 b FE(\227)33 b(Basic)f(XML-RPC)i(ser)t(v)m (er)0 4302 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 4448 y(The)k FJ(SimpleXMLRPCServer)e FN(module)h(pro)o(vides)g(a)i (basic)g(serv)o(er)f(frame)n(w)o(ork)e(for)i(XML-RPC)i(serv)o(ers)e (written)g(in)h(Python.)0 4548 y(Serv)o(ers)32 b(can)g(either)g(be)g (free)g(standing,)i(using)e FJ(SimpleXMLRPCServer)p FN(,)g(or)g (embedded)e(in)j(a)f(CGI)h(en)m(vironment,)f(using)0 4648 y FJ(CGIXMLRPCRequestHandler)p FN(.)0 4795 y FL(class)21 b FD(SimpleXMLRPCServer)p FJ(\()p FK(addr)r FC([)p FK(,)15 b(r)m(equestHandler)r FC([)p FK(,)k(lo)o(gRequests)p FC([)p FK(,)f(allow)p 2646 4795 25 4 v 30 w(none)p FC([)p FK(,)g(encoding)12 b FC(])g(])g(])g(])p FJ(\))208 4894 y FN(Create)27 b(a)g(ne)n(w)f(serv)o(er)g(instance.)44 b(This)27 b(class)h(pro)o(vides)d(methods)g(for)h(re)o(gistration)g(of) g(functions)f(that)i(can)g(be)f(called)h(by)208 4994 y(the)32 b(XML-RPC)h(protocol.)60 b(The)33 b FK(r)m(equestHandler)g FN(parameter)e(should)g(be)h(a)h(f)o(actory)f(for)g(request)g(handler)f (instances;)208 5093 y(it)c(def)o(aults)g(to)h FJ (SimpleXMLRPCRequestHandler)p FN(.)41 b(The)27 b FK(addr)i FN(and)d FK(r)m(equestHandler)i FN(parameters)e(are)h(passed)g(to)208 5193 y(the)e FJ(SocketServer.TCPServer)d FN(constructor)-5 b(.)39 b(If)26 b FK(lo)o(gRequests)e FN(is)i(true)g(\(the)f(def)o (ault\),)g(requests)g(will)i(be)e(logged;)208 5293 y(setting)d(this)h (parameter)e(to)i(f)o(alse)g(will)g(turn)f(of)n(f)g(logging.)30 b(The)23 b FK(allow)p 2294 5293 V 29 w(none)e FN(and)h FK(encoding)f FN(parameters)g(are)i(passed)f(on)g(to)208 5392 y FJ(xmlrpclib)g FN(and)g(control)g(the)i(XML-RPC)g(responses)e (that)i(will)g(be)f(returned)e(from)h(the)i(serv)o(er)-5 b(.)68 b(Changed)22 b(in)i(v)o(ersion)p 0 5549 3901 4 v 0 5649 a FI(688)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 689 701 TeXDict begin 689 700 bop 208 83 a FN(2.5:)19 b(The)h FK(allow)p 695 83 25 4 v 29 w(none)g FN(and)f FK(encoding)f FN(parameters)h(were)h(added.)0 230 y FL(class)h FD (CGIXMLRPCRequestHandler)p FJ(\()p FC([)p FK(allow)p 1617 230 V 25 w(none)p FC([)p FK(,)d(encoding)12 b FC(])g(])p FJ(\))208 330 y FN(Create)30 b(a)h(ne)n(w)g(instance)f(to)h(handle)e (XML-RPC)i(requests)g(in)f(a)h(CGI)g(en)m(vironment.)53 b(The)31 b FK(allow)p 3228 330 V 29 w(none)f FN(and)g FK(encoding)208 429 y FN(parameters)22 b(are)i(passed)g(on)f(to)h FJ(xmlrpclib)f FN(and)g(control)f(the)i(XML-RPC)h(responses)e(that)h (will)g(be)g(returned)e(from)h(the)208 529 y(serv)o(er)-5 b(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.3.)76 b(Changed)19 b(in)h(v)o(ersion)f(2.5:)h(The)g FK(allow)p 2356 529 V 29 w(none)f FN(and)h FK(encoding)e FN(parameters)h(were)h(added.)0 676 y FL(class)h FD(SimpleXMLRPCRequestHandler)p FJ(\(\))208 775 y FN(Create)k(a)g(ne)n(w)g(request)g(handler)e(instance.)39 b(This)25 b(request)g(handler)e(supports)h FJ(POST)h FN(requests)g(and)f(modi\002es)h(logging)e(so)208 875 y(that)d(the)g FK(lo)o(gRequests)f FN(parameter)g(to)h(the)g FJ(SimpleXMLRPCServer)e FN(constructor)g(parameter)h(is)i(honored.)0 1160 y Fv(18.25.1)101 b(SimpleXMLRPCSer)s(v)n(er)31 b(Objects)0 1363 y FN(The)24 b FJ(SimpleXMLRPCServer)e FN(class)j(is)g(based)f(on)g FJ(SocketServer.TCPServer)d FN(and)j(pro)o(vides)f(a)h(means)g(of)h (creating)0 1462 y(simple,)20 b(stand)g(alone)g(XML-RPC)g(serv)o(ers.)0 1609 y FD(register_function)p FJ(\()p FK(function)p FC([)p FK(,)15 b(name)d FC(])p FJ(\))208 1709 y FN(Re)o(gister)31 b(a)g(function)e(that)i(can)g(respond)f(to)h(XML-RPC)h(requests.)57 b(If)30 b FK(name)h FN(is)h(gi)n(v)o(en,)g(it)g(will)g(be)e(the)i (method)d(name)208 1808 y(associated)19 b(with)g FK(function)p FN(,)f(otherwise)g FK(function)p FJ(.__name__)e FN(will)k(be)f(used.)25 b FK(name)18 b FN(can)h(be)g(either)g(a)h(normal)e(or)h(Unicode)208 1908 y(string,)g(and)h(may)g(contain)f(characters)g(not)h(le)o(gal)f (in)i(Python)e(identi\002ers,)g(including)g(the)h(period)f(character)-5 b(.)0 2055 y FD(register_instance)p FJ(\()p FK(instance)p FC([)p FK(,)16 b(allow)p 1445 2055 V 29 w(dotted)p 1683 2055 V 29 w(names)c FC(])p FJ(\))208 2155 y FN(Re)o(gister)21 b(an)g(object)f(which)h(is)h(used)f(to)g(e)o(xpose)f(method)g(names)g (which)h(ha)n(v)o(e)f(not)h(been)g(re)o(gistered)e(using)i FJ(register_-)208 2254 y(function\(\))p FN(.)45 b(If)27 b FK(instance)g FN(contains)g(a)h FJ(_dispatch\(\))e FN(method,)i(it)g(is)g(called)g(with)f(the)h(requested)e(method)g(name) 208 2354 y(and)c(the)h(parameters)f(from)h(the)g(request.)33 b(Its)24 b(API)g(is)g FJ(def)49 b(_dispatch\(self,)e(method,)i (params\))22 b FN(\(note)g(that)208 2453 y FK(par)o(ams)h FN(does)h(not)g(represent)f(a)i(v)n(ariable)e(ar)o(gument)f(list\).)37 b(If)24 b(it)h(calls)g(an)f(underlying)e(function)g(to)j(perform)d(its) j(task,)g(that)208 2553 y(function)20 b(is)k(called)e(as)h FJ(func\()1149 2568 y(*)1199 2553 y(params\))p FN(,)e(e)o(xpanding)f (the)i(parameter)f(list.)33 b(The)22 b(return)g(v)n(alue)g(from)f FJ(_dispatch\(\))208 2653 y FN(is)i(returned)d(to)j(the)f(client)h(as)g (the)f(result.)32 b(If)22 b FK(instance)f FN(does)i(not)f(ha)n(v)o(e)f (a)i FJ(_dispatch\(\))e FN(method,)g(it)i(is)h(searched)d(for)h(an)208 2752 y(attrib)n(ute)d(matching)g(the)h(name)g(of)g(the)g(requested)f (method.)208 2885 y(If)j(the)g(optional)f FK(allow)p 895 2885 V 29 w(dotted)p 1133 2885 V 29 w(names)h FN(ar)o(gument)e(is)j (true)f(and)g(the)g(instance)g(does)g(not)g(ha)n(v)o(e)g(a)g FJ(_dispatch\(\))f FN(method,)208 2985 y(then)g(if)i(the)f(requested)f (method)g(name)h(contains)f(periods,)h(each)g(component)d(of)j(the)h (method)d(name)i(is)h(searched)f(for)f(indi-)208 3084 y(vidually)-5 b(,)17 b(with)j(the)g(ef)n(fect)f(that)g(a)h(simple)g (hierarchical)e(search)h(is)i(performed.)h(The)d(v)n(alue)g(found)f (from)g(this)i(search)g(is)g(then)208 3184 y(called)g(with)g(the)g (parameters)f(from)g(the)h(request,)g(and)f(the)i(return)e(v)n(alue)g (is)i(passed)f(back)g(to)g(the)g(client.)p 208 3260 3693 17 v 208 3634 17 374 v 282 3375 a FL(W)-5 b(ar)o(ning:)61 b FN(Enabling)21 b(the)i FK(allow)p 1322 3375 25 4 v 30 w(dotted)p 1561 3375 V 28 w(names)g FN(option)e(allo)n(ws)j (intruders)d(to)i(access)h(your)e(module')-5 b(s)22 b(global)g(v)n (ari-)282 3475 y(ables)e(and)g(may)f(allo)n(w)h(intruders)f(to)h(e)o(x) o(ecute)f(arbitrary)f(code)h(on)h(your)f(machine.)k(Only)d(use)g(this)h (option)e(on)g(a)h(secure,)282 3575 y(closed)g(netw)o(ork.)p 3883 3634 17 374 v 208 3651 3693 17 v 208 3792 a(Changed)31 b(in)i(v)o(ersion)e(2.3.5,)j(2.4.1:)d FK(allow)p 1545 3792 25 4 v 30 w(dotted)p 1784 3792 V 28 w(names)i FN(w)o(as)g(added)e (to)i(plug)f(a)h(security)f(hole;)38 b(prior)32 b(v)o(ersions)g(are)208 3891 y(insecure.)0 4038 y FD(register_introspection_functions)p FJ(\(\))208 4138 y FN(Re)o(gisters)40 b(the)g(XML-RPC)g(introspection)e (functions)g FJ(system.listMethods)p FN(,)k FJ(system.methodHelp)37 b FN(and)208 4237 y FJ(system.methodSignature)p FN(.)47 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 4384 y FD (register_multicall_functions)p FJ(\(\))208 4484 y FN(Re)o(gisters)h (the)g(XML-RPC)h(multicall)f(function)f(system.multicall.)0 4631 y FD(rpc_paths)208 4730 y FN(An)h(attrib)n(ute)h(v)n(alue)e(that)i (must)g(be)g(a)g(tuple)f(listing)h(v)n(alid)f(path)g(portions)g(of)g (the)h(URL)g(for)f(recei)n(ving)f(XML-RPC)i(requests.)208 4830 y(Requests)i(posted)e(to)i(other)f(paths)g(will)i(result)e(in)h(a) g(404)f(\223no)g(such)g(page\224)g(HTTP)h(error)-5 b(.)31 b(If)23 b(this)g(tuple)f(is)i(empty)-5 b(,)22 b(all)h(paths)208 4930 y(will)d(be)h(considered)d(v)n(alid.)24 b(The)c(def)o(ault)g(v)n (alue)f(is)i FJ(\('/',)49 b('/RPC2'\))p FN(.)h(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 5077 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(18.25.)52 b FJ(SimpleXMLRPCServer)20 b FI(\227)j(Basic)g(XML-RPC)h(ser)r(v)n(er)1599 b(689)p eop end %%Page: 690 702 TeXDict begin 690 701 bop 236 174 a FA(from)44 b(SimpleXMLRPCServer)e (import)i(SimpleXMLRPCServer)236 357 y(#)h(Create)f(server)236 448 y(server)g(=)h(SimpleXMLRPCServer\(\("localhost",)39 b(8000\)\))236 540 y(server.register_introspection_functions\()o(\))236 722 y(#)45 b(Register)e(pow\(\))h(function;)g(this)g(will)g(use)g(the)h (value)f(of)236 814 y(#)h(pow.__name__)e(as)h(the)h(name,)f(which)g(is) g(just)g('pow'.)236 905 y(server.register_function\(pow\))236 1088 y(#)h(Register)e(a)i(function)f(under)g(a)g(different)f(name)236 1179 y(def)i(adder_function\(x,y\):)416 1270 y(return)e(x)i(+)g(y)236 1362 y(server.register_function\(adder_function,)38 b('add'\))236 1544 y(#)45 b(Register)e(an)i(instance;)e(all)i(the)f(methods)f(of)i (the)f(instance)g(are)236 1636 y(#)h(published)e(as)i(XML-RPC)e (methods)h(\(in)g(this)g(case,)g(just)h('div'\).)236 1727 y(class)f(MyFuncs:)416 1818 y(def)g(div\(self,)f(x,)i(y\):)595 1910 y(return)f(x)g(//)h(y)236 2092 y (server.register_instance\(MyFuncs\(\)\))236 2275 y(#)g(Run)f(the)h (server's)e(main)h(loop)236 2366 y(server.serve_forever\(\))0 2653 y FN(The)20 b(follo)n(wing)e(client)j(code)e(will)i(call)g(the)f (methods)f(made)h(a)n(v)n(ailable)f(by)h(the)g(preceding)e(serv)o(er:) 236 2891 y FA(import)44 b(xmlrpclib)236 3073 y(s)h(=)g (xmlrpclib.Server\('http://localhost:8)o(000'\))236 3165 y(print)f(s.pow\(2,3\))88 b(#)45 b(Returns)f(2)1537 3178 y(**)1627 3165 y(3)g(=)g(8)236 3256 y(print)g(s.add\(2,3\))88 b(#)45 b(Returns)f(5)236 3347 y(print)g(s.div\(5,2\))88 b(#)45 b(Returns)f(5//2)g(=)g(2)236 3530 y(#)h(Print)f(list)g(of)h (available)e(methods)236 3621 y(print)h(s.system.listMethods\(\))0 4046 y Fv(18.25.2)101 b(CGIXMLRPCRequestHandler)0 4249 y FN(The)20 b FJ(CGIXMLRPCRequestHandler)c FN(class)21 b(can)f(be)h(used)f(to)g(handle)f(XML-RPC)i(requests)f(sent)g(to)g (Python)f(CGI)i(scripts.)0 4396 y FD(register_function)p FJ(\()p FK(function)p FC([)p FK(,)15 b(name)d FC(])p FJ(\))208 4496 y FN(Re)o(gister)31 b(a)g(function)e(that)i(can)g (respond)f(to)h(XML-RPC)h(requests.)57 b(If)30 b FK(name)h FN(is)h(gi)n(v)o(en,)g(it)g(will)g(be)e(the)i(method)d(name)208 4595 y(associated)d(with)h(function,)f(otherwise)g FK(function.)p 1727 4595 25 4 v 1754 4595 V 57 w(name)p 1965 4595 V 1994 4595 V 86 w FN(will)h(be)g(used.)43 b FK(name)26 b FN(can)h(be)f(either)g(a)h(normal)e(or)i(Unicode)208 4695 y(string,)19 b(and)h(may)g(contain)f(characters)g(not)h(le)o(gal)f (in)i(Python)e(identi\002ers,)g(including)g(the)h(period)f(character)-5 b(.)0 4842 y FD(register_instance)p FJ(\()p FK(instance)p FJ(\))208 4941 y FN(Re)o(gister)21 b(an)g(object)f(which)h(is)h(used)f (to)g(e)o(xpose)f(method)g(names)g(which)h(ha)n(v)o(e)f(not)h(been)g (re)o(gistered)e(using)i FJ(register_-)208 5041 y(function\(\))p FN(.)46 b(If)28 b(instance)f(contains)g(a)h FJ(_dispatch\(\))f FN(method,)h(it)g(is)h(called)f(with)f(the)h(requested)f(method)f(name) 208 5141 y(and)21 b(the)h(parameters)f(from)g(the)h(request;)g(the)g (return)f(v)n(alue)g(is)i(returned)d(to)i(the)g(client)g(as)h(the)f (result.)30 b(If)22 b(instance)f(does)h(not)208 5240 y(ha)n(v)o(e)i(a)i FJ(_dispatch\(\))d FN(method,)i(it)h(is)g(searched)e (for)g(an)h(attrib)n(ute)g(matching)f(the)h(name)f(of)h(the)g (requested)f(method;)i(if)208 5340 y(the)21 b(requested)e(method)h (name)g(contains)h(periods,)f(each)g(component)f(of)i(the)g(method)f (name)g(is)i(searched)e(for)g(indi)n(vidually)-5 b(,)p 0 5549 3901 4 v 0 5649 a FI(690)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 691 703 TeXDict begin 691 702 bop 208 83 a FN(with)24 b(the)g(ef)n(fect)g(that) g(a)g(simple)g(hierarchical)f(search)h(is)h(performed.)34 b(The)24 b(v)n(alue)f(found)g(from)g(this)h(search)g(is)h(then)f (called)208 183 y(with)c(the)g(parameters)f(from)g(the)h(request,)g (and)f(the)i(return)e(v)n(alue)g(is)i(passed)f(back)g(to)g(the)g (client.)0 330 y FD(register_introspection_functions)p FJ(\(\))208 429 y FN(Re)o(gister)44 b(the)g(XML-RPC)h(introspection)d (functions)h FJ(system.listMethods)p FN(,)k FJ(system.methodHelp)42 b FN(and)208 529 y FJ(system.methodSignature)p FN(.)0 676 y FD(register_multicall_functions)p FJ(\(\))208 775 y FN(Re)o(gister)20 b(the)g(XML-RPC)h(multicall)f(function)e FJ(system.multicall)p FN(.)0 922 y FD(handle_request)p FJ(\()p FC([)p FK(r)m(equest)p 1037 922 25 4 v 26 w(te)n(xt)j(=)g(None) 12 b FC(])p FJ(\))208 1022 y FN(Handle)20 b(a)h(XML-RPC)g(request.)26 b(If)20 b FK(r)m(equest)p 1528 1022 V 30 w(te)n(xt)j FN(is)e(gi)n(v)o(en,)f(it)h(should)f(be)g(the)h(POST)g(data)g(pro)o (vided)d(by)i(the)h(HTTP)g(serv)o(er)m(,)208 1121 y(otherwise)e(the)h (contents)g(of)g(stdin)g(will)h(be)f(used.)0 1268 y(Example:)236 1506 y FA(class)44 b(MyFuncs:)416 1598 y(def)g(div\(self,)f(x,)i(y\))f (:)h(return)f(x)g(//)h(y)236 1872 y(handler)f(=)h (CGIXMLRPCRequestHandler\(\))236 1963 y (handler.register_function\(pow\))236 2054 y (handler.register_function\(lambda)40 b(x,y:)k(x+y,)g('add'\))236 2146 y(handler.register_introspection_functions)o(\(\))236 2237 y(handler.register_instance\(MyFuncs\(\)\))236 2328 y(handler.handle_request\(\))0 2838 y FE(18.26)122 b Fx(DocXMLRPCServer)29 b FE(\227)k(Self-documenting)i(XML-RPC)e(ser)t(v) m(er)0 3071 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3218 y(The)30 b FJ(DocXMLRPCServer)e FN(module)i(e)o(xtends)f(the)h (classes)i(found)d(in)h FJ(SimpleXMLRPCServer)e FN(to)j(serv)o(e)f (HTML)g(docu-)0 3318 y(mentation)24 b(in)i(response)e(to)i(HTTP)f(GET)h (requests.)40 b(Serv)o(ers)25 b(can)g(either)g(be)g(free)g(standing,)h (using)f FJ(DocXMLRPCServer)p FN(,)f(or)0 3417 y(embedded)18 b(in)i(a)h(CGI)g(en)m(vironment,)c(using)i FJ (DocCGIXMLRPCRequestHandler)p FN(.)0 3564 y FL(class)i FD(DocXMLRPCServer)p FJ(\()p FK(addr)r FC([)p FK(,)16 b(r)m(equestHandler)r FC([)p FK(,)i(lo)o(gRequests)12 b FC(])g(])p FJ(\))208 3664 y FN(Create)122 b(a)g(ne)n(w)g(serv)o(er)f (instance.)330 b(All)123 b(parameters)e(ha)n(v)o(e)g(the)h(same)g (meaning)f(as)208 3764 y(for)197 b FJ (SimpleXMLRPCServer.SimpleXMLRPCServ)o(er)p FN(;)281 b FK(r)m(equestHandler)199 b FN(def)o(aults)e(to)208 3863 y FJ(DocXMLRPCRequestHandler)p FN(.)0 4010 y FL(class)21 b FD(DocCGIXMLRPCRequestHandler)p FJ(\(\))208 4110 y FN(Create)f(a)h(ne)n(w)f(instance)f(to)i(handle)e(XML-RPC)i(requests)e (in)i(a)f(CGI)h(en)m(vironment.)0 4257 y FL(class)g FD (DocXMLRPCRequestHandler)p FJ(\(\))208 4356 y FN(Create)d(a)g(ne)n(w)f (request)g(handler)g(instance.)23 b(This)18 b(request)f(handler)g (supports)f(XML-RPC)j(POST)f(requests,)g(documentation)208 4456 y(GET)h(requests,)g(and)g(modi\002es)g(logging)e(so)j(that)g(the)f FK(lo)o(gRequests)f FN(parameter)g(to)i(the)f FJ(DocXMLRPCServer)e FN(constructor)208 4555 y(parameter)h(is)j(honored.)0 4840 y Fv(18.26.1)101 b(DocXMLRPCSer)s(v)n(er)30 b(Objects)0 5043 y FN(The)18 b FJ(DocXMLRPCServer)e FN(class)k(is)f(deri)n(v)o(ed)e (from)g FJ(SimpleXMLRPCServer.SimpleXMLRPCServer)12 b FN(and)18 b(pro)o(vides)0 5143 y(a)26 b(means)f(of)g(creating)f (self-documenting,)f(stand)j(alone)e(XML-RPC)i(serv)o(ers.)40 b(HTTP)26 b(POST)g(requests)f(are)g(handled)f(as)i(XML-)0 5242 y(RPC)d(method)d(calls.)30 b(HTTP)22 b(GET)f(requests)g(are)h (handled)e(by)h(generating)f(p)o(ydoc-style)f(HTML)j(documentation.)k (This)21 b(allo)n(ws)h(a)0 5342 y(serv)o(er)d(to)i(pro)o(vide)d(its)j (o)n(wn)f(web-based)e(documentation.)p 0 5549 3901 4 v 0 5649 a FI(18.26.)52 b FJ(DocXMLRPCServer)21 b FI(\227)i (Self-documenting)i(XML-RPC)f(ser)r(v)n(er)1305 b(691)p eop end %%Page: 692 704 TeXDict begin 692 703 bop 0 83 a FD(set_server_title)p FJ(\()p FK(server)p 1062 83 25 4 v 27 w(title)p FJ(\))208 183 y FN(Set)16 b(the)g(title)h(used)f(in)g(the)g(generated)f(HTML)h (documentation.)k(This)c(title)h(will)g(be)f(used)g(inside)g(the)g (HTML)g(\224title\224)g(element.)0 330 y FD(set_server_name)p FJ(\()p FK(server)p 1012 330 V 27 w(name)p FJ(\))208 429 y FN(Set)25 b(the)g(name)g(used)g(in)g(the)g(generated)e(HTML)i (documentation.)37 b(This)25 b(name)f(will)i(appear)e(at)i(the)f(top)f (of)h(the)g(generated)208 529 y(documentation)17 b(inside)j(a)g (\224h1\224)g(element.)0 676 y FD(set_server_documentation)p FJ(\()p FK(server)p 1462 676 V 26 w(documentation)p FJ(\))208 775 y FN(Set)25 b(the)g(description)f(used)h(in)g(the)g(generated)f (HTML)h(documentation.)36 b(This)26 b(description)d(will)j(appear)e(as) i(a)f(paragraph,)208 875 y(belo)n(w)19 b(the)h(serv)o(er)g(name,)f(in)h (the)h(documentation.)0 1160 y Fv(18.26.2)101 b (DocCGIXMLRPCRequestHandler)0 1363 y FN(The)15 b FJ (DocCGIXMLRPCRequestHandler)c FN(class)16 b(is)g(deri)n(v)o(ed)e(from)g FJ(SimpleXMLRPCServer.CGIXMLRPCReques)o(tHand)o(ler)0 1462 y FN(and)27 b(pro)o(vides)f(a)i(means)f(of)g(creating)g (self-documenting,)e(XML-RPC)j(CGI)g(scripts.)48 b(HTTP)27 b(POST)h(requests)f(are)h(handled)e(as)0 1562 y(XML-RPC)h(method)e (calls.)45 b(HTTP)26 b(GET)h(requests)f(are)g(handled)f(by)h (generating)f(p)o(ydoc-style)f(HTML)j(documentation.)40 b(This)0 1662 y(allo)n(ws)20 b(a)h(serv)o(er)e(to)i(pro)o(vide)d(its)j (o)n(wn)f(web-based)e(documentation.)0 1808 y FD(set_server_title)p FJ(\()p FK(server)p 1062 1808 V 27 w(title)p FJ(\))208 1908 y FN(Set)e(the)g(title)h(used)f(in)g(the)g(generated)f(HTML)h (documentation.)k(This)c(title)h(will)g(be)f(used)g(inside)g(the)g (HTML)g(\224title\224)g(element.)0 2055 y FD(set_server_name)p FJ(\()p FK(server)p 1012 2055 V 27 w(name)p FJ(\))208 2155 y FN(Set)25 b(the)g(name)g(used)g(in)g(the)g(generated)e(HTML)i (documentation.)37 b(This)25 b(name)f(will)i(appear)e(at)i(the)f(top)f (of)h(the)g(generated)208 2254 y(documentation)17 b(inside)j(a)g (\224h1\224)g(element.)0 2401 y FD(set_server_documentation)p FJ(\()p FK(server)p 1462 2401 V 26 w(documentation)p FJ(\))208 2501 y FN(Set)25 b(the)g(description)f(used)h(in)g(the)g (generated)f(HTML)h(documentation.)36 b(This)26 b(description)d(will)j (appear)e(as)i(a)f(paragraph,)208 2600 y(belo)n(w)19 b(the)h(serv)o(er)g(name,)f(in)h(the)h(documentation.)p 0 5549 3901 4 v 0 5649 a FI(692)2122 b(Chapter)23 b(18.)53 b(Inter)r(net)23 b(Protocols)g(and)h(Suppor)s(t)p eop end %%Page: 693 705 TeXDict begin 693 704 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3296 427 y FG(NINETEEN)p 0 515 V 2046 978 a FT(Multimedia)57 b(Ser)6 b(vices)0 1457 y FN(The)16 b(modules)f(described)f(in)i(this)h (chapter)e(implement)f(v)n(arious)h(algorithms)g(or)h(interf)o(aces)f (that)h(are)g(mainly)f(useful)g(for)h(multimedia)0 1556 y(applications.)24 b(The)o(y)19 b(are)h(a)n(v)n(ailable)g(at)g(the)h (discretion)e(of)h(the)g(installation.)k(Here')-5 b(s)21 b(an)f(o)o(v)o(ervie)n(w:)50 1700 y FD(audioop)297 b FN(Manipulate)19 b(ra)o(w)h(audio)f(data.)50 1799 y FD(imageop)297 b FN(Manipulate)19 b(ra)o(w)h(image)g(data.)50 1899 y FD(aifc)447 b FN(Read)21 b(and)e(write)i(audio)e(\002les)i(in)f(AIFF)h (or)f(AIFC)h(format.)50 1998 y FD(sunau)397 b FN(Pro)o(vide)19 b(an)h(interf)o(ace)g(to)g(the)g(Sun)g(A)-5 b(U)21 b(sound)e(format.)50 2098 y FD(wave)447 b FN(Pro)o(vide)19 b(an)h(interf)o(ace)g(to)g(the)g (W)-10 b(A)f(V)21 b(sound)e(format.)50 2198 y FD(chunk)397 b FN(Module)19 b(to)i(read)e(IFF)i(chunks.)50 2297 y FD(colorsys)247 b FN(Con)m(v)o(ersion)18 b(functions)h(between)h(RGB)h (and)f(other)f(color)g(systems.)50 2397 y FD(rgbimg)347 b FN(Read)21 b(and)e(write)i(image)e(\002les)j(in)e(\223SGI)g(RGB\224)i (format)d(\(the)h(module)e(is)j FK(not)f FN(SGI)h(speci\002c)f (though!\).)50 2497 y FD(imghdr)347 b FN(Determine)20 b(the)g(type)f(of)h(image)g(contained)f(in)h(a)h(\002le)f(or)g(byte)g (stream.)50 2596 y FD(sndhdr)347 b FN(Determine)20 b(type)f(of)h(a)h (sound)e(\002le.)50 2696 y FD(ossaudiodev)97 b FN(Access)21 b(to)g(OSS-compatible)d(audio)h(de)n(vices.)0 3061 y FE(19.1)121 b Fx(audioop)32 b FE(\227)g(Manipulate)j(r)o(a)n(w)f(audio) g(data)0 3294 y FN(The)16 b FJ(audioop)g FN(module)f(contains)g(some)h (useful)g(operations)f(on)h(sound)f(fragments.)22 b(It)17 b(operates)e(on)h(sound)f(fragments)g(consisting)0 3394 y(of)23 b(signed)g(inte)o(ger)g(samples)h(8,)g(16)f(or)h(32)f(bits)h (wide,)g(stored)f(in)h(Python)f(strings.)35 b(This)24 b(is)h(the)e(same)h(format)f(as)h(used)f(by)h(the)f FJ(al)0 3493 y FN(and)d FJ(sunaudiodev)e FN(modules.)24 b(All)d(scalar)f(items) h(are)f(inte)o(gers,)f(unless)i(speci\002ed)f(otherwise.)0 3640 y(This)g(module)f(pro)o(vides)g(support)f(for)i(a-LA)-7 b(W)f(,)20 b(u-LA)-7 b(W)19 b(and)h(Intel/D)m(VI)f(ADPCM)i(encodings.)0 3787 y(A)i(fe)n(w)g(of)g(the)g(more)f(complicated)g(operations)f(only)h (tak)o(e)h(16-bit)f(samples,)i(otherwise)e(the)h(sample)g(size)h(\(in)e (bytes\))h(is)h(al)o(w)o(ays)f(a)0 3887 y(parameter)c(of)h(the)g (operation.)0 4034 y(The)g(module)f(de\002nes)h(the)g(follo)n(wing)e(v) n(ariables)i(and)f(functions:)0 4181 y FL(exception)g FD(error)208 4280 y FN(This)h(e)o(xception)e(is)j(raised)f(on)g(all)h (errors,)e(such)h(as)h(unkno)n(wn)d(number)g(of)i(bytes)g(per)g (sample,)f(etc.)0 4427 y FD(add)p FJ(\()p FK(fr)o(a)o(gment1,)f(fr)o(a) o(gment2,)h(width)p FJ(\))208 4527 y FN(Return)i(a)h(fragment)e(which)h (is)i(the)e(addition)g(of)g(the)h(tw)o(o)g(samples)f(passed)h(as)g (parameters.)29 b FK(width)21 b FN(is)i(the)f(sample)f(width)g(in)208 4626 y(bytes,)e(either)h FJ(1)p FN(,)g FJ(2)h FN(or)f FJ(4)p FN(.)25 b(Both)20 b(fragments)f(should)g(ha)n(v)o(e)h(the)g (same)h(length.)0 4773 y FD(adpcm2lin)p FJ(\()p FK(adpcmfr)o(a)o (gment,)16 b(width,)k(state)p FJ(\))208 4873 y FN(Decode)g(an)h (Intel/D)m(VI)f(ADPCM)i(coded)e(fragment)f(to)j(a)f(linear)g(fragment.) 26 b(See)c(the)f(description)f(of)h FJ(lin2adpcm\(\))e FN(for)208 4972 y(details)25 b(on)f(ADPCM)i(coding.)38 b(Return)25 b(a)g(tuple)f FJ(\()p FK(sample)p FJ(,)49 b FK(ne)o(wstate)p FJ(\))25 b FN(where)f(the)h(sample)g(has)g(the)g (width)g(speci\002ed)f(in)208 5072 y FK(width)p FN(.)0 5219 y FD(alaw2lin)p FJ(\()p FK(fr)o(a)o(gment,)18 b(width)p FJ(\))208 5319 y FN(Con)m(v)o(ert)24 b(sound)h(fragments)f(in)i(a-LA)-7 b(W)25 b(encoding)f(to)i(linearly)f(encoded)f(sound)h(fragments.)40 b(a-LA)-7 b(W)25 b(encoding)f(al)o(w)o(ays)p 0 5549 3901 4 v 3762 5649 a FI(693)p eop end %%Page: 694 706 TeXDict begin 694 705 bop 208 83 a FN(uses)20 b(8)h(bits)f(samples,)g (so)h FK(width)f FN(refers)g(only)f(to)i(the)f(sample)g(width)g(of)g (the)g(output)f(fragment)f(here.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.5.)0 230 y FD(avg)p FJ(\()p FK(fr)o(a)o(gment,)f(width)p FJ(\))208 330 y FN(Return)h(the)i(a)n(v)o(erage)d(o)o(v)o(er)h(all)i (samples)f(in)h(the)f(fragment.)0 476 y FD(avgpp)p FJ(\()p FK(fr)o(a)o(gment,)e(width)p FJ(\))208 576 y FN(Return)j(the)h(a)n(v)o (erage)f(peak-peak)f(v)n(alue)h(o)o(v)o(er)g(all)i(samples)f(in)g(the)g (fragment.)29 b(No)22 b(\002ltering)g(is)h(done,)e(so)h(the)g (usefulness)g(of)208 676 y(this)e(routine)f(is)i(questionable.)0 823 y FD(bias)p FJ(\()p FK(fr)o(a)o(gment,)d(width,)i(bias)p FJ(\))208 922 y FN(Return)f(a)i(fragment)d(that)j(is)g(the)f(original)f (fragment)f(with)j(a)f(bias)h(added)e(to)h(each)g(sample.)0 1069 y FD(cross)p FJ(\()p FK(fr)o(a)o(gment,)e(width)p FJ(\))208 1169 y FN(Return)h(the)i(number)d(of)i(zero)f(crossings)h(in) h(the)f(fragment)e(passed)i(as)h(an)f(ar)o(gument.)0 1316 y FD(findfactor)p FJ(\()p FK(fr)o(a)o(gment,)d(r)m(efer)m(ence)p FJ(\))208 1415 y FN(Return)22 b(a)h(f)o(actor)f FK(F)k FN(such)d(that)g FJ(rms\(add\()p FK(fr)o(a)o(gment)q FJ(,)47 b(mul\()p FK(r)m(efer)m(ence)p FJ(,)i(-)p FK(F)s FJ(\)\)\))22 b FN(is)i(minimal,)e(i.e.,)i(return)d(the)i(f)o(actor)208 1515 y(with)28 b(which)g(you)g(should)f(multiply)h FK(r)m(efer)m(ence)g FN(to)h(mak)o(e)f(it)h(match)f(as)h(well)g(as)g(possible)g(to)f FK(fr)o(a)o(gment)q FN(.)50 b(The)28 b(fragments)208 1614 y(should)19 b(both)g(contain)g(2-byte)g(samples.)208 1747 y(The)g(time)i(tak)o(en)f(by)f(this)i(routine)e(is)i(proportional) c(to)k FJ(len\()p FK(fr)o(a)o(gment)q FJ(\))p FN(.)0 1894 y FD(findfit)p FJ(\()p FK(fr)o(a)o(gment,)d(r)m(efer)m(ence)p FJ(\))208 1994 y FN(T)m(ry)h(to)h(match)g FK(r)m(efer)m(ence)g FN(as)h(well)g(as)f(possible)g(to)g(a)h(portion)e(of)g FK(fr)o(a)o(gment)i FN(\(which)e(should)h(be)g(the)g(longer)f (fragment\).)j(This)208 2093 y(is)29 b(\(conceptually\))d(done)h(by)h (taking)g(slices)i(out)e(of)g FK(fr)o(a)o(gment)q FN(,)i(using)e FJ(findfactor\(\))f FN(to)i(compute)e(the)h(best)h(match,)208 2193 y(and)19 b(minimizing)g(the)h(result.)25 b(The)20 b(fragments)e(should)h(both)h(contain)f(2-byte)g(samples.)25 b(Return)19 b(a)i(tuple)f FJ(\()p FK(of)o(fset)q FJ(,)49 b FK(factor)r FJ(\))208 2293 y FN(where)15 b FK(of)o(fset)j FN(is)f(the)g(\(inte)o(ger\))d(of)n(fset)i(into)g FK(fr)o(a)o(gment)h FN(where)f(the)g(optimal)f(match)h(started)g(and)g FK(factor)i FN(is)f(the)g(\(\003oating-point\))208 2392 y(f)o(actor)i(as)i(per)f FJ(findfactor\(\))p FN(.)0 2539 y FD(findmax)p FJ(\()p FK(fr)o(a)o(gment,)e(length)p FJ(\))208 2639 y FN(Search)j FK(fr)o(a)o(gment)h FN(for)f(a)h(slice)g(of)f(length)g FK(length)f FN(samples)i(\(not)f(bytes!\))f(with)i(maximum)e(ener)o(gy) -5 b(,)19 b(i.e.,)j(return)e FK(i)i FN(for)f(which)208 2738 y FJ(rms\(fragment[i)908 2753 y(*)958 2738 y(2:\(i+length\))1558 2753 y(*)1608 2738 y(2]\))15 b FN(is)21 b(maximal.)j(The)c(fragments)e (should)h(both)h(contain)f(2-byte)g(samples.)208 2871 y(The)g(routine)g(tak)o(es)i(time)f(proportional)d(to)k FJ(len\()p FK(fr)o(a)o(gment)q FJ(\))p FN(.)0 3018 y FD(getsample)p FJ(\()p FK(fr)o(a)o(gment,)c(width,)j(inde)n(x)p FJ(\))208 3118 y FN(Return)f(the)i(v)n(alue)e(of)h(sample)g FK(inde)n(x)g FN(from)f(the)h(fragment.)0 3265 y FD(lin2adpcm)p FJ(\()p FK(fr)o(a)o(gment,)d(width,)j(state)p FJ(\))208 3364 y FN(Con)m(v)o(ert)e(samples)i(to)g(4)g(bit)h(Intel/D)m(VI)e (ADPCM)i(encoding.)h(ADPCM)f(coding)e(is)i(an)f(adapti)n(v)o(e)e (coding)h(scheme,)g(whereby)208 3464 y(each)f(4)h(bit)g(number)e(is)j (the)e(dif)n(ference)f(between)h(one)g(sample)h(and)f(the)h(ne)o(xt,)f (di)n(vided)f(by)i(a)g(\(v)n(arying\))d(step.)25 b(The)19 b(Intel/D)m(VI)208 3563 y(ADPCM)i(algorithm)d(has)j(been)e(selected)h (for)g(use)g(by)g(the)g(IMA,)g(so)h(it)g(may)e(well)i(become)e(a)i (standard.)208 3696 y FK(state)26 b FN(is)h(a)f(tuple)f(containing)f (the)i(state)h(of)e(the)h(coder)-5 b(.)41 b(The)26 b(coder)f(returns)g (a)h(tuple)f FJ(\()p FK(adpcmfr)o(a)o(g)p FJ(,)48 b FK(ne)o(wstate)p FJ(\))p FN(,)26 b(and)g(the)208 3796 y FK(ne)o(wstate)g FN(should)f(be)h(passed)g(to)g(the)h(ne)o(xt)e(call)i(of)f FJ(lin2adpcm\(\))p FN(.)41 b(In)26 b(the)g(initial)h(call,)g FJ(None)f FN(can)g(be)h(passed)f(as)h(the)208 3896 y(state.)e FK(adpcmfr)o(a)o(g)19 b FN(is)i(the)f(ADPCM)h(coded)e(fragment)f(pack)o (ed)h(2)i(4-bit)e(v)n(alues)h(per)g(byte.)0 4042 y FD(lin2alaw)p FJ(\()p FK(fr)o(a)o(gment,)e(width)p FJ(\))208 4142 y FN(Con)m(v)o(ert)26 b(samples)h(in)h(the)g(audio)f(fragment)e(to)j (a-LA)-7 b(W)28 b(encoding)d(and)i(return)g(this)h(as)g(a)g(Python)f (string.)47 b(a-LA)-7 b(W)27 b(is)i(an)208 4242 y(audio)18 b(encoding)f(format)h(whereby)g(you)g(get)h(a)h(dynamic)d(range)h(of)h (about)g(13)f(bits)i(using)f(only)f(8)h(bit)h(samples.)k(It)c(is)g (used)f(by)208 4341 y(the)h(Sun)g(audio)f(hardw)o(are,)f(among)h (others.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 4488 y FD(lin2lin)p FJ(\()p FK(fr)o(a)o(gment,)f(width,)i(ne)o(wwidth)p FJ(\))208 4588 y FN(Con)m(v)o(ert)e(samples)i(between)g(1-,)g(2-)f(and) h(4-byte)f(formats.)0 4735 y FD(lin2ulaw)p FJ(\()p FK(fr)o(a)o(gment,)f (width)p FJ(\))208 4834 y FN(Con)m(v)o(ert)25 b(samples)i(in)h(the)f (audio)f(fragment)g(to)h(u-LA)-7 b(W)26 b(encoding)g(and)g(return)g (this)i(as)g(a)f(Python)f(string.)46 b(u-LA)-7 b(W)27 b(is)h(an)208 4934 y(audio)18 b(encoding)f(format)h(whereby)g(you)g (get)h(a)h(dynamic)d(range)h(of)h(about)g(14)f(bits)i(using)f(only)f(8) h(bit)h(samples.)k(It)c(is)g(used)f(by)208 5034 y(the)h(Sun)g(audio)f (hardw)o(are,)f(among)h(others.)0 5180 y FD(minmax)p FJ(\()p FK(fr)o(a)o(gment,)f(width)p FJ(\))208 5280 y FN(Return)h(a)i(tuple)f(consisting)f(of)h(the)g(minimum)f(and)h (maximum)e(v)n(alues)i(of)g(all)h(samples)f(in)g(the)g(sound)g (fragment.)p 0 5549 3901 4 v 0 5649 a FI(694)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 695 707 TeXDict begin 695 706 bop 0 83 a FD(max)p FJ(\()p FK(fr)o(a)o(gment,)18 b(width)p FJ(\))208 183 y FN(Return)h(the)i(maximum)d(of)i(the)g FK(absolute)f(value)h FN(of)g(all)g(samples)h(in)f(a)h(fragment.)0 330 y FD(maxpp)p FJ(\()p FK(fr)o(a)o(gment,)d(width)p FJ(\))208 429 y FN(Return)h(the)i(maximum)d(peak-peak)g(v)n(alue)h(in)i (the)f(sound)f(fragment.)0 576 y FD(mul)p FJ(\()p FK(fr)o(a)o(gment,)f (width,)j(factor)r FJ(\))208 676 y FN(Return)26 b(a)i(fragment)d(that)j (has)f(all)h(samples)f(in)g(the)g(original)f(fragment)g(multiplied)g (by)h(the)g(\003oating-point)e(v)n(alue)h FK(factor)r FN(.)208 775 y(Ov)o(er\003o)n(w)19 b(is)i(silently)f(ignored.)0 922 y FD(ratecv)p FJ(\()p FK(fr)o(a)o(gment,)e(width,)i(nc)o(hannels,)e (inr)o(ate)o(,)i(outr)o(ate)o(,)f(state)p FC([)p FK(,)h(weightA)p FC([)p FK(,)g(weightB)12 b FC(])g(])p FJ(\))208 1022 y FN(Con)m(v)o(ert)18 b(the)i(frame)g(rate)g(of)g(the)g(input)g (fragment.)208 1152 y FK(state)j FN(is)h(a)f(tuple)g(containing)e(the)i (state)h(of)f(the)g(con)m(v)o(erter)-5 b(.)31 b(The)23 b(con)m(v)o(erter)e(returns)h(a)h(tuple)g FJ(\()p FK(ne)o(wfr)o(a)o (gment)q FJ(,)48 b FK(ne)o(wstate)p FJ(\))p FN(,)208 1251 y(and)19 b FK(ne)o(wstate)h FN(should)f(be)i(passed)f(to)g(the)g (ne)o(xt)g(call)g(of)g FJ(ratecv\(\))p FN(.)k(The)c(initial)h(call)f (should)f(pass)i FJ(None)f FN(as)h(the)f(state.)208 1381 y(The)c FK(weightA)h FN(and)g FK(weightB)g FN(ar)o(guments)e(are)i (parameters)f(for)g(a)i(simple)f(digital)g(\002lter)g(and)g(def)o(ault) f(to)h FJ(1)h FN(and)e FJ(0)i FN(respecti)n(v)o(ely)-5 b(.)0 1528 y FD(reverse)p FJ(\()p FK(fr)o(a)o(gment,)18 b(width)p FJ(\))208 1628 y FN(Re)n(v)o(erse)h(the)i(samples)f(in)g(a)h (fragment)d(and)i(returns)f(the)h(modi\002ed)f(fragment.)0 1774 y FD(rms)p FJ(\()p FK(fr)o(a)o(gment,)f(width)p FJ(\))208 1874 y FN(Return)h(the)i(root-mean-square)16 b(of)k(the)g(fragment,)e(i.e.)1894 1975 y Fh(s)p 1977 1975 238 4 v 1987 2022 a(P)2088 2084 y Ft(S)2139 2096 y Fs(i)2167 2048 y Fg(2)p 1987 2121 218 4 v 2070 2197 a Ft(n)208 2353 y FN(This)i(is)h(a)g(measure)e(of)h(the)g(po)n(wer)f (in)i(an)f(audio)f(signal.)0 2500 y FD(tomono)p FJ(\()p FK(fr)o(a)o(gment,)f(width,)i(lfactor)-9 b(,)20 b(rfactor)r FJ(\))208 2600 y FN(Con)m(v)o(ert)i(a)i(stereo)f(fragment)f(to)i(a)g (mono)e(fragment.)33 b(The)23 b(left)h(channel)f(is)h(multiplied)f(by)g FK(lfactor)i FN(and)e(the)h(right)f(channel)208 2700 y(by)c FK(rfactor)k FN(before)18 b(adding)h(the)h(tw)o(o)h(channels)e (to)h(gi)n(v)o(e)g(a)g(mono)f(signal.)0 2846 y FD(tostereo)p FJ(\()p FK(fr)o(a)o(gment,)f(width,)i(lfactor)-9 b(,)19 b(rfactor)r FJ(\))208 2946 y FN(Generate)k(a)h(stereo)f(fragment)f (from)h(a)h(mono)f(fragment.)34 b(Each)23 b(pair)g(of)h(samples)g(in)f (the)h(stereo)g(fragment)e(are)i(computed)208 3046 y(from)h(the)h(mono) e(sample,)k(whereby)c(left)i(channel)f(samples)h(are)g(multiplied)f(by) h FK(lfactor)i FN(and)e(right)f(channel)g(samples)h(by)208 3145 y FK(rfactor)r FN(.)0 3292 y FD(ulaw2lin)p FJ(\()p FK(fr)o(a)o(gment,)18 b(width)p FJ(\))208 3392 y FN(Con)m(v)o(ert)23 b(sound)h(fragments)g(in)h(u-LA)-7 b(W)25 b(encoding)e(to)i(linearly)g (encoded)e(sound)h(fragments.)39 b(u-LA)-7 b(W)24 b(encoding)f(al)o(w)o (ays)208 3491 y(uses)d(8)h(bits)f(samples,)g(so)h FK(width)f FN(refers)g(only)f(to)i(the)f(sample)g(width)g(of)g(the)g(output)f (fragment)f(here.)0 3638 y(Note)31 b(that)h(operations)e(such)h(as)h FJ(mul\(\))f FN(or)g FJ(max\(\))g FN(mak)o(e)g(no)g(distinction)f (between)h(mono)f(and)h(stereo)g(fragments,)i(i.e.)e(all)0 3738 y(samples)24 b(are)f(treated)g(equal.)35 b(If)23 b(this)h(is)h(a)f(problem)e(the)h(stereo)h(fragment)e(should)g(be)i (split)g(into)f(tw)o(o)h(mono)f(fragments)f(\002rst)i(and)0 3838 y(recombined)18 b(later)-5 b(.)25 b(Here)20 b(is)h(an)f(e)o (xample)f(of)h(ho)n(w)g(to)g(do)g(that:)236 4076 y FA(def)45 b(mul_stereo\(sample,)c(width,)j(lfactor,)g(rfactor\):)416 4167 y(lsample)f(=)i(audioop.tomono\(sample,)c(width,)j(1,)g(0\))416 4258 y(rsample)f(=)i(audioop.tomono\(sample,)c(width,)j(0,)g(1\))416 4350 y(lsample)f(=)i(audioop.mul\(sample,)d(width,)h(lfactor\))416 4441 y(rsample)g(=)i(audioop.mul\(sample,)d(width,)h(rfactor\))416 4532 y(lsample)g(=)i(audioop.tostereo\(lsample,)40 b(width,)k(1,)h(0\)) 416 4624 y(rsample)e(=)i(audioop.tostereo\(rsample,)40 b(width,)k(0,)h(1\))416 4715 y(return)e(audioop.add\(lsample,)f (rsample,)h(width\))0 5001 y FN(If)24 b(you)g(use)g(the)g(ADPCM)h (coder)f(to)g(b)n(uild)g(netw)o(ork)f(pack)o(ets)h(and)g(you)f(w)o(ant) i(your)e(protocol)f(to)j(be)f(stateless)i(\(i.e.)e(to)g(be)g(able)g(to) 0 5101 y(tolerate)19 b(pack)o(et)f(loss\))i(you)e(should)g(not)h(only)f (transmit)h(the)g(data)g(b)n(ut)g(also)g(the)g(state.)25 b(Note)19 b(that)h(you)e(should)g(send)h(the)g FK(initial)g FN(state)0 5201 y(\(the)f(one)f(you)g(passed)h(to)g FJ(lin2adpcm\(\))p FN(\))e(along)h(to)h(the)g(decoder)m(,)e(not)i(the)g(\002nal)g(state)h (\(as)f(returned)e(by)i(the)g(coder\).)23 b(If)17 b(you)g(w)o(ant)0 5300 y(to)k(use)f FJ(struct.struct\(\))e FN(to)j(store)g(the)f(state)h (in)g(binary)e(you)g(can)i(code)e(the)i(\002rst)g(element)f(\(the)g (predicted)f(v)n(alue\))g(in)i(16)f(bits)0 5400 y(and)g(the)g(second)f (\(the)h(delta)g(inde)o(x\))f(in)h(8.)p 0 5549 3901 4 v 0 5649 a FI(19.1.)52 b FJ(audioop)22 b FI(\227)h(Manipulate)i(r)o(a)n (w)f(audio)g(data)2077 b(695)p eop end %%Page: 696 708 TeXDict begin 696 707 bop 0 83 a FN(The)25 b(ADPCM)g(coders)g(ha)n(v)o (e)f(ne)n(v)o(er)g(been)g(tried)h(against)f(other)g(ADPCM)i(coders,)f (only)f(against)g(themselv)o(es.)39 b(It)25 b(could)f(well)i(be)0 183 y(that)20 b(I)h(misinterpreted)d(the)i(standards)g(in)g(which)g (case)g(the)o(y)g(will)h(not)e(be)i(interoperable)c(with)k(the)f (respecti)n(v)o(e)f(standards.)0 330 y(The)26 b FJ(find)356 345 y(*)406 330 y(\(\))h FN(routines)e(might)h(look)g(a)i(bit)f(funn)o (y)e(at)i(\002rst)g(sight.)45 b(The)o(y)26 b(are)h(primarily)e(meant)h (to)h(do)g(echo)f(cancellation.)43 b(A)0 429 y(reasonably)19 b(f)o(ast)j(w)o(ay)f(to)h(do)f(this)g(is)h(to)g(pick)f(the)g(most)g (ener)o(getic)f(piece)g(of)h(the)h(output)e(sample,)g(locate)i(that)f (in)g(the)g(input)g(sample)0 529 y(and)f(subtract)f(the)h(whole)g (output)f(sample)h(from)f(the)h(input)g(sample:)236 767 y FA(def)45 b(echocancel\(outputdata,)c(inputdata\):)416 858 y(pos)j(=)h(audioop.findmax\(outputdata,)40 b(800\))178 b(#)45 b(one)f(tenth)g(second)416 950 y(out_test)f(=)i(outputdata[pos) 1539 963 y(*)1584 950 y(2:])416 1041 y(in_test)e(=)i(inputdata[pos)1449 1054 y(*)1494 1041 y(2:])416 1132 y(ipos,)f(factor)f(=)i (audioop.findfit\(in_test,)c(out_test\))416 1224 y(#)j(Optional)g (\(for)g(better)g(cancellation\):)416 1315 y(#)g(factor)g(=)h (audioop.findfactor\(in_test[ipos)2304 1328 y(*)2349 1315 y(2:ipo)o(s)2618 1328 y(*)2663 1315 y(2+le)o(n\(out_)o(test\)])o (,)416 1406 y(#)627 b(out_test\))416 1498 y(prefill)43 b(=)i('\\0')1044 1511 y(*)1089 1498 y(\(pos+ipos\))1539 1511 y(*)1584 1498 y(2)416 1589 y(postfill)e(=)i('\\0')1089 1602 y(*)1134 1589 y(\(len\(inputdata\)-len\(prefill\)-len)o(\(outpu)o (tdata\))o(\))416 1680 y(outputdata)e(=)h(prefill)g(+)h (audioop.mul\(outputdata,2,-factor\))39 b(+)45 b(postfill)416 1772 y(return)e(audioop.add\(inputdata,)f(outputdata,)g(2\))0 2282 y FE(19.2)121 b Fx(imageop)32 b FE(\227)g(Manipulate)j(r)o(a)n(w)f (image)f(data)0 2514 y FN(The)26 b FJ(imageop)g FN(module)e(contains)i (some)g(useful)g(operations)f(on)g(images.)43 b(It)27 b(operates)f(on)f(images)h(consisting)g(of)g(8)g(or)g(32)g(bit)0 2614 y(pix)o(els)20 b(stored)g(in)g(Python)f(strings.)25 b(This)20 b(is)h(the)g(same)f(format)f(as)i(used)f(by)g FJ(gl.lrectwrite\(\))e FN(and)h(the)h FJ(imgfile)g FN(module.)0 2761 y(The)g(module)f(de\002nes)h(the)g(follo)n(wing)e(v)n(ariables)i (and)f(functions:)0 2908 y FL(exception)g FD(error)208 3007 y FN(This)h(e)o(xception)e(is)j(raised)f(on)g(all)h(errors,)e (such)h(as)h(unkno)n(wn)d(number)g(of)i(bits)h(per)e(pix)o(el,)h(etc.)0 3154 y FD(crop)p FJ(\()p FK(ima)o(g)o(e)o(,)f(psize)o(,)i(width,)f (height,)f(x0,)h(y0,)g(x1,)f(y1)p FJ(\))208 3254 y FN(Return)i(the)i (selected)f(part)g(of)g FK(ima)o(g)o(e)p FN(,)g(which)g(should)f(be)h FK(width)g FN(by)g FK(height)h FN(in)f(size)h(and)f(consist)g(of)g(pix) o(els)g(of)g FK(psize)h FN(bytes.)208 3354 y FK(x0)p FN(,)g FK(y0)p FN(,)g FK(x1)g FN(and)f FK(y1)h FN(are)g(lik)o(e)g(the)g FJ(gl.lrectread\(\))e FN(parameters,)h(i.e.)h(the)g(boundary)d(is)k (included)e(in)h(the)g(ne)n(w)f(image.)208 3453 y(The)h(ne)n(w)g (boundaries)f(need)h(not)g(be)g(inside)h(the)g(picture.)34 b(Pix)o(els)24 b(that)g(f)o(all)g(outside)f(the)g(old)g(image)h(will)g (ha)n(v)o(e)f(their)g(v)n(alue)208 3553 y(set)e(to)f(zero.)k(If)c FK(x0)g FN(is)i(bigger)c(than)i FK(x1)g FN(the)g(ne)n(w)g(image)g(is)h (mirrored.)i(The)d(same)g(holds)g(for)g(the)g(y)g(coordinates.)0 3700 y FD(scale)p FJ(\()p FK(ima)o(g)o(e)o(,)f(psize)o(,)i(width,)f (height,)f(ne)o(wwidth,)g(ne)o(wheight)q FJ(\))208 3799 y FN(Return)e FK(ima)o(g)o(e)h FN(scaled)g(to)g(size)h FK(ne)o(wwidth)f FN(by)g FK(ne)o(wheight)q FN(.)23 b(No)18 b(interpolation)e(is)j(done,)e(scaling)h(is)h(done)e(by)h (simple-minded)208 3899 y(pix)o(el)h(duplication)g(or)h(remo)o(v)n(al.) k(Therefore,)18 b(computer)n(-generated)f(images)j(or)g(dithered)f (images)i(will)g(not)f(look)g(nice)g(after)208 3999 y(scaling.)0 4145 y FD(tovideo)p FJ(\()p FK(ima)o(g)o(e)o(,)e(psize)o(,)j(width,)f (height)q FJ(\))208 4245 y FN(Run)k(a)g(v)o(ertical)g(lo)n(w-pass)f (\002lter)i(o)o(v)o(er)d(an)i(image.)37 b(It)24 b(does)g(so)g(by)g (computing)e(each)i(destination)f(pix)o(el)g(as)i(the)f(a)n(v)o(erage)f (of)208 4345 y(tw)o(o)e(v)o(ertically-aligned)d(source)i(pix)o(els.)26 b(The)21 b(main)f(use)h(of)g(this)g(routine)f(is)i(to)f(forestall)f(e)o (xcessi)n(v)o(e)g(\003ick)o(er)h(if)g(the)g(image)g(is)208 4444 y(displayed)e(on)g(a)i(video)e(de)n(vice)h(that)g(uses)h (interlacing,)d(hence)h(the)i(name.)0 4591 y FD(grey2mono)p FJ(\()p FK(ima)o(g)o(e)o(,)d(width,)i(height,)f(thr)m(eshold)r FJ(\))208 4691 y FN(Con)m(v)o(ert)h(a)j(8-bit)f(deep)g(gre)o(yscale)f (image)h(to)g(a)h(1-bit)f(deep)g(image)g(by)g(thresholding)e(all)j(the) f(pix)o(els.)31 b(The)23 b(resulting)e(image)208 4790 y(is)g(tightly)e(pack)o(ed)g(and)h(is)h(probably)d(only)h(useful)h(as)h (an)f(ar)o(gument)e(to)i FJ(mono2grey\(\))p FN(.)0 4937 y FD(dither2mono)p FJ(\()p FK(ima)o(g)o(e)o(,)e(width,)i(height)q FJ(\))208 5037 y FN(Con)m(v)o(ert)e(an)i(8-bit)g(gre)o(yscale)f(image)h (to)g(a)h(1-bit)e(monochrome)e(image)j(using)f(a)i(\(simple-minded\))c (dithering)i(algorithm.)0 5184 y FD(mono2grey)p FJ(\()p FK(ima)o(g)o(e)o(,)f(width,)i(height,)f(p0,)h(p1)p FJ(\))208 5283 y FN(Con)m(v)o(ert)27 b(a)i(1-bit)e(monochrome)f(image)i(to)g(an)h (8)f(bit)h(gre)o(yscale)e(or)i(color)e(image.)50 b(All)29 b(pix)o(els)f(that)h(are)f(zero-v)n(alued)e(on)208 5383 y(input)d(get)h(v)n(alue)g FK(p0)g FN(on)g(output)f(and)g(all)i(one-v)n (alue)d(input)i(pix)o(els)g(get)g(v)n(alue)g FK(p1)g FN(on)g(output.)35 b(T)-7 b(o)25 b(con)m(v)o(ert)d(a)j(monochrome)p 0 5549 3901 4 v 0 5649 a FI(696)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 697 709 TeXDict begin 697 708 bop 208 83 a FN(black-and-white)17 b(image)i(to)i(gre)o(yscale)e(pass)i(the)f(v)n(alues)g FJ(0)g FN(and)g FJ(255)g FN(respecti)n(v)o(ely)-5 b(.)0 230 y FD(grey2grey4)p FJ(\()p FK(ima)o(g)o(e)o(,)18 b(width,)i(height)q FJ(\))208 330 y FN(Con)m(v)o(ert)e(an)i(8-bit)g(gre)o(yscale)f(image)h (to)g(a)h(4-bit)e(gre)o(yscale)g(image)h(without)f(dithering.)0 476 y FD(grey2grey2)p FJ(\()p FK(ima)o(g)o(e)o(,)f(width,)i(height)q FJ(\))208 576 y FN(Con)m(v)o(ert)e(an)i(8-bit)g(gre)o(yscale)f(image)h (to)g(a)h(2-bit)e(gre)o(yscale)g(image)h(without)f(dithering.)0 723 y FD(dither2grey2)p FJ(\()p FK(ima)o(g)o(e)o(,)e(width,)k(height)q FJ(\))208 823 y FN(Con)m(v)o(ert)28 b(an)h(8-bit)g(gre)o(yscale)g (image)g(to)g(a)h(2-bit)f(gre)o(yscale)g(image)g(with)h(dithering.)51 b(As)31 b(for)e FJ(dither2mono\(\))p FN(,)h(the)208 922 y(dithering)18 b(algorithm)h(is)i(currently)d(v)o(ery)h(simple.)0 1069 y FD(grey42grey)p FJ(\()p FK(ima)o(g)o(e)o(,)f(width,)i(height)q FJ(\))208 1169 y FN(Con)m(v)o(ert)e(a)j(4-bit)e(gre)o(yscale)g(image)h (to)g(an)h(8-bit)e(gre)o(yscale)g(image.)0 1316 y FD(grey22grey)p FJ(\()p FK(ima)o(g)o(e)o(,)f(width,)i(height)q FJ(\))208 1415 y FN(Con)m(v)o(ert)e(a)j(2-bit)e(gre)o(yscale)g(image)h(to)g(an)h (8-bit)e(gre)o(yscale)g(image.)0 1562 y FD(backward_compatible)208 1662 y FN(If)f(set)h(to)f(0,)h(the)f(functions)f(in)i(this)f(module)f (use)i(a)g(non-backw)o(ard)c(compatible)h(w)o(ay)j(of)f(representing)e (multi-byte)h(pix)o(els)h(on)208 1761 y(little-endian)k(systems.)35 b(The)23 b(SGI)h(for)e(which)h(this)h(module)e(w)o(as)i(originally)e (written)h(is)i(a)f(big-endian)d(system,)j(so)g(setting)208 1861 y(this)j(v)n(ariable)f(will)h(ha)n(v)o(e)f(no)h(ef)n(fect.)44 b(Ho)n(we)n(v)o(er)m(,)26 b(the)h(code)f(w)o(asn')o(t)g(originally)g (intended)f(to)i(run)f(on)g(an)o(ything)f(else,)k(so)e(it)208 1961 y(made)21 b(assumptions)f(about)h(byte)g(order)g(which)g(are)g (not)h(uni)n(v)o(ersal.)27 b(Setting)22 b(this)g(v)n(ariable)f(to)g(0)h (will)g(cause)g(the)g(byte)f(order)208 2060 y(to)f(be)g(re)n(v)o(ersed) f(on)g(little-endian)g(systems,)i(so)f(that)h(it)g(then)e(is)i(the)g (same)f(as)h(on)f(big-endian)e(systems.)0 2388 y FE(19.3)121 b Fx(aifc)32 b FE(\227)h(Read)i(and)g(wr)r(ite)e(AIFF)g(and)i(AIFC)f (\002les)0 2620 y FN(This)18 b(module)e(pro)o(vides)g(support)h(for)g (reading)f(and)i(writing)f(AIFF)h(and)f(AIFF-C)i(\002les.)25 b(AIFF)18 b(is)h(Audio)e(Interchange)e(File)k(F)o(ormat,)0 2720 y(a)h(format)f(for)g(storing)g(digital)g(audio)g(samples)h(in)g(a) g(\002le.)25 b(AIFF-C)20 b(is)h(a)f(ne)n(wer)f(v)o(ersion)g(of)g(the)h (format)e(that)i(includes)f(the)h(ability)f(to)0 2820 y(compress)g(the)i(audio)e(data.)0 2966 y FL(Ca)n(v)o(eat:)k FN(Some)c(operations)e(may)i(only)f(w)o(ork)h(under)f(IRIX;)h(these)h (will)f(raise)h FJ(ImportError)e FN(when)g(attempting)g(to)h(import)g (the)0 3066 y FJ(cl)h FN(module,)f(which)h(is)h(only)e(a)n(v)n(ailable) h(on)g(IRIX.)0 3213 y(Audio)e(\002les)h(ha)n(v)o(e)f(a)h(number)d(of)j (parameters)e(that)h(describe)g(the)g(audio)g(data.)24 b(The)18 b(sampling)g(rate)g(or)g(frame)g(rate)g(is)i(the)e(number)f (of)0 3313 y(times)j(per)g(second)f(the)g(sound)g(is)i(sampled.)j(The)c (number)e(of)h(channels)g(indicate)g(if)h(the)g(audio)f(is)i(mono,)d (stereo,)i(or)f(quadro.)k(Each)0 3412 y(frame)e(consists)h(of)f(one)g (sample)g(per)g(channel.)28 b(The)21 b(sample)g(size)h(is)h(the)e(size) h(in)g(bytes)f(of)h(each)f(sample.)28 b(Thus)21 b(a)h(frame)f(consists) 0 3512 y(of)f FK(nc)o(hannels)p FN(*)p FK(samplesize)d FN(bytes,)j(and)g(a)g(second')-5 b(s)20 b(w)o(orth)g(of)g(audio)f (consists)h(of)g FK(nc)o(hannels)p FN(*)p FK(samplesize)p FN(*)p FK(fr)o(amer)o(ate)c FN(bytes.)0 3659 y(F)o(or)h(e)o(xample,)g (CD)h(quality)f(audio)f(has)i(a)g(sample)f(size)i(of)e(tw)o(o)h(bytes)f (\(16)g(bits\),)h(uses)g(tw)o(o)g(channels)e(\(stereo\))h(and)g(has)h (a)g(frame)f(rate)0 3758 y(of)24 b(44,100)e(frames/second.)36 b(This)24 b(gi)n(v)o(es)g(a)h(frame)e(size)i(of)f(4)g(bytes)g(\(2*2\),) g(and)g(a)g(second')-5 b(s)24 b(w)o(orth)g(occupies)f(2*2*44100)e (bytes)0 3858 y(\(176,400)c(bytes\).)0 4005 y(Module)i FJ(aifc)h FN(de\002nes)g(the)g(follo)n(wing)f(function:)0 4152 y FD(open)p FJ(\()p FK(\002le)p FC([)p FK(,)g(mode)12 b FC(])p FJ(\))208 4251 y FN(Open)j(an)i(AIFF)g(or)f(AIFF-C)h(\002le)g (and)f(return)f(an)i(object)f(instance)g(with)g(methods)g(that)g(are)h (described)e(belo)n(w)-5 b(.)23 b(The)16 b(ar)o(gument)208 4351 y FK(\002le)j FN(is)i(either)e(a)h(string)g(naming)e(a)i(\002le)g (or)g(a)g(\002le)g(object.)25 b FK(mode)19 b FN(must)g(be)h FJ('r')g FN(or)f FJ('rb')h FN(when)f(the)g(\002le)i(must)f(be)f(opened) f(for)208 4451 y(reading,)23 b(or)i FJ('w')f FN(or)h FJ('wb')f FN(when)g(the)g(\002le)i(must)e(be)h(opened)e(for)g(writing.) 38 b(If)24 b(omitted,)h FK(\002le)p FJ(.mode)f FN(is)h(used)f(if)h(it)g (e)o(xists,)208 4550 y(otherwise)d FJ('rb')h FN(is)h(used.)34 b(When)23 b(used)g(for)f(writing,)i(the)f(\002le)h(object)e(should)g (be)i(seekable,)f(unless)g(you)f(kno)n(w)g(ahead)h(of)208 4650 y(time)d(ho)n(w)g(man)o(y)f(samples)h(you)f(are)h(going)f(to)h (write)h(in)f(total)h(and)e(use)i FJ(writeframesraw\(\))c FN(and)j FJ(setnframes\(\))p FN(.)0 4797 y(Objects)g(returned)f(by)h FJ(open\(\))f FN(when)h(a)g(\002le)h(is)g(opened)e(for)g(reading)g(ha)n (v)o(e)h(the)g(follo)n(wing)f(methods:)0 4944 y FD(getnchannels)p FJ(\(\))208 5043 y FN(Return)g(the)i(number)d(of)i(audio)f(channels)g (\(1)h(for)g(mono,)e(2)j(for)e(stereo\).)0 5190 y FD(getsampwidth)p FJ(\(\))208 5290 y FN(Return)g(the)i(size)f(in)h(bytes)f(of)g(indi)n (vidual)e(samples.)p 0 5549 3901 4 v 0 5649 a FI(19.3.)52 b FJ(aifc)23 b FI(\227)g(Read)g(and)h(wr)q(ite)f(AIFF)g(and)h(AIFC)f (\002les)1890 b(697)p eop end %%Page: 698 710 TeXDict begin 698 709 bop 0 83 a FD(getframerate)p FJ(\(\))208 183 y FN(Return)19 b(the)i(sampling)e(rate)h(\(number)e(of)i(audio)f (frames)h(per)f(second\).)0 330 y FD(getnframes)p FJ(\(\))208 429 y FN(Return)g(the)i(number)d(of)i(audio)f(frames)h(in)g(the)g (\002le.)0 576 y FD(getcomptype)p FJ(\(\))208 676 y FN(Return)27 b(a)i(four)n(-character)c(string)i(describing)g(the)h(type)f(of)h (compression)e(used)i(in)g(the)g(audio)g(\002le.)49 b(F)o(or)27 b(AIFF)i(\002les,)i(the)208 775 y(returned)18 b(v)n(alue)h(is)j FJ('NONE')p FN(.)0 922 y FD(getcompname)p FJ(\(\))208 1022 y FN(Return)29 b(a)h(human-readable)c(description)i(of)h(the)h (type)f(of)g(compression)f(used)i(in)f(the)h(audio)f(\002le.)54 b(F)o(or)29 b(AIFF)h(\002les,)j(the)208 1121 y(returned)18 b(v)n(alue)h(is)j FJ('not)49 b(compressed')p FN(.)0 1268 y FD(getparams)p FJ(\(\))208 1368 y FN(Return)19 b(a)i(tuple)f (consisting)f(of)h(all)h(of)f(the)g(abo)o(v)o(e)f(v)n(alues)g(in)i(the) f(abo)o(v)o(e)e(order)-5 b(.)0 1515 y FD(getmarkers)p FJ(\(\))208 1614 y FN(Return)22 b(a)i(list)h(of)e(mark)o(ers)f(in)i (the)f(audio)g(\002le.)35 b(A)24 b(mark)o(er)e(consists)i(of)f(a)h (tuple)e(of)i(three)e(elements.)35 b(The)23 b(\002rst)h(is)g(the)f (mark)208 1714 y(ID)f(\(an)g(inte)o(ger\),)f(the)h(second)g(is)h(the)g (mark)e(position)g(in)i(frames)f(from)f(the)h(be)o(ginning)e(of)i(the)h (data)f(\(an)g(inte)o(ger\),)f(the)h(third)208 1814 y(is)f(the)f(name)f (of)h(the)h(mark)e(\(a)h(string\).)0 1961 y FD(getmark)p FJ(\()p FK(id)r FJ(\))208 2060 y FN(Return)f(the)i(tuple)e(as)i (described)e(in)h FJ(getmarkers\(\))f FN(for)h(the)g(mark)f(with)h(the) h(gi)n(v)o(en)e FK(id)r FN(.)0 2207 y FD(readframes)p FJ(\()p FK(nfr)o(ames)p FJ(\))208 2307 y FN(Read)k(and)g(return)g(the)g (ne)o(xt)g FK(nfr)o(ames)g FN(frames)g(from)g(the)g(audio)g(\002le.)35 b(The)24 b(returned)d(data)j(is)g(a)g(string)f(containing)f(for)h(each) 208 2406 y(frame)c(the)h(uncompressed)e(samples)i(of)g(all)h(channels.) 0 2553 y FD(rewind)p FJ(\(\))208 2653 y FN(Re)n(wind)f(the)g(read)f (pointer)-5 b(.)24 b(The)c(ne)o(xt)g FJ(readframes\(\))e FN(will)j(start)g(from)e(the)h(be)o(ginning.)0 2800 y FD(setpos)p FJ(\()p FK(pos)p FJ(\))208 2899 y FN(Seek)g(to)g(the)g (speci\002ed)g(frame)g(number)-5 b(.)0 3046 y FD(tell)p FJ(\(\))208 3146 y FN(Return)19 b(the)i(current)d(frame)i(number)-5 b(.)0 3293 y FD(close)p FJ(\(\))208 3392 y FN(Close)20 b(the)h(AIFF)f(\002le.)26 b(After)20 b(calling)g(this)g(method,)f(the)h (object)g(can)g(no)f(longer)g(be)h(used.)0 3539 y(Objects)c(returned)d (by)i FJ(open\(\))g FN(when)f(a)i(\002le)g(is)g(opened)e(for)h(writing) g(ha)n(v)o(e)f(all)i(the)g(abo)o(v)o(e)d(methods,)i(e)o(xcept)g(for)f FJ(readframes\(\))0 3639 y FN(and)23 b FJ(setpos\(\))p FN(.)35 b(In)24 b(addition)e(the)i(follo)n(wing)e(methods)h(e)o(xist.) 36 b(The)23 b FJ(get)2283 3654 y(*)2333 3639 y(\(\))h FN(methods)e(can)i(only)f(be)h(called)g(after)f(the)h(corre-)0 3738 y(sponding)29 b FJ(set)486 3753 y(*)536 3738 y(\(\))i FN(methods)f(ha)n(v)o(e)h(been)f(called.)58 b(Before)31 b(the)g(\002rst)h FJ(writeframes\(\))e FN(or)h FJ(writeframesraw\(\))p FN(,)g(all)0 3838 y(parameters)19 b(e)o(xcept)g(for)h(the)g(number)e (of)i(frames)g(must)g(be)g(\002lled)h(in.)0 3985 y FD(aiff)p FJ(\(\))208 4084 y FN(Create)g(an)g(AIFF)g(\002le.)28 b(The)20 b(def)o(ault)h(is)g(that)g(an)g(AIFF-C)h(\002le)f(is)h (created,)e(unless)h(the)g(name)f(of)h(the)g(\002le)h(ends)e(in)h FJ('.aiff')208 4184 y FN(in)f(which)g(case)g(the)g(def)o(ault)g(is)h (an)f(AIFF)h(\002le.)0 4331 y FD(aifc)p FJ(\(\))208 4431 y FN(Create)c(an)g(AIFF-C)g(\002le.)24 b(The)17 b(def)o(ault)f(is)i (that)f(an)g(AIFF-C)g(\002le)h(is)g(created,)e(unless)h(the)g(name)f (of)h(the)g(\002le)h(ends)e(in)h FJ('.aiff')208 4530 y FN(in)j(which)g(case)g(the)g(def)o(ault)g(is)h(an)f(AIFF)h(\002le.)0 4677 y FD(setnchannels)p FJ(\()p FK(nc)o(hannels)p FJ(\))208 4777 y FN(Specify)e(the)h(number)f(of)g(channels)h(in)g(the)g(audio)f (\002le.)0 4924 y FD(setsampwidth)p FJ(\()p FK(width)p FJ(\))208 5023 y FN(Specify)g(the)h(size)h(in)f(bytes)g(of)g(audio)f (samples.)0 5170 y FD(setframerate)p FJ(\()p FK(r)o(ate)p FJ(\))208 5270 y FN(Specify)g(the)h(sampling)f(frequenc)o(y)f(in)i (frames)g(per)g(second.)p 0 5549 3901 4 v 0 5649 a FI(698)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 699 711 TeXDict begin 699 710 bop 0 83 a FD(setnframes)p FJ(\()p FK(nfr)o(ames)p FJ(\))208 183 y FN(Specify)27 b(the)h(number)f(of)h (frames)g(that)g(are)g(to)h(be)f(written)g(to)g(the)h(audio)e(\002le.) 50 b(If)28 b(this)h(parameter)e(is)i(not)f(set,)j(or)d(not)g(set)208 282 y(correctly)-5 b(,)18 b(the)i(\002le)h(needs)f(to)g(support)f (seeking.)0 429 y FD(setcomptype)p FJ(\()p FK(type)o(,)f(name)p FJ(\))208 529 y FN(Specify)d(the)h(compression)e(type.)23 b(If)16 b(not)f(speci\002ed,)i(the)f(audio)f(data)g(will)i(not)f(be)g (compressed.)22 b(In)15 b(AIFF)i(\002les,)g(compression)208 628 y(is)22 b(not)f(possible.)28 b(The)21 b(name)g(parameter)f(should)g (be)h(a)h(human-readable)c(description)i(of)h(the)g(compression)f (type,)h(the)g(type)208 728 y(parameter)f(should)h(be)h(a)g(four)n (-character)d(string.)30 b(Currently)20 b(the)i(follo)n(wing)e (compression)h(types)g(are)h(supported:)27 b(NONE,)208 828 y(ULA)-7 b(W)f(,)20 b(ALA)-7 b(W)f(,)20 b(G722.)0 975 y FD(setparams)p FJ(\()p FK(nc)o(hannels,)c(sampwidth,)j(fr)o(amer) o(ate)o(,)h(comptype)o(,)f(compname)p FJ(\))208 1074 y FN(Set)j(all)g(the)f(abo)o(v)o(e)f(parameters)g(at)i(once.)28 b(The)21 b(ar)o(gument)e(is)j(a)g(tuple)f(consisting)g(of)g(the)h(v)n (arious)e(parameters.)27 b(This)22 b(means)208 1174 y(that)e(it)h(is)g (possible)f(to)g(use)h(the)f(result)g(of)g(a)h FJ(getparams\(\))d FN(call)j(as)g(ar)o(gument)d(to)i FJ(setparams\(\))p FN(.)0 1321 y FD(setmark)p FJ(\()p FK(id,)f(pos,)g(name)p FJ(\))208 1420 y FN(Add)26 b(a)h(mark)f(with)g(the)h(gi)n(v)o(en)f(id)g (\(lar)o(ger)f(than)h(0\),)i(and)e(the)h(gi)n(v)o(en)e(name)h(at)i(the) e(gi)n(v)o(en)g(position.)43 b(This)27 b(method)e(can)i(be)208 1520 y(called)20 b(at)g(an)o(y)g(time)g(before)f FJ(close\(\))p FN(.)0 1667 y FD(tell)p FJ(\(\))208 1766 y FN(Return)g(the)i(current)d (write)j(position)e(in)h(the)h(output)e(\002le.)25 b(Useful)20 b(in)h(combination)c(with)k FJ(setmark\(\))p FN(.)0 1913 y FD(writeframes)p FJ(\()p FK(data)p FJ(\))208 2013 y FN(Write)f(data)g(to)h(the)f(output)f(\002le.)26 b(This)20 b(method)f(can)h(only)f(be)h(called)g(after)g(the)g(audio)f(\002le)i (parameters)e(ha)n(v)o(e)h(been)f(set.)0 2160 y FD(writeframesraw)p FJ(\()p FK(data)p FJ(\))208 2259 y FN(Lik)o(e)h FJ(writeframes\(\))p FN(,)e(e)o(xcept)h(that)h(the)g(header)f(of)h(the)h(audio)e(\002le)i (is)g(not)f(updated.)0 2406 y FD(close)p FJ(\(\))208 2506 y FN(Close)k(the)g(AIFF)g(\002le.)36 b(The)23 b(header)g(of)g(the) h(\002le)g(is)h(updated)d(to)i(re\003ect)g(the)f(actual)h(size)g(of)g (the)f(audio)g(data.)36 b(After)23 b(calling)208 2606 y(this)d(method,)f(the)h(object)g(can)g(no)f(longer)g(be)h(used.)0 2933 y FE(19.4)121 b Fx(sunau)32 b FE(\227)h(Read)i(and)f(wr)r(ite)g (Sun)g(A)-6 b(U)33 b(\002les)0 3166 y FN(The)22 b FJ(sunau)g FN(module)f(pro)o(vides)g(a)i(con)m(v)o(enient)c(interf)o(ace)j(to)h (the)f(Sun)g(A)-5 b(U)24 b(sound)d(format.)30 b(Note)23 b(that)f(this)h(module)e(is)j(interf)o(ace-)0 3265 y(compatible)19 b(with)h(the)g(modules)f FJ(aifc)h FN(and)g FJ(wave)p FN(.)0 3412 y(An)g(audio)f(\002le)i(consists)g(of)f(a)h(header)e(follo) n(wed)f(by)i(the)g(data.)25 b(The)20 b(\002elds)h(of)f(the)g(header)f (are:)440 3639 y FL(Field)p 931 3668 4 100 v 363 w(Contents)p 390 3672 3120 4 v 440 3741 a FN(magic)h(w)o(ord)p 931 3771 4 100 v 148 w(The)f(four)h(bytes)g(`)p FJ(.snd)p FN('.)440 3841 y(header)f(size)p 931 3871 V 172 w(Size)h(of)g(the)g (header)m(,)f(including)f(info,)i(in)g(bytes.)440 3941 y(data)g(size)p 931 3971 V 255 w(Physical)f(size)i(of)f(the)g(data,)g (in)g(bytes.)440 4040 y(encoding)p 931 4070 V 236 w(Indicates)f(ho)n(w) h(the)g(audio)f(samples)h(are)h(encoded.)440 4140 y(sample)f(rate)p 931 4170 V 162 w(The)f(sampling)h(rate.)440 4240 y(#)h(of)e(channels)p 931 4269 V 99 w(The)g(number)g(of)h(channels)f(in)h(the)h(samples.)440 4339 y(info)p 931 4369 V 410 w FH(A)t(S)t(C)t(I)t(I)i FN(string)d(gi)n(ving)f(a)i(description)d(of)i(the)g(audio)g(\002le)h (\(padded)d(with)i(null)g(bytes\).)0 4564 y(Apart)31 b(from)g(the)g(info)g(\002eld,)k(all)d(header)e(\002elds)j(are)e(4)h (bytes)f(in)h(size.)60 b(The)o(y)31 b(are)g(all)h(32-bit)f(unsigned)f (inte)o(gers)h(encoded)e(in)0 4664 y(big-endian)18 b(byte)i(order)-5 b(.)0 4811 y(The)20 b FJ(sunau)g FN(module)e(de\002nes)i(the)h(follo)n (wing)d(functions:)0 4958 y FD(open)p FJ(\()p FK(\002le)o(,)h(mode)p FJ(\))208 5057 y FN(If)h FK(\002le)g FN(is)h(a)g(string,)e(open)g(the)i (\002le)f(by)g(that)g(name,)g(otherwise)f(treat)i(it)g(as)f(a)h (seekable)f(\002le-lik)o(e)g(object.)k FK(mode)c FN(can)g(be)g(an)o(y)f (of)208 5223 y FD('r')o FN(Read)h(only)g(mode.)208 5356 y FD('w')o FN(Write)h(only)e(mode.)p 0 5549 3901 4 v 0 5649 a FI(19.4.)52 b FJ(sunau)22 b FI(\227)i(Read)f(and)h(wr)q(ite)f (Sun)h(A)l(U)f(\002les)2112 b(699)p eop end %%Page: 700 712 TeXDict begin 700 711 bop 208 83 a FN(Note)20 b(that)g(it)h(does)f(not) g(allo)n(w)g(read/write)f(\002les.)208 216 y(A)h FK(mode)g FN(of)g FJ('r')g FN(returns)f(a)i FJ(AU_read)e FN(object,)h(while)g(a)h FK(mode)e FN(of)h FJ('w')g FN(or)g FJ('wb')g FN(returns)f(a)i FJ(AU_write)e FN(object.)0 363 y FD(openfp)p FJ(\()p FK(\002le)o(,)g(mode)p FJ(\))208 462 y FN(A)h(synon)o(ym)e(for)i FJ(open)p FN(,)g(maintained)e(for)i(backw)o(ards)f(compatibility)-5 b(.)0 609 y(The)20 b FJ(sunau)g FN(module)e(de\002nes)i(the)h(follo)n (wing)d(e)o(xception:)0 756 y FL(exception)h FD(Error)208 856 y FN(An)h(error)f(raised)h(when)f(something)g(is)i(impossible)f (because)f(of)h(Sun)g(A)-5 b(U)21 b(specs)g(or)f(implementation)e (de\002cienc)o(y)-5 b(.)0 1003 y(The)20 b FJ(sunau)g FN(module)e(de\002nes)i(the)h(follo)n(wing)d(data)i(items:)0 1149 y FD(AUDIO_FILE_MAGIC)208 1249 y FN(An)f(inte)o(ger)g(e)n(v)o(ery) f(v)n(alid)h(Sun)h(A)-5 b(U)20 b(\002le)h(be)o(gins)d(with,)i(stored)f (in)h(big-endian)d(form.)24 b(This)c(is)h(the)e(string)h(`)p FJ(.snd)p FN(')e(interpreted)208 1349 y(as)i(an)h(inte)o(ger)-5 b(.)0 1496 y FD(AUDIO_FILE_ENCODING_MULAW_8)0 1595 y (AUDIO_FILE_ENCODING_LINEAR_8)0 1695 y(AUDIO_FILE_ENCODING_LINEAR_16)0 1794 y(AUDIO_FILE_ENCODING_LINEAR_24)0 1894 y (AUDIO_FILE_ENCODING_LINEAR_32)0 1994 y(AUDIO_FILE_ENCODING_ALAW_8)208 2093 y FN(V)c(alues)20 b(of)g(the)g(encoding)e(\002eld)i(from)f(the)i (A)-5 b(U)21 b(header)e(which)g(are)h(supported)f(by)g(this)i(module.)0 2240 y FD(AUDIO_FILE_ENCODING_FLOAT)0 2340 y (AUDIO_FILE_ENCODING_DOUBLE)0 2439 y(AUDIO_FILE_ENCODING_ADPCM_G721)0 2539 y(AUDIO_FILE_ENCODING_ADPCM_G722)0 2639 y (AUDIO_FILE_ENCODING_ADPCM_G723_3)0 2738 y (AUDIO_FILE_ENCODING_ADPCM_G723_5)208 2838 y FN(Additional)c(kno)n(wn)g (v)n(alues)i(of)f(the)h(encoding)e(\002eld)i(from)f(the)g(A)-5 b(U)20 b(header)m(,)d(b)n(ut)i(which)f(are)h(not)g(supported)d(by)j (this)g(module.)0 3123 y Fv(19.4.1)101 b(A)-5 b(U)p 516 3123 30 4 v 36 w(read)29 b(Objects)0 3326 y FN(A)-5 b(U)p 120 3326 25 4 v 30 w(read)20 b(objects,)g(as)g(returned)f(by)h FJ(open\(\))f FN(abo)o(v)o(e,)g(ha)n(v)o(e)g(the)h(follo)n(wing)f (methods:)0 3473 y FD(close)p FJ(\(\))208 3572 y FN(Close)h(the)h (stream,)e(and)h(mak)o(e)g(the)g(instance)g(unusable.)k(\(This)c(is)h (called)f(automatically)e(on)i(deletion.\))0 3719 y FD(getnchannels)p FJ(\(\))208 3819 y FN(Returns)g(number)e(of)i(audio)f(channels)g(\(1)h (for)g(mone,)f(2)h(for)g(stereo\).)0 3966 y FD(getsampwidth)p FJ(\(\))208 4065 y FN(Returns)g(sample)g(width)f(in)i(bytes.)0 4212 y FD(getframerate)p FJ(\(\))208 4312 y FN(Returns)f(sampling)f (frequenc)o(y)-5 b(.)0 4459 y FD(getnframes)p FJ(\(\))208 4558 y FN(Returns)20 b(number)e(of)i(audio)f(frames.)0 4705 y FD(getcomptype)p FJ(\(\))208 4805 y FN(Returns)h(compression)e (type.)24 b(Supported)19 b(compression)f(types)i(are)g FJ('ULAW')p FN(,)f FJ('ALAW')h FN(and)g FJ('NONE')p FN(.)0 4952 y FD(getcompname)p FJ(\(\))208 5051 y FN(Human-readable)31 b(v)o(ersion)j(of)h FJ(getcomptype\(\))p FN(.)68 b(The)35 b(supported)e(types)i(ha)n(v)o(e)f(the)h(respecti)n(v)o(e)f(names)h FJ('CCITT)208 5151 y(G.711)48 b(u-law')p FN(,)20 b FJ('CCITT)49 b(G.711)f(A-law')20 b FN(and)g FJ('not)49 b(compressed')p FN(.)0 5298 y FD(getparams)p FJ(\(\))208 5397 y FN(Returns)17 b(a)h(tuple)f FJ(\()p FK(nc)o(hannels)p FJ(,)47 b FK(sampwidth)p FJ(,)h FK(fr)o(amer)o(ate)p FJ(,)h FK(nfr)o(ames)p FJ(,)f FK(comptype)p FJ(,)g FK(compname)p FJ(\))p FN(,)16 b(equi)n(v)n(alent)g (to)h(out-)p 0 5549 3901 4 v 0 5649 a FI(700)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 701 713 TeXDict begin 701 712 bop 208 83 a FN(put)19 b(of)h(the)h FJ(get)697 98 y(*)747 83 y(\(\))e FN(methods.)0 230 y FD(readframes)p FJ(\()p FK(n)p FJ(\))208 330 y FN(Reads)j(and)f (returns)g(at)i(most)f FK(n)g FN(frames)f(of)h(audio,)f(as)i(a)f (string)g(of)g(bytes.)30 b(The)21 b(data)h(will)h(be)f(returned)e(in)i (linear)g(format.)29 b(If)208 429 y(the)20 b(original)f(data)h(is)h(in) f(u-LA)-7 b(W)20 b(format,)f(it)i(will)g(be)f(con)m(v)o(erted.)0 576 y FD(rewind)p FJ(\(\))208 676 y FN(Re)n(wind)g(the)g(\002le)h (pointer)e(to)h(the)g(be)o(ginning)e(of)i(the)g(audio)f(stream.)0 823 y(The)j(follo)n(wing)e(tw)o(o)j(methods)e(de\002ne)g(a)i(term)f (\223position\224)f(which)g(is)i(compatible)e(between)g(them,)h(and)g (is)h(otherwise)e(implemen-)0 922 y(tation)f(dependent.)0 1069 y FD(setpos)p FJ(\()p FK(pos)p FJ(\))208 1169 y FN(Set)g(the)h(\002le)f(pointer)f(to)i(the)f(speci\002ed)g(position.)k (Only)c(v)n(alues)g(returned)e(from)h FJ(tell\(\))h FN(should)f(be)h (used)g(for)f FK(pos)p FN(.)0 1316 y FD(tell)p FJ(\(\))208 1415 y FN(Return)f(current)f(\002le)i(pointer)e(position.)23 b(Note)c(that)f(the)h(returned)d(v)n(alue)i(has)h(nothing)d(to)j(do)f (with)h(the)f(actual)g(position)g(in)h(the)208 1515 y(\002le.)0 1662 y(The)h(follo)n(wing)e(tw)o(o)j(functions)e(are)h(de\002ned)f(for) g(compatibility)g(with)h(the)h FJ(aifc)p FN(,)e(and)h(don')o(t)f(do)g (an)o(ything)f(interesting.)0 1808 y FD(getmarkers)p FJ(\(\))208 1908 y FN(Returns)i FJ(None)p FN(.)0 2055 y FD(getmark)p FJ(\()p FK(id)r FJ(\))208 2155 y FN(Raise)h(an)f(error) -5 b(.)0 2440 y Fv(19.4.2)101 b(A)-5 b(U)p 516 2440 30 4 v 36 w(wr)q(ite)28 b(Objects)0 2642 y FN(A)-5 b(U)p 120 2642 25 4 v 30 w(write)21 b(objects,)e(as)i(returned)e(by)g FJ(open\(\))h FN(abo)o(v)o(e,)e(ha)n(v)o(e)i(the)g(follo)n(wing)f (methods:)0 2789 y FD(setnchannels)p FJ(\()p FK(n)p FJ(\))208 2889 y FN(Set)h(the)h(number)d(of)i(channels.)0 3036 y FD(setsampwidth)p FJ(\()p FK(n)p FJ(\))208 3135 y FN(Set)g(the)h (sample)f(width)f(\(in)h(bytes.\))0 3282 y FD(setframerate)p FJ(\()p FK(n)p FJ(\))208 3382 y FN(Set)g(the)h(frame)e(rate.)0 3529 y FD(setnframes)p FJ(\()p FK(n)p FJ(\))208 3628 y FN(Set)h(the)h(number)d(of)i(frames.)k(This)d(can)f(be)g(later)g (changed,)e(when)i(and)f(if)i(more)e(frames)h(are)g(written.)0 3775 y FD(setcomptype)p FJ(\()p FK(type)o(,)e(name)p FJ(\))208 3875 y FN(Set)i(the)h(compression)d(type)i(and)f (description.)24 b(Only)c FJ('NONE')f FN(and)h FJ('ULAW')g FN(are)g(supported)e(on)i(output.)0 4022 y FD(setparams)p FJ(\()p FK(tuple)p FJ(\))208 4121 y FN(The)25 b FK(tuple)g FN(should)f(be)h FJ(\()p FK(nc)o(hannels)p FJ(,)47 b FK(sampwidth)p FJ(,)i FK(fr)o(amer)o(ate)p FJ(,)f FK(nfr)o(ames)p FJ(,)h FK(comptype)p FJ(,)f FK(compname)p FJ(\))p FN(,)24 b(with)i(v)n(alues)208 4221 y(v)n(alid)19 b(for)h(the)g FJ(set)782 4236 y(*)832 4221 y(\(\))g FN(methods.)k(Set)c(all)h (parameters.)0 4368 y FD(tell)p FJ(\(\))208 4468 y FN(Return)47 b(current)g(position)h(in)g(the)g(\002le,)56 b(with)49 b(the)f(same)g(disclaimer)g(for)g(the)g FJ(AU_read.tell\(\))e FN(and)i FJ(AU_-)208 4567 y(read.setpos\(\))18 b FN(methods.)0 4714 y FD(writeframesraw)p FJ(\()p FK(data)p FJ(\))208 4814 y FN(Write)i(audio)g(frames,)f(without)g(correcting)g FK(nfr)o(ames)p FN(.)0 4961 y FD(writeframes)p FJ(\()p FK(data)p FJ(\))208 5060 y FN(Write)h(audio)g(frames)f(and)h(mak)o(e)g (sure)g FK(nfr)o(ames)g FN(is)h(correct.)0 5207 y FD(close)p FJ(\(\))208 5307 y FN(Mak)o(e)f(sure)g FK(nfr)o(ames)g FN(is)h(correct,)e(and)g(close)i(the)f(\002le.)p 0 5549 3901 4 v 0 5649 a FI(19.4.)52 b FJ(sunau)22 b FI(\227)i(Read)f(and)h (wr)q(ite)f(Sun)h(A)l(U)f(\002les)2112 b(701)p eop end %%Page: 702 714 TeXDict begin 702 713 bop 208 83 a FN(This)20 b(method)f(is)i(called)f (upon)f(deletion.)0 230 y(Note)h(that)g(it)h(is)g(in)m(v)n(alid)e(to)i (set)g(an)o(y)e(parameters)g(after)h(calling)g FJ(writeframes\(\))e FN(or)i FJ(writeframesraw\(\))p FN(.)0 557 y FE(19.5)121 b Fx(wave)32 b FE(\227)h(Read)i(and)g(wr)r(ite)e(W)-6 b(A)e(V)32 b(\002les)0 790 y FN(The)40 b FJ(wave)g FN(module)f(pro)o (vides)g(a)i(con)m(v)o(enient)d(interf)o(ace)h(to)i(the)f(W)-10 b(A)f(V)41 b(sound)f(format.)84 b(It)41 b(does)f(not)g(support)f (compres-)0 890 y(sion/decompression,)17 b(b)n(ut)j(it)h(does)f (support)f(mono/stereo.)0 1037 y(The)h FJ(wave)g FN(module)f(de\002nes) h(the)g(follo)n(wing)e(function)h(and)g(e)o(xception:)0 1184 y FD(open)p FJ(\()p FK(\002le)p FC([)p FK(,)g(mode)12 b FC(])p FJ(\))208 1283 y FN(If)20 b FK(\002le)g FN(is)h(a)g(string,)e (open)g(the)i(\002le)f(by)g(that)g(name,)g(other)f(treat)h(it)h(as)g(a) g(seekable)e(\002le-lik)o(e)i(object.)j FK(mode)c FN(can)g(be)g(an)o(y) f(of)208 1449 y FD('r')p FL(,)h FD('rb')o FN(Read)g(only)f(mode.)208 1582 y FD('w')p FL(,)h FD('wb')o FN(Write)h(only)e(mode.)208 1748 y(Note)h(that)g(it)h(does)f(not)g(allo)n(w)g(read/write)f(W)-10 b(A)f(V)21 b(\002les.)208 1881 y(A)e FK(mode)g FN(of)f FJ('r')h FN(or)g FJ('rb')g FN(returns)f(a)i FJ(Wave_read)d FN(object,)i(while)g(a)g FK(mode)g FN(of)g FJ('w')g FN(or)f FJ('wb')h FN(returns)f(a)i FJ(Wave_write)208 1981 y FN(object.)k(If)19 b FK(mode)g FN(is)h(omitted)f(and)g(a)h(\002le-lik)o(e)f(object)g(is)i (passed)e(as)h FK(\002le)p FN(,)g FK(\002le)p FJ(.mode)e FN(is)j(used)e(as)h(the)g(def)o(ault)f(v)n(alue)f(for)h FK(mode)208 2080 y FN(\(the)g(`)p FJ(b)p FN(')h(\003ag)h(is)g(still)g (added)e(if)i(necessary\).)0 2227 y FD(openfp)p FJ(\()p FK(\002le)o(,)e(mode)p FJ(\))208 2327 y FN(A)h(synon)o(ym)e(for)i FJ(open\(\))p FN(,)f(maintained)g(for)g(backw)o(ards)g(compatibility)-5 b(.)0 2474 y FL(exception)19 b FD(Error)208 2573 y FN(An)h(error)g (raised)g(when)g(something)f(is)i(impossible)f(because)g(it)i(violates) e(the)g(W)-10 b(A)f(V)22 b(speci\002cation)d(or)i(hits)g(an)f (implementa-)208 2673 y(tion)f(de\002cienc)o(y)-5 b(.)0 2958 y Fv(19.5.1)101 b(W)l(a)n(v)n(e)p 629 2958 30 4 v 36 w(read)29 b(Objects)0 3161 y FN(W)-7 b(a)n(v)o(e)p 189 3161 25 4 v 30 w(read)20 b(objects,)f(as)i(returned)e(by)g FJ(open\(\))p FN(,)h(ha)n(v)o(e)f(the)i(follo)n(wing)d(methods:)0 3307 y FD(close)p FJ(\(\))208 3407 y FN(Close)i(the)h(stream,)e(and)h (mak)o(e)g(the)g(instance)g(unusable.)k(This)c(is)h(called)f (automatically)f(on)h(object)f(collection.)0 3554 y FD(getnchannels)p FJ(\(\))208 3654 y FN(Returns)h(number)e(of)i(audio)f(channels)g(\()p FJ(1)i FN(for)e(mono,)g FJ(2)h FN(for)g(stereo\).)0 3800 y FD(getsampwidth)p FJ(\(\))208 3900 y FN(Returns)g(sample)g(width)f (in)i(bytes.)0 4047 y FD(getframerate)p FJ(\(\))208 4147 y FN(Returns)f(sampling)f(frequenc)o(y)-5 b(.)0 4293 y FD(getnframes)p FJ(\(\))208 4393 y FN(Returns)20 b(number)e(of)i (audio)f(frames.)0 4540 y FD(getcomptype)p FJ(\(\))208 4640 y FN(Returns)h(compression)e(type)i(\()p FJ('NONE')f FN(is)i(the)f(only)g(supported)e(type\).)0 4786 y FD(getcompname)p FJ(\(\))208 4886 y FN(Human-readable)f(v)o(ersion)h(of)i FJ(getcomptype\(\))p FN(.)j(Usually)d FJ('not)50 b(compressed')18 b FN(parallels)i FJ('NONE')p FN(.)0 5033 y FD(getparams)p FJ(\(\))208 5133 y FN(Returns)d(a)h(tuple)f FJ(\()p FK(nc)o(hannels)p FJ(,)47 b FK(sampwidth)p FJ(,)h FK(fr)o(amer)o(ate)p FJ(,)h FK(nfr)o(ames)p FJ(,)f FK(comptype)p FJ(,)g FK(compname)p FJ(\))p FN(,)16 b(equi)n(v)n(alent)g(to)h(out-)208 5232 y(put)i(of)h(the)h FJ(get)697 5247 y(*)747 5232 y(\(\))e FN(methods.)p 0 5549 3901 4 v 0 5649 a FI(702)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 703 715 TeXDict begin 703 714 bop 0 83 a FD(readframes)p FJ(\()p FK(n)p FJ(\))208 183 y FN(Reads)20 b(and)g(returns)f(at)i(most)f FK(n)g FN(frames)g(of)g(audio,)f(as)i(a)f(string)g(of)g(bytes.)0 330 y FD(rewind)p FJ(\(\))208 429 y FN(Re)n(wind)g(the)g(\002le)h (pointer)e(to)h(the)g(be)o(ginning)e(of)i(the)g(audio)f(stream.)0 576 y(The)h(follo)n(wing)e(tw)o(o)j(methods)e(are)h(de\002ned)f(for)h (compatibility)e(with)j(the)f FJ(aifc)g FN(module,)f(and)g(don')o(t)g (do)h(an)o(ything)e(interesting.)0 723 y FD(getmarkers)p FJ(\(\))208 823 y FN(Returns)i FJ(None)p FN(.)0 969 y FD(getmark)p FJ(\()p FK(id)r FJ(\))208 1069 y FN(Raise)h(an)f(error)-5 b(.)0 1216 y(The)22 b(follo)n(wing)e(tw)o(o)j(methods)e(de\002ne)g(a)i (term)f(\223position\224)f(which)g(is)i(compatible)e(between)g(them,)h (and)g(is)h(otherwise)e(implemen-)0 1316 y(tation)f(dependent.)0 1462 y FD(setpos)p FJ(\()p FK(pos)p FJ(\))208 1562 y FN(Set)g(the)h(\002le)f(pointer)f(to)i(the)f(speci\002ed)g(position.)0 1709 y FD(tell)p FJ(\(\))208 1808 y FN(Return)f(current)g(\002le)i (pointer)e(position.)0 2093 y Fv(19.5.2)101 b(W)l(a)n(v)n(e)p 629 2093 30 4 v 36 w(wr)q(ite)28 b(Objects)0 2296 y FN(W)-7 b(a)n(v)o(e)p 189 2296 25 4 v 30 w(write)20 b(objects,)g(as)h(returned) d(by)i FJ(open\(\))p FN(,)f(ha)n(v)o(e)h(the)g(follo)n(wing)f(methods:) 0 2443 y FD(close)p FJ(\(\))208 2543 y FN(Mak)o(e)h(sure)g FK(nfr)o(ames)g FN(is)h(correct,)e(and)g(close)i(the)f(\002le.)26 b(This)20 b(method)f(is)i(called)f(upon)f(deletion.)0 2690 y FD(setnchannels)p FJ(\()p FK(n)p FJ(\))208 2789 y FN(Set)h(the)h(number)d(of)i(channels.)0 2936 y FD(setsampwidth)p FJ(\()p FK(n)p FJ(\))208 3036 y FN(Set)g(the)h(sample)f(width)f(to)i FK(n)f FN(bytes.)0 3183 y FD(setframerate)p FJ(\()p FK(n)p FJ(\))208 3282 y FN(Set)g(the)h(frame)e(rate)h(to)h FK(n)p FN(.)0 3429 y FD(setnframes)p FJ(\()p FK(n)p FJ(\))208 3529 y FN(Set)f(the)h(number)d(of)i(frames)g(to)g FK(n)p FN(.)25 b(This)20 b(will)h(be)f(changed)f(later)h(if)g(more)g(frames)g (are)g(written.)0 3676 y FD(setcomptype)p FJ(\()p FK(type)o(,)e(name)p FJ(\))208 3775 y FN(Set)g(the)g(compression)d(type)j(and)f (description.)22 b(At)d(the)e(moment,)g(only)g(compression)f(type)h(`)p FJ(NONE)p FN(')g(is)h(supported,)e(meaning)208 3875 y(no)j (compression.)0 4022 y FD(setparams)p FJ(\()p FK(tuple)p FJ(\))208 4121 y FN(The)25 b FK(tuple)g FN(should)f(be)h FJ(\()p FK(nc)o(hannels)p FJ(,)47 b FK(sampwidth)p FJ(,)i FK(fr)o(amer)o(ate)p FJ(,)f FK(nfr)o(ames)p FJ(,)h FK(comptype)p FJ(,)f FK(compname)p FJ(\))p FN(,)24 b(with)i(v)n(alues)208 4221 y(v)n(alid)19 b(for)h(the)g FJ(set)782 4236 y(*)832 4221 y(\(\))g FN(methods.)k(Sets)d(all)f(parameters.)0 4368 y FD(tell)p FJ(\(\))208 4468 y FN(Return)33 b(current)g(position)h (in)g(the)g(\002le,)39 b(with)34 b(the)g(same)h(disclaimer)f(for)f(the) i FJ(Wave_read.tell\(\))c FN(and)j FJ(Wave_-)208 4567 y(read.setpos\(\))18 b FN(methods.)0 4714 y FD(writeframesraw)p FJ(\()p FK(data)p FJ(\))208 4814 y FN(Write)i(audio)g(frames,)f (without)g(correcting)g FK(nfr)o(ames)p FN(.)0 4961 y FD(writeframes)p FJ(\()p FK(data)p FJ(\))208 5060 y FN(Write)h(audio)g (frames)f(and)h(mak)o(e)g(sure)g FK(nfr)o(ames)g FN(is)h(correct.)0 5207 y(Note)32 b(that)h(it)g(is)g(in)m(v)n(alid)e(to)i(set)g(an)o(y)e (parameters)g(after)h(calling)g FJ(writeframes\(\))f FN(or)h FJ(writeframesraw\(\))p FN(,)h(and)e(an)o(y)0 5307 y(attempt)20 b(to)g(do)g(so)h(will)f(raise)h FJ(wave.Error)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(19.5.)52 b FJ(wave)23 b FI(\227)g(Read)g(and)h(wr)q(ite)f(W)l(A)-6 b(V)25 b(\002les)2264 b(703)p eop end %%Page: 704 716 TeXDict begin 704 715 bop 0 86 a FE(19.6)121 b Fx(chunk)32 b FE(\227)h(Read)i(IFF)e(chunk)n(ed)i(data)0 319 y FN(This)26 b(module)f(pro)o(vides)f(an)i(interf)o(ace)f(for)g(reading)g(\002les)i (that)f(use)g(EA)g(IFF)h(85)e(chunks.)2685 289 y FF(1)2760 319 y FN(This)h(format)f(is)i(used)e(in)h(at)h(least)g(the)0 419 y(Audio)17 b(Interchange)e(File)j(F)o(ormat)f(\(AIFF/AIFF-C\))h (and)f(the)g(Real)i(Media)e(File)i(F)o(ormat)d(\(RMFF\).)i(The)g(W)-10 b(A)f(VE)18 b(audio)e(\002le)j(format)0 518 y(is)i(closely)f(related)g (and)f(can)h(also)h(be)f(read)g(using)f(this)i(module.)0 665 y(A)g(chunk)d(has)j(the)f(follo)n(wing)f(structure:)555 882 y FL(Offset)p 820 912 4 100 v 98 w(Length)p 1173 912 V 100 w(Contents)p 505 915 2890 4 v 643 985 a FN(0)p 820 1015 4 100 v 292 w(4)p 1173 1015 V 206 w(Chunk)g(ID)643 1084 y(4)p 820 1114 V 292 w(4)p 1173 1114 V 206 w(Size)h(of)g(chunk)f (in)h(big-endian)e(byte)i(order)m(,)e(not)i(including)f(the)h(header) 643 1184 y(8)p 820 1214 V 292 w FK(n)p 1173 1214 V 206 w FN(Data)g(bytes,)g(where)g FK(n)g FN(is)h(the)f(size)h(gi)n(v)o(en)e (in)h(the)g(preceding)f(\002eld)578 1284 y(8)h(+)h FK(n)p 820 1313 V 151 w FN(0)g(or)f(1)p 1173 1313 V 129 w(P)o(ad)g(byte)f (needed)g(if)i FK(n)f FN(is)h(odd)e(and)h(chunk)f(alignment)g(is)i (used)0 1499 y(The)f(ID)g(is)h(a)g(4-byte)e(string)h(which)f (identi\002es)i(the)f(type)f(of)h(chunk.)0 1646 y(The)g(size)h(\002eld) g(\(a)f(32-bit)f(v)n(alue,)h(encoded)f(using)g(big-endian)f(byte)i (order\))f(gi)n(v)o(es)h(the)g(size)h(of)g(the)f(chunk)f(data,)h(not)g (including)f(the)0 1745 y(8-byte)g(header)-5 b(.)0 1892 y(Usually)24 b(an)g(IFF-type)g(\002le)g(consists)h(of)f(one)g(or)g (more)f(chunks.)36 b(The)23 b(proposed)g(usage)g(of)h(the)g FJ(Chunk)g FN(class)h(de\002ned)f(here)f(is)i(to)0 1992 y(instantiate)20 b(an)h(instance)f(at)h(the)g(start)g(of)f(each)g (chunk)f(and)h(read)g(from)g(the)g(instance)g(until)h(it)g(reaches)f (the)h(end,)f(after)g(which)g(a)h(ne)n(w)0 2091 y(instance)f(can)g(be)g (instantiated.)k(At)d(the)f(end)g(of)g(the)g(\002le,)h(creating)e(a)h (ne)n(w)g(instance)g(will)h(f)o(ail)g(with)f(a)h FJ(EOFError)e FN(e)o(xception.)0 2238 y FL(class)i FD(Chunk)p FJ(\()p FK(\002le)p FC([)p FK(,)d(align,)i(big)o(endian,)d(inclheader)d FC(])p FJ(\))208 2338 y FN(Class)23 b(which)e(represents)f(a)i(chunk.) 28 b(The)21 b FK(\002le)h FN(ar)o(gument)d(is)j(e)o(xpected)e(to)i(be)f (a)h(\002le-lik)o(e)g(object.)28 b(An)22 b(instance)f(of)h(this)g (class)208 2438 y(is)h(speci\002cally)f(allo)n(wed.)30 b(The)22 b(only)f(method)g(that)h(is)h(needed)e(is)i FJ(read\(\))p FN(.)30 b(If)22 b(the)h(methods)e FJ(seek\(\))g FN(and)h FJ(tell\(\))g FN(are)208 2537 y(present)i(and)h(don')o(t)f (raise)i(an)f(e)o(xception,)g(the)o(y)g(are)g(also)h(used.)41 b(If)25 b(these)h(methods)e(are)i(present)e(and)h(raise)h(an)g(e)o (xception,)208 2637 y(the)o(y)d(are)g(e)o(xpected)g(to)h(not)f(ha)n(v)o (e)g(altered)g(the)h(object.)35 b(If)24 b(the)g(optional)e(ar)o(gument) g FK(align)h FN(is)i(true,)f(chunks)e(are)i(assumed)f(to)208 2736 y(be)i(aligned)g(on)h(2-byte)f(boundaries.)40 b(If)26 b FK(align)f FN(is)i(f)o(alse,)h(no)d(alignment)g(is)i(assumed.)42 b(The)25 b(def)o(ault)g(v)n(alue)h(is)h(true.)42 b(If)26 b(the)208 2836 y(optional)21 b(ar)o(gument)g FK(big)o(endian)g FN(is)j(f)o(alse,)g(the)f(chunk)e(size)j(is)g(assumed)e(to)h(be)g(in)g (little-endian)f(order)-5 b(.)32 b(This)24 b(is)g(needed)d(for)208 2936 y(W)-10 b(A)f(VE)24 b(audio)f(\002les.)38 b(The)24 b(def)o(ault)g(v)n(alue)f(is)j(true.)36 b(If)24 b(the)h(optional)e(ar)o (gument)e FK(inclheader)k FN(is)g(true,)g(the)f(size)h(gi)n(v)o(en)e (in)i(the)208 3035 y(chunk)18 b(header)h(includes)h(the)g(size)h(of)f (the)g(header)-5 b(.)24 b(The)c(def)o(ault)f(v)n(alue)h(is)h(f)o(alse.) 0 3182 y(A)g FJ(Chunk)f FN(object)f(supports)g(the)h(follo)n(wing)f (methods:)0 3329 y FD(getname)p FJ(\(\))208 3429 y FN(Returns)h(the)g (name)f(\(ID\))h(of)g(the)g(chunk.)k(This)c(is)h(the)f(\002rst)h(4)f (bytes)g(of)g(the)h(chunk.)0 3576 y FD(getsize)p FJ(\(\))208 3675 y FN(Returns)f(the)g(size)h(of)f(the)g(chunk.)0 3822 y FD(close)p FJ(\(\))208 3922 y FN(Close)g(and)g(skip)g(to)h(the)f (end)f(of)h(the)h(chunk.)i(This)d(does)g(not)g(close)g(the)h (underlying)c(\002le.)0 4069 y(The)j(remaining)e(methods)h(will)i (raise)g FJ(IOError)e FN(if)i(called)f(after)g(the)g FJ(close\(\))f FN(method)g(has)h(been)g(called.)0 4215 y FD(isatty)p FJ(\(\))208 4315 y FN(Returns)g FJ(False)p FN(.)0 4462 y FD(seek)p FJ(\()p FK(pos)p FC([)p FK(,)f(whence)12 b FC(])p FJ(\))208 4562 y FN(Set)21 b(the)h(chunk')-5 b(s)20 b(current)f(position.)27 b(The)21 b FK(whence)g FN(ar)o(gument)e(is)j(optional)e(and)g(def)o(aults)h(to)g FJ(0)h FN(\(absolute)e(\002le)i(positioning\);)208 4661 y(other)c(v)n(alues)h(are)h FJ(1)g FN(\(seek)f(relati)n(v)o(e)g(to)g (the)h(current)e(position\))g(and)h FJ(2)h FN(\(seek)f(relati)n(v)o(e)g (to)h(the)f(\002le')-5 b(s)21 b(end\).)j(There)18 b(is)j(no)e(return) 208 4761 y(v)n(alue.)24 b(If)c(the)g(underlying)e(\002le)i(does)g(not)g (allo)n(w)g(seek,)g(only)g(forw)o(ard)e(seeks)j(are)f(allo)n(wed.)0 4908 y FD(tell)p FJ(\(\))208 5007 y FN(Return)f(the)i(current)d (position)i(into)g(the)g(chunk.)0 5154 y FD(read)p FJ(\()p FC([)p FK(size)12 b FC(])p FJ(\))208 5254 y FN(Read)23 b(at)h(most)f FK(size)h FN(bytes)f(from)f(the)i(chunk)d(\(less)j(if)g (the)f(read)f(hits)i(the)f(end)g(of)g(the)g(chunk)f(before)g(obtaining) f FK(size)j FN(bytes\).)p 0 5321 1560 4 v 90 5377 a FB(1)120 5400 y FH(\223EA)16 b(IFF)h(85\224)g(Standard)i(for)e(Interchange)j(F)o (ormat)e(Files,)f(Jerry)g(Morrison,)h(Electronic)h(Arts,)e(January)h (1985.)p 0 5549 3901 4 v 0 5649 a FI(704)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 705 717 TeXDict begin 705 716 bop 208 83 a FN(If)21 b(the)h FK(size)h FN(ar)o(gument)d(is)j(ne)o(gati)n(v)o(e)c(or)j(omitted,)f(read)h(all)g (data)g(until)g(the)g(end)f(of)h(the)g(chunk.)28 b(The)22 b(bytes)g(are)f(returned)g(as)h(a)208 183 y(string)d(object.)25 b(An)20 b(empty)f(string)h(is)h(returned)e(when)g(the)i(end)e(of)h(the) g(chunk)f(is)i(encountered)d(immediately)-5 b(.)0 330 y FD(skip)p FJ(\(\))208 429 y FN(Skip)19 b(to)h(the)f(end)g(of)g(the)h (chunk.)j(All)d(further)e(calls)j(to)e FJ(read\(\))g FN(for)g(the)h(chunk)e(will)i(return)f FJ('')p FN(.)24 b(If)c(you)f(are)g(not)g(interested)208 529 y(in)h(the)g(contents)g(of) f(the)i(chunk,)d(this)j(method)e(should)g(be)h(called)g(so)h(that)f (the)g(\002le)h(points)f(to)g(the)g(start)h(of)f(the)g(ne)o(xt)f (chunk.)0 856 y FE(19.7)121 b Fx(colorsys)31 b FE(\227)i(Con)n(v)m (ersions)h(betw)o(een)i(color)d(systems)0 1089 y FN(The)21 b FJ(colorsys)f FN(module)f(de\002nes)i(bidirectional)e(con)m(v)o (ersions)g(of)h(color)h(v)n(alues)f(between)g(colors)h(e)o(xpressed)e (in)i(the)g(RGB)i(\(Red)0 1189 y(Green)i(Blue\))g(color)g(space)g(used) g(in)h(computer)d(monitors)h(and)h(three)g(other)g(coordinate)e (systems:)36 b(YIQ,)25 b(HLS)h(\(Hue)f(Lightness)0 1288 y(Saturation\))19 b(and)i(HSV)g(\(Hue)f(Saturation)g(V)-9 b(alue\).)26 b(Coordinates)20 b(in)h(all)g(of)g(these)g(color)f(spaces) h(are)f(\003oating)h(point)f(v)n(alues.)26 b(In)21 b(the)0 1388 y(YIQ)i(space,)f(the)h(Y)g(coordinate)d(is)k(between)e(0)g(and)g (1,)h(b)n(ut)g(the)f(I)h(and)f(Q)h(coordinates)e(can)h(be)g(positi)n(v) o(e)g(or)g(ne)o(gati)n(v)o(e.)30 b(In)22 b(all)h(other)0 1488 y(spaces,)d(the)g(coordinates)f(are)h(all)h(between)e(0)h(and)g (1.)0 1634 y(More)g(information)d(about)j(color)f(spaces)h(can)g(be)h (found)d(at)j FO(http://www)l(.po)n(ynton.com/Col)o(orF)-7 b(A)n(Q.h)o(tml)h FN(.)0 1781 y(The)20 b FJ(colorsys)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f(functions:)0 1928 y FD(rgb_to_yiq)p FJ(\()p FK(r)-9 b(,)19 b(g)o(,)h(b)p FJ(\))208 2028 y FN(Con)m(v)o(ert)e(the)i(color)g(from)f(RGB)i (coordinates)e(to)h(YIQ)h(coordinates.)0 2175 y FD(yiq_to_rgb)p FJ(\()p FK(y)-5 b(,)19 b(i,)h(q)p FJ(\))208 2274 y FN(Con)m(v)o(ert)e (the)i(color)g(from)f(YIQ)h(coordinates)f(to)h(RGB)i(coordinates.)0 2421 y FD(rgb_to_hls)p FJ(\()p FK(r)-9 b(,)19 b(g)o(,)h(b)p FJ(\))208 2521 y FN(Con)m(v)o(ert)e(the)i(color)g(from)f(RGB)i (coordinates)e(to)h(HLS)h(coordinates.)0 2668 y FD(hls_to_rgb)p FJ(\()p FK(h,)d(l,)j(s)p FJ(\))208 2767 y FN(Con)m(v)o(ert)d(the)i (color)g(from)f(HLS)i(coordinates)d(to)i(RGB)i(coordinates.)0 2914 y FD(rgb_to_hsv)p FJ(\()p FK(r)-9 b(,)19 b(g)o(,)h(b)p FJ(\))208 3014 y FN(Con)m(v)o(ert)e(the)i(color)g(from)f(RGB)i (coordinates)e(to)h(HSV)h(coordinates.)0 3161 y FD(hsv_to_rgb)p FJ(\()p FK(h,)d(s,)j(v)p FJ(\))208 3260 y FN(Con)m(v)o(ert)d(the)i (color)g(from)f(HSV)i(coordinates)d(to)j(RGB)g(coordinates.)0 3407 y(Example:)236 3645 y FA(>>>)45 b(import)e(colorsys)236 3737 y(>>>)i(colorsys.rgb_to_hsv\(.3,)c(.4,)j(.2\))236 3828 y(\(0.25,)g(0.5,)g(0.4\))236 3919 y(>>>)h (colorsys.hsv_to_rgb\(0.25,)40 b(0.5,)k(0.4\))236 4011 y(\(0.3,)g(0.4,)g(0.2\))0 4521 y FE(19.8)121 b Fx(rgbimg)32 b FE(\227)h(Read)i(and)f(wr)r(ite)g(\223SGI)f(RGB\224)g(\002les)0 4753 y FL(Depr)o(ecated)19 b(since)i(r)o(elease)f(2.5.)k FN(This)c(module)f(is)i(not)f(maintained)f(an)o(ymore)f(and)h(seems)i (to)f(be)h(unused.)0 4900 y(The)29 b FJ(rgbimg)g FN(module)g(allo)n(ws) g(Python)g(programs)f(to)h(access)h(SGI)g(imglib)f(image)g(\002les)i (\(also)f(kno)n(wn)e(as)i(`)p FO(.rgb)p FN(')e(\002les\).)54 b(The)0 5000 y(module)30 b(is)j(f)o(ar)f(from)f(complete,)i(b)n(ut)f (is)h(pro)o(vided)c(an)o(yw)o(ay)h(since)i(the)g(functionality)e(that)i (there)f(is)i(enough)c(in)j(some)g(cases.)0 5100 y(Currently)-5 b(,)18 b(colormap)h(\002les)i(are)f(not)g(supported.)0 5246 y FL(Note:)k FN(This)d(module)e(is)i(only)e(b)n(uilt)h(by)g(def)o (ault)g(for)f(32-bit)g(platforms;)g(it)i(is)g(not)f(e)o(xpected)f(to)h (w)o(ork)g(properly)e(on)h(other)h(systems.)0 5393 y(The)g(module)f (de\002nes)h(the)g(follo)n(wing)e(v)n(ariables)i(and)f(functions:)p 0 5549 3901 4 v 0 5649 a FI(19.7.)52 b FJ(colorsys)22 b FI(\227)h(Con)n(v)n(ersions)g(betw)o(een)h(color)f(systems)1672 b(705)p eop end %%Page: 706 718 TeXDict begin 706 717 bop 0 83 a FL(exception)19 b FD(error)208 183 y FN(This)h(e)o(xception)e(is)j(raised)f(on)g(all)h(errors,)e(such) h(as)h(unsupported)c(\002le)k(type,)e(etc.)0 330 y FD(sizeofimage)p FJ(\()p FK(\002le)p FJ(\))208 429 y FN(This)27 b(function)e(returns)h (a)i(tuple)e FJ(\()p FK(x)p FJ(,)50 b FK(y)p FJ(\))27 b FN(where)g FK(x)g FN(and)g FK(y)g FN(are)g(the)g(size)h(of)f(the)g (image)g(in)g(pix)o(els.)45 b(Only)27 b(4)g(byte)f(RGB)m(A)208 529 y(pix)o(els,)19 b(3)h(byte)g(RGB)i(pix)o(els,)d(and)h(1)g(byte)g (gre)o(yscale)f(pix)o(els)h(are)g(currently)e(supported.)0 676 y FD(longimagedata)p FJ(\()p FK(\002le)p FJ(\))208 775 y FN(This)26 b(function)f(reads)h(and)f(decodes)h(the)g(image)g(on) g(the)g(speci\002ed)g(\002le,)i(and)e(returns)f(it)i(as)g(a)g(Python)e (string.)43 b(The)26 b(string)208 875 y(has)k(4)g(byte)g(RGB)m(A)h(pix) o(els.)55 b(The)30 b(bottom)f(left)h(pix)o(el)g(is)h(the)f(\002rst)h (in)f(the)g(string.)55 b(This)30 b(format)f(is)i(suitable)f(to)h(pass)f (to)208 975 y FJ(gl.lrectwrite\(\))p FN(,)17 b(for)j(instance.)0 1121 y FD(longstoimage)p FJ(\()p FK(data,)d(x,)j(y)-5 b(,)21 b(z,)g(\002le)p FJ(\))208 1221 y FN(This)j(function)f(writes)i (the)f(RGB)m(A)i(data)e(in)g FK(data)g FN(to)g(image)g(\002le)h FK(\002le)p FN(.)38 b FK(x)25 b FN(and)f FK(y)g FN(gi)n(v)o(e)g(the)g (size)h(of)g(the)f(image.)37 b FK(z)25 b FN(is)g(1)g(if)g(the)208 1321 y(sa)n(v)o(ed)16 b(image)h(should)f(be)h(1)g(byte)f(gre)o(yscale,) g(3)i(if)f(the)g(sa)n(v)o(ed)g(image)f(should)g(be)h(3)g(byte)f(RGB)j (data,)e(or)g(4)g(if)g(the)g(sa)n(v)o(ed)g(images)208 1420 y(should)j(be)i(4)g(byte)f(RGB)m(A)i(data.)29 b(The)21 b(input)g(data)h(al)o(w)o(ays)g(contains)f(4)g(bytes)h(per)f(pix)o(el.) 29 b(These)21 b(are)h(the)g(formats)e(returned)208 1520 y(by)f FJ(gl.lrectread\(\))p FN(.)0 1667 y FD(ttob)p FJ(\()p FK(\003a)o(g)p FJ(\))208 1766 y FN(This)d(function)f(sets)j(a)f (global)f(\003ag)h(which)f(de\002nes)g(whether)g(the)h(scan)f(lines)h (of)g(the)f(image)h(are)f(read)g(or)h(written)f(from)g(bottom)208 1866 y(to)i(top)g(\(\003ag)g(is)h(zero,)e(compatible)g(with)h(SGI)h (GL\))f(or)g(from)f(top)h(to)g(bottom)f(\(\003ag)h(is)h(one,)e (compatible)g(with)h(X\).)g(The)g(def)o(ault)208 1966 y(is)j(zero.)0 2293 y FE(19.9)121 b Fx(imghdr)32 b FE(\227)h(Deter)s (mine)h(the)h(type)f(of)g(an)g(image)0 2526 y FN(The)20 b FJ(imghdr)f FN(module)g(determines)g(the)i(type)e(of)h(image)g (contained)e(in)j(a)f(\002le)h(or)f(byte)g(stream.)0 2673 y(The)g FJ(imghdr)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (function:)0 2820 y FD(what)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(h)12 b FC(])p FJ(\))208 2919 y FN(T)-6 b(ests)22 b(the)g(image)f(data)h(contained)e(in)i(the)g(\002le)g(named) f(by)h FK(\002lename)p FN(,)e(and)i(returns)e(a)j(string)e(describing)f (the)i(image)f(type.)30 b(If)208 3019 y(optional)18 b FK(h)j FN(is)g(pro)o(vided,)c(the)j FK(\002lename)f FN(is)j(ignored)c (and)i FK(h)g FN(is)h(assumed)f(to)g(contain)f(the)h(byte)g(stream)g (to)h(test.)0 3166 y(The)f(follo)n(wing)e(image)i(types)g(are)g (recognized,)e(as)j(listed)f(belo)n(w)g(with)g(the)h(return)e(v)n(alue) g(from)g FJ(what\(\))p FN(:)1183 3392 y FL(V)-8 b(alue)p 1530 3422 4 100 v 199 w(Image)20 b(f)n(ormat)p 1134 3425 1633 4 v 1183 3495 a FJ('rgb')p 1530 3525 4 100 v 149 w FN(SGI)g(ImgLib)f(Files)1183 3595 y FJ('gif')p 1530 3624 V 149 w FN(GIF)h(87a)g(and)g(89a)f(Files)1183 3694 y FJ('pbm')p 1530 3724 V 149 w FN(Portable)g(Bitmap)i(Files)1183 3794 y FJ('pgm')p 1530 3824 V 149 w FN(Portable)e(Graymap)g(Files)1183 3893 y FJ('ppm')p 1530 3923 V 149 w FN(Portable)g(Pixmap)h(Files)1183 3993 y FJ('tiff')p 1530 4023 V 99 w FN(TIFF)g(Files)1183 4093 y FJ('rast')p 1530 4123 V 99 w FN(Sun)g(Raster)h(Files)1183 4192 y FJ('xbm')p 1530 4222 V 149 w FN(X)g(Bitmap)f(Files)1183 4292 y FJ('jpeg')p 1530 4322 V 99 w FN(JPEG)h(data)f(in)g(JFIF)h(or)f (Exif)g(formats)1183 4392 y FJ('bmp')p 1530 4422 V 149 w FN(BMP)h(\002les)1183 4491 y FJ('png')p 1530 4521 V 149 w FN(Portable)e(Netw)o(ork)h(Graphics)0 4716 y(Ne)n(w)g(in)h(v)o (ersion)e(2.5:)g(Exif)h(detection.)0 4863 y(Y)-9 b(ou)20 b(can)g(e)o(xtend)e(the)j(list)g(of)f(\002le)h(types)f FJ(imghdr)f FN(can)h(recognize)f(by)h(appending)d(to)k(this)f(v)n (ariable:)0 5010 y FD(tests)208 5110 y FN(A)i(list)h(of)f(functions)f (performing)e(the)k(indi)n(vidual)d(tests.)32 b(Each)22 b(function)e(tak)o(es)j(tw)o(o)f(ar)o(guments:)27 b(the)22 b(byte-stream)f(and)h(an)208 5209 y(open)d(\002le-lik)o(e)h(object.)k (When)c FJ(what\(\))g FN(is)h(called)f(with)g(a)h(byte-stream,)e(the)h (\002le-lik)o(e)g(object)g(will)h(be)f FJ(None)p FN(.)208 5342 y(The)f(test)i(function)e(should)g(return)g(a)i(string)f (describing)e(the)i(image)g(type)g(if)g(the)h(test)g(succeeded,)d(or)i FJ(None)g FN(if)h(it)g(f)o(ailed.)p 0 5549 3901 4 v 0 5649 a FI(706)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 707 719 TeXDict begin 707 718 bop 0 83 a FN(Example:)236 321 y FA(>>>)45 b(import)e(imghdr)236 413 y(>>>)i (imghdr.what\('/tmp/bass.gif'\))236 504 y('gif')0 1014 y FE(19.10)122 b Fx(sndhdr)31 b FE(\227)i(Deter)s(mine)i(type)f(of)g (sound)h(\002le)0 1247 y FN(The)24 b FJ(sndhdr)h FN(pro)o(vides)e (utility)i(functions)e(which)h(attempt)h(to)g(determine)e(the)i(type)f (of)h(sound)e(data)i(which)f(is)i(in)f(a)g(\002le.)40 b(When)0 1346 y(these)19 b(functions)f(are)h(able)g(to)h(determine)d (what)i(type)g(of)g(sound)f(data)h(is)h(stored)f(in)g(a)h(\002le,)f (the)o(y)g(return)f(a)i(tuple)e FJ(\()p FK(type)p FJ(,)49 b FK(sampling)p 3849 1346 25 4 v 28 w(-)0 1446 y(r)o(ate)p FJ(,)g FK(c)o(hannels)p FJ(,)f FK(fr)o(ames)p FJ(,)h FK(bits)p 1075 1446 V 30 w(per)p 1216 1446 V 29 w(sample)p FJ(\))p FN(.)24 b(The)19 b(v)n(alue)f(for)g FK(type)g FN(indicates)h(the)f(data)h(type)f(and)g(will)i(be)e(one)g(of)h(the)g (strings)0 1546 y FJ('aifc')p FN(,)26 b FJ('aiff')p FN(,)f FJ('au')p FN(,)h FJ('hcom')p FN(,)g FJ('sndr')p FN(,)g FJ('sndt')p FN(,)g FJ('voc')p FN(,)f FJ('wav')p FN(,)h FJ('8svx')p FN(,)g FJ('sb')p FN(,)g FJ('ub')p FN(,)g(or)f FJ('ul')p FN(.)40 b(The)0 1645 y FK(sampling)p 311 1645 V 28 w(r)o(ate)21 b FN(will)h(be)f(either)g(the)g(actual)g(v)n(alue)f (or)h FJ(0)g FN(if)g(unkno)n(wn)e(or)i(dif)n(\002cult)f(to)h(decode.)26 b(Similarly)-5 b(,)21 b FK(c)o(hannels)e FN(will)j(be)f(either)0 1745 y(the)g(number)e(of)i(channels)f(or)h FJ(0)g FN(if)g(it)h(cannot)e (be)h(determined)e(or)i(if)g(the)g(v)n(alue)g(is)g(dif)n(\002cult)g(to) g(decode.)26 b(The)21 b(v)n(alue)f(for)h FK(fr)o(ames)g FN(will)0 1845 y(be)f(either)f(the)h(number)e(of)i(frames)f(or)h FJ(-1)p FN(.)25 b(The)19 b(last)i(item)f(in)g(the)g(tuple,)f FK(bits)p 2268 1845 V 30 w(per)p 2409 1845 V 30 w(sample)p FN(,)g(will)i(either)e(be)h(the)g(sample)f(size)i(in)f(bits)0 1944 y(or)g FJ('A')g FN(for)g(A-LA)-7 b(W)20 b(or)f FJ('U')i FN(for)e(u-LA)-7 b(W.)0 2091 y FD(what)p FJ(\()p FK(\002lename)p FJ(\))208 2191 y FN(Determines)20 b(the)i(type)f(of)g(sound)f(data)h (stored)g(in)h(the)f(\002le)h FK(\002lename)f FN(using)g FJ(whathdr\(\))p FN(.)27 b(If)21 b(it)h(succeeds,)g(returns)e(a)i (tuple)208 2290 y(as)e(described)f(abo)o(v)o(e,)g(otherwise)g FJ(None)h FN(is)h(returned.)0 2437 y FD(whathdr)p FJ(\()p FK(\002lename)p FJ(\))208 2537 y FN(Determines)26 b(the)h(type)g(of)f (sound)g(data)h(stored)g(in)g(a)h(\002le)f(based)g(on)g(the)g(\002le)h (header)-5 b(.)44 b(The)27 b(name)g(of)f(the)h(\002le)h(is)g(gi)n(v)o (en)e(by)208 2636 y FK(\002lename)p FN(.)d(This)e(function)d(returns)h (a)i(tuple)f(as)h(described)e(abo)o(v)o(e)f(on)i(success,)g(or)g FJ(None)p FN(.)0 2964 y FE(19.11)122 b Fx(ossaudiodev)30 b FE(\227)j(Access)f(to)i(OSS-compatib)n(le)f(audio)i(de)l(vices)0 3197 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3343 y(This)k(module)f (allo)n(ws)i(you)e(to)i(access)g(the)f(OSS)h(\(Open)e(Sound)g(System\)) h(audio)g(interf)o(ace.)33 b(OSS)24 b(is)g(a)n(v)n(ailable)f(for)g(a)g (wide)h(range)0 3443 y(of)19 b(open-source)e(and)h(commercial)g (Unices,)h(and)g(is)h(the)g(standard)e(audio)g(interf)o(ace)h(for)f (Linux)g(and)h(recent)g(v)o(ersions)f(of)h(FreeBSD.)0 3590 y FL(See)i(Also:)0 3737 y FK(Open)f(Sound)e(System)i(Pr)l(o)o(gr)o (ammer')m(s)g(Guide)0 3836 y Fy(\()p FO(http://www)l(.opensound.)o (com/pg)o(uid)o(e/)o(oss)o(.pd)o(f)-6 b Fy(\))208 3936 y FN(the)20 b(of)n(\002cial)g(documentation)d(for)i(the)i(OSS)g(C)g (API)0 4083 y(The)h(module)f(de\002nes)h(a)h(lar)o(ge)e(number)g(of)h (constants)f(supplied)h(by)g(the)g(OSS)h(de)n(vice)e(dri)n(v)o(er;)h (see)h FJ(<sys/soundcard.h>)d FN(on)0 4183 y(either)g(Linux)f(or)h (FreeBSD)h(for)e(a)i(listing)f(.)0 4329 y FJ(ossaudiodev)f FN(de\002nes)h(the)g(follo)n(wing)e(v)n(ariables)i(and)f(functions:)0 4476 y FL(exception)g FD(OSSAudioError)208 4576 y FN(This)h(e)o (xception)e(is)j(raised)f(on)g(certain)g(errors.)k(The)c(ar)o(gument)e (is)j(a)f(string)g(describing)f(what)h(went)g(wrong.)208 4709 y(\(If)25 b FJ(ossaudiodev)e FN(recei)n(v)o(es)i(an)h(error)e (from)g(a)i(system)g(call)g(such)f(as)h FJ(open\(\))p FN(,)g FJ(write\(\))p FN(,)g(or)f FJ(ioctl\(\))p FN(,)h(it)g(raises)208 4808 y FJ(IOError)p FN(.)e(Errors)19 b(detected)g(directly)h(by)g FJ(ossaudiodev)e FN(result)i(in)h FJ(OSSAudioError)p FN(.\))208 4941 y(\(F)o(or)e(backw)o(ards)g(compatibility)-5 b(,)18 b(the)i(e)o(xception)e(class)k(is)f(also)f(a)n(v)n(ailable)g(as) h FJ(ossaudiodev.error)p FN(.\))0 5088 y FD(open)p FJ(\()p FC([)p FK(de)o(vice)o(,)30 b FC(])p FK(mode)p FJ(\))208 5188 y FN(Open)18 b(an)h(audio)f(de)n(vice)g(and)g(return)g(an)h(OSS)g (audio)f(de)n(vice)g(object.)24 b(This)19 b(object)g(supports)e(man)o (y)h(\002le-lik)o(e)h(methods,)f(such)208 5287 y(as)30 b FJ(read\(\))p FN(,)i FJ(write\(\))p FN(,)f(and)e FJ(fileno\(\))g FN(\(although)f(there)h(are)h(subtle)g(dif)n(ferences)e(between)h(con)m (v)o(entional)g(U)t FH(N)t(I)t(X)p 0 5549 3901 4 v 0 5649 a FI(19.10.)52 b FJ(sndhdr)22 b FI(\227)h(Deter)r(mine)i(type)e (of)g(sound)g(\002le)2016 b(707)p eop end %%Page: 708 720 TeXDict begin 708 719 bop 208 83 a FN(read/write)18 b(semantics)i(and)f (those)h(of)f(OSS)i(audio)e(de)n(vices\).)24 b(It)c(also)g(supports)e (a)j(number)d(of)h(audio-speci\002c)f(methods;)h(see)208 183 y(belo)n(w)g(for)h(the)g(complete)f(list)i(of)f(methods.)208 315 y FK(de)o(vice)29 b FN(is)i(the)e(audio)g(de)n(vice)g(\002lename)h (to)g(use.)54 b(If)29 b(it)i(is)g(not)e(speci\002ed,)j(this)e(module)f (\002rst)h(looks)g(in)g(the)g(en)m(vironment)208 415 y(v)n(ariable)19 b(A)-5 b(UDIODEV)20 b(for)f(a)i(de)n(vice)e(to)i(use.) k(If)20 b(not)g(found,)e(it)j(f)o(alls)g(back)e(to)i(`)p FO(/de)n(v/dsp)p FN('.)208 548 y FK(mode)k FN(is)j(one)e(of)g FJ('r')g FN(for)g(read-only)e(\(record\))g(access,)29 b FJ('w')d FN(for)g(write-only)f(\(playback\))f(access)j(and)f FJ('rw')g FN(for)g(both.)208 648 y(Since)c(man)o(y)g(sound)f(cards)h (only)g(allo)n(w)h(one)f(process)g(to)h(ha)n(v)o(e)f(the)g(recorder)f (or)h(player)g(open)f(at)i(a)h(time,)f(it)g(is)g(a)g(good)f(idea)208 747 y(to)f(open)g(the)g(de)n(vice)g(only)f(for)h(the)g(acti)n(vity)g (needed.)28 b(Further)m(,)20 b(some)h(sound)g(cards)g(are)g(half-duple) o(x:)k(the)o(y)c(can)g(be)g(opened)208 847 y(for)e(reading)g(or)h (writing,)f(b)n(ut)h(not)g(both)g(at)g(once.)208 980 y(Note)j(the)h(unusual)f(calling)g(syntax:)32 b(the)24 b FK(\002r)o(st)h FN(ar)o(gument)d(is)i(optional,)g(and)f(the)h(second) f(is)i(required.)34 b(This)24 b(is)h(a)f(historical)208 1079 y(artif)o(act)c(for)f(compatibility)g(with)h(the)g(older)g FJ(linuxaudiodev)e FN(module)h(which)g FJ(ossaudiodev)g FN(supersedes.)0 1226 y FD(openmixer)p FJ(\()p FC([)p FK(de)o(vice)12 b FC(])p FJ(\))208 1326 y FN(Open)20 b(a)i(mix)o(er)f(de)n(vice)f(and)h(return)f(an)h(OSS)i(mix)o(er)d(de)n (vice)h(object.)28 b FK(de)o(vice)20 b FN(is)j(the)e(mix)o(er)g(de)n (vice)f(\002lename)h(to)h(use.)28 b(If)22 b(it)g(is)208 1425 y(not)e(speci\002ed,)g(this)h(module)e(\002rst)j(looks)e(in)g(the) h(en)m(vironment)c(v)n(ariable)j(MIXERDEV)g(for)g(a)h(de)n(vice)f(to)h (use.)26 b(If)20 b(not)h(found,)208 1525 y(it)f(f)o(alls)h(back)f(to)g (`)p FO(/de)n(v/mix)n(er)p FN('.)0 1810 y Fv(19.11.1)101 b(A)m(udio)29 b(De)m(vice)g(Objects)0 2013 y FN(Before)20 b(you)f(can)h(write)g(to)h(or)f(read)f(from)g(an)h(audio)g(de)n(vice,)f (you)g(must)h(call)h(three)f(methods)f(in)h(the)g(correct)g(order:)104 2226 y(1.)41 b FJ(setfmt\(\))19 b FN(to)h(set)h(the)f(output)f(format) 104 2392 y(2.)41 b FJ(channels\(\))18 b FN(to)j(set)g(the)f(number)e (of)i(channels)104 2558 y(3.)41 b FJ(speed\(\))19 b FN(to)h(set)h(the)g (sample)e(rate)0 2772 y(Alternately)-5 b(,)28 b(you)e(can)h(use)h(the)g FJ(setparameters\(\))d FN(method)h(to)h(set)i(all)f(three)f(audio)f (parameters)g(at)i(once.)46 b(This)28 b(is)g(more)0 2871 y(con)m(v)o(enient,)17 b(b)n(ut)j(may)g(not)g(be)g(as)h(\003e)o(xible)f (in)g(all)h(cases.)0 3018 y(The)f(audio)f(de)n(vice)g(objects)h (returned)f(by)h FJ(open\(\))f FN(de\002ne)h(the)g(follo)n(wing)f (methods)g(and)g(\(read-only\))f(attrib)n(utes:)0 3165 y FD(close)p FJ(\(\))208 3264 y FN(Explicitly)23 b(close)h(the)g(audio) g(de)n(vice.)36 b(When)24 b(you)f(are)h(done)f(writing)h(to)g(or)g (reading)f(from)g(an)h(audio)f(de)n(vice,)h(you)g(should)208 3364 y(e)o(xplicitly)19 b(close)h(it.)26 b(A)20 b(closed)g(de)n(vice)g (cannot)f(be)h(used)g(again.)0 3511 y FD(fileno)p FJ(\(\))208 3611 y FN(Return)f(the)i(\002le)f(descriptor)f(associated)h(with)g(the) h(de)n(vice.)0 3757 y FD(read)p FJ(\()p FK(size)p FJ(\))208 3857 y FN(Read)d FK(size)i FN(bytes)f(from)f(the)g(audio)g(input)g(and) g(return)g(them)g(as)h(a)h(Python)d(string.)24 b(Unlik)o(e)19 b(most)i(U)t FH(N)t(I)t(X)g FN(de)n(vice)d(dri)n(v)o(ers,)g(OSS)208 3957 y(audio)24 b(de)n(vices)i(in)g(blocking)e(mode)h(\(the)g(def)o (ault\))g(will)i(block)e FJ(read\(\))g FN(until)h(the)g(entire)f (requested)g(amount)f(of)i(data)g(is)208 4056 y(a)n(v)n(ailable.)0 4203 y FD(write)p FJ(\()p FK(data)p FJ(\))208 4303 y FN(Write)19 b(the)g(Python)f(string)g FK(data)h FN(to)g(the)g(audio)f (de)n(vice)g(and)g(return)g(the)h(number)e(of)i(bytes)f(written.)25 b(If)18 b(the)h(audio)f(de)n(vice)h(is)g(in)208 4402 y(blocking)g(mode)i(\(the)g(def)o(ault\),)g(the)h(entire)f(string)g(is) i(al)o(w)o(ays)f(written)f(\(again,)g(this)h(is)h(dif)n(ferent)d(from)g (usual)k(U)t FH(N)t(I)t(X)g FN(de)n(vice)208 4502 y(semantics\).)g(If)c (the)g(de)n(vice)g(is)h(in)f(non-blocking)d(mode,)i(some)h(data)g(may)g (not)f(be)h(written\227see)g FJ(writeall\(\))p FN(.)0 4649 y FD(writeall)p FJ(\()p FK(data)p FJ(\))208 4749 y FN(Write)f(the)g(entire)f(Python)g(string)g FK(data)g FN(to)h(the)g(audio)f(de)n(vice:)24 b(w)o(aits)19 b(until)g(the)g (audio)f(de)n(vice)g(is)h(able)g(to)g(accept)f(data,)h(writes)208 4848 y(as)24 b(much)e(data)i(as)g(it)g(will)g(accept,)g(and)f(repeats)g (until)h FK(data)e FN(has)i(been)f(completely)f(written.)35 b(If)23 b(the)h(de)n(vice)e(is)j(in)e(blocking)208 4948 y(mode)d(\(the)h(def)o(ault\),)g(this)h(has)f(the)h(same)g(ef)n(fect)e (as)j FJ(write\(\))p FN(;)e FJ(writeall\(\))f FN(is)j(only)d(useful)h (in)h(non-blocking)c(mode.)208 5047 y(Has)i(no)g(return)f(v)n(alue,)g (since)i(the)f(amount)f(of)h(data)g(written)g(is)h(al)o(w)o(ays)g (equal)e(to)h(the)h(amount)e(of)g(data)h(supplied.)0 5194 y(The)g(follo)n(wing)e(methods)i(each)g(map)f(to)i(e)o(xactly)e (one)h FJ(ioctl\(\))f FN(system)i(call.)k(The)20 b(correspondence)d(is) k(ob)o(vious:)j(for)19 b(e)o(xample,)0 5294 y FJ(setfmt\(\))27 b FN(corresponds)f(to)j(the)f FJ(SNDCTL_DSP_SETFMT)d FN(ioctl,)31 b(and)c FJ(sync\(\))h FN(to)g FJ(SNDCTL_DSP_SYNC)e FN(\(this)j(can)f(be)0 5394 y(useful)20 b(when)f(consulting)g(the)h (OSS)h(documentation\).)h(If)e(the)g(underlying)e FJ(ioctl\(\))h FN(f)o(ails,)i(the)o(y)e(all)i(raise)f FJ(IOError)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(708)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 709 721 TeXDict begin 709 720 bop 0 83 a FD(nonblock)p FJ(\(\))208 183 y FN(Put)26 b(the)g(de)n(vice)f(into)h(non-blocking)c(mode.)41 b(Once)26 b(in)g(non-blocking)c(mode,)k(there)g(is)g(no)g(w)o(ay)g(to)g (return)f(it)h(to)g(blocking)208 282 y(mode.)0 429 y FD(getfmts)p FJ(\(\))208 529 y FN(Return)e(a)h(bitmask)g(of)g(the)f (audio)g(output)g(formats)g(supported)f(by)i(the)g(soundcard.)37 b(Some)24 b(of)h(the)g(formats)f(supported)f(by)208 628 y(OSS)e(are:)364 741 y FL(F)n(ormat)p 1109 771 4 100 v 530 w(Description)p 314 774 3480 4 v 364 844 a FJ(AFMT_MU_LAW)p 1109 874 4 100 v 247 w FN(a)g(logarithmic)d(encoding)g(\(used)h(by)h (Sun)g FJ(.au)g FN(\002les)h(and)f FO(/de)n(v/audio)p FN(\))364 943 y FJ(AFMT_A_LAW)p 1109 973 V 297 w FN(a)h(logarithmic)d (encoding)364 1043 y FJ(AFMT_IMA_ADPCM)p 1109 1073 V 97 w FN(a)j(4:1)e(compressed)g(format)g(de\002ned)g(by)h(the)g (Interacti)n(v)o(e)f(Multimedia)g(Association)364 1143 y FJ(AFMT_U8)p 1109 1173 V 447 w FN(Unsigned,)g(8-bit)g(audio)364 1242 y FJ(AFMT_S16_LE)p 1109 1272 V 247 w FN(Signed,)g(16-bit)g(audio,) g(little-endian)g(byte)h(order)f(\(as)h(used)g(by)g(Intel)g (processors\))364 1342 y FJ(AFMT_S16_BE)p 1109 1372 V 247 w FN(Signed,)f(16-bit)g(audio,)g(big-endian)f(byte)i(order)f(\(as)h (used)g(by)g(68k,)f(Po)n(werPC,)h(Sparc\))364 1442 y FJ(AFMT_S8)p 1109 1471 V 447 w FN(Signed,)f(8)h(bit)h(audio)364 1541 y FJ(AFMT_U16_LE)p 1109 1571 V 247 w FN(Unsigned,)e(16-bit)g (little-endian)g(audio)364 1641 y FJ(AFMT_U16_BE)p 1109 1671 V 247 w FN(Unsigned,)g(16-bit)g(big-endian)f(audio)208 1769 y(Consult)31 b(the)g(OSS)i(documentation)28 b(for)j(a)h(full)f (list)i(of)e(audio)f(formats,)k(and)c(note)h(that)h(most)g(de)n(vices)e (support)h(only)f(a)208 1868 y(subset)25 b(of)g(these)g(formats.)39 b(Some)25 b(older)f(de)n(vices)h(only)f(support)g FJ(AFMT_U8)p FN(;)j(the)e(most)g(common)e(format)i(used)f(today)h(is)208 1968 y FJ(AFMT_S16_LE)p FN(.)0 2115 y FD(setfmt)p FJ(\()p FK(format)q FJ(\))208 2215 y FN(T)m(ry)h(to)g(set)h(the)g(current)e (audio)h(format)f(to)i FK(format)q FN(\227see)f FJ(getfmts\(\))g FN(for)g(a)h(list.)44 b(Returns)27 b(the)f(audio)g(format)f(that)i(the) 208 2314 y(de)n(vice)17 b(w)o(as)h(set)h(to,)f(which)f(may)h(not)f(be)h (the)g(requested)f(format.)23 b(May)17 b(also)h(be)g(used)g(to)g (return)e(the)i(current)f(audio)g(format\227)208 2414 y(do)i(this)i(by)f(passing)g(an)g(\223audio)f(format\224)g(of)h FJ(AFMT_QUERY)p FN(.)0 2561 y FD(channels)p FJ(\()p FK(nc)o(hannels)p FJ(\))208 2660 y FN(Set)28 b(the)g(number)e(of)h(output)g(channels)f (to)i FK(nc)o(hannels)p FN(.)46 b(A)28 b(v)n(alue)f(of)g(1)h(indicates) g(monophonic)c(sound,)k(2)g(stereophonic.)208 2760 y(Some)21 b(de)n(vices)g(may)h(ha)n(v)o(e)f(more)g(than)g(2)h(channels,)f(and)g (some)h(high-end)d(de)n(vices)i(may)h(not)f(support)g(mono.)28 b(Returns)22 b(the)208 2860 y(number)c(of)i(channels)f(the)h(de)n(vice) g(w)o(as)h(set)g(to.)0 3006 y FD(speed)p FJ(\()p FK(sampler)o(ate)p FJ(\))208 3106 y FN(T)m(ry)g(to)h(set)g(the)g(audio)f(sampling)g(rate)g (to)h FK(sampler)o(ate)f FN(samples)h(per)f(second.)29 b(Returns)22 b(the)f(rate)h(actually)f(set.)31 b(Most)22 b(sound)208 3206 y(de)n(vices)d(don')o(t)g(support)g(arbitrary)f (sampling)h(rates.)26 b(Common)18 b(rates)j(are:)1038 3321 y FL(Rate)p 1293 3351 V 140 w(Description)p 988 3354 2132 4 v 1038 3424 a FN(8000)p 1293 3454 4 100 v 139 w(def)o(ault)e(rate)i(for)e FO(/de)n(v/audio)1038 3523 y FN(11025)p 1293 3553 V 97 w(speech)h(recording)1038 3623 y(22050)p 1293 3653 V 1038 3723 a(44100)p 1293 3753 V 97 w(CD)h(quality)e(audio)h(\(at)g(16)g(bits/sample)g(and)f(2)i (channels\))1038 3822 y(96000)p 1293 3852 V 97 w(D)m(VD)f(quality)g (audio)f(\(at)h(24)g(bits/sample\))0 3959 y FD(sync)p FJ(\(\))208 4058 y FN(W)-7 b(ait)29 b(until)f(the)g(sound)f(de)n(vice)g (has)h(played)f(e)n(v)o(ery)g(byte)g(in)h(its)h(b)n(uf)n(fer)-5 b(.)48 b(\(This)28 b(happens)e(implicitly)i(when)f(the)h(de)n(vice)g (is)208 4158 y(closed.\))c(The)c(OSS)h(documentation)c(recommends)h (closing)i(and)f(re-opening)f(the)i(de)n(vice)f(rather)g(than)h(using)g FJ(sync\(\))p FN(.)0 4305 y FD(reset)p FJ(\(\))208 4404 y FN(Immediately)e(stop)h(playing)g(or)g(recording)f(and)h(return)g (the)h(de)n(vice)f(to)h(a)g(state)g(where)g(it)g(can)g(accept)f (commands.)k(The)d(OSS)208 4504 y(documentation)d(recommends)h(closing) h(and)h(re-opening)d(the)k(de)n(vice)e(after)h(calling)g FJ(reset\(\))p FN(.)0 4651 y FD(post)p FJ(\(\))208 4751 y FN(T)-6 b(ell)27 b(the)f(dri)n(v)o(er)f(that)i(there)f(is)i(lik)o (ely)e(to)h(be)f(a)h(pause)f(in)h(the)g(output,)f(making)g(it)h (possible)f(for)g(the)h(de)n(vice)e(to)i(handle)f(the)208 4850 y(pause)21 b(more)h(intelligently)-5 b(.)29 b(Y)-9 b(ou)22 b(might)f(use)i(this)f(after)g(playing)f(a)i(spot)f(sound)f(ef) n(fect,)h(before)f(w)o(aiting)h(for)f(user)h(input,)g(or)208 4950 y(before)c(doing)h(disk)h(I/O.)0 5097 y(The)g(follo)n(wing)e(con)m (v)o(enience)g(methods)h(combine)f(se)n(v)o(eral)i(ioctls,)g(or)g(one)g (ioctl)g(and)g(some)g(simple)g(calculations.)0 5244 y FD(setparameters)p FJ(\()p FK(format,)d(nc)o(hannels,)h(sampler)o(ate)i FC([)p FK(,)g(strict=F)-6 b(alse)12 b FC(])p FJ(\))208 5343 y FN(Set)38 b(the)f(k)o(e)o(y)g(audio)g(sampling)f (parameters\227sample)g(format,)k(number)c(of)h(channels,)k(and)c (sampling)f(rate\227in)h(one)p 0 5549 3901 4 v 0 5649 a FI(19.11.)52 b FJ(ossaudiodev)21 b FI(\227)j(Access)d(to)j (OSS-compatib)n(le)g(audio)g(de)n(vices)1288 b(709)p eop end %%Page: 710 722 TeXDict begin 710 721 bop 208 83 a FN(method)29 b(call.)58 b FK(format)q FN(,)35 b FK(nc)o(hannels)p FN(,)c(and)g FK(sampler)o(ate)f FN(should)g(be)h(as)h(speci\002ed)f(in)g(the)g FJ(setfmt\(\))p FN(,)i FJ(channels\(\))p FN(,)208 183 y(and)19 b FJ(speed\(\))f FN(methods.)24 b(If)19 b FK(strict)k FN(is)d(true,)f FJ(setparameters\(\))f FN(checks)h(to)g(see)h(if)g (each)f(parameter)f(w)o(as)j(actually)e(set)208 282 y(to)26 b(the)g(requested)e(v)n(alue,)j(and)e(raises)i FJ(OSSAudioError)d FN(if)i(not.)42 b(Returns)25 b(a)i(tuple)e(\()p FK(format)q FN(,)j FK(nc)o(hannels)p FN(,)d FK(sampler)o(ate)p FN(\))208 382 y(indicating)19 b(the)i(parameter)f(v)n(alues)h(that)g(were)g (actually)f(set)i(by)f(the)g(de)n(vice)f(dri)n(v)o(er)g(\(i.e.,)h(the)g (same)g(as)h(the)f(return)f(v)n(alues)h(of)208 482 y FJ(setfmt\(\))p FN(,)e FJ(channels\(\))p FN(,)f(and)i FJ(speed\(\))p FN(\).)208 614 y(F)o(or)f(e)o(xample,)533 837 y FA(\(fmt,)44 b(channels,)g(rate\))g(=)g(dsp.setparameters\(fmt,)e (channels,)h(rate\))208 994 y FN(is)21 b(equi)n(v)n(alent)d(to)533 1217 y FA(fmt)45 b(=)f(dsp.setfmt\(fmt\))533 1309 y(channels)g(=)h (dsp.channels\(channels\))533 1400 y(rate)g(=)f(dsp.rate\(channels\))0 1601 y FD(bufsize)p FJ(\(\))208 1701 y FN(Returns)20 b(the)g(size)h(of)f(the)g(hardw)o(are)f(b)n(uf)n(fer)m(,)f(in)i (samples.)0 1848 y FD(obufcount)p FJ(\(\))208 1948 y FN(Returns)g(the)g(number)e(of)i(samples)g(that)h(are)f(in)g(the)g (hardw)o(are)f(b)n(uf)n(fer)g(yet)h(to)g(be)h(played.)0 2094 y FD(obuffree)p FJ(\(\))208 2194 y FN(Returns)f(the)g(number)e(of) i(samples)g(that)h(could)e(be)h(queued)f(into)g(the)i(hardw)o(are)d(b)n (uf)n(fer)h(to)i(be)f(played)f(without)g(blocking.)0 2341 y(Audio)g(de)n(vice)h(objects)g(also)g(support)f(se)n(v)o(eral)g (read-only)f(attrib)n(utes:)0 2488 y FD(closed)208 2587 y FN(Boolean)h(indicating)g(whether)g(the)h(de)n(vice)g(has)g(been)g (closed.)0 2734 y FD(name)208 2834 y FN(String)f(containing)g(the)h (name)f(of)h(the)g(de)n(vice)g(\002le.)0 2981 y FD(mode)208 3080 y FN(The)f(I/O)i(mode)e(for)h(the)g(\002le,)g(either)g FJ("r")p FN(,)g FJ("rw")p FN(,)g(or)g FJ("w")p FN(.)0 3365 y Fv(19.11.2)101 b(Mix)m(er)28 b(De)m(vice)g(Objects)0 3568 y FN(The)20 b(mix)o(er)f(object)h(pro)o(vides)e(tw)o(o)j (\002le-lik)o(e)f(methods:)0 3715 y FD(close)p FJ(\(\))208 3814 y FN(This)f(method)f(closes)i(the)f(open)f(mix)o(er)h(de)n(vice)f (\002le.)25 b(An)o(y)19 b(further)f(attempts)h(to)h(use)f(the)g(mix)o (er)g(after)g(this)h(\002le)g(is)g(closed)f(will)208 3914 y(raise)h(an)g FJ(IOError)p FN(.)0 4061 y FD(fileno)p FJ(\(\))208 4160 y FN(Returns)g(the)g(\002le)h(handle)e(number)f(of)i (the)g(open)f(mix)o(er)h(de)n(vice)f(\002le.)0 4307 y(The)h(remaining)e (methods)h(are)h(speci\002c)h(to)f(audio)f(mixing:)0 4454 y FD(controls)p FJ(\(\))208 4554 y FN(This)32 b(method)g(returns)f (a)i(bitmask)g(specifying)e(the)h(a)n(v)n(ailable)g(mix)o(er)g (controls)g(\(\223Control\224)f(being)h(a)h(speci\002c)g(mixable)208 4653 y(\223channel\224,)24 b(such)g(as)i FJ(SOUND_MIXER_PCM)c FN(or)i FJ(SOUND_MIXER_SYNTH)p FN(\).)e(This)j(bitmask)f(indicates)h(a) g(subset)g(of)f(all)208 4753 y(a)n(v)n(ailable)19 b(mix)o(er)g (controls\227the)f FJ(SOUND_MIXER_)1809 4768 y(*)1877 4753 y FN(constants)i(de\002ned)f(at)h(module)f(le)n(v)o(el.)24 b(T)-7 b(o)20 b(determine)f(if,)h(for)f(e)o(xam-)208 4853 y(ple,)h(the)g(current)f(mix)o(er)g(object)g(supports)h(a)g(PCM)h (mix)o(er)m(,)e(use)h(the)h(follo)n(wing)d(Python)h(code:)444 5076 y FA(mixer=ossaudiodev.openmixer\(\))444 5168 y(if)44 b(mixer.controls\(\))e(&)j(\(1)g(<<)f(ossaudiodev.SOUND_MIXER_PCM\):) 623 5259 y(#)h(PCM)f(is)h(supported)623 5350 y(...)f(code)h(...)p 0 5549 3901 4 v 0 5649 a FI(710)2531 b(Chapter)24 b(19.)52 b(Multimedia)25 b(Ser)r(vices)p eop end %%Page: 711 723 TeXDict begin 711 722 bop 208 83 a FN(F)o(or)21 b(most)h(purposes,)e (the)i FJ(SOUND_MIXER_VOLUME)d FN(\(master)i(v)n(olume\))f(and)h FJ(SOUND_MIXER_PCM)f FN(controls)h(should)208 183 y(suf)n(\002ce\227b)n (ut)15 b(code)h(that)h(uses)g(the)f(mix)o(er)g(should)f(be)i(\003e)o (xible)e(when)h(it)h(comes)g(to)f(choosing)f(mix)o(er)h(controls.)22 b(On)17 b(the)f(Gra)n(vis)208 282 y(Ultrasound,)i(for)i(e)o(xample,)e FJ(SOUND_MIXER_VOLUME)g FN(does)h(not)h(e)o(xist.)0 429 y FD(stereocontrols)p FJ(\(\))208 529 y FN(Returns)26 b(a)h(bitmask)f(indicating)f(stereo)h(mix)o(er)f(controls.)43 b(If)26 b(a)h(bit)g(is)g(set,)h(the)f(corresponding)c(control)i(is)i (stereo;)j(if)c(it)i(is)208 628 y(unset,)21 b(the)h(control)e(is)j (either)e(monophonic)e(or)i(not)h(supported)d(by)j(the)f(mix)o(er)g (\(use)h(in)g(combination)d(with)j FJ(controls\(\))208 728 y FN(to)e(determine)f(which\).)208 861 y(See)h(the)g(code)g(e)o (xample)f(for)g(the)h FJ(controls\(\))f FN(function)g(for)g(an)h(e)o (xample)f(of)h(getting)g(data)g(from)f(a)h(bitmask.)0 1008 y FD(reccontrols)p FJ(\(\))208 1107 y FN(Returns)36 b(a)i(bitmask)e(specifying)g(the)h(mix)o(er)f(controls)g(that)h(may)f (be)h(used)g(to)g(record.)74 b(See)37 b(the)g(code)g(e)o(xample)e(for) 208 1207 y FJ(controls\(\))18 b FN(for)i(an)g(e)o(xample)f(of)h (reading)f(from)g(a)h(bitmask.)0 1354 y FD(get)p FJ(\()p FK(contr)l(ol)p FJ(\))208 1453 y FN(Returns)k(the)h(v)n(olume)f(of)h(a) h(gi)n(v)o(en)d(mix)o(er)h(control.)39 b(The)24 b(returned)g(v)n(olume) g(is)h(a)h(2-tuple)e FJ(\(left_volume,right_-)208 1553 y(volume\))p FN(.)f(V)-11 b(olumes)18 b(are)g(speci\002ed)g(as)h (numbers)e(from)g(0)i(\(silent\))f(to)g(100)g(\(full)f(v)n(olume\).)23 b(If)c(the)f(control)f(is)i(monophonic,)208 1653 y(a)h(2-tuple)f(is)i (still)h(returned,)c(b)n(ut)i(both)f(v)n(olumes)h(are)g(the)g(same.)208 1786 y(Raises)33 b FJ(OSSAudioError)d FN(if)i(an)g(in)m(v)n(alid)f (control)g(w)o(as)h(is)h(speci\002ed,)i(or)c FJ(IOError)h FN(if)g(an)g(unsupported)d(control)i(is)208 1885 y(speci\002ed.)0 2032 y FD(set)p FJ(\()p FK(contr)l(ol,)19 b(\(left,)h(right\))p FJ(\))208 2132 y FN(Sets)i(the)g(v)n(olume)f(for)h(a)g(gi)n(v)o(en)f (mix)o(er)g(control)f(to)i FJ(\(left,right\))p FN(.)29 b FJ(left)22 b FN(and)f FJ(right)h FN(must)g(be)f(ints)i(and)e(between) g(0)208 2231 y(\(silent\))h(and)h(100)f(\(full)g(v)n(olume\).)32 b(On)22 b(success,)i(the)f(ne)n(w)g(v)n(olume)f(is)i(returned)d(as)i(a) h(2-tuple.)31 b(Note)23 b(that)g(this)h(may)e(not)h(be)208 2331 y(e)o(xactly)c(the)h(same)g(as)h(the)g(v)n(olume)e(speci\002ed,)g (because)h(of)g(the)g(limited)g(resolution)f(of)h(some)g(soundcard')-5 b(s)18 b(mix)o(ers.)208 2464 y(Raises)28 b FJ(OSSAudioError)d FN(if)i(an)g(in)m(v)n(alid)f(mix)o(er)g(control)f(w)o(as)j (speci\002ed,)g(or)f(if)g(the)g(speci\002ed)f(v)n(olumes)h(were)f (out-of-)208 2563 y(range.)0 2710 y FD(get_recsrc)p FJ(\(\))208 2810 y FN(This)20 b(method)f(returns)g(a)i(bitmask)e(indicating)g (which)h(control\(s\))e(are)j(currently)d(being)h(used)h(as)h(a)g (recording)d(source.)0 2957 y FD(set_recsrc)p FJ(\()p FK(bitmask)q FJ(\))208 3056 y FN(Call)30 b(this)g(function)d(to)j (specify)e(a)i(recording)d(source.)52 b(Returns)29 b(a)g(bitmask)g (indicating)f(the)i(ne)n(w)f(recording)e(source)h(\(or)208 3156 y(sources\))22 b(if)i(successful;)h(raises)f FJ(IOError)f FN(if)h(an)f(in)m(v)n(alid)g(source)f(w)o(as)j(speci\002ed.)34 b(T)-7 b(o)24 b(set)g(the)g(current)e(recording)f(source)208 3256 y(to)f(the)g(microphone)d(input:)444 3480 y FA(mixer.setrecsrc)42 b(\(1)j(<<)f(ossaudiodev.SOUND_MIXER_MIC\))p 0 5549 3901 4 v 0 5649 a FI(19.11.)52 b FJ(ossaudiodev)21 b FI(\227)j(Access)d(to)j (OSS-compatib)n(le)g(audio)g(de)n(vices)1288 b(711)p eop end %%Page: 712 724 TeXDict begin 712 723 bop 0 5549 3901 4 v 0 5649 a FI(712)p eop end %%Page: 713 725 TeXDict begin 713 724 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3395 427 y FG(TWENTY)p 0 515 V 798 978 a FT(Gr)n(aphical)56 b(User)h(Interf)-6 b(aces)58 b(with)g(Tk)0 1465 y FN(Tk/Tcl)18 b(has)h(long)f(been)f(an)i(inte)o(gral)e(part)i(of)f(Python.)23 b(It)c(pro)o(vides)e(a)i(rob)n(ust)f(and)g(platform)f(independent)f (windo)n(wing)g(toolkit,)i(that)0 1565 y(is)j(a)n(v)n(ailable)f(to)g (Python)f(programmers)f(using)h(the)i FJ(Tkinter)e FN(module,)g(and)g (its)i(e)o(xtension,)e(the)h FJ(Tix)g FN(module.)0 1712 y(The)f FJ(Tkinter)g FN(module)g(is)h(a)h(thin)e(object-oriented)e (layer)i(on)h(top)f(of)h(Tcl/Tk.)k(T)-7 b(o)20 b(use)g FJ(Tkinter)p FN(,)f(you)f(don')o(t)g(need)i(to)f(write)h(Tcl)0 1811 y(code,)h(b)n(ut)g(you)f(will)i(need)f(to)g(consult)g(the)g(Tk)g (documentation,)e(and)h(occasionally)g(the)i(Tcl)f(documentation.)k FJ(Tkinter)c FN(is)h(a)g(set)0 1911 y(of)e(wrappers)e(that)i(implement) f(the)h(Tk)g(widgets)f(as)i(Python)e(classes.)26 b(In)19 b(addition,)g(the)g(internal)h(module)e FJ(_tkinter)h FN(pro)o(vides)f(a)0 2010 y(threadsafe)h(mechanism)g(which)g(allo)n(ws) i(Python)e(and)h(Tcl)g(to)g(interact.)0 2157 y(Tk)f(is)i(not)e(the)h (only)e(GUI)i(for)f(Python;)g(see)h(section)f(20.6,)f(\223Other)h(User) h(Interf)o(ace)e(Modules)h(and)g(P)o(ackages,)-6 b(\224)19 b(for)g(more)g(informa-)0 2257 y(tion)h(on)g(other)f(GUI)h(toolkits)g (for)g(Python.)50 2400 y FD(Tkinter)347 b FN(Interf)o(ace)19 b(to)h(Tcl/Tk)g(for)g(graphical)e(user)i(interf)o(aces)50 2500 y FD(Tix)547 b FN(Tk)20 b(Extension)f(W)m(idgets)h(for)g(Tkinter) 50 2599 y FD(ScrolledText)97 b FN(T)-6 b(e)o(xt)20 b(widget)g(with)g(a) h(v)o(ertical)e(scroll)i(bar)-5 b(.)50 2699 y FD(turtle)397 b FN(An)20 b(en)m(vironment)e(for)h(turtle)h(graphics.)0 3003 y FE(20.1)121 b Fx(Tkinter)32 b FE(\227)g(Python)j(interf)l(ace)g (to)f(Tcl/Tk)0 3236 y FN(The)17 b FJ(Tkinter)g FN(module)f(\(\223Tk)h (interf)o(ace\224\))g(is)h(the)g(standard)e(Python)h(interf)o(ace)f(to) i(the)g(Tk)f(GUI)h(toolkit.)23 b(Both)18 b(Tk)f(and)g FJ(Tkinter)0 3336 y FN(are)i(a)n(v)n(ailable)f(on)g(most)i(U)t FH(N)t(I)t(X)i FN(platforms,)c(as)h(well)g(as)g(on)f(W)m(indo)n(ws)g (and)g(Macintosh)g(systems.)25 b(\(Tk)18 b(itself)h(is)h(not)e(part)g (of)h(Python;)0 3435 y(it)i(is)g(maintained)e(at)h(Acti)n(v)o (eState.\))0 3582 y FL(See)h(Also:)0 3729 y FK(Python)e(Tkinter)i (Resour)m(ces)0 3829 y Fy(\()p FO(http://www)l(.p)n(ython.org/t)o(op)o (ics/tkinte)o(r/)-6 b Fy(\))208 3928 y FN(The)16 b(Python)h(Tkinter)f (T)-7 b(opic)17 b(Guide)f(pro)o(vides)g(a)h(great)g(deal)g(of)g (information)e(on)i(using)g(Tk)g(from)f(Python)g(and)h(links)g(to)g (other)208 4028 y(sources)i(of)h(information)e(on)i(Tk.)0 4175 y FK(An)g(Intr)l(oduction)e(to)i(Tkinter)0 4274 y Fy(\()p FO(http://www)l(.p)n(ythonw)o(are)o(.)o(com/lib)o(r)o(ar)r (y/an)o(-in)o(tro)o(du)o(ction)o(-to)o(-tkint)o(er)l(.h)o(tm)-6 b Fy(\))208 4374 y FN(Fredrik)19 b(Lundh')-5 b(s)19 b(on-line)g (reference)f(material.)0 4521 y FK(Tkinter)j(r)m(efer)m(ence:)j(a)d (GUI)f(for)h(Python)0 4621 y Fy(\()p FO(http://www)l(.nmt.edu/tcc/help) o(/p)o(ubs/l)o(an)o(g.h)o(tml)-6 b Fy(\))208 4720 y FN(On-line)19 b(reference)f(material.)0 4867 y FK(Tkinter)j(for)f(JPython)0 4967 y Fy(\()p FO(http://jtkinter)l(.sourcef)n(orge)n(.n)o(et)-6 b Fy(\))208 5066 y FN(The)19 b(Jython)h(interf)o(ace)f(to)h(Tkinter)-5 b(.)0 5213 y FK(Python)19 b(and)g(Tkinter)i(Pr)l(o)o(gr)o(amming)0 5313 y Fy(\()p FO(http://www)l(.amaz)o(on.com/e)n(x)n(ec/ob)o(ido)o (s/ASIN/)o(188)o(47)o(77)o(81)o(3)-6 b Fy(\))p 0 5549 3901 4 v 3762 5649 a FI(713)p eop end %%Page: 714 726 TeXDict begin 714 725 bop 208 83 a FN(The)19 b(book)g(by)h(John)g (Grayson)f(\(ISBN)h(1-884777-81-3\).)0 367 y Fv(20.1.1)101 b(Tkinter)28 b(Modules)0 570 y FN(Most)d(of)g(the)h(time,)g(the)f FJ(Tkinter)g FN(module)e(is)k(all)e(you)g(really)f(need,)i(b)n(ut)f(a)h (number)d(of)i(additional)f(modules)g(are)h(a)n(v)n(ailable)g(as)0 670 y(well.)g(The)20 b(Tk)f(interf)o(ace)g(is)h(located)f(in)h(a)g (binary)f(module)f(named)g FJ(_tkinter)p FN(.)24 b(This)c(module)e (contains)h(the)h(lo)n(w-le)n(v)o(el)e(interf)o(ace)0 769 y(to)g(Tk,)g(and)f(should)g(ne)n(v)o(er)f(be)i(used)g(directly)f (by)g(application)f(programmers.)22 b(It)c(is)h(usually)e(a)h(shared)f (library)g(\(or)g(DLL\),)g(b)n(ut)h(might)0 869 y(in)i(some)g(cases)h (be)f(statically)h(link)o(ed)e(with)i(the)f(Python)f(interpreter)-5 b(.)0 1016 y(In)26 b(addition)g(to)g(the)h(Tk)f(interf)o(ace)g(module,) h FJ(Tkinter)f FN(includes)g(a)h(number)d(of)j(Python)e(modules.)43 b(The)27 b(tw)o(o)f(most)h(important)0 1115 y(modules)18 b(are)g(the)h FJ(Tkinter)f FN(module)g(itself,)h(and)f(a)i(module)d (called)i FJ(Tkconstants)p FN(.)j(The)d(former)e(automatically)g (imports)i(the)0 1215 y(latter)m(,)h(so)g(to)h(use)f(Tkinter)m(,)f(all) i(you)e(need)g(to)i(do)e(is)j(to)e(import)f(one)h(module:)236 1362 y FA(import)44 b(Tkinter)0 1648 y FN(Or)m(,)20 b(more)f(often:)236 1795 y FA(from)44 b(Tkinter)g(import)1133 1808 y(*)0 2082 y FL(class)21 b FD(Tk)p FJ(\()p FK(scr)m(eenName=None)o(,)e (baseName=None)o(,)f(className='Tk',)i(useTk=1)p FJ(\))208 2182 y FN(The)h FJ(Tk)h FN(class)h(is)g(instantiated)e(without)g(ar)o (guments.)29 b(This)22 b(creates)g(a)g(tople)n(v)o(el)f(widget)g(of)h (Tk)f(which)h(usually)f(is)i(the)f(main)208 2281 y(windo)n(w)g(of)i(an) f(application.)34 b(Each)24 b(instance)f(has)h(its)h(o)n(wn)e (associated)g(Tcl)h(interpreter)-5 b(.)71 b(Changed)22 b(in)i(v)o(ersion)f(2.4:)g(The)208 2381 y FK(useTk)e FN(parameter)e(w)o(as)i(added.)0 2528 y FD(Tcl)p FJ(\()p FK(scr)m(eenName=None)o(,)e(baseName=None)o(,)f(className='Tk',)i (useTk=0)p FJ(\))208 2627 y FN(The)j FJ(Tcl)h FN(function)e(is)j(a)f(f) o(actory)f(function)f(which)h(creates)h(an)g(object)f(much)g(lik)o(e)i (that)f(created)f(by)g(the)h FJ(Tk)g FN(class,)i(e)o(xcept)208 2727 y(that)h(it)i(does)e(not)g(initialize)h(the)g(Tk)f(subsystem.)47 b(This)28 b(is)h(most)e(often)g(useful)g(when)g(dri)n(ving)f(the)i(Tcl) g(interpreter)e(in)i(an)208 2827 y(en)m(vironment)g(where)j(one)g (doesn')o(t)f(w)o(ant)h(to)h(create)f(e)o(xtraneous)f(tople)n(v)o(el)g (windo)n(ws,)j(or)f(where)f(one)g(cannot)f(\(such)h(as)210 2926 y(U)t FH(N)t(I)t(X)r FN(/Linux)23 b(systems)i(without)e(an)i(X)f (serv)o(er\).)36 b(An)24 b(object)g(created)f(by)h(the)g FJ(Tcl)h FN(object)e(can)h(ha)n(v)o(e)g(a)h(T)-7 b(ople)n(v)o(el)23 b(windo)n(w)208 3026 y(created)c(\(and)g(the)h(Tk)g(subsystem)g (initialized\))g(by)f(calling)h(its)h FJ(loadtk)f FN(method.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 3173 y(Other)h(modules)f(that)h (pro)o(vide)e(Tk)i(support)f(include:)0 3399 y FD(ScrolledText)39 b FN(T)-6 b(e)o(xt)20 b(widget)g(with)g(a)h(v)o(ertical)e(scroll)i(bar) e(b)n(uilt)i(in.)0 3563 y FD(tkColorChooser)39 b FN(Dialog)20 b(to)g(let)h(the)f(user)g(choose)f(a)i(color)-5 b(.)0 3727 y FD(tkCommonDialog)39 b FN(Base)21 b(class)g(for)f(the)g(dialogs) g(de\002ned)f(in)h(the)g(other)g(modules)f(listed)h(here.)0 3892 y FD(tkFileDialog)39 b FN(Common)19 b(dialogs)h(to)g(allo)n(w)g (the)g(user)g(to)h(specify)e(a)i(\002le)g(to)f(open)f(or)h(sa)n(v)o(e.) 0 4056 y FD(tkFont)40 b FN(Utilities)22 b(to)e(help)g(w)o(ork)f(with)i (fonts.)0 4221 y FD(tkMessageBox)39 b FN(Access)21 b(to)f(standard)g (Tk)g(dialog)f(box)o(es.)0 4385 y FD(tkSimpleDialog)39 b FN(Basic)21 b(dialogs)f(and)f(con)m(v)o(enience)e(functions.)0 4549 y FD(Tkdnd)41 b FN(Drag-and-drop)12 b(support)j(for)g FJ(Tkinter)p FN(.)23 b(This)17 b(is)g(e)o(xperimental)d(and)i(should)f (become)g(deprecated)g(when)g(it)j(is)f(replaced)208 4649 y(with)j(the)g(Tk)g(DND.)0 4813 y FD(turtle)40 b FN(T)l(urtle)20 b(graphics)f(in)i(a)f(Tk)g(windo)n(w)-5 b(.)0 5097 y Fv(20.1.2)101 b(Tkinter)28 b(Lif)m(e)g(Preser)s(v)n(er)0 5300 y FN(This)c(section)f(is)i(not)e(designed)f(to)i(be)f(an)h(e)o (xhausti)n(v)o(e)e(tutorial)h(on)g(either)g(Tk)g(or)h(Tkinter)-5 b(.)34 b(Rather)m(,)24 b(it)g(is)h(intended)d(as)i(a)g(stop)g(gap,)0 5400 y(pro)o(viding)17 b(some)j(introductory)e(orientation)g(on)i(the)g (system.)p 0 5549 3901 4 v 0 5649 a FI(714)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 715 727 TeXDict begin 715 726 bop 0 83 a FN(Credits:)125 296 y FM(\017)41 b FN(Tkinter)19 b(w)o(as)i(written)f(by)f(Steen)i(Lumholt) d(and)i(Guido)f(v)n(an)h(Rossum.)125 462 y FM(\017)41 b FN(Tk)20 b(w)o(as)h(written)f(by)f(John)h(Ousterhout)f(while)h(at)h (Berk)o(ele)o(y)-5 b(.)125 628 y FM(\017)41 b FN(This)20 b(Life)g(Preserv)o(er)f(w)o(as)i(written)f(by)g(Matt)g(Conw)o(ay)g(at)h (the)f(Uni)n(v)o(ersity)f(of)h(V)-5 b(ir)o(ginia.)125 794 y FM(\017)41 b FN(The)19 b(html)h(rendering,)e(and)i(some)g (liberal)g(editing,)f(w)o(as)i(produced)c(from)j(a)g(FrameMak)o(er)f(v) o(ersion)g(by)h(K)n(en)g(Manheimer)-5 b(.)125 960 y FM(\017)41 b FN(Fredrik)19 b(Lundh)f(elaborated)h(and)g(re)n(vised)h(the)g(class)h (interf)o(ace)f(descriptions,)e(to)j(get)f(them)g(current)f(with)h(Tk)g (4.2.)125 1127 y FM(\017)41 b FN(Mik)o(e)20 b(Clarkson)h(con)m(v)o (erted)d(the)j(documentation)d(to)j(L)1814 1110 y FF(A)1844 1127 y FN(T)1881 1145 y(E)1921 1127 y(X,)g(and)f(compiled)g(the)h(User) g(Interf)o(ace)f(chapter)g(of)g(the)h(reference)208 1226 y(manual.)0 1494 y FI(Ho)o(w)i(T)-10 b(o)23 b(Use)g(This)f(Section)0 1697 y FN(This)d(section)g(is)i(designed)d(in)h(tw)o(o)h(parts:)k(the)c (\002rst)g(half)f(\(roughly\))d(co)o(v)o(ers)i(background)e(material,)j (while)g(the)g(second)g(half)g(can)g(be)0 1797 y(tak)o(en)h(to)g(the)g (k)o(e)o(yboard)e(as)j(a)f(handy)f(reference.)0 1944 y(When)f(trying)g(to)h(answer)f(questions)g(of)g(the)h(form)f(\223ho)n (w)g(do)g(I)h(do)f(blah\224,)g(it)h(is)h(often)e(best)h(to)g(\002nd)f (out)g(ho)n(w)g(to)h(do\223blah\224)e(in)i(straight)0 2043 y(Tk,)29 b(and)e(then)g(con)m(v)o(ert)e(this)j(back)f(into)g(the)h (corresponding)c FJ(Tkinter)j FN(call.)47 b(Python)26 b(programmers)f(can)i(often)g(guess)h(at)g(the)0 2143 y(correct)21 b(Python)f(command)g(by)i(looking)e(at)i(the)g(Tk)f (documentation.)27 b(This)22 b(means)g(that)g(in)g(order)e(to)i(use)g (Tkinter)m(,)f(you)g(will)h(ha)n(v)o(e)0 2243 y(to)29 b(kno)n(w)e(a)j(little)f(bit)g(about)f(Tk.)50 b(This)29 b(document)d(can')o(t)i(ful\002ll)h(that)g(role,)h(so)f(the)g(best)g (we)g(can)f(do)g(is)i(point)e(you)g(to)h(the)f(best)0 2342 y(documentation)17 b(that)k(e)o(xists.)k(Here)20 b(are)g(some)g(hints:)125 2572 y FM(\017)41 b FN(The)28 b(authors)f(strongly)h(suggest)g(getting)f(a)i(cop)o(y)f(of)g(the)h(Tk) f(man)g(pages.)50 b(Speci\002cally)-5 b(,)30 b(the)e(man)g(pages)g(in)h (the)g FJ(mann)208 2672 y FN(directory)e(are)h(most)h(useful.)50 b(The)28 b FJ(man3)h FN(man)f(pages)g(describe)g(the)h(C)g(interf)o (ace)f(to)h(the)f(Tk)h(library)f(and)g(thus)g(are)h(not)208 2772 y(especially)19 b(helpful)g(for)h(script)g(writers.)125 2938 y FM(\017)41 b FN(Addison-W)-7 b(esle)o(y)27 b(publishes)i(a)g (book)f(called)h FK(Tcl)g(and)g(the)g(Tk)g(T)-8 b(oolkit)30 b FN(by)e(John)h(Ousterhout)e(\(ISBN)j(0-201-63337-X\))208 3037 y(which)22 b(is)i(a)g(good)d(introduction)g(to)i(Tcl)g(and)g(Tk)g (for)f(the)h(no)o(vice.)33 b(The)22 b(book)g(is)i(not)f(e)o(xhausti)n (v)o(e,)f(and)g(for)h(man)o(y)e(details)j(it)208 3137 y(defers)19 b(to)h(the)h(man)e(pages.)125 3303 y FM(\017)41 b FN(`)p FO(Tkinter)l(.p)n(y)p FN(')18 b(is)j(a)f(last)h(resort)f(for)g (most,)g(b)n(ut)g(can)g(be)g(a)h(good)e(place)g(to)i(go)f(when)f (nothing)g(else)h(mak)o(es)h(sense.)0 3533 y FL(See)g(Also:)0 3680 y FK(ActiveState)e(Tcl)i(Home)f(P)-7 b(a)o(g)o(e)0 3779 y Fy(\()p FO(http://tcl.activ)n(estate)o(.com/)i Fy(\))208 3879 y FN(The)19 b(Tk/Tcl)h(de)n(v)o(elopment)d(is)22 b(lar)o(gely)c(taking)i(place)g(at)g(Acti)n(v)o(eState.)0 4026 y FK(Tcl)h(and)e(the)h(Tk)h(T)-8 b(oolkit)0 4125 y Fy(\()p FO(http://www)l(.amaz)o(on.com/e)n(x)n(ec/ob)o(ido)o(s/ASIN/) o(020)o(16)o(33)o(37)o(X)i Fy(\))208 4225 y FN(The)19 b(book)g(by)h(John)g(Ousterhout,)e(the)i(in)m(v)o(entor)e(of)i(Tcl)g(.) 0 4372 y FK(Pr)o(actical)g(Pr)l(o)o(gr)o(amming)e(in)j(Tcl)f(and)g(Tk)0 4471 y Fy(\()p FO(http://www)l(.amaz)o(on.com/e)n(x)n(ec/ob)o(ido)o (s/ASIN/)o(013)o(02)o(20)o(28)o(0)-6 b Fy(\))208 4571 y FN(Brent)20 b(W)-7 b(elch')i(s)21 b(enc)o(yclopedic)c(book.)p 0 5549 3901 4 v 0 5649 a FI(20.1.)52 b FJ(Tkinter)22 b FI(\227)h(Python)h(interf)n(ace)f(to)g(Tcl/Tk)2108 b(715)p eop end %%Page: 716 728 TeXDict begin 716 727 bop 0 83 a FI(A)23 b(Simple)i(Hello)f(W)n(or)q (ld)g(Prog)o(r)o(am)0 377 y FA(from)44 b(Tkinter)g(import)897 390 y(*)0 560 y(class)g(Application\(Frame\):)179 651 y(def)h(say_hi\(self\):)359 743 y(print)f("hi)g(there,)g(everyone!")179 925 y(def)h(createWidgets\(self\):)359 1017 y(self.QUIT)e(=)i (Button\(self\))359 1108 y(self.QUIT["text"])d(=)i("QUIT")359 1199 y(self.QUIT["fg"])132 b(=)44 b("red")359 1290 y (self.QUIT["command"])d(=)90 b(self.quit)359 1473 y (self.QUIT.pack\({"side":)41 b("left"}\))359 1656 y(self.hi_there)h(=)j (Button\(self\))359 1747 y(self.hi_there["text"])c(=)k("Hello",)359 1838 y(self.hi_there["command"])40 b(=)45 b(self.say_hi)359 2021 y(self.hi_there.pack\({"side":)40 b("left"}\))179 2204 y(def)45 b(__init__\(self,)d(master=None\):)359 2295 y(Frame.__init__\(self,)f(master\))359 2386 y(self.pack\(\))359 2478 y(self.createWidgets\(\))0 2660 y(root)j(=)h(Tk\(\))0 2752 y(app)f(=)h(Application\(master=root\))0 2843 y(app.mainloop\(\))0 2934 y(root.destroy\(\))0 3355 y Fv(20.1.3)101 b(A)28 b(\(V)-8 b(er)s(y\))29 b(Quic)n(k)e(Look)i(at)e(Tcl/Tk)0 3558 y FN(The)i(class)h(hierarchy)e(looks)g(complicated,)i(b)n(ut)g(in) f(actual)h(practice,)g(application)e(programmers)f(almost)i(al)o(w)o (ays)h(refer)f(to)h(the)0 3658 y(classes)21 b(at)g(the)f(v)o(ery)f (bottom)g(of)h(the)g(hierarchy)-5 b(.)0 3804 y(Notes:)125 3999 y FM(\017)41 b FN(These)22 b(classes)i(are)f(pro)o(vided)d(for)j (the)g(purposes)e(of)i(or)o(ganizing)d(certain)i(functions)f(under)h (one)g(namespace.)32 b(The)o(y)22 b(aren')o(t)208 4099 y(meant)d(to)i(be)f(instantiated)f(independently)-5 b(.)125 4256 y FM(\017)41 b FN(The)19 b FJ(Tk)i FN(class)g(is)g(meant)f(to)g (be)g(instantiated)g(only)f(once)h(in)g(an)g(application.)j (Application)c(programmers)f(need)h(not)h(instan-)208 4356 y(tiate)g(one)g(e)o(xplicitly)-5 b(,)18 b(the)j(system)f(creates)g (one)g(whene)n(v)o(er)e(an)o(y)h(of)h(the)h(other)e(classes)i(are)f (instantiated.)125 4513 y FM(\017)41 b FN(The)23 b FJ(Widget)h FN(class)h(is)g(not)e(meant)h(to)g(be)g(instantiated,)g(it)h(is)g (meant)e(only)h(for)f(subclassing)g(to)i(mak)o(e)e(\223real\224)h (widgets)g(\(in)208 4612 y(C)263 4605 y(++)357 4612 y(,)c(this)h(is)g (called)f(an)g(`abstract)g(class'\).)0 4807 y(T)-7 b(o)25 b(mak)o(e)g(use)g(of)g(this)g(reference)f(material,)h(there)g(will)h (be)f(times)g(when)f(you)h(will)g(need)g(to)g(kno)n(w)f(ho)n(w)g(to)h (read)g(short)g(passages)0 4907 y(of)g(Tk)f(and)h(ho)n(w)f(to)h (identify)f(the)g(v)n(arious)g(parts)h(of)g(a)g(Tk)g(command.)37 b(\(See)25 b(section)f(20.1.4)f(for)h(the)h FJ(Tkinter)f FN(equi)n(v)n(alents)g(of)0 5007 y(what')-5 b(s)21 b(belo)n(w)-5 b(.\))0 5154 y(Tk)18 b(scripts)g(are)g(Tcl)g(programs.)23 b(Lik)o(e)18 b(all)g(Tcl)h(programs,)d(Tk)i(scripts)g(are)g(just)h (lists)g(of)f(tok)o(ens)f(separated)h(by)f(spaces.)25 b(A)18 b(Tk)g(widget)0 5253 y(is)j(just)g(its)g FK(class)p FN(,)g(the)f FK(options)f FN(that)h(help)g(con\002gure)e(it,)j(and)f (the)g FK(actions)g FN(that)g(mak)o(e)g(it)g(do)g(useful)g(things.)0 5400 y(T)-7 b(o)20 b(mak)o(e)g(a)h(widget)e(in)i(Tk,)f(the)g(command)e (is)j(al)o(w)o(ays)g(of)f(the)g(form:)p 0 5549 3901 4 v 0 5649 a FI(716)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 717 729 TeXDict begin 717 728 bop 954 174 a FA(classCommand)42 b(newPathname)h(options)0 545 y Fo(classCommand)e FN(denotes)20 b(which)f(kind)h(of)g(widget)f(to)i(mak)o(e)e(\(a)i(b)n(utton,)e(a)h (label,)g(a)h(menu...\))0 711 y Fo(newP)m(athname)40 b FN(is)22 b(the)f(ne)n(w)g(name)f(for)g(this)h(widget.)27 b(All)21 b(names)g(in)g(Tk)g(must)g(be)f(unique.)26 b(T)-7 b(o)21 b(help)f(enforce)g(this,)h(widgets)g(in)g(Tk)208 811 y(are)j(named)f(with)i FK(pathnames)p FN(,)f(just)h(lik)o(e)g (\002les)g(in)g(a)g(\002le)g(system.)38 b(The)25 b(top)f(le)n(v)o(el)g (widget,)h(the)f FK(r)l(oot)p FN(,)i(is)g(called)e FJ(.)39 b FN(\(period\))208 910 y(and)23 b(children)g(are)h(delimited)f(by)h (more)f(periods.)36 b(F)o(or)23 b(e)o(xample,)h FJ (.myApp.controlPanel.okButton)19 b FN(might)24 b(be)208 1010 y(the)c(name)f(of)h(a)h(widget.)0 1176 y Fo(options)41 b FN(con\002gure)20 b(the)i(widget')-5 b(s)22 b(appearance)f(and)g(in)i (some)f(cases,)h(its)g(beha)n(vior)-5 b(.)30 b(The)22 b(options)f(come)h(in)g(the)h(form)e(of)h(a)h(list)g(of)208 1276 y(\003ags)i(and)g(v)n(alues.)39 b(Flags)26 b(are)f(preceded)e(by)i (a)g(`-',)h(lik)o(e)h(U)t FH(N)t(I)t(X)h FN(shell)e(command)d(\003ags,) j(and)f(v)n(alues)g(are)g(put)g(in)g(quotes)f(if)208 1375 y(the)o(y)19 b(are)h(more)g(than)f(one)h(w)o(ord.)0 1605 y(F)o(or)g(e)o(xample:)416 1843 y FA(button)133 b(.fred)h(-fg)44 b(red)g(-text)g("hi)h(there")550 1935 y(\210)314 b(\210)224 b(\\_____________________/)550 2026 y(|)314 b(|)717 b(|)460 2117 y(class)179 b(new)537 b(options)416 2209 y(command)88 b(widget)h(\(-opt)44 b(val)g(-opt)g(val)g(...\))0 2495 y FN(Once)21 b(created,)g(the)h (pathname)e(to)h(the)h(widget)f(becomes)g(a)h(ne)n(w)f(command.)27 b(This)22 b(ne)n(w)f FK(widg)o(et)h(command)g FN(is)h(the)e (programmer')-5 b(s)0 2595 y(handle)16 b(for)h(getting)f(the)h(ne)n(w)h (widget)e(to)i(perform)d(some)i FK(action)p FN(.)23 b(In)17 b(C,)h(you')l(d)d(e)o(xpress)i(this)h(as)g(someAction\(fred,)c (someOptions\),)0 2695 y(in)20 b(C)140 2688 y(++)234 2695 y(,)h(you)e(w)o(ould)h(e)o(xpress)f(this)i(as)g (fred.someAction\(someOptions\),)14 b(and)20 b(in)g(Tk,)g(you)f(say:) 416 2933 y FA(.fred)44 b(someAction)f(someOptions)0 3219 y FN(Note)20 b(that)g(the)h(object)e(name,)h FJ(.fred)p FN(,)f(starts)i(with)g(a)f(dot.)0 3366 y(As)i(you')l(d)d(e)o(xpect,)h (the)h(le)o(gal)f(v)n(alues)h(for)f FK(someAction)g FN(will)i(depend)e (on)g(the)h(widget')-5 b(s)21 b(class:)28 b FJ(.fred)49 b(disable)20 b FN(w)o(orks)h(if)g(fred)0 3466 y(is)g(a)g(b)n(utton)e (\(fred)g(gets)i(gre)o(yed)d(out\),)h(b)n(ut)h(does)g(not)g(w)o(ork)g (if)g(fred)g(is)h(a)f(label)h(\(disabling)d(of)i(labels)h(is)g(not)f (supported)e(in)i(Tk\).)0 3613 y(The)e(le)o(gal)g(v)n(alues)f(of)h FK(someOptions)g FN(is)h(action)f(dependent.)k(Some)c(actions,)g(lik)o (e)h FJ(disable)p FN(,)e(require)g(no)h(ar)o(guments,)e(others,)i(lik)o (e)0 3712 y(a)j(te)o(xt-entry)d(box')-5 b(s)20 b FJ(delete)f FN(command,)f(w)o(ould)i(need)f(ar)o(guments)f(to)j(specify)e(what)h (range)f(of)h(te)o(xt)g(to)h(delete.)0 3997 y Fv(20.1.4)101 b(Mapping)29 b(Basic)g(Tk)e(into)h(Tkinter)0 4200 y FN(Class)22 b(commands)c(in)i(Tk)g(correspond)e(to)i(class)i(constructors)c(in)j (Tkinter)-5 b(.)416 4438 y FA(button)43 b(.fred)717 b(=====>)88 b(fred)45 b(=)f(Button\(\))0 4725 y FN(The)28 b(master)h(of)f(an)g (object)g(is)i(implicit)e(in)h(the)f(ne)n(w)h(name)f(gi)n(v)o(en)f(to)i (it)g(at)g(creation)e(time.)50 b(In)29 b(Tkinter)m(,)g(masters)f(are)h (speci\002ed)0 4825 y(e)o(xplicitly)-5 b(.)416 5063 y FA(button)43 b(.panel.fred)447 b(=====>)88 b(fred)45 b(=)f(Button\(panel\))0 5349 y FN(The)17 b(con\002guration)d(options)i (in)h(Tk)g(are)g(gi)n(v)o(en)f(in)h(lists)h(of)f(hyphened)d(tags)j (follo)n(wed)f(by)h(v)n(alues.)23 b(In)17 b(Tkinter)m(,)f(options)g (are)h(speci\002ed)p 0 5549 3901 4 v 0 5649 a FI(20.1.)52 b FJ(Tkinter)22 b FI(\227)h(Python)h(interf)n(ace)f(to)g(Tcl/Tk)2108 b(717)p eop end %%Page: 718 730 TeXDict begin 718 729 bop 0 83 a FN(as)32 b(k)o(e)o(yw)o(ord-ar)o (guments)26 b(in)31 b(the)g(instance)f(constructor)m(,)h(and)f(k)o(e)o (yw)o(ord-ar)o(gs)e(for)i(con\002gure)f(calls)j(or)e(as)i(instance)e (indices,)j(in)0 183 y(dictionary)18 b(style,)j(for)e(established)h (instances.)25 b(See)20 b(section)g(20.1.6)f(on)h(setting)g(options.) 416 421 y FA(button)43 b(.fred)h(-fg)h(red)358 b(=====>)88 b(fred)45 b(=)f(Button\(panel,)f(fg)h(=)h("red"\))416 512 y(.fred)f(configure)f(-fg)h(red)224 b(=====>)88 b(fred["fg"])44 b(=)g(red)1671 603 y(OR)g(==>)89 b(fred.config\(fg)43 b(=)i("red"\))0 890 y FN(In)29 b(Tk,)h(to)f(perform)e(an)i(action)g(on) f(a)i(widget,)g(use)f(the)g(widget)g(name)f(as)i(a)f(command,)g(and)f (follo)n(w)g(it)i(with)f(an)g(action)f(name,)0 990 y(possibly)20 b(with)h(ar)o(guments)d(\(options\).)24 b(In)c(Tkinter)m(,)f(you)h (call)h(methods)e(on)h(the)h(class)g(instance)g(to)f(in)m(v)n(ok)o(e)f (actions)i(on)f(the)g(widget.)0 1089 y(The)g(actions)g(\(methods\))e (that)i(a)h(gi)n(v)o(en)e(widget)h(can)g(perform)e(are)i(listed)h(in)f (the)g(Tkinter)-5 b(.p)o(y)19 b(module.)416 1327 y FA(.fred)44 b(invoke)716 b(=====>)88 b(fred.invoke\(\))0 1614 y FN(T)-7 b(o)21 b(gi)n(v)o(e)f(a)h(widget)f(to)h(the)g(pack)o(er)e(\(geometry)g (manager\),)f(you)i(call)h(pack)f(with)h(optional)f(ar)o(guments.)k(In) c(Tkinter)m(,)g(the)g(P)o(ack)h(class)0 1714 y(holds)h(all)i(this)f (functionality)-5 b(,)20 b(and)j(the)f(v)n(arious)g(forms)g(of)g(the)h (pack)f(command)f(are)i(implemented)d(as)k(methods.)31 b(All)24 b(widgets)e(in)0 1813 y FJ(Tkinter)17 b FN(are)h(subclassed)f (from)g(the)g(P)o(ack)o(er)m(,)g(and)g(so)i(inherit)e(all)h(the)g (packing)e(methods.)23 b(See)18 b(the)g FJ(Tix)f FN(module)g (documentation)0 1913 y(for)j(additional)e(information)g(on)i(the)g(F)o (orm)g(geometry)e(manager)-5 b(.)416 2151 y FA(pack)44 b(.fred)g(-side)g(left)313 b(=====>)88 b(fred.pack\(side)43 b(=)i("left"\))0 2574 y Fv(20.1.5)101 b(Ho)o(w)27 b(Tk)g(and)i(Tkinter) f(are)h(Related)0 2777 y FL(Note:)f FN(This)22 b(w)o(as)h(deri)n(v)o (ed)e(from)g(a)h(graphical)f(image;)h(the)g(image)g(will)h(be)f(used)g (more)f(directly)g(in)h(a)h(subsequent)d(v)o(ersion)h(of)h(this)0 2877 y(document.)0 3024 y(From)e(the)g(top)g(do)n(wn:)0 3237 y FL(Y)-9 b(our)20 b(A)n(pp)h(Her)o(e)e(\(Python\))421 3316 y(\257)912 3237 y FN(A)i(Python)e(application)f(mak)o(es)i(a)h FJ(Tkinter)e FN(call.)0 3403 y FL(Tkinter)i(\(Python)e(Module\))434 3482 y(\257)936 3403 y FN(This)h(call)h(\(say)-5 b(,)19 b(for)g(e)o(xample,)f(creating)h(a)h(b)n(utton)f(widget\),)g(is)i (implemented)d(in)i(the)g FK(Tkinter)g FN(mod-)208 3503 y(ule,)i(which)g(is)i(written)e(in)g(Python.)31 b(This)22 b(Python)g(function)e(will)k(parse)e(the)g(commands)f(and)h(the)g(ar)o (guments)f(and)h(con)m(v)o(ert)208 3602 y(them)d(into)h(a)h(form)e (that)h(mak)o(es)g(them)g(look)g(as)g(if)h(the)o(y)e(had)h(come)g(from) f(a)h(Tk)g(script)h(instead)f(of)f(a)i(Python)e(script.)0 3768 y FL(tkinter)h(\(C\))176 3844 y(\257)422 3768 y FN(These)i(commands)e(and)i(their)f(ar)o(guments)f(will)j(be)f(passed)g (to)g(a)g(C)h(function)e(in)h(the)g FK(tkinter)g FN(-)g(note)g(the)g (lo)n(wercase)f(-)208 3868 y(e)o(xtension)d(module.)0 4034 y FL(Tk)j(W)o(idgets)192 4113 y(\257)432 4034 y(\(C)f(and)h(Tcl\)) 42 b FN(This)23 b(C)i(function)d(is)j(able)f(to)f(mak)o(e)h(calls)g (into)g(other)f(C)h(modules,)g(including)e(the)h(C)i(functions)d(that) 208 4134 y(mak)o(e)g(up)h(the)g(Tk)f(library)-5 b(.)32 b(Tk)23 b(is)h(implemented)d(in)i(C)h(and)e(some)h(Tcl.)34 b(The)22 b(Tcl)i(part)e(of)h(the)g(Tk)g(widgets)g(is)h(used)e(to)h (bind)208 4233 y(certain)g(def)o(ault)h(beha)n(viors)f(to)h(widgets,)h (and)f(is)h(e)o(x)o(ecuted)d(once)i(at)h(the)f(point)f(where)h(the)g (Python)f FJ(Tkinter)h FN(module)f(is)208 4333 y(imported.)g(\(The)c (user)h(ne)n(v)o(er)f(sees)i(this)g(stage\).)0 4499 y FL(Tk)g(\(C\))105 4575 y(\257)279 4499 y FN(The)f(Tk)g(part)g(of)g(the) g(Tk)g(W)m(idgets)g(implement)f(the)h(\002nal)g(mapping)f(to)h(...)0 4665 y FL(Xlib)h(\(C\))130 4741 y(\257)330 4665 y FN(the)f(Xlib)g (library)f(to)i(dra)o(w)e(graphics)g(on)h(the)g(screen.)0 4950 y Fv(20.1.6)101 b(Handy)28 b(Ref)m(erence)0 5153 y FI(Setting)d(Options)0 5356 y FN(Options)20 b(control)f(things)g(lik) o(e)i(the)f(color)f(and)h(border)e(width)i(of)g(a)h(widget.)j(Options)c (can)g(be)g(set)h(in)g(three)e(w)o(ays:)p 0 5549 3901 4 v 0 5649 a FI(718)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 719 731 TeXDict begin 719 730 bop 0 83 a FL(At)20 b(object)g(cr)o(eation)f (time,)h(using)h(k)o(eyw)o(ord)f(ar)o(guments)41 b FN(:)444 305 y FA(fred)j(=)h(Button\(self,)d(fg)j(=)g("red",)e(bg)i(=)g ("blue"\))0 607 y FL(After)20 b(object)f(cr)o(eation,)g(tr)o(eating)f (the)j(option)e(name)i(lik)o(e)g(a)f(dictionary)f(index)42 b FN(:)444 828 y FA(fred["fg"])h(=)i("red")444 920 y(fred["bg"])e(=)i ("blue")0 1221 y FL(Use)21 b(the)f(con\002g\(\))g(method)g(to)g(update) g(multiple)h(attrs)f(subsequent)h(to)f(object)f(cr)o(eation)40 b FN(:)444 1443 y FA(fred.config\(fg)i(=)j("red",)f(bg)g(=)h("blue"\))0 1801 y FN(F)o(or)20 b(a)g(complete)g(e)o(xplanation)d(of)j(a)h(gi)n(v)o (en)e(option)g(and)g(its)j(beha)n(vior)m(,)c(see)i(the)h(Tk)f(man)f (pages)h(for)g(the)g(widget)g(in)g(question.)0 1948 y(Note)j(that)g (the)g(man)f(pages)h(list)h(\224ST)-8 b(AND)m(ARD)23 b(OPTIONS\224)g(and)f(\224WIDGET)h(SPECIFIC)h(OPTIONS\224)e(for)h(each) f(widget.)33 b(The)0 2048 y(former)25 b(is)h(a)h(list)g(of)f(options)f (that)h(are)g(common)e(to)i(man)o(y)f(widgets,)i(the)f(latter)h(are)f (the)g(options)f(that)h(are)g(idiosyncratic)e(to)i(that)0 2147 y(particular)19 b(widget.)24 b(The)c(Standard)f(Options)h(are)g (documented)d(on)j(the)g FK(options)p FN(\(3\))f(man)g(page.)0 2294 y(No)k(distinction)g(between)f(standard)h(and)f(widget-speci\002c) h(options)f(is)i(made)f(in)h(this)f(document.)33 b(Some)23 b(options)f(don')o(t)g(apply)g(to)0 2394 y(some)j(kinds)f(of)h (widgets.)40 b(Whether)24 b(a)i(gi)n(v)o(en)e(widget)g(responds)g(to)h (a)h(particular)e(option)f(depends)h(on)h(the)g(class)h(of)f(the)g (widget;)0 2494 y(b)n(uttons)20 b(ha)n(v)o(e)f(a)i FJ(command)e FN(option,)g(labels)h(do)g(not.)0 2640 y(The)h(options)f(supported)g (by)h(a)h(gi)n(v)o(en)e(widget)h(are)g(listed)h(in)f(that)h(widget')-5 b(s)21 b(man)g(page,)g(or)g(can)g(be)g(queried)f(at)i(runtime)e(by)h (calling)0 2740 y(the)26 b FJ(config\(\))g FN(method)f(without)g(ar)o (guments,)h(or)g(by)g(calling)g(the)g FJ(keys\(\))g FN(method)f(on)h (that)g(widget.)43 b(The)26 b(return)f(v)n(alue)h(of)0 2840 y(these)19 b(calls)h(is)g(a)f(dictionary)e(whose)i(k)o(e)o(y)f(is) i(the)f(name)g(of)f(the)h(option)f(as)i(a)f(string)g(\(for)f(e)o (xample,)f FJ('relief')p FN(\))h(and)g(whose)h(v)n(alues)0 2939 y(are)h(5-tuples.)0 3086 y(Some)32 b(options,)i(lik)o(e)e FJ(bg)g FN(are)g(synon)o(yms)e(for)i(common)e(options)h(with)h(long)g (names)f(\()p FJ(bg)h FN(is)h(shorthand)d(for)i(\224background\224\).)0 3186 y(P)o(assing)21 b(the)h FJ(config\(\))e FN(method)g(the)i(name)f (of)g(a)h(shorthand)d(option)h(will)j(return)d(a)i(2-tuple,)e(not)h (5-tuple.)27 b(The)21 b(2-tuple)g(passed)0 3285 y(back)f(will)g (contain)g(the)g(name)f(of)h(the)h(synon)o(ym)c(and)j(the)g (\223real\224)g(option)f(\(such)h(as)h FJ(\('bg',)48 b('background'\))p FN(\).)1005 3500 y FL(Index)p 1257 3530 4 100 v 100 w(Meaning)p 2445 3530 V 874 w(Example)p 956 3533 1989 4 v 1086 3603 a FN(0)p 1257 3633 4 100 v 180 w(option)19 b(name)p 2445 3633 V 774 w FJ('relief')1086 3703 y FN(1)p 1257 3733 V 180 w(option)g(name)h(for)f(database)h (lookup)p 2445 3733 V 97 w FJ('relief')1086 3802 y FN(2)p 1257 3832 V 180 w(option)f(class)i(for)f(database)f(lookup)p 2445 3832 V 116 w FJ('Relief')1086 3902 y FN(3)p 1257 3932 V 180 w(def)o(ault)h(v)n(alue)p 2445 3932 V 758 w FJ('raised')1086 4002 y FN(4)p 1257 4032 V 180 w(current)f(v)n(alue)p 2445 4032 V 753 w FJ('groove')0 4215 y FN(Example:)236 4453 y FA(>>>)45 b(print)f(fred.config\(\))236 4545 y({'relief')g(:)g (\('relief',)f('relief',)h('Relief',)f('raised',)g('groove'\)})0 4831 y FN(Of)30 b(course,)h(the)e(dictionary)f(printed)g(will)j (include)d(all)j(the)e(options)g(a)n(v)n(ailable)g(and)g(their)g(v)n (alues.)53 b(This)30 b(is)g(meant)g(only)e(as)j(an)0 4931 y(e)o(xample.)0 5197 y FI(The)23 b(P)m(ac)n(k)n(er)0 5400 y FN(The)d(pack)o(er)f(is)i(one)f(of)g(Tk')-5 b(s)20 b(geometry-management)15 b(mechanisms.)p 0 5549 3901 4 v 0 5649 a FI(20.1.)52 b FJ(Tkinter)22 b FI(\227)h(Python)h(interf)n (ace)f(to)g(Tcl/Tk)2108 b(719)p eop end %%Page: 720 732 TeXDict begin 720 731 bop 0 83 a FN(Geometry)21 b(managers)h(are)h (used)f(to)h(specify)g(the)g(relati)n(v)o(e)f(positioning)f(of)h(the)h (positioning)e(of)i(widgets)g(within)f(their)h(container)e(-)0 183 y(their)h(mutual)g FK(master)p FN(.)31 b(In)22 b(contrast)g(to)h (the)f(more)g(cumbersome)e FK(placer)i FN(\(which)f(is)i(used)f(less)i (commonly)-5 b(,)20 b(and)i(we)g(do)g(not)g(co)o(v)o(er)0 282 y(here\),)i(the)f(pack)o(er)g(tak)o(es)h(qualitati)n(v)o(e)f (relationship)f(speci\002cation)h(-)h FK(abo)o(ve)p FN(,)g FK(to)g(the)g(left)g(of)p FN(,)h FK(\002lling)p FN(,)e(etc)i(-)f(and)f (w)o(orks)g(e)n(v)o(erything)0 382 y(out)d(to)g(determine)f(the)h(e)o (xact)g(placement)f(coordinates)f(for)i(you.)0 529 y(The)j(size)h(of)f (an)o(y)g FK(master)h FN(widget)e(is)j(determined)c(by)i(the)g(size)h (of)f(the)h(\224sla)n(v)o(e)f(widgets\224)g(inside.)35 b(The)23 b(pack)o(er)f(is)i(used)f(to)h(control)0 628 y(where)15 b(sla)n(v)o(e)h(widgets)f(appear)f(inside)h(the)h(master)f (into)g(which)g(the)o(y)g(are)g(pack)o(ed.)22 b(Y)-9 b(ou)15 b(can)g(pack)g(widgets)g(into)h(frames,)f(and)g(frames)0 728 y(into)28 b(other)f(frames,)i(in)g(order)e(to)h(achie)n(v)o(e)f (the)h(kind)f(of)h(layout)f(you)g(desire.)49 b(Additionally)-5 b(,)28 b(the)g(arrangement)d(is)30 b(dynamically)0 828 y(adjusted)19 b(to)i(accommodate)d(incremental)g(changes)i(to)g(the)g (con\002guration,)d(once)j(it)h(is)g(pack)o(ed.)0 975 y(Note)e(that)h(widgets)f(do)g(not)g(appear)f(until)h(the)o(y)g(ha)n(v) o(e)f(had)h(their)g(geometry)f(speci\002ed)h(with)g(a)h(geometry)d (manager)-5 b(.)24 b(It')-5 b(s)20 b(a)f(common)0 1074 y(early)25 b(mistak)o(e)h(to)f(lea)n(v)o(e)h(out)f(the)h(geometry)d (speci\002cation,)j(and)f(then)h(be)f(surprised)g(when)g(the)g(widget)g (is)i(created)e(b)n(ut)g(nothing)0 1174 y(appears.)f(A)d(widget)e(will) i(appear)e(only)h(after)g(it)h(has)f(had,)f(for)h(e)o(xample,)e(the)j (pack)o(er')-5 b(s)19 b FJ(pack\(\))h FN(method)f(applied)g(to)h(it.)0 1321 y(The)f(pack\(\))f(method)g(can)h(be)g(called)h(with)f(k)o(e)o(yw) o(ord-option/v)n(alue)14 b(pairs)20 b(that)f(control)f(where)h(the)g (widget)g(is)i(to)e(appear)f(within)i(its)0 1420 y(container)m(,)e(and) i(ho)n(w)f(it)i(is)g(to)g(beha)n(v)o(e)e(when)g(the)i(main)e (application)g(windo)n(w)g(is)i(resized.)k(Here)20 b(are)g(some)g(e)o (xamples:)416 1658 y FA(fred.pack\(\))939 b(#)45 b(defaults)e(to)i (side)f(=)h("top")416 1750 y(fred.pack\(side)d(=)j("left"\))416 1841 y(fred.pack\(expand)d(=)i(1\))0 2254 y FI(P)m(ac)n(k)n(er)23 b(Options)0 2457 y FN(F)o(or)c(more)f(e)o(xtensi)n(v)o(e)g(information) e(on)j(the)g(pack)o(er)f(and)h(the)g(options)f(that)h(it)h(can)f(tak)o (e,)g(see)h(the)f(man)g(pages)f(and)h(page)f(183)g(of)h(John)0 2556 y(Ousterhout')-5 b(s)19 b(book.)0 2786 y FL(anchor)121 2849 y(\257)311 2786 y FN(Anchor)g(type.)25 b(Denotes)19 b(where)h(the)g(pack)o(er)f(is)i(to)g(place)f(each)g(sla)n(v)o(e)g(in)g (its)i(parcel.)0 2952 y FL(expand)115 3031 y(\257)300 2952 y FN(Boolean,)d FJ(0)i FN(or)f FJ(1)p FN(.)0 3118 y FL(\002ll)32 3180 y(\257)134 3118 y FN(Le)o(gal)f(v)n(alues:)25 b FJ('x')p FN(,)20 b FJ('y')p FN(,)g FJ('both')p FN(,)f FJ('none')p FN(.)0 3284 y FL(ipadx)85 3363 y(\257)219 3284 y(and)i(ipady)459 3363 y(\257)614 3284 y FN(A)f(distance)g(-)h (designating)d(internal)i(padding)e(on)i(each)f(side)i(of)f(the)g(sla)n (v)o(e)h(widget.)0 3450 y FL(padx)74 3529 y(\257)196 3450 y(and)g(pady)425 3529 y(\257)568 3450 y FN(A)f(distance)g(-)g (designating)f(e)o(xternal)g(padding)f(on)i(each)g(side)g(of)g(the)g (sla)n(v)o(e)h(widget.)0 3616 y FL(side)55 3680 y(\257)180 3616 y FN(Le)o(gal)e(v)n(alues)h(are:)25 b FJ('left')p FN(,)19 b FJ('right')p FN(,)h FJ('top')p FN(,)f FJ('bottom')p FN(.)0 3885 y FI(Coupling)25 b(Widget)f(V)-6 b(ar)q(iab)n(les)0 4087 y FN(The)22 b(current-v)n(alue)d(setting)j(of)f(some)h(widgets)g (\(lik)o(e)g(te)o(xt)f(entry)h(widgets\))f(can)h(be)g(connected)e (directly)h(to)h(application)e(v)n(ariables)0 4187 y(by)28 b(using)g(special)h(options.)49 b(These)29 b(options)f(are)g FJ(variable)p FN(,)i FJ(textvariable)p FN(,)f FJ(onvalue)p FN(,)g FJ(offvalue)p FN(,)h(and)e FJ(value)p FN(.)0 4287 y(This)21 b(connection)d(w)o(orks)i(both)g(w)o(ays:)27 b(if)20 b(the)h(v)n(ariable)e(changes)h(for)g(an)o(y)g(reason,)f(the)i (widget)f(it')-5 b(s)22 b(connected)d(to)h(will)i(be)e(updated)0 4386 y(to)g(re\003ect)h(the)f(ne)n(w)g(v)n(alue.)0 4533 y(Unfortunately)-5 b(,)18 b(in)j(the)f(current)g(implementation)e(of)j FJ(Tkinter)f FN(it)h(is)h(not)f(possible)f(to)h(hand)f(o)o(v)o(er)f(an) i(arbitrary)e(Python)h(v)n(ariable)0 4633 y(to)j(a)g(widget)g(through)e (a)i FJ(variable)f FN(or)g FJ(textvariable)g FN(option.)31 b(The)23 b(only)f(kinds)g(of)h(v)n(ariables)f(for)g(which)h(this)g(w)o (orks)g(are)0 4732 y(v)n(ariables)c(that)i(are)f(subclassed)g(from)f(a) h(class)i(called)e(V)-9 b(ariable,)19 b(de\002ned)g(in)h(the)g FJ(Tkinter)g FN(module.)0 4879 y(There)47 b(are)h(man)o(y)f(useful)h (subclasses)g(of)g(V)-9 b(ariable)47 b(already)g(de\002ned:)80 b FJ(StringVar)p FN(,)54 b FJ(IntVar)p FN(,)g FJ(DoubleVar)p FN(,)g(and)0 4979 y FJ(BooleanVar)p FN(.)23 b(T)-7 b(o)20 b(read)f(the)g(current)f(v)n(alue)h(of)g(such)g(a)h(v)n(ariable,)e (call)i(the)f FJ(get\(\))g FN(method)f(on)h(it,)h(and)f(to)g(change)f (its)j(v)n(alue)d(you)0 5079 y(call)26 b(the)f FJ(set\(\))f FN(method.)38 b(If)25 b(you)g(follo)n(w)f(this)i(protocol,)e(the)h (widget)g(will)g(al)o(w)o(ays)h(track)e(the)i(v)n(alue)e(of)h(the)g(v)n (ariable,)g(with)g(no)0 5178 y(further)19 b(interv)o(ention)e(on)j (your)f(part.)0 5325 y(F)o(or)h(e)o(xample:)p 0 5549 3901 4 v 0 5649 a FI(720)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 721 733 TeXDict begin 721 732 bop 236 174 a FA(class)44 b(App\(Frame\):)416 266 y(def)g(__init__\(self,)e(master=None\):)595 357 y(Frame.__init__\(self,)f(master\))595 448 y(self.pack\(\))595 631 y(self.entrythingy)h(=)j(Entry\(\))595 722 y (self.entrythingy.pack\(\))595 905 y(#)g(here)f(is)g(the)h(application) e(variable)595 996 y(self.contents)g(=)h(StringVar\(\))595 1088 y(#)h(set)f(it)g(to)h(some)f(value)595 1179 y (self.contents.set\("this)d(is)j(a)h(variable"\))595 1270 y(#)g(tell)f(the)g(entry)g(widget)g(to)g(watch)g(this)g(variable) 595 1362 y(self.entrythingy["textvariable"])39 b(=)45 b(self.contents)595 1544 y(#)g(and)f(here)g(we)h(get)f(a)h(callback)e (when)h(the)g(user)h(hits)f(return.)595 1636 y(#)h(we)f(will)g(have)g (the)h(program)e(print)h(out)h(the)f(value)g(of)g(the)595 1727 y(#)h(application)e(variable)g(when)h(the)g(user)h(hits)f(return) 595 1818 y(self.entrythingy.bind\('<Key-Return>',)1581 1910 y(self.print_contents\))416 2092 y(def)g(print_contents\(self,)d (event\):)595 2183 y(print)j("hi.)g(contents)g(of)g(entry)g(is)g(now)h (---->",)e(\\)864 2275 y(self.contents.get\(\))0 2686 y FI(The)23 b(Windo)o(w)h(Manager)0 2889 y FN(In)g(Tk,)h(there)e(is)i (a)g(utility)f(command,)f FJ(wm)p FN(,)i(for)f(interacting)f(with)h (the)g(windo)n(w)f(manager)-5 b(.)36 b(Options)24 b(to)g(the)g FJ(wm)g FN(command)f(allo)n(w)0 2989 y(you)28 b(to)h(control)f(things)g (lik)o(e)i(titles,)h(placement,)f(icon)f(bitmaps,)h(and)e(the)h(lik)o (e.)52 b(In)28 b FJ(Tkinter)p FN(,)j(these)e(commands)e(ha)n(v)o(e)h (been)0 3088 y(implemented)21 b(as)i(methods)f(on)g(the)h FJ(Wm)g FN(class.)33 b(T)-7 b(ople)n(v)o(el)21 b(widgets)i(are)f (subclassed)h(from)e(the)i FJ(Wm)g FN(class,)h(and)e(so)h(can)g(call)g (the)f FJ(Wm)0 3188 y FN(methods)d(directly)-5 b(.)0 3335 y(T)e(o)22 b(get)g(at)g(the)g(tople)n(v)o(el)f(windo)n(w)g(that)h (contains)f(a)h(gi)n(v)o(en)f(widget,)g(you)g(can)h(often)f(just)h (refer)f(to)h(the)g(widget')-5 b(s)22 b(master)-5 b(.)30 b(Of)22 b(course)0 3434 y(if)h(the)f(widget)g(has)g(been)g(pack)o(ed)f (inside)h(of)g(a)g(frame,)g(the)g(master)h(w)o(on')o(t)e(represent)g(a) h(tople)n(v)o(el)f(windo)n(w)-5 b(.)30 b(T)-7 b(o)23 b(get)f(at)h(the)f(tople)n(v)o(el)0 3534 y(windo)n(w)c(that)h(contains) g(an)g(arbitrary)e(widget,)i(you)f(can)h(call)h(the)f FJ(_root\(\))f FN(method.)23 b(This)d(method)d(be)o(gins)h(with)i(an)f (underscore)0 3634 y(to)h(denote)f(the)i(f)o(act)f(that)g(this)h (function)d(is)k(part)d(of)h(the)h(implementation,)c(and)j(not)g(an)g (interf)o(ace)f(to)i(Tk)f(functionality)-5 b(.)0 3781 y(Here)20 b(are)g(some)g(e)o(xamples)f(of)h(typical)g(usage:)p 0 5549 3901 4 v 0 5649 a FI(20.1.)52 b FJ(Tkinter)22 b FI(\227)h(Python)h(interf)n(ace)f(to)g(Tcl/Tk)2108 b(721)p eop end %%Page: 722 734 TeXDict begin 722 733 bop 236 174 a FA(from)44 b(Tkinter)g(import)1133 187 y(*)236 266 y(class)g(App\(Frame\):)416 357 y(def)g (__init__\(self,)e(master=None\):)595 448 y(Frame.__init__\(self,)f (master\))595 540 y(self.pack\(\))236 814 y(#)k(create)f(the)g (application)236 905 y(myapp)g(=)h(App\(\))236 1088 y(#)236 1179 y(#)g(here)f(are)g(method)g(calls)g(to)h(the)f(window)g(manager)f (class)236 1270 y(#)236 1362 y(myapp.master.title\("My)e(Do-Nothing)j (Application"\))236 1453 y(myapp.master.maxsize\(1000,)d(400\))236 1636 y(#)k(start)f(the)g(program)236 1727 y(myapp.mainloop\(\))0 2139 y FI(Tk)22 b(Option)i(Data)f(T)-10 b(ypes)0 2342 y FL(anchor)41 b FN(Le)o(gal)33 b(v)n(alues)i(are)f(points)h(of)f(the)h (compass:)54 b FJ("n")p FN(,)38 b FJ("ne")p FN(,)g FJ("e")p FN(,)g FJ("se")p FN(,)g FJ("s")p FN(,)g FJ("sw")p FN(,)g FJ("w")p FN(,)g FJ("nw")p FN(,)g(and)c(also)208 2442 y FJ("center")p FN(.)0 2608 y FL(bitmap)41 b FN(There)25 b(are)g(eight)g(b)n(uilt-in,)h(named)e(bitmaps:)36 b FJ('error')p FN(,)25 b FJ('gray25')p FN(,)h FJ('gray50')p FN(,)f FJ('hourglass')p FN(,)g FJ('info')p FN(,)208 2708 y FJ('questhead')p FN(,)20 b FJ('question')p FN(,)g FJ('warning')p FN(.)29 b(T)-7 b(o)21 b(specify)g(an)h(X)g(bitmap)f(\002lename,)g(gi)n (v)o(e)g(the)h(full)f(path)h(to)f(the)h(\002le,)208 2807 y(preceded)c(with)i(an)g FJ(@)p FN(,)h(as)g(in)f FJ ("@/usr/contrib/bitmap/gumby.bit")p FN(.)0 2973 y FL(boolean)40 b FN(Y)-9 b(ou)20 b(can)g(pass)h(inte)o(gers)e(0)h(or)g(1)g(or)g(the)h (strings)f FJ("yes")g FN(or)f FJ("no")h FN(.)0 3139 y FL(callback)41 b FN(This)20 b(is)h(an)o(y)f(Python)f(function)f(that)i (tak)o(es)h(no)f(ar)o(guments.)j(F)o(or)c(e)o(xample:)623 3363 y FA(def)44 b(print_it\(\):)982 3455 y(print)g("hi)g(there")623 3546 y(fred["command"])e(=)j(print_it)0 3852 y FL(color)40 b FN(Colors)22 b(can)g(be)g(gi)n(v)o(en)e(as)j(the)e(names)h(of)f(X)i (colors)e(in)h(the)g(r)o(gb)m(.txt)e(\002le,)i(or)g(as)g(strings)g (representing)e(RGB)j(v)n(alues)e(in)h(4)g(bit:)208 3951 y FJ("#RGB")p FN(,)e(8)h(bit:)27 b FJ("#RRGGBB")p FN(,)20 b(12)g(bit\224)h FJ("#RRRGGGBBB")p FN(,)e(or)i(16)g(bit)g FJ("#RRRRGGGGBBBB")d FN(ranges,)i(where)h(R,G,B)208 4051 y(here)e(represent)g(an)o(y)h(le)o(gal)f(he)o(x)g(digit.)25 b(See)c(page)e(160)h(of)g(Ousterhout')-5 b(s)19 b(book)f(for)i (details.)0 4217 y FL(cursor)41 b FN(The)23 b(standard)g(X)h(cursor)e (names)i(from)e(`)p FO(cursorf)n(ont.h)p FN(')f(can)i(be)h(used,)f (without)g(the)h FJ(XC_)f FN(pre\002x.)35 b(F)o(or)23 b(e)o(xample)f(to)i(get)f(a)208 4317 y(hand)d(cursor)g(\()p FJ(XC_hand2)p FN(\),)g(use)i(the)f(string)h FJ("hand2")p FN(.)28 b(Y)-9 b(ou)20 b(can)i(also)f(specify)g(a)h(bitmap)f(and)g (mask)g(\002le)h(of)f(your)f(o)n(wn.)208 4416 y(See)g(page)g(179)f(of)h (Ousterhout')-5 b(s)19 b(book.)0 4582 y FL(distance)41 b FN(Screen)27 b(distances)g(can)h(be)f(speci\002ed)g(in)h(either)f (pix)o(els)g(or)g(absolute)g(distances.)47 b(Pix)o(els)27 b(are)h(gi)n(v)o(en)e(as)i(numbers)e(and)208 4682 y(absolute)e (distances)i(as)g(strings,)g(with)g(the)f(trailing)g(character)f (denoting)g(units:)35 b FJ(c)26 b FN(for)f(centimetres,)h FJ(i)f FN(for)g(inches,)h FJ(m)g FN(for)208 4782 y(millimetres,)19 b FJ(p)i FN(for)e(printer')-5 b(s)20 b(points.)k(F)o(or)c(e)o(xample,)f (3.5)g(inches)h(is)h(e)o(xpressed)e(as)i FJ("3.5i")p FN(.)0 4948 y FL(f)n(ont)40 b FN(Tk)16 b(uses)h(a)f(list)h(font)f(name) f(format,)h(such)g(as)g FJ({courier)49 b(10)g(bold})p FN(.)23 b(F)o(ont)16 b(sizes)h(with)f(positi)n(v)o(e)f(numbers)g(are)h (measured)208 5047 y(in)k(points;)g(sizes)h(with)f(ne)o(gati)n(v)o(e)e (numbers)h(are)h(measured)f(in)h(pix)o(els.)0 5213 y FL(geometry)39 b FN(This)18 b(is)h(a)f(string)f(of)h(the)g(form)e(`)p FK(width)p FJ(x)p FK(height)q FN(',)g(where)h(width)h(and)f(height)g (are)g(measured)g(in)h(pix)o(els)f(for)g(most)h(widgets)208 5313 y(\(in)i(characters)f(for)g(widgets)h(displaying)f(te)o(xt\).)25 b(F)o(or)19 b(e)o(xample:)24 b FJ(fred["geometry"])47 b(=)j("200x100")p FN(.)p 0 5549 3901 4 v 0 5649 a FI(722)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i (Tk)p eop end %%Page: 723 735 TeXDict begin 723 734 bop 0 83 a FL(justify)40 b FN(Le)o(gal)20 b(v)n(alues)f(are)i(the)f(strings:)25 b FJ("left")p FN(,)19 b FJ("center")p FN(,)g FJ("right")p FN(,)h(and)f FJ("fill")p FN(.)0 234 y FL(r)o(egion)40 b FN(This)18 b(is)g(a)g(string)g(with)f (four)g(space-delimited)f(elements,)h(each)h(of)f(which)g(is)i(a)f(le)o (gal)f(distance)g(\(see)h(abo)o(v)o(e\).)k(F)o(or)17 b(e)o(xample:)208 333 y FJ("2)49 b(3)h(4)f(5")21 b FN(and)e FJ("3i)50 b(2i)f(4.5i)g(2i")20 b FN(and)g FJ("3c)49 b(2c)h(4c)f (10.43c")19 b FN(are)i(all)f(le)o(gal)g(re)o(gions.)0 484 y FL(r)o(elief)40 b FN(Determines)25 b(what)g(the)h(border)d(style) j(of)f(a)h(widget)f(will)h(be.)40 b(Le)o(gal)24 b(v)n(alues)h(are:)36 b FJ("raised")p FN(,)25 b FJ("sunken")p FN(,)g FJ("flat")p FN(,)208 584 y FJ("groove")p FN(,)19 b(and)g FJ("ridge")p FN(.)0 734 y FL(scr)o(ollcommand)40 b FN(This)24 b(is)h(almost)e(al)o (w)o(ays)i(the)e FJ(set\(\))h FN(method)e(of)i(some)f(scrollbar)g (widget,)h(b)n(ut)g(can)f(be)h(an)o(y)f(widget)g(method)208 834 y(that)18 b(tak)o(es)i(a)f(single)g(ar)o(gument.)j(Refer)d(to)g (the)f(\002le)i(`)p FO(Demo/tkinter/matt/can)o(v)n(as-with-scroll)o(ba) o(rs)o(.p)m(y)p FN(')14 b(in)19 b(the)g(Python)e(source)208 934 y(distrib)n(ution)i(for)g(an)h(e)o(xample.)0 1084 y FL(wrap:)41 b FN(Must)20 b(be)g(one)g(of:)25 b FJ("none")p FN(,)19 b FJ("char")p FN(,)h(or)g FJ("word")p FN(.)0 1346 y FI(Bindings)k(and)g(Ev)n(ents)0 1549 y FN(The)h(bind)g(method)f (from)h(the)g(widget)g(command)f(allo)n(ws)i(you)f(to)g(w)o(atch)h(for) f(certain)g(e)n(v)o(ents)g(and)g(to)h(ha)n(v)o(e)f(a)h(callback)e (function)0 1648 y(trigger)19 b(when)h(that)g(e)n(v)o(ent)f(type)h (occurs.)k(The)c(form)f(of)h(the)g(bind)g(method)e(is:)416 1887 y FA(def)44 b(bind\(self,)f(sequence,)g(func,)h(add=''\):)0 2126 y FN(where:)0 2318 y FL(sequence)e FN(is)21 b(a)g(string)g(that)f (denotes)g(the)h(tar)o(get)f(kind)f(of)i(e)n(v)o(ent.)k(\(See)c(the)g (bind)e(man)i(page)f(and)g(page)g(201)f(of)i(John)f(Ousterhout')-5 b(s)208 2417 y(book)18 b(for)i(details\).)0 2568 y FL(func)41 b FN(is)29 b(a)g(Python)e(function,)h(taking)g(one)f(ar)o(gument,)h(to) g(be)h(in)m(v)n(ok)o(ed)d(when)i(the)g(e)n(v)o(ent)f(occurs.)48 b(An)29 b(Ev)o(ent)e(instance)h(will)h(be)208 2668 y(passed)20 b(as)h(the)f(ar)o(gument.)i(\(Functions)d(deplo)o(yed)g(this)h(w)o(ay)g (are)h(commonly)d(kno)n(wn)g(as)j FK(callbac)n(ks)p FN(.\))0 2818 y FL(add)41 b FN(is)20 b(optional,)e(either)h(`')g(or)f(`)p FJ(+)p FN('.)25 b(P)o(assing)19 b(an)g(empty)f(string)h(denotes)f(that) h(this)h(binding)d(is)j(to)f(replace)f(an)o(y)h(other)f(bindings)f (that)208 2918 y(this)h(e)n(v)o(ent)f(is)i(associated)f(with.)24 b(Preceeding)17 b(with)h(a)h(`)p FJ(+)p FN(')e(means)h(that)g(this)h (function)d(is)j(to)f(be)g(added)f(to)h(the)g(list)h(of)f(functions)208 3017 y(bound)g(to)i(this)h(e)n(v)o(ent)e(type.)0 3209 y(F)o(or)h(e)o(xample:)416 3447 y FA(def)44 b(turnRed\(self,)f (event\):)595 3539 y(event.widget["activeforeground"])c(=)45 b("red")416 3721 y(self.button.bind\("<Enter>",)40 b(self.turnRed\))0 4008 y FN(Notice)19 b(ho)n(w)f(the)h(widget)f(\002eld)h(of)g(the)g(e)n (v)o(ent)e(is)j(being)e(accessed)h(in)g(the)g FJ(turnRed\(\))e FN(callback.)24 b(This)19 b(\002eld)g(contains)f(the)h(widget)0 4107 y(that)24 b(caught)e(the)i(X)g(e)n(v)o(ent.)34 b(The)23 b(follo)n(wing)f(table)h(lists)i(the)e(other)g(e)n(v)o(ent)g(\002elds)h (you)e(can)i(access,)g(and)f(ho)n(w)g(the)o(y)g(are)g(denoted)f(in)0 4207 y(Tk,)e(which)f(can)h(be)h(useful)e(when)h(referring)e(to)i(the)g (Tk)g(man)g(pages.)236 4445 y FA(Tk)269 b(Tkinter)44 b(Event)g(Field)581 b(Tk)269 b(Tkinter)44 b(Event)g(Field)236 4537 y(--)269 b(-------------------)579 b(--)269 b(-------------------) 236 4628 y(\045f)g(focus)1209 b(\045A)269 b(char)236 4719 y(\045h)g(height)1164 b(\045E)269 b(send_event)236 4811 y(\045k)g(keycode)1119 b(\045K)269 b(keysym)236 4902 y(\045s)g(state)1209 b(\045N)269 b(keysym_num)236 4993 y(\045t)g(time)1254 b(\045T)269 b(type)236 5085 y(\045w)g(width)1209 b(\045W)269 b(widget)236 5176 y(\045x)g(x)1389 b(\045X)269 b(x_root)236 5267 y(\045y)g(y)1389 b(\045Y)269 b(y_root)p 0 5549 3901 4 v 0 5649 a FI(20.1.)52 b FJ(Tkinter)22 b FI(\227)h(Python)h(interf)n(ace)f(to)g(Tcl/Tk)2108 b(723)p eop end %%Page: 724 736 TeXDict begin 724 735 bop 0 83 a FI(The)23 b(inde)n(x)g(P)m(ar)o (ameter)0 286 y FN(A)k(number)e(of)h(widgets)g(require\223inde)o(x\224) d(parameters)j(to)g(be)h(passed.)43 b(These)27 b(are)f(used)g(to)h (point)f(at)h(a)f(speci\002c)h(place)f(in)h(a)g(T)-6 b(e)o(xt)0 386 y(widget,)19 b(or)h(to)h(particular)e(characters)g(in)h (an)g(Entry)g(widget,)f(or)h(to)g(particular)f(menu)g(items)i(in)f(a)h (Menu)f(widget.)0 615 y FL(Entry)g(widget)g(indexes)h(\(index,)f(view)g (index,)g(etc.\))785 695 y(\257)1640 615 y FN(Entry)28 b(widgets)i(ha)n(v)o(e)f(options)g(that)h(refer)f(to)h(character)e (positions)i(in)g(the)208 715 y(te)o(xt)20 b(being)f(displayed.)24 b(Y)-9 b(ou)19 b(can)h(use)h(these)f FJ(Tkinter)f FN(functions)g(to)h (access)h(these)g(special)f(points)g(in)g(te)o(xt)g(widgets:)208 898 y FL(AtEnd\(\))41 b FN(refers)19 b(to)i(the)f(last)h(position)e(in) i(the)f(te)o(xt)208 1031 y FL(AtInsert\(\))40 b FN(refers)20 b(to)g(the)g(point)g(where)f(the)i(te)o(xt)f(cursor)f(is)208 1163 y FL(AtSelFirst\(\))40 b FN(indicates)20 b(the)g(be)o(ginning)d (point)j(of)g(the)g(selected)g(te)o(xt)208 1296 y FL(AtSelLast\(\))40 b FN(denotes)19 b(the)h(last)i(point)d(of)h(the)g(selected)g(te)o(xt)g (and)g(\002nally)208 1429 y FL(At\(x)p FC([)p FL(,)f(y)12 b FC(])p FL(\))40 b FN(refers)19 b(to)g(the)g(character)f(at)i(pix)o (el)f(location)f FK(x)p FN(,)i FK(y)g FN(\(with)f FK(y)h FN(not)f(used)g(in)g(the)g(case)h(of)f(a)h(te)o(xt)f(entry)f(widget,)h (which)390 1529 y(contains)h(a)g(single)g(line)h(of)f(te)o(xt\).)0 1711 y FL(T)-8 b(ext)21 b(widget)e(indexes)333 1790 y(\257)735 1711 y FN(The)h(inde)o(x)f(notation)g(for)g(T)-6 b(e)o(xt)20 b(widgets)g(is)h(v)o(ery)e(rich)h(and)g(is)h(best)f(described)f(in)i (the)f(Tk)g(man)g(pages.)0 1877 y FL(Menu)h(indexes)g(\(menu.in)m(v)o (ok)o(e\(\),)e(menu.entrycon\002g\(\),)f(etc.\))963 1956 y(\257)1994 1877 y FN(Some)h(options)e(and)i(methods)e(for)h(menus)g (manipulate)f(speci\002c)208 1977 y(menu)i(entries.)25 b(An)o(ytime)19 b(a)h(menu)g(inde)o(x)f(is)i(needed)e(for)g(an)h (option)f(or)h(a)h(parameter)m(,)d(you)h(may)h(pass)h(in:)307 2143 y FM(\017)41 b FN(an)24 b(inte)o(ger)g(which)f(refers)h(to)g(the)h (numeric)e(position)g(of)h(the)g(entry)g(in)g(the)g(widget,)h(counted)e (from)g(the)h(top,)h(starting)390 2243 y(with)c(0;)307 2376 y FM(\017)41 b FN(the)20 b(string)g FJ('active')p FN(,)f(which)h(refers)g(to)g(the)g(menu)f(position)h(that)g(is)h (currently)e(under)f(the)j(cursor;)307 2508 y FM(\017)41 b FN(the)20 b(string)g FJ("last")g FN(which)g(refers)f(to)i(the)f(last) h(menu)e(item;)307 2641 y FM(\017)41 b FN(An)22 b(inte)o(ger)f (preceded)g(by)g FJ(@)p FN(,)i(as)g(in)f FJ(@6)p FN(,)h(where)e(the)h (inte)o(ger)f(is)i(interpreted)e(as)h(a)h(y)f(pix)o(el)g(coordinate)e (in)i(the)g(menu')-5 b(s)390 2741 y(coordinate)18 b(system;)307 2874 y FM(\017)41 b FN(the)16 b(string)f FJ("none")p FN(,)g(which)g(indicates)g(no)g(menu)f(entry)h(at)h(all,)g(most)g (often)e(used)h(with)h(menu.acti)n(v)n(ate\(\))c(to)k(deacti)n(v)n(ate) 390 2973 y(all)21 b(entries,)f(and)f(\002nally)-5 b(,)307 3106 y FM(\017)41 b FN(a)28 b(te)o(xt)f(string)f(that)h(is)h(pattern)f (matched)f(against)g(the)h(label)g(of)g(the)g(menu)f(entry)-5 b(,)27 b(as)h(scanned)e(from)g(the)h(top)g(of)g(the)390 3206 y(menu)20 b(to)g(the)h(bottom.)j(Note)d(that)f(this)h(inde)o(x)f (type)g(is)h(considered)e(after)h(all)h(the)g(others,)e(which)h(means)g (that)h(matches)390 3305 y(for)f(menu)f(items)i(labelled)e FJ(last)p FN(,)h FJ(active)p FN(,)f(or)h FJ(none)g FN(may)g(be)g (interpreted)f(as)h(the)h(abo)o(v)o(e)d(literals,)j(instead.)0 3574 y FI(Images)0 3777 y FN(Bitmap/Pix)o(elmap)e(images)h(can)g(be)g (created)f(through)f(the)i(subclasses)h(of)f FJ(Tkinter.Image)p FN(:)125 4006 y FM(\017)41 b FJ(BitmapImage)18 b FN(can)i(be)g(used)g (for)g(X11)g(bitmap)f(data.)125 4172 y FM(\017)41 b FJ(PhotoImage)18 b FN(can)i(be)h(used)e(for)h(GIF)h(and)e(PPM/PGM)i(color)e(bitmaps.)0 4402 y(Either)h(type)f(of)h(image)g(is)h(created)f(through)e(either)h (the)i FJ(file)f FN(or)f(the)i FJ(data)f FN(option)f(\(other)g(options) g(are)h(a)n(v)n(ailable)g(as)h(well\).)0 4549 y(The)28 b(image)f(object)h(can)g(then)f(be)h(used)g(where)n(v)o(er)e(an)i FJ(image)g FN(option)f(is)i(supported)d(by)i(some)g(widget)f(\(e.g.)48 b(labels,)30 b(b)n(uttons,)0 4649 y(menus\).)24 b(In)c(these)h(cases,)g (Tk)f(will)h(not)f(k)o(eep)g(a)h(reference)d(to)j(the)f(image.)25 b(When)20 b(the)g(last)i(Python)d(reference)f(to)j(the)f(image)g (object)0 4749 y(is)h(deleted,)e(the)i(image)e(data)h(is)h(deleted)f (as)h(well,)f(and)g(Tk)g(will)h(display)f(an)g(empty)f(box)g(where)n(v) o(er)g(the)h(image)f(w)o(as)i(used.)p 0 5549 3901 4 v 0 5649 a FI(724)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 725 737 TeXDict begin 725 736 bop 0 87 a FE(20.2)121 b Fx(Tix)33 b FE(\227)f(Extension)j(widgets)f(f)l(or)g(Tk)0 320 y FN(The)18 b FJ(Tix)g FN(\(Tk)f(Interf)o(ace)g(Extension\))g(module)f (pro)o(vides)h(an)h(additional)f(rich)g(set)i(of)f(widgets.)24 b(Although)17 b(the)h(standard)f(Tk)h(library)0 420 y(has)g(man)o(y)f (useful)g(widgets,)h(the)o(y)f(are)h(f)o(ar)f(from)g(complete.)23 b(The)18 b FJ(Tix)g FN(library)e(pro)o(vides)g(most)i(of)g(the)g (commonly)d(needed)i(widgets)0 519 y(that)22 b(are)f(missing)h(from)e (standard)h(Tk:)27 b FJ(HList)p FN(,)22 b FJ(ComboBox)p FN(,)e FJ(Control)h FN(\(a.k.a.)28 b(SpinBox\))21 b(and)g(an)g (assortment)g(of)g(scrollable)0 619 y(widgets.)k FJ(Tix)19 b FN(also)h(includes)f(man)o(y)f(more)g(widgets)i(that)f(are)h (generally)e(useful)h(in)g(a)h(wide)f(range)g(of)g(applications:)24 b FJ(NoteBook)p FN(,)0 719 y FJ(FileEntry)p FN(,)19 b FJ(PanedWindow)p FN(,)f(etc;)j(there)f(are)g(more)f(than)h(40)g(of)g (them.)0 866 y(W)m(ith)i(all)g(these)g(ne)n(w)g(widgets,)f(you)g(can)g (introduce)f(ne)n(w)i(interaction)e(techniques)g(into)i(applications,)e (creating)h(more)g(useful)g(and)0 965 y(more)d(intuiti)n(v)o(e)g(user)h (interf)o(aces.)24 b(Y)-9 b(ou)18 b(can)h(design)f(your)g(application)f (by)i(choosing)e(the)i(most)g(appropriate)d(widgets)j(to)g(match)g(the) 0 1065 y(special)h(needs)g(of)g(your)f(application)g(and)g(users.)0 1212 y FL(See)i(Also:)0 1358 y FK(T)-5 b(ix)21 b(Homepa)o(g)o(e)0 1458 y Fy(\()p FO(http://tix.sourcef)n(orge)o(.ne)o(t/)-6 b Fy(\))208 1558 y FN(The)19 b(home)h(page)f(for)h FJ(Tix)p FN(.)25 b(This)20 b(includes)f(links)i(to)f(additional)f(documentation) e(and)j(do)n(wnloads.)0 1705 y FK(T)-5 b(ix)21 b(Man)f(P)-7 b(a)o(g)o(es)0 1804 y Fy(\()p FO(http://tix.sourcef)n(orge)o(.ne)o(t/d) o(ist/curre)o(nt)o(/man/)g Fy(\))208 1904 y FN(On-line)19 b(v)o(ersion)g(of)h(the)g(man)g(pages)f(and)h(reference)f(material.)0 2051 y FK(T)-5 b(ix)21 b(Pr)l(o)o(gr)o(amming)e(Guide)0 2150 y Fy(\()p FO(http://tix.sourcef)n(orge)o(.ne)o(t/d)o(ist/curre)o (nt)o(/do)o(cs/tix-bo)o(ok/tix.b)o(oo)o(k.html)-6 b Fy(\))208 2250 y FN(On-line)19 b(v)o(ersion)g(of)h(the)g(programmer')-5 b(s)17 b(reference)i(material.)0 2397 y FK(T)-5 b(ix)21 b(De)o(velopment)e(Applications)0 2496 y Fy(\()p FO(http://tix.sourcef) n(orge)o(.ne)o(t/Ti)o(de)o(/)-6 b Fy(\))208 2596 y FN(T)m(ix)19 b(applications)f(for)h(de)n(v)o(elopment)d(of)j(T)m(ix)g(and)g(Tkinter) f(programs.)23 b(T)m(ide)c(applications)f(w)o(ork)h(under)f(Tk)h(or)g (Tkinter)m(,)f(and)208 2696 y(include)h FL(T)o(ixInspect)p FN(,)h(an)g(inspector)f(to)i(remotely)d(modify)h(and)h(deb)n(ug)f(T)m (ix/Tk/Tkinter)f(applications.)0 2981 y Fv(20.2.1)101 b(Using)28 b(Tix)0 3180 y FL(class)21 b FD(Tix)p FJ(\()p FK(scr)m(eenName)p FC([)p FK(,)e(baseName)p FC([)p FK(,)g(className)12 b FC(])g(])p FJ(\))208 3280 y FN(T)-7 b(ople)n(v)o(el)25 b(widget)g(of)h(T)m(ix)g(which)g(represents)f(mostly)h(the)h(main)e (windo)n(w)h(of)g(an)g(application.)41 b(It)27 b(has)f(an)g(associated) g(Tcl)208 3379 y(interpreter)-5 b(.)208 3512 y(Classes)26 b(in)f(the)f FJ(Tix)h FN(module)e(subclasses)j(the)e(classes)i(in)f (the)g FJ(Tkinter)f FN(module.)37 b(The)24 b(former)f(imports)h(the)h (latter)m(,)g(so)208 3612 y(to)d(use)g FJ(Tix)g FN(with)h(Tkinter)m(,)e (all)h(you)g(need)f(to)h(do)g(is)h(to)g(import)e(one)g(module.)30 b(In)21 b(general,)h(you)f(can)h(just)h(import)e FJ(Tix)p FN(,)h(and)208 3712 y(replace)d(the)h(tople)n(v)o(el)f(call)i(to)f FJ(Tkinter.Tk)f FN(with)h FJ(Tix.Tk)p FN(:)444 3936 y FA(import)44 b(Tix)444 4027 y(from)g(Tkconstants)f(import)1520 4040 y(*)444 4118 y(root)h(=)h(Tix.Tk\(\))0 4322 y FN(T)-7 b(o)23 b(use)g FJ(Tix)p FN(,)h(you)e(must)h(ha)n(v)o(e)g(the)g FJ(Tix)g FN(widgets)g(installed,)g(usually)f(alongside)g(your)g (installation)h(of)f(the)h(Tk)g(widgets.)33 b(T)-7 b(o)24 b(test)0 4421 y(your)19 b(installation,)g(try)h(the)h(follo)n(wing:)236 4660 y FA(import)44 b(Tix)236 4751 y(root)g(=)h(Tix.Tk\(\))236 4842 y(root.tk.eval\('package)d(require)h(Tix'\))0 5129 y FN(If)29 b(this)h(f)o(ails,)j(you)28 b(ha)n(v)o(e)h(a)h(Tk)g (installation)f(problem)e(which)i(must)h(be)f(resolv)o(ed)f(before)h (proceeding.)50 b(Use)30 b(the)g(en)m(vironment)0 5228 y(v)n(ariable)24 b(TIX)p 435 5228 25 4 v 29 w(LIBRAR)-5 b(Y)25 b(to)g(point)f(to)h(the)g(installed)g FJ(Tix)g FN(library)f(directory)-5 b(,)23 b(and)i(mak)o(e)f(sure)h(you)f(ha)n(v) o(e)g(the)h(dynamic)e(object)0 5328 y(library)18 b(\(`)p FO(tix8183.dll)p FN(')d(or)k(`)p FO(libtix8183.so)p FN('\))c(in)20 b(the)f(same)g(directory)f(that)h(contains)g(your)f(Tk)h(dynamic)e (object)i(library)f(\(`)p FO(tk8183.dll)p FN(')p 0 5549 3901 4 v 0 5649 a FI(20.2.)52 b FJ(Tix)23 b FI(\227)g(Extension)h (widgets)f(f)n(or)g(Tk)2344 b(725)p eop end %%Page: 726 738 TeXDict begin 726 737 bop 0 83 a FN(or)27 b(`)p FO(libtk8183.so)p FN('\).)43 b(The)27 b(directory)f(with)i(the)f(dynamic)f(object)h (library)f(should)h(also)h(ha)n(v)o(e)e(a)i(\002le)g(called)g(`)p FO(pkgInde)n(x.tcl)p FN(')c(\(case)0 183 y(sensiti)n(v)o(e\),)19 b(which)h(contains)g(the)g(line:)236 421 y FA(package)44 b(ifneeded)f(Tix)i(8.1)f([list)g(load)g("[file)g(join)g($dir)g (tix8183.dll]")f(Tix])0 844 y Fv(20.2.2)101 b(Tix)27 b(Widgets)0 1047 y FN(T)m(ix)h(introduces)f(o)o(v)o(er)g(40)h(widget)g (classes)i(to)e(the)h FJ(Tkinter)f FN(repertoire.)47 b(There)28 b(is)h(a)g(demo)f(of)g(all)h(the)f FJ(Tix)h FN(widgets)f(in)h(the)0 1147 y(`)p FO(Demo/tix)p FN(')19 b(directory)f(of)i(the)g(standard)f(distrib)n(ution.)0 1415 y FI(Basic)k(Widgets)0 1604 y FL(class)e FD(Balloon)p FJ(\(\))208 1703 y FN(A)f(Balloon)f(that)g(pops)g(up)g(o)o(v)o(er)f(a)i (widget)f(to)h(pro)o(vide)d(help.)24 b(When)c(the)f(user)h(mo)o(v)o(es) e(the)i(cursor)e(inside)h(a)h(widget)f(to)h(which)208 1803 y(a)28 b(Balloon)g(widget)g(has)g(been)g(bound,)g(a)g(small)h (pop-up)d(windo)n(w)h(with)i(a)f(descripti)n(v)o(e)f(message)h(will)h (be)f(sho)n(wn)g(on)g(the)208 1903 y(screen.)0 2050 y FL(class)21 b FD(ButtonBox)p FJ(\(\))208 2149 y FN(The)e(ButtonBox)h (widget)f(creates)i(a)f(box)f(of)h(b)n(uttons,)g(such)g(as)h(is)g (commonly)d(used)i(for)f FJ(Ok)50 b(Cancel)p FN(.)0 2296 y FL(class)21 b FD(ComboBox)p FJ(\(\))208 2396 y FN(The)j(ComboBox)f (widget)h(is)h(similar)g(to)g(the)f(combo)f(box)h(control)f(in)i(MS)g (W)m(indo)n(ws.)37 b(The)24 b(user)h(can)f(select)h(a)g(choice)f(by)208 2495 y(either)19 b(typing)g(in)i(the)f(entry)f(subwdget)g(or)h (selecting)g(from)f(the)h(listbox)g(subwidget.)0 2642 y FL(class)h FD(Control)p FJ(\(\))208 2742 y FN(The)30 b(Control)f(widget)h(is)i(also)e(kno)n(wn)f(as)i(the)g FJ(SpinBox)f FN(widget.)55 b(The)30 b(user)g(can)g(adjust)h(the)f(v)n (alue)g(by)g(pressing)g(the)208 2841 y(tw)o(o)25 b(arro)n(w)f(b)n (uttons)h(or)f(by)h(entering)f(the)h(v)n(alue)f(directly)h(into)g(the)g (entry)-5 b(.)38 b(The)25 b(ne)n(w)g(v)n(alue)f(will)i(be)f(check)o(ed) f(against)h(the)208 2941 y(user)n(-de\002ned)18 b(upper)h(and)g(lo)n (wer)h(limits.)0 3088 y FL(class)h FD(LabelEntry)p FJ(\(\))208 3188 y FN(The)i(LabelEntry)f(widget)h(packages)g(an)h(entry)f(widget)g (and)h(a)g(label)g(into)f(one)h(me)o(ga)e(widget.)36 b(It)24 b(can)g(be)f(used)h(be)g(used)f(to)208 3287 y(simplify)c(the)h (creation)f(of)h(\223entry-form\224)e(type)h(of)h(interf)o(ace.)0 3434 y FL(class)h FD(LabelFrame)p FJ(\(\))208 3534 y FN(The)g(LabelFrame)f(widget)h(packages)g(a)h(frame)e(widget)h(and)g(a) h(label)g(into)f(one)g(me)o(ga)g(widget.)28 b(T)-7 b(o)22 b(create)f(widgets)h(inside)f(a)208 3633 y(LabelFrame)f(widget,)h(one)g (creates)g(the)h(ne)n(w)f(widgets)g(relati)n(v)o(e)g(to)g(the)h FJ(frame)f FN(subwidget)f(and)h(manage)f(them)h(inside)h(the)208 3733 y FJ(frame)d FN(subwidget.)0 3880 y FL(class)i FD(Meter)p FJ(\(\))208 3979 y FN(The)e(Meter)g(widget)f(can)i(be)f(used)g(to)g (sho)n(w)g(the)h(progress)e(of)h(a)g(background)d(job)j(which)g(may)g (tak)o(e)g(a)h(long)e(time)i(to)f(e)o(x)o(ecute.)0 4126 y FL(class)i FD(OptionMenu)p FJ(\(\))208 4226 y FN(The)e(OptionMenu)f (creates)j(a)f(menu)g(b)n(utton)f(of)h(options.)0 4373 y FL(class)h FD(PopupMenu)p FJ(\(\))208 4472 y FN(The)f(PopupMenu)f (widget)h(can)h(be)g(used)g(as)g(a)h(replacement)d(of)i(the)g FJ(tk_popup)f FN(command.)25 b(The)c(adv)n(antage)e(of)i(the)g FJ(Tix)208 4572 y(PopupMenu)e FN(widget)g(is)i(it)g(requires)f(less)h (application)e(code)g(to)h(manipulate.)0 4719 y FL(class)h FD(Select)p FJ(\(\))208 4819 y FN(The)d(Select)i(widget)f(is)h(a)g (container)e(of)h(b)n(utton)f(subwidgets.)24 b(It)19 b(can)g(be)g(used)g(to)h(pro)o(vide)d(radio-box)g(or)i(check-box)d (style)k(of)208 4918 y(selection)f(options)h(for)f(the)h(user)-5 b(.)0 5065 y FL(class)21 b FD(StdButtonBox)p FJ(\(\))208 5165 y FN(The)e(StdButtonBox)g(widget)h(is)h(a)g(group)d(of)i(standard) f(b)n(uttons)h(for)f(Motif-lik)o(e)h(dialog)f(box)o(es.)p 0 5549 3901 4 v 0 5649 a FI(726)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 727 739 TeXDict begin 727 738 bop 0 83 a FI(File)24 b(Selectors)0 272 y FL(class)d FD(DirList)p FJ(\(\))208 372 y FN(The)h(DirList)i (widget)e(displays)h(a)h(list)g(vie)n(w)f(of)g(a)g(directory)-5 b(,)22 b(its)i(pre)n(vious)e(directories)g(and)g(its)i (sub-directories.)32 b(The)23 b(user)208 471 y(can)d(choose)f(one)g(of) h(the)h(directories)e(displayed)g(in)h(the)g(list)i(or)e(change)e(to)j (another)d(directory)-5 b(.)0 618 y FL(class)21 b FD(DirTree)p FJ(\(\))208 718 y FN(The)f(DirT)m(ree)g(widget)h(displays)f(a)i(tree)f (vie)n(w)f(of)h(a)g(directory)-5 b(,)19 b(its)j(pre)n(vious)d (directories)h(and)g(its)i(sub-directories.)j(The)c(user)208 817 y(can)f(choose)f(one)g(of)h(the)h(directories)e(displayed)g(in)h (the)g(list)i(or)e(change)e(to)j(another)d(directory)-5 b(.)0 964 y FL(class)21 b FD(DirSelectDialog)p FJ(\(\))208 1064 y FN(The)e(DirSelectDialog)g(widget)g(presents)g(the)g (directories)g(in)h(the)f(\002le)i(system)e(in)h(a)g(dialog)f(windo)n (w)-5 b(.)23 b(The)c(user)h(can)f(use)h(this)208 1163 y(dialog)f(windo)n(w)g(to)h(na)n(vigate)f(through)f(the)j(\002le)f (system)h(to)f(select)h(the)f(desired)g(directory)-5 b(.)0 1310 y FL(class)21 b FD(DirSelectBox)p FJ(\(\))208 1410 y FN(The)f FJ(DirSelectBox)g FN(is)h(similar)h(to)f(the)g (standard)f(Motif\(TM\))f(directory-selection)f(box.)27 b(It)21 b(is)h(generally)d(used)i(for)g(the)208 1510 y(user)c(to)g(choose)f(a)i(directory)-5 b(.)22 b(DirSelectBox)17 b(stores)g(the)g(directories)f(mostly)h(recently)g(selected)g(into)g(a) g(ComboBox)f(widget)208 1609 y(so)k(that)g(the)o(y)g(can)g(be)g (quickly)f(selected)h(again.)0 1756 y FL(class)h FD(ExFileSelectBox)p FJ(\(\))208 1856 y FN(The)f(ExFileSelectBox)f(widget)h(is)i(usually)e (embedded)e(in)i(a)h(tixExFileSelectDialog)e(widget.)25 b(It)c(pro)o(vides)e(an)h(con)m(v)o(enient)208 1955 y(method)f(for)h (the)g(user)g(to)h(select)g(\002les.)27 b(The)20 b(style)h(of)f(the)h FJ(ExFileSelectBox)d FN(widget)i(is)i(v)o(ery)d(similar)i(to)f(the)h (standard)208 2055 y(\002le)f(dialog)g(on)f(MS)i(W)m(indo)n(ws)f(3.1.)0 2202 y FL(class)h FD(FileSelectBox)p FJ(\(\))208 2301 y FN(The)j(FileSelectBox)h(is)h(similar)f(to)g(the)g(standard)f (Motif\(TM\))f(\002le-selection)i(box.)38 b(It)25 b(is)h(generally)e (used)g(for)h(the)g(user)f(to)208 2401 y(choose)c(a)j(\002le.)30 b(FileSelectBox)22 b(stores)g(the)f(\002les)i(mostly)f(recently)e (selected)i(into)f(a)i FJ(ComboBox)d FN(widget)i(so)g(that)g(the)o(y)f (can)208 2501 y(be)f(quickly)f(selected)h(again.)0 2648 y FL(class)h FD(FileEntry)p FJ(\(\))208 2747 y FN(The)c(FileEntry)g (widget)h(can)g(be)g(used)f(to)i(input)e(a)h(\002lename.)24 b(The)18 b(user)g(can)f(type)h(in)g(the)g(\002lename)f(manually)-5 b(.)23 b(Alternati)n(v)o(ely)-5 b(,)208 2847 y(the)20 b(user)g(can)g(press)g(the)g(b)n(utton)g(widget)f(that)i(sits)g(ne)o (xt)f(to)g(the)g(entry)-5 b(,)19 b(which)h(will)h(bring)e(up)g(a)i (\002le)g(selection)f(dialog.)0 3115 y FI(Hier)o(achical)k(ListBo)n(x)0 3304 y FL(class)d FD(HList)p FJ(\(\))208 3404 y FN(The)26 b(HList)h(widget)f(can)g(be)g(used)g(to)h(display)f(an)o(y)f(data)i (that)f(ha)n(v)o(e)g(a)h(hierarchical)d(structure,)j(for)f(e)o(xample,) g(\002le)h(system)208 3503 y(directory)g(trees.)54 b(The)29 b(list)i(entries)e(are)h(indented)e(and)h(connected)e(by)j(branch)e (lines)i(according)d(to)j(their)f(places)h(in)g(the)208 3603 y(hierarchy)-5 b(.)0 3750 y FL(class)21 b FD(CheckList)p FJ(\(\))208 3849 y FN(The)27 b(CheckList)h(widget)g(displays)f(a)i (list)g(of)f(items)g(to)g(be)g(selected)g(by)g(the)g(user)-5 b(.)48 b(CheckList)28 b(acts)h(similarly)f(to)g(the)g(Tk)208 3949 y(checkb)n(utton)e(or)j(radiob)n(utton)e(widgets,)k(e)o(xcept)d (it)i(is)g(capable)e(of)g(handling)g(man)o(y)f(more)i(items)g(than)g (checkb)n(uttons)e(or)208 4049 y(radiob)n(uttons.)0 4195 y FL(class)21 b FD(Tree)p FJ(\(\))208 4295 y FN(The)e(T)m(ree)h(widget) g(can)g(be)g(used)g(to)h(display)f(hierarchical)e(data)i(in)h(a)f(tree) h(form.)j(The)c(user)g(can)g(adjust)g(the)g(vie)n(w)g(of)g(the)h(tree) 208 4395 y(by)e(opening)g(or)g(closing)h(parts)g(of)g(the)g(tree.)0 4663 y FI(T)-10 b(ab)n(ular)24 b(ListBo)n(x)0 4852 y FL(class)d FD(TList)p FJ(\(\))208 4951 y FN(The)e(TList)h(widget)f(can) h(be)g(used)f(to)h(display)f(data)h(in)g(a)g(tab)n(ular)f(format.)24 b(The)19 b(list)i(entries)e(of)h(a)g FJ(TList)f FN(widget)h(are)f (similar)208 5051 y(to)e(the)g(entries)g(in)g(the)g(Tk)f(listbox)h (widget.)24 b(The)16 b(main)h(dif)n(ferences)e(are)i(\(1\))f(the)h FJ(TList)g FN(widget)f(can)h(display)g(the)g(list)h(entries)208 5151 y(in)23 b(a)h(tw)o(o)g(dimensional)e(format)h(and)g(\(2\))g(you)g (can)g(use)h(graphical)e(images)h(as)i(well)f(as)g(multiple)f(colors)g (and)g(fonts)h(for)f(the)208 5250 y(list)e(entries.)p 0 5549 3901 4 v 0 5649 a FI(20.2.)52 b FJ(Tix)23 b FI(\227)g(Extension) h(widgets)f(f)n(or)g(Tk)2344 b(727)p eop end %%Page: 728 740 TeXDict begin 728 739 bop 0 83 a FI(Manager)24 b(Widgets)0 272 y FL(class)d FD(PanedWindow)p FJ(\(\))208 372 y FN(The)f(P)o(anedW) m(indo)n(w)f(widget)h(allo)n(ws)h(the)g(user)g(to)g(interacti)n(v)o (ely)e(manipulate)g(the)i(sizes)h(of)e(se)n(v)o(eral)g(panes.)27 b(The)20 b(panes)h(can)208 471 y(be)27 b(arranged)f(either)i(v)o (ertically)f(or)h(horizontally)-5 b(.)45 b(The)28 b(user)g(changes)f (the)h(sizes)h(of)f(the)g(panes)f(by)h(dragging)d(the)j(resize)208 571 y(handle)19 b(between)g(tw)o(o)h(panes.)0 718 y FL(class)h FD(ListNoteBook)p FJ(\(\))208 817 y FN(The)16 b(ListNoteBook)f(widget)h (is)h(v)o(ery)e(similar)i(to)f(the)h FJ(TixNoteBook)d FN(widget:)23 b(it)17 b(can)g(be)f(used)g(to)g(display)g(man)o(y)f (windo)n(ws)208 917 y(in)20 b(a)g(limited)g(space)h(using)e(a)i (notebook)d(metaphor)-5 b(.)23 b(The)d(notebook)e(is)j(di)n(vided)d (into)i(a)h(stack)f(of)g(pages)g(\(windo)n(ws\).)j(At)e(one)208 1017 y(time)e(only)g(one)g(of)g(these)h(pages)f(can)g(be)g(sho)n(wn.)24 b(The)c(user)f(can)g(na)n(vigate)f(through)g(these)h(pages)h(by)f (choosing)e(the)j(name)f(of)208 1116 y(the)h(desired)f(page)h(in)g(the) g FJ(hlist)g FN(subwidget.)0 1263 y FL(class)h FD(NoteBook)p FJ(\(\))208 1363 y FN(The)d(NoteBook)g(widget)h(can)g(be)g(used)g(to)g (display)f(man)o(y)g(windo)n(ws)g(in)i(a)f(limited)g(space)g(using)g(a) g(notebook)e(metaphor)-5 b(.)23 b(The)208 1462 y(notebook)h(is)j(di)n (vided)f(into)g(a)h(stack)g(of)f(pages.)44 b(At)27 b(one)f(time)h(only) f(one)g(of)g(these)h(pages)f(can)h(be)f(sho)n(wn.)44 b(The)26 b(user)h(can)208 1562 y(na)n(vigate)19 b(through)f(these)i (pages)g(by)f(choosing)g(the)h(visual)g(\223tabs\224)h(at)f(the)g(top)g (of)g(the)g(NoteBook)f(widget.)0 1830 y FI(Image)24 b(T)-10 b(ypes)0 2033 y FN(The)20 b FJ(Tix)g FN(module)f(adds:)125 2246 y FM(\017)41 b FN(pixmap)18 b(capabilities)i(to)h(all)f FJ(Tix)h FN(and)e FJ(Tkinter)h FN(widgets)g(to)g(create)g(color)f (images)h(from)f(XPM)i(\002les.)125 2412 y FM(\017)41 b FN(Compound)27 b(image)i(types)h(can)f(be)h(used)f(to)h(create)g (images)f(that)h(consists)g(of)f(multiple)h(horizontal)d(lines;)35 b(each)30 b(line)g(is)208 2512 y(composed)25 b(of)h(a)i(series)f(of)g (items)g(\(te)o(xts,)i(bitmaps,)f(images)e(or)h(spaces\))g(arranged)e (from)h(left)h(to)g(right.)45 b(F)o(or)26 b(e)o(xample,)h(a)208 2612 y(compound)17 b(image)i(can)h(be)h(used)f(to)g(display)f(a)i (bitmap)e(and)h(a)h(te)o(xt)f(string)g(simultaneously)e(in)j(a)f(Tk)g FJ(Button)g FN(widget.)0 2880 y FI(Miscellaneous)k(Widgets)0 3069 y FL(class)d FD(InputOnly)p FJ(\(\))208 3168 y FN(The)g(InputOnly) f(widgets)i(are)g(to)h(accept)e(inputs)h(from)f(the)h(user)m(,)g(which) g(can)f(be)h(done)g(with)g(the)g FJ(bind)g FN(command)e(\()r(U)t FH(N)t(I)t(X)208 3268 y FN(only\).)0 3536 y FI(F)n(or)r(m)i(Geometr)r (y)h(Manager)0 3739 y FN(In)d(addition,)f FJ(Tix)h FN(augments)f FJ(Tkinter)g FN(by)h(pro)o(viding:)0 3886 y FL(class)h FD(Form)p FJ(\(\))208 3986 y FN(The)e(F)o(orm)h(geometry)e(manager)h (based)h(on)f(attachment)g(rules)i(for)e(all)i(Tk)f(widgets.)0 4271 y Fv(20.2.3)101 b(Tix)27 b(Commands)0 4460 y FL(class)21 b FD(tixCommand)p FJ(\(\))208 4559 y FN(The)k(tix)i(commands)d(pro)o (vide)h(access)h(to)h(miscellaneous)e(elements)h(of)g FJ(Tix)p FN(')-5 b(s)27 b(internal)e(state)i(and)f(the)g FJ(Tix)g FN(application)208 4659 y(conte)o(xt.)34 b(Most)24 b(of)g(the)f(information)f(manipulated)g(by)h(these)h(methods)f (pertains)g(to)h(the)g(application)e(as)j(a)f(whole,)g(or)f(to)h(a)208 4758 y(screen)19 b(or)h(display)-5 b(,)19 b(rather)h(than)f(to)i(a)f (particular)f(windo)n(w)-5 b(.)208 4891 y(T)e(o)20 b(vie)n(w)g(the)g (current)f(settings,)h(the)g(common)f(usage)h(is:)444 5115 y FA(import)44 b(Tix)444 5207 y(root)g(=)h(Tix.Tk\(\))444 5298 y(print)f(root.tix_configure\(\))p 0 5549 3901 4 v 0 5649 a FI(728)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 729 741 TeXDict begin 729 740 bop 0 83 a FD(tix_configure)p FJ(\()p FC([)p FK(cnf)o(,)12 b FC(])17 b FK(**kw)p FJ(\))208 183 y FN(Query)29 b(or)h(modify)e(the)i(con\002guration)e(options)h(of) h(the)g(T)m(ix)g(application)f(conte)o(xt.)54 b(If)30 b(no)f(option)g(is)i(speci\002ed,)h(returns)208 282 y(a)d(dictionary)f (all)i(of)f(the)g(a)n(v)n(ailable)g(options.)52 b(If)29 b(option)f(is)j(speci\002ed)e(with)g(no)g(v)n(alue,)i(then)e(the)g (method)f(returns)h(a)g(list)208 382 y(describing)c(the)i(one)f(named)g (option)f(\(this)i(list)h(will)g(be)f(identical)f(to)h(the)g (corresponding)c(sublist)28 b(of)e(the)h(v)n(alue)f(returned)208 482 y(if)f(no)f(option)g(is)i(speci\002ed\).)38 b(If)25 b(one)f(or)h(more)f(option-v)n(alue)e(pairs)j(are)g(speci\002ed,)g (then)g(the)g(method)e(modi\002es)i(the)g(gi)n(v)o(en)208 581 y(option\(s\))20 b(to)i(ha)n(v)o(e)f(the)h(gi)n(v)o(en)f(v)n (alue\(s\);)g(in)h(this)h(case)f(the)g(method)e(returns)h(an)h(empty)f (string.)30 b(Option)21 b(may)g(be)h(an)o(y)f(of)h(the)208 681 y(con\002guration)17 b(options.)0 828 y FD(tix_cget)p FJ(\()p FK(option)p FJ(\))208 927 y FN(Returns)23 b(the)g(current)e(v)n (alue)i(of)g(the)g(con\002guration)d(option)i(gi)n(v)o(en)g(by)h FK(option)p FN(.)32 b(Option)22 b(may)h(be)g(an)o(y)f(of)h(the)g (con\002guration)208 1027 y(options.)0 1174 y FD(tix_getbitmap)p FJ(\()p FK(name)p FJ(\))208 1273 y FN(Locates)33 b(a)i(bitmap)e(\002le) i(of)f(the)g(name)f FJ(name.xpm)g FN(or)h FJ(name)g FN(in)g(one)f(of)h (the)g(bitmap)g(directories)f(\(see)h(the)g FJ(tix_-)208 1373 y(addbitmapdir\(\))23 b FN(method\).)40 b(By)26 b(using)f FJ(tix_getbitmap\(\))p FN(,)g(you)g(can)g(a)n(v)n(oid)h(hard) e(coding)h(the)g(pathnames)g(of)208 1473 y(the)c(bitmap)g(\002les)i(in) f(your)e(application.)28 b(When)22 b(successful,)g(it)g(returns)f(the)h (complete)e(pathname)h(of)g(the)h(bitmap)f(\002le,)h(pre-)208 1572 y(\002x)o(ed)e(with)h(the)g(character)e(`)p FJ(@)p FN('.)26 b(The)21 b(returned)e(v)n(alue)h(can)h(be)f(used)h(to)g (con\002gure)e(the)i FJ(bitmap)f FN(option)f(of)i(the)g(Tk)f(and)h(T)m (ix)208 1672 y(widgets.)0 1819 y FD(tix_addbitmapdir)p FJ(\()p FK(dir)m(ectory)p FJ(\))208 1918 y FN(T)m(ix)36 b(maintains)g(a)i(list)f(of)g(directories)f(under)f(which)h(the)h FJ(tix_getimage\(\))e FN(and)h FJ(tix_getbitmap\(\))e FN(meth-)208 2018 y(ods)h(will)i(search)e(for)g(image)g(\002les.)73 b(The)35 b(standard)g(bitmap)g(directory)e(is)k(`)p FO($TIX)p 2745 2018 23 4 v 25 w(LIBRAR)l(Y/bitmaps)p FN('.)70 b(The)35 b FJ(tix_-)208 2118 y(addbitmapdir\(\))25 b FN(method)h(adds)h FK(dir)m(ectory)h FN(into)f(this)h(list.)48 b(By)28 b(using)f(this)h (method,)g(the)f(image)g(\002les)i(of)e(an)g(appli-)208 2217 y(cations)20 b(can)f(also)i(be)f(located)g(using)f(the)i FJ(tix_getimage\(\))d FN(or)i FJ(tix_getbitmap\(\))e FN(method.)0 2364 y FD(tix_filedialog)p FJ(\()p FC([)p FK(dlgclass)12 b FC(])p FJ(\))208 2464 y FN(Returns)25 b(the)g(\002le)h(selection)g(dialog)e(that)i(may)f(be)g(shared)g(among) f(dif)n(ferent)g(calls)i(from)e(this)i(application.)39 b(This)26 b(method)208 2563 y(will)j(create)g(a)g(\002le)g(selection)g (dialog)f(widget)g(when)g(it)i(is)g(called)e(the)h(\002rst)h(time.)50 b(This)29 b(dialog)f(will)i(be)f(returned)e(by)h(all)208 2663 y(subsequent)21 b(calls)j(to)f FJ(tix_filedialog\(\))p FN(.)32 b(An)23 b(optional)f(dlgclass)h(parameter)e(can)i(be)g(passed)g (as)h(a)g(string)f(to)g(spec-)208 2763 y(i\002ed)g(what)f(type)h(of)f (\002le)i(selection)e(dialog)g(widget)h(is)g(desired.)32 b(Possible)24 b(options)d(are)i FJ(tix)p FN(,)g FJ(FileSelectDialog)e FN(or)208 2862 y FJ(tixExFileSelectDialog)p FN(.)0 3009 y FD(tix_getimage)p FJ(\()p FK(self)o(,)e(name)p FJ(\))208 3109 y FN(Locates)27 b(an)h(image)f(\002le)i(of)f(the)g(name)f(`)p FO(name)o(.xpm)p FN(',)h(`)p FO(name)o(.xbm)p FN(')e(or)i(`)p FO(name)o(.ppm)p FN(')e(in)i(one)f(of)h(the)f(bitmap)h(directories)208 3208 y(\(see)g(the)h FJ(tix_addbitmapdir\(\))c FN(method)j(abo)o(v)o (e\).)47 b(If)29 b(more)e(than)h(one)g(\002le)h(with)g(the)g(same)f (name)g(\(b)n(ut)g(dif)n(ferent)208 3308 y(e)o(xtensions\))17 b(e)o(xist,)i(then)g(the)g(image)f(type)h(is)g(chosen)f(according)f(to) j(the)e(depth)g(of)h(the)g(X)h(display:)k(xbm)18 b(images)h(are)f (chosen)208 3408 y(on)24 b(monochrome)e(displays)j(and)f(color)h (images)g(are)g(chosen)f(on)h(color)f(displays.)39 b(By)26 b(using)e FJ(tix_getimage\(\))p FN(,)g(you)208 3507 y(can)29 b(a)n(v)n(oid)h(hard)g(coding)e(the)i(pathnames)f(of)h(the)g(image)g (\002les)h(in)f(your)f(application.)53 b(When)30 b(successful,)i(this)f (method)208 3607 y(returns)22 b(the)h(name)f(of)h(the)g(ne)n(wly)g (created)f(image,)h(which)g(can)f(be)h(used)g(to)g(con\002gure)f(the)h FJ(image)g FN(option)e(of)i(the)g(Tk)g(and)208 3707 y(T)m(ix)d (widgets.)0 3853 y FD(tix_option_get)p FJ(\()p FK(name)p FJ(\))208 3953 y FN(Gets)g(the)h(options)e(maintained)g(by)g(the)i(T)m (ix)f(scheme)g(mechanism.)0 4100 y FD(tix_resetoptions)p FJ(\()p FK(ne)o(wSc)o(heme)o(,)15 b(ne)o(wF)-9 b(ontSet)q FC([)p FK(,)19 b(ne)o(wScmPrio)12 b FC(])p FJ(\))208 4200 y FN(Resets)24 b(the)g(scheme)f(and)g(fontset)g(of)g(the)h(T)m(ix) f(application)f(to)i FK(ne)o(wSc)o(heme)e FN(and)h FK(ne)o(wF)-9 b(ontSet)q FN(,)23 b(respecti)n(v)o(ely)-5 b(.)33 b(This)24 b(af)n(fects)208 4299 y(only)18 b(those)h(widgets)f(created)h(after)f (this)i(call.)25 b(Therefore,)17 b(it)j(is)f(best)h(to)f(call)g(the)g (resetoptions)f(method)g(before)g(the)h(creation)208 4399 y(of)g(an)o(y)h(widgets)g(in)g(a)h(T)m(ix)f(application.)208 4532 y(The)27 b(optional)g(parameter)f FK(ne)o(wScmPrio)h FN(can)g(be)h(gi)n(v)o(en)f(to)h(reset)g(the)g(priority)e(le)n(v)o(el)i (of)f(the)h(Tk)g(options)f(set)h(by)g(the)g(T)m(ix)208 4631 y(schemes.)208 4764 y(Because)h(of)g(the)g(w)o(ay)h(Tk)f(handles)f (the)i(X)f(option)g(database,)h(after)f(T)m(ix)h(has)f(been)g(has)g (imported)f(and)h(inited,)i(it)f(is)g(not)208 4864 y(possible)h(to)g (reset)h(the)f(color)f(schemes)h(and)g(font)g(sets)h(using)f(the)g FJ(tix_config\(\))f FN(method.)57 b(Instead,)33 b(the)e FJ(tix_-)208 4963 y(resetoptions\(\))18 b FN(method)h(must)h(be)g (used.)p 0 5549 3901 4 v 0 5649 a FI(20.2.)52 b FJ(Tix)23 b FI(\227)g(Extension)h(widgets)f(f)n(or)g(Tk)2344 b(729)p eop end %%Page: 730 742 TeXDict begin 730 741 bop 0 88 a FE(20.3)121 b Fx(ScrolledText)30 b FE(\227)j(Scrolled)g(T)-14 b(e)l(xt)34 b(Widget)0 321 y FN(The)23 b FJ(ScrolledText)e FN(module)g(pro)o(vides)h(a)h(class)h (of)e(the)h(same)g(name)g(which)f(implements)g(a)h(basic)g(te)o(xt)g (widget)g(which)f(has)h(a)0 421 y(v)o(ertical)d(scroll)g(bar)g (con\002gured)e(to)j(do)f(the)g(\223right)g(thing.)-6 b(\224)25 b(Using)20 b(the)g FJ(ScrolledText)f FN(class)i(is)h(a)f(lot) f(easier)h(than)f(setting)g(up)g(a)0 520 y(te)o(xt)g(widget)g(and)f (scroll)i(bar)e(directly)-5 b(.)24 b(The)c(constructor)e(is)j(the)g (same)f(as)h(that)f(of)g(the)g FJ(Tkinter.Text)f FN(class.)0 667 y(The)27 b(te)o(xt)g(widget)f(and)h(scrollbar)f(are)h(pack)o(ed)f (together)g(in)h(a)g FJ(Frame)p FN(,)i(and)d(the)h(methods)f(of)h(the)g FJ(Grid)g FN(and)g FJ(Pack)f FN(geometry)0 767 y(managers)16 b(are)h(acquired)e(from)i(the)g FJ(Frame)f FN(object.)24 b(This)17 b(allo)n(ws)h(the)f FJ(ScrolledText)e FN(widget)i(to)g(be)g (used)g(directly)f(to)i(achie)n(v)o(e)0 866 y(most)i(normal)f(geometry) g(management)f(beha)n(vior)-5 b(.)0 1013 y(Should)19 b(more)g(speci\002c)i(control)e(be)h(necessary)-5 b(,)19 b(the)h(follo)n(wing)e(attrib)n(utes)j(are)f(a)n(v)n(ailable:)0 1160 y FD(frame)208 1260 y FN(The)f(frame)h(which)f(surrounds)g(the)h (te)o(xt)g(and)g(scroll)g(bar)g(widgets.)0 1407 y FD(vbar)208 1506 y FN(The)f(scroll)i(bar)e(widget.)0 1834 y FE(20.4)121 b Fx(turtle)32 b FE(\227)h(T)-14 b(ur)5 b(tle)33 b(g)o(r)o(aphics)g(f)l (or)i(Tk)0 2066 y FN(The)29 b FJ(turtle)g FN(module)f(pro)o(vides)g (turtle)h(graphics)f(primiti)n(v)o(es,)j(in)e(both)g(an)g (object-oriented)e(and)i(procedure-oriented)24 b(w)o(ays.)0 2166 y(Because)c(it)h(uses)g FJ(Tkinter)e FN(for)h(the)g(underlying)e (graphics,)g(it)j(needs)f(a)h(v)o(ersion)e(of)h(p)o(ython)e(installed)i (with)h(Tk)f(support.)0 2313 y(The)d(procedural)e(interf)o(ace)h(uses)h (a)h(pen)f(and)f(a)i(can)m(v)n(as)e(which)h(are)g(automagically)e (created)h(when)h(an)o(y)f(of)h(the)g(functions)f(are)h(called.)0 2460 y(The)j FJ(turtle)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f (functions:)0 2607 y FD(degrees)p FJ(\(\))208 2706 y FN(Set)h(angle)g(measurement)e(units)j(to)f(de)o(grees.)0 2853 y FD(radians)p FJ(\(\))208 2953 y FN(Set)g(angle)g(measurement)e (units)j(to)f(radians.)0 3100 y FD(setup)p FJ(\()p FK(**kwar)m(gs)p FJ(\))208 3199 y FN(Sets)h(the)f(size)h(and)e(position)h(of)g(the)g (main)g(windo)n(w)-5 b(.)23 b(K)n(e)o(yw)o(ords)c(are:)349 3365 y FM(\017)o FJ(width)p FN(:)25 b(either)20 b(a)g(size)h(in)g(pix)o (els)f(or)f(a)i(fraction)e(of)h(the)g(screen.)25 b(The)20 b(def)o(ault)f(is)i(50\045)f(of)g(the)g(screen.)349 3498 y FM(\017)o FJ(height)p FN(:)25 b(either)20 b(a)g(size)h(in)g(pix)o (els)e(or)h(a)h(fraction)e(of)h(the)g(screen.)k(The)c(def)o(ault)g(is)h (50\045)f(of)g(the)g(screen.)349 3631 y FM(\017)o FJ(startx)p FN(:)k(starting)18 b(position)g(in)h(pix)o(els)f(from)g(the)g(left)h (edge)f(of)h(the)f(screen.)24 b FJ(None)19 b FN(is)g(the)g(def)o(ault)f (v)n(alue)g(and)g(centers)390 3731 y(the)i(windo)n(w)g(horizontally)e (on)h(screen.)349 3863 y FM(\017)o FJ(starty)p FN(:)24 b(starting)19 b(position)f(in)h(pix)o(els)f(from)g(the)h(top)g(edge)f (of)h(the)g(screen.)24 b FJ(None)18 b FN(is)i(the)f(def)o(ault)f(v)n (alue)h(and)f(centers)390 3963 y(the)i(windo)n(w)g(v)o(ertically)f(on)g (screen.)208 4129 y(Examples:)444 4353 y FA(#)44 b(Uses)h(default)e (geometry:)h(50\045)g(x)h(50\045)f(of)g(screen,)g(centered.)444 4445 y(setup\(\))444 4627 y(#)g(Sets)h(window)e(to)i(200x200)f(pixels,) f(in)i(upper)f(left)g(of)g(screen)444 4719 y(setup)g(\(width=200,)f (height=200,)g(startx=0,)g(starty=0\))444 4901 y(#)h(Sets)h(window)e (to)i(75\045)f(of)h(screen)f(by)g(50\045)g(of)h(screen,)f(and)g (centers)g(it.)444 4993 y(setup\(width=.75,)e(height=0.5,)h (startx=None,)g(starty=None\))0 5196 y FD(title)p FJ(\()p FK(title)p 434 5196 25 4 v 29 w(str)r FJ(\))208 5296 y FN(Set)20 b(the)h(windo)n(w')-5 b(s)19 b(title)i(to)f FK(title)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(730)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i (Tk)p eop end %%Page: 731 743 TeXDict begin 731 742 bop 0 83 a FD(done)p FJ(\(\))208 183 y FN(Enters)26 b(the)h(Tk)f(main)h(loop.)44 b(The)26 b(windo)n(w)g(will)i(continue)d(to)i(be)f(displayed)g(until)h(the)g (user)f(closes)h(it)h(or)e(the)h(process)g(is)208 282 y(killed.)0 429 y FD(reset)p FJ(\(\))208 529 y FN(Clear)20 b(the)g(screen,)g(re-center)f(the)h(pen,)f(and)h(set)h(v)n(ariables)e (to)i(the)f(def)o(ault)f(v)n(alues.)0 676 y FD(clear)p FJ(\(\))208 775 y FN(Clear)h(the)g(screen.)0 922 y FD(tracer)p FJ(\()p FK(\003a)o(g)p FJ(\))208 1022 y FN(Set)h(tracing)e(on/of)n(f)g (\(according)f(to)j(whether)e(\003ag)i(is)g(true)f(or)g(not\).)25 b(T)m(racing)19 b(means)i(line)f(are)g(dra)o(wn)g(more)f(slo)n(wly)-5 b(,)20 b(with)h(an)208 1121 y(animation)d(of)i(an)g(arro)n(w)g(along)f (the)h(line.)0 1268 y FD(speed)p FJ(\()p FK(speed)r FJ(\))208 1368 y FN(Set)j(the)g(speed)f(of)g(the)h(turtle.)32 b(V)-9 b(alid)23 b(v)n(alues)f(for)g(the)h(parameter)e FK(speed)k FN(are)d FJ('fastest')g FN(\(no)g(delay\),)g FJ('fast')p FN(,)h(\(delay)208 1468 y(5ms\),)c FJ('normal')g FN(\(delay)h(10ms\),)f FJ('slow')g FN(\(delay)h(15ms\),)f(and)g FJ('slowest')g FN(\(delay)h(20ms\).)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1614 y FD(delay)p FJ(\()p FK(delay)p FJ(\))208 1714 y FN(Set)h(the)h(speed)e(of)h(the)h(turtle)f(to)g FK(delay)p FN(,)f(which)h(is)h(gi)n(v)o(en)e(in)h(ms.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1861 y FD(forward)p FJ(\()p FK(distance)p FJ(\))208 1961 y FN(Go)h(forw)o(ard)e FK(distance)i FN(steps.)0 2107 y FD(backward)p FJ(\()p FK(distance)p FJ(\))208 2207 y FN(Go)g(backw)o(ard)e FK(distance)i FN(steps.)0 2354 y FD(left)p FJ(\()p FK(angle)p FJ(\))208 2454 y FN(T)l(urn)31 b(left)h FK(angle)e FN(units.)60 b(Units)32 b(are)g(by)f(def)o(ault)g(de)o(grees,)j(b)n(ut)d(can)h(be)g (set)g(via)g(the)g FJ(degrees\(\))e FN(and)i FJ(radians\(\))208 2553 y FN(functions.)0 2700 y FD(right)p FJ(\()p FK(angle)p FJ(\))208 2800 y FN(T)l(urn)c(right)h FK(angle)f FN(units.)53 b(Units)30 b(are)f(by)g(def)o(ault)g(de)o(grees,)h(b)n(ut)f(can)g(be)h (set)g(via)f(the)h FJ(degrees\(\))e FN(and)h FJ(radians\(\))208 2899 y FN(functions.)0 3046 y FD(up)p FJ(\(\))208 3146 y FN(Mo)o(v)o(e)19 b(the)h(pen)f(up)h(\227)h(stop)f(dra)o(wing.)0 3293 y FD(down)p FJ(\(\))208 3392 y FN(Mo)o(v)o(e)f(the)h(pen)f(do)n (wn)h(\227)g(dra)o(w)g(when)f(mo)o(ving.)0 3539 y FD(width)p FJ(\()p FK(width)p FJ(\))208 3639 y FN(Set)h(the)h(line)f(width)g(to)g FK(width)p FN(.)0 3786 y FD(color)p FJ(\()p FK(s)p FJ(\))0 3885 y FD(color)p FJ(\()p FK(\(r)-9 b(,)19 b(g)o(,)h(b\))p FJ(\))0 3985 y FD(color)p FJ(\()p FK(r)-9 b(,)19 b(g)o(,)i(b)p FJ(\))208 4084 y FN(Set)f(the)f(pen)g(color)-5 b(.)24 b(In)19 b(the)g(\002rst)h(form,)e(the)i(color)e(is)i(speci\002ed)f(as)h (a)g(Tk)f(color)g(speci\002cation)f(as)i(a)g(string.)k(The)19 b(second)g(form)208 4184 y(speci\002es)f(the)g(color)e(as)j(a)f(tuple)f (of)h(the)g(RGB)h(v)n(alues,)e(each)h(in)f(the)h(range)f([0..1].)22 b(F)o(or)c(the)f(third)h(form,)f(the)g(color)g(is)i(speci\002ed)208 4284 y(gi)n(ving)f(the)j(RGB)g(v)n(alues)f(as)h(three)f(separate)f (parameters)g(\(each)h(in)g(the)g(range)f([0..1]\).)0 4431 y FD(write)p FJ(\()p FK(te)n(xt)q FC([)p FK(,)h(mo)o(ve)12 b FC(])p FJ(\))208 4530 y FN(Write)19 b FK(te)n(xt)i FN(at)e(the)f(current)g(pen)g(position.)23 b(If)c FK(mo)o(ve)f FN(is)i(true,)e(the)h(pen)f(is)i(mo)o(v)o(ed)c(to)j(the)g(bottom-right) d(corner)h(of)h(the)h(te)o(xt.)24 b(By)208 4630 y(def)o(ault,)19 b FK(mo)o(ve)h FN(is)h(f)o(alse.)0 4777 y FD(fill)p FJ(\()p FK(\003a)o(g)p FJ(\))208 4876 y FN(The)f(complete)h(speci\002cations)f (are)i(rather)e(comple)o(x,)f(b)n(ut)j(the)f(recommended)d(usage)j(is:) 28 b(call)22 b FJ(fill\(1\))e FN(before)g(dra)o(wing)208 4976 y(a)g(path)g(you)f(w)o(ant)h(to)h(\002ll,)g(and)e(call)i FJ(fill\(0\))e FN(when)h(you)f(\002nish)i(to)f(dra)o(w)f(the)i(path.)0 5123 y FD(begin_fill)p FJ(\(\))208 5222 y FN(Switch)e(turtle)f(into)h (\002lling)g(mode;)f(Must)h(e)n(v)o(entually)e(be)i(follo)n(wed)f(by)g (a)h(corresponding)d(end)p 2988 5222 25 4 v 29 w(\002ll\(\))j(call.)25 b(Otherwise)18 b(it)i(will)208 5322 y(be)g(ignored.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.5.)p 0 5549 3901 4 v 0 5649 a FI(20.4.)52 b FJ(turtle)22 b FI(\227)h(T)-10 b(ur)s(tle)24 b(g)o(r)o(aphics)f(f)n(or)g(Tk)2323 b(731)p eop end %%Page: 732 744 TeXDict begin 732 743 bop 0 83 a FD(end_fill)p FJ(\(\))208 183 y FN(End)19 b(\002lling)h(mode,)f(and)h(\002ll)h(the)f(shape;)g (equi)n(v)n(alent)e(to)j FJ(fill\(0\))p FN(.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.5.)0 330 y FD(circle)p FJ(\()p FK(r)o(adius)p FC([)p FK(,)g(e)n(xtent)13 b FC(])p FJ(\))208 429 y FN(Dra)o(w)24 b(a)h(circle)g(with)g(radius)f FK(r)o(adius)g FN(whose)h(center)n(-point)e(is)i FK(r)o(adius)g FN(units)f(left)h(of)g (the)g(turtle.)38 b FK(e)n(xtent)26 b FN(determines)e(which)208 529 y(part)19 b(of)h(a)h(circle)f(is)h(dra)o(wn:)j(if)d(not)f(gi)n(v)o (en)e(it)j(def)o(aults)f(to)h(a)f(full)g(circle.)208 662 y(If)k FK(e)n(xtent)i FN(is)g(not)e(a)h(full)g(circle,)g(one)g (endpoint)d(of)j(the)f(arc)h(is)h(the)e(current)g(pen)g(position.)37 b(The)24 b(arc)h(is)h(dra)o(wn)d(in)i(a)g(counter)208 761 y(clockwise)c(direction)f(if)i FK(r)o(adius)g FN(is)g(positi)n(v)o (e,)f(otherwise)g(in)h(a)h(clockwise)e(direction.)28 b(In)22 b(the)f(process,)h(the)g(direction)e(of)i(the)208 861 y(turtle)e(is)h(changed)d(by)i(the)g(amount)f(of)h(the)g FK(e)n(xtent)q FN(.)0 1008 y FD(goto)p FJ(\()p FK(x,)f(y)p FJ(\))0 1107 y FD(goto)p FJ(\()p FK(\(x,)g(y\))p FJ(\))208 1207 y FN(Go)h(to)g(co-ordinates)e FK(x)p FN(,)j FK(y)p FN(.)k(The)20 b(co-ordinates)e(may)i(be)g(speci\002ed)g(either)g(as)h (tw)o(o)f(separate)g(ar)o(guments)e(or)i(as)h(a)f(2-tuple.)0 1354 y FD(towards)p FJ(\()p FK(x,)f(y)p FJ(\))208 1453 y FN(Return)h(the)h(angle)f(of)g(the)h(line)g(from)e(the)i(turtle')-5 b(s)21 b(position)f(to)h(the)f(point)g FK(x)p FN(,)i FK(y)p FN(.)27 b(The)20 b(co-ordinates)f(may)h(be)h(speci\002ed)f (either)208 1553 y(as)g(tw)o(o)h(separate)f(ar)o(guments,)e(as)i(a)h (2-tuple,)e(or)h(as)h(another)d(pen)i(object.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1700 y FD(heading)p FJ(\(\))208 1800 y FN(Return)g(the)i(current)d(orientation)h(of)h(the)g(turtle.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 1946 y FD(setheading)p FJ(\()p FK(angle)p FJ(\))208 2046 y FN(Set)h(the)h(orientation)d(of)i (the)g(turtle)g(to)h FK(angle)p FN(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.3.)0 2193 y FD(position)p FJ(\(\))208 2293 y FN(Return)g(the)i (current)d(location)i(of)g(the)g(turtle)g(as)h(an)f FJ(\(x,y\))g FN(pair)-5 b(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 2439 y FD(setx)p FJ(\()p FK(x)p FJ(\))208 2539 y FN(Set)h(the)h(x)f (coordinate)e(of)i(the)g(turtle)g(to)h FK(x)p FN(.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 2686 y FD(sety)p FJ(\()p FK(y)p FJ(\))208 2786 y FN(Set)h(the)h(y)f(coordinate)e(of)i (the)g(turtle)g(to)h FK(y)p FN(.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f (2.3.)0 2932 y FD(window_width)p FJ(\(\))208 3032 y FN(Return)g(the)i (width)e(of)h(the)g(can)m(v)n(as)g(windo)n(w)-5 b(.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3179 y FD(window_height)p FJ(\(\))208 3279 y FN(Return)g(the)i(height)e(of)h(the)g(can)m(v)n(as)f (windo)n(w)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 3425 y(This)32 b(module)e(also)h(does)g FJ(from)49 b(math)g(import)1657 3440 y(*)1707 3425 y FN(,)34 b(so)e(see)g(the)f(documentation)e(for)i (the)g FJ(math)g FN(module)f(for)h(additional)0 3525 y(constants)20 b(and)f(functions)g(useful)h(for)f(turtle)h(graphics.)0 3672 y FD(demo)p FJ(\(\))208 3772 y FN(Ex)o(ercise)f(the)h(module)f(a)i (bit.)0 3918 y FL(exception)e FD(Error)208 4018 y FN(Exception)f (raised)i(on)g(an)o(y)f(error)g(caught)g(by)h(this)h(module.)0 4165 y(F)o(or)f(e)o(xamples,)f(see)h(the)h(code)e(of)h(the)g FJ(demo\(\))g FN(function.)0 4312 y(This)g(module)f(de\002nes)h(the)g (follo)n(wing)f(classes:)0 4459 y FL(class)i FD(Pen)p FJ(\(\))208 4558 y FN(De\002ne)h(a)i(pen.)32 b(All)24 b(abo)o(v)o(e)d(functions)g(can)i(be)g(called)f(as)i(a)f(methods)f(on)h (the)g(gi)n(v)o(en)e(pen.)33 b(The)22 b(constructor)f(automatically)208 4658 y(creates)f(a)g(can)m(v)n(as)g(do)f(be)i(dra)o(wn)e(on.)0 4805 y FL(class)i FD(Turtle)p FJ(\(\))208 4904 y FN(De\002ne)f(a)g (pen.)25 b(This)20 b(is)h(essentially)f(a)h(synon)o(ym)d(for)i FJ(Pen\(\))p FN(;)f FJ(Turtle)h FN(is)h(an)f(empty)g(subclass)g(of)g FJ(Pen)p FN(.)0 5051 y FL(class)h FD(RawPen)p FJ(\()p FK(can)m(vas)p FJ(\))208 5151 y FN(De\002ne)e(a)h(pen)f(which)g(dra)o (ws)h(on)f(a)h(can)m(v)n(as)f FK(can)m(vas)p FN(.)k(This)d(is)h(useful) e(if)h(you)e(w)o(ant)i(to)g(use)g(the)f(module)g(to)h(create)f (graphics)f(in)208 5251 y(a)i(\223real\224)g(program.)p 0 5549 3901 4 v 0 5649 a FI(732)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 733 745 TeXDict begin 733 744 bop 0 83 a Fv(20.4.1)101 b(T)-12 b(ur)t(tle)o(,)27 b(P)-5 b(en)29 b(and)g(Ra)n(wP)-5 b(en)29 b(Objects)0 286 y FN(Most)20 b(of)g(the)g(global)f(functions)g(a)n(v)n (ailable)g(in)h(the)g(module)f(are)h(also)g(a)n(v)n(ailable)g(as)h (methods)e(of)g(the)h FJ(Turtle)p FN(,)g FJ(Pen)g FN(and)f FJ(RawPen)0 386 y FN(classes,)i(af)n(fecting)e(only)g(the)h(state)h(of) f(the)g(gi)n(v)o(en)f(pen.)0 532 y(The)i(only)g(method)f(which)h(is)h (more)f(po)n(werful)e(as)j(a)g(method)e(is)j FJ(degrees\(\))p FN(,)d(which)h(tak)o(es)h(an)f(optional)f(ar)o(gument)f(letting)i(you)0 632 y(specify)f(the)g(number)e(of)i(units)g(corresponding)d(to)j(a)h (full)f(circle:)0 779 y FD(degrees)p FJ(\()p FC([)p FK(fullcir)m(cle)12 b FC(])p FJ(\))208 879 y FK(fullcir)m(cle)23 b FN(is)i(by)e(def)o(ault) f(360.)34 b(This)24 b(can)f(cause)g(the)h(pen)f(to)g(ha)n(v)o(e)g(an)o (y)g(angular)f(units)h(whate)n(v)o(er:)31 b(gi)n(v)o(e)22 b FK(fullcir)m(cle)i FN(2*)p Ft(\031)i FN(for)208 978 y(radians,)19 b(or)h(400)f(for)h(gradians.)0 1306 y FE(20.5)121 b(Idle)0 1538 y FN(Idle)20 b(is)h(the)f(Python)f(IDE)h(b)n(uilt)h(with) f(the)g FJ(Tkinter)g FN(GUI)g(toolkit.)0 1685 y(IDLE)g(has)g(the)g (follo)n(wing)f(features:)125 1915 y FM(\017)41 b FN(coded)19 b(in)h(100\045)f(pure)h(Python,)e(using)i(the)g FJ(Tkinter)g FN(GUI)g(toolkit)125 2081 y FM(\017)41 b FN(cross-platform:)23 b(w)o(orks)c(on)h(W)m(indo)n(ws)g(and)h(U)t FH(N)t(I)t(X)j FN(\(on)19 b(Mac)h(OS,)h(there)f(are)g(currently)e(problems)h(with)h (Tcl/Tk\))125 2247 y FM(\017)41 b FN(multi-windo)n(w)19 b(te)o(xt)i(editor)f(with)i(multiple)e(undo,)g(Python)g(colorizing)g (and)h(man)o(y)f(other)g(features,)h(e.g.)27 b(smart)22 b(indent)e(and)208 2347 y(call)g(tips)125 2513 y FM(\017)41 b FN(Python)19 b(shell)h(windo)n(w)f(\(a.k.a.)24 b(interacti)n(v)o(e)19 b(interpreter\))125 2679 y FM(\017)41 b FN(deb)n(ugger)18 b(\(not)h(complete,)g(b)n(ut)h(you)f(can)h(set)h(breakpoints,)d(vie)n (w)i(and)g(step\))0 2964 y Fv(20.5.1)101 b(Men)o(us)0 3167 y FI(File)24 b(men)o(u)0 3356 y FL(New)d(windo)o(w)41 b FN(create)20 b(a)h(ne)n(w)f(editing)f(windo)n(w)0 3522 y FL(Open...)41 b FN(open)19 b(an)h(e)o(xisting)f(\002le)0 3688 y FL(Open)i(module...)40 b FN(open)19 b(an)i(e)o(xisting)e(module) g(\(searches)g(sys.path\))0 3854 y FL(Class)i(br)o(o)o(wser)41 b FN(sho)n(w)19 b(classes)j(and)d(methods)h(in)g(current)f(\002le)0 4020 y FL(P)o(ath)h(br)o(o)o(wser)41 b FN(sho)n(w)20 b(sys.path)f(directories,)g(modules,)g(classes)i(and)f(methods)0 4333 y FL(Sa)n(v)o(e)41 b FN(sa)n(v)o(e)20 b(current)f(windo)n(w)g(to)h (the)h(associated)f(\002le)g(\(unsa)n(v)o(ed)f(windo)n(ws)g(ha)n(v)o(e) h(a)h(*)f(before)f(and)g(after)h(the)g(windo)n(w)g(title\))0 4499 y FL(Sa)n(v)o(e)g(As...)41 b FN(sa)n(v)o(e)20 b(current)f(windo)n (w)g(to)i(ne)n(w)f(\002le,)g(which)g(becomes)f(the)h(associated)g (\002le)0 4665 y FL(Sa)n(v)o(e)g(Copy)g(As...)41 b FN(sa)n(v)o(e)20 b(current)f(windo)n(w)g(to)i(dif)n(ferent)d(\002le)j(without)e (changing)g(the)h(associated)g(\002le)0 4895 y FL(Close)41 b FN(close)21 b(current)d(windo)n(w)i(\(asks)g(to)g(sa)n(v)o(e)h(if)f (unsa)n(v)o(ed\))0 5061 y FL(Exit)41 b FN(close)20 b(all)h(windo)n(ws)f (and)f(quit)h(IDLE)g(\(asks)g(to)h(sa)n(v)o(e)f(if)h(unsa)n(v)o(ed\))p 0 5549 3901 4 v 0 5649 a FI(20.5.)52 b(Idle)3393 b(733)p eop end %%Page: 734 746 TeXDict begin 734 745 bop 0 83 a FI(Edit)24 b(men)o(u)0 272 y FL(Undo)41 b FN(Undo)20 b(last)h(change)d(to)j(current)e(windo)n (w)g(\(max)g(1000)g(changes\))0 438 y FL(Redo)41 b FN(Redo)20 b(last)h(undone)d(change)h(to)h(current)f(windo)n(w)0 668 y FL(Cut)41 b FN(Cop)o(y)20 b(selection)g(into)g(system-wide)f (clipboard;)g(then)g(delete)h(selection)0 834 y FL(Copy)41 b FN(Cop)o(y)19 b(selection)h(into)g(system-wide)g(clipboard)0 1000 y FL(P)o(aste)41 b FN(Insert)20 b(system-wide)f(clipboard)f(into)i (windo)n(w)0 1166 y FL(Select)g(All)42 b FN(Select)20 b(the)h(entire)e(contents)h(of)g(the)g(edit)g(b)n(uf)n(fer)0 1396 y FL(Find...)41 b FN(Open)19 b(a)i(search)f(dialog)f(box)g(with)i (man)o(y)e(options)0 1562 y FL(Find)i(again)40 b FN(Repeat)20 b(last)i(search)0 1728 y FL(Find)f(selection)41 b FN(Search)19 b(for)h(the)g(string)g(in)g(the)h(selection)0 1894 y FL(Find)g(in)g(Files...)41 b FN(Open)19 b(a)i(search)f(dialog)f(box)g (for)h(searching)f(\002les)0 2060 y FL(Replace...)40 b FN(Open)20 b(a)g(search-and-replace)d(dialog)i(box)0 2226 y FL(Go)h(to)g(line)41 b FN(Ask)21 b(for)f(a)g(line)g(number)f (and)g(sho)n(w)h(that)h(line)0 2456 y FL(Indent)g(r)o(egion)40 b FN(Shift)20 b(selected)g(lines)h(right)f(4)g(spaces)0 2622 y FL(Dedent)g(r)o(egion)40 b FN(Shift)21 b(selected)f(lines)g (left)h(4)f(spaces)0 2788 y FL(Comment)g(out)g(r)o(egion)40 b FN(Insert)20 b(##)g(in)g(front)f(of)h(selected)g(lines)0 2954 y FL(Uncomment)g(r)o(egion)40 b FN(Remo)o(v)o(e)19 b(leading)g(#)i(or)f(##)f(from)g(selected)i(lines)0 3120 y FL(T)-8 b(abify)20 b(r)o(egion)40 b FN(T)l(urns)20 b FK(leading)f FN(stretches)h(of)g(spaces)h(into)e(tabs)0 3286 y FL(Untabify)g(r)o(egion)40 b FN(T)l(urn)20 b FK(all)g FN(tabs)h(into)f(the)g(right)f(number)g(of)h(spaces)0 3452 y FL(Expand)h(w)o(ord)41 b FN(Expand)23 b(the)h(w)o(ord)g(you)g (ha)n(v)o(e)g(typed)f(to)i(match)f(another)f(w)o(ord)h(in)h(the)g(same) f(b)n(uf)n(fer;)i(repeat)e(to)h(get)f(a)h(dif)n(ferent)208 3552 y(e)o(xpansion)0 3718 y FL(F)n(ormat)19 b(P)o(aragraph)40 b FN(Reformat)19 b(the)h(current)f(blank-line-separated)e(paragraph)0 3948 y FL(Import)j(module)42 b FN(Import)19 b(or)g(reload)h(the)g (current)f(module)0 4114 y FL(Run)i(script)41 b FN(Ex)o(ecute)19 b(the)i(current)d(\002le)j(in)g(the)p 1422 4114 25 4 v 1452 4114 V 80 w(main)p 1649 4114 V 1678 4114 V 79 w(namespace)0 4465 y FI(Windo)o(ws)j(men)o(u)0 4654 y FL(Zoom)c(Height)41 b FN(toggles)19 b(the)h(windo)n(w)g(between)f (normal)g(size)i(\(24x80\))c(and)j(maximum)f(height.)0 4884 y(The)k(rest)g(of)g(this)h(menu)e(lists)j(the)e(names)g(of)f(all)i (open)e(windo)n(ws;)i(select)g(one)f(to)g(bring)f(it)i(to)f(the)g(fore) o(ground)c(\(deiconifying)h(it)k(if)0 4984 y(necessary\).)p 0 5549 3901 4 v 0 5649 a FI(734)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 735 747 TeXDict begin 735 746 bop 0 83 a FI(Deb)n(ug)24 b(men)o(u)g(\(in)f(the) h(Python)f(Shell)i(windo)o(w)e(only\))0 272 y FL(Go)d(to)g(\002le/line) 42 b FN(look)19 b(around)f(the)j(insert)f(point)f(for)h(a)g(\002lename) g(and)g(linenumber)m(,)d(open)i(the)h(\002le,)h(and)f(sho)n(w)g(the)g (line.)0 437 y FL(Open)h(stack)f(viewer)40 b FN(sho)n(w)20 b(the)h(stack)f(traceback)f(of)h(the)g(last)h(e)o(xception)0 603 y FL(Deb)n(ugger)f(toggle)40 b FN(Run)20 b(commands)e(in)j(the)f (shell)g(under)f(the)h(deb)n(ugger)0 769 y FL(JIT)h(Stack)f(viewer)g (toggle)40 b FN(Open)19 b(stack)h(vie)n(wer)g(on)g(traceback)0 1135 y Fv(20.5.2)101 b(Basic)28 b(editing)h(and)g(na)n(vigation)125 1324 y FM(\017)41 b FJ(Backspace)19 b FN(deletes)h(to)g(the)g(left;)h FJ(Del)f FN(deletes)g(to)h(the)f(right)125 1490 y FM(\017)41 b FN(Arro)n(w)19 b(k)o(e)o(ys)h(and)f FJ(Page)49 b(Up)p FN(/)p FJ(Page)g(Down)20 b FN(to)h(mo)o(v)o(e)d(around)125 1655 y FM(\017)41 b FJ(Home)p FN(/)p FJ(End)19 b FN(go)h(to)g(be)o (gin/end)e(of)i(line)125 1821 y FM(\017)41 b FJ(C-Home)p FN(/)p FJ(C-End)18 b FN(go)i(to)g(be)o(gin/end)e(of)i(\002le)125 1987 y FM(\017)41 b FN(Some)19 b FL(Emacs)i FN(bindings)e(may)h(also)g (w)o(ork,)g(including)e FJ(C-B)p FN(,)i FJ(C-P)p FN(,)g FJ(C-A)p FN(,)g FJ(C-E)p FN(,)g FJ(C-D)p FN(,)g FJ(C-L)0 2255 y FI(A)n(utomatic)k(indentation)0 2458 y FN(After)c(a)h (block-opening)c(statement,)j(the)g(ne)o(xt)g(line)h(is)g(indented)e (by)h(4)h(spaces)f(\(in)h(the)f(Python)f(Shell)i(windo)n(w)e(by)i(one)e (tab\).)26 b(After)0 2557 y(certain)e(k)o(e)o(yw)o(ords)f(\(break,)h (return)g(etc.\))38 b(the)25 b(ne)o(xt)f(line)g(is)i(dedented.)37 b(In)24 b(leading)g(indentation,)f FJ(Backspace)h FN(deletes)g(up)h(to) f(4)0 2657 y(spaces)k(if)f(the)o(y)g(are)g(there.)46 b FJ(Tab)27 b FN(inserts)g(1-4)g(spaces)h(\(in)f(the)g(Python)f(Shell)i (windo)n(w)e(one)h(tab\).)45 b(See)28 b(also)g(the)f(indent/dedent)0 2756 y(re)o(gion)19 b(commands)f(in)i(the)h(edit)f(menu.)0 3025 y FI(Python)k(Shell)g(windo)o(w)125 3213 y FM(\017)41 b FJ(C-C)20 b FN(interrupts)f(e)o(x)o(ecuting)f(command)125 3379 y FM(\017)41 b FJ(C-D)20 b FN(sends)g(end-of-\002le;)e(closes)j (windo)n(w)e(if)i(typed)e(at)h(a)h(`)p FJ(>>>)49 b FN(')20 b(prompt)125 3608 y FM(\017)41 b FJ(Alt-p)19 b FN(retrie)n(v)o(es)h (pre)n(vious)e(command)g(matching)h(what)h(you)g(ha)n(v)o(e)f(typed)125 3773 y FM(\017)41 b FJ(Alt-n)19 b FN(retrie)n(v)o(es)h(ne)o(xt)125 3939 y FM(\017)41 b FJ(Return)19 b FN(while)h(on)g(an)o(y)g(pre)n (vious)e(command)g(retrie)n(v)o(es)i(that)g(command)125 4105 y FM(\017)41 b FJ(Alt-/)19 b FN(\(Expand)f(w)o(ord\))i(is)h(also)f (useful)g(here)0 4471 y Fv(20.5.3)101 b(Syntax)28 b(colors)0 4674 y FN(The)22 b(coloring)e(is)j(applied)e(in)h(a)g(background)c (\223thread,)-6 b(\224)22 b(so)g(you)f(may)g(occasionally)g(see)h (uncolorized)e(te)o(xt.)30 b(T)-7 b(o)22 b(change)e(the)i(color)0 4774 y(scheme,)d(edit)i(the)f FJ([Colors])f FN(section)h(in)h(`)p FO(con\002g.txt)p FN('.)0 5003 y FL(Python)e(syntax)h(colors:)40 b(K)n(eyw)o(ords)g FN(orange)208 5135 y FL(Strings)62 b FN(green)208 5268 y FL(Comments)41 b FN(red)208 5400 y FL(De\002nitions)g FN(blue)p 0 5549 3901 4 v 0 5649 a FI(20.5.)52 b(Idle)3393 b(735)p eop end %%Page: 736 748 TeXDict begin 736 747 bop 0 83 a FL(Shell)21 b(colors:)40 b(Console)20 b(output)41 b FN(bro)n(wn)208 216 y FL(stdout)f FN(blue)208 349 y FL(stderr)h FN(dark)19 b(green)208 482 y FL(stdin)41 b FN(black)0 750 y FI(Command)24 b(line)g(usage)0 1044 y FA(idle.py)44 b([-c)g(command])f([-d])i([-e])f([-s])g([-t)g (title])g([arg])g(...)0 1227 y(-c)g(command)89 b(run)44 b(this)g(command)0 1318 y(-d)448 b(enable)44 b(debugger)0 1409 y(-e)448 b(edit)44 b(mode;)g(arguments)f(are)i(files)f(to)g(be)h (edited)0 1501 y(-s)448 b(run)44 b($IDLESTARTUP)f(or)i($PYTHONSTARTUP)d (first)0 1592 y(-t)i(title)179 b(set)44 b(title)g(of)h(shell)f(window)0 1879 y FN(If)20 b(there)g(are)g(ar)o(guments:)104 2108 y(1.)41 b(If)17 b FL(-e)h FN(is)g(used,)g(ar)o(guments)d(are)j(\002les) g(opened)e(for)h(editing)g(and)g FJ(sys.argv)g FN(re\003ects)h(the)f (ar)o(guments)f(passed)h(to)h(IDLE)f(itself.)104 2274 y(2.)41 b(Otherwise,)19 b(if)i FL(-c)f FN(is)h(used,)f(all)h(ar)o (guments)d(are)i(placed)f(in)i FJ(sys.argv[1:...])p FN(,)c(with)k FJ(sys.argv[0])d FN(set)j(to)g FJ('-c')p FN(.)104 2440 y(3.)41 b(Otherwise,)34 b(if)e(neither)g FL(-e)g FN(nor)f FL(-c)h FN(is)h(used,)h(the)f(\002rst)f(ar)o(gument)e(is)j(a)f(script)g (which)g(is)h(e)o(x)o(ecuted)d(with)i(the)g(remaining)208 2540 y(ar)o(guments)24 b(in)i FJ(sys.argv[1:...])41 b FN(and)25 b FJ(sys.argv[0])g FN(set)i(to)f(the)g(script)g(name.)42 b(If)26 b(the)g(script)h(name)e(is)i('-',)g(no)208 2640 y(script)20 b(is)h(e)o(x)o(ecuted)d(b)n(ut)i(an)h(interacti)n(v)o(e)d (Python)h(session)i(is)g(started;)f(the)h(ar)o(guments)d(are)i(still)h (a)n(v)n(ailable)f(in)g FJ(sys.argv)p FN(.)0 2967 y FE(20.6)121 b(Other)34 b(Gr)o(aphical)g(User)g(Interf)l(ace)h(P)-5 b(ac)n(kages)0 3200 y FN(There)19 b(are)h(an)h(number)d(of)i(e)o (xtension)f(widget)g(sets)j(to)e FJ(Tkinter)p FN(.)0 3347 y FK(Python)f(me)m(gawidg)o(ets)0 3446 y Fy(\()p FO(http://pmw)l(.sourcef)n(orge)o(.n)o(et/)-7 b Fy(\))208 3546 y FN(is)19 b(a)h(toolkit)e(for)h(b)n(uilding)e(high-le)n(v)o(el)g (compound)f(widgets)j(in)g(Python)f(using)h(the)g FJ(Tkinter)f FN(module.)23 b(It)c(consists)h(of)e(a)i(set)208 3646 y(of)d(base)g(classes)h(and)f(a)h(library)e(of)h(\003e)o(xible)f(and)h (e)o(xtensible)f(me)o(ga)o(widgets)f(b)n(uilt)j(on)f(this)g (foundation.)22 b(These)17 b(me)o(ga)o(widgets)208 3745 y(include)g(notebooks,)f(combobox)o(es,)f(selection)j(widgets,)g(paned) f(widgets,)h(scrolled)f(widgets,)h(dialog)f(windo)n(ws,)h(etc.)24 b(Also,)208 3845 y(with)c(the)g(Pmw)-5 b(.Blt)20 b(interf)o(ace)g(to)g (BL)-8 b(T)i(,)21 b(the)f(b)n(usy)-5 b(,)19 b(graph,)g(stripchart,)g (tabset)h(and)g(v)o(ector)f(commands)f(are)i(be)h(a)n(v)n(ailable.)208 3978 y(The)j(initial)h(ideas)g(for)f(Pmw)h(were)g(tak)o(en)f(from)g (the)g(Tk)h FJ(itcl)f FN(e)o(xtensions)g FJ([incr)49 b(Tk])25 b FN(by)f(Michael)g(McLennan)f(and)208 4077 y FJ([incr)48 b(Widgets])16 b FN(by)h(Mark)f(Ulferts.)24 b(Se)n(v)o(eral)15 b(of)i(the)g(me)o(ga)o(widgets)d(are)j(direct)f (translations)g(from)g(the)h(itcl)g(to)g(Python.)208 4177 y(It)k(of)n(fers)g(most)g(of)g(the)g(range)g(of)g(widgets)g(that)g FJ([incr)49 b(Widgets])20 b FN(does,)i(and)e(is)j(almost)e(as)h (complete)e(as)i(T)m(ix,)g(lacking)208 4277 y(ho)n(we)n(v)o(er)c(T)m (ix')-5 b(s)20 b(f)o(ast)h FJ(HList)f FN(widget)g(for)f(dra)o(wing)g (trees.)0 4424 y FK(Tkinter3000)g(W)-5 b(idg)o(et)20 b(Construction)g(Kit)h(\(WCK\))0 4523 y Fy(\()p FO(http://tkinter)l (.effbot.or)o(g/)-6 b Fy(\))208 4623 y FN(is)24 b(a)h(library)d(that)i (allo)n(ws)h(you)e(to)h(write)g(ne)n(w)f(Tkinter)g(widgets)h(in)g(pure) f(Python.)35 b(The)23 b(WCK)j(frame)n(w)o(ork)21 b(gi)n(v)o(es)j(you)f (full)208 4722 y(control)d(o)o(v)o(er)h(widget)h(creation,)f (con\002guration,)f(screen)i(appearance,)e(and)i(e)n(v)o(ent)f (handling.)29 b(WCK)24 b(widgets)e(can)g(be)g(v)o(ery)208 4822 y(f)o(ast)g(and)g(light-weight,)f(since)i(the)o(y)e(can)h(operate) g(directly)f(on)h(Python)f(data)h(structures,)g(without)g(ha)n(ving)f (to)h(transfer)g(data)208 4922 y(through)c(the)i(Tk/Tcl)g(layer)-5 b(.)0 5069 y(Other)20 b(GUI)g(packages)f(are)h(also)h(a)n(v)n(ailable)e (for)h(Python:)0 5215 y FK(wxPython)p 0 5549 3901 4 v 0 5649 a FI(736)2030 b(Chapter)23 b(20.)52 b(Gr)o(aphical)24 b(User)e(Interf)n(aces)g(with)i(Tk)p eop end %%Page: 737 749 TeXDict begin 737 748 bop 0 83 a Fy(\()p FO(http://www)l(.wxp)n (ython.org)-6 b Fy(\))208 183 y FN(wxPython)23 b(is)i(a)h (cross-platform)c(GUI)j(toolkit)f(for)g(Python)g(that)h(is)g(b)n(uilt)g (around)e(the)i(popular)e(wxW)m(idgets)h(C)3543 176 y(++)3662 183 y(toolkit.)208 282 y(It)h(pro)o(vides)e(a)j(nati)n(v)o(e)e(look)g (and)g(feel)h(for)g(applications)f(on)g(W)m(indo)n(ws,)i(Mac)f(OS)g(X,) h(and)g(U)t FH(N)t(I)t(X)i FN(systems)e(by)e(using)h(each)208 382 y(platform')-5 b(s)23 b(nati)n(v)o(e)g(widgets)h(where)g(e)n(v)o (er)f(possible,)i(\(GTK+)f(on)i(U)t FH(N)t(I)t(X)r FN(-lik)o(e)f (systems\).)37 b(In)24 b(addition)f(to)i(an)f(e)o(xtensi)n(v)o(e)f(set) 208 482 y(of)j(widgets,)i(wxPython)d(pro)o(vides)h(classes)i(for)e (online)g(documentation)e(and)i(conte)o(xt)g(sensiti)n(v)o(e)g(help,)i (printing,)f(HTML)208 581 y(vie)n(wing,)g(lo)n(w-le)n(v)o(el)g(de)n (vice)f(conte)o(xt)g(dra)o(wing,)i(drag)e(and)h(drop,)h(system)f (clipboard)f(access,)j(an)f(XML-based)e(resource)208 681 y(format)j(and)h(more,)i(including)c(an)j(e)n(v)o(er)e(gro)n(wing)g (library)h(of)g(user)n(-contrib)n(uted)e(modules.)54 b(Both)31 b(the)f(wxW)m(idgets)g(and)208 780 y(wxPython)17 b(projects)h(are)h(under)f(acti)n(v)o(e)g(de)n(v)o(elopment)f(and)h (continuous)f(impro)o(v)o(ement,)f(and)i(ha)n(v)o(e)h(acti)n(v)o(e)f (and)h(helpful)f(user)208 880 y(and)h(de)n(v)o(eloper)f(communities.)0 1027 y FK(wxPython)h(in)i(Action)0 1127 y Fy(\()p FO(http://www)l (.amaz)o(on.com/e)n(x)n(ec/ob)o(ido)o(s/ASIN/)o(193)o(23)o(94)o(62)o(1) -6 b Fy(\))208 1226 y FN(The)19 b(wxPython)g(book,)f(by)i(Noel)g (Rappin)g(and)g(Robin)f(Dunn.)0 1373 y FK(PyQt)208 1473 y FN(PyQt)i(is)i(a)e FL(sip)p FN(-wrapped)f(binding)g(to)i(the)f(Qt)h (toolkit.)28 b(Qt)22 b(is)h(an)e(e)o(xtensi)n(v)o(e)f(C)2500 1466 y(++)2616 1473 y(GUI)h(toolkit)g(that)h(is)g(a)n(v)n(ailable)f (for)i(U)t FH(N)t(I)t(X)r FN(,)208 1572 y(W)m(indo)n(ws)31 b(and)g(Mac)h(OS)h(X.)f FL(sip)h FN(is)g(a)f(tool)g(for)f(generating)f (bindings)h(for)g(C)2605 1565 y(++)2732 1572 y(libraries)g(as)i(Python) e(classes,)k(and)d(is)208 1672 y(speci\002cally)e(designed)f(for)h (Python.)54 b(An)30 b(online)g(manual)f(is)j(a)n(v)n(ailable)e(at)h FO(http://www)l(.opendocspub)n(l)o(ishi)o(ng.)o(com/p)n(yq)o(t/)208 1772 y FN(\(errata)19 b(are)h(located)g(at)g FO(http://www)l(.v)n(aldy) o(as)o(.org/p)n(ytho)o(n/)o(boo)o(k.html)-7 b FN(\).)0 1918 y FK(PyKDE)0 2018 y Fy(\()p FO(http://www)l(.r)q(iv)n (erbankcomputing)o(.co)m(.u)o(k/p)n(ykde)o(/in)o(de)m(x.ph)o(p)h Fy(\))208 2118 y FN(PyKDE)30 b(is)h(a)g FL(sip)p FN(-wrapped)e(interf)o (ace)h(to)g(the)g(KDE)h(desktop)e(libraries.)55 b(KDE)31 b(is)g(a)g(desktop)e(en)m(vironment)f(for)k(U)t FH(N)t(I)t(X)208 2217 y FN(computers;)18 b(the)i(graphical)f(components)f(are)i(based)g (on)g(Qt.)0 2364 y FK(FXPy)0 2464 y Fy(\()p FO(http://fxp)n(y)-7 b(.sourcef)n(orge)o(.n)o(et/)g Fy(\))208 2563 y FN(is)27 b(a)h(Python)e(e)o(xtension)f(module)h(which)g(pro)o(vides)f(an)i (interf)o(ace)g(to)g(the)g FK(FO)m(X)f FN(GUI.)h(FO)m(X)g(is)h(a)g(C) 3200 2556 y(++)3321 2563 y(based)f(T)-7 b(oolkit)26 b(for)208 2663 y(de)n(v)o(eloping)13 b(Graphical)i(User)h(Interf)o(aces)f(easily) h(and)g(ef)n(fecti)n(v)o(ely)-5 b(.)21 b(It)16 b(of)n(fers)f(a)i(wide,) f(and)g(gro)n(wing,)f(collection)g(of)g(Controls,)208 2763 y(and)29 b(pro)o(vides)f(state)j(of)f(the)g(art)g(f)o(acilities)h (such)f(as)g(drag)g(and)f(drop,)i(selection,)h(as)f(well)f(as)h(OpenGL) e(widgets)h(for)g(3D)208 2862 y(graphical)20 b(manipulation.)26 b(FO)m(X)c(also)g(implements)f(icons,)g(images,)h(and)f(user)n(-con)m (v)o(enience)d(features)j(such)g(as)h(status)g(line)208 2962 y(help,)d(and)h(tooltips.)208 3095 y(Ev)o(en)25 b(though)g(FO)m(X)i(of)n(fers)f(a)h(lar)o(ge)e(collection)h(of)g (controls)g(already)-5 b(,)27 b(FO)m(X)g(le)n(v)o(erages)e(C)2943 3088 y(++)3064 3095 y(to)i(allo)n(w)g(programmers)c(to)208 3194 y(easily)i(b)n(uild)g(additional)f(Controls)h(and)g(GUI)h (elements,)g(simply)f(by)g(taking)f(e)o(xisting)h(controls,)g(and)g (creating)g(a)g(deri)n(v)o(ed)208 3294 y(class)c(which)e(simply)h(adds) g(or)g(rede\002nes)f(the)i(desired)e(beha)n(vior)-5 b(.)0 3441 y FK(PyGTK)0 3540 y Fy(\()p FO(http://www)l(.daa.com.au/\230ja)o (mes/softw)n(are)o(/p)m(ygtk/)f Fy(\))208 3640 y FN(is)23 b(a)g(set)g(of)f(bindings)f(for)g(the)i(GTK)f(widget)g(set.)32 b(It)23 b(pro)o(vides)e(an)h(object)g(oriented)f(interf)o(ace)g(that)i (is)g(slightly)f(higher)f(le)n(v)o(el)208 3740 y(than)27 b(the)h(C)g(one.)47 b(It)28 b(automatically)f(does)g(all)h(the)g(type)g (casting)f(and)g(reference)f(counting)g(that)i(you)f(w)o(ould)g(ha)n(v) o(e)g(to)h(do)208 3839 y(normally)18 b(with)i(the)h(C)g(API.)f(There)f (are)i(also)f(bindings)f(to)h(GNOME,)g(and)g(a)g(tutorial)g(is)h(a)n(v) n(ailable.)p 0 5549 3901 4 v 0 5649 a FI(20.6.)52 b(Other)23 b(Gr)o(aphical)g(User)g(Interf)n(ace)f(P)m(ac)n(kages)2016 b(737)p eop end %%Page: 738 750 TeXDict begin 738 749 bop 0 5549 3901 4 v 0 5649 a FI(738)p eop end %%Page: 739 751 TeXDict begin 739 750 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3145 427 y FG(TWENTY)-8 b(ONE)p 0 515 V 2161 978 a FT(Inter)5 b(nationalization)0 1457 y FN(The)18 b(modules)f(described)h(in)g(this) h(chapter)e(help)h(you)g(write)h(softw)o(are)f(that)g(is)i(independent) 15 b(of)j(language)f(and)h(locale)g(by)g(pro)o(viding)0 1556 y(mechanisms)e(for)g(selecting)h(a)g(language)e(to)i(be)g(used)g (in)g(program)e(messages)i(or)f(by)h(tailoring)f(output)f(to)i(match)g (local)g(con)m(v)o(entions.)0 1703 y(The)j(list)h(of)f(modules)f (described)g(in)h(this)h(chapter)e(is:)50 1846 y FD(gettext)98 b FN(Multilingual)19 b(internationalization)e(services.)50 1946 y FD(locale)148 b FN(Internationalization)17 b(services.)0 2249 y FE(21.1)121 b Fx(gettext)32 b FE(\227)g(Multilingual)h(inter)s (nationalization)j(ser)t(vices)0 2481 y FN(The)17 b FJ(gettext)f FN(module)f(pro)o(vides)h(internationalization)e(\(I18N\))h(and)i (localization)e(\(L10N\))h(services)h(for)f(your)g(Python)g(modules)0 2581 y(and)30 b(applications.)57 b(It)31 b(supports)f(both)g(the)h(GNU) g FJ(gettext)g FN(message)f(catalog)h(API)g(and)f(a)i(higher)e(le)n(v)o (el,)j(class-based)d(API)0 2681 y(that)25 b(may)g(be)g(more)g (appropriate)e(for)i(Python)f(\002les.)41 b(The)25 b(interf)o(ace)f (described)g(belo)n(w)h(allo)n(ws)h(you)e(to)i(write)f(your)f(module)g (and)0 2780 y(application)17 b(messages)h(in)g(one)g(natural)f (language,)g(and)g(pro)o(vide)f(a)j(catalog)e(of)h(translated)g (messages)g(for)g(running)d(under)i(dif)n(ferent)0 2880 y(natural)i(languages.)0 3027 y(Some)h(hints)g(on)g(localizing)f(your)g (Python)g(modules)g(and)h(applications)f(are)h(also)g(gi)n(v)o(en.)0 3312 y Fv(21.1.1)101 b(GNU)27 b FP(gettext)h Fv(API)0 3515 y FN(The)21 b FJ(gettext)g FN(module)f(de\002nes)h(the)h(follo)n (wing)e(API,)h(which)g(is)i(v)o(ery)d(similar)i(to)g(the)f(GNU)h FL(gettext)e FN(API.)h(If)h(you)e(use)i(this)g(API)0 3614 y(you)i(will)i(af)n(fect)f(the)g(translation)f(of)h(your)f(entire) g(application)g(globally)-5 b(.)38 b(Often)25 b(this)g(is)h(what)f(you) g(w)o(ant)g(if)g(your)f(application)g(is)0 3714 y(monolingual,)16 b(with)j(the)g(choice)f(of)h(language)e(dependent)f(on)j(the)g(locale)f (of)h(your)e(user)-5 b(.)25 b(If)19 b(you)f(are)g(localizing)g(a)i (Python)d(module,)0 3813 y(or)j(if)g(your)f(application)g(needs)h(to)g (switch)h(languages)d(on)i(the)g(\003y)-5 b(,)20 b(you)g(probably)d(w)o (ant)k(to)f(use)g(the)h(class-based)f(API)g(instead.)0 3960 y FD(bindtextdomain)p FJ(\()p FK(domain)p FC([)p FK(,)c(localedir)e FC(])p FJ(\))208 4060 y FN(Bind)23 b(the)h FK(domain)e FN(to)i(the)g(locale)f(directory)f FK(localedir)r FN(.)35 b(More)23 b(concretely)-5 b(,)22 b FJ(gettext)h FN(will)h(look)f(for)g(binary)g(`)p FO(.mo)p FN(')g(\002les)208 4160 y(for)30 b(the)i(gi)n(v)o(en)e(domain)g(using)h (the)h(path)f(\(on)h(U)t FH(N)t(I)t(X)r FN(\):)49 b(`)p FK(localedir)r FI(/)p FK(langua)o(g)o(e)p FI(/LC)p 2719 4160 25 4 v 26 w(MESSA)n(GES/)p FK(domain)p FI(.mo)p FN(',)34 b(where)208 4259 y FK(langua)o(g)o(es)22 b FN(is)j(searched)f (for)g(in)g(the)h(en)m(vironment)c(v)n(ariables)i(LANGU)m(A)m(GE,)h(LC) p 2681 4259 V 30 w(ALL,)g(LC)p 3024 4259 V 30 w(MESSA)m(GES,)g(and)f (LANG)208 4359 y(respecti)n(v)o(ely)-5 b(.)208 4492 y(If)20 b FK(localedir)h FN(is)g(omitted)f(or)g FJ(None)p FN(,)f(then)h(the)g (current)f(binding)g(for)g FK(domain)g FN(is)i(returned.)2867 4462 y FF(1)0 4639 y FD(bind_textdomain_codeset)p FJ(\()p FK(domain)p FC([)o FK(,)15 b(codeset)e FC(])p FJ(\))208 4738 y FN(Bind)19 b(the)g FK(domain)f FN(to)i FK(codeset)q FN(,)f(changing)f(the)h(encoding)e(of)j(strings)f(returned)f(by)h(the)g FJ(gettext\(\))f FN(f)o(amily)h(of)g(functions.)208 4838 y(If)h FK(codeset)h FN(is)g(omitted,)e(then)h(the)g(current)f(binding)f (is)k(returned.)208 4971 y(Ne)n(w)e(in)g(v)o(ersion)f(2.4.)p 0 5025 1560 4 v 90 5080 a FB(1)120 5104 y FH(The)d(def)o(ault)j(locale) f(directory)h(is)d(system)h(dependent;)j(for)c(e)o(xample,)i(on)e (RedHat)i(Linux)f(it)g(is)f(`)p Ff(/usr/share/locale)p FH(',)k(b)o(ut)c(on)h(Solaris)g(it)g(is)f(`)p Ff(/usr/lib/locale)p FH('.)23 b(The)0 5183 y Fz(gettext)18 b FH(module)i(does)g(not)g(try)g (to)g(support)g(these)h(system)e(dependent)j(def)o(aults;)i(instead)d (its)f(def)o(ault)h(is)f(`)p Fe(sys.prefix)p Ff(/share/locale)p FH('.)29 b(F)o(or)19 b(this)h(reason,)h(it)f(is)0 5262 y(al)o(w)o(ays)f(best)e(to)h(call)g Fz(bindtextdomain\(\))c FH(with)k(an)f(e)o(xplicit)j(absolute)f(path)f(at)g(the)f(start)h(of)f (your)h(application.)p 0 5549 3901 4 v 3762 5649 a FI(739)p eop end %%Page: 740 752 TeXDict begin 740 751 bop 0 83 a FD(textdomain)p FJ(\()p FC([)p FK(domain)12 b FC(])p FJ(\))208 183 y FN(Change)26 b(or)h(query)g(the)g(current)f(global)h(domain.)45 b(If)27 b FK(domain)g FN(is)h FJ(None)p FN(,)h(then)e(the)g(current)g(global)f (domain)g(is)j(returned,)208 282 y(otherwise)19 b(the)h(global)g (domain)e(is)k(set)f(to)f FK(domain)p FN(,)e(which)i(is)h(returned.)0 429 y FD(gettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 529 y FN(Return)e(the)h(localized)f(translation)g(of)g FK(messa)o(g)o(e)p FN(,)h(based)f(on)h(the)g(current)e(global)h (domain,)f(language,)g(and)h(locale)h(directory)-5 b(.)208 628 y(This)20 b(function)e(is)k(usually)d(aliased)h(as)h FJ(_)g FN(in)f(the)g(local)h(namespace)e(\(see)h(e)o(xamples)f(belo)n (w\).)0 775 y FD(lgettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 875 y FN(Equi)n(v)n(alent)c(to)i FJ(gettext\(\))p FN(,)f(b)n(ut)h(the)f(translation)g(is)i(returned)d(in)i(the)g (preferred)e(system)i(encoding,)e(if)i(no)g(other)f(encoding)208 975 y(w)o(as)21 b(e)o(xplicitly)e(set)i(with)f FJ (bind_textdomain_codeset\(\))p FN(.)208 1107 y(Ne)n(w)g(in)g(v)o (ersion)f(2.4.)0 1254 y FD(dgettext)p FJ(\()p FK(domain,)e(messa)o(g)o (e)p FJ(\))208 1354 y FN(Lik)o(e)j FJ(gettext\(\))p FN(,)e(b)n(ut)j (look)e(the)h(message)g(up)g(in)g(the)h(speci\002ed)f FK(domain)p FN(.)0 1501 y FD(ldgettext)p FJ(\()p FK(domain,)d(messa)o (g)o(e)p FJ(\))208 1600 y FN(Equi)n(v)n(alent)f(to)j FJ(dgettext\(\))p FN(,)f(b)n(ut)g(the)h(translation)f(is)i(returned)c (in)j(the)g(preferred)d(system)j(encoding,)e(if)i(no)f(other)g(encod-) 208 1700 y(ing)h(w)o(as)i(e)o(xplicitly)f(set)h(with)f FJ(bind_textdomain_codeset\(\))p FN(.)208 1833 y(Ne)n(w)g(in)g(v)o (ersion)f(2.4.)0 1980 y FD(ngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)j(n)p FJ(\))208 2079 y FN(Lik)o(e)g FJ(gettext\(\))p FN(,)e(b)n(ut)j(consider)e(plural)g(forms.)24 b(If)c(a)h(translation)e(is)i(found,)d(apply)i(the)g(plural)f(formula)g (to)h FK(n)p FN(,)g(and)g(return)208 2179 y(the)29 b(resulting)f (message)h(\(some)g(languages)e(ha)n(v)o(e)i(more)f(than)h(tw)o(o)g (plural)g(forms\).)50 b(If)29 b(no)g(translation)f(is)i(found,)g (return)208 2279 y FK(singular)21 b FN(if)f FK(n)h FN(is)g(1;)f(return) f FK(plur)o(al)h FN(otherwise.)208 2411 y(The)e(Plural)h(formula)f(is)i (tak)o(en)f(from)f(the)h(catalog)f(header)-5 b(.)24 b(It)19 b(is)h(a)g(C)g(or)f(Python)f(e)o(xpression)f(that)i(has)h(a)f(free)g(v) n(ariable)f FK(n)p FN(;)i(the)208 2511 y(e)o(xpression)c(e)n(v)n (aluates)h(to)i(the)f(inde)o(x)e(of)i(the)g(plural)f(in)i(the)f (catalog.)23 b(See)c(the)f(GNU)g(gette)o(xt)f(documentation)e(for)j (the)g(precise)208 2611 y(syntax)h(to)h(be)h(used)e(in)i(`)p FO(.po)p FN(')e(\002les)i(and)f(the)g(formulas)f(for)g(a)i(v)n(ariety)e (of)h(languages.)208 2743 y(Ne)n(w)g(in)g(v)o(ersion)f(2.3.)0 2890 y FD(lngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)i(n)p FJ(\))208 2990 y FN(Equi)n(v)n(alent)d(to)j FJ(ngettext\(\))p FN(,)f(b)n(ut)g(the)h(translation)f(is)i(returned)c(in)j(the)g (preferred)d(system)j(encoding,)e(if)i(no)f(other)g(encod-)208 3090 y(ing)h(w)o(as)i(e)o(xplicitly)f(set)h(with)f FJ (bind_textdomain_codeset\(\))p FN(.)208 3222 y(Ne)n(w)g(in)g(v)o (ersion)f(2.4.)0 3369 y FD(dngettext)p FJ(\()p FK(domain,)e(singular)-9 b(,)19 b(plur)o(al,)g(n)p FJ(\))208 3469 y FN(Lik)o(e)h FJ(ngettext\(\))p FN(,)e(b)n(ut)i(look)g(the)g(message)g(up)g(in)g(the) g(speci\002ed)g FK(domain)p FN(.)208 3602 y(Ne)n(w)g(in)g(v)o(ersion)f (2.3.)0 3749 y FD(ldngettext)p FJ(\()p FK(domain,)e(singular)-9 b(,)19 b(plur)o(al,)g(n)p FJ(\))208 3848 y FN(Equi)n(v)n(alent)29 b(to)j FJ(dngettext\(\))p FN(,)g(b)n(ut)f(the)h(translation)e(is)j (returned)c(in)j(the)f(preferred)e(system)j(encoding,)g(if)f(no)g (other)208 3948 y(encoding)18 b(w)o(as)j(e)o(xplicitly)e(set)i(with)f FJ(bind_textdomain_codeset\(\))p FN(.)208 4081 y(Ne)n(w)g(in)g(v)o (ersion)f(2.4.)0 4228 y(Note)k(that)h(GNU)g FL(gettext)d FN(also)j(de\002nes)f(a)h FJ(dcgettext\(\))e FN(method,)h(b)n(ut)g (this)h(w)o(as)g(deemed)e(not)h(useful)g(and)g(so)h(it)g(is)g (currently)0 4327 y(unimplemented.)0 4474 y(Here')-5 b(s)20 b(an)h(e)o(xample)d(of)i(typical)g(usage)g(for)f(this)i(API:)236 4712 y FA(import)44 b(gettext)236 4804 y (gettext.bindtextdomain\('myapplication',)38 b ('/path/to/my/language/directory'\))236 4895 y (gettext.textdomain\('myapplication'\))236 4986 y(_)45 b(=)g(gettext.gettext)236 5078 y(#)g(...)236 5169 y(print)f(_\('This)g (is)g(a)h(translatable)e(string.'\))p 0 5549 3901 4 v 0 5649 a FI(740)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 741 753 TeXDict begin 741 752 bop 0 83 a Fv(21.1.2)101 b(Class-based)29 b(API)0 286 y FN(The)i(class-based)h(API)g(of)f(the)h FJ(gettext)f FN(module)f(gi)n(v)o(es)i(you)f(more)f(\003e)o(xibility)h (and)h(greater)e(con)m(v)o(enience)f(than)i(the)h(GNU)0 386 y FL(gettext)d FN(API.)i(It)g(is)h(the)f(recommended)d(w)o(ay)j(of) g(localizing)f(your)f(Python)h(applications)g(and)g(modules.)57 b FJ(gettext)30 b FN(de\002nes)0 485 y(a)23 b(\223translations\224)f (class)i(which)e(implements)g(the)h(parsing)e(of)i(GNU)g(`)p FO(.mo)p FN(')f(format)g(\002les,)i(and)e(has)h(methods)f(for)g (returning)f(either)0 585 y(standard)16 b(8-bit)g(strings)h(or)f (Unicode)g(strings.)24 b(Instances)16 b(of)h(this)g (\223translations\224)f(class)i(can)f(also)g(install)g(themselv)o(es)f (in)h(the)g(b)n(uilt-in)0 684 y(namespace)i(as)i(the)f(function)f FJ(_\(\))p FN(.)0 831 y FD(find)p FJ(\()p FK(domain)p FC([)p FK(,)e(localedir)r FC([)p FK(,)i(langua)o(g)o(es)p FC([)p FK(,)f(all)12 b FC(])g(])g(])p FJ(\))208 931 y FN(This)37 b(function)f(implements)h(the)h(standard)e(`)p FO(.mo)p FN(')h(\002le)h(search)g(algorithm.)75 b(It)38 b(tak)o(es)g(a)g FK(domain)p FN(,)j(identical)c(to)h(what)208 1031 y FJ(textdomain\(\))29 b FN(tak)o(es.)56 b(Optional)30 b FK(localedir)i FN(is)g(as)f(in)g FJ(bindtextdomain\(\))d FN(Optional)i FK(langua)o(g)o(es)f FN(is)j(a)f(list)h(of)208 1130 y(strings,)19 b(where)h(each)g(string)g(is)h(a)g(language)d(code.) 208 1263 y(If)25 b FK(localedir)h FN(is)g(not)f(gi)n(v)o(en,)g(then)f (the)h(def)o(ault)g(system)g(locale)g(directory)e(is)j(used.)2669 1233 y FF(2)2742 1263 y FN(If)f FK(langua)o(g)o(es)e FN(is)j(not)f(gi)n(v)o(en,)g(then)g(the)208 1363 y(follo)n(wing)18 b(en)m(vironment)f(v)n(ariables)i(are)i(searched:)j(LANGU)m(A)m(GE,)19 b(LC)p 2373 1363 25 4 v 30 w(ALL,)h(LC)p 2712 1363 V 30 w(MESSA)m(GES,)f(and)h(LANG.)g(The)g(\002rst)208 1462 y(one)e(returning)f(a)i(non-empty)d(v)n(alue)i(is)i(used)f(for)f(the)h FK(langua)o(g)o(es)e FN(v)n(ariable.)23 b(The)c(en)m(vironment)c(v)n (ariables)j(should)g(contain)g(a)208 1562 y(colon)h(separated)g(list)i (of)f(languages,)f(which)g(will)i(be)f(split)h(on)f(the)g(colon)f(to)i (produce)d(the)i(e)o(xpected)f(list)i(of)f(language)e(code)208 1662 y(strings.)208 1794 y FJ(find\(\))j FN(then)g(e)o(xpands)g(and)g (normalizes)g(the)h(languages,)f(and)g(then)h(iterates)g(through)e (them,)h(searching)g(for)g(an)h(e)o(xisting)208 1894 y(\002le)e(b)n(uilt)h(of)f(these)g(components:)208 2027 y(`)p FK(localedir)r FI(/)p FK(langua)o(g)o(e)p FI(/LC)p 1006 2027 V 25 w(MESSA)n(GES/)p FK(domain)p FI(.mo)p FN(')208 2160 y(The)27 b(\002rst)h(such)g(\002le)g(name)f(that)h(e)o (xists)g(is)h(returned)d(by)h FJ(find\(\))p FN(.)47 b(If)28 b(no)f(such)h(\002le)g(is)h(found,)e(then)g FJ(None)h FN(is)h(returned.)208 2259 y(If)d FK(all)g FN(is)h(gi)n(v)o(en,)f(it)h (returns)e(a)i(list)g(of)f(all)h(\002le)g(names,)g(in)f(the)g(order)f (in)h(which)g(the)o(y)f(appear)g(in)i(the)f(languages)e(list)k(or)e (the)208 2359 y(en)m(vironment)17 b(v)n(ariables.)0 2506 y FD(translation)p FJ(\()p FK(domain)p FC([)p FK(,)f(localedir)r FC([)p FK(,)j(langua)o(g)o(es)p FC([)p FK(,)f(class)p 1903 2506 V 30 w FC([)p FK(,)i(fallbac)n(k)q FC([)p FK(,)g(codeset)13 b FC(])f(])g(])g(])g(])p FJ(\))208 2605 y FN(Return)25 b(a)g FJ(Translations)f FN(instance)h(based)g(on)g(the)h FK(domain)p FN(,)f FK(localedir)r FN(,)h(and)f FK(langua)o(g)o(es)p FN(,)g(which)f(are)i(\002rst)g(passed)f(to)208 2705 y FJ(find\(\))17 b FN(to)i(get)f(a)h(list)h(of)e(the)g(associated)h(`)p FO(.mo)p FN(')e(\002le)j(paths.)k(Instances)18 b(with)g(identical)g(`)p FO(.mo)p FN(')g(\002le)h(names)f(are)h(cached.)k(The)208 2805 y(actual)i(class)i(instantiated)e(is)i(either)e FK(class)p 1497 2805 V 57 w FN(if)h(pro)o(vided,)e(otherwise)h FJ(GNUTranslations)p FN(.)40 b(The)25 b(class')-5 b(s)27 b(constructor)208 2904 y(must)c(tak)o(e)h(a)f(single)h(\002le)g(object) f(ar)o(gument.)32 b(If)23 b(pro)o(vided,)f FK(codeset)i FN(will)h(change)d(the)h(charset)g(used)g(to)h(encode)e(translated)208 3004 y(strings.)208 3137 y(If)32 b(multiple)h(\002les)h(are)f(found,)h (later)f(\002les)h(are)f(used)g(as)h(f)o(allbacks)e(for)h(earlier)f (ones.)63 b(T)-7 b(o)34 b(allo)n(w)f(setting)g(the)g(f)o(allback,)208 3236 y FJ(copy.copy)27 b FN(is)j(used)f(to)g(clone)f(each)h (translation)f(object)g(from)g(the)h(cache;)k(the)28 b(actual)h(instance)g(data)f(is)i(still)g(shared)208 3336 y(with)20 b(the)g(cache.)208 3469 y(If)j(no)g(`)p FO(.mo)p FN(')g(\002le)h(is)g(found,)f(this)h(function)d(raises)j FJ(IOError)f FN(if)h FK(fallbac)n(k)g FN(is)g(f)o(alse)g(\(which)f(is)h (the)g(def)o(ault\),)f(and)g(returns)f(a)208 3568 y FJ (NullTranslations)17 b FN(instance)j(if)h FK(fallbac)n(k)g FN(is)g(true.)208 3701 y(Changed)d(in)j(v)o(ersion)e(2.4:)g(Added)g (the)i FK(codeset)g FN(parameter)-5 b(.)0 3848 y FD(install)p FJ(\()p FK(domain)p FC([)p FK(,)17 b(localedir)r FC([)p FK(,)i(unicode)g FC([)p FK(,)h(codeset)q FC([)p FK(,)g(names)12 b FC(])g(])g(])g(])p FJ(\))208 3948 y FN(This)31 b(installs)h(the)g (function)e FJ(_)h FN(in)h(Python')-5 b(s)31 b(b)n(uiltin)g(namespace,) i(based)e(on)g FK(domain)p FN(,)h FK(localedir)r FN(,)i(and)d FK(codeset)h FN(which)208 4047 y(are)25 b(passed)g(to)g(the)g(function) e FJ(translation\(\))p FN(.)38 b(The)25 b FK(unicode)f FN(\003ag)h(is)h(passed)f(to)g(the)g(resulting)g(translation)f(object') -5 b(s)208 4147 y FJ(install)19 b FN(method.)208 4280 y(F)o(or)g(the)i FK(names)e FN(parameter)m(,)g(please)h(see)h(the)f (description)e(of)i(the)h(translation)e(object')-5 b(s)20 b FJ(install)f FN(method.)208 4413 y(As)h(seen)h(belo)n(w)-5 b(,)19 b(you)g(usually)g(mark)h(the)g(strings)g(in)g(your)f (application)g(that)h(are)g(candidates)f(for)h(translation,)f(by)g (wrapping)208 4512 y(them)g(in)i(a)f(call)h(to)f(the)h FJ(_\(\))f FN(function,)e(lik)o(e)i(this:)444 4737 y FA(print)44 b(_\('This)f(string)h(will)g(be)h(translated.'\))208 4926 y FN(F)o(or)20 b(con)m(v)o(enience,)d(you)i(w)o(ant)i(the)f FJ(_\(\))h FN(function)e(to)h(be)h(installed)f(in)h(Python')-5 b(s)19 b(b)n(uiltin)h(namespace,)g(so)g(it)i(is)f(easily)g(acces-)208 5026 y(sible)f(in)g(all)h(modules)e(of)h(your)f(application.)208 5158 y(Changed)f(in)j(v)o(ersion)e(2.4:)g(Added)g(the)i FK(codeset)g FN(parameter)-5 b(.)75 b(Changed)19 b(in)h(v)o(ersion)f (2.5:)h(Added)f(the)h FK(names)g FN(parameter)-5 b(.)p 0 5230 1560 4 v 90 5285 a FB(2)120 5309 y FH(See)17 b(the)h(footnote)h (for)e Fz(bindtextdomain\(\))d FH(abo)o(v)o(e.)p 0 5549 3901 4 v 0 5649 a FI(21.1.)52 b FJ(gettext)22 b FI(\227)h(Multilingual) j(inter)r(nationalization)h(ser)r(vices)1584 b(741)p eop end %%Page: 742 754 TeXDict begin 742 753 bop 0 83 a FI(The)23 b FJ(NullTranslations)d FI(class)0 286 y FN(T)m(ranslation)26 b(classes)j(are)e(what)h (actually)f(implement)f(the)i(translation)e(of)h(original)g(source)g (\002le)h(message)f(strings)h(to)f(translated)0 386 y(message)18 b(strings.)24 b(The)18 b(base)h(class)g(used)f(by)g(all)h(translation)e (classes)j(is)f FJ(NullTranslations)p FN(;)e(this)h(pro)o(vides)f(the)h (basic)h(inter)n(-)0 485 y(f)o(ace)h(you)f(can)h(use)h(to)f(write)h (your)d(o)n(wn)i(specialized)g(translation)f(classes.)26 b(Here)20 b(are)g(the)g(methods)g(of)f FJ(NullTranslations)p FN(:)0 632 y FD(__init__)p FJ(\()p FC([)p FK(fp)12 b FC(])p FJ(\))208 732 y FN(T)-7 b(ak)o(es)26 b(an)h(optional)e(\002le)i (object)f FK(fp)p FN(,)i(which)e(is)h(ignored)e(by)h(the)g(base)h (class.)44 b(Initializes)27 b(\223protected\224)d(instance)i(v)n (ariables)p 208 831 25 4 v 232 831 a FK(info)20 b FN(and)p 527 831 V 49 w FK(c)o(har)o(set)h FN(which)e(are)g(set)h(by)f(deri)n(v) o(ed)f(classes,)j(as)f(well)g(as)p 2259 831 V 50 w FK(fallbac)n(k)q FN(,)f(which)g(is)i(set)f(through)d FJ(add_fallback)p FN(.)208 931 y(It)j(then)g(calls)h FJ(self._parse\(fp\))d FN(if)i FK(fp)g FN(is)i(not)d FJ(None)p FN(.)0 1078 y FD(_parse)p FJ(\()p FK(fp)p FJ(\))208 1177 y FN(No-op')l(d)14 b(in)i(the)h(base)f(class,)i(this)f(method)e(tak)o(es)i(\002le)g (object)f FK(fp)p FN(,)h(and)f(reads)g(the)h(data)f(from)f(the)i (\002le,)g(initializing)f(its)i(message)208 1277 y(catalog.)24 b(If)c(you)f(ha)n(v)o(e)h(an)g(unsupported)e(message)i(catalog)f (\002le)i(format,)e(you)h(should)f(o)o(v)o(erride)f(this)j(method)d(to) j(parse)f(your)208 1377 y(format.)0 1524 y FD(add_fallback)p FJ(\()p FK(fallbac)n(k)q FJ(\))208 1623 y FN(Add)26 b FK(fallbac)n(k)i FN(as)f(the)g(f)o(allback)f(object)h(for)f(the)h (current)f(translation)g(object.)44 b(A)28 b(translation)e(object)g (should)g(consult)h(the)208 1723 y(f)o(allback)19 b(if)h(it)h(cannot)e (pro)o(vide)g(a)h(translation)f(for)h(a)h(gi)n(v)o(en)d(message.)0 1870 y FD(gettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 1969 y FN(If)30 b(a)i(f)o(allback)e(has)h(been)f(set,)k(forw)o(ard)29 b FJ(gettext\(\))h FN(to)h(the)g(f)o(allback.)56 b(Otherwise,)33 b(return)d(the)h(translated)f(message.)208 2069 y(Ov)o(erridden)17 b(in)j(deri)n(v)o(ed)f(classes.)0 2216 y FD(lgettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 2315 y FN(If)27 b(a)i(f)o(allback)e(has)h(been)g(set,)i(forw)o(ard)d FJ(lgettext\(\))f FN(to)j(the)f(f)o(allback.)47 b(Otherwise,)30 b(return)d(the)h(translated)f(message.)208 2415 y(Ov)o(erridden)17 b(in)j(deri)n(v)o(ed)f(classes.)208 2548 y(Ne)n(w)h(in)g(v)o(ersion)f (2.4.)0 2695 y FD(ugettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 2794 y FN(If)h(a)h(f)o(allback)f(has)h(been)f(set,)i(forw)o (ard)d FJ(ugettext\(\))g FN(to)i(the)g(f)o(allback.)k(Otherwise,)c (return)e(the)i(translated)f(message)h(as)g(a)208 2894 y(Unicode)e(string.)24 b(Ov)o(erridden)18 b(in)i(deri)n(v)o(ed)f (classes.)0 3041 y FD(ngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)j(n)p FJ(\))208 3141 y FN(If)27 b(a)i(f)o(allback)e (has)h(been)g(set,)i(forw)o(ard)d FJ(ngettext\(\))f FN(to)j(the)f(f)o (allback.)47 b(Otherwise,)30 b(return)d(the)h(translated)f(message.)208 3240 y(Ov)o(erridden)17 b(in)j(deri)n(v)o(ed)f(classes.)208 3373 y(Ne)n(w)h(in)g(v)o(ersion)f(2.3.)0 3520 y FD(lngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)i(n)p FJ(\))208 3619 y FN(If)27 b(a)i(f)o(allback)e(has)h(been)g(set,)i(forw)o(ard)d FJ(ngettext\(\))f FN(to)j(the)f(f)o(allback.)47 b(Otherwise,)30 b(return)d(the)h(translated)f(message.)208 3719 y(Ov)o(erridden)17 b(in)j(deri)n(v)o(ed)f(classes.)208 3852 y(Ne)n(w)h(in)g(v)o(ersion)f (2.4.)0 3999 y FD(ungettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)i(n)p FJ(\))208 4098 y FN(If)i(a)g(f)o(allback)f (has)i(been)e(set,)i(forw)o(ard)e FJ(ungettext\(\))g FN(to)h(the)g(f)o(allback.)27 b(Otherwise,)21 b(return)f(the)h (translated)g(message)g(as)208 4198 y(a)f(Unicode)f(string.)25 b(Ov)o(erridden)17 b(in)k(deri)n(v)o(ed)d(classes.)208 4331 y(Ne)n(w)i(in)g(v)o(ersion)f(2.3.)0 4478 y FD(info)p FJ(\(\))208 4577 y FN(Return)g(the)i(\223protected\224)d FJ(_info)i FN(v)n(ariable.)0 4724 y FD(charset)p FJ(\(\))208 4824 y FN(Return)f(the)i(\223protected\224)d FJ(_charset)h FN(v)n(ariable.)0 4971 y FD(output_charset)p FJ(\(\))208 5070 y FN(Return)29 b(the)h(\223protected\224)e FJ(_output_charset)f FN(v)n(ariable,)k(which)f(de\002nes)f(the)h(encoding)e(used)i(to)g (return)e(translated)208 5170 y(messages.)208 5303 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)p 0 5549 3901 4 v 0 5649 a FI(742)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 743 755 TeXDict begin 743 754 bop 0 83 a FD(set_output_charset)p FJ(\()p FK(c)o(har)o(set)q FJ(\))208 183 y FN(Change)26 b(the)i(\223protected\224)e FJ(_output_charset)f FN(v)n(ariable,)j (which)f(de\002nes)h(the)f(encoding)f(used)h(to)h(return)e(translated) 208 282 y(messages.)208 411 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)0 558 y FD(install)p FJ(\()p FC([)p FK(unicode)e FC([)p FK(,)j(names)12 b FC(])g(])p FJ(\))208 657 y FN(If)23 b(the)h FK(unicode)e FN(\003ag)i(is)h(f)o(alse,)g(this)f(method)f (installs)h FJ(self.gettext\(\))e FN(into)i(the)f(b)n(uilt-in)h (namespace,)f(binding)f(it)i(to)208 757 y(`)p FJ(_)p FN('.)g(If)c FK(unicode)f FN(is)i(true,)f(it)g(binds)g FJ(self.ugettext\(\))e FN(instead.)25 b(By)20 b(def)o(ault,)g FK(unicode)e FN(is)j(f)o(alse.)208 886 y(If)g(the)h FK(names)g FN(parameter)e(is)j(gi)n(v)o(en,)d(it)j(must)f(be)f(a)i(sequence)d (containing)g(the)i(names)f(of)h(functions)e(you)h(w)o(ant)h(to)g (install)g(in)208 985 y(the)i(b)n(uiltin)g(namespace)g(in)g(addition)g (to)g FJ(_\(\))p FN(.)38 b(Supported)23 b(names)h(are)g FJ('gettext')g FN(\(bound)e(to)j FJ(self.gettext\(\))208 1085 y FN(or)k FJ(self.ugettext\(\))e FN(according)g(to)j(the)f FK(unicode)f FN(\003ag\),)k FJ('ngettext')c FN(\(bound)f(to)j FJ(self.ngettext\(\))d FN(or)208 1185 y FJ(self.ungettext\(\))17 b FN(according)h(to)j(the)f FK(unicode)f FN(\003ag\),)g FJ('lgettext')g FN(and)h FJ('lngettext')p FN(.)208 1313 y(Note)27 b(that)g(this)h(is)g(only)f(one)f(w)o(ay)-5 b(,)29 b(albeit)e(the)h(most)f(con)m(v)o(enient)d(w)o(ay)-5 b(,)29 b(to)e(mak)o(e)g(the)g FJ(_)h FN(function)e(a)n(v)n(ailable)h (to)g(your)f(ap-)208 1413 y(plication.)41 b(Because)26 b(it)h(af)n(fects)f(the)g(entire)g(application)e(globally)-5 b(,)26 b(and)f(speci\002cally)h(the)g(b)n(uilt-in)f(namespace,)h (localized)208 1512 y(modules)19 b(should)g(ne)n(v)o(er)g(install)h FJ(_)p FN(.)26 b(Instead,)19 b(the)o(y)g(should)h(use)g(this)h(code)e (to)i(mak)o(e)e FJ(_)i FN(a)n(v)n(ailable)f(to)g(their)g(module:)444 1732 y FA(import)44 b(gettext)444 1824 y(t)g(=)h (gettext.translation\('mymodule',)40 b(...\))444 1915 y(_)k(=)h(t.gettext)208 2100 y FN(This)20 b(puts)g FJ(_)h FN(only)e(in)h(the)h(module')-5 b(s)19 b(global)g(namespace)g(and)h(so) g(only)g(af)n(fects)g(calls)g(within)g(this)h(module.)208 2229 y(Changed)d(in)j(v)o(ersion)e(2.5:)g(Added)g(the)i FK(names)f FN(parameter)-5 b(.)0 2494 y FI(The)23 b FJ(GNUTranslations) d FI(class)0 2696 y FN(The)26 b FJ(gettext)g FN(module)f(pro)o(vides)f (one)i(additional)f(class)i(deri)n(v)o(ed)e(from)g FJ(NullTranslations) p FN(:)35 b FJ(GNUTranslations)p FN(.)0 2796 y(This)19 b(class)h(o)o(v)o(errides)c FJ(_parse\(\))i FN(to)h(enable)f(reading)f (GNU)i FL(gettext)e FN(format)h(`)p FO(.mo)p FN(')g(\002les)i(in)e (both)g(big-endian)f(and)h(little-endian)0 2896 y(format.)24 b(It)c(also)h(coerces)e(both)h(message)g(ids)g(and)g(message)g(strings) g(to)h(Unicode.)0 3043 y FJ(GNUTranslations)f FN(parses)j(optional)e (meta-data)g(out)i(of)f(the)g(translation)g(catalog.)31 b(It)23 b(is)h(con)m(v)o(ention)19 b(with)k(GNU)g FL(gettext)d FN(to)0 3142 y(include)14 b(meta-data)h(as)h(the)f(translation)g(for)g (the)g(empty)f(string.)23 b(This)16 b(meta-data)e(is)j(in)e(RFC)i (822-style)d FJ(key:)99 b(value)15 b FN(pairs,)h(and)0 3242 y(should)i(contain)h(the)g FJ(Project-Id-Version)e FN(k)o(e)o(y)-5 b(.)24 b(If)19 b(the)h(k)o(e)o(y)f FJ(Content-Type)e FN(is)k(found,)c(then)i(the)h FJ(charset)f FN(property)0 3341 y(is)30 b(used)f(to)h(initialize)f(the)h(\223protected\224)d FJ(_charset)i FN(instance)g(v)n(ariable,)h(def)o(aulting)e(to)h FJ(None)g FN(if)h(not)f(found.)50 b(If)30 b(the)f(charset)0 3441 y(encoding)20 b(is)i(speci\002ed,)g(then)f(all)i(message)e(ids)h (and)g(message)f(strings)h(read)f(from)g(the)h(catalog)f(are)g(con)m(v) o(erted)f(to)h(Unicode)g(using)0 3541 y(this)f(encoding.)i(The)d FJ(ugettext\(\))f FN(method)g(al)o(w)o(ays)i(returns)e(a)i(Unicode,)e (while)i(the)f FJ(gettext\(\))f FN(returns)g(an)i(encoded)d(8-bit)0 3640 y(string.)23 b(F)o(or)15 b(the)g(message)g(id)h(ar)o(guments)d(of) i(both)f(methods,)h(either)g(Unicode)f(strings)h(or)g(8-bit)g(strings)g (containing)e(only)h(US-ASCII)0 3740 y(characters)k(are)h(acceptable.)k (Note)c(that)g(the)g(Unicode)e(v)o(ersion)h(of)h(the)g(methods)e (\(i.e.)25 b FJ(ugettext\(\))17 b FN(and)i FJ(ungettext\(\))p FN(\))e(are)0 3840 y(the)j(recommended)d(interf)o(ace)j(to)g(use)g(for) g(internationalized)e(Python)h(programs.)0 3986 y(The)h(entire)g(set)h (of)f(k)o(e)o(y/v)n(alue)e(pairs)i(are)g(placed)g(into)g(a)g (dictionary)f(and)g(set)i(as)g(the)f(\223protected\224)f FJ(_info)h FN(instance)f(v)n(ariable.)0 4133 y(If)40 b(the)h(`)p FO(.mo)p FN(')f(\002le')-5 b(s)42 b(magic)e(number)f(is)i (in)m(v)n(alid,)j(or)d(if)f(other)g(problems)f(occur)h(while)h(reading) e(the)h(\002le,)46 b(instantiating)40 b(a)0 4233 y FJ(GNUTranslations) 18 b FN(class)j(can)f(raise)h FJ(IOError)p FN(.)0 4380 y(The)f(follo)n(wing)e(methods)i(are)g(o)o(v)o(erridden)d(from)i(the)h (base)g(class)h(implementation:)0 4527 y FD(gettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 4626 y FN(Look)g(up)i(the)g FK(messa)o(g)o(e)h FN(id)f(in)g(the)g(catalog)g(and)f(return)g(the)h (corresponding)d(message)j(string,)g(as)h(an)f(8-bit)g(string)f (encoded)208 4726 y(with)30 b(the)f(catalog')-5 b(s)30 b(charset)f(encoding,)h(if)g(kno)n(wn.)53 b(If)29 b(there)h(is)g(no)g (entry)f(in)h(the)g(catalog)f(for)g(the)h FK(messa)o(g)o(e)g FN(id,)i(and)d(a)208 4826 y(f)o(allback)21 b(has)h(been)f(set,)i(the)f (look)f(up)g(is)i(forw)o(arded)d(to)i(the)g(f)o(allback')-5 b(s)21 b FJ(gettext\(\))g FN(method.)29 b(Otherwise,)21 b(the)h FK(messa)o(g)o(e)208 4925 y FN(id)e(is)h(returned.)0 5072 y FD(lgettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 5172 y FN(Equi)n(v)n(alent)15 b(to)i FJ(gettext\(\))p FN(,)f(b)n(ut)h(the)f(translation)g(is)i(returned)d(in)i(the)g (preferred)e(system)i(encoding,)e(if)i(no)g(other)f(encoding)208 5271 y(w)o(as)21 b(e)o(xplicitly)e(set)i(with)f FJ (set_output_charset\(\))p FN(.)208 5400 y(Ne)n(w)g(in)g(v)o(ersion)f (2.4.)p 0 5549 3901 4 v 0 5649 a FI(21.1.)52 b FJ(gettext)22 b FI(\227)h(Multilingual)j(inter)r(nationalization)h(ser)r(vices)1584 b(743)p eop end %%Page: 744 756 TeXDict begin 744 755 bop 0 83 a FD(ugettext)p FJ(\()p FK(messa)o(g)o(e)p FJ(\))208 183 y FN(Look)27 b(up)h(the)g FK(messa)o(g)o(e)h FN(id)f(in)h(the)f(catalog)g(and)g(return)f(the)h (corresponding)d(message)j(string,)i(as)f(a)g(Unicode)f(string.)49 b(If)208 282 y(there)22 b(is)j(no)e(entry)f(in)i(the)f(catalog)g(for)f (the)i FK(messa)o(g)o(e)f FN(id,)h(and)f(a)h(f)o(allback)e(has)i(been)e (set,)j(the)e(look)g(up)g(is)h(forw)o(arded)d(to)j(the)208 382 y(f)o(allback')-5 b(s)19 b FJ(ugettext\(\))g FN(method.)24 b(Otherwise,)19 b(the)i FK(messa)o(g)o(e)f FN(id)g(is)h(returned.)0 529 y FD(ngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)j(n)p FJ(\))208 628 y FN(Do)27 b(a)g(plural-forms)e(lookup)h(of)h(a)g (message)h(id.)46 b FK(singular)28 b FN(is)g(used)f(as)h(the)g(message) f(id)g(for)g(purposes)f(of)h(lookup)e(in)j(the)208 728 y(catalog,)c(while)h FK(n)f FN(is)i(used)e(to)h(determine)e(which)h (plural)g(form)f(to)i(use.)38 b(The)25 b(returned)d(message)j(string)f (is)h(an)g(8-bit)f(string)208 828 y(encoded)18 b(with)i(the)h(catalog') -5 b(s)19 b(charset)h(encoding,)e(if)j(kno)n(wn.)208 960 y(If)c(the)h(message)g(id)g(is)h(not)e(found)g(in)h(the)g(catalog,) f(and)g(a)i(f)o(allback)e(is)i(speci\002ed,)e(the)h(request)f(is)i (forw)o(arded)d(to)i(the)g(f)o(allback')-5 b(s)208 1060 y FJ(ngettext\(\))18 b FN(method.)24 b(Otherwise,)c(when)f FK(n)i FN(is)g(1)f FK(singular)h FN(is)h(returned,)c(and)h FK(plur)o(al)h FN(is)h(returned)d(in)j(all)g(other)e(cases.)208 1193 y(Ne)n(w)h(in)g(v)o(ersion)f(2.3.)0 1340 y FD(lngettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)i(n)p FJ(\))208 1439 y FN(Equi)n(v)n(alent)c(to)i FJ(gettext\(\))p FN(,)f(b)n(ut)h(the) f(translation)g(is)i(returned)d(in)i(the)g(preferred)e(system)i (encoding,)e(if)i(no)g(other)f(encoding)208 1539 y(w)o(as)21 b(e)o(xplicitly)e(set)i(with)f FJ(set_output_charset\(\))p FN(.)208 1672 y(Ne)n(w)g(in)g(v)o(ersion)f(2.4.)0 1819 y FD(ungettext)p FJ(\()p FK(singular)-9 b(,)17 b(plur)o(al,)i(n)p FJ(\))208 1918 y FN(Do)27 b(a)g(plural-forms)e(lookup)h(of)h(a)g (message)h(id.)46 b FK(singular)28 b FN(is)g(used)f(as)h(the)g(message) f(id)g(for)g(purposes)f(of)h(lookup)e(in)j(the)208 2018 y(catalog,)18 b(while)i FK(n)g FN(is)g(used)f(to)h(determine)e(which)h (plural)g(form)g(to)h(use.)k(The)c(returned)d(message)j(string)f(is)i (a)f(Unicode)e(string.)208 2151 y(If)f(the)h(message)g(id)g(is)h(not)e (found)g(in)h(the)g(catalog,)f(and)g(a)i(f)o(allback)e(is)i (speci\002ed,)e(the)h(request)f(is)i(forw)o(arded)d(to)i(the)g(f)o (allback')-5 b(s)208 2250 y FJ(ungettext\(\))18 b FN(method.)24 b(Otherwise,)c(when)f FK(n)h FN(is)i(1)e FK(singular)h FN(is)g(returned,)e(and)g FK(plur)o(al)h FN(is)h(returned)d(in)j(all)f (other)g(cases.)208 2383 y(Here)g(is)h(an)f(e)o(xample:)444 2607 y FA(n)44 b(=)h(len\(os.listdir\('.'\)\))444 2699 y(cat)f(=)h(GNUTranslations\(somefile\))444 2790 y(message)e(=)i (cat.ungettext\()623 2881 y('There)f(is)g(\045\(num\)d)g(file)g(in)h (this)f(directory',)623 2973 y('There)g(are)g(\045\(num\)d)g(files)g (in)g(this)h(directory',)623 3064 y(n\))g(\045)f({'num':)g(n})208 3254 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3522 y FI(Solar)q(is)24 b(message)f(catalog)h(suppor)s(t)0 3725 y FN(The)18 b(Solaris)h(operating)d(system)j(de\002nes)f(its)h(o)n(wn)f (binary)f(`)p FO(.mo)p FN(')h(\002le)h(format,)e(b)n(ut)h(since)h(no)f (documentation)d(can)j(be)h(found)d(on)i(this)0 3824 y(format,)h(it)i(is)g(not)f(supported)e(at)j(this)f(time.)0 4093 y FI(The)j(Catalog)h(constr)q(uctor)0 4296 y FN(GNOME)f(uses)h(a)g (v)o(ersion)e(of)h(the)g FJ(gettext)g FN(module)f(by)h(James)h (Henstridge,)e(b)n(ut)i(this)f(v)o(ersion)g(has)g(a)h(slightly)f(dif)n (ferent)e(API.)0 4395 y(Its)g(documented)c(usage)j(w)o(as:)236 4633 y FA(import)44 b(gettext)236 4725 y(cat)h(=)f (gettext.Catalog\(domain,)d(localedir\))236 4816 y(_)k(=)g(cat.gettext) 236 4907 y(print)f(_\('hello)g(world'\))0 5194 y FN(F)o(or)26 b(compatibility)e(with)i(this)h(older)e(module,)h(the)g(function)e FJ(Catalog\(\))h FN(is)i(an)f(alias)h(for)e(the)h FJ(translation\(\))e FN(function)0 5294 y(described)19 b(abo)o(v)o(e.)p 0 5549 3901 4 v 0 5649 a FI(744)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 745 757 TeXDict begin 745 756 bop 0 83 a FN(One)23 b(dif)n(ference)f(between)g (this)i(module)e(and)h(Henstridge')-5 b(s:)31 b(his)24 b(catalog)e(objects)i(supported)d(access)j(through)d(a)j(mapping)d (API,)0 183 y(b)n(ut)f(this)h(appears)e(to)i(be)f(unused)f(and)g(so)i (is)g(not)f(currently)e(supported.)0 468 y Fv(21.1.3)101 b(Inter)r(nationalizing)31 b(y)n(our)d(prog)o(r)o(ams)i(and)f(modules)0 670 y FN(Internationalization)15 b(\(I18N\))i(refers)h(to)g(the)g (operation)f(by)h(which)f(a)i(program)d(is)j(made)f(a)o(w)o(are)g(of)g (multiple)g(languages.)23 b(Localiza-)0 770 y(tion)c(\(L10N\))f(refers) h(to)h(the)g(adaptation)e(of)h(your)f(program,)g(once)h (internationalized,)e(to)i(the)h(local)f(language)f(and)h(cultural)g (habits.)0 870 y(In)h(order)f(to)h(pro)o(vide)e(multilingual)h (messages)h(for)g(your)f(Python)g(programs,)f(you)h(need)h(to)g(tak)o (e)g(the)h(follo)n(wing)d(steps:)104 1100 y(1.)41 b(prepare)18 b(your)h(program)f(or)i(module)f(by)h(specially)g(marking)e (translatable)i(strings)104 1266 y(2.)41 b(run)19 b(a)i(suite)f(of)g (tools)g(o)o(v)o(er)f(your)g(mark)o(ed)g(\002les)i(to)f(generate)f(ra)o (w)h(messages)h(catalogs)104 1432 y(3.)41 b(create)19 b(language)g(speci\002c)h(translations)g(of)g(the)g(message)g(catalogs) 104 1598 y(4.)41 b(use)20 b(the)g FJ(gettext)g FN(module)e(so)j(that)f (message)g(strings)h(are)f(properly)e(translated)0 1828 y(In)25 b(order)e(to)i(prepare)e(your)h(code)g(for)g(I18N,)g(you)g (need)g(to)h(look)f(at)h(all)g(the)g(strings)g(in)g(your)e(\002les.)40 b(An)o(y)24 b(string)g(that)h(needs)g(to)g(be)0 1927 y(translated)20 b(should)f(be)h(mark)o(ed)f(by)h(wrapping)e(it)j(in)f FJ(_\('...'\))k FN(\227)d(that)f(is,)h(a)g(call)g(to)f(the)g(function)f FJ(_\(\))p FN(.)25 b(F)o(or)19 b(e)o(xample:)236 2074 y FA(filename)44 b(=)g('mylog.txt')236 2165 y(message)g(=)h (_\('writing)e(a)h(log)h(message'\))236 2257 y(fp)g(=)f (open\(filename,)f('w'\))236 2348 y(fp.write\(message\))236 2439 y(fp.close\(\))0 2726 y FN(In)17 b(this)h(e)o(xample,)e(the)i (string)f FJ('writing)48 b(a)i(log)f(message')17 b FN(is)h(mark)o(ed)e (as)i(a)g(candidate)e(for)h(translation,)g(while)g(the)h(strings)0 2826 y FJ('mylog.txt')h FN(and)g FJ('w')i FN(are)f(not.)0 2972 y(The)26 b(Python)f(distrib)n(ution)g(comes)h(with)h(tw)o(o)g (tools)f(which)g(help)g(you)f(generate)g(the)i(message)f(catalogs)g (once)g(you')l(v)o(e)e(prepared)0 3072 y(your)g(source)g(code.)39 b(These)25 b(may)g(or)g(may)g(not)f(be)h(a)n(v)n(ailable)g(from)f(a)i (binary)e(distrib)n(ution,)g(b)n(ut)i(the)o(y)e(can)h(be)g(found)e(in)j (a)f(source)0 3172 y(distrib)n(ution,)19 b(in)h(the)g(`)p FO(T)-9 b(ools/i18n)p FN(')17 b(directory)-5 b(.)0 3319 y(The)21 b FL(pygettext)481 3288 y FF(3)533 3319 y FN(program)e(scans)j (all)f(your)f(Python)g(source)h(code)f(looking)g(for)g(the)i(strings)f (you)f(pre)n(viously)f(mark)o(ed)h(as)i(translat-)0 3418 y(able.)k(It)20 b(is)i(similar)e(to)h(the)f(GNU)h FL(gettext)e FN(program)f(e)o(xcept)i(that)g(it)h(understands)e(all)i(the)g (intricacies)f(of)g(Python)f(source)h(code,)g(b)n(ut)0 3518 y(kno)n(ws)e(nothing)f(about)g(C)j(or)e(C)928 3511 y(++)1022 3518 y(source)g(code.)23 b(Y)-9 b(ou)18 b(don')o(t)f(need)h (GNU)h FJ(gettext)f FN(unless)h(you')l(re)d(also)j(going)e(to)i(be)f (translating)0 3617 y(C)j(code)f(\(such)f(as)i(C)g(e)o(xtension)e (modules\).)0 3764 y FL(pygettext)f FN(generates)h(te)o(xtual)g (Uniforum-style)f(human)g(readable)h(message)h(catalog)f(`)p FO(.pot)p FN(')g(\002les,)h(essentially)g(structured)f(human)0 3864 y(readable)c(\002les)j(which)e(contain)f(e)n(v)o(ery)g(mark)o(ed)g (string)h(in)h(the)g(source)e(code,)i(along)e(with)i(a)g(placeholder)d (for)i(the)g(translation)g(strings.)0 3964 y FL(pygettext)21 b FN(is)j(a)f(command)e(line)i(script)g(that)h(supports)d(a)j(similar)f (command)e(line)i(interf)o(ace)f(as)i FL(xgettext)p FN(;)e(for)h (details)g(on)g(its)h(use,)0 4063 y(run:)236 4301 y FA(pygettext.py)43 b(--help)0 4588 y FN(Copies)32 b(of)f(these)h(`)p FO(.pot)p FN(')e(\002les)j(are)e(then)g(handed)f(o)o(v)o(er)h(to)g(the)h(indi)n (vidual)e(human)g(translators)h(who)g(write)h(language-speci\002c)0 4688 y(v)o(ersions)22 b(for)g(e)n(v)o(ery)f(supported)g(natural)h (language.)31 b(The)o(y)22 b(send)g(you)g(back)g(the)h(\002lled)g(in)g (language-speci\002c)d(v)o(ersions)i(as)i(a)f(`)p FO(.po)p FN(')0 4787 y(\002le.)34 b(Using)23 b(the)f FL(msgfmt.py)884 4757 y FF(4)940 4787 y FN(program)f(\(in)h(the)h(`)p FO(T)-9 b(ools/i18n)p FN(')20 b(directory\),)h(you)h(tak)o(e)h(the)g(`) p FO(.po)p FN(')e(\002les)j(from)e(your)g(translators)g(and)0 4887 y(generate)e(the)i(machine-readable)c(`)p FO(.mo)p FN(')k(binary)e(catalog)h(\002les.)30 b(The)22 b(`)p FO(.mo)p FN(')f(\002les)h(are)g(what)f(the)h FJ(gettext)f FN(module)f(uses)j(for)e(the)0 4986 y(actual)f(translation)f (processing)g(during)g(run-time.)p 0 5057 1560 4 v 90 5113 a FB(3)120 5136 y FH(Franc)-25 b(\270)t(ois)38 b(Pinard)h(has)f (written)i(a)e(program)h(called)h Fd(xpot)e FH(which)h(does)f(a)g (similar)h(job)m(.)85 b(It)38 b(is)g(a)o(v)n(ailable)j(as)d(part)h(of)f (his)g Fd(po-utils)h FH(package)h(at)0 5215 y Ff(http://po-utils)o (.progiciels-bpi.ca/)6 b FH(.)90 5273 y FB(4)120 5296 y Fd(msgfmt.py)18 b FH(is)f(binary)i(compatible)i(with)d(GNU)f Fd(msgfmt)i FH(e)o(xcept)g(that)g(it)g(pro)o(vides)g(a)e(simpler)m(,)i (all-Python)h(implementation.)27 b(W)m(ith)18 b(this)h(and)f Fd(pygettext.py)p FH(,)0 5375 y(you)f(generally)j(w)o(on')o(t)e(need)g (to)f(install)i(the)f(GNU)e Fd(gettext)j FH(package)g(to)e (internationalize)23 b(your)17 b(Python)h(applications.)p 0 5549 3901 4 v 0 5649 a FI(21.1.)52 b FJ(gettext)22 b FI(\227)h(Multilingual)j(inter)r(nationalization)h(ser)r(vices)1584 b(745)p eop end %%Page: 746 758 TeXDict begin 746 757 bop 0 83 a FN(Ho)n(w)24 b(you)f(use)i(the)f FJ(gettext)f FN(module)g(in)h(your)f(code)h(depends)f(on)g(whether)h (you)f(are)h(internationalizing)d(a)k(single)f(module)f(or)0 183 y(your)c(entire)h(application.)j(The)d(ne)o(xt)f(tw)o(o)i(sections) f(will)h(discuss)g(each)f(case.)0 451 y FI(Localizing)k(y)n(our)f (module)0 654 y FN(If)c(you)g(are)h(localizing)e(your)h(module,)f(you)h (must)g(tak)o(e)h(care)f(not)h(to)f(mak)o(e)h(global)e(changes,)h(e.g.) 24 b(to)c(the)g(b)n(uilt-in)f(namespace.)k(Y)-9 b(ou)0 753 y(should)19 b(not)h(use)g(the)h(GNU)f FJ(gettext)g FN(API)g(b)n(ut)g(instead)g(the)h(class-based)e(API.)0 900 y(Let')-5 b(s)29 b(say)f(your)f(module)g(is)i(called)f (\223spam\224)g(and)g(the)g(module')-5 b(s)27 b(v)n(arious)g(natural)h (language)e(translation)i(`)p FO(.mo)p FN(')f(\002les)i(reside)f(in)0 1000 y(`)p FO(/usr/share/locale)p FN(')16 b(in)21 b(GNU)f FL(gettext)f FN(format.)k(Here')-5 b(s)21 b(what)f(you)f(w)o(ould)h (put)g(at)g(the)g(top)g(of)g(your)f(module:)236 1238 y FA(import)44 b(gettext)236 1329 y(t)h(=)g (gettext.translation\('spam',)40 b('/usr/share/locale'\))236 1421 y(_)45 b(=)g(t.lgettext)0 1707 y FN(If)20 b(your)f(translators)h (were)g(pro)o(viding)d(you)i(with)i(Unicode)e(strings)h(in)g(their)g(`) p FO(.po)p FN(')f(\002les,)i(you')l(d)d(instead)i(do:)236 1946 y FA(import)44 b(gettext)236 2037 y(t)h(=)g (gettext.translation\('spam',)40 b('/usr/share/locale'\))236 2128 y(_)45 b(=)g(t.ugettext)0 2539 y FI(Localizing)24 b(y)n(our)f(application)0 2742 y FN(If)g(you)g(are)g(localizing)f(your) h(application,)f(you)g(can)i(install)g(the)f FJ(_\(\))g FN(function)f(globally)g(into)h(the)h(b)n(uilt-in)e(namespace,)h (usually)0 2842 y(in)e(the)f(main)g(dri)n(v)o(er)f(\002le)i(of)f(your)g (application.)k(This)c(will)i(let)f(all)g(your)e (application-speci\002c)f(\002les)k(just)f(use)f FJ(_\('...'\))25 b FN(without)0 2942 y(ha)n(ving)19 b(to)h(e)o(xplicitly)g(install)g(it) h(in)g(each)e(\002le.)0 3088 y(In)h(the)g(simple)g(case)h(then,)e(you)h (need)f(only)h(add)f(the)h(follo)n(wing)f(bit)h(of)g(code)g(to)g(the)g (main)g(dri)n(v)o(er)f(\002le)i(of)f(your)f(application:)236 3327 y FA(import)44 b(gettext)236 3418 y (gettext.install\('myapplication'\))0 3705 y FN(If)20 b(you)f(need)h(to)g(set)h(the)f(locale)g(directory)f(or)h(the)g FK(unicode)f FN(\003ag,)h(you)f(can)h(pass)h(these)f(into)g(the)g FJ(install\(\))f FN(function:)236 3943 y FA(import)44 b(gettext)236 4034 y(gettext.install\('myapplication',)c ('/usr/share/locale',)h(unicode=1\))0 4447 y FI(Changing)24 b(languages)h(on)e(the)g(\003y)0 4650 y FN(If)31 b(your)f(program)f (needs)i(to)g(support)f(man)o(y)g(languages)g(at)i(the)f(same)g(time,)j (you)c(may)h(w)o(ant)h(to)f(create)g(multiple)f(translation)0 4749 y(instances)20 b(and)g(then)f(switch)i(between)e(them)h(e)o (xplicitly)-5 b(,)19 b(lik)o(e)h(so:)p 0 5549 3901 4 v 0 5649 a FI(746)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization) p eop end %%Page: 747 759 TeXDict begin 747 758 bop 236 174 a FA(import)44 b(gettext)236 357 y(lang1)g(=)h(gettext.translation\('myapplication',)39 b(languages=['en']\))236 448 y(lang2)44 b(=)h (gettext.translation\('myapplication',)39 b(languages=['fr']\))236 540 y(lang3)44 b(=)h(gettext.translation\('myapplication',)39 b(languages=['de']\))236 722 y(#)45 b(start)f(by)g(using)g(language1) 236 814 y(lang1.install\(\))236 996 y(#)h(...)f(time)g(goes)h(by,)f (user)g(selects)g(language)f(2)236 1088 y(lang2.install\(\))236 1270 y(#)i(...)f(more)g(time)h(goes)f(by,)g(user)g(selects)g(language)f (3)236 1362 y(lang3.install\(\))0 1774 y FI(Def)n(erred)23 b(tr)o(anslations)0 1976 y FN(In)18 b(most)g(coding)f(situations,)h (strings)g(are)g(translated)f(where)h(the)o(y)f(are)h(coded.)23 b(Occasionally)17 b(ho)n(we)n(v)o(er)m(,)f(you)i(need)f(to)h(mark)g (strings)0 2076 y(for)i(translation,)f(b)n(ut)h(defer)f(actual)h (translation)f(until)h(later)-5 b(.)26 b(A)21 b(classic)g(e)o(xample)d (is:)236 2314 y FA(animals)44 b(=)h(['mollusk',)729 2406 y('albatross',)371 2497 y('rat',)371 2588 y('penguin',)371 2680 y('python',)371 2771 y(])236 2862 y(#)g(...)236 2954 y(for)g(a)f(in)h(animals:)416 3045 y(print)f(a)0 3331 y FN(Here,)21 b(you)f(w)o(ant)h(to)g(mark)f(the)h(strings)g(in)g (the)g FJ(animals)f FN(list)i(as)f(being)f(translatable,)g(b)n(ut)h (you)f(don')o(t)f(actually)i(w)o(ant)g(to)g(translate)0 3431 y(them)f(until)g(the)o(y)f(are)h(printed.)0 3578 y(Here)g(is)h(one)f(w)o(ay)g(you)f(can)h(handle)f(this)i(situation:)236 3816 y FA(def)45 b(_\(message\):)e(return)g(message)236 3999 y(animals)h(=)h([_\('mollusk'\),)729 4090 y(_\('albatross'\),)371 4181 y(_\('rat'\),)371 4273 y(_\('penguin'\),)371 4364 y(_\('python'\),)371 4455 y(])236 4638 y(del)g(_)236 4821 y(#)g(...)236 4912 y(for)g(a)f(in)h(animals:)416 5003 y(print)f(_\(a\))0 5290 y FN(This)26 b(w)o(orks)f(because)g(the)g (dummy)f(de\002nition)g(of)i FJ(_\(\))f FN(simply)g(returns)g(the)g (string)h(unchanged.)38 b(And)25 b(this)h(dummy)e(de\002nition)0 5389 y(will)19 b(temporarily)d(o)o(v)o(erride)g(an)o(y)h(de\002nition)h (of)f FJ(_\(\))i FN(in)f(the)g(b)n(uilt-in)g(namespace)f(\(until)h(the) g FJ(del)g FN(command\).)k(T)-7 b(ak)o(e)18 b(care,)g(though)p 0 5549 3901 4 v 0 5649 a FI(21.1.)52 b FJ(gettext)22 b FI(\227)h(Multilingual)j(inter)r(nationalization)h(ser)r(vices)1584 b(747)p eop end %%Page: 748 760 TeXDict begin 748 759 bop 0 83 a FN(if)20 b(you)g(ha)n(v)o(e)f(a)i(pre) n(vious)e(de\002nition)g(of)h FJ(_)g FN(in)g(the)h(local)f(namespace.)0 230 y(Note)i(that)g(the)h(second)e(use)i(of)e FJ(_\(\))i FN(will)g(not)f(identify)f(\223a\224)h(as)h(being)e(translatable)h(to)g (the)g FL(pygettext)e FN(program,)h(since)h(it)h(is)g(not)f(a)0 330 y(string.)0 476 y(Another)d(w)o(ay)h(to)g(handle)f(this)i(is)g (with)g(the)f(follo)n(wing)e(e)o(xample:)236 715 y FA(def)45 b(N_\(message\):)d(return)i(message)236 897 y(animals)g(=)h ([N_\('mollusk'\),)729 989 y(N_\('albatross'\),)371 1080 y(N_\('rat'\),)371 1171 y(N_\('penguin'\),)371 1263 y(N_\('python'\),) 371 1354 y(])236 1537 y(#)g(...)236 1628 y(for)g(a)f(in)h(animals:)416 1719 y(print)f(_\(a\))0 2019 y FN(In)19 b(this)i(case,)f(you)e(are)i (marking)e(translatable)h(strings)h(with)f(the)h(function)e FJ(N_\(\))p FN(,)2429 1989 y FF(5)2482 2019 y FN(which)h(w)o(on')o(t)f (con\003ict)i(with)f(an)o(y)g(de\002nition)g(of)0 2118 y FJ(_\(\))p FN(.)33 b(Ho)n(we)n(v)o(er)m(,)21 b(you)h(will)i(need)e (to)h(teach)g(your)e(message)i(e)o(xtraction)e(program)g(to)i(look)f (for)g(translatable)g(strings)h(mark)o(ed)e(with)0 2218 y FJ(N_\(\))p FN(.)k FL(pygettext)18 b FN(and)h FL(xpot)h FN(both)f(support)g(this)i(through)d(the)i(use)h(of)f(command)e(line)i (switches.)0 2483 y FJ(gettext\(\))h FI(vs)o(.)28 b FJ(lgettext\(\))0 2686 y FN(In)h(Python)f(2.4)h(the)g FJ(lgettext\(\))f FN(f)o(amily)h(of)f(functions)g(were)h(introduced.)50 b(The)29 b(intention)f(of)h(these)g(functions)f(is)i(to)g(pro-)0 2786 y(vide)23 b(an)h(alternati)n(v)o(e)e(which)i(is)g(more)f (compliant)f(with)i(the)g(current)f(implementation)e(of)j(GNU)g(gette)o (xt.)34 b(Unlik)o(e)24 b FJ(gettext\(\))p FN(,)0 2885 y(which)j(returns)g(strings)h(encoded)e(with)i(the)g(same)g(codeset)g (used)f(in)i(the)e(translation)g(\002le,)k FJ(lgettext\(\))26 b FN(will)j(return)e(strings)0 2985 y(encoded)20 b(with)j(the)f (preferred)e(system)j(encoding,)d(as)j(returned)d(by)i FJ(locale.getpreferredencoding\(\))p FN(.)k(Also)d(notice)0 3085 y(that)k(Python)e(2.4)h(introduces)g(ne)n(w)g(functions)f(to)i(e)o (xplicitly)f(choose)g(the)h(codeset)f(used)g(in)h(translated)f (strings.)45 b(If)26 b(a)h(codeset)g(is)0 3184 y(e)o(xplicitly)21 b(set,)i(e)n(v)o(en)e FJ(lgettext\(\))f FN(will)j(return)e(translated)g (strings)h(in)g(the)g(requested)f(codeset,)g(as)i(w)o(ould)e(be)h(e)o (xpected)e(in)j(the)0 3284 y(GNU)e(gette)o(xt)e(implementation.)0 3565 y Fv(21.1.4)101 b(Ac)n(kno)o(wledgements)0 3768 y FN(The)19 b(follo)n(wing)e(people)i(contrib)n(uted)e(code,)h (feedback,)g(design)g(suggestions,)h(pre)n(vious)e(implementations,)g (and)i(v)n(aluable)f(e)o(xperi-)0 3868 y(ence)i(to)g(the)g(creation)g (of)f(this)i(module:)125 4080 y FM(\017)41 b FN(Peter)20 b(Funk)125 4239 y FM(\017)41 b FN(James)20 b(Henstridge)125 4398 y FM(\017)41 b FN(Juan)19 b(Da)n(vid)h(Ib)5 b(\264)-33 b(a)7 b(\230)-35 b(nez)19 b(P)o(alomar)125 4557 y FM(\017)41 b FN(Marc-Andr)5 b(\264)-33 b(e)18 b(Lemb)n(ur)o(g)125 4715 y FM(\017)41 b FN(Martin)19 b(v)n(on)h(L)7 b(\250)-35 b(owis)125 4874 y FM(\017)41 b FN(Franc)-32 b(\270)s(ois)20 b(Pinard)125 5033 y FM(\017)41 b FN(Barry)19 b(W)-7 b(arsa)o(w)125 5192 y FM(\017)41 b FN(Gusta)n(v)n(o)20 b(Nieme)o(yer)p 0 5321 1560 4 v 90 5377 a FB(5)120 5400 y FH(The)c(choice)j(of)e Fz(N_\(\))f FH(here)i(is)f(totally)j(arbitrary;)f(it)f(could)g(ha)o(v)o (e)g(just)f(as)g(easily)i(been)f Fz(MarkThisStringForTranslation\(\))p FH(.)p 0 5549 3901 4 v 0 5649 a FI(748)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 749 761 TeXDict begin 749 760 bop 0 86 a FE(21.2)121 b Fx(locale)32 b FE(\227)h(Inter)s(nationalization)j(ser)t(vices)0 319 y FN(The)26 b FJ(locale)g FN(module)f(opens)h(access)h(to)f(the)h (POSIX)g(locale)f(database)g(and)g(functionality)-5 b(.)41 b(The)26 b(POSIX)h(locale)f(mechanism)0 419 y(allo)n(ws)c(programmers)e (to)i(deal)g(with)h(certain)e(cultural)h(issues)h(in)f(an)g (application,)f(without)h(requiring)e(the)i(programmer)d(to)k(kno)n(w)0 518 y(all)e(the)f(speci\002cs)h(of)f(each)f(country)g(where)g(the)i (softw)o(are)e(is)i(e)o(x)o(ecuted.)0 665 y(The)j FJ(locale)f FN(module)g(is)i(implemented)d(on)i(top)g(of)f(the)h FJ(_locale)g FN(module,)f(which)h(in)g(turn)f(uses)i(an)f(ANSI)g(C)h (locale)f(imple-)0 765 y(mentation)19 b(if)h(a)n(v)n(ailable.)0 912 y(The)g FJ(locale)f FN(module)g(de\002nes)h(the)g(follo)n(wing)f(e) o(xception)f(and)i(functions:)0 1059 y FL(exception)f FD(Error)208 1158 y FN(Exception)f(raised)i(when)g FJ(setlocale\(\))e FN(f)o(ails.)0 1305 y FD(setlocale)p FJ(\()p FK(cate)m(gory)p FC([)p FK(,)f(locale)12 b FC(])p FJ(\))208 1405 y FN(If)24 b FK(locale)g FN(is)h(speci\002ed,)g(it)g(may)f(be)h(a)g(string,)g(a)g (tuple)f(of)g(the)g(form)g FJ(\()p FK(langua)o(g)o(e)e(code)p FJ(,)48 b FK(encoding)p FJ(\))p FN(,)23 b(or)i FJ(None)p FN(.)37 b(If)25 b(it)g(is)g(a)208 1504 y(tuple,)16 b(it)g(is)h(con)m(v) o(erted)c(to)j(a)h(string)e(using)h(the)g(locale)f(aliasing)h(engine.) 22 b(If)16 b FK(locale)f FN(is)i(gi)n(v)o(en)e(and)g(not)h FJ(None)p FN(,)g FJ(setlocale\(\))208 1604 y FN(modi\002es)25 b(the)i(locale)f(setting)g(for)g(the)g FK(cate)m(gory)p FN(.)43 b(The)26 b(a)n(v)n(ailable)f(cate)o(gories)h(are)g(listed)h(in) f(the)h(data)f(description)f(belo)n(w)-5 b(.)208 1704 y(The)23 b(v)n(alue)h(is)h(the)f(name)g(of)f(a)i(locale.)36 b(An)25 b(empty)e(string)h(speci\002es)g(the)g(user')-5 b(s)25 b(def)o(ault)e(settings.)37 b(If)24 b(the)g(modi\002cation)f(of) 208 1803 y(the)d(locale)g(f)o(ails,)g(the)h(e)o(xception)d FJ(Error)i FN(is)h(raised.)k(If)20 b(successful,)f(the)i(ne)n(w)f (locale)g(setting)g(is)h(returned.)208 1936 y(If)f FK(locale)f FN(is)i(omitted)f(or)g FJ(None)p FN(,)g(the)g(current)f(setting)h(for)f FK(cate)m(gory)g FN(is)i(returned.)208 2069 y FJ(setlocale\(\))d FN(is)j(not)f(thread)f(safe)i(on)f(most)g(systems.)25 b(Applications)19 b(typically)h(start)g(with)h(a)f(call)h(of)444 2293 y FA(import)44 b(locale)444 2384 y (locale.setlocale\(locale.LC_ALL,)39 b(''\))208 2574 y FN(This)21 b(sets)h(the)f(locale)g(for)g(all)g(cate)o(gories)f(to)h (the)h(user')-5 b(s)21 b(def)o(ault)f(setting)h(\(typically)f (speci\002ed)h(in)g(the)g(LANG)h(en)m(vironment)208 2674 y(v)n(ariable\).)h(If)d(the)g(locale)g(is)h(not)f(changed)f(thereafter) m(,)f(using)i(multithreading)d(should)i(not)h(cause)g(problems.)208 2806 y(Changed)e(in)j(v)o(ersion)e(2.0:)g(Added)g(support)g(for)h (tuple)g(v)n(alues)f(of)h(the)h FK(locale)e FN(parameter)-5 b(.)0 2953 y FD(localeconv)p FJ(\(\))208 3053 y FN(Returns)20 b(the)g(database)f(of)h(the)h(local)f(con)m(v)o(entions)d(as)k(a)g (dictionary)-5 b(.)22 b(This)f(dictionary)d(has)j(the)f(follo)n(wing)e (strings)i(as)h(k)o(e)o(ys:)p 0 5549 3901 4 v 0 5649 a FI(21.2.)52 b FJ(locale)22 b FI(\227)h(Inter)r(nationalization)j(ser) r(vices)2068 b(749)p eop end %%Page: 750 762 TeXDict begin 750 761 bop 257 70 a FL(Category)p 853 100 4 100 v 318 w(K)n(ey)p 2497 100 V 1502 w(Meaning)p 208 103 4192 4 v 257 173 a FJ(LC_NUMERIC)p 853 203 4 100 v 148 w('decimal_point')p 2497 203 V 894 w FN(Decimal)20 b(point)f(character)-5 b(.)p 853 701 4 499 v 905 272 a FJ('grouping')p 2497 701 V 1144 w FN(Sequence)26 b(of)h(numbers)e (specifying)h(which)g(relati)n(v)o(e)h(posi-)2549 372 y(tions)37 b(the)g FJ('thousands_sep')d FN(is)k(e)o(xpected.)74 b(If)36 b(the)2549 472 y(sequence)d(is)i(terminated)e(with)i FJ(CHAR_MAX)p FN(,)e(no)h(further)2549 571 y(grouping)13 b(is)k(performed.)k(If)16 b(the)g(sequence)f(terminates)g(with)2549 671 y(a)20 b FJ(0)p FN(,)h(the)f(last)h(group)d(size)j(is)g(repeatedly) e(used.)p 853 800 4 100 v 905 770 a FJ('thousands_sep')p 2497 800 V 894 w FN(Character)g(used)h(between)g(groups.)p 208 804 4192 4 v 257 873 a FJ(LC_MONETARY)p 853 903 4 100 v 98 w('int_curr_symbol')p 2497 903 V 794 w FN(International)e (currenc)o(y)g(symbol.)p 853 1003 V 905 973 a FJ('currency_symbol')p 2497 1003 V 794 w FN(Local)i(currenc)o(y)d(symbol.)p 853 1202 4 200 v 905 1073 a FJ('p_cs_precedes/n_cs_precedes')p 2497 1202 V 194 w FN(Whether)25 b(the)h(currenc)o(y)e(symbol)g (precedes)h(the)h(v)n(alue)f(\(for)2549 1172 y(positi)n(v)o(e)19 b(resp.)25 b(ne)o(gati)n(v)o(e)18 b(v)n(alues\).)p 853 1401 V 905 1272 a FJ('p_sep_by_space/n_sep_by_space')p 2497 1401 V 94 w FN(Whether)34 b(the)h(currenc)o(y)d(symbol)i(is)i (separated)e(from)f(the)2549 1372 y(v)n(alue)19 b(by)h(a)h(space)f (\(for)f(positi)n(v)o(e)g(resp.)25 b(ne)o(gati)n(v)o(e)18 b(v)n(alues\).)p 853 1501 4 100 v 905 1471 a FJ('mon_decimal_point')p 2497 1501 V 694 w FN(Decimal)i(point)f(used)h(for)g(monetary)e(v)n (alues.)p 853 1700 4 200 v 905 1571 a FJ('frac_digits')p 2497 1700 V 994 w FN(Number)g(of)h(fractional)e(digits)j(used)f(in)g (local)g(formatting)f(of)2549 1670 y(monetary)g(v)n(alues.)p 853 1900 V 905 1770 a FJ('int_frac_digits')p 2497 1900 V 794 w FN(Number)26 b(of)h(fractional)g(digits)g(used)g(in)h (international)e(for)n(-)2549 1870 y(matting)19 b(of)h(monetary)e(v)n (alues.)p 853 1999 4 100 v 905 1969 a FJ('mon_thousands_sep')p 2497 1999 V 694 w FN(Group)h(separator)g(used)h(for)f(monetary)f(v)n (alues.)p 853 2198 4 200 v 905 2069 a FJ('mon_grouping')p 2497 2198 V 944 w FN(Equi)n(v)n(alent)26 b(to)h FJ('grouping')p FN(,)h(used)g(for)f(monetary)f(v)n(al-)2549 2169 y(ues.)p 853 2298 4 100 v 905 2268 a FJ('positive_sign')p 2497 2298 V 894 w FN(Symbol)19 b(used)h(to)g(annotate)f(a)i(positi)n(v)o(e)e (monetary)g(v)n(alue.)p 853 2398 V 905 2368 a FJ('negative_sign')p 2497 2398 V 894 w FN(Symbol)g(used)h(to)g(annotate)f(a)i(ne)o(gati)n(v) o(e)d(monetary)g(v)n(alue.)p 853 2597 4 200 v 905 2467 a FJ('p_sign_posn/n_sign_posn')p 2497 2597 V 394 w FN(The)30 b(position)g(of)g(the)h(sign)f(\(for)g(positi)n(v)o(e)g(resp.)55 b(ne)o(gati)n(v)o(e)2549 2567 y(v)n(alues\),)19 b(see)i(belo)n(w)-5 b(.)208 2689 y(All)20 b(numeric)f(v)n(alues)h(can)g(be)g(set)h(to)f FJ(CHAR_MAX)g FN(to)g(indicate)g(that)g(there)g(is)h(no)f(v)n(alue)f (speci\002ed)h(in)g(this)h(locale.)208 2815 y(The)e(possible)h(v)n (alues)g(for)g FJ('p_sign_posn')e FN(and)i FJ('n_sign_posn')e FN(are)i(gi)n(v)o(en)f(belo)n(w)-5 b(.)971 2937 y FL(V)d(alue)p 1318 2967 4 100 v 199 w(Explanation)p 822 2971 2465 4 v 1046 3040 a FJ(0)p 1318 3070 4 100 v 274 w FN(Currenc)o(y)18 b(and)i(v)n(alue)f(are)h(surrounded)e(by)h(parentheses.)1046 3140 y FJ(1)p 1318 3170 V 274 w FN(The)g(sign)i(should)e(precede)g(the) h(v)n(alue)f(and)h(currenc)o(y)e(symbol.)1046 3240 y FJ(2)p 1318 3270 V 274 w FN(The)h(sign)i(should)e(follo)n(w)g(the)h(v)n (alue)g(and)g(currenc)o(y)d(symbol.)1046 3339 y FJ(3)p 1318 3369 V 274 w FN(The)i(sign)i(should)e(immediately)g(precede)f(the) j(v)n(alue.)1046 3439 y FJ(4)p 1318 3469 V 274 w FN(The)e(sign)i (should)e(immediately)g(follo)n(w)g(the)h(v)n(alue.)871 3539 y FJ(CHAR_MAX)p 1318 3568 V 99 w FN(Nothing)e(is)k(speci\002ed)d (in)i(this)g(locale.)0 3679 y FD(nl_langinfo)p FJ(\()p FK(option)p FJ(\))208 3778 y FN(Return)k(some)g(locale-speci\002c)f (information)f(as)j(a)g(string.)41 b(This)25 b(function)f(is)i(not)f(a) n(v)n(ailable)g(on)g(all)h(systems,)h(and)e(the)h(set)208 3878 y(of)i(possible)g(options)f(might)h(also)g(v)n(ary)f(across)i (platforms.)48 b(The)28 b(possible)g(ar)o(gument)e(v)n(alues)i(are)g (numbers,)g(for)g(which)208 3978 y(symbolic)19 b(constants)h(are)g(a)n (v)n(ailable)f(in)i(the)f(locale)g(module.)0 4124 y FD (getdefaultlocale)p FJ(\()p FC([)p FK(en)m(vvar)o(s)12 b FC(])p FJ(\))208 4224 y FN(T)m(ries)22 b(to)g(determine)f(the)h(def)o (ault)f(locale)h(settings)h(and)e(returns)g(them)h(as)h(a)f(tuple)g(of) g(the)g(form)f FJ(\()p FK(langua)o(g)o(e)f(code)p FJ(,)48 b FK(encod-)208 4324 y(ing)p FJ(\))p FN(.)208 4450 y(According)23 b(to)j(POSIX,)f(a)h(program)d(which)i(has)h(not)f(called)g FJ(setlocale\(LC_ALL,)47 b(''\))26 b FN(runs)f(using)f(the)i(portable) 208 4550 y FJ('C')c FN(locale.)30 b(Calling)22 b FJ(setlocale\(LC_ALL,) 47 b(''\))22 b FN(lets)h(it)g(use)f(the)g(def)o(ault)g(locale)f(as)i (de\002ned)e(by)h(the)g(LANG)g(v)n(ari-)208 4649 y(able.)30 b(Since)22 b(we)g(do)g(not)g(w)o(ant)g(to)g(interfere)f(with)h(the)g (current)f(locale)h(setting)g(we)g(thus)g(emulate)g(the)g(beha)n(vior)e (in)i(the)h(w)o(ay)208 4749 y(described)18 b(abo)o(v)o(e.)208 4875 y(T)-7 b(o)28 b(maintain)e(compatibility)h(with)h(other)f (platforms,)h(not)f(only)g(the)h(LANG)g(v)n(ariable)f(is)h(tested,)i(b) n(ut)e(a)g(list)h(of)e(v)n(ariables)208 4975 y(gi)n(v)o(en)h(as)i(en)m (vv)n(ars)d(parameter)-5 b(.)52 b(The)29 b(\002rst)h(found)d(to)j(be)f (de\002ned)f(will)i(be)f(used.)53 b FK(en)m(vvar)o(s)28 b FN(def)o(aults)h(to)h(the)f(search)g(path)208 5074 y(used)21 b(in)h(GNU)g(gette)o(xt;)g(it)g(must)g(al)o(w)o(ays)g (contain)f(the)h(v)n(ariable)e(name)i(`)p FJ(LANG)p FN('.)e(The)i(GNU)g (gette)o(xt)f(search)g(path)g(contains)208 5174 y FJ('LANGUAGE')p FN(,)d FJ('LC_ALL')p FN(,)h FJ('LC_CTYPE')p FN(,)g(and)g FJ('LANG')p FN(,)h(in)g(that)h(order)-5 b(.)208 5300 y(Except)24 b(for)h(the)h(code)f FJ('C')p FN(,)g(the)g(language)f(code) h(corresponds)e(to)j(RFC)h(1766.)40 b FK(langua)o(g)o(e)23 b(code)i FN(and)g FK(encoding)f FN(may)h(be)208 5400 y FJ(None)20 b FN(if)g(their)g(v)n(alues)g(cannot)f(be)h(determined.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.0.)p 0 5549 3901 4 v 0 5649 a FI(750)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization) p eop end %%Page: 751 763 TeXDict begin 751 762 bop 0 83 a FD(getlocale)p FJ(\()p FC([)p FK(cate)m(gory)12 b FC(])p FJ(\))208 183 y FN(Returns)19 b(the)h(current)f(setting)h(for)g(the)g(gi)n(v)o(en)e(locale)i(cate)o (gory)e(as)j(sequence)e(containing)f FK(langua)o(g)o(e)g(code)p FN(,)h FK(encoding)p FN(.)k FK(cate-)208 282 y(gory)c FN(may)h(be)g(one)g(of)g(the)g FJ(LC_)1146 297 y(*)1216 282 y FN(v)n(alues)g(e)o(xcept)f FJ(LC_ALL)p FN(.)g(It)i(def)o(aults)f (to)g FJ(LC_CTYPE)p FN(.)208 415 y(Except)k(for)h(the)h(code)f FJ('C')p FN(,)g(the)g(language)f(code)h(corresponds)e(to)j(RFC)h(1766.) 40 b FK(langua)o(g)o(e)23 b(code)i FN(and)g FK(encoding)f FN(may)h(be)208 515 y FJ(None)20 b FN(if)g(their)g(v)n(alues)g(cannot)f (be)h(determined.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.0.)0 662 y FD(getpreferredencoding)p FJ(\()p FC([)p FK(do)p 1179 662 25 4 v 25 w(setlocale)12 b FC(])p FJ(\))208 761 y FN(Return)17 b(the)g(encoding)f(used)h(for)g(te)o(xt)h(data,)g (according)d(to)j(user)g(preferences.)k(User)c(preferences)e(are)h(e)o (xpressed)g(dif)n(ferently)208 861 y(on)e(dif)n(ferent)g(systems,)i (and)e(might)g(not)h(be)g(a)n(v)n(ailable)g(programmatically)c(on)k (some)g(systems,)h(so)f(this)h(function)d(only)h(returns)208 960 y(a)20 b(guess.)208 1093 y(On)j(some)g(systems,)h(it)g(is)g (necessary)e(to)h(in)m(v)n(ok)o(e)f FJ(setlocale)g FN(to)h(obtain)g (the)g(user)g(preferences,)e(so)j(this)f(function)f(is)i(not)208 1193 y(thread-safe.)f(If)d(in)m(v)n(oking)e(setlocale)i(is)h(not)f (necessary)g(or)f(desired,)h FK(do)p 2328 1193 V 29 w(setlocale)g FN(should)f(be)h(set)h(to)f FJ(False)p FN(.)208 1326 y(Ne)n(w)g(in)g(v)o(ersion)f(2.3.)0 1473 y FD(normalize)p FJ(\()p FK(localename)p FJ(\))208 1572 y FN(Returns)h(a)i(normalized)d (locale)i(code)f(for)h(the)g(gi)n(v)o(en)f(locale)h(name.)27 b(The)21 b(returned)e(locale)i(code)f(is)i(formatted)e(for)g(use)h (with)208 1672 y FJ(setlocale\(\))p FN(.)i(If)d(normalization)e(f)o (ails,)j(the)f(original)f(name)g(is)j(returned)c(unchanged.)208 1805 y(If)25 b(the)h(gi)n(v)o(en)f(encoding)f(is)j(not)f(kno)n(wn,)g (the)g(function)e(def)o(aults)i(to)g(the)g(def)o(ault)f(encoding)f(for) h(the)i(locale)e(code)h(just)g(lik)o(e)208 1904 y FJ(setlocale\(\))p FN(.)49 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 2051 y FD(resetlocale)p FJ(\()p FC([)p FK(cate)m(gory)12 b FC(])p FJ(\))208 2151 y FN(Sets)21 b(the)f(locale)g(for)f FK(cate)m(gory)g FN(to)i(the)f(def)o(ault)f(setting.)208 2284 y(The)h(def)o(ault)g (setting)h(is)g(determined)e(by)h(calling)h FJ(getdefaultlocale\(\))p FN(.)j FK(cate)m(gory)19 b FN(def)o(aults)h(to)h FJ(LC_ALL)p FN(.)41 b(Ne)n(w)21 b(in)208 2383 y(v)o(ersion)d(2.0.)0 2530 y FD(strcoll)p FJ(\()p FK(string1,)g(string2)p FJ(\))208 2630 y FN(Compares)g(tw)o(o)i(strings)g(according)e(to)i(the)f(current) g FJ(LC_COLLATE)f FN(setting.)25 b(As)c(an)o(y)d(other)h(compare)f (function,)g(returns)h(a)208 2729 y(ne)o(gati)n(v)o(e,)e(or)i(a)h (positi)n(v)o(e)f(v)n(alue,)f(or)i FJ(0)p FN(,)f(depending)e(on)i (whether)g FK(string1)g FN(collates)h(before)e(or)h(after)g FK(string2)h FN(or)f(is)i(equal)d(to)i(it.)0 2876 y FD(strxfrm)p FJ(\()p FK(string)p FJ(\))208 2976 y FN(T)m(ransforms)29 b(a)j(string)f(to)h(one)f(that)g(can)h(be)f(used)g(for)g(the)h(b)n (uilt-in)f(function)e FJ(cmp\(\))p FN(,)34 b(and)d(still)h(returns)f (locale-a)o(w)o(are)208 3076 y(results.)26 b(This)20 b(function)f(can)h(be)h(used)f(when)g(the)g(same)h(string)f(is)h (compared)e(repeatedly)-5 b(,)18 b(e.g.)25 b(when)20 b(collating)g(a)h(sequence)208 3175 y(of)e(strings.)0 3322 y FD(format)p FJ(\()p FK(format,)g(val)p FC([)p FK(,)g(gr)l(ouping)p FC([)p FK(,)g(monetary)12 b FC(])g(])p FJ(\))208 3422 y FN(F)o(ormats)24 b(a)h(number)e FK(val)i FN(according)e(to)i(the)g(current)f FJ(LC_NUMERIC)f FN(setting.)39 b(The)25 b(format)e(follo)n(ws)i(the)g(con)m(v)o(entions)d(of)208 3521 y(the)h FJ(\045)g FN(operator)-5 b(.)32 b(F)o(or)23 b(\003oating)g(point)f(v)n(alues,)h(the)g(decimal)g(point)f(is)i (modi\002ed)e(if)h(appropriate.)32 b(If)23 b FK(gr)l(ouping)e FN(is)j(true,)f(also)208 3621 y(tak)o(es)d(the)g(grouping)e(into)i (account.)208 3754 y(If)g FK(monetary)f FN(is)i(true,)f(the)g(con)m(v)o (ersion)d(uses)k(monetary)d(thousands)h(separator)g(and)h(grouping)d (strings.)208 3887 y(Please)29 b(note)e(that)i(this)g(function)d(will)j (only)f(w)o(ork)f(for)h(e)o(xactly)f(one)h(\045char)g(speci\002er)-5 b(.)49 b(F)o(or)28 b(whole)g(format)f(strings,)j(use)208 3986 y FJ(format_string\(\))p FN(.)208 4119 y(Changed)18 b(in)j(v)o(ersion)e(2.5:)g(Added)g(the)i FK(monetary)e FN(parameter)-5 b(.)0 4266 y FD(format_string)p FJ(\()p FK(format,)17 b(val)p FC([)p FK(,)j(gr)l(ouping)12 b FC(])p FJ(\))208 4366 y FN(Processes)20 b(formatting)e(speci\002ers)j (as)g(in)f FJ(format)49 b(\045val)p FN(,)19 b(b)n(ut)i(tak)o(es)f(the)g (current)f(locale)h(settings)h(into)f(account.)208 4498 y(Ne)n(w)g(in)g(v)o(ersion)f(2.5.)0 4645 y FD(currency)p FJ(\()p FK(val)p FC([)p FK(,)f(symbol)p FC([)p FK(,)i(gr)l(ouping)p FC([)p FK(,)e(international)12 b FC(])g(])g(])p FJ(\))208 4745 y FN(F)o(ormats)19 b(a)i(number)d FK(val)j FN(according)d(to)i (the)g(current)f FJ(LC_MONETARY)g FN(settings.)208 4878 y(The)28 b(returned)e(string)i(includes)g(the)g(currenc)o(y)e(symbol)i (if)g FK(symbol)g FN(is)i(true,)g(which)d(is)j(the)e(def)o(ault.)49 b(If)28 b FK(gr)l(ouping)f FN(is)i(true)208 4977 y(\(which)18 b(is)j(not)e(the)h(def)o(ault\),)e(grouping)f(is)k(done)e(with)h(the)f (v)n(alue.)24 b(If)c FK(international)e FN(is)i(true)g(\(which)e(is)j (not)e(the)h(def)o(ault\),)f(the)208 5077 y(international)f(currenc)o (y)g(symbol)h(is)i(used.)208 5210 y(Note)f(that)g(this)h(function)d (will)j(not)f(w)o(ork)g(with)g(the)g(`C')g(locale,)g(so)h(you)e(ha)n(v) o(e)h(to)g(set)h(a)g(locale)f(via)g FJ(setlocale\(\))f FN(\002rst.)208 5343 y(Ne)n(w)h(in)g(v)o(ersion)f(2.5.)p 0 5549 3901 4 v 0 5649 a FI(21.2.)52 b FJ(locale)22 b FI(\227)h(Inter)r(nationalization)j(ser)r(vices)2068 b(751)p eop end %%Page: 752 764 TeXDict begin 752 763 bop 0 83 a FD(str)p FJ(\()p FK(\003oat)q FJ(\))208 183 y FN(F)o(ormats)15 b(a)i(\003oating)e(point)h(number)e (using)i(the)g(same)g(format)g(as)g(the)h(b)n(uilt-in)e(function)g FJ(str\()p FK(\003oat)q FJ(\))p FN(,)g(b)n(ut)h(tak)o(es)h(the)f (decimal)208 282 y(point)j(into)h(account.)0 429 y FD(atof)p FJ(\()p FK(string)p FJ(\))208 529 y FN(Con)m(v)o(erts)f(a)h(string)g (to)g(a)h(\003oating)e(point)h(number)m(,)e(follo)n(wing)g(the)i FJ(LC_NUMERIC)f FN(settings.)0 676 y FD(atoi)p FJ(\()p FK(string)p FJ(\))208 775 y FN(Con)m(v)o(erts)g(a)h(string)g(to)g(an)h (inte)o(ger)m(,)d(follo)n(wing)h(the)h FJ(LC_NUMERIC)f FN(con)m(v)o(entions.)0 922 y FD(LC_CTYPE)208 1022 y FN(Locale)25 b(cate)o(gory)e(for)i(the)h(character)e(type)h(functions.) 40 b(Depending)24 b(on)h(the)g(settings)h(of)f(this)i(cate)o(gory)-5 b(,)24 b(the)i(functions)e(of)208 1121 y(module)18 b FJ(string)i FN(dealing)f(with)i(case)f(change)f(their)h(beha)n(viour)-5 b(.)0 1268 y FD(LC_COLLATE)208 1368 y FN(Locale)22 b(cate)o(gory)f(for) h(sorting)g(strings.)33 b(The)22 b(functions)g FJ(strcoll\(\))g FN(and)g FJ(strxfrm\(\))f FN(of)i(the)g FJ(locale)f FN(module)g(are)208 1468 y(af)n(fected.)0 1614 y FD(LC_TIME)208 1714 y FN(Locale)d(cate)o (gory)g(for)g(the)h(formatting)f(of)h(time.)25 b(The)19 b(function)g FJ(time.strftime\(\))f FN(follo)n(ws)i(these)g(con)m(v)o (entions.)0 1861 y FD(LC_MONETARY)208 1961 y FN(Locale)54 b(cate)o(gory)e(for)i(formatting)f(of)h(monetary)f(v)n(alues.)128 b(The)54 b(a)n(v)n(ailable)h(options)e(are)i(a)n(v)n(ailable)f(from)g (the)208 2060 y FJ(localeconv\(\))18 b FN(function.)0 2207 y FD(LC_MESSAGES)208 2307 y FN(Locale)j(cate)o(gory)f(for)h (message)h(display)-5 b(.)29 b(Python)21 b(currently)f(does)i(not)f (support)g(application)f(speci\002c)i(locale-a)o(w)o(are)f(mes-)208 2406 y(sages.)j(Messages)18 b(displayed)e(by)h(the)g(operating)e (system,)j(lik)o(e)g(those)f(returned)e(by)i FJ(os.strerror\(\))f FN(might)g(be)i(af)n(fected)208 2506 y(by)h(this)i(cate)o(gory)-5 b(.)0 2653 y FD(LC_NUMERIC)208 2752 y FN(Locale)28 b(cate)o(gory)f(for) i(formatting)e(numbers.)50 b(The)29 b(functions)e FJ(format\(\))p FN(,)k FJ(atoi\(\))p FN(,)f FJ(atof\(\))f FN(and)f FJ(str\(\))h FN(of)g(the)208 2852 y FJ(locale)19 b FN(module)g(are)h(af)n(fected)f (by)h(that)g(cate)o(gory)-5 b(.)23 b(All)e(other)e(numeric)g (formatting)f(operations)h(are)h(not)g(af)n(fected.)0 2999 y FD(LC_ALL)208 3099 y FN(Combination)27 b(of)i(all)h(locale)f (settings.)53 b(If)29 b(this)h(\003ag)f(is)h(used)g(when)e(the)i (locale)f(is)h(changed,)g(setting)f(the)g(locale)g(for)g(all)208 3198 y(cate)o(gories)19 b(is)i(attempted.)j(If)d(that)f(f)o(ails)h(for) f(an)o(y)f(cate)o(gory)-5 b(,)18 b(no)i(cate)o(gory)f(is)i(changed)e (at)h(all.)26 b(When)20 b(the)h(locale)f(is)h(retrie)n(v)o(ed)208 3298 y(using)c(this)i(\003ag,)f(a)g(string)g(indicating)f(the)h (setting)f(for)h(all)g(cate)o(gories)f(is)i(returned.)k(This)18 b(string)f(can)h(be)g(later)g(used)g(to)g(restore)208 3397 y(the)i(settings.)0 3544 y FD(CHAR_MAX)208 3644 y FN(This)g(is)h(a)g(symbolic)e(constant)g(used)h(for)g(dif)n(ferent)e (v)n(alues)i(returned)f(by)g FJ(localeconv\(\))p FN(.)0 3791 y(The)i FJ(nl_langinfo)e FN(function)g(accepts)i(one)g(of)f(the)h (follo)n(wing)f(k)o(e)o(ys.)27 b(Most)21 b(descriptions)f(are)h(tak)o (en)f(from)g(the)h(corresponding)0 3890 y(description)e(in)h(the)g(GNU) h(C)g(library)-5 b(.)0 4037 y FD(CODESET)208 4137 y FN(Return)19 b(a)i(string)f(with)g(the)g(name)g(of)g(the)g(character)f(encoding)f (used)i(in)g(the)h(selected)f(locale.)0 4284 y FD(D_T_FMT)208 4383 y FN(Return)h(a)h(string)f(that)h(can)g(be)g(used)f(as)h(a)h (format)d(string)i(for)f(strftime\(3\))f(to)i(represent)f(time)h(and)f (date)g(in)h(a)g(locale-speci\002c)208 4483 y(w)o(ay)-5 b(.)0 4630 y FD(D_FMT)208 4729 y FN(Return)19 b(a)i(string)f(that)g (can)g(be)g(used)g(as)h(a)g(format)e(string)h(for)f(strftime\(3\))g(to) h(represent)f(a)i(date)f(in)g(a)h(locale-speci\002c)e(w)o(ay)-5 b(.)0 4876 y FD(T_FMT)208 4976 y FN(Return)19 b(a)i(string)f(that)g (can)g(be)g(used)g(as)h(a)g(format)e(string)h(for)f(strftime\(3\))g(to) h(represent)f(a)i(time)f(in)h(a)f(locale-speci\002c)g(w)o(ay)-5 b(.)0 5123 y FD(T_FMT_AMPM)208 5222 y FN(The)19 b(return)g(v)n(alue)h (can)g(be)g(used)g(as)h(a)g(format)e(string)g(for)h(`strftime')f(to)i (represent)e(time)h(in)g(the)h(am/pm)e(format.)0 5369 y FD(DAY_1)49 b(...)99 b(DAY_7)p 0 5549 3901 4 v 0 5649 a FI(752)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 753 765 TeXDict begin 753 764 bop 208 83 a FN(Return)21 b(name)h(of)f(the)h (n-th)g(day)f(of)h(the)g(week.)31 b FL(W)-5 b(ar)o(ning:)27 b FN(This)c(follo)n(ws)e(the)h(US)h(con)m(v)o(ention)c(of)j FJ(DAY_1)f FN(being)h(Sunday)-5 b(,)208 183 y(not)19 b(the)i(international)d(con)m(v)o(ention)f(\(ISO)j(8601\))f(that)h (Monday)f(is)i(the)f(\002rst)h(day)e(of)h(the)h(week.)0 330 y FD(ABDAY_1)49 b(...)99 b(ABDAY_7)208 429 y FN(Return)19 b(abbre)n(viated)f(name)i(of)g(the)g(n-th)f(day)h(of)g(the)g(week.)0 576 y FD(MON_1)49 b(...)99 b(MON_12)208 676 y FN(Return)19 b(name)h(of)g(the)g(n-th)f(month.)0 823 y FD(ABMON_1)49 b(...)99 b(ABMON_12)208 922 y FN(Return)19 b(abbre)n(viated)f(name)i (of)g(the)g(n-th)f(month.)0 1069 y FD(RADIXCHAR)208 1169 y FN(Return)g(radix)h(character)f(\(decimal)g(dot,)g(decimal)h(comma,)f (etc.\))0 1316 y FD(THOUSEP)208 1415 y FN(Return)g(separator)g (character)g(for)h(thousands)f(\(groups)f(of)i(three)g(digits\).)0 1562 y FD(YESEXPR)208 1662 y FN(Return)e(a)h(re)o(gular)f(e)o (xpression)f(that)i(can)g(be)g(used)g(with)g(the)g(re)o(ge)o(x)e (function)h(to)h(recognize)e(a)i(positi)n(v)o(e)g(response)f(to)h(a)g (yes/no)208 1761 y(question.)47 b FL(W)-5 b(ar)o(ning:)40 b FN(The)28 b(e)o(xpression)f(is)i(in)f(the)g(syntax)g(suitable)g(for)f (the)h FJ(regex\(\))g FN(function)e(from)h(the)h(C)h(library)-5 b(,)208 1861 y(which)19 b(might)h(dif)n(fer)f(from)g(the)h(syntax)g (used)g(in)g FJ(re)p FN(.)0 2008 y FD(NOEXPR)208 2107 y FN(Return)25 b(a)h(re)o(gular)e(e)o(xpression)h(that)h(can)f(be)h (used)f(with)h(the)g(re)o(ge)o(x\(3\))d(function)h(to)i(recognize)e(a)j (ne)o(gati)n(v)o(e)c(response)i(to)h(a)208 2207 y(yes/no)19 b(question.)0 2354 y FD(CRNCYSTR)208 2454 y FN(Return)24 b(the)h(currenc)o(y)d(symbol,)j(preceded)e(by)h(\224-\224)h(if)g(the)g (symbol)e(should)h(appear)g(before)f(the)i(v)n(alue,)g(\224+\224)g(if)g (the)g(symbol)208 2553 y(should)19 b(appear)g(after)h(the)g(v)n(alue,)f (or)h(\224.)-6 b(\224)20 b(if)h(the)f(symbol)f(should)g(replace)h(the)g (radix)g(character)-5 b(.)0 2700 y FD(ERA)208 2800 y FN(The)19 b(return)g(v)n(alue)h(represents)f(the)h(era)h(used)f(in)g (the)g(current)f(locale.)208 2932 y(Most)i(locales)h(do)f(not)g (de\002ne)g(this)h(v)n(alue.)27 b(An)22 b(e)o(xample)e(of)h(a)h(locale) f(which)g(does)g(de\002ne)g(this)h(v)n(alue)f(is)h(the)f(Japanese)g (one.)208 3032 y(In)c(Japan,)g(the)g(traditional)f(representation)g(of) h(dates)g(includes)g(the)g(name)g(of)g(the)g(era)h(corresponding)c(to)j (the)g(then-emperor')-5 b(s)208 3132 y(reign.)208 3265 y(Normally)20 b(it)i(should)f(not)g(be)g(necessary)g(to)h(use)g(this)g (v)n(alue)f(directly)-5 b(.)27 b(Specifying)20 b(the)i FJ(E)g FN(modi\002er)e(in)i(their)f(format)g(strings)208 3364 y(causes)i(the)f FJ(strftime)g FN(function)f(to)i(use)g(this)g (information.)31 b(The)22 b(format)g(of)g(the)h(returned)e(string)h(is) i(not)e(speci\002ed,)h(and)208 3464 y(therefore)18 b(you)h(should)g (not)h(assume)g(kno)n(wledge)e(of)i(it)h(on)f(dif)n(ferent)f(systems.)0 3611 y FD(ERA_YEAR)208 3710 y FN(The)g(return)g(v)n(alue)h(gi)n(v)o(es) g(the)g(year)f(in)i(the)f(rele)n(v)n(ant)f(era)h(of)g(the)g(locale.)0 3857 y FD(ERA_D_T_FMT)208 3957 y FN(This)g(return)f(v)n(alue)g(can)h (be)g(used)f(as)i(a)g(format)e(string)g(for)h FJ(strftime)f FN(to)h(represent)f(dates)h(and)f(times)i(in)f(a)g(locale-speci\002c) 208 4056 y(era-based)e(w)o(ay)-5 b(.)0 4203 y FD(ERA_D_FMT)208 4303 y FN(This)21 b(return)f(v)n(alue)h(can)g(be)h(used)f(as)h(a)g (format)e(string)h(for)g FJ(strftime)g FN(to)g(represent)f(time)i(in)g (a)f(locale-speci\002c)g(era-based)208 4403 y(w)o(ay)-5 b(.)0 4549 y FD(ALT_DIGITS)208 4649 y FN(The)19 b(return)g(v)n(alue)h (is)h(a)g(representation)d(of)i(up)f(to)i(100)e(v)n(alues)h(used)g(to)g (represent)f(the)h(v)n(alues)g(0)g(to)h(99.)0 4796 y(Example:)p 0 5549 3901 4 v 0 5649 a FI(21.2.)52 b FJ(locale)22 b FI(\227)h(Inter)r(nationalization)j(ser)r(vices)2068 b(753)p eop end %%Page: 754 766 TeXDict begin 754 765 bop 236 174 a FA(>>>)45 b(import)e(locale)236 266 y(>>>)i(loc)f(=)h(locale.getlocale\(locale.LC_ALL\))39 b(#)45 b(get)f(current)g(locale)236 357 y(>>>)h (locale.setlocale\(locale.LC_ALL,)39 b('de_DE'\))44 b(#)g(use)h(German) e(locale;)h(name)g(might)g(vary)g(with)h(platform)236 448 y(>>>)g(locale.strcoll\('f\\xe4n',)40 b('foo'\))k(#)h(compare)e(a)i (string)f(containing)f(an)i(umlaut)236 540 y(>>>)g (locale.setlocale\(locale.LC_ALL,)39 b(''\))44 b(#)h(use)f(user's)g (preferred)g(locale)236 631 y(>>>)h(locale.setlocale\(locale.LC_ALL,)39 b('C'\))44 b(#)h(use)f(default)g(\(C\))g(locale)236 722 y(>>>)h(locale.setlocale\(locale.LC_ALL,)39 b(loc\))44 b(#)h(restore)f(saved)g(locale)0 1146 y Fv(21.2.1)101 b(Bac)n(kg)o(round,)30 b(details)o(,)d(hints)o(,)h(tips)f(and)i(ca)n(v) n(eats)0 1348 y FN(The)23 b(C)h(standard)e(de\002nes)h(the)g(locale)g (as)h(a)f(program-wide)d(property)h(that)i(may)g(be)g(relati)n(v)o(ely) f(e)o(xpensi)n(v)o(e)f(to)i(change.)33 b(On)23 b(top)g(of)0 1448 y(that,)e(some)g(implementation)e(are)i(brok)o(en)f(in)h(such)g(a) g(w)o(ay)h(that)f(frequent)e(locale)i(changes)f(may)h(cause)g(core)g (dumps.)26 b(This)c(mak)o(es)0 1548 y(the)e(locale)g(some)n(what)g (painful)f(to)h(use)g(correctly)-5 b(.)0 1695 y(Initially)g(,)28 b(when)f(a)h(program)d(is)k(started,)g(the)e(locale)h(is)g(the)g(`)p FJ(C)p FN(')f(locale,)i(no)e(matter)g(what)g(the)h(user')-5 b(s)28 b(preferred)d(locale)i(is.)48 b(The)0 1794 y(program)30 b(must)j(e)o(xplicitly)e(say)i(that)g(it)g(w)o(ants)g(the)g(user')-5 b(s)32 b(preferred)f(locale)h(settings)h(by)f(calling)g FJ(setlocale\(LC_ALL,)0 1894 y(''\))p FN(.)0 2041 y(It)c(is)g (generally)e(a)h(bad)g(idea)g(to)h(call)g FJ(setlocale\(\))d FN(in)j(some)f(library)f(routine,)i(since)f(as)h(a)g(side)g(ef)n(fect)f (it)h(af)n(fects)f(the)g(entire)0 2140 y(program.)k(Sa)n(ving)23 b(and)f(restoring)g(it)h(is)h(almost)f(as)h(bad:)30 b(it)24 b(is)g(e)o(xpensi)n(v)o(e)d(and)h(af)n(fects)h(other)f(threads)g(that)h (happen)f(to)h(run)f(before)0 2240 y(the)e(settings)h(ha)n(v)o(e)e (been)h(restored.)0 2387 y(If,)25 b(when)f(coding)f(a)i(module)f(for)g (general)f(use,)j(you)d(need)h(a)h(locale)g(independent)d(v)o(ersion)h (of)h(an)h(operation)d(that)j(is)h(af)n(fected)d(by)0 2486 y(the)e(locale)g(\(such)g(as)h FJ(string.lower\(\))p FN(,)e(or)h(certain)f(formats)h(used)g(with)h FJ(time.strftime\(\))p FN(\),)c(you)j(will)h(ha)n(v)o(e)f(to)g(\002nd)g(a)0 2586 y(w)o(ay)g(to)g(do)f(it)i(without)e(using)g(the)h(standard)e (library)h(routine.)26 b(Ev)o(en)19 b(better)i(is)g(con)m(vincing)d (yourself)i(that)h(using)f(locale)h(settings)g(is)0 2686 y(okay)-5 b(.)23 b(Only)d(as)h(a)g(last)g(resort)f(should)f(you)g (document)f(that)j(your)e(module)f(is)k(not)d(compatible)g(with)h (non-`)p FJ(C)p FN(')e(locale)i(settings.)0 2833 y(The)59 b(case)h(con)m(v)o(ersion)d(functions)h(in)i(the)g FJ(string)f FN(module)f(are)i(af)n(fected)e(by)h(the)h(locale)f(settings.)144 b(When)59 b(a)0 2932 y(call)48 b(to)f(the)g FJ(setlocale\(\))e FN(function)h(changes)g(the)h FJ(LC_CTYPE)f FN(settings,)54 b(the)47 b(v)n(ariables)f FJ(string.lowercase)p FN(,)0 3032 y FJ(string.uppercase)25 b FN(and)i FJ(string.letters)f FN(are)h(recalculated.)46 b(Note)28 b(that)g(code)f(that)g(uses)h (these)g(v)n(ariable)f(through)0 3131 y(`)p FJ(from)h FN(...)50 b FJ(import)28 b FN(...)-6 b(',)29 b(e.g.)f FJ(from)49 b(string)g(import)g(letters)p FN(,)29 b(is)h(not)e(af)n (fected)f(by)h(subsequent)f FJ(setlocale\(\))0 3231 y FN(calls.)0 3378 y(The)g(only)f(w)o(ay)h(to)g(perform)e(numeric)h (operations)g(according)f(to)i(the)g(locale)g(is)h(to)f(use)g(the)g (special)h(functions)d(de\002ned)h(by)h(this)0 3478 y(module:)d FJ(atof\(\))p FN(,)19 b FJ(atoi\(\))p FN(,)h FJ(format\(\))p FN(,)f FJ(str\(\))p FN(.)0 3763 y Fv(21.2.2)101 b(F)m(or)28 b(e)m(xtension)h(wr)q(iters)f(and)h(prog)o(r)o(ams)h(that)d(embed)j (Python)0 3965 y FN(Extension)d(modules)g(should)h(ne)n(v)o(er)f(call)i FJ(setlocale\(\))p FN(,)f(e)o(xcept)g(to)g(\002nd)g(out)h(what)f(the)g (current)f(locale)i(is.)50 b(But)29 b(since)g(the)0 4065 y(return)22 b(v)n(alue)g(can)h(only)f(be)h(used)f(portably)g(to)h (restore)f(it,)i(that)f(is)h(not)f(v)o(ery)e(useful)i(\(e)o(xcept)e (perhaps)h(to)h(\002nd)g(out)f(whether)g(or)h(not)0 4165 y(the)d(locale)g(is)h(`)p FJ(C)p FN('\).)0 4312 y(When)g(Python)g(code) g(uses)h(the)g FJ(locale)f FN(module)f(to)i(change)e(the)i(locale,)f (this)h(also)g(af)n(fects)g(the)f(embedding)e(application.)28 b(If)22 b(the)0 4411 y(embedding)i(application)g(doesn')o(t)h(w)o(ant)h (this)g(to)h(happen,)e(it)i(should)e(remo)o(v)o(e)f(the)i FJ(_locale)f FN(e)o(xtension)g(module)g(\(which)g(does)0 4511 y(all)d(the)g(w)o(ork\))f(from)g(the)h(table)g(of)g(b)n(uilt-in)f (modules)g(in)h(the)g(`)p FO(con\002g.c)p FN(')f(\002le,)i(and)e(mak)o (e)h(sure)f(that)h(the)g FJ(_locale)g FN(module)e(is)j(not)0 4610 y(accessible)d(as)h(a)g(shared)e(library)-5 b(.)0 4895 y Fv(21.2.3)101 b(Access)27 b(to)h(message)h(catalogs)0 5098 y FN(The)c(locale)g(module)e(e)o(xposes)i(the)g(C)h(library')-5 b(s)24 b(gette)o(xt)h(interf)o(ace)f(on)h(systems)g(that)g(pro)o(vide)e (this)j(interf)o(ace.)39 b(It)25 b(consists)h(of)f(the)0 5198 y(functions)e FJ(gettext\(\))p FN(,)h FJ(dgettext\(\))p FN(,)g FJ(dcgettext\(\))p FN(,)f FJ(textdomain\(\))p FN(,)h FJ(bindtextdomain\(\))p FN(,)e(and)i FJ(bind_-)0 5297 y(textdomain_codeset\(\))p FN(.)c(These)c(are)g(similar)g(to)h (the)f(same)g(functions)e(in)j(the)f FJ(gettext)f FN(module,)g(b)n(ut)h (use)g(the)g(C)h(library')-5 b(s)0 5397 y(binary)19 b(format)g(for)h (message)g(catalogs,)f(and)h(the)g(C)h(library')-5 b(s)20 b(search)f(algorithms)g(for)h(locating)f(message)h(catalogs.)p 0 5549 3901 4 v 0 5649 a FI(754)2578 b(Chapter)23 b(21.)52 b(Inter)r(nationalization)p eop end %%Page: 755 767 TeXDict begin 755 766 bop 0 83 a FN(Python)26 b(applications)h(should)f (normally)g(\002nd)i(no)f(need)g(to)g(in)m(v)n(ok)o(e)g(these)g (functions,)h(and)f(should)g(use)g FJ(gettext)g FN(instead.)47 b(A)0 183 y(kno)n(wn)18 b(e)o(xception)g(to)i(this)g(rule)g(are)f (applications)g(that)h(link)f(use)h(additional)e(C)j(libraries)e(which) h(internally)e(in)m(v)n(ok)o(e)h FJ(gettext\(\))0 282 y FN(or)29 b FJ(dcgettext\(\))p FN(.)52 b(F)o(or)29 b(these)h (applications,)g(it)h(may)e(be)g(necessary)g(to)h(bind)f(the)g(te)o(xt) h(domain,)g(so)g(that)g(the)g(libraries)f(can)0 382 y(properly)18 b(locate)i(their)g(message)g(catalogs.)p 0 5549 3901 4 v 0 5649 a FI(21.2.)52 b FJ(locale)22 b FI(\227)h(Inter)r (nationalization)j(ser)r(vices)2068 b(755)p eop end %%Page: 756 768 TeXDict begin 756 767 bop 0 5549 3901 4 v 0 5649 a FI(756)p eop end %%Page: 757 769 TeXDict begin 757 768 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3119 427 y FG(TWENTYTW)n(O)p 0 515 V 1933 978 a FT(Prog)n(r)n(am)56 b(F)-9 b(r)n(ame)l(w)n(or)s(ks)0 1468 y FN(The)17 b(modules)f (described)g(in)h(this)h(chapter)e(are)i(frame)n(w)o(orks)d(that)i (will)h(lar)o(gely)e(dictate)h(the)h(structure)e(of)h(your)f(program.) 22 b(Currently)0 1568 y(the)e(modules)f(described)g(here)h(are)g(all)h (oriented)e(to)n(w)o(ard)g(writing)h(command-line)d(interf)o(aces.)0 1714 y(The)j(full)g(list)h(of)f(modules)f(described)g(in)h(this)h (chapter)e(is:)50 1858 y FD(cmd)199 b FN(Build)20 b(line-oriented)e (command)g(interpreters.)50 1957 y FD(shlex)99 b FN(Simple)20 b(le)o(xical)f(analysis)i(for)g(U)t FH(N)t(I)t(X)i FN(shell-lik)o(e)d (languages.)0 2261 y FE(22.1)121 b Fx(cmd)33 b FE(\227)f(Suppor)5 b(t)35 b(f)l(or)f(line-or)r(iented)h(command)f(inter)t(preters)0 2494 y FN(The)25 b FJ(Cmd)f FN(class)i(pro)o(vides)d(a)j(simple)e (frame)n(w)o(ork)f(for)h(writing)h(line-oriented)d(command)h (interpreters.)38 b(These)24 b(are)h(often)f(useful)0 2594 y(for)c(test)h(harnesses,)e(administrati)n(v)o(e)g(tools,)h(and)f (prototypes)g(that)h(will)h(later)f(be)g(wrapped)f(in)h(a)h(more)e (sophisticated)g(interf)o(ace.)0 2741 y FL(class)i FD(Cmd)p FJ(\()p FC([)p FK(completek)o(e)n(y)p FC([)p FK(,)c(stdin)p FC([)p FK(,)j(stdout)13 b FC(])f(])g(])p FJ(\))208 2840 y FN(A)19 b FJ(Cmd)h FN(instance)f(or)g(subclass)g(instance)g(is)h(a)g (line-oriented)d(interpreter)h(frame)n(w)o(ork.)k(There)d(is)h(no)f (good)f(reason)h(to)g(instan-)208 2940 y(tiate)24 b FJ(Cmd)g FN(itself;)j(rather)m(,)d(it')-5 b(s)25 b(useful)f(as)h(a)f(superclass) g(of)g(an)g(interpreter)f(class)i(you)e(de\002ne)h(yourself)f(in)h (order)f(to)h(inherit)208 3040 y FJ(Cmd)p FN(')-5 b(s)20 b(methods)f(and)h(encapsulate)f(action)h(methods.)208 3172 y(The)k(optional)g(ar)o(gument)f FK(completek)o(e)n(y)g FN(is)j(the)f FJ(readline)f FN(name)h(of)g(a)g(completion)e(k)o(e)o(y;) k(it)f(def)o(aults)e(to)i FJ(Tab)p FN(.)39 b(If)25 b FK(com-)208 3272 y(pletek)o(e)n(y)19 b FN(is)i(not)f FJ(None)g FN(and)g FJ(readline)f FN(is)i(a)n(v)n(ailable,)e(command)g (completion)f(is)j(done)e(automatically)-5 b(.)208 3405 y(The)31 b(optional)f(ar)o(guments)g FK(stdin)h FN(and)g FK(stdout)i FN(specify)e(the)h(input)f(and)g(output)f(\002le)i(objects) g(that)f(the)h(Cmd)g(instance)f(or)208 3504 y(subclass)20 b(instance)g(will)h(use)f(for)g(input)f(and)h(output.)k(If)c(not)f (speci\002ed,)h(the)o(y)g(will)g(def)o(ault)g(to)g FK(sys.stdin)h FN(and)e FK(sys.stdout)q FN(.)208 3637 y(Changed)f(in)j(v)o(ersion)e (2.3:)g(The)h FK(stdin)g FN(and)g FK(stdout)h FN(parameters)e(were)h (added.)0 3922 y Fv(22.1.1)101 b(Cmd)28 b(Objects)0 4125 y FN(A)21 b FJ(Cmd)f FN(instance)g(has)g(the)g(follo)n(wing)f(methods:) 0 4271 y FD(cmdloop)p FJ(\()p FC([)p FK(intr)l(o)12 b FC(])p FJ(\))208 4371 y FN(Repeatedly)26 b(issue)i(a)g(prompt,)f (accept)g(input,)i(parse)e(an)g(initial)h(pre\002x)f(of)n(f)f(the)i (recei)n(v)o(ed)e(input,)i(and)f(dispatch)g(to)g(action)208 4471 y(methods,)18 b(passing)i(them)g(the)g(remainder)f(of)g(the)i (line)f(as)h(ar)o(gument.)208 4603 y(The)f(optional)g(ar)o(gument)e(is) k(a)g(banner)d(or)i(intro)f(string)h(to)g(be)f(issued)h(before)f(the)h (\002rst)h(prompt)d(\(this)i(o)o(v)o(errides)e(the)i FJ(intro)208 4703 y FN(class)g(member\).)208 4836 y(If)42 b(the)h FJ(readline)e FN(module)g(is)j(loaded,)j(input)42 b(will)h(automatically)e(inherit)h FL(bash)p FN(-lik)o(e)h (history-list)f(editing)f(\(e.g.)208 4935 y FJ(Control-P)28 b FN(scrolls)h(back)f(to)i(the)f(last)h(command,)f FJ(Control-N)f FN(forw)o(ard)f(to)j(the)f(ne)o(xt)f(one,)j FJ(Control-F)d FN(mo)o(v)o(es)208 5035 y(the)20 b(cursor)f(to)h(the)h(right)e (non-destructi)n(v)o(ely)-5 b(,)16 b FJ(Control-B)j FN(mo)o(v)o(es)g (the)h(cursor)g(to)g(the)g(left)g(non-destructi)n(v)o(ely)-5 b(,)16 b(etc.\).)208 5168 y(An)k(end-of-\002le)e(on)i(input)f(is)i (passed)f(back)g(as)h(the)f(string)g FJ('EOF')p FN(.)208 5300 y(An)j(interpreter)f(instance)i(will)g(recognize)e(a)i(command)e (name)h(`)p FJ(foo)p FN(')g(if)h(and)f(only)g(if)h(it)h(has)f(a)g (method)e FJ(do_foo\(\))p FN(.)35 b(As)208 5400 y(a)25 b(special)h(case,)h(a)f(line)f(be)o(ginning)e(with)j(the)f(character)g (`)p FJ(?)p FN(')40 b(is)27 b(dispatched)d(to)i(the)f(method)f FJ(do_help\(\))p FN(.)40 b(As)26 b(another)p 0 5549 3901 4 v 3762 5649 a FI(757)p eop end %%Page: 758 770 TeXDict begin 758 769 bop 208 83 a FN(special)16 b(case,)h(a)f(line)g (be)o(ginning)e(with)i(the)g(character)f(`)p FJ(!)p FN(')23 b(is)17 b(dispatched)e(to)h(the)g(method)f FJ(do_shell\(\))g FN(\(if)h(such)f(a)i(method)208 183 y(is)k(de\002ned\).)208 315 y(This)d(method)e(will)j(return)e(when)g(the)h FJ(postcmd\(\))f FN(method)f(returns)h(a)i(true)e(v)n(alue.)24 b(The)17 b FK(stop)h FN(ar)o(gument)e(to)i FJ(postcmd\(\))208 415 y FN(is)j(the)f(return)f(v)n(alue)g(from)h(the)g(command')-5 b(s)18 b(corresponding)f FJ(do_)2177 430 y(*)2227 415 y(\(\))j FN(method.)208 548 y(If)g(completion)f(is)j(enabled,)e (completing)f(commands)g(will)i(be)g(done)f(automatically)-5 b(,)19 b(and)h(completing)f(of)i(commands)e(ar)o(gs)208 648 y(is)26 b(done)e(by)h(calling)f FJ(complete_foo\(\))g FN(with)h(ar)o(guments)e FK(te)n(xt)q FN(,)28 b FK(line)p FN(,)e FK(be)m(gidx)p FN(,)f(and)g FK(endidx)p FN(.)39 b FK(te)n(xt)27 b FN(is)f(the)f(string)g(pre\002x)208 747 y(we)d(are)h(attempting)e(to)i(match:)29 b(all)23 b(returned)d(matches)i(must)h(be)o(gin)e(with)i(it.)32 b FK(line)23 b FN(is)g(the)g(current)e(input)g(line)i(with)g(leading) 208 847 y(whitespace)c(remo)o(v)o(ed,)e FK(be)m(gidx)i FN(and)h FK(endidx)f FN(are)h(the)g(be)o(ginning)d(and)j(ending)f(inde) o(x)o(es)f(of)i(the)g(pre\002x)f(te)o(xt,)h(which)g(could)f(be)208 946 y(used)g(to)i(pro)o(vide)d(dif)n(ferent)g(completion)h(depending)e (upon)i(which)h(position)f(the)h(ar)o(gument)e(is)j(in.)208 1079 y(All)c(subclasses)h(of)f FJ(Cmd)g FN(inherit)f(a)i(prede\002ned)d FJ(do_help\(\))p FN(.)22 b(This)c(method,)e(called)h(with)g(an)g(ar)o (gument)d FJ('bar')p FN(,)k(in)m(v)n(ok)o(es)208 1179 y(the)k(corresponding)e(method)h FJ(help_bar\(\))p FN(.)32 b(W)m(ith)23 b(no)f(ar)o(gument,)f FJ(do_help\(\))h FN(lists)i(all)f(a) n(v)n(ailable)g(help)f(topics)h(\(that)208 1279 y(is,)d(all)h(commands) e(with)h(corresponding)d FJ(help_)1703 1294 y(*)1753 1279 y(\(\))i FN(methods\),)g(and)g(also)i(lists)g(an)o(y)f (undocumented)c(commands.)0 1425 y FD(onecmd)p FJ(\()p FK(str)r FJ(\))208 1525 y FN(Interpret)27 b(the)i(ar)o(gument)d(as)k (though)d(it)i(had)f(been)g(typed)g(in)h(response)f(to)h(the)g(prompt.) 49 b(This)29 b(may)f(be)h(o)o(v)o(erridden,)f(b)n(ut)208 1625 y(should)17 b(not)i(normally)e(need)i(to)g(be;)g(see)h(the)f FJ(precmd\(\))f FN(and)g FJ(postcmd\(\))g FN(methods)g(for)g(useful)h (e)o(x)o(ecution)d(hooks.)24 b(The)208 1724 y(return)f(v)n(alue)g(is)j (a)e(\003ag)h(indicating)e(whether)g(interpretation)f(of)i(commands)f (by)h(the)g(interpreter)f(should)g(stop.)38 b(If)24 b(there)g(is)208 1824 y(a)e FJ(do_)417 1839 y(*)467 1824 y(\(\))e FN(method)h(for)g(the) g(command)f FK(str)r FN(,)i(the)g(return)e(v)n(alue)h(of)g(that)h (method)e(is)j(returned,)c(otherwise)i(the)h(return)e(v)n(alue)208 1924 y(from)f(the)h FJ(default\(\))f FN(method)g(is)i(returned.)0 2070 y FD(emptyline)p FJ(\(\))208 2170 y FN(Method)26 b(called)h(when)g(an)g(empty)g(line)h(is)g(entered)e(in)i(response)f (to)g(the)h(prompt.)45 b(If)27 b(this)h(method)e(is)j(not)e(o)o(v)o (erridden,)f(it)208 2270 y(repeats)19 b(the)i(last)g(nonempty)d (command)g(entered.)0 2417 y FD(default)p FJ(\()p FK(line)p FJ(\))208 2516 y FN(Method)i(called)h(on)f(an)i(input)e(line)h(when)g (the)g(command)e(pre\002x)i(is)h(not)f(recognized.)k(If)c(this)h (method)e(is)i(not)f(o)o(v)o(erridden,)d(it)208 2616 y(prints)h(an)i(error)e(message)h(and)f(returns.)0 2763 y FD(completedefault)p FJ(\()p FK(te)n(xt,)f(line)o(,)i(be)m(gidx,)e (endidx)p FJ(\))208 2862 y FN(Method)h(called)i(to)g(complete)f(an)g (input)h(line)f(when)h(no)f(command-speci\002c)e FJ(complete_)2942 2877 y(*)2992 2862 y(\(\))h FN(method)h(is)i(a)n(v)n(ailable.)k(By)208 2962 y(def)o(ault,)19 b(it)i(returns)e(an)h(empty)f(list.)0 3109 y FD(precmd)p FJ(\()p FK(line)p FJ(\))208 3208 y FN(Hook)h(method)g(e)o(x)o(ecuted)g(just)i(before)e(the)h(command)e (line)j FK(line)f FN(is)i(interpreted,)d(b)n(ut)h(after)g(the)g(input)g (prompt)f(is)i(generated)208 3308 y(and)g(issued.)33 b(This)23 b(method)f(is)h(a)h(stub)e(in)h FJ(Cmd)p FN(;)i(it)e(e)o (xists)h(to)f(be)g(o)o(v)o(erridden)c(by)k(subclasses.)33 b(The)23 b(return)e(v)n(alue)h(is)i(used)f(as)208 3408 y(the)c(command)e(which)i(will)h(be)f(e)o(x)o(ecuted)f(by)h(the)g FJ(onecmd\(\))f FN(method;)h(the)g FJ(precmd\(\))f FN(implementation)f (may)i(re-write)208 3507 y(the)h(command)e(or)i(simply)g(return)f FK(line)h FN(unchanged.)0 3654 y FD(postcmd)p FJ(\()p FK(stop,)e(line)p FJ(\))208 3754 y FN(Hook)26 b(method)g(e)o(x)o (ecuted)f(just)j(after)f(a)g(command)f(dispatch)g(is)i(\002nished.)46 b(This)27 b(method)f(is)j(a)e(stub)g(in)h FJ(Cmd)p FN(;)j(it)d(e)o (xists)f(to)208 3853 y(be)j(o)o(v)o(erridden)e(by)i(subclasses.)58 b FK(line)31 b FN(is)h(the)e(command)f(line)i(which)g(w)o(as)g(e)o(x)o (ecuted,)h(and)e FK(stop)h FN(is)h(a)f(\003ag)g(which)f(indi-)208 3953 y(cates)d(whether)e(e)o(x)o(ecution)g(will)i(be)f(terminated)g (after)g(the)g(call)h(to)g FJ(postcmd\(\))p FN(;)i(this)e(will)g(be)f (the)h(return)e(v)n(alue)h(of)h(the)208 4053 y FJ(onecmd\(\))22 b FN(method.)31 b(The)23 b(return)f(v)n(alue)g(of)h(this)g(method)f (will)h(be)g(used)g(as)h(the)f(ne)n(w)f(v)n(alue)h(for)f(the)h (internal)f(\003ag)h(which)208 4152 y(corresponds)17 b(to)k FK(stop)p FN(;)f(returning)e(f)o(alse)j(will)g(cause)f (interpretation)e(to)i(continue.)0 4299 y FD(preloop)p FJ(\(\))208 4399 y FN(Hook)f(method)g(e)o(x)o(ecuted)f(once)i(when)f FJ(cmdloop\(\))g FN(is)j(called.)j(This)20 b(method)f(is)i(a)g(stub)f (in)g FJ(Cmd)p FN(;)h(it)g(e)o(xists)f(to)h(be)f(o)o(v)o(errid-)208 4498 y(den)f(by)h(subclasses.)0 4645 y FD(postloop)p FJ(\(\))208 4745 y FN(Hook)f(method)f(e)o(x)o(ecuted)g(once)i(when)f FJ(cmdloop\(\))g FN(is)i(about)e(to)h(return.)k(This)c(method)f(is)i(a) f(stub)g(in)g FJ(Cmd)p FN(;)g(it)h(e)o(xists)f(to)h(be)208 4845 y(o)o(v)o(erridden)16 b(by)k(subclasses.)0 4991 y(Instances)g(of)g FJ(Cmd)g FN(subclasses)g(ha)n(v)o(e)g(some)g(public) f(instance)h(v)n(ariables:)0 5138 y FD(prompt)208 5238 y FN(The)f(prompt)g(issued)h(to)h(solicit)f(input.)0 5385 y FD(identchars)p 0 5549 3901 4 v 0 5649 a FI(758)2486 b(Chapter)23 b(22.)52 b(Prog)o(r)o(am)24 b(F)l(r)o(ame)n(w)o(or)q(ks)p eop end %%Page: 759 771 TeXDict begin 759 770 bop 208 83 a FN(The)19 b(string)h(of)g (characters)f(accepted)h(for)f(the)h(command)f(pre\002x.)0 230 y FD(lastcmd)208 330 y FN(The)g(last)i(nonempty)d(command)h (pre\002x)g(seen.)0 476 y FD(intro)208 576 y FN(A)h(string)g(to)g (issue)h(as)g(an)f(intro)g(or)g(banner)-5 b(.)24 b(May)c(be)g(o)o(v)o (erridden)d(by)i(gi)n(ving)g(the)h FJ(cmdloop\(\))g FN(method)e(an)i (ar)o(gument.)0 723 y FD(doc_header)208 823 y FN(The)f(header)g(to)i (issue)g(if)f(the)g(help)g(output)f(has)h(a)h(section)f(for)f (documented)f(commands.)0 969 y FD(misc_header)208 1069 y FN(The)j(header)f(to)i(issue)g(if)f(the)h(help)f(output)f(has)i(a)g (section)f(for)g(miscellaneous)f(help)h(topics)g(\(that)h(is,)g(there)f (are)g FJ(help_)3751 1084 y(*)3801 1069 y(\(\))208 1169 y FN(methods)e(without)g(corresponding)e FJ(do_)1430 1184 y(*)1480 1169 y(\(\))i FN(methods\).)0 1316 y FD(undoc_header)208 1415 y FN(The)25 b(header)g(to)i(issue)f(if)h(the)f(help)f(output)g (has)i(a)f(section)g(for)f(undocumented)e(commands)h(\(that)i(is,)i (there)e(are)g FJ(do_)3751 1430 y(*)3801 1415 y(\(\))208 1515 y FN(methods)19 b(without)g(corresponding)e FJ(help_)1530 1530 y(*)1580 1515 y(\(\))i FN(methods\).)0 1662 y FD(ruler)208 1761 y FN(The)i(character)g(used)h(to)g(dra)o(w)f(separator)g(lines)i (under)d(the)i(help-message)f(headers.)29 b(If)22 b(empty)-5 b(,)21 b(no)h(ruler)f(line)h(is)h(dra)o(wn.)29 b(It)208 1861 y(def)o(aults)19 b(to)i(`)p FJ(=)p FN('.)0 2008 y FD(use_rawinput)208 2107 y FN(A)28 b(\003ag,)h(def)o(aulting)d(to)i (true.)48 b(If)27 b(true,)i FJ(cmdloop\(\))e FN(uses)h FJ(raw_input\(\))f FN(to)h(display)f(a)h(prompt)e(and)h(read)h(the)f (ne)o(xt)208 2207 y(command;)18 b(if)i(f)o(alse,)h FJ (sys.stdout.write\(\))c FN(and)i FJ(sys.stdin.readline\(\))e FN(are)j(used.)25 b(\(This)20 b(means)g(that)g(by)208 2307 y(importing)25 b FJ(readline)p FN(,)k(on)e(systems)h(that)g (support)e(it,)k(the)e(interpreter)e(will)i(automatically)e(support)h FL(Emacs)p FN(-lik)o(e)g(line)208 2406 y(editing)19 b(and)h (command-history)c(k)o(e)o(ystrok)o(es.\))0 2734 y FE(22.2)121 b Fx(shlex)32 b FE(\227)h(Simple)f(le)l(xical)h(analysis)0 2966 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.5.2.)0 3113 y(The)h FJ(shlex)g FN(class)h(mak)o(es)f(it)h(easy)f(to)h(write)f(le)o (xical)g(analyzers)f(for)h(simple)g(syntax)o(es)f(resembling)g(that)i (of)e(the)k(U)t FH(N)t(I)t(X)g FN(shell.)i(This)0 3213 y(will)19 b(often)e(be)g(useful)h(for)f(writing)g(minilanguages,)f (\(for)h(e)o(xample,)f(in)i(run)f(control)g(\002les)i(for)e(Python)g (applications\))f(or)h(for)h(parsing)0 3313 y(quoted)h(strings.)0 3459 y FL(Note:)24 b FN(The)c FJ(shlex)g FN(module)f(currently)f(does)i (not)g(support)f(Unicode)g(input.)0 3606 y(The)h FJ(shlex)g FN(module)e(de\002nes)i(the)h(follo)n(wing)d(functions:)0 3753 y FD(split)p FJ(\()p FK(s)p FC([)p FK(,)h(comments)12 b FC(])p FJ(\))208 3853 y FN(Split)25 b(the)f(string)g FK(s)i FN(using)e(shell-lik)o(e)g(syntax.)37 b(If)24 b FK(comments)g FN(is)i FJ(False)e FN(\(the)g(def)o(ault\),)g(the)h (parsing)e(of)i(comments)e(in)i(the)208 3952 y(gi)n(v)o(en)f(string)h (will)h(be)f(disabled)g(\(setting)g(the)g FJ(commenters)f FN(member)g(of)h(the)g FJ(shlex)g FN(instance)g(to)h(the)f(empty)f (string\).)208 4052 y(This)d(function)f(operates)h(in)h(POSIX)g(mode.) 59 b(Ne)n(w)22 b(in)f(v)o(ersion)g(2.3.)59 b FL(Note:)27 b FN(Since)22 b(the)g FJ(split\(\))e FN(function)g(instantiates)208 4152 y(a)g FJ(shlex)g FN(instance,)g(passing)f FJ(None)h FN(for)g FK(s)h FN(will)g(read)f(the)g(string)g(to)g(split)h(from)e (standard)g(input.)0 4299 y(The)h FJ(shlex)g FN(module)e(de\002nes)i (the)h(follo)n(wing)d(class:)0 4445 y FL(class)j FD(shlex)p FJ(\()p FC([)p FK(instr)m(eam)p FC([)p FK(,)d(in\002le)p FC([)p FK(,)i(posix)12 b FC(])g(])g(])p FJ(\))208 4545 y FN(A)30 b FJ(shlex)f FN(instance)h(or)g(subclass)g(instance)f(is)i(a) f(le)o(xical)g(analyzer)e(object.)54 b(The)29 b(initialization)h(ar)o (gument,)f(if)h(present,)208 4645 y(speci\002es)22 b(where)g(to)h(read) e(characters)h(from.)30 b(It)23 b(must)f(be)h(a)f(\002le-/stream-lik)o (e)g(object)g(with)g FJ(read\(\))g FN(and)g FJ(readline\(\))208 4744 y FN(methods,)h(or)g(a)h(string)f(\(strings)g(are)g(accepted)g (since)g(Python)g(2.3\).)34 b(If)23 b(no)g(ar)o(gument)e(is)j(gi)n(v)o (en,)f(input)g(will)h(be)g(tak)o(en)f(from)208 4844 y FJ(sys.stdin)p FN(.)37 b(The)25 b(second)f(optional)f(ar)o(gument)g(is) i(a)h(\002lename)e(string,)h(which)g(sets)h(the)e(initial)i(v)n(alue)e (of)g(the)h FJ(infile)208 4944 y FN(member)-5 b(.)23 b(If)18 b(the)h FK(instr)m(eam)f FN(ar)o(gument)e(is)k(omitted)e(or)g (equal)g(to)g FJ(sys.stdin)p FN(,)g(this)h(second)e(ar)o(gument)f(def)o (aults)i(to)h(\223stdin\224.)208 5043 y(The)25 b FK(posix)h FN(ar)o(gument)e(w)o(as)j(introduced)c(in)j(Python)f(2.3,)h(and)g (de\002nes)g(the)f(operational)f(mode.)42 b(When)25 b FK(posix)h FN(is)h(not)f(true)208 5143 y(\(def)o(ault\),)h(the)g FJ(shlex)f FN(instance)h(will)g(operate)f(in)h(compatibility)f(mode.)44 b(When)27 b(operating)e(in)i(POSIX)g(mode,)h FJ(shlex)208 5242 y FN(will)20 b(try)g(to)h(be)f(as)h(close)f(as)h(possible)f(to)g (the)h(POSIX)f(shell)h(parsing)e(rules.)25 b(See)20 b(section)g (22.2.1.)0 5389 y FL(See)h(Also:)p 0 5549 3901 4 v 0 5649 a FI(22.2.)52 b FJ(shlex)22 b FI(\227)i(Simple)g(le)n(xical)g (analysis)2319 b(759)p eop end %%Page: 760 772 TeXDict begin 760 771 bop 0 83 a FN(Module)19 b FJ(ConfigParser)g FN(\(section)g(9.2\):)208 183 y(P)o(arser)h(for)f(con\002guration)f (\002les)j(similar)f(to)g(the)h(W)m(indo)n(ws)e(`)p FO(.ini)p FN(')g(\002les.)0 461 y Fv(22.2.1)101 b(shle)m(x)28 b(Objects)0 663 y FN(A)21 b FJ(shlex)f FN(instance)f(has)i(the)f(follo)n(wing)f (methods:)0 810 y FD(get_token)p FJ(\(\))208 910 y FN(Return)g(a)h(tok) o(en.)25 b(If)19 b(tok)o(ens)h(ha)n(v)o(e)f(been)g(stack)o(ed)h(using)g FJ(push_token\(\))p FN(,)e(pop)h(a)h(tok)o(en)f(of)n(f)h(the)g(stack.) 25 b(Otherwise,)19 b(read)208 1010 y(one)j(from)g(the)h(input)f (stream.)34 b(If)23 b(reading)e(encounters)h(an)h(immediate)f (end-of-\002le,)f FJ(self.eof)h FN(is)i(returned)e(\(the)g(empty)208 1109 y(string)d(\()p FJ('')p FN(\))h(in)g(non-POSIX)f(mode,)g(and)h FJ(None)g FN(in)g(POSIX)h(mode\).)0 1256 y FD(push_token)p FJ(\()p FK(str)r FJ(\))208 1356 y FN(Push)f(the)g(ar)o(gument)e(onto)h (the)h(tok)o(en)g(stack.)0 1503 y FD(read_token)p FJ(\(\))208 1602 y FN(Read)27 b(a)g(ra)o(w)g(tok)o(en.)44 b(Ignore)25 b(the)i(pushback)e(stack,)k(and)d(do)h(not)f(interpret)g(source)g (requests.)45 b(\(This)27 b(is)h(not)e(ordinarily)f(a)208 1702 y(useful)19 b(entry)h(point,)f(and)g(is)j(documented)17 b(here)j(only)f(for)h(the)g(sak)o(e)g(of)g(completeness.\))0 1849 y FD(sourcehook)p FJ(\()p FK(\002lename)p FJ(\))208 1948 y FN(When)j FJ(shlex)g FN(detects)g(a)h(source)e(request)h(\(see)h FJ(source)e FN(belo)n(w\))h(this)h(method)d(is)k(gi)n(v)o(en)d(the)h (follo)n(wing)f(tok)o(en)g(as)i(ar)o(gu-)208 2048 y(ment,)19 b(and)h(e)o(xpected)e(to)j(return)e(a)h(tuple)g(consisting)g(of)f(a)i (\002lename)f(and)f(an)i(open)e(\002le-lik)o(e)h(object.)208 2173 y(Normally)-5 b(,)16 b(this)i(method)f(\002rst)i(strips)f(an)o(y)f (quotes)g(of)n(f)g(the)h(ar)o(gument.)k(If)c(the)g(result)g(is)g(an)g (absolute)f(pathname,)g(or)g(there)h(w)o(as)208 2273 y(no)24 b(pre)n(vious)e(source)i(request)g(in)h(ef)n(fect,)f(or)g(the)h (pre)n(vious)e(source)g(w)o(as)j(a)f(stream)f(\(such)g(as)h FJ(sys.stdin)p FN(\),)f(the)g(result)h(is)208 2372 y(left)c(alone.)29 b(Otherwise,)21 b(if)h(the)g(result)f(is)i(a)f(relati)n(v)o(e)e (pathname,)g(the)i(directory)e(part)h(of)g(the)h(name)f(of)g(the)h (\002le)g(immediately)208 2472 y(before)i(it)i(on)f(the)g(source)g (inclusion)f(stack)i(is)g(prepended)d(\(this)j(beha)n(vior)d(is)k(lik)o (e)f(the)f(w)o(ay)g(the)h(C)g(preprocessor)d(handles)208 2571 y FJ(#include)48 b("file.h")p FN(\).)208 2697 y(The)23 b(result)i(of)f(the)g(manipulations)e(is)j(treated)f(as)h(a)g (\002lename,)f(and)g(returned)f(as)h(the)h(\002rst)g(component)d(of)h (the)i(tuple,)f(with)208 2796 y FJ(open\(\))i FN(called)i(on)f(it)h(to) g(yield)f(the)g(second)g(component.)44 b(\(Note:)c(this)28 b(is)g(the)f(re)n(v)o(erse)g(of)g(the)h(order)e(of)h(ar)o(guments)e(in) 208 2896 y(instance)19 b(initialization!\))208 3021 y(This)h(hook)f(is) i(e)o(xposed)d(so)j(that)f(you)f(can)h(use)g(it)h(to)f(implement)f (directory)g(search)g(paths,)h(addition)f(of)h(\002le)g(e)o(xtensions,) f(and)208 3120 y(other)25 b(namespace)f(hacks.)42 b(There)25 b(is)i(no)f(corresponding)c(`close')j(hook,)h(b)n(ut)g(a)g(shle)o(x)g (instance)f(will)i(call)f(the)g FJ(close\(\))208 3220 y FN(method)18 b(of)i(the)g(sourced)f(input)h(stream)g(when)g(it)g (returns)i FH(E)t(O)t(F)r FN(.)208 3345 y(F)o(or)d(more)h(e)o(xplicit)f (control)g(of)h(source)g(stacking,)f(use)h(the)g FJ(push_source\(\))f FN(and)g FJ(pop_source\(\))g FN(methods.)0 3492 y FD(push_source)p FJ(\()p FK(str)m(eam)p FC([)p FK(,)f(\002lename)12 b FC(])p FJ(\))208 3592 y FN(Push)21 b(an)h(input)f(source)g(stream)g (onto)g(the)h(input)f(stack.)29 b(If)22 b(the)f(\002lename)h(ar)o (gument)d(is)k(speci\002ed)e(it)h(will)h(later)e(be)h(a)n(v)n(ailable) 208 3691 y(for)k(use)i(in)f(error)f(messages.)47 b(This)27 b(is)h(the)g(same)f(method)f(used)h(internally)f(by)h(the)g FJ(sourcehook)f FN(method.)92 b(Ne)n(w)27 b(in)208 3791 y(v)o(ersion)18 b(2.1.)0 3938 y FD(pop_source)p FJ(\(\))208 4037 y FN(Pop)k(the)h(last-pushed)f(input)g(source)g(from)g(the)h (input)f(stack.)33 b(This)23 b(is)h(the)f(same)g(method)e(used)i (internally)e(when)i(the)g(le)o(x)o(er)208 4137 y(reaches)e FH(E)t(O)t(F)i FN(on)c(a)i(stack)o(ed)f(input)f(stream.)51 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 4284 y FD(error_leader)p FJ(\()p FC([)p FK(\002le)p FC([)p FK(,)e(line)12 b FC(])g(])p FJ(\))208 4383 y FN(This)25 b(method)f(generates)h(an)g(error)f (message)i(leader)e(in)i(the)f(format)g(of)g(a)j(U)t FH(N)t(I)t(X)g FN(C)e(compiler)f(error)f(label;)k(the)d(format)g(is)208 4483 y FJ('"\045s",)48 b(line)h(\045d:)99 b(')p FN(,)29 b(where)e(the)g(`)p FJ(\045s)p FN(')g(is)h(replaced)e(with)h(the)g (name)g(of)g(the)g(current)f(source)g(\002le)i(and)f(the)g(`)p FJ(\045d)p FN(')208 4583 y(with)20 b(the)g(current)f(input)g(line)i (number)d(\(the)i(optional)f(ar)o(guments)f(can)i(be)g(used)g(to)g(o)o (v)o(erride)e(these\).)208 4708 y(This)23 b(con)m(v)o(enience)d(is)k (pro)o(vided)d(to)i(encourage)e FJ(shlex)i FN(users)h(to)f(generate)f (error)g(messages)h(in)h(the)f(standard,)g(parseable)208 4807 y(format)c(understood)e(by)j(Emacs)g(and)g(other)h(U)t FH(N)t(I)t(X)i FN(tools.)0 4954 y(Instances)k(of)f FJ(shlex)h FN(subclasses)h(ha)n(v)o(e)e(some)h(public)g(instance)f(v)n(ariables)h (which)f(either)h(control)f(le)o(xical)h(analysis)g(or)g(can)g(be)0 5054 y(used)20 b(for)f(deb)n(ugging:)0 5201 y FD(commenters)208 5300 y FN(The)j(string)g(of)g(characters)f(that)i(are)f(recognized)e (as)k(comment)d(be)o(ginners.)29 b(All)23 b(characters)f(from)f(the)i (comment)e(be)o(ginner)208 5400 y(to)f(end)g(of)f(line)i(are)f (ignored.)j(Includes)c(just)i(`)p FJ(#)p FN(')f(by)f(def)o(ault.)p 0 5549 3901 4 v 0 5649 a FI(760)2486 b(Chapter)23 b(22.)52 b(Prog)o(r)o(am)24 b(F)l(r)o(ame)n(w)o(or)q(ks)p eop end %%Page: 761 773 TeXDict begin 761 772 bop 0 83 a FD(wordchars)208 183 y FN(The)16 b(string)h(of)g(characters)f(that)h(will)h(accumulate)e (into)g(multi-character)f(tok)o(ens.)24 b(By)17 b(def)o(ault,)g (includes)f(all)k FH(A)t(S)t(C)t(I)t(I)h FN(alphanu-)208 282 y(merics)f(and)f(underscore.)0 429 y FD(whitespace)208 529 y FN(Characters)26 b(that)g(will)i(be)e(considered)f(whitespace)h (and)g(skipped.)43 b(Whitespace)26 b(bounds)f(tok)o(ens.)44 b(By)27 b(def)o(ault,)g(includes)208 628 y(space,)19 b(tab,)h(linefeed)g(and)f(carriage-return.)0 775 y FD(escape)208 875 y FN(Characters)k(that)h(will)g(be)g(considered)e(as)i(escape.)35 b(This)24 b(will)g(be)g(only)f(used)g(in)h(POSIX)g(mode,)g(and)f (includes)g(just)h(`)p FM(n)p FN(')f(by)208 975 y(def)o(ault.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 1121 y FD(quotes)208 1221 y FN(Characters)26 b(that)h(will)g(be)f(considered)f(string)i (quotes.)43 b(The)27 b(tok)o(en)e(accumulates)h(until)h(the)f(same)h (quote)f(is)h(encountered)208 1321 y(again)i(\(thus,)j(dif)n(ferent)c (quote)i(types)g(protect)f(each)h(other)f(as)i(in)f(the)h(shell.\))54 b(By)31 b(def)o(ault,)h(includes)f FH(A)t(S)t(C)t(I)t(I)j FN(single)c(and)208 1420 y(double)18 b(quotes.)0 1567 y FD(escapedquotes)208 1667 y FN(Characters)25 b(in)i FJ(quotes)e FN(that)i(will)g(interpret)e(escape)h(characters)f (de\002ned)g(in)h FJ(escape)p FN(.)43 b(This)26 b(is)h(only)f(used)g (in)g(POSIX)208 1766 y(mode,)19 b(and)g(includes)h(just)g(`)p FJ(")p FN(')g(by)g(def)o(ault.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.) 0 1913 y FD(whitespace_split)208 2013 y FN(If)j FJ(True)p FN(,)g(tok)o(ens)f(will)i(only)f(be)g(split)g(in)h(whitespaces.)30 b(This)23 b(is)g(useful,)f(for)f(e)o(xample,)g(for)h(parsing)f(command) f(lines)i(with)208 2113 y FJ(shlex)p FN(,)d(getting)h(tok)o(ens)f(in)i (a)f(similar)h(w)o(ay)f(to)g(shell)h(ar)o(guments.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 2259 y FD(infile)208 2359 y FN(The)i(name)g(of)g(the)h(current)f(input)g(\002le,)h(as)h (initially)e(set)i(at)f(class)h(instantiation)d(time)i(or)g(stack)o(ed) f(by)g(later)h(source)f(requests.)208 2459 y(It)f(may)g(be)g(useful)g (to)g(e)o(xamine)f(this)h(when)g(constructing)e(error)h(messages.)0 2606 y FD(instream)208 2705 y FN(The)g(input)h(stream)g(from)f(which)h (this)g FJ(shlex)g FN(instance)g(is)h(reading)e(characters.)0 2852 y FD(source)208 2952 y FN(This)25 b(member)g(is)h FJ(None)g FN(by)f(def)o(ault.)41 b(If)25 b(you)g(assign)h(a)g(string)g (to)f(it,)j(that)e(string)f(will)i(be)e(recognized)f(as)i(a)g(le)o (xical-le)n(v)o(el)208 3051 y(inclusion)20 b(request)h(similar)h(to)g (the)g(`)p FJ(source)p FN(')f(k)o(e)o(yw)o(ord)f(in)i(v)n(arious)e (shells.)31 b(That)21 b(is,)i(the)f(immediately)e(follo)n(wing)g(tok)o (en)208 3151 y(will)j(opened)e(as)i(a)g(\002lename)g(and)f(input)g(tak) o(en)g(from)g(that)g(stream)h(until)h FH(E)t(O)t(F)r FN(,)g(at)f(which)f(point)g(the)h FJ(close\(\))f FN(method)f(of)208 3251 y(that)d(stream)g(will)h(be)g(called)f(and)g(the)g(input)g(source) f(will)j(again)d(become)g(the)h(original)g(input)f(stream.)25 b(Source)17 b(requests)h(may)208 3350 y(be)i(stack)o(ed)g(an)o(y)f (number)f(of)i(le)n(v)o(els)g(deep.)0 3497 y FD(debug)208 3597 y FN(If)h(this)i(member)d(is)j(numeric)d(and)i FJ(1)g FN(or)g(more,)f(a)h FJ(shlex)g FN(instance)f(will)i(print)e(v)o(erbose) f(progress)h(output)g(on)g(its)i(beha)n(vior)-5 b(.)208 3696 y(If)20 b(you)f(need)g(to)i(use)f(this,)h(you)e(can)h(read)g(the)g (module)f(source)g(code)h(to)g(learn)g(the)g(details.)0 3843 y FD(lineno)208 3943 y FN(Source)f(line)h(number)f(\(count)f(of)i (ne)n(wlines)g(seen)g(so)h(f)o(ar)f(plus)g(one\).)0 4090 y FD(token)208 4189 y FN(The)f(tok)o(en)h(b)n(uf)n(fer)-5 b(.)24 b(It)c(may)g(be)g(useful)g(to)g(e)o(xamine)f(this)i(when)e (catching)g(e)o(xceptions.)0 4336 y FD(eof)208 4436 y FN(T)-7 b(ok)o(en)16 b(used)i(to)g(determine)e(end)h(of)h(\002le.)25 b(This)17 b(will)i(be)f(set)g(to)g(the)g(empty)f(string)g(\()p FJ('')p FN(\),)g(in)h(non-POSIX)f(mode,)g(and)g(to)h FJ(None)208 4535 y FN(in)i(POSIX)h(mode.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.3.)0 4820 y Fv(22.2.2)101 b(P)l(arsing)29 b(Rules)0 5023 y FN(When)20 b(operating)e(in)j(non-POSIX)d(mode,)h FJ(shlex)h FN(will)h(try)f(to)h(obe)o(y)d(to)j(the)f(follo)n(wing)f (rules.)125 5253 y FM(\017)41 b FN(Quote)i(characters)g(are)h(not)g (recognized)e(within)i(w)o(ords)g(\()p FJ(Do"Not"Separate)e FN(is)j(parsed)e(as)i(the)f(single)g(w)o(ord)208 5353 y FJ(Do"Not"Separate)p FN(\);)p 0 5549 3901 4 v 0 5649 a FI(22.2.)52 b FJ(shlex)22 b FI(\227)i(Simple)g(le)n(xical)g(analysis) 2319 b(761)p eop end %%Page: 762 774 TeXDict begin 762 773 bop 125 83 a FM(\017)41 b FN(Escape)19 b(characters)h(are)g(not)g(recognized;)125 249 y FM(\017)41 b FN(Enclosing)18 b(characters)i(in)g(quotes)g(preserv)o(e)e(the)i (literal)h(v)n(alue)e(of)h(all)h(characters)e(within)h(the)g(quotes;) 125 415 y FM(\017)41 b FN(Closing)20 b(quotes)f(separate)h(w)o(ords)g (\()p FJ("Do"Separate)e FN(is)j(parsed)e(as)i FJ("Do")f FN(and)g FJ(Separate)p FN(\);)125 581 y FM(\017)41 b FN(If)21 b FJ(whitespace_split)e FN(is)j FJ(False)p FN(,)g(an)o(y)e (character)g(not)i(declared)e(to)h(be)h(a)g(w)o(ord)e(character)m(,)g (whitespace,)h(or)h(a)g(quote)208 681 y(will)e(be)h(returned)d(as)j(a)g (single-character)c(tok)o(en.)25 b(If)20 b(it)h(is)g FJ(True)p FN(,)e FJ(shlex)h FN(will)h(only)f(split)g(w)o(ords)g(in)h (whitespaces;)125 847 y FM(\017)41 b FN(EOF)20 b(is)h(signaled)f(with)g (an)g(empty)g(string)f(\()p FJ('')p FN(\);)125 1013 y FM(\017)41 b FN(It')-5 b(s)20 b(not)g(possible)g(to)h(parse)e(empty)h (strings,)g(e)n(v)o(en)f(if)h(quoted.)0 1243 y(When)g(operating)e(in)j (POSIX)f(mode,)f FJ(shlex)h FN(will)h(try)f(to)g(obe)o(y)f(to)i(the)f (follo)n(wing)e(parsing)i(rules.)125 1473 y FM(\017)41 b FN(Quotes)31 b(are)h(stripped)g(out,)i(and)e(do)f(not)h(separate)g(w) o(ords)g(\()p FJ("Do"Not"Separate")d FN(is)k(parsed)e(as)i(the)f (single)g(w)o(ord)208 1572 y FJ(DoNotSeparate)p FN(\);)125 1738 y FM(\017)41 b FN(Non-quoted)17 b(escape)j(characters)f(\(e.g.)24 b(`)p FM(n)p FN('\))c(preserv)o(e)e(the)j(literal)f(v)n(alue)f(of)h (the)h(ne)o(xt)e(character)g(that)h(follo)n(ws;)125 1904 y FM(\017)41 b FN(Enclosing)21 b(characters)h(in)h(quotes)f(which)g (are)h(not)f(part)h(of)f FJ(escapedquotes)f FN(\(e.g.)32 b(`)p FJ(')p FN('\))23 b(preserv)o(e)e(the)i(literal)g(v)n(alue)f(of) 208 2004 y(all)e(characters)g(within)g(the)g(quotes;)125 2170 y FM(\017)41 b FN(Enclosing)20 b(characters)i(in)g(quotes)g(which) g(are)g(part)g(of)g FJ(escapedquotes)e FN(\(e.g.)31 b(`)p FJ(")p FN('\))21 b(preserv)o(es)h(the)g(literal)g(v)n(alue)g(of)g(all) 208 2270 y(characters)c(within)h(the)h(quotes,)e(with)i(the)f(e)o (xception)f(of)h(the)h(characters)e(mentioned)f(in)j FJ(escape)p FN(.)k(The)19 b(escape)h(characters)208 2369 y(retain)g(its)i(special)g(meaning)d(only)i(when)f(follo)n(wed)g(by)h (the)g(quote)f(in)h(use,)g(or)g(the)g(escape)g(character)f(itself.)29 b(Otherwise)21 b(the)208 2469 y(escape)f(character)f(will)h(be)h (considered)d(a)j(normal)e(character)-5 b(.)125 2635 y FM(\017)41 b FN(EOF)20 b(is)h(signaled)f(with)g(a)h FJ(None)f FN(v)n(alue;)125 2801 y FM(\017)41 b FN(Quoted)19 b(empty)g(strings)h(\()p FJ('')p FN(\))g(are)g(allo)n(wed;)p 0 5549 3901 4 v 0 5649 a FI(762)2486 b(Chapter)23 b(22.)52 b(Prog)o(r)o(am)24 b(F)l(r)o(ame)n(w)o(or)q(ks)p eop end %%Page: 763 775 TeXDict begin 763 774 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)2990 427 y FG(TWENTYTHREE)p 0 515 V 2157 978 a FT(De)-6 b(v)h(elopment)57 b(T)-25 b(ools)0 1465 y FN(The)29 b(modules)f(described)f(in)j(this)f (chapter)f(help)h(you)f(write)h(softw)o(are.)51 b(F)o(or)29 b(e)o(xample,)h(the)f FJ(pydoc)f FN(module)g(tak)o(es)h(a)h(module)0 1565 y(and)h(generates)f(documentation)f(based)i(on)g(the)g(module')-5 b(s)31 b(contents.)58 b(The)31 b FJ(doctest)g FN(and)f FJ(unittest)h FN(modules)f(contains)0 1664 y(frame)n(w)o(orks)18 b(for)i(writing)g(unit)f(tests)j(that)e(automatically)f(e)o(x)o(ercise) g(code)h(and)f(v)o(erify)g(that)h(the)g(e)o(xpected)f(output)g(is)i (produced.)0 1811 y(The)f(list)h(of)f(modules)f(described)g(in)h(this)h (chapter)e(is:)50 1954 y FD(pydoc)696 b FN(Documentation)18 b(generator)g(and)i(online)f(help)h(system.)50 2054 y FD(doctest)596 b FN(A)21 b(frame)n(w)o(ork)d(for)i(v)o(erifying)d (interacti)n(v)o(e)i(Python)g(e)o(xamples.)50 2154 y FD(unittest)546 b FN(Unit)21 b(testing)f(frame)n(w)o(ork)e(for)h (Python.)50 2253 y FD(test)746 b FN(Re)o(gression)20 b(tests)h(package)e(containing)f(the)i(testing)g(suite)h(for)f(Python.) 50 2353 y FD(test.test_support)96 b FN(Support)19 b(for)h(Python)f(re)o (gression)f(tests.)0 2655 y FE(23.1)121 b Fx(pydoc)32 b FE(\227)h(Documentation)j(gener)o(ator)g(and)e(online)h(help)f (system)0 2888 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 3035 y(The)26 b FJ(pydoc)g FN(module)f(automatically)f(generates)i (documentation)d(from)i(Python)g(modules.)42 b(The)26 b(documentation)d(can)j(be)g(pre-)0 3135 y(sented)20 b(as)h(pages)f(of)f(te)o(xt)i(on)e(the)i(console,)e(serv)o(ed)g(to)h(a) h(W)-7 b(eb)21 b(bro)n(wser)m(,)d(or)i(sa)n(v)o(ed)g(to)g(HTML)g (\002les.)0 3282 y(The)29 b(b)n(uilt-in)g(function)e FJ(help\(\))i FN(in)m(v)n(ok)o(es)g(the)g(online)g(help)g(system)g(in)h (the)f(interacti)n(v)o(e)f(interpreter)m(,)i(which)e(uses)i FJ(pydoc)f FN(to)0 3381 y(generate)21 b(its)h(documentation)d(as)k(te)o (xt)f(on)f(the)h(console.)29 b(The)21 b(same)h(te)o(xt)g(documentation) d(can)j(also)g(be)f(vie)n(wed)h(from)e(outside)i(the)0 3481 y(Python)d(interpreter)g(by)g(running)f FL(pydoc)i FN(as)h(a)g(script)f(at)h(the)f(operating)e(system')-5 b(s)21 b(command)d(prompt.)24 b(F)o(or)19 b(e)o(xample,)g(running)236 3719 y FA(pydoc)44 b(sys)0 4006 y FN(at)28 b(a)f(shell)g(prompt)f(will) i(display)e(documentation)e(on)j(the)g FJ(sys)g FN(module,)g(in)g(a)h (style)f(similar)h(to)f(the)g(manual)f(pages)h(sho)n(wn)f(by)0 4105 y(the)i(U)t FH(N)t(I)t(X)h FL(man)e FN(command.)41 b(The)26 b(ar)o(gument)e(to)i FL(pydoc)g FN(can)g(be)g(the)h(name)e(of) h(a)h(function,)f(module,)g(or)g(package,)g(or)g(a)g(dotted)0 4205 y(reference)f(to)h(a)h(class,)h(method,)e(or)g(function)f(within)h (a)g(module)f(or)h(module)f(in)h(a)h(package.)42 b(If)26 b(the)g(ar)o(gument)e(to)i FL(pydoc)g FN(looks)0 4304 y(lik)o(e)21 b(a)h(path)f(\(that)f(is,)i(it)g(contains)f(the)g(path)f (separator)g(for)h(your)f(operating)f(system,)i(such)g(as)h(a)f(slash)h (in)h(U)t FH(N)t(I)t(X)r FN(\),)f(and)f(refers)f(to)i(an)0 4404 y(e)o(xisting)d(Python)g(source)h(\002le,)h(then)e(documentation)e (is)22 b(produced)17 b(for)j(that)g(\002le.)0 4551 y(Specifying)k(a)j FL(-w)f FN(\003ag)g(before)e(the)i(ar)o(gument)e(will)j(cause)f(HTML)f (documentation)e(to)j(be)g(written)g(out)g(to)g(a)g(\002le)h(in)f(the)g (current)0 4651 y(directory)-5 b(,)18 b(instead)i(of)g(displaying)e(te) o(xt)i(on)g(the)g(console.)0 4797 y(Specifying)f(a)h FL(-k)h FN(\003ag)g(before)e(the)h(ar)o(gument)e(will)j(search)f(the)g (synopsis)g(lines)h(of)f(all)h(a)n(v)n(ailable)f(modules)f(for)h(the)g (k)o(e)o(yw)o(ord)f(gi)n(v)o(en)0 4897 y(as)i(the)f(ar)o(gument,)e (again)i(in)g(a)h(manner)e(similar)h(to)h(the)h(U)t FH(N)t(I)t(X)h FL(man)e FN(command.)j(The)c(synopsis)f(line)i(of)f(a)h(module)e(is)i (the)f(\002rst)h(line)0 4997 y(of)f(its)h(documentation)c(string.)0 5144 y(Y)-9 b(ou)32 b(can)h(also)g(use)h FL(pydoc)e FN(to)i(start)f(an) g(HTTP)g(serv)o(er)f(on)h(the)g(local)g(machine)e(that)j(will)f(serv)o (e)g(documentation)d(to)j(visiting)0 5243 y(W)-7 b(eb)29 b(bro)n(wsers.)49 b FL(pydoc)29 b(-p)g(1234)e FN(will)i(start)g(a)g (HTTP)g(serv)o(er)e(on)h(port)g(1234,)h(allo)n(wing)f(you)f(to)i(bro)n (wse)f(the)h(documentation)0 5343 y(at)f FJ(http://localhost:1234/)d FN(in)j(your)e(preferred)g(W)-7 b(eb)29 b(bro)n(wser)-5 b(.)47 b FL(pydoc)27 b(-g)h FN(will)h(start)f(the)g(serv)o(er)f(and)g (additionally)p 0 5549 3901 4 v 3762 5649 a FI(763)p eop end %%Page: 764 776 TeXDict begin 764 775 bop 0 83 a FN(bring)19 b(up)h(a)g(small)h FJ(Tkinter)p FN(-based)d(graphical)h(interf)o(ace)g(to)i(help)e(you)h (search)f(for)h(documentation)d(pages.)0 230 y(When)26 b FL(pydoc)f FN(generates)g(documentation,)f(it)j(uses)f(the)g(current) e(en)m(vironment)f(and)i(path)h(to)g(locate)f(modules.)41 b(Thus,)27 b(in)m(v)n(oking)0 330 y FL(pydoc)d(spam)h FN(documents)d(precisely)h(the)h(v)o(ersion)f(of)h(the)g(module)f(you)g (w)o(ould)g(get)h(if)h(you)e(started)h(the)g(Python)f(interpreter)f (and)0 429 y(typed)d(`)p FJ(import)49 b(spam)p FN('.)0 576 y(Module)20 b(docs)h(for)f(core)g(modules)g(are)h(assumed)g(to)g (reside)f(in)i FO(http://www)l(.p)n(ython.org)o(/do)o(c/curren)o(t/l)o (ib)o(/)-6 b FN(.)28 b(This)21 b(can)g(be)g(o)o(v)o(erridden)0 676 y(by)g(setting)g(the)g(PYTHONDOCS)h(en)m(vironment)c(v)n(ariable)i (to)i(a)f(dif)n(ferent)f(URL)i(or)f(to)g(a)h(local)f(directory)e (containing)h(the)h(Library)0 775 y(Reference)e(Manual)h(pages.)0 1103 y FE(23.2)121 b Fx(doctest)32 b FE(\227)g(T)-14 b(est)34 b(inter)o(activ)m(e)g(Python)g(e)l(xamples)0 1336 y FN(The)23 b FJ(doctest)f FN(module)g(searches)h(for)f(pieces)h (of)g(te)o(xt)g(that)g(look)f(lik)o(e)i(interacti)n(v)o(e)d(Python)h (sessions,)j(and)d(then)h(e)o(x)o(ecutes)f(those)0 1435 y(sessions)f(to)f(v)o(erify)f(that)h(the)o(y)g(w)o(ork)f(e)o(xactly)h (as)g(sho)n(wn.)25 b(There)19 b(are)h(se)n(v)o(eral)g(common)e(w)o(ays) j(to)f(use)g(doctest:)125 1665 y FM(\017)41 b FN(T)-7 b(o)20 b(check)g(that)g(a)h(module')-5 b(s)20 b(docstrings)f(are)i (up-to-date)d(by)i(v)o(erifying)e(that)j(all)g(interacti)n(v)o(e)e(e)o (xamples)g(still)j(w)o(ork)e(as)h(docu-)208 1765 y(mented.)125 1931 y FM(\017)41 b FN(T)-7 b(o)28 b(perform)f(re)o(gression)g(testing) i(by)f(v)o(erifying)e(that)j(interacti)n(v)o(e)e(e)o(xamples)h(from)f (a)i(test)h(\002le)f(or)f(a)h(test)h(object)e(w)o(ork)g(as)208 2030 y(e)o(xpected.)125 2196 y FM(\017)41 b FN(T)-7 b(o)23 b(write)h(tutorial)g(documentation)c(for)j(a)i(package,)e(liberally)g (illustrated)g(with)h(input-output)d(e)o(xamples.)34 b(Depending)22 b(on)208 2296 y(whether)14 b(the)i(e)o(xamples)f(or)g (the)h(e)o(xpository)d(te)o(xt)j(are)g(emphasized,)f(this)h(has)g(the)g (\003a)n(v)n(or)f(of)h(\224literate)g(testing\224)f(or)h(\224e)o(x)o (ecutable)208 2396 y(documentation\224.)0 2626 y(Here')-5 b(s)20 b(a)h(complete)e(b)n(ut)h(small)h(e)o(xample)e(module:)p 0 5549 3901 4 v 0 5649 a FI(764)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 765 777 TeXDict begin 765 776 bop 236 174 a FA(""")236 266 y(This)44 b(is)h(the)f("example")g(module.)236 448 y(The)h(example)e(module)h (supplies)g(one)g(function,)f(factorial\(\).)88 b(For)44 b(example,)236 631 y(>>>)h(factorial\(5\))236 722 y(120)236 814 y(""")236 996 y(def)g(factorial\(n\):)416 1088 y("""Return)e(the)h (factorial)g(of)g(n,)h(an)f(exact)g(integer)g(>=)g(0.)416 1270 y(If)g(the)g(result)g(is)h(small)f(enough)g(to)g(fit)g(in)h(an)f (int,)g(return)g(an)h(int.)416 1362 y(Else)f(return)g(a)g(long.)416 1544 y(>>>)g([factorial\(n\))f(for)h(n)h(in)f(range\(6\)])416 1636 y([1,)g(1,)g(2,)h(6,)f(24,)h(120])416 1727 y(>>>)f ([factorial\(long\(n\)\))e(for)i(n)h(in)f(range\(6\)])416 1818 y([1,)g(1,)g(2,)h(6,)f(24,)h(120])416 1910 y(>>>)f (factorial\(30\))416 2001 y(265252859812191058636308480000000L)416 2092 y(>>>)g(factorial\(30L\))416 2183 y (265252859812191058636308480000000L)416 2275 y(>>>)g(factorial\(-1\)) 416 2366 y(Traceback)f(\(most)h(recent)g(call)g(last\):)595 2457 y(...)416 2549 y(ValueError:)f(n)h(must)g(be)h(>=)f(0)416 2731 y(Factorials)f(of)h(floats)g(are)g(OK,)h(but)f(the)g(float)g(must) g(be)h(an)f(exact)g(integer:)416 2823 y(>>>)g(factorial\(30.1\))416 2914 y(Traceback)f(\(most)h(recent)g(call)g(last\):)595 3005 y(...)416 3097 y(ValueError:)f(n)h(must)g(be)h(exact)f(integer)416 3188 y(>>>)g(factorial\(30.0\))416 3279 y (265252859812191058636308480000000L)416 3462 y(It)g(must)g(also)g(not)h (be)f(ridiculously)f(large:)416 3553 y(>>>)h(factorial\(1e100\))416 3645 y(Traceback)f(\(most)h(recent)g(call)g(last\):)595 3736 y(...)416 3827 y(OverflowError:)e(n)j(too)f(large)416 3919 y(""")p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(765)p eop end %%Page: 766 778 TeXDict begin 766 777 bop 416 266 a FA(import)43 b(math)416 357 y(if)h(not)g(n)h(>=)g(0:)595 448 y(raise)f(ValueError\("n)f(must)h (be)g(>=)h(0"\))416 540 y(if)f(math.floor\(n\))f(!=)h(n:)595 631 y(raise)g(ValueError\("n)f(must)h(be)g(exact)g(integer"\))416 722 y(if)g(n+1)g(==)h(n:)89 b(#)45 b(catch)f(a)h(value)f(like)g(1e300) 595 814 y(raise)g(OverflowError\("n)e(too)i(large"\))416 905 y(result)f(=)i(1)416 996 y(factor)e(=)i(2)416 1088 y(while)f(factor)f(<=)i(n:)595 1179 y(result)909 1192 y(*)954 1179 y(=)f(factor)595 1270 y(factor)g(+=)g(1)416 1362 y(return)f(result)236 1544 y(def)i(_test\(\):)416 1636 y(import)e(doctest)416 1727 y(doctest.testmod\(\))236 1910 y(if)i(__name__)e(==)i("__main__":)416 2001 y(_test\(\))0 2287 y FN(If)20 b(you)f(run)h(`)p FO(e)n(xample)o(.p)n(y)p FN(')d(directly)j(from)f(the)h(command)e(line,)i FJ(doctest)g FN(w)o(orks)f(its)j(magic:)236 2526 y FA($)45 b(python)f(example.py)236 2617 y($)0 2903 y FN(There')-5 b(s)20 b(no)h(output!)k(That')-5 b(s)21 b(normal,)f(and)g(it)h(means)g(all)g(the)g(e)o(xamples)f(w)o (ork)o(ed.)25 b(P)o(ass)d FL(-v)f FN(to)g(the)g(script,)f(and)h FJ(doctest)f FN(prints)g(a)0 3003 y(detailed)g(log)f(of)h(what)h(it')-5 b(s)21 b(trying,)e(and)g(prints)h(a)h(summary)e(at)h(the)g(end:)236 3241 y FA($)45 b(python)f(example.py)f(-v)236 3333 y(Trying:)416 3424 y(factorial\(5\))236 3515 y(Expecting:)416 3606 y(120)236 3698 y(ok)236 3789 y(Trying:)416 3880 y([factorial\(n\))f (for)j(n)f(in)h(range\(6\)])236 3972 y(Expecting:)416 4063 y([1,)f(1,)g(2,)h(6,)f(24,)h(120])236 4154 y(ok)236 4246 y(Trying:)416 4337 y([factorial\(long\(n\)\))c(for)k(n)f(in)h (range\(6\)])236 4428 y(Expecting:)416 4520 y([1,)f(1,)g(2,)h(6,)f(24,) h(120])236 4611 y(ok)0 4898 y FN(And)20 b(so)g(on,)g(e)n(v)o(entually)e (ending)h(with:)p 0 5549 3901 4 v 0 5649 a FI(766)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 767 779 TeXDict begin 767 778 bop 236 174 a FA(Trying:)416 266 y(factorial\(1e100\))236 357 y(Expecting:)416 448 y(Traceback)43 b(\(most)h(recent)g(call)g(last\):)595 540 y(...)416 631 y(OverflowError:)e(n)j(too)f(large)236 722 y(ok)236 814 y(1)h(items)f(had)g(no)h(tests:)416 905 y(__main__._test)236 996 y(2)g(items)f(passed)g(all)g(tests:)371 1088 y(1)g(tests)g(in)h (__main__)371 1179 y(8)f(tests)g(in)h(__main__.factorial)236 1270 y(9)g(tests)f(in)g(3)h(items.)236 1362 y(9)g(passed)f(and)g(0)h (failed.)236 1453 y(Test)f(passed.)236 1544 y($)0 1831 y FN(That')-5 b(s)25 b(all)g(you)f(need)g(to)g(kno)n(w)g(to)h(start)g (making)e(producti)n(v)o(e)f(use)j(of)g FJ(doctest)p FN(!)37 b(Jump)24 b(in.)39 b(The)24 b(follo)n(wing)f(sections)i(pro)o (vide)0 1930 y(full)e(details.)34 b(Note)23 b(that)g(there)g(are)g(man) o(y)f(e)o(xamples)g(of)h(doctests)g(in)g(the)h(standard)e(Python)g (test)i(suite)f(and)g(libraries.)33 b(Especially)0 2030 y(useful)20 b(e)o(xamples)f(can)h(be)g(found)e(in)j(the)f(standard)f (test)i(\002le)g(`)p FO(Lib/test/test)p 2196 2030 23 4 v 23 w(doctest.p)n(y)p FN('.)0 2315 y Fv(23.2.1)101 b(Simple)29 b(Usage:)35 b(Chec)n(king)29 b(Examples)g(in)f(Docstr)q (ings)0 2518 y FN(The)21 b(simplest)i(w)o(ay)f(to)f(start)i(using)e (doctest)h(\(b)n(ut)f(not)h(necessarily)f(the)h(w)o(ay)g(you')o(ll)e (continue)h(to)h(do)f(it\))h(is)h(to)f(end)f(each)h(module)e FJ(M)0 2617 y FN(with:)236 2856 y FA(def)45 b(_test\(\):)416 2947 y(import)e(doctest)416 3038 y(doctest.testmod\(\))236 3221 y(if)i(__name__)e(==)i("__main__":)416 3312 y(_test\(\))0 3599 y FJ(doctest)19 b FN(then)h(e)o(xamines)f(docstrings)g(in)i (module)d FJ(M)p FN(.)0 3746 y(Running)h(the)h(module)f(as)i(a)f (script)h(causes)f(the)g(e)o(xamples)f(in)i(the)f(docstrings)f(to)h (get)g(e)o(x)o(ecuted)f(and)g(v)o(eri\002ed:)236 3892 y FA(python)44 b(M.py)0 4179 y FN(This)30 b(w)o(on')o(t)e(display)h(an) o(ything)e(unless)j(an)g(e)o(xample)e(f)o(ails,)k(in)e(which)f(case)h (the)f(f)o(ailing)g(e)o(xample\(s\))f(and)h(the)g(cause\(s\))g(of)h (the)0 4279 y(f)o(ailure\(s\))18 b(are)h(printed)e(to)i(stdout,)g(and)f (the)h(\002nal)g(line)g(of)f(output)g(is)i(`)2020 4294 y FJ(***)2170 4279 y(Test)48 b(Failed)2718 4294 y(***)2916 4279 y FK(N)55 b FJ(failures.)p FN(',)18 b(where)g FK(N)25 b FN(is)0 4378 y(the)20 b(number)f(of)h(e)o(xamples)f(that)h(f)o (ailed.)0 4525 y(Run)g(it)h(with)f(the)h FL(-v)f FN(switch)g(instead:) 236 4763 y FA(python)44 b(M.py)g(-v)0 5050 y FN(and)20 b(a)g(detailed)g(report)f(of)h(all)h(e)o(xamples)e(tried)h(is)h (printed)e(to)h(standard)f(output,)g(along)g(with)h(assorted)g (summaries)g(at)g(the)h(end.)0 5197 y(Y)-9 b(ou)60 b(can)g(force)g(v)o (erbose)f(mode)g(by)h(passing)h FJ(verbose=True)d FN(to)j FJ(testmod\(\))p FN(,)69 b(or)61 b(prohibit)e(it)i(by)f(passing)0 5296 y FJ(verbose=False)p FN(.)54 b(In)30 b(either)g(of)h(those)f (cases,)j FJ(sys.argv)d FN(is)i(not)e(e)o(xamined)e(by)i FJ(testmod\(\))g FN(\(so)g(passing)g FL(-v)h FN(or)f(not)0 5396 y(has)20 b(no)g(ef)n(fect\).)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples)1840 b(767)p eop end %%Page: 768 780 TeXDict begin 768 779 bop 0 83 a FN(F)o(or)20 b(more)f(information)f (on)i FJ(testmod\(\))p FN(,)f(see)h(section)g(23.2.4.)0 368 y Fv(23.2.2)101 b(Simple)29 b(Usage:)35 b(Chec)n(king)29 b(Examples)g(in)f(a)g(T)-12 b(e)m(xt)27 b(File)0 571 y FN(Another)35 b(simple)h(application)e(of)i(doctest)f(is)i(testing)f (interacti)n(v)o(e)f(e)o(xamples)g(in)h(a)g(te)o(xt)g(\002le.)73 b(This)36 b(can)g(be)g(done)e(with)j(the)0 670 y FJ(testfile\(\))19 b FN(function:)236 909 y FA(import)44 b(doctest)236 1000 y(doctest.testfile\("example.txt"\))0 1286 y FN(That)26 b(short)h(script)f(e)o(x)o(ecutes)g(and)g(v)o(eri\002es)g(an)o(y)g (interacti)n(v)o(e)f(Python)h(e)o(xamples)f(contained)g(in)i(the)g (\002le)g(`)p FO(e)n(xample)o(.txt)p FN('.)42 b(The)26 b(\002le)0 1386 y(content)17 b(is)i(treated)f(as)h(if)g(it)f(were)h(a)f (single)g(giant)g(docstring;)g(the)g(\002le)h(doesn')o(t)e(need)g(to)h (contain)g(a)g(Python)f(program!)22 b(F)o(or)c(e)o(xample,)0 1486 y(perhaps)h(`)p FO(e)n(xample)o(.txt)p FN(')f(contains)h(this:)236 1724 y FA(The)45 b(``example``)e(module)236 1815 y (======================)236 1998 y(Using)h(``factorial``)236 2089 y(-------------------)236 2272 y(This)g(is)h(an)f(example)g(text)g (file)g(in)h(reStructuredText)d(format.)88 b(First)44 b(import)236 2363 y(``factorial``)f(from)h(the)g(``example``)f(module:) 416 2546 y(>>>)h(from)g(example)g(import)g(factorial)236 2728 y(Now)h(use)f(it:)416 2911 y(>>>)g(factorial\(6\))416 3002 y(120)0 3289 y FN(Running)19 b FJ (doctest.testfile\("example.txt"\))c FN(then)k(\002nds)i(the)f(error)f (in)h(this)h(documentation:)236 3527 y FA(File)44 b("./example.txt",)f (line)h(14,)g(in)h(example.txt)236 3619 y(Failed)f(example:)416 3710 y(factorial\(6\))236 3801 y(Expected:)416 3892 y(120)236 3984 y(Got:)416 4075 y(720)0 4362 y FN(As)25 b(with)f FJ(testmod\(\))p FN(,)f FJ(testfile\(\))f FN(w)o(on')o(t)h(display)g (an)o(ything)f(unless)i(an)g(e)o(xample)e(f)o(ails.)37 b(If)23 b(an)h(e)o(xample)f(does)g(f)o(ail,)i(then)0 4461 y(the)20 b(f)o(ailing)g(e)o(xample\(s\))e(and)i(the)g(cause\(s\))g (of)g(the)g(f)o(ailure\(s\))f(are)h(printed)f(to)i(stdout,)e(using)h (the)g(same)g(format)f(as)i FJ(testmod\(\))p FN(.)0 4608 y(By)g(def)o(ault,)f FJ(testfile\(\))g FN(looks)g(for)g(\002les)i(in)f (the)g(calling)g(module')-5 b(s)19 b(directory)-5 b(.)25 b(See)d(section)e(23.2.4)f(for)h(a)i(description)d(of)i(the)0 4708 y(optional)e(ar)o(guments)f(that)i(can)g(be)g(used)g(to)h(tell)g (it)f(to)h(look)e(for)h(\002les)h(in)f(other)g(locations.)0 4855 y(Lik)o(e)j FJ(testmod\(\))p FN(,)g FJ(testfile\(\))p FN(')-5 b(s)22 b(v)o(erbosity)g(can)h(be)g(set)h(with)g(the)f FL(-v)g FN(command-line)d(switch)k(or)f(with)g(the)h(optional)e(k)o(e)o (y-)0 4954 y(w)o(ord)e(ar)o(gument)d FK(verbose)p FN(.)0 5101 y(F)o(or)j(more)f(information)f(on)i FJ(testfile\(\))p FN(,)e(see)j(section)f(23.2.4.)p 0 5549 3901 4 v 0 5649 a FI(768)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 769 781 TeXDict begin 769 780 bop 0 83 a Fv(23.2.3)101 b(Ho)o(w)27 b(It)g(W)m(or)q(ks)0 286 y FN(This)g(section)f(e)o(xamines)g(in)g (detail)h(ho)n(w)f(doctest)g(w)o(orks:)38 b(which)26 b(docstrings)g(it)h(looks)f(at,)j(ho)n(w)d(it)h(\002nds)g(interacti)n (v)o(e)e(e)o(xamples,)0 386 y(what)g(e)o(x)o(ecution)e(conte)o(xt)h(it) i(uses,)h(ho)n(w)d(it)i(handles)e(e)o(xceptions,)h(and)g(ho)n(w)f (option)g(\003ags)i(can)f(be)g(used)g(to)g(control)f(its)i(beha)n(vior) -5 b(.)0 485 y(This)17 b(is)h(the)f(information)d(that)j(you)f(need)g (to)i(kno)n(w)d(to)i(write)g(doctest)g(e)o(xamples;)g(for)f (information)f(about)h(actually)g(running)f(doctest)0 585 y(on)20 b(these)g(e)o(xamples,)f(see)i(the)f(follo)n(wing)f (sections.)0 853 y FI(Which)24 b(Docstr)q(ings)e(Are)h(Examined?)0 1056 y FN(The)f(module)f(docstring,)g(and)g(all)i(function,)e(class)i (and)f(method)f(docstrings)g(are)h(searched.)30 b(Objects)22 b(imported)f(into)h(the)g(module)0 1156 y(are)e(not)g(searched.)0 1303 y(In)h(addition,)f(if)h FJ(M.__test__)f FN(e)o(xists)h(and)g (\224is)h(true\224,)e(it)i(must)f(be)g(a)h(dict,)f(and)g(each)f(entry)h (maps)f(a)i(\(string\))e(name)h(to)g(a)g(function)0 1402 y(object,)c(class)g(object,)g(or)f(string.)23 b(Function)16 b(and)g(class)i(object)e(docstrings)f(found)g(from)h FJ(M.__test__)f FN(are)h(searched,)h(and)f(strings)0 1502 y(are)k(treated)g(as)h(if)f(the)o(y)g(were)g(docstrings.)k(In)19 b(output,)g(a)i(k)o(e)o(y)e FJ(K)i FN(in)f FJ(M.__test__)f FN(appears)g(with)i(name)236 1740 y FA(<name)44 b(of)h(M>.__test__.K)0 2026 y FN(An)o(y)19 b(classes)j(found)c(are)i(recursi)n(v)o(ely)f (searched)g(similarly)-5 b(,)19 b(to)h(test)i(docstrings)d(in)h(their)g (contained)e(methods)i(and)f(nested)h(classes.)0 2173 y(Changed)f(in)h(v)o(ersion)f(2.4:)h(A)g(\224pri)n(v)n(ate)f(name\224)h (concept)f(is)i(deprecated)d(and)i(no)g(longer)f(documented.)0 2442 y FI(Ho)o(w)k(are)g(Docstr)q(ing)g(Examples)g(Recogniz)o(ed?)0 2645 y FN(In)k(most)g(cases)h(a)g(cop)o(y-and-paste)c(of)j(an)h (interacti)n(v)o(e)e(console)g(session)i(w)o(orks)f(\002ne,)i(b)n(ut)e (doctest)g(isn')o(t)g(trying)f(to)i(do)f(an)g(e)o(xact)0 2744 y(emulation)22 b(of)h(an)o(y)g(speci\002c)g(Python)g(shell.)35 b(All)24 b(hard)e(tab)i(characters)e(are)i(e)o(xpanded)c(to)k(spaces,)g (using)f(8-column)e(tab)j(stops.)35 b(If)0 2844 y(you)19 b(don')o(t)g(belie)n(v)o(e)g(tabs)i(should)e(mean)g(that,)h(too)g(bad:) 25 b(don')o(t)18 b(use)j(hard)e(tabs,)h(or)g(write)h(your)e(o)n(wn)g FJ(DocTestParser)g FN(class.)0 2991 y(Changed)e(in)i(v)o(ersion)f(2.4:) g(Expanding)e(tabs)j(to)g(spaces)g(is)g(ne)n(w;)g(pre)n(vious)f(v)o (ersions)f(tried)i(to)g(preserv)o(e)e(hard)h(tabs,)h(with)g(confusing)0 3090 y(results.)236 3328 y FA(>>>)45 b(#)f(comments)g(are)g(ignored)236 3420 y(>>>)h(x)f(=)h(12)236 3511 y(>>>)g(x)236 3602 y(12)236 3694 y(>>>)g(if)f(x)h(==)f(13:)236 3785 y(...)224 b(print)44 b("yes")236 3876 y(...)h(else:)236 3968 y(...)224 b(print)44 b("no")236 4059 y(...)224 b(print)44 b("NO")236 4150 y(...)224 b(print)44 b("NO!!!")236 4242 y(...)236 4333 y(no)236 4424 y(NO)236 4516 y(NO!!!)236 4607 y(>>>)0 4894 y FN(An)o(y)25 b(e)o(xpected)f(output)h(must)g(immediately)g (follo)n(w)g(the)h(\002nal)g FJ('>>>)49 b(')26 b FN(or)f FJ('...)49 b(')43 b FN(line)25 b(containing)f(the)i(code,)g(and)f(the)h (e)o(x-)0 4993 y(pected)19 b(output)g(\(if)i(an)o(y\))e(e)o(xtends)g (to)h(the)g(ne)o(xt)g FJ('>>>)49 b(')20 b FN(or)g(all-whitespace)g (line.)0 5140 y(The)g(\002ne)g(print:)125 5370 y FM(\017)41 b FN(Expected)22 b(output)g(cannot)h(contain)f(an)i(all-whitespace)f (line,)h(since)g(such)f(a)h(line)g(is)h(tak)o(en)e(to)h(signal)f(the)h (end)f(of)g(e)o(xpected)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g (Python)h(e)n(xamples)1840 b(769)p eop end %%Page: 770 782 TeXDict begin 770 781 bop 208 83 a FN(output.)27 b(If)22 b(e)o(xpected)e(output)g(does)i(contain)e(a)i(blank)f(line,)h(put)f FJ(<BLANKLINE>)f FN(in)i(your)e(doctest)h(e)o(xample)g(each)g(place)g (a)208 183 y(blank)f(line)h(is)h(e)o(xpected.)54 b(Changed)20 b(in)h(v)o(ersion)e(2.4:)i FJ(<BLANKLINE>)e FN(w)o(as)j(added;)f(there) f(w)o(as)i(no)f(w)o(ay)g(to)g(use)g(e)o(xpected)208 282 y(output)e(containing)f(empty)h(lines)i(in)f(pre)n(vious)f(v)o (ersions.)125 445 y FM(\017)41 b FN(Output)19 b(to)h(stdout)g(is)h (captured,)e(b)n(ut)h(not)g(output)f(to)h(stderr)g(\(e)o(xception)e (tracebacks)h(are)h(captured)e(via)j(a)f(dif)n(ferent)f(means\).)125 607 y FM(\017)41 b FN(If)25 b(you)f(continue)g(a)i(line)g(via)f (backslashing)f(in)i(an)f(interacti)n(v)o(e)f(session,)j(or)e(for)g(an) o(y)g(other)f(reason)h(use)h(a)g(backslash,)f(you)208 707 y(should)19 b(use)h(a)h(ra)o(w)f(docstring,)e(which)i(will)h (preserv)o(e)e(your)f(backslashes)i(e)o(xactly)f(as)i(you)f(type)f (them:)444 929 y FA(>>>)44 b(def)g(f\(x\):)444 1021 y(...)223 b(r'''Backslashes)43 b(in)h(a)h(raw)f(docstring:)f(m\\n''')444 1112 y(>>>)h(print)g(f.__doc__)444 1203 y(Backslashes)f(in)h(a)h(raw)f (docstring:)f(m\\n)208 1480 y FN(Otherwise,)25 b(the)f(backslash)g (will)i(be)e(interpreted)f(as)j(part)e(of)g(the)h(string.)38 b(F)o(or)24 b(e)o(xample,)g(the)h(\224)p FM(n)p FN(\224)f(abo)o(v)o(e)f (w)o(ould)h(be)h(inter)n(-)208 1579 y(preted)c(as)i(a)g(ne)n(wline)e (character)-5 b(.)31 b(Alternati)n(v)o(ely)-5 b(,)20 b(you)i(can)g(double)f(each)g(backslash)h(in)h(the)f(doctest)g(v)o (ersion)f(\(and)g(not)h(use)208 1679 y(a)e(ra)o(w)g(string\):)444 1901 y FA(>>>)44 b(def)g(f\(x\):)444 1992 y(...)223 b('''Backslashes)43 b(in)h(a)h(raw)f(docstring:)g(m\\\\n''')444 2084 y(>>>)g(print)g (f.__doc__)444 2175 y(Backslashes)f(in)h(a)h(raw)f(docstring:)f(m\\n) 125 2477 y FM(\017)e FN(The)19 b(starting)h(column)f(doesn')o(t)g (matter:)533 2700 y FA(>>>)45 b(assert)f("Easy!")802 2791 y(>>>)h(import)f(math)982 2882 y(>>>)g(math.floor\(1.9\))982 2974 y(1.0)208 3244 y FN(and)30 b(as)i(man)o(y)d(leading)h(whitespace)h (characters)f(are)g(stripped)g(from)g(the)h(e)o(xpected)f(output)f(as)j (appeared)d(in)i(the)g(initial)208 3344 y FJ('>>>)49 b(')20 b FN(line)g(that)h(started)f(the)g(e)o(xample.)0 3611 y FI(What')l(s)k(the)f(Ex)n(ecution)g(Conte)n(xt?)0 3814 y FN(By)h(def)o(ault,)g(each)g(time)g FJ(doctest)f FN(\002nds)h(a)g(docstring)f(to)h(test,)h(it)g(uses)f(a)g FK(shallow)g(copy)f FN(of)h FJ(M)p FN(')-5 b(s)24 b(globals,)g(so)h (that)f(running)d(tests)0 3913 y(doesn')o(t)g(change)h(the)h(module')-5 b(s)22 b(real)h(globals,)g(and)f(so)i(that)f(one)f(test)i(in)f FJ(M)h FN(can')o(t)e(lea)n(v)o(e)g(behind)g(crumbs)g(that)h (accidentally)f(allo)n(w)0 4013 y(another)k(test)i(to)g(w)o(ork.)46 b(This)27 b(means)g(e)o(xamples)g(can)g(freely)f(use)i(an)o(y)e(names)i (de\002ned)e(at)i(top-le)n(v)o(el)e(in)h FJ(M)p FN(,)h(and)f(names)g (de\002ned)0 4112 y(earlier)20 b(in)g(the)g(docstring)f(being)g(run.)24 b(Examples)c(cannot)f(see)i(names)e(de\002ned)h(in)g(other)f (docstrings.)0 4259 y(Y)-9 b(ou)28 b(can)f(force)h(use)g(of)g(your)f(o) n(wn)g(dict)h(as)h(the)f(e)o(x)o(ecution)e(conte)o(xt)h(by)h(passing)g FJ(globs=your_dict)e FN(to)i FJ(testmod\(\))f FN(or)0 4359 y FJ(testfile\(\))19 b FN(instead.)0 4626 y FI(What)24 b(About)g(Exceptions?)0 4828 y FN(No)k(problem,)f(pro)o(vided)e(that)j (the)g(traceback)e(is)i(the)g(only)f(output)f(produced)f(by)i(the)h(e)o (xample:)39 b(just)28 b(paste)g(in)f(the)h(traceback.)3869 4798 y FF(1)0 4928 y FN(Since)20 b(tracebacks)g(contain)f(details)h (that)h(are)f(lik)o(ely)g(to)h(change)e(rapidly)g(\(for)g(e)o(xample,)g (e)o(xact)h(\002le)h(paths)f(and)f(line)i(numbers\),)d(this)0 5028 y(is)j(one)f(case)g(where)g(doctest)g(w)o(orks)g(hard)f(to)h(be)h (\003e)o(xible)e(in)h(what)h(it)g(accepts.)0 5175 y(Simple)f(e)o (xample:)p 0 5242 1560 4 v 90 5298 a FB(1)120 5321 y FH(Examples)i(containing)j(both)d(e)o(xpected)i(output)f(and)g(an)f(e)o (xception)i(are)e(not)h(supported.)36 b(T)n(rying)22 b(to)g(guess)g(where)g(one)g(ends)g(and)h(the)f(other)h(be)o(gins)g(is) e(too)0 5400 y(error)o(-prone,)d(and)g(that)g(also)g(mak)o(es)f(for)g (a)g(confusing)i(test.)p 0 5549 3901 4 v 0 5649 a FI(770)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 771 783 TeXDict begin 771 782 bop 236 174 a FA(>>>)45 b([1,)f(2,)g (3].remove\(42\))236 266 y(Traceback)g(\(most)g(recent)f(call)i (last\):)326 357 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 448 y(ValueError:)f(list.remove\(x\):)g(x)h(not)h(in)f(list)0 735 y FN(That)30 b(doctest)g(succeeds)g(if)h FJ(ValueError)e FN(is)i(raised,)h(with)f(the)f(`)p FJ(list.remove\(x\):)96 b(x)50 b(not)f(in)h(list)p FN(')30 b(detail)g(as)0 834 y(sho)n(wn.)0 981 y(The)25 b(e)o(xpected)f(output)g(for)h(an)g(e)o (xception)e(must)j(start)g(with)f(a)h(traceback)e(header)m(,)h(which)g (may)g(be)g(either)g(of)g(the)h(follo)n(wing)d(tw)o(o)0 1081 y(lines,)d(indented)f(the)h(same)h(as)f(the)h(\002rst)g(line)f(of) g(the)g(e)o(xample:)236 1319 y FA(Traceback)44 b(\(most)g(recent)f (call)i(last\):)236 1410 y(Traceback)f(\(innermost)f(last\):)0 1697 y FN(The)17 b(traceback)f(header)g(is)i(follo)n(wed)e(by)h(an)g (optional)f(traceback)g(stack,)h(whose)g(contents)g(are)g(ignored)f(by) g(doctest.)24 b(The)17 b(traceback)0 1797 y(stack)j(is)h(typically)f (omitted,)f(or)h(copied)f(v)o(erbatim)g(from)g(an)h(interacti)n(v)o(e)f (session.)0 1943 y(The)h(traceback)f(stack)h(is)h(follo)n(wed)e(by)g (the)h(most)h(interesting)e(part:)25 b(the)20 b(line\(s\))g(containing) e(the)i(e)o(xception)e(type)i(and)f(detail.)25 b(This)0 2043 y(is)c(usually)f(the)g(last)h(line)f(of)g(a)h(traceback,)d(b)n(ut) j(can)f(e)o(xtend)e(across)j(multiple)e(lines)i(if)f(the)g(e)o (xception)f(has)h(a)h(multi-line)e(detail:)236 2281 y FA(>>>)45 b(raise)f(ValueError\('multi\\n)176 b(line\\ndetail'\))236 2373 y(Traceback)44 b(\(most)g(recent)f(call)i(last\):)326 2464 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 2555 y(ValueError:)f(multi)416 2647 y(line)236 2738 y(detail)0 3024 y FN(The)24 b(last)i(three)e(lines)h(\(starting)f(with)h FJ(ValueError)p FN(\))f(are)g(compared)f(against)h(the)h(e)o(xception') -5 b(s)23 b(type)h(and)g(detail,)i(and)e(the)h(rest)0 3124 y(are)20 b(ignored.)0 3271 y(Best)i(practice)e(is)i(to)f(omit)f (the)h(traceback)f(stack,)h(unless)f(it)i(adds)e(signi\002cant)h (documentation)d(v)n(alue)i(to)h(the)f(e)o(xample.)26 b(So)21 b(the)g(last)0 3371 y(e)o(xample)e(is)i(probably)d(better)i (as:)236 3609 y FA(>>>)45 b(raise)f(ValueError\('multi\\n)176 b(line\\ndetail'\))236 3700 y(Traceback)44 b(\(most)g(recent)f(call)i (last\):)416 3791 y(...)236 3883 y(ValueError:)e(multi)416 3974 y(line)236 4065 y(detail)0 4352 y FN(Note)19 b(that)g(tracebacks)f (are)h(treated)f(v)o(ery)g(specially)-5 b(.)24 b(In)18 b(particular)m(,)g(in)h(the)g(re)n(written)f(e)o(xample,)f(the)i(use)h (of)e(`)p FJ(...)p FN(')24 b(is)c(independent)0 4452 y(of)i(doctest')-5 b(s)22 b FJ(ELLIPSIS)f FN(option.)29 b(The)21 b(ellipsis)i(in)f(that)g(e)o(xample)f(could)g(be)h(left)g (out,)g(or)g(could)f(just)h(as)h(well)f(be)g(three)g(\(or)f(three)0 4551 y(hundred\))c(commas)j(or)g(digits,)g(or)g(an)g(indented)f (transcript)g(of)h(a)g(Monty)g(Python)f(skit.)0 4698 y(Some)h(details)g(you)g(should)f(read)g(once,)h(b)n(ut)g(w)o(on')o(t)f (need)h(to)g(remember:)125 4928 y FM(\017)41 b FN(Doctest)20 b(can')o(t)g(guess)g(whether)f(your)g(e)o(xpected)g(output)g(came)h (from)g(an)g(e)o(xception)f(traceback)g(or)h(from)f(ordinary)f (printing.)208 5028 y(So,)35 b(e.g.,)g(an)d(e)o(xample)f(that)i(e)o (xpects)e(`)p FJ(ValueError:)97 b(42)50 b(is)f(prime)p FN(')32 b(will)h(pass)g(whether)f FJ(ValueError)f FN(is)208 5127 y(actually)17 b(raised)h(or)f(if)h(the)g(e)o(xample)f(merely)g (prints)g(that)h(traceback)f(te)o(xt.)24 b(In)18 b(practice,)f (ordinary)f(output)g(rarely)h(be)o(gins)g(with)208 5227 y(a)j(traceback)f(header)g(line,)h(so)h(this)f(doesn')o(t)f(create)h (real)g(problems.)125 5393 y FM(\017)41 b FN(Each)21 b(line)i(of)f(the)g(traceback)f(stack)i(\(if)f(present\))f(must)i(be)f (indented)f(further)g(than)h(the)g(\002rst)h(line)g(of)f(the)g(e)o (xample,)f FK(or)i FN(start)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples)1840 b(771)p eop end %%Page: 772 784 TeXDict begin 772 783 bop 208 83 a FN(with)20 b(a)g(non-alphanumeric)c (character)-5 b(.)24 b(The)19 b(\002rst)i(line)f(follo)n(wing)e(the)i (traceback)e(header)h(indented)g(the)h(same)g(and)f(starting)208 183 y(with)28 b(an)g(alphanumeric)d(is)k(tak)o(en)f(to)g(be)g(the)g (start)h(of)f(the)g(e)o(xception)e(detail.)48 b(Of)29 b(course)e(this)i(does)e(the)h(right)g(thing)f(for)208 282 y(genuine)18 b(tracebacks.)125 448 y FM(\017)41 b FN(When)28 b(the)h FJ(IGNORE_EXCEPTION_DETAIL)d FN(doctest)i(option)g (is)i(is)g(speci\002ed,)g(e)n(v)o(erything)d(follo)n(wing)g(the)i (leftmost)208 548 y(colon)19 b(is)i(ignored.)125 714 y FM(\017)41 b FN(The)27 b(interacti)n(v)o(e)g(shell)h(omits)g(the)g (traceback)f(header)f(line)i(for)g(some)f FJ(SyntaxError)p FN(s.)47 b(But)29 b(doctest)f(uses)g(the)g(trace-)208 814 y(back)d(header)f(line)i(to)g(distinguish)f(e)o(xceptions)g(from)f (non-e)o(xceptions.)39 b(So)26 b(in)g(the)g(rare)g(case)g(where)f(you)g (need)g(to)h(test)h(a)208 913 y FJ(SyntaxError)e FN(that)i(omits)g(the) g(traceback)f(header)m(,)h(you)f(will)i(need)e(to)i(manually)d(add)i (the)g(traceback)e(header)h(line)h(to)208 1013 y(your)18 b(test)k(e)o(xample.)125 1179 y FM(\017)41 b FN(F)o(or)19 b(some)h FJ(SyntaxError)p FN(s,)f(Python)g(displays)h(the)g(character)f (position)h(of)f(the)i(syntax)e(error)m(,)g(using)g(a)i FJ(\210)g FN(mark)o(er:)444 1403 y FA(>>>)44 b(1)h(1)533 1494 y(File)g("<stdin>",)e(line)h(1)623 1586 y(1)h(1)713 1677 y(\210)444 1768 y(SyntaxError:)e(invalid)g(syntax)208 2041 y FN(Since)18 b(the)h(lines)g(sho)n(wing)f(the)g(position)g(of)h (the)f(error)g(come)g(before)f(the)i(e)o(xception)e(type)h(and)g (detail,)h(the)o(y)f(are)g(not)h(check)o(ed)208 2140 y(by)g(doctest.)25 b(F)o(or)20 b(e)o(xample,)e(the)j(follo)n(wing)d (test)j(w)o(ould)f(pass,)g(e)n(v)o(en)f(though)g(it)i(puts)f(the)g FJ(\210)h FN(mark)o(er)e(in)h(the)g(wrong)f(location:)444 2365 y FA(>>>)44 b(1)h(1)444 2456 y(Traceback)e(\(most)h(recent)g(call) g(last\):)533 2547 y(File)h("<stdin>",)e(line)h(1)623 2639 y(1)h(1)623 2730 y(\210)444 2821 y(SyntaxError:)e(invalid)g (syntax)0 3191 y FN(Changed)18 b(in)i(v)o(ersion)f(2.4:)g(The)h (ability)f(to)h(handle)f(a)h(multi-line)f(e)o(xception)f(detail,)h(and) h(the)f FJ(IGNORE_EXCEPTION_DETAIL)0 3290 y FN(doctest)h(option,)f (were)h(added.)0 3559 y FI(Option)k(Flags)f(and)g(Directiv)n(es)0 3762 y FN(A)g(number)e(of)i(option)e(\003ags)i(control)f(v)n(arious)f (aspects)i(of)g(doctest')-5 b(s)22 b(beha)n(vior)-5 b(.)32 b(Symbolic)21 b(names)i(for)f(the)g(\003ags)i(are)e(supplied)g(as)0 3861 y(module)c(constants,)g(which)h(can)g(be)g(or'ed)f(together)f(and) i(passed)g(to)g(v)n(arious)f(functions.)23 b(The)c(names)g(can)f(also)i (be)f(used)g(in)g(doctest)0 3961 y(directi)n(v)o(es)g(\(see)i(belo)n (w\).)0 4108 y(The)30 b(\002rst)g(group)f(of)g(options)h(de\002ne)f (test)i(semantics,)h(controlling)c(aspects)i(of)g(ho)n(w)g(doctest)f (decides)h(whether)f(actual)h(output)0 4207 y(matches)20 b(an)g(e)o(xample')-5 b(s)19 b(e)o(xpected)g(output:)0 4354 y FD(DONT_ACCEPT_TRUE_FOR_1)208 4454 y FN(By)24 b(def)o(ault,)h(if)g(an)f(e)o(xpected)f(output)g(block)g(contains)h (just)h FJ(1)p FN(,)g(an)g(actual)f(output)f(block)h(containing)e(just) j FJ(1)g FN(or)f(just)h FJ(True)208 4553 y FN(is)32 b(considered)e(to)i (be)f(a)i(match,)g(and)e(similarly)h(for)f FJ(0)h FN(v)o(ersus)f FJ(False)p FN(.)59 b(When)32 b FJ(DONT_ACCEPT_TRUE_FOR_1)c FN(is)208 4653 y(speci\002ed,)21 b(neither)g(substitution)g(is)i(allo)n (wed.)29 b(The)22 b(def)o(ault)f(beha)n(vior)f(caters)i(to)g(that)g (Python)f(changed)f(the)i(return)e(type)i(of)208 4753 y(man)o(y)c(functions)g(from)h(inte)o(ger)f(to)i(boolean;)f(doctests)g (e)o(xpecting)f(\224little)i(inte)o(ger\224)f(output)f(still)j(w)o(ork) e(in)h(these)g(cases.)25 b(This)208 4852 y(option)19 b(will)h(probably)e(go)i(a)o(w)o(ay)-5 b(,)19 b(b)n(ut)i(not)e(for)h (se)n(v)o(eral)g(years.)0 4999 y FD(DONT_ACCEPT_BLANKLINE)208 5099 y FN(By)f(def)o(ault,)g(if)g(an)h(e)o(xpected)d(output)h(block)h (contains)f(a)i(line)f(containing)f(only)g(the)i(string)f FJ(<BLANKLINE>)p FN(,)e(then)i(that)g(line)208 5198 y(will)h(match)g(a) g(blank)f(line)h(in)h(the)f(actual)f(output.)24 b(Because)c(a)h (genuinely)d(blank)h(line)h(delimits)g(the)g(e)o(xpected)f(output,)f (this)j(is)208 5298 y(the)h(only)g(w)o(ay)h(to)g(communicate)e(that)i (a)g(blank)f(line)h(is)h(e)o(xpected.)31 b(When)23 b FJ(DONT_ACCEPT_BLANKLINE)c FN(is)24 b(speci\002ed,)208 5398 y(this)c(substitution)g(is)h(not)f(allo)n(wed.)p 0 5549 3901 4 v 0 5649 a FI(772)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 773 785 TeXDict begin 773 784 bop 0 83 a FD(NORMALIZE_WHITESPACE)208 183 y FN(When)32 b(speci\002ed,)i(all)f(sequences)e(of)h(whitespace)g (\(blanks)f(and)h(ne)n(wlines\))f(are)h(treated)g(as)h(equal.)60 b(An)o(y)32 b(sequence)f(of)208 282 y(whitespace)21 b(within)g(the)h(e) o(xpected)e(output)g(will)i(match)g(an)o(y)e(sequence)h(of)g (whitespace)g(within)h(the)f(actual)h(output.)28 b(By)22 b(de-)208 382 y(f)o(ault,)17 b(whitespace)g(must)h(match)f(e)o(xactly) -5 b(.)23 b FJ(NORMALIZE_WHITESPACE)14 b FN(is)k(especially)f(useful)g (when)g(a)h(line)g(of)f(e)o(xpected)208 482 y(output)i(is)i(v)o(ery)e (long,)g(and)g(you)h(w)o(ant)g(to)g(wrap)g(it)h(across)f(multiple)g (lines)g(in)h(your)e(source.)0 628 y FD(ELLIPSIS)208 728 y FN(When)k(speci\002ed,)g(an)g(ellipsis)h(mark)o(er)e(\()p FJ(...)p FN(\))33 b(in)24 b(the)f(e)o(xpected)e(output)h(can)h(match)g (an)o(y)f(substring)h(in)g(the)g(actual)g(output.)208 828 y(This)16 b(includes)g(substrings)g(that)h(span)f(line)h (boundaries,)e(and)h(empty)f(substrings,)i(so)g(it')-5 b(s)17 b(best)g(to)g(k)o(eep)f(usage)g(of)h(this)g(simple.)208 927 y(Complicated)k(uses)j(can)f(lead)g(to)g(the)g(same)g(kinds)g(of)g (\224oops,)f(it)i(matched)e(too)h(much!\224)e(surprises)i(that)3309 894 y Fp(d)3325 927 y FJ(.)3375 942 y(*)3415 927 y Fp(c)13 b FN(is)24 b(prone)d(to)i(in)208 1027 y(re)o(gular)18 b(e)o(xpressions.)0 1174 y FD(IGNORE_EXCEPTION_DETAIL)208 1273 y FN(When)g(speci\002ed,)h(an)g(e)o(xample)e(that)i(e)o(xpects)f (an)h(e)o(xception)e(passes)i(if)g(an)g(e)o(xception)e(of)i(the)g(e)o (xpected)e(type)h(is)i(raised,)f(e)n(v)o(en)208 1373 y(if)i(the)g(e)o(xception)e(detail)i(does)g(not)g(match.)27 b(F)o(or)21 b(e)o(xample,)f(an)h(e)o(xample)e(e)o(xpecting)h(`)p FJ(ValueError:)97 b(42)p FN(')21 b(will)h(pass)f(if)208 1473 y(the)f(actual)g(e)o(xception)e(raised)i(is)h(`)p FJ(ValueError:)97 b(3)1911 1488 y(*)1961 1473 y(14)p FN(',)20 b(b)n(ut)g(will)h(f)o(ail,)f(e.g.,)g(if)g FJ(TypeError)f FN(is)i(raised.)208 1605 y(Note)28 b(that)h(a)g(similar)g(ef)n(fect)g (can)f(be)h(obtained)e(using)i FJ(ELLIPSIS)p FN(,)e(and)i FJ(IGNORE_EXCEPTION_DETAIL)c FN(may)j(go)208 1705 y(a)o(w)o(ay)e(when)g (Python)f(releases)i(prior)f(to)h(2.4)f(become)f(uninteresting.)43 b(Until)27 b(then,)g FJ(IGNORE_EXCEPTION_DETAIL)208 1805 y FN(is)c(the)g(only)f(clear)h(w)o(ay)g(to)g(write)g(a)g(doctest)g (that)g(doesn')o(t)e(care)i(about)e(the)i(e)o(xception)e(detail)i(yet)g (continues)f(to)h(pass)g(under)208 1904 y(Python)c(releases)h(prior)f (to)i(2.4)e(\(doctest)h(directi)n(v)o(es)f(appear)g(to)h(be)g(comments) f(to)i(them\).)j(F)o(or)c(e)o(xample,)444 2129 y FA(>>>)44 b(\(1,)g(2\)[3])g(=)h('moo')f(#doctest:)f(+IGNORE_EXCEPTION_DETAIL)444 2220 y(Traceback)g(\(most)h(recent)g(call)g(last\):)533 2311 y(File)h("<stdin>",)e(line)h(1,)g(in)h(?)444 2402 y(TypeError:)e(object)h(doesn't)f(support)h(item)g(assignment)208 2592 y FN(passes)20 b(under)f(Python)g(2.4)h(and)f(Python)g(2.3.)25 b(The)20 b(detail)g(changed)e(in)j(2.4,)e(to)h(say)h(\224does)e (not\224)h(instead)g(of)g(\224doesn')o(t\224.)0 2739 y FD(SKIP)208 2838 y FN(When)i(speci\002ed,)h(do)g(not)f(run)g(the)h(e) o(xample)e(at)j(all.)33 b(This)23 b(can)g(be)g(useful)f(in)h(conte)o (xts)f(where)g(doctest)h(e)o(xamples)f(serv)o(e)g(as)208 2938 y(both)e(documentation)e(and)i(test)i(cases,)g(and)e(an)h(e)o (xample)f(should)g(be)h(included)e(for)i(documentation)d(purposes,)i(b) n(ut)h(should)208 3038 y(not)g(be)g(check)o(ed.)27 b(E.g.,)20 b(the)i(e)o(xample')-5 b(s)20 b(output)g(might)h(be)g(random;)f(or)h (the)h(e)o(xample)e(might)g(depend)g(on)h(resources)f(which)208 3137 y(w)o(ould)f(be)h(una)n(v)n(ailable)f(to)h(the)g(test)i(dri)n(v)o (er)-5 b(.)208 3270 y(The)19 b(SKIP)i(\003ag)f(can)g(also)h(be)f(used)g (for)f(temporarily)g(\224commenting)e(out\224)j(e)o(xamples.)0 3417 y FD(COMPARISON_FLAGS)208 3517 y FN(A)g(bitmask)g(or'ing)f (together)f(all)j(the)f(comparison)f(\003ags)h(abo)o(v)o(e.)0 3664 y(The)g(second)f(group)g(of)h(options)f(controls)g(ho)n(w)h(test)h (f)o(ailures)f(are)g(reported:)0 3810 y FD(REPORT_UDIFF)208 3910 y FN(When)g(speci\002ed,)f(f)o(ailures)h(that)g(in)m(v)n(olv)o(e)f (multi-line)g(e)o(xpected)g(and)g(actual)h(outputs)g(are)g(displayed)f (using)h(a)g(uni\002ed)g(dif)n(f.)0 4057 y FD(REPORT_CDIFF)208 4157 y FN(When)25 b(speci\002ed,)h(f)o(ailures)g(that)f(in)m(v)n(olv)o (e)f(multi-line)h(e)o(xpected)f(and)h(actual)g(outputs)g(will)h(be)f (displayed)g(using)g(a)h(conte)o(xt)208 4256 y(dif)n(f.)0 4403 y FD(REPORT_NDIFF)208 4503 y FN(When)i(speci\002ed,)i(dif)n (ferences)d(are)h(computed)f(by)h FJ(difflib.Differ)p FN(,)g(using)g(the)h(same)g(algorithm)e(as)i(the)f(popular)208 4602 y(`)p FO(ndiff)n(.p)n(y)p FN(')14 b(utility)-5 b(.)24 b(This)18 b(is)h(the)e(only)g(method)f(that)i(marks)f(dif)n(ferences)f (within)i(lines)g(as)g(well)g(as)h(across)e(lines.)25 b(F)o(or)17 b(e)o(xample,)208 4702 y(if)22 b(a)g(line)g(of)f(e)o (xpected)f(output)h(contains)g(digit)h FJ(1)g FN(where)f(actual)h (output)e(contains)h(letter)h FJ(l)p FN(,)g(a)h(line)f(is)g(inserted)g (with)f(a)i(caret)208 4802 y(marking)18 b(the)i(mismatching)f(column)g (positions.)0 4948 y FD(REPORT_ONLY_FIRST_FAILURE)208 5048 y FN(When)e(speci\002ed,)g(display)g(the)g(\002rst)h(f)o(ailing)f (e)o(xample)f(in)h(each)g(doctest,)h(b)n(ut)f(suppress)g(output)f(for)h (all)g(remaining)f(e)o(xamples.)208 5148 y(This)i(will)h(pre)n(v)o(ent) e(doctest)h(from)g(reporting)e(correct)i(e)o(xamples)f(that)i(break)e (because)h(of)g(earlier)g(f)o(ailures;)h(b)n(ut)f(it)h(might)f(also)208 5247 y(hide)j(incorrect)g(e)o(xamples)g(that)h(f)o(ail)g(independently) d(of)j(the)g(\002rst)h(f)o(ailure.)30 b(When)22 b FJ (REPORT_ONLY_FIRST_FAILURE)208 5347 y FN(is)i(speci\002ed,)f(the)g (remaining)f(e)o(xamples)g(are)h(still)h(run,)f(and)g(still)h(count)e (to)n(w)o(ards)h(the)g(total)g(number)f(of)g(f)o(ailures)h(reported;)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(773)p eop end %%Page: 774 786 TeXDict begin 774 785 bop 208 83 a FN(only)19 b(the)h(output)f(is)i (suppressed.)0 230 y FD(REPORTING_FLAGS)208 330 y FN(A)f(bitmask)g (or'ing)f(together)f(all)j(the)f(reporting)f(\003ags)h(abo)o(v)o(e.)0 476 y(\224Doctest)g(directi)n(v)o(es\224)g(may)f(be)i(used)f(to)g (modify)f(the)h(option)g(\003ags)g(for)g(indi)n(vidual)e(e)o(xamples.) 25 b(Doctest)20 b(directi)n(v)o(es)g(are)g(e)o(xpressed)0 576 y(as)h(a)g(special)f(Python)f(comment)g(follo)n(wing)f(an)i(e)o (xample')-5 b(s)19 b(source)h(code:)216 719 y FJ(directive)696 b FN(::=)99 b FJ("#")49 b("doctest:")f(directive_options)216 819 y(directive_options)296 b FN(::=)99 b FJ(directive_option)47 b(\(",")i(directive_option\))3500 834 y(*)216 919 y(directive_option) 346 b FN(::=)99 b FJ(on_or_off)48 b(directive_option_name)216 1018 y(on_or_off)696 b FN(::=)99 b FJ("+")49 b(|)h("-")216 1118 y(directive_option_name)96 b FN(::=)j FJ("DONT_ACCEPT_BLANKLINE") 46 b(|)j("NORMALIZE_WHITESPACE")d(|)k(...)0 1303 y FN(Whitespace)20 b(is)g(not)g(allo)n(wed)f(between)g(the)h FJ(+)g FN(or)f FJ(-)i FN(and)e(the)h(directi)n(v)o(e)e(option)h(name.)24 b(The)19 b(directi)n(v)o(e)g(option)f(name)i(can)f(be)h(an)o(y)f(of)0 1402 y(the)h(option)f(\003ag)h(names)g(e)o(xplained)f(abo)o(v)o(e.)0 1549 y(An)c(e)o(xample')-5 b(s)15 b(doctest)g(directi)n(v)o(es)f (modify)g(doctest')-5 b(s)16 b(beha)n(vior)e(for)g(that)i(single)f(e)o (xample.)22 b(Use)16 b FJ(+)g FN(to)f(enable)g(the)g(named)g(beha)n (vior)m(,)0 1649 y(or)20 b FJ(-)g FN(to)h(disable)f(it.)0 1796 y(F)o(or)g(e)o(xample,)e(this)j(test)g(passes:)236 2034 y FA(>>>)45 b(print)f(range\(20\))f(#doctest:)g (+NORMALIZE_WHITESPACE)236 2125 y([0,)134 b(1,)90 b(2,)f(3,)g(4,)h(5,)f (6,)g(7,)h(8,)f(9,)236 2217 y(10,)g(11,)45 b(12,)f(13,)g(14,)h(15,)f (16,)g(17,)h(18,)f(19])0 2503 y FN(W)m(ithout)21 b(the)h(directi)n(v)o (e)f(it)i(w)o(ould)e(f)o(ail,)i(both)e(because)g(the)h(actual)g(output) f(doesn')o(t)f(ha)n(v)o(e)i(tw)o(o)g(blanks)f(before)g(the)h (single-digit)e(list)0 2603 y(elements,)f(and)g(because)g(the)h(actual) g(output)e(is)j(on)e(a)h(single)g(line.)25 b(This)20 b(test)g(also)g(passes,)h(and)e(also)h(requires)e(a)j(directi)n(v)o(e)d (to)i(do)f(so:)236 2841 y FA(>>>)45 b(print)f(range\(20\))f(#)i (doctest:+ELLIPSIS)236 2932 y([0,)g(1,)f(...,)g(18,)h(19])0 3219 y FN(Multiple)20 b(directi)n(v)o(es)f(can)h(be)g(used)g(on)g(a)g (single)h(physical)e(line,)h(separated)f(by)h(commas:)236 3457 y FA(>>>)45 b(print)f(range\(20\))f(#)i(doctest:)e(+ELLIPSIS,)g (+NORMALIZE_WHITESPACE)236 3548 y([0,)179 b(1,)45 b(...,)133 b(18,)179 b(19])0 3835 y FN(If)20 b(multiple)g(directi)n(v)o(e)f (comments)g(are)h(used)g(for)f(a)i(single)f(e)o(xample,)e(then)i(the)o (y)g(are)g(combined:)236 4073 y FA(>>>)45 b(print)f(range\(20\))f(#)i (doctest:)e(+ELLIPSIS)236 4164 y(...)762 b(#)45 b(doctest:)e (+NORMALIZE_WHITESPACE)236 4256 y([0,)179 b(1,)45 b(...,)133 b(18,)179 b(19])0 4542 y FN(As)27 b(the)f(pre)n(vious)f(e)o(xample)g (sho)n(ws,)i(you)f(can)g(add)g(`)p FJ(...)p FN(')42 b(lines)27 b(to)f(your)f(e)o(xample)g(containing)g(only)g(directi)n(v)o(es.)42 b(This)27 b(can)f(be)0 4642 y(useful)20 b(when)f(an)h(e)o(xample)f(is)i (too)f(long)g(for)f(a)i(directi)n(v)o(e)e(to)h(comfortably)e(\002t)j (on)e(the)h(same)h(line:)236 4880 y FA(>>>)45 b(print)f(range\(5\))f(+) i(range\(10,20\))e(+)h(range\(30,40\))f(+)i(range\(50,60\))236 4971 y(...)g(#)f(doctest:)g(+ELLIPSIS)236 5063 y([0,)h(...,)f(4,)g(10,) h(...,)f(19,)g(30,)g(...,)h(39,)f(50,)g(...,)g(59])0 5349 y FN(Note)23 b(that)g(since)h(all)g(options)e(are)h(disabled)f(by) h(def)o(ault,)g(and)g(directi)n(v)o(es)f(apply)g(only)g(to)i(the)f(e)o (xample)f(the)o(y)g(appear)g(in,)i(enabling)p 0 5549 3901 4 v 0 5649 a FI(774)2576 b(Chapter)23 b(23.)52 b(De)n(v)n (elopment)24 b(T)-10 b(ools)p eop end %%Page: 775 787 TeXDict begin 775 786 bop 0 83 a FN(options)29 b(\(via)g FJ(+)h FN(in)g(a)g(directi)n(v)o(e\))e(is)j(usually)e(the)h(only)f (meaningful)e(choice.)53 b(Ho)n(we)n(v)o(er)m(,)30 b(option)e(\003ags)j (can)e(also)h(be)g(passed)f(to)0 183 y(functions)22 b(that)h(run)f (doctests,)i(establishing)e(dif)n(ferent)f(def)o(aults.)33 b(In)23 b(such)g(cases,)h(disabling)e(an)h(option)f(via)h FJ(-)g FN(in)h(a)f(directi)n(v)o(e)f(can)0 282 y(be)e(useful.)0 429 y(Changed)47 b(in)h(v)o(ersion)e(2.4:)i(Constants)g FJ(DONT_ACCEPT_BLANKLINE)p FN(,)c FJ(NORMALIZE_WHITESPACE)p FN(,)h FJ(ELLIPSIS)p FN(,)0 529 y FJ(IGNORE_EXCEPTION_DETAIL)p FN(,)53 b FJ(REPORT_UDIFF)p FN(,)i FJ(REPORT_CDIFF)p FN(,)g FJ(REPORT_NDIFF)p FN(,)g FJ(REPORT_ONLY_-)0 628 y(FIRST_FAILURE)p FN(,)26 b FJ(COMPARISON_FLAGS)f FN(and)i FJ(REPORTING_FLAGS)f FN(were)i(added;)i(by)e(def)o(ault)f FJ(<BLANKLINE>)f FN(in)0 728 y(e)o(xpected)19 b(output)h(matches)h(an)g (empty)f(line)h(in)g(actual)g(output;)f(and)g(doctest)h(directi)n(v)o (es)f(were)h(added.)82 b(Changed)19 b(in)i(v)o(ersion)f(2.5:)0 828 y(Constant)g FJ(SKIP)g FN(w)o(as)h(added.)0 975 y(There')-5 b(s)20 b(also)g(a)h(w)o(ay)f(to)g(re)o(gister)f(ne)n(w)h(option)f (\003ag)h(names,)g(although)e(this)i(isn')o(t)g(useful)g(unless)g(you)f (intend)g(to)i(e)o(xtend)d FJ(doctest)0 1074 y FN(internals)i(via)g (subclassing:)0 1221 y FD(register_optionflag)p FJ(\()p FK(name)p FJ(\))208 1321 y FN(Create)42 b(a)h(ne)n(w)f(option)e(\003ag) j(with)f(a)h(gi)n(v)o(en)e(name,)46 b(and)c(return)f(the)h(ne)n(w)g (\003ag')-5 b(s)43 b(inte)o(ger)e(v)n(alue.)90 b FJ(register_-)208 1420 y(optionflag\(\))23 b FN(can)j(be)f(used)g(when)g(subclassing)g FJ(OutputChecker)e FN(or)j FJ(DocTestRunner)d FN(to)j(create)f(ne)n(w)g (op-)208 1520 y(tions)30 b(that)g(are)f(supported)f(by)i(your)f (subclasses.)54 b FJ(register_optionflag)27 b FN(should)i(al)o(w)o(ays) h(be)g(called)g(using)g(the)208 1620 y(follo)n(wing)18 b(idiom:)533 1844 y FA(MY_FLAG)44 b(=)h (register_optionflag\('MY_FLAG'\))208 2033 y FN(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)0 2301 y FI(W)m(ar)r(nings)0 2504 y FJ(doctest)k FN(is)h(serious)f(about)f(requiring)g(e)o(xact)g (matches)h(in)h(e)o(xpected)e(output.)33 b(If)23 b(e)n(v)o(en)f(a)i (single)f(character)f(doesn')o(t)g(match,)i(the)0 2604 y(test)g(f)o(ails.)36 b(This)24 b(will)g(probably)d(surprise)i(you)g(a) h(fe)n(w)f(times,)i(as)f(you)f(learn)g(e)o(xactly)f(what)i(Python)e (does)h(and)g(doesn')o(t)f(guarantee)0 2704 y(about)f(output.)31 b(F)o(or)22 b(e)o(xample,)f(when)h(printing)f(a)i(dict,)f(Python)g (doesn')o(t)f(guarantee)f(that)j(the)f(k)o(e)o(y-v)n(alue)e(pairs)j (will)g(be)f(printed)f(in)0 2803 y(an)o(y)e(particular)g(order)m(,)g (so)h(a)h(test)g(lik)o(e)236 3041 y FA(>>>)45 b(foo\(\))236 3133 y({"Hermione":)e("hippogryph",)g("Harry":)g("broomstick"})0 3419 y FN(is)21 b(vulnerable!)i(One)d(w)o(orkaround)d(is)k(to)g(do)236 3657 y FA(>>>)45 b(foo\(\))f(==)g({"Hermione":)f("hippogryph",)f ("Harry":)i("broomstick"})236 3749 y(True)0 4035 y FN(instead.)25 b(Another)19 b(is)i(to)f(do)236 4273 y FA(>>>)45 b(d)f(=)h (foo\(\).items\(\))236 4365 y(>>>)g(d.sort\(\))236 4456 y(>>>)g(d)236 4547 y([\('Harry',)e('broomstick'\),)g(\('Hermione',)g ('hippogryph'\)])0 4834 y FN(There)19 b(are)h(others,)g(b)n(ut)g(you)f (get)i(the)f(idea.)0 4981 y(Another)f(bad)g(idea)i(is)g(to)f(print)g (things)f(that)i(embed)e(an)h(object)f(address,)h(lik)o(e)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(775)p eop end %%Page: 776 788 TeXDict begin 776 787 bop 236 174 a FA(>>>)45 b(id\(1.0\))e(#)i (certain)f(to)g(fail)g(some)g(of)h(the)f(time)236 266 y(7948648)236 357 y(>>>)h(class)f(C:)g(pass)236 448 y(>>>)h(C\(\))134 b(#)44 b(the)h(default)e(repr\(\))h(for)g(instances)g(embeds)f(an)i (address)236 540 y(<__main__.C)e(instance)h(at)g(0x00AC18F0>)0 826 y FN(The)20 b FJ(ELLIPSIS)f FN(directi)n(v)o(e)g(gi)n(v)o(es)h(a)g (nice)g(approach)e(for)i(the)g(last)h(e)o(xample:)236 1064 y FA(>>>)45 b(C\(\))f(#doctest:)f(+ELLIPSIS)236 1156 y(<__main__.C)g(instance)h(at)g(0x...>)0 1442 y FN(Floating-point)29 b(numbers)g(are)i(also)g(subject)f(to)h(small)g (output)f(v)n(ariations)g(across)h(platforms,)h(because)e(Python)f (defers)i(to)g(the)0 1542 y(platform)19 b(C)i(library)e(for)g(\003oat)i (formatting,)d(and)h(C)j(libraries)d(v)n(ary)h(widely)f(in)i(quality)e (here.)236 1780 y FA(>>>)45 b(1./7)89 b(#)44 b(risky)236 1871 y(0.14285714285714285)236 1963 y(>>>)h(print)f(1./7)g(#)g(safer) 236 2054 y(0.142857142857)236 2145 y(>>>)h(print)f(round\(1./7,)f(6\))h (#)h(much)f(safer)236 2237 y(0.142857)0 2523 y FN(Numbers)15 b(of)h(the)g(form)e FJ(I/2.)902 2538 y(**)1002 2523 y(J)i FN(are)g(safe)g(across)g(all)g(platforms,)g(and)f(I)h(often)f(contri)n (v)o(e)f(doctest)i(e)o(xamples)f(to)h(produce)e(numbers)0 2623 y(of)20 b(that)g(form:)236 2861 y FA(>>>)45 b(3./4)89 b(#)44 b(utterly)g(safe)236 2952 y(0.75)0 3239 y FN(Simple)20 b(fractions)f(are)h(also)h(easier)f(for)g(people)f(to)h(understand,)e (and)i(that)g(mak)o(es)g(for)g(better)f(documentation.)0 3524 y Fv(23.2.4)101 b(Basic)28 b(API)0 3727 y FN(The)18 b(functions)f FJ(testmod\(\))h FN(and)g FJ(testfile\(\))f FN(pro)o(vide)g(a)i(simple)f(interf)o(ace)g(to)h(doctest)f(that)h (should)e(be)i(suf)n(\002cient)f(for)g(most)0 3826 y(basic)i(uses.)26 b(F)o(or)20 b(a)g(less)i(formal)d(introduction)e(to)k(these)f(tw)o(o)g (functions,)f(see)i(sections)f(23.2.1)e(and)i(23.2.2.)0 3973 y FD(testfile)p FJ(\()p FK(\002lename)p FC([)p FK(,)25 b(module)p 1070 3973 25 4 v 29 w(r)m(elative)12 b FC(][)p FK(,)28 b(name)12 b FC(][)p FK(,)27 b(pac)n(ka)o(g)o(e)12 b FC(][)p FK(,)27 b(globs)12 b FC(][)p FK(,)27 b(verbose)12 b FC(][)p FK(,)28 b(r)m(eport)13 b FC(][)p FK(,)29 b(option\003a)o(gs) 12 b FC(][)p FK(,)25 b(e)n(x-)450 4073 y(tr)o(a)o(globs)12 b FC(][)p FK(,)17 b(r)o(aise)p 1026 4073 V 30 w(on)p 1140 4073 V 29 w(err)l(or)d FC(][)p FK(,)20 b(par)o(ser)14 b FC(][)p FK(,)20 b(encoding)12 b FC(])p FJ(\))208 4157 y FN(All)20 b(ar)o(guments)f(e)o(xcept)g FK(\002lename)g FN(are)h(optional,)f(and)g(should)g(be)h(speci\002ed)g(in)h(k)o(e)o(yw) o(ord)d(form.)208 4289 y(T)-6 b(est)20 b(e)o(xamples)g(in)g(the)g (\002le)h(named)e FK(\002lename)p FN(.)24 b(Return)c(`)p FJ(\()p FK(failur)m(e)p 2152 4289 V 28 w(count)q FJ(,)49 b FK(test)p 2581 4289 V 30 w(count)q FJ(\))p FN('.)208 4422 y(Optional)19 b(ar)o(gument)f FK(module)p 1103 4422 V 28 w(r)m(elative)i FN(speci\002es)h(ho)n(w)f(the)g(\002lename)g (should)f(be)h(interpreted:)349 4635 y FM(\017)o FN(If)h FK(module)p 718 4635 V 28 w(r)m(elative)g FN(is)g FJ(True)f FN(\(the)h(def)o(ault\),)e(then)h FK(\002lename)g FN(speci\002es)h(an)f (OS-independent)e(module-relati)n(v)o(e)f(path.)390 4735 y(By)22 b(def)o(ault,)e(this)h(path)g(is)h(relati)n(v)o(e)e(to)h(the)g (calling)f(module')-5 b(s)20 b(directory;)g(b)n(ut)h(if)g(the)g FK(pac)n(ka)o(g)o(e)f FN(ar)o(gument)e(is)k(speci\002ed,)390 4835 y(then)17 b(it)g(is)h(relati)n(v)o(e)e(to)i(that)f(package.)22 b(T)-7 b(o)17 b(ensure)f(OS-independence,)f FK(\002lename)g FN(should)h(use)i FJ(/)f FN(characters)f(to)h(separate)390 4934 y(path)j(se)o(gments,)f(and)h(may)g(not)f(be)i(an)f(absolute)f (path)h(\(i.e.,)f(it)i(may)f(not)g(be)o(gin)f(with)h FJ(/)p FN(\).)349 5067 y FM(\017)o FN(If)27 b FK(module)p 724 5067 V 28 w(r)m(elative)g FN(is)g FJ(False)p FN(,)g(then)g FK(\002lename)e FN(speci\002es)i(an)f(OS-speci\002c)h(path.)43 b(The)26 b(path)h(may)f(be)g(absolute)g(or)390 5167 y(relati)n(v)o(e;) 20 b(relati)n(v)o(e)f(paths)h(are)g(resolv)o(ed)f(with)h(respect)g(to)h (the)f(current)f(w)o(orking)f(directory)-5 b(.)208 5380 y(Optional)19 b(ar)o(gument)g FK(name)g FN(gi)n(v)o(es)i(the)f(name)g (of)g(the)h(test;)h(by)e(def)o(ault,)g(or)g(if)h FJ(None)p FN(,)f FJ(os.path.basename\()p FK(\002lename)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(776)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 777 789 TeXDict begin 777 788 bop 208 83 a FN(is)21 b(used.)208 216 y(Optional)j(ar)o(gument)f FK(pac)n(ka)o(g)o(e)h FN(is)j(a)f(Python)e(package)g(or)h(the)g(name)g(of)g(a)h(Python)e (package)g(whose)i(directory)d(should)i(be)208 315 y(used)d(as)h(the)g (base)f(directory)f(for)h(a)h(module-relati)n(v)o(e)d(\002lename.)31 b(If)22 b(no)h(package)e(is)i(speci\002ed,)g(then)f(the)g(calling)h (module')-5 b(s)208 415 y(directory)15 b(is)k(used)e(as)h(the)g(base)g (directory)e(for)h(module-relati)n(v)o(e)d(\002lenames.)24 b(It)18 b(is)g(an)g(error)e(to)i(specify)f FK(pac)n(ka)o(g)o(e)f FN(if)i FK(module)p 3849 415 25 4 v 28 w(-)208 515 y(r)m(elative)i FN(is)h FJ(False)p FN(.)208 648 y(Optional)c(ar)o(gument)e FK(globs)i FN(gi)n(v)o(es)h(a)g(dict)g(to)g(be)f(used)h(as)g(the)g (globals)g(when)f(e)o(x)o(ecuting)e(e)o(xamples.)23 b(A)c(ne)n(w)e (shallo)n(w)h(cop)o(y)f(of)208 747 y(this)k(dict)h(is)g(created)f(for)g (the)g(doctest,)g(so)h(its)g(e)o(xamples)e(start)i(with)g(a)g(clean)f (slate.)29 b(By)22 b(def)o(ault,)f(or)g(if)g FJ(None)p FN(,)g(a)h(ne)n(w)f(empty)208 847 y(dict)f(is)h(used.)208 980 y(Optional)i(ar)o(gument)g FK(e)n(xtr)o(a)o(globs)h FN(gi)n(v)o(es)g(a)h(dict)g(mer)o(ged)d(into)j(the)f(globals)g(used)h (to)g(e)o(x)o(ecute)e(e)o(xamples.)37 b(This)25 b(w)o(orks)f(lik)o(e) 208 1079 y FJ(dict.update\(\))p FN(:)k(if)c FK(globs)e FN(and)g FK(e)n(xtr)o(a)o(globs)g FN(ha)n(v)o(e)h(a)g(common)e(k)o(e)o (y)-5 b(,)22 b(the)h(associated)g(v)n(alue)f(in)h FK(e)n(xtr)o(a)o (globs)f FN(appears)g(in)208 1179 y(the)i(combined)f(dict.)38 b(By)25 b(def)o(ault,)f(or)h(if)g FJ(None)p FN(,)g(no)f(e)o(xtra)g (globals)g(are)g(used.)38 b(This)25 b(is)g(an)g(adv)n(anced)d(feature)i (that)g(allo)n(ws)208 1279 y(parameterization)d(of)j(doctests.)37 b(F)o(or)24 b(e)o(xample,)f(a)i(doctest)f(can)g(be)g(written)g(for)g(a) g(base)g(class,)i(using)e(a)h(generic)e(name)g(for)208 1378 y(the)d(class,)i(then)e(reused)g(to)h(test)h(an)o(y)e(number)f(of) h(subclasses)h(by)g(passing)f(an)h FK(e)n(xtr)o(a)o(globs)f FN(dict)h(mapping)e(the)i(generic)e(name)208 1478 y(to)h(the)g (subclass)h(to)f(be)g(tested.)208 1611 y(Optional)e(ar)o(gument)e FK(verbose)j FN(prints)g(lots)h(of)e(stuf)n(f)h(if)g(true,)g(and)g (prints)f(only)g(f)o(ailures)h(if)h(f)o(alse;)g(by)e(def)o(ault,)h(or)f (if)i FJ(None)p FN(,)e(it')-5 b(s)208 1710 y(true)19 b(if)i(and)f(only)f(if)h FJ('-v')g FN(is)i(in)e FJ(sys.argv)p FN(.)208 1843 y(Optional)27 b(ar)o(gument)e FK(r)m(eport)30 b FN(prints)e(a)g(summary)f(at)h(the)h(end)e(when)g(true,)j(else)f (prints)e(nothing)g(at)h(the)g(end.)48 b(In)28 b(v)o(erbose)208 1943 y(mode,)19 b(the)h(summary)f(is)i(detailed,)e(else)i(the)f (summary)f(is)i(v)o(ery)e(brief)g(\(in)h(f)o(act,)h(empty)e(if)h(all)h (tests)h(passed\).)208 2076 y(Optional)d(ar)o(gument)f FK(option\003a)o(gs)g FN(or')-5 b(s)20 b(together)f(option)g(\003ags.) 25 b(See)c(section)f(23.2.3.)208 2208 y(Optional)k(ar)o(gument)f FK(r)o(aise)p 1032 2208 V 29 w(on)p 1145 2208 V 29 w(err)l(or)29 b FN(def)o(aults)24 b(to)i(f)o(alse.)40 b(If)25 b(true,)h(an)f(e)o (xception)f(is)i(raised)f(upon)f(the)h(\002rst)h(f)o(ailure)e(or)h(un-) 208 2308 y(e)o(xpected)g(e)o(xception)h(in)h(an)g(e)o(xample.)45 b(This)28 b(allo)n(ws)f(f)o(ailures)g(to)h(be)f(post-mortem)e(deb)n (ugged.)44 b(Def)o(ault)27 b(beha)n(vior)f(is)i(to)208 2408 y(continue)18 b(running)g(e)o(xamples.)208 2540 y(Optional)i(ar)o(gument)f FK(par)o(ser)k FN(speci\002es)f(a)f FJ(DocTestParser)f FN(\(or)g(subclass\))h(that)h(should)e(be)h(used)g (to)g(e)o(xtract)f(tests)j(from)208 2640 y(the)d(\002les.)26 b(It)20 b(def)o(aults)g(to)g(a)h(normal)e(parser)g(\(i.e.,)h FJ(DocTestParser\(\))p FN(\).)208 2773 y(Optional)f(ar)o(gument)f FK(encoding)g FN(speci\002es)j(an)f(encoding)e(that)i(should)f(be)h (used)g(to)h(con)m(v)o(ert)d(the)i(\002le)h(to)f(unicode.)208 2906 y(Ne)n(w)g(in)g(v)o(ersion)f(2.4.)208 3039 y(Changed)f(in)j(v)o (ersion)e(2.5:)g(The)h(parameter)f FK(encoding)f FN(w)o(as)j(added.)0 3185 y FD(testmod)p FJ(\()p FC([)p FK(m)12 b FC(][)p FK(,)19 b(name)12 b FC(][)p FK(,)20 b(globs)12 b FC(][)p FK(,)20 b(verbose)12 b FC(][)p FK(,)20 b(r)m(eport)13 b FC(][)p FK(,)21 b(option\003a)o(gs)12 b FC(][)p FK(,)19 b(e)n(xtr)o(a)o(globs)12 b FC(][)p FK(,)20 b(r)o(aise)p 3146 3185 V 29 w(on)p 3259 3185 V 29 w(err)l(or)14 b FC(][)p FK(,)22 b(e)n(xclude)p 3849 3185 V 28 w(-)400 3285 y(empty)12 b FC(])p FJ(\))208 3369 y FN(All)20 b(ar)o(guments)f (are)h(optional,)e(and)i(all)h(e)o(xcept)e(for)g FK(m)i FN(should)e(be)h(speci\002ed)g(in)h(k)o(e)o(yw)o(ord)d(form.)208 3502 y(T)-6 b(est)24 b(e)o(xamples)f(in)h(docstrings)e(in)i(functions)f (and)g(classes)i(reachable)d(from)h(module)f FK(m)j FN(\(or)e(module)f FJ(__main__)h FN(if)h FK(m)h FN(is)208 3601 y(not)19 b(supplied)h(or)f(is)j FJ(None)p FN(\),)d(starting)h(with)g FK(m)p FJ(.__doc__)p FN(.)208 3734 y(Also)d(test)h(e)o(xamples)f (reachable)f(from)g(dict)h FK(m)p FJ(.__test__)p FN(,)g(if)g(it)h(e)o (xists)g(and)f(is)h(not)f FJ(None)p FN(.)24 b FK(m)p FJ(.__test__)16 b FN(maps)h(names)208 3834 y(\(strings\))23 b(to)i(functions,)f(classes)h(and)f(strings;)j(function)22 b(and)i(class)i(docstrings)d(are)h(searched)g(for)g(e)o(xamples;)h (strings)g(are)208 3933 y(searched)19 b(directly)-5 b(,)18 b(as)j(if)g(the)o(y)e(were)h(docstrings.)208 4066 y(Only)f(docstrings)g (attached)h(to)g(objects)g(belonging)e(to)i(module)f FK(m)i FN(are)f(searched.)208 4199 y(Return)f(`)p FJ(\()p FK(failur)m(e)p 756 4199 V 29 w(count)q FJ(,)49 b FK(test)p 1186 4199 V 30 w(count)q FJ(\))p FN('.)208 4332 y(Optional)19 b(ar)o(gument)f FK(name)h FN(gi)n(v)o(es)h(the)g(name)g(of)g(the)g (module;)f(by)h(def)o(ault,)f(or)h(if)g FJ(None)p FN(,)g FK(m)p FJ(.__name__)f FN(is)i(used.)208 4465 y(Optional)36 b(ar)o(gument)g FK(e)n(xclude)p 1145 4465 V 29 w(empty)h FN(def)o(aults)h(to)f(f)o(alse.)79 b(If)37 b(true,)42 b(objects)37 b(for)g(which)h(no)f(doctests)h(are)g(found)e(are)208 4564 y(e)o(xcluded)43 b(from)i(consideration.)100 b(The)45 b(def)o(ault)g(is)i(a)f(backw)o(ard)e(compatibility)h(hack,)51 b(so)46 b(that)g(code)f(still)i(using)208 4664 y FJ (doctest.master.summarize\(\))26 b FN(in)32 b(conjunction)c(with)j FJ(testmod\(\))f FN(continues)g(to)h(get)h(output)d(for)i(objects)208 4763 y(with)20 b(no)g(tests.)26 b(The)20 b FK(e)n(xclude)p 1082 4763 V 28 w(empty)g FN(ar)o(gument)e(to)j(the)f(ne)n(wer)f FJ(DocTestFinder)g FN(constructor)f(def)o(aults)i(to)g(true.)208 4896 y(Optional)e(ar)o(guments)f FK(e)n(xtr)o(a)o(globs)p FN(,)i FK(verbose)p FN(,)g FK(r)m(eport)q FN(,)h FK(option\003a)o(gs)p FN(,)d FK(r)o(aise)p 2395 4896 V 29 w(on)p 2508 4896 V 29 w(err)l(or)r FN(,)j(and)f FK(globs)g FN(are)g(the)h(same)f(as)h (for)f(func-)208 4996 y(tion)g FJ(testfile\(\))g FN(abo)o(v)o(e,)g(e)o (xcept)g(that)h FK(globs)g FN(def)o(aults)g(to)g FK(m)p FJ(.__dict__)p FN(.)208 5129 y(Changed)e(in)j(v)o(ersion)e(2.3:)g(The)h (parameter)f FK(option\003a)o(gs)f FN(w)o(as)j(added.)208 5262 y(Changed)d(in)j(v)o(ersion)e(2.4:)g(The)h(parameters)f FK(e)n(xtr)o(a)o(globs)p FN(,)g FK(r)o(aise)p 2113 5262 V 30 w(on)p 2227 5262 V 29 w(err)l(or)k FN(and)d FK(e)n(xclude)p 2844 5262 V 29 w(empty)g FN(were)g(added.)208 5394 y(Changed)e(in)j(v)o (ersion)e(2.5:)g(The)h(optional)f(ar)o(gument)f FK(isprivate)p FN(,)i(deprecated)e(in)j(2.4,)e(w)o(as)i(remo)o(v)o(ed.)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(777)p eop end %%Page: 778 790 TeXDict begin 778 789 bop 0 83 a FN(There')-5 b(s)27 b(also)g(a)h(function)e(to)h(run)f(the)i(doctests)f(associated)g(with)g (a)h(single)f(object.)46 b(This)27 b(function)f(is)i(pro)o(vided)d(for) h(backw)o(ard)0 183 y(compatibility)-5 b(.)23 b(There)c(are)h(no)g (plans)g(to)h(deprecate)d(it,)j(b)n(ut)f(it')-5 b(s)22 b(rarely)d(useful:)0 330 y FD(run_docstring_examples)p FJ(\()p FK(f)o(,)d(globs)p FC([)p FK(,)k(verbose)12 b FC(][)p FK(,)19 b(name)12 b FC(][)p FK(,)19 b(compile\003a)o(gs)12 b FC(][)p FK(,)17 b(option\003a)o(gs)12 b FC(])p FJ(\))208 429 y FN(T)-6 b(est)20 b(e)o(xamples)g(associated)g(with)g(object)g FK(f)12 b FN(;)21 b(for)e(e)o(xample,)g FK(f)33 b FN(may)19 b(be)h(a)h(module,)e(function,)f(or)i(class)h(object.)208 562 y(A)f(shallo)n(w)g(cop)o(y)g(of)f(dictionary)g(ar)o(gument)f FK(globs)h FN(is)i(used)f(for)g(the)g(e)o(x)o(ecution)e(conte)o(xt.)208 694 y(Optional)h(ar)o(gument)f FK(name)h FN(is)i(used)f(in)h(f)o (ailure)e(messages,)h(and)g(def)o(aults)g(to)g FJ("NoName")p FN(.)208 826 y(If)28 b(optional)g(ar)o(gument)f FK(verbose)i FN(is)h(true,)h(output)c(is)j(generated)e(e)n(v)o(en)g(if)h(there)g (are)g(no)g(f)o(ailures.)51 b(By)29 b(def)o(ault,)i(output)d(is)208 926 y(generated)18 b(only)h(in)i(case)f(of)g(an)g(e)o(xample)f(f)o (ailure.)208 1058 y(Optional)g(ar)o(gument)e FK(compile\003a)o(gs)i FN(gi)n(v)o(es)g(the)h(set)h(of)f(\003ags)g(that)g(should)f(be)h(used)g (by)g(the)g(Python)f(compiler)f(when)i(running)208 1158 y(the)26 b(e)o(xamples.)44 b(By)27 b(def)o(ault,)h(or)e(if)h FJ(None)p FN(,)h(\003ags)g(are)e(deduced)f(corresponding)f(to)j(the)f (set)i(of)f(future)e(features)h(found)f(in)208 1258 y FK(globs)p FN(.)208 1390 y(Optional)19 b(ar)o(gument)f FK(option\003a)o(gs)g FN(w)o(orks)i(as)g(for)g(function)e FJ(testfile\(\))h FN(abo)o(v)o(e.)0 1674 y Fv(23.2.5)101 b(Unittest)27 b(API)0 1877 y FN(As)f(your)e(collection)h(of)g (doctest'ed)f(modules)g(gro)n(ws,)i(you')o(ll)e(w)o(ant)i(a)g(w)o(ay)f (to)h(run)e(all)i(their)f(doctests)h(systematically)-5 b(.)39 b(Prior)25 b(to)0 1977 y(Python)c(2.4,)g FJ(doctest)g FN(had)g(a)h(barely)f(documented)e FJ(Tester)i FN(class)i(that)f (supplied)e(a)j(rudimentary)c(w)o(ay)i(to)h(combine)f(doctests)0 2077 y(from)26 b(multiple)g(modules.)45 b FJ(Tester)26 b FN(w)o(as)i(feeble,)g(and)e(in)h(practice)g(most)g(serious)f(Python)g (testing)h(frame)n(w)o(orks)e(b)n(uild)i(on)g(the)0 2176 y FJ(unittest)d FN(module,)g(which)g(supplies)g(man)o(y)f(\003e)o (xible)h(w)o(ays)h(to)f(combine)f(tests)j(from)e(multiple)f(sources.)38 b(So,)25 b(in)g(Python)e(2.4,)0 2276 y FJ(doctest)p FN(')-5 b(s)17 b FJ(Tester)f FN(class)i(is)g(deprecated,)e(and)g FJ(doctest)h FN(pro)o(vides)e(tw)o(o)i(functions)f(that)h(can)g(be)g (used)g(to)g(create)f FJ(unittest)0 2375 y FN(test)27 b(suites)f(from)f(modules)f(and)h(te)o(xt)h(\002les)h(containing)c (doctests.)42 b(These)25 b(test)i(suites)f(can)g(then)f(be)h(run)f (using)g FJ(unittest)g FN(test)0 2475 y(runners:)236 2713 y FA(import)44 b(unittest)236 2805 y(import)g(doctest)236 2896 y(import)g(my_module_with_doctests,)d(and_another)236 3079 y(suite)j(=)h(unittest.TestSuite\(\))236 3170 y(for)g(mod)f(in)g (my_module_with_doctests,)d(and_another:)416 3261 y (suite.addTest\(doctest.DocTestSuite\(m)o(od\)\))236 3352 y(runner)j(=)h(unittest.TextTestRunner\(\))236 3444 y(runner.run\(suite\))0 3730 y FN(There)32 b(are)h(tw)o(o)g(main)g (functions)e(for)i(creating)f FJ(unittest.TestSuite)e FN(instances)j(from)e(te)o(xt)i(\002les)h(and)f(modules)e(with)0 3830 y(doctests:)0 3977 y FD(DocFileSuite)p FJ(\()p FC([)p FK(module)p 941 3977 25 4 v 26 w(r)m(elative)12 b FC(][)p FK(,)31 b(pac)n(ka)o(g)o(e)12 b FC(][)p FK(,)31 b(setUp)12 b FC(][)p FK(,)32 b(tearDown)12 b FC(][)p FK(,)31 b(globs)12 b FC(][)p FK(,)31 b(option\003a)o(gs)12 b FC(][)p FK(,)30 b(par)o(ser)14 b FC(][)p FK(,)32 b(en-)650 4076 y(coding)12 b FC(])p FJ(\))208 4160 y FN(Con)m(v)o(ert)18 b(doctest)i(tests)i(from) d(one)g(or)h(more)g(te)o(xt)g(\002les)h(to)f(a)h FJ(unittest.TestSuite) p FN(.)208 4292 y(The)16 b(returned)g FJ(unittest.TestSuite)e FN(is)19 b(to)e(be)g(run)g(by)f(the)i(unittest)f(frame)n(w)o(ork)e(and) i(runs)g(the)g(interacti)n(v)o(e)f(e)o(xamples)208 4392 y(in)25 b(each)h(\002le.)42 b(If)25 b(an)h(e)o(xample)e(in)i(an)o(y)e (\002le)j(f)o(ails,)g(then)e(the)h(synthesized)f(unit)g(test)h(f)o (ails,)i(and)d(a)h FJ(failureException)208 4492 y FN(e)o(xception)17 b(is)j(raised)f(sho)n(wing)f(the)h(name)g(of)g(the)g(\002le)h (containing)d(the)i(test)i(and)d(a)i(\(sometimes)e(approximate\))f (line)i(number)-5 b(.)208 4624 y(P)o(ass)21 b(one)e(or)h(more)g(paths)g (\(as)g(strings\))g(to)g(te)o(xt)g(\002les)i(to)e(be)g(e)o(xamined.)208 4756 y(Options)f(may)h(be)g(pro)o(vided)e(as)j(k)o(e)o(yw)o(ord)d(ar)o (guments:)208 4889 y(Optional)h(ar)o(gument)f FK(module)p 1103 4889 V 28 w(r)m(elative)i FN(speci\002es)h(ho)n(w)f(the)g (\002lenames)g(in)g FK(paths)g FN(should)f(be)h(interpreted:)349 5101 y FM(\017)o FN(If)h FK(module)p 718 5101 V 28 w(r)m(elative)h FN(is)g FJ(True)f FN(\(the)g(def)o(ault\),)f(then)g(each)h(\002lename)g (speci\002es)g(an)g(OS-independent)e(module-relati)n(v)o(e)390 5201 y(path.)49 b(By)29 b(def)o(ault,)g(this)g(path)f(is)h(relati)n(v)o (e)f(to)g(the)g(calling)g(module')-5 b(s)28 b(directory;)i(b)n(ut)f(if) f(the)g FK(pac)n(ka)o(g)o(e)g FN(ar)o(gument)e(is)390 5300 y(speci\002ed,)32 b(then)e(it)h(is)f(relati)n(v)o(e)g(to)g(that)g (package.)53 b(T)-7 b(o)30 b(ensure)g(OS-independence,)f(each)g (\002lename)h(should)f(use)h FJ(/)390 5400 y FN(characters)19 b(to)i(separate)f(path)f(se)o(gments,)h(and)f(may)h(not)g(be)g(an)g (absolute)f(path)h(\(i.e.,)g(it)h(may)e(not)h(be)o(gin)f(with)i FJ(/)p FN(\).)p 0 5549 3901 4 v 0 5649 a FI(778)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 779 791 TeXDict begin 779 790 bop 349 83 a FM(\017)o FN(If)22 b FK(module)p 719 83 25 4 v 28 w(r)m(elative)f FN(is)i FJ(False)p FN(,)e(then)g(each)g(\002lename)g(speci\002es)h(an)f (OS-speci\002c)h(path.)28 b(The)21 b(path)g(may)g(be)g(absolute)390 183 y(or)f(relati)n(v)o(e;)g(relati)n(v)o(e)f(paths)h(are)g(resolv)o (ed)f(with)h(respect)g(to)h(the)f(current)f(w)o(orking)f(directory)-5 b(.)208 396 y(Optional)24 b(ar)o(gument)f FK(pac)n(ka)o(g)o(e)h FN(is)j(a)f(Python)e(package)g(or)h(the)g(name)g(of)g(a)h(Python)e (package)g(whose)i(directory)d(should)i(be)208 496 y(used)e(as)i(the)f (base)g(directory)f(for)g(module-relati)n(v)o(e)e(\002lenames.)37 b(If)23 b(no)h(package)f(is)i(speci\002ed,)f(then)g(the)g(calling)g (module')-5 b(s)208 595 y(directory)15 b(is)k(used)e(as)h(the)g(base)g (directory)e(for)h(module-relati)n(v)o(e)d(\002lenames.)24 b(It)18 b(is)g(an)g(error)e(to)i(specify)f FK(pac)n(ka)o(g)o(e)f FN(if)i FK(module)p 3849 595 V 28 w(-)208 695 y(r)m(elative)i FN(is)h FJ(False)p FN(.)208 828 y(Optional)g(ar)o(gument)f FK(setUp)i FN(speci\002es)h(a)f(set-up)g(function)e(for)i(the)g(test)h (suite.)31 b(This)22 b(is)h(called)f(before)f(running)f(the)i(tests)h (in)208 927 y(each)d(\002le.)27 b(The)20 b FK(setUp)h FN(function)e(will)i(be)f(passed)h(a)g FJ(DocTest)f FN(object.)25 b(The)c(setUp)g(function)d(can)j(access)g(the)g(test)g(globals)208 1027 y(as)f(the)h FK(globs)e FN(attrib)n(ute)h(of)g(the)g(test)h (passed.)208 1160 y(Optional)j(ar)o(gument)e FK(tearDown)j FN(speci\002es)g(a)g(tear)n(-do)n(wn)e(function)h(for)g(the)h(test)g (suite.)40 b(This)25 b(is)h(called)e(after)h(running)e(the)208 1259 y(tests)f(in)e(each)h(\002le.)27 b(The)21 b FK(tearDown)f FN(function)f(will)j(be)f(passed)f(a)i FJ(DocTest)e FN(object.)26 b(The)20 b(setUp)h(function)f(can)g(access)i(the)208 1359 y(test)f(globals)e(as)i(the)f FK(globs)g FN(attrib)n(ute)g(of)g (the)g(test)h(passed.)208 1492 y(Optional)g(ar)o(gument)f FK(globs)h FN(is)i(a)g(dictionary)d(containing)g(the)j(initial)f (global)f(v)n(ariables)h(for)f(the)h(tests.)32 b(A)23 b(ne)n(w)f(cop)o(y)f(of)h(this)208 1591 y(dictionary)c(is)j(created)f (for)f(each)h(test.)26 b(By)20 b(def)o(ault,)g FK(globs)f FN(is)i(a)g(ne)n(w)f(empty)f(dictionary)-5 b(.)208 1724 y(Optional)31 b(ar)o(gument)f FK(option\003a)o(gs)g FN(speci\002es)j (the)f(def)o(ault)f(doctest)h(options)g(for)f(the)h(tests,)37 b(created)31 b(by)h(or)n(-ing)f(together)208 1824 y(indi)n(vidual)26 b(option)h(\003ags.)49 b(See)29 b(section)f(23.2.3.)47 b(See)29 b(function)d FJ(set_unittest_reportflags\(\))e FN(belo)n(w)k(for)f(a)208 1924 y(better)19 b(w)o(ay)i(to)f(set)h (reporting)d(options.)208 2056 y(Optional)i(ar)o(gument)f FK(par)o(ser)k FN(speci\002es)f(a)f FJ(DocTestParser)f FN(\(or)g(subclass\))h(that)h(should)e(be)h(used)g(to)g(e)o(xtract)f (tests)j(from)208 2156 y(the)d(\002les.)26 b(It)20 b(def)o(aults)g(to)g (a)h(normal)e(parser)g(\(i.e.,)h FJ(DocTestParser\(\))p FN(\).)208 2289 y(Optional)f(ar)o(gument)f FK(encoding)g FN(speci\002es)j(an)f(encoding)e(that)i(should)f(be)h(used)g(to)h(con)m (v)o(ert)d(the)i(\002le)h(to)f(unicode.)208 2422 y(Ne)n(w)g(in)g(v)o (ersion)f(2.4.)208 2555 y(Changed)24 b(in)i(v)o(ersion)f(2.5:)g(The)h (global)f FJ(__file__)g FN(w)o(as)h(added)f(to)h(the)g(globals)f(pro)o (vided)f(to)i(doctests)g(loaded)e(from)h(a)208 2654 y(te)o(xt)20 b(\002le)g(using)g FJ(DocFileSuite\(\))p FN(.)208 2787 y(Changed)e(in)j(v)o(ersion)e(2.5:)g(The)h(parameter)f FK(encoding)f FN(w)o(as)j(added.)0 2934 y FD(DocTestSuite)p FJ(\()p FC([)p FK(module)12 b FC(][)p FK(,)k(globs)c FC(][)p FK(,)19 b(e)n(xtr)o(a)o(globs)12 b FC(][)p FK(,)18 b(test)p 1977 2934 V 31 w(\002nder)c FC(][)p FK(,)k(setUp)12 b FC(][)p FK(,)20 b(tearDown)12 b FC(][)p FK(,)19 b(c)o(hec)n(k)o(er)14 b FC(])p FJ(\))208 3033 y FN(Con)m(v)o(ert)k(doctest)i(tests)i(for)d(a) i(module)e(to)h(a)h FJ(unittest.TestSuite)p FN(.)208 3166 y(The)28 b(returned)g FJ(unittest.TestSuite)e FN(is)k(to)f(be)g (run)g(by)f(the)h(unittest)h(frame)n(w)o(ork)d(and)h(runs)h(each)f (doctest)h(in)h(the)208 3266 y(module.)e(If)21 b(an)o(y)g(of)h(the)f (doctests)h(f)o(ail,)g(then)g(the)g(synthesized)e(unit)i(test)g(f)o (ails,)h(and)e(a)h FJ(failureException)d FN(e)o(xception)208 3366 y(is)i(raised)f(sho)n(wing)f(the)h(name)g(of)f(the)i(\002le)f (containing)f(the)h(test)h(and)f(a)g(\(sometimes)g(approximate\))d (line)k(number)-5 b(.)208 3498 y(Optional)24 b(ar)o(gument)e FK(module)i FN(pro)o(vides)f(the)i(module)f(to)h(be)g(tested.)39 b(It)26 b(can)e(be)h(a)h(module)d(object)i(or)f(a)i(\(possibly)e (dotted\))208 3598 y(module)18 b(name.)25 b(If)20 b(not)g(speci\002ed,) f(the)h(module)f(calling)h(this)h(function)d(is)j(used.)208 3731 y(Optional)g(ar)o(gument)f FK(globs)h FN(is)i(a)g(dictionary)d (containing)g(the)j(initial)f(global)f(v)n(ariables)h(for)f(the)h (tests.)32 b(A)23 b(ne)n(w)f(cop)o(y)f(of)h(this)208 3830 y(dictionary)c(is)j(created)f(for)f(each)h(test.)26 b(By)20 b(def)o(ault,)g FK(globs)f FN(is)i(a)g(ne)n(w)f(empty)f (dictionary)-5 b(.)208 3963 y(Optional)19 b(ar)o(gument)f FK(e)n(xtr)o(a)o(globs)i FN(speci\002es)h(an)g(e)o(xtra)f(set)h(of)f (global)g(v)n(ariables,)g(which)g(is)h(mer)o(ged)e(into)h FK(globs)p FN(.)26 b(By)21 b(def)o(ault,)208 4063 y(no)e(e)o(xtra)h (globals)f(are)i(used.)208 4196 y(Optional)e(ar)o(gument)e FK(test)p 971 4196 V 31 w(\002nder)k FN(is)g(the)f FJ(DocTestFinder)e FN(object)h(\(or)h(a)g(drop-in)e(replacement\))g(that)i(is)h(used)f(to) g(e)o(xtract)208 4295 y(doctests)g(from)f(the)h(module.)208 4428 y(Optional)f(ar)o(guments)f FK(setUp)p FN(,)i FK(tearDown)p FN(,)g(and)f FK(option\003a)o(gs)f FN(are)j(the)f(same)g(as)h(for)f (function)e FJ(DocFileSuite\(\))g FN(abo)o(v)o(e.)208 4561 y(Ne)n(w)i(in)g(v)o(ersion)f(2.3.)208 4694 y(Changed)j(in)i(v)o (ersion)f(2.4:)g(The)h(parameters)f FK(globs)p FN(,)h FK(e)n(xtr)o(a)o(globs)p FN(,)g FK(test)p 2317 4694 V 30 w(\002nder)r FN(,)g FK(setUp)p FN(,)g FK(tearDown)p FN(,)h(and)e FK(option\003a)o(gs)f FN(were)208 4794 y(added;)d(this)h (function)f(no)n(w)g(uses)i(the)f(same)h(search)f(technique)e(as)j FJ(testmod\(\))p FN(.)0 4940 y(Under)26 b(the)i(co)o(v)o(ers,)f FJ(DocTestSuite\(\))f FN(creates)h(a)h FJ(unittest.TestSuite)c FN(out)j(of)g FJ(doctest.DocTestCase)e FN(in-)0 5040 y(stances,)f(and)e FJ(DocTestCase)g FN(is)i(a)f(subclass)g(of)g FJ(unittest.TestCase)p FN(.)31 b FJ(DocTestCase)21 b FN(isn')o(t)i(documented)d(here)j(\(it')-5 b(s)0 5140 y(an)20 b(internal)g(detail\),)f(b)n(ut)h(studying)f(its)i(code)f(can)g (answer)g(questions)f(about)g(the)i(e)o(xact)e(details)i(of)f FJ(unittest)f FN(inte)o(gration.)0 5287 y(Similarly)-5 b(,)16 b FJ(DocFileSuite\(\))d FN(creates)j(a)g FJ(unittest.TestSuite)d FN(out)i(of)g FJ(doctest.DocFileCase)e FN(instances,)j(and)0 5386 y FJ(DocFileCase)j FN(is)i(a)f(subclass)h(of)f FJ(DocTestCase)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(779)p eop end %%Page: 780 792 TeXDict begin 780 791 bop 0 83 a FN(So)32 b(both)f(w)o(ays)h(of)f (creating)g(a)h FJ(unittest.TestSuite)d FN(run)i(instances)h(of)f FJ(DocTestCase)p FN(.)58 b(This)32 b(is)h(important)d(for)h(a)0 183 y(subtle)e(reason:)41 b(when)28 b(you)g(run)f FJ(doctest)h FN(functions)g(yourself,)h(you)e(can)i(control)e(the)i FJ(doctest)f FN(options)f(in)i(use)g(directly)-5 b(,)0 282 y(by)27 b(passing)h(option)e(\003ags)i(to)g FJ(doctest)f FN(functions.)47 b(Ho)n(we)n(v)o(er)m(,)27 b(if)h(you')l(re)e(writing)h (a)h FJ(unittest)f FN(frame)n(w)o(ork,)g FJ(unittest)0 382 y FN(ultimately)19 b(controls)h(when)f(and)h(ho)n(w)f(tests)j(get)e (run.)k(The)c(frame)n(w)o(ork)e(author)g(typically)i(w)o(ants)g(to)g (control)f FJ(doctest)h FN(reporting)0 482 y(options)g(\(perhaps,)f (e.g.,)i(speci\002ed)f(by)h(command)e(line)i(options\),)e(b)n(ut)i (there')-5 b(s)21 b(no)f(w)o(ay)h(to)g(pass)h(options)e(through)e FJ(unittest)i FN(to)0 581 y FJ(doctest)f FN(test)j(runners.)0 728 y(F)o(or)c(this)i(reason,)e FJ(doctest)g FN(also)h(supports)e(a)j (notion)d(of)h FJ(doctest)g FN(reporting)f(\003ags)i(speci\002c)g(to)g FJ(unittest)f FN(support,)f(via)i(this)0 828 y(function:)0 975 y FD(set_unittest_reportflags)p FJ(\()p FK(\003a)o(gs)p FJ(\))208 1074 y FN(Set)h(the)h FJ(doctest)e FN(reporting)f(\003ags)j (to)f(use.)208 1207 y(Ar)o(gument)d FK(\003a)o(gs)j FN(or')-5 b(s)21 b(together)d(option)h(\003ags.)26 b(See)20 b(section)g(23.2.3.)j (Only)d(\224reporting)e(\003ags\224)i(can)g(be)h(used.)208 1340 y(This)27 b(is)g(a)h(module-global)23 b(setting,)28 b(and)f(af)n(fects)f(all)i(future)d(doctests)i(run)f(by)h(module)e FJ(unittest)p FN(:)38 b(the)27 b FJ(runTest\(\))208 1439 y FN(method)14 b(of)i FJ(DocTestCase)e FN(looks)h(at)i(the)f(option)e (\003ags)j(speci\002ed)e(for)g(the)h(test)h(case)f(when)g(the)g FJ(DocTestCase)e FN(instance)208 1539 y(w)o(as)30 b(constructed.)52 b(If)30 b(no)f(reporting)f(\003ags)i(were)g(speci\002ed)g(\(which)e(is) j(the)f(typical)f(and)h(e)o(xpected)e(case\),)k FJ(doctest)p FN(')-5 b(s)208 1639 y FJ(unittest)29 b FN(reporting)e(\003ags)k(are)e (or'ed)g(into)h(the)g(option)e(\003ags,)33 b(and)c(the)h(option)f (\003ags)h(so)g(augmented)e(are)i(passed)f(to)208 1738 y(the)j FJ(DocTestRunner)f FN(instance)h(created)g(to)g(run)g(the)h (doctest.)61 b(If)33 b(an)o(y)f(reporting)e(\003ags)j(were)f (speci\002ed)h(when)f(the)208 1838 y FJ(DocTestCase)18 b FN(instance)i(w)o(as)h(constructed,)d FJ(doctest)p FN(')-5 b(s)20 b FJ(unittest)f FN(reporting)g(\003ags)h(are)g(ignored.) 208 1971 y(The)f(v)n(alue)h(of)g(the)g FJ(unittest)f FN(reporting)f(\003ags)j(in)f(ef)n(fect)g(before)f(the)h(function)e(w)o (as)j(called)f(is)h(returned)e(by)g(the)i(function.)208 2104 y(Ne)n(w)f(in)g(v)o(ersion)f(2.4.)0 2389 y Fv(23.2.6)101 b(Adv)n(anced)29 b(API)0 2591 y FN(The)16 b(basic)g(API)g(is)h(a)g (simple)f(wrapper)f(that')-5 b(s)16 b(intended)f(to)h(mak)o(e)g (doctest)g(easy)g(to)g(use.)24 b(It)16 b(is)h(f)o(airly)f(\003e)o (xible,)g(and)f(should)g(meet)i(most)0 2691 y(users')23 b(needs;)i(ho)n(we)n(v)o(er)m(,)d(if)h(you)g(require)f(more)h (\002ne-grained)e(control)h(o)o(v)o(er)g(testing,)i(or)f(wish)h(to)f(e) o(xtend)g(doctest')-5 b(s)23 b(capabilities,)0 2791 y(then)d(you)f (should)g(use)i(the)f(adv)n(anced)e(API.)0 2938 y(The)23 b(adv)n(anced)f(API)i(re)n(v)n(olv)o(es)e(around)g(tw)o(o)i(container)e (classes,)k(which)d(are)h(used)f(to)h(store)f(the)h(interacti)n(v)o(e)e (e)o(xamples)h(e)o(xtracted)0 3037 y(from)c(doctest)h(cases:)125 3267 y FM(\017)41 b FJ(Example)p FN(:)24 b(A)d(single)f(p)o(ython)e (statement,)i(paired)f(with)i(its)g(e)o(xpected)e(output.)125 3433 y FM(\017)41 b FJ(DocTest)p FN(:)24 b(A)d(collection)e(of)h FJ(Example)p FN(s,)f(typically)h(e)o(xtracted)e(from)i(a)g(single)g (docstring)f(or)h(te)o(xt)g(\002le.)0 3663 y(Additional)f(processing)g (classes)i(are)f(de\002ned)f(to)i(\002nd,)e(parse,)h(and)g(run,)f(and)h (check)f(doctest)h(e)o(xamples:)125 3893 y FM(\017)41 b FJ(DocTestFinder)p FN(:)21 b(Finds)c(all)g(docstrings)f(in)g(a)h(gi)n (v)o(en)f(module,)f(and)h(uses)h(a)g FJ(DocTestParser)e FN(to)i(create)f(a)h FJ(DocTest)208 3993 y FN(from)i(e)n(v)o(ery)g (docstring)f(that)j(contains)e(interacti)n(v)o(e)g(e)o(xamples.)125 4159 y FM(\017)41 b FJ(DocTestParser)p FN(:)23 b(Creates)e(a)f FJ(DocTest)g FN(object)f(from)h(a)g(string)g(\(such)g(as)h(an)f (object')-5 b(s)20 b(docstring\).)125 4325 y FM(\017)41 b FJ(DocTestRunner)p FN(:)46 b(Ex)o(ecutes)30 b(the)i(e)o(xamples)e(in) i(a)g FJ(DocTest)p FN(,)h(and)e(uses)h(an)f FJ(OutputChecker)f FN(to)i(v)o(erify)e(their)208 4424 y(output.)125 4590 y FM(\017)41 b FJ(OutputChecker)p FN(:)25 b(Compares)c(the)h(actual)f (output)f(from)h(a)h(doctest)f(e)o(xample)f(with)h(the)h(e)o(xpected)e (output,)g(and)h(decides)208 4690 y(whether)e(the)o(y)g(match.)0 4920 y(The)h(relationships)f(among)g(these)h(processing)f(classes)i (are)f(summarized)f(in)h(the)g(follo)n(wing)f(diagram:)p 0 5549 3901 4 v 0 5649 a FI(780)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 781 793 TeXDict begin 781 792 bop 1492 174 a FA(list)44 b(of:)236 266 y(+------+)851 b(+---------+)236 357 y(|module|)44 b(--DocTestFinder->)e(|)i(DocTest)g(|)h(--DocTestRunner->)d(results)236 448 y(+------+)178 b(|)359 b(\210)224 b(+---------+)e(|)314 b(\210)179 b(\(printed\))774 540 y(|)359 b(|)224 b(|)44 b(Example)g(|)224 b(|)314 b(|)774 631 y(v)359 b(|)224 b(|)134 b(...)g(|)224 b(v)314 b(|)729 722 y(DocTestParser)133 b(|)44 b(Example)g(|)134 b(OutputChecker)1447 814 y(+---------+)0 1226 y FI(DocT)-10 b(est)22 b(Objects)0 1415 y FL(class)f FD(DocTest)p FJ(\()p FK(e)n(xamples,)d(globs,)h(name)o(,)h(\002lename)o (,)f(lineno,)g(docstring)p FJ(\))208 1515 y FN(A)i(collection)f(of)g (doctest)g(e)o(xamples)g(that)h(should)f(be)g(run)g(in)h(a)g(single)g (namespace.)k(The)c(constructor)d(ar)o(guments)h(are)i(used)208 1614 y(to)f(initialize)g(the)g(member)f(v)n(ariables)h(of)g(the)g(same) g(names.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 1761 y FJ(DocTest)e FN(de\002nes)h(the)g(follo)n(wing)e(member)h(v)n (ariables.)24 b(The)o(y)16 b(are)i(initialized)g(by)g(the)g (constructor)m(,)e(and)h(should)g(not)h(be)g(modi\002ed)0 1861 y(directly)-5 b(.)0 2008 y FD(examples)208 2107 y FN(A)20 b(list)i(of)d FJ(Example)h FN(objects)g(encoding)e(the)i (indi)n(vidual)f(interacti)n(v)o(e)f(Python)h(e)o(xamples)h(that)g (should)f(be)h(run)g(by)f(this)i(test.)0 2254 y FD(globs)208 2354 y FN(The)e(namespace)h(\(aka)f(globals\))h(that)g(the)g(e)o (xamples)f(should)h(be)g(run)f(in.)26 b(This)20 b(is)h(a)g(dictionary)d (mapping)h(names)h(to)g(v)n(alues.)208 2453 y(An)o(y)15 b(changes)h(to)g(the)h(namespace)e(made)g(by)h(the)h(e)o(xamples)e (\(such)h(as)h(binding)e(ne)n(w)h(v)n(ariables\))f(will)i(be)g (re\003ected)e(in)i FJ(globs)208 2553 y FN(after)i(the)i(test)g(is)g (run.)0 2700 y FD(name)208 2799 y FN(A)31 b(string)f(name)h (identifying)e(the)h FJ(DocTest)p FN(.)57 b(T)-7 b(ypically)i(,)32 b(this)f(is)h(the)f(name)f(of)h(the)g(object)f(or)h(\002le)g(that)g (the)g(test)h(w)o(as)208 2899 y(e)o(xtracted)18 b(from.)0 3046 y FD(filename)208 3146 y FN(The)28 b(name)g(of)g(the)g(\002le)h (that)g(this)g FJ(DocTest)f FN(w)o(as)h(e)o(xtracted)e(from;)32 b(or)c FJ(None)g FN(if)h(the)f(\002lename)g(is)i(unkno)n(wn,)e(or)g(if) h(the)208 3245 y FJ(DocTest)19 b FN(w)o(as)i(not)f(e)o(xtracted)f(from) g(a)h(\002le.)0 3392 y FD(lineno)208 3492 y FN(The)k(line)i(number)d (within)i FJ(filename)f FN(where)h(this)g FJ(DocTest)g FN(be)o(gins,)g(or)g FJ(None)g FN(if)g(the)h(line)f(number)e(is)j(una)n (v)n(ailable.)208 3591 y(This)20 b(line)g(number)f(is)i(zero-based)d (with)i(respect)g(to)h(the)f(be)o(ginning)d(of)j(the)h(\002le.)0 3738 y FD(docstring)208 3838 y FN(The)f(string)g(that)h(the)f(test)i(w) o(as)f(e)o(xtracted)f(from,)f(or)h(`None`)g(if)g(the)h(string)f(is)i (una)n(v)n(ailable,)d(or)h(if)h(the)g(test)g(w)o(as)h(not)e(e)o (xtracted)208 3937 y(from)f(a)h(string.)0 4206 y FI(Example)k(Objects)0 4395 y FL(class)d FD(Example)p FJ(\()p FK(sour)m(ce)o(,)d(want)q FC([)p FK(,)j(e)n(xc)p 1203 4395 25 4 v 29 w(msg)12 b FC(][)p FK(,)20 b(lineno)12 b FC(][)p FK(,)19 b(indent)13 b FC(][)p FK(,)19 b(options)12 b FC(])p FJ(\))208 4494 y FN(A)24 b(single)h(interacti)n(v)o(e)e(e)o(xample,)h(consisting)f(of) h(a)h(Python)e(statement)i(and)e(its)j(e)o(xpected)d(output.)36 b(The)24 b(constructor)e(ar)o(gu-)208 4594 y(ments)e(are)g(used)g(to)g (initialize)g(the)h(member)d(v)n(ariables)i(of)g(the)g(same)g(names.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4.)0 4741 y FJ(Example)e FN(de\002nes)h(the)g(follo)n(wing)e(member)h(v)n(ariables.)24 b(The)o(y)16 b(are)i(initialized)g(by)g(the)g(constructor)m(,)e(and)h (should)g(not)h(be)g(modi\002ed)0 4840 y(directly)-5 b(.)0 4987 y FD(source)208 5087 y FN(A)28 b(string)g(containing)e(the)i (e)o(xample')-5 b(s)27 b(source)g(code.)48 b(This)28 b(source)f(code)g(consists)i(of)f(a)g(single)g(Python)f(statement,)i (and)208 5187 y(al)o(w)o(ays)20 b(ends)g(with)g(a)h(ne)n(wline;)f(the)g (constructor)e(adds)i(a)h(ne)n(wline)e(when)h(necessary)-5 b(.)0 5333 y FD(want)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g (Python)h(e)n(xamples)1840 b(781)p eop end %%Page: 782 794 TeXDict begin 782 793 bop 208 83 a FN(The)29 b(e)o(xpected)g(output)g (from)g(running)f(the)i(e)o(xample')-5 b(s)29 b(source)h(code)f (\(either)h(from)f(stdout,)j(or)e(a)g(traceback)f(in)h(case)h(of)208 183 y(e)o(xception\).)40 b FJ(want)26 b FN(ends)g(with)g(a)h(ne)n (wline)e(unless)i(no)e(output)g(is)i(e)o(xpected,)f(in)h(which)e(case)i (it')-5 b(s)27 b(an)f(empty)f(string.)43 b(The)208 282 y(constructor)18 b(adds)i(a)g(ne)n(wline)g(when)f(necessary)-5 b(.)0 429 y FD(exc_msg)208 529 y FN(The)18 b(e)o(xception)f(message)i (generated)f(by)g(the)h(e)o(xample,)f(if)h(the)g(e)o(xample)f(is)i(e)o (xpected)d(to)j(generate)d(an)i(e)o(xception;)f(or)h FJ(None)208 628 y FN(if)29 b(it)h(is)g(not)f(e)o(xpected)e(to)j (generate)e(an)h(e)o(xception.)50 b(This)29 b(e)o(xception)e(message)i (is)h(compared)e(against)g(the)h(return)f(v)n(alue)208 728 y(of)h FJ(traceback.format_exception_only\(\))p FN(.)49 b FJ(exc_msg)29 b FN(ends)h(with)g(a)g(ne)n(wline)g(unless)g(it')-5 b(s)31 b FJ(None)p FN(.)54 b(The)208 828 y(constructor)18 b(adds)i(a)g(ne)n(wline)g(if)g(needed.)0 975 y FD(lineno)208 1074 y FN(The)30 b(line)h(number)e(within)i(the)g(string)f(containing)f (this)j(e)o(xample)d(where)i(the)g(e)o(xample)e(be)o(gins.)56 b(This)31 b(line)h(number)d(is)208 1174 y(zero-based)18 b(with)i(respect)g(to)g(the)h(be)o(ginning)c(of)j(the)g(containing)f (string.)0 1321 y FD(indent)208 1420 y FN(The)j(e)o(xample')-5 b(s)21 b(indentation)g(in)i(the)f(containing)f(string,)h(i.e.,)h(the)g (number)d(of)i(space)h(characters)e(that)i(precede)e(the)i(e)o(xam-)208 1520 y(ple')-5 b(s)20 b(\002rst)h(prompt.)0 1667 y FD(options)208 1766 y FN(A)i(dictionary)f(mapping)g(from)g(option)g(\003ags)i(to)f FJ(True)h FN(or)f FJ(False)p FN(,)g(which)g(is)h(used)g(to)f(o)o(v)o (erride)e(def)o(ault)i(options)f(for)h(this)208 1866 y(e)o(xample.)45 b(An)o(y)26 b(option)h(\003ags)g(not)g(contained)f(in) i(this)g(dictionary)d(are)j(left)f(at)h(their)f(def)o(ault)g(v)n(alue)g (\(as)g(speci\002ed)h(by)f(the)208 1966 y FJ(DocTestRunner)p FN(')-5 b(s)18 b FJ(optionflags)p FN(\).)23 b(By)e(def)o(ault,)e(no)h (options)f(are)h(set.)0 2234 y FI(DocT)-10 b(estFinder)22 b(objects)0 2423 y FL(class)f FD(DocTestFinder)p FJ(\()p FC([)p FK(verbose)12 b FC(][)p FK(,)k(par)o(ser)e FC(][)p FK(,)20 b(r)m(ecur)o(se)12 b FC(][)p FK(,)20 b(e)n(xclude)p 2302 2423 25 4 v 29 w(empty)12 b FC(])p FJ(\))208 2522 y FN(A)29 b(processing)e(class)j(used)e(to)h(e)o(xtract)f(the)g FJ(DocTest)p FN(s)h(that)f(are)h(rele)n(v)n(ant)e(to)i(a)g(gi)n(v)o(en) f(object,)i(from)d(its)j(docstring)d(and)208 2622 y(the)22 b(docstrings)g(of)h(its)g(contained)f(objects.)32 b FJ(DocTest)p FN(s)23 b(can)f(currently)f(be)i(e)o(xtracted)f(from)f(the)i(follo)n (wing)e(object)i(types:)208 2722 y(modules,)18 b(functions,)h(classes,) i(methods,)e(staticmethods,)g(classmethods,)g(and)h(properties.)208 2855 y(The)i(optional)f(ar)o(gument)f FK(verbose)i FN(can)g(be)h(used)f (to)g(display)g(the)g(objects)h(searched)e(by)h(the)g(\002nder)-5 b(.)32 b(It)22 b(def)o(aults)g(to)h FJ(False)208 2954 y FN(\(no)c(output\).)208 3087 y(The)h(optional)f(ar)o(gument)f FK(par)o(ser)23 b FN(speci\002es)e(the)f FJ(DocTestParser)f FN(object)h(\(or)g(a)g(drop-in)f(replacement\))f(that)j(is)g(used)f(to) 208 3187 y(e)o(xtract)f(doctests)h(from)f(docstrings.)208 3319 y(If)f(the)h(optional)f(ar)o(gument)e FK(r)m(ecur)o(se)k FN(is)f(f)o(alse,)h(then)e FJ(DocTestFinder.find\(\))e FN(will)j(only)f(e)o(xamine)g(the)h(gi)n(v)o(en)e(object,)208 3419 y(and)i(not)h(an)o(y)f(contained)g(objects.)208 3552 y(If)f(the)g(optional)f(ar)o(gument)f FK(e)n(xclude)p 1282 3552 V 29 w(empty)i FN(is)i(f)o(alse,)f(then)f FJ (DocTestFinder.find\(\))d FN(will)k(include)e(tests)j(for)e(objects)208 3652 y(with)i(empty)f(docstrings.)208 3784 y(Ne)n(w)h(in)g(v)o(ersion)f (2.4.)0 3931 y FJ(DocTestFinder)f FN(de\002nes)i(the)g(follo)n(wing)f (method:)0 4078 y FD(find)p FJ(\()p FK(obj)p FC([)p FK(,)f(name)12 b FC(][)p FK(,)19 b(module)12 b FC(][)p FK(,)19 b(globs)12 b FC(][)p FK(,)18 b(e)n(xtr)o(a)o(globs)12 b FC(])p FJ(\))208 4178 y FN(Return)18 b(a)h(list)h(of)e(the)h FJ(DocTest)p FN(s)f(that)h(are)f(de\002ned)g(by)g FK(obj)p FN(')-5 b(s)19 b(docstring,)e(or)i(by)f(an)o(y)g(of)g(its)i(contained)d (objects')h(docstrings.)208 4311 y(The)28 b(optional)g(ar)o(gument)f FK(name)i FN(speci\002es)h(the)f(object')-5 b(s)29 b(name;)34 b(this)29 b(name)g(will)h(be)f(used)g(to)h(construct)e(names)h(for)g (the)208 4410 y(returned)18 b FJ(DocTest)p FN(s.)24 b(If)c FK(name)g FN(is)h(not)f(speci\002ed,)g(then)f FK(obj)p FJ(.__name__)g FN(is)i(used.)208 4543 y(The)f(optional)g(parameter)f FK(module)h FN(is)i(the)f(module)e(that)i(contains)g(the)f(gi)n(v)o(en) g(object.)27 b(If)20 b(the)h(module)f(is)i(not)e(speci\002ed)h(or)g(is) 208 4643 y(None,)j(then)h(the)f(test)i(\002nder)e(will)h(attempt)f(to)h (automatically)e(determine)g(the)i(correct)f(module.)37 b(The)24 b(object')-5 b(s)24 b(module)g(is)208 4742 y(used:)349 4956 y FM(\017)o FN(As)d(a)g(def)o(ault)e(namespace,)g(if)h FK(globs)g FN(is)h(not)f(speci\002ed.)349 5088 y FM(\017)o FN(T)-7 b(o)16 b(pre)n(v)o(ent)e(the)i(DocT)-6 b(estFinder)14 b(from)h(e)o(xtracting)f(DocT)-6 b(ests)16 b(from)f(objects)h(that)f (are)h(imported)e(from)h(other)g(modules.)390 5188 y(\(Contained)k (objects)h(with)g(modules)f(other)h(than)f FK(module)h FN(are)g(ignored.\))349 5321 y FM(\017)o FN(T)-7 b(o)21 b(\002nd)e(the)i(name)e(of)h(the)g(\002le)h(containing)e(the)h(object.) p 0 5549 3901 4 v 0 5649 a FI(782)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 783 795 TeXDict begin 783 794 bop 349 83 a FM(\017)o FN(T)-7 b(o)21 b(help)e(\002nd)h(the)g(line)h(number)d(of)i(the)g(object)g (within)g(its)h(\002le.)208 289 y(If)28 b FK(module)g FN(is)h FJ(False)p FN(,)h(no)e(attempt)h(to)f(\002nd)h(the)f(module)g (will)h(be)f(made.)50 b(This)29 b(is)g(obscure,)g(of)g(use)g(mostly)f (in)h(testing)208 389 y(doctest)17 b(itself:)25 b(if)18 b FK(module)e FN(is)j FJ(False)p FN(,)f(or)f(is)i FJ(None)e FN(b)n(ut)h(cannot)f(be)g(found)f(automatically)-5 b(,)17 b(then)g(all)h(objects)g(are)f(considered)208 488 y(to)j(belong)f(to)h (the)g(\(non-e)o(xistent\))d(module,)i(so)i(all)f(contained)f(objects)h (will)h(\(recursi)n(v)o(ely\))c(be)k(searched)e(for)g(doctests.)208 617 y(The)j(globals)g(for)g(each)g FJ(DocTest)g FN(is)h(formed)e(by)h (combining)f FK(globs)h FN(and)g FK(e)n(xtr)o(a)o(globs)f FN(\(bindings)g(in)i FK(e)n(xtr)o(a)o(globs)f FN(o)o(v)o(erride)208 717 y(bindings)e(in)i FK(globs)p FN(\).)29 b(A)23 b(ne)n(w)e(shallo)n (w)h(cop)o(y)f(of)h(the)f(globals)h(dictionary)e(is)j(created)e(for)g (each)h FJ(DocTest)p FN(.)29 b(If)22 b FK(globs)f FN(is)i(not)208 817 y(speci\002ed,)h(then)f(it)i(def)o(aults)f(to)g(the)g(module')-5 b(s)p 1622 817 25 4 v 1652 817 V 82 w FK(dict)p 1807 817 V 1837 817 V 60 w FN(,)25 b(if)f(speci\002ed,)g(or)g FJ({})g FN(otherwise.)36 b(If)23 b FK(e)n(xtr)o(a)o(globs)h FN(is)h(not)e(speci\002ed,)208 916 y(then)c(it)i(def)o(aults)f(to)g FJ({})p FN(.)0 1181 y FI(DocT)-10 b(estP)m(arser)21 b(objects)0 1366 y FL(class)g FD(DocTestParser)p FJ(\(\))208 1466 y FN(A)d(processing)f(class)i(used)f(to)h(e)o(xtract)e(interacti)n(v)o (e)g(e)o(xamples)g(from)g(a)i(string,)f(and)g(use)g(them)g(to)g(create) g(a)h FJ(DocTest)e FN(object.)208 1566 y(Ne)n(w)j(in)g(v)o(ersion)f (2.4.)0 1712 y FJ(DocTestParser)f FN(de\002nes)i(the)g(follo)n(wing)f (methods:)0 1859 y FD(get_doctest)p FJ(\()p FK(string)o(,)f(globs,)i (name)o(,)f(\002lename)o(,)g(lineno)p FJ(\))208 1959 y FN(Extract)g(all)i(doctest)f(e)o(xamples)f(from)g(the)h(gi)n(v)o(en)f (string,)h(and)f(collect)i(them)e(into)h(a)h FJ(DocTest)e FN(object.)208 2088 y FK(globs)p FN(,)34 b FK(name)p FN(,)h FK(\002lename)p FN(,)f(and)e FK(lineno)g FN(are)g(attrib)n(utes) h(for)e(the)i(ne)n(w)f FJ(DocTest)g FN(object.)61 b(See)33 b(the)g(documentation)c(for)208 2188 y FJ(DocTest)19 b FN(for)h(more)f(information.)0 2335 y FD(get_examples)p FJ(\()p FK(string)p FC([)p FK(,)f(name)12 b FC(])p FJ(\))208 2434 y FN(Extract)18 b(all)i(doctest)f(e)o(xamples)g(from)f(the)h(gi)n (v)o(en)f(string,)h(and)g(return)f(them)h(as)i(a)e(list)i(of)e FJ(Example)g FN(objects.)24 b(Line)19 b(numbers)208 2534 y(are)h(0-based.)j(The)d(optional)f(ar)o(gument)f FK(name)i FN(is)h(a)f(name)g(identifying)e(this)j(string,)e(and)h(is)h(only)e (used)h(for)g(error)f(messages.)0 2681 y FD(parse)p FJ(\()p FK(string)p FC([)p FK(,)g(name)12 b FC(])p FJ(\))208 2780 y FN(Di)n(vide)23 b(the)h(gi)n(v)o(en)f(string)g(into)h(e)o (xamples)f(and)g(interv)o(ening)f(te)o(xt,)i(and)f(return)g(them)h(as)g (a)h(list)g(of)e(alternating)g FJ(Example)p FN(s)208 2880 y(and)f(strings.)34 b(Line)23 b(numbers)f(for)h(the)g FJ(Example)p FN(s)g(are)g(0-based.)33 b(The)23 b(optional)f(ar)o (gument)e FK(name)j FN(is)h(a)g(name)f(identifying)208 2980 y(this)d(string,)g(and)g(is)h(only)e(used)h(for)g(error)f (messages.)0 3245 y FI(DocT)-10 b(estRunner)22 b(objects)0 3430 y FL(class)f FD(DocTestRunner)p FJ(\()p FC([)p FK(c)o(hec)n(k)o (er)14 b FC(][)p FK(,)i(verbose)c FC(][)p FK(,)19 b(option\003a)o(gs)12 b FC(])p FJ(\))208 3529 y FN(A)20 b(processing)f(class)i(used)f(to)h(e) o(x)o(ecute)d(and)i(v)o(erify)f(the)h(interacti)n(v)o(e)f(e)o(xamples)g (in)h(a)h FJ(DocTest)p FN(.)208 3658 y(The)h(comparison)e(between)h(e)o (xpected)g(outputs)g(and)h(actual)g(outputs)g(is)h(done)e(by)h(an)g FJ(OutputChecker)p FN(.)30 b(This)22 b(compar)n(-)208 3758 y(ison)i(may)f(be)h(customized)f(with)h(a)g(number)f(of)g(option)g (\003ags;)k(see)d(section)g(23.2.3)e(for)i(more)f(information.)34 b(If)24 b(the)g(option)208 3858 y(\003ags)c(are)h(insuf)n(\002cient,)e (then)h(the)g(comparison)f(may)h(also)g(be)h(customized)e(by)h(passing) g(a)h(subclass)f(of)g FJ(OutputChecker)208 3957 y FN(to)g(the)g (constructor)-5 b(.)208 4086 y(The)30 b(test)i(runner')-5 b(s)29 b(display)i(output)e(can)i(be)g(controlled)e(in)i(tw)o(o)g(w)o (ays.)57 b(First,)35 b(an)30 b(output)g(function)f(can)i(be)g(passed)f (to)208 4186 y FJ(TestRunner.run\(\))p FN(;)41 b(this)c(function)e (will)i(be)f(called)g(with)g(strings)h(that)f(should)f(be)h(displayed.) 72 b(It)37 b(def)o(aults)e(to)208 4286 y FJ(sys.stdout.write)p FN(.)61 b(If)33 b(capturing)f(the)h(output)f(is)i(not)f(suf)n (\002cient,)i(then)e(the)g(display)g(output)f(can)h(be)g(also)h(cus-) 208 4385 y(tomized)24 b(by)i(subclassing)f(DocT)-6 b(estRunner)m(,)25 b(and)g(o)o(v)o(erriding)d(the)k(methods)f FJ(report_start)p FN(,)g FJ(report_success)p FN(,)208 4485 y FJ (report_unexpected_exception)p FN(,)15 b(and)20 b FJ(report_failure)p FN(.)208 4614 y(The)k(optional)f(k)o(e)o(yw)o(ord)f(ar)o(gument)g FK(c)o(hec)n(k)o(er)k FN(speci\002es)f(the)f FJ(OutputChecker)f FN(object)g(\(or)h(drop-in)e(replacement\))g(that)208 4714 y(should)d(be)h(used)g(to)g(compare)f(the)h(e)o(xpected)f(outputs) g(to)h(the)g(actual)g(outputs)g(of)f(doctest)h(e)o(xamples.)208 4843 y(The)h(optional)g(k)o(e)o(yw)o(ord)g(ar)o(gument)f FK(verbose)i FN(controls)f(the)h FJ(DocTestRunner)p FN(')-5 b(s)21 b(v)o(erbosity)-5 b(.)29 b(If)22 b FK(verbose)g FN(is)i FJ(True)p FN(,)e(then)208 4942 y(information)f(is)j(printed)e (about)h(each)g(e)o(xample,)f(as)i(it)h(is)f(run.)34 b(If)23 b FK(verbose)g FN(is)i FJ(False)p FN(,)e(then)g(only)g(f)o (ailures)g(are)g(printed.)34 b(If)208 5042 y FK(verbose)20 b FN(is)h(unspeci\002ed,)d(or)i FJ(None)p FN(,)g(then)g(v)o(erbose)e (output)h(is)i(used)f(if)n(f)g(the)h(command-line)c(switch)k FL(-v)e FN(is)j(used.)208 5171 y(The)16 b(optional)g(k)o(e)o(yw)o(ord)f (ar)o(gument)f FK(option\003a)o(gs)h FN(can)i(be)f(used)h(to)g(control) f(ho)n(w)g(the)h(test)h(runner)d(compares)h(e)o(xpected)f(output)208 5271 y(to)20 b(actual)g(output,)f(and)g(ho)n(w)h(it)h(displays)f(f)o (ailures.)k(F)o(or)c(more)g(information,)d(see)k(section)f(23.2.3.)208 5400 y(Ne)n(w)g(in)g(v)o(ersion)f(2.4.)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples)1840 b(783)p eop end %%Page: 784 796 TeXDict begin 784 795 bop 0 83 a FJ(DocTestParser)18 b FN(de\002nes)i(the)g(follo)n(wing)f(methods:)0 230 y FD(report_start)p FJ(\()p FK(out,)e(test,)k(e)n(xample)p FJ(\))208 330 y FN(Report)h(that)h(the)g(test)h(runner)d(is)j(about)e (to)h(process)f(the)h(gi)n(v)o(en)f(e)o(xample.)31 b(This)23 b(method)f(is)i(pro)o(vided)c(to)j(allo)n(w)g(subclasses)208 429 y(of)c FJ(DocTestRunner)g FN(to)h(customize)g(their)f(output;)h(it) g(should)g(not)f(be)i(called)f(directly)-5 b(.)208 562 y FK(e)n(xample)19 b FN(is)h(the)g(e)o(xample)e(about)g(to)i(be)f (processed.)24 b FK(test)e FN(is)e(the)g(test)g(containing)e FK(e)n(xample)p FN(.)24 b FK(out)c FN(is)h(the)e(output)g(function)e (that)208 662 y(w)o(as)k(passed)f(to)g FJ(DocTestRunner.run\(\))p FN(.)0 808 y FD(report_success)p FJ(\()p FK(out,)d(test,)k(e)n(xample)o (,)e(got)q FJ(\))208 908 y FN(Report)54 b(that)g(the)h(gi)n(v)o(en)e(e) o(xample)g(ran)h(successfully)-5 b(.)127 b(This)54 b(method)g(is)h(pro) o(vided)d(to)i(allo)n(w)h(subclasses)g(of)208 1008 y FJ(DocTestRunner)18 b FN(to)i(customize)g(their)g(output;)f(it)i (should)e(not)h(be)g(called)g(directly)-5 b(.)208 1141 y FK(e)n(xample)31 b FN(is)i(the)f(e)o(xample)f(about)g(to)h(be)g (processed.)60 b FK(got)33 b FN(is)g(the)f(actual)g(output)f(from)g (the)h(e)o(xample.)59 b FK(test)35 b FN(is)e(the)f(test)208 1240 y(containing)18 b FK(e)n(xample)p FN(.)24 b FK(out)e FN(is)f(the)f(output)f(function)f(that)j(w)o(as)g(passed)f(to)g FJ(DocTestRunner.run\(\))p FN(.)0 1387 y FD(report_failure)p FJ(\()p FK(out,)d(test,)k(e)n(xample)o(,)e(got)q FJ(\))208 1487 y FN(Report)27 b(that)h(the)g(gi)n(v)o(en)f(e)o(xample)g(f)o (ailed.)48 b(This)28 b(method)f(is)i(pro)o(vided)d(to)i(allo)n(w)g (subclasses)g(of)g FJ(DocTestRunner)e FN(to)208 1586 y(customize)19 b(their)h(output;)f(it)i(should)e(not)h(be)g(called)g (directly)-5 b(.)208 1719 y FK(e)n(xample)31 b FN(is)i(the)f(e)o (xample)f(about)g(to)h(be)g(processed.)60 b FK(got)33 b FN(is)g(the)f(actual)g(output)f(from)g(the)h(e)o(xample.)59 b FK(test)35 b FN(is)e(the)f(test)208 1819 y(containing)18 b FK(e)n(xample)p FN(.)24 b FK(out)e FN(is)f(the)f(output)f(function)f (that)j(w)o(as)g(passed)f(to)g FJ(DocTestRunner.run\(\))p FN(.)0 1966 y FD(report_unexpected_exception)p FJ(\()p FK(out,)14 b(test,)21 b(e)n(xample)o(,)f(e)n(xc)p 2129 1966 25 4 v 30 w(info)p FJ(\))208 2065 y FN(Report)h(that)i(the)f(gi)n (v)o(en)f(e)o(xample)g(raised)h(an)h(une)o(xpected)c(e)o(xception.)30 b(This)22 b(method)f(is)j(pro)o(vided)19 b(to)k(allo)n(w)f(subclasses)h (of)208 2165 y FJ(DocTestRunner)18 b FN(to)i(customize)g(their)g (output;)f(it)i(should)e(not)h(be)g(called)g(directly)-5 b(.)208 2298 y FK(e)n(xample)21 b FN(is)i(the)g(e)o(xample)d(about)i (to)g(be)g(processed.)30 b FK(e)n(xc)p 1900 2298 V 30 w(info)22 b FN(is)h(a)g(tuple)f(containing)e(information)g(about)h(the) h(une)o(xpected)208 2397 y(e)o(xception)f(\(as)j(returned)d(by)i FJ(sys.exc_info\(\))p FN(\).)32 b FK(test)25 b FN(is)g(the)e(test)h (containing)e FK(e)n(xample)p FN(.)33 b FK(out)25 b FN(is)f(the)f (output)f(function)208 2497 y(that)e(w)o(as)h(passed)f(to)g FJ(DocTestRunner.run\(\))p FN(.)0 2644 y FD(run)p FJ(\()p FK(test)q FC([)p FK(,)g(compile\003a)o(gs)12 b FC(][)p FK(,)18 b(out)13 b FC(][)p FK(,)20 b(clear)p 1366 2644 V 29 w(globs)12 b FC(])p FJ(\))208 2743 y FN(Run)20 b(the)g(e)o (xamples)f(in)h FK(test)j FN(\(a)d FJ(DocTest)g FN(object\),)f(and)g (display)h(the)g(results)h(using)e(the)i(writer)f(function)e FK(out)q FN(.)208 2876 y(The)h(e)o(xamples)g(are)h(run)g(in)g(the)g (namespace)f FJ(test.globs)p FN(.)k(If)d FK(clear)p 2332 2876 V 30 w(globs)f FN(is)i(true)f(\(the)g(def)o(ault\),)f(then)g(this) i(namespace)208 2976 y(will)h(be)f(cleared)g(after)g(the)g(test)i (runs,)e(to)h(help)e(with)i(garbage)e(collection.)27 b(If)22 b(you)e(w)o(ould)h(lik)o(e)h(to)f(e)o(xamine)f(the)i(namespace) 208 3076 y(after)d(the)i(test)g(completes,)e(then)h(use)g FK(clear)p 1488 3076 V 29 w(globs=F)-6 b(alse)p FN(.)208 3208 y FK(compile\003a)o(gs)22 b FN(gi)n(v)o(es)i(the)h(set)g(of)f (\003ags)h(that)f(should)g(be)g(used)g(by)g(the)g(Python)g(compiler)f (when)h(running)e(the)i(e)o(xamples.)37 b(If)208 3308 y(not)19 b(speci\002ed,)h(then)g(it)h(will)g(def)o(ault)e(to)h(the)h (set)g(of)f(future-import)d(\003ags)j(that)h(apply)e(to)h FK(globs)p FN(.)208 3441 y(The)j(output)f(of)i(each)f(e)o(xample)g(is)h (check)o(ed)f(using)g(the)h FJ(DocTestRunner)p FN(')-5 b(s)22 b(output)h(check)o(er)m(,)g(and)g(the)g(results)i(are)e(for)n(-) 208 3540 y(matted)c(by)h(the)g FJ(DocTestRunner.report_)1730 3555 y(*)1797 3540 y FN(methods.)0 3687 y FD(summarize)p FJ(\()p FC([)p FK(verbose)12 b FC(])p FJ(\))208 3787 y FN(Print)24 b(a)h(summary)f(of)g(all)h(the)g(test)g(cases)h(that)f (ha)n(v)o(e)f(been)g(run)g(by)g(this)h(DocT)-6 b(estRunner)m(,)24 b(and)g(return)f(a)i(tuple)g(`)p FJ(\()p FK(failur)m(e)p 3849 3787 V 28 w(-)208 3887 y(count)q FJ(,)48 b FK(test)p 613 3887 V 30 w(count)q FJ(\))p FN('.)208 4019 y(The)20 b(optional)g FK(verbose)h FN(ar)o(gument)e(controls)h(ho)n(w)h (detailed)f(the)i(summary)d(is.)29 b(If)21 b(the)g(v)o(erbosity)f(is)i (not)f(speci\002ed,)g(then)g(the)208 4119 y FJ(DocTestRunner)p FN(')-5 b(s)18 b(v)o(erbosity)h(is)i(used.)0 4387 y FI(OutputChec)n(k)n (er)i(objects)0 4576 y FL(class)e FD(OutputChecker)p FJ(\(\))208 4676 y FN(A)33 b(class)g(used)g(to)g(check)f(the)h(whether) e(the)i(actual)g(output)e(from)h(a)h(doctest)f(e)o(xample)g(matches)g (the)h(e)o(xpected)e(output.)208 4775 y FJ(OutputChecker)23 b FN(de\002nes)i(tw)o(o)h(methods:)34 b FJ(check_output)p FN(,)24 b(which)h(compares)f(a)i(gi)n(v)o(en)e(pair)h(of)g(outputs,)g (and)g(re-)208 4875 y(turns)16 b(true)g(if)h(the)o(y)f(match;)h(and)f FJ(output_difference)p FN(,)e(which)i(returns)g(a)h(string)f (describing)f(the)i(dif)n(ferences)d(between)208 4975 y(tw)o(o)20 b(outputs.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 5122 y FJ(OutputChecker)g FN(de\002nes)i(the)g(follo)n(wing)f(methods:) 0 5268 y FD(check_output)p FJ(\()p FK(want,)f(got,)h(option\003a)o(gs)p FJ(\))208 5368 y FN(Return)g FJ(True)h FN(if)n(f)g(the)g(actual)g (output)f(from)g(an)h(e)o(xample)f(\()p FK(got)q FN(\))h(matches)f(the) h(e)o(xpected)f(output)g(\()p FK(want)q FN(\).)25 b(These)20 b(strings)g(are)p 0 5549 3901 4 v 0 5649 a FI(784)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 785 797 TeXDict begin 785 796 bop 208 83 a FN(al)o(w)o(ays)26 b(considered)e(to)i(match)g(if)g(the)o(y)f(are)h(identical;)i(b)n(ut)e (depending)e(on)h(what)h(option)f(\003ags)h(the)g(test)h(runner)d(is)j (using,)208 183 y(se)n(v)o(eral)19 b(non-e)o(xact)f(match)i(types)g (are)g(also)g(possible.)25 b(See)c(section)e(23.2.3)g(for)g(more)h (information)e(about)h(option)g(\003ags.)0 330 y FD(output_difference)p FJ(\()p FK(e)n(xample)o(,)d(got,)k(option\003a)o(gs)p FJ(\))208 429 y FN(Return)j(a)i(string)f(describing)e(the)j(dif)n (ferences)d(between)h(the)i(e)o(xpected)d(output)h(for)h(a)g(gi)n(v)o (en)f(e)o(xample)g(\()p FK(e)n(xample)p FN(\))g(and)h(the)208 529 y(actual)c(output)f(\()p FK(got)q FN(\).)24 b FK(option\003a)o(gs) 18 b FN(is)j(the)f(set)h(of)f(option)f(\003ags)i(used)f(to)g(compare)f FK(want)i FN(and)f FK(got)q FN(.)0 814 y Fv(23.2.7)101 b(Deb)n(ugging)0 1017 y FN(Doctest)20 b(pro)o(vides)f(se)n(v)o(eral)g (mechanisms)h(for)f(deb)n(ugging)f(doctest)i(e)o(xamples:)125 1246 y FM(\017)41 b FN(Se)n(v)o(eral)17 b(functions)g(con)m(v)o(ert)f (doctests)i(to)g(e)o(x)o(ecutable)f(Python)g(programs,)f(which)i(can)g (be)g(run)f(under)g(the)h(Python)f(deb)n(ugger)m(,)208 1346 y FJ(pdb)p FN(.)125 1512 y FM(\017)41 b FN(The)18 b FJ(DebugRunner)f FN(class)i(is)h(a)f(subclass)f(of)h FJ(DocTestRunner)d FN(that)j(raises)g(an)f(e)o(xception)f(for)h(the)h (\002rst)g(f)o(ailing)f(e)o(xam-)208 1612 y(ple,)23 b(containing)f (information)f(about)h(that)i(e)o(xample.)33 b(This)23 b(information)e(can)j(be)f(used)g(to)h(perform)d(post-mortem)g(deb)n (ug-)208 1711 y(ging)e(on)h(the)g(e)o(xample.)125 1877 y FM(\017)41 b FN(The)54 b FJ(unittest)g FN(cases)i(generated)d(by)i FJ(DocTestSuite\(\))e FN(support)g(the)i FJ(debug\(\))f FN(method)g(de\002ned)g(by)208 1977 y FJ(unittest.TestCase)p FN(.)125 2143 y FM(\017)41 b FN(Y)-9 b(ou)26 b(can)h(add)g(a)h(call)f (to)h FJ(pdb.set_trace\(\))d FN(in)i(a)h(doctest)f(e)o(xample,)g(and)g (you')o(ll)f(drop)g(into)h(the)h(Python)e(deb)n(ugger)208 2243 y(when)c(that)g(line)h(is)g(e)o(x)o(ecuted.)30 b(Then)22 b(you)g(can)g(inspect)h(current)e(v)n(alues)h(of)g(v)n(ariables,)g(and) g(so)h(on.)32 b(F)o(or)22 b(e)o(xample,)g(suppose)208 2342 y(`)p FO(a.p)n(y)p FN(')d(contains)g(just)i(this)f(module)f (docstring:)444 2567 y FA(""")444 2658 y(>>>)44 b(def)g(f\(x\):)444 2749 y(...)223 b(g\(x)937 2762 y(*)982 2749 y(2\))444 2840 y(>>>)44 b(def)g(g\(x\):)444 2932 y(...)223 b(print)44 b(x+3)444 3023 y(...)223 b(import)44 b(pdb;)g(pdb.set_trace\(\))444 3114 y(>>>)g(f\(3\))444 3206 y(9)444 3297 y(""")208 3570 y FN(Then)19 b(an)h(interacti)n(v)o(e)f(Python)g(session)i(may)e(look)h (lik)o(e)g(this:)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g (Python)h(e)n(xamples)1840 b(785)p eop end %%Page: 786 798 TeXDict begin 786 797 bop 444 174 a FA(>>>)44 b(import)g(a,)g(doctest) 444 266 y(>>>)g(doctest.testmod\(a\))444 357 y(--Return--)444 448 y(>)g(<doctest)g(a[1]>\(3\)g\(\)->None)444 540 y(->)g(import)g (pdb;)g(pdb.set_trace\(\))444 631 y(\(Pdb\))g(list)533 722 y(1)224 b(def)45 b(g\(x\):)533 814 y(2)404 b(print)44 b(x+3)533 905 y(3)90 b(->)224 b(import)44 b(pdb;)g(pdb.set_trace\(\)) 444 996 y([EOF])444 1088 y(\(Pdb\))g(print)g(x)444 1179 y(6)444 1270 y(\(Pdb\))g(step)444 1362 y(--Return--)444 1453 y(>)g(<doctest)g(a[0]>\(2\)f\(\)->None)444 1544 y(->)g(g\(x)713 1557 y(*)758 1544 y(2\))444 1636 y(\(Pdb\))g(list)533 1727 y(1)224 b(def)45 b(f\(x\):)533 1818 y(2)90 b(->)224 b(g\(x)1117 1831 y(*)1162 1818 y(2\))444 1910 y([EOF])444 2001 y(\(Pdb\))44 b(print)g(x)444 2092 y(3)444 2183 y(\(Pdb\))g(step) 444 2275 y(--Return--)444 2366 y(>)g(<doctest)g(a[2]>\(1\)?\(\)->None) 444 2457 y(->)g(f\(3\))444 2549 y(\(Pdb\))g(cont)444 2640 y(\(0,)g(3\))444 2731 y(>>>)208 3004 y FN(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(The)h(ability)g(to)g(use)h FJ(pdb.set_trace\(\))d FN(usefully)h(inside)h(doctests)g(w)o(as)h (added.)0 3234 y(Functions)e(that)i(con)m(v)o(ert)d(doctests)i(to)g (Python)f(code,)h(and)f(possibly)h(run)f(the)h(synthesized)g(code)f (under)g(the)h(deb)n(ugger:)0 3381 y FD(script_from_examples)p FJ(\()p FK(s)p FJ(\))208 3480 y FN(Con)m(v)o(ert)e(te)o(xt)i(with)h(e)o (xamples)e(to)h(a)h(script.)208 3613 y(Ar)o(gument)h FK(s)k FN(is)g(a)f(string)g(containing)e(doctest)h(e)o(xamples.)38 b(The)25 b(string)f(is)i(con)m(v)o(erted)d(to)i(a)g(Python)f(script,)i (where)e(doctest)208 3713 y(e)o(xamples)14 b(in)j FK(s)g FN(are)e(con)m(v)o(erted)f(to)i(re)o(gular)e(code,)i(and)g(e)n(v)o (erything)d(else)k(is)g(con)m(v)o(erted)c(to)j(Python)f(comments.)23 b(The)15 b(generated)208 3812 y(script)20 b(is)h(returned)d(as)j(a)g (string.)j(F)o(or)c(e)o(xample,)623 4037 y FA(import)44 b(doctest)623 4128 y(print)g(doctest.script_from_examples\(r""")802 4219 y(Set)h(x)f(and)h(y)f(to)h(1)g(and)f(2.)802 4311 y(>>>)h(x,)f(y)h(=)g(1,)f(2)802 4493 y(Print)g(their)g(sum:)802 4584 y(>>>)h(print)f(x+y)802 4676 y(3)623 4767 y("""\))208 5048 y FN(displays:)p 0 5549 3901 4 v 0 5649 a FI(786)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 787 799 TeXDict begin 787 798 bop 623 174 a FA(#)45 b(Set)f(x)h(and)f(y)h(to)f (1)h(and)f(2.)623 266 y(x,)h(y)f(=)h(1,)f(2)623 357 y(#)623 448 y(#)h(Print)f(their)g(sum:)623 540 y(print)g(x+y)623 631 y(#)h(Expected:)623 722 y(##)g(3)208 1003 y FN(This)15 b(function)f(is)j(used)e(internally)g(by)g(other)g(functions)f(\(see)i (belo)n(w\),)g(b)n(ut)f(can)h(also)g(be)g(useful)f(when)g(you)g(w)o (ant)g(to)h(transform)208 1103 y(an)k(interacti)n(v)o(e)f(Python)g (session)h(into)g(a)h(Python)e(script.)208 1236 y(Ne)n(w)h(in)g(v)o (ersion)f(2.4.)0 1382 y FD(testsource)p FJ(\()p FK(module)o(,)e(name)p FJ(\))208 1482 y FN(Con)m(v)o(ert)h(the)i(doctest)g(for)g(an)g(object)g (to)g(a)h(script.)208 1615 y(Ar)o(gument)e FK(module)j FN(is)h(a)f(module)f(object,)h(or)g(dotted)f(name)h(of)g(a)g(module,)f (containing)g(the)h(object)g(whose)f(doctests)i(are)f(of)208 1714 y(interest.)29 b(Ar)o(gument)20 b FK(name)h FN(is)i(the)f(name)f (\(within)g(the)h(module\))e(of)i(the)g(object)f(with)h(the)g(doctests) g(of)f(interest.)30 b(The)22 b(result)208 1814 y(is)j(a)f(string,)h (containing)e(the)h(object')-5 b(s)24 b(docstring)f(con)m(v)o(erted)e (to)k(a)g(Python)e(script,)i(as)g(described)e(for)g FJ(script_from_-) 208 1914 y(examples\(\))18 b FN(abo)o(v)o(e.)24 b(F)o(or)c(e)o(xample,) e(if)j(module)d(`)p FO(a.p)n(y)p FN(')h(contains)h(a)g(top-le)n(v)o(el) f(function)g FJ(f\(\))p FN(,)g(then)444 2047 y FA(import)44 b(a,)g(doctest)444 2138 y(print)g(doctest.testsource\(a,)d("a.f"\))208 2327 y FN(prints)31 b(a)h(script)g(v)o(ersion)f(of)g(function)f FJ(f\(\))p FN(')-5 b(s)32 b(docstring,)h(with)f(doctests)g(con)m(v)o (erted)d(to)j(code,)i(and)d(the)h(rest)g(placed)f(in)208 2427 y(comments.)208 2560 y(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 2707 y FD(debug)p FJ(\()p FK(module)o(,)f(name)p FC([)p FK(,)h(pm)12 b FC(])p FJ(\))208 2806 y FN(Deb)n(ug)19 b(the)h(doctests)g(for)g(an)g(object.)208 2939 y(The)e FK(module)f FN(and)h FK(name)g FN(ar)o(guments)f(are)h(the)h(same)f(as) i(for)e(function)e FJ(testsource\(\))h FN(abo)o(v)o(e.)23 b(The)18 b(synthesized)g(Python)208 3039 y(script)23 b(for)f(the)i(named)e(object')-5 b(s)23 b(docstring)e(is)k(written)d (to)i(a)f(temporary)e(\002le,)k(and)d(then)h(that)g(\002le)h(is)g(run)f (under)f(the)h(control)208 3138 y(of)c(the)i(Python)e(deb)n(ugger)m(,)e FJ(pdb)p FN(.)208 3271 y(A)j(shallo)n(w)g(cop)o(y)g(of)f FK(module)p FJ(.__dict__)f FN(is)j(used)f(for)g(both)f(local)h(and)g (global)f(e)o(x)o(ecution)f(conte)o(xt.)208 3404 y(Optional)23 b(ar)o(gument)e FK(pm)j FN(controls)f(whether)g(post-mortem)e(deb)n (ugging)h(is)i(used.)36 b(If)24 b FK(pm)g FN(has)g(a)g(true)f(v)n (alue,)h(the)g(script)g(\002le)208 3504 y(is)f(run)e(directly)-5 b(,)21 b(and)h(the)g(deb)n(ugger)e(gets)i(in)m(v)n(olv)o(ed)e(only)i (if)g(the)g(script)h(terminates)e(via)h(raising)g(an)g(unhandled)e(e)o (xception.)208 3603 y(If)k(it)g(does,)h(then)f(post-mortem)e(deb)n (ugging)f(is)k(in)m(v)n(ok)o(ed,)e(via)h FJ(pdb.post_mortem\(\))p FN(,)f(passing)g(the)h(traceback)f(object)208 3703 y(from)f(the)h (unhandled)e(e)o(xception.)33 b(If)23 b FK(pm)h FN(is)g(not)f (speci\002ed,)h(or)f(is)i(f)o(alse,)f(the)g(script)f(is)i(run)d(under)g (the)i(deb)n(ugger)d(from)i(the)208 3803 y(start,)d(via)g(passing)g(an) g(appropriate)e FJ(execfile\(\))h FN(call)i(to)f FJ(pdb.run\(\))p FN(.)208 3935 y(Ne)n(w)g(in)g(v)o(ersion)f(2.3.)208 4068 y(Changed)f(in)j(v)o(ersion)e(2.4:)g(The)h FK(pm)g FN(ar)o(gument)e(w)o (as)j(added.)0 4215 y FD(debug_src)p FJ(\()p FK(sr)m(c)p FC([)p FK(,)e(pm)12 b FC(][)p FK(,)19 b(globs)12 b FC(])p FJ(\))208 4315 y FN(Deb)n(ug)19 b(the)h(doctests)g(in)h(a)f(string.)208 4448 y(This)g(is)i(lik)o(e)f(function)e FJ(debug\(\))g FN(abo)o(v)o(e,)g(e)o(xcept)h(that)h(a)g(string)f(containing)f(doctest) h(e)o(xamples)f(is)j(speci\002ed)e(directly)-5 b(,)20 b(via)208 4547 y(the)g FK(sr)m(c)h FN(ar)o(gument.)208 4680 y(Optional)e(ar)o(gument)f FK(pm)i FN(has)g(the)h(same)f(meaning)f (as)i(in)f(function)e FJ(debug\(\))i FN(abo)o(v)o(e.)208 4813 y(Optional)i(ar)o(gument)f FK(globs)j FN(gi)n(v)o(es)f(a)h (dictionary)d(to)j(use)g(as)g(both)f(local)g(and)h(global)e(e)o(x)o (ecution)g(conte)o(xt.)33 b(If)24 b(not)f(speci\002ed,)208 4913 y(or)c FJ(None)p FN(,)h(an)g(empty)g(dictionary)e(is)j(used.)k(If) 20 b(speci\002ed,)g(a)g(shallo)n(w)g(cop)o(y)f(of)h(the)h(dictionary)d (is)j(used.)208 5045 y(Ne)n(w)f(in)g(v)o(ersion)f(2.4.)0 5192 y(The)i FJ(DebugRunner)g FN(class,)h(and)g(the)f(special)h(e)o (xceptions)e(it)j(may)e(raise,)h(are)g(of)f(most)h(interest)g(to)g (testing)f(frame)n(w)o(ork)f(authors,)0 5292 y(and)h(will)h(only)e(be)h (sk)o(etched)g(here.)28 b(See)21 b(the)h(source)e(code,)h(and)f (especially)h FJ(DebugRunner)p FN(')-5 b(s)20 b(docstring)g(\(which)h (is)h(a)g(doctest!\))0 5391 y(for)e(more)f(details:)p 0 5549 3901 4 v 0 5649 a FI(23.2.)52 b FJ(doctest)22 b FI(\227)h(T)-10 b(est)23 b(inter)o(activ)n(e)g(Python)h(e)n(xamples) 1840 b(787)p eop end %%Page: 788 800 TeXDict begin 788 799 bop 0 83 a FL(class)21 b FD(DebugRunner)p FJ(\()p FC([)p FK(c)o(hec)n(k)o(er)14 b FC(][)p FK(,)j(verbose)12 b FC(][)p FK(,)19 b(option\003a)o(gs)12 b FC(])p FJ(\))208 183 y FN(A)22 b(subclass)g(of)f FJ(DocTestRunner)f FN(that)h(raises)i (an)e(e)o(xception)f(as)i(soon)f(as)i(a)f(f)o(ailure)f(is)i (encountered.)j(If)c(an)f(une)o(xpected)208 282 y(e)o(xception)f (occurs,)i(an)g FJ(UnexpectedException)e FN(e)o(xception)g(is)k (raised,)e(containing)f(the)h(test,)i(the)e(e)o(xample,)g(and)g(the)208 382 y(original)f(e)o(xception.)29 b(If)22 b(the)h(output)e(doesn')o(t)g (match,)h(then)g(a)h FJ(DocTestFailure)d FN(e)o(xception)g(is)k (raised,)e(containing)f(the)208 482 y(test,)f(the)h(e)o(xample,)d(and)i (the)g(actual)g(output.)208 614 y(F)o(or)j(information)f(about)h(the)h (constructor)e(parameters)h(and)g(methods,)h(see)g(the)g(documentation) d(for)i FJ(DocTestRunner)208 714 y FN(in)d(section)g(23.2.6.)0 861 y(There)f(are)h(tw)o(o)h(e)o(xceptions)e(that)h(may)g(be)g(raised)g (by)f FJ(DebugRunner)g FN(instances:)0 1008 y FL(exception)g FD(DocTestFailure)p FJ(\()p FK(test,)f(e)n(xample)o(,)i(got)q FJ(\))208 1107 y FN(An)k(e)o(xception)f(thro)n(wn)h(by)g FJ(DocTestRunner)f FN(to)i(signal)g(that)g(a)g(doctest)g(e)o(xample')-5 b(s)24 b(actual)h(output)e(did)i(not)f(match)h(its)208 1207 y(e)o(xpected)18 b(output.)24 b(The)c(constructor)e(ar)o(guments)g (are)i(used)g(to)g(initialize)h(the)f(member)f(v)n(ariables)g(of)h(the) g(same)h(names.)0 1354 y FJ(DocTestFailure)d FN(de\002nes)i(the)g (follo)n(wing)f(member)g(v)n(ariables:)0 1453 y FD(test)208 1553 y FN(The)g FJ(DocTest)h FN(object)g(that)g(w)o(as)h(being)e(run)g (when)h(the)g(e)o(xample)f(f)o(ailed.)0 1700 y FD(example)208 1799 y FN(The)g FJ(Example)h FN(that)g(f)o(ailed.)0 1946 y FD(got)208 2046 y FN(The)f(e)o(xample')-5 b(s)20 b(actual)g(output.)0 2193 y FL(exception)f FD(UnexpectedException)p FJ(\()p FK(test,)e(e)n(xample)o(,)j(e)n(xc)p 1940 2193 25 4 v 30 w(info)p FJ(\))208 2292 y FN(An)25 b(e)o(xception)f(thro)n(wn)h(by)h FJ(DocTestRunner)e FN(to)i(signal)f(that)h(a)h(doctest)e(e)o(xample)g (raised)h(an)f(une)o(xpected)f(e)o(xception.)208 2392 y(The)19 b(constructor)g(ar)o(guments)f(are)i(used)g(to)g(initialize)h (the)f(member)f(v)n(ariables)g(of)h(the)g(same)g(names.)0 2539 y FJ(UnexpectedException)d FN(de\002nes)j(the)g(follo)n(wing)f (member)g(v)n(ariables:)0 2639 y FD(test)208 2738 y FN(The)g FJ(DocTest)h FN(object)g(that)g(w)o(as)h(being)e(run)g(when)h(the)g(e)o (xample)f(f)o(ailed.)0 2885 y FD(example)208 2985 y FN(The)g FJ(Example)h FN(that)g(f)o(ailed.)0 3132 y FD(exc_info)208 3231 y FN(A)g(tuple)g(containing)e(information)g(about)h(the)i(une)o (xpected)c(e)o(xception,)h(as)j(returned)d(by)i FJ(sys.exc_info\(\))p FN(.)0 3516 y Fv(23.2.8)101 b(Soapbo)m(x)0 3719 y FN(As)21 b(mentioned)d(in)j(the)f(introduction,)d FJ(doctest)j FN(has)g(gro)n(wn)f(to)h(ha)n(v)o(e)g(three)g(primary)e(uses:)104 3948 y(1.)41 b(Checking)19 b(e)o(xamples)g(in)h(docstrings.)104 4114 y(2.)41 b(Re)o(gression)19 b(testing.)104 4279 y(3.)41 b(Ex)o(ecutable)18 b(documentation)f(/)k(literate)f(testing.)0 4509 y(These)k(uses)h(ha)n(v)o(e)e(dif)n(ferent)g(requirements,)g(and)g (it)i(is)g(important)e(to)h(distinguish)f(them.)37 b(In)23 b(particular)m(,)h(\002lling)g(your)f(docstrings)0 4608 y(with)d(obscure)f(test)i(cases)g(mak)o(es)f(for)g(bad)g (documentation.)0 4755 y(When)26 b(writing)g(a)h(docstring,)g(choose)e (docstring)h(e)o(xamples)f(with)i(care.)43 b(There')-5 b(s)27 b(an)f(art)h(to)f(this)i(that)e(needs)g(to)h(be)f(learned\227it) 0 4855 y(may)d(not)f(be)i(natural)e(at)h(\002rst.)35 b(Examples)22 b(should)g(add)h(genuine)e(v)n(alue)i(to)g(the)g (documentation.)31 b(A)24 b(good)e(e)o(xample)f(can)i(often)g(be)0 4954 y(w)o(orth)h(man)o(y)g(w)o(ords.)39 b(If)25 b(done)f(with)i(care,) f(the)g(e)o(xamples)f(will)i(be)f(in)m(v)n(aluable)e(for)i(your)e (users,)j(and)f(will)h(pay)e(back)h(the)g(time)g(it)0 5054 y(tak)o(es)d(to)f(collect)h(them)f(man)o(y)f(times)i(o)o(v)o(er)e (as)j(the)e(years)g(go)g(by)g(and)g(things)g(change.)28 b(I'm)21 b(still)i(amazed)d(at)i(ho)n(w)f(often)g(one)g(of)g(my)0 5154 y FJ(doctest)e FN(e)o(xamples)h(stops)g(w)o(orking)f(after)g(a)i (\224harmless\224)f(change.)0 5300 y(Doctest)29 b(also)f(mak)o(es)h(an) f(e)o(xcellent)g(tool)g(for)g(re)o(gression)f(testing,)j(especially)e (if)h(you)f(don')o(t)f(skimp)h(on)g(e)o(xplanatory)d(te)o(xt.)50 b(By)0 5400 y(interlea)n(ving)17 b(prose)h(and)f(e)o(xamples,)h(it)h (becomes)e(much)h(easier)g(to)h(k)o(eep)e(track)h(of)g(what')-5 b(s)19 b(actually)f(being)f(tested,)i(and)f(why)-5 b(.)23 b(When)p 0 5549 3901 4 v 0 5649 a FI(788)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 789 801 TeXDict begin 789 800 bop 0 83 a FN(a)27 b(test)g(f)o(ails,)i(good)c (prose)h(can)g(mak)o(e)g(it)h(much)f(easier)g(to)h(\002gure)f(out)g (what)g(the)h(problem)d(is,)29 b(and)d(ho)n(w)g(it)h(should)e(be)i (\002x)o(ed.)43 b(It')-5 b(s)0 183 y(true)22 b(that)g(you)g(could)f (write)i(e)o(xtensi)n(v)o(e)d(comments)i(in)g(code-based)e(testing,)j (b)n(ut)f(fe)n(w)h(programmers)c(do.)31 b(Man)o(y)21 b(ha)n(v)o(e)h(found)e(that)0 282 y(using)26 b(doctest)g(approaches)e (instead)j(leads)f(to)h(much)e(clearer)h(tests.)45 b(Perhaps)26 b(this)h(is)g(simply)f(because)g(doctest)g(mak)o(es)g(writing)0 382 y(prose)18 b(a)i(little)g(easier)f(than)f(writing)h(code,)f(while)h (writing)g(comments)e(in)j(code)e(is)i(a)f(little)h(harder)-5 b(.)24 b(I)19 b(think)f(it)i(goes)f(deeper)e(than)i(just)0 482 y(that:)25 b(the)20 b(natural)g(attitude)f(when)h(writing)f(a)i (doctest-based)e(test)i(is)g(that)f(you)f(w)o(ant)h(to)h(e)o(xplain)d (the)j(\002ne)f(points)g(of)f(your)g(softw)o(are,)0 581 y(and)25 b(illustrate)h(them)f(with)h(e)o(xamples.)40 b(This)26 b(in)g(turn)f(naturally)f(leads)i(to)g(test)h(\002les)f(that) g(start)g(with)g(the)g(simplest)g(features,)g(and)0 681 y(logically)16 b(progress)h(to)g(complications)f(and)h(edge)f(cases.)25 b(A)18 b(coherent)e(narrati)n(v)o(e)f(is)j(the)g(result,)f(instead)h (of)f(a)g(collection)g(of)g(isolated)0 780 y(functions)22 b(that)i(test)h(isolated)f(bits)g(of)g(functionality)d(seemingly)i(at)i (random.)34 b(It')-5 b(s)24 b(a)g(dif)n(ferent)f(attitude,)h(and)f (produces)f(dif)n(ferent)0 880 y(results,)e(blurring)f(the)h (distinction)f(between)g(testing)i(and)e(e)o(xplaining.)0 1027 y(Re)o(gression)g(testing)i(is)g(best)f(con\002ned)f(to)h (dedicated)f(objects)h(or)g(\002les.)26 b(There)19 b(are)h(se)n(v)o (eral)g(options)f(for)h(or)o(ganizing)d(tests:)125 1253 y FM(\017)41 b FN(Write)g(te)o(xt)g(\002les)h(containing)d(test)j (cases)g(as)g(interacti)n(v)o(e)d(e)o(xamples,)45 b(and)c(test)h(the)f (\002les)h(using)e FJ(testfile\(\))g FN(or)208 1353 y FJ(DocFileSuite\(\))p FN(.)58 b(This)32 b(is)h(recommended,)f(although) e(is)j(easiest)g(to)f(do)f(for)h(ne)n(w)g(projects,)i(designed)d(from)g (the)208 1452 y(start)20 b(to)h(use)f(doctest.)125 1617 y FM(\017)41 b FN(De\002ne)27 b(functions)f(named)h FJ(_regrtest_)p Fn(topic)f FN(that)i(consist)g(of)f(single)h(docstrings,)g(containing)e (test)i(cases)h(for)e(the)208 1716 y(named)21 b(topics.)33 b(These)23 b(functions)e(can)i(be)f(included)g(in)h(the)g(same)g (\002le)g(as)h(the)e(module,)g(or)h(separated)f(out)g(into)h(a)g (separate)208 1816 y(test)e(\002le.)125 1980 y FM(\017)41 b FN(De\002ne)20 b(a)g FJ(__test__)g FN(dictionary)e(mapping)g(from)h (re)o(gression)g(test)i(topics)f(to)h(docstrings)e(containing)f(test)j (cases.)0 2386 y FE(23.3)121 b Fx(unittest)31 b FE(\227)i(Unit)h (testing)g(fr)o(ame)n(w)o(or)r(k)0 2619 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 2766 y(The)f(Python)g(unit)g(testing)g (frame)n(w)o(ork,)f(sometimes)h(referred)f(to)i(as)g(\223PyUnit,)-6 b(\224)18 b(is)i(a)f(Python)e(language)g(v)o(ersion)g(of)h(JUnit,)i(by) e(K)n(ent)0 2866 y(Beck)k(and)g(Erich)g(Gamma.)30 b(JUnit)23 b(is,)g(in)g(turn,)f(a)g(Ja)n(v)n(a)h(v)o(ersion)e(of)h(K)n(ent')-5 b(s)22 b(Smalltalk)g(testing)h(frame)n(w)o(ork.)29 b(Each)21 b(is)i(the)g(de)f(f)o(acto)0 2965 y(standard)d(unit)h(testing)g(frame)n (w)o(ork)e(for)i(its)h(respecti)n(v)o(e)e(language.)0 3112 y FJ(unittest)k FN(supports)g(test)i(automation,)e(sharing)g(of)h (setup)g(and)g(shutdo)n(wn)e(code)i(for)f(tests,)j(aggre)o(gation)21 b(of)j(tests)h(into)f(collec-)0 3212 y(tions,)30 b(and)e(independence)d (of)k(the)f(tests)h(from)f(the)g(reporting)f(frame)n(w)o(ork.)47 b(The)28 b FJ(unittest)f FN(module)g(pro)o(vides)g(classes)i(that)0 3311 y(mak)o(e)20 b(it)h(easy)f(to)g(support)f(these)h(qualities)h(for) e(a)i(set)g(of)f(tests.)0 3458 y(T)-7 b(o)20 b(achie)n(v)o(e)f(this,)i FJ(unittest)e FN(supports)g(some)h(important)f(concepts:)0 3684 y FL(test)h(\002xtur)o(e)208 3784 y FN(A)g FK(test)g(\002xtur)m(e) g FN(represents)e(the)i(preparation)e(needed)g(to)i(perform)d(one)j(or) f(more)g(tests,)i(and)e(an)o(y)g(associate)h(cleanup)e(actions.)208 3883 y(This)i(may)g(in)m(v)n(olv)o(e,)e(for)i(e)o(xample,)e(creating)h (temporary)f(or)i(proxy)f(databases,)g(directories,)g(or)h(starting)g (a)h(serv)o(er)e(process.)0 4048 y FL(test)h(case)208 4148 y FN(A)35 b FK(test)g(case)g FN(is)h(the)f(smallest)g(unit)g(of)f (testing.)69 b(It)35 b(checks)f(for)h(a)g(speci\002c)g(response)f(to)g (a)i(particular)d(set)j(of)e(inputs.)208 4247 y FJ(unittest)19 b FN(pro)o(vides)f(a)j(base)f(class,)h FJ(TestCase)p FN(,)e(which)h(may)f(be)i(used)f(to)g(create)g(ne)n(w)g(test)h(cases.)0 4412 y FL(test)f(suite)208 4511 y FN(A)h FK(test)i(suite)e FN(is)i(a)e(collection)g(of)g(test)h(cases,)g(test)g(suites,)g(or)f (both.)28 b(It)21 b(is)i(used)e(to)g(aggre)o(gate)e(tests)j(that)g (should)e(be)h(e)o(x)o(ecuted)208 4611 y(together)-5 b(.)0 4775 y FL(test)20 b(runner)208 4875 y FN(A)26 b FK(test)h(runner)f FN(is)h(a)f(component)e(which)h(orchestrates)h(the)g (e)o(x)o(ecution)e(of)h(tests)j(and)d(pro)o(vides)f(the)j(outcome)d(to) i(the)g(user)-5 b(.)208 4975 y(The)22 b(runner)e(may)i(use)h(a)g (graphical)e(interf)o(ace,)g(a)i(te)o(xtual)f(interf)o(ace,)g(or)g (return)f(a)i(special)g(v)n(alue)e(to)i(indicate)f(the)g(results)h(of) 208 5074 y(e)o(x)o(ecuting)18 b(the)i(tests.)0 5300 y(The)g(test)h (case)g(and)e(test)i(\002xture)f(concepts)f(are)h(supported)e(through)g (the)j FJ(TestCase)e FN(and)g FJ(FunctionTestCase)f FN(classes;)k(the)0 5400 y(former)j(should)g(be)h(used)h(when)e(creating)h(ne)n(w)g(tests,) j(and)c(the)i(latter)f(can)g(be)h(used)f(when)g(inte)o(grating)e(e)o (xisting)i(test)h(code)e(with)p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o(ame)n (w)o(or)q(k)2175 b(789)p eop end %%Page: 790 802 TeXDict begin 790 801 bop 0 83 a FN(a)27 b FJ(unittest)p FN(-dri)n(v)o(en)c(frame)n(w)o(ork.)41 b(When)26 b(b)n(uilding)f(test)i (\002xtures)f(using)g FJ(TestCase)p FN(,)g(the)h FJ(setUp\(\))e FN(and)h FJ(tearDown\(\))0 183 y FN(methods)18 b(can)g(be)h(o)o(v)o (erridden)c(to)k(pro)o(vide)d(initialization)i(and)g(cleanup)g(for)g (the)g(\002xture.)24 b(W)m(ith)19 b FJ(FunctionTestCase)p FN(,)d(e)o(xisting)0 282 y(functions)h(can)i(be)g(passed)g(to)g(the)g (constructor)e(for)h(these)h(purposes.)k(When)c(the)g(test)h(is)f(run,) f(the)h(\002xture)g(initialization)f(is)i(run)e(\002rst;)0 382 y(if)23 b(it)g(succeeds,)g(the)g(cleanup)e(method)g(is)j(run)e (after)g(the)h(test)g(has)g(been)f(e)o(x)o(ecuted,)f(re)o(gardless)h (of)g(the)h(outcome)e(of)h(the)h(test.)33 b(Each)0 482 y(instance)20 b(of)g(the)g FJ(TestCase)f FN(will)i(only)e(be)i(used)f (to)g(run)f(a)i(single)f(test)h(method,)e(so)h(a)h(ne)n(w)f(\002xture)f (is)j(created)d(for)h(each)f(test.)0 628 y(T)-6 b(est)24 b(suites)g(are)f(implemented)e(by)i(the)g FJ(TestSuite)f FN(class.)35 b(This)24 b(class)g(allo)n(ws)f(indi)n(vidual)f(tests)i (and)f(test)h(suites)f(to)h(be)f(aggre-)0 728 y(gated;)c(when)h(the)g (suite)h(is)g(e)o(x)o(ecuted,)d(all)j(tests)g(added)e(directly)g(to)i (the)f(suite)g(and)g(in)g(\223child\224)g(test)h(suites)g(are)f(run.)0 875 y(A)c(test)h(runner)d(is)j(an)f(object)g(that)g(pro)o(vides)e(a)i (single)g(method,)f FJ(run\(\))p FN(,)h(which)g(accepts)g(a)g FJ(TestCase)f FN(or)h FJ(TestSuite)e FN(object)i(as)0 975 y(a)21 b(parameter)m(,)e(and)h(returns)g(a)h(result)g(object.)26 b(The)20 b(class)i FJ(TestResult)e FN(is)h(pro)o(vided)d(for)i(use)h (as)h(the)f(result)f(object.)26 b FJ(unittest)0 1074 y FN(pro)o(vides)19 b(the)h FJ(TextTestRunner)f FN(as)i(an)g(e)o (xample)e(test)j(runner)c(which)j(reports)e(test)j(results)f(on)f(the)h (standard)e(error)g(stream)i(by)0 1174 y(def)o(ault.)33 b(Alternate)22 b(runners)g(can)h(be)g(implemented)e(for)i(other)f(en)m (vironments)e(\(such)j(as)g(graphical)f(en)m(vironments\))e(without)i (an)o(y)0 1273 y(need)e(to)g(deri)n(v)o(e)f(from)g(a)i(speci\002c)f (class.)0 1420 y FL(See)h(Also:)0 1567 y FN(Module)e FJ(doctest)g FN(\(section)h(23.2\):)208 1667 y(Another)e(test-support)h (module)g(with)h(a)h(v)o(ery)e(dif)n(ferent)g(\003a)n(v)n(or)-5 b(.)0 1814 y FK(Simple)20 b(Smalltalk)f(T)-8 b(esting:)25 b(W)-5 b(ith)21 b(P)-7 b(atterns)0 1913 y Fy(\()p FO(http://www)l (.XProg)o(r)o(amming.com/testfr)n(am.htm)h Fy(\))208 2013 y FN(K)n(ent)20 b(Beck')-5 b(s)20 b(original)f(paper)h(on)f (testing)h(frame)n(w)o(orks)f(using)h(the)g(pattern)f(shared)g(by)h FJ(unittest)p FN(.)0 2298 y Fv(23.3.1)101 b(Basic)28 b(e)m(xample)0 2501 y FN(The)19 b FJ(unittest)g FN(module)g(pro)o (vides)f(a)i(rich)f(set)i(of)e(tools)h(for)f(constructing)f(and)h (running)f(tests.)26 b(This)20 b(section)f(demonstrates)f(that)0 2600 y(a)j(small)f(subset)h(of)e(the)i(tools)f(suf)n(\002ce)g(to)g (meet)g(the)h(needs)e(of)h(most)h(users.)0 2747 y(Here)f(is)h(a)g (short)f(script)g(to)g(test)h(three)f(functions)f(from)g(the)h FJ(random)g FN(module:)236 2985 y FA(import)44 b(random)236 3077 y(import)g(unittest)236 3259 y(class)g (TestSequenceFunctions\(unittest.TestCase\))o(:)416 3442 y(def)g(setUp\(self\):)595 3533 y(self.seq)f(=)i(range\(10\))416 3716 y(def)f(testshuffle\(self\):)595 3807 y(#)h(make)f(sure)g(the)g (shuffled)g(sequence)f(does)h(not)h(lose)f(any)g(elements)595 3899 y(random.shuffle\(self.seq\))595 3990 y(self.seq.sort\(\))595 4081 y(self.assertEqual\(self.seq,)c(range\(10\)\))416 4264 y(def)k(testchoice\(self\):)595 4355 y(element)g(=)g (random.choice\(self.seq\))595 4447 y(self.assert_\(element)d(in)k (self.seq\))416 4629 y(def)f(testsample\(self\):)595 4721 y(self.assertRaises\(ValueError,)c(random.sample,)i(self.seq,)i (20\))595 4812 y(for)g(element)g(in)g(random.sample\(self.seq,)d(5\):) 774 4903 y(self.assert_\(element)h(in)i(self.seq\))236 5086 y(if)h(__name__)e(==)i('__main__':)416 5177 y(unittest.main\(\))p 0 5549 3901 4 v 0 5649 a FI(790)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 791 803 TeXDict begin 791 802 bop 0 83 a FN(A)27 b(testcase)h(is)g(created)e (by)g(subclassing)g FJ(unittest.TestCase)p FN(.)42 b(The)27 b(three)f(indi)n(vidual)f(tests)j(are)f(de\002ned)f(with)h(methods)0 183 y(whose)h(names)g(start)h(with)f(the)h(letters)g(`)p FJ(test)p FN('.)48 b(This)29 b(naming)e(con)m(v)o(ention)e(informs)i (the)i(test)g(runner)d(about)i(which)g(methods)0 282 y(represent)19 b(tests.)0 429 y(The)d(crux)g(of)g(each)g(test)i(is)f(a) h(call)f(to)f FJ(assertEqual\(\))f FN(to)i(check)f(for)f(an)i(e)o (xpected)e(result;)j FJ(assert_\(\))d FN(to)i(v)o(erify)e(a)i (condition;)0 529 y(or)32 b FJ(assertRaises\(\))f FN(to)i(v)o(erify)e (that)i(an)g(e)o(xpected)e(e)o(xception)f(gets)j(raised.)63 b(These)32 b(methods)g(are)g(used)h(instead)f(of)h(the)0 628 y FJ(assert)20 b FN(statement)g(so)g(the)g(test)h(runner)e(can)h (accumulate)f(all)h(test)i(results)e(and)g(produce)e(a)i(report.)0 775 y(When)38 b(a)g FJ(setUp\(\))f FN(method)f(is)j(de\002ned,)h(the)e (test)h(runner)d(will)i(run)f(that)h(method)e(prior)h(to)h(each)f (test.)78 b(Lik)o(e)n(wise,)42 b(if)c(a)0 875 y FJ(tearDown\(\))22 b FN(method)g(is)i(de\002ned,)e(the)i(test)g(runner)d(will)j(in)m(v)n (ok)o(e)e(that)h(method)f(after)h(each)f(test.)35 b(In)23 b(the)g(e)o(xample,)f FJ(setUp\(\))0 975 y FN(w)o(as)f(used)f(to)g (create)g(a)h(fresh)f(sequence)f(for)g(each)h(test.)0 1121 y(The)i(\002nal)g(block)f(sho)n(ws)h(a)h(simple)f(w)o(ay)g(to)g (run)f(the)h(tests.)32 b FJ(unittest.main\(\))20 b FN(pro)o(vides)g(a)j (command)d(line)i(interf)o(ace)f(to)i(the)0 1221 y(test)e(script.)k (When)20 b(run)f(from)h(the)g(command)e(line,)i(the)g(abo)o(v)o(e)f (script)h(produces)e(an)j(output)e(that)h(looks)g(lik)o(e)g(this:)236 1459 y FA(...)236 1551 y(----------------------------------------)o (------)o(------)o(------)o(------)o(------)236 1642 y(Ran)45 b(3)f(tests)g(in)h(0.000s)236 1825 y(OK)0 2111 y FN(Instead)23 b(of)g FJ(unittest.main\(\))p FN(,)f(there)h(are)g (other)f(w)o(ays)i(to)g(run)e(the)i(tests)g(with)g(a)g(\002ner)f(le)n (v)o(el)g(of)g(control,)g(less)h(terse)g(output,)0 2211 y(and)c(no)f(requirement)f(to)j(be)f(run)f(from)g(the)i(command)d (line.)25 b(F)o(or)20 b(e)o(xample,)e(the)i(last)h(tw)o(o)g(lines)f (may)g(be)g(replaced)f(with:)236 2358 y FA(suite)44 b(=)h (unittest.TestLoader\(\).loadTestsFromTes)o(tCase\()o(TestSe)o(quence)o (Functi)o(ons\))236 2449 y(unittest.TextTestRunner\(verbosity=2\).run)o (\(suite)o(\))0 2735 y FN(Running)19 b(the)h(re)n(vised)f(script)i (from)e(the)h(interpreter)f(or)g(another)g(script)h(produces)f(the)h (follo)n(wing)f(output:)236 2882 y FA(testchoice)43 b (\(__main__.TestSequenceFunctions\))d(...)k(ok)236 2974 y(testsample)f(\(__main__.TestSequenceFunctions\))d(...)k(ok)236 3065 y(testshuffle)f(\(__main__.TestSequenceFunctions\))d(...)k(ok)236 3248 y(----------------------------------------)o(------)o(------)o (------)o(------)o(------)236 3339 y(Ran)h(3)f(tests)g(in)h(0.110s)236 3521 y(OK)0 3808 y FN(The)20 b(abo)o(v)o(e)f(e)o(xamples)g(sho)n(w)i (the)f(most)h(commonly)d(used)i FJ(unittest)g FN(features)f(which)h (are)h(suf)n(\002cient)f(to)g(meet)h(man)o(y)e(e)n(v)o(eryday)0 3908 y(testing)h(needs.)25 b(The)20 b(remainder)e(of)i(the)g (documentation)d(e)o(xplores)i(the)h(full)g(feature)g(set)h(from)e (\002rst)i(principles.)0 4193 y Fv(23.3.2)101 b(Organizing)29 b(test)e(code)0 4395 y FN(The)19 b(basic)g(b)n(uilding)f(blocks)h(of)g (unit)g(testing)g(are)g FK(test)h(cases)g FN(\227)g(single)f(scenarios) g(that)g(must)g(be)h(set)g(up)f(and)f(check)o(ed)g(for)h(correct-)0 4495 y(ness.)38 b(In)24 b FJ(unittest)p FN(,)g(test)h(cases)g(are)f (represented)f(by)g(instances)i(of)f FJ(unittest)p FN(')-5 b(s)23 b FJ(TestCase)h FN(class.)38 b(T)-7 b(o)24 b(mak)o(e)g(your)f(o) n(wn)0 4595 y(test)e(cases)g(you)e(must)i(write)f(subclasses)g(of)g FJ(TestCase)p FN(,)f(or)h(use)h FJ(FunctionTestCase)p FN(.)0 4742 y(An)27 b(instance)f(of)g(a)h FJ(TestCase)p FN(-deri)n(v)o(ed)c(class)28 b(is)g(an)e(object)g(that)h(can)f (completely)g(run)f(a)i(single)g(test)g(method,)g(together)e(with)0 4841 y(optional)19 b(set-up)h(and)f(tidy-up)g(code.)0 4988 y(The)i(testing)g(code)f(of)h(a)g FJ(TestCase)f FN(instance)h(should)f(be)h(entirely)f(self)i(contained,)d(such)i(that) g(it)h(can)f(be)g(run)f(either)h(in)g(isolation)0 5088 y(or)f(in)g(arbitrary)f(combination)f(with)i(an)o(y)f(number)g(of)h (other)f(test)i(cases.)0 5235 y(The)h(simplest)h FJ(TestCase)e FN(subclass)i(will)g(simply)f(o)o(v)o(erride)e(the)i FJ(runTest\(\))g FN(method)f(in)h(order)f(to)i(perform)d(speci\002c)j (testing)0 5334 y(code:)p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o(ame)n(w)o(or)q(k) 2175 b(791)p eop end %%Page: 792 804 TeXDict begin 792 803 bop 236 174 a FA(import)44 b(unittest)236 357 y(class)g(DefaultWidgetSizeTestCase\(unittest.TestC)o(ase\):)416 448 y(def)g(runTest\(self\):)595 540 y(widget)g(=)g(Widget\('The)f (widget'\))595 631 y(self.assertEqual\(widget.size\(\),)c(\(50,)45 b(50\),)f('incorrect)f(default)h(size'\))0 917 y FN(Note)31 b(that)g(in)g(order)f(to)h(test)h(something,)g(we)f(use)h(the)f(one)f (of)h(the)g FJ(assert)2385 932 y(*)2435 917 y(\(\))f FN(or)g FJ(fail)2865 932 y(*)2915 917 y(\(\))h FN(methods)f(pro)o (vided)e(by)j(the)0 1017 y FJ(TestCase)25 b FN(base)g(class.)42 b(If)25 b(the)h(test)g(f)o(ails,)h(an)f(e)o(xception)d(will)j(be)g (raised,)g(and)f FJ(unittest)g FN(will)h(identify)e(the)i(test)g(case)g (as)g(a)0 1117 y FK(failur)m(e)p FN(.)46 b(An)o(y)27 b(other)f(e)o(xceptions)g(will)i(be)f(treated)g(as)h FK(err)l(or)o(s)p FN(.)47 b(This)28 b(helps)f(you)f(identify)g(where)h (the)g(problem)f(is:)40 b FK(failur)m(es)28 b FN(are)0 1216 y(caused)23 b(by)g(incorrect)g(results)g(-)h(a)g(5)g(where)f(you)g (e)o(xpected)f(a)i(6.)35 b FK(Err)l(or)o(s)25 b FN(are)f(caused)f(by)g (incorrect)f(code)h(-)h(e.g.,)g(a)g FJ(TypeError)0 1316 y FN(caused)c(by)f(an)i(incorrect)d(function)h(call.)0 1463 y(The)k(w)o(ay)g(to)g(run)g(a)g(test)i(case)e(will)h(be)f (described)f(later)-5 b(.)35 b(F)o(or)22 b(no)n(w)-5 b(,)23 b(note)g(that)g(to)g(construct)g(an)g(instance)g(of)f(such)h(a)h (test)g(case,)g(we)0 1562 y(call)d(its)g(constructor)d(without)i(ar)o (guments:)236 1801 y FA(testCase)44 b(=)g (DefaultWidgetSizeTestCase\(\))0 2087 y FN(No)n(w)-5 b(,)19 b(such)f(test)j(cases)e(can)g(be)g(numerous,)f(and)g(their)h (set-up)g(can)g(be)g(repetiti)n(v)o(e.)k(In)c(the)g(abo)o(v)o(e)f (case,)h(constructing)e(a)j FJ(Widget)e FN(in)0 2187 y(each)i(of)g(100)f(W)m(idget)h(test)h(case)g(subclasses)f(w)o(ould)g (mean)f(unsightly)g(duplication.)0 2334 y(Luckily)-5 b(,)17 b(we)h(can)g(f)o(actor)g(out)f(such)h(set-up)g(code)f(by)h (implementing)e(a)j(method)d(called)i FJ(setUp\(\))p FN(,)g(which)f(the)i(testing)f(frame)n(w)o(ork)0 2433 y(will)j(automatically)e(call)h(for)g(us)g(when)g(we)h(run)e(the)h (test:)236 2580 y FA(import)44 b(unittest)236 2763 y(class)g (SimpleWidgetTestCase\(unittest.TestCase\):)416 2854 y(def)g(setUp\(self\):)595 2945 y(self.widget)f(=)i(Widget\('The)e (widget'\))236 3128 y(class)h (DefaultWidgetSizeTestCase\(SimpleWidgetTe)o(stCase)o(\):)416 3219 y(def)g(runTest\(self\):)595 3311 y (self.failUnless\(self.widget.size\(\))39 b(==)44 b(\(50,50\),)1312 3402 y('incorrect)f(default)h(size'\))236 3585 y(class)g (WidgetResizeTestCase\(SimpleWidgetTestCas)o(e\):)416 3676 y(def)g(runTest\(self\):)595 3767 y(self.widget.resize\(100,150\)) 595 3859 y(self.failUnless\(self.widget.size\(\))39 b(==)44 b(\(100,150\),)1312 3950 y('wrong)g(size)g(after)g(resize'\))0 4237 y FN(If)26 b(the)h FJ(setUp\(\))e FN(method)g(raises)i(an)f(e)o (xception)f(while)h(the)g(test)i(is)f(running,)e(the)i(frame)n(w)o(ork) d(will)j(consider)e(the)h(test)i(to)e(ha)n(v)o(e)0 4336 y(suf)n(fered)19 b(an)h(error)m(,)e(and)i(the)g FJ(runTest\(\))f FN(method)g(will)i(not)f(be)g(e)o(x)o(ecuted.)0 4483 y(Similarly)-5 b(,)19 b(we)i(can)f(pro)o(vide)e(a)j FJ(tearDown\(\))d FN(method)h(that)h(tidies)h(up)f(after)g(the)g FJ(runTest\(\))f FN(method)g(has)h(been)g(run:)p 0 5549 3901 4 v 0 5649 a FI(792)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 793 805 TeXDict begin 793 804 bop 236 174 a FA(import)44 b(unittest)236 357 y(class)g(SimpleWidgetTestCase\(unittest.TestCase\):)416 448 y(def)g(setUp\(self\):)595 540 y(self.widget)f(=)i(Widget\('The)e (widget'\))416 722 y(def)h(tearDown\(self\):)595 814 y(self.widget.dispose\(\))595 905 y(self.widget)f(=)i(None)0 1191 y FN(If)20 b FJ(setUp\(\))f FN(succeeded,)g(the)h FJ(tearDown\(\))f FN(method)g(will)i(be)f(run)g(whether)f FJ(runTest\(\))g FN(succeeded)g(or)h(not.)0 1338 y(Such)g(a)g(w)o (orking)f(en)m(vironment)e(for)j(the)g(testing)g(code)g(is)h(called)f (a)g FK(\002xtur)m(e)p FN(.)0 1485 y(Often,)64 b(man)o(y)54 b(small)i(test)g(cases)g(will)g(use)g(the)g(same)f(\002xture.)130 b(In)55 b(this)h(case,)65 b(we)56 b(w)o(ould)e(end)h(up)g(subclassing)0 1585 y FJ(SimpleWidgetTestCase)33 b FN(into)k(man)o(y)e(small)i (one-method)d(classes)j(such)g(as)g FJ(DefaultWidgetSizeTestCase)p FN(.)0 1684 y(This)20 b(is)h(time-consuming)d(and)i(discouraging,)d(so) j(in)h(the)f(same)g(v)o(ein)g(as)h(JUnit,)f FJ(unittest)f FN(pro)o(vides)g(a)i(simpler)e(mechanism:)236 1923 y FA(import)44 b(unittest)236 2105 y(class)g (WidgetTestCase\(unittest.TestCase\):)416 2197 y(def)g(setUp\(self\):) 595 2288 y(self.widget)f(=)i(Widget\('The)e(widget'\))416 2471 y(def)h(tearDown\(self\):)595 2562 y(self.widget.dispose\(\))595 2653 y(self.widget)f(=)i(None)416 2836 y(def)f (testDefaultSize\(self\):)595 2927 y (self.failUnless\(self.widget.size\(\))39 b(==)44 b(\(50,50\),)1312 3019 y('incorrect)f(default)h(size'\))416 3201 y(def)g (testResize\(self\):)595 3293 y(self.widget.resize\(100,150\))595 3384 y(self.failUnless\(self.widget.size\(\))39 b(==)44 b(\(100,150\),)1312 3475 y('wrong)g(size)g(after)g(resize'\))0 3762 y FN(Here)31 b(we)h(ha)n(v)o(e)f(not)g(pro)o(vided)e(a)i FJ(runTest\(\))g FN(method,)h(b)n(ut)f(ha)n(v)o(e)g(instead)g(pro)o (vided)e(tw)o(o)j(dif)n(ferent)e(test)i(methods.)57 b(Class)0 3861 y(instances)26 b(will)i(no)n(w)e(each)g(run)g(one)g(of)g(the)g FJ(test)1544 3876 y(*)1594 3861 y(\(\))g FN(methods,)h(with)g FJ(self.widget)e FN(created)g(and)h(destro)o(yed)f(separately)0 3961 y(for)d(each)h(instance.)32 b(When)23 b(creating)f(an)h(instance)f (we)h(must)g(specify)f(the)h(test)h(method)d(it)j(is)g(to)f(run.)32 b(W)-7 b(e)24 b(do)e(this)i(by)e(passing)h(the)0 4061 y(method)c(name)g(in)i(the)f(constructor:)236 4299 y FA(defaultSizeTestCase)42 b(=)j(WidgetTestCase\('testDefaultSize'\))236 4390 y(resizeTestCase)e(=)h(WidgetTestCase\('testResize'\))0 4677 y FN(T)-6 b(est)27 b(case)f(instances)g(are)g(grouped)e(together)g (according)g(to)i(the)g(features)f(the)o(y)h(test.)43 b FJ(unittest)25 b FN(pro)o(vides)f(a)i(mechanism)f(for)0 4776 y(this:)h(the)20 b FK(test)h(suite)p FN(,)f(represented)f(by)h FJ(unittest)p FN(')-5 b(s)19 b FJ(TestSuite)g FN(class:)236 5014 y FA(widgetTestSuite)43 b(=)h(unittest.TestSuite\(\))236 5106 y(widgetTestSuite.addTest\(WidgetTestCase\(')o(testDe)o(faultS)o (ize'\)\))236 5197 y(widgetTestSuite.addTest\(WidgetTestCase\(')o (testRe)o(size'\))o(\))p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o(ame)n(w)o(or)q(k) 2175 b(793)p eop end %%Page: 794 806 TeXDict begin 794 805 bop 0 83 a FN(F)o(or)20 b(the)g(ease)g(of)g (running)e(tests,)j(as)g(we)f(will)h(see)g(later)m(,)f(it)g(is)h(a)g (good)e(idea)h(to)g(pro)o(vide)e(in)i(each)g(test)h(module)e(a)h (callable)g(object)f(that)0 183 y(returns)g(a)i(pre-b)n(uilt)e(test)i (suite:)236 421 y FA(def)45 b(suite\(\):)416 512 y(suite)f(=)g (unittest.TestSuite\(\))416 603 y (suite.addTest\(WidgetTestCase\('testDe)o(faultS)o(ize'\)\))416 695 y(suite.addTest\(WidgetTestCase\('testRe)o(size'\))o(\))416 786 y(return)f(suite)0 1054 y FN(or)20 b(e)n(v)o(en:)236 1292 y FA(def)45 b(suite\(\):)416 1383 y(tests)f(=)g (['testDefaultSize',)e('testResize'])416 1566 y(return)h (unittest.TestSuite\(map\(WidgetTestCase,)c(tests\)\))0 1852 y FN(Since)22 b(it)h(is)h(a)f(common)d(pattern)i(to)g(create)g(a)h FJ(TestCase)e FN(subclass)i(with)f(man)o(y)g(similarly)g(named)f(test)i (functions,)e FJ(unittest)0 1952 y FN(pro)o(vides)d(a)j FJ(TestLoader)e FN(class)i(that)f(can)g(be)g(used)g(to)h(automate)e (the)h(process)g(of)g(creating)f(a)h(test)h(suite)g(and)f(populating)d (it)k(with)0 2052 y(indi)n(vidual)d(tests.)27 b(F)o(or)19 b(e)o(xample,)236 2290 y FA(suite)44 b(=)h (unittest.TestLoader\(\).loadTestsFromTes)o(tCase\()o(Widget)o(TestCa)o (se\))0 2576 y FN(will)132 b(create)f(a)g(test)h(suite)g(that)f(will)h (run)e FJ(WidgetTestCase.testDefaultSize\(\))c FN(and)0 2676 y FJ(WidgetTestCase.testResize)p FN(.)101 b FJ(TestLoader)45 b FN(uses)i(the)g FJ('test')f FN(method)g(name)g(pre\002x)g(to)h (identify)f(test)0 2776 y(methods)19 b(automatically)-5 b(.)0 2923 y(Note)24 b(that)h(the)f(order)f(in)h(which)g(the)g(v)n (arious)g(test)h(cases)g(will)g(be)f(run)g(is)h(determined)d(by)i (sorting)f(the)i(test)g(function)d(names)i(with)0 3022 y(the)c(b)n(uilt-in)g FJ(cmp\(\))g FN(function.)0 3169 y(Often)27 b(it)i(is)g(desirable)e(to)h(group)e(suites)i(of)g(test)h (cases)f(together)m(,)g(so)g(as)h(to)f(run)f(tests)i(for)e(the)h(whole) f(system)h(at)g(once.)48 b(This)28 b(is)0 3269 y(easy)-5 b(,)27 b(since)g FJ(TestSuite)e FN(instances)i(can)f(be)g(added)f(to)i (a)g FJ(TestSuite)e FN(just)i(as)g FJ(TestCase)f FN(instances)g(can)g (be)g(added)g(to)g(a)0 3368 y FJ(TestSuite)p FN(:)236 3607 y FA(suite1)44 b(=)h(module1.TheTestSuite\(\))236 3698 y(suite2)f(=)h(module2.TheTestSuite\(\))236 3789 y(alltests)f(=)g(unittest.TestSuite\([suite1,)d(suite2]\))0 4076 y FN(Y)-9 b(ou)26 b(can)g(place)g(the)h(de\002nitions)f(of)g(test) h(cases)g(and)f(test)i(suites)f(in)g(the)f(same)h(modules)e(as)i(the)g (code)f(the)o(y)g(are)g(to)h(test)g(\(such)f(as)0 4175 y(`)p FO(widget.p)n(y)p FN('\),)17 b(b)n(ut)j(there)g(are)g(se)n(v)o (eral)f(adv)n(antages)g(to)h(placing)f(the)i(test)g(code)e(in)i(a)f (separate)g(module,)f(such)g(as)i(`)p FO(test)p 3440 4175 23 4 v 26 w(widget.p)n(y)p FN(':)125 4399 y FM(\017)41 b FN(The)19 b(test)i(module)e(can)h(be)g(run)g(standalone)f(from)g(the) h(command)e(line.)125 4563 y FM(\017)41 b FN(The)19 b(test)i(code)f (can)g(more)f(easily)i(be)f(separated)f(from)g(shipped)g(code.)125 4727 y FM(\017)41 b FN(There)19 b(is)i(less)g(temptation)e(to)i(change) d(test)k(code)d(to)h(\002t)h(the)g(code)e(it)i(tests)g(without)f(a)g (good)f(reason.)125 4891 y FM(\017)41 b FN(T)-6 b(est)20 b(code)g(should)f(be)h(modi\002ed)f(much)g(less)j(frequently)c(than)h (the)i(code)e(it)i(tests.)125 5055 y FM(\017)41 b FN(T)-6 b(ested)20 b(code)f(can)h(be)g(ref)o(actored)f(more)g(easily)-5 b(.)125 5218 y FM(\017)41 b FN(T)-6 b(ests)21 b(for)e(modules)g (written)h(in)h(C)g(must)f(be)g(in)h(separate)e(modules)g(an)o(yw)o(ay) -5 b(,)19 b(so)h(why)g(not)f(be)h(consistent?)125 5382 y FM(\017)41 b FN(If)20 b(the)g(testing)g(strate)o(gy)f(changes,)g (there)h(is)h(no)f(need)f(to)i(change)e(the)h(source)f(code.)p 0 5549 3901 4 v 0 5649 a FI(794)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 795 807 TeXDict begin 795 806 bop 0 83 a Fv(23.3.3)101 b(Re-using)29 b(old)f(test)g(code)0 286 y FN(Some)19 b(users)g(will)g(\002nd)g(that)g (the)o(y)g(ha)n(v)o(e)f(e)o(xisting)g(test)i(code)e(that)h(the)o(y)f(w) o(ould)h(lik)o(e)g(to)g(run)f(from)g FJ(unittest)p FN(,)g(without)g (con)m(v)o(erting)0 386 y(e)n(v)o(ery)h(old)h(test)h(function)d(to)j(a) f FJ(TestCase)f FN(subclass.)0 532 y(F)o(or)26 b(this)h(reason,)h FJ(unittest)d FN(pro)o(vides)g(a)i FJ(FunctionTestCase)d FN(class.)45 b(This)27 b(subclass)g(of)f FJ(TestCase)g FN(can)h(be)f(used)g(to)0 632 y(wrap)20 b(an)g(e)o(xisting)f(test)i (function.)j(Set-up)19 b(and)h(tear)n(-do)n(wn)e(functions)h(can)h (also)h(be)f(pro)o(vided.)0 779 y(Gi)n(v)o(en)f(the)i(follo)n(wing)d (test)j(function:)236 1017 y FA(def)45 b(testSomething\(\):)416 1108 y(something)e(=)i(makeSomething\(\))416 1200 y(assert)e (something.name)g(is)h(not)h(None)416 1291 y(#)f(...)0 1578 y FN(one)20 b(can)g(create)g(an)g(equi)n(v)n(alent)e(test)j(case)g (instance)f(as)h(follo)n(ws:)236 1816 y FA(testcase)44 b(=)g(unittest.FunctionTestCase\(testSomething\))0 2102 y FN(If)20 b(there)f(are)h(additional)f(set-up)h(and)f(tear)n(-do)n(wn) g(methods)f(that)j(should)e(be)h(called)f(as)i(part)f(of)g(the)g(test)h (case')-5 b(s)20 b(operation,)e(the)o(y)i(can)0 2202 y(also)h(be)f(pro)o(vided)d(lik)o(e)k(so:)236 2440 y FA(testcase)44 b(=)g(unittest.FunctionTestCase\(testSomething,)1895 2531 y(setUp=makeSomethingDB,)1895 2623 y(tearDown=deleteSomethingDB\)) 0 2909 y FN(T)-7 b(o)24 b(mak)o(e)f(migrating)g(e)o(xisting)g(test)h (suites)h(easier)m(,)f FJ(unittest)f FN(supports)g(tests)h(raising)g FJ(AssertionError)e FN(to)h(indicate)h(test)0 3009 y(f)o(ailure.)g(Ho)n (we)n(v)o(er)m(,)18 b(it)j(is)g(recommended)c(that)j(you)f(use)i(the)f (e)o(xplicit)f FJ(TestCase.fail)2695 3024 y(*)2745 3009 y(\(\))f FN(and)h FJ(TestCase.assert)3753 3024 y(*)3803 3009 y(\(\))0 3109 y FN(methods)g(instead,)h(as)h(future)e(v)o(ersions) g(of)h FJ(unittest)f FN(may)h(treat)g FJ(AssertionError)e FN(dif)n(ferently)-5 b(.)0 3255 y FL(Note:)23 b FN(Ev)o(en)18 b(though)f FJ(FunctionTestCase)f FN(can)i(be)g(used)h(to)f(quickly)f (con)m(v)o(ert)g(an)h(e)o(xisting)g(test)i(base)e(o)o(v)o(er)f(to)i(a)g FJ(unittest)p FN(-)0 3355 y(based)j(system,)g(this)h(approach)d(is)j (not)f(recommended.)28 b(T)-7 b(aking)21 b(the)h(time)h(to)f(set)h(up)f (proper)e FJ(TestCase)h FN(subclasses)i(will)g(mak)o(e)0 3455 y(future)c(test)i(ref)o(actorings)e(in\002nitely)g(easier)-5 b(.)0 3734 y Fv(23.3.4)101 b(Classes)28 b(and)g(functions)0 3917 y FL(class)21 b FD(TestCase)p FJ(\()p FC([)p FK(methodName)12 b FC(])p FJ(\))208 4017 y FN(Instances)23 b(of)i(the)f FJ(TestCase)f FN(class)j(represent)d(the)h(smallest)i(testable)e(units) h(in)f(the)h FJ(unittest)e FN(uni)n(v)o(erse.)36 b(This)25 b(class)208 4116 y(is)d(intended)f(to)h(be)g(used)f(as)i(a)f(base)g (class,)h(with)g(speci\002c)f(tests)h(being)e(implemented)f(by)h (concrete)g(subclasses.)31 b(This)22 b(class)208 4216 y(implements)h(the)h(interf)o(ace)g(needed)f(by)h(the)g(test)i(runner)c (to)j(allo)n(w)f(it)h(to)g(dri)n(v)o(e)e(the)i(test,)h(and)e(methods)f (that)i(the)f(test)h(code)208 4315 y(can)20 b(use)g(to)g(check)g(for)f (and)h(report)f(v)n(arious)g(kinds)h(of)g(f)o(ailure.)208 4442 y(Each)g(instance)h(of)g FJ(TestCase)f FN(will)i(run)e(a)i(single) f(test)h(method:)k(the)21 b(method)e(named)h FK(methodName)p FN(.)27 b(If)21 b(you)f(remember)m(,)208 4542 y(we)g(had)g(an)g (earlier)g(e)o(xample)e(that)j(went)f(something)f(lik)o(e)h(this:)533 4760 y FA(def)45 b(suite\(\):)713 4851 y(suite)f(=)g (unittest.TestSuite\(\))713 4943 y (suite.addTest\(WidgetTestCase\('testDefa)o(ultSiz)o(e'\)\))713 5034 y(suite.addTest\(WidgetTestCase\('testResi)o(ze'\)\))713 5125 y(return)g(suite)208 5400 y FN(Here,)19 b(we)i(create)f(tw)o(o)g (instances)g(of)g FJ(WidgetTestCase)p FN(,)e(each)i(of)g(which)g(runs)f (a)i(single)f(test.)p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o(ame)n(w)o(or)q(k) 2175 b(795)p eop end %%Page: 796 808 TeXDict begin 796 807 bop 208 83 a FK(methodName)18 b FN(def)o(aults)i(to)h FJ('runTest')p FN(.)0 230 y FL(class)g FD(FunctionTestCase)p FJ(\()p FK(testFunc)p FC([)p FK(,)16 b(setUp)p FC([)p FK(,)k(tearDown)p FC([)p FK(,)f(description)12 b FC(])g(])g(])p FJ(\))208 330 y FN(This)20 b(class)h(implements)e(the) h(portion)e(of)i(the)g FJ(TestCase)f FN(interf)o(ace)h(which)f(allo)n (ws)h(the)g(test)h(runner)e(to)h(dri)n(v)o(e)f(the)h(test,)h(b)n(ut)208 429 y(does)c(not)h(pro)o(vide)e(the)i(methods)g(which)f(test)i(code)f (can)g(use)g(to)g(check)f(and)h(report)f(errors.)23 b(This)c(is)g(used) f(to)g(create)g(test)h(cases)208 529 y(using)g(le)o(gac)o(y)g(test)i (code,)e(allo)n(wing)g(it)i(to)g(be)f(inte)o(grated)e(into)i(a)h FJ(unittest)p FN(-based)d(test)j(frame)n(w)o(ork.)0 676 y FL(class)g FD(TestSuite)p FJ(\()p FC([)p FK(tests)12 b FC(])p FJ(\))208 775 y FN(This)26 b(class)i(represents)e(an)g(aggre)o (gation)e(of)i(indi)n(vidual)f(tests)j(cases)f(and)f(test)i(suites.)45 b(The)26 b(class)i(presents)e(the)g(interf)o(ace)208 875 y(needed)d(by)i(the)h(test)g(runner)d(to)i(allo)n(w)h(it)g(to)f(be) g(run)g(as)h(an)o(y)e(other)g(test)i(case.)41 b(Running)24 b(a)h FJ(TestSuite)g FN(instance)f(is)j(the)208 975 y(same)20 b(as)h(iterating)e(o)o(v)o(er)g(the)h(suite,)h(running)d(each)i(test)h (indi)n(vidually)-5 b(.)208 1107 y(If)23 b FK(tests)i FN(is)g(gi)n(v)o(en,)e(it)i(must)e(be)h(an)g(iterable)f(of)h(indi)n (vidual)e(test)i(cases)h(or)e(other)g(test)i(suites)g(that)e(will)i(be) f(used)f(to)h(b)n(uild)g(the)208 1207 y(suite)c(initially)-5 b(.)25 b(Additional)19 b(methods)g(are)h(pro)o(vided)d(to)k(add)e(test) i(cases)g(and)f(suites)h(to)f(the)g(collection)g(later)g(on.)0 1354 y FL(class)h FD(TestLoader)p FJ(\(\))208 1453 y FN(This)37 b(class)i(is)f(responsible)e(for)h(loading)g(tests)h (according)e(to)h(v)n(arious)g(criteria)g(and)g(returning)e(them)j (wrapped)d(in)j(a)208 1553 y FJ(TestSuite)p FN(.)23 b(It)e(can)f(load)g (all)g(tests)i(within)e(a)g(gi)n(v)o(en)f(module)g(or)h FJ(TestCase)f FN(subclass.)0 1700 y FL(class)i FD(TestResult)p FJ(\(\))208 1800 y FN(This)f(class)h(is)g(used)f(to)g(compile)g (information)e(about)h(which)g(tests)j(ha)n(v)o(e)d(succeeded)g(and)h (which)g(ha)n(v)o(e)f(f)o(ailed.)0 1946 y FD(defaultTestLoader)208 2046 y FN(Instance)g(of)h(the)g FJ(TestLoader)e FN(class)j(intended)e (to)h(be)g(shared.)k(If)c(no)g(customization)e(of)i(the)g FJ(TestLoader)f FN(is)i(needed,)208 2146 y(this)f(instance)g(can)g(be)g (used)g(instead)g(of)g(repeatedly)f(creating)g(ne)n(w)h(instances.)0 2293 y FL(class)h FD(TextTestRunner)p FJ(\()p FC([)p FK(str)m(eam)p FC([)p FK(,)c(descriptions)p FC([)p FK(,)i(verbosity)12 b FC(])g(])g(])p FJ(\))208 2392 y FN(A)20 b(basic)h(test)g(runner)d (implementation)g(which)i(prints)g(results)g(on)g(standard)f(error)-5 b(.)24 b(It)d(has)f(a)h(fe)n(w)f(con\002gurable)e(parameters,)208 2492 y(b)n(ut)k(is)h(essentially)f(v)o(ery)f(simple.)31 b(Graphical)21 b(applications)g(which)h(run)f(test)i(suites)g(should)f (pro)o(vide)e(alternate)h(implemen-)208 2591 y(tations.)0 2738 y FD(main)p FJ(\()p FC([)p FK(module)p FC([)p FK(,)d(defaultT)-8 b(est)q FC([)p FK(,)20 b(ar)m(gv)p FC([)p FK(,)f(testRunner)r FC([)p FK(,)g(testLoader)14 b FC(])e(])g(])g(])g(])p FJ(\))208 2838 y FN(A)25 b(command-line)e(program)g(that)j(runs)f(a)g (set)i(of)e(tests;)k(this)d(is)g(primarily)e(for)h(making)f(test)i (modules)e(con)m(v)o(eniently)f(e)o(x)o(e-)208 2938 y(cutable.)h(The)c (simplest)g(use)h(for)e(this)i(function)d(is)k(to)e(include)f(the)h (follo)n(wing)f(line)h(at)h(the)f(end)g(of)g(a)g(test)h(script:)444 3162 y FA(if)44 b(__name__)g(==)g('__main__':)623 3253 y(unittest.main\(\))0 3457 y FN(In)25 b(some)h(cases,)h(the)f(e)o (xisting)f(tests)h(may)f(ha)n(v)o(e)g(been)g(written)h(using)f(the)g FJ(doctest)g FN(module.)40 b(If)25 b(so,)i(that)f(module)e(pro)o(vides) g(a)0 3556 y FJ(DocTestSuite)14 b FN(class)j(that)e(can)h (automatically)e(b)n(uild)h FJ(unittest.TestSuite)e FN(instances)j (from)e(the)i(e)o(xisting)f FJ(doctest)p FN(-)0 3656 y(based)20 b(tests.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 3941 y Fv(23.3.5)101 b(T)-12 b(estCase)28 b(Objects)0 4144 y FN(Each)21 b FJ(TestCase)f FN(instance)h(represents)f(a)i (single)f(test,)h(b)n(ut)g(each)e(concrete)g(subclass)i(may)f(be)g (used)g(to)g(de\002ne)g(multiple)g(tests)h(\227)0 4243 y(the)e(concrete)f(class)i(represents)f(a)g(single)g(test)h(\002xture.) k(The)20 b(\002xture)f(is)i(created)f(and)f(cleaned)h(up)f(for)h(each)g (test)h(case.)0 4390 y FJ(TestCase)31 b FN(instances)g(pro)o(vide)f (three)h(groups)f(of)i(methods:)47 b(one)31 b(group)f(used)h(to)h(run)f (the)h(test,)j(another)30 b(used)i(by)f(the)h(test)0 4490 y(implementation)16 b(to)j(check)f(conditions)f(and)i(report)e(f)o (ailures,)i(and)f(some)g(inquiry)f(methods)h(allo)n(wing)g(information) e(about)i(the)h(test)0 4589 y(itself)i(to)f(be)g(gathered.)0 4736 y(Methods)f(in)i(the)f(\002rst)h(group)d(\(running)g(the)i(test\)) h(are:)0 4883 y FD(setUp)p FJ(\(\))208 4983 y FN(Method)14 b(called)h(to)h(prepare)e(the)i(test)g(\002xture.)23 b(This)16 b(is)h(called)e(immediately)f(before)g(calling)i(the)f(test)i (method;)f(an)o(y)e(e)o(xception)208 5082 y(raised)26 b(by)g(this)h(method)e(will)i(be)g(considered)e(an)h(error)f(rather)h (than)g(a)h(test)g(f)o(ailure.)44 b(The)26 b(def)o(ault)g (implementation)e(does)208 5182 y(nothing.)0 5329 y FD(tearDown)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(796)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 797 809 TeXDict begin 797 808 bop 208 83 a FN(Method)24 b(called)i(immediately) e(after)i(the)g(test)h(method)d(has)i(been)f(called)h(and)f(the)h (result)g(recorded.)40 b(This)26 b(is)h(called)f(e)n(v)o(en)208 183 y(if)c(the)h(test)h(method)d(raised)h(an)h(e)o(xception,)e(so)i (the)f(implementation)f(in)h(subclasses)h(may)f(need)g(to)h(be)g (particularly)e(careful)208 282 y(about)d(checking)h(internal)g(state.) 25 b(An)o(y)19 b(e)o(xception)f(raised)i(by)f(this)i(method)d(will)j (be)e(considered)g(an)g(error)g(rather)g(than)g(a)i(test)208 382 y(f)o(ailure.)i(This)18 b(method)f(will)i(only)e(be)h(called)g(if)g (the)g FJ(setUp\(\))g FN(succeeds,)g(re)o(gardless)e(of)i(the)g (outcome)e(of)i(the)g(test)h(method.)208 482 y(The)g(def)o(ault)h (implementation)e(does)i(nothing.)0 628 y FD(run)p FJ(\()p FC([)p FK(r)m(esult)13 b FC(])p FJ(\))208 728 y FN(Run)27 b(the)h(test,)j(collecting)c(the)h(result)f(into)h(the)g(test)h(result) f(object)f(passed)h(as)g FK(r)m(esult)q FN(.)49 b(If)28 b FK(r)m(esult)i FN(is)f(omitted)e(or)h FJ(None)p FN(,)h(a)208 828 y(temporary)19 b(result)i(object)f(is)i(created)f(\(by)f(calling)h (the)g FJ(defaultTestCase\(\))e FN(method\))g(and)i(used;)g(this)h (result)f(object)208 927 y(is)g(not)f(returned)e(to)i FJ(run\(\))p FN(')-5 b(s)20 b(caller)-5 b(.)208 1060 y(The)19 b(same)i(ef)n(fect)e(may)h(be)g(had)g(by)g(simply)f(calling)h (the)g FJ(TestCase)g FN(instance.)0 1207 y FD(debug)p FJ(\(\))208 1307 y FN(Run)d(the)h(test)h(without)e(collecting)g(the)h (result.)24 b(This)18 b(allo)n(ws)g(e)o(xceptions)e(raised)i(by)f(the)h (test)h(to)f(be)g(propagated)c(to)k(the)g(caller)m(,)208 1406 y(and)h(can)h(be)g(used)g(to)h(support)d(running)g(tests)k(under)d (a)h(deb)n(ugger)-5 b(.)0 1553 y(The)20 b(test)h(code)e(can)h(use)h(an) o(y)e(of)h(the)g(follo)n(wing)f(methods)g(to)h(check)g(for)f(and)h (report)f(f)o(ailures.)0 1700 y FD(assert_)p FJ(\()p FK(e)n(xpr)r FC([)p FK(,)g(msg)12 b FC(])p FJ(\))0 1800 y FD(failUnless)p FJ(\()p FK(e)n(xpr)r FC([)p FK(,)18 b(msg)12 b FC(])p FJ(\))208 1899 y FN(Signal)19 b(a)h(test)g(f)o (ailure)f(if)h FK(e)n(xpr)i FN(is)e(f)o(alse;)g(the)g(e)o(xplanation)d (for)i(the)g(error)g(will)h(be)g FK(msg)f FN(if)h(gi)n(v)o(en,)e (otherwise)h(it)h(will)h(be)e FJ(None)p FN(.)0 2046 y FD(assertEqual)p FJ(\()p FK(\002r)o(st,)g(second)r FC([)p FK(,)g(msg)12 b FC(])p FJ(\))0 2146 y FD(failUnlessEqual)p FJ(\()p FK(\002r)o(st,)18 b(second)r FC([)p FK(,)h(msg)12 b FC(])p FJ(\))208 2245 y FN(T)-6 b(est)25 b(that)f FK(\002r)o(st)j FN(and)d FK(second)h FN(are)g(equal.)37 b(If)24 b(the)g(v)n(alues)g(do) g(not)g(compare)f(equal,)h(the)h(test)g(will)g(f)o(ail)g(with)f(the)h (e)o(xplanation)208 2345 y(gi)n(v)o(en)20 b(by)i FK(msg)p FN(,)h(or)f FJ(None)p FN(.)31 b(Note)22 b(that)g(using)g FJ(failUnlessEqual\(\))d FN(impro)o(v)o(es)i(upon)f(doing)h(the)i (comparison)d(as)j(the)208 2445 y(\002rst)j(parameter)e(to)i FJ(failUnless\(\))p FN(:)35 b(the)25 b(def)o(ault)g(v)n(alue)g(for)h FK(msg)g FN(can)f(be)h(computed)d(to)j(include)f(representations)f(of) 208 2544 y(both)19 b FK(\002r)o(st)k FN(and)c FK(second)r FN(.)0 2691 y FD(assertNotEqual)p FJ(\()p FK(\002r)o(st,)f(second)r FC([)p FK(,)h(msg)12 b FC(])p FJ(\))0 2791 y FD(failIfEqual)p FJ(\()p FK(\002r)o(st,)19 b(second)r FC([)p FK(,)g(msg)12 b FC(])p FJ(\))208 2890 y FN(T)-6 b(est)25 b(that)f FK(\002r)o(st)j FN(and)d FK(second)h FN(are)g(not)f(equal.)37 b(If)24 b(the)g(v)n(alues)g(do)g(compare)f(equal,)h(the)h(test)g(will)g(f)o (ail)g(with)f(the)h(e)o(xplanation)208 2990 y(gi)n(v)o(en)e(by)h FK(msg)p FN(,)i(or)f FJ(None)p FN(.)38 b(Note)25 b(that)g(using)f FJ(failIfEqual\(\))f FN(impro)o(v)o(es)g(upon)h(doing)f(the)i (comparison)e(as)i(the)g(\002rst)208 3090 y(parameter)c(to)i FJ(failUnless\(\))f FN(is)h(that)h(the)f(def)o(ault)f(v)n(alue)g(for)h FK(msg)g FN(can)g(be)g(computed)e(to)i(include)f(representations)f(of) 208 3189 y(both)e FK(\002r)o(st)k FN(and)c FK(second)r FN(.)0 3336 y FD(assertAlmostEqual)p FJ(\()p FK(\002r)o(st,)e(second)r FC([)p FK(,)j(places)p FC([)p FK(,)f(msg)12 b FC(])g(])p FJ(\))0 3436 y FD(failUnlessAlmostEqual)p FJ(\()p FK(\002r)o(st,)17 b(second)r FC([)p FK(,)i(places)p FC([)p FK(,)g(msg)12 b FC(])g(])p FJ(\))208 3535 y FN(T)-6 b(est)24 b(that)g FK(\002r)o(st)i FN(and)e FK(second)h FN(are)f(approximately)d(equal)i (by)h(computing)d(the)j(dif)n(ference,)f(rounding)e(to)j(the)g(gi)n(v)o (en)e(number)208 3635 y(of)k FK(places)p FN(,)h(and)f(comparing)e(to)j (zero.)43 b(Note)26 b(that)h(comparing)d(a)j(gi)n(v)o(en)e(number)g(of) h(decimal)g(places)g(is)i(not)e(the)g(same)h(as)208 3735 y(comparing)22 b(a)j(gi)n(v)o(en)f(number)f(of)h(signi\002cant)h (digits.)39 b(If)25 b(the)f(v)n(alues)h(do)f(not)h(compare)e(equal,)i (the)g(test)h(will)f(f)o(ail)h(with)f(the)208 3834 y(e)o(xplanation)17 b(gi)n(v)o(en)i(by)h FK(msg)p FN(,)g(or)g FJ(None)p FN(.)0 3981 y FD(assertNotAlmostEqual)p FJ(\()p FK(\002r)o(st,)d(second)r FC([)p FK(,)i(places)p FC([)p FK(,)g(msg)12 b FC(])g(])p FJ(\))0 4081 y FD(failIfAlmostEqual)p FJ(\()p FK(\002r)o(st,)17 b(second)r FC([)p FK(,)j(places)p FC([)p FK(,)f(msg)12 b FC(])g(])p FJ(\))208 4180 y FN(T)-6 b(est)16 b(that)h FK(\002r)o(st)h FN(and)e FK(second)i FN(are)e(not)g(approximately)d (equal)j(by)f(computing)f(the)j(dif)n(ference,)d(rounding)g(to)i(the)g (gi)n(v)o(en)f(number)208 4280 y(of)26 b FK(places)p FN(,)h(and)f(comparing)e(to)j(zero.)43 b(Note)26 b(that)h(comparing)d (a)j(gi)n(v)o(en)e(number)g(of)h(decimal)g(places)g(is)i(not)e(the)g (same)h(as)208 4380 y(comparing)22 b(a)j(gi)n(v)o(en)f(number)f(of)h (signi\002cant)h(digits.)39 b(If)25 b(the)f(v)n(alues)h(do)f(not)h (compare)e(equal,)i(the)g(test)h(will)f(f)o(ail)h(with)f(the)208 4479 y(e)o(xplanation)17 b(gi)n(v)o(en)i(by)h FK(msg)p FN(,)g(or)g FJ(None)p FN(.)0 4626 y FD(assertRaises)p FJ(\()p FK(e)n(xception,)d(callable)o(,)i(...)p FJ(\))0 4726 y FD(failUnlessRaises)p FJ(\()p FK(e)n(xception,)d(callable)o(,)j (...)p FJ(\))208 4825 y FN(T)-6 b(est)23 b(that)g(an)g(e)o(xception)e (is)j(raised)e(when)h FK(callable)f FN(is)h(called)g(with)g(an)o(y)f (positional)g(or)h(k)o(e)o(yw)o(ord)e(ar)o(guments)f(that)j(are)g(also) 208 4925 y(passed)f(to)g FJ(assertRaises\(\))p FN(.)30 b(The)22 b(test)h(passes)g(if)g FK(e)n(xception)e FN(is)i(raised,)g(is) g(an)f(error)g(if)g(another)f(e)o(xception)g(is)i(raised,)208 5025 y(or)d(f)o(ails)g(if)h(no)f(e)o(xception)e(is)j(raised.)k(T)-7 b(o)21 b(catch)f(an)o(y)f(of)h(a)h(group)d(of)i(e)o(xceptions,)f(a)i (tuple)e(containing)g(the)h(e)o(xception)e(classes)208 5124 y(may)h(be)h(passed)g(as)h FK(e)n(xception)p FN(.)0 5271 y FD(failIf)p FJ(\()p FK(e)n(xpr)r FC([)p FK(,)e(msg)12 b FC(])p FJ(\))208 5371 y FN(The)17 b(in)m(v)o(erse)f(of)i(the)g FJ(failUnless\(\))e FN(method)g(is)j(the)e FJ(failIf\(\))g FN(method.)23 b(This)18 b(signals)g(a)g(test)g(f)o(ailure)f(if)h FK(e)n(xpr)i FN(is)f(true,)p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o(ame)n(w) o(or)q(k)2175 b(797)p eop end %%Page: 798 810 TeXDict begin 798 809 bop 208 83 a FN(with)20 b FK(msg)g FN(or)g FJ(None)g FN(for)g(the)g(error)f(message.)0 230 y FD(fail)p FJ(\()p FC([)p FK(msg)12 b FC(])p FJ(\))208 330 y FN(Signals)20 b(a)g(test)h(f)o(ailure)f(unconditionally)-5 b(,)16 b(with)21 b FK(msg)f FN(or)g FJ(None)g FN(for)g(the)g(error)f (message.)0 476 y FD(failureException)208 576 y FN(This)31 b(class)g(attrib)n(ute)g(gi)n(v)o(es)f(the)h(e)o(xception)e(raised)i (by)f(the)h FJ(test\(\))f FN(method.)56 b(If)31 b(a)g(test)h(frame)n(w) o(ork)d(needs)h(to)h(use)g(a)208 676 y(specialized)19 b(e)o(xception,)g(possibly)g(to)i(carry)e(additional)h(information,)d (it)k(must)g(subclass)g(this)f(e)o(xception)f(in)h(order)g(to)g (\223play)208 775 y(f)o(air\224)g(with)g(the)g(frame)n(w)o(ork.)j(The)d (initial)g(v)n(alue)g(of)g(this)g(attrib)n(ute)g(is)h FJ(AssertionError)p FN(.)0 922 y(T)-6 b(esting)20 b(frame)n(w)o(orks)e (can)i(use)h(the)f(follo)n(wing)f(methods)g(to)h(collect)g(information) e(on)i(the)g(test:)0 1069 y FD(countTestCases)p FJ(\(\))208 1169 y FN(Return)f(the)i(number)d(of)i(tests)h(represented)e(by)g(this) i(test)g(object.)k(F)o(or)19 b FJ(TestCase)h FN(instances,)f(this)i (will)g(al)o(w)o(ays)g(be)f FJ(1)p FN(.)0 1316 y FD(defaultTestResult)p FJ(\(\))208 1415 y FN(Return)i(an)g(instance)g(of)g(the)h(test)g (result)f(class)i(that)e(should)g(be)g(used)g(for)g(this)h(test)g(case) g(class)g(\(if)g(no)f(other)f(result)i(instance)208 1515 y(is)e(pro)o(vided)c(to)k(the)f FJ(run\(\))g FN(method\).)208 1648 y(F)o(or)i FJ(TestCase)f FN(instances,)i(this)f(will)i(al)o(w)o (ays)e(be)h(an)f(instance)g(of)g FJ(TestResult)p FN(;)g(subclasses)h (of)f FJ(TestCase)g FN(should)208 1747 y(o)o(v)o(erride)17 b(this)k(as)g(necessary)-5 b(.)0 1894 y FD(id)p FJ(\(\))208 1994 y FN(Return)21 b(a)h(string)f(identifying)f(the)i(speci\002c)g (test)g(case.)30 b(This)22 b(is)h(usually)e(the)h(full)f(name)g(of)h (the)g(test)g(method,)f(including)f(the)208 2093 y(module)e(and)i (class)h(name.)0 2240 y FD(shortDescription)p FJ(\(\))208 2340 y FN(Returns)g(a)g(one-line)f(description)g(of)h(the)g(test,)h(or) f FJ(None)g FN(if)h(no)f(description)e(has)j(been)e(pro)o(vided.)26 b(The)21 b(def)o(ault)f(implemen-)208 2439 y(tation)f(of)h(this)h (method)e(returns)g(the)h(\002rst)h(line)g(of)f(the)g(test)h(method')-5 b(s)19 b(docstring,)g(if)h(a)n(v)n(ailable,)f(or)h FJ(None)p FN(.)0 2724 y Fv(23.3.6)101 b(T)-12 b(estSuite)28 b(Objects)0 2927 y FJ(TestSuite)d FN(objects)i(beha)n(v)o(e)e(much)g(lik)o(e)i FJ(TestCase)e FN(objects,)j(e)o(xcept)d(the)o(y)h(do)g(not)g(actually)g (implement)f(a)i(test.)44 b(Instead,)0 3027 y(the)o(y)18 b(are)h(used)g(to)g(aggre)o(gate)d(tests)21 b(into)d(groups)g(of)g (tests)i(that)g(should)d(be)i(run)g(together)-5 b(.)23 b(Some)c(additional)e(methods)h(are)h(a)n(v)n(ailable)0 3127 y(to)h(add)g(tests)h(to)g FJ(TestSuite)e FN(instances:)0 3273 y FD(addTest)p FJ(\()p FK(test)q FJ(\))208 3373 y FN(Add)g(a)i FJ(TestCase)e FN(or)h FJ(TestSuite)f FN(to)h(the)h (suite.)0 3520 y FD(addTests)p FJ(\()p FK(tests)p FJ(\))208 3620 y FN(Add)e(all)i(the)f(tests)i(from)d(an)h(iterable)g(of)g FJ(TestCase)f FN(and)g FJ(TestSuite)h FN(instances)g(to)g(this)h(test)g (suite.)208 3752 y(This)f(is)h(equi)n(v)n(alent)e(to)h(iterating)f(o)o (v)o(er)g FK(tests)p FN(,)i(calling)f FJ(addTest\(\))f FN(for)h(each)f(element.)0 3899 y FJ(TestSuite)g FN(shares)h(the)h (follo)n(wing)d(methods)h(with)i FJ(TestCase)p FN(:)0 4046 y FD(run)p FJ(\()p FK(r)m(esult)q FJ(\))208 4146 y FN(Run)e(the)h(tests)g(associated)g(with)f(this)h(suite,)g (collecting)f(the)g(result)h(into)f(the)h(test)g(result)g(object)f (passed)g(as)h FK(r)m(esult)q FN(.)26 b(Note)19 b(that)208 4245 y(unlik)o(e)g FJ(TestCase.run\(\))p FN(,)f FJ(TestSuite.run\(\))g FN(requires)h(the)h(result)g(object)g(to)g(be)h(passed)f(in.)0 4392 y FD(debug)p FJ(\(\))208 4492 y FN(Run)f(the)h(tests)h(associated) f(with)g(this)g(suite)h(without)e(collecting)g(the)g(result.)25 b(This)20 b(allo)n(ws)g(e)o(xceptions)f(raised)g(by)h(the)g(test)g(to) 208 4591 y(be)g(propagated)d(to)j(the)g(caller)h(and)e(can)h(be)g(used) g(to)h(support)d(running)g(tests)k(under)d(a)h(deb)n(ugger)-5 b(.)0 4738 y FD(countTestCases)p FJ(\(\))208 4838 y FN(Return)19 b(the)i(number)d(of)i(tests)h(represented)e(by)g(this)i(test)g(object,) f(including)e(all)j(indi)n(vidual)d(tests)k(and)d(sub-suites.)0 4985 y(In)24 b(the)h(typical)f(usage)h(of)f(a)h FJ(TestSuite)f FN(object,)h(the)f FJ(run\(\))h FN(method)e(is)j(in)m(v)n(ok)o(ed)d(by) h(a)h FJ(TestRunner)e FN(rather)h(than)g(by)h(the)0 5084 y(end-user)19 b(test)i(harness.)p 0 5549 3901 4 v 0 5649 a FI(798)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 799 811 TeXDict begin 799 810 bop 0 83 a Fv(23.3.7)101 b(T)-12 b(estResult)27 b(Objects)0 286 y FN(A)i FJ(TestResult)f FN(object)g(stores)i(the)f(results)g(of)f(a)i(set)g(of)e(tests.)52 b(The)29 b FJ(TestCase)f FN(and)g FJ(TestSuite)g FN(classes)i(ensure)e (that)0 386 y(results)21 b(are)f(properly)e(recorded;)g(test)j(authors) e(do)h(not)g(need)f(to)i(w)o(orry)e(about)g(recording)f(the)i(outcome)f (of)h(tests.)0 532 y(T)-6 b(esting)25 b(frame)n(w)o(orks)e(b)n(uilt)i (on)g(top)f(of)h FJ(unittest)f FN(may)h(w)o(ant)g(access)g(to)h(the)f FJ(TestResult)e FN(object)i(generated)e(by)i(running)0 632 y(a)e(set)g(of)f(tests)i(for)d(reporting)g(purposes;)h(a)h FJ(TestResult)e FN(instance)h(is)h(returned)e(by)h(the)g FJ(TestRunner.run\(\))e FN(method)h(for)0 732 y(this)g(purpose.)0 879 y FJ(TestResult)f FN(instances)g(ha)n(v)o(e)h(the)g(follo)n(wing)e (attrib)n(utes)i(that)g(will)g(be)g(of)g(interest)g(when)f(inspecting)g (the)h(results)g(of)f(running)f(a)0 978 y(set)i(of)f(tests:)0 1125 y FD(errors)208 1225 y FN(A)26 b(list)h(containing)d(2-tuples)h (of)g FJ(TestCase)g FN(instances)h(and)f(strings)h(holding)e(formatted) h(tracebacks.)40 b(Each)26 b(tuple)f(rep-)208 1324 y(resents)g(a)g (test)h(which)f(raised)f(an)h(une)o(xpected)e(e)o(xception.)77 b(Changed)24 b(in)h(v)o(ersion)f(2.2:)g(Contains)h(formatted)f (tracebacks)208 1424 y(instead)c(of)f FJ(sys.exc_info\(\))g FN(results.)0 1571 y FD(failures)208 1670 y FN(A)51 b(list)h (containing)d(2-tuples)h(of)h FJ(TestCase)f FN(instances)h(and)g (strings)g(holding)e(formatted)h(tracebacks.)116 b(Each)208 1770 y(tuple)52 b(represents)g(a)h(test)h(where)e(a)h(f)o(ailure)g(w)o (as)g(e)o(xplicitly)f(signalled)g(using)h(the)f FJ(TestCase.fail)3630 1785 y(*)3680 1770 y(\(\))f FN(or)208 1870 y FJ(TestCase.assert)958 1885 y(*)1008 1870 y(\(\))34 b FN(methods.)151 b(Changed)35 b(in)j(v)o(ersion)d(2.2:)i(Contains)g(formatted)e(tracebacks)h(instead) h(of)208 1969 y FJ(sys.exc_info\(\))18 b FN(results.)0 2116 y FD(testsRun)208 2216 y FN(The)h(total)i(number)d(of)i(tests)h (run)f(so)g(f)o(ar)-5 b(.)0 2363 y FD(wasSuccessful)p FJ(\(\))208 2462 y FN(Returns)20 b FJ(True)g FN(if)g(all)h(tests)g(run) f(so)g(f)o(ar)g(ha)n(v)o(e)g(passed,)g(otherwise)f(returns)h FJ(False)p FN(.)0 2609 y FD(stop)p FJ(\(\))208 2709 y FN(This)44 b(method)f(can)i(be)f(called)g(to)h(signal)f(that)h(the)g (set)g(of)f(tests)i(being)d(run)h(should)g(be)g(aborted)f(by)h(setting) h(the)208 2808 y FJ(TestResult)p FN(')-5 b(s)24 b FJ(shouldStop)g FN(attrib)n(ute)h(to)h FJ(True)p FN(.)41 b FJ(TestRunner)24 b FN(objects)h(should)g(respect)g(this)h(\003ag)g(and)f(return)208 2908 y(without)19 b(running)f(an)o(y)h(additional)g(tests.)208 3041 y(F)o(or)27 b(e)o(xample,)g(this)h(feature)e(is)i(used)f(by)g(the) h FJ(TextTestRunner)d FN(class)j(to)g(stop)f(the)g(test)h(frame)n(w)o (ork)e(when)g(the)i(user)208 3141 y(signals)19 b(an)g(interrupt)e(from) h(the)i(k)o(e)o(yboard.)i(Interacti)n(v)o(e)17 b(tools)i(which)g(pro)o (vide)e FJ(TestRunner)g FN(implementations)g(can)i(use)208 3240 y(this)h(in)h(a)f(similar)h(manner)-5 b(.)0 3387 y(The)31 b(follo)n(wing)f(methods)h(of)h(the)f FJ(TestResult)g FN(class)h(are)g(used)g(to)f(maintain)g(the)h(internal)f(data)g (structures,)j(and)d(may)h(be)0 3487 y(e)o(xtended)17 b(in)h(subclasses)i(to)e(support)g(additional)f(reporting)f (requirements.)23 b(This)c(is)g(particularly)e(useful)h(in)h(b)n (uilding)e(tools)i(which)0 3586 y(support)g(interacti)n(v)o(e)g (reporting)f(while)i(tests)h(are)g(being)e(run.)0 3733 y FD(startTest)p FJ(\()p FK(test)q FJ(\))208 3833 y FN(Called)h(when)g (the)g(test)h(case)g FK(test)h FN(is)f(about)e(to)i(be)f(run.)208 3966 y(The)f(def)o(ault)h(implementation)e(simply)i(increments)f(the)h (instance')-5 b(s)20 b FJ(testsRun)f FN(counter)-5 b(.)0 4112 y FD(stopTest)p FJ(\()p FK(test)q FJ(\))208 4212 y FN(Called)20 b(after)g(the)g(test)h(case)g FK(test)h FN(has)f(been)e(e)o(x)o(ecuted,)f(re)o(gardless)h(of)h(the)g(outcome.) 208 4345 y(The)f(def)o(ault)h(implementation)e(does)i(nothing.)0 4492 y FD(addError)p FJ(\()p FK(test,)f(err)r FJ(\))208 4591 y FN(Called)f(when)f(the)h(test)h(case)f FK(test)j FN(raises)d(an)g(une)o(xpected)e(e)o(xception)g FK(err)21 b FN(is)d(a)h(tuple)e(of)h(the)g(form)f(returned)f(by)i FJ(sys.exc_-)208 4691 y(info\(\))p FN(:)24 b FJ(\()p FK(type)p FJ(,)49 b FK(value)p FJ(,)f FK(tr)o(acebac)n(k)q FJ(\))p FN(.)208 4824 y(The)19 b(def)o(ault)h(implementation)e(appends) h FJ(\()p FK(test)q FJ(,)50 b FK(err)r FJ(\))21 b FN(to)f(the)g (instance')-5 b(s)21 b FJ(errors)e FN(attrib)n(ute.)0 4971 y FD(addFailure)p FJ(\()p FK(test,)g(err)r FJ(\))208 5070 y FN(Called)28 b(when)g(the)g(test)i(case)e FK(test)j FN(signals)e(a)f(f)o(ailure.)49 b FK(err)31 b FN(is)f(a)e(tuple)g(of)g (the)h(form)e(returned)g(by)h FJ(sys.exc_info\(\))p FN(:)208 5170 y FJ(\()p FK(type)p FJ(,)48 b FK(value)p FJ(,)h FK(tr)o(acebac)n(k)q FJ(\))p FN(.)208 5303 y(The)19 b(def)o(ault)h (implementation)e(appends)h FJ(\()p FK(test)q FJ(,)50 b FK(err)r FJ(\))21 b FN(to)f(the)g(instance')-5 b(s)21 b FJ(failures)e FN(attrib)n(ute.)p 0 5549 3901 4 v 0 5649 a FI(23.3.)52 b FJ(unittest)22 b FI(\227)h(Unit)h(testing)f(fr)o (ame)n(w)o(or)q(k)2175 b(799)p eop end %%Page: 800 812 TeXDict begin 800 811 bop 0 83 a FD(addSuccess)p FJ(\()p FK(test)q FJ(\))208 183 y FN(Called)20 b(when)g(the)g(test)h(case)g FK(test)h FN(succeeds.)208 315 y(The)d(def)o(ault)h(implementation)e (does)i(nothing.)0 600 y Fv(23.3.8)101 b(T)-12 b(estLoader)29 b(Objects)0 803 y FN(The)50 b FJ(TestLoader)f FN(class)i(is)g(used)f (to)g(create)g(test)h(suites)g(from)e(classes)j(and)d(modules.)114 b(Normally)-5 b(,)56 b(there)50 b(is)h(no)0 903 y(need)41 b(to)h(create)f(an)g(instance)g(of)h(this)g(class;)53 b(the)41 b FJ(unittest)g FN(module)f(pro)o(vides)g(an)h(instance)h (that)f(can)h(be)f(shared)g(as)0 1003 y FJ(unittest.defaultTestLoader)p FN(.)j(Using)28 b(a)h(subclass)f(or)g(instance,)h(ho)n(we)n(v)o(er)m(,) f(allo)n(ws)g(customization)f(of)h(some)f(con-)0 1102 y(\002gurable)19 b(properties.)0 1249 y FJ(TestLoader)g FN(objects)h(ha)n(v)o(e)f(the)i(follo)n(wing)d(methods:)0 1396 y FD(loadTestsFromTestCase)p FJ(\()p FK(testCaseClass)p FJ(\))208 1496 y FN(Return)h(a)i(suite)f(of)g(all)h(tests)h(cases)e (contained)f(in)h(the)h FJ(TestCase)p FN(-deri)n(v)o(ed)16 b FJ(testCaseClass)p FN(.)0 1642 y FD(loadTestsFromModule)p FJ(\()p FK(module)p FJ(\))208 1742 y FN(Return)i(a)i(suite)g(of)f(all)h (tests)g(cases)g(contained)e(in)h(the)g(gi)n(v)o(en)f(module.)24 b(This)19 b(method)f(searches)h FK(module)f FN(for)h(classes)h(deri)n (v)o(ed)208 1842 y(from)f FJ(TestCase)g FN(and)h(creates)g(an)g (instance)g(of)g(the)g(class)h(for)f(each)f(test)j(method)c(de\002ned)i (for)f(the)h(class.)208 1974 y FL(W)-5 b(ar)o(ning:)40 b FN(While)29 b(using)e(a)i(hierarchy)d(of)i FJ(TestCase)p FN(-deri)n(v)o(ed)d(classes)k(can)f(be)h(con)m(v)o(enient)c(in)k (sharing)e(\002xtures)h(and)208 2074 y(helper)20 b(functions,)f (de\002ning)h(test)i(methods)f(on)f(base)i(classes)g(that)f(are)g(not)g (intended)f(to)h(be)g(instantiated)g(directly)f(does)h(not)208 2174 y(play)27 b(well)h(with)f(this)h(method.)46 b(Doing)26 b(so,)k(ho)n(we)n(v)o(er)m(,)d(can)g(be)g(useful)g(when)g(the)h (\002xtures)f(are)g(dif)n(ferent)f(and)h(de\002ned)f(in)208 2273 y(subclasses.)0 2420 y FD(loadTestsFromName)p FJ(\()p FK(name)p FC([)p FK(,)16 b(module)c FC(])p FJ(\))208 2520 y FN(Return)19 b(a)i(suite)f(of)g(all)h(tests)h(cases)e(gi)n(v)o (en)f(a)i(string)f(speci\002er)-5 b(.)208 2653 y(The)17 b(speci\002er)h FK(name)g FN(is)h(a)f(\223dotted)f(name\224)g(that)i (may)e(resolv)o(e)g(either)h(to)g(a)h(module,)e(a)h(test)h(case)f (class,)i(a)e(test)h(method)e(within)208 2752 y(a)29 b(test)i(case)e(class,)k(a)d FJ(TestSuite)e FN(instance,)j(or)e(a)h (callable)f(object)g(which)g(returns)f(a)i FJ(TestCase)f FN(or)g FJ(TestSuite)208 2852 y FN(instance.)24 b(These)c(checks)f(are) h(applied)f(in)h(the)g(order)f(listed)i(here;)e(that)h(is,)h(a)f (method)f(on)h(a)g(possible)g(test)h(case)f(class)h(will)g(be)208 2952 y(pick)o(ed)e(up)h(as)h(\223a)f(test)h(method)e(within)h(a)g(test) i(case)e(class\224,)h(rather)e(than)h(\223a)g(callable)g(object\224.) 208 3084 y(F)o(or)15 b(e)o(xample,)g(if)h(you)f(ha)n(v)o(e)g(a)h (module)f FJ(SampleTests)f FN(containing)g(a)i FJ(TestCase)p FN(-deri)n(v)o(ed)c(class)17 b FJ(SampleTestCase)208 3184 y FN(with)80 b(three)f(test)i(methods)d(\()p FJ(test_one\(\))p FN(,)93 b FJ(test_two\(\))p FN(,)g(and)79 b FJ(test_three\(\))p FN(\),)93 b(the)80 b(speci\002er)208 3284 y FJ ('SampleTests.SampleTestCase')41 b FN(w)o(ould)k(cause)g(this)h(method) f(to)h(return)e(a)i(suite)g(which)g(will)g(run)f(all)208 3383 y(three)24 b(test)i(methods.)40 b(Using)25 b(the)g(speci\002er)g FJ('SampleTests.SampleTestCase.test_two)o(')20 b FN(w)o(ould)25 b(cause)g(it)208 3483 y(to)20 b(return)f(a)h(test)h(suite)g(which)e (will)i(run)e(only)h(the)g FJ(test_two\(\))f FN(test)h(method.)k(The)c (speci\002er)g(can)g(refer)f(to)h(modules)f(and)208 3583 y(packages)g(which)g(ha)n(v)o(e)h(not)g(been)f(imported;)g(the)o(y)g (will)i(be)f(imported)f(as)i(a)f(side-ef)n(fect.)208 3715 y(The)f(method)g(optionally)g(resolv)o(es)g FK(name)h FN(relati)n(v)o(e)f(to)i(the)f(gi)n(v)o(en)f FK(module)p FN(.)0 3862 y FD(loadTestsFromNames)p FJ(\()p FK(names)p FC([)p FK(,)d(module)c FC(])p FJ(\))208 3962 y FN(Similar)26 b(to)g FJ(loadTestsFromName\(\))p FN(,)f(b)n(ut)h(tak)o(es)g(a)h (sequence)e(of)h(names)g(rather)f(than)h(a)g(single)h(name.)42 b(The)26 b(return)208 4062 y(v)n(alue)19 b(is)i(a)g(test)g(suite)f (which)g(supports)f(all)i(the)f(tests)i(de\002ned)d(for)g(each)h(name.) 0 4208 y FD(getTestCaseNames)p FJ(\()p FK(testCaseClass)p FJ(\))208 4308 y FN(Return)c(a)h(sorted)f(sequence)f(of)h(method)g (names)g(found)f(within)h FK(testCaseClass)p FN(;)j(this)f(should)d(be) i(a)g(subclass)f(of)h FJ(TestCase)p FN(.)0 4455 y(The)j(follo)n(wing)e (attrib)n(utes)j(of)e(a)i FJ(TestLoader)e FN(can)h(be)g(con\002gured)e (either)i(by)f(subclassing)h(or)g(assignment)f(on)h(an)g(instance:)0 4602 y FD(testMethodPrefix)208 4701 y FN(String)32 b(gi)n(ving)g(the)h (pre\002x)g(of)g(method)f(names)h(which)f(will)i(be)f(interpreted)f(as) i(test)g(methods.)63 b(The)33 b(def)o(ault)f(v)n(alue)h(is)208 4801 y FJ('test')p FN(.)208 4934 y(This)20 b(af)n(fects)g FJ(getTestCaseNames\(\))d FN(and)j(all)h(the)f FJ(loadTestsFrom)2550 4949 y(*)2600 4934 y(\(\))e FN(methods.)0 5081 y FD (sortTestMethodsUsing)208 5180 y FN(Function)28 b(to)h(be)g(used)g(to)h (compare)e(method)g(names)h(when)f(sorting)h(them)g(in)g FJ(getTestCaseNames\(\))e FN(and)i(all)h(the)208 5280 y FJ(loadTestsFrom)858 5295 y(*)908 5280 y(\(\))17 b FN(methods.)24 b(The)19 b(def)o(ault)h(v)n(alue)f(is)i(the)e(b)n (uilt-in)h FJ(cmp\(\))f FN(function;)g(the)h(attrib)n(ute)f(can)h(also) g(be)g(set)208 5380 y(to)g FJ(None)g FN(to)g(disable)g(the)g(sort.)p 0 5549 3901 4 v 0 5649 a FI(800)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 801 813 TeXDict begin 801 812 bop 0 83 a FD(suiteClass)208 183 y FN(Callable)24 b(object)g(that)h(constructs)e(a)i(test)g(suite)g (from)e(a)i(list)h(of)e(tests.)38 b(No)25 b(methods)e(on)h(the)g (resulting)g(object)g(are)g(needed.)208 282 y(The)19 b(def)o(ault)h(v)n(alue)f(is)j(the)e FJ(TestSuite)f FN(class.)208 415 y(This)h(af)n(fects)g(all)h(the)f FJ(loadTestsFrom)1492 430 y(*)1542 415 y(\(\))e FN(methods.)0 743 y FE(23.4)121 b Fx(test)32 b FE(\227)h(Reg)o(ression)i(tests)e(pac)n(kage)i(f)l(or)f (Python)0 975 y FN(The)e FJ(test)g FN(package)e(contains)i(all)g(re)o (gression)f(tests)i(for)e(Python)g(as)i(well)g(as)g(the)f(modules)f FJ(test.test_support)e FN(and)0 1075 y FJ(test.regrtest)p FN(.)c FJ(test.test_support)19 b FN(is)j(used)e(to)h(enhance)f(your)g (tests)i(while)f FJ(test.regrtest)e FN(dri)n(v)o(es)h(the)h(test-)0 1175 y(ing)f(suite.)0 1321 y(Each)f(module)f(in)i(the)f FJ(test)h FN(package)e(whose)h(name)g(starts)h(with)g(`)p FJ(test_)p FN(')e(is)j(a)f(testing)f(suite)h(for)f(a)h(speci\002c)f (module)g(or)g(feature.)0 1421 y(All)25 b(ne)n(w)e(tests)i(should)e(be) h(written)g(using)f(the)h FJ(unittest)f FN(module;)h(using)g FJ(unittest)e FN(is)j(not)f(required)e(b)n(ut)i(mak)o(es)f(the)h(tests) 0 1521 y(more)g(\003e)o(xible)h(and)f(maintenance)f(of)i(the)g(tests)h (easier)-5 b(.)40 b(Some)25 b(older)f(tests)i(are)f(written)g(to)g(use) g FJ(doctest)f FN(and)h(a)g(\223traditional\224)0 1620 y(testing)20 b(style;)h(these)f(styles)h(of)f(tests)h(will)g(not)f(be)g (co)o(v)o(ered.)0 1767 y FL(See)h(Also:)0 1914 y FN(Module)e FJ(unittest)g FN(\(section)h(23.3\):)208 2014 y(Writing)g(PyUnit)g(re)o (gression)e(tests.)0 2161 y(Module)h FJ(doctest)g FN(\(section)h (23.2\):)208 2260 y(T)-6 b(ests)21 b(embedded)d(in)i(documentation)d (strings.)0 2545 y Fv(23.4.1)101 b(Wr)q(iting)29 b(Unit)f(T)-12 b(ests)27 b(f)m(or)h(the)g Fm(test)f Fv(pac)n(kage)0 2748 y FN(It)18 b(is)h(preferred)d(that)i(tests)h(for)e(the)h FJ(test)g FN(package)e(use)i(the)g FJ(unittest)f FN(module)g(and)g (follo)n(w)g(a)i(fe)n(w)e(guidelines.)23 b(One)18 b(is)h(to)f(name)0 2848 y(the)j(test)h(module)d(by)i(starting)g(it)g(with)g(`)p FJ(test_)p FN(')f(and)h(end)f(it)i(with)f(the)g(name)f(of)h(the)g (module)f(being)g(tested.)27 b(The)21 b(test)h(methods)d(in)0 2947 y(the)24 b(test)h(module)e(should)g(start)i(with)f(`)p FJ(test_)p FN(')f(and)h(end)g(with)g(a)h(description)d(of)i(what)g(the) h(method)d(is)k(testing.)36 b(This)25 b(is)g(needed)0 3047 y(so)f(that)h(the)f(methods)f(are)h(recognized)d(by)j(the)g(test)h (dri)n(v)o(er)e(as)h(test)h(methods.)36 b(Also,)25 b(no)f (documentation)d(string)i(for)h(the)g(method)0 3147 y(should)c(be)h (included.)26 b(A)21 b(comment)f(\(such)g(as)i(`)p FJ(#Tests)48 b(function)h(returns)f(only)h(True)g(or)h(False)p FN('\))20 b(should)g(be)0 3246 y(used)25 b(to)g(pro)o(vide)d(documentation)g(for) i(test)i(methods.)38 b(This)25 b(is)h(done)d(because)i(documentation)c (strings)k(get)g(printed)f(out)g(if)h(the)o(y)0 3346 y(e)o(xist)20 b(and)g(thus)g(what)g(test)h(is)g(being)f(run)f(is)i(not) f(stated.)0 3493 y(A)h(basic)f(boilerplate)f(is)i(often)e(used:)p 0 5549 3901 4 v 0 5649 a FI(23.4.)52 b FJ(test)23 b FI(\227)g(Reg)o (ression)g(tests)f(pac)n(kage)h(f)n(or)g(Python)1846 b(801)p eop end %%Page: 802 814 TeXDict begin 802 813 bop 236 174 a FA(import)44 b(unittest)236 266 y(from)g(test)h(import)e(test_support)236 448 y(class)h (MyTestCase1\(unittest.TestCase\):)416 631 y(#)g(Only)g(use)h (setUp\(\))e(and)i(tearDown\(\))e(if)h(necessary)416 814 y(def)g(setUp\(self\):)595 905 y(...)g(code)g(to)h(execute)f(in)g (preparation)f(for)h(tests)g(...)416 1088 y(def)g(tearDown\(self\):)595 1179 y(...)g(code)g(to)h(execute)f(to)g(clean)g(up)g(after)g(tests)g (...)416 1362 y(def)g(test_feature_one\(self\):)595 1453 y(#)h(Test)f(feature)f(one.)595 1544 y(...)h(testing)g(code)g(...)416 1727 y(def)g(test_feature_two\(self\):)595 1818 y(#)h(Test)f(feature)f (two.)595 1910 y(...)h(testing)g(code)g(...)416 2092 y(...)g(more)g(test)g(methods)g(...)236 2275 y(class)g (MyTestCase2\(unittest.TestCase\):)416 2366 y(...)g(same)g(structure)f (as)i(MyTestCase1)e(...)236 2549 y(...)i(more)f(test)g(classes)g(...) 236 2731 y(def)h(test_main\(\):)416 2823 y (test_support.run_unittest\(MyTestCase)o(1,)1581 2914 y(MyTestCase2,)1581 3005 y(...)g(list)f(other)g(tests)g(...)1536 3097 y(\))236 3279 y(if)h(__name__)e(==)i('__main__':)416 3371 y(test_main\(\))0 3657 y FN(This)20 b(boilerplate)f(code)h(allo)n (ws)g(the)g(testing)h(suite)f(to)g(be)h(run)e(by)h FJ(test.regrtest)e FN(as)j(well)g(as)g(on)e(its)j(o)n(wn)d(as)i(a)g(script.)0 3804 y(The)f(goal)g(for)f(re)o(gression)g(testing)h(is)h(to)g(try)e(to) i(break)e(code.)24 b(This)d(leads)f(to)g(a)h(fe)n(w)f(guidelines)f(to)h (be)h(follo)n(wed:)125 4013 y FM(\017)41 b FN(The)24 b(testing)h(suite)h(should)e(e)o(x)o(ercise)g(all)i(classes,)h (functions,)e(and)g(constants.)39 b(This)25 b(includes)g(not)g(just)g (the)g(e)o(xternal)f(API)208 4113 y(that)c(is)h(to)f(be)g(presented)f (to)i(the)f(outside)f(w)o(orld)h(b)n(ut)g(also)h(\224pri)n(v)n(ate\224) e(code.)125 4271 y FM(\017)41 b FN(Whitebox)27 b(testing)h(\(e)o (xamining)e(the)i(code)g(being)f(tested)i(when)e(the)i(tests)g(are)f (being)g(written\))g(is)h(preferred.)47 b(Blackbox)208 4370 y(testing)24 b(\(testing)h(only)e(the)i(published)e(user)i(interf) o(ace\))e(is)j(not)e(complete)g(enough)e(to)j(mak)o(e)f(sure)h(all)g (boundary)d(and)i(edge)208 4470 y(cases)c(are)h(tested.)125 4628 y FM(\017)41 b FN(Mak)o(e)24 b(sure)g(all)h(possible)f(v)n(alues)g (are)g(tested)h(including)d(in)m(v)n(alid)h(ones.)37 b(This)25 b(mak)o(es)f(sure)g(that)h(not)f(only)f(all)i(v)n(alid)f(v)n (alues)208 4727 y(are)c(acceptable)f(b)n(ut)h(also)g(that)h(improper)d (v)n(alues)i(are)g(handled)e(correctly)-5 b(.)125 4885 y FM(\017)41 b FN(Exhaust)16 b(as)i(man)o(y)f(code)g(paths)g(as)h (possible.)24 b(T)-6 b(est)18 b(where)f(branching)f(occurs)g(and)h (thus)h(tailor)f(input)g(to)h(mak)o(e)f(sure)g(as)i(man)o(y)208 4985 y(dif)n(ferent)f(paths)i(through)e(the)i(code)g(are)g(tak)o(en.) 125 5143 y FM(\017)41 b FN(Add)18 b(an)i(e)o(xplicit)e(test)j(for)d(an) o(y)h(b)n(ugs)g(disco)o(v)o(ered)e(for)i(the)g(tested)h(code.)k(This)19 b(will)h(mak)o(e)f(sure)g(that)h(the)f(error)f(does)h(not)g(crop)208 5242 y(up)g(again)g(if)i(the)f(code)g(is)h(changed)d(in)j(the)f (future.)125 5400 y FM(\017)41 b FN(Mak)o(e)20 b(sure)g(to)g(clean)g (up)g(after)f(your)g(tests)j(\(such)d(as)i(close)g(and)e(remo)o(v)o(e)g (all)h(temporary)e(\002les\).)p 0 5549 3901 4 v 0 5649 a FI(802)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 803 815 TeXDict begin 803 814 bop 125 83 a FM(\017)41 b FN(If)27 b(a)g(test)h(is)g(dependent)d(on)i(a)h(speci\002c)f(condition)e(of)i (the)g(operating)f(system)h(then)g(v)o(erify)f(the)h(condition)e (already)h(e)o(xists)208 183 y(before)18 b(attempting)h(the)h(test.)125 346 y FM(\017)41 b FN(Import)19 b(as)i(fe)n(w)g(modules)f(as)i (possible)e(and)g(do)h(it)g(as)h(soon)e(as)i(possible.)k(This)21 b(minimizes)g(e)o(xternal)e(dependencies)g(of)h(tests)208 445 y(and)f(also)i(minimizes)e(possible)h(anomalous)f(beha)n(vior)f (from)i(side-ef)n(fects)f(of)h(importing)e(a)j(module.)125 608 y FM(\017)41 b FN(T)m(ry)22 b(to)h(maximize)e(code)h(reuse.)33 b(On)22 b(occasion,)g(tests)i(will)g(v)n(ary)e(by)g(something)f(as)j (small)f(as)g(what)g(type)f(of)g(input)g(is)i(used.)208 708 y(Minimize)19 b(code)h(duplication)e(by)i(subclassing)f(a)i(basic)f (test)h(class)h(with)e(a)h(class)g(that)f(speci\002es)h(the)f(input:) 444 931 y FA(class)44 b(TestFuncAcceptsSequences\(unittest.Test)o (Case\):)623 1113 y(func)g(=)h(mySuperWhammyFunction)623 1296 y(def)f(test_func\(self\):)802 1387 y(self.func\(self.arg\))444 1570 y(class)g(AcceptLists\(TestFuncAcceptsSequences\):)623 1661 y(arg)g(=)h([1,2,3])444 1844 y(class)f (AcceptStrings\(TestFuncAcceptsSequences)o(\):)623 1935 y(arg)g(=)h('abc')444 2118 y(class)f (AcceptTuples\(TestFuncAcceptsSequences\))o(:)623 2209 y(arg)g(=)h(\(1,2,3\))0 2572 y FL(See)21 b(Also:)0 2719 y FK(T)-8 b(est)22 b(Driven)e(De)o(velopment)208 2818 y FN(A)g(book)f(by)h(K)n(ent)g(Beck)g(on)g(writing)g(tests)h(before)e (code.)0 3102 y Fv(23.4.2)101 b(Running)29 b(tests)e(using)i Fm(test.regrtest)0 3305 y FJ(test.regrtest)16 b FN(can)i(be)h(used)f (as)g(a)h(script)f(to)h(dri)n(v)o(e)e(Python')-5 b(s)17 b(re)o(gression)g(test)i(suite.)25 b(Running)17 b(the)h(script)g(by)g (itself)h(automat-)0 3404 y(ically)g(starts)h(running)d(all)i(re)o (gression)f(tests)i(in)f(the)g FJ(test)g FN(package.)k(It)d(does)e (this)i(by)f(\002nding)f(all)h(modules)f(in)h(the)g(package)f(whose)0 3504 y(name)h(starts)h(with)f(`)p FJ(test_)p FN(',)f(importing)f(them,) i(and)g(e)o(x)o(ecuting)e(the)i(function)f FJ(test_main\(\))f FN(if)j(present.)k(The)19 b(names)f(of)h(tests)0 3603 y(to)f(e)o(x)o(ecute)e(may)h(also)h(be)g(passed)g(to)g(the)f(script.)25 b(Specifying)16 b(a)i(single)f(re)o(gression)g(test)h(\()p FL(python)f(r)o(egrtest.py)f(test)p 3403 3603 25 4 v 29 w(spam.py)p FN(\))i(will)0 3703 y(minimize)h(output)g(and)h(only)f (print)h(whether)f(the)h(test)h(passed)f(or)g(f)o(ailed)g(and)g(thus)g (minimize)g(output.)0 3850 y(Running)c FJ(test.regrtest)g FN(directly)g(allo)n(ws)i(what)g(resources)e(are)i(a)n(v)n(ailable)f (for)g(tests)h(to)g(use)g(to)g(be)f(set.)25 b(Y)-9 b(ou)17 b(do)g(this)h(by)f(using)0 3950 y(the)26 b FL(-u)g FN(command-line)c (option.)40 b(Run)26 b FL(python)f(r)o(egrtest.py)e(-uall)j FN(to)g(turn)f(on)g(all)h(resources;)h(specifying)d FL(all)i FN(as)g(an)g(option)e(for)0 4049 y FL(-u)e FN(enables)g(all)h(possible) e(resources.)30 b(If)22 b(all)g(b)n(ut)h(one)e(resource)g(is)i(desired) e(\(a)h(more)g(common)e(case\),)i(a)h(comma-separated)c(list)k(of)0 4149 y(resources)h(that)h(are)f(not)h(desired)f(may)g(be)g(listed)i (after)e FL(all)p FN(.)39 b(The)24 b(command)f FL(python)h(r)o (egrtest.py)f(-uall,-audio,-lar)o(ge\002le)f FN(will)0 4249 y(run)17 b FJ(test.regrtest)f FN(with)h(all)i(resources)d(e)o (xcept)h(the)h FL(audio)f FN(and)g FL(lar)o(ge\002le)h FN(resources.)23 b(F)o(or)17 b(a)h(list)h(of)e(all)i(resources)d(and)h (more)0 4348 y(command-line)g(options,)i(run)h FL(python)g(r)o (egrtest.py)e(-h)p FN(.)0 4495 y(Some)k(other)g(w)o(ays)h(to)f(e)o(x)o (ecute)f(the)i(re)o(gression)e(tests)j(depend)d(on)h(what)g(platform)f (the)i(tests)g(are)g(being)e(e)o(x)o(ecuted)g(on.)31 b(On)25 b(U)t FH(N)t(I)t(X)r FN(,)0 4595 y(you)f(can)h(run)f FL(mak)o(e)h(test)g FN(at)g(the)g(top-le)n(v)o(el)e(directory)g(where)h (Python)g(w)o(as)i(b)n(uilt.)38 b(On)25 b(W)m(indo)n(ws,)g(e)o(x)o (ecuting)e FL(rt.bat)h FN(from)g(your)0 4694 y(`)p FO(PCBuild)p FN(')18 b(directory)g(will)j(run)f(all)h(re)o(gression)d(tests.)0 5020 y FE(23.5)121 b Fx(test.test_support)29 b FE(\227)k(Utility)f (functions)j(f)l(or)f(tests)0 5253 y FN(The)20 b FJ(test.test_support)d FN(module)i(pro)o(vides)g(support)g(for)g(Python')-5 b(s)19 b(re)o(gression)g(tests.)0 5400 y(This)h(module)f(de\002nes)h (the)g(follo)n(wing)f(e)o(xceptions:)p 0 5549 3901 4 v 0 5649 a FI(23.5.)52 b FJ(test.test_support)20 b FI(\227)j(Utility)h (functions)g(f)n(or)e(tests)1675 b(803)p eop end %%Page: 804 816 TeXDict begin 804 815 bop 0 83 a FL(exception)19 b FD(TestFailed)208 183 y FN(Exception)f(to)i(be)g(raised)g(when)g(a)h(test)g(f)o(ails.)0 330 y FL(exception)e FD(TestSkipped)208 429 y FN(Subclass)28 b(of)h FJ(TestFailed)p FN(.)48 b(Raised)29 b(when)f(a)h(test)h(is)f (skipped.)49 b(This)29 b(occurs)e(when)h(a)h(needed)f(resource)f (\(such)h(as)h(a)208 529 y(netw)o(ork)19 b(connection\))e(is)k(not)f(a) n(v)n(ailable)g(at)h(the)f(time)g(of)g(testing.)0 676 y FL(exception)f FD(ResourceDenied)208 775 y FN(Subclass)k(of)h FJ(TestSkipped)p FN(.)34 b(Raised)24 b(when)f(a)h(resource)e(\(such)h (as)i(a)f(netw)o(ork)e(connection\))f(is)k(not)e(a)n(v)n(ailable.)35 b(Raised)208 875 y(by)19 b(the)i FJ(requires\(\))d FN(function.)0 1022 y(The)i FJ(test.test_support)d FN(module)i(de\002nes)h(the)g (follo)n(wing)f(constants:)0 1169 y FD(verbose)208 1268 y FJ(True)k FN(when)h(v)o(erbose)e(output)h(is)h(enabled.)35 b(Should)23 b(be)h(check)o(ed)e(when)h(more)g(detailed)h(information)d (is)k(desired)e(about)g(a)208 1368 y(running)18 b(test.)25 b FK(verbose)20 b FN(is)h(set)g(by)f FJ(test.regrtest)p FN(.)0 1515 y FD(have_unicode)208 1614 y FJ(True)g FN(when)f(Unicode)g (support)g(is)i(a)n(v)n(ailable.)0 1761 y FD(is_jython)208 1861 y FJ(True)f FN(if)g(the)g(running)e(interpreter)h(is)i(Jython.)0 2008 y FD(TESTFN)208 2107 y FN(Set)28 b(to)g(the)g(path)g(that)g(a)h (temporary)c(\002le)k(may)f(be)g(created)f(at.)49 b(An)o(y)27 b(temporary)f(that)i(is)h(created)e(should)g(be)h(closed)g(and)208 2207 y(unlink)o(ed)18 b(\(remo)o(v)o(ed\).)0 2354 y(The)i FJ(test.test_support)d FN(module)i(de\002nes)h(the)g(follo)n(wing)f (functions:)0 2501 y FD(forget)p FJ(\()p FK(module)p 601 2501 25 4 v 27 w(name)p FJ(\))208 2600 y FN(Remo)o(v)o(es)28 b(the)i(module)e(named)h FK(module)p 1458 2600 V 28 w(name)g FN(from)g FJ(sys.modules)f FN(and)h(deletes)h(an)o(y)f(byte-compiled)e (\002les)j(of)g(the)208 2700 y(module.)0 2847 y FD(is_resource_enabled) p FJ(\()p FK(r)m(esour)m(ce)p FJ(\))208 2946 y FN(Returns)43 b FJ(True)h FN(if)g FK(r)m(esour)m(ce)g FN(is)h(enabled)e(and)g(a)n(v)n (ailable.)96 b(The)44 b(list)h(of)f(a)n(v)n(ailable)f(resources)g(is)i (only)e(set)i(when)208 3046 y FJ(test.regrtest)18 b FN(is)j(e)o(x)o (ecuting)d(the)i(tests.)0 3193 y FD(requires)p FJ(\()p FK(r)m(esour)m(ce)p FC([)p FK(,)e(msg)12 b FC(])p FJ(\))208 3293 y FN(Raises)29 b FJ(ResourceDenied)d FN(if)i FK(r)m(esour)m(ce)g FN(is)h(not)e(a)n(v)n(ailable.)48 b FK(msg)28 b FN(is)h(the)f(ar)o (gument)e(to)i FJ(ResourceDenied)e FN(if)i(it)h(is)208 3392 y(raised.)38 b(Al)o(w)o(ays)25 b(returns)f(true)g(if)h(called)g (by)f(a)h(function)e(whose)h FJ(__name__)g FN(is)i FJ('__main__')p FN(.)37 b(Used)25 b(when)f(tests)i(are)208 3492 y(e)o(x)o(ecuted)18 b(by)i FJ(test.regrtest)p FN(.)0 3639 y FD(findfile)p FJ(\()p FK(\002lename)p FJ(\))208 3738 y FN(Return)26 b(the)g(path)h(to)f(the)h(\002le)g(named)f FK(\002lename)p FN(.)43 b(If)26 b(no)h(match)f(is)h(found)e FK(\002lename)h FN(is)h(returned.)43 b(This)26 b(does)h(not)f(equal)g(a)208 3838 y(f)o(ailure)19 b(since)i(it)f(could)g(be)g(the)g(path)g(to)g(the) g(\002le.)0 3985 y FD(run_unittest)p FJ(\()p FK(*classes)p FJ(\))208 4084 y FN(Ex)o(ecute)d FJ(unittest.TestCase)f FN(subclasses)i(passed)h(to)f(the)h(function.)j(The)c(function)f(scans) i(the)f(classes)i(for)e(methods)208 4184 y(starting)h(with)i(the)f (pre\002x)f(`)p FJ(test_)p FN(')h(and)f(e)o(x)o(ecutes)g(the)h(tests)i (indi)n(vidually)-5 b(.)22 b(This)f(is)g(the)f(preferred)e(w)o(ay)i(to) g(e)o(x)o(ecute)f(tests.)0 4331 y FD(run_suite)p FJ(\()p FK(suite)p FC([)p FK(,)f(testclass)12 b FC(])p FJ(\))208 4431 y FN(Ex)o(ecute)22 b(the)j FJ(unittest.TestSuite)c FN(instance)j FK(suite)p FN(.)37 b(The)23 b(optional)g(ar)o(gument)f FK(testclass)j FN(accepts)f(one)g(of)g(the)g(test)208 4530 y(classes)d(in)f(the)g(suite)h(so)g(as)f(to)h(print)e(out)h(more)g (detailed)f(information)f(on)i(where)f(the)i(testing)f(suite)g (originated)f(from.)p 0 5549 3901 4 v 0 5649 a FI(804)2576 b(Chapter)23 b(23.)52 b(De)n(v)n(elopment)24 b(T)-10 b(ools)p eop end %%Page: 805 817 TeXDict begin 805 816 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3057 427 y FG(TWENTYFOUR)p 0 515 V 1826 978 a FT(The)57 b(Python)h(Deb)l (ugger)0 1468 y FN(The)24 b(module)e FJ(pdb)i FN(de\002nes)g(an)g (interacti)n(v)o(e)f(source)g(code)h(deb)n(ugger)e(for)h(Python)g (programs.)35 b(It)24 b(supports)f(setting)h(\(conditional\))0 1568 y(breakpoints)17 b(and)i(single)h(stepping)e(at)i(the)f(source)g (line)h(le)n(v)o(el,)f(inspection)f(of)h(stack)h(frames,)e(source)h (code)g(listing,)g(and)g(e)n(v)n(aluation)0 1667 y(of)i(arbitrary)f (Python)g(code)g(in)h(the)h(conte)o(xt)d(of)i(an)o(y)g(stack)g(frame.) 27 b(It)22 b(also)f(supports)f(post-mortem)f(deb)n(ugging)g(and)i(can)g (be)g(called)0 1767 y(under)e(program)f(control.)0 1914 y(The)30 b(deb)n(ugger)f(is)j(e)o(xtensible)d(\227)j(it)f(is)h (actually)e(de\002ned)g(as)h(the)g(class)g FJ(Pdb)p FN(.)57 b(This)31 b(is)g(currently)e(undocumented)f(b)n(ut)i(easily)0 2013 y(understood)18 b(by)h(reading)g(the)h(source.)25 b(The)19 b(e)o(xtension)g(interf)o(ace)h(uses)g(the)g(modules)g FJ(bdb)g FN(\(undocumented\))c(and)j FJ(cmd)p FN(.)0 2160 y(The)h(deb)n(ugger')-5 b(s)18 b(prompt)h(is)i(`)p FJ(\(Pdb\))49 b FN('.)25 b(T)-7 b(ypical)19 b(usage)h(to)h(run)e(a)i (program)d(under)g(control)h(of)h(the)g(deb)n(ugger)e(is:)236 2398 y FA(>>>)45 b(import)e(pdb)236 2490 y(>>>)i(import)e(mymodule)236 2581 y(>>>)i(pdb.run\('mymodule.test\(\)'\))236 2672 y(>)g(<string>\(0\)?\(\))236 2764 y(\(Pdb\))f(continue)236 2855 y(>)h(<string>\(1\)?\(\))236 2946 y(\(Pdb\))f(continue)236 3038 y(NameError:)f('spam')236 3129 y(>)i(<string>\(1\)?\(\))236 3220 y(\(Pdb\))0 3507 y FN(`)p FO(pdb)m(.p)n(y)p FN(')18 b(can)i(also)h(be)f(in)m(v)n(ok)o(ed)e(as)j(a)g(script)f(to)g(deb)n(ug) f(other)h(scripts.)25 b(F)o(or)20 b(e)o(xample:)236 3745 y FA(python)44 b(-m)h(pdb)f(myscript.py)0 4031 y FN(When)24 b(in)m(v)n(ok)o(ed)e(as)i(a)g(script,)g(pdb)f(will)i(automatically)d (enter)h(post-mortem)f(deb)n(ugging)f(if)j(the)g(program)d(being)i(deb) n(ugged)e(e)o(xits)0 4131 y(abnormally)-5 b(.)30 b(After)22 b(post-mortem)f(deb)n(ugging)f(\(or)i(after)g(normal)f(e)o(xit)i(of)f (the)h(program\),)e(pdb)g(will)j(restart)e(the)h(program.)30 b(Auto-)0 4231 y(matic)18 b(restarting)f(preserv)o(es)g(pdb')-5 b(s)17 b(state)i(\(such)e(as)i(breakpoints\))d(and)h(in)h(most)g(cases) h(is)g(more)e(useful)g(than)h(quitting)f(the)h(deb)n(ugger)0 4330 y(upon)h(program')-5 b(s)18 b(e)o(xit.)51 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.4:)h(Restarting)g(post-mortem)e(beha)n(vior)h (added.)0 4477 y(T)-7 b(ypical)20 b(usage)g(to)g(inspect)g(a)g(crashed) g(program)e(is:)p 0 5549 3901 4 v 3762 5649 a FI(805)p eop end %%Page: 806 818 TeXDict begin 806 817 bop 236 174 a FA(>>>)45 b(import)e(pdb)236 266 y(>>>)i(import)e(mymodule)236 357 y(>>>)i(mymodule.test\(\))236 448 y(Traceback)f(\(most)g(recent)f(call)i(last\):)326 540 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)326 631 y(File)g("./mymodule.py",)e(line)i(4,)h(in)f(test)416 722 y(test2\(\))326 814 y(File)g("./mymodule.py",)e(line)i(3,)h(in)f (test2)416 905 y(print)g(spam)236 996 y(NameError:)f(spam)236 1088 y(>>>)i(pdb.pm\(\))236 1179 y(>)g(./mymodule.py\(3\)test2\(\))236 1270 y(->)g(print)f(spam)236 1362 y(\(Pdb\))0 1648 y FN(The)20 b(module)f(de\002nes)h(the)g(follo)n(wing)e(functions;)h (each)h(enters)g(the)g(deb)n(ugger)e(in)j(a)f(slightly)g(dif)n(ferent)f (w)o(ay:)0 1795 y FD(run)p FJ(\()p FK(statement)q FC([)p FK(,)g(globals)p FC([)p FK(,)g(locals)12 b FC(])g(])p FJ(\))208 1895 y FN(Ex)o(ecute)k(the)i FK(statement)i FN(\(gi)n(v)o(en)c(as)j(a)f(string\))g(under)e(deb)n(ugger)g(control.) 23 b(The)18 b(deb)n(ugger)e(prompt)g(appears)h(before)g(an)o(y)g(code) 208 1994 y(is)h(e)o(x)o(ecuted;)f(you)f(can)i(set)g(breakpoints)e(and)h (type)g(`)p FJ(continue)p FN(',)f(or)h(you)g(can)g(step)h(through)d (the)j(statement)f(using)g(`)p FJ(step)p FN(')208 2094 y(or)25 b(`)p FJ(next)p FN(')f(\(all)i(these)g(commands)d(are)j(e)o (xplained)d(belo)n(w\).)40 b(The)25 b(optional)g FK(globals)f FN(and)h FK(locals)g FN(ar)o(guments)f(specify)h(the)208 2193 y(en)m(vironment)c(in)j(which)f(the)i(code)e(is)i(e)o(x)o(ecuted;) f(by)g(def)o(ault)g(the)g(dictionary)e(of)i(the)g(module)f FJ(__main__)g FN(is)i(used.)36 b(\(See)208 2293 y(the)20 b(e)o(xplanation)e(of)i(the)g FJ(exec)g FN(statement)g(or)g(the)g FJ(eval\(\))g FN(b)n(uilt-in)f(function.\))0 2440 y FD(runeval)p FJ(\()p FK(e)n(xpr)m(ession)p FC([)p FK(,)f(globals)p FC([)p FK(,)h(locals)12 b FC(])g(])p FJ(\))208 2540 y FN(Ev)n(aluate)23 b(the)i FK(e)n(xpr)m(ession)f FN(\(gi)n(v)o(en)f(as)j (a)f(string\))e(under)h(deb)n(ugger)e(control.)37 b(When)24 b FJ(runeval\(\))g FN(returns,)h(it)g(returns)f(the)208 2639 y(v)n(alue)19 b(of)h(the)g(e)o(xpression.)k(Otherwise)19 b(this)i(function)e(is)i(similar)f(to)h FJ(run\(\))p FN(.)0 2786 y FD(runcall)p FJ(\()p FK(function)p FC([)p FK(,)c(ar)m(gument,)i(...)12 b FC(])p FJ(\))208 2886 y FN(Call)29 b(the)g FK(function)f FN(\(a)h(function)e(or)i(method)e (object,)j(not)f(a)g(string\))f(with)i(the)e(gi)n(v)o(en)g(ar)o (guments.)49 b(When)29 b FJ(runcall\(\))208 2985 y FN(returns,)22 b(it)i(returns)e(whate)n(v)o(er)f(the)i(function)e(call)i(returned.)32 b(The)22 b(deb)n(ugger)f(prompt)g(appears)h(as)i(soon)e(as)i(the)e (function)g(is)208 3085 y(entered.)0 3232 y FD(set_trace)p FJ(\(\))208 3331 y FN(Enter)27 b(the)h(deb)n(ugger)d(at)j(the)g (calling)g(stack)g(frame.)46 b(This)28 b(is)h(useful)e(to)h(hard-code)e (a)i(breakpoint)d(at)j(a)h(gi)n(v)o(en)d(point)h(in)h(a)208 3431 y(program,)17 b(e)n(v)o(en)j(if)g(the)g(code)g(is)h(not)f (otherwise)f(being)g(deb)n(ugged)f(\(e.g.)25 b(when)19 b(an)h(assertion)g(f)o(ails\).)0 3578 y FD(post_mortem)p FJ(\()p FK(tr)o(acebac)n(k)q FJ(\))208 3678 y FN(Enter)f(post-mortem)f (deb)n(ugging)g(of)i(the)g(gi)n(v)o(en)f FK(tr)o(acebac)n(k)h FN(object.)0 3824 y FD(pm)p FJ(\(\))208 3924 y FN(Enter)f(post-mortem)f (deb)n(ugging)g(of)i(the)g(traceback)f(found)f(in)j FJ (sys.last_traceback)p FN(.)0 4252 y FE(24.1)121 b(Deb)n(ugger)36 b(Commands)0 4484 y FN(The)27 b(deb)n(ugger)f(recognizes)g(the)h(follo) n(wing)f(commands.)46 b(Most)27 b(commands)f(can)i(be)f(abbre)n(viated) e(to)j(one)f(or)g(tw)o(o)h(letters;)k(e.g.)0 4584 y(`)p FJ(h\(elp\))p FN(')20 b(means)g(that)h(either)f(`)p FJ(h)p FN(')h(or)f(`)p FJ(help)p FN(')g(can)h(be)g(used)f(to)h(enter)g(the)f (help)h(command)e(\(b)n(ut)h(not)g(`)p FJ(he)p FN(')h(or)f(`)p FJ(hel)p FN(',)g(nor)g(`)p FJ(H)p FN(')h(or)0 4684 y(`)p FJ(Help)p FN(')g(or)h(`)p FJ(HELP)p FN('\).)e(Ar)o(guments)g(to)i (commands)e(must)i(be)g(separated)f(by)h(whitespace)f(\(spaces)h(or)f (tabs\).)31 b(Optional)21 b(ar)o(guments)0 4783 y(are)g(enclosed)f(in)h (square)f(brack)o(ets)h(\(`)p FJ([])p FN('\))f(in)h(the)g(command)e (syntax;)i(the)g(square)f(brack)o(ets)g(must)h(not)g(be)g(typed.)26 b(Alternati)n(v)o(es)20 b(in)0 4883 y(the)g(command)e(syntax)i(are)g (separated)f(by)h(a)h(v)o(ertical)e(bar)h(\(`)p FJ(|)p FN('\).)0 5030 y(Entering)f(a)j(blank)e(line)h(repeats)g(the)f(last)i (command)d(entered.)26 b(Exception:)f(if)d(the)f(last)g(command)e(w)o (as)j(a)g(`)p FJ(list)p FN(')e(command,)f(the)0 5129 y(ne)o(xt)g(11)h(lines)h(are)f(listed.)0 5276 y(Commands)h(that)h(the)g (deb)n(ugger)e(doesn')o(t)g(recognize)h(are)h(assumed)f(to)h(be)g (Python)f(statements)h(and)g(are)f(e)o(x)o(ecuted)g(in)h(the)g(conte)o (xt)0 5376 y(of)k(the)g(program)e(being)h(deb)n(ugged.)41 b(Python)25 b(statements)h(can)g(also)h(be)f(pre\002x)o(ed)e(with)j(an) f(e)o(xclamation)e(point)i(\(`)p FJ(!)p FN('\).)42 b(This)26 b(is)h(a)p 0 5549 3901 4 v 0 5649 a FI(806)2443 b(Chapter)23 b(24.)52 b(The)24 b(Python)f(Deb)n(ugger)p eop end %%Page: 807 819 TeXDict begin 807 818 bop 0 83 a FN(po)n(werful)17 b(w)o(ay)j(to)f (inspect)g(the)h(program)d(being)h(deb)n(ugged;)f(it)k(is)f(e)n(v)o(en) e(possible)h(to)g(change)f(a)i(v)n(ariable)e(or)h(call)h(a)g(function.) j(When)0 183 y(an)d(e)o(xception)e(occurs)i(in)g(such)g(a)h(statement,) e(the)i(e)o(xception)d(name)i(is)h(printed)e(b)n(ut)h(the)g(deb)n (ugger')-5 b(s)18 b(state)j(is)h(not)d(changed.)0 330 y(Multiple)h(commands)f(may)h(be)h(entered)e(on)h(a)h(single)g(line,)g (separated)e(by)h(`)p FJ(;;)p FN('.)26 b(\(A)21 b(single)f(`)p FJ(;)p FN(')h(is)g(not)g(used)f(as)h(it)h(is)f(the)g(separator)0 429 y(for)29 b(multiple)g(commands)f(in)h(a)h(line)g(that)g(is)g (passed)f(to)h(the)g(Python)e(parser)-5 b(.\))53 b(No)29 b(intelligence)g(is)h(applied)f(to)g(separating)g(the)0 529 y(commands;)19 b(the)h(input)f(is)i(split)g(at)g(the)f(\002rst)h(`) p FJ(;;)p FN(')f(pair)m(,)f(e)n(v)o(en)g(if)i(it)g(is)g(in)f(the)g (middle)g(of)g(a)g(quoted)f(string.)0 676 y(The)26 b(deb)n(ugger)e (supports)i(aliases.)44 b(Aliases)28 b(can)e(ha)n(v)o(e)g(parameters)f (which)h(allo)n(ws)h(one)f(a)h(certain)f(le)n(v)o(el)g(of)g (adaptability)f(to)i(the)0 775 y(conte)o(xt)19 b(under)g(e)o (xamination.)0 922 y(If)24 b(a)g(\002le)h(`)p FO(.pdbrc)p FN(')47 b(e)o(xists)24 b(in)g(the)g(user')-5 b(s)25 b(home)e(directory) f(or)i(in)g(the)g(current)e(directory)-5 b(,)23 b(it)i(is)f(read)g(in)g (and)f(e)o(x)o(ecuted)f(as)j(if)f(it)h(had)0 1022 y(been)i(typed)g(at)i (the)f(deb)n(ugger)d(prompt.)47 b(This)28 b(is)h(particularly)d(useful) h(for)h(aliases.)49 b(If)27 b(both)h(\002les)g(e)o(xist,)i(the)e(one)g (in)g(the)g(home)0 1121 y(directory)18 b(is)k(read)d(\002rst)i(and)f (aliases)h(de\002ned)e(there)h(can)g(be)g(o)o(v)o(erridden)d(by)j(the)g (local)g(\002le.)0 1351 y FL(h\(elp\))g FC([)p Fo(command)13 b FC(])39 b FN(W)m(ithout)18 b(ar)o(gument,)e(print)h(the)h(list)h(of)f (a)n(v)n(ailable)f(commands.)23 b(W)m(ith)18 b(a)h FK(command)f FN(as)h(ar)o(gument,)d(print)h(help)208 1451 y(about)j(that)i(command.) 27 b(`)p FJ(help)49 b(pdb)p FN(')21 b(displays)h(the)f(full)h (documentation)c(\002le;)24 b(if)d(the)h(en)m(vironment)d(v)n(ariable)h (P)-8 b(A)m(GER)23 b(is)208 1551 y(de\002ned,)k(the)f(\002le)i(is)f (piped)f(through)e(that)j(command)e(instead.)44 b(Since)27 b(the)f FK(command)i FN(ar)o(gument)c(must)j(be)f(an)h(identi\002er)m (,)208 1650 y(`)p FJ(help)48 b(exec)p FN(')20 b(must)g(be)g(entered)f (to)i(get)f(help)g(on)f(the)i(`)p FJ(!)p FN(')j(command.)0 1816 y FL(w\(her)o(e\))40 b FN(Print)25 b(a)g(stack)g(trace,)g(with)g (the)g(most)f(recent)g(frame)g(at)h(the)g(bottom.)37 b(An)25 b(arro)n(w)f(indicates)g(the)h(current)e(frame,)i(which)208 1916 y(determines)19 b(the)h(conte)o(xt)f(of)h(most)g(commands.)0 2082 y FL(d\(o)o(wn\))41 b FN(Mo)o(v)o(e)19 b(the)h(current)f(frame)g (one)h(le)n(v)o(el)g(do)n(wn)f(in)h(the)g(stack)h(trace)f(\(to)g(a)g (ne)n(wer)g(frame\).)0 2248 y FL(u\(p\))41 b FN(Mo)o(v)o(e)19 b(the)h(current)f(frame)h(one)f(le)n(v)o(el)h(up)g(in)g(the)g(stack)h (trace)f(\(to)g(an)g(older)f(frame\).)0 2430 y FL(b\(r)o(eak\))g FC([[)p Fo(\002lename)p FL(:)12 b FC(])p Fo(lineno)p Fc(|)p Fo(function)p FC([)p FL(,)18 b Fo(condition)12 b FC(])g(])39 b FN(W)m(ith)26 b(a)g FK(lineno)f FN(ar)o(gument,)f(set)i (a)g(break)f(there)g(in)g(the)h(current)e(\002le.)208 2530 y(W)m(ith)i(a)g FK(function)f FN(ar)o(gument,)g(set)i(a)g(break)e (at)h(the)g(\002rst)h(e)o(x)o(ecutable)e(statement)g(within)h(that)g (function.)41 b(The)26 b(line)g(number)208 2630 y(may)e(be)h(pre\002x)o (ed)e(with)i(a)g(\002lename)f(and)h(a)g(colon,)g(to)g(specify)f(a)h (breakpoint)d(in)j(another)f(\002le)h(\(probably)d(one)j(that)g(hasn')o (t)208 2729 y(been)19 b(loaded)h(yet\).)25 b(The)20 b(\002le)h(is)h (searched)d(on)h FJ(sys.path)p FN(.)25 b(Note)20 b(that)h(each)f (breakpoint)e(is)j(assigned)f(a)h(number)e(to)h(which)208 2829 y(all)g(the)h(other)e(breakpoint)f(commands)g(refer)-5 b(.)208 2962 y(If)18 b(a)h(second)e(ar)o(gument)f(is)k(present,)d(it)j (is)f(an)f(e)o(xpression)f(which)h(must)g(e)n(v)n(aluate)g(to)g(true)g (before)f(the)i(breakpoint)d(is)j(honored.)208 3094 y(W)m(ithout)j(ar)o (gument,)f(list)j(all)g(breaks,)e(including)g(for)g(each)h(breakpoint,) e(the)i(number)e(of)i(times)g(that)g(breakpoint)e(has)i(been)208 3194 y(hit,)d(the)g(current)f(ignore)g(count,)g(and)g(the)i(associated) e(condition)g(if)h(an)o(y)-5 b(.)0 3376 y FL(tbr)o(eak)19 b FC([[)p Fo(\002lename)p FL(:)12 b FC(])p Fo(lineno)p Fc(|)p Fo(function)p FC([)p FL(,)18 b Fo(condition)12 b FC(])g(])40 b FN(T)-6 b(emporary)21 b(breakpoint,)h(which)h(is)i (remo)o(v)o(ed)c(automatically)h(when)208 3476 y(it)e(is)i(\002rst)f (hit.)k(The)20 b(ar)o(guments)e(are)i(the)g(same)g(as)h(break.)0 3642 y FL(cl\(ear\))e FC([)p Fo(bpnumber)g FC([)p Fo(bpnumber)h(...)12 b FC(])g(])40 b FN(W)m(ith)33 b(a)h(space)g(separated)f(list)h(of)g (breakpoint)d(numbers,)k(clear)e(those)h(breakpoints.)208 3742 y(W)m(ithout)19 b(ar)o(gument,)f(clear)i(all)h(breaks)e(\(b)n(ut)h (\002rst)h(ask)f(con\002rmation\).)0 3908 y FL(disable)h FC([)p Fo(bpnumber)e FC([)p Fo(bpnumber)g(...)12 b FC(])g(])40 b FN(Disables)19 b(the)g(breakpoints)d(gi)n(v)o(en)h(as)i(a)g(space)f (separated)g(list)h(of)f(breakpoint)e(numbers.)208 4007 y(Disabling)j(a)h(breakpoint)e(means)i(it)g(cannot)f(cause)h(the)g (program)e(to)i(stop)g(e)o(x)o(ecution,)e(b)n(ut)i(unlik)o(e)f (clearing)g(a)h(breakpoint,)e(it)208 4107 y(remains)h(in)i(the)f(list)h (of)f(breakpoints)e(and)i(can)g(be)g(\(re-\)enabled.)0 4273 y FL(enable)g FC([)p Fo(bpnumber)g FC([)p Fo(bpnumber)f(...)12 b FC(])g(])40 b FN(Enables)19 b(the)i(breakpoints)d(speci\002ed.)0 4439 y FL(ignor)o(e)h Fo(bpnumber)h FC([)p Fo(count)12 b FC(])41 b FN(Sets)16 b(the)f(ignore)f(count)h(for)f(the)i(gi)n(v)o (en)e(breakpoint)f(number)-5 b(.)22 b(If)15 b(count)f(is)j(omitted,)e (the)g(ignore)g(count)208 4539 y(is)i(set)g(to)g(0.)24 b(A)17 b(breakpoint)d(becomes)i(acti)n(v)o(e)g(when)g(the)h(ignore)e (count)g(is)j(zero.)23 b(When)16 b(non-zero,)f(the)i(count)e(is)j (decremented)208 4638 y(each)h(time)h(the)g(breakpoint)d(is)k(reached)d (and)h(the)h(breakpoint)e(is)i(not)g(disabled)f(and)g(an)o(y)g (associated)g(condition)f(e)n(v)n(aluates)h(to)208 4738 y(true.)0 4904 y FL(condition)h Fo(bpnumber)f FC([)p Fo(condition)12 b FC(])40 b FN(Condition)27 b(is)i(an)f(e)o(xpression)f (which)h(must)g(e)n(v)n(aluate)f(to)i(true)f(before)e(the)j(breakpoint) d(is)208 5004 y(honored.)c(If)e(condition)f(is)i(absent,)e(an)o(y)h(e)o (xisting)f(condition)g(is)i(remo)o(v)o(ed;)d(i.e.,)h(the)i(breakpoint)d (is)j(made)e(unconditional.)0 5170 y FL(commands)i FC([)p Fo(bpnumber)12 b FC(])39 b FN(Specify)22 b(a)i(list)g(of)f(commands)e (for)i(breakpoint)d(number)i FK(bpnumber)r FN(.)31 b(The)23 b(commands)e(themselv)o(es)208 5269 y(appear)e(on)g(the)i(follo)n(wing) d(lines.)25 b(T)-7 b(ype)20 b(a)h(line)f(containing)e(just)j('end')e (to)h(terminate)g(the)g(commands.)j(An)d(e)o(xample:)p 0 5549 3901 4 v 0 5649 a FI(24.1.)52 b(Deb)n(ugger)24 b(Commands)2716 b(807)p eop end %%Page: 808 820 TeXDict begin 808 819 bop 444 174 a FA(\(Pdb\))44 b(commands)f(1)444 266 y(\(com\))h(print)g(some_variable)444 357 y(\(com\))g(end)444 448 y(\(Pdb\))208 720 y FN(T)-7 b(o)23 b(remo)o(v)o(e)f(all)i(commands) e(from)h(a)h(breakpoint,)d(type)j(commands)d(and)j(follo)n(w)e(it)j (immediately)d(with)i(end;)h(that)e(is,)i(gi)n(v)o(e)208 819 y(no)19 b(commands.)208 951 y(W)m(ith)h(no)g FK(bpnumber)g FN(ar)o(gument,)e(commands)g(refers)i(to)g(the)g(last)i(breakpoint)17 b(set.)208 1082 y(Y)-9 b(ou)20 b(can)i(use)g(breakpoint)d(commands)h (to)h(start)h(your)f(program)e(up)i(again.)28 b(Simply)21 b(use)h(the)g(continue)e(command,)f(or)i(step,)208 1182 y(or)e(an)o(y)h(other)f(command)f(that)j(resumes)f(e)o(x)o(ecution.)208 1314 y(Specifying)d(an)o(y)i(command)f(resuming)g(e)o(x)o(ecution)f (\(currently)h(continue,)g(step,)i(ne)o(xt,)e(return,)h(jump,)f(quit)i (and)f(their)g(abbre-)208 1413 y(viations\))i(terminates)g(the)i (command)d(list)j(\(as)g(if)f(that)g(command)e(w)o(as)j(immediately)e (follo)n(wed)g(by)h(end\).)30 b(This)22 b(is)h(because)208 1513 y(an)o(y)18 b(time)i(you)e(resume)h(e)o(x)o(ecution)e(\(e)n(v)o (en)h(with)h(a)h(simple)f(ne)o(xt)g(or)g(step\),)g(you)g(may)f (encounter)g(another)g(breakpoint\226which)208 1612 y(could)h(ha)n(v)o (e)g(its)j(o)n(wn)d(command)f(list,)j(leading)f(to)g(ambiguities)f (about)g(which)h(list)h(to)g(e)o(x)o(ecute.)208 1744 y(If)j(you)g(use)h(the)g(')-5 b(silent')25 b(command)e(in)i(the)g (command)e(list,)k(the)e(usual)g(message)f(about)g(stopping)g(at)h(a)h (breakpoint)c(is)k(not)208 1844 y(printed.)e(This)c(may)g(be)h (desirable)e(for)h(breakpoints)f(that)h(are)g(to)h(print)f(a)h (speci\002c)f(message)g(and)g(then)g(continue.)k(If)c(none)g(of)208 1943 y(the)g(other)f(commands)g(print)g(an)o(ything,)f(you)h(see)i(no)f (sign)g(that)g(the)h(breakpoint)c(w)o(as)k(reached.)208 2075 y(Ne)n(w)f(in)g(v)o(ersion)f(2.5.)0 2238 y FL(s\(tep\))41 b FN(Ex)o(ecute)18 b(the)i(current)f(line,)g(stop)h(at)g(the)g(\002rst) h(possible)e(occasion)g(\(either)g(in)h(a)g(function)e(that)i(is)h (called)f(or)f(on)h(the)f(ne)o(xt)g(line)208 2338 y(in)h(the)g(current) f(function\).)0 2502 y FL(n\(ext\))40 b FN(Continue)20 b(e)o(x)o(ecution)g(until)h(the)g(ne)o(xt)g(line)g(in)h(the)f(current)f (function)g(is)i(reached)e(or)i(it)g(returns.)27 b(\(The)21 b(dif)n(ference)e(between)208 2601 y(`)p FJ(next)p FN(')25 b(and)i(`)p FJ(step)p FN(')e(is)j(that)f(`)p FJ(step)p FN(')f(stops)h(inside)f(a)h(called)g(function,)f(while)h(`)p FJ(next)p FN(')f(e)o(x)o(ecutes)f(called)i(functions)e(at)208 2701 y(\(nearly\))18 b(full)i(speed,)g(only)f(stopping)g(at)i(the)f(ne) o(xt)f(line)h(in)h(the)f(current)f(function.\))0 2864 y FL(r\(etur)o(n\))40 b FN(Continue)19 b(e)o(x)o(ecution)f(until)i(the) h(current)d(function)h(returns.)0 3028 y FL(c\(ont\(inue\)\))40 b FN(Continue)19 b(e)o(x)o(ecution,)f(only)h(stop)h(when)g(a)g (breakpoint)e(is)j(encountered.)0 3191 y FL(j\(ump\))f Fo(lineno)42 b FN(Set)24 b(the)f(ne)o(xt)g(line)h(that)f(will)h(be)g(e) o(x)o(ecuted.)33 b(Only)23 b(a)n(v)n(ailable)g(in)h(the)f(bottom-most)f (frame.)34 b(This)23 b(lets)i(you)d(jump)208 3291 y(back)d(and)h(e)o(x) o(ecute)f(code)g(again,)g(or)h(jump)f(forw)o(ard)g(to)h(skip)g(code)g (that)g(you)g(don')o(t)e(w)o(ant)i(to)h(run.)208 3423 y(It)i(should)f(be)h(noted)f(that)h(not)g(all)h(jumps)f(are)g(allo)n (wed)f(\227)i(for)e(instance)h(it)h(is)g(not)f(possible)f(to)i(jump)e (into)h(the)g(middle)f(of)h(a)208 3522 y FJ(for)d FN(loop)f(or)h(out)g (of)g(a)g FJ(finally)g FN(clause.)0 3686 y FL(l\(ist\))g FC([)p Fo(\002rst)p FC([)p FL(,)h Fo(last)12 b FC(])g(])41 b FN(List)25 b(source)d(code)h(for)g(the)h(current)e(\002le.)36 b(W)m(ithout)23 b(ar)o(guments,)f(list)j(11)e(lines)h(around)d(the)j (current)e(line)i(or)208 3785 y(continue)c(the)i(pre)n(vious)e (listing.)30 b(W)m(ith)22 b(one)g(ar)o(gument,)d(list)k(11)f(lines)g (around)e(at)i(that)g(line.)30 b(W)m(ith)22 b(tw)o(o)h(ar)o(guments,)d (list)j(the)208 3885 y(gi)n(v)o(en)18 b(range;)i(if)g(the)g(second)g (ar)o(gument)e(is)j(less)g(than)f(the)g(\002rst,)h(it)f(is)i (interpreted)c(as)j(a)g(count.)0 4048 y FL(a\(r)o(gs\))40 b FN(Print)20 b(the)h(ar)o(gument)c(list)22 b(of)e(the)g(current)f (function.)0 4212 y FL(p)i Fo(expression)41 b FN(Ev)n(aluate)20 b(the)i FK(e)n(xpr)m(ession)f FN(in)g(the)h(current)e(conte)o(xt)g(and) h(print)f(its)j(v)n(alue.)k FL(Note:)g FN(`)p FJ(print)p FN(')20 b(can)h(also)h(be)f(used,)h(b)n(ut)208 4312 y(is)f(not)f(a)g (deb)n(ugger)e(command)g(\227)j(this)g(e)o(x)o(ecutes)e(the)h(Python)f FJ(print)h FN(statement.)0 4475 y FL(pp)h Fo(expression)41 b FN(Lik)o(e)19 b(the)g(`)p FJ(p)p FN(')g(command,)e(e)o(xcept)h(the)h (v)n(alue)f(of)h(the)g(e)o(xpression)e(is)j(pretty-printed)c(using)j (the)g FJ(pprint)f FN(module.)0 4639 y FL(alias)i FC([)p Fo(name)g FC([)p FL(command)12 b FC(])g(])40 b FN(Creates)17 b(an)f(alias)i(called)e FK(name)g FN(that)g(e)o(x)o(ecutes)g FK(command)r FN(.)22 b(The)16 b(command)e(must)j FK(not)f FN(be)h(enclosed)208 4738 y(in)22 b(quotes.)31 b(Replaceable)22 b(parameters)f(can)h(be)g(indicated)g(by)g(`)p FJ(\0451)p FN(',)g(`)p FJ(\0452)p FN(',)g(and)g(so)h(on,)f(while)g(`)p FJ(\045)3104 4753 y(*)3154 4738 y FN(')g(is)h(replaced)f(by)g(all)h (the)208 4838 y(parameters.)28 b(If)21 b(no)g(command)f(is)i(gi)n(v)o (en,)f(the)h(current)e(alias)i(for)f FK(name)g FN(is)i(sho)n(wn.)28 b(If)22 b(no)f(ar)o(guments)e(are)j(gi)n(v)o(en,)e(all)j(aliases)208 4938 y(are)d(listed.)208 5069 y(Aliases)i(may)g(be)f(nested)h(and)f (can)h(contain)e(an)o(ything)g(that)i(can)f(be)h(le)o(gally)f(typed)g (at)h(the)g(pdb)f(prompt.)28 b(Note)21 b(that)h(internal)208 5169 y(pdb)15 b(commands)g FK(can)h FN(be)g(o)o(v)o(erridden)d(by)j (aliases.)25 b(Such)16 b(a)h(command)e(is)i(then)f(hidden)f(until)h (the)h(alias)g(is)g(remo)o(v)o(ed.)22 b(Aliasing)208 5268 y(is)f(recursi)n(v)o(ely)d(applied)h(to)h(the)h(\002rst)g(w)o(ord) e(of)h(the)g(command)e(line;)j(all)g(other)e(w)o(ords)h(in)g(the)g (line)h(are)f(left)g(alone.)208 5400 y(As)h(an)f(e)o(xample,)e(here)i (are)g(tw)o(o)g(useful)g(aliases)h(\(especially)f(when)f(placed)h(in)g (the)g(`)p FO(.pdbrc)p FN(')f(\002le\):)p 0 5549 3901 4 v 0 5649 a FI(808)2443 b(Chapter)23 b(24.)52 b(The)24 b(Python)f(Deb)n(ugger)p eop end %%Page: 809 821 TeXDict begin 809 820 bop 444 174 a FA(#Print)44 b(instance)f (variables)g(\(usage)h("pi)h(classInst"\))444 266 y(alias)f(pi)g(for)h (k)f(in)h(\0451.__dict__.keys\(\):)c(print)j ("\0451.",k,"=",\0451.__dict__[k])444 357 y(#Print)g(instance)f (variables)g(in)i(self)444 448 y(alias)f(ps)g(pi)h(self)0 750 y FL(unalias)21 b Fo(name)40 b FN(Deletes)21 b(the)f(speci\002ed)g (alias.)0 912 y FC([)p FL(!)12 b FC(])p Fo(statement)40 b FN(Ex)o(ecute)23 b(the)h(\(one-line\))d FK(statement)k FN(in)f(the)g(conte)o(xt)f(of)g(the)h(current)f(stack)g(frame.)35 b(The)24 b(e)o(xclamation)e(point)h(can)208 1012 y(be)e(omitted)g (unless)h(the)f(\002rst)h(w)o(ord)f(of)h(the)f(statement)h(resembles)f (a)h(deb)n(ugger)d(command.)27 b(T)-7 b(o)22 b(set)g(a)g(global)f(v)n (ariable,)f(you)208 1112 y(can)g(pre\002x)f(the)h(assignment)g(command) e(with)i(a)h(`)p FJ(global)p FN(')e(command)f(on)i(the)g(same)g(line,)g (e.g.:)444 1334 y FA(\(Pdb\))44 b(global)g(list_options;)e (list_options)h(=)i(['-l'])444 1425 y(\(Pdb\))0 1727 y FL(q\(uit\))c FN(Quit)20 b(from)f(the)i(deb)n(ugger)-5 b(.)23 b(The)d(program)e(being)h(e)o(x)o(ecuted)f(is)j(aborted.)0 2053 y FE(24.2)121 b(Ho)n(w)35 b(It)e(W)l(or)r(ks)0 2286 y FN(Some)20 b(changes)f(were)h(made)g(to)g(the)g(interpreter:)125 2505 y FM(\017)41 b FJ(sys.settrace\()p FK(func)p FJ(\))17 b FN(sets)k(the)f(global)f(trace)i(function)125 2667 y FM(\017)41 b FN(there)19 b(can)h(also)h(a)f(local)h(trace)f(function) e(\(see)i(later\))0 2887 y(T)m(race)29 b(functions)f(ha)n(v)o(e)h (three)g(ar)o(guments:)42 b FK(fr)o(ame)p FN(,)31 b FK(e)o(vent)q FN(,)h(and)d FK(ar)m(g)p FN(.)52 b FK(fr)o(ame)30 b FN(is)g(the)f (current)g(stack)g(frame.)52 b FK(e)o(vent)31 b FN(is)f(a)g(string:)0 2986 y FJ('call')p FN(,)21 b FJ('line')p FN(,)h FJ('return')p FN(,)f FJ('exception')p FN(,)g FJ('c_call')p FN(,)g FJ('c_return')p FN(,)g(or)g FJ('c_exception')p FN(.)28 b FK(ar)m(g)22 b FN(depends)0 3086 y(on)e(the)g(e)n(v)o(ent)f(type.)0 3233 y(The)27 b(global)g(trace)h(function)e(is)i(in)m(v)n(ok)o(ed)e (\(with)i FK(e)o(vent)h FN(set)f(to)g FJ('call')p FN(\))f(whene)n(v)o (er)e(a)k(ne)n(w)e(local)h(scope)f(is)i(entered;)h(it)f(should)0 3332 y(return)19 b(a)i(reference)d(to)i(the)h(local)f(trace)g(function) e(to)j(be)f(used)g(that)g(scope,)g(or)g FJ(None)g FN(if)g(the)g(scope)g (shouldn')o(t)e(be)i(traced.)0 3479 y(The)h(local)g(trace)h(function)d (should)i(return)f(a)i(reference)d(to)j(itself)g(\(or)f(to)g(another)f (function)g(for)h(further)f(tracing)g(in)i(that)f(scope\),)g(or)0 3579 y FJ(None)f FN(to)g(turn)g(of)n(f)f(tracing)h(in)g(that)g(scope.)0 3726 y(Instance)f(methods)g(are)i(accepted)e(\(and)g(v)o(ery)g (useful!\))24 b(as)d(trace)f(functions.)0 3873 y(The)g(e)n(v)o(ents)f (ha)n(v)o(e)h(the)g(follo)n(wing)f(meaning:)0 4092 y FD('call')40 b FN(A)25 b(function)d(is)i(called)g(\(or)f(some)h(other)e (code)i(block)e(entered\).)34 b(The)24 b(global)f(trace)g(function)f (is)j(called;)g FK(ar)m(g)f FN(is)h FJ(None)p FN(;)208 4192 y(the)20 b(return)f(v)n(alue)g(speci\002es)i(the)f(local)g(trace)g (function.)0 4354 y FD('line')40 b FN(The)26 b(interpreter)f(is)i (about)e(to)h(e)o(x)o(ecute)f(a)i(ne)n(w)f(line)g(of)g(code)f (\(sometimes)h(multiple)g(line)g(e)n(v)o(ents)f(on)h(one)g(line)g(e)o (xist\).)208 4453 y(The)19 b(local)i(trace)f(function)e(is)j(called;)f FK(ar)m(g)g FN(is)h FJ(None)p FN(;)g(the)f(return)f(v)n(alue)g (speci\002es)i(the)f(ne)n(w)g(local)g(trace)g(function.)0 4615 y FD('return')40 b FN(A)19 b(function)e(\(or)h(other)f(code)h (block\))f(is)i(about)f(to)h(return.)k(The)18 b(local)g(trace)h (function)d(is)k(called;)f FK(ar)m(g)f FN(is)h(the)g(v)n(alue)e(that) 208 4715 y(will)j(be)h(returned.)i(The)d(trace)g(function')-5 b(s)18 b(return)i(v)n(alue)f(is)i(ignored.)0 4877 y FD('exception')39 b FN(An)26 b(e)o(xception)e(has)i(occurred.)39 b(The)25 b(local)h(trace)f(function)f(is)j(called;)h FK(ar)m(g)d FN(is)i(a)f(triple)f FJ(\()p FK(e)n(xception)p FJ(,)48 b FK(value)p FJ(,)208 4977 y FK(tr)o(acebac)n(k)q FJ(\))p FN(;)19 b(the)h(return)f(v)n(alue)h(speci\002es)g(the)h(ne)n(w)f(local) g(trace)g(function.)0 5138 y FD('c_call')40 b FN(A)22 b(C)h(function)d(is)i(about)f(to)h(be)f(called.)29 b(This)22 b(may)f(be)h(an)f(e)o(xtension)g(function)f(or)h(a)h(b)n(uiltin.)29 b FK(ar)m(g)21 b FN(is)i(the)f(C)g(function)208 5238 y(object.)0 5400 y FD('c_return')40 b FN(A)20 b(C)h(function)e(has)h (returned.)j FK(ar)m(g)d FN(is)i FJ(None)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(24.2.)52 b(Ho)o(w)23 b(It)g(W)n(or)q(ks)3034 b(809)p eop end %%Page: 810 822 TeXDict begin 810 821 bop 0 83 a FD('c_exception')39 b FN(A)21 b(C)g(function)d(has)j(thro)n(wn)e(an)h(e)o(xception.)j FK(ar)m(g)d FN(is)h FJ(None)p FN(.)0 313 y(Note)e(that)h(as)g(an)f(e)o (xception)f(is)i(propagated)c(do)n(wn)j(the)g(chain)g(of)g(callers,)h (an)f FJ('exception')f FN(e)n(v)o(ent)g(is)j(generated)c(at)j(each)f (le)n(v)o(el.)0 460 y(F)o(or)h(more)f(information)f(on)i(code)f(and)h (frame)f(objects,)h(refer)f(to)i(the)f FK(Python)f(Refer)m(ence)g (Manual)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(810)2443 b(Chapter)23 b(24.)52 b(The)24 b(Python)f(Deb)n(ugger)p eop end %%Page: 811 823 TeXDict begin 811 822 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3129 427 y FG(TWENTYFIVE)p 0 515 V 1971 978 a FT(The)58 b(Python)f (Pro\002lers)0 1466 y FN(Cop)o(yright)380 1463 y(c)357 1466 y FM(\015)20 b FN(1994,)f(by)h(InfoSeek)e(Corporation,)g(all)j (rights)f(reserv)o(ed.)0 1613 y(Written)g(by)g(James)h(Roskind.)901 1583 y FF(1)0 1760 y FN(Permission)e(to)h(use,)f(cop)o(y)-5 b(,)18 b(modify)-5 b(,)18 b(and)g(distrib)n(ute)h(this)h(Python)f (softw)o(are)g(and)g(its)h(associated)f(documentation)e(for)i(an)o(y)f (purpose)0 1860 y(\(subject)k(to)h(the)f(restriction)g(in)h(the)g (follo)n(wing)e(sentence\))g(without)h(fee)h(is)h(hereby)d(granted,)g (pro)o(vided)f(that)j(the)g(abo)o(v)o(e)e(cop)o(yright)0 1959 y(notice)i(appears)f(in)i(all)g(copies,)f(and)g(that)g(both)g (that)g(cop)o(yright)e(notice)i(and)g(this)h(permission)e(notice)h (appear)f(in)h(supporting)e(doc-)0 2059 y(umentation,)28 b(and)g(that)h(the)f(name)g(of)g(InfoSeek)f(not)h(be)h(used)f(in)h(adv) o(ertising)d(or)j(publicity)e(pertaining)f(to)j(distrib)n(ution)e(of)i (the)0 2158 y(softw)o(are)20 b(without)g(speci\002c,)g(written)g(prior) f(permission.)25 b(This)20 b(permission)g(is)h(e)o(xplicitly)e (restricted)h(to)h(the)f(cop)o(ying)f(and)h(modi\002-)0 2258 y(cation)h(of)h(the)f(softw)o(are)h(to)f(remain)g(in)h(Python,)f (compiled)f(Python,)h(or)g(other)g(languages)f(\(such)h(as)i(C\))f (wherein)f(the)g(modi\002ed)g(or)0 2358 y(deri)n(v)o(ed)d(code)i(is)h (e)o(xclusi)n(v)o(ely)d(imported)h(into)h(a)g(Python)g(module.)0 2505 y(INFOSEEK)34 b(CORPORA)-9 b(TION)35 b(DISCLAIMS)g(ALL)f(W)-10 b(ARRANTIES)35 b(WITH)g(REGARD)g(T)o(O)f(THIS)h(SOFTW)-10 b(ARE,)35 b(IN-)0 2604 y(CLUDING)29 b(ALL)g(IMPLIED)f(W)-10 b(ARRANTIES)29 b(OF)h(MERCHANT)-8 b(ABILITY)28 b(AND)h(FITNESS.)g(IN)g (NO)g(EVENT)g(SHALL)0 2704 y(INFOSEEK)21 b(CORPORA)-9 b(TION)22 b(BE)h(LIABLE)e(FOR)h(ANY)g(SPECIAL,)g(INDIRECT)f(OR)h (CONSEQ)o(UENTIAL)f(D)m(AMA)m(GES)0 2803 y(OR)32 b(ANY)g(D)m(AMA)m(GES) f(WHA)-9 b(TSOEVER)32 b(RESUL)-8 b(TING)32 b(FR)m(OM)g(LOSS)g(OF)g (USE,)g(D)m(A)-9 b(T)h(A)31 b(OR)h(PR)m(OFITS,)g(WHETHER)0 2903 y(IN)25 b(AN)g(A)m(CTION)f(OF)h(CONTRA)m(CT)-6 b(,)25 b(NEGLIGENCE)f(OR)h(O)m(THER)g(T)o(OR)-5 b(TIOUS)24 b(A)m(CTION,)g (ARISING)h(OUT)g(OF)g(OR)g(IN)0 3003 y(CONNECTION)20 b(WITH)h(THE)f(USE)g(OR)i(PERFORMANCE)f(OF)g(THIS)f(SOFTW)-10 b(ARE.)0 3150 y(The)21 b(pro\002ler)f(w)o(as)i(written)f(after)g(only)f (programming)e(in)j(Python)f(for)h(3)g(weeks.)28 b(As)22 b(a)g(result,)f(it)h(is)g(probably)d(clumsy)i(code,)f(b)n(ut)h(I)0 3249 y(don')o(t)g(kno)n(w)h(for)h(sure)g(yet)g('cause)g(I'm)f(a)i(be)o (ginner)d(:-\).)33 b(I)24 b(did)e(w)o(ork)h(hard)f(to)h(mak)o(e)g(the)g (code)f(run)h(f)o(ast,)h(so)f(that)h(pro\002ling)d(w)o(ould)0 3349 y(be)f(a)h(reasonable)d(thing)i(to)g(do.)k(I)d(tried)f(not)f(to)i (repeat)e(code)g(fragments,)g(b)n(ut)h(I'm)g(sure)g(I)g(did)g(some)g (stuf)n(f)f(in)i(really)e(a)o(wkw)o(ard)g(w)o(ays)0 3448 y(at)26 b(times.)42 b(Please)26 b(send)g(suggestions)e(for)h(impro)o(v) o(ements)e(to:)36 b FO(jar@netscape)o(.com)p FN(.)j(I)26 b(w)o(on')o(t)f(promise)f FK(any)h FN(support.)40 b(...b)n(ut)25 b(I')l(d)0 3548 y(appreciate)19 b(the)h(feedback.)0 3875 y FE(25.1)121 b(Introduction)36 b(to)e(the)g(pro\002lers)0 4108 y FN(A)25 b FK(pr)l(o\002ler)f FN(is)i(a)f(program)d(that)i (describes)g(the)h(run)f(time)g(performance)e(of)i(a)h(program,)e(pro)o (viding)f(a)i(v)n(ariety)g(of)g(statistics.)39 b(This)0 4208 y(documentation)26 b(describes)i(the)h(pro\002ler)f(functionality) f(pro)o(vided)f(in)k(the)e(modules)g FJ(profile)h FN(and)f FJ(pstats)p FN(.)50 b(This)30 b(pro\002ler)0 4308 y(pro)o(vides)22 b FK(deterministic)h(pr)l(o\002ling)g FN(of)g(an)o(y)g(Python)f (programs.)33 b(It)24 b(also)g(pro)o(vides)d(a)j(series)g(of)g(report)e (generation)f(tools)j(to)g(allo)n(w)0 4407 y(users)c(to)h(rapidly)e(e)o (xamine)f(the)j(results)f(of)g(a)h(pro\002le)e(operation.)0 4554 y(The)h(Python)f(standard)g(library)g(pro)o(vides)f(three)i(dif)n (ferent)f(pro\002lers:)104 4784 y(1.)41 b FJ(profile)p FN(,)34 b(a)g(pure)d(Python)h(module,)i(described)e(in)h(the)g(sequel.) 62 b(Cop)o(yright)2712 4781 y(c)2689 4784 y FM(\015)33 b FN(1994,)i(by)d(InfoSeek)f(Corporation.)208 4884 y(Changed)18 b(in)j(v)o(ersion)e(2.4:)g(also)i(reports)e(the)h(time)h(spent)f(in)g (calls)h(to)f(b)n(uilt-in)g(functions)f(and)g(methods.)104 5050 y(2.)41 b FJ(cProfile)p FN(,)18 b(a)h(module)f(written)g(in)i(C,)f (with)h(a)f(reasonable)f(o)o(v)o(erhead)e(that)j(mak)o(es)g(it)h (suitable)e(for)h(pro\002ling)e(long-running)208 5149 y(programs.)23 b(Based)d(on)g FJ(lsprof)p FN(,)f(contrib)n(uted)g(by)g (Brett)i(Rosen)g(and)e(T)-6 b(ed)20 b(Czotter)-5 b(.)51 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)p 0 5220 1560 4 v 90 5276 a FB(1)120 5299 y FH(Updated)e(and)e(con)m(v)o(erted)k(to)c (L)827 5288 y FB(A)853 5299 y FH(T)883 5314 y(E)915 5299 y(X)g(by)g(Guido)h(v)n(an)g(Rossum.)k(Further)d(updated)g(by)e(Armin)h (Rigo)g(to)f(inte)o(grate)k(the)d(documentation)j(for)c(the)h(ne)n(w)g Fz(cProfile)0 5378 y FH(module)i(of)f(Python)h(2.5.)p 0 5549 3901 4 v 3762 5649 a FI(811)p eop end %%Page: 812 824 TeXDict begin 812 823 bop 104 83 a FN(3.)41 b FJ(hotshot)p FN(,)21 b(a)i(C)g(module)e(focusing)f(on)i(minimizing)e(the)j(o)o(v)o (erhead)c(while)j(pro\002ling,)f(at)i(the)f(e)o(xpense)f(of)h(long)f (data)h(post-)208 183 y(processing)f(times.)69 b(Changed)22 b(in)h(v)o(ersion)f(2.5:)h(the)g(results)g(should)f(be)h(more)g (meaningful)e(than)h(in)h(the)h(past:)31 b(the)23 b(timing)208 282 y(core)c(contained)g(a)h(critical)h(b)n(ug.)0 512 y(The)g FJ(profile)f FN(and)h FJ(cProfile)g FN(modules)f(e)o(xport)g (the)h(same)g(interf)o(ace,)g(so)g(the)o(y)g(are)g(mostly)g (interchangeables;)e FJ(cProfile)0 612 y FN(has)24 b(a)g(much)e(lo)n (wer)h(o)o(v)o(erhead)e(b)n(ut)j(is)g(not)f(so)h(f)o(ar)f(as)i (well-tested)e(and)g(might)g(not)g(be)g(a)n(v)n(ailable)h(on)f(all)h (systems.)35 b FJ(cProfile)23 b FN(is)0 711 y(really)c(a)g (compatibility)e(layer)i(on)f(top)h(of)g(the)g(internal)f FJ(_lsprof)g FN(module.)23 b(The)c FJ(hotshot)f FN(module)g(is)i (reserv)o(ed)d(to)i(specialized)0 811 y(usages.)0 1138 y FE(25.2)121 b(Instant)35 b(User')-6 b(s)33 b(Man)o(ual)0 1371 y FN(This)20 b(section)g(is)g(pro)o(vided)e(for)h(users)h(that)g (\223don')o(t)e(w)o(ant)i(to)g(read)f(the)h(manual.)-6 b(\224)23 b(It)e(pro)o(vides)d(a)i(v)o(ery)f(brief)g(o)o(v)o(ervie)n(w) -5 b(,)17 b(and)i(allo)n(ws)h(a)0 1471 y(user)g(to)g(rapidly)f(perform) g(pro\002ling)f(on)i(an)g(e)o(xisting)g(application.)0 1618 y(T)-7 b(o)20 b(pro\002le)g(an)g(application)f(with)h(a)h(main)e (entry)h(point)f(of)h FJ(foo\(\))p FN(,)g(you)f(w)o(ould)h(add)f(the)h (follo)n(wing)f(to)h(your)f(module:)236 1765 y FA(import)44 b(cProfile)236 1856 y(cProfile.run\('foo\(\)'\))0 2142 y FN(\(Use)20 b FJ(profile)g FN(instead)g(of)g FJ(cProfile)f FN(if)i(the)f(latter)g(is)h(not)f(a)n(v)n(ailable)g(on)g(your)f (system.\))0 2289 y(The)f(abo)o(v)o(e)f(action)h(w)o(ould)f(cause)i FJ(foo\(\))f FN(to)g(be)h(run,)e(and)h(a)h(series)g(of)f(informati)n(v) o(e)e(lines)j(\(the)f(pro\002le\))f(to)i(be)f(printed.)23 b(The)18 b(abo)o(v)o(e)0 2389 y(approach)h(is)i(most)g(useful)g(when)f (w)o(orking)f(with)i(the)g(interpreter)-5 b(.)25 b(If)c(you)f(w)o(ould) g(lik)o(e)h(to)g(sa)n(v)o(e)g(the)g(results)g(of)g(a)g(pro\002le)f (into)h(a)g(\002le)0 2489 y(for)f(later)g(e)o(xamination,)e(you)h(can)h (supply)f(a)i(\002le)f(name)g(as)h(the)f(second)f(ar)o(gument)f(to)j (the)f FJ(run\(\))g FN(function:)236 2727 y FA(import)44 b(cProfile)236 2818 y(cProfile.run\('foo\(\)',)e('fooprof'\))0 3105 y FN(The)20 b(\002le)h(`)p FO(cPro\002le)o(.p)n(y)p FN(')d(can)i(also)h(be)f(in)m(v)n(ok)o(ed)e(as)j(a)g(script)f(to)g (pro\002le)g(another)f(script.)25 b(F)o(or)19 b(e)o(xample:)236 3343 y FA(python)44 b(-m)h(cProfile)e(myscript.py)0 3629 y FN(`)p FO(cPro\002le)o(.p)n(y)p FN(')18 b(accepts)j(tw)o(o)f (optional)f(ar)o(guments)f(on)i(the)g(command)e(line:)236 3868 y FA(cProfile.py)43 b([-o)i(output_file])d([-s)j(sort_order])0 4154 y FL(-s)21 b FN(only)e(applies)h(to)g(standard)f(output)g(\()p FL(-o)h FN(is)h(not)f(supplied\).)j(Look)c(in)i(the)f FJ(Stats)g FN(documentation)d(for)j(v)n(alid)f(sort)i(v)n(alues.)0 4301 y(When)h(you)f(wish)h(to)g(re)n(vie)n(w)f(the)h(pro\002le,)f(you)g (should)g(use)h(the)g(methods)f(in)h(the)g FJ(pstats)f FN(module.)29 b(T)-7 b(ypically)21 b(you)g(w)o(ould)g(load)0 4401 y(the)f(statistics)i(data)e(as)h(follo)n(ws:)236 4639 y FA(import)44 b(pstats)236 4730 y(p)h(=)g (pstats.Stats\('fooprof'\))0 5017 y FN(The)20 b(class)g FJ(Stats)g FN(\(the)f(abo)o(v)o(e)g(code)g(just)h(created)f(an)h (instance)g(of)f(this)i(class\))f(has)h(a)f(v)n(ariety)f(of)g(methods)g (for)g(manipulating)f(and)0 5116 y(printing)h(the)h(data)g(that)g(w)o (as)h(just)g(read)f(into)g FJ(p)p FN(.)25 b(When)20 b(you)g(ran)f FJ(cProfile.run\(\))g FN(abo)o(v)o(e,)f(what)i(w)o(as)h(printed)e(w)o (as)i(the)g(result)0 5216 y(of)f(three)g(method)e(calls:)p 0 5549 3901 4 v 0 5649 a FI(812)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g(Pro\002lers)p eop end %%Page: 813 825 TeXDict begin 813 824 bop 236 174 a FA (p.strip_dirs\(\).sort_stats\(-1\).print_stat)o(s\(\))0 461 y FN(The)24 b(\002rst)h(method)d(remo)o(v)o(ed)g(the)i(e)o (xtraneous)e(path)i(from)f(all)h(the)h(module)d(names.)37 b(The)23 b(second)h(method)e(sorted)i(all)h(the)f(entries)0 560 y(according)c(to)i(the)g(standard)f(module/line/name)e(string)i (that)h(is)h(printed.)29 b(The)22 b(third)f(method)g(printed)f(out)i (all)g(the)g(statistics.)32 b(Y)-9 b(ou)0 660 y(might)20 b(try)g(the)g(follo)n(wing)e(sort)j(calls:)236 898 y FA(p.sort_stats\('name'\))236 990 y(p.print_stats\(\))0 1276 y FN(The)e(\002rst)h(call)f(will)h(actually)f(sort)g(the)g(list)h (by)f(function)f(name,)g(and)h(the)g(second)f(call)i(will)g(print)e (out)h(the)g(statistics.)26 b(The)19 b(follo)n(wing)0 1376 y(are)h(some)g(interesting)f(calls)i(to)g(e)o(xperiment)d(with:) 236 1614 y FA(p.sort_stats\('cumulative'\).print_stats\(1)o(0\))0 1900 y FN(This)j(sorts)g(the)g(pro\002le)f(by)g(cumulati)n(v)o(e)f (time)i(in)g(a)g(function,)e(and)i(then)f(only)g(prints)g(the)h(ten)g (most)g(signi\002cant)f(lines.)27 b(If)21 b(you)e(w)o(ant)0 2000 y(to)h(understand)e(what)j(algorithms)d(are)j(taking)e(time,)h (the)g(abo)o(v)o(e)f(line)h(is)h(what)f(you)g(w)o(ould)f(use.)0 2147 y(If)h(you)f(were)h(looking)f(to)h(see)h(what)f(functions)f(were)h (looping)e(a)j(lot,)f(and)g(taking)f(a)i(lot)f(of)g(time,)g(you)g(w)o (ould)f(do:)236 2385 y FA(p.sort_stats\('time'\).print_stats\(10\))0 2672 y FN(to)h(sort)h(according)d(to)i(time)g(spent)g(within)g(each)g (function,)e(and)i(then)g(print)f(the)i(statistics)g(for)f(the)g(top)g (ten)g(functions.)0 2819 y(Y)-9 b(ou)20 b(might)f(also)i(try:)236 3057 y FA(p.sort_stats\('file'\).print_stats\('__init)o(__'\))0 3343 y FN(This)h(will)g(sort)g(all)g(the)f(statistics)i(by)e(\002le)i (name,)e(and)f(then)i(print)e(out)i(statistics)h(for)e(only)f(the)i (class)g(init)g(methods)f(\(since)g(the)o(y)g(are)0 3443 y(spelled)f(with)g FJ(__init__)g FN(in)g(them\).)k(As)d(one)f(\002nal)g (e)o(xample,)f(you)g(could)g(try:)236 3681 y FA(p.sort_stats\('time',) 42 b('cum'\).print_stats\(.5,)f('init'\))0 3968 y FN(This)20 b(line)h(sorts)f(statistics)i(with)e(a)h(primary)d(k)o(e)o(y)i(of)g (time,)g(and)f(a)i(secondary)d(k)o(e)o(y)i(of)f(cumulati)n(v)o(e)g (time,)h(and)f(then)h(prints)g(out)g(some)0 4067 y(of)29 b(the)g(statistics.)53 b(T)-7 b(o)29 b(be)g(speci\002c,)j(the)d(list)h (is)g(\002rst)g(culled)e(do)n(wn)h(to)g(50\045)g(\(re:)42 b(`)p FJ(.5)p FN('\))29 b(of)f(its)j(original)d(size,)j(then)e(only)f (lines)0 4167 y(containing)18 b FJ(init)i FN(are)g(maintained,)f(and)g (that)i(sub-sub-list)e(is)i(printed.)0 4314 y(If)30 b(you)f(w)o (ondered)e(what)j(functions)f(called)g(the)h(abo)o(v)o(e)e(functions,)j (you)d(could)h(no)n(w)g(\()p FJ(p)h FN(is)h(still)g(sorted)e(according) f(to)i(the)g(last)0 4413 y(criteria\))20 b(do:)236 4652 y FA(p.print_callers\(.5,)42 b('init'\))0 4938 y FN(and)20 b(you)f(w)o(ould)g(get)i(a)f(list)i(of)d(callers)i(for)e(each)h(of)g (the)g(listed)h(functions.)0 5085 y(If)f(you)f(w)o(ant)i(more)e (functionality)-5 b(,)17 b(you')l(re)i(going)g(to)h(ha)n(v)o(e)g(to)g (read)g(the)g(manual,)f(or)h(guess)g(what)g(the)g(follo)n(wing)f (functions)f(do:)p 0 5549 3901 4 v 0 5649 a FI(25.2.)52 b(Instant)24 b(User')l(s)e(Man)o(ual)2729 b(813)p eop end %%Page: 814 826 TeXDict begin 814 825 bop 236 174 a FA(p.print_callees\(\))236 266 y(p.add\('fooprof'\))0 552 y FN(In)m(v)n(ok)o(ed)25 b(as)k(a)f(script,)h(the)f FJ(pstats)f FN(module)f(is)j(a)f(statistics) h(bro)n(wser)d(for)h(reading)g(and)g(e)o(xamining)e(pro\002le)i(dumps.) 46 b(It)28 b(has)g(a)0 652 y(simple)20 b(line-oriented)e(interf)o(ace)h (\(implemented)f(using)i FJ(cmd)p FN(\))g(and)g(interacti)n(v)o(e)e (help.)0 979 y FE(25.3)121 b(What)34 b(Is)g(Deter)s(ministic)f (Pro\002ling?)0 1212 y FK(Deterministic)e(pr)l(o\002ling)f FN(is)i(meant)f(to)g(re\003ect)g(the)g(f)o(act)g(that)g(all)h FK(function)d(call)p FN(,)34 b FK(function)29 b(r)m(eturn)p FN(,)34 b(and)c FK(e)n(xception)g FN(e)n(v)o(ents)h(are)0 1312 y(monitored,)26 b(and)g(precise)h(timings)g(are)f(made)h(for)f (the)h(interv)n(als)f(between)g(these)h(e)n(v)o(ents)f(\(during)f (which)h(time)h(the)g(user')-5 b(s)27 b(code)0 1411 y(is)k(e)o(x)o (ecuting\).)51 b(In)30 b(contrast,)h FK(statistical)f(pr)l(o\002ling)f FN(\(which)g(is)i(not)e(done)g(by)g(this)i(module\))d(randomly)f (samples)j(the)g(ef)n(fecti)n(v)o(e)0 1511 y(instruction)23 b(pointer)m(,)h(and)g(deduces)f(where)h(time)g(is)i(being)d(spent.)37 b(The)24 b(latter)h(technique)e(traditionally)g(in)m(v)n(olv)o(es)g (less)i(o)o(v)o(erhead)0 1611 y(\(as)c(the)f(code)f(does)h(not)g(need)g (to)g(be)g(instrumented\),)e(b)n(ut)i(pro)o(vides)e(only)i(relati)n(v)o (e)f(indications)g(of)h(where)g(time)g(is)h(being)e(spent.)0 1757 y(In)24 b(Python,)g(since)h(there)f(is)h(an)g(interpreter)d(acti)n (v)o(e)i(during)f(e)o(x)o(ecution,)g(the)i(presence)e(of)h (instrumented)f(code)g(is)j(not)e(required)e(to)0 1857 y(do)h(deterministic)g(pro\002ling.)35 b(Python)23 b(automatically)f (pro)o(vides)g(a)j FK(hook)e FN(\(optional)f(callback\))h(for)g(each)g (e)n(v)o(ent.)36 b(In)23 b(addition,)h(the)0 1957 y(interpreted)17 b(nature)h(of)h(Python)f(tends)g(to)i(add)e(so)h(much)f(o)o(v)o(erhead) f(to)i(e)o(x)o(ecution,)d(that)k(deterministic)e(pro\002ling)f(tends)i (to)g(only)f(add)0 2056 y(small)24 b(processing)f(o)o(v)o(erhead)e(in)j (typical)f(applications.)34 b(The)24 b(result)g(is)g(that)g (deterministic)f(pro\002ling)f(is)j(not)e(that)h(e)o(xpensi)n(v)o(e,)f (yet)0 2156 y(pro)o(vides)18 b(e)o(xtensi)n(v)o(e)h(run)h(time)g (statistics)i(about)d(the)h(e)o(x)o(ecution)e(of)i(a)h(Python)e (program.)0 2303 y(Call)i(count)f(statistics)h(can)f(be)h(used)f(to)g (identify)f(b)n(ugs)h(in)h(code)e(\(surprising)g(counts\),)g(and)g(to)i (identify)e(possible)h(inline-e)o(xpansion)0 2402 y(points)e(\(high)f (call)h(counts\).)24 b(Internal)17 b(time)h(statistics)i(can)e(be)g (used)g(to)g(identify)f(\223hot)h(loops\224)g(that)g(should)f(be)h (carefully)f(optimized.)0 2502 y(Cumulati)n(v)o(e)26 b(time)h(statistics)h(should)e(be)h(used)g(to)g(identify)f(high)g(le)n (v)o(el)h(errors)f(in)h(the)g(selection)g(of)f(algorithms.)45 b(Note)26 b(that)i(the)0 2602 y(unusual)23 b(handling)f(of)h(cumulati)n (v)o(e)f(times)j(in)f(this)g(pro\002ler)f(allo)n(ws)h(statistics)i(for) d(recursi)n(v)o(e)f(implementations)g(of)i(algorithms)e(to)0 2701 y(be)e(directly)g(compared)e(to)i(iterati)n(v)o(e)f (implementations.)0 3029 y FE(25.4)121 b(Ref)l(erence)36 b(Man)o(ual)e(\226)g Fx(profile)d FE(and)k Fx(cProfile)0 3262 y FN(The)24 b(primary)e(entry)i(point)f(for)h(the)g(pro\002ler)f (is)i(the)f(global)g(function)e FJ(profile.run\(\))g FN(\(resp.)37 b FJ(cProfile.run\(\))p FN(\).)d(It)25 b(is)0 3361 y(typically)j(used)g(to)g(create)g(an)o(y)g(pro\002le)g (information.)47 b(The)28 b(reports)g(are)g(formatted)f(and)h(printed)f (using)h(methods)f(of)h(the)h(class)0 3461 y FJ(pstats.Stats)p FN(.)50 b(The)29 b(follo)n(wing)f(is)i(a)g(description)d(of)i(all)h(of) f(these)g(standard)f(entry)h(points)g(and)f(functions.)51 b(F)o(or)29 b(a)g(more)0 3560 y(in-depth)16 b(vie)n(w)i(of)f(some)h(of) g(the)g(code,)f(consider)g(reading)f(the)i(later)g(section)g(on)f (Pro\002ler)h(Extensions,)f(which)g(includes)g(discussion)0 3660 y(of)j(ho)n(w)g(to)g(deri)n(v)o(e)f(\223better\224)g(pro\002lers)h (from)f(the)h(classes)h(presented,)e(or)h(reading)f(the)h(source)f (code)h(for)f(these)i(modules.)0 3807 y FD(run)p FJ(\()p FK(command)r FC([)p FK(,)d(\002lename)12 b FC(])p FJ(\))208 3907 y FN(This)23 b(function)e(tak)o(es)j(a)f(single)g(ar)o(gument)e (that)i(can)g(be)g(passed)g(to)g(the)g FJ(exec)g FN(statement,)h(and)e (an)h(optional)f(\002le)i(name.)33 b(In)208 4006 y(all)24 b(cases)h(this)g(routine)e(attempts)h(to)h FJ(exec)f FN(its)h(\002rst)g(ar)o(gument,)d(and)i(gather)f(pro\002ling)g (statistics)i(from)f(the)g(e)o(x)o(ecution.)35 b(If)208 4106 y(no)22 b(\002le)h(name)f(is)i(present,)e(then)g(this)h(function)e (automatically)g(prints)h(a)h(simple)g(pro\002ling)e(report,)h(sorted)g (by)g(the)h(standard)208 4205 y(name)d(string)h (\(\002le/line/function-name\))c(that)k(is)h(presented)e(in)h(each)g (line.)27 b(The)21 b(follo)n(wing)f(is)i(a)f(typical)g(output)f(from)g (such)208 4305 y(a)g(call:)713 4529 y FA(2706)44 b(function)f(calls)h (\(2004)g(primitive)g(calls\))g(in)g(4.504)g(CPU)g(seconds)444 4712 y(Ordered)f(by:)i(standard)e(name)444 4895 y(ncalls)88 b(tottime)h(percall)f(cumtime)h(percall)44 b (filename:lineno\(function\))668 4986 y(2)179 b(0.006)g(0.003)f(0.953)h (0.477)44 b(pobject.py:75\(save_objects\))533 5077 y(43/3)179 b(0.533)g(0.012)f(0.749)h(0.250)44 b(pobject.py:99\(evaluate\))489 5168 y(...)208 5358 y FN(The)23 b(\002rst)i(line)f(indicates)g(that)g (2706)f(calls)i(were)f(monitored.)34 b(Of)25 b(those)e(calls,)j(2004)d (were)h FK(primitive)p FN(.)37 b(W)-7 b(e)25 b(de\002ne)e FK(primi-)p 0 5549 3901 4 v 0 5649 a FI(814)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g(Pro\002lers)p eop end %%Page: 815 827 TeXDict begin 815 826 bop 208 83 a FK(tive)24 b FN(to)h(mean)e(that)i (the)f(call)h(w)o(as)g(not)f(induced)e(via)i(recursion.)36 b(The)24 b(ne)o(xt)f(line:)34 b FJ(Ordered)48 b(by:)i(standard)e(name)p FN(,)208 183 y(indicates)19 b(that)i(the)f(te)o(xt)g(string)g(in)g(the) g(f)o(ar)g(right)g(column)f(w)o(as)i(used)f(to)g(sort)g(the)h(output.)i (The)d(column)f(headings)g(include:)208 396 y FL(ncalls)h FN(for)g(the)g(number)e(of)i(calls,)208 529 y FL(tottime)f FN(for)g(the)i(total)f(time)g(spent)g(in)h(the)f(gi)n(v)o(en)f (function)f(\(and)i(e)o(xcluding)e(time)i(made)f(in)i(calls)g(to)f (sub-functions\),)208 662 y FL(per)o(call)f FN(is)i(the)g(quotient)d (of)i FJ(tottime)g FN(di)n(vided)f(by)g FJ(ncalls)208 794 y FL(cumtime)h FN(is)26 b(the)f(total)h(time)f(spent)g(in)g(this)h (and)f(all)g(subfunctions)e(\(from)h(in)m(v)n(ocation)f(till)j(e)o (xit\).)40 b(This)25 b(\002gure)f(is)i(accurate)390 894 y FK(e)o(ven)20 b FN(for)f(recursi)n(v)o(e)g(functions.)208 1027 y FL(per)o(call)g FN(is)i(the)g(quotient)d(of)i FJ(cumtime)g FN(di)n(vided)f(by)g(primiti)n(v)o(e)g(calls)208 1160 y FL(\002lename:lineno\(function\))f FN(pro)o(vides)h(the)h (respecti)n(v)o(e)f(data)h(of)g(each)g(function)208 1373 y(When)d(there)g(are)h(tw)o(o)g(numbers)e(in)i(the)g(\002rst)h(column)d (\(for)h(e)o(xample,)f(`)p FJ(43/3)p FN('\),)h(then)g(the)h(latter)g (is)h(the)e(number)f(of)i(primiti)n(v)o(e)208 1473 y(calls,)30 b(and)d(the)h(former)e(is)j(the)f(actual)g(number)e(of)h(calls.)49 b(Note)28 b(that)g(when)f(the)h(function)e(does)i(not)f(recurse,)i (these)f(tw)o(o)208 1572 y(v)n(alues)19 b(are)h(the)h(same,)f(and)f (only)h(the)g(single)g(\002gure)g(is)h(printed.)0 1719 y FD(runctx)p FJ(\()p FK(command,)c(globals,)i(locals)p FC([)p FK(,)h(\002lename)12 b FC(])p FJ(\))208 1819 y FN(This)24 b(function)f(is)j(similar)f(to)g FJ(run\(\))p FN(,)g(with)g(added)f(ar)o(guments)e(to)j(supply)f(the)h(globals)f(and) g(locals)h(dictionaries)e(for)i(the)208 1918 y FK(command)20 b FN(string.)0 2065 y(Analysis)g(of)g(the)g(pro\002ler)g(data)g(is)h (done)e(using)h(the)g FJ(Stats)g FN(class.)0 2212 y FL(Note:)k FN(The)c FJ(Stats)g FN(class)h(is)g(de\002ned)e(in)i(the)f FJ(pstats)g FN(module.)0 2359 y FL(class)h FD(Stats)p FJ(\()p FK(\002lename)p FC([)p FK(,)c(str)m(eam=sys.stdout)q FC([)p FK(,)j(...)12 b FC(])g(])p FJ(\))208 2459 y FN(This)23 b(class)g(constructor)e(creates)i(an)g(instance)f(of)h(a)g (\223statistics)h(object\224)e(from)g(a)h FK(\002lename)f FN(\(or)g(set)h(of)g(\002lenames\).)32 b FJ(Stats)208 2558 y FN(objects)18 b(are)g(manipulated)f(by)h(methods,)f(in)i(order)e (to)i(print)f(useful)g(reports.)23 b(Y)-9 b(ou)18 b(may)g(specify)g(an) g(alternate)g(output)g(stream)208 2658 y(by)h(gi)n(ving)g(the)h(k)o(e)o (yw)o(ord)f(ar)o(gument,)e FJ(stream)p FN(.)208 2791 y(The)24 b(\002le)h(selected)g(by)f(the)h(abo)o(v)o(e)e(constructor)g (must)h(ha)n(v)o(e)g(been)g(created)g(by)h(the)f(corresponding)d(v)o (ersion)j(of)g FJ(profile)208 2890 y FN(or)19 b FJ(cProfile)p FN(.)24 b(T)-7 b(o)21 b(be)f(speci\002c,)g(there)f(is)i FK(no)f FN(\002le)h(compatibility)d(guaranteed)g(with)i(future)f(v)o (ersions)g(of)h(this)h(pro\002ler)m(,)d(and)208 2990 y(there)h(is)i(no)f(compatibility)f(with)h(\002les)h(produced)d(by)i (other)f(pro\002lers.)208 3123 y(If)h(se)n(v)o(eral)g(\002les)i(are)f (pro)o(vided,)d(all)j(the)g(statistics)h(for)e(identical)g(functions)f (will)j(be)f(coalesced,)e(so)i(that)g(an)g(o)o(v)o(erall)e(vie)n(w)i (of)208 3222 y(se)n(v)o(eral)i(processes)i(can)f(be)g(considered)f(in)h (a)h(single)g(report.)36 b(If)24 b(additional)g(\002les)h(need)f(to)g (be)h(combined)d(with)j(data)f(in)h(an)208 3322 y(e)o(xisting)19 b FJ(Stats)h FN(object,)f(the)h FJ(add\(\))g FN(method)f(can)h(be)g (used.)208 3455 y(Changed)e(in)j(v)o(ersion)e(2.5:)g(The)h FK(str)m(eam)h FN(parameter)e(w)o(as)i(added.)0 3740 y Fv(25.4.1)101 b(The)28 b Fm(Stats)f Fv(Class)0 3943 y FJ(Stats)20 b FN(objects)g(ha)n(v)o(e)f(the)i(follo)n(wing)d (methods:)0 4090 y FD(strip_dirs)p FJ(\(\))208 4189 y FN(This)27 b(method)f(for)h(the)h FJ(Stats)f FN(class)i(remo)o(v)o(es)c (all)k(leading)d(path)h(information)e(from)i(\002le)h(names.)47 b(It)28 b(is)g(v)o(ery)e(useful)h(in)208 4289 y(reducing)22 b(the)i(size)h(of)f(the)h(printout)d(to)j(\002t)g(within)f(\(close)g (to\))g(80)g(columns.)37 b(This)24 b(method)f(modi\002es)h(the)g (object,)h(and)f(the)208 4388 y(stripped)d(information)g(is)i(lost.)33 b(After)23 b(performing)d(a)j(strip)g(operation,)e(the)i(object)f(is)i (considered)d(to)i(ha)n(v)o(e)f(its)i(entries)e(in)h(a)208 4488 y(\223random\224)e(order)m(,)i(as)h(it)g(w)o(as)h(just)f(after)f (object)g(initialization)g(and)g(loading.)33 b(If)24 b FJ(strip_dirs\(\))e FN(causes)h(tw)o(o)h(function)208 4588 y(names)29 b(to)h(be)g(indistinguishable)e(\(the)o(y)g(are)i(on)f (the)h(same)g(line)g(of)g(the)g(same)g(\002lename,)h(and)e(ha)n(v)o(e)g (the)h(same)g(function)208 4687 y(name\),)19 b(then)g(the)h(statistics) i(for)e(these)g(tw)o(o)h(entries)f(are)g(accumulated)e(into)i(a)h (single)f(entry)-5 b(.)0 4834 y FD(add)p FJ(\()p FK(\002lename)p FC([)p FK(,)18 b(...)12 b FC(])p FJ(\))208 4934 y FN(This)30 b(method)f(of)h(the)g FJ(Stats)g FN(class)h(accumulates)f(additional)e (pro\002ling)h(information)f(into)i(the)h(current)d(pro\002ling)h(ob-) 208 5033 y(ject.)51 b(Its)30 b(ar)o(guments)d(should)g(refer)i(to)g (\002lenames)f(created)h(by)f(the)h(corresponding)c(v)o(ersion)j(of)h FJ(profile.run\(\))e FN(or)208 5133 y FJ(cProfile.run\(\))p FN(.)c(Statistics)f(for)e(identically)f(named)h(\(re:)25 b(\002le,)c(line,)f(name\))g(functions)f(are)h(automatically)f(accumu-) 208 5233 y(lated)h(into)g(single)g(function)e(statistics.)p 0 5549 3901 4 v 0 5649 a FI(25.4.)52 b(Ref)n(erence)23 b(Man)o(ual)h(\226)g FJ(profile)d FI(and)j FJ(cProfile)1825 b FI(815)p eop end %%Page: 816 828 TeXDict begin 816 827 bop 0 83 a FD(dump_stats)p FJ(\()p FK(\002lename)p FJ(\))208 183 y FN(Sa)n(v)o(e)17 b(the)h(data)f(loaded) f(into)i(the)f FJ(Stats)g FN(object)g(to)h(a)g(\002le)g(named)e FK(\002lename)p FN(.)23 b(The)17 b(\002le)h(is)h(created)d(if)i(it)g (does)g(not)f(e)o(xist,)h(and)f(is)208 282 y(o)o(v)o(erwritten)g(if)j (it)g(already)f(e)o(xists.)25 b(This)20 b(is)h(equi)n(v)n(alent)d(to)i (the)f(method)g(of)g(the)h(same)g(name)f(on)g(the)h FJ(profile.Profile) 208 382 y FN(and)f FJ(cProfile.Profile)f FN(classes.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.3.)0 529 y FD(sort_stats)p FJ(\()p FK(k)o(e)n(y)p FC([)p FK(,)g(...)12 b FC(])p FJ(\))208 628 y FN(This)j(method)f(modi\002es)h(the)g FJ(Stats)g FN(object)g(by)g(sorting)g(it)h(according)d(to)i(the)h (supplied)e(criteria.)23 b(The)15 b(ar)o(gument)e(is)j(typically)208 728 y(a)k(string)g(identifying)e(the)i(basis)h(of)f(a)h(sort)f(\(e)o (xample:)j FJ('time')d FN(or)g FJ('name')p FN(\).)208 861 y(When)g(more)g(than)g(one)h(k)o(e)o(y)f(is)i(pro)o(vided,)c(then)i (additional)g(k)o(e)o(ys)g(are)h(used)f(as)i(secondary)d(criteria)h (when)g(there)h(is)h(equality)208 960 y(in)j(all)i(k)o(e)o(ys)e (selected)h(before)e(them.)41 b(F)o(or)26 b(e)o(xample,)f FJ(sort_stats\('name',)46 b('file'\))25 b FN(will)i(sort)f(all)g(the)g (entries)208 1060 y(according)18 b(to)i(their)g(function)e(name,)i(and) f(resolv)o(e)h(all)g(ties)i(\(identical)d(function)f(names\))i(by)g (sorting)f(by)h(\002le)h(name.)208 1193 y(Abbre)n(viations)h(can)i(be)g (used)g(for)g(an)o(y)f(k)o(e)o(y)h(names,)h(as)g(long)e(as)i(the)g (abbre)n(viation)c(is)26 b(unambiguous.)34 b(The)24 b(follo)n(wing)f (are)208 1293 y(the)d(k)o(e)o(ys)g(currently)e(de\002ned:)1382 1422 y FL(V)-8 b(alid)20 b(Ar)o(g)p 2028 1452 4 100 v 353 w(Meaning)p 1332 1455 1444 4 v 1382 1525 a FJ('calls')p 2028 1555 4 100 v 347 w FN(call)h(count)1382 1624 y FJ('cumulative')p 2028 1654 V 97 w FN(cumulati)n(v)o(e)d(time)1382 1724 y FJ('file')p 2028 1754 V 397 w FN(\002le)j(name)1382 1824 y FJ('module')p 2028 1854 V 297 w FN(\002le)g(name)1382 1923 y FJ('pcalls')p 2028 1953 V 297 w FN(primiti)n(v)o(e)e(call)h (count)1382 2023 y FJ('line')p 2028 2053 V 397 w FN(line)g(number)1382 2123 y FJ('name')p 2028 2152 V 397 w FN(function)e(name)1382 2222 y FJ('nfl')p 2028 2252 V 447 w FN(name/\002le/line)1382 2322 y FJ('stdname')p 2028 2352 V 247 w FN(standard)h(name)1382 2421 y FJ('time')p 2028 2451 V 397 w FN(internal)g(time)208 2549 y(Note)d(that)h(all)g(sorts)f(on)h(statistics)h(are)e(in)h (descending)d(order)h(\(placing)g(most)i(time)g(consuming)d(items)j (\002rst\),)g(where)f(as)h(name,)208 2649 y(\002le,)j(and)f(line)h (number)e(searches)i(are)g(in)g(ascending)e(order)h(\(alphabetical\).)k (The)d(subtle)f(distinction)g(between)h FJ('nfl')f FN(and)208 2749 y FJ('stdname')24 b FN(is)j(that)f(the)g(standard)e(name)i(is)g(a) h(sort)f(of)f(the)h(name)f(as)i(printed,)e(which)h(means)f(that)h(the)g (embedded)d(line)208 2848 y(numbers)c(get)h(compared)f(in)i(an)f(odd)g (w)o(ay)-5 b(.)26 b(F)o(or)20 b(e)o(xample,)f(lines)i(3,)g(20,)f(and)g (40)g(w)o(ould)g(\(if)g(the)h(\002le)g(names)g(were)f(the)h(same\))208 2948 y(appear)c(in)h(the)g(string)g(order)f(20,)h(3)g(and)g(40.)24 b(In)18 b(contrast,)g FJ('nfl')f FN(does)h(a)h(numeric)e(compare)f(of)i (the)h(line)f(numbers.)23 b(In)18 b(f)o(act,)208 3048 y FJ(sort_stats\('nfl'\))f FN(is)k(the)f(same)h(as)g FJ(sort_stats\('name',)46 b('file',)j('line'\))p FN(.)208 3180 y(F)o(or)18 b(backw)o(ard-compatibility)d(reasons,)j(the)h (numeric)e(ar)o(guments)g FJ(-1)p FN(,)i FJ(0)p FN(,)g FJ(1)p FN(,)g(and)f FJ(2)h FN(are)g(permitted.)k(The)o(y)18 b(are)g(interpreted)208 3280 y(as)k FJ('stdname')p FN(,)e FJ('calls')p FN(,)g FJ('time')p FN(,)h(and)g FJ('cumulative')e FN(respecti)n(v)o(ely)-5 b(.)27 b(If)21 b(this)h(old)f(style)g(format)f (\(numeric\))g(is)208 3380 y(used,)f(only)h(one)f(sort)i(k)o(e)o(y)e (\(the)h(numeric)f(k)o(e)o(y\))g(will)i(be)f(used,)g(and)f(additional)g (ar)o(guments)f(will)j(be)f(silently)h(ignored.)0 3526 y FD(reverse_order)p FJ(\(\))208 3626 y FN(This)i(method)e(for)i(the)f FJ(Stats)h FN(class)h(re)n(v)o(erses)e(the)h(ordering)e(of)h(the)h (basic)h(list)g(within)e(the)h(object.)33 b(Note)23 b(that)g(by)f(def)o (ault)208 3726 y(ascending)c(vs)j(descending)d(order)h(is)i(properly)d (selected)i(based)g(on)g(the)g(sort)g(k)o(e)o(y)g(of)g(choice.)0 3873 y FD(print_stats)p FJ(\()p FC([)p FK(r)m(estriction,)e(...)12 b FC(])p FJ(\))208 3972 y FN(This)20 b(method)f(for)g(the)i FJ(Stats)e FN(class)i(prints)f(out)g(a)h(report)e(as)i(described)e(in)h (the)g FJ(profile.run\(\))f FN(de\002nition.)208 4105 y(The)h(order)f(of)i(the)f(printing)f(is)j(based)e(on)g(the)h(last)g FJ(sort_stats\(\))e FN(operation)g(done)h(on)g(the)h(object)f (\(subject)g(to)h(ca)n(v)o(eats)208 4205 y(in)f FJ(add\(\))g FN(and)f FJ(strip_dirs\(\))p FN(\).)208 4338 y(The)i(ar)o(guments)f (pro)o(vided)f(\(if)j(an)o(y\))f(can)g(be)h(used)g(to)g(limit)g(the)g (list)h(do)n(wn)e(to)h(the)g(signi\002cant)f(entries.)30 b(Initially)-5 b(,)21 b(the)h(list)h(is)208 4437 y(tak)o(en)17 b(to)i(be)f(the)g(complete)g(set)h(of)f(pro\002led)f(functions.)23 b(Each)18 b(restriction)f(is)i(either)f(an)h(inte)o(ger)e(\(to)h (select)h(a)f(count)g(of)g(lines\),)208 4537 y(or)j(a)h(decimal)g (fraction)e(between)h(0.0)h(and)f(1.0)g(inclusi)n(v)o(e)g(\(to)h (select)g(a)h(percentage)d(of)h(lines\),)h(or)g(a)g(re)o(gular)e(e)o (xpression)h(\(to)208 4636 y(pattern)h(match)h(the)g(standard)f(name)h (that)g(is)h(printed;)g(as)g(of)f(Python)f(1.5b1,)g(this)h(uses)h(the)f (Perl-style)g(re)o(gular)f(e)o(xpression)208 4736 y(syntax)h(de\002ned) g(by)g(the)h FJ(re)g FN(module\).)34 b(If)24 b(se)n(v)o(eral)f (restrictions)h(are)f(pro)o(vided,)f(then)i(the)o(y)f(are)h(applied)f (sequentially)-5 b(.)34 b(F)o(or)208 4836 y(e)o(xample:)444 5060 y FA(print_stats\(.1,)42 b('foo:'\))208 5249 y FN(w)o(ould)18 b(\002rst)j(limit)f(the)f(printing)g(to)g(\002rst)i(10\045)e(of)g (list,)i(and)e(then)g(only)g(print)g(functions)f(that)i(were)f(part)g (of)h(\002lename)f(`)p FO(.*f)n(oo:)p FN('.)208 5349 y(In)g(contrast,)h(the)g(command:)p 0 5549 3901 4 v 0 5649 a FI(816)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g (Pro\002lers)p eop end %%Page: 817 829 TeXDict begin 817 828 bop 444 174 a FA(print_stats\('foo:',)41 b(.1\))208 364 y FN(w)o(ould)25 b(limit)h(the)g(list)h(to)f(all)h (functions)d(ha)n(ving)h(\002le)i(names)f(`)p FO(.*f)n(oo:)p FN(',)f(and)g(then)h(proceed)e(to)i(only)f(print)g(the)h(\002rst)h (10\045)f(of)208 463 y(them.)0 610 y FD(print_callers)p FJ(\()p FC([)p FK(r)m(estriction,)18 b(...)12 b FC(])p FJ(\))208 710 y FN(This)21 b(method)f(for)h(the)g FJ(Stats)g FN(class)h(prints)f(a)h(list)g(of)f(all)h(functions)e(that)i(called)f (each)g(function)e(in)j(the)f(pro\002led)f(database.)208 810 y(The)i(ordering)e(is)k(identical)e(to)g(that)h(pro)o(vided)d(by)i FJ(print_stats\(\))p FN(,)f(and)h(the)h(de\002nition)e(of)i(the)f (restricting)g(ar)o(gument)208 909 y(is)j(also)g(identical.)37 b(Each)24 b(caller)g(is)i(reported)c(on)j(its)g(o)n(wn)f(line.)38 b(The)24 b(format)f(dif)n(fers)h(slightly)g(depending)e(on)i(the)h (pro\002ler)208 1009 y(that)20 b(produced)e(the)i(stats:)349 1222 y FM(\017)o FN(W)m(ith)h FJ(profile)p FN(,)f(a)h(number)e(is)j (sho)n(wn)e(in)g(parentheses)g(after)g(each)h(caller)f(to)h(sho)n(w)f (ho)n(w)h(man)o(y)e(times)i(this)g(speci\002c)390 1322 y(call)g(w)o(as)g(made.)j(F)o(or)c(con)m(v)o(enience,)d(a)k(second)e (non-parenthesized)e(number)h(repeats)i(the)g(cumulati)n(v)o(e)f(time)h (spent)g(in)390 1421 y(the)g(function)f(at)i(the)f(right.)349 1554 y FM(\017)o FN(W)m(ith)25 b FJ(cProfile)p FN(,)g(each)f(caller)h (is)h(preceeded)d(by)h(three)g(numbers:)33 b(the)25 b(number)e(of)h (times)h(this)h(speci\002c)f(call)g(w)o(as)390 1654 y(made,)18 b(and)g(the)h(total)g(and)f(cumulati)n(v)o(e)e(times)j(spent)g(in)f (the)h(current)e(function)g(while)i(it)g(w)o(as)g(in)m(v)n(ok)o(ed)e (by)h(this)h(speci\002c)390 1753 y(caller)-5 b(.)0 1919 y FD(print_callees)p FJ(\()p FC([)p FK(r)m(estriction,)18 b(...)12 b FC(])p FJ(\))208 2019 y FN(This)23 b(method)f(for)h(the)g FJ(Stats)g FN(class)i(prints)e(a)h(list)g(of)f(all)h(function)e(that)h (were)h(called)f(by)g(the)g(indicated)g(function.)32 b(Aside)208 2119 y(from)20 b(this)i(re)n(v)o(ersal)e(of)h(direction)f (of)h(calls)h(\(re:)27 b(called)21 b(vs)h(w)o(as)g(called)f(by\),)g (the)g(ar)o(guments)e(and)i(ordering)e(are)j(identical)e(to)208 2218 y(the)g FJ(print_callers\(\))e FN(method.)0 2546 y FE(25.5)121 b(Limitations)0 2779 y FN(One)28 b(limitation)g(has)g(to) h(do)e(with)i(accurac)o(y)d(of)i(timing)g(information.)47 b(There)27 b(is)i(a)g(fundamental)d(problem)g(with)i(deterministic)0 2878 y(pro\002lers)i(in)m(v)n(olving)f(accurac)o(y)-5 b(.)55 b(The)31 b(most)g(ob)o(vious)e(restriction)h(is)i(that)f(the)g (underlying)d(\223clock\224)j(is)g(only)g(ticking)f(at)h(a)h(rate)0 2978 y(\(typically\))17 b(of)i(about)f(.001)g(seconds.)24 b(Hence)18 b(no)g(measurements)g(will)i(be)e(more)g(accurate)g(than)h (the)g(underlying)d(clock.)24 b(If)19 b(enough)0 3077 y(measurements)j(are)i(tak)o(en,)g(then)f(the)h(\223error\224)e(will)j (tend)e(to)h(a)n(v)o(erage)e(out.)35 b(Unfortunately)-5 b(,)22 b(remo)o(ving)f(this)j(\002rst)h(error)d(induces)h(a)0 3177 y(second)c(source)h(of)g(error)-5 b(.)0 3324 y(The)21 b(second)f(problem)g(is)i(that)f(it)h(\223tak)o(es)f(a)h(while\224)f (from)f(when)g(an)h(e)n(v)o(ent)g(is)h(dispatched)e(until)g(the)i (pro\002ler')-5 b(s)20 b(call)i(to)f(get)g(the)g(time)0 3424 y(actually)j FK(g)o(ets)i FN(the)f(state)g(of)g(the)g(clock.)39 b(Similarly)-5 b(,)25 b(there)f(is)i(a)g(certain)e(lag)h(when)f(e)o (xiting)g(the)h(pro\002ler)f(e)n(v)o(ent)g(handler)g(from)g(the)0 3523 y(time)e(that)f(the)h(clock')-5 b(s)21 b(v)n(alue)g(w)o(as)h (obtained)e(\(and)g(then)h(squirreled)f(a)o(w)o(ay\),)h(until)h(the)f (user')-5 b(s)22 b(code)f(is)h(once)f(again)f(e)o(x)o(ecuting.)27 b(As)0 3623 y(a)d(result,)h(functions)d(that)i(are)g(called)f(man)o(y)g (times,)i(or)e(call)h(man)o(y)f(functions,)g(will)i(typically)d (accumulate)h(this)h(error)-5 b(.)35 b(The)24 b(error)0 3722 y(that)h(accumulates)f(in)h(this)h(f)o(ashion)e(is)i(typically)e (less)j(than)d(the)h(accurac)o(y)f(of)g(the)i(clock)e(\(less)i(than)e (one)h(clock)f(tick\),)i(b)n(ut)f(it)h FK(can)0 3822 y FN(accumulate)19 b(and)g(become)g(v)o(ery)g(signi\002cant.)0 3969 y(The)g(problem)e(is)k(more)d(important)g(with)h FJ(profile)g FN(than)f(with)i(the)f(lo)n(wer)n(-o)o(v)o(erhead)d FJ(cProfile)p FN(.)23 b(F)o(or)c(this)h(reason,)e FJ(profile)0 4069 y FN(pro)o(vides)k(a)j(means)e(of)h(calibrating)f(itself)i(for)e (a)h(gi)n(v)o(en)f(platform)g(so)h(that)g(this)h(error)e(can)h(be)g (probabilistically)e(\(on)h(the)h(a)n(v)o(erage\))0 4168 y(remo)o(v)o(ed.)51 b(After)30 b(the)f(pro\002ler)g(is)i(calibrated,)g (it)f(will)h(be)e(more)g(accurate)g(\(in)h(a)g(least)g(square)f (sense\),)j(b)n(ut)e(it)g(will)h(sometimes)0 4268 y(produce)21 b(ne)o(gati)n(v)o(e)g(numbers)g(\(when)h(call)i(counts)e(are)h(e)o (xceptionally)e(lo)n(w)-5 b(,)23 b(and)f(the)h(gods)f(of)h(probability) e(w)o(ork)h(against)h(you)f(:-\).)0 4367 y(\))28 b(Do)21 b FK(not)g FN(be)f(alarmed)g(by)h(ne)o(gati)n(v)o(e)e(numbers)g(in)j (the)f(pro\002le.)26 b(The)o(y)20 b(should)g FK(only)h FN(appear)f(if)h(you)f(ha)n(v)o(e)g(calibrated)g(your)g(pro\002ler)m(,) 0 4467 y(and)g(the)g(results)g(are)g(actually)g(better)g(than)g (without)f(calibration.)0 4795 y FE(25.6)121 b(Calibr)o(ation)0 5027 y FN(The)21 b(pro\002ler)f(of)i(the)f FJ(profile)g FN(module)f(subtracts)h(a)h(constant)e(from)h(each)g(e)n(v)o(ent)f (handling)g(time)h(to)h(compensate)e(for)h(the)g(o)o(v)o(er)n(-)0 5127 y(head)d(of)h(calling)g(the)g(time)h(function,)d(and)i(socking)f (a)o(w)o(ay)g(the)h(results.)25 b(By)20 b(def)o(ault,)e(the)i(constant) e(is)i(0.)25 b(The)19 b(follo)n(wing)e(procedure)0 5227 y(can)j(be)g(used)g(to)g(obtain)g(a)g(better)g(constant)g(for)f(a)i(gi) n(v)o(en)e(platform)f(\(see)j(discussion)e(in)i(section)f(Limitations)f (abo)o(v)o(e\).)p 0 5549 3901 4 v 0 5649 a FI(25.5.)52 b(Limitations)3131 b(817)p eop end %%Page: 818 830 TeXDict begin 818 829 bop 236 174 a FA(import)44 b(profile)236 266 y(pr)h(=)f(profile.Profile\(\))236 357 y(for)h(i)f(in)h (range\(5\):)416 448 y(print)f(pr.calibrate\(10000\))0 735 y FN(The)19 b(method)f(e)o(x)o(ecutes)g(the)h(number)f(of)h(Python) f(calls)i(gi)n(v)o(en)e(by)h(the)g(ar)o(gument,)e(directly)h(and)h (again)f(under)g(the)h(pro\002ler)m(,)f(measur)n(-)0 834 y(ing)h(the)g(time)g(for)g(both.)24 b(It)19 b(then)g(computes)f (the)h(hidden)f(o)o(v)o(erhead)f(per)h(pro\002ler)h(e)n(v)o(ent,)f(and) g(returns)h(that)g(as)h(a)g(\003oat.)k(F)o(or)19 b(e)o(xample,)0 934 y(on)h(an)g(800)g(MHz)h(Pentium)e(running)g(W)m(indo)n(ws)g(2000,)g (and)h(using)g(Python')-5 b(s)20 b(time.clock\(\))e(as)j(the)g(timer)m (,)f(the)g(magical)g(number)f(is)0 1034 y(about)g(12.5e-6.)0 1181 y(The)i(object)g(of)g(this)h(e)o(x)o(ercise)f(is)h(to)g(get)f(a)h (f)o(airly)f(consistent)g(result.)29 b(If)21 b(your)f(computer)g(is)i FK(very)g FN(f)o(ast,)g(or)f(your)f(timer)i(function)d(has)0 1280 y(poor)g(resolution,)g(you)g(might)g(ha)n(v)o(e)h(to)g(pass)h (100000,)d(or)h(e)n(v)o(en)h(1000000,)d(to)j(get)g(consistent)g (results.)0 1427 y(When)g(you)f(ha)n(v)o(e)h(a)h(consistent)e(answer)m (,)h(there)f(are)h(three)g(w)o(ays)h(you)e(can)h(use)g(it:)2390 1397 y FF(2)236 1665 y FA(import)44 b(profile)236 1848 y(#)h(1.)f(Apply)g(computed)g(bias)g(to)h(all)f(Profile)f(instances)h (created)f(hereafter.)236 1939 y(profile.Profile.bias)f(=)i (your_computed_bias)236 2122 y(#)h(2.)f(Apply)g(computed)g(bias)g(to)h (a)f(specific)g(Profile)f(instance.)236 2213 y(pr)i(=)f (profile.Profile\(\))236 2305 y(pr.bias)g(=)h(your_computed_bias)236 2487 y(#)g(3.)f(Specify)g(computed)g(bias)g(in)g(instance)g (constructor.)236 2579 y(pr)h(=)f (profile.Profile\(bias=your_computed_bias\))0 2865 y FN(If)20 b(you)f(ha)n(v)o(e)g(a)h(choice,)f(you)g(are)h(better)f(of)n (f)g(choosing)f(a)j(smaller)e(constant,)g(and)h(then)f(your)g(results)h (will)g(\223less)h(often\224)e(sho)n(w)g(up)h(as)0 2965 y(ne)o(gati)n(v)o(e)e(in)i(pro\002le)g(statistics.)0 3292 y FE(25.7)121 b(Extensions)34 b(\227)f(Der)r(iving)g(Better)i (Pro\002lers)0 3525 y FN(The)c FJ(Profile)g FN(class)i(of)e(both)g (modules,)i FJ(profile)e FN(and)g FJ(cProfile)p FN(,)i(were)e(written)h (so)g(that)f(deri)n(v)o(ed)f(classes)j(could)e(be)0 3625 y(de)n(v)o(eloped)c(to)j(e)o(xtend)f(the)h(pro\002ler)-5 b(.)53 b(The)30 b(details)g(are)g(not)f(described)g(here,)i(as)g(doing) d(this)j(successfully)e(requires)g(an)h(e)o(xpert)0 3724 y(understanding)16 b(of)i(ho)n(w)g(the)h FJ(Profile)f FN(class)i(w)o(orks)e(internally)-5 b(.)23 b(Study)18 b(the)h(source)f(code)g(of)g(the)h(module)e(carefully)h(if)h(you)e(w)o (ant)0 3824 y(to)j(pursue)f(this.)0 3971 y(If)g(all)g(you)g(w)o(ant)g (to)g(do)f(is)i(change)e(ho)n(w)g(current)g(time)h(is)h(determined)d (\(for)h(e)o(xample,)g(to)h(force)f(use)h(of)g(w)o(all-clock)f(time)h (or)g(elapsed)0 4070 y(process)h(time\),)g(pass)g(the)g(timing)g (function)e(you)i(w)o(ant)g(to)g(the)h FJ(Profile)e FN(class)i (constructor:)236 4308 y FA(pr)45 b(=)f (profile.Profile\(your_time_func\))0 4595 y FN(The)20 b(resulting)f(pro\002ler)g(will)i(then)f(call)h FJ(your_time_func\(\))p FN(.)0 4825 y FD(profile.Profile)39 b FJ(your_time_func\(\))19 b FN(should)j(return)f(a)h(single)g(number)m(,)e(or)i(a)h(list)g(of)f (numbers)f(whose)g(sum)h(is)i(the)208 4924 y(current)29 b(time)i(\(lik)o(e)g(what)f FJ(os.times\(\))g FN(returns\).)55 b(If)31 b(the)f(function)f(returns)h(a)h(single)g(time)g(number)m(,)g (or)f(the)h(list)h(of)208 5024 y(returned)18 b(numbers)h(has)h(length)f (2,)h(then)g(you)f(will)i(get)g(an)f(especially)f(f)o(ast)i(v)o(ersion) e(of)h(the)g(dispatch)g(routine.)208 5157 y(Be)e(w)o(arned)f(that)g (you)g(should)f(calibrate)h(the)h(pro\002ler)e(class)j(for)e(the)g (timer)h(function)d(that)j(you)f(choose.)23 b(F)o(or)17 b(most)h(machines,)p 0 5228 1560 4 v 90 5284 a FB(2)120 5307 y FH(Prior)g(to)g(Python)h(2.2,)f(it)h(w)o(as)f(necessary)i(to)e (edit)i(the)e(pro\002ler)i(source)f(code)g(to)f(embed)h(the)g(bias)f (as)h(a)f(literal)i(number)l(.)25 b(Y)-7 b(ou)18 b(still)h(can,)g(b)o (ut)f(that)i(method)f(is)f(no)0 5386 y(longer)g(described,)h(because)g (no)e(longer)h(needed.)p 0 5549 3901 4 v 0 5649 a FI(818)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g(Pro\002lers)p eop end %%Page: 819 831 TeXDict begin 819 830 bop 208 83 a FN(a)23 b(timer)f(that)g(returns)g (a)h(lone)f(inte)o(ger)g(v)n(alue)f(will)j(pro)o(vide)c(the)j(best)g (results)f(in)h(terms)g(of)f(lo)n(w)g(o)o(v)o(erhead)e(during)h (pro\002ling.)208 183 y(\()p FJ(os.times\(\))j FN(is)k FK(pr)m(etty)e FN(bad,)h(as)g(it)g(returns)f(a)g(tuple)g(of)h (\003oating)e(point)h(v)n(alues\).)42 b(If)27 b(you)e(w)o(ant)h(to)h (substitute)f(a)h(better)208 282 y(timer)21 b(in)g(the)g(cleanest)g(f)o (ashion,)f(deri)n(v)o(e)g(a)i(class)g(and)f(hardwire)e(a)j(replacement) e(dispatch)g(method)g(that)h(best)g(handles)g(your)208 382 y(timer)f(call,)g(along)f(with)i(the)f(appropriate)e(calibration)g (constant.)0 548 y FD(cProfile.Profile)39 b FJ(your_time_func\(\))22 b FN(should)i(return)f(a)i(single)g(number)-5 b(.)38 b(If)24 b(it)i(returns)e(plain)g(inte)o(gers,)h(you)f(can)208 648 y(also)g(in)m(v)n(ok)o(e)f(the)h(class)h(constructor)d(with)i(a)h (second)e(ar)o(gument)f(specifying)g(the)j(real)f(duration)e(of)i(one)f (unit)h(of)g(time.)37 b(F)o(or)208 747 y(e)o(xample,)30 b(if)g FJ(your_integer_time_func\(\))25 b FN(returns)k(times)h (measured)e(in)i(thousands)e(of)i(seconds,)h(you)d(w)o(ould)208 847 y(constuct)19 b(the)h FJ(Profile)g FN(instance)f(as)i(follo)n(ws:) 444 1071 y FA(pr)44 b(=)h(profile.Profile\(your_integer_time_func,)38 b(0.001\))208 1343 y FN(As)21 b(the)f FJ(cProfile.Profile)d FN(class)22 b(cannot)d(be)h(calibrated,)e(custom)i(timer)g(functions)f (should)g(be)h(used)g(with)g(care)g(and)208 1443 y(should)i(be)h(as)h (f)o(ast)g(as)g(possible.)33 b(F)o(or)23 b(the)g(best)h(results)f(with) h(a)f(custom)g(timer)m(,)g(it)h(might)f(be)g(necessary)f(to)i (hard-code)c(it)k(in)208 1543 y(the)c(C)h(source)e(of)h(the)g(internal) g FJ(_lsprof)f FN(module.)0 1870 y FE(25.8)121 b Fx(hotshot)32 b FE(\227)g(High)i(perf)l(or)s(mance)i(logging)f(pro\002ler)0 2103 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 2250 y(This)34 b(module)e(pro)o(vides)g(a)j(nicer)e(interf)o(ace)g(to)h(the)f FJ(_hotshot)g FN(C)i(module.)64 b(Hotshot)33 b(is)i(a)f(replacement)e (for)i(the)f(e)o(xisting)0 2349 y FJ(profile)e FN(module.)59 b(As)33 b(it')-5 b(s)33 b(written)e(mostly)h(in)g(C,)h(it)f(should)f (result)h(in)g(a)h(much)e(smaller)h(performance)d(impact)i(than)h(the)0 2449 y(e)o(xisting)19 b FJ(profile)h FN(module.)0 2596 y FL(Note:)58 b FN(The)21 b FJ(hotshot)h FN(module)e(focuses)i(on)g (minimizing)e(the)i(o)o(v)o(erhead)e(while)i(pro\002ling,)f(at)h(the)g (e)o(xpense)f(of)h(long)f(data)h(post-)0 2696 y(processing)17 b(times.)25 b(F)o(or)18 b(common)f(usages)h(it)i(is)f(recommended)c(to) k(use)g FJ(cProfile)e FN(instead.)25 b FJ(hotshot)17 b FN(is)j(not)e(maintained)f(and)0 2795 y(might)j(be)g(remo)o(v)o(ed)d (from)j(the)g(standard)f(library)g(in)h(the)g(future.)0 2942 y(Changed)j(in)i(v)o(ersion)e(2.5:)h(the)h(results)g(should)e(be)i (more)e(meaningful)g(than)h(in)g(the)h(past:)34 b(the)25 b(timing)f(core)g(contained)e(a)j(critical)0 3042 y(b)n(ug.)p 0 3132 3901 17 v 0 3423 17 292 v 75 3247 a FL(W)-5 b(ar)o(ning:)49 b FN(The)20 b FJ(hotshot)f FN(pro\002ler)h(does)f(not)h(yet)g(w)o(ork)g (well)g(with)g(threads.)25 b(It)20 b(is)h(useful)f(to)g(use)g(an)g (unthreaded)e(script)i(to)75 3347 y(run)f(the)h(pro\002ler)g(o)o(v)o (er)e(the)j(code)e(you')l(re)f(interested)i(in)g(measuring)f(if)h(at)h (all)g(possible.)p 3883 3423 V 0 3439 3901 17 v 0 3595 a FL(class)g FD(Profile)p FJ(\()p FK(lo)o(g\002le)p FC([)p FK(,)c(linee)o(vents)p FC([)p FK(,)i(linetimings)12 b FC(])g(])p FJ(\))208 3694 y FN(The)22 b(pro\002ler)f(object.)31 b(The)22 b(ar)o(gument)e FK(lo)o(g\002le)i FN(is)h(the)f(name)g(of)g(a) h(log)f(\002le)h(to)g(use)f(for)g(logged)f(pro\002le)h(data.)31 b(The)22 b(ar)o(gument)208 3794 y FK(linee)o(vents)g FN(speci\002es)i(whether)e(to)h(generate)f(e)n(v)o(ents)g(for)h(e)n(v)o (ery)f(source)g(line,)i(or)e(just)i(on)f(function)e(call/return.)33 b(It)23 b(def)o(aults)208 3894 y(to)c FJ(0)h FN(\(only)e(log)h (function)f(call/return\).)23 b(The)c(ar)o(gument)e FK(linetimings)i FN(speci\002es)g(whether)g(to)g(record)f(timing)h(information.)j(It)208 3993 y(def)o(aults)d(to)i FJ(1)f FN(\(store)g(timing)g(information\).)0 4278 y Fv(25.8.1)101 b(Pro\002le)29 b(Objects)0 4481 y FN(Pro\002le)20 b(objects)g(ha)n(v)o(e)g(the)g(follo)n(wing)e (methods:)0 4628 y FD(addinfo)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(value)p FJ(\))208 4727 y FN(Add)g(an)h(arbitrary)f(labelled)h (v)n(alue)f(to)h(the)h(pro\002le)e(output.)0 4874 y FD(close)p FJ(\(\))208 4974 y FN(Close)h(the)h(log\002le)f(and)f(terminate)h(the)g (pro\002ler)-5 b(.)0 5121 y FD(fileno)p FJ(\(\))208 5220 y FN(Return)19 b(the)i(\002le)f(descriptor)f(of)h(the)g(pro\002ler')-5 b(s)20 b(log)g(\002le.)p 0 5549 3901 4 v 0 5649 a FI(25.8.)52 b FJ(hotshot)22 b FI(\227)h(High)h(perf)n(or)r(mance)f(logging)h (pro\002ler)1821 b(819)p eop end %%Page: 820 832 TeXDict begin 820 831 bop 0 83 a FD(run)p FJ(\()p FK(cmd)r FJ(\))208 183 y FN(Pro\002le)18 b(an)g FJ(exec)p FN(-compatible)d (string)j(in)h(the)f(script)g(en)m(vironment.)j(The)d(globals)f(from)h (the)g FJ(__main__)f FN(module)g(are)h(used)208 282 y(as)i(both)g(the)g (globals)g(and)f(locals)i(for)e(the)h(script.)0 429 y FD(runcall)p FJ(\()p FK(func,)e(*ar)m(gs,)i(**k)o(e)n(ywor)m(ds)p FJ(\))208 529 y FN(Pro\002le)g(a)h(single)f(call)h(of)f(a)g(callable.) 25 b(Additional)19 b(positional)h(and)g(k)o(e)o(yw)o(ord)e(ar)o (guments)g(may)i(be)g(passed)h(along;)e(the)i(result)208 628 y(of)f(the)g(call)g(is)i(returned,)c(and)i(e)o(xceptions)e(are)i (allo)n(wed)g(to)g(propagate)e(cleanly)-5 b(,)19 b(while)h(ensuring)f (that)h(pro\002ling)f(is)i(disabled)208 728 y(on)e(the)i(w)o(ay)f(out.) 0 875 y FD(runctx)p FJ(\()p FK(cmd,)f(globals,)g(locals)p FJ(\))208 975 y FN(Ev)n(aluate)g(an)h FJ(exec)p FN(-compatible)d (string)j(in)h(a)f(speci\002c)h(en)m(vironment.)h(The)d(string)h(is)h (compiled)e(before)g(pro\002ling)g(be)o(gins.)0 1121 y FD(start)p FJ(\(\))208 1221 y FN(Start)h(the)g(pro\002ler)-5 b(.)0 1368 y FD(stop)p FJ(\(\))208 1468 y FN(Stop)20 b(the)g(pro\002ler)-5 b(.)0 1752 y Fv(25.8.2)101 b(Using)28 b(hotshot)g(data)0 1955 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.2.)0 2102 y(This)h(module)f(loads)h(hotshot)f(pro\002ling)g(data)h(into)g (the)g(standard)f FJ(pstats)h FN(Stats)h(objects.)0 2249 y FD(load)p FJ(\()p FK(\002lename)p FJ(\))208 2349 y FN(Load)e(hotshot)g(data)h(from)f FK(\002lename)p FN(.)24 b(Returns)c(an)g(instance)g(of)g(the)g FJ(pstats.Stats)f FN(class.)0 2496 y FL(See)i(Also:)0 2642 y FN(Module)e FJ(profile)g FN(\(section)h(25.4\):)208 2742 y(The)f FJ(profile)h FN(module')-5 b(s)19 b FJ(Stats)h FN(class)0 3027 y Fv(25.8.3)101 b(Example)29 b(Usage)0 3230 y FN(Note)24 b(that)g(this)h(e)o(xample)e(runs)g(the)i(p)o(ython)d (\223benchmark\224)f(p)o(ystones.)37 b(It)24 b(can)g(tak)o(e)g(some)g (time)g(to)h(run,)f(and)g(will)g(produce)f(lar)o(ge)0 3329 y(output)c(\002les.)236 3568 y FA(>>>)45 b(import)e(hotshot,)h (hotshot.stats,)e(test.pystone)236 3659 y(>>>)j(prof)f(=)g (hotshot.Profile\("stones.prof"\))236 3750 y(>>>)h(benchtime,)e(stones) h(=)g(prof.runcall\(test.pystone.pystones\))236 3842 y(>>>)h(prof.close\(\))236 3933 y(>>>)g(stats)f(=)g (hotshot.stats.load\("stones.prof"\))236 4024 y(>>>)h (stats.strip_dirs\(\))236 4116 y(>>>)g(stats.sort_stats\('time',)40 b('calls'\))236 4207 y(>>>)45 b(stats.print_stats\(20\))640 4298 y(850004)f(function)f(calls)h(in)h(10.090)e(CPU)i(seconds)371 4481 y(Ordered)e(by:)i(internal)e(time,)h(call)g(count)371 4664 y(ncalls)88 b(tottime)h(percall)f(cumtime)h(percall)43 b(filename:lineno\(function\))595 4755 y(1)179 b(3.295)g(3.295)133 b(10.090)h(10.090)43 b(pystone.py:79\(Proc0\))371 4846 y(150000)178 b(1.315)h(0.000)f(1.315)g(0.000)44 b (pystone.py:203\(Proc7\))416 4938 y(50000)178 b(1.313)h(0.000)f(1.463)g (0.000)44 b(pystone.py:229\(Func2\))281 5029 y(.)281 5120 y(.)281 5212 y(.)p 0 5549 3901 4 v 0 5649 a FI(820)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g(Pro\002lers)p eop end %%Page: 821 833 TeXDict begin 821 832 bop 0 87 a FE(25.9)121 b Fx(timeit)32 b FE(\227)h(Measure)h(e)l(x)l(ecution)i(time)d(of)h(small)e(code)i (snippets)0 320 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 467 y(This)24 b(module)f(pro)o(vides)f(a)i(simple)g(w)o(ay)g(to)h(time) f(small)g(bits)h(of)f(Python)e(code.)36 b(It)24 b(has)h(both)e(command) f(line)i(as)h(well)f(as)h(callable)0 567 y(interf)o(aces.)34 b(It)23 b(a)n(v)n(oids)h(a)f(number)f(of)h(common)e(traps)i(for)g (measuring)f(e)o(x)o(ecution)f(times.)35 b(See)23 b(also)h(T)m(im)f (Peters')h(introduction)c(to)0 666 y(the)g(\223)-7 b(Algorithms\224)19 b(chapter)g(in)i(the)f FK(Python)f(Cookbook)p FN(,)f(published)h(by)g (O'Reilly)-5 b(.)0 813 y(The)20 b(module)f(de\002nes)h(the)g(follo)n (wing)e(public)i(class:)0 960 y FL(class)h FD(Timer)p FJ(\()p FC([)p FK(stmt=)p Fn('pass')e FC([)p FK(,)h(setup=)p Fn('pass')f FC([)p FK(,)h(timer=\241timer)i(function\277)12 b FC(])g(])g(])p FJ(\))208 1060 y FN(Class)21 b(for)f(timing)f(e)o(x)o (ecution)f(speed)i(of)g(small)h(code)e(snippets.)208 1192 y(The)28 b(constructor)g(tak)o(es)h(a)h(statement)e(to)i(be)f (timed,)i(an)e(additional)e(statement)i(used)g(for)g(setup,)h(and)f(a)h (timer)f(function.)208 1292 y(Both)21 b(statements)g(def)o(ault)f(to)h FJ('pass')p FN(;)g(the)g(timer)g(function)e(is)j(platform-dependent)16 b(\(see)21 b(the)g(module)f(doc)g(string\).)27 b(The)208 1392 y(statements)20 b(may)g(contain)f(ne)n(wlines,)g(as)i(long)f(as)g (the)o(y)g(don')o(t)e(contain)i(multi-line)f(string)h(literals.)208 1525 y(T)-7 b(o)21 b(measure)f(the)h(e)o(x)o(ecution)e(time)i(of)f(the) h(\002rst)h(statement,)f(use)g(the)g FJ(timeit\(\))f FN(method.)26 b(The)21 b FJ(repeat\(\))f FN(method)f(is)j(a)208 1624 y(con)m(v)o(enience)17 b(to)j(call)h FJ(timeit\(\))e FN(multiple)g(times)i(and)f(return)f(a)h(list)i(of)e(results.)0 1771 y FD(print_exc)p FJ(\()p FC([)p FK(\002le=)p Fn(None)12 b FC(])p FJ(\))208 1871 y FN(Helper)19 b(to)i(print)e(a)i(traceback)e (from)g(the)h(timed)g(code.)208 2004 y(T)-7 b(ypical)19 b(use:)623 2228 y FA(t)45 b(=)f(Timer\(...\))313 b(#)44 b(outside)g(the)g(try/except)623 2319 y(try:)802 2410 y(t.timeit\(...\))178 b(#)44 b(or)h(t.repeat\(...\))623 2502 y(except:)802 2593 y(t.print_exc\(\))208 2782 y FN(The)21 b(adv)n(antage)f(o)o(v)o(er)h(the)h(standard)f(traceback)g (is)i(that)f(source)f(lines)h(in)h(the)f(compiled)e(template)i(will)h (be)f(displayed.)29 b(The)208 2882 y(optional)18 b FK(\002le)j FN(ar)o(gument)c(directs)k(where)e(the)h(traceback)f(is)i(sent;)g(it)g (def)o(aults)f(to)g FJ(sys.stderr)p FN(.)0 3029 y FD(repeat)p FJ(\()p FC([)p FK(r)m(epeat)p Fn(=3)e FC([)p FK(,)i(number)p Fn(=1000000)12 b FC(])g(])p FJ(\))208 3129 y FN(Call)21 b FJ(timeit\(\))e FN(a)i(fe)n(w)f(times.)208 3261 y(This)25 b(is)g(a)g(con)m(v)o(enience)d(function)h(that)i(calls)h(the)e FJ(timeit\(\))g FN(repeatedly)-5 b(,)24 b(returning)f(a)i(list)h(of)e (results.)39 b(The)25 b(\002rst)g(ar)o(gu-)208 3361 y(ment)g (speci\002es)h(ho)n(w)f(man)o(y)g(times)h(to)f(call)i FJ(timeit\(\))p FN(.)40 b(The)25 b(second)g(ar)o(gument)e(speci\002es)j (the)g FK(number)h FN(ar)o(gument)c(for)208 3461 y FJ(timeit\(\))p FN(.)208 3593 y FL(Note:)k FN(It')-5 b(s)22 b(tempting)f(to)h (calculate)f(mean)g(and)g(standard)g(de)n(viation)f(from)h(the)g (result)h(v)o(ector)e(and)i(report)e(these.)30 b(Ho)n(we)n(v)o(er)m(,) 208 3693 y(this)25 b(is)g(not)f(v)o(ery)g(useful.)37 b(In)25 b(a)g(typical)f(case,)i(the)e(lo)n(west)h(v)n(alue)f(gi)n(v)o (es)g(a)h(lo)n(wer)f(bound)f(for)h(ho)n(w)g(f)o(ast)h(your)e(machine)h (can)208 3793 y(run)c(the)i(gi)n(v)o(en)e(code)h(snippet;)h(higher)e(v) n(alues)h(in)h(the)g(result)f(v)o(ector)g(are)g(typically)g(not)g (caused)g(by)g(v)n(ariability)g(in)g(Python')-5 b(s)208 3892 y(speed,)20 b(b)n(ut)g(by)g(other)g(processes)g(interfering)f (with)h(your)f(timing)h(accurac)o(y)-5 b(.)24 b(So)d(the)f FJ(min\(\))h FN(of)f(the)g(result)h(is)g(probably)e(the)208 3992 y(only)25 b(number)f(you)h(should)f(be)i(interested)f(in.)42 b(After)26 b(that,)h(you)e(should)g(look)g(at)h(the)g(entire)g(v)o (ector)e(and)i(apply)e(common)208 4092 y(sense)c(rather)f(than)h (statistics.)0 4238 y FD(timeit)p FJ(\()p FC([)p FK(number)p Fn(=1000000)12 b FC(])p FJ(\))208 4338 y FN(T)m(ime)25 b FK(number)i FN(e)o(x)o(ecutions)d(of)h(the)h(main)f(statement.)42 b(This)26 b(e)o(x)o(ecutes)e(the)i(setup)g(statement)f(once,)h(and)f (then)h(returns)f(the)208 4438 y(time)c(it)i(tak)o(es)e(to)h(e)o(x)o (ecute)e(the)i(main)f(statement)h(a)g(number)d(of)j(times,)g(measured)e (in)i(seconds)f(as)h(a)g(\003oat.)29 b(The)21 b(ar)o(gument)f(is)208 4537 y(the)j(number)g(of)g(times)i(through)c(the)j(loop,)g(def)o (aulting)e(to)i(one)g(million.)35 b(The)24 b(main)f(statement,)i(the)f (setup)f(statement)h(and)208 4637 y(the)c(timer)g(function)e(to)j(be)f (used)g(are)g(passed)g(to)g(the)g(constructor)-5 b(.)208 4770 y FL(Note:)38 b FN(By)28 b(def)o(ault,)h FJ(timeit\(\))d FN(temporarily)g(turns)h(of)n(f)g(garbage)e(collection)i(during)e(the)j (timing.)46 b(The)27 b(adv)n(antage)f(of)208 4869 y(this)e(approach)d (is)k(that)f(it)g(mak)o(es)f(independent)e(timings)j(more)f (comparable.)33 b(This)23 b(disadv)n(antage)f(is)j(that)e(GC)i(may)e (be)h(an)208 4969 y(important)f(component)h(of)h(the)g(performance)e (of)i(the)h(function)d(being)i(measured.)39 b(If)26 b(so,)h(GC)f(can)f (be)h(re-enabled)d(as)k(the)208 5069 y(\002rst)20 b(statement)g(in)h (the)f FK(setup)g FN(string.)25 b(F)o(or)19 b(e)o(xample:)623 5293 y FA(timeit.Timer\('for)42 b(i)j(in)f(xrange\(10\):)f(oct\(i\)',)h ('gc.enable\(\)'\).timeit\(\))p 0 5549 3901 4 v 0 5649 a FI(25.9.)52 b FJ(timeit)22 b FI(\227)h(Measure)g(e)n(x)n(ecution)g (time)h(of)f(small)h(code)f(snippets)1377 b(821)p eop end %%Page: 822 834 TeXDict begin 822 833 bop 0 83 a Fv(25.9.1)101 b(Command)29 b(Line)g(Interf)m(ace)0 286 y FN(When)20 b(called)g(as)h(a)g(program)d (from)h(the)h(command)e(line,)i(the)g(follo)n(wing)f(form)g(is)i(used:) 236 524 y FA(python)44 b(-m)h(timeit)e([-n)i(N])f([-r)h(N])f([-s)g(S])h ([-t])f([-c])g([-h])g([statement)f(...])0 811 y FN(where)20 b(the)g(follo)n(wing)e(options)i(are)g(understood:)0 1008 y FL(-n)h(N/--number=N)41 b FN(ho)n(w)20 b(man)o(y)f(times)h(to)h (e)o(x)o(ecute)d(')-5 b(statement')0 1161 y FL(-r)20 b(N/--r)o(epeat=N)40 b FN(ho)n(w)19 b(man)o(y)g(times)i(to)f(repeat)g (the)g(timer)g(\(def)o(ault)f(3\))0 1315 y FL(-s)i(S/--setup=S)41 b FN(statement)20 b(to)h(be)f(e)o(x)o(ecuted)e(once)i(initially)g (\(def)o(ault)f FJ('pass')p FN(\))0 1468 y FL(-t/--time)40 b FN(use)20 b FJ(time.time\(\))f FN(\(def)o(ault)g(on)h(all)h (platforms)e(b)n(ut)h(W)m(indo)n(ws\))0 1621 y FL(-c/--clock)40 b FN(use)20 b FJ(time.clock\(\))f FN(\(def)o(ault)g(on)h(W)m(indo)n (ws\))0 1774 y FL(-v/--v)o(erbose)39 b FN(print)20 b(ra)o(w)g(timing)f (results;)i(repeat)f(for)f(more)h(digits)g(precision)0 1927 y FL(-h/--help)41 b FN(print)20 b(a)g(short)g(usage)g(message)g (and)f(e)o(xit)0 2125 y(A)30 b(multi-line)e(statement)h(may)g(be)g(gi)n (v)o(en)f(by)h(specifying)e(each)i(line)h(as)f(a)h(separate)f (statement)g(ar)o(gument;)i(indented)d(lines)i(are)0 2224 y(possible)20 b(by)g(enclosing)f(an)h(ar)o(gument)e(in)i(quotes)f (and)h(using)g(leading)f(spaces.)25 b(Multiple)20 b FL(-s)h FN(options)e(are)h(treated)g(similarly)-5 b(.)0 2371 y(If)23 b FL(-n)g FN(is)g(not)g(gi)n(v)o(en,)e(a)i(suitable)g(number)e (of)h(loops)g(is)i(calculated)e(by)g(trying)g(successi)n(v)o(e)g(po)n (wers)g(of)g(10)h(until)f(the)h(total)g(time)f(is)i(at)0 2471 y(least)d(0.2)e(seconds.)0 2618 y(The)25 b(def)o(ault)f(timer)h (function)e(is)j(platform)e(dependent.)37 b(On)26 b(W)m(indo)n(ws,)f FJ(time.clock\(\))e FN(has)j(microsecond)d(granularity)g(b)n(ut)0 2717 y FJ(time.time\(\))p FN(')-5 b(s)21 b(granularity)f(is)j(1/60th)e (of)h(a)h(second;)g(on)h(U)t FH(N)t(I)t(X)r FN(,)f FJ(time.clock\(\))e FN(has)h(1/100th)f(of)h(a)g(second)g(granularity)0 2817 y(and)g FJ(time.time\(\))g FN(is)i(much)d(more)i(precise.)32 b(On)23 b(either)g(platform,)e(the)i(def)o(ault)g(timer)f(functions)g (measure)g(w)o(all)h(clock)g(time,)0 2917 y(not)29 b(the)f(CPU)i(time.) 51 b(This)29 b(means)g(that)g(other)f(processes)g(running)f(on)i(the)f (same)i(computer)d(may)h(interfere)f(with)j(the)e(timing.)0 3016 y(The)h(best)g(thing)g(to)g(do)g(when)f(accurate)g(timing)h(is)h (necessary)e(is)i(to)g(repeat)e(the)h(timing)g(a)g(fe)n(w)h(times)f (and)g(use)g(the)g(best)h(time.)0 3116 y(The)24 b FL(-r)g FN(option)f(is)i(good)d(for)i(this;)i(the)e(def)o(ault)f(of)h(3)g (repetitions)f(is)i(probably)d(enough)g(in)i(most)g(cases.)38 b(On)26 b(U)t FH(N)t(I)t(X)r FN(,)f(you)f(can)f(use)0 3215 y FJ(time.clock\(\))c FN(to)h(measure)f(CPU)i(time.)0 3362 y FL(Note:)41 b FN(There)28 b(is)h(a)g(certain)f(baseline)g(o)o(v) o(erhead)e(associated)i(with)h(e)o(x)o(ecuting)d(a)j(pass)g(statement.) 50 b(The)28 b(code)g(here)g(doesn')o(t)f(try)0 3462 y(to)f(hide)f(it,)i (b)n(ut)f(you)f(should)f(be)i(a)o(w)o(are)f(of)g(it.)42 b(The)25 b(baseline)h(o)o(v)o(erhead)c(can)k(be)f(measured)g(by)g(in)m (v)n(oking)e(the)j(program)d(without)0 3562 y(ar)o(guments.)0 3708 y(The)e(baseline)g(o)o(v)o(erhead)d(dif)n(fers)i(between)h(Python) f(v)o(ersions!)27 b(Also,)21 b(to)g(f)o(airly)g(compare)f(older)g (Python)g(v)o(ersions)g(to)h(Python)f(2.3,)0 3808 y(you)f(may)h(w)o (ant)g(to)h(use)f(Python')-5 b(s)20 b FL(-O)f FN(option)g(for)h(the)g (older)g(v)o(ersions)f(to)h(a)n(v)n(oid)g(timing)g FJ(SET_LINENO)f FN(instructions.)0 4087 y Fv(25.9.2)101 b(Examples)0 4290 y FN(Here)19 b(are)g(tw)o(o)h(e)o(xample)e(sessions)i(\(one)e (using)h(the)g(command)f(line,)h(one)g(using)f(the)i(module)e(interf)o (ace\))g(that)h(compare)f(the)h(cost)h(of)0 4390 y(using)g FJ(hasattr\(\))f FN(vs.)25 b FJ(try)p FN(/)p FJ(except)19 b FN(to)i(test)g(for)e(missing)h(and)g(present)f(object)h(attrib)n (utes.)236 4628 y FA(\045)45 b(timeit.py)e('try:')h(')90 b(str.__nonzero__')42 b('except)h(AttributeError:')f(')90 b(pass')236 4719 y(100000)44 b(loops,)g(best)g(of)h(3:)f(15.7)g(usec)g (per)h(loop)236 4811 y(\045)g(timeit.py)e('if)i(hasattr\(str,)d ("__nonzero__"\):)h(pass')236 4902 y(100000)h(loops,)g(best)g(of)h(3:)f (4.26)g(usec)g(per)h(loop)236 4993 y(\045)g(timeit.py)e('try:')h(')90 b(int.__nonzero__')42 b('except)h(AttributeError:')f(')90 b(pass')236 5085 y(1000000)44 b(loops,)g(best)g(of)g(3:)h(1.43)f(usec)g (per)g(loop)236 5176 y(\045)h(timeit.py)e('if)i(hasattr\(int,)d ("__nonzero__"\):)h(pass')236 5267 y(100000)h(loops,)g(best)g(of)h(3:)f (2.23)g(usec)g(per)h(loop)p 0 5549 3901 4 v 0 5649 a FI(822)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g(Pro\002lers)p eop end %%Page: 823 835 TeXDict begin 823 834 bop 236 174 a FA(>>>)45 b(import)e(timeit)236 266 y(>>>)i(s)f(=)h("""\\)236 357 y(...)g(try:)236 448 y(...)224 b(str.__nonzero__)236 540 y(...)45 b(except)e (AttributeError:)236 631 y(...)224 b(pass)236 722 y(...)45 b(""")236 814 y(>>>)g(t)f(=)h(timeit.Timer\(stmt=s\))236 905 y(>>>)g(print)f("\045.2f)g(usec/pass")f(\045)h(\(1000000)1940 918 y(*)2029 905 y(t.timeit\(number=100000\)/100000\))236 996 y(17.09)g(usec/pass)236 1088 y(>>>)h(s)f(=)h("""\\)236 1179 y(...)g(if)f(hasattr\(str,)f('__nonzero__'\):)f(pass)236 1270 y(...)j(""")236 1362 y(>>>)g(t)f(=)h(timeit.Timer\(stmt=s\))236 1453 y(>>>)g(print)f("\045.2f)g(usec/pass")f(\045)h(\(1000000)1940 1466 y(*)2029 1453 y(t.timeit\(number=100000\)/100000\))236 1544 y(4.85)g(usec/pass)236 1636 y(>>>)h(s)f(=)h("""\\)236 1727 y(...)g(try:)236 1818 y(...)224 b(int.__nonzero__)236 1910 y(...)45 b(except)e(AttributeError:)236 2001 y(...)224 b(pass)236 2092 y(...)45 b(""")236 2183 y(>>>)g(t)f(=)h (timeit.Timer\(stmt=s\))236 2275 y(>>>)g(print)f("\045.2f)g(usec/pass") f(\045)h(\(1000000)1940 2288 y(*)2029 2275 y (t.timeit\(number=100000\)/100000\))236 2366 y(1.97)g(usec/pass)236 2457 y(>>>)h(s)f(=)h("""\\)236 2549 y(...)g(if)f(hasattr\(int,)f ('__nonzero__'\):)f(pass)236 2640 y(...)j(""")236 2731 y(>>>)g(t)f(=)h(timeit.Timer\(stmt=s\))236 2823 y(>>>)g(print)f ("\045.2f)g(usec/pass")f(\045)h(\(1000000)1940 2836 y(*)2029 2823 y(t.timeit\(number=100000\)/100000\))236 2914 y(3.15)g(usec/pass)0 3201 y FN(T)-7 b(o)29 b(gi)n(v)o(e)f(the)h FJ(timeit)g FN(module)e(access)j(to)f(functions)e(you)h(de\002ne,)j(you)d(can)g (pass)i(a)f FJ(setup)g FN(parameter)e(which)h(contains)h(an)0 3300 y(import)19 b(statement:)236 3538 y FA(def)45 b(test\(\):)416 3630 y("Stupid)e(test)h(function")416 3721 y(L)g(=)h([])416 3812 y(for)f(i)h(in)f(range\(100\):)595 3904 y(L.append\(i\))236 4086 y(if)h(__name__=='__main__':)416 4178 y(from)f(timeit)g(import)f (Timer)416 4269 y(t)h(=)h(Timer\("test\(\)",)d("from)i(__main__)g (import)f(test"\))416 4360 y(print)h(t.timeit\(\))0 4870 y FE(25.10)122 b Fx(trace)32 b FE(\227)g(T)-14 b(r)o(ace)34 b(or)f(tr)o(ac)n(k)g(Python)h(statement)h(e)l(x)l(ecution)0 5103 y FN(The)c FJ(trace)f FN(module)g(allo)n(ws)i(you)e(to)h(trace)g (program)e(e)o(x)o(ecution,)i(generate)f(annotated)f(statement)i(co)o (v)o(erage)e(listings,)34 b(print)0 5203 y(caller/callee)19 b(relationships)f(and)h(list)h(functions)e(e)o(x)o(ecuted)g(during)f(a) j(program)d(run.)24 b(It)c(can)f(be)g(used)g(in)h(another)d(program)h (or)h(from)0 5302 y(the)h(command)e(line.)p 0 5549 3901 4 v 0 5649 a FI(25.10.)52 b FJ(trace)23 b FI(\227)g(T)-10 b(r)o(ace)22 b(or)h(tr)o(ac)n(k)g(Python)g(statement)h(e)n(x)n(ecution) 1559 b(823)p eop end %%Page: 824 836 TeXDict begin 824 835 bop 0 83 a Fv(25.10.1)101 b(Command)29 b(Line)g(Usage)0 286 y FN(The)20 b FJ(trace)g FN(module)e(can)i(be)h (in)m(v)n(ok)o(ed)d(from)h(the)h(command)f(line.)25 b(It)20 b(can)g(be)g(as)h(simple)f(as)236 524 y FA(python)44 b(-m)h(trace)f(--count)f(somefile.py)g(...)0 811 y FN(The)20 b(abo)o(v)o(e)e(will)j(generate)e(annotated)g(listings)h(of)g(all)h (Python)e(modules)g(imported)g(during)f(the)j(e)o(x)o(ecution)d(of)i(`) p FO(some\002le)o(.p)n(y)p FN('.)0 958 y(The)g(follo)n(wing)e (command-line)g(ar)o(guments)g(are)i(supported:)0 1187 y FL(--trace,)f(-t)40 b FN(Display)20 b(lines)h(as)g(the)o(y)e(are)h(e) o(x)o(ecuted.)0 1353 y FL(--count,)f(-c)41 b FN(Produce)22 b(a)h(set)g(of)g(annotated)e(listing)i(\002les)g(upon)f(program)e (completion)h(that)i(sho)n(ws)g(ho)n(w)f(man)o(y)g(times)h(each)f (state-)208 1453 y(ment)d(w)o(as)i(e)o(x)o(ecuted.)0 1619 y FL(--r)o(eport,)d(-r)41 b FN(Produce)19 b(an)h(annotated)f(list) i(from)e(an)h(earlier)g(program)e(run)i(that)g(used)g(the)g FL(--count)f FN(and)h FL(--\002le)g FN(ar)o(guments.)0 1785 y FL(--no-r)o(eport,)e(-R)41 b FN(Do)26 b(not)h(generate)e (annotated)g(listings.)45 b(This)27 b(is)h(useful)e(if)h(you)e(intend)h (to)h(mak)o(e)f(se)n(v)o(eral)g(runs)h(with)f FL(--count)208 1885 y FN(then)19 b(produce)f(a)j(single)f(set)h(of)f(annotated)f (listings)h(at)h(the)f(end.)0 2051 y FL(--listfuncs,)g(-l)41 b FN(List)21 b(the)f(functions)f(e)o(x)o(ecuted)f(by)i(running)e(the)j (program.)0 2217 y FL(--trackcalls,)e(-T)41 b FN(Generate)20 b(calling)f(relationships)g(e)o(xposed)g(by)h(running)e(the)i(program.) 0 2383 y FL(--\002le,)g(-f)41 b FN(Name)20 b(a)g(\002le)h(containing)d (\(or)i(to)g(contain\))f(counts.)0 2549 y FL(--co)o(v)o(erdir,)g(-C)41 b FN(Name)20 b(a)h(directory)d(in)i(which)g(to)g(sa)n(v)o(e)h (annotated)d(listing)j(\002les.)0 2715 y FL(--missing,)f(-m)42 b FN(When)20 b(generating)e(annotated)g(listings,)j(mark)e(lines)i (which)e(were)i(not)e(e)o(x)o(ecuted)g(with)h(`)p FJ(>>>>>>)p FN('.)0 2881 y FL(--summary,)f(-s)42 b FN(When)20 b(using)g FL(--count)f FN(or)h FL(--r)o(eport)p FN(,)e(write)i(a)h(brief)f (summary)e(to)j(stdout)e(for)h(each)g(\002le)h(processed.)0 3047 y FL(--ignor)o(e-module)39 b FN(Ignore)18 b(the)j(named)e(module)f (and)i(its)h(submodules)e(\(if)h(it)h(is)g(a)f(package\).)k(May)c(be)g (gi)n(v)o(en)f(multiple)g(times.)0 3213 y FL(--ignor)o(e-dir)39 b FN(Ignore)29 b(all)i(modules)e(and)h(packages)f(in)h(the)h(named)e (directory)f(and)i(subdirectories.)54 b(May)30 b(be)g(gi)n(v)o(en)f (multiple)208 3313 y(times.)0 3598 y Fv(25.10.2)101 b(Prog)o(r)o (amming)31 b(Interf)m(ace)0 3797 y FL(class)21 b FD(Trace)p FJ(\()p FC([)p FK(count=1)p FC([)p FK(,)71 b(tr)o(ace=1)p FC([)p FK(,)j(countfuncs=0)p FC([)p FK(,)e(countcaller)o(s=0)p FC([)p FK(,)h(ignor)m(emods=\(\))p FC([)p FK(,)g(ignor)m(edir)o(s=\(\)) p FC([)p FK(,)g(in-)487 3897 y(\002le=None)p FC([)p FK(,)18 b(out\002le=None)12 b FC(])g(])g(])g(])g(])g(])g(])g(])p FJ(\))208 3980 y FN(Create)23 b(an)g(object)g(to)g(trace)g(e)o(x)o (ecution)e(of)i(a)h(single)f(statement)g(or)g(e)o(xpression.)32 b(All)24 b(parameters)e(are)h(optional.)32 b FK(count)24 b FN(en-)208 4080 y(ables)c(counting)e(of)i(line)g(numbers.)k FK(tr)o(ace)c FN(enables)f(line)i(e)o(x)o(ecution)d(tracing.)24 b FK(countfuncs)18 b FN(enables)i(listing)g(of)g(the)g(functions)208 4180 y(called)i(during)f(the)i(run.)32 b FK(countcaller)o(s)22 b FN(enables)h(call)g(relationship)e(tracking.)32 b FK(ignor)m(emods)21 b FN(is)j(a)f(list)h(of)e(modules)g(or)h(pack-)208 4279 y(ages)e(to)g(ignore.)26 b FK(ignor)m(edir)o(s)20 b FN(is)i(a)f(list)i (of)d(directories)g(whose)h(modules)f(or)g(packages)g(should)g(be)h (ignored.)k FK(in\002le)c FN(is)h(the)f(\002le)208 4379 y(from)e(which)g(to)i(read)e(stored)h(count)f(information.)k FK(out\002le)c FN(is)i(a)g(\002le)g(in)f(which)g(to)g(write)g(updated)f (count)g(information.)0 4526 y FD(run)p FJ(\()p FK(cmd)r FJ(\))208 4625 y FN(Run)h FK(cmd)i FN(under)d(control)g(of)h(the)g(T)m (race)g(object)f(with)i(the)f(current)f(tracing)g(parameters.)0 4772 y FD(runctx)p FJ(\()p FK(cmd)r FC([)p FK(,)g(globals=None)p FC([)p FK(,)f(locals=None)12 b FC(])g(])p FJ(\))208 4872 y FN(Run)24 b FK(cmd)j FN(under)c(control)g(of)h(the)h(T)m(race)f (object)g(with)h(the)f(current)f(tracing)h(parameters)f(in)i(the)g (de\002ned)e(global)h(and)g(local)208 4972 y(en)m(vironments.)e(If)e (not)g(de\002ned,)f FK(globals)g FN(and)g FK(locals)i FN(def)o(ault)e(to)h(empty)g(dictionaries.)0 5118 y FD(runfunc)p FJ(\()p FK(func,)e(*ar)m(gs,)i(**kwds)p FJ(\))208 5218 y FN(Call)h FK(func)e FN(with)i(the)f(gi)n(v)o(en)f(ar)o(guments)f (under)h(control)g(of)h(the)g FJ(Trace)g FN(object)f(with)i(the)f (current)f(tracing)g(parameters.)p 0 5549 3901 4 v 0 5649 a FI(824)2501 b(Chapter)24 b(25.)52 b(The)23 b(Python)g (Pro\002lers)p eop end %%Page: 825 837 TeXDict begin 825 836 bop 0 83 a FN(This)20 b(is)h(a)g(simple)f(e)o (xample)f(sho)n(wing)g(the)h(use)h(of)f(this)g(module:)236 321 y FA(import)44 b(sys)236 413 y(import)g(trace)236 595 y(#)h(create)f(a)g(Trace)g(object,)g(telling)g(it)g(what)g(to)h (ignore,)e(and)i(whether)e(to)236 687 y(#)i(do)f(tracing)g(or)h (line-counting)d(or)j(both.)236 778 y(tracer)f(=)h(trace.Trace\()416 869 y(ignoredirs=[sys.prefix,)c(sys.exec_prefix],)416 960 y(trace=0,)416 1052 y(count=1\))236 1234 y(#)k(run)f(the)h(new)f (command)g(using)g(the)g(given)g(tracer)236 1326 y (tracer.run\('main\(\)'\))236 1508 y(#)h(make)f(a)h(report,)e(placing)h (output)g(in)g(/tmp)236 1600 y(r)h(=)g(tracer.results\(\))236 1691 y(r.write_results\(show_missing=True,)39 b(coverdir="/tmp"\))p 0 5549 3901 4 v 0 5649 a FI(25.10.)52 b FJ(trace)23 b FI(\227)g(T)-10 b(r)o(ace)22 b(or)h(tr)o(ac)n(k)g(Python)g(statement)h (e)n(x)n(ecution)1559 b(825)p eop end %%Page: 826 838 TeXDict begin 826 837 bop 0 5549 3901 4 v 0 5649 a FI(826)p eop end %%Page: 827 839 TeXDict begin 827 838 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3203 427 y FG(TWENTYSIX)p 0 515 V 1518 978 a FT(Python)57 b(Runtime)g(Ser)6 b(vices)0 1466 y FN(The)21 b(modules)g(described)f (in)i(this)g(chapter)f(pro)o(vide)e(a)j(wide)g(range)e(of)i(services)f (related)g(to)h(the)g(Python)e(interpreter)g(and)h(its)i(inter)n(-)0 1566 y(action)d(with)g(its)h(en)m(vironment.)h(Here')-5 b(s)21 b(an)f(o)o(v)o(ervie)n(w:)50 1692 y FD(sys)497 b FN(Access)21 b(system-speci\002c)f(parameters)f(and)h(functions.)50 1792 y FD(__builtin__)97 b FN(The)20 b(module)f(that)h(pro)o(vides)f (the)h(b)n(uilt-in)g(namespace.)50 1891 y FD(__main__)247 b FN(The)20 b(en)m(vironment)d(where)j(the)g(top-le)n(v)o(el)f(script)h (is)h(run.)50 1991 y FD(warnings)247 b FN(Issue)21 b(w)o(arning)e (messages)h(and)g(control)f(their)h(disposition.)50 2091 y FD(contextlib)147 b FN(Utilities)22 b(for)d FJ(with)p FN(-statement)g(conte)o(xts.)50 2190 y FD(atexit)347 b FN(Re)o(gister)21 b(and)e(e)o(x)o(ecute)g(cleanup)g(functions.)50 2290 y FD(traceback)197 b FN(Print)21 b(or)f(retrie)n(v)o(e)f(a)h (stack)g(traceback.)50 2390 y FD(__future__)147 b FN(Future)20 b(statement)g(de\002nitions)50 2489 y FD(gc)547 b FN(Interf)o(ace)19 b(to)i(the)f(c)o(ycle-detecting)e(garbage)g(collector)-5 b(.)50 2589 y FD(inspect)297 b FN(Extract)20 b(information)e(and)h (source)h(code)f(from)g(li)n(v)o(e)h(objects.)50 2688 y FD(site)447 b FN(A)21 b(standard)e(w)o(ay)h(to)h(reference)d (site-speci\002c)j(modules.)50 2788 y FD(user)447 b FN(A)21 b(standard)e(w)o(ay)h(to)h(reference)d(user)n(-speci\002c)i(modules.)50 2888 y FD(fpectl)347 b FN(Pro)o(vide)19 b(control)g(for)h(\003oating)f (point)h(e)o(xception)e(handling.)0 3185 y FE(26.1)121 b Fx(sys)33 b FE(\227)f(System-speci\002c)h(par)o(ameters)h(and)h (functions)0 3418 y FN(This)28 b(module)e(pro)o(vides)g(access)j(to)f (some)f(v)n(ariables)g(used)h(or)f(maintained)f(by)i(the)g(interpreter) e(and)h(to)h(functions)e(that)i(interact)0 3517 y(strongly)19 b(with)h(the)g(interpreter)-5 b(.)24 b(It)d(is)g(al)o(w)o(ays)f(a)n(v)n (ailable.)0 3664 y FD(argv)208 3764 y FN(The)27 b(list)h(of)f(command)e (line)j(ar)o(guments)d(passed)i(to)g(a)h(Python)e(script.)46 b FJ(argv[0])27 b FN(is)h(the)g(script)f(name)g(\(it)g(is)h(operating) 208 3863 y(system)21 b(dependent)e(whether)h(this)i(is)h(a)e(full)g (pathname)f(or)h(not\).)28 b(If)21 b(the)g(command)f(w)o(as)i(e)o(x)o (ecuted)d(using)i(the)g FL(-c)h FN(command)208 3963 y(line)h(option)g (to)h(the)g(interpreter)m(,)f FJ(argv[0])g FN(is)h(set)h(to)f(the)g (string)f FJ('-c')p FN(.)36 b(If)24 b(no)f(script)h(name)f(w)o(as)i (passed)f(to)g(the)g(Python)208 4063 y(interpreter)m(,)18 b FJ(argv[0])h FN(is)i(the)f(empty)g(string.)0 4210 y FD(byteorder)208 4309 y FN(An)e(indicator)f(of)i(the)f(nati)n(v)o(e)g (byte)g(order)-5 b(.)24 b(This)19 b(will)g(ha)n(v)o(e)f(the)h(v)n(alue) f FJ('big')g FN(on)g(big-endian)e(\(most-signi\002cant)h(byte)h (\002rst\))208 4409 y(platforms,)g(and)i FJ('little')f FN(on)h(little-endian)f(\(least-signi\002cant)g(byte)h(\002rst\))g (platforms.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 4556 y FD(subversion)208 4655 y FN(A)25 b(triple)f(\(repo,)h(branch,)f (v)o(ersion\))f(representing)f(the)j(Sub)o(v)o(ersion)d(information)h (of)h(the)h(Python)e(interpreter)-5 b(.)38 b FK(r)m(epo)24 b FN(is)i(the)208 4755 y(name)20 b(of)h(the)h(repository)-5 b(,)19 b FJ('CPython')p FN(.)27 b FK(br)o(anc)o(h)20 b FN(is)i(a)g(string)f(of)g(one)g(of)g(the)h(forms)e FJ('trunk')p FN(,)h FJ('branches/name')208 4855 y FN(or)31 b FJ('tags/name')p FN(.)56 b FK(ver)o(sion)32 b FN(is)g(the)f(output)f (of)h FJ(svnversion)p FN(,)i(if)e(the)h(interpreter)d(w)o(as)j(b)n (uilt)g(from)e(a)i(Sub)o(v)o(ersion)208 4954 y(check)o(out;)22 b(it)h(contains)f(the)h(re)n(vision)f(number)e(\(range\))h(and)h (possibly)g(a)i(trailing)e('M')g(if)h(there)f(were)h(local)f (modi\002cations.)208 5054 y(If)g(the)i(tree)f(w)o(as)g(e)o(xported)e (\(or)i(svn)m(v)o(ersion)e(w)o(as)i(not)g(a)n(v)n(ailable\),)g(it)h(is) g(the)f(re)n(vision)f(of)g FJ(Include/patchlevel.h)e FN(if)208 5154 y(the)g(branch)e(is)k(a)e(tag.)25 b(Otherwise,)20 b(it)h(is)g FJ(None)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 5300 y FD(builtin_module_names)208 5400 y FN(A)h(tuple)f(of)h(strings)g (gi)n(ving)e(the)i(names)f(of)h(all)g(modules)f(that)h(are)f(compiled)g (into)g(this)i(Python)d(interpreter)-5 b(.)24 b(\(This)c(informa-)p 0 5549 3901 4 v 3762 5649 a FI(827)p eop end %%Page: 828 840 TeXDict begin 828 839 bop 208 83 a FN(tion)19 b(is)j(not)d(a)n(v)n (ailable)h(in)h(an)o(y)e(other)g(w)o(ay)i(\227)f FJ(modules.keys\(\))e FN(only)i(lists)h(the)g(imported)d(modules.\))0 230 y FD(copyright)208 330 y FN(A)i(string)g(containing)e(the)j(cop)o(yright) d(pertaining)g(to)j(the)f(Python)f(interpreter)-5 b(.)0 476 y FD(_current_frames)p FJ(\(\))208 576 y FN(Return)23 b(a)i(dictionary)e(mapping)f(each)i(thread')-5 b(s)24 b(identi\002er)g(to)g(the)h(topmost)e(stack)i(frame)e(currently)g(acti) n(v)o(e)h(in)g(that)h(thread)208 676 y(at)c(the)g(time)g(the)g (function)e(is)j(called.)27 b(Note)21 b(that)g(functions)f(in)h(the)g FJ(traceback)f FN(module)f(can)i(b)n(uild)f(the)h(call)h(stack)f(gi)n (v)o(en)208 775 y(such)e(a)i(frame.)208 904 y(This)e(is)i(most)f (useful)f(for)g(deb)n(ugging)e(deadlock:)23 b(this)d(function)e(does)h (not)g(require)g(the)g(deadlock)o(ed)f(threads')g(cooperation,)208 1004 y(and)23 b(such)h(threads')f(call)h(stacks)g(are)g(frozen)f(for)g (as)i(long)e(as)i(the)o(y)e(remain)g(deadlock)o(ed.)34 b(The)24 b(frame)f(returned)f(for)h(a)i(non-)208 1103 y(deadlock)o(ed)c(thread)h(may)i(bear)f(no)g(relationship)f(to)h(that)h (thread')-5 b(s)23 b(current)f(acti)n(vity)h(by)g(the)h(time)g(calling) f(code)g(e)o(xamines)208 1203 y(the)d(frame.)208 1332 y(This)g(function)e(should)i(be)g(used)g(for)f(internal)h(and)f (specialized)h(purposes)f(only)-5 b(.)49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1479 y FD(dllhandle)208 1578 y FN(Inte)o(ger)f(specifying)h(the)h(handle)f(of)h(the)g(Python)f(DLL.) h(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws.)0 1725 y FD(displayhook)p FJ(\()p FK(value)p FJ(\))208 1825 y FN(If)c FK(value)f FN(is)i(not)f FJ(None)p FN(,)g(this)h(function)d (prints)i(it)h(to)f FJ(sys.stdout)p FN(,)f(and)h(sa)n(v)o(es)g(it)h(in) f FJ(__builtin__._)p FN(.)208 1954 y FJ(sys.displayhook)33 b FN(is)k(called)f(on)f(the)h(result)g(of)f(e)n(v)n(aluating)g(an)g(e)o (xpression)g(entered)f(in)i(an)g(interacti)n(v)o(e)f(Python)208 2053 y(session.)81 b(The)39 b(display)f(of)g(these)i(v)n(alues)e(can)h (be)g(customized)e(by)i(assigning)f(another)f(one-ar)o(gument)e (function)i(to)208 2153 y FJ(sys.displayhook)p FN(.)0 2300 y FD(excepthook)p FJ(\()p FK(type,)18 b(value,)h(tr)o(acebac)n(k)q FJ(\))208 2399 y FN(This)h(function)e(prints)i(out)g(a)h(gi)n(v)o(en)e (traceback)f(and)i(e)o(xception)e(to)j FJ(sys.stderr)p FN(.)208 2528 y(When)31 b(an)g(e)o(xception)f(is)j(raised)e(and)g (uncaught,)h(the)f(interpreter)f(calls)j FJ(sys.excepthook)c FN(with)j(three)f(ar)o(guments,)208 2628 y(the)h(e)o(xception)e(class,) 36 b(e)o(xception)31 b(instance,)j(and)e(a)h(traceback)e(object.)60 b(In)32 b(an)h(interacti)n(v)o(e)e(session)h(this)h(happens)e(just)208 2727 y(before)h(control)g(is)i(returned)d(to)j(the)f(prompt;)39 b(in)33 b(a)h(Python)e(program)f(this)j(happens)e(just)i(before)e(the)h (program)f(e)o(xits.)208 2827 y(The)e(handling)f(of)h(such)g(top-le)n (v)o(el)g(e)o(xceptions)f(can)h(be)h(customized)e(by)h(assigning)g (another)f(three-ar)o(gument)e(function)208 2927 y(to)20 b FJ(sys.excepthook)p FN(.)0 3073 y FD(__displayhook__)0 3173 y(__excepthook__)208 3273 y FN(These)28 b(objects)g(contain)f(the) h(original)f(v)n(alues)h(of)g FJ(displayhook)f FN(and)h FJ(excepthook)f FN(at)i(the)f(start)h(of)f(the)g(program.)208 3372 y(The)o(y)20 b(are)h(sa)n(v)o(ed)g(so)h(that)g FJ(displayhook)e FN(and)h FJ(excepthook)f FN(can)h(be)g(restored)g(in)g(case)h(the)o(y)f (happen)f(to)h(get)h(replaced)208 3472 y(with)e(brok)o(en)e(objects.)0 3619 y FD(exc_info)p FJ(\(\))208 3718 y FN(This)26 b(function)f (returns)h(a)h(tuple)f(of)g(three)h(v)n(alues)f(that)g(gi)n(v)o(e)g (information)e(about)i(the)h(e)o(xception)d(that)j(is)h(currently)d (being)208 3818 y(handled.)36 b(The)25 b(information)d(returned)h(is)j (speci\002c)f(both)f(to)g(the)h(current)f(thread)f(and)h(to)h(the)g (current)e(stack)i(frame.)38 b(If)25 b(the)208 3918 y(current)f(stack)h (frame)g(is)h(not)g(handling)d(an)j(e)o(xception,)e(the)i(information)d (is)j(tak)o(en)f(from)g(the)g(calling)g(stack)h(frame,)f(or)h(its)208 4017 y(caller)m(,)g(and)f(so)h(on)g(until)f(a)h(stack)g(frame)f(is)i (found)d(that)i(is)g(handling)e(an)i(e)o(xception.)40 b(Here,)26 b(\223handling)e(an)i(e)o(xception\224)e(is)208 4117 y(de\002ned)g(as)j(\223e)o(x)o(ecuting)c(or)j(ha)n(ving)f(e)o(x)o (ecuted)e(an)j(e)o(xcept)f(clause.)-6 b(\224)42 b(F)o(or)25 b(an)o(y)g(stack)h(frame,)g(only)f(information)f(about)h(the)208 4217 y(most)20 b(recently)f(handled)g(e)o(xception)f(is)j(accessible.) 208 4345 y(If)31 b(no)g(e)o(xception)f(is)j(being)e(handled)f(an)o (ywhere)f(on)j(the)f(stack,)k(a)d(tuple)f(containing)f(three)h FJ(None)h FN(v)n(alues)f(is)i(returned.)208 4445 y(Otherwise,)20 b(the)i(v)n(alues)e(returned)g(are)h FJ(\()p FK(type)p FJ(,)49 b FK(value)p FJ(,)f FK(tr)o(acebac)n(k)q FJ(\))p FN(.)27 b(Their)20 b(meaning)g(is:)28 b FK(type)21 b FN(gets)h(the)f(e)o(xception)e(type)208 4545 y(of)j(the)h(e)o(xception) e(being)h(handled)f(\(a)i(class)g(object\);)g FK(value)g FN(gets)g(the)g(e)o(xception)d(parameter)i(\(its)h FK(associated)f (value)g FN(or)h(the)208 4644 y(second)e(ar)o(gument)f(to)i FJ(raise)p FN(,)g(which)f(is)i(al)o(w)o(ays)g(a)f(class)i(instance)d (if)i(the)f(e)o(xception)e(type)i(is)h(a)f(class)h(object\);)g FK(tr)o(acebac)n(k)208 4744 y FN(gets)29 b(a)g(traceback)e(object)h (\(see)h(the)g(Reference)e(Manual\))h(which)g(encapsulates)g(the)h (call)g(stack)g(at)g(the)g(point)e(where)i(the)208 4844 y(e)o(xception)18 b(originally)g(occurred.)208 4972 y(If)j FJ(exc_clear\(\))f FN(is)i(called,)f(this)h(function)d(will)j(return)e (three)h FJ(None)g FN(v)n(alues)g(until)g(either)g(another)f(e)o (xception)g(is)i(raised)208 5072 y(in)e(the)g(current)f(thread)g(or)h (the)g(e)o(x)o(ecution)e(stack)j(returns)e(to)h(a)h(frame)e(where)h (another)f(e)o(xception)f(is)j(being)e(handled.)208 5201 y FL(W)-5 b(ar)o(ning:)32 b FN(Assigning)24 b(the)h FK(tr)o(acebac)n(k) g FN(return)e(v)n(alue)h(to)h(a)g(local)f(v)n(ariable)g(in)g(a)h (function)e(that)i(is)g(handling)e(an)h(e)o(xception)208 5300 y(will)h(cause)f(a)h(circular)e(reference.)36 b(This)24 b(will)i(pre)n(v)o(ent)c(an)o(ything)g(referenced)h(by)h(a)g(local)h(v) n(ariable)e(in)h(the)h(same)f(function)208 5400 y(or)d(by)g(the)h (traceback)f(from)f(being)h(garbage)f(collected.)29 b(Since)22 b(most)f(functions)g(don')o(t)f(need)h(access)h(to)g(the)g(traceback,)f (the)p 0 5549 3901 4 v 0 5649 a FI(828)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 829 841 TeXDict begin 829 840 bop 208 83 a FN(best)27 b(solution)g(is)i(to)e (use)h(something)e(lik)o(e)i FJ(exctype,)48 b(value)h(=)h (sys.exc_info\(\)[:2])24 b FN(to)k(e)o(xtract)f(only)g(the)208 183 y(e)o(xception)21 b(type)h(and)g(v)n(alue.)33 b(If)22 b(you)g(do)h(need)f(the)h(traceback,)f(mak)o(e)h(sure)f(to)h(delete)g (it)h(after)e(use)h(\(best)g(done)f(with)h(a)h FJ(try)208 282 y FN(...)33 b FJ(finally)22 b FN(statement\))h(or)f(to)h(call)h FJ(exc_info\(\))d FN(in)j(a)f(function)e(that)i(does)g(not)g(itself)g (handle)f(an)h(e)o(xception.)31 b FL(Note:)208 382 y FN(Be)o(ginning)26 b(with)h(Python)g(2.2,)i(such)e(c)o(ycles)h(are)f (automatically)g(reclaimed)f(when)i(garbage)d(collection)i(is)i (enabled)d(and)208 482 y(the)o(y)19 b(become)g(unreachable,)f(b)n(ut)i (it)h(remains)e(more)h(ef)n(\002cient)f(to)i(a)n(v)n(oid)f(creating)f (c)o(ycles.)0 628 y FD(exc_clear)p FJ(\(\))208 728 y FN(This)j(function)f(clears)i(all)g(information)e(relating)g(to)i(the)g (current)e(or)h(last)i(e)o(xception)d(that)h(occurred)f(in)i(the)f (current)g(thread.)208 828 y(After)d(calling)h(this)h(function,)d FJ(exc_info\(\))h FN(will)h(return)f(three)h FJ(None)g FN(v)n(alues)g(until)g(another)e(e)o(xception)g(is)j(raised)f(in)h(the) 208 927 y(current)d(thread)i(or)g(the)g(e)o(x)o(ecution)e(stack)i (returns)f(to)i(a)f(frame)g(where)f(another)g(e)o(xception)f(is)k (being)d(handled.)208 1056 y(This)f(function)f(is)i(only)f(needed)f(in) i(only)f(a)h(fe)n(w)f(obscure)f(situations.)25 b(These)18 b(include)f(logging)g(and)h(error)f(handling)g(systems)208 1155 y(that)23 b(report)f(information)f(on)i(the)g(last)h(or)f(current) f(e)o(xception.)32 b(This)24 b(function)d(can)i(also)h(be)f(used)g(to)g (try)g(to)h(free)f(resources)208 1255 y(and)h(trigger)g(object)h (\002nalization,)h(though)d(no)i(guarantee)e(is)k(made)d(as)i(to)g (what)f(objects)g(will)h(be)f(freed,)g(if)h(an)o(y)-5 b(.)80 b(Ne)n(w)25 b(in)208 1354 y(v)o(ersion)18 b(2.3.)0 1501 y FD(exc_type)0 1601 y(exc_value)0 1701 y(exc_traceback)208 1800 y FL(Depr)o(ecated)h(since)i(r)o(elease)e(1.5.)24 b FN(Use)d FJ(exc_info\(\))e FN(instead.)208 1928 y(Since)26 b(the)o(y)g(are)g(global)g(v)n(ariables,)h(the)o(y)e(are)i(not)f (speci\002c)h(to)f(the)h(current)e(thread,)i(so)f(their)h(use)f(is)i (not)e(safe)h(in)f(a)h(multi-)208 2028 y(threaded)h(program.)53 b(When)30 b(no)g(e)o(xception)e(is)k(being)d(handled,)i FJ(exc_type)e FN(is)i(set)g(to)g FJ(None)f FN(and)f(the)i(other)e(tw)o (o)i(are)208 2128 y(unde\002ned.)0 2275 y FD(exec_prefix)208 2374 y FN(A)e(string)g(gi)n(ving)f(the)h(site-speci\002c)g(directory)f (pre\002x)g(where)h(the)g(platform-dependent)24 b(Python)k(\002les)i (are)f(installed;)34 b(by)208 2474 y(def)o(ault,)c(this)g(is)h(also)e FJ('/usr/local')p FN(.)52 b(This)29 b(can)g(be)h(set)g(at)g(b)n(uild)f (time)h(with)f(the)h FL(--exec-pr)o(e\002x)d FN(ar)o(gument)g(to)j(the) 208 2573 y FL(con\002gur)o(e)25 b FN(script.)45 b(Speci\002cally)-5 b(,)27 b(all)g(con\002guration)d(\002les)k(\(e.g.)44 b(the)27 b(`)p FO(p)n(ycon\002g.h)p FN(')d(header)i(\002le\))h(are)g (installed)f(in)h(the)g(di-)208 2673 y(rectory)d FJ(exec_prefix)48 b(+)h('/lib/python)p FK(ver)o(sion)p FJ(/config')p FN(,)24 b(and)h(shared)g(library)g(modules)g(are)h(installed)f(in)208 2773 y FJ(exec_prefix)47 b(+)j('/lib/python)p FK(ver)o(sion)p FJ(/lib-dynload')p FN(,)15 b(where)20 b FK(ver)o(sion)g FN(is)h(equal)f(to)g FJ(version[:3])p FN(.)0 2920 y FD(executable)208 3019 y FN(A)e(string)g(gi)n(ving)f(the)i(name)e(of)h(the)g(e)o(x)o (ecutable)f(binary)g(for)g(the)i(Python)e(interpreter)m(,)f(on)i (systems)h(where)f(this)g(mak)o(es)g(sense.)0 3166 y FD(exit)p FJ(\()p FC([)p FK(ar)m(g)12 b FC(])p FJ(\))208 3266 y FN(Exit)19 b(from)f(Python.)24 b(This)19 b(is)h(implemented)e (by)h(raising)f(the)i FJ(SystemExit)e FN(e)o(xception,)f(so)j(cleanup)e (actions)h(speci\002ed)g(by)208 3365 y(\002nally)k(clauses)i(of)e FJ(try)h FN(statements)g(are)g(honored,)e(and)i(it)h(is)f(possible)g (to)g(intercept)f(the)h(e)o(xit)g(attempt)g(at)g(an)g(outer)f(le)n(v)o (el.)208 3465 y(The)18 b(optional)g(ar)o(gument)e FK(ar)m(g)j FN(can)f(be)h(an)g(inte)o(ger)e(gi)n(ving)h(the)h(e)o(xit)f(status)i (\(def)o(aulting)d(to)i(zero\),)f(or)g(another)f(type)i(of)f(object.) 208 3565 y(If)24 b(it)i(is)f(an)g(inte)o(ger)m(,)f(zero)g(is)i (considered)d(\223successful)h(termination\224)f(and)h(an)o(y)g (nonzero)f(v)n(alue)h(is)i(considered)d(\223abnormal)208 3664 y(termination\224)h(by)h(shells)i(and)f(the)g(lik)o(e.)43 b(Most)26 b(systems)g(require)f(it)i(to)f(be)g(in)g(the)g(range)f (0-127,)h(and)g(produce)e(unde\002ned)208 3764 y(results)g(otherwise.) 37 b(Some)24 b(systems)g(ha)n(v)o(e)g(a)h(con)m(v)o(ention)c(for)j (assigning)f(speci\002c)i(meanings)e(to)h(speci\002c)h(e)o(xit)f (codes,)h(b)n(ut)208 3863 y(these)e(are)f(generally)g(underde)n(v)o (eloped;)f(U)t FH(N)t(I)t(X)26 b FN(programs)21 b(generally)g(use)i(2)g (for)f(command)f(line)i(syntax)f(errors)g(and)g(1)h(for)208 3963 y(all)h(other)g(kind)f(of)h(errors.)35 b(If)24 b(another)f(type)h (of)g(object)f(is)i(passed,)g FJ(None)f FN(is)h(equi)n(v)n(alent)d(to)j (passing)e(zero,)i(and)e(an)o(y)g(other)208 4063 y(object)e(is)i (printed)d(to)i FJ(sys.stderr)f FN(and)g(results)h(in)g(an)g(e)o(xit)f (code)g(of)h(1.)30 b(In)21 b(particular)m(,)g FJ(sys.exit\("some)47 b(error)208 4162 y(message"\))19 b FN(is)i(a)f(quick)g(w)o(ay)g(to)g(e) o(xit)g(a)h(program)d(when)h(an)i(error)e(occurs.)0 4309 y FD(exitfunc)208 4409 y FN(This)g(v)n(alue)g(is)h(not)g(actually)e (de\002ned)h(by)g(the)h(module,)e(b)n(ut)h(can)g(be)h(set)g(by)f(the)h (user)f(\(or)g(by)g(a)h(program\))d(to)i(specify)g(a)h(clean-)208 4509 y(up)j(action)g(at)h(program)e(e)o(xit.)36 b(When)23 b(set,)i(it)g(should)e(be)g(a)i(parameterless)d(function.)34 b(This)24 b(function)e(will)j(be)f(called)f(when)208 4608 y(the)f(interpreter)e(e)o(xits.)30 b(Only)22 b(one)f(function)g (may)g(be)h(installed)g(in)g(this)h(w)o(ay;)g(to)f(allo)n(w)g(multiple) f(functions)f(which)i(will)h(be)208 4708 y(called)18 b(at)h(termination,)f(use)h(the)g FJ(atexit)f FN(module.)23 b FL(Note:)h FN(The)18 b(e)o(xit)h(function)e(is)i(not)g(called)g(when) f(the)h(program)d(is)k(killed)208 4807 y(by)h(a)h(signal,)g(when)f(a)h (Python)e(f)o(atal)i(internal)f(error)f(is)j(detected,)e(or)g(when)g FJ(os._exit\(\))g FN(is)h(called.)29 b FL(Depr)o(ecated)21 b(since)208 4907 y(r)o(elease)e(2.4.)24 b FN(Use)d FJ(atexit)f FN(instead.)0 5054 y FD(getcheckinterval)p FJ(\(\))208 5154 y FN(Return)f(the)i(interpreter')-5 b(s)18 b(\223check)i(interv)n (al\224;)f(see)i FJ(setcheckinterval\(\))p FN(.)48 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.3.)0 5300 y FD(getdefaultencoding)p FJ(\(\))208 5400 y FN(Return)k(the)g(name)g(of)h(the)f(current)f(def)o (ault)h(string)h(encoding)d(used)i(by)h(the)f(Unicode)g (implementation.)68 b(Ne)n(w)24 b(in)g(v)o(ersion)p 0 5549 3901 4 v 0 5649 a FI(26.1.)52 b FJ(sys)23 b FI(\227)g (System-speci\002c)e(par)o(ameters)i(and)h(functions)1707 b(829)p eop end %%Page: 830 842 TeXDict begin 830 841 bop 208 83 a FN(2.0.)0 230 y FD(getdlopenflags)p FJ(\(\))208 330 y FN(Return)18 b(the)i(current)e(v)n(alue)h(of)g(the)g (\003ags)h(that)f(are)h(used)f(for)f FJ(dlopen\(\))h FN(calls.)25 b(The)19 b(\003ag)h(constants)f(are)g(de\002ned)f(in)i (the)f FJ(dl)208 429 y FN(and)g FJ(DLFCN)h FN(modules.)k(A)-6 b(v)n(ailability:)26 b(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.2.)0 576 y FD(getfilesystemencoding)p FJ(\(\))208 676 y FN(Return)28 b(the)h(name)f(of)g(the)h(encoding)e (used)h(to)h(con)m(v)o(ert)e(Unicode)h(\002lenames)g(into)h(system)g (\002le)g(names,)h(or)f FJ(None)f FN(if)i(the)208 775 y(system)20 b(def)o(ault)f(encoding)g(is)i(used.)j(The)c(result)g(v)n (alue)g(depends)f(on)h(the)g(operating)e(system:)349 941 y FM(\017)o FN(On)i(W)m(indo)n(ws)g(9x,)g(the)g(encoding)e(is)j (\223mbcs\224.)349 1074 y FM(\017)o FN(On)f(Mac)h(OS)g(X,)f(the)g (encoding)e(is)j(\223utf-8\224.)349 1207 y FM(\017)o FN(On)d(U)t FH(N)t(I)t(X)r FN(,)g(the)e(encoding)e(is)j(the)f(user')-5 b(s)16 b(preference)e(according)g(to)j(the)f(result)g(of)f(nl)p 2847 1207 25 4 v 30 w(langinfo\(CODESET\),)e(or)j FJ(None)390 1307 y FN(if)21 b(the)f FJ(nl_langinfo\(CODESET\))d FN(f)o(ailed.)349 1439 y FM(\017)o FN(On)80 b(W)m(indo)n(ws)g(NT+,)95 b(\002le)81 b(names)e(are)i(Unicode)d(nati)n(v)o(ely)-5 b(,)94 b(so)80 b(no)g(con)m(v)o(ersion)d(is)k(performed.)390 1539 y FJ(getfilesystemencoding\(\))46 b FN(still)52 b(returns)d FJ('mbcs')p FN(,)56 b(as)51 b(this)g(is)g(the)f(encoding)e(that)i (applications)390 1639 y(should)23 b(use)i(when)e(the)o(y)h(e)o (xplicitly)f(w)o(ant)h(to)g(con)m(v)o(ert)e(Unicode)h(strings)h(to)h (byte)e(strings)h(that)h(are)f(equi)n(v)n(alent)e(when)390 1738 y(used)e(as)h(\002le)g(names.)208 1904 y(Ne)n(w)f(in)g(v)o(ersion) f(2.3.)0 2051 y FD(getrefcount)p FJ(\()p FK(object)q FJ(\))208 2151 y FN(Return)26 b(the)i(reference)d(count)i(of)f(the)i FK(object)q FN(.)46 b(The)27 b(count)f(returned)f(is)k(generally)c(one) i(higher)f(than)h(you)f(might)h(e)o(xpect,)208 2250 y(because)19 b(it)i(includes)e(the)i(\(temporary\))c(reference)h(as)j(an)f(ar)o (gument)e(to)j FJ(getrefcount\(\))p FN(.)0 2397 y FD(getrecursionlimit) p FJ(\(\))208 2497 y FN(Return)i(the)g(current)g(v)n(alue)g(of)g(the)h (recursion)e(limit,)j(the)e(maximum)f(depth)h(of)h(the)f(Python)g (interpreter)f(stack.)35 b(This)24 b(limit)208 2597 y(pre)n(v)o(ents)30 b(in\002nite)i(recursion)e(from)h(causing)g(an)h(o)o(v)o(er\003o)n(w)e (of)i(the)g(C)g(stack)g(and)g(crashing)f(Python.)59 b(It)32 b(can)f(be)h(set)h(by)208 2696 y FJ(setrecursionlimit\(\))p FN(.)0 2843 y FD(_getframe)p FJ(\()p FC([)p FK(depth)12 b FC(])p FJ(\))208 2943 y FN(Return)22 b(a)h(frame)f(object)h(from)f (the)g(call)i(stack.)33 b(If)23 b(optional)e(inte)o(ger)h FK(depth)g FN(is)i(gi)n(v)o(en,)e(return)f(the)i(frame)f(object)h(that) g(man)o(y)208 3042 y(calls)i(belo)n(w)f(the)g(top)g(of)h(the)f(stack.) 38 b(If)25 b(that)f(is)i(deeper)d(than)h(the)g(call)h(stack,)h FJ(ValueError)d FN(is)j(raised.)37 b(The)24 b(def)o(ault)g(for)208 3142 y FK(depth)19 b FN(is)i(zero,)e(returning)f(the)j(frame)e(at)i (the)f(top)g(of)g(the)g(call)g(stack.)208 3275 y(This)g(function)e (should)i(be)g(used)g(for)f(internal)h(and)f(specialized)h(purposes)f (only)-5 b(.)0 3422 y FD(getwindowsversion)p FJ(\(\))208 3521 y FN(Return)25 b(a)i(tuple)e(containing)f(\002)n(v)o(e)i (components,)f(describing)g(the)h(W)m(indo)n(ws)f(v)o(ersion)g (currently)f(running.)40 b(The)26 b(elements)208 3621 y(are)20 b FK(major)r FN(,)f FK(minor)r FN(,)h FK(b)n(uild)r FN(,)g FK(platform)p FN(,)f(and)h FK(te)n(xt)q FN(.)26 b FK(te)n(xt)d FN(contains)c(a)i(string)f(while)g(all)h(other)e(v)n (alues)h(are)g(inte)o(gers.)208 3754 y FK(platform)f FN(may)h(be)g(one)g(of)g(the)g(follo)n(wing)e(v)n(alues:)848 3883 y FL(Constant)p 2391 3913 4 100 v 1270 w(Platf)n(orm)p 799 3916 2511 4 v 848 3986 a FJ(0)50 b(\(VER_PLATFORM_WIN32s\))p 2391 4016 4 100 v 444 w FN(W)m(in32s)20 b(on)g(W)m(indo)n(ws)f(3.1)848 4086 y FJ(1)50 b(\(VER_PLATFORM_WIN32_WINDOWS\))p 2391 4115 V 94 w FN(W)m(indo)n(ws)20 b(95/98/ME)848 4185 y FJ(2)50 b(\(VER_PLATFORM_WIN32_NT\))p 2391 4215 V 344 w FN(W)m(indo)n(ws)20 b(NT/2000/XP)848 4285 y FJ(3)50 b(\(VER_PLATFORM_WIN32_CE\))p 2391 4315 V 344 w FN(W)m(indo)n(ws)20 b(CE)208 4413 y(This)g(function)e(wraps)h(the)h(W)m(in32)f FJ(GetVersionEx\(\))f FN(function;)g(see)j(the)f(Microsoft)f (documentation)d(for)k(more)f(infor)n(-)208 4512 y(mation)g(about)g (these)i(\002elds.)208 4645 y(A)-6 b(v)n(ailability:)24 b(W)m(indo)n(ws.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4792 y FD(hexversion)208 4892 y FN(The)26 b(v)o(ersion)g(number)f (encoded)g(as)i(a)h(single)e(inte)o(ger)-5 b(.)45 b(This)27 b(is)h(guaranteed)c(to)j(increase)g(with)g(each)f(v)o(ersion,)h (including)208 4991 y(proper)c(support)g(for)h(non-production)d (releases.)39 b(F)o(or)24 b(e)o(xample,)h(to)g(test)g(that)g(the)g (Python)f(interpreter)f(is)j(at)f(least)h(v)o(ersion)208 5091 y(1.5.2,)18 b(use:)p 0 5549 3901 4 v 0 5649 a FI(830)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 831 843 TeXDict begin 831 842 bop 444 174 a FA(if)44 b(sys.hexversion)f(>=)h (0x010502F0:)623 266 y(#)h(use)f(some)g(advanced)g(feature)623 357 y(...)444 448 y(else:)623 540 y(#)h(use)f(an)h(alternative)e (implementation)f(or)j(warn)f(the)g(user)623 631 y(...)208 820 y FN(This)23 b(is)h(called)f(`)p FJ(hexversion)p FN(')e(since)i(it)h(only)e(really)g(looks)h(meaningful)e(when)h(vie)n (wed)g(as)i(the)f(result)g(of)g(passing)g(it)g(to)208 920 y(the)e(b)n(uilt-in)f FJ(hex\(\))g FN(function.)26 b(The)21 b FJ(version_info)e FN(v)n(alue)h(may)h(be)f(used)h(for)f(a)i (more)e(human-friendly)d(encoding)i(of)208 1020 y(the)h(same)g (information.)48 b(Ne)n(w)21 b(in)f(v)o(ersion)f(1.5.2.)0 1167 y FD(last_type)0 1266 y(last_value)0 1366 y(last_traceback)208 1465 y FN(These)j(three)g(v)n(ariables)g(are)h(not)f(al)o(w)o(ays)h (de\002ned;)g(the)o(y)f(are)h(set)h(when)e(an)g(e)o(xception)f(is)j (not)e(handled)f(and)h(the)h(interpreter)208 1565 y(prints)k(an)g (error)f(message)h(and)g(a)h(stack)g(traceback.)45 b(Their)27 b(intended)f(use)h(is)i(to)e(allo)n(w)h(an)f(interacti)n(v)o(e)f(user)h (to)h(import)e(a)208 1665 y(deb)n(ugger)17 b(module)h(and)g(engage)g (in)i(post-mortem)d(deb)n(ugging)g(without)h(ha)n(ving)g(to)i(re-e)o(x) o(ecute)d(the)i(command)f(that)h(caused)208 1764 y(the)27 b(error)-5 b(.)44 b(\(T)-7 b(ypical)26 b(use)i(is)g(`)p FJ(import)48 b(pdb;)h(pdb.pm\(\))p FN(')26 b(to)h(enter)f(the)i (post-mortem)c(deb)n(ugger;)29 b(see)e(chapter)f(24,)208 1864 y(\223The)19 b(Python)g(Deb)n(ugger)m(,)-6 b(\224)18 b(for)i(more)f(information.\))208 1997 y(The)g(meaning)g(of)h(the)g(v)n (ariables)g(is)h(the)f(same)g(as)h(that)g(of)f(the)g(return)f(v)n (alues)h(from)f FJ(exc_info\(\))g FN(abo)o(v)o(e.)k(\(Since)d(there)g (is)208 2096 y(only)f(one)h(interacti)n(v)o(e)e(thread,)h (thread-safety)g(is)i(not)f(a)g(concern)f(for)g(these)i(v)n(ariables,)e (unlik)o(e)g(for)h FJ(exc_type)f FN(etc.\))0 2243 y FD(maxint)208 2343 y FN(The)26 b(lar)o(gest)f(positi)n(v)o(e)h(inte)o(ger)f (supported)f(by)i(Python')-5 b(s)26 b(re)o(gular)f(inte)o(ger)g(type.) 43 b(This)26 b(is)i(at)e(least)h(2**31-1.)41 b(The)26 b(lar)o(gest)208 2443 y(ne)o(gati)n(v)o(e)18 b(inte)o(ger)h(is)i FJ(-maxint-1)e FN(\227)i(the)f(asymmetry)f(results)h(from)f(the)h(use)h (of)f(2')-5 b(s)20 b(complement)f(binary)f(arithmetic.)0 2589 y FD(maxunicode)208 2689 y FN(An)25 b(inte)o(ger)g(gi)n(ving)f (the)i(lar)o(gest)f(supported)e(code)i(point)g(for)g(a)h(Unicode)f (character)-5 b(.)40 b(The)26 b(v)n(alue)f(of)g(this)h(depends)e(on)i (the)208 2789 y(con\002guration)17 b(option)i(that)h(speci\002es)h (whether)e(Unicode)g(characters)g(are)i(stored)e(as)i(UCS-2)g(or)e (UCS-4.)0 2936 y FD(modules)208 3035 y FN(This)k(is)g(a)h(dictionary)d (that)i(maps)g(module)e(names)i(to)g(modules)f(which)g(ha)n(v)o(e)g (already)g(been)g(loaded.)32 b(This)23 b(can)g(be)g(manip-)208 3135 y(ulated)f(to)g(force)g(reloading)f(of)h(modules)g(and)g(other)f (tricks.)32 b(Note)23 b(that)g(remo)o(ving)d(a)j(module)e(from)g(this)j (dictionary)c(is)k FK(not)208 3234 y FN(the)c(same)g(as)h(calling)f FJ(reload\(\))f FN(on)h(the)g(corresponding)d(module)i(object.)0 3381 y FD(path)208 3481 y FN(A)h(list)h(of)e(strings)h(that)f (speci\002es)h(the)g(search)f(path)h(for)f(modules.)k(Initialized)c (from)g(the)h(en)m(vironment)c(v)n(ariable)j(PYTHON-)208 3581 y(P)-8 b(A)f(TH,)20 b(plus)g(an)g(installation-dependent)d(def)o (ault.)208 3713 y(As)24 b(initialized)g(upon)f(program)f(startup,)i (the)g(\002rst)h(item)f(of)g(this)h(list,)h FJ(path[0])p FN(,)e(is)h(the)f(directory)e(containing)g(the)j(script)208 3813 y(that)f(w)o(as)i(used)e(to)h(in)m(v)n(ok)o(e)e(the)h(Python)g (interpreter)-5 b(.)37 b(If)24 b(the)h(script)f(directory)f(is)j(not)e (a)n(v)n(ailable)g(\(e.g.)37 b(if)25 b(the)g(interpreter)e(is)208 3913 y(in)m(v)n(ok)o(ed)e(interacti)n(v)o(ely)h(or)g(if)i(the)f(script) h(is)g(read)e(from)h(standard)f(input\),)g FJ(path[0])h FN(is)h(the)f(empty)g(string,)g(which)g(directs)208 4012 y(Python)i(to)j(search)e(modules)g(in)h(the)h(current)d(directory)h (\002rst.)46 b(Notice)27 b(that)g(the)g(script)g(directory)e(is)j (inserted)f FK(befor)m(e)g FN(the)208 4112 y(entries)20 b(inserted)f(as)i(a)g(result)f(of)g(PYTHONP)-8 b(A)f(TH.)208 4245 y(A)20 b(program)e(is)j(free)f(to)h(modify)d(this)j(list)g(for)f (its)h(o)n(wn)f(purposes.)208 4378 y(Changed)e(in)j(v)o(ersion)e(2.3:)g (Unicode)g(strings)i(are)f(no)f(longer)g(ignored.)0 4524 y FD(platform)208 4624 y FN(This)f(string)h(contains)f(a)h(platform)e (identi\002er)m(,)h(e.g.)24 b FJ('sunos5')18 b FN(or)g FJ('linux1')p FN(.)24 b(This)19 b(can)f(be)h(used)f(to)h(append)e (platform-)208 4724 y(speci\002c)j(components)e(to)i FJ(path)p FN(,)g(for)g(instance.)0 4871 y FD(prefix)208 4970 y FN(A)33 b(string)f(gi)n(ving)g(the)g(site-speci\002c)h (directory)e(pre\002x)h(where)g(the)h(platform)e(independent)g(Python)g (\002les)j(are)f(installed;)208 5070 y(by)c(def)o(ault,)j(this)e(is)h (the)f(string)g FJ('/usr/local')p FN(.)53 b(This)30 b(can)g(be)g(set)g (at)h(b)n(uild)e(time)i(with)f(the)g FL(--pr)o(e\002x)f FN(ar)o(gument)e(to)208 5169 y(the)f FL(con\002gur)o(e)g FN(script.)44 b(The)26 b(main)g(collection)g(of)g(Python)f(library)h (modules)f(is)j(installed)e(in)h(the)g(directory)d FJ(prefix)49 b(+)208 5269 y('/lib/python)p FK(ver)o(sion)p FJ(')26 b FN(while)i(the)h(platform)d(independent)g(header)h(\002les)j(\(all)f (e)o(xcept)e(`)p FO(p)n(ycon\002g.h)p FN('\))f(are)j(stored)e(in)208 5369 y FJ(prefix)48 b(+)i('/include/python)p FK(ver)o(sion)p FJ(')p FN(,)17 b(where)i FK(ver)o(sion)i FN(is)g(equal)e(to)i FJ(version[:3])p FN(.)p 0 5549 3901 4 v 0 5649 a FI(26.1.)52 b FJ(sys)23 b FI(\227)g(System-speci\002c)e(par)o(ameters)i(and)h (functions)1707 b(831)p eop end %%Page: 832 844 TeXDict begin 832 843 bop 0 83 a FD(ps1)0 183 y(ps2)208 282 y FN(Strings)19 b(specifying)f(the)i(primary)e(and)h(secondary)f (prompt)g(of)h(the)h(interpreter)-5 b(.)23 b(These)d(are)f(only)g (de\002ned)g(if)h(the)f(interpreter)208 382 y(is)30 b(in)f(interacti)n (v)o(e)e(mode.)51 b(Their)28 b(initial)i(v)n(alues)e(in)h(this)h(case)f (are)g FJ('>>>)49 b(')30 b FN(and)e FJ('...)49 b(')p FN(.)j(If)29 b(a)g(non-string)e(object)i(is)208 482 y(assigned)17 b(to)i(either)f(v)n(ariable,)f(its)j FJ(str\(\))e FN(is)h(re-e)n(v)n (aluated)d(each)i(time)g(the)h(interpreter)e(prepares)g(to)h(read)g(a)h (ne)n(w)f(interacti)n(v)o(e)208 581 y(command;)g(this)j(can)f(be)g (used)g(to)g(implement)f(a)h(dynamic)f(prompt.)0 728 y FD(setcheckinterval)p FJ(\()p FK(interval)p FJ(\))208 828 y FN(Set)e(the)g(interpreter')-5 b(s)16 b(\223check)g(interv)n (al\224.)23 b(This)17 b(inte)o(ger)f(v)n(alue)h(determines)f(ho)n(w)g (often)g(the)i(interpreter)d(checks)h(for)h(periodic)208 927 y(things)22 b(such)g(as)i(thread)e(switches)h(and)f(signal)h (handlers.)31 b(The)22 b(def)o(ault)g(is)i FJ(100)p FN(,)f(meaning)e (the)i(check)f(is)i(performed)c(e)n(v)o(ery)208 1027 y(100)14 b(Python)h(virtual)g(instructions.)23 b(Setting)15 b(it)i(to)f(a)g(lar)o(ger)e(v)n(alue)i(may)f(increase)g(performance)e (for)i(programs)f(using)h(threads.)208 1127 y(Setting)20 b(it)h(to)f(a)g(v)n(alue)g FJ(<=)g FN(0)h(checks)e(e)n(v)o(ery)g (virtual)h(instruction,)e(maximizing)h(responsi)n(v)o(eness)f(as)j (well)g(as)g(o)o(v)o(erhead.)0 1273 y FD(setdefaultencoding)p FJ(\()p FK(name)p FJ(\))208 1373 y FN(Set)32 b(the)g(current)f(def)o (ault)h(string)f(encoding)g(used)g(by)h(the)g(Unicode)f (implementation.)59 b(If)32 b FK(name)f FN(does)h(not)g(match)f(an)o(y) 208 1473 y(a)n(v)n(ailable)23 b(encoding,)g FJ(LookupError)f FN(is)j(raised.)37 b(This)24 b(function)e(is)j(only)f(intended)e(to)i (be)g(used)g(by)g(the)g FJ(site)g FN(module)208 1572 y(implementation)16 b(and,)h(where)h(needed,)f(by)h FJ(sitecustomize)p FN(.)k(Once)c(used)g(by)g(the)g FJ(site)g FN(module,)f(it)i(is)g(remo)o (v)o(ed)d(from)208 1672 y(the)k FJ(sys)g FN(module')-5 b(s)19 b(namespace.)50 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.0.)0 1819 y FD(setdlopenflags)p FJ(\()p FK(n)p FJ(\))208 1918 y FN(Set)39 b(the)g(\003ags)g(used)g(by)g(the)g(interpreter)e(for)h FJ(dlopen\(\))g FN(calls,)44 b(such)39 b(as)h(when)e(the)h(interpreter) e(loads)i(e)o(xtension)208 2018 y(modules.)96 b(Among)43 b(other)g(things,)50 b(this)44 b(will)h(enable)f(a)h(lazy)f(resolving)e (of)i(symbols)g(when)g(importing)e(a)j(mod-)208 2118 y(ule,)52 b(if)47 b(called)f(as)h FJ(sys.setdlopenflags\(0\))p FN(.)100 b(T)-7 b(o)46 b(share)g(symbols)g(across)g(e)o(xtension)f (modules,)51 b(call)c(as)208 2217 y FJ(sys.setdlopenflags\(dl.RTLD_NOW) d(|)49 b(dl.RTLD_GLOBAL\))p FN(.)22 b(Symbolic)g(names)i(for)f(the)h (\003ag)g(modules)208 2317 y(can)d(be)h(either)g(found)e(in)i(the)g FJ(dl)g FN(module,)f(or)g(in)h(the)g FJ(DLFCN)g FN(module.)29 b(If)21 b FJ(DLFCN)h FN(is)h(not)e(a)n(v)n(ailable,)h(it)h(can)e(be)h (generated)208 2417 y(from)d(`)p FO(/usr/include/dlfcn.h)p FN(')c(using)k(the)i FL(h2py)f FN(script.)25 b(A)-6 b(v)n(ailability:) 26 b(U)t FH(N)t(I)t(X)r FN(.)52 b(Ne)n(w)20 b(in)g(v)o(ersion)f(2.2.)0 2563 y FD(setprofile)p FJ(\()p FK(pr)l(o\002lefunc)p FJ(\))208 2663 y FN(Set)j(the)g(system')-5 b(s)23 b(pro\002le)e (function,)g(which)g(allo)n(ws)h(you)f(to)h(implement)f(a)i(Python)d (source)i(code)f(pro\002ler)g(in)h(Python.)29 b(See)208 2763 y(chapter)21 b(25)h(for)g(more)g(information)e(on)i(the)g(Python)g (pro\002ler)-5 b(.)31 b(The)22 b(system')-5 b(s)23 b(pro\002le)f (function)f(is)i(called)g(similarly)f(to)h(the)208 2862 y(system')-5 b(s)22 b(trace)g(function)e(\(see)i FJ(settrace\(\))p FN(\),)e(b)n(ut)i(it)g(isn')o(t)g(called)g(for)f(each)g(e)o(x)o(ecuted) f(line)i(of)g(code)f(\(only)f(on)i(call)g(and)208 2962 y(return,)i(b)n(ut)h(the)g(return)f(e)n(v)o(ent)g(is)i(reported)d(e)n (v)o(en)h(when)g(an)h(e)o(xception)e(has)i(been)f(set\).)40 b(The)24 b(function)g(is)i(thread-speci\002c,)208 3062 y(b)n(ut)c(there)h(is)h(no)e(w)o(ay)h(for)f(the)h(pro\002ler)f(to)h (kno)n(w)f(about)f(conte)o(xt)h(switches)h(between)f(threads,)h(so)g (it)h(does)e(not)h(mak)o(e)f(sense)208 3161 y(to)e(use)g(this)h(in)f (the)h(presence)e(of)h(multiple)f(threads.)24 b(Also,)d(its)g(return)e (v)n(alue)h(is)h(not)f(used,)f(so)i(it)g(can)f(simply)f(return)h FJ(None)p FN(.)0 3308 y FD(setrecursionlimit)p FJ(\()p FK(limit)q FJ(\))208 3408 y FN(Set)30 b(the)g(maximum)f(depth)g(of)g (the)i(Python)d(interpreter)h(stack)h(to)g FK(limit)q FN(.)56 b(This)30 b(limit)h(pre)n(v)o(ents)d(in\002nite)i(recursion)f (from)208 3507 y(causing)19 b(an)h(o)o(v)o(er\003o)n(w)e(of)i(the)h(C)g (stack)f(and)g(crashing)f(Python.)208 3640 y(The)c(highest)g(possible)h (limit)g(is)h(platform-dependent.)i(A)d(user)g(may)f(need)g(to)h(set)h (the)e(limit)i(higher)d(when)h(she)h(has)g(a)h(program)208 3740 y(that)j(requires)f(deep)h(recursion)f(and)h(a)g(platform)f(that)i (supports)e(a)i(higher)e(limit.)25 b(This)c(should)e(be)i(done)e(with)h (care,)g(because)208 3839 y(a)g(too-high)e(limit)j(can)f(lead)g(to)g(a) h(crash.)0 3986 y FD(settrace)p FJ(\()p FK(tr)o(acefunc)p FJ(\))208 4086 y FN(Set)31 b(the)g(system')-5 b(s)31 b(trace)g(function,)g(which)g(allo)n(ws)g(you)f(to)h(implement)e(a)i (Python)f(source)g(code)g(deb)n(ugger)f(in)i(Python.)208 4185 y(See)21 b(section)g(24.2,)f(\223Ho)n(w)h(It)g(W)-7 b(orks,)h(\224)22 b(in)f(the)g(chapter)f(on)h(the)g(Python)f(deb)n (ugger)-5 b(.)26 b(The)20 b(function)g(is)i(thread-speci\002c;)e(for)g (a)208 4285 y(deb)n(ugger)14 b(to)j(support)f(multiple)g(threads,)g(it) i(must)f(be)f(re)o(gistered)g(using)g FJ(settrace\(\))g FN(for)g(each)g(thread)g(being)g(deb)n(ugged.)208 4385 y FL(Note:)29 b FN(The)22 b FJ(settrace\(\))g FN(function)f(is)i (intended)f(only)g(for)g(implementing)e(deb)n(uggers,)i(pro\002lers,)g (co)o(v)o(erage)e(tools)j(and)208 4484 y(the)c(lik)o(e.)24 b(Its)c(beha)n(vior)d(is)j(part)f(of)g(the)g(implementation)d (platform,)i(rather)g(than)h(part)f(of)h(the)g(language)e (de\002nition,)h(and)h(thus)208 4584 y(may)g(not)h(be)g(a)n(v)n (ailable)g(in)g(all)h(Python)e(implementations.)0 4731 y FD(settscdump)p FJ(\()p FK(on)p 639 4731 25 4 v 27 w(\003a)o(g)p FJ(\))208 4831 y FN(Acti)n(v)n(ate)c(dumping)f(of)i(VM)g (measurements)f(using)g(the)h(Pentium)g(timestamp)f(counter)m(,)g(if)i FK(on)p 2952 4831 V 28 w(\003a)o(g)f FN(is)h(true.)23 b(Deacti)n(v)n(ate)15 b(these)208 4930 y(dumps)22 b(if)i FK(on)p 617 4930 V 29 w(\003a)o(g)e FN(is)i(of)n(f.)34 b(The)23 b(function)f(is)i(a)n(v)n(ailable)f(only)g(if)h(Python)e(w)o (as)i(compiled)e(with)i FL(--with-tsc)p FN(.)33 b(T)-7 b(o)24 b(understand)208 5030 y(the)c(output)f(of)h(this)g(dump,)f(read) h(`)p FO(Python/ce)n(v)n(al.c)p FN(')d(in)k(the)f(Python)f(sources.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.4.)0 5177 y FD(stdin)0 5276 y(stdout)0 5376 y(stderr)p 0 5549 3901 4 v 0 5649 a FI(832)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r (vices)p eop end %%Page: 833 845 TeXDict begin 833 844 bop 208 83 a FN(File)31 b(objects)f (corresponding)d(to)j(the)h(interpreter')-5 b(s)29 b(standard)g(input,) j(output)d(and)h(error)f(streams.)56 b FJ(stdin)30 b FN(is)h(used)f(for)208 183 y(all)24 b(interpreter)f(input)h(e)o(xcept)f (for)g(scripts)i(b)n(ut)f(including)f(calls)i(to)f FJ(input\(\))g FN(and)f FJ(raw_input\(\))p FN(.)36 b FJ(stdout)24 b FN(is)h(used)208 282 y(for)j(the)h(output)f(of)g FJ(print)h FN(and)f(e)o(xpression)g(statements)h(and)f(for)g(the)h(prompts)f(of)h FJ(input\(\))f FN(and)g FJ(raw_input\(\))p FN(.)208 382 y(The)e(interpreter')-5 b(s)26 b(o)n(wn)h(prompts)f(and)g(\(almost)h (all)h(of\))e(its)i(error)e(messages)i(go)e(to)i FJ(stderr)p FN(.)45 b FJ(stdout)27 b FN(and)f FJ(stderr)208 482 y FN(needn')o(t)j(be)i(b)n(uilt-in)g(\002le)h(objects:)48 b(an)o(y)30 b(object)h(is)h(acceptable)f(as)h(long)e(as)j(it)f(has)f(a) h FJ(write\(\))f FN(method)f(that)h(tak)o(es)h(a)208 581 y(string)f(ar)o(gument.)56 b(\(Changing)29 b(these)j(objects)f (doesn')o(t)f(af)n(fect)h(the)g(standard)f(I/O)i(streams)f(of)g (processes)g(e)o(x)o(ecuted)f(by)208 681 y FJ(os.popen\(\))p FN(,)18 b FJ(os.system\(\))h FN(or)h(the)g FJ(exec)1728 696 y(*)1778 681 y(\(\))f FN(f)o(amily)h(of)g(functions)f(in)h(the)g FJ(os)h FN(module.\))0 828 y FD(__stdin__)0 927 y(__stdout__)0 1027 y(__stderr__)208 1127 y FN(These)j(objects)g(contain)g(the)g (original)g(v)n(alues)g(of)g FJ(stdin)p FN(,)h FJ(stderr)f FN(and)g FJ(stdout)g FN(at)h(the)g(start)g(of)f(the)h(program.)36 b(The)o(y)208 1226 y(are)20 b(used)g(during)f(\002nalization,)h(and)g (could)f(be)i(useful)e(to)i(restore)f(the)h(actual)f(\002les)h(to)g (kno)n(wn)e(w)o(orking)g(\002le)i(objects)f(in)h(case)208 1326 y(the)o(y)e(ha)n(v)o(e)h(been)f(o)o(v)o(erwritten)f(with)i(a)h (brok)o(en)e(object.)0 1473 y FD(tracebacklimit)208 1572 y FN(When)24 b(this)h(v)n(ariable)f(is)h(set)h(to)e(an)h(inte)o(ger)e (v)n(alue,)i(it)g(determines)f(the)h(maximum)d(number)h(of)i(le)n(v)o (els)f(of)g(traceback)g(infor)n(-)208 1672 y(mation)c(printed)g(when)h (an)g(unhandled)e(e)o(xception)g(occurs.)28 b(The)21 b(def)o(ault)g(is)h FJ(1000)p FN(.)28 b(When)21 b(set)h(to)g FJ(0)g FN(or)f(less,)h(all)g(traceback)208 1772 y(information)17 b(is)k(suppressed)f(and)f(only)h(the)g(e)o(xception)e(type)i(and)f(v)n (alue)h(are)g(printed.)0 1918 y FD(version)208 2018 y FN(A)35 b(string)f(containing)f(the)h(v)o(ersion)f(number)g(of)h(the)h (Python)e(interpreter)g(plus)i(additional)e(information)f(on)i(the)h(b) n(uild)208 2118 y(number)24 b(and)i(compiler)f(used.)43 b(It)26 b(has)h(a)g(v)n(alue)e(of)h(the)h(form)e FJ(')p FK(ver)o(sion)49 b FJ(\(#)p FK(b)n(uild)p 2688 2118 25 4 v 29 w(number)r FJ(,)f FK(b)n(uild)p 3242 2118 V 29 w(date)p FJ(,)g FK(b)n(uild)p 3683 2118 V 29 w(time)p FJ(\))208 2217 y([)p FK(compiler)r FJ(]')p FN(.)43 b(The)27 b(\002rst)g(three)f(characters)g(are)h(used)f(to)h(identify)f(the)g(v)o (ersion)g(in)h(the)f(installation)h(directories)f(\(where)208 2317 y(appropriate)17 b(on)j(each)g(platform\).)j(An)d(e)o(xample:)444 2450 y FA(>>>)44 b(import)g(sys)444 2541 y(>>>)g(sys.version)444 2632 y('1.5.2)g(\(#0)g(Apr)g(13)h(1999,)f(10:51:12\))f([MSC)h(32)h(bit) f(\(Intel\)]')0 2834 y FD(api_version)208 2934 y FN(The)28 b(C)h(API)g(v)o(ersion)e(for)h(this)h(interpreter)-5 b(.)48 b(Programmers)27 b(may)h(\002nd)g(this)h(useful)f(when)g(deb)n (ugging)d(v)o(ersion)j(con\003icts)208 3033 y(between)19 b(Python)g(and)h(e)o(xtension)e(modules.)50 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 3180 y FD(version_info)208 3280 y FN(A)e(tuple)g(containing)e(the)j(\002)n(v)o(e)e(components)f (of)i(the)h(v)o(ersion)d(number:)22 b FK(major)r FN(,)c FK(minor)r FN(,)f FK(micr)l(o)p FN(,)h FK(r)m(eleasele)o(vel)p FN(,)g(and)e FK(serial)p FN(.)25 b(All)208 3379 y(v)n(alues)17 b(e)o(xcept)h FK(r)m(eleasele)o(vel)g FN(are)g(inte)o(gers;)g(the)h (release)f(le)n(v)o(el)g(is)h FJ('alpha')p FN(,)f FJ('beta')p FN(,)g FJ('candidate')p FN(,)f(or)h FJ('final')p FN(.)208 3479 y(The)j FJ(version_info)g FN(v)n(alue)g(corresponding)d(to)k(the)g (Python)f(v)o(ersion)g(2.0)g(is)i FJ(\(2,)50 b(0,)f(0,)g('final',)g (0\))p FN(.)61 b(Ne)n(w)208 3579 y(in)20 b(v)o(ersion)f(2.0.)0 3725 y FD(warnoptions)208 3825 y FN(This)g(is)i(an)f(implementation)d (detail)j(of)g(the)f(w)o(arnings)g(frame)n(w)o(ork;)f(do)h(not)h (modify)e(this)i(v)n(alue.)k(Refer)c(to)g(the)f FJ(warnings)208 3925 y FN(module)f(for)i(more)f(information)f(on)i(the)g(w)o(arnings)f (frame)n(w)o(ork.)0 4072 y FD(winver)208 4171 y FN(The)g(v)o(ersion)g (number)f(used)i(to)g(form)f(re)o(gistry)g(k)o(e)o(ys)h(on)f(W)m(indo)n (ws)g(platforms.)24 b(This)c(is)h(stored)f(as)g(string)g(resource)f (1000)f(in)208 4271 y(the)g(Python)g(DLL.)h(The)f(v)n(alue)h(is)g (normally)f(the)g(\002rst)i(three)f(characters)e(of)i FJ(version)p FN(.)24 b(It)19 b(is)h(pro)o(vided)c(in)j(the)g FJ(sys)g FN(module)208 4370 y(for)e(informational)f(purposes;)i (modifying)e(this)j(v)n(alue)f(has)h(no)f(ef)n(fect)g(on)g(the)g(re)o (gistry)g(k)o(e)o(ys)g(used)g(by)g(Python.)23 b(A)-6 b(v)n(ailability:)208 4470 y(W)m(indo)n(ws.)0 4617 y FL(See)21 b(Also:)0 4764 y FN(Module)e FJ(site)h FN(\(section)g (26.11\):)208 4863 y(This)g(describes)g(ho)n(w)f(to)i(use)f(.pth)g (\002les)h(to)f(e)o(xtend)f FJ(sys.path)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(26.1.)52 b FJ(sys)23 b FI(\227)g (System-speci\002c)e(par)o(ameters)i(and)h(functions)1707 b(833)p eop end %%Page: 834 846 TeXDict begin 834 845 bop 0 86 a FE(26.2)121 b Fx(__builtin__)30 b FE(\227)j(Built-in)g(objects)0 319 y FN(This)24 b(module)d(pro)o (vides)h(direct)h(access)h(to)f(all)h(`b)n(uilt-in')e(identi\002ers)h (of)g(Python;)h(for)f(e)o(xample,)f FJ(__builtin__.open)f FN(is)k(the)0 419 y(full)20 b(name)g(for)f(the)h(b)n(uilt-in)g (function)e FJ(open\(\))p FN(.)25 b(See)20 b(chapter)g(2,)g (\223Built-in)g(Objects.)-6 b(\224)0 566 y(This)17 b(module)e(is)j(not) f(normally)e(accessed)i(e)o(xplicitly)f(by)g(most)h(applications,)f(b)n (ut)h(can)f(be)h(useful)f(in)h(modules)f(that)h(pro)o(vide)e(objects)0 665 y(with)k(the)g(same)g(name)f(as)i(a)f(b)n(uilt-in)f(v)n(alue,)g(b)n (ut)h(in)g(which)g(the)g(b)n(uilt-in)f(of)g(that)h(name)g(is)g(also)h (needed.)j(F)o(or)18 b(e)o(xample,)g(in)h(a)g(module)0 765 y(that)h(w)o(ants)h(to)f(implement)f(an)h FJ(open\(\))g FN(function)e(that)j(wraps)f(the)g(b)n(uilt-in)f FJ(open\(\))p FN(,)h(this)h(module)d(can)i(be)h(used)e(directly:)236 912 y FA(import)44 b(__builtin__)236 1094 y(def)h(open\(path\):)416 1186 y(f)f(=)h(__builtin__.open\(path,)c('r'\))416 1277 y(return)i(UpperCaser\(f\))236 1460 y(class)h(UpperCaser:)416 1551 y('''Wrapper)f(around)h(a)g(file)g(that)h(converts)e(output)h(to)g (upper-case.''')416 1734 y(def)g(__init__\(self,)e(f\):)595 1825 y(self._f)i(=)g(f)416 2008 y(def)g(read\(self,)f(count=-1\):)595 2099 y(return)h(self._f.read\(count\).upper\(\))416 2282 y(#)g(...)0 2568 y FN(As)28 b(an)f(implementation)f(detail,)i(most)g (modules)e(ha)n(v)o(e)h(the)g(name)g FJ(__builtins__)f FN(\(note)g(the)i(`)p FJ(s)p FN('\))e(made)h(a)n(v)n(ailable)g(as)h (part)0 2668 y(of)e(their)h(globals.)43 b(The)27 b(v)n(alue)f(of)g FJ(__builtins__)f FN(is)j(normally)d(either)h(this)h(module)e(or)i(the) f(v)n(alue)g(of)g(this)i(modules')-5 b(s)26 b FJ(__-)0 2767 y(dict__)20 b FN(attrib)n(ute.)26 b(Since)21 b(this)g(is)h(an)e (implementation)f(detail,)h(it)i(may)e(not)g(be)h(used)f(by)h (alternate)f(implementations)f(of)h(Python.)0 3194 y FE(26.3)121 b Fx(__main__)31 b FE(\227)i(T)-14 b(op-le)l(v)m(el)34 b(scr)r(ipt)f(en)n(vironment)0 3427 y FN(This)24 b(module)e(represents) h(the)g(\(otherwise)g(anon)o(ymous\))d(scope)j(in)h(which)f(the)h (interpreter')-5 b(s)22 b(main)h(program)f(e)o(x)o(ecutes)g(\227)i (com-)0 3527 y(mands)17 b(read)h(either)g(from)f(standard)g(input,)g (from)g(a)i(script)f(\002le,)h(or)f(from)f(an)h(interacti)n(v)o(e)f (prompt.)23 b(It)18 b(is)h(this)g(en)m(vironment)c(in)j(which)0 3627 y(the)i(idiomatic)g(\223conditional)e(script\224)i(stanza)g (causes)h(a)f(script)g(to)h(run:)236 3865 y FA(if)45 b(__name__)e(==)i("__main__":)416 3956 y(main\(\))0 4466 y FE(26.4)121 b Fx(warnings)31 b FE(\227)i(W)-5 b(ar)s(ning)35 b(control)0 4699 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 4846 y(W)-7 b(arning)19 b(messages)g(are)h(typically)e(issued)i(in)f (situations)h(where)e(it)j(is)f(useful)f(to)g(alert)h(the)f(user)h(of)f (some)g(condition)f(in)h(a)h(program,)0 4945 y(where)h(that)h (condition)e(\(normally\))f(doesn')o(t)h(w)o(arrant)h(raising)g(an)h(e) o(xception)e(and)h(terminating)f(the)h(program.)27 b(F)o(or)22 b(e)o(xample,)e(one)0 5045 y(might)g(w)o(ant)g(to)g(issue)h(a)g(w)o (arning)e(when)g(a)i(program)d(uses)j(an)f(obsolete)f(module.)0 5192 y(Python)26 b(programmers)e(issue)k(w)o(arnings)e(by)g(calling)h (the)g FJ(warn\(\))f FN(function)f(de\002ned)h(in)h(this)h(module.)44 b(\(C)27 b(programmers)d(use)0 5292 y FJ(PyErr_Warn\(\))p FN(;)19 b(see)h(the)h FK(Python/C)e(API)h(Refer)m(ence)f(Manual)g FN(for)h(details\).)p 0 5549 3901 4 v 0 5649 a FI(834)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 835 847 TeXDict begin 835 846 bop 0 83 a FN(W)-7 b(arning)18 b(messages)g(are)g(normally)e(written)i(to)g FJ(sys.stderr)p FN(,)f(b)n(ut)h(their)g(disposition)f(can)h(be)g(changed)f(\003e)o (xibly)-5 b(,)17 b(from)g(ignoring)0 183 y(all)i(w)o(arnings)f(to)g (turning)f(them)h(into)h(e)o(xceptions.)j(The)d(disposition)e(of)h(w)o (arnings)g(can)g(v)n(ary)g(based)g(on)g(the)g(w)o(arning)g(cate)o(gory) e(\(see)0 282 y(belo)n(w\),)i(the)g(te)o(xt)h(of)f(the)h(w)o(arning)e (message,)h(and)g(the)h(source)f(location)g(where)f(it)j(is)f(issued.) 25 b(Repetitions)18 b(of)g(a)h(particular)f(w)o(arning)0 382 y(for)i(the)g(same)g(source)g(location)f(are)h(typically)f (suppressed.)0 529 y(There)29 b(are)i(tw)o(o)f(stages)h(in)f(w)o (arning)f(control:)44 b(\002rst,)34 b(each)c(time)g(a)h(w)o(arning)e (is)i(issued,)h(a)f(determination)d(is)j(made)f(whether)f(a)0 628 y(message)c(should)f(be)h(issued)g(or)f(not;)k(ne)o(xt,)d(if)g(a)g (message)g(is)h(to)f(be)g(issued,)h(it)g(is)g(formatted)d(and)i (printed)e(using)i(a)g(user)n(-settable)0 728 y(hook.)0 875 y(The)k(determination)d(whether)i(to)h(issue)g(a)h(w)o(arning)d (message)i(is)h(controlled)d(by)h(the)h(w)o(arning)f(\002lter)m(,)j (which)d(is)i(a)f(sequence)f(of)0 975 y(matching)20 b(rules)h(and)f (actions.)27 b(Rules)22 b(can)e(be)h(added)f(to)h(the)g(\002lter)h(by)e (calling)h FJ(filterwarnings\(\))d FN(and)j(reset)g(to)g(its)h(def)o (ault)0 1074 y(state)f(by)f(calling)f FJ(resetwarnings\(\))p FN(.)0 1221 y(The)24 b(printing)g(of)g(w)o(arning)g(messages)h(is)g (done)f(by)h(calling)f FJ(showwarning\(\))p FN(,)g(which)g(may)g(be)h (o)o(v)o(erridden;)f(the)h(def)o(ault)f(im-)0 1321 y(plementation)17 b(of)h(this)i(function)d(formats)g(the)i(message)g(by)f(calling)g FJ(formatwarning\(\))p FN(,)f(which)h(is)i(also)f(a)n(v)n(ailable)f (for)g(use)h(by)0 1420 y(custom)h(implementations.)0 1705 y Fv(26.4.1)101 b(W)l(ar)r(ning)30 b(Categor)q(ies)0 1908 y FN(There)19 b(are)h(a)g(number)e(of)h(b)n(uilt-in)h(e)o (xceptions)e(that)i(represent)e(w)o(arning)h(cate)o(gories.)24 b(This)c(cate)o(gorization)d(is)k(useful)e(to)h(be)g(able)f(to)0 2008 y(\002lter)i(out)e(groups)g(of)h(w)o(arnings.)k(The)c(follo)n (wing)f(w)o(arnings)g(cate)o(gory)f(classes)j(are)g(currently)d (de\002ned:)50 2316 y FL(Class)p 1343 2346 4 100 v 1156 w(Description)p 0 2349 4774 4 v 50 2419 a FJ(Warning)p 1343 2448 4 100 v 995 w FN(This)i(is)h(the)f(base)h(class)g(of)f(all)h (w)o(arning)e(cate)o(gory)f(classes.)26 b(It)20 b(is)i(a)e(subclass)h (of)f FJ(Exception)p FN(.)50 2518 y FJ(UserWarning)p 1343 2548 V 795 w FN(The)g(def)o(ault)f(cate)o(gory)f(for)i FJ(warn\(\))p FN(.)50 2618 y FJ(DeprecationWarning)p 1343 2648 V 445 w FN(Base)h(cate)o(gory)d(for)i(w)o(arnings)f(about)g (deprecated)g(features.)50 2717 y FJ(SyntaxWarning)p 1343 2747 V 695 w FN(Base)i(cate)o(gory)d(for)i(w)o(arnings)f(about)g (dubious)g(syntactic)h(features.)50 2817 y FJ(RuntimeWarning)p 1343 2847 V 645 w FN(Base)h(cate)o(gory)d(for)i(w)o(arnings)f(about)g (dubious)g(runtime)g(features.)50 2917 y FJ(FutureWarning)p 1343 2947 V 695 w FN(Base)i(cate)o(gory)d(for)i(w)o(arnings)f(about)g (constructs)h(that)g(will)h(change)e(semantically)g(in)i(the)f(future.) 50 3016 y FJ(PendingDeprecationWarning)p 1343 3046 V 95 w FN(Base)h(cate)o(gory)d(for)i(w)o(arnings)f(about)g(features)h (that)g(will)h(be)f(deprecated)f(in)h(the)g(future)f(\(ignored)f(by)i (def)o(ault\).)50 3116 y FJ(ImportWarning)p 1343 3146 V 695 w FN(Base)h(cate)o(gory)d(for)i(w)o(arnings)f(triggered)g(during) f(the)i(process)g(of)g(importing)e(a)j(module)e(\(ignored)f(by)h(def)o (ault\).)50 3216 y FJ(UnicodeWarning)p 1343 3245 V 645 w FN(Base)i(cate)o(gory)d(for)i(w)o(arnings)f(related)h(to)g(Unicode.)0 3441 y(While)27 b(these)g(are)f(technically)g(b)n(uilt-in)g(e)o (xceptions,)g(the)o(y)g(are)g(documented)e(here,)k(because)e (conceptually)e(the)o(y)i(belong)f(to)i(the)0 3540 y(w)o(arnings)19 b(mechanism.)0 3687 y(User)h(code)g(can)f(de\002ne)h(additional)e(w)o (arning)h(cate)o(gories)g(by)h(subclassing)f(one)g(of)h(the)g(standard) f(w)o(arning)g(cate)o(gories.)k(A)e(w)o(arning)0 3787 y(cate)o(gory)d(must)j(al)o(w)o(ays)f(be)g(a)h(subclass)f(of)g(the)h FJ(Warning)e FN(class.)0 4072 y Fv(26.4.2)101 b(The)28 b(W)l(ar)r(nings)i(Filter)0 4275 y FN(The)20 b(w)o(arnings)f(\002lter)i (controls)e(whether)g(w)o(arnings)g(are)i(ignored,)d(displayed,)g(or)i (turned)f(into)h(errors)f(\(raising)h(an)g(e)o(xception\).)0 4421 y(Conceptually)-5 b(,)28 b(the)h(w)o(arnings)e(\002lter)i (maintains)f(an)h(ordered)d(list)k(of)e(\002lter)h(speci\002cations;)j (an)o(y)c(speci\002c)h(w)o(arning)e(is)j(matched)0 4521 y(against)24 b(each)g(\002lter)h(speci\002cation)e(in)i(the)f(list)i (in)e(turn)g(until)g(a)h(match)f(is)h(found;)g(the)f(match)g (determines)g(the)g(disposition)f(of)i(the)0 4621 y(match.)f(Each)c (entry)f(is)j(a)e(tuple)g(of)g(the)g(form)f(\()p FK(action)p FN(,)g FK(messa)o(g)o(e)p FN(,)h FK(cate)m(gory)p FN(,)f FK(module)p FN(,)g FK(lineno)p FN(\),)f(where:)125 4851 y FM(\017)41 b FK(action)19 b FN(is)i(one)f(of)g(the)g(follo)n(wing)e (strings:)p 0 5549 3901 4 v 0 5649 a FI(26.4.)52 b FJ(warnings)22 b FI(\227)h(W)m(ar)r(ning)h(control)2418 b(835)p eop end %%Page: 836 848 TeXDict begin 836 847 bop 257 70 a FL(V)-8 b(alue)p 754 100 4 100 v 348 w(Disposition)p 208 103 3727 4 v 257 173 a FJ("error")p 754 203 4 100 v 198 w FN(turn)20 b(matching)f(w)o (arnings)g(into)h(e)o(xceptions)257 272 y FJ("ignore")p 754 302 V 148 w FN(ne)n(v)o(er)f(print)h(matching)e(w)o(arnings)257 372 y FJ("always")p 754 402 V 148 w FN(al)o(w)o(ays)j(print)f(matching) e(w)o(arnings)257 472 y FJ("default")p 754 501 V 98 w FN(print)i(the)g(\002rst)h(occurrence)d(of)i(matching)f(w)o(arnings)g (for)g(each)h(location)g(where)f(the)h(w)o(arning)f(is)i(issued)257 571 y FJ("module")p 754 601 V 148 w FN(print)f(the)g(\002rst)h (occurrence)d(of)i(matching)f(w)o(arnings)g(for)g(each)h(module)f (where)h(the)g(w)o(arning)f(is)i(issued)257 671 y FJ("once")p 754 701 V 248 w FN(print)f(only)f(the)h(\002rst)h(occurrence)d(of)i (matching)f(w)o(arnings,)g(re)o(gardless)g(of)h(location)125 882 y FM(\017)41 b FK(messa)o(g)o(e)18 b FN(is)h(a)f(string)g (containing)e(a)j(re)o(gular)d(e)o(xpression)h(that)h(the)g(w)o(arning) f(message)h(must)g(match)g(\(the)f(match)h(is)h(compiled)208 981 y(to)h(al)o(w)o(ays)h(be)f(case-insensiti)n(v)o(e\))125 1148 y FM(\017)41 b FK(cate)m(gory)16 b FN(is)k(a)e(class)h(\(a)g (subclass)f(of)g FJ(Warning)p FN(\))f(of)h(which)g(the)g(w)o(arning)f (cate)o(gory)f(must)i(be)g(a)h(subclass)g(in)f(order)f(to)h(match)125 1314 y FM(\017)41 b FK(module)21 b FN(is)i(a)g(string)f(containing)e(a) j(re)o(gular)e(e)o(xpression)f(that)j(the)f(module)f(name)h(must)g (match)g(\(the)g(match)f(is)j(compiled)c(to)208 1413 y(be)g(case-sensiti)n(v)o(e\))125 1579 y FM(\017)41 b FK(lineno)17 b FN(is)j(an)f(inte)o(ger)e(that)i(the)g(line)g(number)e (where)h(the)h(w)o(arning)e(occurred)g(must)i(match,)f(or)h FJ(0)g FN(to)g(match)f(all)h(line)g(numbers)0 1809 y(Since)24 b(the)g FJ(Warning)f FN(class)i(is)g(deri)n(v)o(ed)e(from)g(the)h(b)n (uilt-in)f FJ(Exception)g FN(class,)j(to)e(turn)f(a)i(w)o(arning)e (into)h(an)g(error)f(we)h(simply)0 1909 y(raise)c FJ (category\(message\))p FN(.)0 2056 y(The)i(w)o(arnings)f(\002lter)h(is) h(initialized)f(by)f FL(-W)h FN(options)g(passed)f(to)i(the)f(Python)e (interpreter)h(command)f(line.)30 b(The)22 b(interpreter)e(sa)n(v)o(es) 0 2155 y(the)e(ar)o(guments)d(for)i(all)i FL(-W)f FN(options)e(without) h(interpretation)f(in)i FJ(sys.warnoptions)p FN(;)e(the)i FJ(warnings)e FN(module)h(parses)g(these)0 2255 y(when)j(it)g(is)i (\002rst)f(imported)d(\(in)m(v)n(alid)h(options)g(are)h(ignored,)e (after)i(printing)f(a)h(message)g(to)h FJ(sys.stderr)p FN(\).)0 2402 y(The)29 b(w)o(arnings)f(that)g(are)h(ignored)e(by)i(def) o(ault)f(may)g(be)h(enabled)f(by)g(passing)h FL(-Wd)g FN(to)g(the)g(interpreter)-5 b(.)50 b(This)29 b(enables)f(def)o(ault)0 2501 y(handling)20 b(for)i(all)h(w)o(arnings,)e(including)g(those)h (that)g(are)g(normally)f(ignored)f(by)i(def)o(ault.)30 b(This)23 b(is)g(particular)e(useful)g(for)h(enabling)0 2601 y(ImportW)-7 b(arning)23 b(when)i(deb)n(ugging)e(problems)i (importing)e(a)j(de)n(v)o(eloped)e(package.)40 b(ImportW)-7 b(arning)23 b(can)i(also)h(be)g(enabled)e(e)o(x-)0 2701 y(plicitly)c(in)g(Python)f(code)h(using:)416 2939 y FA (warnings.simplefilter\('default',)39 b(ImportWarning\))0 3362 y Fv(26.4.3)101 b(A)l(v)n(ailab)n(le)29 b(Functions)0 3551 y FD(warn)p FJ(\()p FK(messa)o(g)o(e)p FC([)p FK(,)19 b(cate)m(gory)p FC([)p FK(,)f(stac)n(kle)o(vel)12 b FC(])g(])p FJ(\))208 3651 y FN(Issue)22 b(a)h(w)o(arning,)f(or)g(maybe)f(ignore)g (it)i(or)f(raise)h(an)g(e)o(xception.)29 b(The)22 b FK(cate)m(gory)g FN(ar)o(gument,)e(if)j(gi)n(v)o(en,)e(must)i(be)f(a)h(w)o(arning)208 3750 y(cate)o(gory)e(class)i(\(see)g(abo)o(v)o(e\);)f(it)i(def)o(aults) e(to)h FJ(UserWarning)p FN(.)31 b(Alternati)n(v)o(ely)22 b FK(messa)o(g)o(e)h FN(can)f(be)h(a)g FJ(Warning)f FN(instance,)208 3850 y(in)d(which)g(case)h FK(cate)m(gory)f FN(will)h(be)g(ignored)e (and)h FJ(message.__class__)e FN(will)j(be)g(used.)k(In)19 b(this)i(case)f(the)f(message)h(te)o(xt)208 3950 y(will)i(be)g FJ(str\(message\))p FN(.)27 b(This)22 b(function)e(raises)j(an)e(e)o (xception)f(if)i(the)g(particular)e(w)o(arning)h(issued)h(is)g(changed) e(into)i(an)208 4049 y(error)j(by)i(the)g(w)o(arnings)f(\002lter)i(see) g(abo)o(v)o(e.)43 b(The)27 b FK(stac)n(kle)o(vel)g FN(ar)o(gument)e (can)i(be)g(used)g(by)f(wrapper)g(functions)g(written)g(in)208 4149 y(Python,)18 b(lik)o(e)j(this:)444 4373 y FA(def)44 b(deprecation\(message\):)623 4464 y(warnings.warn\(message,)d (DeprecationWarning,)h(stacklevel=2\))208 4654 y FN(This)28 b(mak)o(es)f(the)h(w)o(arning)f(refer)g(to)g FJ(deprecation\(\))p FN(')-5 b(s)27 b(caller)m(,)i(rather)e(than)g(to)h(the)g(source)f(of)g FJ(deprecation\(\))208 4753 y FN(itself)20 b(\(since)g(the)h(latter)f (w)o(ould)f(defeat)h(the)g(purpose)f(of)h(the)g(w)o(arning)f (message\).)0 4900 y FD(warn_explicit)p FJ(\()p FK(messa)o(g)o(e)o(,)f (cate)m(gory)-5 b(,)19 b(\002lename)o(,)g(lineno)p FC([)p FK(,)g(module)p FC([)p FK(,)f(r)m(e)m(gistry)p FC([)p FK(,)j(module)p 2863 4900 25 4 v 28 w(globals)12 b FC(])g(])g(])p FJ(\))208 5000 y FN(This)35 b(is)h(a)g(lo)n(w-le)n(v)o(el)e(interf)o (ace)h(to)g(the)h(functionality)d(of)i FJ(warn\(\))p FN(,)j(passing)d(in)h(e)o(xplicitly)e(the)h(message,)k(cate)o(gory)-5 b(,)208 5099 y(\002lename)39 b(and)g(line)h(number)m(,)i(and)d (optionally)f(the)i(module)e(name)h(and)g(the)h(re)o(gistry)f(\(which)g (should)f(be)i(the)g FJ(__-)208 5199 y(warningregistry__)30 b FN(dictionary)i(of)h(the)g(module\).)63 b(The)33 b(module)f(name)h (def)o(aults)f(to)i(the)f(\002lename)g(with)h FJ(.py)208 5299 y FN(stripped;)c(if)e(no)f(re)o(gistry)g(is)i(passed,)g(the)f(w)o (arning)e(is)j(ne)n(v)o(er)d(suppressed.)47 b FK(messa)o(g)o(e)28 b FN(must)f(be)h(a)g(string)g(and)f FK(cate)m(gory)f FN(a)208 5398 y(subclass)20 b(of)g FJ(Warning)f FN(or)h FK(messa)o(g)o(e)h FN(may)e(be)i(a)f FJ(Warning)g FN(instance,)f(in)h (which)g(case)h FK(cate)m(gory)e FN(will)i(be)f(ignored.)p 0 5549 3901 4 v 0 5649 a FI(836)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 837 849 TeXDict begin 837 848 bop 208 83 a FK(module)p 459 83 25 4 v 28 w(globals)p FN(,)18 b(if)h(supplied,)f(should)g(be)i(the)f (global)f(namespace)g(in)h(use)g(by)g(the)g(code)g(for)f(which)h(the)g (w)o(arning)f(is)i(issued.)208 183 y(\(This)d(ar)o(gument)f(is)j(used)e (to)h(support)f(displaying)f(source)h(for)g(modules)g(found)f(in)i (zip\002les)h(or)e(other)g(non-\002lesystem)g(import)208 282 y(sources,)i(and)h(w)o(as)h(added)e(in)h(Python)f(2.5.\))0 429 y FD(showwarning)p FJ(\()p FK(messa)o(g)o(e)o(,)f(cate)m(gory)-5 b(,)19 b(\002lename)o(,)g(lineno)p FC([)p FK(,)g(\002le)12 b FC(])p FJ(\))208 529 y FN(Write)31 b(a)h(w)o(arning)d(to)j(a)f (\002le.)58 b(The)31 b(def)o(ault)f(implementation)f(calls)i FJ(formatwarning\()p FK(messa)o(g)o(e)p FJ(,)47 b FK(cate)m(gory)p FJ(,)h FK(\002le-)208 628 y(name)p FJ(,)g FK(lineno)p FJ(\))23 b FN(and)g(writes)i(the)e(resulting)g(string)h(to)g FK(\002le)p FN(,)h(which)e(def)o(aults)g(to)h FJ(sys.stderr)p FN(.)35 b(Y)-9 b(ou)23 b(may)h(replace)f(this)208 728 y(function)18 b(with)i(an)h(alternati)n(v)o(e)d(implementation)g(by)i (assigning)g(to)g FJ(warnings.showwarning)p FN(.)0 875 y FD(formatwarning)p FJ(\()p FK(messa)o(g)o(e)o(,)e(cate)m(gory)-5 b(,)19 b(\002lename)o(,)g(lineno)p FJ(\))208 975 y FN(F)o(ormat)h(a)i (w)o(arning)f(the)h(standard)e(w)o(ay)-5 b(.)29 b(This)22 b(returns)f(a)h(string)f(which)g(may)g(contain)g(embedded)f(ne)n (wlines)h(and)g(ends)g(in)h(a)208 1074 y(ne)n(wline.)0 1221 y FD(filterwarnings)p FJ(\()p FK(action)p FC([)p FK(,)16 b(messa)o(g)o(e)p FC([)p FK(,)k(cate)m(gory)p FC([)p FK(,)f(module)p FC([)p FK(,)f(lineno)p FC([)p FK(,)h(append)12 b FC(])g(])g(])g(])g(])p FJ(\))208 1321 y FN(Insert)24 b(an)i(entry)e(into)h(the)g(list)i(of)e(w)o(arnings)f (\002lters.)41 b(The)25 b(entry)g(is)h(inserted)e(at)i(the)g(front)e (by)h(def)o(ault;)i(if)e FK(append)h FN(is)g(true,)208 1420 y(it)j(is)h(inserted)e(at)i(the)f(end.)50 b(This)29 b(checks)f(the)h(types)g(of)g(the)g(ar)o(guments,)f(compiles)h(the)g (message)f(and)h(module)e(re)o(gular)208 1520 y(e)o(xpressions,)j(and)f (inserts)h(them)f(as)h(a)g(tuple)f(in)h(the)f(list)i(of)e(w)o(arnings)g (\002lters.)53 b(Entries)30 b(closer)f(to)h(the)f(front)g(of)g(the)g (list)208 1620 y(o)o(v)o(erride)22 b(entries)i(later)g(in)h(the)f (list,)i(if)f(both)f(match)f(a)i(particular)e(w)o(arning.)37 b(Omitted)24 b(ar)o(guments)e(def)o(ault)i(to)g(a)h(v)n(alue)e(that)208 1719 y(matches)c(e)n(v)o(erything.)0 1866 y FD(simplefilter)p FJ(\()p FK(action)p FC([)p FK(,)d(cate)m(gory)p FC([)p FK(,)j(lineno)p FC([)p FK(,)g(append)11 b FC(])h(])g(])p FJ(\))208 1966 y FN(Insert)36 b(a)h(simple)g(entry)f(into)h(the)g(list) h(of)e(w)o(arnings)g(\002lters.)76 b(The)36 b(meaning)g(of)g(the)h (function)e(parameters)h(is)i(as)f(for)208 2065 y FJ (filterwarnings\(\))p FN(,)21 b(b)n(ut)j(re)o(gular)d(e)o(xpressions)h (are)i(not)f(needed)f(as)i(the)f(\002lter)h(inserted)f(al)o(w)o(ays)h (matches)f(an)o(y)g(mes-)208 2165 y(sage)d(in)g(an)o(y)g(module)e(as)j (long)f(as)h(the)f(cate)o(gory)e(and)i(line)g(number)e(match.)0 2312 y FD(resetwarnings)p FJ(\(\))208 2411 y FN(Reset)j(the)f(w)o (arnings)f(\002lter)-5 b(.)25 b(This)20 b(discards)g(the)g(ef)n(fect)f (of)h(all)h(pre)n(vious)d(calls)j(to)f FJ(filterwarnings\(\))p FN(,)d(including)h(that)208 2511 y(of)h(the)i FL(-W)f FN(command)e(line)j(options)e(and)g(calls)i(to)g FJ(simplefilter\(\))p FN(.)0 2838 y FE(26.5)121 b Fx(contextlib)31 b FE(\227)i(Utilities)f(f) l(or)i Fx(with)p FE(-statement)g(conte)l(xts)n(.)0 3071 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3218 y(This)h(module)f(pro)o (vides)g(utilities)i(for)e(common)f(tasks)j(in)m(v)n(olving)d(the)i FJ(with)g FN(statement.)0 3365 y(Functions)f(pro)o(vided:)0 3512 y FD(contextmanager)p FJ(\()p FK(func)p FJ(\))208 3612 y FN(This)h(function)f(is)j(a)f(decorator)d(that)j(can)f(be)h (used)f(to)h(de\002ne)f(a)h(f)o(actory)e(function)g(for)h FJ(with)g FN(statement)h(conte)o(xt)e(managers,)208 3711 y(without)g(needing)g(to)h(create)g(a)h(class)g(or)f(separate)f FJ(__enter__\(\))g FN(and)h FJ(__exit__\(\))f FN(methods.)208 3844 y(A)h(simple)g(e)o(xample)f(\(this)i(is)g(not)f(recommended)d(as)k (a)f(real)g(w)o(ay)h(of)f(generating)e(HTML!\):)444 4068 y FA(from)44 b(__future__)f(import)h(with_statement)444 4159 y(from)g(contextlib)f(import)h(contextmanager)444 4342 y(@contextmanager)444 4433 y(def)g(tag\(name\):)623 4525 y(print)g("<\045s>")g(\045)h(name)623 4616 y(yield)623 4707 y(print)f("</\045s>")g(\045)g(name)444 4890 y(>>>)g(with)g (tag\("h1"\):)444 4981 y(...)179 b(print)44 b("foo")444 5073 y(...)444 5164 y(<h1>)444 5255 y(foo)444 5347 y(</h1>)p 0 5549 3901 4 v 0 5649 a FI(26.5.)52 b FJ(contextlib)21 b FI(\227)j(Utilities)g(f)n(or)f FJ(with)p FI(-statement)f(conte)n(xts) o(.)1546 b(837)p eop end %%Page: 838 850 TeXDict begin 838 849 bop 208 83 a FN(The)20 b(function)g(being)g (decorated)f(must)i(return)f(a)i(generator)n(-iterator)c(when)i (called.)27 b(This)22 b(iterator)e(must)h(yield)g(e)o(xactly)f(one)208 183 y(v)n(alue,)f(which)g(will)i(be)g(bound)d(to)i(the)g(tar)o(gets)g (in)g(the)h FJ(with)f FN(statement')-5 b(s)20 b FJ(as)g FN(clause,)g(if)h(an)o(y)-5 b(.)208 315 y(At)15 b(the)h(point)e(where)h (the)g(generator)e(yields,)j(the)f(block)g(nested)f(in)i(the)f FJ(with)g FN(statement)g(is)h(e)o(x)o(ecuted.)22 b(The)15 b(generator)e(is)j(then)208 415 y(resumed)f(after)h(the)g(block)f(is)j (e)o(xited.)k(If)17 b(an)f(unhandled)e(e)o(xception)g(occurs)h(in)i (the)f(block,)g(it)h(is)g(reraised)f(inside)g(the)h(generator)208 515 y(at)28 b(the)f(point)g(where)g(the)g(yield)g(occurred.)45 b(Thus,)29 b(you)d(can)h(use)h(a)g FJ(try)p FN(...)p FJ(except)p FN(...)p FJ(finally)c FN(statement)j(to)g(trap)h(the)208 614 y(error)20 b(\(if)i(an)o(y\),)e(or)h(ensure)g(that)h(some)f (cleanup)g(tak)o(es)h(place.)29 b(If)21 b(an)h(e)o(xception)d(is)k (trapped)d(merely)h(in)g(order)g(to)h(log)f(it)h(or)f(to)208 714 y(perform)g(some)j(action)f(\(rather)g(than)g(to)h(suppress)f(it)i (entirely\),)e(the)h(generator)e(must)i(reraise)f(that)h(e)o(xception.) 34 b(Otherwise)208 814 y(the)27 b(generator)f(conte)o(xt)h(manager)f (will)i(indicate)f(to)h(the)g FJ(with)f FN(statement)h(that)g(the)g(e)o (xception)d(has)j(been)f(handled,)h(and)208 913 y(e)o(x)o(ecution)18 b(will)j(resume)e(with)h(the)h(statement)f(immediately)e(follo)n(wing)h (the)h FJ(with)g FN(statement.)0 1060 y FD(nested)p FJ(\()p FK(mgr1)p FC([)p FK(,)e(mgr2)p FC([)p FK(,)i(...)12 b FC(])g(])p FJ(\))208 1160 y FN(Combine)19 b(multiple)g(conte)o(xt)g (managers)g(into)h(a)h(single)f(nested)g(conte)o(xt)f(manager)-5 b(.)208 1293 y(Code)20 b(lik)o(e)g(this:)444 1517 y FA(from)44 b(contextlib)f(import)h(nested)444 1699 y(with)g(nested\(A,)f(B,)i(C\)) f(as)h(\(X,)f(Y,)h(Z\):)623 1791 y(do_something\(\))208 1980 y FN(is)21 b(equi)n(v)n(alent)d(to)j(this:)444 2204 y FA(with)44 b(A)h(as)f(X:)623 2296 y(with)g(B)h(as)f(Y:)802 2387 y(with)h(C)f(as)h(Z:)982 2478 y(do_something\(\))208 2668 y FN(Note)21 b(that)h(if)g(the)g FJ(__exit__\(\))e FN(method)h(of)g(one)g(of)h(the)g(nested)f(conte)o(xt)f(managers)h (indicates)g(an)h(e)o(xception)e(should)h(be)208 2767 y(suppressed,)f(no)g(e)o(xception)f(information)g(will)j(be)f(passed)g (to)g(an)o(y)g(remaining)e(outer)h(conte)o(xt)g(managers.)27 b(Similarly)-5 b(,)20 b(if)i(the)208 2867 y FJ(__exit__\(\))e FN(method)h(of)h(one)f(of)h(the)g(nested)g(managers)e(raises)j(an)f(e)o (xception,)e(an)o(y)i(pre)n(vious)e(e)o(xception)g(state)j(will)g(be) 208 2967 y(lost;)e(the)g(ne)n(w)f(e)o(xception)f(will)i(be)f(passed)h (to)g(the)f FJ(__exit__\(\))g FN(methods)f(of)h(an)o(y)g(remaining)f (outer)h(conte)o(xt)f(managers.)208 3066 y(In)h(general,)f FJ(__exit__\(\))h FN(methods)f(should)h(a)n(v)n(oid)g(raising)g(e)o (xceptions,)f(and)h(in)h(particular)e(the)o(y)h(should)g(not)g (re-raise)g(a)208 3166 y(passed-in)f(e)o(xception.)0 3313 y FD(closing)p FJ(\()p FK(thing)p FJ(\))208 3412 y FN(Return)g(a)i(conte)o(xt)e(manager)f(that)j(closes)f FK(thing)g FN(upon)f(completion)f(of)i(the)g(block.)k(This)c(is)i (basically)d(equi)n(v)n(alent)g(to:)444 3637 y FA(from)44 b(contextlib)f(import)h(contextmanager)444 3819 y(@contextmanager)444 3911 y(def)g(closing\(thing\):)623 4002 y(try:)802 4093 y(yield)g(thing)623 4184 y(finally:)802 4276 y(thing.close\(\))208 4465 y FN(And)19 b(lets)i(you)f(write)g(code)f(lik)o(e)i(this:)444 4689 y FA(from)44 b(__future__)f(import)h(with_statement)444 4781 y(from)g(contextlib)f(import)h(closing)444 4872 y(import)g(urllib)444 5055 y(with)g (closing\(urllib.urlopen\('http://www.pyth)o(on.org)o('\)\))39 b(as)44 b(page:)623 5146 y(for)g(line)h(in)f(page:)802 5237 y(print)g(line)p 0 5549 3901 4 v 0 5649 a FI(838)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 839 851 TeXDict begin 839 850 bop 208 83 a FN(without)24 b(needing)f(to)j(e)o (xplicitly)e(close)h FJ(page)p FN(.)39 b(Ev)o(en)24 b(if)i(an)f(error)f (occurs,)h FJ(page.close\(\))e FN(will)j(be)f(called)g(when)g(the)208 183 y FJ(with)20 b FN(block)f(is)i(e)o(xited.)0 330 y FL(See)g(Also:)0 476 y FN(PEP)g(0343,)d(\223)p FK(The)j(\224with\224)g (statement)p FN(\224)208 576 y(The)e(speci\002cation,)h(background,)c (and)k(e)o(xamples)f(for)g(the)i(Python)e FJ(with)h FN(statement.)0 903 y FE(26.6)121 b Fx(atexit)32 b FE(\227)h(Exit)f(handlers)0 1136 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 1283 y(The)k FJ(atexit)f FN(module)g(de\002nes)g(a)i(single)f(function)e(to)i(re)o (gister)f(cleanup)g(functions.)32 b(Functions)22 b(thus)h(re)o (gistered)f(are)h(automati-)0 1383 y(cally)d(e)o(x)o(ecuted)e(upon)h (normal)g(interpreter)g(termination.)0 1530 y(Note:)33 b(the)24 b(functions)f(re)o(gistered)g(via)h(this)h(module)e(are)h(not) g(called)g(when)f(the)h(program)e(is)j(killed)f(by)g(a)h(signal,)g (when)e(a)i(Python)0 1629 y(f)o(atal)20 b(internal)g(error)f(is)i (detected,)e(or)h(when)g FJ(os._exit\(\))f FN(is)i(called.)0 1776 y(This)f(is)h(an)g(alternate)e(interf)o(ace)h(to)g(the)g (functionality)e(pro)o(vided)g(by)i(the)g FJ(sys.exitfunc)e FN(v)n(ariable.)0 1923 y(Note:)39 b(This)28 b(module)d(is)j(unlik)o (ely)e(to)i(w)o(ork)e(correctly)g(when)h(used)g(with)g(other)f(code)h (that)g(sets)h FJ(sys.exitfunc)p FN(.)44 b(In)27 b(partic-)0 2023 y(ular)m(,)j(other)e(core)g(Python)g(modules)g(are)g(free)h(to)g (use)g FJ(atexit)f FN(without)g(the)h(programmer')-5 b(s)26 b(kno)n(wledge.)48 b(Authors)28 b(who)g(use)0 2122 y FJ(sys.exitfunc)i FN(should)g(con)m(v)o(ert)g(their)h(code)f(to) i(use)g FJ(atexit)f FN(instead.)58 b(The)31 b(simplest)h(w)o(ay)f(to)h (con)m(v)o(ert)d(code)i(that)g(sets)0 2222 y FJ(sys.exitfunc)19 b FN(is)i(to)f(import)f FJ(atexit)h FN(and)f(re)o(gister)h(the)g (function)f(that)h(had)g(been)f(bound)f(to)j FJ(sys.exitfunc)p FN(.)0 2369 y FD(register)p FJ(\()p FK(func)p FC([)p FK(,)d(*ar)m(gs)p FC([)p FK(,)h(**kar)m(gs)12 b FC(])g(])p FJ(\))208 2468 y FN(Re)o(gister)22 b FK(func)f FN(as)i(a)f(function)e (to)i(be)g(e)o(x)o(ecuted)e(at)j(termination.)28 b(An)o(y)22 b(optional)e(ar)o(guments)g(that)i(are)g(to)g(be)g(passed)g(to)g FK(func)208 2568 y FN(must)e(be)g(passed)g(as)h(ar)o(guments)d(to)i FJ(register\(\))p FN(.)208 2701 y(At)j(normal)f(program)g(termination)f (\(for)i(instance,)g(if)h FJ(sys.exit\(\))d FN(is)k(called)e(or)g(the)g (main)g(module')-5 b(s)22 b(e)o(x)o(ecution)f(com-)208 2800 y(pletes\),)h(all)h(functions)f(re)o(gistered)f(are)h(called)h(in) f(last)i(in,)f(\002rst)g(out)f(order)-5 b(.)32 b(The)22 b(assumption)f(is)j(that)e(lo)n(wer)g(le)n(v)o(el)h(modules)208 2900 y(will)d(normally)f(be)h(imported)f(before)f(higher)h(le)n(v)o(el) h(modules)f(and)h(thus)g(must)g(be)g(cleaned)g(up)g(later)-5 b(.)208 3033 y(If)23 b(an)h(e)o(xception)e(is)j(raised)f(during)e(e)o (x)o(ecution)g(of)h(the)h(e)o(xit)g(handlers,)f(a)h(traceback)f(is)i (printed)d(\(unless)i FJ(SystemExit)f FN(is)208 3133 y(raised\))17 b(and)g(the)g(e)o(xception)f(information)f(is)k(sa)n(v)o (ed.)24 b(After)17 b(all)h(e)o(xit)g(handlers)e(ha)n(v)o(e)h(had)g(a)h (chance)f(to)h(run)e(the)i(last)g(e)o(xception)208 3232 y(to)i(be)g(raised)g(is)h(re-raised.)0 3379 y FL(See)g(Also:)0 3526 y FN(Module)e FJ(readline)g FN(\(section)h(15.7\):)208 3626 y(Useful)g(e)o(xample)e(of)i FJ(atexit)g FN(to)g(read)g(and)g (write)g FJ(readline)f FN(history)h(\002les.)0 3910 y Fv(26.6.1)101 b Fm(atexit)26 b Fv(Example)0 4113 y FN(The)h(follo)n (wing)f(simple)i(e)o(xample)e(demonstrates)g(ho)n(w)h(a)h(module)e(can) i(initialize)g(a)g(counter)e(from)g(a)i(\002le)g(when)f(it)i(is)f (imported)0 4213 y(and)d(sa)n(v)o(e)g(the)g(counter')-5 b(s)24 b(updated)g(v)n(alue)g(automatically)g(when)h(the)g(program)e (terminates)i(without)f(relying)g(on)h(the)g(application)0 4313 y(making)19 b(an)h(e)o(xplicit)g(call)g(into)g(this)h(module)e(at) h(termination.)p 0 5549 3901 4 v 0 5649 a FI(26.6.)52 b FJ(atexit)22 b FI(\227)h(Exit)h(handlers)2618 b(839)p eop end %%Page: 840 852 TeXDict begin 840 851 bop 236 83 a FA(try:)416 174 y(_count)43 b(=)i(int\(open\("/tmp/counter"\).read\(\)\))236 266 y(except)f(IOError:)416 357 y(_count)f(=)i(0)236 540 y(def)g(incrcounter\(n\):)416 631 y(global)e(_count)416 722 y(_count)g(=)i(_count)f(+)h(n)236 905 y(def)g(savecounter\(\):)416 996 y(open\("/tmp/counter",)c("w"\).write\("\045d")h(\045)j(_count\)) 236 1179 y(import)f(atexit)236 1270 y(atexit.register\(savecounter\))0 1557 y FN(Positional)20 b(and)g(k)o(e)o(yw)o(ord)f(ar)o(guments)g(may)h (also)h(be)f(passed)g(to)h FJ(register\(\))e FN(to)i(be)g(passed)f (along)g(to)g(the)h(re)o(gistered)e(function)0 1656 y(when)h(it)g(is)i (called:)236 1895 y FA(def)45 b(goodbye\(name,)d(adjective\):)416 1986 y(print)i('Goodbye,)f(\045s,)h(it)h(was)f(\045s)h(to)f(meet)g (you.')g(\045)h(\(name,)f(adjective\))236 2169 y(import)g(atexit)236 2260 y(atexit.register\(goodbye,)d('Donny',)j('nice'\))236 2443 y(#)h(or:)236 2534 y(atexit.register\(goodbye,)c (adjective='nice',)h(name='Donny'\))0 3038 y FE(26.7)121 b Fx(traceback)31 b FE(\227)i(Pr)r(int)g(or)g(retr)r(ie)l(v)m(e)h(a)g (stac)n(k)f(tr)o(acebac)n(k)0 3271 y FN(This)28 b(module)f(pro)o(vides) f(a)j(standard)e(interf)o(ace)g(to)i(e)o(xtract,)g(format)e(and)g (print)h(stack)g(traces)g(of)g(Python)f(programs.)47 b(It)28 b(e)o(xactly)0 3371 y(mimics)20 b(the)h(beha)n(vior)e(of)h(the) g(Python)g(interpreter)e(when)i(it)h(prints)f(a)h(stack)g(trace.)k (This)c(is)g(useful)f(when)g(you)f(w)o(ant)i(to)g(print)e(stack)0 3470 y(traces)h(under)f(program)f(control,)h(such)h(as)h(in)f(a)h (\223wrapper\224)d(around)g(the)j(interpreter)-5 b(.)0 3617 y(The)24 b(module)f(uses)i(traceback)f(objects)g(\227)h(this)g(is) h(the)e(object)g(type)g(that)h(is)g(stored)f(in)h(the)f(v)n(ariables)g FJ(sys.exc_traceback)0 3717 y FN(\(deprecated\))18 b(and)h FJ(sys.last_traceback)f FN(and)h(returned)g(as)i(the)f(third)f(item)i (from)e FJ(sys.exc_info\(\))p FN(.)0 3863 y(The)h(module)f(de\002nes)h (the)g(follo)n(wing)e(functions:)0 4010 y FD(print_tb)p FJ(\()p FK(tr)o(acebac)n(k)q FC([)p FK(,)f(limit)q FC([)p FK(,)22 b(\002le)12 b FC(])g(])p FJ(\))208 4110 y FN(Print)25 b(up)f(to)h FK(limit)j FN(stack)d(trace)g(entries)g(from)f FK(tr)o(acebac)n(k)q FN(.)39 b(If)25 b FK(limit)i FN(is)f(omitted)e(or) h FJ(None)p FN(,)h(all)g(entries)e(are)h(printed.)39 b(If)25 b FK(\002le)208 4210 y FN(is)e(omitted)e(or)h FJ(None)p FN(,)g(the)h(output)d(goes)i(to)h FJ(sys.stderr)p FN(;)f(otherwise)f(it)i(should)e(be)i(an)f(open)f(\002le)i(or)f (\002le-lik)o(e)g(object)f(to)208 4309 y(recei)n(v)o(e)e(the)h(output.) 0 4456 y FD(print_exception)p FJ(\()p FK(type)o(,)d(value)o(,)j(tr)o (acebac)n(k)q FC([)p FK(,)f(limit)q FC([)p FK(,)i(\002le)12 b FC(])g(])p FJ(\))208 4556 y FN(Print)k(e)o(xception)f(information)f (and)h(up)i(to)f FK(limit)j FN(stack)d(trace)h(entries)f(from)g FK(tr)o(acebac)n(k)g FN(to)h FK(\002le)p FN(.)24 b(This)16 b(dif)n(fers)g(from)f FJ(print_-)208 4655 y(tb\(\))21 b FN(in)h(the)g(follo)n(wing)e(w)o(ays:)29 b(\(1\))21 b(if)h FK(tr)o(acebac)n(k)g FN(is)h(not)e FJ(None)p FN(,)h(it)g(prints) g(a)g(header)e(`)p FJ(Traceback)48 b(\(most)h(recent)208 4755 y(call)g(last\):)p FN(';)23 b(\(2\))g(it)g(prints)g(the)g(e)o (xception)e FK(type)i FN(and)f FK(value)h FN(after)f(the)h(stack)g (trace;)i(\(3\))d(if)h FK(type)g FN(is)h FJ(SyntaxError)208 4855 y FN(and)f FK(value)h FN(has)h(the)f(appropriate)e(format,)i(it)h (prints)f(the)g(line)g(where)g(the)g(syntax)g(error)f(occurred)g(with)h (a)h(caret)f(indicating)208 4954 y(the)c(approximate)e(position)h(of)h (the)g(error)-5 b(.)0 5101 y FD(print_exc)p FJ(\()p FC([)p FK(limit)q FC([)p FK(,)19 b(\002le)12 b FC(])g(])p FJ(\))208 5201 y FN(This)67 b(is)h(a)f(shorthand)f(for)g FJ (print_exception\(sys.exc_type,)44 b(sys.exc_value,)k(sys.exc_-)208 5300 y(traceback,)g FK(limit)q FJ(,)i FK(\002le)p FJ(\))p FN(.)25 b(\(In)19 b(f)o(act,)i(it)g(uses)g FJ(sys.exc_info\(\))d FN(to)i(retrie)n(v)o(e)f(the)h(same)h(information)d(in)i(a)h(thread-) 208 5400 y(safe)f(w)o(ay)g(instead)g(of)g(using)g(the)g(deprecated)e(v) n(ariables.\))p 0 5549 3901 4 v 0 5649 a FI(840)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 841 853 TeXDict begin 841 852 bop 0 83 a FD(format_exc)p FJ(\()p FC([)p FK(limit)13 b FC(])p FJ(\))208 183 y FN(This)20 b(is)h(lik)o(e)g FJ(print_exc\()p FK(limit)q FJ(\))e FN(b)n(ut)h(returns)f(a)i(string)f(instead)g(of)g(printing)f(to)h(a)g (\002le.)52 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.4.)0 330 y FD(print_last)p FJ(\()p FC([)p FK(limit)q FC([)p FK(,)h(\002le)12 b FC(])g(])p FJ(\))208 429 y FN(This)37 b(is)h(a)g(shorthand)d(for)i FJ(print_exception\(sys.last_type,)44 b(sys.last_value,)j(sys.last_-) 208 529 y(traceback,)h FK(limit)q FJ(,)i FK(\002le)p FJ(\))p FN(.)0 676 y FD(print_stack)p FJ(\()p FC([)p FK(f)12 b FC([)p FK(,)18 b(limit)q FC([)p FK(,)j(\002le)12 b FC(])g(])g(])p FJ(\))208 775 y FN(This)23 b(function)e(prints)h(a)i (stack)f(trace)g(from)e(its)j(in)m(v)n(ocation)d(point.)33 b(The)22 b(optional)g FK(f)36 b FN(ar)o(gument)20 b(can)j(be)g(used)f (to)h(specify)g(an)208 875 y(alternate)i(stack)h(frame)f(to)h(start.)43 b(The)25 b(optional)g FK(limit)j FN(and)e FK(\002le)g FN(ar)o(guments)e(ha)n(v)o(e)h(the)h(same)g(meaning)e(as)j(for)e FJ(print_-)208 975 y(exception\(\))p FN(.)0 1121 y FD(extract_tb)p FJ(\()p FK(tr)o(acebac)n(k)q FC([)p FK(,)17 b(limit)c FC(])p FJ(\))208 1221 y FN(Return)26 b(a)h(list)h(of)e(up)g(to)h FK(limit)i FN(\223pre-processed\224)24 b(stack)j(trace)g(entries)f(e)o (xtracted)g(from)f(the)i(traceback)e(object)h FK(tr)o(acebac)n(k)q FN(.)208 1321 y(It)i(is)i(useful)e(for)g(alternate)g(formatting)f(of)h (stack)h(traces.)50 b(If)28 b FK(limit)j FN(is)f(omitted)e(or)g FJ(None)p FN(,)i(all)f(entries)g(are)f(e)o(xtracted.)49 b(A)208 1420 y(\223pre-processed\224)22 b(stack)k(trace)f(entry)g(is)h (a)g(quadruple)d(\()p FK(\002lename)p FN(,)i FK(line)h(number)r FN(,)g FK(function)e(name)p FN(,)i FK(te)n(xt)q FN(\))g(representing)e (the)208 1520 y(information)g(that)j(is)g(usually)f(printed)g(for)g(a)h (stack)g(trace.)44 b(The)26 b FK(te)n(xt)j FN(is)f(a)f(string)f(with)h (leading)f(and)g(trailing)g(whitespace)208 1620 y(stripped;)19 b(if)h(the)h(source)e(is)i(not)f(a)n(v)n(ailable)g(it)h(is)g FJ(None)p FN(.)0 1766 y FD(extract_stack)p FJ(\()p FC([)p FK(f)12 b FC([)p FK(,)18 b(limit)13 b FC(])f(])p FJ(\))208 1866 y FN(Extract)j(the)h(ra)o(w)f(traceback)g(from)g(the)g(current)g (stack)h(frame.)23 b(The)15 b(return)g(v)n(alue)g(has)h(the)g(same)g (format)f(as)h(for)g FJ(extract_-)208 1966 y(tb\(\))p FN(.)24 b(The)c(optional)f FK(f)33 b FN(and)20 b FK(limit)i FN(ar)o(guments)c(ha)n(v)o(e)i(the)g(same)g(meaning)f(as)i(for)f FJ(print_stack\(\))p FN(.)0 2113 y FD(format_list)p FJ(\()p FK(list)q FJ(\))208 2212 y FN(Gi)n(v)o(en)k(a)h(list)h(of)f(tuples)g (as)h(returned)d(by)i FJ(extract_tb\(\))e FN(or)i FJ(extract_stack\(\)) p FN(,)f(return)g(a)i(list)g(of)f(strings)g(ready)208 2312 y(for)e(printing.)35 b(Each)24 b(string)f(in)i(the)f(resulting)f (list)i(corresponds)d(to)i(the)g(item)g(with)h(the)f(same)g(inde)o(x)f (in)h(the)g(ar)o(gument)e(list.)208 2411 y(Each)g(string)h(ends)g(in)g (a)h(ne)n(wline;)g(the)f(strings)g(may)g(contain)f(internal)g(ne)n (wlines)h(as)h(well,)g(for)f(those)g(items)g(whose)g(source)208 2511 y(te)o(xt)d(line)g(is)h(not)f FJ(None)p FN(.)0 2658 y FD(format_exception_only)p FJ(\()p FK(type)o(,)c(value)p FJ(\))208 2758 y FN(F)o(ormat)27 b(the)h(e)o(xception)e(part)h(of)h(a)g (traceback.)47 b(The)27 b(ar)o(guments)f(are)i(the)g(e)o(xception)e (type)h(and)h(v)n(alue)f(such)h(as)g(gi)n(v)o(en)f(by)208 2857 y FJ(sys.last_type)e FN(and)h FJ(sys.last_value)p FN(.)44 b(The)27 b(return)f(v)n(alue)g(is)i(a)g(list)g(of)f(strings,)h (each)f(ending)f(in)h(a)g(ne)n(wline.)208 2957 y(Normally)-5 b(,)27 b(the)h(list)g(contains)f(a)h(single)g(string;)j(ho)n(we)n(v)o (er)m(,)c(for)f FJ(SyntaxError)h FN(e)o(xceptions,)g(it)h(contains)f (se)n(v)o(eral)g(lines)208 3056 y(that)19 b(\(when)f(printed\))g (display)g(detailed)h(information)e(about)h(where)h(the)g(syntax)f (error)g(occurred.)23 b(The)c(message)g(indicating)208 3156 y(which)g(e)o(xception)g(occurred)f(is)j(the)f(al)o(w)o(ays)h (last)g(string)f(in)g(the)g(list.)0 3303 y FD(format_exception)p FJ(\()p FK(type)o(,)d(value)o(,)i(tb)p FC([)p FK(,)h(limit)13 b FC(])p FJ(\))208 3403 y FN(F)o(ormat)j(a)j(stack)e(trace)h(and)f(the) h(e)o(xception)e(information.)21 b(The)d(ar)o(guments)d(ha)n(v)o(e)i (the)h(same)g(meaning)e(as)i(the)g(corresponding)208 3502 y(ar)o(guments)g(to)j FJ(print_exception\(\))p FN(.)k(The)20 b(return)g(v)n(alue)g(is)i(a)f(list)h(of)e(strings,)h(each)g(ending)e (in)i(a)g(ne)n(wline)f(and)h(some)208 3602 y(containing)d(internal)i (ne)n(wlines.)26 b(When)20 b(these)h(lines)g(are)g(concatenated)d(and)i (printed,)f(e)o(xactly)h(the)h(same)f(te)o(xt)h(is)g(printed)f(as)208 3701 y(does)f FJ(print_exception\(\))p FN(.)0 3848 y FD(format_tb)p FJ(\()p FK(tb)p FC([)p FK(,)f(limit)13 b FC(])p FJ(\))208 3948 y FN(A)20 b(shorthand)e(for)i FJ(format_list\(extract_tb\()p FK(tb)p FJ(,)45 b FK(limit)q FJ(\)\))p FN(.)0 4095 y FD(format_stack)p FJ(\()p FC([)p FK(f)12 b FC([)p FK(,)18 b(limit)13 b FC(])f(])p FJ(\))208 4194 y FN(A)20 b(shorthand)e(for)i FJ(format_list\(extract_stack\()p FK(f)12 b FJ(,)45 b FK(limit)q FJ(\)\))p FN(.)0 4341 y FD(tb_lineno)p FJ(\()p FK(tb)p FJ(\))208 4441 y FN(This)23 b(function)e(returns)h(the)h(current)e(line)i(number)e(set)j(in)f(the)g (traceback)e(object.)32 b(This)23 b(function)e(w)o(as)j(necessary)e (because)208 4541 y(in)f(v)o(ersions)f(of)g(Python)g(prior)g(to)h(2.3)g (when)f(the)h FL(-O)g FN(\003ag)g(w)o(as)h(passed)e(to)i(Python)d(the)i FK(tb)p FJ(.tb_lineno)f FN(w)o(as)i(not)e(updated)208 4640 y(correctly)-5 b(.)23 b(This)d(function)f(has)h(no)g(use)g(in)h(v) o(ersions)e(past)h(2.3.)0 4925 y Fv(26.7.1)101 b(T)-12 b(r)o(acebac)n(k)28 b(Example)0 5128 y FN(This)g(simple)g(e)o(xample)e (implements)h(a)h(basic)g(read-e)n(v)n(al-print)c(loop,)29 b(similar)f(to)g(\(b)n(ut)f(less)i(useful)e(than\))g(the)h(standard)f (Python)0 5228 y(interacti)n(v)o(e)19 b(interpreter)f(loop.)25 b(F)o(or)19 b(a)i(more)e(complete)g(implementation)f(of)i(the)h (interpreter)d(loop,)h(refer)h(to)g(the)g FJ(code)g FN(module.)p 0 5549 3901 4 v 0 5649 a FI(26.7.)52 b FJ(traceback)22 b FI(\227)h(Pr)q(int)h(or)f(retr)q(ie)n(v)n(e)f(a)h(stac)n(k)g(tr)o (acebac)n(k)1717 b(841)p eop end %%Page: 842 854 TeXDict begin 842 853 bop 236 174 a FA(import)44 b(sys,)g(traceback)236 357 y(def)h(run_user_code\(envdir\):)416 448 y(source)e(=)i (raw_input\(">>>)e("\))416 540 y(try:)595 631 y(exec)h(source)g(in)g (envdir)416 722 y(except:)595 814 y(print)g("Exception)f(in)i(user)f (code:")595 905 y(print)g('-')999 918 y(*)1044 905 y(60)595 996 y(traceback.print_exc\(file=sys.stdout\))595 1088 y(print)g('-')999 1101 y(*)1044 1088 y(60)236 1270 y(envdir)g(=)h({}) 236 1362 y(while)f(1:)416 1453 y(run_user_code\(envdir\))0 1957 y FE(26.8)121 b Fx(__future__)31 b FE(\227)i(Future)h(statement)h (de\002nitions)0 2190 y FJ(__future__)19 b FN(is)i(a)g(real)f(module,)e (and)i(serv)o(es)g(three)g(purposes:)125 2385 y FM(\017)41 b FN(T)-7 b(o)20 b(a)n(v)n(oid)g(confusing)e(e)o(xisting)i(tools)g (that)h(analyze)e(import)h(statements)g(and)g(e)o(xpect)f(to)i(\002nd)f (the)g(modules)f(the)o(y')l(re)g(import-)208 2485 y(ing.)125 2637 y FM(\017)41 b FN(T)-7 b(o)22 b(ensure)f(that)h(future)p 907 2637 25 4 v 28 w(statements)h(run)e(under)g(releases)h(prior)f(to)h (2.1)g(at)g(least)h(yield)f(runtime)f(e)o(xceptions)f(\(the)i(import)f (of)208 2737 y FJ(__future__)d FN(will)j(f)o(ail,)g(because)e(there)h (w)o(as)h(no)f(module)f(of)g(that)i(name)e(prior)h(to)g(2.1\).)125 2889 y FM(\017)41 b FN(T)-7 b(o)22 b(document)e(when)i(incompatible)e (changes)h(were)h(introduced,)e(and)i(when)f(the)o(y)h(will)h(be)f (\227)h(or)f(were)g(\227)g(made)g(manda-)208 2989 y(tory)-5 b(.)51 b(This)30 b(is)g(a)g(form)e(of)h(e)o(x)o(ecutable)f (documentation,)g(and)h(can)g(be)h(inspected)e(programatically)f(via)i (importing)f FJ(__-)208 3089 y(future__)19 b FN(and)g(e)o(xamining)f (its)k(contents.)0 3284 y(Each)e(statement)g(in)g(`)p 643 3284 23 4 v 670 3284 V 53 w FO(future)p 889 3284 V 915 3284 V 52 w(.p)n(y)p FN(')g(is)h(of)f(the)g(form:)236 3431 y FA(FeatureName)43 b(=)i("_Feature\(")e FK(OptionalRelease)k FJ(",")i FK(MandatoryRelease)e FJ(",")1432 3531 y FK(CompilerFla)o(g)h FJ("\)")0 3826 y FN(where,)d(normally)-5 b(,)43 b FK(OptionalRelease)38 b FN(is)j(less)h(than)e FK(MandatoryRelease)p FN(,)i(and)e(both)g(are)g (5-tuples)g(of)g(the)g(same)h(form)e(as)0 3925 y FJ(sys.version_info)p FN(:)416 4164 y FA(\(PY_MAJOR_VERSION,)i(#)k(the)f(2)h(in)g(2.1.0a3;)e (an)h(int)460 4255 y(PY_MINOR_VERSION,)e(#)j(the)f(1;)h(an)f(int)460 4346 y(PY_MICRO_VERSION,)e(#)j(the)f(0;)h(an)f(int)460 4438 y(PY_RELEASE_LEVEL,)e(#)j("alpha",)f("beta",)f("candidate")g(or)i ("final";)e(string)460 4529 y(PY_RELEASE_SERIAL)f(#)j(the)f(3;)h(an)f (int)416 4620 y(\))0 4907 y FK(OptionalRelease)18 b FN(records)h(the)h (\002rst)h(release)g(in)f(which)g(the)g(feature)f(w)o(as)i(accepted.)0 5054 y(In)29 b(the)g(case)h(of)f(a)g FK(MandatoryRelease)e FN(that)j(has)f(not)g(yet)g(occurred,)g FK(MandatoryRelease)e FN(predicts)i(the)g(release)g(in)h(which)f(the)0 5154 y(feature)19 b(will)i(become)e(part)h(of)g(the)g(language.)0 5300 y(Else)h FK(MandatoryRelease)d FN(records)i(when)g(the)g(feature)g (became)f(part)h(of)h(the)f(language;)f(in)i(releases)g(at)g(or)f (after)g(that,)h(modules)e(no)0 5400 y(longer)g(need)g(a)i(future)e (statement)h(to)g(use)h(the)f(feature)f(in)i(question,)d(b)n(ut)j(may)e (continue)g(to)h(use)h(such)f(imports.)p 0 5549 3901 4 v 0 5649 a FI(842)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 843 855 TeXDict begin 843 854 bop 0 83 a FK(MandatoryRelease)18 b FN(may)i(also)g(be)g FJ(None)p FN(,)g(meaning)f(that)h(a)h(planned)d (feature)h(got)h(dropped.)0 230 y(Instances)85 b(of)g(class)i FJ(_Feature)d FN(ha)n(v)o(e)h(tw)o(o)h(corresponding)c(methods,)101 b FJ(getOptionalRelease\(\))82 b FN(and)0 330 y FJ (getMandatoryRelease\(\))p FN(.)0 476 y FK(CompilerFla)o(g)19 b FN(is)h(the)g(\(bit\002eld\))e(\003ag)i(that)f(should)g(be)g(passed)h (in)f(the)h(fourth)e(ar)o(gument)f(to)j(the)f(b)n(uiltin)g(function)f FJ(compile\(\))g FN(to)0 576 y(enable)e(the)h(feature)g(in)g (dynamically)e(compiled)g(code.)24 b(This)17 b(\003ag)g(is)h(stored)f (in)g(the)g FJ(compiler_flag)e FN(attrib)n(ute)i(on)f FJ(_Feature)0 676 y FN(instances.)0 823 y(No)k(feature)f(description)g (will)i(e)n(v)o(er)e(be)i(deleted)e(from)g FJ(__future__)p FN(.)0 1147 y FE(26.9)121 b Fx(gc)33 b FE(\227)g(Garbage)i(Collector)f (interf)l(ace)0 1380 y FN(This)18 b(module)f(pro)o(vides)f(an)i(interf) o(ace)f(to)i(the)f(optional)f(garbage)f(collector)-5 b(.)23 b(It)c(pro)o(vides)d(the)i(ability)g(to)g(disable)g(the)g (collector)m(,)f(tune)0 1480 y(the)24 b(collection)e(frequenc)o(y)-5 b(,)21 b(and)j(set)g(deb)n(ugging)d(options.)34 b(It)24 b(also)g(pro)o(vides)e(access)j(to)e(unreachable)f(objects)h(that)h (the)g(collector)0 1579 y(found)18 b(b)n(ut)h(cannot)g(free.)24 b(Since)19 b(the)h(collector)e(supplements)h(the)g(reference)f (counting)f(already)i(used)g(in)h(Python,)e(you)h(can)g(disable)0 1679 y(the)k(collector)f(if)i(you)e(are)h(sure)g(your)f(program)e(does) j(not)g(create)g(reference)e(c)o(ycles.)34 b(Automatic)22 b(collection)g(can)h(be)g(disabled)f(by)0 1779 y(calling)f FJ(gc.disable\(\))p FN(.)29 b(T)-7 b(o)22 b(deb)n(ug)e(a)i(leaking)f (program)f(call)i FJ(gc.set_debug\(gc.DEBUG_LEAK\))p FN(.)17 b(Notice)22 b(that)g(this)0 1878 y(includes)d FJ(gc.DEBUG_SAVEALL)p FN(,)f(causing)h(garbage-collected)e(objects)j (to)g(be)g(sa)n(v)o(ed)g(in)g(gc.garbage)e(for)h(inspection.)0 2025 y(The)h FJ(gc)g FN(module)f(pro)o(vides)f(the)j(follo)n(wing)d (functions:)0 2172 y FD(enable)p FJ(\(\))208 2272 y FN(Enable)h (automatic)g(garbage)f(collection.)0 2418 y FD(disable)p FJ(\(\))208 2518 y FN(Disable)i(automatic)f(garbage)f(collection.)0 2665 y FD(isenabled)p FJ(\(\))208 2765 y FN(Returns)i(true)f(if)i (automatic)e(collection)g(is)i(enabled.)0 2911 y FD(collect)p FJ(\()p FC([)p FK(g)o(ener)o(ation)12 b FC(])p FJ(\))208 3011 y FN(W)m(ith)19 b(no)g(ar)o(guments,)e(run)h(a)i(full)f (collection.)24 b(The)18 b(optional)g(ar)o(gument)f FK(g)o(ener)o (ation)g FN(may)i(be)g(an)g(inte)o(ger)f(specifying)g(which)208 3111 y(generation)h(to)j(collect)g(\(from)e(0)i(to)g(2\).)30 b(A)22 b FJ(ValueError)f FN(is)h(raised)g(if)g(the)g(generation)e (number)g(is)i(in)m(v)n(alid.)29 b(The)21 b(number)208 3210 y(of)e(unreachable)f(objects)i(found)f(is)i(returned.)208 3340 y(Changed)d(in)j(v)o(ersion)e(2.5:)g(The)h(optional)f FK(g)o(ener)o(ation)f FN(ar)o(gument)g(w)o(as)j(added.)0 3487 y FD(set_debug)p FJ(\()p FK(\003a)o(gs)p FJ(\))208 3587 y FN(Set)c(the)h(garbage)d(collection)h(deb)n(ugging)e(\003ags.)25 b(Deb)n(ugging)15 b(information)g(will)j(be)f(written)g(to)g FJ(sys.stderr)p FN(.)23 b(See)17 b(belo)n(w)208 3686 y(for)i(a)i(list)g(of)f(deb)n(ugging)e(\003ags)i(which)g(can)g(be)g (combined)e(using)i(bit)g(operations)f(to)h(control)f(deb)n(ugging.)0 3833 y FD(get_debug)p FJ(\(\))208 3933 y FN(Return)g(the)i(deb)n (ugging)c(\003ags)k(currently)d(set.)0 4080 y FD(get_objects)p FJ(\(\))208 4179 y FN(Returns)i(a)g(list)h(of)f(all)h(objects)f(track)o (ed)f(by)h(the)g(collector)m(,)f(e)o(xcluding)f(the)i(list)h(returned.) 49 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.2.)0 4326 y FD(set_threshold)p FJ(\()p FK(thr)m(eshold0)p FC([)p FK(,)d(thr)m(eshold1)p FC([)p FK(,)i(thr)m(eshold2)12 b FC(])g(])p FJ(\))208 4426 y FN(Set)20 b(the)h(garbage)d(collection)h(thresholds)g(\(the)h (collection)f(frequenc)o(y\).)j(Setting)e FK(thr)m(eshold0)f FN(to)h(zero)g(disables)g(collection.)208 4556 y(The)g(GC)h (classi\002es)h(objects)e(into)g(three)h(generations)d(depending)g(on)i (ho)n(w)g(man)o(y)g(collection)f(sweeps)i(the)o(y)f(ha)n(v)o(e)g(survi) n(v)o(ed.)208 4655 y(Ne)n(w)h(objects)f(are)h(placed)f(in)h(the)g (youngest)f(generation)e(\(generation)h FJ(0)p FN(\).)27 b(If)21 b(an)g(object)f(survi)n(v)o(es)g(a)h(collection)f(it)i(is)g(mo) o(v)o(ed)208 4755 y(into)k(the)h(ne)o(xt)g(older)f(generation.)43 b(Since)27 b(generation)e FJ(2)j FN(is)g(the)f(oldest)g(generation,)f (objects)h(in)g(that)g(generation)e(remain)208 4855 y(there)17 b(after)g(a)h(collection.)23 b(In)18 b(order)e(to)i(decide)f(when)g(to) h(run,)g(the)f(collector)g(k)o(eeps)h(track)f(of)g(the)h(number)e (object)h(allocations)208 4954 y(and)k(deallocations)g(since)i(the)f (last)h(collection.)30 b(When)22 b(the)g(number)f(of)h(allocations)f (minus)h(the)g(number)f(of)h(deallocations)208 5054 y(e)o(xceeds)16 b FK(thr)m(eshold0)p FN(,)g(collection)g(starts.)25 b(Initially)17 b(only)f(generation)g FJ(0)h FN(is)h(e)o(xamined.)k(If)c(generation)d FJ(0)i FN(has)h(been)e(e)o(xamined)208 5154 y(more)30 b(than)h FK(thr)m(eshold1)f FN(times)i(since)f(generation)f FJ(1)h FN(has)h(been)f(e)o(xamined,)h(then)e(generation)g FJ(1)h FN(is)i(e)o(xamined)c(as)j(well.)208 5253 y(Similarly)-5 b(,)19 b FK(thr)m(eshold2)g FN(controls)g(the)h(number)e(of)i (collections)g(of)g(generation)e FJ(1)j FN(before)d(collecting)h (generation)g FJ(2)p FN(.)0 5400 y FD(get_count)p FJ(\(\))p 0 5549 3901 4 v 0 5649 a FI(26.9.)52 b FJ(gc)23 b FI(\227)g(Garbage)g (Collector)h(interf)n(ace)2284 b(843)p eop end %%Page: 844 856 TeXDict begin 844 855 bop 208 83 a FN(Return)19 b(the)i(current)d (collection)i(counts)f(as)i(a)g(tuple)e(of)h FJ(\()p FK(count0)p FJ(,)48 b FK(count1)p FJ(,)f FK(count2)p FJ(\))p FN(.)i(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 230 y FD(get_threshold)p FJ(\(\))208 330 y FN(Return)g(the)i(current)d (collection)i(thresholds)f(as)i(a)f(tuple)g(of)g FJ(\()p FK(thr)m(eshold0)p FJ(,)47 b FK(thr)m(eshold1)p FJ(,)h FK(thr)m(eshold2)p FJ(\))p FN(.)0 476 y FD(get_referrers)p FJ(\()p FK(*objs)p FJ(\))208 576 y FN(Return)19 b(the)h(list)h(of)f (objects)f(that)h(directly)f(refer)g(to)h(an)o(y)g(of)f(objs.)25 b(This)20 b(function)e(will)j(only)e(locate)h(those)f(containers)g (which)208 676 y(support)d(garbage)f(collection;)j(e)o(xtension)e (types)i(which)f(do)g(refer)g(to)h(other)f(objects)g(b)n(ut)h(do)f(not) h(support)e(garbage)g(collection)208 775 y(will)k(not)g(be)g(found.)208 908 y(Note)d(that)h(objects)f(which)g(ha)n(v)o(e)g(already)g(been)f (dereferenced,)g(b)n(ut)h(which)g(li)n(v)o(e)g(in)h(c)o(ycles)g(and)f (ha)n(v)o(e)g(not)g(yet)g(been)g(collected)208 1008 y(by)28 b(the)h(garbage)f(collector)g(can)h(be)g(listed)g(among)f(the)h (resulting)g(referrers.)50 b(T)-7 b(o)29 b(get)h(only)e(currently)f(li) n(v)o(e)i(objects,)i(call)208 1107 y FJ(collect\(\))19 b FN(before)f(calling)i FJ(get_referrers\(\))p FN(.)208 1240 y(Care)h(must)h(be)g(tak)o(en)f(when)g(using)g(objects)g(returned) f(by)h FJ(get_referrers\(\))e FN(because)i(some)h(of)f(them)g(could)g (still)i(be)208 1340 y(under)18 b(construction)f(and)i(hence)g(in)h(a)g (temporarily)d(in)m(v)n(alid)i(state.)25 b(A)-6 b(v)n(oid)19 b(using)g FJ(get_referrers\(\))e FN(for)i(an)o(y)g(purpose)208 1439 y(other)g(than)h(deb)n(ugging.)208 1572 y(Ne)n(w)g(in)g(v)o (ersion)f(2.2.)0 1719 y FD(get_referents)p FJ(\()p FK(*objs)p FJ(\))208 1819 y FN(Return)25 b(a)i(list)g(of)f(objects)g(directly)f (referred)f(to)j(by)f(an)o(y)f(of)h(the)g(ar)o(guments.)41 b(The)25 b(referents)g(returned)g(are)h(those)g(objects)208 1918 y(visited)19 b(by)g(the)g(ar)o(guments')e(C-le)n(v)o(el)h FJ(tp_traverse)g FN(methods)g(\(if)h(an)o(y\),)g(and)f(may)h(not)g(be)g (all)h(objects)f(actually)f(directly)208 2018 y(reachable.)23 b FJ(tp_traverse)17 b FN(methods)h(are)g(supported)f(only)h(by)g (objects)h(that)g(support)e(garbage)g(collection,)g(and)i(are)f(only) 208 2118 y(required)f(to)i(visit)g(objects)f(that)h(may)g(be)f(in)m(v)n (olv)o(ed)f(in)i(a)g(c)o(ycle.)24 b(So,)19 b(for)g(e)o(xample,)e(if)i (an)g(inte)o(ger)e(is)j(directly)e(reachable)g(from)208 2217 y(an)i(ar)o(gument,)d(that)k(inte)o(ger)e(object)g(may)h(or)g(may) g(not)f(appear)g(in)i(the)f(result)g(list.)208 2350 y(Ne)n(w)g(in)g(v)o (ersion)f(2.3.)0 2497 y(The)h(follo)n(wing)e(v)n(ariable)h(is)j(pro)o (vided)17 b(for)j(read-only)e(access)j(\(you)d(can)i(mutate)g(its)h(v)n (alue)f(b)n(ut)g(should)f(not)h(rebind)f(it\):)0 2644 y FD(garbage)208 2743 y FN(A)i(list)i(of)e(objects)g(which)f(the)h (collector)g(found)e(to)j(be)f(unreachable)e(b)n(ut)i(could)f(not)h(be) g(freed)g(\(uncollectable)e(objects\).)27 b(By)208 2843 y(def)o(ault,)16 b(this)h(list)h(contains)e(only)f(objects)i(with)f FJ(__del__\(\))g FN(methods.)2377 2813 y FF(1)2433 2843 y FN(Objects)g(that)h(ha)n(v)o(e)f FJ(__del__\(\))g FN(methods)f(and) 208 2943 y(are)h(part)g(of)f(a)i(reference)e(c)o(ycle)g(cause)h(the)h (entire)e(reference)g(c)o(ycle)h(to)g(be)g(uncollectable,)f(including)f (objects)i(not)g(necessarily)208 3042 y(in)21 b(the)h(c)o(ycle)f(b)n (ut)h(reachable)e(only)g(from)h(it.)30 b(Python)20 b(doesn')o(t)g (collect)i(such)f(c)o(ycles)g(automatically)g(because,)g(in)g(general,) g(it)208 3142 y(isn')o(t)j(possible)g(for)h(Python)e(to)i(guess)g(a)g (safe)g(order)e(in)i(which)f(to)h(run)f(the)h FJ(__del__\(\))f FN(methods.)37 b(If)25 b(you)e(kno)n(w)h(a)h(safe)208 3242 y(order)m(,)19 b(you)h(can)h(force)f(the)h(issue)h(by)f(e)o (xamining)e(the)i FK(garba)o(g)o(e)e FN(list,)k(and)d(e)o(xplicitly)g (breaking)f(c)o(ycles)i(due)g(to)g(your)f(objects)208 3341 y(within)d(the)g(list.)26 b(Note)17 b(that)h(these)f(objects)h (are)f(k)o(ept)g(ali)n(v)o(e)g(e)n(v)o(en)g(so)h(by)f(virtue)g(of)g (being)g(in)g(the)h FK(garba)o(g)o(e)e FN(list,)j(so)f(the)o(y)f (should)208 3441 y(be)24 b(remo)o(v)o(ed)e(from)h FK(garba)o(g)o(e)g FN(too.)38 b(F)o(or)24 b(e)o(xample,)g(after)g(breaking)e(c)o(ycles,)j (do)f FJ(del)50 b(gc.garbage[:])31 b FN(to)25 b(empty)f(the)208 3540 y(list.)h(It')-5 b(s)19 b(generally)d(better)i(to)h(a)n(v)n(oid)e (the)i(issue)f(by)g(not)g(creating)f(c)o(ycles)h(containing)f(objects)g (with)i FJ(__del__\(\))e FN(methods,)208 3640 y(and)i FK(garba)o(g)o(e)g FN(can)h(be)g(e)o(xamined)e(in)j(that)f(case)h(to)f (v)o(erify)f(that)h(no)g(such)g(c)o(ycles)g(are)g(being)f(created.)208 3773 y(If)h FJ(DEBUG_SAVEALL)e FN(is)j(set,)g(then)f(all)g(unreachable) e(objects)i(will)h(be)f(added)f(to)i(this)f(list)i(rather)d(than)h (freed.)0 3920 y(The)g(follo)n(wing)e(constants)i(are)g(pro)o(vided)e (for)h(use)i(with)f FJ(set_debug\(\))p FN(:)0 4067 y FD(DEBUG_STATS)208 4166 y FN(Print)g(statistics)i(during)c(collection.) 24 b(This)c(information)e(can)i(be)g(useful)g(when)f(tuning)g(the)i (collection)e(frequenc)o(y)-5 b(.)0 4313 y FD(DEBUG_COLLECTABLE)208 4413 y FN(Print)20 b(information)e(on)h(collectable)h(objects)g(found.) 0 4560 y FD(DEBUG_UNCOLLECTABLE)208 4659 y FN(Print)27 b(information)e(of)i(uncollectable)f(objects)h(found)f(\(objects)h (which)f(are)i(not)f(reachable)f(b)n(ut)h(cannot)g(be)g(freed)g(by)g (the)208 4759 y(collector\).)c(These)d(objects)g(will)h(be)f(added)f (to)i(the)f FJ(garbage)f FN(list.)0 4906 y FD(DEBUG_INSTANCES)208 5005 y FN(When)i FJ(DEBUG_COLLECTABLE)e FN(or)j FJ(DEBUG_UNCOLLECTABLE) c FN(is)23 b(set,)f(print)g(information)d(about)h(instance)i(objects) 208 5105 y(found.)p 0 5159 1560 4 v 90 5215 a FB(1)120 5238 y FH(Prior)17 b(to)g(Python)h(2.2,)e(the)i(list)g(contained)i(all) e(instance)h(objects)g(in)e(unreachable)k(c)o(ycles,)d(not)f(only)h (those)g(with)f Fz(__del__\(\))f FH(methods.)p 0 5549 3901 4 v 0 5649 a FI(844)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 845 857 TeXDict begin 845 856 bop 0 83 a FD(DEBUG_OBJECTS)208 183 y FN(When)15 b FJ(DEBUG_COLLECTABLE)e FN(or)j FJ (DEBUG_UNCOLLECTABLE)d FN(is)k(set,)g(print)e(information)f(about)g (objects)i(other)f(than)208 282 y(instance)k(objects)h(found.)0 429 y FD(DEBUG_SAVEALL)208 529 y FN(When)e(set,)h(all)g(unreachable)d (objects)i(found)e(will)j(be)g(appended)d(to)i FK(garba)o(g)o(e)f FN(rather)h(than)f(being)h(freed.)23 b(This)c(can)f(be)g(useful)208 628 y(for)h(deb)n(ugging)f(a)i(leaking)g(program.)0 775 y FD(DEBUG_LEAK)208 875 y FN(The)67 b(deb)n(ugging)e(\003ags)j (necessary)f(for)g(the)g(collector)g(to)g(print)g(information)f(about)g (a)i(leaking)f(program)208 975 y(\(equal)39 b(to)j FJ (DEBUG_COLLECTABLE)k(|)k(DEBUG_UNCOLLECTABLE)c(|)k(DEBUG_INSTANCES)d(|) i(DEBUG_-)208 1074 y(OBJECTS)f(|)i(DEBUG_SAVEALL)p FN(\).)0 1402 y FE(26.10)122 b Fx(inspect)31 b FE(\227)i(Inspect)h(liv)m(e)f (objects)0 1634 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.1.)0 1781 y(The)k FJ(inspect)f FN(module)g(pro)o(vides)f(se)n(v)o(eral)i (useful)g(functions)e(to)j(help)e(get)h(information)e(about)h(li)n(v)o (e)h(objects)g(such)g(as)h(modules,)0 1881 y(classes,)k(methods,)d (functions,)g(tracebacks,)g(frame)g(objects,)h(and)f(code)g(objects.)40 b(F)o(or)25 b(e)o(xample,)g(it)h(can)f(help)g(you)g(e)o(xamine)f(the)0 1981 y(contents)c(of)g(a)i(class,)f(retrie)n(v)o(e)f(the)g(source)g (code)g(of)h(a)g(method,)e(e)o(xtract)h(and)g(format)g(the)h(ar)o (gument)d(list)k(for)e(a)h(function,)e(or)h(get)h(all)0 2080 y(the)f(information)e(you)h(need)h(to)g(display)g(a)g(detailed)g (traceback.)0 2227 y(There)f(are)h(four)f(main)h(kinds)f(of)h(services) g(pro)o(vided)d(by)j(this)h(module:)i(type)d(checking,)e(getting)h (source)g(code,)h(inspecting)e(classes)0 2327 y(and)i(functions,)e(and) i(e)o(xamining)e(the)i(interpreter)f(stack.)0 2612 y Fv(26.10.1)101 b(T)-12 b(ypes)28 b(and)h(members)0 2814 y FN(The)c FJ(getmembers\(\))e FN(function)g(retrie)n(v)o(es)h(the)h (members)f(of)g(an)h(object)g(such)f(as)i(a)f(class)h(or)f(module.)38 b(The)24 b(ele)n(v)o(en)g(functions)0 2914 y(whose)17 b(names)g(be)o(gin)f(with)i(\223is\224)g(are)g(mainly)e(pro)o(vided)f (as)j(con)m(v)o(enient)d(choices)i(for)g(the)g(second)g(ar)o(gument)e (to)i FJ(getmembers\(\))p FN(.)0 3014 y(The)o(y)i(also)i(help)e(you)h (determine)e(when)i(you)f(can)h(e)o(xpect)f(to)i(\002nd)f(the)g(follo)n (wing)e(special)j(attrib)n(utes:)p 0 5549 3901 4 v 0 5649 a FI(26.10.)52 b FJ(inspect)22 b FI(\227)h(Inspect)g(liv)n(e)h (objects)2302 b(845)p eop end %%Page: 846 858 TeXDict begin 846 857 bop 404 70 a FL(T)-6 b(ype)p 698 100 4 100 v 171 w(Attrib)n(ute)p 1317 100 V 288 w(Description)p 3319 100 V 1591 w(Notes)p 282 103 3337 4 v 366 173 a FN(module)p 698 203 4 100 v 754 173 25 4 v 784 173 V 192 w(doc)p 935 173 V 964 173 V 1317 203 4 100 v 438 w(documentation)18 b(string)p 3319 203 V 698 302 V 754 272 25 4 v 784 272 V 809 272 a(\002le)p 920 272 V 950 272 V 1317 302 4 100 v 453 w(\002lename)i(\(missing)g(for)f(b)n (uilt-in)h(modules\))p 3319 302 V 282 306 3337 4 v 410 375 a(class)p 698 405 4 100 v 754 375 25 4 v 784 375 V 238 w(doc)p 935 375 V 964 375 V 1317 405 4 100 v 438 w(documentation)e(string)p 3319 405 V 698 505 V 754 475 25 4 v 784 475 V 809 475 a(module)p 1065 475 V 1093 475 V 1317 505 4 100 v 308 w(name)i(of)g(module)f(in)h(which)g(this)g (class)h(w)o(as)g(de\002ned)p 3319 505 V 282 508 3337 4 v 366 578 a(method)p 698 608 4 100 v 754 578 25 4 v 784 578 V 192 w(doc)p 935 578 V 964 578 V 1317 608 4 100 v 438 w(documentation)d(string)p 3319 608 V 698 707 V 754 677 25 4 v 784 677 V 809 677 a(name)p 995 677 V 1024 677 V 1317 707 4 100 v 378 w(name)i(with)g(which)g(this)h(method)d (w)o(as)j(de\002ned)p 3319 707 V 698 807 V 749 777 a(im)p 842 777 25 4 v 30 w(class)p 1317 807 4 100 v 340 w(class)g(object)f (that)g(ask)o(ed)g(for)g(this)h(method)p 3319 807 V 783 w(\(1\))p 698 907 V 749 877 a(im)p 842 877 25 4 v 30 w(func)p 1317 907 4 100 v 352 w(function)e(object)g(containing)g (implementation)f(of)i(method)p 3319 907 V 698 1006 V 749 976 a(im)p 842 976 25 4 v 30 w(self)p 1317 1006 4 100 v 381 w(instance)g(to)g(which)g(this)h(method)e(is)i(bound,)d(or)i FJ(None)p 3319 1006 V 282 1010 3337 4 v 352 1079 a FN(function)p 698 1109 4 100 v 754 1079 25 4 v 784 1079 V 178 w(doc)p 935 1079 V 964 1079 V 1317 1109 4 100 v 438 w(documentation)e(string)p 3319 1109 V 698 1209 V 754 1179 25 4 v 784 1179 V 809 1179 a(name)p 995 1179 V 1024 1179 V 1317 1209 4 100 v 378 w(name)i(with)g(which)g(this)h(function)d(w)o(as)j(de\002ned)p 3319 1209 V 698 1308 V 749 1279 a(func)p 903 1279 25 4 v 29 w(code)p 1317 1308 4 100 v 283 w(code)f(object)f(containing)g (compiled)f(function)h(bytecode)p 3319 1308 V 698 1408 V 749 1378 a(func)p 903 1378 25 4 v 29 w(def)o(aults)p 1317 1408 4 100 v 178 w(tuple)h(of)g(an)o(y)f(def)o(ault)h(v)n(alues)g (for)f(ar)o(guments)p 3319 1408 V 698 1508 V 749 1478 a(func)p 903 1478 25 4 v 29 w(doc)p 1317 1508 4 100 v 320 w(\(same)h(as)p 1682 1478 25 4 v 1712 1478 V 81 w(doc)p 1863 1478 V 1892 1478 V 59 w(\))p 3319 1508 4 100 v 698 1607 V 749 1577 a(func)p 903 1577 25 4 v 29 w(globals)p 1317 1607 4 100 v 200 w(global)g(namespace)f(in)h(which)g(this)g (function)f(w)o(as)i(de\002ned)p 3319 1607 V 698 1707 V 749 1677 a(func)p 903 1677 25 4 v 29 w(name)p 1317 1707 4 100 v 260 w(\(same)f(as)p 1682 1677 25 4 v 1712 1677 V 81 w(name)p 1923 1677 V 1952 1677 V 59 w(\))p 3319 1707 4 100 v 282 1710 3337 4 v 331 1780 a(traceback)p 698 1810 4 100 v 98 w(tb)p 819 1780 25 4 v 30 w(frame)p 1317 1810 4 100 v 329 w(frame)g(object)f(at)i(this)g(le)n(v)o(el)p 3319 1810 V 698 1910 V 749 1880 a(tb)p 819 1880 25 4 v 30 w(lasti)p 1317 1910 4 100 v 386 w(inde)o(x)e(of)h(last)h (attempted)e(instruction)g(in)i(bytecode)p 3319 1910 V 698 2009 V 749 1979 a(tb)p 819 1979 25 4 v 30 w(lineno)p 1317 2009 4 100 v 315 w(current)e(line)h(number)f(in)h(Python)f(source) h(code)p 3319 2009 V 698 2109 V 749 2079 a(tb)p 819 2079 25 4 v 30 w(ne)o(xt)p 1317 2109 4 100 v 381 w(ne)o(xt)g(inner)f (traceback)g(object)h(\(called)f(by)h(this)h(le)n(v)o(el\))p 3319 2109 V 282 2112 3337 4 v 394 2182 a(frame)p 698 2212 4 100 v 160 w(f)p 782 2182 25 4 v 30 w(back)p 1317 2212 4 100 v 403 w(ne)o(xt)f(outer)f(frame)g(object)h(\(this)g(frame') -5 b(s)20 b(caller\))p 3319 2212 V 698 2311 V 749 2281 a(f)p 782 2281 25 4 v 30 w(b)n(uiltins)p 1317 2311 4 100 v 313 w(b)n(uilt-in)g(namespace)f(seen)h(by)g(this)h(frame)p 3319 2311 V 698 2411 V 749 2381 a(f)p 782 2381 25 4 v 30 w(code)p 1317 2411 4 100 v 403 w(code)f(object)f(being)h(e)o(x)o (ecuted)e(in)i(this)h(frame)p 3319 2411 V 698 2511 V 749 2481 a(f)p 782 2481 25 4 v 30 w(e)o(xc)p 927 2481 V 29 w(traceback)p 1317 2511 4 100 v 97 w(traceback)e(if)i(raised)f(in) g(this)h(frame,)e(or)h FJ(None)p 3319 2511 V 698 2610 V 749 2580 a FN(f)p 782 2580 25 4 v 30 w(e)o(xc)p 927 2580 V 29 w(type)p 1317 2610 4 100 v 273 w(e)o(xception)f(type)g(if)i (raised)f(in)g(this)h(frame,)e(or)h FJ(None)p 3319 2610 V 698 2710 V 749 2680 a FN(f)p 782 2680 25 4 v 30 w(e)o(xc)p 927 2680 V 29 w(v)n(alue)p 1317 2710 4 100 v 238 w(e)o(xception)f(v)n (alue)g(if)i(raised)f(in)g(this)h(frame,)e(or)h FJ(None)p 3319 2710 V 698 2809 V 749 2780 a FN(f)p 782 2780 25 4 v 30 w(globals)p 1317 2809 4 100 v 320 w(global)g(namespace)f(seen)h (by)g(this)g(frame)p 3319 2809 V 698 2909 V 749 2879 a(f)p 782 2879 25 4 v 30 w(lasti)p 1317 2909 4 100 v 423 w(inde)o(x)f(of)h(last)h(attempted)e(instruction)g(in)i(bytecode)p 3319 2909 V 698 3009 V 749 2979 a(f)p 782 2979 25 4 v 30 w(lineno)p 1317 3009 4 100 v 352 w(current)e(line)h(number)f(in)h (Python)f(source)h(code)p 3319 3009 V 698 3108 V 749 3078 a(f)p 782 3078 25 4 v 30 w(locals)p 1317 3108 4 100 v 367 w(local)g(namespace)f(seen)i(by)e(this)i(frame)p 3319 3108 V 698 3208 V 749 3178 a(f)p 782 3178 25 4 v 30 w(restricted)p 1317 3208 4 100 v 251 w(0)g(or)e(1)i(if)f(frame)g(is) h(in)f(restricted)g(e)o(x)o(ecution)e(mode)p 3319 3208 V 698 3308 V 749 3278 a(f)p 782 3278 25 4 v 30 w(trace)p 1317 3308 4 100 v 399 w(tracing)i(function)e(for)i(this)g(frame,)f(or)h FJ(None)p 3319 3308 V 282 3311 3337 4 v 412 3381 a FN(code)p 698 3411 4 100 v 179 w(co)p 833 3381 25 4 v 29 w(ar)o(gcount)p 1317 3411 4 100 v 219 w(number)f(of)h(ar)o(guments)e(\(not)h(including) g(*)h(or)g(**)g(ar)o(gs\))p 3319 3411 V 698 3510 V 749 3480 a(co)p 833 3480 25 4 v 29 w(code)p 1317 3510 4 100 v 353 w(string)g(of)g(ra)o(w)g(compiled)f(bytecode)p 3319 3510 V 698 3610 V 749 3580 a(co)p 833 3580 25 4 v 29 w(consts)p 1317 3610 4 100 v 303 w(tuple)h(of)g(constants)g(used)g (in)g(the)g(bytecode)p 3319 3610 V 698 3709 V 749 3680 a(co)p 833 3680 25 4 v 29 w(\002lename)p 1317 3709 4 100 v 224 w(name)g(of)g(\002le)h(in)f(which)g(this)g(code)g(object)g(w) o(as)h(created)p 3319 3709 V 698 3809 V 749 3779 a(co)p 833 3779 25 4 v 29 w(\002rstlineno)p 1317 3809 4 100 v 173 w(number)e(of)h(\002rst)h(line)f(in)g(Python)f(source)h(code)p 3319 3809 V 698 3909 V 749 3879 a(co)p 833 3879 25 4 v 29 w(\003ags)p 1317 3909 4 100 v 354 w(bitmap:)25 b(1=optimized)18 b FJ(|)i FN(2=ne)n(wlocals)f FJ(|)i FN(4=*ar)o(g)d FJ(|)j FN(8=**ar)o(g)p 3319 3909 V 698 4008 V 749 3978 a(co)p 833 3978 25 4 v 29 w(lnotab)p 1317 4008 4 100 v 302 w(encoded)e (mapping)f(of)i(line)g(numbers)f(to)h(bytecode)f(indices)p 3319 4008 V 698 4108 V 749 4078 a(co)p 833 4078 25 4 v 29 w(name)p 1317 4108 4 100 v 330 w(name)h(with)g(which)g(this)h (code)e(object)h(w)o(as)h(de\002ned)p 3319 4108 V 698 4208 V 749 4178 a(co)p 833 4178 25 4 v 29 w(names)p 1317 4208 4 100 v 298 w(tuple)f(of)g(names)g(of)g(local)g(v)n(ariables)p 3319 4208 V 698 4307 V 749 4277 a(co)p 833 4277 25 4 v 29 w(nlocals)p 1317 4307 4 100 v 275 w(number)f(of)h(local)g(v)n (ariables)p 3319 4307 V 698 4407 V 749 4377 a(co)p 833 4377 25 4 v 29 w(stacksize)p 1317 4407 4 100 v 211 w(virtual)g(machine) f(stack)h(space)g(required)p 3319 4407 V 698 4506 V 749 4477 a(co)p 833 4477 25 4 v 29 w(v)n(arnames)p 1317 4506 4 100 v 193 w(tuple)g(of)g(names)g(of)g(ar)o(guments)e(and)i(local)g(v) n(ariables)p 3319 4506 V 282 4510 3337 4 v 383 4579 a(b)n(uiltin)p 698 4609 4 100 v 754 4579 25 4 v 784 4579 V 210 w(doc)p 935 4579 V 964 4579 V 1317 4609 4 100 v 438 w(documentation)e(string)p 3319 4609 V 698 4709 V 754 4679 25 4 v 784 4679 V 809 4679 a(name)p 995 4679 V 1024 4679 V 1317 4709 4 100 v 378 w(original)h(name)h(of)g(this)h(function)d(or)i(method)p 3319 4709 V 698 4809 V 754 4779 25 4 v 784 4779 V 809 4779 a(self)p 934 4779 V 964 4779 V 1317 4809 4 100 v 439 w(instance)g(to)g(which)g(a)h(method)e(is)i(bound,)d(or)i FJ(None)p 3319 4809 V 0 5003 a FN(Note:)0 5216 y FL(\(1\))40 b FN(Changed)19 b(in)i(v)o(ersion)d(2.2:)i FJ(im_class)f FN(used)h(to)h(refer)e(to)h(the)h(class)g(that)f(de\002ned)f(the)h (method.)0 5382 y FD(getmembers)p FJ(\()p FK(object)q FC([)p FK(,)e(pr)m(edicate)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(846)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 847 859 TeXDict begin 847 858 bop 208 83 a FN(Return)24 b(all)i(the)g(members)e (of)h(an)g(object)g(in)g(a)h(list)h(of)e(\(name,)g(v)n(alue\))f(pairs)i (sorted)e(by)h(name.)40 b(If)25 b(the)g(optional)g FK(pr)m(edicate)208 183 y FN(ar)o(gument)17 b(is)22 b(supplied,)c(only)i(members)f(for)g (which)h(the)g(predicate)f(returns)h(a)g(true)g(v)n(alue)g(are)g (included.)0 330 y FD(getmoduleinfo)p FJ(\()p FK(path)p FJ(\))208 429 y FN(Return)j(a)i(tuple)e(of)h(v)n(alues)f(that)i (describe)e(ho)n(w)g(Python)g(will)i(interpret)e(the)h(\002le)g (identi\002ed)f(by)h FK(path)f FN(if)h(it)h(is)g(a)g(module,)e(or)208 529 y FJ(None)i FN(if)h(it)h(w)o(ould)e(not)g(be)h(identi\002ed)f(as)i (a)f(module.)40 b(The)26 b(return)e(tuple)i(is)g FJ(\()p FK(name)p FJ(,)49 b FK(suf)o(\002x)p FJ(,)f FK(mode)p FJ(,)h FK(mtype)p FJ(\))p FN(,)26 b(where)208 628 y FK(name)20 b FN(is)h(the)g(name)f(of)g(the)h(module)e(without)h(the)h(name)f(of)g (an)o(y)g(enclosing)g(package,)f FK(suf)o(\002x)h FN(is)i(the)e (trailing)g(part)h(of)f(the)h(\002le)208 728 y(name)k(\(which)g(may)g (not)h(be)f(a)i(dot-delimited)d(e)o(xtension\),)h FK(mode)g FN(is)i(the)f FJ(open\(\))f FN(mode)g(that)h(w)o(ould)f(be)h(used)f(\() p FJ('r')h FN(or)208 828 y FJ('rb')p FN(\),)21 b(and)g FK(mtype)g FN(is)h(an)g(inte)o(ger)e(gi)n(ving)g(the)i(type)f(of)g(the) g(module.)28 b FK(mtype)21 b FN(will)h(ha)n(v)o(e)f(a)h(v)n(alue)f (which)g(can)g(be)h(compared)208 927 y(to)27 b(the)g(constants)f (de\002ned)g(in)h(the)g FJ(imp)g FN(module;)i(see)f(the)f (documentation)d(for)i(that)h(module)f(for)g(more)g(information)f(on) 208 1027 y(module)18 b(types.)0 1174 y FD(getmodulename)p FJ(\()p FK(path)p FJ(\))208 1273 y FN(Return)f(the)h(name)g(of)g(the)g (module)f(named)g(by)h(the)g(\002le)h FK(path)p FN(,)e(without)h (including)e(the)j(names)e(of)h(enclosing)f(packages.)23 b(This)208 1373 y(uses)k(the)f(same)h(algorithm)e(as)j(the)e (interpreter)f(uses)j(when)e(searching)f(for)h(modules.)43 b(If)27 b(the)g(name)f(cannot)f(be)i(matched)208 1473 y(according)18 b(to)i(the)g(interpreter')-5 b(s)19 b(rules,)h FJ(None)g FN(is)h(returned.)0 1620 y FD(ismodule)p FJ(\()p FK(object)q FJ(\))208 1719 y FN(Return)e(true)h(if)h(the)f(object)f(is) j(a)e(module.)0 1866 y FD(isclass)p FJ(\()p FK(object)q FJ(\))208 1966 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e (class.)0 2113 y FD(ismethod)p FJ(\()p FK(object)q FJ(\))208 2212 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(method.)0 2359 y FD(isfunction)p FJ(\()p FK(object)q FJ(\))208 2459 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(Python)f (function)g(or)h(unnamed)e(\(lambda\))g(function.)0 2606 y FD(istraceback)p FJ(\()p FK(object)q FJ(\))208 2705 y FN(Return)h(true)h(if)h(the)f(object)f(is)j(a)e(traceback.)0 2852 y FD(isframe)p FJ(\()p FK(object)q FJ(\))208 2952 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(frame.)0 3099 y FD(iscode)p FJ(\()p FK(object)q FJ(\))208 3198 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(code.)0 3345 y FD(isbuiltin)p FJ(\()p FK(object)q FJ(\))208 3445 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(b)n(uilt-in)g (function.)0 3591 y FD(isroutine)p FJ(\()p FK(object)q FJ(\))208 3691 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(user)n (-de\002ned)f(or)h(b)n(uilt-in)f(function)g(or)h(method.)0 3838 y FD(ismethoddescriptor)p FJ(\()p FK(object)q FJ(\))208 3938 y FN(Return)f(true)h(if)h(the)f(object)f(is)j(a)e(method)f (descriptor)m(,)f(b)n(ut)i(not)g(if)h(ismethod\(\))d(or)i(isclass\(\))h (or)f(isfunction\(\))e(are)i(true.)208 4070 y(This)j(is)h(ne)n(w)f(as)h (of)e(Python)g(2.2,)h(and,)g(for)g(e)o(xample,)f(is)i(true)f(of)f(int.) p 2260 4070 25 4 v 2290 4070 V 60 w(add)p 2441 4070 V 2469 4070 V 58 w(.)35 b(An)23 b(object)f(passing)h(this)h(test)g(has)f (a)p 3656 4070 V 3686 4070 V 83 w(get)p 3818 4070 V 3847 4070 V 59 w(-)208 4170 y(attrib)n(ute)d(b)n(ut)i(not)f(a)p 822 4170 V 852 4170 V 81 w(set)p 974 4170 V 1004 4170 V 82 w(attrib)n(ute,)g(b)n(ut)g(be)o(yond)e(that)i(the)h(set)g(of)f (attrib)n(utes)g(v)n(aries.)p 2815 4170 V 2845 4170 V 87 w(name)p 3055 4170 V 3084 4170 V 81 w(is)h(usually)f(sensible,)g (and)p 208 4270 V 237 4270 V 262 4270 a(doc)p 388 4270 V 417 4270 V 80 w(often)e(is.)208 4403 y(Methods)e(implemented)g(via)h (descriptors)f(that)i(also)g(pass)g(one)e(of)i(the)f(other)g(tests)h (return)e(f)o(alse)i(from)f(the)g(ismethoddescrip-)208 4502 y(tor\(\))25 b(test,)j(simply)e(because)g(the)g(other)f(tests)i (promise)f(more)f(\226)h(you)g(can,)h(e.g.,)g(count)e(on)h(ha)n(ving)f (the)h(im)p 3426 4502 V 30 w(func)f(attrib)n(ute)208 4602 y(\(etc\))19 b(when)h(an)g(object)g(passes)h(ismethod\(\).)0 4749 y FD(isdatadescriptor)p FJ(\()p FK(object)q FJ(\))208 4848 y FN(Return)e(true)h(if)h(the)f(object)f(is)j(a)e(data)g (descriptor)-5 b(.)208 4981 y(Data)19 b(descriptors)f(ha)n(v)o(e)g (both)h(a)p 1170 4981 V 1200 4981 V 79 w(get)p 1332 4981 V 1361 4981 V 79 w(and)f(a)p 1607 4981 V 1636 4981 V 79 w(set)p 1758 4981 V 1788 4981 V 80 w(attrib)n(ute.)24 b(Examples)18 b(are)h(properties)f(\(de\002ned)g(in)h(Python\),)e (getsets,)208 5081 y(and)g(members.)23 b(The)18 b(latter)g(tw)o(o)g (are)g(de\002ned)f(in)h(C)h(and)e(there)h(are)f(more)g(speci\002c)i (tests)g(a)n(v)n(ailable)e(for)h(those)f(types,)h(which)g(is)208 5180 y(rob)n(ust)g(across)h(Python)e(implementations.)23 b(T)-7 b(ypically)i(,)17 b(data)i(descriptors)e(will)j(also)f(ha)n(v)o (e)p 2881 5180 V 2911 5180 V 78 w(name)p 3122 5180 V 3151 5180 V 78 w(and)p 3339 5180 V 3369 5180 V 78 w(doc)p 3520 5180 V 3548 5180 V 78 w(attrib)n(utes)208 5280 y(\(properties,)f (getsets,)i(and)g(members)f(ha)n(v)o(e)h(both)f(of)h(these)g(attrib)n (utes\),)g(b)n(ut)g(this)h(is)g(not)f(guaranteed.)48 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)p 0 5549 3901 4 v 0 5649 a FI(26.10.)52 b FJ(inspect)22 b FI(\227)h(Inspect)g(liv)n(e)h (objects)2302 b(847)p eop end %%Page: 848 860 TeXDict begin 848 859 bop 0 83 a FD(isgetsetdescriptor)p FJ(\()p FK(object)q FJ(\))208 183 y FN(Return)19 b(true)h(if)h(the)f (object)f(is)j(a)e(getset)h(descriptor)-5 b(.)208 315 y(getsets)20 b(are)g(attrib)n(utes)h(de\002ned)e(in)h(e)o(xtension)f (modules)g(via)h FJ(PyGetSetDef)f FN(structures.)25 b(F)o(or)19 b(Python)h(implementations)208 415 y(without)f(such)h(types,)g(this)g (method)f(will)i(al)o(w)o(ays)g(return)e FJ(False)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 562 y FD(ismemberdescriptor)p FJ(\()p FK(object)q FJ(\))208 662 y FN(Return)g(true)h(if)h(the)f (object)f(is)j(a)e(member)f(descriptor)-5 b(.)208 794 y(Member)28 b(descriptors)h(are)h(attrib)n(utes)f(de\002ned)g(in)h(e)o (xtension)e(modules)h(via)h FJ(PyMemberDef)e FN(structures.)53 b(F)o(or)30 b(Python)208 894 y(implementations)18 b(without)h(such)h (types,)g(this)h(method)e(will)h(al)o(w)o(ays)h(return)e FJ(False)p FN(.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f(2.5.)0 1179 y Fv(26.10.2)101 b(Retr)q(ie)m(ving)30 b(source)e(code)0 1368 y FD(getdoc)p FJ(\()p FK(object)q FJ(\))208 1467 y FN(Get)e(the)h(documentation)c(string)j(for)g(an)g(object.)43 b(All)27 b(tabs)f(are)h(e)o(xpanded)c(to)k(spaces.)44 b(T)-7 b(o)26 b(clean)g(up)g(docstrings)f(that)i(are)208 1567 y(indented)c(to)i(line)g(up)g(with)g(blocks)f(of)h(code,)g(an)o(y) g(whitespace)f(than)g(can)h(be)g(uniformly)e(remo)o(v)o(ed)f(from)i (the)h(second)f(line)208 1667 y(onw)o(ards)19 b(is)i(remo)o(v)o(ed.)0 1814 y FD(getcomments)p FJ(\()p FK(object)q FJ(\))208 1913 y FN(Return)26 b(in)i(a)f(single)h(string)e(an)o(y)h(lines)g(of)g (comments)g(immediately)e(preceding)h(the)h(object')-5 b(s)27 b(source)f(code)h(\(for)f(a)i(class,)208 2013 y(function,)18 b(or)i(method\),)e(or)i(at)h(the)f(top)g(of)f(the)i (Python)e(source)g(\002le)i(\(if)f(the)g(object)g(is)h(a)g(module\).)0 2160 y FD(getfile)p FJ(\()p FK(object)q FJ(\))208 2259 y FN(Return)e(the)h(name)f(of)h(the)g(\(te)o(xt)g(or)f(binary\))g (\002le)h(in)g(which)g(an)g(object)f(w)o(as)i(de\002ned.)j(This)c(will) h(f)o(ail)f(with)g(a)g FJ(TypeError)f FN(if)208 2359 y(the)h(object)f(is)j(a)e(b)n(uilt-in)g(module,)e(class,)j(or)f (function.)0 2506 y FD(getmodule)p FJ(\()p FK(object)q FJ(\))208 2605 y FN(T)m(ry)f(to)i(guess)f(which)g(module)e(an)i(object) g(w)o(as)h(de\002ned)e(in.)0 2752 y FD(getsourcefile)p FJ(\()p FK(object)q FJ(\))208 2852 y FN(Return)h(the)i(name)e(of)h(the) h(Python)e(source)g(\002le)i(in)g(which)e(an)i(object)e(w)o(as)j (de\002ned.)k(This)21 b(will)h(f)o(ail)g(with)f(a)h FJ(TypeError)e FN(if)208 2952 y(the)g(object)f(is)j(a)e(b)n(uilt-in)g(module,)e (class,)j(or)f(function.)0 3098 y FD(getsourcelines)p FJ(\()p FK(object)q FJ(\))208 3198 y FN(Return)28 b(a)i(list)g(of)f (source)f(lines)h(and)g(starting)g(line)g(number)e(for)i(an)g(object.) 51 b(The)28 b(ar)o(gument)f(may)i(be)g(a)g(module,)h(class,)208 3298 y(method,)17 b(function,)g(traceback,)h(frame,)g(or)g(code)g (object.)24 b(The)19 b(source)f(code)g(is)i(returned)d(as)j(a)f(list)h (of)e(the)h(lines)g(correspond-)208 3397 y(ing)h(to)h(the)g(object)f (and)g(the)h(line)g(number)e(indicates)i(where)f(in)h(the)g(original)e (source)h(\002le)i(the)f(\002rst)g(line)g(of)g(code)f(w)o(as)i(found.) 208 3497 y(An)e FJ(IOError)f FN(is)i(raised)f(if)h(the)f(source)f(code) h(cannot)f(be)h(retrie)n(v)o(ed.)0 3644 y FD(getsource)p FJ(\()p FK(object)q FJ(\))208 3743 y FN(Return)29 b(the)h(te)o(xt)g(of) f(the)h(source)f(code)h(for)f(an)h(object.)53 b(The)30 b(ar)o(gument)d(may)j(be)g(a)g(module,)h(class,)i(method,)e(function,) 208 3843 y(traceback,)22 b(frame,)i(or)f(code)g(object.)35 b(The)23 b(source)g(code)g(is)h(returned)e(as)j(a)f(single)f(string.)35 b(An)24 b FJ(IOError)f FN(is)h(raised)g(if)g(the)208 3943 y(source)19 b(code)g(cannot)h(be)g(retrie)n(v)o(ed.)0 4228 y Fv(26.10.3)101 b(Classes)28 b(and)h(functions)0 4416 y FD(getclasstree)p FJ(\()p FK(classes)p FC([)p FK(,)18 b(unique)12 b FC(])p FJ(\))208 4516 y FN(Arrange)19 b(the)j(gi)n(v)o(en)e(list)i(of)f(classes)h(into)f(a)h(hierarchy)d(of)i (nested)g(lists.)29 b(Where)22 b(a)f(nested)g(list)i(appears,)d(it)i (contains)e(classes)208 4616 y(deri)n(v)o(ed)e(from)h(the)h(class)h (whose)f(entry)f(immediately)g(precedes)g(the)i(list.)26 b(Each)19 b(entry)h(is)h(a)f(2-tuple)f(containing)f(a)j(class)g(and)208 4715 y(a)26 b(tuple)g(of)g(its)h(base)f(classes.)45 b(If)26 b(the)g FK(unique)f FN(ar)o(gument)f(is)j(true,)g(e)o(xactly)e(one)h (entry)f(appears)h(in)g(the)g(returned)f(structure)208 4815 y(for)c(each)h(class)h(in)f(the)g(gi)n(v)o(en)f(list.)31 b(Otherwise,)22 b(classes)i(using)d(multiple)g(inheritance)g(and)g (their)h(descendants)f(will)i(appear)208 4915 y(multiple)c(times.)0 5061 y FD(getargspec)p FJ(\()p FK(func)p FJ(\))208 5161 y FN(Get)e(the)f(names)h(and)f(def)o(ault)g(v)n(alues)g(of)g(a)h (function')-5 b(s)16 b(ar)o(guments.)21 b(A)d(tuple)e(of)g(four)g (things)g(is)i(returned:)j FJ(\()p FK(ar)m(gs)p FJ(,)49 b FK(var)o(ar)m(gs)p FJ(,)208 5261 y FK(varkw)p FJ(,)g FK(defaults)p FJ(\))p FN(.)25 b FK(ar)m(gs)20 b FN(is)i(a)f(list)g(of)f (the)h(ar)o(gument)d(names)i(\(it)h(may)e(contain)h(nested)g(lists\).) 27 b FK(var)o(ar)m(gs)19 b FN(and)h FK(varkw)h FN(are)g(the)p 0 5549 3901 4 v 0 5649 a FI(848)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 849 861 TeXDict begin 849 860 bop 208 83 a FN(names)22 b(of)g(the)660 98 y FJ(*)733 83 y FN(and)876 98 y FJ(**)999 83 y FN(ar)o(guments)f(or) h FJ(None)p FN(.)32 b FK(defaults)22 b FN(is)i(a)f(tuple)f(of)h(def)o (ault)f(ar)o(gument)e(v)n(alues)i(or)g(None)g(if)h(there)g(are)208 183 y(no)c(def)o(ault)h(ar)o(guments;)e(if)i(this)h(tuple)f(has)g FK(n)h FN(elements,)e(the)o(y)h(correspond)d(to)k(the)f(last)h FK(n)f FN(elements)g(listed)h(in)f FK(ar)m(gs)p FN(.)0 330 y FD(getargvalues)p FJ(\()p FK(fr)o(ame)p FJ(\))208 429 y FN(Get)28 b(information)e(about)i(ar)o(guments)e(passed)i(into)g (a)h(particular)e(frame.)48 b(A)29 b(tuple)f(of)g(four)f(things)h(is)h (returned:)40 b FJ(\()p FK(ar)m(gs)p FJ(,)208 529 y FK(var)o(ar)m(gs)p FJ(,)48 b FK(varkw)p FJ(,)i FK(locals)p FJ(\))p FN(.)j FK(ar)m(gs)30 b FN(is)h(a)f(list)h(of)f(the)g(ar)o(gument)d(names)j (\(it)g(may)f(contain)g(nested)h(lists\).)55 b FK(var)o(ar)m(gs)29 b FN(and)208 628 y FK(varkw)20 b FN(are)g(the)h(names)e(of)h(the)1121 643 y FJ(*)1191 628 y FN(and)1332 643 y FJ(**)1452 628 y FN(ar)o(guments)e(or)i FJ(None)p FN(.)25 b FK(locals)20 b FN(is)h(the)f(locals)h(dictionary)d(of)i(the)g(gi)n(v)o(en)f(frame.)0 775 y FD(formatargspec)p FJ(\()p FK(ar)m(gs)p FC([)p FK(,)e(var)o(ar)m(gs,)j(varkw)-6 b(,)20 b(defaults,)f(formatar)m(g)o(,) h(formatvar)o(ar)m(gs,)f(formatvarkw)-6 b(,)19 b(formatvalue)o(,)g (join)12 b FC(])p FJ(\))208 875 y FN(F)o(ormat)20 b(a)i(pretty)f(ar)o (gument)e(spec)i(from)f(the)i(four)e(v)n(alues)h(returned)f(by)h FJ(getargspec\(\))p FN(.)26 b(The)c(format*)d(ar)o(guments)h(are)208 975 y(the)g(corresponding)c(optional)j(formatting)g(functions)f(that)j (are)f(called)g(to)g(turn)g(names)g(and)f(v)n(alues)h(into)g(strings.)0 1121 y FD(formatargvalues)p FJ(\()p FK(ar)m(gs)p FC([)p FK(,)d(var)o(ar)m(gs,)i(varkw)-6 b(,)21 b(locals,)e(formatar)m(g)o(,)h (formatvar)o(ar)m(gs,)f(formatvarkw)-6 b(,)19 b(formatvalue)o(,)g(join) 12 b FC(])p FJ(\))208 1221 y FN(F)o(ormat)22 b(a)h(pretty)f(ar)o (gument)f(spec)h(from)g(the)h(four)f(v)n(alues)g(returned)f(by)i FJ(getargvalues\(\))p FN(.)31 b(The)22 b(format*)g(ar)o(guments)208 1321 y(are)e(the)g(corresponding)d(optional)i(formatting)f(functions)h (that)h(are)g(called)g(to)g(turn)g(names)g(and)f(v)n(alues)h(into)g (strings.)0 1468 y FD(getmro)p FJ(\()p FK(cls)p FJ(\))208 1567 y FN(Return)28 b(a)i(tuple)f(of)g(class)h(cls')-5 b(s)31 b(base)e(classes,)k(including)27 b(cls,)32 b(in)e(method)e (resolution)g(order)-5 b(.)51 b(No)30 b(class)g(appears)e(more)208 1667 y(than)e(once)h(in)g(this)g(tuple.)45 b(Note)27 b(that)h(the)f(method)e(resolution)h(order)g(depends)g(on)g(cls')-5 b(s)29 b(type.)45 b(Unless)27 b(a)h(v)o(ery)e(peculiar)208 1766 y(user)n(-de\002ned)18 b(metatype)h(is)i(in)g(use,)f(cls)h(will)g (be)f(the)g(\002rst)h(element)f(of)f(the)i(tuple.)0 2051 y Fv(26.10.4)101 b(The)28 b(inter)s(preter)i(stac)n(k)0 2254 y FN(When)16 b(the)g(follo)n(wing)f(functions)g(return)g (\223frame)g(records,)-6 b(\224)16 b(each)f(record)g(is)i(a)g(tuple)f (of)g(six)h(items:)23 b(the)16 b(frame)g(object,)g(the)g(\002lename,)0 2354 y(the)k(line)h(number)e(of)h(the)g(current)f(line,)i(the)f (function)f(name,)g(a)i(list)h(of)e(lines)h(of)f(conte)o(xt)f(from)h (the)g(source)g(code,)f(and)h(the)h(inde)o(x)e(of)0 2453 y(the)h(current)f(line)h(within)g(that)h(list.)p 0 2527 3901 17 v 0 4136 17 1610 v 75 2642 a FL(W)-5 b(ar)o(ning:)49 b FN(K)n(eeping)18 b(references)f(to)j(frame)e(objects,)h(as)h(found)e (in)h(the)g(\002rst)h(element)f(of)g(the)g(frame)g(records)f(these)h (functions)75 2742 y(return,)j(can)h(cause)g(your)f(program)e(to)k (create)e(reference)g(c)o(ycles.)33 b(Once)23 b(a)g(reference)f(c)o (ycle)g(has)h(been)g(created,)f(the)h(lifespan)75 2841 y(of)29 b(all)g(objects)g(which)g(can)g(be)g(accessed)g(from)f(the)h (objects)g(which)g(form)f(the)h(c)o(ycle)g(can)g(become)e(much)i (longer)e(e)n(v)o(en)i(if)75 2941 y(Python')-5 b(s)28 b(optional)f(c)o(ycle)h(detector)g(is)h(enabled.)49 b(If)29 b(such)f(c)o(ycles)g(must)h(be)g(created,)g(it)h(is)f(important)e(to)i (ensure)f(the)o(y)g(are)75 3041 y(e)o(xplicitly)19 b(brok)o(en)f(to)j (a)n(v)n(oid)f(the)g(delayed)f(destruction)f(of)i(objects)g(and)g (increased)f(memory)g(consumption)e(which)j(occurs.)75 3140 y(Though)e(the)j(c)o(ycle)f(detector)f(will)i(catch)f(these,)h (destruction)e(of)h(the)h(frames)f(\(and)f(local)i(v)n(ariables\))e (can)h(be)h(made)e(determin-)75 3240 y(istic)j(by)f(remo)o(ving)d(the)k (c)o(ycle)e(in)i(a)f FJ(finally)g FN(clause.)28 b(This)21 b(is)h(also)g(important)d(if)j(the)f(c)o(ycle)g(detector)f(w)o(as)i (disabled)e(when)75 3339 y(Python)f(w)o(as)i(compiled)e(or)g(using)h FJ(gc.disable\(\))p FN(.)j(F)o(or)d(e)o(xample:)311 3439 y FA(def)44 b(handle_stackframe_without_leak\(\):)490 3530 y(frame)g(=)h(inspect.currentframe\(\))490 3622 y(try:)670 3713 y(#)f(do)h(something)e(with)h(the)h(frame)490 3804 y(finally:)670 3896 y(del)f(frame)p 3883 4136 V 0 4153 3901 17 v 0 4308 a FN(The)19 b(optional)g FK(conte)n(xt)h FN(ar)o(gument)e(supported)f(by)j(most)f(of)h(these)f(functions)g (speci\002es)h(the)f(number)f(of)h(lines)h(of)g(conte)o(xt)e(to)i (return,)0 4408 y(which)g(are)g(centered)f(around)f(the)i(current)f (line.)0 4555 y FD(getframeinfo)p FJ(\()p FK(fr)o(ame)p FC([)p FK(,)e(conte)n(xt)c FC(])p FJ(\))208 4654 y FN(Get)24 b(information)d(about)i(a)i(frame)e(or)g(traceback)g(object.)36 b(A)24 b(5-tuple)f(is)i(returned,)d(the)i(last)h(\002)n(v)o(e)f (elements)f(of)h(the)g(frame')-5 b(s)208 4754 y(frame)19 b(record.)0 4901 y FD(getouterframes)p FJ(\()p FK(fr)o(ame)p FC([)p FK(,)e(conte)n(xt)c FC(])p FJ(\))208 5000 y FN(Get)26 b(a)g(list)h(of)e(frame)g(records)g(for)g(a)h(frame)f(and)g(all)i (outer)d(frames.)42 b(These)25 b(frames)g(represent)g(the)h(calls)g (that)g(lead)g(to)g(the)208 5100 y(creation)e(of)h FK(fr)o(ame)p FN(.)41 b(The)25 b(\002rst)h(entry)f(in)g(the)h(returned)d(list)k (represents)d FK(fr)o(ame)p FN(;)29 b(the)c(last)h(entry)f(represents)f (the)i(outermost)208 5200 y(call)20 b(on)g FK(fr)o(ame)p FN(')-5 b(s)21 b(stack.)0 5347 y FD(getinnerframes)p FJ(\()p FK(tr)o(acebac)n(k)q FC([)p FK(,)16 b(conte)n(xt)d FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(26.10.)52 b FJ(inspect)22 b FI(\227)h(Inspect)g(liv)n(e)h(objects)2302 b(849)p eop end %%Page: 850 862 TeXDict begin 850 861 bop 208 83 a FN(Get)29 b(a)g(list)g(of)f(frame)g (records)g(for)g(a)h(traceback')-5 b(s)27 b(frame)h(and)g(all)h(inner)f (frames.)49 b(These)28 b(frames)g(represent)g(calls)h(made)208 183 y(as)c(a)g(consequence)d(of)j FK(fr)o(ame)p FN(.)38 b(The)24 b(\002rst)i(entry)d(in)i(the)g(list)h(represents)d FK(tr)o(acebac)n(k)q FN(;)k(the)d(last)i(entry)e(represents)g(where)g (the)208 282 y(e)o(xception)18 b(w)o(as)j(raised.)0 429 y FD(currentframe)p FJ(\(\))208 529 y FN(Return)e(the)i(frame)e(object) h(for)f(the)h(caller')-5 b(s)21 b(stack)f(frame.)0 676 y FD(stack)p FJ(\()p FC([)p FK(conte)n(xt)13 b FC(])p FJ(\))208 775 y FN(Return)22 b(a)g(list)i(of)e(frame)g(records)f(for)h (the)h(caller')-5 b(s)22 b(stack.)32 b(The)23 b(\002rst)g(entry)e(in)i (the)g(returned)d(list)k(represents)d(the)i(caller;)h(the)208 875 y(last)d(entry)e(represents)g(the)i(outermost)d(call)j(on)f(the)g (stack.)0 1022 y FD(trace)p FJ(\()p FC([)p FK(conte)n(xt)13 b FC(])p FJ(\))208 1121 y FN(Return)28 b(a)i(list)g(of)f(frame)f (records)g(for)g(the)h(stack)h(between)e(the)h(current)f(frame)g(and)g (the)h(frame)g(in)g(which)f(an)h(e)o(xception)208 1221 y(currently)22 b(being)i(handled)f(w)o(as)i(raised)g(in.)38 b(The)24 b(\002rst)h(entry)f(in)h(the)f(list)i(represents)d(the)i (caller;)i(the)d(last)i(entry)d(represents)208 1321 y(where)c(the)h(e)o (xception)f(w)o(as)i(raised.)0 1648 y FE(26.11)122 b Fx(site)32 b FE(\227)h(Site-speci\002c)f(con\002gur)o(ation)k(hook)0 1881 y FL(This)27 b(module)g(is)g(automatically)d(imported)h(during)i (initialization.)41 b FN(The)26 b(automatic)f(import)g(can)g(be)h (suppressed)f(using)h(the)0 1981 y(interpreter')-5 b(s)19 b FL(-S)h FN(option.)0 2127 y(Importing)e(this)j(module)d(will)j (append)e(site-speci\002c)h(paths)g(to)h(the)f(module)f(search)g(path.) 0 2274 y(It)h(starts)g(by)f(constructing)f(up)h(to)h(four)e (directories)g(from)h(a)h(head)f(and)g(a)h(tail)g(part.)k(F)o(or)19 b(the)h(head)f(part,)g(it)h(uses)g FJ(sys.prefix)e FN(and)0 2374 y FJ(sys.exec_prefix)p FN(;)f(empty)i(heads)f(are)h(skipped.)24 b(F)o(or)18 b(the)i(tail)f(part,)g(it)h(uses)f(the)h(empty)e(string)h (and)f(then)h(`)p FO(lib/site-pac)o(kages)p FN(')0 2474 y(\(on)25 b(W)m(indo)n(ws\))g(or)g(`)p FO(lib/p)n(ython2.5/site-pa)o(c) o(kage)o(s)p FN(')c(and)k(then)g(`)p FO(lib/site-p)n(ython)p FN(')d(\(on)27 b(U)t FH(N)t(I)t(X)h FN(and)e(Macintosh\).)40 b(F)o(or)26 b(each)f(of)h(the)0 2573 y(distinct)g(head-tail)e (combinations,)h(it)h(sees)h(if)e(it)i(refers)e(to)h(an)f(e)o(xisting)g (directory)-5 b(,)24 b(and)h(if)h(so,)h(adds)f(it)g(to)g FJ(sys.path)e FN(and)h(also)0 2673 y(inspects)20 b(the)g(ne)n(wly)g (added)f(path)h(for)f(con\002guration)f(\002les.)0 2820 y(A)28 b(path)f(con\002guration)f(\002le)i(is)h(a)f(\002le)g(whose)g (name)f(has)h(the)f(form)g(`)p FK(pac)n(ka)o(g)o(e)p FI(.pth)p FN(')f(and)i(e)o(xists)g(in)g(one)f(of)g(the)h(four)f (directories)0 2919 y(mentioned)21 b(abo)o(v)o(e;)j(its)g(contents)e (are)i(additional)d(items)j(\(one)f(per)f(line\))h(to)h(be)f(added)f (to)i FJ(sys.path)p FN(.)33 b(Non-e)o(xisting)21 b(items)j(are)0 3019 y(ne)n(v)o(er)g(added)h(to)h FJ(sys.path)p FN(,)g(b)n(ut)g(no)f (check)g(is)i(made)e(that)h(the)f(item)h(refers)g(to)g(a)g(directory)e (\(rather)g(than)i(a)g(\002le\).)42 b(No)26 b(item)g(is)0 3119 y(added)16 b(to)h FJ(sys.path)e FN(more)h(than)h(once.)23 b(Blank)17 b(lines)g(and)f(lines)h(be)o(ginning)d(with)j FJ(#)h FN(are)e(skipped.)23 b(Lines)17 b(starting)f(with)h FJ(import)0 3218 y FN(are)j(e)o(x)o(ecuted.)0 3365 y(F)o(or)27 b(e)o(xample,)h(suppose)e FJ(sys.prefix)g FN(and)h FJ(sys.exec_prefix)e FN(are)i(set)h(to)g(`)p FO(/usr/local)p FN('.)44 b(The)27 b(Python)f(2.5.3)g(library)h(is)0 3465 y(then)18 b(installed)g(in)h(`)p FO(/usr/local/lib/p)n(ython2.)o(5)p FN(')13 b(\(where)k(only)h(the)g (\002rst)i(three)e(characters)f(of)i FJ(sys.version)e FN(are)h(used)g(to)h(form)f(the)0 3564 y(installation)24 b(path)f(name\).)36 b(Suppose)22 b(this)j(has)f(a)h(subdirectory)c(`)p FO(/usr/local/lib/p)n(ython2.)o(5/sit)o(e-p)o(ac)o(kag)o(es)p FN(')d(with)25 b(three)e(subsubdi-)0 3664 y(rectories,)f(`)p FO(f)n(oo)p FN(',)g(`)p FO(bar)p FN(')f(and)h(`)p FO(spam)p FN(',)h(and)f(tw)o(o)h(path)f(con\002guration)e(\002les,)j(`)p FO(f)n(oo)m(.pth)p FN(')d(and)i(`)p FO(bar)l(.pth)p FN('.)30 b(Assume)23 b(`)p FO(f)n(oo)m(.pth)p FN(')c(contains)0 3764 y(the)h(follo)n(wing:)236 4002 y FA(#)45 b(foo)f(package)g (configuration)236 4184 y(foo)236 4276 y(bar)236 4367 y(bletch)0 4654 y FN(and)20 b(`)p FO(bar)l(.pth)p FN(')e(contains:)236 4892 y FA(#)45 b(bar)f(package)g(configuration)236 5074 y(bar)0 5361 y FN(Then)19 b(the)i(follo)n(wing)d(directories)h(are)h (added)f(to)i FJ(sys.path)p FN(,)e(in)h(this)h(order:)p 0 5549 3901 4 v 0 5649 a FI(850)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 851 863 TeXDict begin 851 862 bop 236 83 a FA (/usr/local/lib/python2.3/site-packages/b)o(ar)236 174 y(/usr/local/lib/python2.3/site-packages/f)o(oo)0 461 y FN(Note)21 b(that)f(`)p FO(b)o(letch)p FN(')f(is)i(omitted)f(because) g(it)i(doesn')o(t)d(e)o(xist;)i(the)g(`)p FO(bar)p FN(')e(directory)g (precedes)h(the)h(`)p FO(f)n(oo)p FN(')e(directory)g(because)h(`)p FO(bar)l(.pth)p FN(')0 560 y(comes)j(alphabetically)e(before)h(`)p FO(f)n(oo)m(.pth)p FN(';)g(and)h(`)p FO(spam)p FN(')f(is)i(omitted)f (because)f(it)i(is)g(not)f(mentioned)e(in)j(either)f(path)f (con\002guration)0 660 y(\002le.)0 807 y(After)d(these)f(path)h (manipulations,)e(an)h(attempt)h(is)h(made)e(to)h(import)e(a)j(module)d (named)h FJ(sitecustomize)p FN(,)f(which)h(can)h(perform)0 907 y(arbitrary)g(site-speci\002c)h(customizations.)k(If)c(this)g (import)f(f)o(ails)i(with)g(an)f FJ(ImportError)f FN(e)o(xception,)f (it)j(is)g(silently)f(ignored.)0 1053 y(Note)i(that)h(for)e(some)h (non-)r(U)t FH(N)t(I)t(X)i FN(systems,)f FJ(sys.prefix)e FN(and)h FJ(sys.exec_prefix)e FN(are)i(empty)-5 b(,)21 b(and)h(the)h(path)e(manipula-)0 1153 y(tions)f(are)g(skipped;)f(ho)n (we)n(v)o(er)g(the)h(import)f(of)h FJ(sitecustomize)e FN(is)j(still)h(attempted.)0 1481 y FE(26.12)122 b Fx(user)32 b FE(\227)h(User-speci\002c)g(con\002gur)o(ation)i(hook)0 1713 y FN(As)21 b(a)f(polic)o(y)-5 b(,)18 b(Python)h(doesn')o(t)f(run)h (user)n(-speci\002ed)g(code)g(on)h(startup)f(of)h(Python)f(programs.)k (\(Only)c(interacti)n(v)o(e)f(sessions)j(e)o(x)o(ecute)0 1813 y(the)f(script)g(speci\002ed)g(in)h(the)f(PYTHONST)-8 b(AR)j(TUP)21 b(en)m(vironment)c(v)n(ariable)i(if)h(it)h(e)o(xists\).)0 1960 y(Ho)n(we)n(v)o(er)m(,)i(some)h(programs)f(or)h(sites)h(may)f (\002nd)g(it)h(con)m(v)o(enient)d(to)j(allo)n(w)f(users)g(to)h(ha)n(v)o (e)f(a)g(standard)g(customization)e(\002le,)k(which)0 2059 y(gets)e(run)e(when)h(a)h(program)d(requests)i(it.)36 b(This)23 b(module)f(implements)h(such)g(a)g(mechanism.)34 b(A)24 b(program)d(that)i(wishes)h(to)g(use)g(the)0 2159 y(mechanism)19 b(must)h(e)o(x)o(ecute)f(the)h(statement)236 2397 y FA(import)44 b(user)0 2684 y FN(The)18 b FJ(user)g FN(module)f(looks)g(for)h(a)g(\002le)h(`)p FO(.p)n(ythonrc.p)n(y)p FN(')d(in)i(the)g(user')-5 b(s)18 b(home)g(directory)e(and)i(if)g(it)h (can)f(be)g(opened,)f(e)o(x)o(ecutes)g(it)h(\(using)0 2783 y FJ(execfile\(\))p FN(\))i(in)i(its)h(o)n(wn)e(\(the)h(module)e FJ(user)p FN(')-5 b(s\))22 b(global)f(namespace.)28 b(Errors)21 b(during)f(this)i(phase)g(are)g(not)f(caught;)h(that')-5 b(s)22 b(up)0 2883 y(to)d(the)g(program)d(that)j(imports)f(the)h FJ(user)g FN(module,)e(if)i(it)h(wishes.)25 b(The)18 b(home)g(directory)f(is)j(assumed)e(to)h(be)g(named)e(by)i(the)g(HOME)0 2983 y(en)m(vironment)e(v)n(ariable;)i(if)i(this)f(is)i(not)d(set,)i (the)f(current)f(directory)g(is)i(used.)0 3130 y(The)j(user')-5 b(s)24 b(`)p FO(.p)n(ythonrc.p)n(y)p FN(')d(could)i(concei)n(v)n(ably)e (test)k(for)f FJ(sys.version)e FN(if)i(it)h(wishes)f(to)g(do)g(dif)n (ferent)e(things)i(depending)d(on)0 3229 y(the)f(Python)f(v)o(ersion.)0 3376 y(A)24 b(w)o(arning)e(to)i(users:)32 b(be)23 b(v)o(ery)g(conserv)n (ati)n(v)o(e)e(in)i(what)h(you)e(place)i(in)f(your)g(`)p FO(.p)n(ythonrc.p)n(y)p FN(')d(\002le.)36 b(Since)23 b(you)g(don')o(t)f(kno)n(w)g(which)0 3476 y(programs)c(will)j(use)g (it,)f(changing)e(the)j(beha)n(vior)d(of)i(standard)f(modules)g(or)h (functions)f(is)i(generally)e(not)h(a)g(good)f(idea.)0 3623 y(A)26 b(suggestion)e(for)h(programmers)d(who)j(wish)h(to)f(use)h (this)g(mechanism:)34 b(a)26 b(simple)f(w)o(ay)g(to)h(let)g(users)f (specify)g(options)f(for)h(your)0 3722 y(package)15 b(is)j(to)f(ha)n(v) o(e)f(them)h(de\002ne)f(v)n(ariables)g(in)h(their)f(`)p FO(.p)n(ythonrc.p)n(y)p FN(')f(\002le)i(that)g(you)f(test)i(in)e(your)g (module.)22 b(F)o(or)17 b(e)o(xample,)f(a)h(module)0 3822 y FJ(spam)j FN(that)g(has)h(a)f(v)o(erbosity)f(le)n(v)o(el)h(can)g (look)f(for)h(a)g(v)n(ariable)f FJ(user.spam_verbose)p FN(,)f(as)j(follo)n(ws:)236 3969 y FA(import)44 b(user)236 4151 y(verbose)g(=)h(bool\(getattr\(user,)c("spam_verbose",)i(0\)\))0 4438 y FN(\(The)38 b(three-ar)o(gument)d(form)j(of)g FJ(getattr\(\))g FN(is)h(used)g(in)g(case)g(the)f(user)h(has)g(not)f (de\002ned)g FJ(spam_verbose)f FN(in)i(their)0 4537 y(`)p FO(.p)n(ythonrc.p)n(y)p FN(')18 b(\002le.\))0 4684 y(Programs)h(with)h (e)o(xtensi)n(v)o(e)f(customization)g(needs)g(are)i(better)e(of)n(f)h (reading)f(a)h(program-speci\002c)e(customization)g(\002le.)0 4831 y(Programs)i(with)i(security)f(or)h(pri)n(v)n(ac)o(y)e(concerns)g (should)h FK(not)g FN(import)g(this)h(module;)f(a)h(user)g(can)f (easily)h(break)f(into)g(a)h(program)e(by)0 4931 y(placing)f(arbitrary) g(code)g(in)i(the)f(`)p FO(.p)n(ythonrc.p)n(y)p FN(')d(\002le.)0 5078 y(Modules)i(for)h(general)f(use)h(should)g FK(not)f FN(import)h(this)g(module;)f(it)i(may)f(interfere)f(with)h(the)g (operation)f(of)h(the)g(importing)e(program.)0 5225 y FL(See)j(Also:)0 5371 y FN(Module)e FJ(site)h FN(\(section)g(26.11\):)p 0 5549 3901 4 v 0 5649 a FI(26.12.)52 b FJ(user)23 b FI(\227)g(User-speci\002c)e(con\002gur)o(ation)i(hook)1971 b(851)p eop end %%Page: 852 864 TeXDict begin 852 863 bop 208 83 a FN(Site-wide)20 b(customization)e (mechanism.)0 410 y FE(26.13)122 b Fx(fpectl)31 b FE(\227)i(Floating)i (point)f(e)l(xception)h(control)0 643 y FL(Note:)30 b FN(The)22 b FJ(fpectl)g FN(module)g(is)i(not)e(b)n(uilt)h(by)f(def)o (ault,)h(and)f(its)i(usage)e(is)i(discouraged)d(and)h(may)g(be)h (dangerous)e(e)o(xcept)h(in)h(the)0 743 y(hands)c(of)h(e)o(xperts.)k (See)d(also)g(the)f(section)g(26.13.2)d(on)j(limitations)g(for)g(more)f (details.)0 890 y(Most)g(computers)e(carry)g(out)h(\003oating)g(point)g (operations)f(in)i(conformance)c(with)k(the)f(so-called)g(IEEE-754)e (standard.)23 b(On)c(an)o(y)f(real)0 989 y(computer)m(,)25 b(some)h(\003oating)f(point)g(operations)f(produce)g(results)i(that)g (cannot)f(be)h(e)o(xpressed)f(as)h(a)h(normal)d(\003oating)h(point)g(v) n(alue.)0 1089 y(F)o(or)20 b(e)o(xample,)e(try)236 1327 y FA(>>>)45 b(import)e(math)236 1419 y(>>>)i(math.exp\(1000\))236 1510 y(inf)236 1601 y(>>>)g(math.exp\(1000\))d(/)j(math.exp\(1000\))236 1693 y(nan)0 1979 y FN(\(The)17 b(e)o(xample)g(abo)o(v)o(e)f(will)i(w)o (ork)g(on)f(man)o(y)g(platforms.)23 b(DEC)18 b(Alpha)f(may)h(be)f(one)h (e)o(xception.\))k(\224Inf\224)17 b(is)h(a)h(special,)f(non-numeric)0 2079 y(v)n(alue)j(in)i(IEEE-754)d(that)i(stands)g(for)g (\224in\002nity\224,)f(and)h(\224nan\224)f(means)h(\224not)g(a)g (number)-5 b(.)f(\224)21 b(Note)h(that,)h(other)e(than)h(the)g (non-numeric)0 2178 y(results,)k(nothing)d(special)i(happened)d(when)j (you)e(ask)o(ed)i(Python)f(to)h(carry)e(out)i(those)g(calculations.)37 b(That)25 b(is)h(in)f(f)o(act)f(the)h(def)o(ault)0 2278 y(beha)n(viour)18 b(prescribed)h(in)h(the)g(IEEE-754)e(standard,)h(and) g(if)i(it)g(w)o(orks)f(for)f(you,)g(stop)h(reading)f(no)n(w)-5 b(.)0 2425 y(In)30 b(some)f(circumstances,)i(it)g(w)o(ould)e(be)h (better)f(to)h(raise)g(an)g(e)o(xception)e(and)h(stop)h(processing)f (at)h(the)g(point)f(where)g(the)h(f)o(aulty)0 2524 y(operation)c(w)o (as)k(attempted.)48 b(The)28 b FJ(fpectl)g FN(module)f(is)i(for)f(use)g (in)h(that)f(situation.)49 b(It)29 b(pro)o(vides)e(control)g(o)o(v)o (er)g(\003oating)g(point)0 2624 y(units)c(from)g(se)n(v)o(eral)f(hardw) o(are)g(manuf)o(acturers,)f(allo)n(wing)i(the)g(user)g(to)h(turn)e(on)h (the)g(generation)e(of)i FJ(SIGFPE)g FN(whene)n(v)o(er)e(an)o(y)i(of)0 2724 y(the)g(IEEE-754)d(e)o(xceptions)h(Di)n(vision)h(by)g(Zero,)h(Ov)o (er\003o)n(w)-5 b(,)21 b(or)i(In)m(v)n(alid)e(Operation)g(occurs.)31 b(In)23 b(tandem)e(with)i(a)g(pair)g(of)f(wrapper)0 2823 y(macros)h(that)i(are)f(inserted)f(into)h(the)g(C)h(code)f(comprising)e (your)h(p)o(ython)f(system,)j FJ(SIGFPE)f FN(is)h(trapped)e(and)g(con)m (v)o(erted)f(into)i(the)0 2923 y(Python)19 b FJ(FloatingPointError)e FN(e)o(xception.)0 3070 y(The)j FJ(fpectl)f FN(module)g(de\002nes)h (the)g(follo)n(wing)f(functions)g(and)g(may)h(raise)h(the)f(gi)n(v)o (en)f(e)o(xception:)0 3217 y FD(turnon_sigfpe)p FJ(\(\))208 3316 y FN(T)l(urn)g(on)h(the)g(generation)e(of)i FJ(SIGFPE)p FN(,)f(and)h(set)h(up)f(an)g(appropriate)e(signal)i(handler)-5 b(.)0 3463 y FD(turnoff_sigfpe)p FJ(\(\))208 3563 y FN(Reset)21 b(def)o(ault)e(handling)g(of)g(\003oating)h(point)f(e)o(xceptions.)0 3710 y FL(exception)g FD(FloatingPointError)208 3809 y FN(After)24 b FJ(turnon_sigfpe\(\))e FN(has)i(been)g(e)o(x)o(ecuted,) f(a)i(\003oating)e(point)h(operation)e(that)i(raises)h(one)f(of)g(the)g (IEEE-754)e(e)o(x-)208 3909 y(ceptions)d(Di)n(vision)h(by)f(Zero,)h(Ov) o(er\003o)n(w)-5 b(,)18 b(or)i(In)m(v)n(alid)f(operation)f(will)j(in)f (turn)g(raise)g(this)h(standard)e(Python)g(e)o(xception.)0 4194 y Fv(26.13.1)101 b(Example)0 4397 y FN(The)20 b(follo)n(wing)e(e)o (xample)h(demonstrates)g(ho)n(w)h(to)g(start)h(up)f(and)f(test)i (operation)e(of)g(the)i FJ(fpectl)e FN(module.)p 0 5549 3901 4 v 0 5649 a FI(852)2319 b(Chapter)23 b(26.)52 b(Python)24 b(Runtime)g(Ser)r(vices)p eop end %%Page: 853 865 TeXDict begin 853 864 bop 236 174 a FA(>>>)45 b(import)e(fpectl)236 266 y(>>>)i(import)e(fpetest)236 357 y(>>>)i(fpectl.turnon_sigfpe\(\)) 236 448 y(>>>)g(fpetest.test\(\))236 540 y(overflow)358 b(PASS)236 631 y(FloatingPointError:)42 b(Overflow)236 814 y(div)j(by)f(0)359 b(PASS)236 905 y(FloatingPointError:)42 b(Division)h(by)i(zero)326 996 y([)g(more)f(output)g(from)g(test)g (elided)g(])236 1088 y(>>>)h(import)e(math)236 1179 y(>>>)i (math.exp\(1000\))236 1270 y(Traceback)f(\(most)g(recent)f(call)i (last\):)326 1362 y(File)f("<stdin>",)f(line)h(1,)h(in)f(?)236 1453 y(FloatingPointError:)e(in)i(math_1)0 1876 y Fv(26.13.2)101 b(Limitations)29 b(and)g(other)f(consider)o(ations)0 2079 y FN(Setting)17 b(up)f(a)h(gi)n(v)o(en)f(processor)f(to)i(trap)f (IEEE-754)f(\003oating)h(point)g(errors)g(currently)f(requires)g (custom)i(code)f(on)g(a)h(per)n(-architecture)0 2179 y(basis.)26 b(Y)-9 b(ou)19 b(may)h(ha)n(v)o(e)f(to)i(modify)d FJ(fpectl)i FN(to)g(control)f(your)g(particular)g(hardw)o(are.)0 2326 y(Con)m(v)o(ersion)27 b(of)h(an)h(IEEE-754)d(e)o(xception)h(to)h (a)i(Python)d(e)o(xception)g(requires)h(that)g(the)h(wrapper)e(macros)h FJ(PyFPE_START_-)0 2425 y(PROTECT)21 b FN(and)h FJ(PyFPE_END_PROTECT)e FN(be)i(inserted)g(into)g(your)f(code)g(in)i(an)f(appropriate)e(f)o (ashion.)30 b(Python)21 b(itself)i(has)f(been)0 2525 y(modi\002ed)d(to)h(support)f(the)h FJ(fpectl)g FN(module,)f(b)n(ut)h (man)o(y)f(other)g(codes)h(of)g(interest)g(to)g(numerical)f(analysts)h (ha)n(v)o(e)g(not.)0 2672 y(The)g FJ(fpectl)f FN(module)g(is)i(not)f (thread-safe.)0 2819 y FL(See)h(Also:)0 2965 y FN(Some)e(\002les)h(in)g (the)f(source)g(distrib)n(ution)f(may)h(be)g(interesting)g(in)g (learning)f(more)h(about)f(ho)n(w)h(this)h(module)e(operates.)24 b(The)19 b(include)0 3065 y(\002le)27 b(`)p FO(Include/p)n(yfpe)o(.h)p FN(')22 b(discusses)28 b(the)e(implementation)f(of)h(this)h(module)f (at)h(some)f(length.)44 b(`)p FO(Modules/fpetestmodule)o(.c)p FN(')21 b(gi)n(v)o(es)0 3165 y(se)n(v)o(eral)f(e)o(xamples)f(of)h(use.) 25 b(Man)o(y)19 b(additional)g(e)o(xamples)g(can)h(be)g(found)e(in)j(`) p FO(Objects/\003oatobject.c)p FN('.)p 0 5549 3901 4 v 0 5649 a FI(26.13.)52 b FJ(fpectl)22 b FI(\227)h(Floating)i(point)f (e)n(xception)f(control)1905 b(853)p eop end %%Page: 854 866 TeXDict begin 854 865 bop 0 5549 3901 4 v 0 5649 a FI(854)p eop end %%Page: 855 867 TeXDict begin 855 866 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)2990 427 y FG(TWENTYSEVEN)p 0 515 V 1368 978 a FT(Custom)58 b(Python)g(Inter)6 b(preters)0 1466 y FN(The)18 b(modules)f(described)g (in)h(this)h(chapter)e(allo)n(w)i(writing)e(interf)o(aces)h(similar)g (to)h(Python')-5 b(s)17 b(interacti)n(v)o(e)g(interpreter)-5 b(.)23 b(If)18 b(you)g(w)o(ant)g(a)0 1566 y(Python)h(interpreter)f (that)h(supports)g(some)g(special)h(feature)f(in)h(addition)e(to)i(the) f(Python)g(language,)f(you)g(should)h(look)g(at)h(the)g FJ(code)0 1665 y FN(module.)54 b(\(The)29 b FJ(codeop)h FN(module)f(is)i(lo)n(wer)n(-le)n(v)o(el,)g(used)f(to)g(support)f (compiling)f(a)j(possibly-incomplete)c(chunk)i(of)h(Python)0 1765 y(code.\))0 1912 y(The)20 b(full)g(list)h(of)f(modules)f (described)g(in)h(this)h(chapter)e(is:)50 2055 y FD(code)198 b FN(Base)21 b(classes)h(for)d(interacti)n(v)o(e)g(Python)g (interpreters.)50 2155 y FD(codeop)98 b FN(Compile)20 b(\(possibly)f(incomplete\))g(Python)g(code.)0 2457 y FE(27.1)121 b Fx(code)32 b FE(\227)h(Inter)t(preter)i(base)g(classes)0 2690 y FN(The)29 b FJ(code)g FN(module)e(pro)o(vides)h(f)o(acilities)h (to)h(implement)d(read-e)n(v)n(al-print)f(loops)j(in)g(Python.)51 b(T)-7 b(w)o(o)29 b(classes)h(and)f(con)m(v)o(enience)0 2790 y(functions)19 b(are)h(included)f(which)g(can)h(be)g(used)g(to)h (b)n(uild)e(applications)g(which)h(pro)o(vide)e(an)i(interacti)n(v)o(e) f(interpreter)g(prompt.)0 2937 y FL(class)i FD(InteractiveInterpreter)p FJ(\()p FC([)p FK(locals)12 b FC(])p FJ(\))208 3036 y FN(This)23 b(class)g(deals)g(with)g(parsing)f(and)g(interpreter)g (state)h(\(the)g(user')-5 b(s)23 b(namespace\);)f(it)i(does)f(not)f (deal)h(with)g(input)f(b)n(uf)n(fering)208 3136 y(or)i(prompting)f(or)i (input)f(\002le)i(naming)d(\(the)i(\002lename)g(is)h(al)o(w)o(ays)f (passed)g(in)g(e)o(xplicitly\).)38 b(The)25 b(optional)f FK(locals)h FN(ar)o(gument)208 3236 y(speci\002es)20 b(the)g(dictionary)e(in)i(which)g(code)f(will)i(be)f(e)o(x)o(ecuted;)e (it)j(def)o(aults)e(to)h(a)h(ne)n(wly)e(created)g(dictionary)f(with)i (k)o(e)o(y)g FJ('__-)208 3335 y(name__')f FN(set)i(to)f FJ('__console__')f FN(and)g(k)o(e)o(y)h FJ('__doc__')f FN(set)i(to)f FJ(None)p FN(.)0 3482 y FL(class)h FD(InteractiveConsole) p FJ(\()p FC([)p FK(locals)p FC([)p FK(,)16 b(\002lename)c FC(])g(])p FJ(\))208 3582 y FN(Closely)79 b(emulate)f(the)h(beha)n (vior)f(of)g(the)h(interacti)n(v)o(e)f(Python)g(interpreter)-5 b(.)200 b(This)79 b(class)h(b)n(uilds)f(on)208 3681 y FJ(InteractiveInterpreter)43 b FN(and)i(adds)i(prompting)d(using)i(the) g(f)o(amiliar)g FJ(sys.ps1)g FN(and)g FJ(sys.ps2)p FN(,)52 b(and)208 3781 y(input)19 b(b)n(uf)n(fering.)0 3928 y FD(interact)p FJ(\()p FC([)p FK(banner)r FC([)p FK(,)e(r)m(eadfunc)p FC([)p FK(,)h(local)12 b FC(])g(])g(])p FJ(\))208 4027 y FN(Con)m(v)o(enience)21 b(function)h(to)i(run)f(a)h(read-e)n(v)n (al-print)c(loop.)35 b(This)24 b(creates)g(a)g(ne)n(w)g(instance)f(of)g FJ(InteractiveConsole)208 4127 y FN(and)30 b(sets)h FK(r)m(eadfunc)f FN(to)g(be)h(used)f(as)i(the)e FJ(raw_input\(\))g FN(method,)h(if)g (pro)o(vided.)54 b(If)30 b FK(local)h FN(is)g(pro)o(vided,)g(it)g(is)h (passed)208 4227 y(to)d(the)h FJ(InteractiveConsole)c FN(constructor)i(for)g(use)i(as)g(the)f(def)o(ault)g(namespace)f(for)h (the)g(interpreter)f(loop.)52 b(The)208 4326 y FJ(interact\(\))24 b FN(method)h(of)h(the)g(instance)g(is)h(then)f(run)g(with)g FK(banner)h FN(passed)f(as)h(the)f(banner)f(to)h(use,)i(if)e(pro)o (vided.)41 b(The)208 4426 y(console)19 b(object)h(is)h(discarded)e (after)g(use.)0 4573 y FD(compile_command)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)e(\002lename)p FC([)p FK(,)h(symbol)12 b FC(])g(])p FJ(\))208 4672 y FN(This)23 b(function)f(is)j(useful)e(for)g (programs)e(that)j(w)o(ant)g(to)f(emulate)g(Python')-5 b(s)23 b(interpreter)f(main)h(loop)g(\(a.k.a.)34 b(the)24 b(read-e)n(v)n(al-)208 4772 y(print)29 b(loop\).)52 b(The)29 b(trick)o(y)g(part)h(is)g(to)g(determine)e(when)i(the)f(user)h(has)g (entered)f(an)g(incomplete)g(command)e(that)j(can)g(be)208 4872 y(completed)21 b(by)i(entering)e(more)i(te)o(xt)g(\(as)g(opposed)e (to)j(a)f(complete)f(command)f(or)i(a)g(syntax)g(error\).)32 b(This)23 b(function)f FK(almost)208 4971 y FN(al)o(w)o(ays)e(mak)o(es) g(the)g(same)h(decision)e(as)i(the)f(real)h(interpreter)d(main)i(loop.) 208 5104 y FK(sour)m(ce)37 b FN(is)h(the)f(source)g(string;)46 b FK(\002lename)36 b FN(is)i(the)f(optional)f(\002lename)h(from)f (which)h(source)g(w)o(as)h(read,)j(def)o(aulting)35 b(to)208 5204 y FJ('<input>')p FN(;)16 b(and)g FK(symbol)g FN(is)h(the)f (optional)e(grammar)h(start)i(symbol,)e(which)h(should)f(be)h(either)g FJ('single')f FN(\(the)h(def)o(ault\))208 5303 y(or)j FJ('eval')p FN(.)p 0 5549 3901 4 v 3762 5649 a FI(855)p eop end %%Page: 856 868 TeXDict begin 856 867 bop 208 83 a FN(Returns)22 b(a)h(code)f(object)g (\(the)g(same)g(as)h FJ(compile\()p FK(sour)m(ce)p FJ(,)48 b FK(\002lename)p FJ(,)g FK(symbol)p FJ(\))p FN(\))22 b(if)g(the)h(command)d(is)k(complete)d(and)208 183 y(v)n(alid;)i FJ(None)f FN(if)h(the)f(command)e(is)k(incomplete;)e(raises)h FJ(SyntaxError)e FN(if)h(the)h(command)d(is)j(complete)f(and)f (contains)h(a)208 282 y(syntax)d(error)m(,)g(or)g(raises)i FJ(OverflowError)e FN(or)h FJ(ValueError)e FN(if)j(the)f(command)e (contains)i(an)g(in)m(v)n(alid)f(literal.)0 567 y Fv(27.1.1)101 b(Inter)o(activ)n(e)27 b(Inter)s(preter)j(Objects)0 765 y FD(runsource)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)18 b(\002lename)p FC([)p FK(,)g(symbol)12 b FC(])g(])p FJ(\))208 865 y FN(Compile)23 b(and)g(run)g(some)g(source)g(in)h(the)g (interpreter)-5 b(.)34 b(Ar)o(guments)22 b(are)i(the)f(same)h(as)h(for) e FJ(compile_command\(\))p FN(;)g(the)208 965 y(def)o(ault)c(for)h FK(\002lename)f FN(is)i FJ('<input>')p FN(,)e(and)g(for)h FK(symbol)g FN(is)h FJ('single')p FN(.)j(One)c(se)n(v)o(eral)g(things)f (can)h(happen:)349 1178 y FM(\017)o FN(The)79 b(input)f(is)i (incorrect;)108 b FJ(compile_command\(\))76 b FN(raised)j(an)g(e)o (xception)f(\()p FJ(SyntaxError)f FN(or)390 1278 y FJ(OverflowError)p FN(\).)100 b(A)46 b(syntax)f(traceback)f(will)j(be)e(printed)g(by)g (calling)g(the)h FJ(showsyntaxerror\(\))390 1377 y FN(method.)24 b FJ(runsource\(\))18 b FN(returns)i FJ(False)p FN(.)349 1510 y FM(\017)o FN(The)52 b(input)g(is)h(incomplete,)58 b(and)52 b(more)g(input)f(is)i(required;)67 b FJ(compile_command\(\))50 b FN(returned)g FJ(None)p FN(.)390 1610 y FJ(runsource\(\))19 b FN(returns)g FJ(True)p FN(.)349 1742 y FM(\017)o FN(The)k(input)f(is) i(complete;)g FJ(compile_command\(\))c FN(returned)i(a)h(code)g (object.)33 b(The)23 b(code)f(is)i(e)o(x)o(ecuted)d(by)i(calling)390 1842 y(the)i FJ(runcode\(\))g FN(\(which)f(also)i(handles)e(run-time)g (e)o(xceptions,)h(e)o(xcept)f(for)h FJ(SystemExit)p FN(\).)38 b FJ(runsource\(\))390 1942 y FN(returns)20 b FJ(False)p FN(.)208 2155 y(The)f(return)g(v)n(alue)h(can)g(be)g(used)g(to)g (decide)g(whether)f(to)h(use)h FJ(sys.ps1)e FN(or)h FJ(sys.ps2)g FN(to)g(prompt)e(the)j(ne)o(xt)e(line.)0 2302 y FD(runcode)p FJ(\()p FK(code)p FJ(\))208 2401 y FN(Ex)o(ecute)j(a)i(code)f(object.) 34 b(When)24 b(an)f(e)o(xception)f(occurs,)h FJ(showtraceback\(\))f FN(is)i(called)g(to)f(display)g(a)h(traceback.)34 b(All)208 2501 y(e)o(xceptions)18 b(are)i(caught)f(e)o(xcept)h FJ(SystemExit)p FN(,)e(which)i(is)h(allo)n(wed)f(to)g(propagate.)208 2634 y(A)k(note)f(about)g FJ(KeyboardInterrupt)p FN(:)30 b(this)25 b(e)o(xception)d(may)h(occur)g(else)n(where)g(in)h(this)h (code,)f(and)f(may)h(not)f(al)o(w)o(ays)208 2734 y(be)d(caught.)k(The) 19 b(caller)i(should)e(be)h(prepared)e(to)i(deal)g(with)h(it.)0 2880 y FD(showsyntaxerror)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 2980 y FN(Display)18 b(the)h(syntax)g(error)e(that)i (just)h(occurred.)i(This)d(does)g(not)g(display)f(a)h(stack)g(trace)g (because)g(there)f(isn')o(t)h(one)f(for)g(syntax)208 3080 y(errors.)29 b(If)22 b FK(\002lename)e FN(is)j(gi)n(v)o(en,)e(it)h (is)h(stuf)n(fed)e(into)h(the)g(e)o(xception)e(instead)h(of)h(the)g (def)o(ault)f(\002lename)h(pro)o(vided)d(by)i(Python')-5 b(s)208 3179 y(parser)m(,)15 b(because)h(it)g(al)o(w)o(ays)h(uses)g FJ('<string>')d FN(when)i(reading)e(from)h(a)i(string.)23 b(The)16 b(output)f(is)i(written)f(by)f(the)h FJ(write\(\))208 3279 y FN(method.)0 3426 y FD(showtraceback)p FJ(\(\))208 3525 y FN(Display)g(the)i(e)o(xception)d(that)i(just)h(occurred.)j(W)-7 b(e)19 b(remo)o(v)o(e)c(the)i(\002rst)h(stack)f(item)g(because)g(it)h (is)g(within)f(the)g(interpreter)e(object)208 3625 y(implementation.)22 b(The)e(output)f(is)i(written)f(by)g(the)g FJ(write\(\))g FN(method.)0 3772 y FD(write)p FJ(\()p FK(data)p FJ(\))208 3872 y FN(Write)h(a)g(string)f(to)h(the)g(standard)e(error)g(stream)i (\()p FJ(sys.stderr)p FN(\).)j(Deri)n(v)o(ed)19 b(classes)j(should)e(o) o(v)o(erride)e(this)j(to)g(pro)o(vide)e(the)208 3971 y(appropriate)e(output)i(handling)g(as)i(needed.)0 4256 y Fv(27.1.2)101 b(Inter)o(activ)n(e)27 b(Console)i(Objects)0 4459 y FN(The)23 b FJ(InteractiveConsole)d FN(class)k(is)g(a)f (subclass)g(of)g FJ(InteractiveInterpreter)p FN(,)d(and)j(so)g(of)n (fers)f(all)i(the)f(methods)0 4559 y(of)d(the)g(interpreter)f(objects)h (as)h(well)f(as)h(the)f(follo)n(wing)f(additions.)0 4705 y FD(interact)p FJ(\()p FC([)p FK(banner)14 b FC(])p FJ(\))208 4805 y FN(Closely)j(emulate)g(the)h(interacti)n(v)o(e)e (Python)g(console.)24 b(The)17 b(optional)f(banner)g(ar)o(gument)f (specify)i(the)g(banner)f(to)i(print)f(before)208 4905 y(the)24 b(\002rst)i(interaction;)f(by)g(def)o(ault)f(it)h(prints)f(a)i (banner)d(similar)i(to)f(the)h(one)f(printed)g(by)g(the)h(standard)e (Python)h(interpreter)m(,)208 5004 y(follo)n(wed)15 b(by)i(the)g(class) i(name)d(of)h(the)g(console)g(object)g(in)g(parentheses)f(\(so)h(as)h (not)f(to)h(confuse)e(this)h(with)h(the)f(real)g(interpreter)208 5104 y(\226)j(since)g(it')-5 b(s)21 b(so)g(close!\).)0 5251 y FD(push)p FJ(\()p FK(line)p FJ(\))208 5350 y FN(Push)k(a)h(line) g(of)f(source)g(te)o(xt)g(to)h(the)f(interpreter)-5 b(.)40 b(The)25 b(line)h(should)e(not)i(ha)n(v)o(e)f(a)h(trailing)e(ne)n (wline;)k(it)e(may)f(ha)n(v)o(e)g(internal)p 0 5549 3901 4 v 0 5649 a FI(856)2259 b(Chapter)23 b(27.)52 b(Custom)24 b(Python)f(Inter)r(preters)p eop end %%Page: 857 869 TeXDict begin 857 868 bop 208 83 a FN(ne)n(wlines.)56 b(The)31 b(line)f(is)i(appended)d(to)i(a)g(b)n(uf)n(fer)f(and)g(the)h (interpreter')-5 b(s)29 b FJ(runsource\(\))h FN(method)f(is)j(called)f (with)g(the)208 183 y(concatenated)22 b(contents)i(of)h(the)f(b)n(uf)n (fer)g(as)h(source.)38 b(If)24 b(this)i(indicates)e(that)h(the)g (command)d(w)o(as)k(e)o(x)o(ecuted)d(or)h(in)m(v)n(alid,)h(the)208 282 y(b)n(uf)n(fer)16 b(is)i(reset;)h(otherwise,)e(the)h(command)e(is)i (incomplete,)f(and)g(the)g(b)n(uf)n(fer)g(is)h(left)g(as)g(it)h(w)o(as) f(after)f(the)h(line)g(w)o(as)g(appended.)208 382 y(The)23 b(return)g(v)n(alue)h(is)h FJ(True)e FN(if)i(more)e(input)g(is)i (required,)e FJ(False)h FN(if)h(the)f(line)g(w)o(as)h(dealt)f(with)g (in)g(some)g(w)o(ay)g(\(this)h(is)g(the)208 482 y(same)20 b(as)h FJ(runsource\(\))p FN(\).)0 628 y FD(resetbuffer)p FJ(\(\))208 728 y FN(Remo)o(v)o(e)e(an)o(y)g(unhandled)f(source)h(te)o (xt)h(from)f(the)h(input)g(b)n(uf)n(fer)-5 b(.)0 875 y FD(raw_input)p FJ(\()p FC([)p FK(pr)l(ompt)13 b FC(])p FJ(\))208 975 y FN(Write)18 b(a)h(prompt)e(and)g(read)h(a)h(line.)24 b(The)18 b(returned)e(line)j(does)f(not)f(include)h(the)g(trailing)g (ne)n(wline.)23 b(When)18 b(the)g(user)h(enters)f(the)210 1074 y FH(E)t(O)t(F)24 b FN(k)o(e)o(y)e(sequence,)f FJ(EOFError)g FN(is)j(raised.)30 b(The)22 b(base)h(implementation)d(uses)j(the)f(b)n (uilt-in)f(function)g FJ(raw_input\(\))p FN(;)208 1174 y(a)f(subclass)h(may)e(replace)h(this)h(with)f(a)g(dif)n(ferent)f (implementation.)0 1501 y FE(27.2)121 b Fx(codeop)32 b FE(\227)h(Compile)g(Python)i(code)0 1734 y FN(The)20 b FJ(codeop)g FN(module)f(pro)o(vides)f(utilities)j(upon)e(which)h(the) g(Python)g(read-e)n(v)n(al-print)d(loop)i(can)h(be)g(emulated,)f(as)j (is)f(done)e(in)i(the)0 1834 y FJ(code)g FN(module.)28 b(As)22 b(a)g(result,)g(you)e(probably)f(don')o(t)h(w)o(ant)i(to)g(use) f(the)h(module)e(directly;)h(if)h(you)f(w)o(ant)g(to)h(include)f(such)g (a)h(loop)e(in)0 1933 y(your)f(program)f(you)h(probably)f(w)o(ant)i(to) h(use)f(the)g FJ(code)g FN(module)f(instead.)0 2080 y(There)g(are)h(tw) o(o)h(parts)f(to)g(this)h(job:)104 2310 y(1.)41 b(Being)24 b(able)g(to)g(tell)h(if)g(a)g(line)f(of)g(input)f(completes)h(a)h (Python)e(statement:)33 b(in)24 b(short,)h(telling)f(whether)f(to)i (print)e(`)p FJ(>>>)49 b FN(')25 b(or)208 2410 y(`)p FJ(...)48 b FN(')26 b(ne)o(xt.)104 2576 y(2.)41 b(Remembering)19 b(which)i(future)g(statements)h(the)f(user)h(has)g(entered,)e(so)i (subsequent)f(input)f(can)i(be)g(compiled)e(with)i(these)f(in)208 2675 y(ef)n(fect.)0 2905 y(The)f FJ(codeop)f FN(module)g(pro)o(vides)g (a)h(w)o(ay)h(of)f(doing)e(each)i(of)g(these)h(things,)e(and)h(a)g(w)o (ay)h(of)e(doing)g(them)h(both.)0 3052 y(T)-7 b(o)20 b(do)g(just)h(the)f(former:)0 3199 y FD(compile_command)p FJ(\()p FK(sour)m(ce)p FC([)p FK(,)d(\002lename)p FC([)p FK(,)h(symbol)12 b FC(])g(])p FJ(\))208 3299 y FN(T)m(ries)27 b(to)h(compile)e FK(sour)m(ce)p FN(,)j(which)e(should)f(be)i(a)f (string)g(of)g(Python)g(code)f(and)h(return)f(a)i(code)f(object)g(if)g FK(sour)m(ce)h FN(is)g(v)n(alid)208 3398 y(Python)36 b(code.)75 b(In)37 b(that)g(case,)42 b(the)37 b(\002lename)g(attrib)n (ute)g(of)g(the)g(code)g(object)g(will)h(be)f FK(\002lename)p FN(,)j(which)d(def)o(aults)f(to)208 3498 y FJ('<input>')p FN(.)23 b(Returns)d FJ(None)g FN(if)h FK(sour)m(ce)f FN(is)h FK(not)f FN(v)n(alid)g(Python)f(code,)g(b)n(ut)h(is)h(a)g (pre\002x)e(of)h(v)n(alid)g(Python)f(code.)208 3631 y(If)e(there)g(is)i (a)f(problem)e(with)i FK(sour)m(ce)p FN(,)g(an)g(e)o(xception)e(will)i (be)g(raised.)24 b FJ(SyntaxError)16 b FN(is)j(raised)e(if)h(there)f (is)i(in)m(v)n(alid)e(Python)208 3730 y(syntax,)i(and)g FJ(OverflowError)g FN(or)h FJ(ValueError)f FN(if)h(there)g(is)h(an)f (in)m(v)n(alid)f(literal.)208 3863 y(The)i FK(symbol)g FN(ar)o(gument)f(determines)g(whether)h FK(sour)m(ce)g FN(is)i(compiled)d(as)i(a)g(statement)f(\()p FJ('single')p FN(,)g(the)g(def)o(ault\))g(or)g(as)i(an)208 3963 y(e)o(xpression)18 b(\()p FJ('eval')p FN(\).)24 b(An)o(y)19 b(other)h(v)n(alue)f(will)i (cause)f FJ(ValueError)f FN(to)h(be)h(raised.)208 4096 y FL(Ca)n(v)o(eat:)31 b FN(It)25 b(is)g(possible)f(\(b)n(ut)g(not)g (lik)o(ely\))g(that)h(the)f(parser)g(stops)h(parsing)e(with)h(a)h (successful)f(outcome)f(before)g(reaching)208 4195 y(the)e(end)g(of)h (the)g(source;)f(in)h(this)h(case,)f(trailing)f(symbols)g(may)g(be)h (ignored)e(instead)h(of)h(causing)f(an)g(error)-5 b(.)29 b(F)o(or)22 b(e)o(xample,)e(a)208 4295 y(backslash)g(follo)n(wed)g(by)h (tw)o(o)h(ne)n(wlines)f(may)g(be)g(follo)n(wed)f(by)h(arbitrary)f (garbage.)26 b(This)21 b(will)i(be)e(\002x)o(ed)g(once)f(the)i(API)f (for)208 4394 y(the)f(parser)f(is)i(better)-5 b(.)0 4541 y FL(class)21 b FD(Compile)p FJ(\(\))208 4641 y FN(Instances)e(of)h (this)h(class)g(ha)n(v)o(e)e FJ(__call__\(\))g FN(methods)g(identical)h (in)g(signature)f(to)i(the)f(b)n(uilt-in)f(function)g FJ(compile\(\))p FN(,)208 4741 y(b)n(ut)27 b(with)h(the)g(dif)n (ference)d(that)j(if)g(the)g(instance)f(compiles)g(program)f(te)o(xt)h (containing)f(a)i FJ(__future__)e FN(statement,)k(the)208 4840 y(instance)19 b(')l(remembers')f(and)i(compiles)f(all)i (subsequent)e(program)f(te)o(xts)i(with)h(the)f(statement)g(in)g (force.)0 4987 y FL(class)h FD(CommandCompiler)p FJ(\(\))208 5087 y FN(Instances)g(of)g(this)h(class)h(ha)n(v)o(e)e FJ(__call__\(\))f FN(methods)h(identical)g(in)g(signature)g(to)h FJ(compile_command\(\))p FN(;)d(the)j(dif-)208 5186 y(ference)k(is)j (that)f(if)g(the)f(instance)h(compiles)f(program)e(te)o(xt)j (containing)e(a)i FJ(__future__)e FN(statement,)j(the)f(instance)f(')l (re-)208 5286 y(members')18 b(and)i(compiles)f(all)i(subsequent)e (program)f(te)o(xts)i(with)h(the)f(statement)g(in)g(force.)p 0 5549 3901 4 v 0 5649 a FI(27.2.)52 b FJ(codeop)22 b FI(\227)h(Compile)i(Python)e(code)2309 b(857)p eop end %%Page: 858 870 TeXDict begin 858 869 bop 0 83 a FN(A)29 b(note)e(on)h(v)o(ersion)f (compatibility:)39 b(the)28 b FJ(Compile)g FN(and)f FJ(CommandCompiler) f FN(are)i(ne)n(w)g(in)g(Python)f(2.2.)48 b(If)28 b(you)f(w)o(ant)h(to) 0 183 y(enable)20 b(the)g(future-tracking)d(features)i(of)h(2.2)g(b)n (ut)g(also)h(retain)f(compatibility)e(with)j(2.1)e(and)h(earlier)g(v)o (ersions)f(of)h(Python)f(you)h(can)0 282 y(either)g(write)236 520 y FA(try:)416 612 y(from)44 b(codeop)g(import)f(CommandCompiler)416 703 y(compile_command)f(=)j(CommandCompiler\(\))416 794 y(del)f(CommandCompiler)236 886 y(except)g(ImportError:)416 977 y(from)g(codeop)g(import)f(compile_command)0 1264 y FN(which)20 b(is)h(a)f(lo)n(w-impact)f(change,)g(b)n(ut)h(introduces) f(possibly)g(unw)o(anted)g(global)g(state)i(into)f(your)f(program,)f (or)i(you)f(can)h(write:)236 1502 y FA(try:)416 1593 y(from)44 b(codeop)g(import)f(CommandCompiler)236 1684 y(except)h(ImportError:)416 1776 y(def)g(CommandCompiler\(\):)595 1867 y(from)g(codeop)g(import)g(compile_command)595 1958 y(return)g(compile_command)0 2245 y FN(and)20 b(then)f(call)i FJ(CommandCompiler)d FN(e)n(v)o(ery)h(time)h(you)f(need)h(a)h(fresh)e (compiler)g(object.)p 0 5549 3901 4 v 0 5649 a FI(858)2259 b(Chapter)23 b(27.)52 b(Custom)24 b(Python)f(Inter)r(preters)p eop end %%Page: 859 871 TeXDict begin 859 870 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3030 427 y FG(TWENTYEIGHT)p 0 515 V 1952 978 a FT(Restr)s(icted)58 b(Ex)-6 b(ecution)p 0 1385 3901 17 v 0 1759 17 374 v 75 1501 a FL(W)h(ar)o(ning:)49 b FN(In)19 b(Python)f(2.3)g(these)i (modules)e(ha)n(v)o(e)h(been)f(disabled)h(due)f(to)i(v)n(arious)e(kno)n (wn)g(and)g(not)h(readily)g(\002xable)f(security)75 1600 y(holes.)43 b(The)25 b(modules)h(are)g(still)h(documented)d(here)h(to)i (help)e(in)i(reading)d(old)i(code)g(that)g(uses)h(the)f FJ(rexec)g FN(and)g FJ(Bastion)75 1700 y FN(modules.)p 3883 1759 V 0 1776 3901 17 v 0 1931 a FK(Restricted)16 b(e)n(xecution)g FN(is)h(the)f(basic)h(frame)n(w)o(ork)d(in)i(Python)f (that)i(allo)n(ws)f(for)g(the)g(se)o(gre)o(gation)e(of)i(trusted)f(and) h(untrusted)f(code.)23 b(The)0 2030 y(frame)n(w)o(ork)c(is)k(based)e (on)g(the)h(notion)e(that)h(trusted)g(Python)g(code)g(\(a)g FK(supervisor)p FN(\))g(can)h(create)f(a)h(\223padded)e(cell')h(\(or)g (en)m(vironment\))0 2130 y(with)h(limited)g(permissions,)f(and)g(run)g (the)h(untrusted)f(code)g(within)g(this)i(cell.)30 b(The)21 b(untrusted)g(code)g(cannot)g(break)f(out)i(of)g(its)g(cell,)0 2230 y(and)c(can)g(only)g(interact)f(with)i(sensiti)n(v)o(e)f(system)h (resources)e(through)f(interf)o(aces)i(de\002ned)g(and)f(managed)g(by)h (the)g(trusted)g(code.)24 b(The)0 2329 y(term)e(\223restricted)f(e)o(x) o(ecution\224)e(is)k(f)o(a)n(v)n(ored)e(o)o(v)o(er)f (\223safe-Python\224)g(since)i(true)f(safety)h(is)g(hard)f(to)h (de\002ne,)f(and)h(is)g(determined)e(by)i(the)0 2429 y(w)o(ay)17 b(the)h(restricted)e(en)m(vironment)f(is)j(created.)23 b(Note)17 b(that)h(the)f(restricted)g(en)m(vironments)d(can)j(be)g (nested,)h(with)f(inner)g(cells)h(creating)0 2529 y(subcells)i(of)g (lesser)m(,)g(b)n(ut)h(ne)n(v)o(er)d(greater)m(,)h(pri)n(vile)o(ge.)0 2675 y(An)i(interesting)g(aspect)h(of)f(Python')-5 b(s)20 b(restricted)h(e)o(x)o(ecution)f(model)g(is)j(that)e(the)h(interf)o (aces)f(presented)f(to)h(untrusted)f(code)h(usually)0 2775 y(ha)n(v)o(e)j(the)g(same)h(names)f(as)h(those)g(presented)e(to)i (trusted)f(code.)37 b(Therefore)22 b(no)i(special)h(interf)o(aces)f (need)f(to)i(be)f(learned)g(to)g(write)0 2875 y(code)g(designed)f(to)i (run)f(in)h(a)g(restricted)g(en)m(vironment.)35 b(And)24 b(because)g(the)h(e)o(xact)f(nature)g(of)h(the)f(padded)f(cell)j(is)f (determined)e(by)0 2974 y(the)f(supervisor)m(,)f(dif)n(ferent)f (restrictions)i(can)g(be)g(imposed,)g(depending)d(on)j(the)h (application.)29 b(F)o(or)22 b(e)o(xample,)f(it)i(might)f(be)g(deemed)0 3074 y(\223safe\224)31 b(for)g(untrusted)f(code)g(to)h(read)g(an)o(y)g (\002le)g(within)g(a)h(speci\002ed)f(directory)-5 b(,)32 b(b)n(ut)f(ne)n(v)o(er)f(to)h(write)g(a)h(\002le.)59 b(In)31 b(this)g(case,)k(the)0 3174 y(supervisor)22 b(may)g(rede\002ne) g(the)h(b)n(uilt-in)g FJ(open\(\))f FN(function)g(so)h(that)h(it)f (raises)h(an)f(e)o(xception)e(whene)n(v)o(er)g(the)j FK(mode)e FN(parameter)g(is)0 3273 y FJ('w')p FN(.)36 b(It)24 b(might)f(also)h(perform)e(a)j FJ(chroot\(\))p FN(-lik)o(e)d(operation)g(on)h(the)h FK(\002lename)f FN(parameter)m(,)g(such)g(that)h(root)f(is)i(al)o(w)o(ays)f(relati)n(v) o(e)0 3373 y(to)j(some)f(safe)h(\223sandbox\224)d(area)i(of)g(the)h (\002lesystem.)44 b(In)26 b(this)h(case,)h(the)f(untrusted)e(code)g(w)o (ould)h(still)i(see)f(an)f(b)n(uilt-in)g FJ(open\(\))0 3472 y FN(function)c(in)i(its)h(en)m(vironment,)c(with)j(the)g(same)g (calling)f(interf)o(ace.)35 b(The)24 b(semantics)g(w)o(ould)f(be)h (identical)f(too,)h(with)g FJ(IOError)p FN(s)0 3572 y(being)19 b(raised)h(when)g(the)g(supervisor)f(determined)f(that)i(an)g(unallo)n (w)o(able)f(parameter)g(is)i(being)e(used.)0 3719 y(The)24 b(Python)f(run-time)g(determines)g(whether)g(a)h(particular)f(code)h (block)f(is)i(e)o(x)o(ecuting)d(in)i(restricted)g(e)o(x)o(ecution)e (mode)h(based)h(on)0 3819 y(the)31 b(identity)f(of)h(the)g FJ(__builtins__)e FN(object)h(in)h(its)h(global)e(v)n(ariables:)46 b(if)31 b(this)g(is)h(\(the)f(dictionary)e(of\))h(the)h(standard)f FJ(__-)0 3918 y(builtin__)19 b FN(module,)g(the)h(code)f(is)i(deemed)e (to)i(be)f(unrestricted,)e(else)j(it)g(is)g(deemed)e(to)i(be)f (restricted.)0 4065 y(Python)h(code)h(e)o(x)o(ecuting)f(in)h (restricted)g(mode)g(f)o(aces)h(a)g(number)d(of)j(limitations)f(that)h (are)f(designed)f(to)i(pre)n(v)o(ent)e(it)i(from)f(escaping)0 4165 y(from)i(the)g(padded)f(cell.)39 b(F)o(or)24 b(instance,)h(the)g (function)e(object)h(attrib)n(ute)g FJ(func_globals)f FN(and)h(the)h(class)h(and)e(instance)g(object)0 4264 y(attrib)n(ute)c FJ(__dict__)f FN(are)h(una)n(v)n(ailable.)0 4411 y(T)-7 b(w)o(o)20 b(modules)g(pro)o(vide)e(the)i(frame)n(w)o(ork)e (for)i(setting)g(up)f(restricted)h(e)o(x)o(ecution)e(en)m(vironments:) 50 4554 y FD(rexec)198 b FN(Basic)21 b(restricted)f(e)o(x)o(ecution)e (frame)n(w)o(ork.)50 4654 y FD(Bastion)98 b FN(Pro)o(viding)18 b(restricted)i(access)h(to)f(objects.)0 4797 y FL(See)h(Also:)0 4944 y FK(Gr)o(ail)f(Home)g(P)-7 b(a)o(g)o(e)0 5043 y Fy(\()p FO(http://g)o(r)o(ail.sourcef)n(orge)n(.ne)o(t/)h Fy(\))208 5143 y FN(Grail,)24 b(an)f(Internet)f(bro)n(wser)g(written)h (in)h(Python,)f(uses)h(these)f(modules)f(to)i(support)e(Python)g (applets.)34 b(More)23 b(information)208 5242 y(on)c(the)i(use)f(of)g (Python')-5 b(s)19 b(restricted)h(e)o(x)o(ecution)e(mode)h(in)i(Grail)f (is)h(a)n(v)n(ailable)f(on)g(the)g(W)-7 b(eb)21 b(site.)p 0 5549 3901 4 v 3762 5649 a FI(859)p eop end %%Page: 860 872 TeXDict begin 860 871 bop 0 87 a FE(28.1)121 b Fx(rexec)32 b FE(\227)h(Restr)r(icted)h(e)l(x)l(ecution)i(fr)o(ame)n(w)o(or)r(k)0 320 y FN(Changed)19 b(in)h(v)o(ersion)f(2.3:)h(Disabled)g(module.)p 0 410 3901 17 v 0 602 17 192 v 75 526 a FL(W)-5 b(ar)o(ning:)50 b FN(The)19 b(documentation)f(has)i(been)g(left)g(in)g(place)g(to)h (help)e(in)i(reading)d(old)i(code)g(that)g(uses)h(the)f(module.)p 3883 602 V 0 618 3901 17 v 0 773 a(This)38 b(module)f(contains)h(the)g FJ(RExec)g FN(class,)43 b(which)38 b(supports)f FJ(r_eval\(\))p FN(,)42 b FJ(r_execfile\(\))p FN(,)e FJ(r_exec\(\))p FN(,)i(and)c FJ(r_-)0 873 y(import\(\))27 b FN(methods,)i(which)f(are)g (restricted)f(v)o(ersions)g(of)h(the)g(standard)f(Python)g(functions)g FJ(eval\(\))p FN(,)i FJ(execfile\(\))e FN(and)0 972 y(the)18 b FJ(exec)g FN(and)f FJ(import)h FN(statements.)24 b(Code)18 b(e)o(x)o(ecuted)e(in)j(this)f(restricted)g(en)m(vironment)d(will)k (only)e(ha)n(v)o(e)g(access)i(to)f(modules)f(and)0 1072 y(functions)i(that)h(are)g(deemed)f(safe;)i(you)e(can)h(subclass)g FJ(RExec)g FN(to)h(add)e(or)h(remo)o(v)o(e)e(capabilities)i(as)h (desired.)p 0 1162 V 0 1735 17 574 v 75 1278 a FL(W)-5 b(ar)o(ning:)59 b FN(While)23 b(the)f FJ(rexec)g FN(module)g(is)h (designed)e(to)i(perform)d(as)k(described)d(belo)n(w)-5 b(,)22 b(it)h(does)f(ha)n(v)o(e)g(a)h(fe)n(w)g(kno)n(wn)e(vul-)75 1377 y(nerabilities)k(which)g(could)g(be)g(e)o(xploited)f(by)h (carefully)g(written)g(code.)41 b(Thus)25 b(it)h(should)f(not)g(be)h (relied)f(upon)f(in)i(situations)75 1477 y(requiring)f(\223production)g (ready\224)i(security)-5 b(.)46 b(In)27 b(such)h(situations,)h(e)o(x)o (ecution)d(via)h(sub-processes)g(or)g(v)o(ery)g(careful)f(\223cleans-) 75 1576 y(ing\224)i(of)h(both)f(code)h(and)f(data)h(to)h(be)f (processed)f(may)g(be)h(necessary)-5 b(.)51 b(Alternati)n(v)o(ely)-5 b(,)29 b(help)g(in)g(patching)f(kno)n(wn)f FJ(rexec)75 1676 y FN(vulnerabilities)19 b(w)o(ould)g(be)h(welcomed.)p 3883 1735 V 0 1752 3901 17 v 0 1907 a FL(Note:)j FN(The)16 b FJ(RExec)h FN(class)h(can)f(pre)n(v)o(ent)e(code)h(from)g(performing) e(unsafe)j(operations)e(lik)o(e)i(reading)f(or)h(writing)f(disk)h (\002les,)h(or)f(using)0 2007 y(TCP/IP)27 b(sock)o(ets.)45 b(Ho)n(we)n(v)o(er)m(,)26 b(it)h(does)f(not)h(protect)e(against)h(code) g(using)g(e)o(xtremely)f(lar)o(ge)h(amounts)f(of)i(memory)e(or)h (processor)0 2106 y(time.)0 2253 y FL(class)21 b FD(RExec)p FJ(\()p FC([)p FK(hooks)p FC([)p FK(,)c(verbose)12 b FC(])g(])p FJ(\))208 2353 y FN(Returns)20 b(an)g(instance)g(of)f(the)i FJ(RExec)e FN(class.)208 2480 y FK(hooks)g FN(is)h(an)g(instance)f(of)h (the)g FJ(RHooks)f FN(class)h(or)g(a)g(subclass)g(of)g(it.)25 b(If)20 b(it)g(is)h(omitted)e(or)g FJ(None)p FN(,)h(the)f(def)o(ault)g FJ(RHooks)h FN(class)208 2580 y(is)25 b(instantiated.)37 b(Whene)n(v)o(er)23 b(the)h FJ(rexec)g FN(module)f(searches)h(for)g(a)h (module)e(\(e)n(v)o(en)g(a)i(b)n(uilt-in)f(one\))f(or)i(reads)f(a)h (module')-5 b(s)208 2680 y(code,)18 b(it)h(doesn')o(t)f(actually)g(go)g (out)h(to)g(the)g(\002le)g(system)g(itself.)25 b(Rather)m(,)19 b(it)g(calls)h(methods)e(of)g(an)h FJ(RHooks)f FN(instance)h(that)g(w)o (as)208 2779 y(passed)i(to)h(or)g(created)f(by)h(its)h(constructor)-5 b(.)28 b(\(Actually)-5 b(,)21 b(the)h FJ(RExec)g FN(object)f(doesn')o (t)f(mak)o(e)i(these)g(calls)h(\227)f(the)o(y)f(are)h(made)208 2879 y(by)d(a)h(module)e(loader)h(object)g(that')-5 b(s)20 b(part)f(of)g(the)h FJ(RExec)f FN(object.)24 b(This)c(allo)n(ws)g (another)e(le)n(v)o(el)h(of)h(\003e)o(xibility)-5 b(,)18 b(which)h(can)h(be)208 2979 y(useful)f(when)h(changing)e(the)i (mechanics)f(of)h FJ(import)g FN(within)g(the)g(restricted)g(en)m (vironment.\))208 3106 y(By)26 b(pro)o(viding)d(an)i(alternate)g FJ(RHooks)h FN(object,)g(we)g(can)f(control)g(the)h(\002le)g(system)g (accesses)g(made)f(to)h(import)f(a)h(module,)208 3206 y(without)16 b(changing)g(the)h(actual)g(algorithm)f(that)i(controls)e (the)i(order)e(in)i(which)e(those)i(accesses)g(are)f(made.)24 b(F)o(or)17 b(instance,)g(we)208 3305 y(could)k(substitute)h(an)g FJ(RHooks)g FN(object)f(that)i(passes)g(all)f(\002lesystem)h(requests)f (to)g(a)h(\002le)g(serv)o(er)e(else)n(where,)h(via)g(some)g(RPC)208 3405 y(mechanism)17 b(such)h(as)i(ILU.)e(Grail')-5 b(s)19 b(applet)f(loader)g(uses)h(this)g(to)g(support)e(importing)g(applets)h (from)g(a)h(URL)g(for)f(a)h(directory)-5 b(.)208 3532 y(If)20 b FK(verbose)g FN(is)h(true,)e(additional)g(deb)n(ugging)f (output)h(may)g(be)i(sent)f(to)g(standard)f(output.)0 3679 y(It)28 b(is)h(important)d(to)i(be)f(a)o(w)o(are)h(that)f(code)g (running)f(in)i(a)g(restricted)f(en)m(vironment)e(can)i(still)i(call)f (the)g FJ(sys.exit\(\))f FN(function.)0 3779 y(T)-7 b(o)29 b(disallo)n(w)g(restricted)g(code)f(from)g(e)o(xiting)g(the)h (interpreter)m(,)g(al)o(w)o(ays)g(protect)f(calls)i(that)f(cause)g (restricted)g(code)f(to)h(run)f(with)0 3879 y(a)i FJ(try)p FN(/)p FJ(except)e FN(statement)h(that)g(catches)g(the)g FJ(SystemExit)f FN(e)o(xception.)50 b(Remo)o(ving)28 b(the)h FJ(sys.exit\(\))f FN(function)g(from)0 3978 y(the)d(restricted) g(en)m(vironment)c(is)26 b(not)f(suf)n(\002cient)g(\227)g(the)g (restricted)g(code)f(could)g(still)i(use)f FJ(raise)49 b(SystemExit)p FN(.)38 b(Remo)o(ving)0 4078 y FJ(SystemExit)19 b FN(is)i(not)f(a)g(reasonable)f(option;)g(some)h(library)f(code)h(mak) o(es)g(use)g(of)g(this)h(and)f(w)o(ould)f(break)g(were)h(it)h(not)f(a)n (v)n(ailable.)0 4225 y FL(See)h(Also:)0 4372 y FK(Gr)o(ail)f(Home)g(P) -7 b(a)o(g)o(e)0 4471 y Fy(\()p FO(http://g)o(r)o(ail.sourcef)n(orge)n (.ne)o(t/)h Fy(\))208 4571 y FN(Grail)26 b(is)h(a)f(W)-7 b(eb)27 b(bro)n(wser)d(written)i(entirely)f(in)h(Python.)41 b(It)27 b(uses)f(the)g FJ(rexec)g FN(module)e(as)j(a)f(foundation)e (for)h(supporting)208 4670 y(Python)19 b(applets,)g(and)h(can)g(be)g (used)g(as)h(an)f(e)o(xample)f(usage)h(of)g(this)g(module.)0 4951 y Fv(28.1.1)101 b(REx)m(ec)28 b(Objects)0 5154 y FJ(RExec)20 b FN(instances)g(support)f(the)h(follo)n(wing)f(methods:)0 5300 y FD(r_eval)p FJ(\()p FK(code)p FJ(\))208 5400 y FK(code)f FN(must)i(either)f(be)h(a)g(string)f(containing)f(a)i(Python) f(e)o(xpression,)e(or)j(a)g(compiled)e(code)h(object,)g(which)g(will)h (be)g(e)n(v)n(aluated)p 0 5549 3901 4 v 0 5649 a FI(860)2493 b(Chapter)24 b(28.)52 b(Restr)q(icted)23 b(Ex)n(ecution)p eop end %%Page: 861 873 TeXDict begin 861 872 bop 208 83 a FN(in)18 b(the)h(restricted)f(en)m (vironment')-5 b(s)16 b FJ(__main__)h FN(module.)24 b(The)18 b(v)n(alue)g(of)g(the)h(e)o(xpression)e(or)h(code)g(object)g(will)h(be) g(returned.)0 230 y FD(r_exec)p FJ(\()p FK(code)p FJ(\))208 330 y FK(code)g FN(must)g(either)g(be)h(a)g(string)f(containing)f(one)h (or)h(more)e(lines)i(of)g(Python)e(code,)h(or)g(a)i(compiled)d(code)h (object,)g(which)g(will)208 429 y(be)h(e)o(x)o(ecuted)e(in)i(the)h (restricted)e(en)m(vironment')-5 b(s)18 b FJ(__main__)h FN(module.)0 576 y FD(r_execfile)p FJ(\()p FK(\002lename)p FJ(\))208 676 y FN(Ex)o(ecute)f(the)j(Python)e(code)g(contained)g(in)h (the)g(\002le)h FK(\002lename)e FN(in)i(the)f(restricted)f(en)m (vironment')-5 b(s)18 b FJ(__main__)h FN(module.)0 823 y(Methods)i(whose)g(names)g(be)o(gin)f(with)i(`)p FJ(s_)p FN(')f(are)g(similar)h(to)g(the)f(functions)f(be)o(ginning)f(with)j(`)p FJ(r_)p FN(',)f(b)n(ut)g(the)h(code)e(will)j(be)e(granted)0 922 y(access)g(to)f(restricted)g(v)o(ersions)f(of)h(the)g(standard)f (I/O)i(streams)f FJ(sys.stdin)p FN(,)f FJ(sys.stderr)p FN(,)f(and)i FJ(sys.stdout)p FN(.)0 1069 y FD(s_eval)p FJ(\()p FK(code)p FJ(\))208 1169 y FK(code)f FN(must)h(be)g(a)h(string) f(containing)e(a)j(Python)e(e)o(xpression,)f(which)i(will)h(be)f(e)n(v) n(aluated)f(in)h(the)g(restricted)g(en)m(vironment.)0 1316 y FD(s_exec)p FJ(\()p FK(code)p FJ(\))208 1415 y FK(code)27 b FN(must)h(be)g(a)g(string)g(containing)d(one)j(or)f(more)h (lines)g(of)g(Python)e(code,)j(which)f(will)g(be)g(e)o(x)o(ecuted)e(in) i(the)g(restricted)208 1515 y(en)m(vironment.)0 1662 y FD(s_execfile)p FJ(\()p FK(code)p FJ(\))208 1761 y FN(Ex)o(ecute)18 b(the)j(Python)e(code)g(contained)g(in)h(the)g(\002le) h FK(\002lename)e FN(in)i(the)f(restricted)f(en)m(vironment.)0 1908 y FJ(RExec)i FN(objects)h(must)g(also)g(support)f(v)n(arious)f (methods)h(which)g(will)i(be)f(implicitly)f(called)h(by)f(code)g(e)o(x) o(ecuting)f(in)i(the)g(restricted)0 2008 y(en)m(vironment.)29 b(Ov)o(erriding)21 b(these)i(methods)e(in)i(a)g(subclass)g(is)h(used)e (to)h(change)e(the)i(policies)g(enforced)d(by)j(a)g(restricted)f(en)m (viron-)0 2107 y(ment.)0 2254 y FD(r_import)p FJ(\()p FK(modulename)p FC([)p FK(,)16 b(globals)p FC([)p FK(,)j(locals)p FC([)p FK(,)g(fr)l(omlist)13 b FC(])f(])g(])p FJ(\))208 2354 y FN(Import)18 b(the)j(module)d FK(modulename)p FN(,)g(raising)i(an)g FJ(ImportError)f FN(e)o(xception)f(if)i(the)h (module)d(is)k(considered)c(unsafe.)0 2501 y FD(r_open)p FJ(\()p FK(\002lename)p FC([)p FK(,)f(mode)p FC([)p FK(,)i(b)n(ufsize) 12 b FC(])g(])p FJ(\))208 2600 y FN(Method)23 b(called)i(when)f FJ(open\(\))h FN(is)g(called)g(in)g(the)g(restricted)g(en)m(vironment.) 35 b(The)25 b(ar)o(guments)e(are)i(identical)f(to)h(those)g(of)208 2700 y FJ(open\(\))p FN(,)17 b(and)h(a)g(\002le)h(object)e(\(or)h(a)g (class)h(instance)f(compatible)e(with)j(\002le)f(objects\))g(should)f (be)h(returned.)k FJ(RExec)p FN(')-5 b(s)18 b(def)o(ault)208 2800 y(beha)n(viour)c(is)k(allo)n(w)f(opening)e(an)o(y)i(\002le)g(for)g (reading,)f(b)n(ut)h(forbidding)d(an)o(y)i(attempt)h(to)g(write)g(a)h (\002le.)24 b(See)18 b(the)f(e)o(xample)e(belo)n(w)208 2899 y(for)k(an)h(implementation)e(of)i(a)h(less)g(restricti)n(v)o(e)e FJ(r_open\(\))p FN(.)0 3046 y FD(r_reload)p FJ(\()p FK(module)p FJ(\))208 3146 y FN(Reload)h(the)g(module)f(object)g FK(module)p FN(,)g(re-parsing)f(and)i(re-initializing)f(it.)0 3293 y FD(r_unload)p FJ(\()p FK(module)p FJ(\))208 3392 y FN(Unload)g(the)h(module)f(object)g FK(module)h FN(\(remo)o(v)o(e)d (it)k(from)f(the)g(restricted)f(en)m(vironment')-5 b(s)18 b FJ(sys.modules)h FN(dictionary\).)0 3539 y(And)h(their)g(equi)n(v)n (alents)e(with)j(access)g(to)f(restricted)g(standard)f(I/O)h(streams:)0 3686 y FD(s_import)p FJ(\()p FK(modulename)p FC([)p FK(,)c(globals)p FC([)p FK(,)j(locals)p FC([)p FK(,)g(fr)l(omlist)13 b FC(])f(])g(])p FJ(\))208 3786 y FN(Import)18 b(the)j(module)d FK(modulename)p FN(,)g(raising)i(an)g FJ(ImportError)f FN(e)o(xception)f(if)i(the)h(module)d(is)k(considered)c(unsafe.)0 3932 y FD(s_reload)p FJ(\()p FK(module)p FJ(\))208 4032 y FN(Reload)i(the)g(module)f(object)g FK(module)p FN(,)g(re-parsing)f (and)i(re-initializing)f(it.)0 4179 y FD(s_unload)p FJ(\()p FK(module)p FJ(\))208 4279 y FN(Unload)g(the)h(module)f(object)g FK(module)p FN(.)0 4563 y Fv(28.1.2)101 b(De\002ning)29 b(restr)q(icted)g(en)n(vironments)0 4766 y FN(The)d FJ(RExec)f FN(class)i(has)f(the)g(follo)n(wing)e(class)j(attrib)n(utes,)g(which)e (are)h(used)f(by)h(the)g FJ(__init__\(\))e FN(method.)41 b(Changing)24 b(them)0 4866 y(on)d(an)g(e)o(xisting)g(instance)g(w)o (on')o(t)f(ha)n(v)o(e)h(an)o(y)f(ef)n(fect;)i(instead,)f(create)g(a)h (subclass)g(of)f FJ(RExec)g FN(and)f(assign)i(them)f(ne)n(w)g(v)n (alues)g(in)h(the)0 4966 y(class)f(de\002nition.)j(Instances)c(of)g (the)g(ne)n(w)g(class)h(will)g(then)f(use)g(those)g(ne)n(w)g(v)n (alues.)k(All)d(these)g(attrib)n(utes)f(are)g(tuples)g(of)g(strings.)0 5113 y FD(nok_builtin_names)208 5212 y FN(Contains)h(the)g(names)g(of)g (b)n(uilt-in)g(functions)e(which)i(will)h FK(not)f FN(be)g(a)n(v)n (ailable)g(to)h(programs)d(running)g(in)j(the)f(restricted)g(en)m(vi-) 208 5312 y(ronment.)29 b(The)23 b(v)n(alue)e(for)h FJ(RExec)g FN(is)i FJ(\('open',)48 b('reload',)g('__import__'\))p FN(.)30 b(\(This)22 b(gi)n(v)o(es)g(the)g(e)o(xceptions,)p 0 5549 3901 4 v 0 5649 a FI(28.1.)52 b FJ(rexec)22 b FI(\227)i(Restr)q(icted)f(e)n(x)n(ecution)f(fr)o(ame)n(w)o(or)q(k)1991 b(861)p eop end %%Page: 862 874 TeXDict begin 862 873 bop 208 83 a FN(because)24 b(by)h(f)o(ar)g(the)h (majority)e(of)h(b)n(uilt-in)g(functions)f(are)h(harmless.)40 b(A)26 b(subclass)g(that)f(w)o(ants)h(to)g(o)o(v)o(erride)d(this)j(v)n (ariable)208 183 y(should)16 b(probably)g(start)j(with)f(the)g(v)n (alue)f(from)g(the)h(base)g(class)h(and)e(concatenate)f(additional)h (forbidden)e(functions)i(\227)h(when)208 282 y(ne)n(w)i(dangerous)e(b)n (uilt-in)h(functions)g(are)h(added)f(to)h(Python,)f(the)o(y)h(will)h (also)f(be)g(added)f(to)i(this)f(module.\))0 429 y FD (ok_builtin_modules)208 529 y FN(Contains)e(the)h(names)g(of)g(b)n (uilt-in)f(modules)g(which)h(can)f(be)h(safely)g(imported.)k(The)c(v)n (alue)f(for)g FJ(RExec)h FN(is)h FJ(\('audioop',)208 628 y('array',)48 b('binascii',)g('cmath',)g('errno',)g('imageop',)g ('marshal',)g('math',)208 728 y('md5',)g('operator',)g('parser',)g ('regex',)g('select',)h('sha',)f('_sre',)h('strop',)208 828 y('struct',)f('time'\))p FN(.)e(A)28 b(similar)g(remark)f(about)f (o)o(v)o(erriding)f(this)j(v)n(ariable)f(applies)g(\227)h(use)g(the)g (v)n(alue)f(from)g(the)208 927 y(base)20 b(class)h(as)g(a)g(starting)e (point.)0 1074 y FD(ok_path)208 1174 y FN(Contains)24 b(the)g(directories)f(which)h(will)h(be)g(searched)e(when)h(an)g FJ(import)g FN(is)h(performed)d(in)j(the)f(restricted)g(en)m (vironment.)208 1273 y(The)19 b(v)n(alue)h(for)f FJ(RExec)h FN(is)h(the)g(same)f(as)h FJ(sys.path)e FN(\(at)i(the)f(time)g(the)g (module)f(is)i(loaded\))e(for)h(unrestricted)e(code.)0 1420 y FD(ok_posix_names)208 1520 y FN(Contains)31 b(the)h(names)f(of)g (the)h(functions)e(in)i(the)g FJ(os)g FN(module)e(which)h(will)i(be)e (a)n(v)n(ailable)h(to)f(programs)f(running)g(in)i(the)208 1620 y(restricted)41 b(en)m(vironment.)87 b(The)41 b(v)n(alue)h(for)f FJ(RExec)g FN(is)i FJ(\('error',)48 b('fstat',)h('listdir',)e('lstat',) 208 1719 y('readlink',)g('stat',)i('times',)f('uname',)g('getpid',)h ('getppid',)f('getcwd',)208 1819 y('getuid',)g('getgid',)g('geteuid',)g ('getegid'\))p FN(.)0 1966 y FD(ok_sys_names)208 2065 y FN(Contains)41 b(the)g(names)g(of)g(the)h(functions)d(and)i(v)n (ariables)g(in)g(the)h FJ(sys)f FN(module)f(which)h(will)h(be)f(a)n(v)n (ailable)g(to)h(pro-)208 2165 y(grams)22 b(running)e(in)j(the)g (restricted)f(en)m(vironment.)30 b(The)22 b(v)n(alue)g(for)g FJ(RExec)g FN(is)i FJ(\('ps1',)49 b('ps2',)f('copyright',)208 2265 y('version',)g('platform',)f('exit',)i('maxint'\))p FN(.)0 2411 y FD(ok_file_types)208 2511 y FN(Contains)15 b(the)h(\002le)h(types)f(from)f(which)g(modules)g(are)h(allo)n(wed)f (to)i(be)e(loaded.)23 b(Each)15 b(\002le)i(type)f(is)h(an)e(inte)o(ger) g(constant)h(de\002ned)208 2611 y(in)i(the)h FJ(imp)g FN(module.)k(The)18 b(meaningful)e(v)n(alues)i(are)h FJ(PY_SOURCE)p FN(,)e FJ(PY_COMPILED)p FN(,)g(and)h FJ(C_EXTENSION)p FN(.)f(The)h(v)n(alue)208 2710 y(for)i FJ(RExec)g FN(is)i FJ(\(C_EXTENSION,)47 b(PY_SOURCE\))p FN(.)19 b(Adding)g FJ(PY_COMPILED)h FN(in)g(subclasses)i(is)f(not)g(recommended;)208 2810 y(an)f(attack)o(er)h(could)e(e)o(xit)i(the)g(restricted)f(e)o(x)o (ecution)f(mode)h(by)g(putting)g(a)h(for)o(ged)d(byte-compiled)g (\002le)k(\(`)p FO(.p)n(yc)p FN('\))e(an)o(ywhere)e(in)208 2910 y(your)k(\002le)i(system,)g(for)e(e)o(xample)g(by)h(writing)g(it)h (to)f(`)p FO(/tmp)p FN(')g(or)g(uploading)e(it)j(to)f(the)h(`)p FO(/incoming)p FN(')d(directory)g(of)i(your)f(public)208 3009 y(FTP)e(serv)o(er)-5 b(.)0 3294 y Fv(28.1.3)101 b(An)28 b(e)m(xample)0 3497 y FN(Let)23 b(us)g(say)g(that)f(we)h(w)o (ant)g(a)g(slightly)g(more)e(relax)o(ed)h(polic)o(y)f(than)h(the)h (standard)e FJ(RExec)i FN(class.)33 b(F)o(or)22 b(e)o(xample,)g(if)h (we')l(re)f(willing)0 3597 y(to)e(allo)n(w)g(\002les)i(in)e(`)p FO(/tmp)p FN(')f(to)i(be)f(written,)g(we)g(can)g(subclass)h(the)f FJ(RExec)g FN(class:)236 3835 y FA(class)44 b (TmpWriterRExec\(rexec.RExec\):)416 3926 y(def)g(r_open\(self,)f(file,) h(mode='r',)f(buf=-1\):)595 4017 y(if)h(mode)h(in)f(\('r',)g('rb'\):) 774 4109 y(pass)595 4200 y(elif)g(mode)g(in)h(\('w',)f('wb',)g('a',)g ('ab'\):)774 4291 y(#)h(check)f(filename)f(:)i(must)f(begin)g(with)g (/tmp/)774 4383 y(if)h(file[:5]!='/tmp/':)954 4474 y(raise)f(IOError,)f ("can't)h(write)g(outside)f(/tmp")774 4565 y(elif)h (\(string.find\(file,)e('/../'\))i(>=)g(0)h(or)998 4657 y(file[:3])f(==)g('../')g(or)h(file[-3:])e(==)i('/..'\):)954 4748 y(raise)f(IOError,)f("'..')h(in)g(filename)g(forbidden")595 4839 y(else:)g(raise)g(IOError,)f("Illegal)h(open\(\))g(mode")595 4931 y(return)g(open\(file,)f(mode,)h(buf\))0 5170 y FN(Notice)29 b(that)h(the)g(abo)o(v)o(e)e(code)g(will)j(occasionally)d (forbid)g(a)i(perfectly)e(v)n(alid)h(\002lename;)34 b(for)29 b(e)o(xample,)h(code)f(in)h(the)f(restricted)0 5270 y(en)m(vironment)22 b(w)o(on')o(t)j(be)g(able)h(to)f(open)g(a)g(\002le)i(called)e(`)p FO(/tmp/f)n(oo/../bar)p FN('.)36 b(T)-7 b(o)26 b(\002x)g(this,)h(the)e FJ(r_open\(\))g FN(method)f(w)o(ould)h(ha)n(v)o(e)f(to)0 5369 y(simplify)17 b(the)g(\002lename)g(to)g(`)p FO(/tmp/bar)p FN(',)f(which)h(w)o(ould)f(require)g(splitting)i(apart)e(the)i (\002lename)f(and)f(performing)f(v)n(arious)h(operations)p 0 5549 3901 4 v 0 5649 a FI(862)2493 b(Chapter)24 b(28.)52 b(Restr)q(icted)23 b(Ex)n(ecution)p eop end %%Page: 863 875 TeXDict begin 863 874 bop 0 83 a FN(on)15 b(it.)24 b(In)15 b(cases)h(where)f(security)g(is)h(at)g(stak)o(e,)h(it)f(may)f(be)g (preferable)e(to)j(write)g(simple)f(code)g(which)g(is)h(sometimes)f(o)o (v)o(erly)f(restricti)n(v)o(e,)0 183 y(instead)20 b(of)g(more)f (general)g(code)h(that)g(is)h(also)g(more)e(comple)o(x)g(and)g(may)h (harbor)e(a)j(subtle)f(security)g(hole.)0 510 y FE(28.2)121 b Fx(Bastion)32 b FE(\227)g(Restr)r(icting)i(access)f(to)h(objects)0 743 y FN(Changed)19 b(in)h(v)o(ersion)f(2.3:)h(Disabled)g(module.)p 0 833 3901 17 v 0 1024 17 192 v 75 948 a FL(W)-5 b(ar)o(ning:)50 b FN(The)19 b(documentation)f(has)i(been)g(left)g(in)g(place)g(to)h (help)e(in)i(reading)d(old)i(code)g(that)g(uses)h(the)f(module.)p 3883 1024 V 0 1041 3901 17 v 0 1196 a(According)f(to)i(the)g (dictionary)-5 b(,)19 b(a)j(bastion)e(is)i(\223a)g(forti\002ed)e(area)h (or)g(position\224,)f(or)h(\223something)e(that)i(is)h(considered)e(a)h (stronghold.)-6 b(\224)0 1296 y(It')h(s)24 b(a)f(suitable)g(name)g(for) f(this)i(module,)e(which)h(pro)o(vides)e(a)j(w)o(ay)f(to)g(forbid)f (access)i(to)f(certain)g(attrib)n(utes)g(of)g(an)g(object.)33 b(It)24 b(must)0 1395 y(al)o(w)o(ays)g(be)f(used)g(with)h(the)f FJ(rexec)g FN(module,)g(in)g(order)f(to)i(allo)n(w)f(restricted-mode)e (programs)h(access)i(to)f(certain)g(safe)h(attrib)n(utes)0 1495 y(of)c(an)g(object,)f(while)i(den)o(ying)d(access)i(to)h(other)m (,)e(unsafe)g(attrib)n(utes.)0 1642 y FD(Bastion)p FJ(\()p FK(object)q FC([)p FK(,)f(\002lter)r FC([)p FK(,)i(name)p FC([)p FK(,)f(class)12 b FC(])g(])g(])p FJ(\))208 1741 y FN(Protect)21 b(the)g(object)g FK(object)q FN(,)g(returning)e(a)j (bastion)f(for)f(the)i(object.)27 b(An)o(y)21 b(attempt)g(to)g(access)h (one)f(of)g(the)h(object')-5 b(s)21 b(attrib)n(utes)208 1841 y(will)f(ha)n(v)o(e)g(to)g(be)g(appro)o(v)o(ed)d(by)j(the)g FK(\002lter)i FN(function;)d(if)h(the)g(access)h(is)g(denied)e(an)h FJ(AttributeError)e FN(e)o(xception)g(will)j(be)208 1941 y(raised.)208 2073 y(If)g(present,)g FK(\002lter)j FN(must)e(be)f(a)h (function)e(that)i(accepts)g(a)g(string)f(containing)f(an)h(attrib)n (ute)h(name,)f(and)g(returns)g(true)g(if)h(access)208 2173 y(to)g(that)h(attrib)n(ute)f(will)h(be)f(permitted;)g(if)h FK(\002lter)i FN(returns)c(f)o(alse,)j(the)e(access)h(is)g(denied.)31 b(The)22 b(def)o(ault)g(\002lter)g(denies)g(access)h(to)208 2273 y(an)o(y)c(function)g(be)o(ginning)f(with)i(an)h(underscore)d(\(`) p FJ(_)p FN('\).)24 b(The)c(bastion')-5 b(s)21 b(string)f (representation)e(will)j(be)g(`)p FJ(<Bastion)48 b(for)208 2372 y FK(name)p FJ(>)p FN(')19 b(if)h(a)h(v)n(alue)e(for)h FK(name)f FN(is)i(pro)o(vided;)d(otherwise,)h(`)p FJ(repr\()p FK(object)q FJ(\))p FN(')g(will)i(be)f(used.)208 2505 y FK(class)p FN(,)g(if)f(present,)g(should)g(be)g(a)h(subclass)g(of)f FJ(BastionClass)p FN(;)g(see)h(the)f(code)g(in)h(`)p FO(bastion.p)n(y)p FN(')d(for)i(the)g(details.)25 b(Ov)o(errid-)208 2605 y(ing)19 b(the)i(def)o(ault)e FJ(BastionClass)g FN(will)i(rarely)e(be)h(required.)0 2752 y FL(class)h FD(BastionClass)p FJ(\()p FK(g)o(etfunc,)16 b(name)p FJ(\))208 2851 y FN(Class)25 b(which)e(actually)g(implements)g(bastion) h(objects.)35 b(This)24 b(is)h(the)f(def)o(ault)f(class)i(used)f(by)f FJ(Bastion\(\))p FN(.)35 b(The)23 b FK(g)o(etfunc)208 2951 y FN(parameter)13 b(is)k(a)f(function)d(which)i(returns)g(the)g(v) n(alue)g(of)g(an)g(attrib)n(ute)g(which)g(should)g(be)g(e)o(xposed)f (to)h(the)h(restricted)f(e)o(x)o(ecution)208 3051 y(en)m(vironment)23 b(when)i(called)h(with)h(the)f(name)g(of)g(the)g(attrib)n(ute)g(as)h (the)f(only)f(parameter)-5 b(.)42 b FK(name)26 b FN(is)h(used)f(to)g (construct)g(the)208 3150 y FJ(repr\(\))19 b FN(of)h(the)g FJ(BastionClass)f FN(instance.)p 0 5549 3901 4 v 0 5649 a FI(28.2.)52 b FJ(Bastion)22 b FI(\227)h(Restr)q(icting)h(access)d(to) i(objects)1995 b(863)p eop end %%Page: 864 876 TeXDict begin 864 875 bop 0 5549 3901 4 v 0 5649 a FI(864)p eop end %%Page: 865 877 TeXDict begin 865 876 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3110 427 y FG(TWENTYNINE)p 0 515 V 2193 978 a FT(Impor)8 b(ting)57 b(Modules)0 1468 y FN(The)22 b(modules)f(described)g(in)i(this)g (chapter)e(pro)o(vide)f(ne)n(w)j(w)o(ays)f(to)h(import)e(other)h (Python)f(modules)g(and)h(hooks)f(for)h(customizing)0 1568 y(the)e(import)f(process.)0 1714 y(The)h(full)g(list)h(of)f (modules)f(described)g(in)h(this)h(chapter)e(is:)50 1858 y FD(imp)547 b FN(Access)21 b(the)f(implementation)e(of)i(the)g FJ(import)g FN(statement.)50 1957 y FD(zipimport)247 b FN(support)19 b(for)h(importing)e(Python)h(modules)g(from)g(ZIP)h (archi)n(v)o(es.)50 2057 y FD(pkgutil)347 b FN(Utilities)22 b(to)e(support)f(e)o(xtension)f(of)i(packages.)50 2157 y FD(modulefinder)97 b FN(Find)20 b(modules)f(used)h(by)g(a)h(script.) 50 2256 y FD(runpy)447 b FN(Locate)20 b(and)f(e)o(x)o(ecute)g(Python)g (modules)g(as)i(scripts)0 2559 y FE(29.1)121 b Fx(imp)33 b FE(\227)f(Access)h(the)h Fx(import)e FE(inter)s(nals)0 2792 y FN(This)19 b(module)e(pro)o(vides)g(an)i(interf)o(ace)f(to)g (the)h(mechanisms)f(used)g(to)h(implement)e(the)i FJ(import)f FN(statement.)25 b(It)19 b(de\002nes)f(the)h(follo)n(w-)0 2891 y(ing)h(constants)g(and)f(functions:)0 3038 y FD(get_magic)p FJ(\(\))208 3138 y FN(Return)28 b(the)i(magic)f(string)g(v)n(alue)f (used)h(to)h(recognize)e(byte-compiled)e(code)j(\002les)h(\(`)p FO(.p)n(yc)p FN(')f(\002les\).)53 b(\(This)29 b(v)n(alue)g(may)g(be)208 3237 y(dif)n(ferent)18 b(for)i(each)f(Python)h(v)o(ersion.\))0 3384 y FD(get_suffixes)p FJ(\(\))208 3484 y FN(Return)j(a)h(list)h(of)f (triples,)g(each)g(describing)e(a)i(particular)f(type)g(of)h(module.)34 b(Each)24 b(triple)f(has)h(the)g(form)f FJ(\()p FK(suf)o(\002x)p FJ(,)48 b FK(mode)p FJ(,)208 3583 y FK(type)p FJ(\))p FN(,)30 b(where)d FK(suf)o(\002x)i FN(is)g(a)g(string)f(to)h(be)f (appended)e(to)j(the)f(module)g(name)f(to)i(form)f(the)g(\002lename)g (to)h(search)f(for)m(,)h FK(mode)208 3683 y FN(is)f(the)g(mode)e (string)h(to)h(pass)g(to)g(the)f(b)n(uilt-in)g FJ(open\(\))g FN(function)f(to)i(open)e(the)i(\002le)g(\(this)g(can)f(be)h FJ('r')f FN(for)g(te)o(xt)g(\002les)i(or)208 3783 y FJ('rb')21 b FN(for)f(binary)g(\002les\),)i(and)e FK(type)h FN(is)h(the)g(\002le)f (type,)g(which)g(has)g(one)g(of)g(the)g(v)n(alues)g FJ(PY_SOURCE)p FN(,)e FJ(PY_COMPILED)p FN(,)h(or)208 3882 y FJ(C_EXTENSION)p FN(,)e(described)h(belo)n(w)-5 b(.)0 4029 y FD(find_module)p FJ(\()p FK(name)p FC([)p FK(,)17 b(path)12 b FC(])p FJ(\))208 4129 y FN(T)m(ry)28 b(to)h(\002nd)f(the)h(module)e FK(name)h FN(on)g(the)h(search)f(path)g FK(path)p FN(.)50 b(If)28 b FK(path)g FN(is)i(a)f(list)h(of)e(directory)f(names,)j(each)f (directory)e(is)208 4228 y(searched)20 b(for)i(\002les)h(with)f(an)o(y) f(of)g(the)h(suf)n(\002x)o(es)g(returned)e(by)h FJ(get_suffixes\(\))f FN(abo)o(v)o(e.)29 b(In)m(v)n(alid)20 b(names)i(in)g(the)g(list)h(are) 208 4328 y(silently)d(ignored)e(\(b)n(ut)i(all)h(list)g(items)g(must)g (be)f(strings\).)25 b(If)20 b FK(path)f FN(is)i(omitted)f(or)g FJ(None)p FN(,)g(the)g(list)h(of)f(directory)f(names)h(gi)n(v)o(en)208 4428 y(by)j FJ(sys.path)g FN(is)i(searched,)f(b)n(ut)g(\002rst)h(it)g (searches)f(a)g(fe)n(w)g(special)g(places:)33 b(it)25 b(tries)g(to)f(\002nd)g(a)g(b)n(uilt-in)g(module)e(with)j(the)208 4527 y(gi)n(v)o(en)c(name)h(\()p FJ(C_BUILTIN)p FN(\),)e(then)i(a)h (frozen)e(module)g(\()p FJ(PY_FROZEN)p FN(\),)g(and)h(on)g(some)g (systems)h(some)f(other)g(places)h(are)208 4627 y(look)o(ed)g(in)i(as)g (well)g(\(on)f(the)h(Mac,)h(it)f(looks)f(for)g(a)h(resource)f(\()p FJ(PY_RESOURCE)p FN(\);)e(on)j(W)m(indo)n(ws,)g(it)g(looks)f(in)h(the)g (re)o(gistry)208 4727 y(which)19 b(may)h(point)f(to)i(a)f(speci\002c)h (\002le\).)208 4859 y(If)27 b(search)h(is)g(successful,)i(the)d(return) g(v)n(alue)g(is)i(a)f(triple)g FJ(\()p FK(\002le)p FJ(,)49 b FK(pathname)p FJ(,)e FK(description)p FJ(\))27 b FN(where)g FK(\002le)h FN(is)g(an)g(open)f(\002le)208 4959 y(object)f(positioned)g (at)h(the)h(be)o(ginning,)e FK(pathname)f FN(is)j(the)f(pathname)f(of)g (the)i(\002le)f(found,)g(and)g FK(description)f FN(is)i(a)g(triple)f (as)208 5059 y(contained)19 b(in)j(the)f(list)i(returned)d(by)h FJ(get_suffixes\(\))e FN(describing)h(the)h(kind)g(of)g(module)f (found.)27 b(If)21 b(the)h(module)e(does)208 5158 y(not)e(li)n(v)o(e)g (in)g(a)h(\002le,)h(the)e(returned)f FK(\002le)h FN(is)h FJ(None)p FN(,)g FK(\002lename)e FN(is)i(the)g(empty)f(string,)g(and)g (the)g FK(description)g FN(tuple)g(contains)f(empty)208 5258 y(strings)h(for)f(its)i(suf)n(\002x)f(and)g(mode;)g(the)g(module)f (type)g(is)j(as)e(indicate)g(in)g(parentheses)f(abo)o(v)o(e.)23 b(If)18 b(the)g(search)g(is)h(unsuccessful,)208 5357 y FJ(ImportError)f FN(is)j(raised.)k(Other)20 b(e)o(xceptions)f (indicate)g(problems)g(with)h(the)g(ar)o(guments)f(or)g(en)m (vironment.)p 0 5549 3901 4 v 3762 5649 a FI(865)p eop end %%Page: 866 878 TeXDict begin 866 877 bop 208 83 a FN(This)25 b(function)f(does)h(not)g (handle)f(hierarchical)g(module)g(names)h(\(names)g(containing)f (dots\).)40 b(In)25 b(order)f(to)i(\002nd)f FK(P)p FN(.)p FK(M)s FN(,)g(that)208 183 y(is,)20 b(submodule)d FK(M)24 b FN(of)19 b(package)f FK(P)p FN(,)i(use)f FJ(find_module\(\))f FN(and)h FJ(load_module\(\))f FN(to)h(\002nd)h(and)e(load)i(package)e FK(P)p FN(,)h(and)208 282 y(then)25 b(use)h FJ(find_module\(\))d FN(with)j(the)g FK(path)f FN(ar)o(gument)e(set)j(to)g FK(P)p FJ(.__path__)p FN(.)40 b(When)26 b FK(P)f FN(itself)i(has)f(a)g (dotted)e(name,)208 382 y(apply)19 b(this)i(recipe)e(recursi)n(v)o(ely) -5 b(.)0 529 y FD(load_module)p FJ(\()p FK(name)o(,)17 b(\002le)o(,)j(\002lename)o(,)f(description)p FJ(\))208 628 y FN(Load)f(a)j(module)d(that)i(w)o(as)g(pre)n(viously)e(found)g (by)h FJ(find_module\(\))f FN(\(or)h(by)g(an)h(otherwise)f(conducted)f (search)h(yielding)208 728 y(compatible)i(results\).)34 b(This)23 b(function)e(does)i(more)f(than)h(importing)e(the)i(module:) 30 b(if)23 b(the)g(module)f(w)o(as)i(already)d(imported,)208 828 y(it)26 b(is)i(equi)n(v)n(alent)c(to)i(a)h FJ(reload\(\))p FN(!)42 b(The)26 b FK(name)f FN(ar)o(gument)f(indicates)i(the)g(full)g (module)f(name)h(\(including)e(the)i(package)208 927 y(name,)20 b(if)h(this)h(is)g(a)g(submodule)d(of)h(a)i(package\).)k (The)21 b FK(\002le)g FN(ar)o(gument)d(is)23 b(an)e(open)f(\002le,)h (and)g FK(\002lename)f FN(is)i(the)f(corresponding)208 1027 y(\002le)30 b(name;)35 b(these)30 b(can)f(be)h FJ(None)g FN(and)g FJ('')p FN(,)i(respecti)n(v)o(ely)-5 b(,)30 b(when)g(the)g(module)e(is)j(not)f(being)f(loaded)g(from)g(a)h(\002le.) 55 b(The)208 1127 y FK(description)20 b FN(ar)o(gument)e(is)k(a)f (tuple,)g(as)g(w)o(ould)g(be)g(returned)e(by)h FJ(get_suffixes\(\))p FN(,)f(describing)g(what)i(kind)f(of)h(module)208 1226 y(must)f(be)g(loaded.)208 1359 y(If)c(the)h(load)f(is)i(successful,)f (the)g(return)e(v)n(alue)h(is)i(the)f(module)e(object;)j(otherwise,)e (an)h(e)o(xception)e(\(usually)g FJ(ImportError)p FN(\))208 1459 y(is)21 b(raised.)208 1591 y FL(Important:)28 b FN(the)22 b(caller)h(is)g(responsible)e(for)h(closing)f(the)i FK(\002le)f FN(ar)o(gument,)e(if)j(it)g(w)o(as)g(not)f FJ(None)p FN(,)g(e)n(v)o(en)g(when)f(an)h(e)o(xception)208 1691 y(is)f(raised.)j(This)d(is)g(best)f(done)g(using)f(a)i FJ(try)f FN(...)25 b FJ(finally)20 b FN(statement.)0 1838 y FD(new_module)p FJ(\()p FK(name)p FJ(\))208 1938 y FN(Return)f(a)i(ne)n(w)f(empty)f(module)g(object)h(called)g FK(name)p FN(.)k(This)c(object)g(is)h FK(not)f FN(inserted)g(in)g FJ(sys.modules)p FN(.)0 2084 y FD(lock_held)p FJ(\(\))208 2184 y FN(Return)27 b FJ(True)g FN(if)h(the)f(import)g(lock)g(is)h (currently)e(held,)i(else)g FJ(False)p FN(.)47 b(On)27 b(platforms)g(without)f(threads,)j(al)o(w)o(ays)f(return)208 2284 y FJ(False)p FN(.)208 2417 y(On)g(platforms)f(with)h(threads,)h(a) g(thread)e(e)o(x)o(ecuting)f(an)i(import)f(holds)h(an)g(internal)f (lock)h(until)g(the)g(import)f(is)i(complete.)208 2516 y(This)20 b(lock)g(blocks)f(other)h(threads)g(from)f(doing)g(an)h (import)f(until)h(the)h(original)e(import)g(completes,)g(which)h(in)g (turn)g(pre)n(v)o(ents)208 2616 y(other)g(threads)h(from)g(seeing)g (incomplete)f(module)g(objects)h(constructed)f(by)h(the)h(original)e (thread)h(while)g(in)h(the)g(process)f(of)208 2715 y(completing)d(its)j (import)e(\(and)h(the)g(imports,)f(if)h(an)o(y)-5 b(,)19 b(triggered)g(by)g(that\).)0 2862 y FD(acquire_lock)p FJ(\(\))208 2962 y FN(Acquires)e(the)g(interpreter')-5 b(s)17 b(import)g(lock)g(for)g(the)h(current)f(thread.)23 b(This)18 b(lock)f(should)g(be)h(used)f(by)h(import)f(hooks)f(to)i (ensure)208 3062 y(thread-safety)26 b(when)i(importing)e(modules.)49 b(On)29 b(platforms)e(without)h(threads,)h(this)g(function)e(does)h (nothing.)99 b(Ne)n(w)28 b(in)208 3161 y(v)o(ersion)18 b(2.3.)0 3308 y FD(release_lock)p FJ(\(\))208 3408 y FN(Release)h(the)g(interpreter')-5 b(s)17 b(import)h(lock.)24 b(On)19 b(platforms)e(without)h(threads,)g(this)i(function)d(does)h (nothing.)48 b(Ne)n(w)19 b(in)g(v)o(ersion)208 3507 y(2.3.)0 3654 y(The)i(follo)n(wing)e(constants)h(with)i(inte)o(ger)d(v)n(alues,) i(de\002ned)f(in)h(this)g(module,)f(are)h(used)f(to)i(indicate)e(the)h (search)f(result)h(of)g FJ(find_-)0 3754 y(module\(\))p FN(.)0 3901 y FD(PY_SOURCE)208 4000 y FN(The)e(module)g(w)o(as)i(found) e(as)i(a)f(source)g(\002le.)0 4147 y FD(PY_COMPILED)208 4247 y FN(The)f(module)g(w)o(as)i(found)e(as)i(a)f(compiled)f(code)g (object)h(\002le.)0 4394 y FD(C_EXTENSION)208 4493 y FN(The)f(module)g(w)o(as)i(found)e(as)i(dynamically)d(loadable)h (shared)g(library)-5 b(.)0 4640 y FD(PY_RESOURCE)208 4740 y FN(The)27 b(module)g(w)o(as)i(found)d(as)j(a)f(Mac)g(OS)h(9)f (resource.)47 b(This)29 b(v)n(alue)e(can)h(only)f(be)h(returned)e(on)i (a)g(Mac)g(OS)h(9)f(or)g(earlier)208 4839 y(Macintosh.)0 4986 y FD(PKG_DIRECTORY)208 5086 y FN(The)19 b(module)g(w)o(as)i(found) e(as)i(a)f(package)f(directory)-5 b(.)0 5233 y FD(C_BUILTIN)208 5332 y FN(The)19 b(module)g(w)o(as)i(found)e(as)i(a)f(b)n(uilt-in)g (module.)p 0 5549 3901 4 v 0 5649 a FI(866)2590 b(Chapter)24 b(29.)52 b(Impor)s(ting)24 b(Modules)p eop end %%Page: 867 879 TeXDict begin 867 878 bop 0 83 a FD(PY_FROZEN)208 183 y FN(The)19 b(module)g(w)o(as)i(found)e(as)i(a)f(frozen)f(module)g (\(see)h FJ(init_frozen\(\))p FN(\).)0 330 y(The)32 b(follo)n(wing)g (constant)g(and)g(functions)f(are)i(obsolete;)39 b(their)32 b(functionality)f(is)j(a)n(v)n(ailable)e(through)f FJ(find_module\(\))g FN(or)0 429 y FJ(load_module\(\))p FN(.)23 b(The)o(y)c(are)h(k)o(ept)g (around)f(for)g(backw)o(ard)g(compatibility:)0 576 y FD(SEARCH_ERROR)208 676 y FN(Unused.)0 823 y FD(init_builtin)p FJ(\()p FK(name)p FJ(\))208 922 y FN(Initialize)i(the)g(b)n(uilt-in)g (module)e(called)j FK(name)e FN(and)h(return)f(its)i(module)e(object.) 28 b(If)21 b(the)h(module)e(w)o(as)i(already)e(initialized,)h(it)208 1022 y(will)h(be)h(initialized)e FK(a)o(gain)p FN(.)30 b(A)23 b(fe)n(w)f(modules)f(cannot)g(be)h(initialized)g(twice)h(\227)g (attempting)e(to)h(initialize)g(these)h(again)e(will)208 1121 y(raise)f(an)g FJ(ImportError)f FN(e)o(xception.)k(If)d(there)g (is)h(no)f(b)n(uilt-in)f(module)g(called)h FK(name)p FN(,)f FJ(None)h FN(is)h(returned.)0 1268 y FD(init_frozen)p FJ(\()p FK(name)p FJ(\))208 1368 y FN(Initialize)26 b(the)h(frozen)e (module)h(called)g FK(name)h FN(and)f(return)f(its)j(module)e(object.) 44 b(If)27 b(the)f(module)g(w)o(as)h(already)f(initialized,)208 1468 y(it)31 b(will)g(be)g(initialized)f FK(a)o(gain)p FN(.)56 b(If)30 b(there)h(is)g(no)g(frozen)e(module)g(called)i FK(name)p FN(,)h FJ(None)f FN(is)g(returned.)55 b(\(Frozen)30 b(modules)208 1567 y(are)g(modules)f(written)g(in)i(Python)e(whose)g (compiled)g(byte-code)f(object)h(is)i(incorporated)d(into)h(a)i (custom-b)n(uilt)e(Python)208 1667 y(interpreter)18 b(by)i(Python')-5 b(s)19 b FL(fr)o(eeze)g FN(utility)-5 b(.)25 b(See)c(`)p FO(T)-9 b(ools/freez)o(e/)p FN(')16 b(for)k(no)n(w)-5 b(.\))0 1814 y FD(is_builtin)p FJ(\()p FK(name)p FJ(\))208 1913 y FN(Return)19 b FJ(1)h FN(if)g(there)f(is)i(a)f(b)n(uilt-in)f (module)g(called)g FK(name)g FN(which)g(can)h(be)g(initialized)f (again.)24 b(Return)19 b FJ(-1)h FN(if)g(there)f(is)i(a)f(b)n(uilt-in) 208 2013 y(module)c(called)h FK(name)g FN(which)g(cannot)g(be)h (initialized)f(again)f(\(see)i FJ(init_builtin\(\))p FN(\).)k(Return)17 b FJ(0)h FN(if)g(there)f(is)i(no)e(b)n(uilt-in)208 2113 y(module)h(called)i FK(name)p FN(.)0 2259 y FD(is_frozen)p FJ(\()p FK(name)p FJ(\))208 2359 y FN(Return)k FJ(True)h FN(if)h(there)e(is)i(a)g(frozen)e(module)f(\(see)j FJ(init_frozen\(\))p FN(\))d(called)i FK(name)p FN(,)g(or)g FJ(False)g FN(if)g(there)g(is)h (no)f(such)208 2459 y(module.)0 2606 y FD(load_compiled)p FJ(\()p FK(name)o(,)17 b(pathname)o(,)h FC([)p FK(\002le)12 b FC(])p FJ(\))208 2705 y FN(Load)27 b(and)h(initialize)h(a)g(module)e (implemented)g(as)i(a)g(byte-compiled)d(code)i(\002le)h(and)f(return)g (its)h(module)f(object.)49 b(If)29 b(the)208 2805 y(module)c(w)o(as)j (already)e(initialized,)h(it)h(will)g(be)e(initialized)h FK(a)o(gain)p FN(.)44 b(The)26 b FK(name)h FN(ar)o(gument)d(is)k(used)e (to)h(create)g(or)g(access)g(a)208 2904 y(module)d(object.)40 b(The)25 b FK(pathname)f FN(ar)o(gument)f(points)i(to)h(the)f (byte-compiled)e(code)i(\002le.)41 b(The)26 b FK(\002le)f FN(ar)o(gument)e(is)k(the)e(byte-)208 3004 y(compiled)19 b(code)h(\002le,)i(open)e(for)g(reading)f(in)i(binary)f(mode,)g(from)g (the)h(be)o(ginning.)j(It)d(must)g(currently)f(be)g(a)i(real)f(\002le)g (object,)208 3104 y(not)e(a)i(user)n(-de\002ned)d(class)k(emulating)c (a)j(\002le.)0 3251 y FD(load_dynamic)p FJ(\()p FK(name)o(,)c(pathname) p FC([)p FK(,)h(\002le)12 b FC(])p FJ(\))208 3350 y FN(Load)k(and)h (initialize)g(a)h(module)e(implemented)g(as)i(a)g(dynamically)d (loadable)h(shared)h(library)f(and)h(return)f(its)i(module)e(object.) 208 3450 y(If)23 b(the)h(module)f(w)o(as)i(already)d(initialized,)j(it) f(will)h(be)f(initialized)f FK(a)o(gain)p FN(.)35 b(Some)24 b(modules)f(don')o(t)f(lik)o(e)i(that)g(and)g(may)f(raise)208 3549 y(an)c(e)o(xception.)k(The)c FK(pathname)f FN(ar)o(gument)f(must)j (point)f(to)h(the)f(shared)g(library)-5 b(.)23 b(The)d FK(name)f FN(ar)o(gument)e(is)j(used)g(to)g(construct)208 3649 y(the)27 b(name)f(of)h(the)g(initialization)f(function:)37 b(an)27 b(e)o(xternal)f(C)i(function)d(called)i(`)p FJ(init)p FK(name)p FJ(\(\))p FN(')d(in)j(the)g(shared)g(library)f(is)208 3749 y(called.)g(The)21 b(optional)f FK(\002le)g FN(ar)o(gument)f(is)j (ignored.)j(\(Note:)h(using)21 b(shared)f(libraries)g(is)i(highly)e (system)h(dependent,)e(and)h(not)208 3848 y(all)g(systems)h(support)e (it.\))0 3995 y FD(load_source)p FJ(\()p FK(name)o(,)e(pathname)p FC([)p FK(,)h(\002le)12 b FC(])p FJ(\))208 4095 y FN(Load)23 b(and)g(initialize)h(a)g(module)f(implemented)f(as)i(a)h(Python)e (source)g(\002le)h(and)g(return)e(its)j(module)e(object.)35 b(If)24 b(the)g(module)208 4194 y(w)o(as)j(already)f(initialized,)i(it) g(will)f(be)g(initialized)f FK(a)o(gain)p FN(.)44 b(The)27 b FK(name)f FN(ar)o(gument)f(is)i(used)g(to)g(create)g(or)f(access)i(a) f(module)208 4294 y(object.)k(The)22 b FK(pathname)f FN(ar)o(gument)f(points)j(to)f(the)h(source)f(\002le.)33 b(The)22 b FK(\002le)h FN(ar)o(gument)d(is)j(the)g(source)f(\002le,)h (open)f(for)g(reading)208 4394 y(as)29 b(te)o(xt,)h(from)d(the)h(be)o (ginning.)47 b(It)29 b(must)f(currently)f(be)h(a)h(real)f(\002le)h (object,)h(not)e(a)g(user)n(-de\002ned)f(class)i(emulating)e(a)i (\002le.)208 4493 y(Note)19 b(that)h(if)g(a)f(properly)f(matching)g (byte-compiled)f(\002le)j(\(with)f(suf)n(\002x)g(`)p FO(.p)n(yc)p FN(')h(or)f(`)p FO(.p)n(y)o(o)p FN('\))e(e)o(xists,)j(it)h (will)f(be)f(used)h(instead)f(of)208 4593 y(parsing)g(the)h(gi)n(v)o (en)f(source)g(\002le.)0 4740 y FL(class)i FD(NullImporter)p FJ(\()p FK(path)p 991 4740 25 4 v 26 w(string)p FJ(\))208 4839 y FN(The)g FJ(NullImporter)g FN(type)h(is)h(a)g(PEP)g(302)e (import)g(hook)g(that)i(handles)e(non-directory)e(path)j(strings)g(by)g (f)o(ailing)f(to)i(\002nd)208 4939 y(an)o(y)e(modules.)29 b(Calling)22 b(this)g(type)g(with)g(an)g(e)o(xisting)f(directory)f(or)h (empty)h(string)f(raises)i FJ(ImportError)p FN(.)28 b(Otherwise,)22 b(a)208 5039 y FJ(NullImporter)c FN(instance)i(is)h(returned.)208 5170 y(Python)g(adds)i(instances)g(of)g(this)g(type)g(to)g FJ(sys.path_importer_cache)c FN(for)j(an)o(y)g(path)h(entries)g(that)g (are)g(not)f(direc-)208 5269 y(tories)e(and)f(are)i(not)e(handled)g(by) h(an)o(y)f(other)h(path)f(hooks)g(on)h FJ(sys.path_hooks)p FN(.)j(Instances)d(ha)n(v)o(e)f(only)h(one)f(method:)208 5400 y FD(find_module)p FJ(\()p FK(fullname)e FC([)p FK(,)j(path)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(29.1.)52 b FJ(imp)23 b FI(\227)g(Access)f(the)h FJ(import)f FI(inter)r(nals)2181 b(867)p eop end %%Page: 868 880 TeXDict begin 868 879 bop 390 83 a FN(This)21 b(method)d(al)o(w)o(ays)j (returns)e FJ(None)p FN(,)h(indicating)f(that)h(the)g(requested)f (module)g(could)g(not)h(be)g(found.)208 216 y(Ne)n(w)g(in)g(v)o(ersion) f(2.5.)0 501 y Fv(29.1.1)101 b(Examples)0 704 y FN(The)30 b(follo)n(wing)g(function)f(emulates)h(what)h(w)o(as)h(the)e(standard)g (import)g(statement)g(up)h(to)g(Python)e(1.4)h(\(no)h(hierarchical)e (mod-)0 803 y(ule)f(names\).)48 b(\(This)27 b FK(implementation)f FN(w)o(ouldn')o(t)g(w)o(ork)i(in)g(that)g(v)o(ersion,)g(since)h FJ(find_module\(\))d FN(has)i(been)f(e)o(xtended)f(and)0 903 y FJ(load_module\(\))18 b FN(has)j(been)e(added)g(in)i(1.4.\))236 1141 y FA(import)44 b(imp)236 1232 y(import)g(sys)236 1415 y(def)h(__import__\(name,)d(globals=None,)g(locals=None,)h (fromlist=None\):)416 1506 y(#)h(Fast)g(path:)g(see)h(if)f(the)h (module)e(has)i(already)e(been)h(imported.)416 1598 y(try:)595 1689 y(return)g(sys.modules[name])416 1780 y(except)f(KeyError:)595 1872 y(pass)416 2054 y(#)h(If)h(any)f(of)h(the)f(following)f(calls)h (raises)g(an)g(exception,)416 2146 y(#)g(there's)g(a)h(problem)e(we)i (can't)f(handle)f(--)i(let)f(the)h(caller)e(handle)h(it.)416 2328 y(fp,)g(pathname,)f(description)g(=)i(imp.find_module\(name\))416 2511 y(try:)595 2602 y(return)f(imp.load_module\(name,)d(fp,)j (pathname,)g(description\))416 2694 y(finally:)595 2785 y(#)h(Since)f(we)g(may)g(exit)h(via)f(an)g(exception,)f(close)h(fp)h (explicitly.)595 2876 y(if)f(fp:)774 2968 y(fp.close\(\))0 3254 y FN(A)28 b(more)e(complete)g(e)o(xample)g(that)i(implements)e (hierarchical)g(module)g(names)h(and)f(includes)h(a)h FJ(reload\(\))e FN(function)g(can)h(be)0 3354 y(found)f(in)j(the)f (module)f FJ(knee)p FN(.)49 b(The)27 b FJ(knee)h FN(module)f(can)h(be)g (found)f(in)h(`)p FO(Demo/imputil/)p FN(')d(in)j(the)h(Python)e(source) g(distrib)n(ution.)0 3781 y FE(29.2)121 b Fx(zipimport)31 b FE(\227)i(Impor)5 b(t)34 b(modules)g(from)f(Zip)g(archiv)m(es)0 4014 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 4160 y(This)28 b(module)e(adds)h(the)g(ability)g(to)h(import)e(Python)h(modules)f(\(`) p FO(*.p)n(y)p FN(',)i(`)p FO(*.p)n(y[co])p FN('\))e(and)h(packages)f (from)g(ZIP-format)g(archi)n(v)o(es.)0 4260 y(It)h(is)h(usually)f(not)f (needed)g(to)h(use)g(the)g FJ(zipimport)f FN(module)g(e)o(xplicitly;)j (it)f(is)g(automatically)d(used)i(by)f(the)h(b)n(uiltin)g FJ(import)0 4360 y FN(mechanism)19 b(for)g FJ(sys.path)h FN(items)g(that)h(are)f(paths)g(to)g(ZIP)g(archi)n(v)o(es.)0 4507 y(T)-7 b(ypically)i(,)31 b FJ(sys.path)f FN(is)h(a)g(list)h(of)e (directory)e(names)i(as)h(strings.)56 b(This)31 b(module)e(also)h(allo) n(ws)h(an)f(item)h(of)f FJ(sys.path)f FN(to)0 4606 y(be)d(a)g(string)g (naming)e(a)j(ZIP)f(\002le)g(archi)n(v)o(e.)41 b(The)26 b(ZIP)g(archi)n(v)o(e)e(can)i(contain)f(a)h(subdirectory)e(structure)h (to)h(support)e(package)h(im-)0 4706 y(ports,)34 b(and)d(a)h(path)g (within)f(the)h(archi)n(v)o(e)e(can)i(be)g(speci\002ed)f(to)h(only)f (import)g(from)g(a)h(subdirectory)-5 b(.)57 b(F)o(or)31 b(e)o(xample,)i(the)f(path)0 4805 y(`)p FO(/tmp/e)n(xample)o(.zip/lib/) p FN(')15 b(w)o(ould)k(only)h(import)f(from)g(the)h(`)p FO(lib/)p FN(')f(subdirectory)e(within)j(the)h(archi)n(v)o(e.)0 4952 y(An)o(y)i(\002les)h(may)f(be)h(present)f(in)g(the)h(ZIP)g(archi)n (v)o(e,)e(b)n(ut)i(only)f(\002les)h(`)p FO(.p)n(y)p FN(')f(and)g(`)p FO(.p)n(y[co])p FN(')f(are)i(a)n(v)n(ailable)f(for)g(import.)34 b(ZIP)23 b(import)g(of)0 5052 y(dynamic)18 b(modules)g(\(`)p FO(.p)n(yd)p FN(',)f(`)p FO(.so)p FN('\))i(is)h(disallo)n(wed.)k(Note) 19 b(that)g(if)h(an)f(archi)n(v)o(e)f(only)g(contains)g(`)p FO(.p)n(y)p FN(')h(\002les,)h(Python)e(will)i(not)f(attempt)0 5152 y(to)k(modify)d(the)j(archi)n(v)o(e)e(by)h(adding)f(the)h (corresponding)d(`)p FO(.p)n(yc)p FN(')k(or)f(`)p FO(.p)n(y)o(o)p FN(')f(\002le,)i(meaning)e(that)h(if)h(a)g(ZIP)g(archi)n(v)o(e)e (doesn')o(t)g(contain)0 5251 y(`)p FO(.p)n(yc)p FN(')f(\002les,)h (importing)d(may)i(be)g(rather)f(slo)n(w)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(868)2590 b(Chapter)24 b(29.)52 b(Impor)s(ting)24 b(Modules)p eop end %%Page: 869 881 TeXDict begin 869 880 bop 0 83 a FN(Using)25 b(the)g(b)n(uilt-in)g FJ(reload\(\))g FN(function)e(will)j(f)o(ail)g(if)f(called)h(on)e(a)i (module)e(loaded)g(from)g(a)i(ZIP)g(archi)n(v)o(e;)g(it)g(is)g(unlik)o (ely)e(that)0 183 y FJ(reload\(\))19 b FN(w)o(ould)h(be)g(needed,)e (since)j(this)g(w)o(ould)e(imply)h(that)g(the)g(ZIP)g(has)h(been)e (altered)h(during)e(runtime.)0 330 y(The)i(a)n(v)n(ailable)g(attrib)n (utes)g(of)g(this)g(module)f(are:)0 476 y FL(exception)g FD(ZipImportError)208 576 y FN(Exception)44 b(raised)j(by)f (zipimporter)e(objects.)104 b(It')-5 b(s)47 b(a)g(subclass)f(of)g FJ(ImportError)p FN(,)52 b(so)47 b(it)g(can)f(be)g(caught)g(as)208 676 y FJ(ImportError)p FN(,)18 b(too.)0 823 y FL(class)j FD(zipimporter)208 922 y FN(The)e(class)j(for)d(importing)f(ZIP)j (\002les.)26 b(See)20 b(\223)p FK(zipimporter)g(Objects)p FN(\224)h(\(section)e(29.2.1\))f(for)i(constructor)e(details.)0 1069 y FL(See)j(Also:)0 1216 y FK(PKZIP)f(Application)f(Note)0 1316 y Fy(\()p FO(http://www)l(.pkw)o(are)o(.com/b)o(usin)o(ess)p 1114 1316 23 4 v 21 w(and)p 1261 1316 V 26 w(de)n(v)n(elopers/de)n(v)n (eloper/a)o(pp)o(not)o(e/)-6 b Fy(\))208 1415 y FN(Documentation)17 b(on)j(the)g(ZIP)g(\002le)h(format)e(by)h(Phil)h(Katz,)f(the)g(creator) f(of)h(the)h(format)e(and)g(algorithms)g(used.)0 1562 y(PEP)i(0273,)d(\223)p FK(Import)i(Modules)g(fr)l(om)g(Zip)h(Ar)m(c)o (hives)p FN(\224)208 1662 y(Written)j(by)f(James)h(C.)h(Ahlstrom,)f (who)f(also)h(pro)o(vided)e(an)h(implementation.)34 b(Python)23 b(2.3)g(follo)n(ws)g(the)h(speci\002cation)f(in)208 1761 y(PEP)f(273,)g(b)n(ut)g(uses)h(an)f(implementation)e(written)i(by)g (Just)g(v)n(an)g(Rossum)g(that)h(uses)f(the)g(import)g(hooks)f (described)g(in)h(PEP)208 1861 y(302.)0 2008 y(PEP)f(0302,)d(\223)p FK(Ne)o(w)j(Import)f(Hooks)p FN(\224)208 2107 y(The)f(PEP)i(to)g(add)e (the)h(import)g(hooks)f(that)h(help)g(this)g(module)f(w)o(ork.)0 2392 y Fv(29.2.1)101 b(zipimpor)t(ter)29 b(Objects)0 2581 y FL(class)21 b FD(zipimporter)p FJ(\()p FK(ar)m(c)o(hivepath)p FJ(\))208 2681 y FN(Create)27 b(a)g(ne)n(w)g(zipimporter)e(instance.)45 b FK(ar)m(c)o(hivepath)25 b FN(must)i(be)g(a)h(path)e(to)h(a)h (zip\002le.)45 b FJ(ZipImportError)25 b FN(is)j(raised)f(if)208 2780 y FK(ar)m(c)o(hivepath)18 b FN(doesn')o(t)g(point)i(to)g(a)h(v)n (alid)e(ZIP)i(archi)n(v)o(e.)0 2927 y FD(find_module)p FJ(\()p FK(fullname)p FC([)p FK(,)c(path)12 b FC(])p FJ(\))208 3027 y FN(Search)17 b(for)f(a)i(module)f(speci\002ed)g(by)g FK(fullname)p FN(.)23 b FK(fullname)17 b FN(must)g(be)h(the)f(fully)g (quali\002ed)g(\(dotted\))f(module)g(name.)24 b(It)17 b(returns)208 3127 y(the)26 b(zipimporter)e(instance)i(itself)h(if)f (the)g(module)f(w)o(as)i(found,)f(or)g FJ(None)g FN(if)g(it)h(w)o(asn') o(t.)43 b(The)26 b(optional)e FK(path)i FN(ar)o(gument)e(is)208 3226 y(ignored\227it')-5 b(s)18 b(there)i(for)g(compatibility)e(with)j (the)f(importer)f(protocol.)0 3373 y FD(get_code)p FJ(\()p FK(fullname)p FJ(\))208 3473 y FN(Return)g(the)i(code)e(object)h(for)f (the)h(speci\002ed)g(module.)k(Raise)d FJ(ZipImportError)d FN(if)j(the)f(module)f(couldn')o(t)f(be)i(found.)0 3620 y FD(get_data)p FJ(\()p FK(pathname)p FJ(\))208 3719 y FN(Return)f(the)i(data)f(associated)g(with)g FK(pathname)p FN(.)j(Raise)e FJ(IOError)f FN(if)g(the)g(\002le)h(w)o(asn')o(t)f (found.)0 3866 y FD(get_source)p FJ(\()p FK(fullname)p FJ(\))208 3966 y FN(Return)j(the)h(source)f(code)g(for)g(the)h (speci\002ed)f(module.)34 b(Raise)25 b FJ(ZipImportError)d FN(if)i(the)g(module)e(couldn')o(t)g(be)i(found,)208 4065 y(return)19 b FJ(None)h FN(if)g(the)g(archi)n(v)o(e)f(does)h (contain)f(the)h(module,)f(b)n(ut)h(has)h(no)e(source)h(for)f(it.)0 4212 y FD(is_package)p FJ(\()p FK(fullname)p FJ(\))208 4312 y FN(Return)e(T)m(rue)g(if)h(the)g(module)e(speci\002ed)i(by)f FK(fullname)g FN(is)h(a)h(package.)j(Raise)d FJ(ZipImportError)d FN(if)i(the)f(module)g(couldn')o(t)208 4411 y(be)j(found.)0 4558 y FD(load_module)p FJ(\()p FK(fullname)p FJ(\))208 4658 y FN(Load)i(the)i(module)e(speci\002ed)h(by)g FK(fullname)p FN(.)34 b FK(fullname)23 b FN(must)h(be)f(the)h(fully)f(quali\002ed)f (\(dotted\))g(module)g(name.)35 b(It)23 b(returns)208 4758 y(the)d(imported)e(module,)h(or)h(raises)h FJ(ZipImportError)d FN(if)i(it)h(w)o(asn')o(t)f(found.)0 5042 y Fv(29.2.2)101 b(Examples)0 5245 y FN(Here)26 b(is)h(an)e(e)o(xample)g(that)h(imports) f(a)h(module)f(from)g(a)h(ZIP)g(archi)n(v)o(e)f(-)h(note)f(that)h(the)g FJ(zipimport)f FN(module)f(is)j(not)f(e)o(xplicitly)0 5345 y(used.)p 0 5549 3901 4 v 0 5649 a FI(29.2.)52 b FJ(zipimport)22 b FI(\227)h(Impor)s(t)g(modules)h(from)f(Zip)h(archiv)n (es)1714 b(869)p eop end %%Page: 870 882 TeXDict begin 870 881 bop 236 174 a FA($)45 b(unzip)f(-l)g (/tmp/example.zip)236 266 y(Archive:)89 b(/tmp/example.zip)326 357 y(Length)223 b(Date)134 b(Time)179 b(Name)281 448 y(--------)f(----)134 b(----)179 b(----)460 540 y(8467)89 b(11-26-02)44 b(22:30)134 b(jwzthreading.py)281 631 y(--------)851 b(-------)460 722 y(8467)h(1)44 b(file)236 814 y($)h(./python)236 905 y(Python)f(2.3)g(\(#1,)h(Aug)f(1)h(2003,)f(19:54:32\))236 996 y(>>>)h(import)e(sys)236 1088 y(>>>)i(sys.path.insert\(0,)c ('/tmp/example.zip'\))87 b(#)44 b(Add)h(.zip)f(file)g(to)h(front)f(of)g (path)236 1179 y(>>>)h(import)e(jwzthreading)236 1270 y(>>>)i(jwzthreading.__file__)236 1362 y ('/tmp/example.zip/jwzthreading.py')0 1872 y FE(29.3)121 b Fx(pkgutil)32 b FE(\227)g(P)-5 b(ac)n(kage)35 b(e)l(xtension)g (utility)0 2104 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 2251 y(This)h(module)f(pro)o(vides)g(a)h(single)g(function:)0 2398 y FD(extend_path)p FJ(\()p FK(path,)d(name)p FJ(\))208 2498 y FN(Extend)j(the)i(search)f(path)g(for)g(the)h(modules)f(which)g (comprise)g(a)h(package.)28 b(Intended)20 b(use)h(is)i(to)f(place)f (the)h(follo)n(wing)e(code)208 2597 y(in)g(a)h(package')-5 b(s)19 b(`)p 731 2597 23 4 v 758 2597 V 53 w FO(init)p 881 2597 V 907 2597 V 52 w(.p)n(y)p FN(':)444 2822 y FA(from)44 b(pkgutil)g(import)f(extend_path)444 2913 y(__path__)g(=)i(extend_path\(__path__,)c(__name__\))208 3102 y FN(This)18 b(will)g(add)f(to)h(the)g(package')-5 b(s)17 b FJ(__path__)g FN(all)i(subdirectories)d(of)h(directories)g(on) h FJ(sys.path)e FN(named)h(after)h(the)g(pack-)208 3202 y(age.)24 b(This)d(is)g(useful)e(if)i(one)f(w)o(ants)g(to)h(distrib)n (ute)e(dif)n(ferent)g(parts)h(of)g(a)g(single)h(logical)e(package)g(as) i(multiple)e(directories.)208 3335 y(It)d(also)g(looks)f(for)h(`)p FO(*.pkg)p FN(')f(\002les)i(be)o(ginning)c(where)1698 3350 y FJ(*)1765 3335 y FN(matches)i(the)h FK(name)g FN(ar)o(gument.)21 b(This)16 b(feature)f(is)i(similar)f(to)g(`)p FO(*.pth)p FN(')f(\002les)208 3434 y(\(see)26 b(the)g FJ(site)f FN(module)g(for)g(more)g(information\),)f(e)o(xcept)h(that)h (it)h(doesn')o(t)d(special-case)i(lines)g(starting)f(with)h FJ(import)p FN(.)208 3534 y(A)e(`)p FO(*.pkg)p FN(')g(\002le)h(is)g (trusted)f(at)h(f)o(ace)f(v)n(alue:)33 b(apart)24 b(from)f(checking)f (for)i(duplicates,)g(all)h(entries)f(found)f(in)h(a)h(`)p FO(*.pkg)p FN(')f(\002le)h(are)208 3634 y(added)19 b(to)h(the)g(path,)g (re)o(gardless)e(of)i(whether)f(the)o(y)h(e)o(xist)g(on)g(the)g (\002lesystem.)25 b(\(This)20 b(is)h(a)g(feature.\))208 3767 y(If)g(the)h(input)f(path)g(is)i(not)f(a)g(list)h(\(as)f(is)g(the) g(case)g(for)g(frozen)e(packages\))g(it)j(is)g(returned)c(unchanged.)27 b(The)22 b(input)f(path)g(is)i(not)208 3866 y(modi\002ed;)c(an)h(e)o (xtended)e(cop)o(y)h(is)i(returned.)j(Items)c(are)g(only)f(appended)f (to)i(the)h(cop)o(y)e(at)i(the)f(end.)208 3999 y(It)c(is)g(assumed)g (that)f FJ(sys.path)g FN(is)i(a)f(sequence.)22 b(Items)16 b(of)g FJ(sys.path)e FN(that)i(are)g(not)f(\(Unicode)g(or)g(8-bit\))g (strings)h(referring)208 4099 y(to)k(e)o(xisting)f(directories)g(are)g (ignored.)k(Unicode)c(items)i(on)e FJ(sys.path)g FN(that)h(cause)g (errors)f(when)g(used)h(as)g(\002lenames)g(may)208 4198 y(cause)g(this)g(function)f(to)h(raise)h(an)f(e)o(xception)e(\(in)i (line)g(with)h FJ(os.path.isdir\(\))d FN(beha)n(vior\).)0 4526 y FE(29.4)121 b Fx(modulefinder)30 b FE(\227)j(Find)h(modules)g (used)g(b)n(y)f(a)h(scr)r(ipt)0 4759 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e (2.3.)0 4905 y(This)h(module)e(pro)o(vides)g(a)j FJ(ModuleFinder)d FN(class)i(that)g(can)g(be)g(used)f(to)h(determine)e(the)i(set)h(of)e (modules)g(imported)f(by)i(a)g(script.)0 5005 y FJ(modulefinder.py)e FN(can)h(also)h(be)g(run)f(as)i(a)f(script,)g(gi)n(ving)e(the)i (\002lename)f(of)h(a)g(Python)f(script)h(as)g(its)h(ar)o(gument,)c (after)j(which)f(a)0 5105 y(report)g(of)h(the)g(imported)f(modules)g (will)i(be)f(printed.)0 5252 y FD(AddPackagePath)p FJ(\()p FK(pkg)p 876 5252 25 4 v 26 w(name)o(,)f(path)p FJ(\))208 5351 y FN(Record)g(that)h(the)h(package)d(named)h FK(pkg)p 1396 5351 V 29 w(name)h FN(can)g(be)g(found)e(in)j(the)f(speci\002ed)g FK(path)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(870)2590 b(Chapter)24 b(29.)52 b(Impor)s(ting)24 b(Modules)p eop end %%Page: 871 883 TeXDict begin 871 882 bop 0 83 a FD(ReplacePackage)p FJ(\()p FK(oldname)o(,)16 b(ne)o(wname)p FJ(\))208 183 y FN(Allo)n(ws)22 b(specifying)f(that)h(the)g(module)f(named)g FK(oldname)g FN(is)i(in)g(f)o(act)f(the)g(package)f(named)g FK(ne)o(wname)p FN(.)30 b(The)22 b(most)g(common)208 282 y(usage)d(w)o(ould)h(be)g(to)g(handle)f(ho)n(w)h(the)g FJ(_xmlplus)g FN(package)e(replaces)i(the)g FJ(xml)g FN(package.)0 429 y FL(class)h FD(ModuleFinder)p FJ(\()p FC([)p FK(path=None)o(,)16 b(deb)n(ug=0,)i(e)n(xcludes=[],)i(r)m (eplace)p 2332 429 25 4 v 29 w(paths=[])12 b FC(])p FJ(\))208 529 y FN(This)22 b(class)h(pro)o(vides)d FJ(run_script\(\))h FN(and)g FJ(report\(\))h FN(methods)f(to)h(determine)f(the)h(set)h(of)f (modules)f(imported)f(by)i(a)208 628 y(script.)35 b FK(path)22 b FN(can)i(be)f(a)h(list)h(of)e(directories)g(to)h(search)f(for)g (modules;)h(if)g(not)f(speci\002ed,)h FJ(sys.path)f FN(is)h(used.)35 b FK(deb)n(ug)22 b FN(sets)208 728 y(the)g(deb)n(ugging)e(le)n(v)o(el;) k(higher)d(v)n(alues)h(mak)o(e)g(the)h(class)g(print)f(deb)n(ugging)e (messages)j(about)e(what)i(it')-5 b(s)24 b(doing.)30 b FK(e)n(xcludes)23 b FN(is)208 828 y(a)e(list)h(of)f(module)f(names)h (to)g(e)o(xclude)f(from)g(the)h(analysis.)28 b FK(r)m(eplace)p 2225 828 V 29 w(paths)21 b FN(is)h(a)f(list)i(of)e FJ(\()p FK(oldpath)p FJ(,)47 b FK(ne)o(wpath)p FJ(\))19 b FN(tuples)i(that)208 927 y(will)f(be)h(replaced)e(in)h(module)f(paths.)0 1074 y FD(report)p FJ(\(\))208 1174 y FN(Print)g(a)h(report)e(to)h(standard) f(output)g(that)i(lists)g(the)g(modules)e(imported)g(by)g(the)i(script) f(and)g(their)g(paths,)g(as)h(well)g(as)g(modules)208 1273 y(that)g(are)g(missing)g(or)g(seem)g(to)h(be)f(missing.)0 1420 y FD(run_script)p FJ(\()p FK(pathname)p FJ(\))208 1520 y FN(Analyze)f(the)h(contents)g(of)g(the)g FK(pathname)e FN(\002le,)j(which)e(must)h(contain)g(Python)f(code.)0 1847 y FE(29.5)121 b Fx(runpy)32 b FE(\227)h(Locating)i(and)g(e)l(x)l (ecuting)g(Python)g(modules)n(.)0 2080 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2227 y(The)j FJ(runpy)f FN(module)g(is)i (used)f(to)g(locate)g(and)g(run)f(Python)g(modules)g(without)g (importing)f(them)i(\002rst.)31 b(Its)23 b(main)f(use)g(is)h(to)f (imple-)0 2327 y(ment)c(the)g FL(-m)h FN(command)e(line)h(switch)h (that)f(allo)n(ws)h(scripts)g(to)f(be)h(located)e(using)h(the)h(Python) e(module)g(namespace)g(rather)h(than)g(the)0 2426 y(\002lesystem.)0 2573 y(When)i(e)o(x)o(ecuted)e(as)j(a)g(script,)f(the)g(module)f(ef)n (fecti)n(v)o(ely)f(operates)i(as)h(follo)n(ws:)416 2811 y FA(del)44 b(sys.argv[0])88 b(#)44 b(Remove)g(the)h(runpy)e(module)h (from)g(the)h(arguments)416 2903 y(run_module\(sys.argv[0],)c (run_name="__main__",)g(alter_sys=True\))0 3189 y FN(The)20 b FJ(runpy)g FN(module)e(pro)o(vides)h(a)i(single)f(function:)0 3336 y FD(run_module)p FJ(\()p FK(mod)p 699 3336 V 27 w(name)p FC([)p FK(,)f(init)p 1098 3336 V 30 w(globals)12 b FC(])18 b([)p FK(,)j(run)p 1642 3336 V 29 w(name)12 b FC(][)p FK(,)19 b(alter)p 2141 3336 V 29 w(sys)12 b FC(])p FJ(\))208 3436 y FN(Ex)o(ecute)17 b(the)h(code)g(of)h(the)f (speci\002ed)g(module)g(and)g(return)f(the)h(resulting)g(module)f (globals)h(dictionary)-5 b(.)22 b(The)d(module')-5 b(s)17 b(code)208 3535 y(is)22 b(\002rst)h(located)e(using)g(the)h(standard)f (import)g(mechanism)f(\(refer)h(to)h(PEP)g(302)f(for)g(details\))h(and) g(then)f(e)o(x)o(ecuted)f(in)i(a)g(fresh)208 3635 y(module)c (namespace.)208 3768 y(The)28 b(optional)f(dictionary)g(ar)o(gument)f FK(init)p 1490 3768 V 30 w(globals)h FN(may)i(be)f(used)g(to)h (pre-populate)d(the)j(globals)f(dictionary)e(before)i(the)208 3867 y(code)20 b(is)i(e)o(x)o(ecuted.)27 b(The)21 b(supplied)f (dictionary)f(will)j(not)f(be)h(modi\002ed.)27 b(If)21 b(an)o(y)f(of)h(the)h(special)f(global)f(v)n(ariables)h(belo)n(w)g(are) 208 3967 y(de\002ned)e(in)h(the)g(supplied)f(dictionary)-5 b(,)18 b(those)i(de\002nitions)g(are)g(o)o(v)o(erridden)d(by)i(the)i FJ(run_module)d FN(function.)208 4100 y(The)f(special)h(global)f(v)n (ariables)f FJ(__name__)p FN(,)h FJ(__file__)p FN(,)g FJ(__loader__)g FN(and)g FJ(__builtins__)f FN(are)i(set)g(in)g(the)g (glob-)208 4199 y(als)j(dictionary)d(before)h(the)h(module)f(code)g(is) i(e)o(x)o(ecuted.)208 4332 y FJ(__name__)e FN(is)i(set)g(to)f FK(run)p 1022 4332 V 29 w(name)g FN(if)h(this)f(optional)f(ar)o(gument) f(is)j(supplied,)e(and)h(the)g FK(mod)p 2896 4332 V 29 w(name)f FN(ar)o(gument)f(otherwise.)208 4465 y FJ(__loader__)k FN(is)i(set)h(to)e(the)h(PEP)g(302)f(module)f(loader)h(used)g(to)h (retrie)n(v)o(e)e(the)i(code)e(for)h(the)h(module)e(\(This)h(loader)g (may)208 4565 y(be)d(a)g(wrapper)f(around)f(the)j(standard)e(import)g (mechanism\).)208 4698 y FJ(__file__)f FN(is)j(set)f(to)g(the)g(name)f (pro)o(vided)e(by)j(the)f(module)g(loader)-5 b(.)24 b(If)19 b(the)h(loader)f(does)g(not)h(mak)o(e)f(\002lename)g(information)208 4797 y(a)n(v)n(ailable,)g(this)i(v)n(ariable)e(is)i(set)g(to)f FJ(None)p FN(.)208 4930 y FJ(__builtins__)15 b FN(is)k(automatically)d (initialised)i(with)f(a)h(reference)e(to)i(the)f(top)h(le)n(v)o(el)f (namespace)f(of)h(the)h FJ(__builtin_-)208 5030 y(_)i FN(module.)208 5163 y(If)27 b(the)h(ar)o(gument)d FK(alter)p 923 5163 V 30 w(sys)j FN(is)h(supplied)e(and)g(e)n(v)n(aluates)g(to)h FJ(True)p FN(,)h(then)e FJ(sys.argv[0])f FN(is)j(updated)d(with)i(the)f (v)n(alue)208 5262 y(of)c FJ(__file__)g FN(and)g FJ (sys.modules[__name__])d FN(is)25 b(updated)d(with)i(a)g(temporary)e (module)g(object)h(for)g(the)h(module)p 0 5549 3901 4 v 0 5649 a FI(29.5.)52 b FJ(runpy)22 b FI(\227)i(Locating)f(and)h(e)n (x)n(ecuting)e(Python)i(modules)o(.)1659 b(871)p eop end %%Page: 872 884 TeXDict begin 872 883 bop 208 83 a FN(being)21 b(e)o(x)o(ecuted.)31 b(Both)22 b FJ(sys.argv[0])g FN(and)g FJ(sys.modules[__name__])d FN(are)k(restored)e(to)i(their)f(original)g(v)n(alues)208 183 y(before)c(the)j(function)d(returns.)208 315 y(Note)i(that)g(this)g (manipulation)e(of)i FJ(sys)g FN(is)h(not)f(thread-safe.)j(Other)d (threads)f(may)h(see)h(the)f(partially)f(initialised)h(module,)f(as)208 415 y(well)k(as)h(the)f(altered)f(list)i(of)f(ar)o(guments.)31 b(It)23 b(is)h(recommended)c(that)j(the)g FJ(sys)g FN(module)f(be)g (left)i(alone)e(when)g(in)m(v)n(oking)f(this)208 515 y(function)d(from)h(threaded)g(code.)0 662 y FL(See)i(Also:)0 808 y FN(PEP)g(338,)e(\223)p FK(Executing)f(modules)i(as)g(scripts)p FN(\224)208 908 y(PEP)g(written)g(and)g(implemented)e(by)i(Nick)g (Coghlan.)p 0 5549 3901 4 v 0 5649 a FI(872)2590 b(Chapter)24 b(29.)52 b(Impor)s(ting)24 b(Modules)p eop end %%Page: 873 885 TeXDict begin 873 884 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3471 427 y FG(THIR)n(TY)p 0 515 V 1368 978 a FT(Python)57 b(Language)f(Ser)6 b(vices)0 1468 y FN(Python)19 b(pro)o(vides)e(a)k (number)c(of)j(modules)e(to)i(assist)h(in)f(w)o(orking)e(with)i(the)g (Python)e(language.)23 b(These)d(modules)e(support)h(tok)o(eniz-)0 1568 y(ing,)h(parsing,)f(syntax)g(analysis,)h(bytecode)f(disassembly)-5 b(,)19 b(and)g(v)n(arious)g(other)h(f)o(acilities.)0 1714 y(These)g(modules)f(include:)50 1841 y FD(parser)347 b FN(Access)21 b(parse)f(trees)h(for)e(Python)g(source)h(code.)50 1940 y FD(symbol)347 b FN(Constants)21 b(representing)d(internal)h (nodes)h(of)g(the)g(parse)g(tree.)50 2040 y FD(token)397 b FN(Constants)21 b(representing)d(terminal)h(nodes)h(of)g(the)g(parse) g(tree.)50 2140 y FD(keyword)297 b FN(T)-6 b(est)21 b(whether)e(a)i (string)f(is)h(a)g(k)o(e)o(yw)o(ord)d(in)i(Python.)50 2239 y FD(tokenize)247 b FN(Le)o(xical)20 b(scanner)f(for)h(Python)f (source)g(code.)50 2339 y FD(tabnanny)247 b FN(T)-7 b(ool)20 b(for)g(detecting)f(white)h(space)g(related)g(problems)f(in)h(Python)f (source)h(\002les)h(in)f(a)h(directory)d(tree.)50 2438 y FD(pyclbr)347 b FN(Supports)19 b(information)f(e)o(xtraction)h(for)g (a)i(Python)e(class)i(bro)n(wser)-5 b(.)50 2538 y FD(py_compile)147 b FN(Compile)20 b(Python)f(source)h(\002les)h(to)f(byte-code)e (\002les.)50 2638 y FD(compileall)147 b FN(T)-7 b(ools)21 b(for)e(byte-compiling)e(all)k(Python)e(source)h(\002les)h(in)f(a)h (directory)d(tree.)50 2737 y FD(dis)497 b FN(Disassembler)20 b(for)g(Python)f(byte)h(code.)50 2837 y FD(pickletools)97 b FN(Contains)20 b(e)o(xtensi)n(v)o(e)f(comments)g(about)g(the)i (pickle)e(protocols)g(and)h(pickle-machine)d(opcodes,)i(as)i(well)f(as) h(some)f(useful)g(functions.)50 2937 y FD(distutils)197 b FN(Support)19 b(for)h(b)n(uilding)f(and)g(installing)h(Python)f (modules)g(into)h(an)g(e)o(xisting)g(Python)f(installation.)0 3302 y FE(30.1)121 b Fx(parser)32 b FE(\227)h(Access)f(Python)j(parse)f (trees)0 3535 y FN(The)22 b FJ(parser)f FN(module)f(pro)o(vides)h(an)g (interf)o(ace)g(to)h(Python')-5 b(s)22 b(internal)f(parser)g(and)g (byte-code)f(compiler)-5 b(.)29 b(The)22 b(primary)e(purpose)0 3635 y(for)f(this)h(interf)o(ace)f(is)i(to)f(allo)n(w)f(Python)g(code)g (to)h(edit)f(the)h(parse)f(tree)h(of)g(a)g(Python)e(e)o(xpression)g (and)h(create)h(e)o(x)o(ecutable)e(code)h(from)0 3734 y(this.)38 b(This)25 b(is)g(better)f(than)g(trying)f(to)i(parse)f(and)g (modify)f(an)h(arbitrary)f(Python)g(code)h(fragment)e(as)k(a)e(string)h (because)e(parsing)h(is)0 3834 y(performed)18 b(in)i(a)h(manner)d (identical)i(to)g(the)g(code)g(forming)e(the)i(application.)k(It)c(is)h (also)g(f)o(aster)-5 b(.)0 3981 y(There)26 b(are)g(a)h(fe)n(w)f(things) g(to)g(note)g(about)f(this)i(module)e(which)h(are)g(important)f(to)i (making)e(use)h(of)g(the)h(data)f(structures)g(created.)0 4080 y(This)c(is)g(not)g(a)g(tutorial)f(on)g(editing)g(the)g(parse)h (trees)f(for)g(Python)g(code,)g(b)n(ut)g(some)h(e)o(xamples)e(of)i (using)f(the)g FJ(parser)g FN(module)g(are)0 4180 y(presented.)0 4327 y(Most)30 b(importantly)-5 b(,)30 b(a)g(good)e(understanding)f(of) j(the)f(Python)g(grammar)f(processed)h(by)g(the)h(internal)f(parser)g (is)i(required.)52 b(F)o(or)0 4426 y(full)26 b(information)e(on)i(the)h (language)e(syntax,)i(refer)e(to)i(the)g FK(Python)e(Langua)o(g)o(e)f (Refer)m(ence)p FN(.)43 b(The)27 b(parser)e(itself)i(is)h(created)e (from)0 4526 y(a)e(grammar)e(speci\002cation)h(de\002ned)g(in)h(the)f (\002le)i(`)p FO(Gr)o(ammar/Gr)o(ammar)p FN(')d(in)i(the)g(standard)f (Python)f(distrib)n(ution.)34 b(The)24 b(parse)f(trees)0 4626 y(stored)31 b(in)h(the)g(AST)g(objects)f(created)g(by)g(this)h (module)f(are)g(the)h(actual)f(output)g(from)f(the)i(internal)f(parser) g(when)g(created)g(by)0 4725 y(the)26 b FJ(expr\(\))g FN(or)g FJ(suite\(\))g FN(functions,)g(described)f(belo)n(w)-5 b(.)42 b(The)26 b(AST)h(objects)f(created)g(by)g FJ(sequence2ast\(\))e FN(f)o(aithfully)0 4825 y(simulate)18 b(those)g(structures.)24 b(Be)19 b(a)o(w)o(are)f(that)g(the)g(v)n(alues)g(of)g(the)g(sequences)g (which)f(are)h(considered)f(\223correct\224)g(will)i(v)n(ary)e(from)g (one)0 4925 y(v)o(ersion)i(of)h(Python)f(to)h(another)f(as)i(the)g (formal)e(grammar)f(for)i(the)g(language)f(is)i(re)n(vised.)j(Ho)n(we)n (v)o(er)m(,)18 b(transporting)g(code)i(from)f(one)0 5024 y(Python)i(v)o(ersion)f(to)i(another)f(as)h(source)f(te)o(xt)h(will)g (al)o(w)o(ays)h(allo)n(w)f(correct)e(parse)i(trees)g(to)g(be)g(created) f(in)h(the)g(tar)o(get)f(v)o(ersion,)f(with)0 5124 y(the)25 b(only)e(restriction)h(being)g(that)g(migrating)f(to)i(an)f(older)g(v)o (ersion)f(of)i(the)f(interpreter)f(will)i(not)f(support)g(more)f (recent)h(language)0 5223 y(constructs.)j(The)20 b(parse)h(trees)h(are) e(not)h(typically)f(compatible)g(from)g(one)g(v)o(ersion)g(to)h (another)m(,)f(whereas)g(source)g(code)h(has)g(al)o(w)o(ays)0 5323 y(been)f(forw)o(ard-compatible.)p 0 5549 3901 4 v 3762 5649 a FI(873)p eop end %%Page: 874 886 TeXDict begin 874 885 bop 0 83 a FN(Each)28 b(element)g(of)g(the)g (sequences)f(returned)g(by)h FJ(ast2list\(\))f FN(or)h FJ(ast2tuple\(\))e FN(has)j(a)g(simple)f(form.)48 b(Sequences)27 b(rep-)0 183 y(resenting)f(non-terminal)f(elements)h(in)i(the)f (grammar)e(al)o(w)o(ays)j(ha)n(v)o(e)e(a)i(length)e(greater)g(than)h (one.)45 b(The)27 b(\002rst)h(element)f(is)h(an)f(in-)0 282 y(te)o(ger)h(which)f(identi\002es)i(a)g(production)c(in)k(the)f (grammar)-5 b(.)48 b(These)28 b(inte)o(gers)g(are)g(gi)n(v)o(en)f (symbolic)h(names)g(in)g(the)g(C)i(header)d(\002le)0 382 y(`)p FO(Include/g)o(r)o(aminit.h)p FN(')20 b(and)k(the)h(Python)e (module)h FJ(symbol)p FN(.)38 b(Each)24 b(additional)f(element)i(of)f (the)h(sequence)e(represents)h(a)h(compo-)0 482 y(nent)c(of)g(the)h (production)c(as)k(recognized)e(in)h(the)h(input)e(string:)28 b(these)21 b(are)h(al)o(w)o(ays)g(sequences)e(which)h(ha)n(v)o(e)g(the) g(same)h(form)e(as)j(the)0 581 y(parent.)28 b(An)22 b(important)e (aspect)h(of)h(this)g(structure)e(which)h(should)g(be)g(noted)g(is)h (that)g(k)o(e)o(yw)o(ords)e(used)h(to)h(identify)e(the)i(parent)f(node) 0 681 y(type,)e(such)h(as)h(the)f(k)o(e)o(yw)o(ord)e FJ(if)i FN(in)h(an)f FJ(if_stmt)p FN(,)f(are)h(included)e(in)i(the)g (node)f(tree)h(without)g(an)o(y)f(special)h(treatment.)k(F)o(or)c(e)o (xam-)0 780 y(ple,)g(the)h FJ(if)g FN(k)o(e)o(yw)o(ord)d(is)k (represented)d(by)h(the)g(tuple)g FJ(\(1,)50 b('if'\))p FN(,)20 b(where)g FJ(1)h FN(is)g(the)g(numeric)e(v)n(alue)h(associated) g(with)h(all)g FJ(NAME)0 880 y FN(tok)o(ens,)26 b(including)e(v)n (ariable)h(and)g(function)f(names)h(de\002ned)g(by)g(the)h(user)-5 b(.)41 b(In)26 b(an)f(alternate)g(form)g(returned)f(when)h(line)g (number)0 980 y(information)16 b(is)j(requested,)e(the)h(same)g(tok)o (en)f(might)h(be)g(represented)e(as)j FJ(\(1,)49 b('if',)g(12\))p FN(,)18 b(where)g(the)g FJ(12)g FN(represents)f(the)h(line)0 1079 y(number)g(at)j(which)f(the)g(terminal)f(symbol)h(w)o(as)h(found.) 0 1226 y(T)-6 b(erminal)29 b(elements)g(are)h(represented)e(in)h(much)g (the)h(same)g(w)o(ay)-5 b(,)31 b(b)n(ut)f(without)f(an)o(y)f(child)i (elements)f(and)g(the)h(addition)e(of)i(the)0 1326 y(source)g(te)o(xt)g (which)g(w)o(as)h(identi\002ed.)55 b(The)30 b(e)o(xample)f(of)h(the)g FJ(if)h FN(k)o(e)o(yw)o(ord)e(abo)o(v)o(e)f(is)k(representati)n(v)o(e.) 53 b(The)30 b(v)n(arious)g(types)g(of)0 1425 y(terminal)19 b(symbols)h(are)g(de\002ned)f(in)i(the)f(C)h(header)e(\002le)i(`)p FO(Include/tok)o(en.h)p FN(')15 b(and)20 b(the)g(Python)f(module)g FJ(token)p FN(.)0 1572 y(The)28 b(AST)g(objects)g(are)g(not)f(required) f(to)j(support)d(the)i(functionality)e(of)i(this)g(module,)h(b)n(ut)f (are)f(pro)o(vided)f(for)h(three)h(purposes:)0 1672 y(to)23 b(allo)n(w)h(an)f(application)f(to)h(amortize)f(the)i(cost)f(of)g (processing)f(comple)o(x)g(parse)h(trees,)h(to)f(pro)o(vide)f(a)h (parse)g(tree)h(representation)0 1772 y(which)e(conserv)o(es)e(memory)h (space)h(when)f(compared)f(to)i(the)h(Python)d(list)k(or)d(tuple)h (representation,)e(and)i(to)g(ease)h(the)f(creation)f(of)0 1871 y(additional)d(modules)g(in)i(C)g(which)f(manipulate)f(parse)h (trees.)25 b(A)20 b(simple)f(\223wrapper\224)e(class)k(may)e(be)g (created)g(in)g(Python)f(to)i(hide)f(the)0 1971 y(use)h(of)g(AST)h (objects.)0 2118 y(The)j FJ(parser)f FN(module)g(de\002nes)h(functions) f(for)g(a)i(fe)n(w)f(distinct)g(purposes.)36 b(The)23 b(most)i(important)d(purposes)h(are)h(to)g(create)g(AST)0 2217 y(objects)g(and)f(to)h(con)m(v)o(ert)e(AST)i(objects)g(to)g(other) f(representations)f(such)h(as)i(parse)f(trees)g(and)f(compiled)g(code)g (objects,)h(b)n(ut)g(there)0 2317 y(are)c(also)h(functions)d(which)i (serv)o(e)g(to)g(query)f(the)h(type)g(of)g(parse)g(tree)g(represented)e (by)i(an)g(AST)h(object.)0 2464 y FL(See)g(Also:)0 2611 y FN(Module)e FJ(symbol)h FN(\(section)f(30.2\):)208 2710 y(Useful)h(constants)f(representing)g(internal)g(nodes)g(of)h(the) g(parse)g(tree.)0 2857 y(Module)f FJ(token)h FN(\(section)f(30.3\):)208 2957 y(Useful)h(constants)f(representing)g(leaf)h(nodes)f(of)h(the)g (parse)g(tree)g(and)g(functions)f(for)g(testing)i(node)e(v)n(alues.)0 3242 y Fv(30.1.1)101 b(Creating)29 b(AST)f(Objects)0 3445 y FN(AST)j(objects)g(may)f(be)h(created)f(from)g(source)g(code)g (or)g(from)g(a)h(parse)g(tree.)56 b(When)31 b(creating)f(an)g(AST)i (object)e(from)g(source,)0 3544 y(dif)n(ferent)19 b(functions)f(are)i (used)g(to)h(create)f(the)g FJ('eval')f FN(and)h FJ('exec')g FN(forms.)0 3691 y FD(expr)p FJ(\()p FK(sour)m(ce)p FJ(\))208 3791 y FN(The)c FJ(expr\(\))h FN(function)e(parses)i(the)g(parameter)e FK(sour)m(ce)i FN(as)h(if)f(it)h(were)f(an)f(input)h(to)g(`)p FJ(compile\()p FK(sour)m(ce)p FJ(,)47 b('file.py',)208 3890 y('eval'\))p FN('.)59 b(If)33 b(the)f(parse)g(succeeds,)i(an)e (AST)h(object)f(is)h(created)e(to)i(hold)e(the)h(internal)g(parse)g (tree)g(representation,)208 3990 y(otherwise)19 b(an)h(appropriate)e(e) o(xception)g(is)j(thro)n(wn.)0 4137 y FD(suite)p FJ(\()p FK(sour)m(ce)p FJ(\))208 4236 y FN(The)52 b FJ(suite\(\))g FN(function)e(parses)j(the)g(parameter)e FK(sour)m(ce)h FN(as)h(if)g(it)g(were)g(an)f(input)g(to)h(`)p FJ(compile\()p FK(sour)m(ce)p FJ(,)208 4336 y('file.py',)48 b('exec'\))p FN('.)55 b(If)31 b(the)g(parse)f(succeeds,)j(an)e(AST)g(object)f(is)i (created)e(to)h(hold)f(the)h(internal)f(parse)h(tree)208 4436 y(representation,)17 b(otherwise)j(an)g(appropriate)e(e)o (xception)g(is)j(thro)n(wn.)0 4583 y FD(sequence2ast)p FJ(\()p FK(sequence)p FJ(\))208 4682 y FN(This)26 b(function)e(accepts) i(a)h(parse)f(tree)g(represented)e(as)j(a)g(sequence)e(and)g(b)n(uilds) h(an)g(internal)g(representation)e(if)i(possible.)208 4782 y(If)f(it)h(can)f(v)n(alidate)g(that)h(the)f(tree)h(conforms)d(to) j(the)g(Python)e(grammar)g(and)h(all)h(nodes)e(are)i(v)n(alid)f(node)f (types)h(in)h(the)g(host)208 4881 y(v)o(ersion)16 b(of)h(Python,)f(an)h (AST)h(object)e(is)j(created)d(from)g(the)i(internal)e(representation)f (and)i(returned)e(to)j(the)f(called.)24 b(If)17 b(there)g(is)208 4981 y(a)j(problem)f(creating)g(the)i(internal)e(representation,)f(or)i (if)h(the)f(tree)h(cannot)e(be)h(v)n(alidated,)f(a)i FJ(ParserError)e FN(e)o(xception)g(is)208 5081 y(thro)n(wn.)k(An)c(AST) g(object)f(created)g(this)h(w)o(ay)g(should)f(not)g(be)h(assumed)f(to)h (compile)f(correctly;)g(normal)g(e)o(xceptions)f(thro)n(wn)208 5180 y(by)25 b(compilation)f(may)i(still)h(be)f(initiated)f(when)h(the) g(AST)g(object)f(is)i(passed)f(to)g FJ(compileast\(\))p FN(.)41 b(This)26 b(may)f(indicate)208 5280 y(problems)18 b(not)h(related)g(to)h(syntax)f(\(such)g(as)i(a)f FJ(MemoryError)e FN(e)o(xception\),)f(b)n(ut)j(may)f(also)h(be)g(due)f(to)h(constructs)e (such)i(as)208 5380 y(the)g(result)g(of)g(parsing)f FJ(del)49 b(f\(0\))p FN(,)20 b(which)g(escapes)g(the)g(Python)f(parser)h(b)n(ut)g (is)h(check)o(ed)e(by)h(the)g(bytecode)f(compiler)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(874)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 875 887 TeXDict begin 875 886 bop 208 83 a FN(Sequences)37 b(representing)g (terminal)g(tok)o(ens)h(may)g(be)h(represented)e(as)i(either)f(tw)o (o-element)f(lists)j(of)f(the)f(form)g FJ(\(1,)208 183 y('name'\))29 b FN(or)h(as)h(three-element)d(lists)k(of)e(the)g(form)g FJ(\(1,)49 b('name',)f(56\))p FN(.)56 b(If)30 b(the)g(third)g(element)f (is)j(present,)g(it)f(is)208 282 y(assumed)20 b(to)h(be)f(a)i(v)n(alid) e(line)h(number)-5 b(.)25 b(The)c(line)f(number)f(may)i(be)f (speci\002ed)h(for)f(an)o(y)g(subset)h(of)f(the)h(terminal)f(symbols)g (in)208 382 y(the)g(input)f(tree.)0 529 y FD(tuple2ast)p FJ(\()p FK(sequence)p FJ(\))208 628 y FN(This)h(is)h(the)f(same)h (function)d(as)j FJ(sequence2ast\(\))p FN(.)i(This)d(entry)g(point)f (is)i(maintained)e(for)g(backw)o(ard)g(compatibility)-5 b(.)0 913 y Fv(30.1.2)101 b(Con)n(v)n(er)t(ting)28 b(AST)h(Objects)0 1116 y FN(AST)21 b(objects,)f(re)o(gardless)f(of)i(the)g(input)e(used)i (to)g(create)f(them,)g(may)g(be)h(con)m(v)o(erted)d(to)j(parse)f(trees) h(represented)e(as)j(list-)f(or)f(tuple-)0 1216 y(trees,)i(or)g(may)g (be)f(compiled)g(into)h(e)o(x)o(ecutable)e(code)h(objects.)30 b(P)o(arse)22 b(trees)g(may)g(be)g(e)o(xtracted)e(with)i(or)g(without)f (line)h(numbering)0 1315 y(information.)0 1462 y FD(ast2list)p FJ(\()p FK(ast)q FC([)p FK(,)d(line)p 758 1462 25 4 v 29 w(info)12 b FC(])p FJ(\))208 1562 y FN(This)21 b(function)f(accepts) i(an)f(AST)h(object)f(from)f(the)i(caller)f(in)h FK(ast)i FN(and)d(returns)f(a)i(Python)f(list)h(representing)e(the)h(equi)n(v)n (alent)208 1662 y(parse)g(tree.)29 b(The)21 b(resulting)g(list)i (representation)c(can)i(be)h(used)f(for)g(inspection)g(or)g(the)h (creation)e(of)h(a)h(ne)n(w)g(parse)f(tree)h(in)f(list)208 1761 y(form.)41 b(This)26 b(function)f(does)h(not)f(f)o(ail)i(so)f (long)f(as)i(memory)e(is)i(a)n(v)n(ailable)e(to)h(b)n(uild)g(the)g (list)h(representation.)41 b(If)26 b(the)g(parse)208 1861 y(tree)e(will)h(only)f(be)g(used)g(for)g(inspection,)g FJ(ast2tuple\(\))f FN(should)g(be)h(used)h(instead)f(to)g(reduce)f (memory)g(consumption)208 1960 y(and)c(fragmentation.)j(When)e(the)g (list)i(representation)c(is)j(required,)d(this)i(function)f(is)i (signi\002cantly)e(f)o(aster)h(than)g(retrie)n(ving)e(a)208 2060 y(tuple)h(representation)f(and)i(con)m(v)o(erting)d(that)k(to)f (nested)g(lists.)208 2193 y(If)26 b FK(line)p 420 2193 V 29 w(info)h FN(is)g(true,)h(line)e(number)f(information)f(will)j(be)g (included)e(for)g(all)j(terminal)d(tok)o(ens)h(as)i(a)f(third)e (element)h(of)h(the)208 2293 y(list)22 b(representing)e(the)h(tok)o (en.)28 b(Note)21 b(that)h(the)g(line)f(number)f(pro)o(vided)f (speci\002es)j(the)f(line)h(on)f(which)g(the)g(tok)o(en)g FK(ends)p FN(.)28 b(This)208 2392 y(information)17 b(is)k(omitted)f(if) g(the)h(\003ag)f(is)h(f)o(alse)g(or)f(omitted.)0 2539 y FD(ast2tuple)p FJ(\()p FK(ast)q FC([)p FK(,)f(line)p 808 2539 V 29 w(info)12 b FC(])p FJ(\))208 2639 y FN(This)18 b(function)e(accepts)i(an)g(AST)g(object)f(from)g(the)h(caller)g(in)g FK(ast)i FN(and)e(returns)f(a)h(Python)f(tuple)g(representing)f(the)i (equi)n(v)n(alent)208 2738 y(parse)h(tree.)25 b(Other)20 b(than)g(returning)e(a)j(tuple)e(instead)h(of)g(a)h(list,)g(this)g (function)d(is)j(identical)f(to)g FJ(ast2list\(\))p FN(.)208 2871 y(If)g FK(line)p 414 2871 V 29 w(info)g FN(is)h(true,)f(line)g (number)e(information)g(will)j(be)f(included)f(for)g(all)i(terminal)e (tok)o(ens)h(as)h(a)f(third)g(element)f(of)h(the)g(list)208 2971 y(representing)e(the)i(tok)o(en.)k(This)c(information)e(is)j (omitted)f(if)g(the)g(\003ag)h(is)g(f)o(alse)g(or)e(omitted.)0 3118 y FD(compileast)p FJ(\()p FK(ast)q FC([)p FK(,)g(\002lename)48 b Fn(=)h('<ast>')12 b FC(])p FJ(\))208 3217 y FN(The)29 b(Python)f(byte)h(compiler)f(can)i(be)f(in)m(v)n(ok)o(ed)f(on)h(an)h (AST)f(object)g(to)h(produce)e(code)g(objects)i(which)f(can)g(be)h (used)f(as)208 3317 y(part)d(of)g(an)g FJ(exec)g FN(statement)g(or)h(a) f(call)h(to)g(the)f(b)n(uilt-in)g FJ(eval\(\))g FN(function.)42 b(This)26 b(function)f(pro)o(vides)f(the)j(interf)o(ace)e(to)208 3417 y(the)e(compiler)m(,)g(passing)h(the)g(internal)f(parse)g(tree)h (from)f FK(ast)i FN(to)f(the)g(parser)m(,)g(using)f(the)h(source)f (\002le)h(name)g(speci\002ed)f(by)h(the)208 3516 y FK(\002lename)19 b FN(parameter)-5 b(.)23 b(The)d(def)o(ault)g(v)n(alue)f(supplied)g (for)h FK(\002lename)f FN(indicates)h(that)g(the)g(source)g(w)o(as)h (an)f(AST)h(object.)208 3649 y(Compiling)48 b(an)h(AST)h(object)e(may)h (result)h(in)f(e)o(xceptions)f(related)g(to)i(compilation;)62 b(an)49 b(e)o(xample)f(w)o(ould)h(be)g(a)208 3749 y FJ(SyntaxError)28 b FN(caused)h(by)g(the)h(parse)f(tree)g(for)g FJ(del)50 b(f\(0\))p FN(:)44 b(this)30 b(statement)f(is)i(considered)c(le)o(gal)i (within)h(the)f(for)n(-)208 3848 y(mal)d(grammar)e(for)i(Python)e(b)n (ut)j(is)g(not)e(a)i(le)o(gal)e(language)g(construct.)41 b(The)26 b FJ(SyntaxError)e FN(raised)i(for)g(this)g(condition)208 3948 y(is)f(actually)f(generated)f(by)h(the)g(Python)g(byte-compiler)d (normally)-5 b(,)24 b(which)g(is)h(why)f(it)h(can)f(be)g(raised)h(at)g (this)g(point)e(by)i(the)208 4047 y FJ(parser)d FN(module.)32 b(Most)23 b(causes)g(of)g(compilation)e(f)o(ailure)h(can)h(be)g (diagnosed)e(programmatically)f(by)i(inspection)g(of)h(the)208 4147 y(parse)c(tree.)0 4432 y Fv(30.1.3)101 b(Quer)q(ies)29 b(on)f(AST)h(Objects)0 4635 y FN(T)-7 b(w)o(o)19 b(functions)e(are)i (pro)o(vided)d(which)i(allo)n(w)g(an)h(application)e(to)i(determine)e (if)i(an)f(AST)h(w)o(as)g(created)f(as)i(an)e(e)o(xpression)f(or)h(a)h (suite.)0 4735 y(Neither)e(of)f(these)i(functions)d(can)i(be)g(used)g (to)g(determine)f(if)h(an)g(AST)h(w)o(as)g(created)e(from)g(source)g (code)h(via)g FJ(expr\(\))g FN(or)f FJ(suite\(\))0 4834 y FN(or)k(from)f(a)i(parse)f(tree)g(via)g FJ(sequence2ast\(\))p FN(.)0 4981 y FD(isexpr)p FJ(\()p FK(ast)q FJ(\))208 5081 y FN(When)f FK(ast)j FN(represents)c(an)i FJ('eval')f FN(form,)g(this)h(function)e(returns)g(true,)i(otherwise)f(it)h (returns)f(f)o(alse.)25 b(This)20 b(is)g(useful,)f(since)208 5180 y(code)26 b(objects)i(normally)e(cannot)g(be)i(queried)e(for)h (this)h(information)d(using)i(e)o(xisting)g(b)n(uilt-in)g(functions.)45 b(Note)28 b(that)g(the)208 5280 y(code)23 b(objects)h(created)f(by)h FJ(compileast\(\))e FN(cannot)h(be)h(queried)e(lik)o(e)j(this)f(either) m(,)g(and)g(are)g(identical)f(to)h(those)g(created)208 5380 y(by)19 b(the)i(b)n(uilt-in)e FJ(compile\(\))g FN(function.)p 0 5549 3901 4 v 0 5649 a FI(30.1.)52 b FJ(parser)22 b FI(\227)h(Access)f(Python)i(parse)e(trees)2110 b(875)p eop end %%Page: 876 888 TeXDict begin 876 887 bop 0 83 a FD(issuite)p FJ(\()p FK(ast)q FJ(\))208 183 y FN(This)23 b(function)f(mirrors)h FJ(isexpr\(\))f FN(in)i(that)g(it)g(reports)f(whether)f(an)i(AST)g (object)f(represents)g(an)g FJ('exec')g FN(form,)g(com-)208 282 y(monly)e(kno)n(wn)g(as)i(a)g(\223suite.)-6 b(\224)32 b(It)23 b(is)h(not)e(safe)g(to)h(assume)g(that)f(this)h(function)e(is)j (equi)n(v)n(alent)c(to)j(`)p FJ(not)49 b(isexpr\()p FK(ast)q FJ(\))p FN(',)22 b(as)208 382 y(additional)c(syntactic)i(fragments)f (may)h(be)g(supported)e(in)i(the)h(future.)0 667 y Fv(30.1.4)101 b(Exceptions)29 b(and)f(Error)h(Handling)0 870 y FN(The)24 b(parser)f(module)f(de\002nes)i(a)g(single)g(e)o(xception,)e(b)n(ut)i (may)g(also)g(pass)g(other)f(b)n(uilt-in)g(e)o(xceptions)g(from)f (other)h(portions)g(of)h(the)0 969 y(Python)19 b(runtime)g(en)m (vironment.)j(See)f(each)e(function)g(for)g(information)f(about)h(the)i (e)o(xceptions)d(it)j(can)f(raise.)0 1116 y FL(exception)f FD(ParserError)208 1216 y FN(Exception)27 b(raised)j(when)e(a)i(f)o (ailure)f(occurs)g(within)g(the)h(parser)f(module.)51 b(This)30 b(is)g(generally)e(produced)f(for)i(v)n(alidation)208 1315 y(f)o(ailures)17 b(rather)h(than)f(the)h(b)n(uilt)g(in)h FJ(SyntaxError)d FN(thro)n(wn)h(during)f(normal)h(parsing.)23 b(The)18 b(e)o(xception)e(ar)o(gument)g(is)j(either)208 1415 y(a)26 b(string)g(describing)f(the)h(reason)f(of)h(the)g(f)o (ailure)g(or)g(a)g(tuple)g(containing)e(a)j(sequence)e(causing)g(the)i (f)o(ailure)e(from)g(a)i(parse)208 1515 y(tree)22 b(passed)g(to)g FJ(sequence2ast\(\))e FN(and)i(an)g(e)o(xplanatory)e(string.)30 b(Calls)24 b(to)e FJ(sequence2ast\(\))e FN(need)i(to)g(be)g(able)g(to) 208 1614 y(handle)g(either)i(type)f(of)h(e)o(xception,)e(while)i(calls) h(to)f(other)f(functions)f(in)i(the)g(module)e(will)j(only)e(need)g(to) h(be)g(a)o(w)o(are)f(of)h(the)208 1714 y(simple)c(string)g(v)n(alues.)0 1861 y(Note)f(that)g(the)f(functions)g FJ(compileast\(\))p FN(,)f FJ(expr\(\))p FN(,)h(and)g FJ(suite\(\))g FN(may)h(thro)n(w)f(e) o(xceptions)f(which)h(are)h(normally)e(thro)n(wn)0 1960 y(by)24 b(the)g(parsing)f(and)g(compilation)g(process.)36 b(These)24 b(include)f(the)h(b)n(uilt)h(in)f(e)o(xceptions)e FJ(MemoryError)p FN(,)i FJ(OverflowError)p FN(,)0 2060 y FJ(SyntaxError)p FN(,)29 b(and)e FJ(SystemError)p FN(.)48 b(In)28 b(these)h(cases,)i(these)d(e)o(xceptions)f(carry)g(all)i(the)f (meaning)f(normally)g(associated)0 2160 y(with)20 b(them.)25 b(Refer)20 b(to)g(the)h(descriptions)e(of)h(each)f(function)g(for)g (detailed)h(information.)0 2445 y Fv(30.1.5)101 b(AST)28 b(Objects)0 2648 y FN(Ordered)21 b(and)h(equality)g(comparisons)f(are)h (supported)f(between)g(AST)i(objects.)32 b(Pickling)22 b(of)h(AST)f(objects)h(\(using)f(the)g FJ(pickle)0 2747 y FN(module\))c(is)k(also)e(supported.)0 2894 y FD(ASTType)208 2994 y FN(The)f(type)h(of)g(the)g(objects)g(returned)f(by)g FJ(expr\(\))p FN(,)h FJ(suite\(\))f FN(and)h FJ(sequence2ast\(\))p FN(.)0 3141 y(AST)h(objects)f(ha)n(v)o(e)f(the)h(follo)n(wing)f (methods:)0 3287 y FD(compile)p FJ(\()p FC([)p FK(\002lename)12 b FC(])p FJ(\))208 3387 y FN(Same)20 b(as)h FJ(compileast\()p FK(ast)q FJ(,)48 b FK(\002lename)p FJ(\))p FN(.)0 3534 y FD(isexpr)p FJ(\(\))208 3634 y FN(Same)20 b(as)h FJ(isexpr\()p FK(ast)q FJ(\))p FN(.)0 3780 y FD(issuite)p FJ(\(\))208 3880 y FN(Same)f(as)h FJ(issuite\()p FK(ast)q FJ(\))p FN(.)0 4027 y FD(tolist)p FJ(\()p FC([)p FK(line)p 520 4027 25 4 v 28 w(info)12 b FC(])p FJ(\))208 4126 y FN(Same)20 b(as)h FJ(ast2list\()p FK(ast)q FJ(,)48 b FK(line)p 1279 4126 V 29 w(info)p FJ(\))p FN(.)0 4273 y FD(totuple)p FJ(\()p FC([)p FK(line)p 570 4273 V 28 w(info)12 b FC(])p FJ(\))208 4373 y FN(Same)20 b(as)h FJ(ast2tuple\()p FK(ast)q FJ(,)48 b FK(line)p 1329 4373 V 29 w(info)p FJ(\))p FN(.)0 4658 y Fv(30.1.6)101 b(Examples)0 4861 y FN(The)25 b(parser)f(modules)g (allo)n(ws)i(operations)d(to)j(be)f(performed)d(on)j(the)g(parse)g (tree)g(of)g(Python)f(source)g(code)g(before)g(the)h(bytecode)0 4960 y(is)31 b(generated,)f(and)f(pro)o(vides)f(for)h(inspection)g(of)g (the)h(parse)g(tree)g(for)f(information)e(gathering)h(purposes.)52 b(T)-7 b(w)o(o)30 b(e)o(xamples)f(are)0 5060 y(presented.)22 b(The)16 b(simple)f(e)o(xample)g(demonstrates)f(emulation)g(of)i(the)f FJ(compile\(\))g FN(b)n(uilt-in)g(function)f(and)h(the)h(comple)o(x)e (e)o(xample)0 5160 y(sho)n(ws)20 b(the)g(use)h(of)f(a)g(parse)g(tree)h (for)e(information)f(disco)o(v)o(ery)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(876)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 877 889 TeXDict begin 877 888 bop 0 83 a FI(Em)o(ulation)25 b(of)f FJ(compile\(\))0 286 y FN(While)g(man)o(y)e(useful)h(operations)f(may)h (tak)o(e)h(place)f(between)g(parsing)f(and)h(bytecode)f(generation,)g (the)h(simplest)h(operation)e(is)i(to)0 386 y(do)c(nothing.)j(F)o(or)d (this)g(purpose,)f(using)g(the)i FJ(parser)e FN(module)g(to)h(produce)f (an)h(intermediate)e(data)i(structure)g(is)h(equi)n(v)n(alent)d(to)j (the)0 485 y(code)236 723 y FA(>>>)45 b(code)f(=)g(compile\('a)g(+)g (5',)h('file.py',)e('eval'\))236 815 y(>>>)i(a)f(=)h(5)236 906 y(>>>)g(eval\(code\))236 997 y(10)0 1284 y FN(The)25 b(equi)n(v)n(alent)e(operation)h(using)g(the)h FJ(parser)g FN(module)f(is)i(some)n(what)e(longer)m(,)h(and)f(allo)n(ws)i(the)f (intermediate)e(internal)i(parse)0 1383 y(tree)20 b(to)h(be)f(retained) f(as)i(an)f(AST)g(object:)236 1622 y FA(>>>)45 b(import)e(parser)236 1713 y(>>>)i(ast)f(=)h(parser.expr\('a)d(+)j(5'\))236 1804 y(>>>)g(code)f(=)g(ast.compile\('file.py'\))236 1896 y(>>>)h(a)f(=)h(5)236 1987 y(>>>)g(eval\(code\))236 2078 y(10)0 2365 y FN(An)20 b(application)f(which)h(needs)f(both)h(AST) g(and)g(code)f(objects)h(can)g(package)f(this)i(code)e(into)h(readily)g (a)n(v)n(ailable)f(functions:)236 2603 y FA(import)44 b(parser)236 2786 y(def)h(load_suite\(source_string\):)416 2877 y(ast)f(=)h(parser.suite\(source_string\))416 2968 y(return)e(ast,)i(ast.compile\(\))236 3151 y(def)g (load_expression\(source_string\):)416 3242 y(ast)f(=)h (parser.expr\(source_string\))416 3334 y(return)e(ast,)i (ast.compile\(\))0 3746 y FI(Inf)n(or)r(mation)24 b(Disco)o(v)n(er)r(y) 0 3948 y FN(Some)h(applications)g(bene\002t)g(from)g(direct)h(access)g (to)g(the)g(parse)f(tree.)42 b(The)26 b(remainder)d(of)j(this)g (section)g(demonstrates)e(ho)n(w)i(the)0 4048 y(parse)19 b(tree)g(pro)o(vides)e(access)j(to)f(module)f(documentation)e (de\002ned)i(in)i(docstrings)d(without)i(requiring)e(that)i(the)g(code) g(being)f(e)o(xam-)0 4148 y(ined)23 b(be)h(loaded)e(into)h(a)h(running) e(interpreter)g(via)h FJ(import)p FN(.)35 b(This)23 b(can)h(be)f(v)o (ery)g(useful)g(for)g(performing)d(analyses)k(of)f(untrusted)0 4247 y(code.)0 4394 y(Generally)-5 b(,)24 b(the)g(e)o(xample)f(will)i (demonstrate)e(ho)n(w)h(the)h(parse)f(tree)g(may)g(be)g(tra)n(v)o (ersed)g(to)g(distill)i(interesting)d(information.)35 b(T)-7 b(w)o(o)0 4494 y(functions)30 b(and)h(a)g(set)h(of)f(classes)i (are)e(de)n(v)o(eloped)e(which)i(pro)o(vide)e(programmatic)g(access)i (to)h(high)e(le)n(v)o(el)h(function)f(and)h(class)0 4593 y(de\002nitions)g(pro)o(vided)e(by)i(a)h(module.)59 b(The)31 b(classes)i(e)o(xtract)e(information)e(from)i(the)g(parse)h(tree)g(and) f(pro)o(vide)e(access)k(to)f(the)0 4693 y(information)21 b(at)j(a)f(useful)g(semantic)g(le)n(v)o(el,)g(one)g(function)f(pro)o (vides)f(a)j(simple)f(lo)n(w-le)n(v)o(el)f(pattern)h(matching)e (capability)-5 b(,)23 b(and)g(the)0 4793 y(other)17 b(function)f (de\002nes)h(a)h(high-le)n(v)o(el)d(interf)o(ace)i(to)h(the)f(classes)i (by)e(handling)f(\002le)i(operations)e(on)h(behalf)g(of)g(the)h(caller) -5 b(.)24 b(All)18 b(source)0 4892 y(\002les)26 b(mentioned)e(here)h (which)g(are)g(not)g(part)g(of)h(the)f(Python)f(installation)h(are)h (located)f(in)g(the)h(`)p FO(Demo/parser/)p FN(')d(directory)g(of)j (the)0 4992 y(distrib)n(ution.)0 5139 y(The)19 b(dynamic)f(nature)g(of) h(Python)f(allo)n(ws)h(the)g(programmer)d(a)k(great)f(deal)g(of)g (\003e)o(xibility)-5 b(,)18 b(b)n(ut)h(most)g(modules)f(need)h(only)f (a)i(limited)0 5238 y(measure)29 b(of)i(this)f(when)g(de\002ning)f (classes,)34 b(functions,)d(and)f(methods.)54 b(In)30 b(this)h(e)o(xample,)g(the)f(only)g(de\002nitions)f(that)i(will)g(be)0 5338 y(considered)19 b(are)i(those)g(which)f(are)h(de\002ned)f(in)i (the)f(top)f(le)n(v)o(el)h(of)g(their)f(conte)o(xt,)g(e.g.,)h(a)g (function)e(de\002ned)h(by)h(a)g FJ(def)g FN(statement)g(at)p 0 5549 3901 4 v 0 5649 a FI(30.1.)52 b FJ(parser)22 b FI(\227)h(Access)f(Python)i(parse)e(trees)2110 b(877)p eop end %%Page: 878 890 TeXDict begin 878 889 bop 0 83 a FN(column)24 b(zero)g(of)h(a)h (module,)f(b)n(ut)g(not)f(a)i(function)d(de\002ned)i(within)f(a)i (branch)e(of)g(an)h FJ(if)h FN(...)40 b FJ(else)25 b FN(construct,)g(though)e(there)i(are)0 183 y(some)f(good)e(reasons)i (for)f(doing)g(so)h(in)g(some)g(situations.)36 b(Nesting)24 b(of)g(de\002nitions)f(will)i(be)f(handled)e(by)i(the)g(code)f(de)n(v)o (eloped)e(in)0 282 y(the)f(e)o(xample.)0 429 y(T)-7 b(o)26 b(construct)g(the)g(upper)n(-le)n(v)o(el)e(e)o(xtraction)g(methods,)j (we)g(need)e(to)i(kno)n(w)e(what)h(the)g(parse)g(tree)h(structure)e (looks)h(lik)o(e)g(and)g(ho)n(w)0 529 y(much)g(of)i(it)g(we)g(actually) e(need)h(to)h(be)f(concerned)e(about.)46 b(Python)26 b(uses)i(a)g(moderately)d(deep)i(parse)g(tree)h(so)f(there)g(are)h(a)g (lar)o(ge)0 628 y(number)c(of)i(intermediate)e(nodes.)42 b(It)26 b(is)h(important)d(to)i(read)g(and)f(understand)f(the)i(formal) f(grammar)f(used)i(by)f(Python.)41 b(This)27 b(is)0 728 y(speci\002ed)19 b(in)h(the)g(\002le)g(`)p FO(Gr)o(ammar/Gr)o(ammar)p FN(')f(in)h(the)g(distrib)n(ution.)j(Consider)d(the)f(simplest)h(case)h (of)e(interest)h(when)f(searching)f(for)0 828 y(docstrings:)24 b(a)d(module)e(consisting)g(of)h(a)h(docstring)d(and)i(nothing)e(else.) 26 b(\(See)20 b(\002le)h(`)p FO(docstr)q(ing.p)n(y)p FN('.\))236 1066 y FA("""Some)44 b(documentation.)236 1157 y(""")0 1444 y FN(Using)20 b(the)g(interpreter)e(to)i(tak)o(e)g(a) h(look)e(at)h(the)g(parse)g(tree,)f(we)i(\002nd)e(a)i(be)n(wildering)d (mass)i(of)g(numbers)e(and)i(parentheses,)e(with)j(the)0 1543 y(documentation)c(b)n(uried)i(deep)h(in)g(nested)g(tuples.)236 1782 y FA(>>>)45 b(import)e(parser)236 1873 y(>>>)i(import)e(pprint)236 1964 y(>>>)i(ast)f(=)h(parser.suite\(open\('docstring.py'\).re)o (ad\(\)\))236 2055 y(>>>)g(tup)f(=)h(ast.totuple\(\))236 2147 y(>>>)g(pprint.pprint\(tup\))236 2238 y(\(257,)281 2329 y(\(264,)326 2421 y(\(265,)371 2512 y(\(266,)416 2603 y(\(267,)460 2695 y(\(307,)505 2786 y(\(287,)550 2877 y(\(288,)595 2969 y(\(289,)640 3060 y(\(290,)685 3151 y(\(292,)729 3243 y(\(293,)774 3334 y(\(294,)819 3425 y(\(295,)864 3517 y(\(296,)909 3608 y(\(297,)954 3699 y(\(298,)998 3791 y(\(299,)1043 3882 y(\(300,)f(\(3,)h('"""Some)e (documentation.\\n"""'\)\)\)\)\)\)\)\)\)\)\)\)\)\)\)\)\),)371 3973 y(\(4,)h(''\)\)\),)281 4065 y(\(4,)g(''\),)281 4156 y(\(0,)g(''\)\))0 4442 y FN(The)24 b(numbers)e(at)j(the)f(\002rst)h (element)e(of)h(each)g(node)f(in)h(the)g(tree)g(are)g(the)g(node)g (types;)h(the)o(y)f(map)f(directly)h(to)g(terminal)f(and)h(non-)0 4542 y(terminal)g(symbols)g(in)h(the)g(grammar)-5 b(.)37 b(Unfortunately)-5 b(,)23 b(the)o(y)h(are)h(represented)e(as)i(inte)o (gers)f(in)h(the)g(internal)f(representation,)f(and)0 4642 y(the)j(Python)g(structures)g(generated)e(do)i(not)h(change)e (that.)43 b(Ho)n(we)n(v)o(er)m(,)26 b(the)h FJ(symbol)f FN(and)g FJ(token)g FN(modules)f(pro)o(vide)g(symbolic)0 4741 y(names)20 b(for)f(the)i(node)e(types)h(and)f(dictionaries)h (which)f(map)h(from)f(the)h(inte)o(gers)g(to)g(the)g(symbolic)f(names)h (for)g(the)g(node)f(types.)0 4888 y(In)f(the)h(output)e(presented)h (abo)o(v)o(e,)f(the)h(outermost)g(tuple)g(contains)g(four)f(elements:) 25 b(the)18 b(inte)o(ger)g FJ(257)g FN(and)g(three)h(additional)e (tuples.)0 4988 y(Node)k(type)g FJ(257)h FN(has)g(the)f(symbolic)g (name)g FJ(file_input)p FN(.)28 b(Each)21 b(of)g(these)h(inner)f (tuples)g(contains)g(an)h(inte)o(ger)e(as)j(the)e(\002rst)i(ele-)0 5087 y(ment;)d(these)g(inte)o(gers,)e FJ(264)p FN(,)i FJ(4)p FN(,)g(and)f FJ(0)p FN(,)h(represent)f(the)h(node)e(types)i FJ(stmt)p FN(,)f FJ(NEWLINE)p FN(,)g(and)g FJ(ENDMARKER)p FN(,)g(respecti)n(v)o(ely)-5 b(.)23 b(Note)0 5187 y(that)18 b(these)g(v)n(alues)f(may)g(change)g(depending)e(on)i(the)h(v)o(ersion) e(of)i(Python)e(you)h(are)h(using;)g(consult)f(`)p FO(symbol.p)n(y)p FN(')g(and)g(`)p FO(tok)o(en.p)n(y)p FN(')e(for)0 5287 y(details)22 b(of)f(the)h(mapping.)28 b(It)22 b(should)f(be)g(f)o (airly)h(clear)f(that)h(the)g(outermost)e(node)h(is)h(related)g (primarily)e(to)i(the)f(input)g(source)g(rather)0 5386 y(than)j(the)g(contents)f(of)h(the)h(\002le,)g(and)f(may)g(be)g(disre)o (garded)d(for)j(the)g(moment.)36 b(The)24 b FJ(stmt)g FN(node)f(is)i(much)e(more)h(interesting.)36 b(In)p 0 5549 3901 4 v 0 5649 a FI(878)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 879 891 TeXDict begin 879 890 bop 0 83 a FN(particular)m(,)15 b(all)j(docstrings)d(are)i(found)e(in)h(subtrees)h(which)f(are)g (formed)f(e)o(xactly)h(as)i(this)f(node)e(is)j(formed,)d(with)i(the)g (only)f(dif)n(ference)0 183 y(being)22 b(the)h(string)g(itself.)33 b(The)23 b(association)f(between)h(the)g(docstring)e(in)i(a)h(similar)f (tree)g(and)f(the)h(de\002ned)f(entity)h(\(class,)h(function,)0 282 y(or)f(module\))f(which)h(it)h(describes)f(is)i(gi)n(v)o(en)d(by)h (the)h(position)f(of)g(the)h(docstring)e(subtree)h(within)g(the)g(tree) h(de\002ning)e(the)i(described)0 382 y(structure.)0 529 y(By)18 b(replacing)e(the)h(actual)g(docstring)f(with)i(something)e(to) h(signify)g(a)h(v)n(ariable)e(component)f(of)i(the)g(tree,)h(we)g(allo) n(w)f(a)h(simple)f(pattern)0 628 y(matching)g(approach)g(to)i(check)f (an)o(y)g(gi)n(v)o(en)f(subtree)h(for)g(equi)n(v)n(alence)f(to)i(the)g (general)e(pattern)h(for)g(docstrings.)23 b(Since)c(the)g(e)o(xample)0 728 y(demonstrates)e(information)f(e)o(xtraction,)h(we)i(can)f(safely)h (require)e(that)h(the)h(tree)f(be)h(in)f(tuple)g(form)g(rather)f(than)h (list)i(form,)e(allo)n(wing)0 828 y(a)e(simple)g(v)n(ariable)e (representation)g(to)h(be)h FJ(['variable_name'])p FN(.)21 b(A)16 b(simple)f(recursi)n(v)o(e)f(function)g(can)i(implement)e(the)h (pattern)0 927 y(matching,)k(returning)f(a)i(Boolean)g(and)f(a)i (dictionary)d(of)i(v)n(ariable)f(name)h(to)g(v)n(alue)g(mappings.)j (\(See)d(\002le)h(`)p FO(e)n(xample)o(.p)n(y)p FN('.\))236 1074 y FA(from)44 b(types)g(import)g(ListType,)g(TupleType)236 1257 y(def)h(match\(pattern,)d(data,)i(vars=None\):)416 1348 y(if)g(vars)g(is)h(None:)595 1439 y(vars)f(=)h({})416 1531 y(if)f(type\(pattern\))f(is)h(ListType:)595 1622 y(vars[pattern[0]])e(=)j(data)595 1713 y(return)f(1,)g(vars)416 1805 y(if)g(type\(pattern\))f(is)h(not)h(TupleType:)595 1896 y(return)f(\(pattern)f(==)i(data\),)f(vars)416 1987 y(if)g(len\(data\))f(!=)i(len\(pattern\):)595 2079 y(return)f(0,)g (vars)416 2170 y(for)g(pattern,)f(data)i(in)f(map\(None,)f(pattern,)h (data\):)595 2261 y(same,)g(vars)g(=)h(match\(pattern,)d(data,)i (vars\))595 2353 y(if)g(not)h(same:)774 2444 y(break)416 2535 y(return)e(same,)h(vars)0 2822 y FN(Using)29 b(this)g(simple)f (representation)f(for)h(syntactic)g(v)n(ariables)g(and)g(the)g (symbolic)g(node)g(types,)i(the)f(pattern)e(for)h(the)h(candidate)0 2921 y(docstring)19 b(subtrees)h(becomes)f(f)o(airly)h(readable.)j (\(See)e(\002le)f(`)p FO(e)n(xample)o(.p)n(y)p FN('.\))p 0 5549 3901 4 v 0 5649 a FI(30.1.)52 b FJ(parser)22 b FI(\227)h(Access)f(Python)i(parse)e(trees)2110 b(879)p eop end %%Page: 880 892 TeXDict begin 880 891 bop 236 83 a FA(import)44 b(symbol)236 174 y(import)g(token)236 357 y(DOCSTRING_STMT_PATTERN)d(=)k(\()416 448 y(symbol.stmt,)416 540 y(\(symbol.simple_stmt,)460 631 y(\(symbol.small_stmt,)505 722 y(\(symbol.expr_stmt,)550 814 y(\(symbol.testlist,)595 905 y(\(symbol.test,)640 996 y(\(symbol.and_test,)685 1088 y(\(symbol.not_test,)729 1179 y(\(symbol.comparison,)774 1270 y(\(symbol.expr,)819 1362 y(\(symbol.xor_expr,)864 1453 y(\(symbol.and_expr,)909 1544 y(\(symbol.shift_expr,)954 1636 y(\(symbol.arith_expr,)998 1727 y(\(symbol.term,)1043 1818 y(\(symbol.factor,)1088 1910 y(\(symbol.power,)1133 2001 y(\(symbol.atom,)1178 2092 y(\(token.STRING,)d(['docstring']\))1178 2183 y (\)\)\)\)\)\)\)\)\)\)\)\)\)\)\)\),)460 2275 y(\(token.NEWLINE,)h(''\)) 460 2366 y(\)\))0 2653 y FN(Using)19 b(the)g FJ(match\(\))g FN(function)e(with)i(this)h(pattern,)e(e)o(xtracting)f(the)j(module)d (docstring)h(from)g(the)h(parse)g(tree)g(created)g(pre)n(viously)0 2752 y(is)i(easy:)236 2990 y FA(>>>)45 b(found,)e(vars)i(=)f (match\(DOCSTRING_STMT_PATTERN,)c(tup[1]\))236 3082 y(>>>)45 b(found)236 3173 y(1)236 3264 y(>>>)g(vars)236 3356 y({'docstring':)e ('"""Some)g(documentation.\\n"""'})0 3642 y FN(Once)26 b(speci\002c)g(data)h(can)f(be)g(e)o(xtracted)f(from)g(a)i(location)e (where)h(it)h(is)g(e)o(xpected,)f(the)g(question)f(of)h(where)g (information)e(can)i(be)0 3742 y(e)o(xpected)d(needs)h(to)h(be)f (answered.)37 b(When)25 b(dealing)e(with)i(docstrings,)f(the)h(answer)f (is)h(f)o(airly)f(simple:)34 b(the)25 b(docstring)e(is)i(the)g(\002rst) 0 3842 y FJ(stmt)16 b FN(node)f(in)i(a)g(code)e(block)g(\()p FJ(file_input)g FN(or)h FJ(suite)g FN(node)f(types\).)23 b(A)17 b(module)e(consists)i(of)f(a)h(single)f FJ(file_input)f FN(node,)0 3941 y(and)21 b(class)i(and)e(function)e(de\002nitions)i (each)g(contain)g(e)o(xactly)g(one)g FJ(suite)g FN(node.)28 b(Classes)23 b(and)e(functions)f(are)i(readily)e(identi\002ed)0 4041 y(as)i(subtrees)f(of)h(code)e(block)h(nodes)g(which)g(start)h (with)f FJ(\(stmt,)49 b(\(compound_stmt,)e(\(classdef,)h(...)29 b FN(or)21 b FJ(\(stmt,)0 4140 y(\(compound_stmt,)47 b(\(funcdef,)h(...)p FN(.)40 b(Note)25 b(that)h(these)f(subtrees)g (cannot)f(be)h(matched)f(by)h FJ(match\(\))f FN(since)i(it)g(does)0 4240 y(not)c(support)f(multiple)h(sibling)g(nodes)f(to)i(match)f (without)f(re)o(gard)g(to)h(number)-5 b(.)30 b(A)23 b(more)e(elaborate) h(matching)f(function)f(could)i(be)0 4340 y(used)e(to)g(o)o(v)o(ercome) e(this)j(limitation,)e(b)n(ut)h(this)h(is)g(suf)n(\002cient)f(for)f (the)i(e)o(xample.)0 4487 y(Gi)n(v)o(en)15 b(the)h(ability)g(to)g (determine)f(whether)g(a)h(statement)g(might)f(be)h(a)g(docstring)f (and)g(e)o(xtract)h(the)g(actual)f(string)h(from)f(the)h(statement,)0 4586 y(some)j(w)o(ork)g(needs)h(to)f(be)h(performed)d(to)i(w)o(alk)h (the)g(parse)f(tree)h(for)f(an)g(entire)g(module)g(and)g(e)o(xtract)f (information)g(about)g(the)i(names)0 4686 y(de\002ned)h(in)g(each)h (conte)o(xt)e(of)h(the)h(module)e(and)h(associate)h(an)o(y)f (docstrings)g(with)g(the)h(names.)29 b(The)21 b(code)g(to)h(perform)e (this)i(w)o(ork)f(is)0 4785 y(not)f(complicated,)e(b)n(ut)i(bears)g (some)g(e)o(xplanation.)0 4932 y(The)j(public)f(interf)o(ace)g(to)h (the)g(classes)i(is)f(straightforw)o(ard)c(and)j(should)f(probably)f (be)i(some)n(what)f(more)g(\003e)o(xible.)33 b(Each)23 b(\223major\224)0 5032 y(block)e(of)h(the)g(module)f(is)i(described)e (by)h(an)g(object)g(pro)o(viding)d(se)n(v)o(eral)i(methods)g(for)h (inquiry)f(and)g(a)i(constructor)d(which)i(accepts)0 5132 y(at)f(least)h(the)f(subtree)f(of)g(the)h(complete)f(parse)h(tree) g(which)f(it)h(represents.)26 b(The)21 b FJ(ModuleInfo)e FN(constructor)g(accepts)i(an)g(optional)0 5231 y FK(name)f FN(parameter)e(since)j(it)g(cannot)e(otherwise)g(determine)g(the)h (name)g(of)g(the)g(module.)0 5378 y(The)29 b(public)f(classes)j (include)d FJ(ClassInfo)p FN(,)i FJ(FunctionInfo)p FN(,)g(and)e FJ(ModuleInfo)p FN(.)51 b(All)30 b(objects)f(pro)o(vide)e(the)j (methods)p 0 5549 3901 4 v 0 5649 a FI(880)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 881 893 TeXDict begin 881 892 bop 0 83 a FJ(get_name\(\))p FN(,)33 b FJ(get_docstring\(\))p FN(,)f FJ(get_class_names\(\))p FN(,)g(and)f FJ(get_class_info\(\))p FN(.)57 b(The)32 b FJ(ClassInfo)0 183 y FN(objects)k(support)e FJ(get_method_names\(\))f FN(and)i FJ(get_method_info\(\))f FN(while)h(the)h(other)f(classes)i (pro)o(vide)d FJ(get_-)0 282 y(function_names\(\))18 b FN(and)h FJ(get_function_info\(\))p FN(.)0 429 y(W)m(ithin)26 b(each)g(of)g(the)g(forms)f(of)h(code)f(block)g(that)i(the)f(public)f (classes)i(represent,)f(most)g(of)g(the)g(required)f(information)e(is)k (in)g(the)0 529 y(same)22 b(form)f(and)h(is)h(accessed)f(in)h(the)f (same)g(w)o(ay)-5 b(,)22 b(with)g(classes)i(ha)n(ving)d(the)h (distinction)f(that)h(functions)f(de\002ned)g(at)i(the)f(top)g(le)n(v)o (el)0 628 y(are)g(referred)f(to)i(as)g(\223methods.)-6 b(\224)31 b(Since)22 b(the)h(dif)n(ference)d(in)j(nomenclature)d (re\003ects)i(a)h(real)g(semantic)f(distinction)g(from)f(functions)0 728 y(de\002ned)i(outside)g(of)h(a)g(class,)i(the)d(implementation)f (needs)i(to)g(maintain)f(the)g(distinction.)36 b(Hence,)24 b(most)g(of)f(the)h(functionality)e(of)0 828 y(the)j(public)f(classes)h (can)g(be)g(implemented)e(in)h(a)i(common)c(base)j(class,)i FJ(SuiteInfoBase)p FN(,)d(with)h(the)f(accessors)h(for)f(function)0 927 y(and)e(method)e(information)g(pro)o(vided)g(else)n(where.)30 b(Note)22 b(that)h(there)e(is)j(only)d(one)h(class)h(which)e (represents)h(function)e(and)i(method)0 1027 y(information;)c(this)j (parallels)f(the)g(use)g(of)g(the)g FJ(def)h FN(statement)f(to)g (de\002ne)g(both)f(types)h(of)g(elements.)0 1174 y(Most)27 b(of)f(the)g(accessor)g(functions)f(are)i(declared)e(in)h FJ(SuiteInfoBase)f FN(and)h(do)g(not)g(need)f(to)i(be)f(o)o(v)o (erridden)d(by)j(subclasses.)0 1273 y(More)i(importantly)-5 b(,)27 b(the)h(e)o(xtraction)f(of)h(most)g(information)e(from)h(a)h (parse)g(tree)h(is)g(handled)d(through)g(a)j(method)e(called)h(by)g (the)0 1373 y FJ(SuiteInfoBase)d FN(constructor)-5 b(.)43 b(The)27 b(e)o(xample)e(code)i(for)f(most)h(of)f(the)h(classes)h(is)g (clear)f(when)f(read)g(alongside)g(the)h(formal)0 1473 y(grammar)m(,)18 b(b)n(ut)j(the)g(method)e(which)h(recursi)n(v)o(ely)f (creates)i(ne)n(w)f(information)e(objects)j(requires)e(further)g(e)o (xamination.)24 b(Here)d(is)h(the)0 1572 y(rele)n(v)n(ant)d(part)h(of)g (the)g FJ(SuiteInfoBase)e FN(de\002nition)h(from)h(`)p FO(e)n(xample)o(.p)n(y)p FN(':)236 1810 y FA(class)44 b(SuiteInfoBase:)416 1902 y(_docstring)f(=)h('')416 1993 y(_name)g(=)g('')416 2176 y(def)g(__init__\(self,)e(tree)j(=)f(None\):) 595 2267 y(self._class_info)e(=)j({})595 2358 y(self._function_info)d (=)i({})595 2450 y(if)g(tree:)774 2541 y(self._extract_info\(tree\))416 2724 y(def)g(_extract_info\(self,)e(tree\):)595 2815 y(#)j(extract)e(docstring)595 2906 y(if)h(len\(tree\))g(==)g(2:)774 2998 y(found,)g(vars)g(=)h(match\(DOCSTRING_STMT_PATTERN[1],)39 b(tree[1]\))595 3089 y(else:)774 3180 y(found,)44 b(vars)g(=)h (match\(DOCSTRING_STMT_PATTERN,)40 b(tree[3]\))595 3272 y(if)k(found:)774 3363 y(self._docstring)f(=)h (eval\(vars['docstring']\))595 3454 y(#)h(discover)e(inner)h (definitions)595 3546 y(for)g(node)g(in)h(tree[1:]:)774 3637 y(found,)f(vars)g(=)h(match\(COMPOUND_STMT_PATTERN,)40 b(node\))774 3728 y(if)45 b(found:)954 3820 y(cstmt)f(=)g (vars['compound'])954 3911 y(if)g(cstmt[0])g(==)g(symbol.funcdef:)1133 4002 y(name)g(=)h(cstmt[2][1])1133 4094 y(self._function_info[name])40 b(=)45 b(FunctionInfo\(cstmt\))954 4185 y(elif)f(cstmt[0])f(==)i (symbol.classdef:)1133 4276 y(name)f(=)h(cstmt[2][1])1133 4368 y(self._class_info[name])c(=)k(ClassInfo\(cstmt\))0 4654 y FN(After)23 b(initializing)g(some)g(internal)f(state,)j(the)e (constructor)e(calls)j(the)f FJ(_extract_info\(\))e FN(method.)33 b(This)23 b(method)f(performs)0 4754 y(the)e(b)n(ulk)f(of)h(the)g (information)d(e)o(xtraction)h(which)h(tak)o(es)i(place)e(in)h(the)g (entire)f(e)o(xample.)24 b(The)19 b(e)o(xtraction)g(has)h(tw)o(o)g (distinct)g(phases:)0 4853 y(the)25 b(location)f(of)g(the)h(docstring)e (for)i(the)f(parse)h(tree)g(passed)f(in,)i(and)e(the)h(disco)o(v)o(ery) e(of)h(additional)g(de\002nitions)g(within)g(the)h(code)0 4953 y(block)19 b(represented)g(by)g(the)i(parse)f(tree.)0 5100 y(The)25 b(initial)g FJ(if)g FN(test)h(determines)e(whether)g(the) h(nested)g(suite)h(is)f(of)g(the)g(\223short)g(form\224)f(or)h(the)g (\223long)f(form.)-6 b(\224)38 b(The)25 b(short)g(form)f(is)0 5199 y(used)c(when)g(the)g(code)f(block)g(is)j(on)d(the)i(same)f(line)g (as)h(the)f(de\002nition)f(of)h(the)h(code)e(block,)g(as)i(in)p 0 5549 3901 4 v 0 5649 a FI(30.1.)52 b FJ(parser)22 b FI(\227)h(Access)f(Python)i(parse)e(trees)2110 b(881)p eop end %%Page: 882 894 TeXDict begin 882 893 bop 236 174 a FA(def)45 b(square\(x\):)e("Square) g(an)i(argument.";)e(return)h(x)2343 187 y(**)2478 174 y(2)0 461 y FN(while)20 b(the)g(long)g(form)f(uses)i(an)f(indented)e (block)i(and)f(allo)n(ws)i(nested)f(de\002nitions:)236 699 y FA(def)45 b(make_power\(exp\):)416 790 y("Make)f(a)g(function)g (that)g(raises)g(an)g(argument)g(to)g(the)g(exponent)g(`exp'.")416 882 y(def)g(raiser\(x,)f(y=exp\):)595 973 y(return)h(x)998 986 y(**)1133 973 y(y)416 1064 y(return)f(raiser)0 1351 y FN(When)25 b(the)g(short)g(form)f(is)i(used,)f(the)g(code)g(block)f (may)g(contain)g(a)i(docstring)e(as)h(the)g(\002rst,)i(and)e(possibly)f (only)-5 b(,)25 b FJ(small_stmt)0 1450 y FN(element.)e(The)16 b(e)o(xtraction)f(of)h(such)h(a)g(docstring)e(is)i(slightly)f(dif)n (ferent)f(and)h(requires)g(only)f(a)i(portion)e(of)h(the)h(complete)e (pattern)h(used)0 1550 y(in)21 b(the)f(more)g(common)e(case.)26 b(As)21 b(implemented,)e(the)h(docstring)f(will)i(only)f(be)g(found)f (if)i(there)f(is)h(only)f(one)f FJ(small_stmt)h FN(node)0 1650 y(in)h(the)g FJ(simple_stmt)f FN(node.)27 b(Since)21 b(most)g(functions)f(and)g(methods)g(which)h(use)g(the)g(short)g(form)f (do)h(not)g(pro)o(vide)e(a)i(docstring,)0 1749 y(this)g(may)f(be)h (considered)d(suf)n(\002cient.)26 b(The)20 b(e)o(xtraction)f(of)h(the)g (docstring)f(proceeds)h(using)g(the)g FJ(match\(\))g FN(function)f(as)i(described)0 1849 y(abo)o(v)o(e,)d(and)i(the)g(v)n (alue)g(of)g(the)g(docstring)f(is)i(stored)e(as)i(an)f(attrib)n(ute)g (of)g(the)g FJ(SuiteInfoBase)f FN(object.)0 1996 y(After)k(docstring)g (e)o(xtraction,)f(a)i(simple)g(de\002nition)f(disco)o(v)o(ery)e (algorithm)h(operates)h(on)g(the)h FJ(stmt)g FN(nodes)e(of)i(the)g FJ(suite)f FN(node.)0 2095 y(The)g(special)h(case)h(of)e(the)h(short)g (form)e(is)j(not)f(tested;)i(since)e(there)f(are)h(no)f FJ(stmt)h FN(nodes)f(in)h(the)g(short)f(form,)h(the)g(algorithm)e(will) 0 2195 y(silently)e(skip)g(the)h(single)f FJ(simple_stmt)e FN(node)i(and)f(correctly)g(not)h(disco)o(v)o(er)e(an)o(y)i(nested)g (de\002nitions.)0 2342 y(Each)f(statement)h(in)g(the)g(code)f(block)g (is)h(cate)o(gorized)e(as)i(a)h(class)f(de\002nition,)f(function)f(or)h (method)g(de\002nition,)f(or)i(something)e(else.)0 2442 y(F)o(or)23 b(the)g(de\002nition)f(statements,)i(the)f(name)g(of)g(the) g(element)f(de\002ned)h(is)h(e)o(xtracted)e(and)g(a)i(representation)d (object)i(appropriate)d(to)0 2541 y(the)g(de\002nition)f(is)h(created)g (with)g(the)g(de\002ning)e(subtree)h(passed)h(as)h(an)f(ar)o(gument)d (to)j(the)g(constructor)-5 b(.)23 b(The)d(representation)e(objects)0 2641 y(are)i(stored)g(in)g(instance)g(v)n(ariables)f(and)h(may)g(be)g (retrie)n(v)o(ed)e(by)i(name)g(using)f(the)i(appropriate)c(accessor)j (methods.)0 2788 y(The)56 b(public)f(classes)i(pro)o(vide)c(an)o(y)i (accessors)h(required)e(which)i(are)g(more)f(speci\002c)h(than)f(those) h(pro)o(vided)d(by)j(the)0 2887 y FJ(SuiteInfoBase)27 b FN(class,)k(b)n(ut)e(the)g(real)g(e)o(xtraction)e(algorithm)g (remains)h(common)f(to)i(all)g(forms)f(of)h(code)f(blocks.)50 b(A)29 b(high-)0 2987 y(le)n(v)o(el)20 b(function)e(can)i(be)g(used)g (to)h(e)o(xtract)e(the)h(complete)f(set)i(of)f(information)e(from)h(a)i (source)e(\002le.)26 b(\(See)20 b(\002le)h(`)p FO(e)n(xample)o(.p)n(y)p FN('.\))236 3225 y FA(def)45 b(get_docs\(fileName\):)416 3317 y(import)e(os)416 3408 y(import)g(parser)416 3590 y(source)g(=)i(open\(fileName\).read\(\))416 3682 y(basename)e(=)i (os.path.basename\(os.path.splitext\(fil)o(eName\))o([0]\))416 3773 y(ast)f(=)h(parser.suite\(source\))416 3864 y(return)e (ModuleInfo\(ast.totuple\(\),)e(basename\))0 4151 y FN(This)30 b(pro)o(vides)e(an)i(easy-to-use)f(interf)o(ace)g(to)h(the)g (documentation)d(of)i(a)i(module.)52 b(If)30 b(information)e(is)j (required)d(which)h(is)i(not)0 4251 y(e)o(xtracted)20 b(by)i(the)g(code)f(of)g(this)i(e)o(xample,)d(the)i(code)f(may)h(be)f (e)o(xtended)f(at)j(clearly)e(de\002ned)g(points)g(to)h(pro)o(vide)e (additional)g(capa-)0 4350 y(bilities.)0 4678 y FE(30.2)121 b Fx(symbol)32 b FE(\227)h(Constants)i(used)f(with)g(Python)h(parse)f (trees)0 4910 y FN(This)24 b(module)e(pro)o(vides)g(constants)h(which)h (represent)e(the)i(numeric)e(v)n(alues)i(of)f(internal)g(nodes)g(of)g (the)h(parse)g(tree.)35 b(Unlik)o(e)24 b(most)0 5010 y(Python)18 b(constants,)h(these)g(use)h(lo)n(wer)n(-case)e(names.)24 b(Refer)c(to)f(the)g(\002le)h(`)p FO(Gr)o(ammar/Gr)o(ammar)p FN(')e(in)i(the)f(Python)f(distrib)n(ution)g(for)h(the)0 5110 y(de\002nitions)f(of)h(the)h(names)f(in)g(the)g(conte)o(xt)f(of)h (the)h(language)d(grammar)-5 b(.)23 b(The)c(speci\002c)h(numeric)e(v)n (alues)h(which)f(the)i(names)f(map)f(to)0 5209 y(may)i(change)f (between)g(Python)g(v)o(ersions.)0 5356 y(This)h(module)f(also)i(pro)o (vides)d(one)i(additional)f(data)h(object:)p 0 5549 3901 4 v 0 5649 a FI(882)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 883 895 TeXDict begin 883 894 bop 0 83 a FD(sym_name)208 183 y FN(Dictionary)21 b(mapping)g(the)i(numeric)e(v)n(alues)h(of)h(the)g (constants)f(de\002ned)g(in)h(this)g(module)e(back)h(to)h(name)f (strings,)i(allo)n(wing)208 282 y(more)19 b(human-readable)d (representation)j(of)g(parse)h(trees)h(to)f(be)g(generated.)0 429 y FL(See)h(Also:)0 576 y FN(Module)e FJ(parser)h FN(\(section)f(30.1\):)208 676 y(The)g(second)h(e)o(xample)f(for)g(the) h FJ(parser)g FN(module)f(sho)n(ws)h(ho)n(w)g(to)g(use)g(the)h FJ(symbol)e FN(module.)0 1003 y FE(30.3)121 b Fx(token)32 b FE(\227)h(Constants)i(used)g(with)f(Python)g(parse)g(trees)0 1236 y FN(This)23 b(module)e(pro)o(vides)g(constants)h(which)g (represent)f(the)i(numeric)e(v)n(alues)h(of)g(leaf)h(nodes)f(of)g(the)g (parse)h(tree)f(\(terminal)g(tok)o(ens\).)0 1336 y(Refer)h(to)g(the)g (\002le)g(`)p FO(Gr)o(ammar/Gr)o(ammar)p FN(')f(in)h(the)g(Python)e (distrib)n(ution)h(for)g(the)h(de\002nitions)f(of)g(the)h(names)g(in)g (the)f(conte)o(xt)g(of)h(the)0 1435 y(language)18 b(grammar)-5 b(.)24 b(The)c(speci\002c)g(numeric)f(v)n(alues)h(which)g(the)g(names)g (map)f(to)i(may)e(change)g(between)h(Python)f(v)o(ersions.)0 1582 y(This)e(module)e(also)j(pro)o(vides)d(one)h(data)h(object)f(and)g (some)h(functions.)22 b(The)17 b(functions)e(mirror)h(de\002nitions)g (in)g(the)h(Python)f(C)i(header)0 1682 y(\002les.)0 1829 y FD(tok_name)208 1928 y FN(Dictionary)j(mapping)g(the)i(numeric)e(v)n (alues)h(of)h(the)g(constants)f(de\002ned)g(in)h(this)g(module)e(back)h (to)h(name)f(strings,)i(allo)n(wing)208 2028 y(more)19 b(human-readable)d(representation)j(of)g(parse)h(trees)h(to)f(be)g (generated.)0 2175 y FD(ISTERMINAL)p FJ(\()p FK(x)p FJ(\))208 2274 y FN(Return)f(true)h(for)g(terminal)f(tok)o(en)h(v)n(alues.)0 2421 y FD(ISNONTERMINAL)p FJ(\()p FK(x)p FJ(\))208 2521 y FN(Return)f(true)h(for)g(non-terminal)d(tok)o(en)j(v)n(alues.)0 2668 y FD(ISEOF)p FJ(\()p FK(x)p FJ(\))208 2767 y FN(Return)f(true)h (if)h FK(x)f FN(is)i(the)e(mark)o(er)f(indicating)g(the)h(end)g(of)f (input.)0 2914 y FL(See)i(Also:)0 3061 y FN(Module)e FJ(parser)h FN(\(section)f(30.1\):)208 3161 y(The)g(second)h(e)o (xample)f(for)g(the)h FJ(parser)g FN(module)f(sho)n(ws)h(ho)n(w)g(to)g (use)g(the)h FJ(symbol)e FN(module.)0 3488 y FE(30.4)121 b Fx(keyword)32 b FE(\227)g(T)-14 b(esting)34 b(f)l(or)g(Python)h(k)n (e)n(yw)o(ords)0 3721 y FN(This)20 b(module)f(allo)n(ws)i(a)f(Python)f (program)f(to)j(determine)d(if)j(a)g(string)e(is)j(a)e(k)o(e)o(yw)o (ord.)0 3868 y FD(iskeyword)p FJ(\()p FK(s)p FJ(\))208 3967 y FN(Return)f(true)h(if)h FK(s)g FN(is)g(a)f(Python)f(k)o(e)o(yw)o (ord.)0 4114 y FD(kwlist)208 4214 y FN(Sequence)h(containing)g(all)j (the)e(k)o(e)o(yw)o(ords)g(de\002ned)g(for)g(the)h(interpreter)-5 b(.)28 b(If)22 b(an)o(y)f(k)o(e)o(yw)o(ords)g(are)g(de\002ned)g(to)h (only)f(be)h(acti)n(v)o(e)208 4313 y(when)d(particular)g FJ(__future__)g FN(statements)h(are)g(in)h(ef)n(fect,)e(these)h(will)h (be)f(included)f(as)i(well.)0 4641 y FE(30.5)121 b Fx(tokenize)31 b FE(\227)i(T)-14 b(ok)n(eniz)n(er)34 b(f)l(or)g(Python)g(source)0 4874 y FN(The)28 b FJ(tokenize)g FN(module)g(pro)o(vides)f(a)i(le)o (xical)g(scanner)f(for)g(Python)f(source)h(code,)i(implemented)d(in)i (Python.)50 b(The)28 b(scanner)0 4973 y(in)h(this)g(module)e(returns)h (comments)g(as)h(tok)o(ens)f(as)i(well,)h(making)c(it)j(useful)e(for)g (implementing)e(\223pretty-printers,)-6 b(\224)28 b(including)0 5073 y(colorizers)19 b(for)h(on-screen)e(displays.)0 5220 y(The)i(primary)e(entry)i(point)f(is)i(a)g(generator:)0 5367 y FD(generate_tokens)p FJ(\()p FK(r)m(eadline)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(30.3.)52 b FJ(token)22 b FI(\227)i(Constants)e(used)h(with)h(Python)g(parse)e(trees)1680 b(883)p eop end %%Page: 884 896 TeXDict begin 884 895 bop 208 83 a FN(The)21 b FJ(generate_tokens\(\))d FN(generator)i(requires)g(one)h(ar)o(gment,)f FK(r)m(eadline)p FN(,)g(which)h(must)h(be)f(a)h(callable)f(object)g(which)208 183 y(pro)o(vides)f(the)j(same)g(interf)o(ace)f(as)h(the)f FJ(readline\(\))g FN(method)f(of)h(b)n(uilt-in)g(\002le)i(objects)e (\(see)h(section)f(3.9\).)31 b(Each)22 b(call)h(to)208 282 y(the)d(function)e(should)h(return)g(one)h(line)g(of)g(input)g(as)h (a)f(string.)208 415 y(The)g(generator)f(produces)g(5-tuples)h(with)g (these)h(members:)26 b(the)20 b(tok)o(en)g(type;)h(the)g(tok)o(en)f (string;)h(a)g(2-tuple)e FJ(\()p FK(sr)l(ow)p FJ(,)50 b FK(scol)p FJ(\))208 515 y FN(of)26 b(ints)h(specifying)e(the)h(ro)n (w)g(and)g(column)f(where)h(the)g(tok)o(en)g(be)o(gins)g(in)g(the)h (source;)i(a)e(2-tuple)e FJ(\()p FK(er)l(ow)p FJ(,)50 b FK(ecol)p FJ(\))26 b FN(of)g(ints)208 614 y(specifying)20 b(the)h(ro)n(w)g(and)g(column)g(where)g(the)g(tok)o(en)g(ends)g(in)h (the)g(source;)f(and)g(the)h(line)g(on)f(which)g(the)g(tok)o(en)g(w)o (as)i(found.)208 714 y(The)c(line)i(passed)f(is)h(the)f FK(lo)o(gical)g FN(line;)g(continuation)e(lines)i(are)h(included.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)d(2.2.)0 861 y(An)i(older)g(entry)f (point)g(is)j(retained)d(for)g(backw)o(ard)g(compatibility:)0 1008 y FD(tokenize)p FJ(\()p FK(r)m(eadline)p FC([)p FK(,)e(tok)o(eneater)d FC(])p FJ(\))208 1107 y FN(The)23 b FJ(tokenize\(\))f FN(function)g(accepts)i(tw)o(o)g(parameters:)31 b(one)23 b(representing)f(the)h(input)g(stream,)h(and)g(one)f(pro)o (viding)e(an)208 1207 y(output)e(mechanism)f(for)i FJ(tokenize\(\))p FN(.)208 1340 y(The)g(\002rst)h(parameter)m(,)d FK(r)m(eadline)p FN(,)h(must)i(be)f(a)h(callable)f(object)g(which)f(pro)o(vides)g(the)h (same)h(interf)o(ace)e(as)j(the)e FJ(readline\(\))208 1439 y FN(method)26 b(of)i(b)n(uilt-in)g(\002le)h(objects)f(\(see)g (section)g(3.9\).)48 b(Each)28 b(call)g(to)h(the)f(function)e(should)i (return)f(one)g(line)h(of)g(input)g(as)208 1539 y(a)c(string.)36 b(Alternately)-5 b(,)24 b FK(r)m(eadline)f FN(may)g(be)h(a)h(callable)e (object)h(that)g(signals)g(completion)e(by)i(raising)g FJ(StopIteration)p FN(.)208 1639 y(Changed)18 b(in)j(v)o(ersion)e(2.5:) g(Added)g FJ(StopIteration)g FN(support.)208 1772 y(The)27 b(second)g(parameter)m(,)g FK(tok)o(eneater)r FN(,)i(must)f(also)g(be)f (a)i(callable)e(object.)47 b(It)28 b(is)h(called)f(once)f(for)g(each)g (tok)o(en,)i(with)f(\002)n(v)o(e)208 1871 y(ar)o(guments,)17 b(corresponding)g(to)k(the)f(tuples)g(generated)e(by)i FJ(generate_tokens\(\))p FN(.)0 2018 y(All)e(constants)g(from)f(the)g FJ(token)h FN(module)e(are)i(also)g(e)o(xported)e(from)h FJ(tokenize)p FN(,)g(as)h(are)g(tw)o(o)g(additional)f(tok)o(en)g(type)g (v)n(alues)g(that)0 2118 y(might)j(be)g(passed)g(to)g(the)g FK(tok)o(eneater)i FN(function)c(by)i FJ(tokenize\(\))p FN(:)0 2265 y FD(COMMENT)208 2364 y FN(T)-7 b(ok)o(en)19 b(v)n(alue)g(used)h(to)h(indicate)e(a)i(comment.)0 2511 y FD(NL)208 2611 y FN(T)-7 b(ok)o(en)25 b(v)n(alue)g(used)g(to)h (indicate)f(a)i(non-terminating)22 b(ne)n(wline.)41 b(The)25 b(NEWLINE)h(tok)o(en)f(indicates)g(the)h(end)f(of)h(a)g(logical)208 2710 y(line)e(of)h(Python)f(code;)i(NL)f(tok)o(ens)f(are)h(generated)e (when)h(a)i(logical)e(line)h(of)f(code)h(is)g(continued)e(o)o(v)o(er)h (multiple)g(physical)208 2810 y(lines.)0 2957 y(Another)17 b(function)f(is)j(pro)o(vided)d(to)i(re)n(v)o(erse)f(the)h(tok)o (enization)e(process.)24 b(This)18 b(is)h(useful)f(for)f(creating)g (tools)h(that)g(tok)o(enize)f(a)i(script,)0 3056 y(modify)g(the)h(tok)o (en)f(stream,)h(and)g(write)g(back)g(the)g(modi\002ed)f(script.)0 3203 y FD(untokenize)p FJ(\()p FK(iter)o(able)p FJ(\))208 3303 y FN(Con)m(v)o(erts)i(tok)o(ens)h(back)h(into)f(Python)g(source)g (code.)32 b(The)22 b FK(iter)o(able)h FN(must)g(return)e(sequences)h (with)h(at)g(least)h(tw)o(o)f(elements,)208 3403 y(the)d(tok)o(en)f (type)h(and)g(the)g(tok)o(en)f(string.)25 b(An)o(y)19 b(additional)g(sequence)g(elements)h(are)g(ignored.)208 3535 y(The)25 b(reconstructed)e(script)i(is)h(returned)e(as)i(a)g (single)f(string.)40 b(The)25 b(result)g(is)i(guaranteed)c(to)i(tok)o (enize)g(back)f(to)i(match)f(the)208 3635 y(input)18 b(so)i(that)g(the)f(con)m(v)o(ersion)e(is)j(lossless)h(and)e (round-trips)e(are)i(assured.)25 b(The)19 b(guarantee)e(applies)j(only) e(to)i(the)f(tok)o(en)g(type)208 3735 y(and)g(tok)o(en)h(string)f(as)i (the)g(spacing)e(between)g(tok)o(ens)h(\(column)f(positions\))g(may)h (change.)49 b(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 3881 y(Example)g(of)h(a)g(script)h(re-writer)e(that)h(transforms)f(\003oat)h (literals)h(into)f(Decimal)g(objects:)p 0 5549 3901 4 v 0 5649 a FI(884)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 885 897 TeXDict begin 885 896 bop 236 174 a FA(def)45 b(decistmt\(s\):)416 266 y("""Substitute)d(Decimals)i(for)g(floats)g(in)g(a)h(string)f(of)g (statements.)416 448 y(>>>)g(from)g(decimal)g(import)g(Decimal)416 540 y(>>>)g(s)h(=)f('print)g(+21.3e-5)1448 553 y(*)1493 540 y(-.1234/81.7')416 631 y(>>>)g(decistmt\(s\))416 722 y("print)f(+Decimal)h(\('21.3e-5'\))1628 735 y(*)1673 722 y(-Decimal)d(\('.1234'\)/Decimal)h(\('81.7'\)")416 905 y(>>>)i(exec\(s\))416 996 y(-3.21716034272e-007)416 1088 y(>>>)g(exec\(decistmt\(s\)\))416 1179 y (-3.217160342717258261933904529E-7)416 1362 y(""")416 1453 y(result)f(=)i([])416 1544 y(g)f(=)h (generate_tokens\(StringIO\(s\).readline\))128 b(#)45 b(tokenize)e(the)i(string)416 1636 y(for)f(toknum,)g(tokval,)f(_,)i(_,) f(_)90 b(in)44 b(g:)595 1727 y(if)g(toknum)g(==)h(NUMBER)f(and)g('.')g (in)h(tokval:)88 b(#)45 b(replace)e(NUMBER)h(tokens)774 1818 y(result.extend\([)954 1910 y(\(NAME,)f('Decimal'\),)954 2001 y(\(OP,)h('\('\),)954 2092 y(\(STRING,)f(repr\(tokval\)\),)954 2183 y(\(OP,)h('\)'\))774 2275 y(]\))595 2366 y(else:)774 2457 y(result.append\(\(toknum,)d(tokval\)\))416 2549 y(return)i(untokenize\(result\))0 3059 y FE(30.6)121 b Fx(tabnanny)31 b FE(\227)i(Detection)i(of)f(ambiguous)h(indentation)0 3292 y FN(F)o(or)20 b(the)h(time)g(being)f(this)h(module)f(is)i (intended)d(to)i(be)g(called)f(as)i(a)f(script.)27 b(Ho)n(we)n(v)o(er) 19 b(it)j(is)f(possible)g(to)g(import)f(it)h(into)g(an)f(IDE)h(and)0 3391 y(use)f(the)h(function)d FJ(check\(\))i FN(described)e(belo)n(w)-5 b(.)0 3538 y FL(W)g(ar)o(ning:)24 b FN(The)19 b(API)h(pro)o(vided)d(by) j(this)g(module)e(is)j(lik)o(ely)f(to)g(change)e(in)i(future)e (releases;)j(such)e(changes)g(may)g(not)g(be)h(backw)o(ard)0 3638 y(compatible.)0 3785 y FD(check)p FJ(\()p FK(\002le)p 407 3785 25 4 v 28 w(or)p 509 3785 V 30 w(dir)r FJ(\))208 3884 y FN(If)j FK(\002le)p 394 3884 V 29 w(or)p 497 3884 V 30 w(dir)i FN(is)f(a)g(directory)e(and)g(not)h(a)h(symbolic)e(link,)i (then)e(recursi)n(v)o(ely)g(descend)g(the)h(directory)f(tree)h(named)f (by)h FK(\002le)p 3848 3884 V 29 w(-)208 3984 y(or)p 287 3984 V 29 w(dir)r FN(,)k(checking)c(all)j(`)p FO(.p)n(y)p FN(')e(\002les)i(along)e(the)h(w)o(ay)-5 b(.)39 b(If)25 b FK(\002le)p 1952 3984 V 30 w(or)p 2056 3984 V 29 w(dir)j FN(is)e(an)f(ordinary)e(Python)h(source)g(\002le,)j(it)e(is)h(check)o (ed)e(for)208 4084 y(whitespace)19 b(related)h(problems.)j(The)d (diagnostic)f(messages)i(are)f(written)g(to)g(standard)f(output)g (using)h(the)g(print)f(statement.)0 4230 y FD(verbose)208 4330 y FN(Flag)h(indicating)f(whether)g(to)h(print)g(v)o(erbose)f (messages.)25 b(This)20 b(is)h(incremented)d(by)i(the)g FJ(-v)h FN(option)e(if)h(called)g(as)h(a)g(script.)0 4477 y FD(filename_only)208 4577 y FN(Flag)h(indicating)f(whether)h(to) h(print)e(only)h(the)h(\002lenames)f(of)g(\002les)i(containing)c (whitespace)i(related)g(problems.)31 b(This)22 b(is)i(set)208 4676 y(to)c(true)g(by)g(the)g FJ(-q)g FN(option)f(if)i(called)f(as)g(a) h(script.)0 4823 y FL(exception)e FD(NannyNag)208 4923 y FN(Raised)h(by)g FJ(tokeneater\(\))f FN(if)h(detecting)f(an)h (ambiguous)e(indent.)24 b(Captured)c(and)f(handled)g(in)h FJ(check\(\))p FN(.)0 5070 y FD(tokeneater)p FJ(\()p FK(type)o(,)e(tok)o(en,)h(start,)i(end,)f(line)p FJ(\))208 5169 y FN(This)g(function)e(is)k(used)d(by)h FJ(check\(\))g FN(as)h(a)f(callback)g(parameter)e(to)j(the)f(function)e FJ(tokenize.tokenize\(\))p FN(.)0 5316 y FL(See)j(Also:)p 0 5549 3901 4 v 0 5649 a FI(30.6.)52 b FJ(tabnanny)22 b FI(\227)h(Detection)h(of)f(ambiguous)h(indentation)1699 b(885)p eop end %%Page: 886 898 TeXDict begin 886 897 bop 0 83 a FN(Module)19 b FJ(tokenize)g FN(\(section)h(30.5\):)208 183 y(Le)o(xical)f(scanner)g(for)h(Python)f (source)g(code.)0 510 y FE(30.7)121 b Fx(pyclbr)32 b FE(\227)h(Python)h(class)f(bro)n(wser)h(suppor)5 b(t)0 743 y FN(The)23 b FJ(pyclbr)g FN(can)h(be)f(used)h(to)f(determine)g (some)g(limited)h(information)d(about)h(the)i(classes,)h(methods)e(and) g(top-le)n(v)o(el)f(functions)0 843 y(de\002ned)f(in)i(a)g(module.)30 b(The)22 b(information)e(pro)o(vided)g(is)j(suf)n(\002cient)f(to)h (implement)e(a)i(traditional)e(three-pane)g(class)i(bro)n(wser)-5 b(.)31 b(The)0 942 y(information)d(is)j(e)o(xtracted)e(from)g(the)h (source)g(code)f(rather)h(than)g(by)f(importing)g(the)h(module,)h(so)g (this)f(module)f(is)i(safe)g(to)f(use)0 1042 y(with)21 b(untrusted)e(source)i(code.)26 b(This)21 b(restriction)f(mak)o(es)g (it)i(impossible)e(to)h(use)g(this)h(module)d(with)i(modules)f(not)g (implemented)f(in)0 1141 y(Python,)g(including)f(man)o(y)h(standard)g (and)h(optional)f(e)o(xtension)f(modules.)0 1288 y FD(readmodule)p FJ(\()p FK(module)p FC([)p FK(,)f(path)12 b FC(])p FJ(\))208 1388 y FN(Read)21 b(a)h(module)e(and)h(return)g(a)h(dictionary)d (mapping)h(class)i(names)g(to)f(class)i(descriptor)d(objects.)28 b(The)22 b(parameter)e FK(module)208 1488 y FN(should)14 b(be)i(the)g(name)f(of)g(a)h(module)f(as)h(a)g(string;)h(it)g(may)e(be) g(the)h(name)f(of)h(a)g(module)e(within)i(a)g(package.)22 b(The)15 b FK(path)g FN(parameter)208 1587 y(should)21 b(be)i(a)g(sequence,)g(and)f(is)i(used)e(to)h(augment)f(the)g(v)n(alue) h(of)f FJ(sys.path)p FN(,)g(which)h(is)h(used)e(to)h(locate)g(module)e (source)208 1687 y(code.)0 1834 y FD(readmodule_ex)p FJ(\()p FK(module)p FC([)p FK(,)16 b(path)c FC(])p FJ(\))208 1933 y FN(Lik)o(e)32 b FJ(readmodule\(\))p FN(,)h(b)n(ut)f(the)g (returned)f(dictionary)-5 b(,)33 b(in)f(addition)f(to)h(mapping)e (class)k(names)d(to)i(class)g(descriptor)208 2033 y(objects,)21 b(also)i(maps)e(top-le)n(v)o(el)g(function)f(names)i(to)g(function)e (descriptor)g(objects.)30 b(Moreo)o(v)o(er)m(,)19 b(if)k(the)f(module)e (being)h(read)208 2133 y(is)f(a)g(package,)e(the)i(k)o(e)o(y)f FJ('__path__')f FN(in)i(the)f(returned)f(dictionary)g(has)i(as)g(its)h (v)n(alue)e(a)h(list)g(which)g(contains)e(the)i(package)208 2232 y(search)f(path.)0 2517 y Fv(30.7.1)101 b(Class)27 b(Descr)q(iptor)i(Objects)0 2720 y FN(The)19 b(class)i(descriptor)d (objects)i(used)f(as)i(v)n(alues)e(in)h(the)g(dictionary)d(returned)h (by)i FJ(readmodule\(\))e FN(and)h FJ(readmodule_ex\(\))0 2820 y FN(pro)o(vide)f(the)i(follo)n(wing)f(data)h(members:)0 2966 y FD(module)208 3066 y FN(The)f(name)h(of)g(the)g(module)f (de\002ning)g(the)h(class)h(described)e(by)h(the)g(class)h(descriptor) -5 b(.)0 3213 y FD(name)208 3313 y FN(The)19 b(name)h(of)g(the)g (class.)0 3459 y FD(super)208 3559 y FN(A)e(list)h(of)e(class)i (descriptors)e(which)g(describe)g(the)h(immediate)f(base)h(classes)h (of)e(the)h(class)h(being)e(described.)23 b(Classes)c(which)208 3659 y(are)26 b(named)e(as)j(superclasses)f(b)n(ut)g(which)g(are)g(not) f(disco)o(v)o(erable)f(by)i FJ(readmodule\(\))e FN(are)i(listed)g(as)h (a)g(string)e(with)i(the)208 3758 y(class)21 b(name)e(instead)h(of)g (class)h(descriptors.)0 3905 y FD(methods)208 4005 y FN(A)f(dictionary)f(mapping)f(method)h(names)h(to)g(line)g(numbers.)0 4152 y FD(file)208 4251 y FN(Name)g(of)f(the)i(\002le)g(containing)d (the)i FJ(class)g FN(statement)g(de\002ning)f(the)h(class.)0 4398 y FD(lineno)208 4498 y FN(The)f(line)i(number)d(of)i(the)g FJ(class)g FN(statement)g(within)g(the)g(\002le)h(named)e(by)h FJ(file)p FN(.)0 4783 y Fv(30.7.2)101 b(Function)28 b(Descr)q(iptor)h (Objects)0 4986 y FN(The)18 b(function)f(descriptor)h(objects)g(used)h (as)g(v)n(alues)g(in)g(the)f(dictionary)f(returned)g(by)i FJ(readmodule_ex\(\))d FN(pro)o(vide)h(the)i(follo)n(w-)0 5085 y(ing)h(data)g(members:)0 5232 y FD(module)208 5332 y FN(The)f(name)h(of)g(the)g(module)f(de\002ning)g(the)h(function)e (described)h(by)h(the)g(function)f(descriptor)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(886)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 887 899 TeXDict begin 887 898 bop 0 83 a FD(name)208 183 y FN(The)19 b(name)h(of)g(the)g(function.)0 330 y FD(file)208 429 y FN(Name)g(of)f(the)i(\002le)g(containing)d(the)i FJ(def)g FN(statement)g(de\002ning)f(the)h(function.)0 576 y FD(lineno)208 676 y FN(The)f(line)i(number)d(of)i(the)g FJ(def)g FN(statement)g (within)g(the)h(\002le)f(named)f(by)h FJ(file)p FN(.)0 1003 y FE(30.8)121 b Fx(py_compile)31 b FE(\227)i(Compile)g(Python)i (source)f(\002les)0 1236 y FN(The)24 b FJ(py_compile)f FN(module)g(pro)o(vides)f(a)j(function)d(to)i(generate)f(a)i(byte-code) d(\002le)j(from)e(a)i(source)e(\002le,)j(and)e(another)e(function)0 1336 y(used)e(when)g(the)g(module)f(source)g(\002le)i(is)g(in)m(v)n(ok) o(ed)d(as)j(a)g(script.)0 1482 y(Though)c(not)i(often)f(needed,)f(this) j(function)d(can)i(be)g(useful)f(when)h(installing)f(modules)g(for)h (shared)f(use,)h(especially)g(if)g(some)g(of)g(the)0 1582 y(users)h(may)g(not)g(ha)n(v)o(e)g(permission)f(to)h(write)g(the)h (byte-code)d(cache)h(\002les)j(in)e(the)g(directory)f(containing)f(the) i(source)f(code.)0 1729 y FL(exception)g FD(PyCompileError)208 1829 y FN(Exception)f(raised)i(when)g(an)g(error)f(occurs)g(while)h (attempting)f(to)i(compile)e(the)h(\002le.)0 1975 y FD(compile)p FJ(\()p FK(\002le)p FC([)p FK(,)e(c\002le)p FC([)p FK(,)i(d\002le)p FC([)p FK(,)f(dor)o(aise)12 b FC(])g(])g(])p FJ(\))208 2075 y FN(Compile)23 b(a)h(source)f(\002le)h(to)g(byte-code)d(and)i (write)h(out)f(the)h(byte-code)e(cache)h(\002le.)36 b(The)23 b(source)g(code)g(is)h(loaded)f(from)g(the)208 2175 y(\002le)f(name)f FK(\002le)p FN(.)30 b(The)22 b(byte-code)e(is)j(written)e(to)h FK(c\002le)p FN(,)g(which)g(def)o(aults)f(to)h FK(\002le)g FJ(+)g('c')g FN(\()p FJ('o')g FN(if)g(optimization)e(is)j(enabled)d(in) 208 2274 y(the)k(current)g(interpreter\).)36 b(If)25 b FK(d\002le)f FN(is)h(speci\002ed,)h(it)f(is)h(used)e(as)h(the)g(name) f(of)h(the)f(source)g(\002le)i(in)e(error)g(messages)h(instead)208 2374 y(of)c FK(\002le)p FN(.)31 b(If)22 b FK(dor)o(aise)f FN(is)i(true,)f(a)h FJ(PyCompileError)d FN(is)j(raised)f(when)f(an)h (error)f(is)i(encountered)d(while)i(compiling)e FK(\002le)p FN(.)31 b(If)208 2474 y FK(dor)o(aise)19 b FN(is)i(f)o(alse)g(\(the)f (def)o(ault\),)f(an)h(error)f(string)h(is)h(written)f(to)g FJ(sys.stderr)p FN(,)f(b)n(ut)h(no)g(e)o(xception)e(is)j(raised.)0 2620 y FD(main)p FJ(\()p FC([)p FK(ar)m(gs)12 b FC(])p FJ(\))208 2720 y FN(Compile)27 b(se)n(v)o(eral)h(source)f(\002les.)49 b(The)28 b(\002les)h(named)e(in)h FK(ar)m(gs)g FN(\(or)g(on)f(the)h (command)e(line,)k(if)e FK(ar)m(gs)h FN(is)g(not)e(speci\002ed\))h(are) 208 2820 y(compiled)20 b(and)h(the)h(resulting)f(bytecode)f(is)j (cached)e(in)h(the)f(normal)g(manner)-5 b(.)29 b(This)22 b(function)e(does)h(not)h(search)f(a)h(directory)208 2919 y(structure)d(to)h(locate)g(source)g(\002les;)h(it)g(only)e (compiles)h(\002les)h(named)e(e)o(xplicitly)-5 b(.)0 3066 y(When)20 b(this)h(module)e(is)i(run)e(as)i(a)g(script,)f(the)g FJ(main\(\))f FN(is)j(used)e(to)g(compile)f(all)i(the)f(\002les)h (named)e(on)h(the)g(command)f(line.)0 3213 y FL(See)i(Also:)0 3360 y FN(Module)e FJ(compileall)g FN(\(section)h(30.9\):)208 3459 y(Utilities)h(to)f(compile)f(all)i(Python)e(source)h(\002les)h(in) f(a)h(directory)d(tree.)0 3787 y FE(30.9)121 b Fx(compileall)31 b FE(\227)i(Byte-compile)g(Python)h(libr)o(ar)r(ies)0 4020 y FN(This)25 b(module)f(pro)o(vides)g(some)h(utility)g(functions)e (to)j(support)e(installing)g(Python)g(libraries.)40 b(These)25 b(functions)e(compile)i(Python)0 4119 y(source)20 b(\002les)i(in)g(a)f (directory)f(tree,)h(allo)n(wing)f(users)h(without)f(permission)h(to)g (write)g(to)g(the)g(libraries)g(to)g(tak)o(e)h(adv)n(antage)d(of)i (cached)0 4219 y(byte-code)d(\002les.)0 4366 y(The)25 b(source)g(\002le)h(for)f(this)h(module)e(may)h(also)h(be)f(used)h(as)g (a)g(script)f(to)h(compile)f(Python)f(sources)h(in)h(directories)e (named)g(on)i(the)0 4465 y(command)18 b(line)i(or)g(in)h FJ(sys.path)p FN(.)0 4612 y FD(compile_dir)p FJ(\()p FK(dir)r FC([)p FK(,)d(maxle)o(vels)p FC([)p FK(,)h(ddir)r FC([)p FK(,)h(for)m(ce)p FC([)p FK(,)g(rx)p FC([)p FK(,)h(quiet)13 b FC(])f(])g(])g(])g(])p FJ(\))208 4712 y FN(Recursi)n(v)o(ely)26 b(descend)h(the)h(directory)e(tree)i(named)f(by)g FK(dir)r FN(,)j(compiling)c(all)j(`)p FO(.p)n(y)p FN(')e(\002les)i(along)e(the)h (w)o(ay)-5 b(.)47 b(The)28 b FK(maxle)o(vels)208 4812 y FN(parameter)17 b(is)k(used)e(to)g(limit)h(the)f(depth)f(of)h(the)h (recursion;)e(it)i(def)o(aults)f(to)g FJ(10)p FN(.)25 b(If)19 b FK(ddir)i FN(is)f(gi)n(v)o(en,)e(it)i(is)g(used)f(as)h(the)g (base)f(path)208 4911 y(from)24 b(which)g(the)i(\002lenames)f(used)f (in)i(error)e(messages)h(will)h(be)f(generated.)38 b(If)25 b FK(for)m(ce)h FN(is)g(true,)g(modules)e(are)h(re-compiled)208 5011 y(e)n(v)o(en)19 b(if)h(the)g(timestamps)g(are)h(up)e(to)i(date.) 208 5144 y(If)31 b FK(rx)h FN(is)g(gi)n(v)o(en,)h(it)f(speci\002es)f(a) h(re)o(gular)e(e)o(xpression)f(of)i(\002le)h(names)f(to)h(e)o(xclude)e (from)g(the)h(search;)37 b(that)31 b(e)o(xpression)f(is)208 5243 y(searched)19 b(for)g(in)i(the)f(full)g(path.)208 5376 y(If)g FK(quiet)h FN(is)g(true,)f(nothing)e(is)j(printed)e(to)i (the)f(standard)f(output)g(in)h(normal)f(operation.)p 0 5549 3901 4 v 0 5649 a FI(30.8.)52 b FJ(py_compile)21 b FI(\227)j(Compile)g(Python)g(source)e(\002les)1869 b(887)p eop end %%Page: 888 900 TeXDict begin 888 899 bop 0 83 a FD(compile_path)p FJ(\()p FC([)p FK(skip)p 829 83 25 4 v 27 w(cur)m(dir)r FC([)p FK(,)20 b(maxle)o(vels)p FC([)p FK(,)f(for)m(ce)12 b FC(])g(])g(])p FJ(\))208 183 y FN(Byte-compile)17 b(all)i(the)g(`)p FO(.p)n(y)p FN(')f(\002les)h(found)e(along)h FJ(sys.path)p FN(.)23 b(If)c FK(skip)p 2306 183 V 30 w(cur)m(dir)h FN(is)g(true)e(\(the)h(def)o(ault\),)e(the)i(current)e(directory)208 282 y(is)g(not)g(included)e(in)i(the)g(search.)24 b(The)16 b FK(maxle)o(vels)h FN(and)f FK(for)m(ce)h FN(parameters)f(def)o(ault)g (to)h FJ(0)g FN(and)f(are)h(passed)g(to)g(the)g FJ(compile_-)208 382 y(dir\(\))i FN(function.)0 529 y(T)-7 b(o)20 b(force)g(a)g (recompile)f(of)h(all)h(the)f(`)p FO(.p)n(y)p FN(')f(\002les)j(in)e (the)g(`)p FO(Lib/)p FN(')f(subdirectory)e(and)j(all)h(its)g (subdirectories:)236 676 y FA(import)44 b(compileall)236 858 y(compileall.compile_dir\('Lib/',)c(force=True\))236 1041 y(#)45 b(Perform)f(same)g(compilation,)f(excluding)g(files)h(in)g (.svn)g(directories.)236 1132 y(import)g(re)236 1224 y(compileall.compile_dir\('Lib/',)c(rx=re.compile\('/[.]svn'\),)h (force=True\))0 1511 y FL(See)21 b(Also:)0 1658 y FN(Module)e FJ(py_compile)g FN(\(section)h(30.8\):)208 1757 y(Byte-compile)e(a)j (single)f(source)f(\002le.)0 2085 y FE(30.10)122 b Fx(dis)32 b FE(\227)h(Disassemb)n(ler)g(f)l(or)h(Python)g(b)n(yte)g(code)0 2317 y FN(The)22 b FJ(dis)h FN(module)e(supports)g(the)i(analysis)f(of) g(Python)g(byte)g(code)f(by)h(disassembling)g(it.)32 b(Since)23 b(there)f(is)h(no)f(Python)g(assembler)m(,)0 2417 y(this)29 b(module)f(de\002nes)g(the)h(Python)f(assembly)g (language.)49 b(The)28 b(Python)g(byte)g(code)g(which)h(this)g(module)e (tak)o(es)i(as)h(an)f(input)f(is)0 2517 y(de\002ned)19 b(in)i(the)f(\002le)h(`)p FO(Include/opcode)o(.h)p FN(')15 b(and)k(used)h(by)g(the)g(compiler)f(and)h(the)g(interpreter)-5 b(.)0 2664 y(Example:)24 b(Gi)n(v)o(en)19 b(the)i(function)d FJ(myfunc)p FN(:)236 2902 y FA(def)45 b(myfunc\(alist\):)416 2993 y(return)e(len\(alist\))0 3280 y FN(the)20 b(follo)n(wing)f (command)f(can)i(be)g(used)g(to)g(get)h(the)f(disassembly)f(of)h FJ(myfunc\(\))p FN(:)236 3518 y FA(>>>)45 b(dis.dis\(myfunc\))326 3609 y(2)493 b(0)45 b(LOAD_GLOBAL)625 b(0)45 b(\(len\))864 3700 y(3)g(LOAD_FAST)715 b(0)45 b(\(alist\))864 3792 y(6)g(CALL_FUNCTION)535 b(1)864 3883 y(9)45 b(RETURN_VALUE)0 4170 y FN(\(The)20 b(\2232\224)f(is)j(a)e(line)h(number\).)0 4316 y(The)f FJ(dis)g FN(module)f(de\002nes)h(the)g(follo)n(wing)f (functions)f(and)i(constants:)0 4463 y FD(dis)p FJ(\()p FC([)p FK(bytesour)m(ce)12 b FC(])p FJ(\))208 4563 y FN(Disassemble)24 b(the)g FK(bytesour)m(ce)f FN(object.)36 b FK(bytesour)m(ce)24 b FN(can)g(denote)f(either)g(a)i(module,)e(a)i (class,)h(a)e(method,)g(a)g(function,)f(or)h(a)208 4663 y(code)e(object.)32 b(F)o(or)22 b(a)h(module,)f(it)i(disassembles)e (all)i(functions.)31 b(F)o(or)22 b(a)i(class,)g(it)f(disassembles)g (all)g(methods.)32 b(F)o(or)22 b(a)i(single)208 4762 y(code)j(sequence,)i(it)g(prints)e(one)h(line)g(per)g(byte)g(code)f (instruction.)48 b(If)28 b(no)f(object)h(is)h(pro)o(vided,)e(it)i (disassembles)g(the)f(last)208 4862 y(traceback.)0 5009 y FD(distb)p FJ(\()p FC([)p FK(tb)12 b FC(])p FJ(\))208 5108 y FN(Disassembles)20 b(the)g(top-of-stack)e(function)h(of)h(a)g (traceback,)f(using)g(the)h(last)h(traceback)e(if)i(none)e(w)o(as)i (passed.)k(The)19 b(instruc-)208 5208 y(tion)g(causing)h(the)g(e)o (xception)e(is)k(indicated.)0 5355 y FD(disassemble)p FJ(\()p FK(code)p FC([)p FK(,)17 b(lasti)12 b FC(])p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(888)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 889 901 TeXDict begin 889 900 bop 208 83 a FN(Disassembles)26 b(a)h(code)e(object,)i(indicating)e(the)h(last)h(instruction)e(if)i FK(lasti)f FN(w)o(as)h(pro)o(vided.)41 b(The)25 b(output)g(is)j(di)n (vided)c(in)j(the)208 183 y(follo)n(wing)18 b(columns:)328 396 y(1.)o(the)i(line)h(number)m(,)d(for)h(the)h(\002rst)h(instruction) e(of)h(each)g(line)328 529 y(2.)o(the)g(current)f(instruction,)g (indicated)g(as)i(`)p FJ(-->)p FN(',)328 662 y(3.)o(a)g(labelled)e (instruction,)g(indicated)g(with)i(`)p FJ(>>)p FN(',)328 794 y(4.)o(the)f(address)g(of)g(the)g(instruction,)328 927 y(5.)o(the)g(operation)f(code)g(name,)328 1060 y(6.)o(operation)g (parameters,)f(and)328 1193 y(7.)o(interpretation)g(of)i(the)g (parameters)f(in)i(parentheses.)208 1406 y(The)k(parameter)f (interpretation)g(recognizes)h(local)h(and)f(global)g(v)n(ariable)g (names,)h(constant)g(v)n(alues,)g(branch)f(tar)o(gets,)h(and)208 1506 y(compare)18 b(operators.)0 1653 y FD(disco)p FJ(\()p FK(code)p FC([)p FK(,)g(lasti)12 b FC(])p FJ(\))208 1752 y FN(A)32 b(synon)o(ym)d(for)j(disassemble.)59 b(It)32 b(is)h(more)e(con)m(v)o(enient)e(to)j(type,)i(and)d(k)o(ept)h(for)f (compatibility)f(with)i(earlier)g(Python)208 1852 y(releases.)0 1999 y FD(opname)208 2098 y FN(Sequence)18 b(of)i(operation)f(names,)g (inde)o(xable)g(using)g(the)h(byte)g(code.)0 2245 y FD(opmap)208 2345 y FN(Dictionary)e(mapping)h(byte)g(codes)h(to)h(operation)d (names.)0 2492 y FD(cmp_op)208 2591 y FN(Sequence)g(of)i(all)h(compare) e(operation)f(names.)0 2738 y FD(hasconst)208 2838 y FN(Sequence)g(of)i(byte)g(codes)g(that)g(ha)n(v)o(e)g(a)g(constant)g (parameter)-5 b(.)0 2985 y FD(hasfree)208 3084 y FN(Sequence)18 b(of)i(byte)g(codes)g(that)g(access)h(a)g(free)e(v)n(ariable.)0 3231 y FD(hasname)208 3331 y FN(Sequence)f(of)i(byte)g(codes)g(that)g (access)h(an)f(attrib)n(ute)g(by)g(name.)0 3478 y FD(hasjrel)208 3577 y FN(Sequence)e(of)i(byte)g(codes)g(that)g(ha)n(v)o(e)g(a)g (relati)n(v)o(e)g(jump)f(tar)o(get.)0 3724 y FD(hasjabs)208 3824 y FN(Sequence)f(of)i(byte)g(codes)g(that)g(ha)n(v)o(e)g(an)g (absolute)f(jump)h(tar)o(get.)0 3971 y FD(haslocal)208 4070 y FN(Sequence)e(of)i(byte)g(codes)g(that)g(access)h(a)g(local)f(v) n(ariable.)0 4217 y FD(hascompare)208 4317 y FN(Sequence)e(of)i(byte)g (codes)g(of)g(Boolean)f(operations.)0 4602 y Fv(30.10.1)101 b(Python)29 b(Byte)f(Code)h(Instr)q(uctions)0 4805 y FN(The)20 b(Python)f(compiler)g(currently)f(generates)h(the)i(follo)n (wing)d(byte)i(code)f(instructions.)0 4952 y FD(STOP_CODE)208 5051 y FN(Indicates)g(end-of-code)e(to)j(the)g(compiler)m(,)f(not)h (used)g(by)f(the)i(interpreter)-5 b(.)0 5198 y FD(NOP)208 5298 y FN(Do)20 b(nothing)e(code.)24 b(Used)d(as)g(a)f(placeholder)e (by)i(the)g(bytecode)f(optimizer)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(30.10.)52 b FJ(dis)23 b FI(\227)g(Disassemb)n(ler)g(f)n (or)g(Python)g(b)n(yte)h(code)1919 b(889)p eop end %%Page: 890 902 TeXDict begin 890 901 bop 0 83 a FD(POP_TOP)208 183 y FN(Remo)o(v)o(es)19 b(the)h(top-of-stack)e(\(T)o(OS\))h(item.)0 330 y FD(ROT_TWO)208 429 y FN(Sw)o(aps)h(the)g(tw)o(o)h(top-most)e (stack)h(items.)0 576 y FD(ROT_THREE)208 676 y FN(Lifts)g(second)f(and) h(third)g(stack)g(item)g(one)g(position)f(up,)h(mo)o(v)o(es)f(top)h(do) n(wn)f(to)h(position)g(three.)0 823 y FD(ROT_FOUR)208 922 y FN(Lifts)g(second,)f(third)h(and)f(forth)h(stack)g(item)g(one)g (position)f(up,)h(mo)o(v)o(es)f(top)h(do)n(wn)f(to)h(position)g(four)-5 b(.)0 1069 y FD(DUP_TOP)208 1169 y FN(Duplicates)19 b(the)i(reference)d (on)i(top)g(of)g(the)g(stack.)0 1316 y(Unary)f(Operations)g(tak)o(e)i (the)f(top)g(of)f(the)i(stack,)f(apply)f(the)h(operation,)e(and)i(push) g(the)g(result)g(back)f(on)h(the)g(stack.)0 1462 y FD(UNARY_POSITIVE) 208 1562 y FN(Implements)e FJ(TOS)50 b(=)f(+TOS)p FN(.)0 1709 y FD(UNARY_NEGATIVE)208 1808 y FN(Implements)18 b FJ(TOS)50 b(=)f(-TOS)p FN(.)0 1955 y FD(UNARY_NOT)208 2055 y FN(Implements)18 b FJ(TOS)50 b(=)f(not)g(TOS)p FN(.)0 2202 y FD(UNARY_CONVERT)208 2301 y FN(Implements)18 b FJ(TOS)50 b(=)f(`TOS`)p FN(.)0 2448 y FD(UNARY_INVERT)208 2548 y FN(Implements)18 b FJ(TOS)50 b(=)f(\230TOS)p FN(.)0 2695 y FD(GET_ITER)208 2794 y FN(Implements)18 b FJ(TOS)50 b(=)f(iter\(TOS\))p FN(.)0 2941 y(Binary)19 b(operations)e(remo)o(v)o (e)h(the)h(top)g(of)g(the)g(stack)g(\(T)o(OS\))g(and)f(the)i(second)e (top-most)g(stack)h(item)h(\(T)o(OS1\))d(from)i(the)g(stack.)25 b(The)o(y)0 3041 y(perform)18 b(the)i(operation,)e(and)i(put)g(the)g (result)g(back)g(on)g(the)g(stack.)0 3188 y FD(BINARY_POWER)208 3287 y FN(Implements)e FJ(TOS)50 b(=)f(TOS1)1168 3302 y(**)1318 3287 y(TOS)p FN(.)0 3434 y FD(BINARY_MULTIPLY)208 3534 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)1168 3549 y(*)1268 3534 y(TOS)p FN(.)0 3681 y FD(BINARY_DIVIDE)208 3780 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(/)h(TOS)20 b FN(when)g FJ(from)49 b(__future__)f(import)g(division)20 b FN(is)h(not)f(in)g(ef)n(fect.)0 3927 y FD(BINARY_FLOOR_DIVIDE)208 4027 y FN(Implements)e FJ(TOS)50 b(=)f(TOS1)g(//)h(TOS)p FN(.)0 4174 y FD(BINARY_TRUE_DIVIDE)208 4273 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(/)h(TOS)20 b FN(when)g FJ(from)49 b(__future__)f(import)g(division)20 b FN(is)h(in)f(ef)n(fect.)0 4420 y FD(BINARY_MODULO)208 4520 y FN(Implements)e FJ(TOS)50 b(=)f(TOS1)g(\045)h(TOS)p FN(.)0 4667 y FD(BINARY_ADD)208 4766 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(+)h(TOS)p FN(.)0 4913 y FD(BINARY_SUBTRACT)208 5013 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(-)h(TOS)p FN(.)0 5160 y FD(BINARY_SUBSCR)208 5259 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1[TOS])p FN(.)p 0 5549 3901 4 v 0 5649 a FI(890)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 891 903 TeXDict begin 891 902 bop 0 83 a FD(BINARY_LSHIFT)208 183 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(<<)h(TOS)p FN(.)0 330 y FD(BINARY_RSHIFT)208 429 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(>>)h(TOS)p FN(.)0 576 y FD(BINARY_AND)208 676 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(&)h(TOS)p FN(.)0 823 y FD(BINARY_XOR)208 922 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(\210)h(TOS)p FN(.)0 1069 y FD(BINARY_OR)208 1169 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1)g(|)h(TOS)p FN(.)0 1316 y(In-place)24 b(operations)h(are)g(lik)o(e)h(binary)f (operations,)g(in)h(that)g(the)o(y)f(remo)o(v)o(e)f(T)o(OS)i(and)f(T)o (OS1,)i(and)e(push)g(the)h(result)g(back)f(on)h(the)0 1415 y(stack,)d(b)n(ut)f(the)h(operation)d(is)j(done)f(in-place)f(when) h(T)o(OS1)g(supports)f(it,)i(and)f(the)h(resulting)e(T)o(OS)h(may)g(be) g(\(b)n(ut)g(does)h(not)f(ha)n(v)o(e)f(to)0 1515 y(be\))f(the)g (original)f(T)o(OS1.)0 1662 y FD(INPLACE_POWER)208 1761 y FN(Implements)f(in-place)i FJ(TOS)49 b(=)g(TOS1)1456 1776 y(**)1606 1761 y(TOS)p FN(.)0 1908 y FD(INPLACE_MULTIPLY)208 2008 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)1456 2023 y(*)1556 2008 y(TOS)p FN(.)0 2155 y FD(INPLACE_DIVIDE)208 2254 y FN(Implements)22 b(in-place)g FJ(TOS)50 b(=)f(TOS1)g(/)h(TOS)24 b FN(when)f FJ(from)49 b(__future__)f(import)g(division)23 b FN(is)i(not)e(in)h(ef-)208 2354 y(fect.)0 2501 y FD (INPLACE_FLOOR_DIVIDE)208 2600 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(//)h(TOS)p FN(.)0 2747 y FD(INPLACE_TRUE_DIVIDE) 208 2847 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(/)h (TOS)20 b FN(when)g FJ(from)49 b(__future__)f(import)h(division)19 b FN(is)i(in)f(ef)n(fect.)0 2994 y FD(INPLACE_MODULO)208 3093 y FN(Implements)e(in-place)i FJ(TOS)49 b(=)g(TOS1)g(\045)h(TOS)p FN(.)0 3240 y FD(INPLACE_ADD)208 3340 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(+)h(TOS)p FN(.)0 3487 y FD(INPLACE_SUBTRACT)208 3586 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(-)h(TOS)p FN(.)0 3733 y FD(INPLACE_LSHIFT)208 3833 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(<<)h(TOS)p FN(.)0 3980 y FD(INPLACE_RSHIFT)208 4079 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(>>)h(TOS)p FN(.)0 4226 y FD(INPLACE_AND)208 4326 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(&)h(TOS)p FN(.)0 4473 y FD(INPLACE_XOR)208 4572 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(\210)h(TOS) p FN(.)0 4719 y FD(INPLACE_OR)208 4819 y FN(Implements)18 b(in-place)i FJ(TOS)49 b(=)g(TOS1)g(|)h(TOS)p FN(.)0 4966 y(The)20 b(slice)h(opcodes)e(tak)o(e)h(up)g(to)g(three)g (parameters.)0 5113 y FD(SLICE+0)208 5212 y FN(Implements)e FJ(TOS)50 b(=)f(TOS[:])p FN(.)0 5359 y FD(SLICE+1)p 0 5549 3901 4 v 0 5649 a FI(30.10.)j FJ(dis)23 b FI(\227)g(Disassemb)n (ler)g(f)n(or)g(Python)g(b)n(yte)h(code)1919 b(891)p eop end %%Page: 892 904 TeXDict begin 892 903 bop 208 83 a FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1[TOS:])p FN(.)0 230 y FD(SLICE+2)208 330 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS1[:TOS])p FN(.)0 476 y FD(SLICE+3)208 576 y FN(Implements)18 b FJ(TOS)50 b(=)f(TOS2[TOS1:TOS])p FN(.)0 723 y(Slice)21 b(assignment)e(needs)h(e)n(v)o(en)f(an)h(additional)f(parameter)-5 b(.)24 b(As)d(an)o(y)e(statement,)h(the)o(y)g(put)f(nothing)g(on)h(the) g(stack.)0 870 y FD(STORE_SLICE+0)208 969 y FN(Implements)e FJ(TOS[:])99 b(=)49 b(TOS1)p FN(.)0 1116 y FD(STORE_SLICE+1)208 1216 y FN(Implements)18 b FJ(TOS1[TOS:])48 b(=)i(TOS2)p FN(.)0 1363 y FD(STORE_SLICE+2)208 1462 y FN(Implements)18 b FJ(TOS1[:TOS])48 b(=)i(TOS2)p FN(.)0 1609 y FD(STORE_SLICE+3)208 1709 y FN(Implements)18 b FJ(TOS2[TOS1:TOS])48 b(=)h(TOS3)p FN(.)0 1856 y FD(DELETE_SLICE+0)208 1955 y FN(Implements)18 b FJ(del)50 b(TOS[:])p FN(.)0 2102 y FD(DELETE_SLICE+1)208 2202 y FN(Implements)18 b FJ(del)50 b(TOS1[TOS:])p FN(.)0 2349 y FD(DELETE_SLICE+2)208 2448 y FN(Implements)18 b FJ(del)50 b(TOS1[:TOS])p FN(.)0 2595 y FD(DELETE_SLICE+3)208 2695 y FN(Implements)18 b FJ(del)50 b(TOS2[TOS1:TOS])p FN(.)0 2842 y FD(STORE_SUBSCR)208 2941 y FN(Implements)18 b FJ(TOS1[TOS])48 b(=)i(TOS2)p FN(.)0 3088 y FD(DELETE_SUBSCR)208 3188 y FN(Implements)18 b FJ(del)50 b(TOS1[TOS])p FN(.)0 3335 y(Miscellaneous)19 b(opcodes.)0 3482 y FD(PRINT_EXPR)208 3581 y FN(Implements)i(the)i(e)o(xpression)f(statement)h(for)f(the)h (interacti)n(v)o(e)f(mode.)32 b(T)o(OS)23 b(is)h(remo)o(v)o(ed)d(from)h (the)h(stack)g(and)g(printed.)32 b(In)208 3681 y(non-interacti)n(v)o(e) 17 b(mode,)i(an)h(e)o(xpression)e(statement)i(is)h(terminated)e(with)i FJ(POP_STACK)p FN(.)0 3828 y FD(PRINT_ITEM)208 3927 y FN(Prints)26 b(T)o(OS)f(to)h(the)f(\002le-lik)o(e)h(object)f(bound)f (to)i FJ(sys.stdout)p FN(.)40 b(There)24 b(is)j(one)e(such)g (instruction)g(for)g(each)g(item)h(in)g(the)208 4027 y FJ(print)19 b FN(statement.)0 4174 y FD(PRINT_ITEM_TO)208 4273 y FN(Lik)o(e)27 b FJ(PRINT_ITEM)p FN(,)f(b)n(ut)h(prints)g(the)g (item)h(second)e(from)h(T)o(OS)g(to)g(the)h(\002le-lik)o(e)f(object)g (at)h(T)o(OS.)f(This)g(is)i(used)e(by)g(the)208 4373 y(e)o(xtended)18 b(print)h(statement.)0 4520 y FD(PRINT_NEWLINE)208 4620 y FN(Prints)25 b(a)g(ne)n(w)f(line)h(on)g FJ(sys.stdout)p FN(.)37 b(This)25 b(is)g(generated)e(as)j(the)f(last)g(operation)e(of)i (a)g FJ(print)f FN(statement,)i(unless)f(the)208 4719 y(statement)20 b(ends)f(with)i(a)f(comma.)0 4866 y FD(PRINT_NEWLINE_TO) 208 4966 y FN(Lik)o(e)f FJ(PRINT_NEWLINE)p FN(,)e(b)n(ut)i(prints)f (the)i(ne)n(w)e(line)i(on)e(the)h(\002le-lik)o(e)h(object)e(on)h(the)g (T)o(OS.)g(This)g(is)h(used)f(by)f(the)i(e)o(xtended)208 5065 y(print)f(statement.)0 5212 y FD(BREAK_LOOP)208 5312 y FN(T)-6 b(erminates)19 b(a)i(loop)e(due)h(to)g(a)h FJ(break)e FN(statement.)p 0 5549 3901 4 v 0 5649 a FI(892)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 893 905 TeXDict begin 893 904 bop 0 83 a FD(CONTINUE_LOOP)81 b FK(tar)m(g)o(et)208 183 y FN(Continues)16 b(a)i(loop)e(due)h(to)g(a)h FJ(continue)e FN(statement.)24 b FK(tar)m(g)o(et)19 b FN(is)f(the)f(address)g(to)g(jump)g(to)g(\(which)f(should)h(be)g(a)g FJ(FOR_ITER)208 282 y FN(instruction\).)0 429 y FD(LIST_APPEND)208 529 y FN(Calls)k FJ(list.append\(TOS1,)47 b(TOS\))p FN(.)19 b(Used)i(to)f(implement)f(list)i(comprehensions.)0 676 y FD(LOAD_LOCALS)208 775 y FN(Pushes)f(a)h(reference)e(to)i(the)g (locals)g(of)f(the)g(current)g(scope)g(on)g(the)h(stack.)26 b(This)21 b(is)g(used)g(in)g(the)f(code)g(for)g(a)h(class)h (de\002nition:)208 875 y(After)d(the)i(class)g(body)e(is)i(e)n(v)n (aluated,)d(the)i(locals)h(are)f(passed)g(to)g(the)h(class)g (de\002nition.)0 1022 y FD(RETURN_VALUE)208 1121 y FN(Returns)f(with)g (T)o(OS)g(to)g(the)h(caller)f(of)g(the)g(function.)0 1268 y FD(YIELD_VALUE)208 1368 y FN(Pops)g FJ(TOS)g FN(and)g(yields)g (it)h(from)e(a)h(generator)-5 b(.)0 1515 y FD(IMPORT_STAR)208 1614 y FN(Loads)23 b(all)i(symbols)e(not)h(starting)f(with)i(`)p FJ(_)p FN(')e(directly)g(from)g(the)h(module)f(T)o(OS)h(to)g(the)g (local)g(namespace.)35 b(The)24 b(module)f(is)208 1714 y(popped)18 b(after)i(loading)e(all)j(names.)k(This)20 b(opcode)f(implements)g FJ(from)49 b(module)g(import)3061 1729 y(*)3111 1714 y FN(.)0 1861 y FD(EXEC_STMT)208 1961 y FN(Implements)18 b FJ(exec)49 b(TOS2,TOS1,TOS)p FN(.)18 b(The)i(compiler)f(\002lls)j(missing)e(optional)f(parameters)g(with)h FJ(None)p FN(.)0 2107 y FD(POP_BLOCK)208 2207 y FN(Remo)o(v)o(es)29 b(one)h(block)f(from)g(the)h(block)f(stack.)56 b(Per)30 b(frame,)i(there)e(is)h(a)f(stack)h(of)f(blocks,)i(denoting)c(nested)i (loops,)i(try)208 2307 y(statements,)20 b(and)f(such.)0 2454 y FD(END_FINALLY)208 2553 y FN(T)-6 b(erminates)18 b(a)i FJ(finally)f FN(clause.)25 b(The)19 b(interpreter)f(recalls)h (whether)g(the)g(e)o(xception)f(has)i(to)f(be)h(re-raised,)e(or)h (whether)g(the)208 2653 y(function)f(returns,)h(and)h(continues)f(with) h(the)g(outer)n(-ne)o(xt)e(block.)0 2800 y FD(BUILD_CLASS)208 2899 y FN(Creates)h(a)h(ne)n(w)f(class)i(object.)j(T)o(OS)19 b(is)h(the)f(methods)g(dictionary)-5 b(,)17 b(T)o(OS1)h(the)i(tuple)f (of)g(the)g(names)g(of)g(the)g(base)h(classes,)g(and)208 2999 y(T)o(OS2)f(the)h(class)i(name.)0 3146 y(All)f(of)f(the)g(follo)n (wing)f(opcodes)f(e)o(xpect)i(ar)o(guments.)i(An)f(ar)o(gument)c(is)22 b(tw)o(o)e(bytes,)g(with)g(the)g(more)g(signi\002cant)f(byte)h(last.)0 3293 y FD(STORE_NAME)81 b FK(namei)208 3392 y FN(Implements)26 b FJ(name)49 b(=)g(TOS)p FN(.)28 b FK(namei)f FN(is)h(the)g(inde)o(x)e (of)i FK(name)e FN(in)i(the)g(attrib)n(ute)f FJ(co_names)g FN(of)g(the)g(code)g(object.)47 b(The)208 3492 y(compiler)18 b(tries)j(to)g(use)f FJ(STORE_LOCAL)f FN(or)h FJ(STORE_GLOBAL)e FN(if)j(possible.)0 3639 y FD(DELETE_NAME)81 b FK(namei)208 3738 y FN(Implements)18 b FJ(del)50 b(name)p FN(,)19 b(where)h FK(namei)g FN(is)h(the)f(inde)o(x)f(into)h FJ(co_names)f FN(attrib)n(ute)h(of)g(the)g(code)g(object.)0 3885 y FD(UNPACK_SEQUENCE)80 b FK(count)208 3985 y FN(Unpacks)19 b(T)o(OS)h(into)g FK(count)h FN(indi)n(vidual)d(v)n(alues,)i(which)f (are)h(put)g(onto)g(the)g(stack)g(right-to-left.)0 4132 y FD(DUP_TOPX)82 b FK(count)208 4231 y FN(Duplicate)19 b FK(count)h FN(items,)g(k)o(eeping)e(them)i(in)g(the)f(same)h(order)-5 b(.)24 b(Due)c(to)g(implementation)d(limits,)k FK(count)f FN(should)f(be)g(between)208 4331 y(1)h(and)f(5)i(inclusi)n(v)o(e.)0 4478 y FD(STORE_ATTR)81 b FK(namei)208 4577 y FN(Implements)18 b FJ(TOS.name)49 b(=)g(TOS1)p FN(,)20 b(where)g FK(namei)f FN(is)i(the)g(inde)o(x)e(of)h(name)f(in)h FJ(co_names)p FN(.)0 4724 y FD(DELETE_ATTR)81 b FK(namei)208 4824 y FN(Implements)18 b FJ(del)50 b(TOS.name)p FN(,)19 b(using)g FK(namei)h FN(as)h(inde)o(x)e(into)h FJ(co_names)p FN(.)0 4971 y FD(STORE_GLOBAL)81 b FK(namei)208 5070 y FN(W)-7 b(orks)20 b(as)h FJ(STORE_NAME)p FN(,)e(b)n(ut)h(stores)g(the)g(name)g (as)h(a)g(global.)0 5217 y FD(DELETE_GLOBAL)81 b FK(namei)208 5317 y FN(W)-7 b(orks)20 b(as)h FJ(DELETE_NAME)p FN(,)d(b)n(ut)j (deletes)f(a)g(global)g(name.)p 0 5549 3901 4 v 0 5649 a FI(30.10.)52 b FJ(dis)23 b FI(\227)g(Disassemb)n(ler)g(f)n(or)g (Python)g(b)n(yte)h(code)1919 b(893)p eop end %%Page: 894 906 TeXDict begin 894 905 bop 0 83 a FD(LOAD_CONST)81 b FK(consti)208 183 y FN(Pushes)20 b(`)p FJ(co_consts[)p FK(consti)p FJ(])p FN(')d(onto)j(the)g(stack.)0 330 y FD(LOAD_NAME)81 b FK(namei)208 429 y FN(Pushes)20 b(the)g(v)n(alue)g(associated)g(with) g(`)p FJ(co_names[)p FK(namei)p FJ(])p FN(')d(onto)i(the)i(stack.)0 576 y FD(BUILD_TUPLE)81 b FK(count)208 676 y FN(Creates)20 b(a)h(tuple)f(consuming)e FK(count)j FN(items)f(from)f(the)i(stack,)f (and)f(pushes)h(the)g(resulting)g(tuple)f(onto)h(the)g(stack.)0 823 y FD(BUILD_LIST)81 b FK(count)208 922 y FN(W)-7 b(orks)20 b(as)h FJ(BUILD_TUPLE)p FN(,)d(b)n(ut)j(creates)f(a)g(list.)0 1069 y FD(BUILD_MAP)81 b FK(zer)l(o)208 1169 y FN(Pushes)20 b(a)h(ne)n(w)f(empty)f(dictionary)f(object)i(onto)f(the)i(stack.)k(The) 19 b(ar)o(gument)f(is)j(ignored)e(and)g(set)i(to)g(zero)e(by)h(the)g (compiler)-5 b(.)0 1316 y FD(LOAD_ATTR)81 b FK(namei)208 1415 y FN(Replaces)20 b(T)o(OS)g(with)g FJ(getattr\(TOS,)48 b(co_names[)p FK(namei)p FJ(]\))p FN(.)0 1562 y FD(COMPARE_OP)81 b FK(opname)208 1662 y FN(Performs)19 b(a)h(Boolean)g(operation.)j(The) d(operation)e(name)i(can)g(be)g(found)e(in)i FJ(cmp_op[)p FK(opname)p FJ(])p FN(.)0 1808 y FD(IMPORT_NAME)81 b FK(namei)208 1908 y FN(Imports)20 b(the)h(module)f FJ(co_names[)p FK(namei)p FJ(])p FN(.)26 b(The)21 b(module)f(object)h(is)h(pushed)e (onto)h(the)g(stack.)29 b(The)21 b(current)f(namespace)208 2008 y(is)h(not)f(af)n(fected:)k(for)19 b(a)i(proper)d(import)h (statement,)h(a)h(subsequent)d FJ(STORE_FAST)h FN(instruction)g (modi\002es)h(the)g(namespace.)0 2155 y FD(IMPORT_FROM)81 b FK(namei)208 2254 y FN(Loads)17 b(the)i(attrib)n(ute)f FJ(co_names[)p FK(namei)p FJ(])e FN(from)h(the)i(module)e(found)f(in)j (T)o(OS.)f(The)g(resulting)g(object)f(is)j(pushed)d(onto)h(the)208 2354 y(stack,)i(to)g(be)g(subsequently)e(stored)i(by)g(a)g FJ(STORE_FAST)f FN(instruction.)0 2501 y FD(JUMP_FORWARD)81 b FK(delta)208 2600 y FN(Increments)18 b(byte)i(code)f(counter)g(by)h FK(delta)p FN(.)0 2747 y FD(JUMP_IF_TRUE)81 b FK(delta)208 2847 y FN(If)20 b(T)o(OS)g(is)h(true,)e(increment)g(the)h(byte)g(code)g (counter)e(by)i FK(delta)p FN(.)25 b(T)o(OS)20 b(is)h(left)f(on)g(the)g (stack.)0 2994 y FD(JUMP_IF_FALSE)81 b FK(delta)208 3093 y FN(If)20 b(T)o(OS)g(is)h(f)o(alse,)f(increment)f(the)h(byte)g(code)f (counter)g(by)h FK(delta)p FN(.)k(T)o(OS)d(is)g(not)f(changed.)0 3240 y FD(JUMP_ABSOLUTE)81 b FK(tar)m(g)o(et)208 3340 y FN(Set)20 b(byte)g(code)g(counter)e(to)j FK(tar)m(g)o(et)q FN(.)0 3487 y FD(FOR_ITER)82 b FK(delta)208 3586 y FJ(TOS)20 b FN(is)h(an)g(iterator)-5 b(.)25 b(Call)d(its)f FJ(next\(\))f FN(method.)25 b(If)20 b(this)h(yields)f(a)h(ne)n(w)f(v)n(alue,)g(push)g (it)h(on)f(the)h(stack)f(\(lea)n(ving)g(the)g(iterator)208 3686 y(belo)n(w)j(it\).)37 b(If)24 b(the)h(iterator)e(indicates)h(it)h (is)g(e)o(xhausted)e FJ(TOS)h FN(is)h(popped,)e(and)h(the)g(byte)f (code)h(counter)f(is)i(incremented)d(by)208 3786 y FK(delta)p FN(.)0 3932 y FD(LOAD_GLOBAL)81 b FK(namei)208 4032 y FN(Loads)19 b(the)h(global)g(named)f FJ(co_names[)p FK(namei)p FJ(])f FN(onto)h(the)h(stack.)0 4179 y FD(SETUP_LOOP)81 b FK(delta)208 4279 y FN(Pushes)20 b(a)g(block)f(for)g(a)h(loop)f(onto) g(the)h(block)f(stack.)25 b(The)20 b(block)f(spans)h(from)e(the)i (current)f(instruction)f(with)j(a)f(size)g(of)g FK(delta)208 4378 y FN(bytes.)0 4525 y FD(SETUP_EXCEPT)81 b FK(delta)208 4625 y FN(Pushes)20 b(a)h(try)f(block)f(from)g(a)i(try-e)o(xcept)d (clause)i(onto)f(the)h(block)g(stack.)25 b FK(delta)20 b FN(points)f(to)i(the)f(\002rst)h(e)o(xcept)e(block.)0 4772 y FD(SETUP_FINALLY)81 b FK(delta)208 4871 y FN(Pushes)20 b(a)h(try)f(block)f(from)g(a)i(try-e)o(xcept)d(clause)i(onto)f(the)h (block)g(stack.)25 b FK(delta)20 b FN(points)f(to)i(the)f(\002nally)g (block.)0 5018 y FD(LOAD_FAST)81 b FK(var)p 647 5018 25 4 v 30 w(num)208 5118 y FN(Pushes)20 b(a)h(reference)d(to)i(the)h (local)f FJ(co_varnames[)p FK(var)p 1952 5118 V 27 w(num)p FJ(])g FN(onto)f(the)h(stack.)0 5265 y FD(STORE_FAST)81 b FK(var)p 697 5265 V 30 w(num)208 5364 y FN(Stores)20 b(T)o(OS)g(into)g(the)g(local)g FJ(co_varnames[)p FK(var)p 1782 5364 V 28 w(num)p FJ(])p FN(.)p 0 5549 3901 4 v 0 5649 a FI(894)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 895 907 TeXDict begin 895 906 bop 0 83 a FD(DELETE_FAST)81 b FK(var)p 747 83 25 4 v 30 w(num)208 183 y FN(Deletes)20 b(local)g FJ(co_varnames[)p FK(var)p 1375 183 V 28 w(num)p FJ(])p FN(.)0 330 y FD(LOAD_CLOSURE)81 b FK(i)208 429 y FN(Pushes)19 b(a)g(reference)e(to)i(the)g(cell)h(contained)d(in)i (slot)g FK(i)h FN(of)f(the)g(cell)g(and)f(free)h(v)n(ariable)f (storage.)23 b(The)c(name)f(of)h(the)g(v)n(ariable)f(is)208 529 y FJ(co_cellvars[)p FK(i)p FJ(])d FN(if)k FK(i)f FN(is)h(less)f(than)g(the)f(length)g(of)h FK(co)p 1902 529 V 29 w(cellvar)o(s)p FN(.)25 b(Otherwise)17 b(it)i(is)f FJ(co_freevars[)p FK(i)48 b FJ(-)h(len\(co_-)208 628 y(cellvars\)])p FN(.)0 775 y FD(LOAD_DEREF)81 b FK(i)208 875 y FN(Loads)22 b(the)h(cell)h(contained)d(in)i(slot)h FK(i)f FN(of)g(the)g(cell)h(and)e(free)h(v)n(ariable)f(storage.)32 b(Pushes)24 b(a)f(reference)e(to)j(the)f(object)f(the)h(cell)208 975 y(contains)c(on)h(the)g(stack.)0 1121 y FD(STORE_DEREF)81 b FK(i)208 1221 y FN(Stores)20 b(T)o(OS)g(into)g(the)g(cell)h (contained)d(in)j(slot)f FK(i)h FN(of)f(the)g(cell)h(and)f(free)f(v)n (ariable)g(storage.)0 1368 y FD(SET_LINENO)81 b FK(lineno)208 1468 y FN(This)20 b(opcode)e(is)k(obsolete.)0 1614 y FD(RAISE_VARARGS)81 b FK(ar)m(gc)208 1714 y FN(Raises)24 b(an)f(e)o(xception.)32 b FK(ar)m(gc)22 b FN(indicates)h(the)g(number)f (of)g(parameters)g(to)i(the)f(raise)g(statement,)g(ranging)f(from)g(0)h (to)g(3.)34 b(The)208 1814 y(handler)18 b(will)j(\002nd)f(the)g (traceback)f(as)i(T)o(OS2,)e(the)i(parameter)d(as)j(T)o(OS1,)f(and)f (the)h(e)o(xception)f(as)i(T)o(OS.)0 1961 y FD(CALL_FUNCTION)81 b FK(ar)m(gc)208 2060 y FN(Calls)17 b(a)g(function.)k(The)16 b(lo)n(w)g(byte)g(of)g FK(ar)m(gc)g FN(indicates)g(the)g(number)e(of)i (positional)g(parameters,)f(the)h(high)g(byte)f(the)h(number)f(of)208 2160 y(k)o(e)o(yw)o(ord)k(parameters.)25 b(On)c(the)g(stack,)g(the)f (opcode)g(\002nds)g(the)h(k)o(e)o(yw)o(ord)e(parameters)h(\002rst.)27 b(F)o(or)21 b(each)f(k)o(e)o(yw)o(ord)f(ar)o(gument,)208 2259 y(the)k(v)n(alue)f(is)i(on)e(top)h(of)f(the)h(k)o(e)o(y)-5 b(.)32 b(Belo)n(w)24 b(the)f(k)o(e)o(yw)o(ord)e(parameters,)h(the)h (positional)f(parameters)g(are)g(on)h(the)g(stack,)g(with)208 2359 y(the)d(right-most)e(parameter)h(on)h(top.)25 b(Belo)n(w)20 b(the)g(parameters,)f(the)h(function)f(object)g(to)i(call)f(is)h(on)f (the)g(stack.)0 2506 y FD(MAKE_FUNCTION)81 b FK(ar)m(gc)208 2606 y FN(Pushes)20 b(a)h(ne)n(w)g(function)d(object)i(on)h(the)f (stack.)26 b(T)o(OS)21 b(is)g(the)g(code)f(associated)g(with)h(the)f (function.)25 b(The)20 b(function)f(object)h(is)208 2705 y(de\002ned)f(to)h(ha)n(v)o(e)g FK(ar)m(gc)g FN(def)o(ault)f (parameters,)g(which)g(are)i(found)d(belo)n(w)i(T)o(OS.)0 2852 y FD(MAKE_CLOSURE)81 b FK(ar)m(gc)208 2952 y FN(Creates)22 b(a)g(ne)n(w)g(function)e(object,)h(sets)i(its)g FK(func)p 1639 2952 V 29 w(closur)m(e)f FN(slot,)g(and)f(pushes)h(it)g(on)g(the)f (stack.)30 b(T)o(OS)22 b(is)h(the)f(code)f(associated)208 3051 y(with)j(the)g(function.)34 b(If)24 b(the)f(code)h(object)f(has)h (N)g(free)g(v)n(ariables,)g(the)g(ne)o(xt)f(N)h(items)g(on)g(the)g (stack)g(are)g(the)g(cells)g(for)f(these)208 3151 y(v)n(ariables.)h (The)c(function)e(also)i(has)h FK(ar)m(gc)f FN(def)o(ault)f (parameters,)g(where)h(are)g(found)e(before)h(the)h(cells.)0 3298 y FD(BUILD_SLICE)81 b FK(ar)m(gc)208 3397 y FN(Pushes)24 b(a)g(slice)g(object)g(on)f(the)h(stack.)36 b FK(ar)m(gc)23 b FN(must)h(be)g(2)g(or)f(3.)36 b(If)24 b(it)g(is)h(2,)g FJ(slice\(TOS1,)47 b(TOS\))24 b FN(is)h(pushed;)f(if)g(it)h(is)g(3,)208 3497 y FJ(slice\(TOS2,)47 b(TOS1,)i(TOS\))20 b FN(is)h(pushed.)j(See)d (the)f FJ(slice\(\))f FN(b)n(uilt-in)h(function)e(for)i(more)f (information.)0 3644 y FD(EXTENDED_ARG)81 b FK(e)n(xt)208 3744 y FN(Pre\002x)o(es)25 b(an)o(y)f(opcode)g(which)g(has)i(an)f(ar)o (gument)e(too)i(big)g(to)g(\002t)h(into)f(the)g(def)o(ault)g(tw)o(o)g (bytes.)40 b FK(e)n(xt)28 b FN(holds)c(tw)o(o)i(additional)208 3843 y(bytes)d(which,)g(tak)o(en)f(together)g(with)h(the)h(subsequent)d (opcode')-5 b(s)22 b(ar)o(gument,)f(comprise)h(a)i(four)n(-byte)d(ar)o (gument,)g FK(e)n(xt)26 b FN(being)208 3943 y(the)20 b(tw)o(o)g(most-signi\002cant)f(bytes.)0 4090 y FD(CALL_FUNCTION_VAR)80 b FK(ar)m(gc)208 4189 y FN(Calls)19 b(a)g(function.)j FK(ar)m(gc)c FN(is)h(interpreted)d(as)j(in)g FJ(CALL_FUNCTION)p FN(.)d(The)h(top)h(element)g(on)g(the)g(stack)g(contains)f(the)i(v)n (ariable)208 4289 y(ar)o(gument)e(list,)k(follo)n(wed)e(by)h(k)o(e)o (yw)o(ord)e(and)i(positional)f(ar)o(guments.)0 4436 y FD(CALL_FUNCTION_KW)80 b FK(ar)m(gc)208 4535 y FN(Calls)18 b(a)f(function.)22 b FK(ar)m(gc)16 b FN(is)i(interpreted)d(as)j(in)f FJ(CALL_FUNCTION)p FN(.)d(The)j(top)f(element)g(on)h(the)g(stack)g (contains)f(the)g(k)o(e)o(yw)o(ord)208 4635 y(ar)o(guments)i (dictionary)-5 b(,)17 b(follo)n(wed)i(by)h(e)o(xplicit)g(k)o(e)o(yw)o (ord)e(and)i(positional)f(ar)o(guments.)0 4782 y FD (CALL_FUNCTION_VAR_KW)79 b FK(ar)m(gc)208 4882 y FN(Calls)18 b(a)f(function.)22 b FK(ar)m(gc)16 b FN(is)i(interpreted)d(as)j(in)f FJ(CALL_FUNCTION)p FN(.)d(The)j(top)f(element)g(on)h(the)g(stack)g (contains)f(the)g(k)o(e)o(yw)o(ord)208 4981 y(ar)o(guments)25 b(dictionary)-5 b(,)26 b(follo)n(wed)g(by)g(the)i(v)n(ariable-ar)o (guments)23 b(tuple,)28 b(follo)n(wed)d(by)i(e)o(xplicit)g(k)o(e)o(yw)o (ord)e(and)h(positional)208 5081 y(ar)o(guments.)0 5228 y FD(HAVE_ARGUMENT)208 5327 y FN(This)k(is)g(not)g(really)g(an)f (opcode.)53 b(It)30 b(identi\002es)g(the)g(di)n(viding)e(line)i (between)f(opcodes)g(which)g(don')o(t)f(tak)o(e)i(ar)o(guments)e FJ(<)p 0 5549 3901 4 v 0 5649 a FI(30.10.)52 b FJ(dis)23 b FI(\227)g(Disassemb)n(ler)g(f)n(or)g(Python)g(b)n(yte)h(code)1919 b(895)p eop end %%Page: 896 908 TeXDict begin 896 907 bop 208 83 a FJ(HAVE_ARGUMENT)18 b FN(and)i(those)g(which)f(do)h FJ(>=)49 b(HAVE_ARGUMENT)p FN(.)0 410 y FE(30.11)122 b Fx(pickletools)30 b FE(\227)j(T)-14 b(ools)33 b(f)l(or)h(pic)n(kle)e(de)l(v)m(elopers)n(.)0 643 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.3.)0 790 y(This)d(module)e (contains)h(v)n(arious)g(constants)g(relating)g(to)h(the)g(intimate)g (details)g(of)f(the)h FJ(pickle)f FN(module,)g(some)h(lengthy)e (comments)0 890 y(about)h(the)h(implementation,)f(and)h(a)g(fe)n(w)g (useful)g(functions)f(for)g(analyzing)g(pickled)g(data.)23 b(The)16 b(contents)g(of)f(this)i(module)e(are)h(useful)0 989 y(for)24 b(Python)f(core)g(de)n(v)o(elopers)f(who)i(are)g(w)o (orking)f(on)g(the)h FJ(pickle)g FN(and)g FJ(cPickle)f FN(implementations;)h(ordinary)e(users)j(of)f(the)0 1089 y FJ(pickle)c FN(module)e(probably)g(w)o(on')o(t)h(\002nd)h(the)h FJ(pickletools)d FN(module)h(rele)n(v)n(ant.)0 1236 y FD(dis)p FJ(\()p FK(pic)n(kle)p FC([)p FK(,)g(out=None)o(,)g(memo=None) o(,)g(indentle)o(vel=4)12 b FC(])p FJ(\))208 1336 y FN(Outputs)26 b(a)i(symbolic)e(disassembly)h(of)g(the)g(pickle)g(to)g(the)h (\002le-lik)o(e)f(object)g FK(out)q FN(,)i(def)o(aulting)c(to)j FJ(sys.stdout)p FN(.)44 b FK(pic)n(kle)208 1435 y FN(can)24 b(be)g(a)h(string)g(or)f(a)h(\002le-lik)o(e)f(object.)38 b FK(memo)24 b FN(can)h(be)f(a)h(Python)f(dictionary)e(that)j(will)g (be)g(used)f(as)h(the)g(pickle')-5 b(s)24 b(memo;)208 1535 y(it)f(can)f(be)h(used)f(to)g(perform)f(disassemblies)i(across)f (multiple)g(pickles)g(created)g(by)g(the)h(same)f(pickler)-5 b(.)32 b(Successi)n(v)o(e)22 b(le)n(v)o(els,)208 1634 y(indicated)d(by)g FJ(MARK)h FN(opcodes)f(in)i(the)f(stream,)g(are)g (indented)e(by)i FK(indentle)o(vel)f FN(spaces.)0 1781 y FD(genops)p FJ(\()p FK(pic)n(kle)p FJ(\))208 1881 y FN(Pro)o(vides)j(an)h(iterator)f(o)o(v)o(er)g(all)i(of)e(the)i(opcodes) d(in)j(a)f(pickle,)g(returning)e(a)j(sequence)e(of)h FJ(\()p FK(opcode)p FJ(,)47 b FK(ar)m(g)p FJ(,)i FK(pos)p FJ(\))23 b FN(triples.)208 1981 y FK(opcode)d FN(is)k(an)e(instance)h (of)f(an)g FJ(OpcodeInfo)g FN(class;)i FK(ar)m(g)f FN(is)g(the)g (decoded)e(v)n(alue,)h(as)h(a)g(Python)f(object,)g(of)g(the)h(opcode') -5 b(s)208 2080 y(ar)o(gument;)17 b FK(pos)k FN(is)g(the)f(position)f (at)i(which)f(this)g(opcode)f(is)i(located.)j FK(pic)n(kle)d FN(can)f(be)g(a)g(string)g(or)g(a)h(\002le-lik)o(e)f(object.)0 2408 y FE(30.12)122 b Fx(distutils)30 b FE(\227)j(Building)h(and)g (installing)g(Python)g(modules)0 2640 y FN(The)21 b FJ(distutils)g FN(package)f(pro)o(vides)g(support)g(for)h(b)n(uilding)g(and)g (installing)g(additional)g(modules)f(into)i(a)g(Python)e(installation.) 0 2740 y(The)g(ne)n(w)h(modules)e(may)h(be)h(either)f(100\045-pure)e (Python,)i(or)g(may)g(be)h(e)o(xtension)e(modules)h(written)g(in)h(C,)g (or)g(may)f(be)g(collections)0 2840 y(of)g(Python)f(packages)g(which)h (include)f(modules)g(coded)g(in)h(both)g(Python)f(and)g(C.)0 2987 y(This)25 b(package)f(is)i(discussed)e(in)i(tw)o(o)f(separate)f (documents)g(which)g(are)h(included)f(in)h(the)g(Python)e (documentation)g(package.)37 b(T)-7 b(o)0 3086 y(learn)15 b(about)g(distrib)n(uting)f(ne)n(w)h(modules)f(using)h(the)h FJ(distutils)e FN(f)o(acilities,)j(read)e FK(Distrib)n(uting)g(Python)g (Modules)p FN(;)h(this)g(includes)0 3186 y(documentation)k(needed)h(to) i(e)o(xtend)f(distutils.)33 b(T)-7 b(o)23 b(learn)f(about)g(installing) g(Python)g(modules,)g(whether)g(or)g(not)h(the)g(author)e(made)0 3285 y(use)f(of)g(the)h FJ(distutils)e FN(package,)f(read)i FK(Installing)f(Python)g(Modules)p FN(.)0 3432 y FL(See)i(Also:)0 3579 y FK(Distrib)n(uting)f(Python)f(Modules)0 3679 y Fy(\()p FO(../dist/dist.html)l Fy(\))208 3778 y FN(The)27 b(manual)g(for)h(de)n(v)o(elopers)d(and)j(packagers)e(of)i(Python)f (modules.)47 b(This)28 b(describes)g(ho)n(w)f(to)i(prepare)d FJ(distutils)p FN(-)208 3878 y(based)19 b(packages)g(so)i(that)f(the)o (y)g(may)f(be)i(easily)f(installed)g(into)g(an)g(e)o(xisting)g(Python)f (installation.)0 4025 y FK(Installing)g(Python)g(Modules)0 4124 y Fy(\()p FO(../inst/inst.html)l Fy(\))208 4224 y FN(An)i(\223administrators\224)e(manual)h(which)g(includes)h (information)d(on)j(installing)g(modules)f(into)g(an)h(e)o(xisting)g (Python)f(installa-)208 4324 y(tion.)k(Y)-9 b(ou)20 b(do)g(not)f(need)h (to)g(be)g(a)h(Python)e(programmer)e(to)k(read)e(this)i(manual.)p 0 5549 3901 4 v 0 5649 a FI(896)2259 b(Chapter)23 b(30.)52 b(Python)24 b(Language)g(Ser)r(vices)p eop end %%Page: 897 909 TeXDict begin 897 908 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3220 427 y FG(THIR)n(TY)-8 b(ONE)p 0 515 V 1528 978 a FT(Python)57 b(compiler)g(pac)l(kage)0 1468 y FN(The)22 b(Python)f(compiler)f (package)h(is)i(a)f(tool)g(for)g(analyzing)e(Python)h(source)g(code)h (and)f(generating)f(Python)h(bytecode.)29 b(The)21 b(com-)0 1568 y(piler)i(contains)g(libraries)f(to)i(generate)e(an)h(abstract)g (syntax)g(tree)g(from)f(Python)g(source)h(code)f(and)h(to)g(generate)f (Python)g(bytecode)0 1667 y(from)d(the)h(tree.)0 1814 y(The)k FJ(compiler)f FN(package)g(is)j(a)e(Python)g(source)f(to)i (bytecode)d(translator)i(written)g(in)g(Python.)37 b(It)24 b(uses)h(the)g(b)n(uilt-in)e(parser)h(and)0 1914 y(standard)h FJ(parser)h FN(module)f(to)h(generated)f(a)h(concrete)f(syntax)h(tree.) 43 b(This)27 b(tree)f(is)h(used)f(to)h(generate)e(an)h(abstract)g (syntax)g(tree)0 2013 y(\(AST\))20 b(and)g(then)f(Python)g(bytecode.)0 2160 y(The)e(full)g(functionality)e(of)i(the)g(package)f(duplicates)g (the)h(b)n(uiltin)g(compiler)f(pro)o(vided)e(with)k(the)f(Python)f (interpreter)-5 b(.)23 b(It)17 b(is)h(intended)0 2260 y(to)e(match)g(its)h(beha)n(vior)d(almost)i(e)o(xactly)-5 b(.)22 b(Why)16 b(implement)f(another)f(compiler)h(that)h(does)g(the)g (same)g(thing?)23 b(The)16 b(package)e(is)j(useful)0 2359 y(for)k(a)h(v)n(ariety)e(of)h(purposes.)28 b(It)22 b(can)f(be)g(modi\002ed)f(more)h(easily)h(than)f(the)g(b)n(uiltin)g (compiler)-5 b(.)28 b(The)21 b(AST)h(it)g(generates)f(is)h(useful)f (for)0 2459 y(analyzing)e(Python)g(source)g(code.)0 2606 y(This)g(chapter)f(e)o(xplains)g(ho)n(w)h(the)g(v)n(arious)f (components)e(of)j(the)g FJ(compiler)f FN(package)g(w)o(ork.)24 b(It)19 b(blends)f(reference)g(material)g(with)0 2706 y(a)j(tutorial.)0 2852 y(The)f(follo)n(wing)e(modules)i(are)g(part)f (of)h(the)h FJ(compiler)e FN(package:)0 3324 y FE(31.1)121 b(The)34 b(basic)g(interf)l(ace)0 3557 y FN(The)27 b(top-le)n(v)o(el)f (of)g(the)i(package)d(de\002nes)i(four)g(functions.)44 b(If)27 b(you)g(import)f FJ(compiler)p FN(,)i(you)e(will)i(get)f(these) h(functions)d(and)i(a)0 3656 y(collection)19 b(of)h(modules)f (contained)g(in)h(the)g(package.)0 3803 y FD(parse)p FJ(\()p FK(b)n(uf)12 b FJ(\))208 3903 y FN(Returns)21 b(an)h(abstract)f(syntax)h(tree)f(for)g(the)h(Python)f(source)g(code)g (in)h FK(b)n(uf)12 b FN(.)30 b(The)21 b(function)f(raises)j FJ(SyntaxError)d FN(if)i(there)208 4002 y(is)f(an)f(error)f(in)h(the)g (source)g(code.)k(The)c(return)f(v)n(alue)g(is)j(a)e FJ(compiler.ast.Module)d FN(instance)j(that)h(contains)e(the)h(tree.)0 4149 y FD(parseFile)p FJ(\()p FK(path)p FJ(\))208 4249 y FN(Return)31 b(an)h(abstract)g(syntax)g(tree)g(for)f(the)i(Python)e (source)g(code)h(in)g(the)g(\002le)h(speci\002ed)f(by)f FK(path)p FN(.)60 b(It)33 b(is)g(equi)n(v)n(alent)d(to)208 4349 y FJ(parse\(open\()p FK(path)p FJ(\).read\(\)\))p FN(.)0 4495 y FD(walk)p FJ(\()p FK(ast,)19 b(visitor)r FC([)p FK(,)i(verbose)12 b FC(])p FJ(\))208 4595 y FN(Do)25 b(a)h(pre-order)d(w)o(alk)j(o)o(v)o(er)e(the)h(abstract)h(syntax)e (tree)i FK(ast)q FN(.)42 b(Call)26 b(the)g(appropriate)d(method)h(on)h (the)h FK(visitor)i FN(instance)d(for)208 4695 y(each)19 b(node)h(encountered.)0 4842 y FD(compile)p FJ(\()p FK(sour)m(ce)o(,)e (\002lename)o(,)h(mode)o(,)h(\003a)o(gs=None)o(,)f(dont)p 1782 4842 25 4 v 28 w(inherit=None)p FJ(\))208 4941 y FN(Compile)f(the)h(string)g FK(sour)m(ce)p FN(,)g(a)g(Python)f(module,) g(statement)h(or)f(e)o(xpression,)g(into)h(a)g(code)f(object)h(that)g (can)g(be)g(e)o(x)o(ecuted)e(by)208 5041 y(the)j(e)o(x)o(ec)f (statement)h(or)g FJ(eval\(\))p FN(.)k(This)d(function)d(is)j(a)g (replacement)d(for)i(the)g(b)n(uilt-in)g FJ(compile\(\))f FN(function.)208 5171 y(The)g FK(\002lename)g FN(will)i(be)g(used)e (for)h(run-time)f(error)g(messages.)208 5300 y(The)j FK(mode)g FN(must)h(be)f('e)o(x)o(ec')f(to)i(compile)f(a)h(module,)f(') -5 b(single')22 b(to)h(compile)e(a)i(single)g(\(interacti)n(v)o(e\))e (statement,)h(or)h('e)n(v)n(al')e(to)208 5400 y(compile)e(an)h(e)o (xpression.)p 0 5549 3901 4 v 3762 5649 a FI(897)p eop end %%Page: 898 910 TeXDict begin 898 909 bop 208 83 a FN(The)19 b FK(\003a)o(gs)h FN(and)g FK(dont)p 829 83 25 4 v 28 w(inherit)i FN(ar)o(guments)c(af)n (fect)i(future-related)d(statements,)j(b)n(ut)h(are)f(not)f(supported)g (yet.)0 230 y FD(compileFile)p FJ(\()p FK(sour)m(ce)p FJ(\))208 330 y FN(Compiles)h(the)g(\002le)h FK(sour)m(ce)f FN(and)f(generates)h(a)g(.p)o(yc)g(\002le.)0 476 y(The)d FJ(compiler)g FN(package)g(contains)g(the)h(follo)n(wing)e(modules:)23 b FJ(ast)p FN(,)18 b FJ(consts)p FN(,)f FJ(future)p FN(,)h FJ(misc)p FN(,)g FJ(pyassem)p FN(,)f FJ(pycodegen)p FN(,)0 576 y FJ(symbols)p FN(,)i FJ(transformer)p FN(,)g(and)g FJ(visitor)p FN(.)0 903 y FE(31.2)121 b(Limitations)0 1136 y FN(There)18 b(are)g(some)g(problems)f(with)i(the)f(error)g (checking)e(of)i(the)h(compiler)e(package.)23 b(The)18 b(interpreter)f(detects)h(syntax)g(errors)g(in)g(tw)o(o)0 1236 y(distinct)24 b(phases.)37 b(One)24 b(set)h(of)f(errors)g(is)h (detected)e(by)h(the)g(interpreter')-5 b(s)23 b(parser)m(,)h(the)g (other)g(set)h(by)f(the)g(compiler)-5 b(.)36 b(The)24 b(compiler)0 1336 y(package)19 b(relies)h(on)g(the)h(interpreter')-5 b(s)19 b(parser)m(,)g(so)h(it)h(get)g(the)f(\002rst)h(phases)f(of)g (error)f(checking)g(for)h(free.)k(It)d(implements)e(the)h(second)0 1435 y(phase)25 b(itself,)i(and)e(that)h(implementation)d(is)k (incomplete.)39 b(F)o(or)25 b(e)o(xample,)g(the)h(compiler)e(package)g (does)h(not)h(raise)f(an)h(error)e(if)i(a)0 1535 y(name)20 b(appears)f(more)g(than)h(once)f(in)i(an)f(ar)o(gument)e(list:)26 b FJ(def)49 b(f\(x,)g(x\):)100 b(...)0 1682 y FN(A)21 b(future)e(v)o(ersion)g(of)h(the)g(compiler)f(should)g(\002x)h(these)h (problems.)0 2009 y FE(31.3)121 b(Python)35 b(Abstr)o(act)e(Syntax)0 2242 y FN(The)20 b FJ(compiler.ast)f FN(module)g(de\002nes)h(an)h (abstract)f(syntax)g(for)f(Python.)25 b(In)20 b(the)h(abstract)f (syntax)g(tree,)g(each)g(node)f(represents)0 2341 y(a)i(syntactic)f (construct.)j(The)d(root)g(of)g(the)g(tree)g(is)h FJ(Module)f FN(object.)0 2488 y(The)c(abstract)f(syntax)g(of)n(fers)g(a)i(higher)d (le)n(v)o(el)i(interf)o(ace)f(to)h(parsed)f(Python)f(source)i(code.)22 b(The)16 b FJ(parser)f FN(module)g(and)g(the)h(compiler)0 2588 y(written)22 b(in)h(C)g(for)e(the)i(Python)e(interpreter)g(use)h (a)h(concrete)e(syntax)h(tree.)31 b(The)22 b(concrete)f(syntax)h(is)h (tied)f(closely)g(to)h(the)f(grammar)0 2688 y(description)d(used)h(for) f(the)i(Python)e(parser)-5 b(.)24 b(Instead)c(of)g(a)h(single)f(node)f (for)g(a)i(construct,)e(there)h(are)g(often)f(se)n(v)o(eral)h(le)n(v)o (els)g(of)g(nested)0 2787 y(nodes)f(that)i(are)f(introduced)e(by)h (Python')-5 b(s)20 b(precedence)e(rules.)0 2934 y(The)j(abstract)f (syntax)h(tree)g(is)h(created)e(by)h(the)g FJ(compiler.transformer)c FN(module.)26 b(The)21 b(transformer)e(relies)i(on)g(the)g(b)n(uiltin)0 3034 y(Python)e(parser)h(to)g(generate)f(a)i(concrete)d(syntax)i(tree.) 25 b(It)20 b(generates)g(an)g(abstract)g(syntax)f(tree)h(from)g(the)g (concrete)f(tree.)0 3181 y(The)i FJ(transformer)e FN(module)h(w)o(as)h (created)f(by)h(Gre)o(g)f(Stein)h(and)g(Bill)h(T)l(utt)f(for)f(an)h(e)o (xperimental)e(Python-to-C)g(compiler)-5 b(.)26 b(The)0 3280 y(current)17 b(v)o(ersion)h(contains)g(a)h(number)e(of)h (modi\002cations)g(and)g(impro)o(v)o(ements,)e(b)n(ut)j(the)f(basic)h (form)f(of)g(the)h(abstract)g(syntax)f(and)g(of)0 3380 y(the)i(transformer)e(are)i(due)g(to)g(Stein)h(and)e(T)l(utt.)0 3665 y Fv(31.3.1)101 b(AST)28 b(Nodes)0 3868 y FN(The)20 b FJ(compiler.ast)f FN(module)g(is)j(generated)d(from)g(a)i(te)o(xt)g (\002le)g(that)g(describes)f(each)g(node)g(type)g(and)g(its)i (elements.)j(Each)c(node)0 3967 y(type)j(is)h(represented)e(as)i(a)f (class)i(that)e(inherits)g(from)f(the)i(abstract)f(base)g(class)h FJ(compiler.ast.Node)d FN(and)i(de\002nes)g(a)h(set)g(of)0 4067 y(named)19 b(attrib)n(utes)h(for)g(child)g(nodes.)0 4214 y FL(class)h FD(Node)p FJ(\(\))208 4313 y FN(The)f FJ(Node)h FN(instances)g(are)g(created)g(automatically)e(by)i(the)g (parser)g(generator)-5 b(.)26 b(The)21 b(recommended)d(interf)o(ace)i (for)g(speci\002c)208 4413 y FJ(Node)f FN(instances)h(is)h(to)f(use)g (the)g(public)f(attrib)n(utes)g(to)h(access)h(child)e(nodes.)24 b(A)d(public)e(attrib)n(ute)g(may)h(be)f(bound)f(to)i(a)h(single)208 4513 y(node)f(or)g(to)i(a)f(sequence)f(of)h(nodes,)f(depending)f(on)i (the)g FJ(Node)g FN(type.)27 b(F)o(or)21 b(e)o(xample,)e(the)j FJ(bases)e FN(attrib)n(ute)h(of)g(the)g FJ(Class)208 4612 y FN(node,)d(is)k(bound)c(to)i(a)h(list)g(of)f(base)g(class)h (nodes,)f(and)f(the)i FJ(doc)f FN(attrib)n(ute)g(is)h(bound)d(to)i(a)h (single)f(node.)208 4745 y(Each)g FJ(Node)h FN(instance)g(has)h(a)f FJ(lineno)g FN(attrib)n(ute)g(which)g(may)f(be)i FJ(None)p FN(.)28 b(XXX)21 b(Not)h(sure)f(what)g(the)g(rules)g(are)g(for)g(which) 208 4845 y(nodes)e(will)i(ha)n(v)o(e)f(a)g(useful)g(lineno.)0 4992 y(All)h FJ(Node)f FN(objects)g(of)n(fer)f(the)h(follo)n(wing)f (methods:)0 5139 y FD(getChildren)p FJ(\(\))208 5238 y FN(Returns)f(a)h(\003attened)g(list)g(of)g(the)g(child)f(nodes)g(and) g(objects)h(in)g(the)f(order)g(the)o(y)g(occur)-5 b(.)24 b(Speci\002cally)-5 b(,)18 b(the)h(order)e(of)i(the)f(nodes)p 0 5549 3901 4 v 0 5649 a FI(898)2323 b(Chapter)23 b(31.)53 b(Python)23 b(compiler)h(pac)n(kage)p eop end %%Page: 899 911 TeXDict begin 899 910 bop 208 83 a FN(is)19 b(the)g(order)e(in)i(which) f(the)o(y)g(appear)f(in)i(the)g(Python)e(grammar)-5 b(.)23 b(Not)c(all)g(of)f(the)h(children)e(are)i FJ(Node)f FN(instances.)25 b(The)18 b(names)208 183 y(of)h(functions)g(and)h(classes,)h(for)e(e)o (xample,)g(are)h(plain)g(strings.)0 330 y FD(getChildNodes)p FJ(\(\))208 429 y FN(Returns)d(a)h(\003attened)g(list)g(of)g(the)g (child)f(nodes)g(in)h(the)g(order)e(the)o(y)h(occur)-5 b(.)24 b(This)17 b(method)g(is)h(lik)o(e)g FJ(getChildren\(\))p FN(,)f(e)o(xcept)208 529 y(that)j(it)h(only)e(returns)g(those)h (children)f(that)i(are)f FJ(Node)g FN(instances.)0 676 y(T)-7 b(w)o(o)29 b(e)o(xamples)f(illustrate)h(the)g(general)f (structure)g(of)h FJ(Node)g FN(classes.)52 b(The)28 b FJ(while)h FN(statement)g(is)h(de\002ned)e(by)g(the)h(follo)n(wing)0 775 y(grammar)18 b(production:)236 1013 y FA(while_stmt:)223 b("while")43 b(expression)g(":")i(suite)909 1105 y(["else")e(":")i (suite])0 1391 y FN(The)19 b FJ(While)h FN(node)f(has)h(three)f(attrib) n(utes:)25 b FJ(test)p FN(,)19 b FJ(body)p FN(,)h(and)f FJ(else_)p FN(.)24 b(\(If)c(the)f(natural)g(name)g(for)h(an)f(attrib)n (ute)h(is)g(also)h(a)f(Python)0 1491 y(reserv)o(ed)15 b(w)o(ord,)i(it)g(can')o(t)f(be)g(used)h(as)g(an)g(attrib)n(ute)f (name.)23 b(An)17 b(underscore)d(is)k(appended)c(to)j(the)f(w)o(ord)g (to)h(mak)o(e)f(it)i(a)f(le)o(gal)f(identi\002er)m(,)0 1591 y(hence)j FJ(else_)h FN(instead)g(of)g FJ(else)p FN(.\))0 1737 y(The)g FJ(if)g FN(statement)g(is)h(more)f(complicated)e (because)i(it)h(can)f(include)f(se)n(v)o(eral)g(tests.)236 1976 y FA(if_stmt:)44 b('if')g(test)g(':')g(suite)g(\('elif')g(test)g (':')g(suite\))2568 1989 y(*)2657 1976 y(['else')g(':')g(suite])0 2262 y FN(The)22 b FJ(If)g FN(node)f(only)h(de\002nes)g(tw)o(o)g (attrib)n(utes:)29 b FJ(tests)22 b FN(and)g FJ(else_)p FN(.)30 b(The)22 b FJ(tests)g FN(attrib)n(ute)g(is)h(a)f(sequence)f(of) h(test)h(e)o(xpression,)0 2362 y(consequent)18 b(body)g(pairs.)25 b(There)18 b(is)j(one)e(pair)g(for)g(each)g FJ(if)p FN(/)p FJ(elif)g FN(clause.)25 b(The)19 b(\002rst)i(element)e(of)g(the)h(pair) f(is)h(the)g(test)g(e)o(xpression.)0 2461 y(The)g(second)f(elements)h (is)h(a)g FJ(Stmt)f FN(node)f(that)h(contains)g(the)g(code)f(to)i(e)o (x)o(ecute)e(if)h(the)g(test)h(is)g(true.)0 2608 y(The)26 b FJ(getChildren\(\))e FN(method)h(of)h FJ(If)h FN(returns)e(a)i (\003at)g(list)g(of)f(child)g(nodes.)43 b(If)26 b(there)g(are)g(three)g FJ(if)p FN(/)p FJ(elif)g FN(clauses)g(and)g(no)0 2708 y FJ(else)e FN(clause,)h(then)f FJ(getChildren\(\))e FN(will)j(return)f(a)g(list)i(of)e(six)g(elements:)33 b(the)25 b(\002rst)g(test)g(e)o(xpression,)e(the)i(\002rst)g FJ(Stmt)p FN(,)g(the)0 2808 y(second)19 b(te)o(xt)h(e)o(xpression,)f (etc.)0 2954 y(The)24 b(follo)n(wing)f(table)h(lists)i(each)e(of)g(the) g FJ(Node)g FN(subclasses)h(de\002ned)e(in)i FJ(compiler.ast)d FN(and)i(each)g(of)g(the)g(public)g(attrib)n(utes)0 3054 y(a)n(v)n(ailable)30 b(on)g(their)g(instances.)54 b(The)30 b(v)n(alues)g(of)g(most)g(of)g(the)h(attrib)n(utes)f(are)g(themselv)o (es)f FJ(Node)h FN(instances)h(or)e(sequences)h(of)0 3154 y(instances.)36 b(When)24 b(the)g(v)n(alue)g(is)h(something)d (other)h(than)h(an)g(instance,)g(the)g(type)g(is)h(noted)e(in)h(the)g (comment.)35 b(The)24 b(attrib)n(utes)g(are)0 3253 y(listed)d(in)f(the) g(order)f(in)h(which)g(the)o(y)g(are)g(returned)e(by)i FJ(getChildren\(\))e FN(and)i FJ(getChildNodes\(\))p FN(.)536 3524 y FL(Node)h(type)339 b(Attrib)n(ute)267 b(V)-8 b(alue)p 487 3557 2927 4 v 487 3557 V 536 3627 a FJ(Add)548 b(left)398 b FN(left)20 b(operand)1234 3726 y FJ(right)348 b FN(right)19 b(operand)p 487 3759 V 487 3759 V 536 3829 a FJ(And)548 b(nodes)348 b FN(list)21 b(of)f(operands)p 487 3862 V 487 3862 V 536 3932 a FJ(AssAttr)946 b FK(attrib)n(ute)20 b(as)g(tar)m(g)o(et)g(of)h(assignment)1234 4032 y FJ(expr)398 b FN(e)o(xpression)18 b(on)i(the)g(left-hand)f(side) h(of)g(the)g(dot)1234 4131 y FJ(attrname)198 b FN(the)20 b(attrib)n(ute)g(name,)f(a)i(string)1234 4231 y FJ(flags)348 b FN(XXX)p 487 4264 V 487 4264 V 536 4334 a FJ(AssList)g(nodes)g FN(list)21 b(of)f(list)h(elements)f(being)f(assigned)h(to)p 487 4367 V 487 4367 V 536 4437 a FJ(AssName)348 b(name)398 b FN(name)19 b(being)g(assigned)h(to)1234 4536 y FJ(flags)348 b FN(XXX)p 487 4570 V 487 4570 V 536 4639 a FJ(AssTuple)298 b(nodes)348 b FN(list)21 b(of)f(tuple)g(elements)g(being)f(assigned)g (to)p 487 4673 V 487 4673 V 536 4742 a FJ(Assert)398 b(test)g FN(the)20 b(e)o(xpression)e(to)j(be)f(tested)1234 4842 y FJ(fail)398 b FN(the)20 b(v)n(alue)f(of)h(the)g FJ(AssertionError)p 487 4875 V 487 4875 V 536 4945 a(Assign)398 b(nodes)348 b FN(a)20 b(list)i(of)d(assignment)h(tar)o(gets,)f(one)h (per)g(equal)f(sign)1234 5045 y FJ(expr)398 b FN(the)20 b(v)n(alue)f(being)h(assigned)p 487 5078 V 487 5078 V 536 5148 a FJ(AugAssign)248 b(node)1234 5247 y(op)1234 5347 y(expr)p 487 5380 V 0 5549 3901 4 v 0 5649 a FI(31.3.)52 b(Python)24 b(Abstr)o(act)f(Syntax)2663 b(899)p eop end %%Page: 900 912 TeXDict begin 900 911 bop 536 70 a FL(Node)21 b(type)339 b(Attrib)n(ute)267 b(V)-8 b(alue)p 487 103 2927 4 v 487 103 V 487 103 V 536 173 a FJ(Backquote)248 b(expr)p 487 206 V 487 206 V 536 276 a(Bitand)398 b(nodes)p 487 309 V 487 309 V 536 379 a(Bitor)448 b(nodes)p 487 412 V 487 412 V 536 482 a(Bitxor)398 b(nodes)p 487 515 V 487 515 V 536 584 a(Break)p 487 618 V 487 618 V 536 687 a(CallFunc)298 b(node)398 b FN(e)o(xpression)18 b(for)i(the)g(callee)1234 787 y FJ(args)398 b FN(a)20 b(list)i(of)d(ar)o(guments)1234 887 y FJ(star_args)148 b FN(the)20 b(e)o(xtended)e(*-ar)o(g)g(v)n(alue) 1234 986 y FJ(dstar_args)98 b FN(the)20 b(e)o(xtended)e(**-ar)o(g)g(v)n (alue)p 487 1020 V 487 1020 V 536 1089 a FJ(Class)448 b(name)398 b FN(the)20 b(name)f(of)h(the)h(class,)f(a)h(string)1234 1189 y FJ(bases)348 b FN(a)20 b(list)i(of)d(base)i(classes)1234 1289 y FJ(doc)448 b FN(doc)19 b(string,)h(a)h(string)e(or)h FJ(None)1234 1388 y(code)398 b FN(the)20 b(body)f(of)h(the)g(class)h (statement)p 487 1421 V 487 1421 V 536 1491 a FJ(Compare)348 b(expr)1234 1591 y(ops)p 487 1624 V 487 1624 V 536 1694 a(Const)448 b(value)p 487 1727 V 487 1727 V 536 1797 a(Continue)p 487 1830 V 487 1830 V 536 1900 a(Decorators)198 b(nodes)348 b FN(List)21 b(of)e(function)g(decorator)f(e)o(xpressions)p 487 1933 V 487 1933 V 536 2002 a FJ(Dict)498 b(items)p 487 2036 V 487 2036 V 536 2105 a(Discard)348 b(expr)p 487 2139 V 487 2139 V 536 2208 a(Div)548 b(left)1234 2308 y(right)p 487 2341 V 487 2341 V 536 2411 a(Ellipsis)p 487 2444 V 487 2444 V 536 2514 a(Expression)198 b(node)536 2614 y(Exec)498 b(expr)1234 2713 y(locals)1234 2813 y(globals)p 487 2846 V 487 2846 V 536 2916 a(FloorDiv)298 b(left)1234 3015 y(right)p 487 3049 V 487 3049 V 536 3118 a(For)548 b(assign)1234 3218 y(list)1234 3318 y(body)1234 3417 y(else_)p 487 3450 V 487 3450 V 536 3520 a(From)498 b(modname)1234 3620 y(names)p 487 3653 V 487 3653 V 536 3723 a(Function)298 b(decorators)98 b(Decorators)19 b FN(or)g FJ(None)1234 3822 y(name)398 b FN(name)19 b(used)h(in)g(def,)g(a)h(string)1234 3922 y FJ(argnames)198 b FN(list)21 b(of)f(ar)o(gument)e(names,)h(as)i (strings)1234 4022 y FJ(defaults)198 b FN(list)21 b(of)f(def)o(ault)f (v)n(alues)1234 4121 y FJ(flags)348 b FN(xxx)1234 4221 y FJ(doc)448 b FN(doc)19 b(string,)h(a)h(string)e(or)h FJ(None)1234 4320 y(code)398 b FN(the)20 b(body)f(of)h(the)g(function)p 487 4354 V 487 4354 V 536 4423 a FJ(GenExpr)348 b(code)p 487 4457 V 487 4457 V 536 4526 a(GenExprFor)198 b(assign)1234 4626 y(iter)1234 4726 y(ifs)p 487 4759 V 487 4759 V 536 4829 a(GenExprIf)248 b(test)p 487 4862 V 487 4862 V 536 4932 a(GenExprInner)98 b(expr)1234 5031 y(quals)p 487 5064 V 487 5064 V 536 5134 a(Getattr)348 b(expr)1234 5234 y(attrname)p 487 5267 V 487 5267 V 536 5337 a(Global)398 b(names)p 487 5370 V 0 5549 3901 4 v 0 5649 a FI(900)2323 b(Chapter)23 b(31.)53 b(Python)23 b(compiler)h(pac)n(kage)p eop end %%Page: 901 913 TeXDict begin 901 912 bop 536 70 a FL(Node)21 b(type)339 b(Attrib)n(ute)267 b(V)-8 b(alue)p 487 103 2927 4 v 487 103 V 487 103 V 536 173 a FJ(If)598 b(tests)1234 272 y(else_)p 487 306 V 487 306 V 536 375 a(Import)398 b(names)p 487 408 V 487 408 V 536 478 a(Invert)g(expr)p 487 511 V 487 511 V 536 581 a(Keyword)348 b(name)1234 681 y(expr)p 487 714 V 487 714 V 536 784 a(Lambda)398 b(argnames)1234 883 y(defaults)1234 983 y(flags)1234 1083 y(code)p 487 1116 V 487 1116 V 536 1186 a(LeftShift)248 b(left)1234 1285 y(right)p 487 1318 V 487 1318 V 536 1388 a(List)498 b(nodes)p 487 1421 V 487 1421 V 536 1491 a(ListComp)298 b(expr)1234 1591 y(quals)p 487 1624 V 487 1624 V 536 1694 a(ListCompFor)148 b(assign)1234 1793 y(list)1234 1893 y(ifs)p 487 1926 V 487 1926 V 536 1996 a(ListCompIf)198 b(test)p 487 2029 V 487 2029 V 536 2099 a(Mod)548 b(left)1234 2198 y(right)p 487 2232 V 487 2232 V 536 2301 a(Module)398 b(doc)448 b FN(doc)19 b(string,)h(a)h(string)e(or)h FJ(None)1234 2401 y(node)398 b FN(body)18 b(of)i(the)h(module,)d(a)j FJ(Stmt)p 487 2434 V 487 2434 V 536 2504 a(Mul)548 b(left)1234 2604 y(right)p 487 2637 V 487 2637 V 536 2707 a(Name)498 b(name)p 487 2740 V 487 2740 V 536 2809 a(Not)548 b(expr)p 487 2843 V 487 2843 V 536 2912 a(Or)598 b(nodes)p 487 2946 V 487 2946 V 536 3015 a(Pass)p 487 3049 V 487 3049 V 536 3118 a(Power)448 b(left)1234 3218 y(right)p 487 3251 V 487 3251 V 536 3321 a(Print)g(nodes)1234 3421 y(dest)p 487 3454 V 487 3454 V 536 3523 a(Printnl)348 b(nodes)1234 3623 y(dest)p 487 3656 V 487 3656 V 536 3726 a(Raise)448 b(expr1)1234 3826 y(expr2)1234 3925 y(expr3)p 487 3958 V 487 3958 V 536 4028 a(Return)398 b(value)p 487 4061 V 487 4061 V 536 4131 a(RightShift)198 b(left)1234 4231 y(right)p 487 4264 V 487 4264 V 536 4334 a(Slice)448 b(expr)1234 4433 y(flags)1234 4533 y(lower)1234 4633 y(upper)p 487 4666 V 487 4666 V 536 4736 a(Sliceobj)298 b(nodes)348 b FN(list)21 b(of)f(statements)p 487 4769 V 487 4769 V 536 4839 a FJ(Stmt)498 b(nodes)p 487 4872 V 487 4872 V 536 4941 a(Sub)548 b(left)1234 5041 y(right)p 487 5074 V 487 5074 V 536 5144 a(Subscript)248 b(expr)1234 5244 y(flags)1234 5343 y(subs)p 487 5377 V 0 5549 3901 4 v 0 5649 a FI(31.3.)52 b(Python)24 b(Abstr)o(act)f(Syntax)2663 b(901)p eop end %%Page: 902 914 TeXDict begin 902 913 bop 536 70 a FL(Node)21 b(type)339 b(Attrib)n(ute)267 b(V)-8 b(alue)p 487 103 2927 4 v 487 103 V 487 103 V 536 173 a FJ(TryExcept)248 b(body)1234 272 y(handlers)1234 372 y(else_)p 487 405 V 487 405 V 536 475 a(TryFinally)198 b(body)1234 575 y(final)p 487 608 V 487 608 V 536 677 a(Tuple)448 b(nodes)p 487 711 V 487 711 V 536 780 a(UnaryAdd)298 b(expr)p 487 814 V 487 814 V 536 883 a(UnarySub)g(expr)p 487 917 V 487 917 V 536 986 a(While)448 b(test)1234 1086 y(body)1234 1186 y(else_)p 487 1219 V 487 1219 V 536 1289 a(With)498 b(expr)1234 1388 y(vars)1234 1488 y(body)p 487 1521 V 487 1521 V 536 1591 a(Yield)448 b(value)p 487 1624 V 487 1624 V 0 2155 a Fv(31.3.2)101 b(Assignment)29 b(nodes)0 2358 y FN(There)18 b(is)h(a)g(collection)f(of)g(nodes)g(used)h(to)f (represent)g(assignments.)24 b(Each)18 b(assignment)g(statement)g(in)h (the)g(source)f(code)f(becomes)h(a)0 2458 y(single)h FJ(Assign)g FN(node)f(in)i(the)f(AST)-6 b(.)20 b(The)f FJ(nodes)g FN(attrib)n(ute)f(is)j(a)f(list)g(that)f(contains)g(a)h (node)e(for)h(each)g(assignment)f(tar)o(get.)24 b(This)c(is)0 2557 y(necessary)h(because)h(assignment)f(can)h(be)g(chained,)g(e.g.)30 b FJ(a)50 b(=)f(b)h(=)g(2)p FN(.)31 b(Each)22 b FJ(Node)g FN(in)g(the)g(list)h(will)g(be)f(one)g(of)g(the)g(follo)n(wing)0 2657 y(classes:)k FJ(AssAttr)p FN(,)20 b FJ(AssList)p FN(,)f FJ(AssName)p FN(,)g(or)h FJ(AssTuple)p FN(.)0 2804 y(Each)i(tar)o(get)f(assignment)h(node)f(will)i(describe)f(the)g (kind)g(of)g(object)g(being)f(assigned)h(to:)30 b FJ(AssName)21 b FN(for)h(a)h(simple)f(name,)g(e.g.)31 b FJ(a)0 2904 y(=)50 b(1)p FN(.)42 b FJ(AssAttr)25 b FN(for)h(an)f(attrib)n(ute)h (assigned,)h(e.g.)41 b FJ(a.x)50 b(=)f(1)p FN(.)43 b FJ(AssList)25 b FN(and)g FJ(AssTuple)g FN(for)h(list)h(and)e(tuple)h(e) o(xpansion)0 3003 y(respecti)n(v)o(ely)-5 b(,)18 b(e.g.)25 b FJ(a,)49 b(b,)g(c)h(=)g(a_tuple)p FN(.)0 3150 y(The)19 b(tar)o(get)f(assignment)g(nodes)h(also)g(ha)n(v)o(e)g(a)g FJ(flags)g FN(attrib)n(ute)g(that)g(indicates)g(whether)f(the)i(node)e (is)i(being)e(used)h(for)f(assignment)0 3250 y(or)i(in)g(a)h(delete)f (statement.)25 b(The)19 b FJ(AssName)h FN(is)h(also)g(used)e(to)i (represent)e(a)h(delete)g(statement,)g(e.g.)25 b FJ(del)49 b(x)p FN(.)0 3397 y(When)29 b(an)g(e)o(xpression)e(contains)h(se)n(v)o (eral)h(attrib)n(ute)f(references,)i(an)f(assignment)f(or)h(delete)f (statement)h(will)h(contain)e(only)g(one)0 3496 y FJ(AssAttr)f FN(node)g(\226)h(for)f(the)h(\002nal)g(attrib)n(ute)f(reference.)46 b(The)28 b(other)f(attrib)n(ute)g(references)f(will)j(be)f(represented) e(as)i FJ(Getattr)0 3596 y FN(nodes)19 b(in)i(the)f FJ(expr)g FN(attrib)n(ute)g(of)g(the)g FJ(AssAttr)f FN(instance.)0 3881 y Fv(31.3.3)101 b(Examples)0 4084 y FN(This)22 b(section)h(sho)n (ws)f(se)n(v)o(eral)g(simple)g(e)o(xamples)f(of)h(ASTs)h(for)f(Python)f (source)h(code.)30 b(The)22 b(e)o(xamples)f(demonstrate)g(ho)n(w)h(to)g (use)0 4183 y(the)e FJ(parse\(\))g FN(function,)e(what)i(the)g(repr)g (of)g(an)g(AST)g(looks)g(lik)o(e,)g(and)g(ho)n(w)f(to)i(access)g (attrib)n(utes)f(of)g(an)g(AST)g(node.)0 4330 y(The)g(\002rst)h(module) e(de\002nes)h(a)g(single)g(function.)j(Assume)e(it)g(is)g(stored)e(in)i (`)p FO(/tmp/doub)o(lelib)m(.p)m(y)p FN('.)236 4568 y FA("""This)44 b(is)g(an)h(example)f(module.)236 4751 y(This)g(is)h(the)f(docstring.)236 4842 y(""")236 5025 y(def)h(double\(x\):)416 5116 y("Return)e(twice)h(the)h(argument")416 5208 y(return)e(x)819 5221 y(*)909 5208 y(2)p 0 5549 3901 4 v 0 5649 a FI(902)2323 b(Chapter)23 b(31.)53 b(Python)23 b(compiler)h(pac)n(kage)p eop end %%Page: 903 915 TeXDict begin 903 914 bop 0 83 a FN(In)21 b(the)h(interacti)n(v)o(e)f (interpreter)f(session)i(belo)n(w)-5 b(,)21 b(I)h(ha)n(v)o(e)f (reformatted)e(the)j(long)f(AST)h(reprs)g(for)f(readability)-5 b(.)28 b(The)21 b(AST)h(reprs)f(use)0 183 y(unquali\002ed)26 b(class)i(names.)47 b(If)27 b(you)g(w)o(ant)h(to)f(create)h(an)f (instance)g(from)g(a)h(repr)m(,)g(you)f(must)g(import)g(the)g(class)i (names)e(from)g(the)0 282 y FJ(compiler.ast)19 b FN(module.)236 520 y FA(>>>)45 b(import)e(compiler)236 612 y(>>>)i(mod)f(=)h (compiler.parseFile\("/tmp/doublelib.p)o(y"\))236 703 y(>>>)g(mod)236 794 y(Module\('This)e(is)i(an)f(example)g (module.\\n\\nThis)e(is)i(the)h(docstring.\\n',)550 886 y(Stmt\([Function\(None,)d('double',)h(['x'],)h([],)g(0,)1223 977 y('Return)f(twice)h(the)g(argument',)1223 1068 y (Stmt\([Return\(Mul\(\(Name\('x'\),)c(Const\(2\)\)\)\)]\)\)]\)\))236 1160 y(>>>)45 b(from)f(compiler.ast)f(import)1536 1173 y(*)236 1251 y(>>>)i(Module\('This)d(is)j(an)f(example)g (module.\\n\\nThis)e(is)j(the)f(docstring.\\n',)236 1342 y(...)179 b(Stmt\([Function\(None,)42 b('double',)h(['x'],)h([],)g(0,) 236 1434 y(...)852 b('Return)43 b(twice)h(the)g(argument',)236 1525 y(...)852 b(Stmt\([Return\(Mul\(\(Name\('x'\),)40 b(Const\(2\)\)\)\)]\)\)]\)\))236 1616 y(Module\('This)j(is)i(an)f (example)g(module.\\n\\nThis)e(is)i(the)h(docstring.\\n',)550 1708 y(Stmt\([Function\(None,)d('double',)h(['x'],)h([],)g(0,)1223 1799 y('Return)f(twice)h(the)g(argument',)1223 1890 y (Stmt\([Return\(Mul\(\(Name\('x'\),)c(Const\(2\)\)\)\)]\)\)]\)\))236 1982 y(>>>)45 b(mod.doc)236 2073 y('This)f(is)h(an)f(example)g (module.\\n\\nThis)e(is)j(the)f(docstring.\\n')236 2164 y(>>>)h(for)f(node)g(in)h(mod.node.nodes:)236 2256 y(...)224 b(print)44 b(node)236 2347 y(...)236 2438 y(Function\(None,)f ('double',)g(['x'],)h([],)g(0,)h('Return)e(twice)h(the)h(argument',)640 2530 y(Stmt\([Return\(Mul\(\(Name\('x'\),)40 b(Const\(2\)\)\)\)]\)\)) 236 2621 y(>>>)45 b(func)f(=)g(mod.node.nodes[0])236 2712 y(>>>)h(func.code)236 2804 y(Stmt\([Return\(Mul\(\(Name\('x'\),)40 b(Const\(2\)\)\)\)]\))0 3252 y FE(31.4)121 b(Using)34 b(Visitors)e(to)i(W)-5 b(alk)33 b(ASTs)0 3485 y FN(The)19 b(visitor)g(pattern)g(is)i(...)j(The)19 b FJ(compiler)g FN(package)f(uses)i(a)g(v)n(ariant)f(on)g(the)g(visitor)g(pattern)g (that)h(tak)o(es)g(adv)n(antage)d(of)i(Python')-5 b(s)0 3585 y(introspection)18 b(features)i(to)g(eliminate)g(the)g(need)g(for) f(much)g(of)h(the)h(visitor')-5 b(s)20 b(infrastructure.)0 3732 y(The)g(classes)i(being)d(visited)i(do)f(not)g(need)g(to)h(be)f (programmed)e(to)i(accept)g(visitors.)26 b(The)21 b(visitor)f(need)g (only)f(de\002ne)h(visit)i(methods)0 3831 y(for)e(classes)h(it)g(is)g (speci\002cally)f(interested)f(in;)i(a)f(def)o(ault)g(visit)h(method)d (can)i(handle)g(the)g(rest.)0 3978 y(XXX)h(The)e(magic)h FJ(visit\(\))g FN(method)e(for)i(visitors.)0 4125 y FD(walk)p FJ(\()p FK(tr)m(ee)o(,)g(visitor)r FC([)p FK(,)g(verbose)12 b FC(])p FJ(\))0 4272 y FL(class)21 b FD(ASTVisitor)p FJ(\(\))208 4371 y FN(The)j FJ(ASTVisitor)g FN(is)i(responsible)e(for)h (w)o(alking)f(o)o(v)o(er)g(the)h(tree)h(in)f(the)g(correct)f(order)-5 b(.)39 b(A)26 b(w)o(alk)f(be)o(gins)g(with)g(a)h(call)f(to)208 4471 y FJ(preorder\(\))p FN(.)38 b(F)o(or)25 b(each)f(node,)h(it)h (checks)f(the)g FK(visitor)i FN(ar)o(gument)c(to)i FJ(preorder\(\))f FN(for)h(a)g(method)f(named)g(`visitN-)208 4571 y(odeT)-7 b(ype,)h(')21 b(where)h(NodeT)-7 b(ype)21 b(is)j(the)f(name)f(of)g(the) h(node')-5 b(s)22 b(class,)i(e.g.)33 b(for)22 b(a)h FJ(While)f FN(node)g(a)h FJ(visitWhile\(\))e FN(w)o(ould)208 4670 y(be)f(called.)k(If)c(the)h(method)e(e)o(xists,)h(it)h(is)g(called)f (with)g(the)h(node)e(as)i(its)g(\002rst)g(ar)o(gument.)208 4803 y(The)28 b(visitor)g(method)f(for)h(a)h(particular)e(node)g(type)h (can)g(control)f(ho)n(w)h(child)g(nodes)g(are)g(visited)h(during)e(the) h(w)o(alk.)50 b(The)208 4903 y FJ(ASTVisitor)18 b FN(modi\002es)h(the)h (visitor)f(ar)o(gument)e(by)j(adding)e(a)i(visit)g(method)e(to)i(the)g (visitor;)g(this)g(method)e(can)h(be)h(used)f(to)208 5002 y(visit)h(a)h(particular)d(child)i(node.)k(If)c(no)f(visitor)h(is) h(found)d(for)i(a)g(particular)f(node)g(type,)g(the)h FJ(default\(\))f FN(method)g(is)i(called.)0 5149 y FJ(ASTVisitor)e FN(objects)h(ha)n(v)o(e)f(the)i(follo)n(wing)d(methods:)0 5296 y(XXX)j(describe)e(e)o(xtra)g(ar)o(guments)p 0 5549 3901 4 v 0 5649 a FI(31.4.)52 b(Using)24 b(Visitors)f(to)g(W)m(alk)g (ASTs)2496 b(903)p eop end %%Page: 904 916 TeXDict begin 904 915 bop 0 83 a FD(default)p FJ(\()p FK(node)p FC([)p FK(,)17 b(...)12 b FC(])p FJ(\))0 230 y FD(dispatch)p FJ(\()p FK(node)p FC([)p FK(,)17 b(...)12 b FC(])p FJ(\))0 377 y FD(preorder)p FJ(\()p FK(tr)m(ee)o(,)19 b(visitor)r FJ(\))0 704 y FE(31.5)121 b(Bytecode)35 b(Gener)o(ation)0 937 y FN(The)24 b(code)g(generator)e(is)j(a)g(visitor)f(that)h(emits)f (bytecodes.)36 b(Each)24 b(visit)h(method)e(can)h(call)h(the)f FJ(emit\(\))g FN(method)f(to)i(emit)f(a)h(ne)n(w)0 1037 y(bytecode.)43 b(The)27 b(basic)g(code)f(generator)f(is)i(specialized)g (for)f(modules,)h(classes,)i(and)e(functions.)43 b(An)27 b(assembler)f(con)m(v)o(erts)f(that)0 1136 y(emitted)20 b(instructions)f(to)i(the)f(lo)n(w-le)n(v)o(el)g(bytecode)e(format.)25 b(It)c(handles)e(things)h(lik)o(e)h(generator)d(of)i(constant)g(lists)i (of)e(code)g(objects)0 1236 y(and)g(calculation)f(of)h(jump)f(of)n (fsets.)p 0 5549 3901 4 v 0 5649 a FI(904)2323 b(Chapter)23 b(31.)53 b(Python)23 b(compiler)h(pac)n(kage)p eop end %%Page: 905 917 TeXDict begin 905 916 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3194 427 y FG(THIR)n(TYTW)n(O)p 0 515 V 1895 978 a FT(Abstr)n(act)58 b(Syntax)g(T)-25 b(rees)0 1466 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.) 0 1613 y(The)28 b FJ(_ast)g FN(module)e(helps)i(Python)f(applications)g (to)h(process)g(trees)g(of)g(the)g(Python)f(abstract)h(syntax)g (grammar)-5 b(.)47 b(The)28 b(Python)0 1713 y(compiler)17 b(currently)g(pro)o(vides)g(read-only)g(access)i(to)g(such)f(trees,)h (meaning)f(that)g(applications)g(can)g(only)g(create)h(a)g(tree)g(for)f (a)h(gi)n(v)o(en)0 1812 y(piece)25 b(of)f(Python)g(source)g(code;)i (generating)d(byte)i(code)f(from)g(a)h(\(potentially)e(modi\002ed\))g (tree)i(is)h(not)e(supported.)37 b(The)25 b(abstract)0 1912 y(syntax)20 b(itself)i(might)e(change)g(with)h(each)g(Python)f (release;)h(this)h(module)e(helps)g(to)i(\002nd)e(out)h (programmatically)d(what)j(the)g(current)0 2012 y(grammar)d(looks)i (lik)o(e.)0 2158 y(An)30 b(abstract)g(syntax)g(tree)g(can)g(be)h (generated)d(by)i(passing)g FJ(_ast.PyCF_ONLY_AST)d FN(as)k(a)g(\003ag) g(to)f(the)g FJ(compile)g FN(b)n(uiltin)0 2258 y(function.)23 b(The)d(result)g(will)h(be)f(a)h(tree)f(of)g(objects)g(whose)g(classes) h(all)g(inherit)f(from)f FJ(_ast.AST)p FN(.)0 2405 y(The)30 b(actual)g(classes)i(are)e(deri)n(v)o(ed)f(from)g(the)h FJ(Parser/Python.asdl)e FN(\002le,)33 b(which)d(is)h(reproduced)d(belo) n(w)-5 b(.)54 b(There)30 b(is)h(one)0 2505 y(class)21 b(de\002ned)e(for)g(each)h(left-hand)e(side)j(symbol)e(in)h(the)g (abstract)g(grammar)e(\(for)h(e)o(xample,)g FJ(_ast.stmt)g FN(or)g FJ(_ast.expr)p FN(\).)24 b(In)0 2604 y(addition,)f(there)g(is)i (one)e(class)i(de\002ned)d(for)h(each)h(constructor)d(on)j(the)f (right-hand)f(side;)j(these)f(classes)h(inherit)e(from)g(the)g(classes) 0 2704 y(for)31 b(the)h(left-hand)f(side)h(trees.)60 b(F)o(or)32 b(e)o(xample,)h FJ(_ast.BinOp)e FN(inherits)h(from)e FJ(_ast.expr)p FN(.)60 b(F)o(or)31 b(production)e(rules)j(with)0 2803 y(alternati)n(v)o(es)27 b(\(aka)g(\224sums\224\),)i(the)f (left-hand)e(side)i(class)h(is)g(abstract:)40 b(only)27 b(instances)h(of)g(speci\002c)g(constructor)e(nodes)h(are)g(e)n(v)o(er) 0 2903 y(created.)0 3050 y(Each)20 b(concrete)f(class)i(has)f(an)g (attrib)n(ute)g FJ(_fields)g FN(which)f(gi)n(v)o(es)h(the)g(names)g(of) g(all)h(child)f(nodes.)0 3197 y(Each)26 b(instance)g(of)g(a)h(concrete) f(class)h(has)g(one)f(attrib)n(ute)g(for)g(each)g(child)g(node,)h(of)f (the)g(type)g(as)i(de\002ned)d(in)i(the)f(grammar)-5 b(.)43 b(F)o(or)0 3296 y(e)o(xample,)24 b FJ(_ast.BinOp)f FN(instances)h(ha)n(v)o(e)g(an)g(attrib)n(ute)g FJ(left)g FN(of)g(type)g FJ(_ast.expr)p FN(.)36 b(Instances)24 b(of)g FJ(_ast.expr)g FN(and)f FJ(_-)0 3396 y(ast.stmt)29 b FN(subclasses)i(also)f(ha)n(v)o(e)f(lineno)g(and)h(col)p 1650 3396 25 4 v 29 w(of)n(fset)g(attrib)n(utes.)54 b(The)30 b(lineno)f(is)i(the)f(line)g(number)e(of)i(source)f(te)o(xt)h(\(1)0 3496 y(inde)o(x)o(ed)16 b(so)j(the)f(\002rst)h(line)f(is)i(line)e(1\))g (and)g(the)g(col)p 1455 3496 V 29 w(of)n(fset)g(is)h(the)g(utf8)e(byte) h(of)n(fset)g(of)g(the)g(\002rst)h(tok)o(en)e(that)i(generated)d(the)j (node.)k(The)0 3595 y(utf8)d(of)n(fset)f(is)i(recorded)e(because)g(the) h(parser)g(uses)h(utf8)e(internally)-5 b(.)0 3742 y(If)25 b(these)h(attrib)n(utes)f(are)h(mark)o(ed)e(as)i(optional)e(in)i(the)f (grammar)f(\(using)h(a)h(question)e(mark\),)h(the)h(v)n(alue)e(might)h (be)h FJ(None)p FN(.)40 b(If)26 b(the)0 3842 y(attrib)n(utes)20 b(can)g(ha)n(v)o(e)g(zero-or)n(-more)d(v)n(alues)j(\(mark)o(ed)e(with)i (an)h(asterisk\),)e(the)i(v)n(alues)e(are)h(represented)f(as)i(Python)e (lists.)0 4169 y FE(32.1)121 b(Abstr)o(act)34 b(Gr)o(ammar)0 4402 y FN(The)28 b(module)f(de\002nes)h(a)g(string)g(constant)g FJ(__version__)e FN(which)i(is)h(the)f(decimal)g(sub)o(v)o(ersion)e(re) n(vision)h(number)g(of)h(the)g(\002le)0 4502 y(sho)n(wn)19 b(belo)n(w)-5 b(.)0 4648 y(The)20 b(abstract)g(grammar)e(is)j (currently)e(de\002ned)g(as)i(follo)n(ws:)236 4837 y FA(--)45 b(ASDL's)f(five)g(builtin)f(types)h(are)h(identifier,)e(int,)h (string,)f(object,)h(bool)236 5020 y(module)g(Python)g(version)g ("$Revision:)f(43614)g($")236 5111 y({)236 5202 y(mod)i(=)f (Module\(stmt)1000 5215 y(*)1088 5202 y(body\))416 5293 y(|)g(Interactive\(stmt)1225 5306 y(*)1312 5293 y(body\))416 5385 y(|)g(Expression\(expr)f(body\))p 0 5549 3901 4 v 3762 5649 a FI(905)p eop end %%Page: 906 918 TeXDict begin 906 917 bop 416 174 a FA(--)44 b(not)g(really)g(an)h (actual)f(node)g(but)g(useful)g(in)g(Jython's)g(typesystem.)416 266 y(|)g(Suite\(stmt)955 279 y(*)1043 266 y(body\))236 448 y(stmt)g(=)h(FunctionDef\(identifier)c(name,)j(arguments)f(args,) 1447 540 y(stmt)1627 553 y(*)1716 540 y(body,)h(expr)2165 553 y(*)2254 540 y(decorators\))505 631 y(|)h(ClassDef\(identifier)d (name,)i(expr)1941 644 y(*)2029 631 y(bases,)g(stmt)2523 644 y(*)2612 631 y(body\))505 722 y(|)h(Return\(expr?)e(value\))505 905 y(|)i(Delete\(expr)1090 918 y(*)1178 905 y(targets\))505 996 y(|)g(Assign\(expr)1090 1009 y(*)1178 996 y(targets,)e(expr)h (value\))505 1088 y(|)h(AugAssign\(expr)d(target,)i(operator)f(op,)i (expr)f(value\))505 1270 y(--)h(not)f(sure)g(if)h(bool)f(is)g(allowed,) g(can)g(always)g(use)g(int)595 1362 y(|)h(Print\(expr?)e(dest,)h(expr) 1672 1375 y(*)1761 1362 y(values,)f(bool)h(nl\))505 1544 y(--)h(use)f('orelse')g(because)f(else)h(is)h(a)f(keyword)g(in)h (target)e(languages)505 1636 y(|)i(For\(expr)e(target,)h(expr)g(iter,)g (stmt)2030 1649 y(*)2119 1636 y(body,)g(stmt)2568 1649 y(*)2657 1636 y(orelse\))505 1727 y(|)h(While\(expr)e(test,)h(stmt)1537 1740 y(*)1626 1727 y(body,)g(stmt)2075 1740 y(*)2164 1727 y(orelse\))505 1818 y(|)h(If\(expr)f(test,)g(stmt)1403 1831 y(*)1492 1818 y(body,)g(stmt)1941 1831 y(*)2029 1818 y(orelse\))505 1910 y(|)h(With\(expr)e(context_expr,)g(expr?)h (optional_vars,)e(stmt)2792 1923 y(*)2881 1910 y(body\))505 2092 y(--)j('type')f(is)g(a)h(bad)f(name)505 2183 y(|)h(Raise\(expr?)e (type,)h(expr?)g(inst,)g(expr?)g(tback\))505 2275 y(|)h (TryExcept\(stmt)1225 2288 y(*)1312 2275 y(body,)f(excepthandler)2166 2288 y(*)2254 2275 y(handlers,)f(stmt)2882 2288 y(*)2971 2275 y(orelse\))505 2366 y(|)i(TryFinally\(stmt)1270 2379 y(*)1357 2366 y(body,)f(stmt)1806 2379 y(*)1895 2366 y(finalbody\))505 2457 y(|)h(Assert\(expr)e(test,)h(expr?)g(msg\)) 505 2640 y(|)h(Import\(alias)1135 2653 y(*)1223 2640 y(names\))505 2731 y(|)g(ImportFrom\(identifier)c(module,)j(alias)2165 2744 y(*)2254 2731 y(names,)f(int?)i(level\))505 2914 y(--)g(Doesn't)e(capture)h(requirement)f(that)h(locals)g(must)g(be)505 3005 y(--)h(defined)e(if)i(globals)f(is)505 3097 y(--)h(still)f (supports)f(use)i(as)f(a)h(function!)505 3188 y(|)g(Exec\(expr)e(body,) h(expr?)g(globals,)g(expr?)g(locals\))505 3371 y(|)h (Global\(identifier)1360 3384 y(*)1447 3371 y(names\))505 3462 y(|)g(Expr\(expr)e(value\))505 3553 y(|)i(Pass)f(|)h(Break)f(|)g (Continue)505 3736 y(--)h(XXX)f(Jython)g(will)g(be)h(different)505 3827 y(--)g(col_offset)e(is)h(the)h(byte)f(offset)g(in)g(the)g(utf8)h (string)e(the)i(parser)f(uses)505 3919 y(attributes)f(\(int)i(lineno,)e (int)i(col_offset\))505 4101 y(--)g(BoolOp\(\))e(can)i(use)f(left)g(&)h (right?)236 4193 y(expr)f(=)h(BoolOp\(boolop)e(op,)h(expr)1537 4206 y(*)1626 4193 y(values\))460 4284 y(|)h(BinOp\(expr)e(left,)h (operator)g(op,)g(expr)g(right\))460 4375 y(|)h(UnaryOp\(unaryop)d(op,) j(expr)f(operand\))460 4467 y(|)h(Lambda\(arguments)d(args,)i(expr)g (body\))460 4558 y(|)h(IfExp\(expr)e(test,)h(expr)g(body,)g(expr)g (orelse\))460 4649 y(|)h(Dict\(expr)955 4662 y(*)1043 4649 y(keys,)f(expr)1492 4662 y(*)1581 4649 y(values\))460 4741 y(|)h(ListComp\(expr)e(elt,)h(comprehension)1987 4754 y(*)2074 4741 y(generators\))460 4832 y(|)h(GeneratorExp\(expr)d (elt,)i(comprehension)2166 4845 y(*)2254 4832 y(generators\))460 4923 y(--)h(the)f(grammar)g(constrains)f(where)h(yield)g(expressions)f (can)h(occur)460 5015 y(|)h(Yield\(expr?)e(value\))460 5106 y(--)i(need)f(sequences)f(for)i(compare)e(to)i(distinguish)e (between)460 5197 y(--)i(x)g(<)f(4)h(<)g(3)f(and)h(\(x)f(<)h(4\))f(<)h (3)460 5289 y(|)g(Compare\(expr)e(left,)h(cmpop)1627 5302 y(*)1716 5289 y(ops,)g(expr)2120 5302 y(*)2209 5289 y(comparators\))460 5380 y(|)h(Call\(expr)e(func,)h(expr)1447 5393 y(*)1536 5380 y(args,)g(keyword)2120 5393 y(*)2209 5380 y(keywords,)p 0 5549 3901 4 v 0 5649 a FI(906)2471 b(Chapter)23 b(32.)52 b(Abstr)o(act)23 b(Syntax)g(T)-10 b(rees)p eop end %%Page: 907 919 TeXDict begin 907 918 bop 281 83 a FA(expr?)44 b(starargs,)f(expr?)h (kwargs\))460 174 y(|)h(Repr\(expr)e(value\))460 266 y(|)i(Num\(object)e(n\))i(--)f(a)h(number)f(as)g(a)h(PyObject.)460 357 y(|)g(Str\(string)e(s\))i(--)f(need)g(to)h(specify)e(raw,)i (unicode,)e(etc?)460 448 y(--)i(other)f(literals?)f(bools?)460 631 y(--)i(the)f(following)g(expression)f(can)h(appear)g(in)g (assignment)f(context)460 722 y(|)i(Attribute\(expr)e(value,)g (identifier)g(attr,)h(expr_context)f(ctx\))460 814 y(|)i (Subscript\(expr)e(value,)g(slice)h(slice,)g(expr_context)f(ctx\))460 905 y(|)i(Name\(identifier)d(id,)j(expr_context)d(ctx\))460 996 y(|)j(List\(expr)955 1009 y(*)1043 996 y(elts,)f(expr_context)f (ctx\))460 1088 y(|)i(Tuple\(expr)1043 1101 y(*)1088 1088 y(elts,)f(expr_context)f(ctx\))505 1270 y(--)i(col_offset)e(is)h (the)h(byte)f(offset)g(in)g(the)g(utf8)h(string)e(the)i(parser)f(uses) 505 1362 y(attributes)f(\(int)i(lineno,)e(int)i(col_offset\))236 1544 y(expr_context)e(=)i(Load)f(|)h(Store)f(|)g(Del)h(|)f(AugLoad)g(|) g(AugStore)g(|)h(Param)236 1727 y(slice)f(=)h(Ellipsis)e(|)i (Slice\(expr?)e(lower,)h(expr?)g(upper,)g(expr?)g(step\))505 1818 y(|)h(ExtSlice\(slice)1225 1831 y(*)1312 1818 y(dims\))505 1910 y(|)g(Index\(expr)e(value\))236 2092 y(boolop)h(=)h(And)f(|)h(Or) 236 2275 y(operator)f(=)g(Add)h(|)f(Sub)h(|)f(Mult)h(|)f(Div)h(|)f(Mod) g(|)h(Pow)f(|)h(LShift)998 2366 y(|)g(RShift)f(|)h(BitOr)f(|)g(BitXor)g (|)h(BitAnd)e(|)i(FloorDiv)236 2549 y(unaryop)f(=)h(Invert)e(|)i(Not)f (|)h(UAdd)f(|)h(USub)236 2731 y(cmpop)f(=)h(Eq)f(|)h(NotEq)f(|)h(Lt)f (|)h(LtE)f(|)h(Gt)f(|)h(GtE)f(|)h(Is)f(|)h(IsNot)f(|)h(In)f(|)h(NotIn) 236 2914 y(comprehension)e(=)i(\(expr)f(target,)f(expr)h(iter,)g(expr) 2254 2927 y(*)2343 2914 y(ifs\))236 3097 y(--)h(not)f(sure)g(what)g(to) h(call)f(the)g(first)g(argument)g(for)g(raise)g(and)g(except)236 3188 y(--)h(TODO\(jhylton\):)d(Figure)i(out)g(if)h(there)f(is)g(a)h (better)f(way)g(to)h(handle)236 3279 y(--)717 b(lineno)44 b(and)g(col_offset)f(fields,)h(particularly)f(when)595 3371 y(--)717 b(ast)44 b(is)h(exposed)e(to)i(Python.)236 3462 y(excepthandler)e(=)i(\(expr?)e(type,)h(expr?)g(name,)g(stmt)2254 3475 y(*)2343 3462 y(body,)g(int)h(lineno,)998 3553 y(int)g (col_offset\))236 3736 y(arguments)f(=)g(\(expr)999 3749 y(*)1088 3736 y(args,)g(identifier?)f(vararg,)460 3827 y(identifier?)g(kwarg,)h(expr)1492 3840 y(*)1581 3827 y(defaults\))595 4010 y(--)g(keyword)g(arguments)f(supplied)h(to)g (call)595 4101 y(keyword)g(=)g(\(identifier)f(arg,)h(expr)g(value\))595 4284 y(--)g(import)g(name)g(with)h(optional)e('as')h(alias.)595 4375 y(alias)g(=)h(\(identifier)e(name,)h(identifier?)e(asname\))236 4467 y(})p 0 5549 3901 4 v 0 5649 a FI(32.1.)52 b(Abstr)o(act)23 b(Gr)o(ammar)2849 b(907)p eop end %%Page: 908 920 TeXDict begin 908 919 bop 0 5549 3901 4 v 0 5649 a FI(908)p eop end %%Page: 909 921 TeXDict begin 909 920 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3066 427 y FG(THIR)n(TYTHREE)p 0 515 V 1736 978 a FT(Miscellaneous)57 b(Ser)6 b(vices)0 1457 y FN(The)20 b(modules)f(described)f(in)j(this)f (chapter)f(pro)o(vide)f(miscellaneous)h(services)h(that)g(are)g(a)n(v)n (ailable)g(in)g(all)h(Python)d(v)o(ersions.)24 b(Here')-5 b(s)0 1556 y(an)20 b(o)o(v)o(ervie)n(w:)50 1702 y FD(formatter)98 b FN(Generic)19 b(output)g(formatter)g(and)h(de)n(vice)f(interf)o(ace.) 0 2031 y FE(33.1)121 b Fx(formatter)31 b FE(\227)i(Gener)r(ic)g(output) j(f)l(or)s(matting)0 2263 y FN(This)24 b(module)d(supports)i(tw)o(o)g (interf)o(ace)g(de\002nitions,)g(each)g(with)g(multiple)g (implementations.)33 b(The)23 b FK(formatter)g FN(interf)o(ace)g(is)h (used)0 2363 y(by)c(the)g FJ(HTMLParser)f FN(class)i(of)f(the)g FJ(htmllib)g FN(module,)e(and)i(the)g FK(writer)i FN(interf)o(ace)d(is) i(required)e(by)g(the)i(formatter)d(interf)o(ace.)0 2510 y(F)o(ormatter)e(objects)i(transform)e(an)h(abstract)h(\003o)n(w)g(of)f (formatting)f(e)n(v)o(ents)h(into)g(speci\002c)h(output)e(e)n(v)o(ents) h(on)g(writer)h(objects.)24 b(F)o(ormat-)0 2610 y(ters)e(manage)f(se)n (v)o(eral)h(stack)g(structures)f(to)h(allo)n(w)g(v)n(arious)f (properties)g(of)h(a)g(writer)g(object)g(to)g(be)g(changed)e(and)h (restored;)h(writers)0 2709 y(need)e(not)h(be)g(able)g(to)h(handle)e (relati)n(v)o(e)g(changes)g(nor)h(an)o(y)f(sort)h(of)g(\223change)f (back\224)g(operation.)26 b(Speci\002c)21 b(writer)g(properties)f (which)0 2809 y(may)26 b(be)g(controlled)e(via)j(formatter)d(objects)i (are)h(horizontal)d(alignment,)i(font,)h(and)f(left)g(mar)o(gin)f (indentations.)41 b(A)27 b(mechanism)0 2908 y(is)d(pro)o(vided)c(which) i(supports)g(pro)o(viding)e(arbitrary)-5 b(,)22 b(non-e)o(xclusi)n(v)o (e)d(style)k(settings)h(to)f(a)g(writer)g(as)g(well.)34 b(Additional)21 b(interf)o(aces)0 3008 y(f)o(acilitate)f(formatting)f (e)n(v)o(ents)g(which)h(are)g(not)g(re)n(v)o(ersible,)e(such)i(as)h (paragraph)d(separation.)0 3155 y(Writer)k(objects)g(encapsulate)e(de)n (vice)h(interf)o(aces.)29 b(Abstract)22 b(de)n(vices,)f(such)h(as)g (\002le)h(formats,)e(are)h(supported)d(as)k(well)f(as)h(physical)0 3255 y(de)n(vices.)h(The)c(pro)o(vided)d(implementations)h(all)j(w)o (ork)e(with)h(abstract)f(de)n(vices.)25 b(The)19 b(interf)o(ace)g(mak)o (es)h(a)n(v)n(ailable)f(mechanisms)g(for)0 3354 y(setting)h(the)g (properties)f(which)h(formatter)e(objects)i(manage)f(and)h(inserting)f (data)h(into)g(the)h(output.)0 3639 y Fv(33.1.1)101 b(The)28 b(F)m(or)r(matter)h(Interf)m(ace)0 3842 y FN(Interf)o(aces)15 b(to)i(create)f(formatters)f(are)h(dependent)f(on)h(the)g(speci\002c)g (formatter)f(class)j(being)d(instantiated.)23 b(The)16 b(interf)o(aces)g(described)0 3942 y(belo)n(w)k(are)g(the)g(required)e (interf)o(aces)i(which)g(all)g(formatters)f(must)i(support)d(once)i (initialized.)0 4088 y(One)g(data)g(element)g(is)h(de\002ned)e(at)i (the)f(module)f(le)n(v)o(el:)0 4235 y FD(AS_IS)208 4335 y FN(V)-9 b(alue)26 b(which)h(can)g(be)h(used)f(in)g(the)g(font)g (speci\002cation)f(passed)i(to)f(the)g FJ(push_font\(\))f FN(method)g(described)g(belo)n(w)-5 b(,)28 b(or)208 4435 y(as)23 b(the)h(ne)n(w)f(v)n(alue)f(to)h(an)o(y)g(other)f FJ(push_)p FK(pr)l(operty)p FJ(\(\))f FN(method.)33 b(Pushing)22 b(the)h FJ(AS_IS)g FN(v)n(alue)f(allo)n(ws)i(the)f(corresponding)208 4534 y FJ(pop_)p FK(pr)l(operty)p FJ(\(\))18 b FN(method)h(to)i(be)f (called)g(without)f(ha)n(ving)g(to)i(track)e(whether)g(the)i(property)d (w)o(as)j(changed.)0 4681 y(The)f(follo)n(wing)e(attrib)n(utes)j(are)f (de\002ned)f(for)g(formatter)g(instance)h(objects:)0 4828 y FD(writer)208 4928 y FN(The)f(writer)h(instance)g(with)h(which)e (the)h(formatter)f(interacts.)0 5074 y FD(end_paragraph)p FJ(\()p FK(blanklines)p FJ(\))208 5174 y FN(Close)h(an)o(y)g(open)f (paragraphs)f(and)i(insert)g(at)h(least)f FK(blanklines)f FN(before)g(the)h(ne)o(xt)g(paragraph.)0 5321 y FD(add_line_break)p FJ(\(\))p 0 5549 3901 4 v 3762 5649 a FI(909)p eop end %%Page: 910 922 TeXDict begin 910 921 bop 208 83 a FN(Add)19 b(a)i(hard)e(line)h(break) g(if)g(one)g(does)g(not)g(already)f(e)o(xist.)25 b(This)20 b(does)g(not)g(break)f(the)h(logical)g(paragraph.)0 230 y FD(add_hor_rule)p FJ(\()p FK(*ar)m(gs,)d(**kw)p FJ(\))208 330 y FN(Insert)23 b(a)h(horizontal)e(rule)h(in)h(the)g(output.)34 b(A)24 b(hard)f(break)f(is)j(inserted)e(if)h(there)f(is)i(data)e(in)h (the)g(current)e(paragraph,)g(b)n(ut)i(the)208 429 y(logical)i (paragraph)f(is)j(not)f(brok)o(en.)44 b(The)27 b(ar)o(guments)f(and)g (k)o(e)o(yw)o(ords)g(are)h(passed)g(on)g(to)g(the)h(writer')-5 b(s)27 b FJ(send_line_-)208 529 y(break\(\))19 b FN(method.)0 676 y FD(add_flowing_data)p FJ(\()p FK(data)p FJ(\))208 775 y FN(Pro)o(vide)g(data)h(which)g(should)f(be)h(formatted)f(with)i (collapsed)e(whitespace.)25 b(Whitespace)20 b(from)g(preceding)e(and)i (successi)n(v)o(e)208 875 y(calls)j(to)g FJ(add_flowing_data\(\))e FN(is)j(considered)d(as)i(well)h(when)e(the)h(whitespace)g(collapse)f (is)i(performed.)31 b(The)23 b(data)208 975 y(which)29 b(is)h(passed)g(to)g(this)g(method)f(is)h(e)o(xpected)e(to)i(be)g(w)o (ord-wrapped)d(by)i(the)h(output)e(de)n(vice.)53 b(Note)30 b(that)g(an)o(y)f(w)o(ord-)208 1074 y(wrapping)18 b(still)j(must)f(be)h (performed)c(by)j(the)g(writer)g(object)g(due)f(to)i(the)f(need)f(to)i (rely)f(on)f(de)n(vice)h(and)f(font)h(information.)0 1221 y FD(add_literal_data)p FJ(\()p FK(data)p FJ(\))208 1321 y FN(Pro)o(vide)15 b(data)h(which)h(should)e(be)i(passed)g(to)g (the)f(writer)h(unchanged.)k(Whitespace,)c(including)e(ne)n(wline)h (and)g(tab)h(characters,)208 1420 y(are)j(considered)e(le)o(gal)i(in)g (the)g(v)n(alue)g(of)g FK(data)p FN(.)0 1567 y FD(add_label_data)p FJ(\()p FK(format,)d(counter)r FJ(\))208 1667 y FN(Insert)j(a)h(label)g (which)f(should)g(be)g(placed)g(to)h(the)g(left)g(of)f(the)h(current)e (left)i(mar)o(gin.)k(This)c(should)e(be)i(used)f(for)h(constructing)208 1766 y(b)n(ulleted)g(or)g(numbered)e(lists.)31 b(If)21 b(the)h FK(format)h FN(v)n(alue)e(is)i(a)f(string,)f(it)h(is)h (interpreted)d(as)i(a)g(format)f(speci\002cation)g(for)g FK(counter)r FN(,)208 1866 y(which)e(should)f(be)h(an)h(inte)o(ger)-5 b(.)24 b(The)19 b(result)h(of)f(this)h(formatting)d(becomes)i(the)g(v)n (alue)g(of)g(the)h(label;)g(if)f FK(format)i FN(is)g(not)e(a)h(string) 208 1966 y(it)27 b(is)h(used)e(as)i(the)f(label)g(v)n(alue)f(directly) -5 b(.)43 b(The)27 b(label)g(v)n(alue)f(is)i(passed)e(as)i(the)f(only)f (ar)o(gument)e(to)j(the)g(writer')-5 b(s)27 b FJ(send_-)208 2065 y(label_data\(\))18 b FN(method.)24 b(Interpretation)17 b(of)j(non-string)e(label)i(v)n(alues)g(is)h(dependent)d(on)i(the)g (associated)g(writer)-5 b(.)208 2198 y(F)o(ormat)20 b(speci\002cations) h(are)g(strings)g(which,)f(in)i(combination)c(with)k(a)f(counter)f(v)n (alue,)g(are)h(used)g(to)h(compute)d(label)i(v)n(alues.)208 2298 y(Each)27 b(character)g(in)i(the)f(format)f(string)h(is)h(copied)f (to)g(the)g(label)g(v)n(alue,)i(with)e(some)g(characters)g(recognized)e (to)i(indicate)208 2397 y(a)f(transform)e(on)i(the)g(counter)f(v)n (alue.)44 b(Speci\002cally)-5 b(,)28 b(the)f(character)f(`)p FJ(1)p FN(')g(represents)g(the)i(counter)d(v)n(alue)h(formatter)g(as)i (an)208 2497 y(Arabic)18 b(number)m(,)e(the)j(characters)f(`)p FJ(A)p FN(')g(and)g(`)p FJ(a)p FN(')h(represent)e(alphabetic)h (representations)f(of)h(the)h(counter)e(v)n(alue)h(in)h(upper)e(and)208 2597 y(lo)n(wer)25 b(case,)j(respecti)n(v)o(ely)-5 b(,)25 b(and)g(`)p FJ(I)p FN(')h(and)g(`)p FJ(i)p FN(')f(represent)g(the)h (counter)f(v)n(alue)g(in)h(Roman)g(numerals,)g(in)g(upper)f(and)g(lo)n (wer)208 2696 y(case.)g(Note)20 b(that)g(the)h(alphabetic)e(and)g (roman)g(transforms)g(require)g(that)h(the)g(counter)f(v)n(alue)g(be)i (greater)e(than)h(zero.)0 2843 y FD(flush_softspace)p FJ(\(\))208 2943 y FN(Send)15 b(an)o(y)f(pending)g(whitespace)h(b)n(uf) n(fered)e(from)i(a)h(pre)n(vious)e(call)i(to)g FJ(add_flowing_data\(\)) c FN(to)k(the)f(associated)h(writer)208 3042 y(object.)24 b(This)c(should)f(be)i(called)f(before)e(an)o(y)i(direct)g (manipulation)e(of)h(the)i(writer)f(object.)0 3189 y FD(push_alignment)p FJ(\()p FK(align)p FJ(\))208 3289 y FN(Push)27 b(a)h(ne)n(w)f(alignment)f(setting)i(onto)f(the)g (alignment)f(stack.)47 b(This)28 b(may)f(be)g FJ(AS_IS)h FN(if)f(no)g(change)g(is)h(desired.)46 b(If)28 b(the)208 3388 y(alignment)20 b(v)n(alue)h(is)h(changed)e(from)g(the)i(pre)n (vious)e(setting,)h(the)h(writer')-5 b(s)21 b FJ(new_alignment\(\))f FN(method)g(is)i(called)f(with)208 3488 y(the)f FK(align)f FN(v)n(alue.)0 3635 y FD(pop_alignment)p FJ(\(\))208 3735 y FN(Restore)h(the)g(pre)n(vious)f(alignment.)0 3881 y FD(push_font)p FJ(\()p Fn(\()p FK(size)o(,)g(italic,)h(bold,)f (teletype)p Fn(\))p FJ(\))208 3981 y FN(Change)24 b(some)i(or)f(all)i (font)e(properties)f(of)h(the)h(writer)f(object.)41 b(Properties)25 b(which)g(are)h(not)f(set)i(to)e FJ(AS_IS)h FN(are)f(set)i(to)f(the)208 4081 y(v)n(alues)g(passed)h(in)g(while)g(others)g(are)g(maintained)e (at)j(their)e(current)g(settings.)46 b(The)26 b(writer')-5 b(s)27 b FJ(new_font\(\))f FN(method)g(is)208 4180 y(called)20 b(with)g(the)g(fully)g(resolv)o(ed)f(font)g(speci\002cation.)0 4327 y FD(pop_font)p FJ(\(\))208 4427 y FN(Restore)h(the)g(pre)n(vious) f(font.)0 4574 y FD(push_margin)p FJ(\()p FK(mar)m(gin)p FJ(\))208 4673 y FN(Increase)e(the)i(number)e(of)h(left)h(mar)o(gin)e (indentations)g(by)h(one,)g(associating)g(the)h(logical)f(tag)g FK(mar)m(gin)g FN(with)h(the)g(ne)n(w)f(indenta-)208 4773 y(tion.)24 b(The)c(initial)g(mar)o(gin)e(le)n(v)o(el)h(is)i FJ(0)p FN(.)k(Changed)18 b(v)n(alues)i(of)f(the)h(logical)f(tag)h(must) g(be)g(true)f(v)n(alues;)h(f)o(alse)g(v)n(alues)f(other)g(than)208 4873 y FJ(AS_IS)g FN(are)i(not)e(suf)n(\002cient)h(to)g(change)f(the)h (mar)o(gin.)0 5019 y FD(pop_margin)p FJ(\(\))208 5119 y FN(Restore)g(the)g(pre)n(vious)f(mar)o(gin.)0 5266 y FD(push_style)p FJ(\()p FK(*styles)p FJ(\))208 5366 y FN(Push)k(an)o(y)f(number)g(of)h(arbitrary)f(style)h (speci\002cations.)34 b(All)24 b(styles)g(are)f(pushed)f(onto)h(the)g (styles)h(stack)f(in)h(order)-5 b(.)33 b(A)24 b(tuple)p 0 5549 3901 4 v 0 5649 a FI(910)2407 b(Chapter)23 b(33.)52 b(Miscellaneous)24 b(Ser)r(vices)p eop end %%Page: 911 923 TeXDict begin 911 922 bop 208 83 a FN(representing)18 b(the)i(entire)g(stack,)g(including)e FJ(AS_IS)i FN(v)n(alues,)g(is)h (passed)f(to)g(the)g(writer')-5 b(s)21 b FJ(new_styles\(\))d FN(method.)0 230 y FD(pop_style)p FJ(\()p FC([)p FK(n)47 b Fn(=)j(1)12 b FC(])p FJ(\))208 330 y FN(Pop)19 b(the)h(last)h FK(n)f FN(style)g(speci\002cations)f(passed)h(to)g FJ(push_style\(\))p FN(.)j(A)d(tuple)g(representing)e(the)h(re)n(vised)h(stack,)f (including)208 429 y FJ(AS_IS)g FN(v)n(alues,)h(is)h(passed)f(to)g(the) h(writer')-5 b(s)20 b FJ(new_styles\(\))f FN(method.)0 576 y FD(set_spacing)p FJ(\()p FK(spacing)p FJ(\))208 676 y FN(Set)h(the)h(spacing)e(style)i(for)e(the)h(writer)-5 b(.)0 823 y FD(assert_line_data)p FJ(\()p FC([)p FK(\003a)o(g)45 b Fn(=)50 b(1)12 b FC(])p FJ(\))208 922 y FN(Inform)h(the)j(formatter)e (that)h(data)g(has)h(been)f(added)f(to)i(the)f(current)f(paragraph)f (out-of-band.)20 b(This)c(should)e(be)i(used)f(when)g(the)208 1022 y(writer)21 b(has)h(been)e(manipulated)g(directly)-5 b(.)28 b(The)21 b(optional)f FK(\003a)o(g)h FN(ar)o(gument)e(can)i(be)h (set)g(to)g(f)o(alse)g(if)g(the)f(writer)h(manipulations)208 1121 y(produced)17 b(a)k(hard)e(line)h(break)g(at)g(the)g(end)g(of)g (the)g(output.)0 1406 y Fv(33.1.2)101 b(F)m(or)r(matter)29 b(Implementations)0 1609 y FN(T)-7 b(w)o(o)17 b(implementations)e(of)i (formatter)e(objects)i(are)g(pro)o(vided)d(by)j(this)g(module.)23 b(Most)17 b(applications)f(may)g(use)h(one)g(of)f(these)h(classes)0 1709 y(without)i(modi\002cation)g(or)h(subclassing.)0 1856 y FL(class)h FD(NullFormatter)p FJ(\()p FC([)p FK(writer)14 b FC(])p FJ(\))208 1955 y FN(A)23 b(formatter)f(which)h(does)g (nothing.)32 b(If)23 b FK(writer)k FN(is)d(omitted,)f(a)h FJ(NullWriter)e FN(instance)h(is)h(created.)33 b(No)23 b(methods)g(of)g(the)208 2055 y(writer)c(are)g(called)h(by)f FJ(NullFormatter)e FN(instances.)25 b(Implementations)17 b(should)i(inherit)f(from)h(this)h(class)g(if)g(implement-)208 2155 y(ing)f(a)i(writer)f(interf)o(ace)f(b)n(ut)i(don')o(t)d(need)i(to) g(inherit)f(an)o(y)h(implementation.)0 2301 y FL(class)h FD(AbstractFormatter)p FJ(\()p FK(writer)r FJ(\))208 2401 y FN(The)g(standard)f(formatter)-5 b(.)27 b(This)21 b(implementation)e(has)j(demonstrated)d(wide)i(applicability)f(to)i (man)o(y)e(writers,)h(and)g(may)g(be)208 2501 y(used)e(directly)h(in)g (most)g(circumstances.)k(It)d(has)f(been)g(used)g(to)g(implement)f(a)h (full-featured)e(W)-7 b(orld)20 b(W)m(ide)h(W)-7 b(eb)21 b(bro)n(wser)-5 b(.)0 2786 y Fv(33.1.3)101 b(The)28 b(Wr)q(iter)h (Interf)m(ace)0 2988 y FN(Interf)o(aces)16 b(to)g(create)h(writers)f (are)h(dependent)d(on)i(the)h(speci\002c)g(writer)f(class)i(being)d (instantiated.)24 b(The)16 b(interf)o(aces)g(described)f(belo)n(w)0 3088 y(are)23 b(the)f(required)f(interf)o(aces)h(which)g(all)h(writers) g(must)f(support)g(once)f(initialized.)32 b(Note)23 b(that)f(while)h (most)g(applications)e(can)h(use)0 3188 y(the)e FJ(AbstractFormatter)e FN(class)j(as)g(a)f(formatter)m(,)f(the)h(writer)g(must)g(typically)f (be)h(pro)o(vided)e(by)i(the)g(application.)0 3335 y FD(flush)p FJ(\(\))208 3434 y FN(Flush)g(an)o(y)f(b)n(uf)n(fered)f (output)h(or)h(de)n(vice)g(control)f(e)n(v)o(ents.)0 3581 y FD(new_alignment)p FJ(\()p FK(align)p FJ(\))208 3681 y FN(Set)31 b(the)h(alignment)e(style.)58 b(The)31 b FK(align)f FN(v)n(alue)h(can)g(be)g(an)o(y)g(object,)i(b)n(ut)e(by)g (con)m(v)o(ention)d(is)k(a)g(string)f(or)g FJ(None)p FN(,)i(where)208 3780 y FJ(None)19 b FN(indicates)h(that)g(the)g (writer')-5 b(s)20 b(\223preferred\224)d(alignment)i(should)f(be)i (used.)25 b(Con)m(v)o(entional)17 b FK(align)i FN(v)n(alues)h(are)f FJ('left')p FN(,)208 3880 y FJ('center')p FN(,)g FJ('right')p FN(,)g(and)g FJ('justify')p FN(.)0 4027 y FD(new_font)p FJ(\()p FK(font)q FJ(\))208 4126 y FN(Set)24 b(the)g(font)g(style.)36 b(The)24 b(v)n(alue)f(of)h FK(font)h FN(will)g(be)f FJ(None)p FN(,)h(indicating)d(that)i(the)g(de)n(vice')-5 b(s)24 b(def)o(ault)f(font)g(should)g(be)h(used,)h(or)208 4226 y(a)e(tuple)f(of)h(the)g(form)f FJ(\()p FK(size)p FN(,)i FK(italic)p FN(,)g FK(bold)r FN(,)e FK(teletype)p FJ(\))p FN(.)33 b(Size)23 b(will)h(be)f(a)g(string)g(indicating)e(the)i(size)h (of)f(font)f(that)h(should)f(be)208 4326 y(used;)i(speci\002c)g (strings)f(and)g(their)f(interpretation)g(must)h(be)g(de\002ned)f(by)h (the)g(application.)33 b(The)23 b FK(italic)p FN(,)h FK(bold)r FN(,)f(and)g FK(teletype)208 4425 y FN(v)n(alues)c(are)h (Boolean)g(v)n(alues)g(specifying)e(which)i(of)g(those)g(font)f(attrib) n(utes)i(should)e(be)h(used.)0 4572 y FD(new_margin)p FJ(\()p FK(mar)m(gin,)d(le)o(vel)p FJ(\))208 4672 y FN(Set)23 b(the)g(mar)o(gin)e(le)n(v)o(el)i(to)g(the)g(inte)o(ger)f FK(le)o(vel)h FN(and)f(the)h(logical)g(tag)g(to)g FK(mar)m(gin)p FN(.)33 b(Interpretation)20 b(of)j(the)g(logical)f(tag)h(is)h(at)g(the) 208 4771 y(writer')-5 b(s)21 b(discretion;)h(the)g(only)f(restriction)g (on)g(the)h(v)n(alue)f(of)g(the)h(logical)f(tag)h(is)h(that)f(it)g(not) g(be)f(a)i(f)o(alse)f(v)n(alue)f(for)g(non-zero)208 4871 y(v)n(alues)e(of)h FK(le)o(vel)p FN(.)0 5018 y FD(new_spacing)p FJ(\()p FK(spacing)p FJ(\))208 5118 y FN(Set)g(the)h(spacing)e(style)i (to)f FK(spacing)p FN(.)0 5264 y FD(new_styles)p FJ(\()p FK(styles)p FJ(\))208 5364 y FN(Set)k(additional)f(styles.)38 b(The)24 b FK(styles)h FN(v)n(alue)f(is)h(a)g(tuple)f(of)g(arbitrary)e (v)n(alues;)k(the)f(v)n(alue)e FJ(AS_IS)h FN(should)f(be)i(ignored.)35 b(The)p 0 5549 3901 4 v 0 5649 a FI(33.1.)52 b FJ(formatter)22 b FI(\227)h(Gener)q(ic)g(output)h(f)n(or)r(matting)2011 b(911)p eop end %%Page: 912 924 TeXDict begin 912 923 bop 208 83 a FK(styles)20 b FN(tuple)g(may)f(be)g (interpreted)f(either)h(as)i(a)f(set)g(or)g(as)g(a)g(stack)g(depending) d(on)i(the)h(requirements)e(of)h(the)h(application)e(and)208 183 y(writer)i(implementation.)0 330 y FD(send_line_break)p FJ(\(\))208 429 y FN(Break)g(the)g(current)f(line.)0 576 y FD(send_paragraph)p FJ(\()p FK(blankline)p FJ(\))208 676 y FN(Produce)i(a)i(paragraph)c(separation)j(of)g(at)h(least)g FK(blankline)e FN(blank)h(lines,)h(or)f(the)g(equi)n(v)n(alent.)30 b(The)23 b FK(blankline)e FN(v)n(alue)g(will)j(be)208 775 y(an)c(inte)o(ger)-5 b(.)25 b(Note)20 b(that)h(the)f (implementation)e(will)k(recei)n(v)o(e)d(a)i(call)g(to)f FJ(send_line_break\(\))e FN(before)h(this)i(call)g(if)g(a)f(line)208 875 y(break)g(is)j(needed;)e(this)i(method)d(should)h(not)h(include)e (ending)h(the)h(last)g(line)g(of)g(the)g(paragraph.)27 b(It)22 b(is)h(only)e(responsible)f(for)208 975 y(v)o(ertical)f (spacing)g(between)h(paragraphs.)0 1121 y FD(send_hor_rule)p FJ(\()p FK(*ar)m(gs,)d(**kw)p FJ(\))208 1221 y FN(Display)30 b(a)h(horizontal)d(rule)i(on)g(the)h(output)e(de)n(vice.)55 b(The)30 b(ar)o(guments)e(to)j(this)g(method)e(are)h(entirely)g (application-)e(and)208 1321 y(writer)n(-speci\002c,)21 b(and)h(should)f(be)h(interpreted)f(with)h(care.)31 b(The)22 b(method)f(implementation)f(may)h(assume)h(that)h(a)f(line)h(break)208 1420 y(has)d(already)f(been)h(issued)g(via)g FJ(send_line_break\(\))p FN(.)0 1567 y FD(send_flowing_data)p FJ(\()p FK(data)p FJ(\))208 1667 y FN(Output)j(character)h(data)g(which)g(may)g(be)g(w)o (ord-wrapped)e(and)i(re-\003o)n(wed)f(as)i(needed.)37 b(W)m(ithin)24 b(an)o(y)g(sequence)f(of)h(calls)h(to)208 1766 y(this)d(method,)g(the)g(writer)h(may)e(assume)i(that)f(spans)h (of)f(multiple)g(whitespace)g(characters)f(ha)n(v)o(e)h(been)g (collapsed)f(to)i(single)208 1866 y(space)d(characters.)0 2013 y FD(send_literal_data)p FJ(\()p FK(data)p FJ(\))208 2113 y FN(Output)26 b(character)h(data)g(which)g(has)h(already)e(been)h (formatted)f(for)h(display)-5 b(.)46 b(Generally)-5 b(,)28 b(this)g(should)e(be)i(interpreted)d(to)208 2212 y(mean)g(that)i(line)g (breaks)f(indicated)f(by)h(ne)n(wline)g(characters)g(should)f(be)i (preserv)o(ed)d(and)i(no)g(ne)n(w)h(line)f(breaks)g(should)g(be)208 2312 y(introduced.)33 b(The)23 b(data)h(may)f(contain)g(embedded)e(ne)n (wline)i(and)g(tab)h(characters,)g(unlik)o(e)f(data)g(pro)o(vided)e(to) j(the)g FJ(send_-)208 2411 y(formatted_data\(\))17 b FN(interf)o(ace.)0 2558 y FD(send_label_data)p FJ(\()p FK(data)p FJ(\))208 2658 y FN(Set)23 b FK(data)e FN(to)i(the)g(left)f (of)g(the)h(current)e(left)i(mar)o(gin,)e(if)i(possible.)31 b(The)22 b(v)n(alue)g(of)h FK(data)e FN(is)j(not)e(restricted;)h (treatment)f(of)g(non-)208 2758 y(string)f(v)n(alues)h(is)h(entirely)e (application-)f(and)i(writer)n(-dependent.)27 b(This)22 b(method)f(will)i(only)e(be)h(called)g(at)g(the)g(be)o(ginning)e(of)208 2857 y(a)g(line.)0 3142 y Fv(33.1.4)101 b(Wr)q(iter)28 b(Implementations)0 3345 y FN(Three)20 b(implementations)e(of)i(the)h (writer)f(object)g(interf)o(ace)f(are)i(pro)o(vided)c(as)22 b(e)o(xamples)d(by)h(this)h(module.)j(Most)d(applications)e(will)0 3445 y(need)h(to)g(deri)n(v)o(e)f(ne)n(w)h(writer)g(classes)h(from)e (the)h FJ(NullWriter)f FN(class.)0 3591 y FL(class)i FD(NullWriter)p FJ(\(\))208 3691 y FN(A)h(writer)g(which)f(only)g(pro)o (vides)g(the)h(interf)o(ace)f(de\002nition;)h(no)f(actions)h(are)g(tak) o(en)f(on)h(an)o(y)f(methods.)29 b(This)23 b(should)e(be)h(the)208 3791 y(base)e(class)h(for)f(all)g(writers)h(which)e(do)h(not)g(need)f (to)i(inherit)e(an)o(y)h(implementation)e(methods.)0 3938 y FL(class)j FD(AbstractWriter)p FJ(\(\))208 4037 y FN(A)i(writer)f(which)h(can)f(be)h(used)g(in)f(deb)n(ugging)f (formatters,)h(b)n(ut)g(not)h(much)f(else.)33 b(Each)22 b(method)g(simply)g(announces)f(itself)208 4137 y(by)e(printing)g(its)i (name)f(and)f(ar)o(guments)g(on)g(standard)g(output.)0 4284 y FL(class)i FD(DumbWriter)p FJ(\()p FC([)p FK(\002le)p FC([)p FK(,)c(maxcol)49 b Fn(=)h(72)12 b FC(])g(])p FJ(\))208 4383 y FN(Simple)k(writer)h(class)g(which)f(writes)i(output)d(on)h(the) h(\002le)g(object)f(passed)h(in)g(as)g FK(\002le)g FN(or)m(,)g(if)g FK(\002le)f FN(is)i(omitted,)e(on)h(standard)e(output.)208 4483 y(The)25 b(output)f(is)i(simply)f(w)o(ord-wrapped)e(to)i(the)h (number)d(of)j(columns)e(speci\002ed)h(by)g FK(maxcol)p FN(.)40 b(This)26 b(class)g(is)h(suitable)e(for)208 4583 y(re\003o)n(wing)18 b(a)j(sequence)e(of)h(paragraphs.)p 0 5549 3901 4 v 0 5649 a FI(912)2407 b(Chapter)23 b(33.)52 b(Miscellaneous)24 b(Ser)r(vices)p eop end %%Page: 913 925 TeXDict begin 913 924 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3132 427 y FG(THIR)n(TYFOUR)p 0 515 V 1449 978 a FT(SGI)57 b(IRIX)h(Speci\002c)g(Ser)6 b(vices)0 1465 y FN(The)24 b(modules)f(described)g(in)h(this)h(chapter)e(pro)o(vide)f(interf)o (aces)i(to)g(features)f(that)i(are)f(unique)f(to)h(SGI')-5 b(s)25 b(IRIX)f(operating)e(system)0 1565 y(\(v)o(ersions)d(4)h(and)g (5\).)50 1705 y FD(al)348 b FN(Audio)19 b(functions)g(on)h(the)g(SGI.) 50 1804 y FD(AL)348 b FN(Constants)20 b(used)g(with)h(the)f FJ(al)g FN(module.)50 1904 y FD(cd)348 b FN(Interf)o(ace)19 b(to)h(the)h(CD-R)m(OM)f(on)g(Silicon)g(Graphics)f(systems.)50 2004 y FD(fl)348 b FN(FORMS)21 b(library)e(for)h(applications)f(with)h (graphical)f(user)h(interf)o(aces.)50 2103 y FD(FL)348 b FN(Constants)20 b(used)g(with)h(the)f FJ(fl)g FN(module.)50 2203 y FD(flp)298 b FN(Functions)19 b(for)h(loading)f(stored)g(FORMS)j (designs.)50 2302 y FD(fm)348 b FK(F)-9 b(ont)20 b(Mana)o(g)o(er)f FN(interf)o(ace)h(for)f(SGI)i(w)o(orkstations.)50 2402 y FD(gl)348 b FN(Functions)19 b(from)h(the)g(Silicon)g(Graphics)f FK(Gr)o(aphics)h(Libr)o(ary)p FN(.)50 2502 y FD(DEVICE)148 b FN(Constants)20 b(used)g(with)h(the)f FJ(gl)g FN(module.)50 2601 y FD(GL)348 b FN(Constants)20 b(used)g(with)h(the)f FJ(gl)g FN(module.)50 2701 y FD(imgfile)98 b FN(Support)19 b(for)g(SGI)i(imglib)e(\002les.)50 2801 y FD(jpeg)248 b FN(Read)20 b(and)g(write)g(image)g(\002les)h(in)g(compressed)d(JPEG)j (format.)0 3105 y FE(34.1)121 b Fx(al)33 b FE(\227)g(A)l(udio)h (functions)h(on)f(the)g(SGI)0 3338 y FN(This)25 b(module)f(pro)o(vides) g(access)i(to)f(the)h(audio)e(f)o(acilities)i(of)f(the)g(SGI)h(Indy)e (and)h(Indigo)e(w)o(orkstations.)39 b(See)26 b(section)f(3A)h(of)f(the) 0 3437 y(IRIX)c(man)g(pages)f(for)h(details.)27 b(Y)-9 b(ou')o(ll)21 b(need)f(to)h(read)g(those)f(man)h(pages)g(to)g (understand)e(what)i(these)g(functions)e(do!)27 b(Some)21 b(of)g(the)0 3537 y(functions)g(are)h(not)g(a)n(v)n(ailable)g(in)h (IRIX)f(releases)h(before)e(4.0.5.)30 b(Again,)22 b(see)h(the)f(manual) f(to)i(check)f(whether)f(a)i(speci\002c)f(function)0 3637 y(is)f(a)n(v)n(ailable)f(on)g(your)f(platform.)0 3783 y(All)i(functions)e(and)g(methods)g(de\002ned)h(in)g(this)h (module)d(are)j(equi)n(v)n(alent)d(to)i(the)h(C)g(functions)d(with)j(`) p FJ(AL)p FN(')f(pre\002x)o(ed)e(to)i(their)g(name.)0 3930 y(Symbolic)f(constants)h(from)f(the)h(C)h(header)e(\002le)i FJ(<audio.h>)e FN(are)h(de\002ned)g(in)g(the)g(standard)f(module)g FJ(AL)p FN(,)h(see)h(belo)n(w)-5 b(.)0 4077 y FL(W)g(ar)o(ning:)28 b FN(The)23 b(current)e(v)o(ersion)g(of)h(the)g(audio)g(library)f(may)h (dump)f(core)h(when)g(bad)g(ar)o(gument)e(v)n(alues)i(are)g(passed)g (rather)g(than)0 4177 y(returning)i(an)i(error)f(status.)44 b(Unfortunately)-5 b(,)24 b(since)i(the)h(precise)e(circumstances)h (under)e(which)i(this)h(may)e(happen)g(are)h(undocu-)0 4276 y(mented)17 b(and)h(hard)g(to)g(check,)g(the)h(Python)e(interf)o (ace)g(can)i(pro)o(vide)d(no)i(protection)f(against)g(this)i(kind)f(of) g(problems.)23 b(\(One)18 b(e)o(xample)0 4376 y(is)j(specifying)e(an)h (e)o(xcessi)n(v)o(e)f(queue)g(size)i(\227)g(there)f(is)h(no)e (documented)f(upper)h(limit.\))0 4523 y(The)h(module)f(de\002nes)h(the) g(follo)n(wing)e(functions:)0 4670 y FD(openport)p FJ(\()p FK(name)o(,)g(dir)m(ection)p FC([)p FK(,)h(con\002g)12 b FC(])p FJ(\))208 4769 y FN(The)k(name)g(and)g(direction)f(ar)o (guments)f(are)j(strings.)23 b(The)17 b(optional)e FK(con\002g)g FN(ar)o(gument)f(is)j(a)g(con\002guration)d(object)i(as)h(returned)208 4869 y(by)f FJ(newconfig\(\))p FN(.)23 b(The)16 b(return)g(v)n(alue)h (is)h(an)f FK(audio)f(port)h(object)p FN(;)h(methods)e(of)g(audio)h (port)f(objects)h(are)g(described)f(belo)n(w)-5 b(.)0 5016 y FD(newconfig)p FJ(\(\))208 5116 y FN(The)29 b(return)g(v)n(alue) h(is)h(a)f(ne)n(w)g FK(audio)f(con\002gur)o(ation)e(object)p FN(;)34 b(methods)c(of)f(audio)h(con\002guration)d(objects)j(are)g (described)208 5215 y(belo)n(w)-5 b(.)0 5362 y FD(queryparams)p FJ(\()p FK(de)o(vice)p FJ(\))p 0 5549 3901 4 v 3762 5649 a FI(913)p eop end %%Page: 914 926 TeXDict begin 914 925 bop 208 83 a FN(The)34 b(de)n(vice)h(ar)o(gument) d(is)37 b(an)e(inte)o(ger)-5 b(.)69 b(The)35 b(return)f(v)n(alue)g(is)i (a)g(list)g(of)f(inte)o(gers)f(containing)f(the)j(data)f(returned)e(by) 208 183 y FJ(ALqueryparams\(\))p FN(.)0 330 y FD(getparams)p FJ(\()p FK(de)o(vice)o(,)18 b(list)q FJ(\))208 429 y FN(The)29 b FK(de)o(vice)g FN(ar)o(gument)e(is)k(an)e(inte)o(ger)-5 b(.)53 b(The)29 b(list)i(ar)o(gument)c(is)j(a)g(list)h(such)e(as)i (returned)d(by)h FJ(queryparams\(\))p FN(;)j(it)f(is)208 529 y(modi\002ed)19 b(in)h(place)g(\(!\).)0 676 y FD(setparams)p FJ(\()p FK(de)o(vice)o(,)e(list)q FJ(\))208 775 y FN(The)h FK(de)o(vice)h FN(ar)o(gument)e(is)j(an)f(inte)o(ger)-5 b(.)24 b(The)c FK(list)j FN(ar)o(gument)18 b(is)j(a)f(list)i(such)e(as) h(returned)d(by)i FJ(queryparams\(\))p FN(.)0 1060 y Fv(34.1.1)101 b(Con\002gur)o(ation)30 b(Objects)0 1263 y FN(Con\002guration)18 b(objects)i(returned)e(by)i FJ(newconfig\(\))f FN(ha)n(v)o(e)g(the)i(follo)n(wing)d(methods:)0 1410 y FD(getqueuesize)p FJ(\(\))208 1510 y FN(Return)h(the)i(queue)e(size.) 0 1656 y FD(setqueuesize)p FJ(\()p FK(size)p FJ(\))208 1756 y FN(Set)h(the)h(queue)e(size.)0 1903 y FD(getwidth)p FJ(\(\))208 2003 y FN(Get)h(the)g(sample)g(width.)0 2149 y FD(setwidth)p FJ(\()p FK(width)p FJ(\))208 2249 y FN(Set)g(the)h (sample)f(width.)0 2396 y FD(getchannels)p FJ(\(\))208 2496 y FN(Get)g(the)g(channel)f(count.)0 2642 y FD(setchannels)p FJ(\()p FK(nc)o(hannels)p FJ(\))208 2742 y FN(Set)h(the)h(channel)e (count.)0 2889 y FD(getsampfmt)p FJ(\(\))208 2989 y FN(Get)h(the)g (sample)g(format.)0 3135 y FD(setsampfmt)p FJ(\()p FK(sampfmt)q FJ(\))208 3235 y FN(Set)g(the)h(sample)f(format.)0 3382 y FD(getfloatmax)p FJ(\(\))208 3482 y FN(Get)g(the)g(maximum)f(v)n (alue)g(for)h(\003oating)f(sample)h(formats.)0 3628 y FD(setfloatmax)p FJ(\()p FK(\003oatmax)p FJ(\))208 3728 y FN(Set)g(the)h(maximum)d(v)n(alue)i(for)f(\003oating)h(sample)g (formats.)0 4013 y Fv(34.1.2)101 b(P)-5 b(or)t(t)28 b(Objects)0 4216 y FN(Port)20 b(objects,)g(as)h(returned)d(by)i FJ(openport\(\))p FN(,)f(ha)n(v)o(e)g(the)h(follo)n(wing)f(methods:)0 4363 y FD(closeport)p FJ(\(\))208 4462 y FN(Close)h(the)h(port.)0 4609 y FD(getfd)p FJ(\(\))208 4709 y FN(Return)e(the)i(\002le)f (descriptor)f(as)i(an)f(int.)0 4856 y FD(getfilled)p FJ(\(\))208 4955 y FN(Return)f(the)i(number)d(of)i(\002lled)g(samples.) 0 5102 y FD(getfillable)p FJ(\(\))208 5202 y FN(Return)f(the)i(number)d (of)i(\002llable)g(samples.)0 5349 y FD(readsamps)p FJ(\()p FK(nsamples)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(914)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 915 927 TeXDict begin 915 926 bop 208 83 a FN(Read)20 b(a)g(number)f(of)g (samples)i(from)e(the)h(queue,)e(blocking)h(if)h(necessary)-5 b(.)24 b(Return)19 b(the)h(data)g(as)h(a)g(string)f(containing)e(the)i (ra)o(w)208 183 y(data,)f(\(e.g.,)g(2)g(bytes)h(per)f(sample)h(in)f (big-endian)f(byte)h(order)f(\(high)h(byte,)g(lo)n(w)h(byte\))f(if)h (you)e(ha)n(v)o(e)h(set)i(the)f(sample)f(width)g(to)208 282 y(2)h(bytes\).)0 429 y FD(writesamps)p FJ(\()p FK(samples)p FJ(\))208 529 y FN(Write)45 b(samples)h(into)e(the)i(queue,)k(blocking) 43 b(if)i(necessary)-5 b(.)99 b(The)45 b(samples)g(are)g(encoded)e(as)j (described)e(for)h(the)208 628 y FJ(readsamps\(\))18 b FN(return)h(v)n(alue.)0 775 y FD(getfillpoint)p FJ(\(\))208 875 y FN(Return)g(the)i(`\002ll)f(point'.)0 1022 y FD(setfillpoint)p FJ(\()p FK(\002llpoint)q FJ(\))208 1121 y FN(Set)g(the)h(`\002ll)f (point'.)0 1268 y FD(getconfig)p FJ(\(\))208 1368 y FN(Return)f(a)i (con\002guration)c(object)j(containing)e(the)j(current)d (con\002guration)g(of)i(the)g(port.)0 1515 y FD(setconfig)p FJ(\()p FK(con\002g)p FJ(\))208 1614 y FN(Set)g(the)h(con\002guration)c (from)i(the)h(ar)o(gument,)e(a)j(con\002guration)c(object.)0 1761 y FD(getstatus)p FJ(\()p FK(list)q FJ(\))208 1861 y FN(Get)j(status)h(information)d(on)i(last)h(error)-5 b(.)0 2188 y FE(34.2)121 b Fx(AL)33 b FE(\227)g(Constants)i(used)g (with)e(the)i Fx(al)d FE(module)0 2421 y FN(This)19 b(module)e (de\002nes)i(symbolic)e(constants)h(needed)g(to)h(use)f(the)h(b)n (uilt-in)f(module)f FJ(al)i FN(\(see)g(abo)o(v)o(e\);)e(the)o(y)h(are)h (equi)n(v)n(alent)e(to)i(those)0 2521 y(de\002ned)h(in)h(the)g(C)h (header)e(\002le)h FJ(<audio.h>)f FN(e)o(xcept)g(that)h(the)g(name)g (pre\002x)f(`)p FJ(AL_)p FN(')g(is)i(omitted.)27 b(Read)21 b(the)g(module)f(source)g(for)g(a)0 2620 y(complete)f(list)i(of)f(the)h (de\002ned)e(names.)24 b(Suggested)19 b(use:)236 2859 y FA(import)44 b(al)236 2950 y(from)g(AL)h(import)909 2963 y(*)0 3460 y FE(34.3)121 b Fx(cd)33 b FE(\227)g(CD-R)n(OM)g (access)g(on)h(SGI)g(systems)0 3693 y FN(This)19 b(module)d(pro)o (vides)h(an)h(interf)o(ace)g(to)g(the)h(Silicon)f(Graphics)f(CD)j (library)-5 b(.)22 b(It)d(is)g(a)n(v)n(ailable)f(only)g(on)g(Silicon)g (Graphics)f(systems.)0 3840 y(The)k(w)o(ay)f(the)h(library)f(w)o(orks)h (is)h(as)f(follo)n(ws.)27 b(A)21 b(program)e(opens)h(the)h(CD-R)m(OM)g (de)n(vice)f(with)h FJ(open\(\))g FN(and)f(creates)h(a)g(parser)f(to)0 3939 y(parse)g(the)g(data)g(from)f(the)h(CD)h(with)f FJ(createparser\(\))p FN(.)j(The)d(object)g(returned)e(by)i FJ(open\(\))f FN(can)h(be)g(used)g(to)g(read)g(data)g(from)0 4039 y(the)j(CD,)g(b)n(ut)g(also)g(to)g(get)g(status)h(information)c (for)i(the)h(CD-R)m(OM)g(de)n(vice,)g(and)f(to)h(get)g(information)d (about)i(the)h(CD,)g(such)g(as)h(the)0 4139 y(table)d(of)g(contents.)27 b(Data)21 b(from)f(the)h(CD)h(is)g(passed)f(to)g(the)g(parser)m(,)f (which)h(parses)g(the)g(frames,)f(and)h(calls)h(an)o(y)e(callback)g (functions)0 4238 y(that)g(ha)n(v)o(e)g(pre)n(viously)e(been)i(added.)0 4385 y(An)j(audio)e(CD)j(is)f(di)n(vided)f(into)g FK(tr)o(ac)n(ks)h FN(or)f FK(pr)l(o)o(gr)o(ams)h FN(\(the)f(terms)h(are)f(used)h (interchangeably\).)28 b(T)m(racks)22 b(can)h(be)f(subdi)n(vided)f (into)0 4485 y FK(indices)p FN(.)j(An)19 b(audio)f(CD)i(contains)e(a)i FK(table)e(of)h(contents)g FN(which)f(gi)n(v)o(es)h(the)g(starts)g(of)g (the)g(tracks)g(on)f(the)h(CD.)h(Inde)o(x)d(0)i(is)h(usually)f(the)0 4584 y(pause)g(before)e(the)i(start)h(of)f(a)g(track.)24 b(The)19 b(start)h(of)f(the)g(track)f(as)i(gi)n(v)o(en)e(by)h(the)g (table)g(of)g(contents)f(is)i(normally)d(the)i(start)h(of)f(inde)o(x)f (1.)0 4731 y(Positions)i(on)f(a)i(CD)f(can)g(be)g(represented)e(in)i (tw)o(o)g(w)o(ays.)25 b(Either)19 b(a)i(frame)e(number)f(or)h(a)h (tuple)g(of)f(three)h(v)n(alues,)f(minutes,)g(seconds)0 4831 y(and)24 b(frames.)38 b(Most)26 b(functions)d(use)i(the)g(latter)g (representation.)36 b(Positions)25 b(can)g(be)g(both)f(relati)n(v)o(e)g (to)h(the)f(be)o(ginning)f(of)h(the)h(CD,)0 4930 y(and)20 b(to)g(the)g(be)o(ginning)e(of)i(the)g(track.)0 5077 y(Module)f FJ(cd)h FN(de\002nes)g(the)h(follo)n(wing)d(functions)h(and) h(constants:)0 5224 y FD(createparser)p FJ(\(\))208 5324 y FN(Create)g(and)g(return)f(an)h(opaque)e(parser)i(object.)k(The)c (methods)f(of)h(the)g(parser)g(object)g(are)g(described)f(belo)n(w)-5 b(.)p 0 5549 3901 4 v 0 5649 a FI(34.2.)52 b FJ(AL)23 b FI(\227)g(Constants)g(used)g(with)h(the)f FJ(al)g FI(module)1994 b(915)p eop end %%Page: 916 928 TeXDict begin 916 927 bop 0 83 a FD(msftoframe)p FJ(\()p FK(minutes,)18 b(seconds,)h(fr)o(ames)p FJ(\))208 183 y FN(Con)m(v)o(erts)e(a)i FJ(\()p FK(minutes)p FJ(,)49 b FK(seconds)p FJ(,)f FK(fr)o(ames)p FJ(\))19 b FN(triple)g (representing)d(time)j(in)g(absolute)f(time)h(code)f(into)g(the)h (corresponding)208 282 y(CD)i(frame)e(number)-5 b(.)0 429 y FD(open)p FJ(\()p FC([)p FK(de)o(vice)p FC([)p FK(,)18 b(mode)12 b FC(])g(])p FJ(\))208 529 y FN(Open)30 b(the)h(CD-R)m(OM)h(de)n(vice.)57 b(The)30 b(return)g(v)n(alue)h(is)h (an)f(opaque)e(player)i(object;)36 b(methods)30 b(of)h(the)g(player)f (object)h(are)208 628 y(described)23 b(belo)n(w)-5 b(.)38 b(The)25 b(de)n(vice)f(is)i(the)f(name)f(of)h(the)g(SCSI)h(de)n(vice)e (\002le,)j(e.g.)38 b FJ('/dev/scsi/sc0d4l0')p FN(,)23 b(or)i FJ(None)p FN(.)208 728 y(If)d(omitted)f(or)h FJ(None)p FN(,)g(the)h(hardw)o(are)d(in)m(v)o(entory)g(is)j(consulted)e(to)h (locate)g(a)h(CD-R)m(OM)g(dri)n(v)o(e.)29 b(The)22 b FK(mode)p FN(,)g(if)h(not)f(omitted,)208 828 y(should)d(be)h(the)g (string)g FJ('r')p FN(.)0 975 y(The)g(module)f(de\002nes)h(the)g(follo) n(wing)e(v)n(ariables:)0 1121 y FL(exception)h FD(error)208 1221 y FN(Exception)f(raised)i(on)g(v)n(arious)f(errors.)0 1368 y FD(DATASIZE)208 1468 y FN(The)i(size)h(of)g(one)f(frame')-5 b(s)21 b(w)o(orth)g(of)g(audio)g(data.)29 b(This)22 b(is)g(the)g(size)g (of)g(the)f(audio)g(data)h(as)g(passed)f(to)h(the)g(callback)f(of)g (type)208 1567 y FJ(audio)p FN(.)0 1714 y FD(BLOCKSIZE)208 1814 y FN(The)e(size)i(of)f(one)g(uninterpreted)d(frame)j(of)g(audio)f (data.)0 1961 y(The)h(follo)n(wing)e(v)n(ariables)i(are)g(states)h(as)g (returned)d(by)i FJ(getstatus\(\))p FN(:)0 2107 y FD(READY)208 2207 y FN(The)f(dri)n(v)o(e)g(is)j(ready)d(for)g(operation)g(loaded)g (with)h(an)g(audio)f(CD.)0 2354 y FD(NODISC)208 2454 y FN(The)g(dri)n(v)o(e)g(does)h(not)g(ha)n(v)o(e)g(a)g(CD)i(loaded.)0 2600 y FD(CDROM)208 2700 y FN(The)d(dri)n(v)o(e)g(is)j(loaded)d(with)h (a)h(CD-R)m(OM.)f(Subsequent)e(play)i(or)g(read)g(operations)e(will)j (return)e(I/O)i(errors.)0 2847 y FD(ERROR)208 2946 y FN(An)f(error)f(occurred)f(while)i(trying)f(to)i(read)e(the)i(disc)f (or)g(its)h(table)f(of)g(contents.)0 3093 y FD(PLAYING)208 3193 y FN(The)f(dri)n(v)o(e)g(is)j(in)e(CD)h(player)e(mode)g(playing)g (an)h(audio)g(CD)h(through)d(its)j(audio)e(jacks.)0 3340 y FD(PAUSED)208 3439 y FN(The)g(dri)n(v)o(e)g(is)j(in)e(CD)h(layer)f (mode)f(with)h(play)g(paused.)0 3586 y FD(STILL)208 3686 y FN(The)i(equi)n(v)n(alent)f(of)h FJ(PAUSED)g FN(on)g(older)g(\(non)f (3301\))g(model)g(T)-7 b(oshiba)22 b(CD-R)m(OM)h(dri)n(v)o(es.)31 b(Such)22 b(dri)n(v)o(es)g(ha)n(v)o(e)g(ne)n(v)o(er)f(been)208 3786 y(shipped)e(by)g(SGI.)0 3932 y FD(audio)0 4032 y(pnum)0 4132 y(index)0 4231 y(ptime)0 4331 y(atime)0 4431 y(catalog)0 4530 y(ident)0 4630 y(control)208 4729 y FN(Inte)o(ger)28 b(constants)i(describing)f(the)h(v)n(arious)f(types)h(of)g(parser)f (callbacks)h(that)g(can)g(be)g(set)h(by)f(the)g FJ(addcallback\(\))208 4829 y FN(method)18 b(of)i(CD)h(parser)f(objects)g(\(see)g(belo)n(w\).) 0 5114 y Fv(34.3.1)101 b(Pla)m(y)n(er)29 b(Objects)0 5317 y FN(Player)20 b(objects)g(\(returned)e(by)i FJ(open\(\))p FN(\))f(ha)n(v)o(e)h(the)g(follo)n(wing)e(methods:)p 0 5549 3901 4 v 0 5649 a FI(916)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 917 929 TeXDict begin 917 928 bop 0 83 a FD(allowremoval)p FJ(\(\))208 183 y FN(Unlocks)19 b(the)h(eject)h(b)n(utton)e(on)h(the)g(CD-R)m(OM)h (dri)n(v)o(e)e(permitting)f(the)i(user)h(to)f(eject)g(the)h(caddy)e(if) h(desired.)0 330 y FD(bestreadsize)p FJ(\(\))208 429 y FN(Returns)k(the)g(best)h(v)n(alue)e(to)i(use)f(for)g(the)g FK(num)p 1600 429 25 4 v 29 w(fr)o(ames)h FN(parameter)e(of)h(the)g FJ(readda\(\))f FN(method.)36 b(Best)26 b(is)f(de\002ned)f(as)h(the)208 529 y(v)n(alue)19 b(that)h(permits)g(a)h(continuous)d(\003o)n(w)i(of)g (data)g(from)f(the)i(CD-R)m(OM)f(dri)n(v)o(e.)0 676 y FD(close)p FJ(\(\))208 775 y FN(Frees)g(the)f(resources)g(associated)g (with)h(the)g(player)e(object.)24 b(After)c(calling)f FJ(close\(\))p FN(,)g(the)g(methods)g(of)g(the)h(object)f(should)208 875 y(no)g(longer)g(be)h(used.)0 1022 y FD(eject)p FJ(\(\))208 1121 y FN(Ejects)g(the)g(caddy)f(from)h(the)g(CD-R)m(OM)g(dri)n(v)o(e.) 0 1268 y FD(getstatus)p FJ(\(\))208 1368 y FN(Returns)k(information)d (pertaining)i(to)h(the)g(current)f(state)i(of)f(the)g(CD-R)m(OM)h(dri)n (v)o(e.)35 b(The)24 b(returned)e(information)g(is)j(a)g(tuple)208 1468 y(with)g(the)h(follo)n(wing)e(v)n(alues:)36 b FK(state)p FN(,)27 b FK(tr)o(ac)n(k)q FN(,)g FK(rtime)p FN(,)h FK(atime)p FN(,)f FK(ttime)p FN(,)g FK(\002r)o(st)q FN(,)h FK(last)q FN(,)g FK(scsi)p 2696 1468 V 30 w(audio)p FN(,)e FK(cur)p 3075 1468 V 29 w(bloc)n(k)q FN(.)42 b FK(rtime)26 b FN(is)h(the)e(time) 208 1567 y(relati)n(v)o(e)c(to)i(the)g(start)g(of)g(the)f(current)g (track;)h FK(atime)g FN(is)g(the)g(time)g(relati)n(v)o(e)f(to)h(the)f (be)o(ginning)e(of)j(the)g(disc;)h FK(ttime)f FN(is)h(the)e(total)208 1667 y(time)e(on)g(the)g(disc.)26 b(F)o(or)20 b(more)g(information)e (on)i(the)g(meaning)f(of)h(the)h(v)n(alues,)e(see)i(the)g(man)f(page)f FK(CDg)o(etstatus)p FN(\(3dm\).)24 b(The)208 1766 y(v)n(alue)19 b(of)h FK(state)h FN(is)g(one)e(of)h(the)g(follo)n(wing:)k FJ(ERROR)p FN(,)c FJ(NODISC)p FN(,)f FJ(READY)p FN(,)h FJ(PLAYING)p FN(,)f FJ(PAUSED)p FN(,)g FJ(STILL)p FN(,)h(or)g FJ(CDROM)p FN(.)0 1913 y FD(gettrackinfo)p FJ(\()p FK(tr)o(ac)n(k)q FJ(\))208 2013 y FN(Returns)j(information)e(about)i(the)g(speci\002ed)g (track.)35 b(The)23 b(returned)f(information)f(is)j(a)g(tuple)f (consisting)g(of)g(tw)o(o)h(elements,)208 2113 y(the)c(start)g(time)h (of)f(the)g(track)g(and)f(the)i(duration)d(of)i(the)g(track.)0 2259 y FD(msftoblock)p FJ(\()p FK(min,)e(sec,)j(fr)o(ame)p FJ(\))208 2359 y FN(Con)m(v)o(erts)16 b(a)i(minutes,)f(seconds,)g (frames)g(triple)g(representing)f(a)h(time)h(in)g(absolute)e(time)i (code)f(into)g(the)g(corresponding)d(logi-)208 2459 y(cal)k(block)f (number)e(for)j(the)f(gi)n(v)o(en)g(CD-R)m(OM)h(dri)n(v)o(e.)23 b(Y)-9 b(ou)17 b(should)g(use)h FJ(msftoframe\(\))e FN(rather)h(than)g FJ(msftoblock\(\))208 2558 y FN(for)k(comparing)e(times.)30 b(The)22 b(logical)f(block)g(number)f(dif)n(fers)h(from)g(the)g(frame)g (number)f(by)i(an)f(of)n(fset)h(required)e(by)h(certain)208 2658 y(CD-R)m(OM)f(dri)n(v)o(es.)0 2805 y FD(play)p FJ(\()p FK(start,)g(play)p FJ(\))208 2904 y FN(Starts)25 b(playback)d(of)i(an)h (audio)e(CD)i(in)g(the)f(CD-R)m(OM)h(dri)n(v)o(e)e(at)i(the)f (speci\002ed)h(track.)37 b(The)24 b(audio)f(output)g(appears)h(on)g (the)208 3004 y(CD-R)m(OM)d(dri)n(v)o(e')-5 b(s)21 b(headphone)d(and)j (audio)f(jacks)i(\(if)f(\002tted\).)28 b(Play)21 b(stops)h(at)g(the)f (end)g(of)g(the)g(disc.)28 b FK(start)c FN(is)e(the)f(number)f(of)208 3104 y(the)g(track)h(at)g(which)f(to)h(start)h(playing)d(the)i(CD;)h (if)f FK(play)f FN(is)i(0,)f(the)g(CD)g(will)h(be)f(set)g(to)g(an)g (initial)g(paused)f(state.)27 b(The)21 b(method)208 3203 y FJ(togglepause\(\))d FN(can)i(then)g(be)g(used)g(to)g(commence)e (play)-5 b(.)0 3350 y FD(playabs)p FJ(\()p FK(minutes,)18 b(seconds,)i(fr)o(ames,)g(play)p FJ(\))208 3450 y FN(Lik)o(e)g FJ(play\(\))p FN(,)f(e)o(xcept)g(that)i(the)f(start)g(is)i(gi)n(v)o(en) c(in)j(minutes,)e(seconds,)h(and)f(frames)h(instead)g(of)g(a)g(track)g (number)-5 b(.)0 3597 y FD(playtrack)p FJ(\()p FK(start,)19 b(play)p FJ(\))208 3696 y FN(Lik)o(e)h FJ(play\(\))p FN(,)f(e)o(xcept)g(that)i(playing)d(stops)j(at)f(the)h(end)e(of)h(the)g (track.)0 3843 y FD(playtrackabs)p FJ(\()p FK(tr)o(ac)n(k,)e(minutes,)i (seconds,)f(fr)o(ames,)h(play)p FJ(\))208 3943 y FN(Lik)o(e)28 b FJ(play\(\))p FN(,)h(e)o(xcept)e(that)h(playing)f(be)o(gins)g(at)h (the)g(speci\002ed)g(absolute)f(time)i(and)e(ends)h(at)g(the)h(end)e (of)h(the)g(speci\002ed)208 4042 y(track.)0 4189 y FD(preventremoval)p FJ(\(\))208 4289 y FN(Locks)19 b(the)h(eject)h(b)n(utton)e(on)h(the)g (CD-R)m(OM)h(dri)n(v)o(e)e(thus)h(pre)n(v)o(enting)d(the)k(user)f(from) f(arbitrarily)g(ejecting)g(the)h(caddy)-5 b(.)0 4436 y FD(readda)p FJ(\()p FK(num)p 499 4436 V 28 w(fr)o(ames)p FJ(\))208 4535 y FN(Reads)22 b(the)g(speci\002ed)f(number)f(of)i (frames)f(from)g(an)h(audio)f(CD)h(mounted)e(in)i(the)g(CD-R)m(OM)g (dri)n(v)o(e.)29 b(The)22 b(return)e(v)n(alue)h(is)i(a)208 4635 y(string)18 b(representing)f(the)i(audio)f(frames.)24 b(This)19 b(string)f(can)h(be)f(passed)h(unaltered)f(to)h(the)f FJ(parseframe\(\))g FN(method)f(of)i(the)208 4735 y(parser)g(object.)0 4882 y FD(seek)p FJ(\()p FK(minutes,)g(seconds,)g(fr)o(ames)p FJ(\))208 4981 y FN(Sets)28 b(the)g(pointer)f(that)h(indicates)f(the)h (starting)g(point)f(of)h(the)f(ne)o(xt)h(read)f(of)h(digital)f(audio)g (data)h(from)f(a)h(CD-R)m(OM.)g(The)208 5081 y(pointer)17 b(is)i(set)g(to)g(an)f(absolute)g(time)h(code)f(location)f(speci\002ed) h(in)h FK(minutes)p FN(,)f FK(seconds)p FN(,)g(and)g FK(fr)o(ames)p FN(.)25 b(The)18 b(return)f(v)n(alue)h(is)i(the)208 5180 y(logical)f(block)h(number)e(to)i(which)g(the)g(pointer)f(has)h (been)g(set.)0 5327 y FD(seekblock)p FJ(\()p FK(bloc)n(k)q FJ(\))p 0 5549 3901 4 v 0 5649 a FI(34.3.)52 b FJ(cd)23 b FI(\227)g(CD-R)n(OM)g(access)e(on)j(SGI)f(systems)2065 b(917)p eop end %%Page: 918 930 TeXDict begin 918 929 bop 208 83 a FN(Sets)28 b(the)g(pointer)f(that)h (indicates)f(the)h(starting)g(point)f(of)h(the)f(ne)o(xt)h(read)f(of)h (digital)f(audio)g(data)h(from)f(a)h(CD-R)m(OM.)g(The)208 183 y(pointer)22 b(is)j(set)f(to)g(the)g(speci\002ed)f(logical)g(block) g(number)-5 b(.)34 b(The)24 b(return)e(v)n(alue)h(is)i(the)f(logical)f (block)g(number)f(to)h(which)h(the)208 282 y(pointer)19 b(has)h(been)f(set.)0 429 y FD(seektrack)p FJ(\()p FK(tr)o(ac)n(k)q FJ(\))208 529 y FN(Sets)28 b(the)g(pointer)f(that)h(indicates)f(the)h (starting)g(point)f(of)h(the)f(ne)o(xt)h(read)f(of)h(digital)f(audio)g (data)h(from)f(a)h(CD-R)m(OM.)g(The)208 628 y(pointer)21 b(is)i(set)g(to)f(the)g(speci\002ed)g(track.)31 b(The)21 b(return)g(v)n(alue)h(is)h(the)f(logical)g(block)f(number)g(to)h(which) g(the)g(pointer)f(has)h(been)208 728 y(set.)0 875 y FD(stop)p FJ(\(\))208 975 y FN(Stops)e(the)g(current)f(playing)g(operation.)0 1121 y FD(togglepause)p FJ(\(\))208 1221 y FN(P)o(auses)h(the)g(CD)h (if)g(it)g(is)g(playing,)d(and)i(mak)o(es)g(it)h(play)f(if)g(it)h(is)g (paused.)0 1506 y Fv(34.3.2)101 b(P)l(arser)29 b(Objects)0 1709 y FN(P)o(arser)20 b(objects)g(\(returned)e(by)i FJ(createparser\(\))p FN(\))e(ha)n(v)o(e)h(the)h(follo)n(wing)f (methods:)0 1856 y FD(addcallback)p FJ(\()p FK(type)o(,)f(func,)h(ar)m (g)p FJ(\))208 1955 y FN(Adds)26 b(a)i(callback)e(for)g(the)i(parser)-5 b(.)45 b(The)26 b(parser)h(has)g(callbacks)g(for)f(eight)h(dif)n (ferent)e(types)i(of)g(data)g(in)g(the)g(digital)g(audio)208 2055 y(data)d(stream.)40 b(Constants)25 b(for)g(these)g(types)g(are)g (de\002ned)f(at)h(the)g FJ(cd)h FN(module)d(le)n(v)o(el)i(\(see)g(abo)o (v)o(e\).)38 b(The)24 b(callback)h(is)h(called)208 2155 y(as)21 b(follo)n(ws:)27 b FK(func)p FJ(\()p FK(ar)m(g)p FJ(,)47 b(type,)i(data\))p FN(,)21 b(where)f FK(ar)m(g)h FN(is)h(the)f(user)g(supplied)f(ar)o(gument,)f FK(type)i FN(is)h(the)f(particular)e(type)i(of)208 2254 y(callback,)27 b(and)f FK(data)f FN(is)j(the)f(data)f(returned)f(for)h(this)h FK(type)f FN(of)h(callback.)43 b(The)26 b(type)g(of)g(the)h(data)f (depends)g(on)g(the)g FK(type)h FN(of)208 2354 y(callback)19 b(as)i(follo)n(ws:)630 2466 y FL(T)-6 b(ype)p 1026 2496 4 100 v 274 w(V)e(alue)p 580 2499 2948 4 v 630 2569 a FJ(audio)p 1026 2599 4 100 v 198 w FN(String)20 b(which)f(can)h(be)g (passed)h(unmodi\002ed)d(to)i FJ(al.writesamps\(\))p FN(.)630 2669 y FJ(pnum)p 1026 2699 V 248 w FN(Inte)o(ger)f(gi)n(ving)f (the)j(program)d(\(track\))h(number)-5 b(.)630 2768 y FJ(index)p 1026 2798 V 198 w FN(Inte)o(ger)19 b(gi)n(ving)f(the)j(inde) o(x)e(number)-5 b(.)630 2868 y FJ(ptime)p 1026 2898 V 198 w FN(T)l(uple)20 b(consisting)f(of)h(the)g(program)e(time)j(in)f (minutes,)f(seconds,)h(and)f(frames.)630 2968 y FJ(atime)p 1026 2998 V 198 w FN(T)l(uple)h(consisting)f(of)h(the)g(absolute)g (time)g(in)g(minutes,)g(seconds,)f(and)h(frames.)630 3067 y FJ(catalog)p 1026 3097 V 98 w FN(String)g(of)g(13)f(characters,) g(gi)n(ving)g(the)h(catalog)g(number)e(of)i(the)g(CD.)630 3167 y FJ(ident)p 1026 3496 4 399 v 198 w FN(String)32 b(of)f(12)h(characters,)i(gi)n(ving)c(the)j(ISRC)g(identi\002cation)d (number)h(of)g(the)1078 3267 y(recording.)22 b(The)16 b(string)h(consists)h(of)f(tw)o(o)g(characters)f(country)g(code,)g (three)h(char)n(-)1078 3366 y(acters)30 b(o)n(wner)g(code,)i(tw)o(o)e (characters)g(gi)n(ving)f(the)h(year)m(,)i(and)d(\002)n(v)o(e)h (characters)1078 3466 y(gi)n(ving)19 b(a)h(serial)h(number)-5 b(.)630 3565 y FJ(control)p 1026 3595 4 100 v 98 w FN(Inte)o(ger)19 b(gi)n(ving)f(the)j(control)e(bits)h(from)f(the)i(CD)g(subcode)e(data)0 3703 y FD(deleteparser)p FJ(\(\))208 3803 y FN(Deletes)j(the)f(parser)g (and)g(frees)g(the)h(memory)e(it)i(w)o(as)g(using.)29 b(The)21 b(object)g(should)f(not)i(be)f(used)g(after)h(this)g(call.)29 b(This)22 b(call)g(is)208 3902 y(done)d(automatically)f(when)i(the)g (last)h(reference)e(to)h(the)g(object)g(is)h(remo)o(v)o(ed.)0 4049 y FD(parseframe)p FJ(\()p FK(fr)o(ame)p FJ(\))208 4149 y FN(P)o(arses)d(one)g(or)f(more)h(frames)f(of)h(digital)g(audio)f (data)h(from)f(a)h(CD)h(such)f(as)h(returned)d(by)i FJ(readda\(\))p FN(.)23 b(It)18 b(determines)f(which)208 4249 y(subcodes)23 b(are)i(present)f(in)h(the)f(data.)38 b(If)25 b(these)g(subcodes)e(ha)n (v)o(e)h(changed)f(since)i(the)g(last)g(frame,)g(then)f FJ(parseframe\(\))208 4348 y FN(e)o(x)o(ecutes)j(a)i(callback)f(of)g (the)h(appropriate)d(type)i(passing)h(to)f(it)i(the)e(subcode)g(data)g (found)f(in)i(the)f(frame.)50 b(Unlik)o(e)28 b(the)h(C)208 4448 y(function,)18 b(more)h(than)h(one)f(frame)h(of)g(digital)g(audio) f(data)h(can)g(be)g(passed)g(to)h(this)f(method.)0 4595 y FD(removecallback)p FJ(\()p FK(type)p FJ(\))208 4694 y FN(Remo)o(v)o(es)f(the)h(callback)f(for)h(the)g(gi)n(v)o(en)f FK(type)p FN(.)0 4841 y FD(resetparser)p FJ(\(\))208 4941 y FN(Resets)h(the)f(\002elds)h(of)f(the)g(parser)f(used)h(for)g (tracking)e(subcodes)h(to)i(an)f(initial)g(state.)25 b FJ(resetparser\(\))18 b FN(should)g(be)h(called)208 5040 y(after)g(the)i(disc)f(has)h(been)e(changed.)p 0 5549 3901 4 v 0 5649 a FI(918)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 919 931 TeXDict begin 919 930 bop 0 88 a FE(34.4)121 b Fx(fl)33 b FE(\227)g(FORMS)g(libr)o(ar)t(y)f(f)l(or)i(g)o(r)o(aphical)g(user)f (interf)l(aces)0 321 y FN(This)e(module)e(pro)o(vides)g(an)h(interf)o (ace)g(to)h(the)f(FORMS)i(Library)d(by)h(Mark)g(Ov)o(ermars.)54 b(The)31 b(source)e(for)h(the)h(library)e(can)i(be)0 421 y(retrie)n(v)o(ed)23 b(by)h(anon)o(ymous)e(ftp)i(from)g(host)h(`)p FJ(ftp.cs.ruu.nl)p FN(',)e(directory)g(`)p FO(SGI/FORMS)p FN('.)g(It)i(w)o(as)h(last)f(tested)g(with)g(v)o(ersion)0 520 y(2.0b)m(.)0 667 y(Most)h(functions)d(are)j(literal)f(translations) g(of)g(their)g(C)h(equi)n(v)n(alents,)f(dropping)d(the)k(initial)f(`)p FJ(fl_)p FN(')g(from)f(their)h(name.)39 b(Constants)0 767 y(used)20 b(by)g(the)g(library)f(are)h(de\002ned)f(in)i(module)d FJ(FL)j FN(described)e(belo)n(w)-5 b(.)0 914 y(The)21 b(creation)f(of)g(objects)h(is)h(a)f(little)h(dif)n(ferent)e(in)h (Python)f(than)g(in)h(C:)h(instead)f(of)g(the)g(`current)e(form')h (maintained)f(by)i(the)g(library)0 1013 y(to)g(which)f(ne)n(w)h(FORMS)h (objects)f(are)f(added,)g(all)h(functions)f(that)h(add)f(a)h(FORMS)h (object)f(to)g(a)g(form)f(are)g(methods)g(of)h(the)g(Python)0 1113 y(object)c(representing)f(the)h(form.)23 b(Consequently)-5 b(,)16 b(there)h(are)h(no)f(Python)f(equi)n(v)n(alents)g(for)h(the)h(C) h(functions)d FJ(fl_addto_form\(\))0 1212 y FN(and)k FJ(fl_end_form\(\))p FN(,)e(and)h(the)i(equi)n(v)n(alent)d(of)i FJ(fl_bgn_form\(\))e FN(is)j(called)f FJ(fl.make_form\(\))p FN(.)0 1359 y(W)-7 b(atch)26 b(out)g(for)f(the)h(some)n(what)f (confusing)e(terminology:)34 b(FORMS)27 b(uses)f(the)g(w)o(ord)f FK(object)g FN(for)g(the)h(b)n(uttons,)g(sliders)g(etc.)42 b(that)0 1459 y(you)23 b(can)g(place)g(in)h(a)g(form.)34 b(In)23 b(Python,)g(`object')g(means)g(an)o(y)g(v)n(alue.)34 b(The)23 b(Python)g(interf)o(ace)g(to)g(FORMS)i(introduces)d(tw)o(o)i (ne)n(w)0 1559 y(Python)e(object)g(types:)31 b(form)22 b(objects)h(\(representing)d(an)j(entire)g(form\))f(and)g(FORMS)i (objects)f(\(representing)d(one)j(b)n(utton,)g(slider)0 1658 y(etc.\).)i(Hopefully)18 b(this)j(isn')o(t)f(too)g(confusing.)0 1805 y(There)i(are)h(no)g(`free)f(objects')h(in)g(the)g(Python)f (interf)o(ace)g(to)h(FORMS,)h(nor)e(is)i(there)f(an)g(easy)g(w)o(ay)g (to)h(add)e(object)h(classes)h(written)0 1905 y(in)g(Python.)36 b(The)24 b(FORMS)h(interf)o(ace)e(to)h(GL)g(e)n(v)o(ent)g(handling)e (is)j(a)n(v)n(ailable,)f(though,)f(so)i(you)e(can)h(mix)g(FORMS)h(with) f(pure)f(GL)0 2004 y(windo)n(ws.)0 2151 y FL(Please)29 b(note:)42 b FN(importing)27 b FJ(fl)j FN(implies)f(a)g(call)h(to)f (the)g(GL)g(function)f FJ(foreground\(\))f FN(and)i(to)g(the)g(FORMS)h (routine)e FJ(fl_-)0 2251 y(init\(\))p FN(.)0 2536 y Fv(34.4.1)101 b(Functions)28 b(De\002ned)h(in)f(Module)i Fm(fl)0 2739 y FN(Module)e FJ(fl)i FN(de\002nes)g(the)f(follo)n(wing)f (functions.)52 b(F)o(or)30 b(more)e(information)g(about)g(what)i(the)o (y)f(do,)i(see)f(the)g(description)e(of)i(the)0 2838 y(equi)n(v)n(alent)18 b(C)k(function)c(in)i(the)h(FORMS)g (documentation:)0 2985 y FD(make_form)p FJ(\()p FK(type)o(,)d(width,)i (height)q FJ(\))208 3085 y FN(Create)d(a)g(form)f(with)h(gi)n(v)o(en)f (type,)g(width)h(and)f(height.)23 b(This)17 b(returns)g(a)g FK(form)g FN(object,)g(whose)g(methods)e(are)i(described)f(belo)n(w)-5 b(.)0 3232 y FD(do_forms)p FJ(\(\))208 3331 y FN(The)20 b(standard)f(FORMS)i(main)f(loop.)25 b(Returns)20 b(a)h(Python)e (object)h(representing)e(the)i(FORMS)i(object)d(needing)g(interaction,) 208 3431 y(or)g(the)i(special)f(v)n(alue)f FJ(FL.EVENT)p FN(.)0 3578 y FD(check_forms)p FJ(\(\))208 3677 y FN(Check)h(for)g (FORMS)i(e)n(v)o(ents.)j(Returns)c(what)f FJ(do_forms\(\))g FN(abo)o(v)o(e)f(returns,)g(or)h FJ(None)h FN(if)g(there)f(is)i(no)e(e) n(v)o(ent)g(that)g(imme-)208 3777 y(diately)f(needs)h(interaction.)0 3924 y FD(set_event_call_back)p FJ(\()p FK(function)p FJ(\))208 4023 y FN(Set)g(the)h(e)n(v)o(ent)e(callback)g(function.)0 4170 y FD(set_graphics_mode)p FJ(\()p FK(r)m(gbmode)o(,)c(doubleb)n(uf) o(fering)p FJ(\))208 4270 y FN(Set)20 b(the)h(graphics)e(modes.)0 4417 y FD(get_rgbmode)p FJ(\(\))208 4516 y FN(Return)g(the)i(current)d (r)o(gb)h(mode.)24 b(This)d(is)g(the)f(v)n(alue)f(of)h(the)h(C)g (global)e(v)n(ariable)g FJ(fl_rgbmode)p FN(.)0 4663 y FD(show_message)p FJ(\()p FK(str1,)f(str2,)j(str3)p FJ(\))208 4763 y FN(Sho)n(w)e(a)i(dialog)e(box)h(with)g(a)h(three-line)d(message) i(and)g(an)g(OK)h(b)n(utton.)0 4910 y FD(show_question)p FJ(\()p FK(str1,)d(str2,)j(str3)p FJ(\))208 5009 y FN(Sho)n(w)g(a)h (dialog)f(box)f(with)i(a)g(three-line)f(message)g(and)g(YES)h(and)f(NO) i(b)n(uttons.)28 b(It)22 b(returns)f FJ(1)h FN(if)g(the)g(user)f (pressed)g(YES,)h FJ(0)208 5109 y FN(if)e(NO.)0 5256 y FD(show_choice)p FJ(\()p FK(str1,)e(str2,)j(str3,)g(b)n(ut1)p FC([)p FK(,)e(b)n(ut2)p FC([)p FK(,)g(b)n(ut3)12 b FC(])g(])p FJ(\))208 5356 y FN(Sho)n(w)18 b(a)i(dialog)e(box)g(with)i(a)f (three-line)f(message)h(and)f(up)h(to)g(three)g(b)n(uttons.)24 b(It)19 b(returns)f(the)i(number)d(of)i(the)g(b)n(utton)f(click)o(ed)p 0 5549 3901 4 v 0 5649 a FI(34.4.)52 b FJ(fl)23 b FI(\227)g(FORMS)g (libr)o(ar)r(y)h(f)n(or)e(g)o(r)o(aphical)i(user)f(interf)n(aces)1705 b(919)p eop end %%Page: 920 932 TeXDict begin 920 931 bop 208 83 a FN(by)19 b(the)i(user)f(\()p FJ(1)p FN(,)g FJ(2)g FN(or)g FJ(3)p FN(\).)0 230 y FD(show_input)p FJ(\()p FK(pr)l(ompt,)e(default)q FJ(\))208 330 y FN(Sho)n(w)e(a)h (dialog)f(box)g(with)h(a)h(one-line)d(prompt)g(message)i(and)f(te)o(xt) h(\002eld)g(in)g(which)f(the)h(user)g(can)g(enter)f(a)h(string.)24 b(The)16 b(second)208 429 y(ar)o(gument)h(is)22 b(the)e(def)o(ault)f (input)h(string.)k(It)d(returns)e(the)h(string)g(v)n(alue)g(as)h (edited)e(by)h(the)g(user)-5 b(.)0 576 y FD(show_file_selector)p FJ(\()p FK(messa)o(g)o(e)o(,)17 b(dir)m(ectory)-5 b(,)20 b(pattern,)f(default)q FJ(\))208 676 y FN(Sho)n(w)24 b(a)g(dialog)g(box)f(in)i(which)f(the)g(user)h(can)f(select)h(a)g (\002le.)38 b(It)25 b(returns)e(the)i(absolute)e(\002lename)h(selected) h(by)f(the)g(user)m(,)h(or)208 775 y FJ(None)20 b FN(if)g(the)g(user)g (presses)h(Cancel.)0 922 y FD(get_directory)p FJ(\(\))0 1022 y FD(get_pattern)p FJ(\(\))0 1121 y FD(get_filename)p FJ(\(\))208 1221 y FN(These)28 b(functions)f(return)g(the)h(directory) -5 b(,)28 b(pattern)g(and)g(\002lename)g(\(the)g(tail)h(part)f(only\))f (selected)h(by)g(the)h(user)f(in)g(the)h(last)208 1321 y FJ(show_file_selector\(\))17 b FN(call.)0 1468 y FD(qdevice)p FJ(\()p FK(de)o(v)p FJ(\))0 1567 y FD(unqdevice)p FJ(\()p FK(de)o(v)p FJ(\))0 1667 y FD(isqueued)p FJ(\()p FK(de)o(v)p FJ(\))0 1766 y FD(qtest)p FJ(\(\))0 1866 y FD(qread)p FJ(\(\))0 1966 y FD(qreset)p FJ(\(\))0 2065 y FD(qenter)p FJ(\()p FK(de)o(v)-6 b(,)18 b(val)p FJ(\))0 2165 y FD(get_mouse)p FJ(\(\))0 2265 y FD(tie)p FJ(\()p FK(b)n(utton,)g(valuator1,)h (valuator2)p FJ(\))208 2364 y FN(These)i(functions)e(are)i(the)h(FORMS) g(interf)o(aces)e(to)i(the)f(corresponding)c(GL)22 b(functions.)k(Use)c (these)f(if)h(you)e(w)o(ant)h(to)h(handle)208 2464 y(some)h(GL)g(e)n(v) o(ents)f(yourself)g(when)h(using)f FJ(fl.do_events\(\))p FN(.)32 b(When)23 b(a)g(GL)h(e)n(v)o(ent)e(is)i(detected)e(that)i (FORMS)g(cannot)208 2563 y(handle,)17 b FJ(fl.do_forms\(\))g FN(returns)h(the)h(special)g(v)n(alue)f FJ(FL.EVENT)g FN(and)g(you)g(should)g(call)h FJ(fl.qread\(\))e FN(to)i(read)g(the)208 2663 y(e)n(v)o(ent)g(from)g(the)h(queue.)k(Don')o(t)19 b(use)h(the)g(equi)n(v)n(alent)f(GL)h(functions!)0 2810 y FD(color)p FJ(\(\))0 2910 y FD(mapcolor)p FJ(\(\))0 3009 y FD(getmcolor)p FJ(\(\))208 3109 y FN(See)54 b(the)g(description) e(in)i(the)g(FORMS)h(documentation)50 b(of)k FJ(fl_color\(\))p FN(,)61 b FJ(fl_mapcolor\(\))51 b FN(and)j FJ(fl_-)208 3208 y(getmcolor\(\))p FN(.)0 3493 y Fv(34.4.2)101 b(F)m(or)r(m)28 b(Objects)0 3696 y FN(F)o(orm)h(objects)g(\(returned)f(by)h FJ(make_form\(\))f FN(abo)o(v)o(e\))g(ha)n(v)o(e)h(the)g(follo)n(wing)f (methods.)52 b(Each)29 b(method)g(corresponds)e(to)j(a)g(C)0 3796 y(function)23 b(whose)h(name)g(is)h(pre\002x)o(ed)e(with)i(`)p FJ(fl_)p FN(';)h(and)e(whose)g(\002rst)i(ar)o(gument)c(is)j(a)g(form)f (pointer;)h(please)g(refer)f(to)g(the)h(of)n(\002cial)0 3895 y(FORMS)c(documentation)c(for)j(descriptions.)0 4042 y(All)k(the)f FJ(add_)455 4057 y(*)505 4042 y(\(\))g FN(methods)f(return)h(a)g(Python)g(object)f(representing)g(the)h(FORMS) i(object.)33 b(Methods)23 b(of)g(FORMS)h(objects)g(are)0 4142 y(described)18 b(belo)n(w)-5 b(.)24 b(Most)c(kinds)f(of)h(FORMS)h (object)e(also)h(ha)n(v)o(e)f(some)g(methods)g(speci\002c)h(to)g(that)g (kind;)f(these)h(methods)e(are)i(listed)0 4242 y(here.)0 4471 y FD(show_form)p FJ(\()p FK(placement,)d(bor)m(dertype)o(,)i(name) p FJ(\))208 4571 y FN(Sho)n(w)g(the)i(form.)0 4718 y FD(hide_form)p FJ(\(\))208 4818 y FN(Hide)f(the)g(form.)0 4964 y FD(redraw_form)p FJ(\(\))208 5064 y FN(Redra)o(w)f(the)h(form.)0 5211 y FD(set_form_position)p FJ(\()p FK(x,)d(y)p FJ(\))208 5311 y FN(Set)j(the)h(form')-5 b(s)19 b(position.)p 0 5549 3901 4 v 0 5649 a FI(920)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 921 933 TeXDict begin 921 932 bop 0 83 a FD(freeze_form)p FJ(\(\))208 183 y FN(Freeze)20 b(the)g(form.)0 330 y FD(unfreeze_form)p FJ(\(\))208 429 y FN(Unfreeze)f(the)h(form.)0 576 y FD(activate_form)p FJ(\(\))208 676 y FN(Acti)n(v)n(ate)f(the)i(form.)0 823 y FD(deactivate_form)p FJ(\(\))208 922 y FN(Deacti)n(v)n(ate)e(the)h (form.)0 1069 y FD(bgn_group)p FJ(\(\))208 1169 y FN(Be)o(gin)f(a)i(ne) n(w)f(group)e(of)i(objects;)g(return)f(a)i(group)d(object.)0 1316 y FD(end_group)p FJ(\(\))208 1415 y FN(End)h(the)h(current)f (group)g(of)g(objects.)0 1562 y FD(find_first)p FJ(\(\))208 1662 y FN(Find)h(the)g(\002rst)h(object)e(in)i(the)f(form.)0 1808 y FD(find_last)p FJ(\(\))208 1908 y FN(Find)g(the)g(last)h(object) f(in)g(the)g(form.)0 2055 y FD(add_box)p FJ(\()p FK(type)o(,)e(x,)j(y) -5 b(,)21 b(w)-6 b(,)20 b(h,)g(name)p FJ(\))208 2155 y FN(Add)f(a)i(box)e(object)h(to)g(the)g(form.)k(No)c(e)o(xtra)g (methods.)0 2301 y FD(add_text)p FJ(\()p FK(type)o(,)e(x,)j(y)-5 b(,)20 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 2401 y FN(Add)f(a)i(te)o (xt)f(object)g(to)g(the)g(form.)k(No)c(e)o(xtra)g(methods.)0 2548 y FD(add_clock)p FJ(\()p FK(type)o(,)e(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 2648 y FN(Add)f(a)i(clock) e(object)h(to)g(the)h(form.)208 2747 y(Method:)j FJ(get_clock\(\))p FN(.)0 2894 y FD(add_button)p FJ(\()p FK(type)o(,)18 b(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 2994 y FN(Add)f(a)i(b)n(utton)e(object)h(to)g(the)g(form.)208 3093 y(Methods:)k FJ(get_button\(\))p FN(,)18 b FJ(set_button\(\))p FN(.)0 3240 y FD(add_lightbutton)p FJ(\()p FK(type)o(,)f(x,)j(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 3340 y FN(Add)f(a)i (lightb)n(utton)d(object)i(to)g(the)h(form.)208 3439 y(Methods:)j FJ(get_button\(\))p FN(,)18 b FJ(set_button\(\))p FN(.)0 3586 y FD(add_roundbutton)p FJ(\()p FK(type)o(,)f(x,)j(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 3686 y FN(Add)f(a)i (roundb)n(utton)c(object)j(to)g(the)g(form.)208 3786 y(Methods:)k FJ(get_button\(\))p FN(,)18 b FJ(set_button\(\))p FN(.)0 3932 y FD(add_slider)p FJ(\()p FK(type)o(,)g(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 4032 y FN(Add)f(a)i (slider)f(object)g(to)g(the)g(form.)208 4132 y(Methods:)k FJ(set_slider_value\(\))p FN(,)17 b FJ(get_slider_value\(\))p FN(,)g FJ(set_slider_bounds\(\))p FN(,)208 4231 y FJ (get_slider_bounds\(\))p FN(,)g FJ(set_slider_return\(\))p FN(,)f FJ(set_slider_size\(\))p FN(,)208 4331 y FJ (set_slider_precision\(\))p FN(,)g FJ(set_slider_step\(\))p FN(.)0 4478 y FD(add_valslider)p FJ(\()p FK(type)o(,)h(x,)k(y)-5 b(,)21 b(w)-6 b(,)20 b(h,)g(name)p FJ(\))208 4577 y FN(Add)f(a)i(v)n (alslider)e(object)h(to)g(the)h(form.)208 4677 y(Methods:)j FJ(set_slider_value\(\))p FN(,)17 b FJ(get_slider_value\(\))p FN(,)g FJ(set_slider_bounds\(\))p FN(,)208 4777 y FJ (get_slider_bounds\(\))p FN(,)g FJ(set_slider_return\(\))p FN(,)f FJ(set_slider_size\(\))p FN(,)208 4876 y FJ (set_slider_precision\(\))p FN(,)g FJ(set_slider_step\(\))p FN(.)0 5023 y FD(add_dial)p FJ(\()p FK(type)o(,)i(x,)j(y)-5 b(,)20 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 5123 y FN(Add)f(a)i(dial)f (object)g(to)g(the)g(form.)208 5222 y(Methods:)k FJ(set_dial_value\(\)) p FN(,)17 b FJ(get_dial_value\(\))p FN(,)h FJ(set_dial_bounds\(\))p FN(,)208 5322 y FJ(get_dial_bounds\(\))p FN(.)p 0 5549 3901 4 v 0 5649 a FI(34.4.)52 b FJ(fl)23 b FI(\227)g(FORMS)g(libr)o(ar) r(y)h(f)n(or)e(g)o(r)o(aphical)i(user)f(interf)n(aces)1705 b(921)p eop end %%Page: 922 934 TeXDict begin 922 933 bop 0 83 a FD(add_positioner)p FJ(\()p FK(type)o(,)17 b(x,)k(y)-5 b(,)20 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 183 y FN(Add)f(a)i(positioner)e(object)g(to)i (the)f(form.)208 282 y(Methods:)k FJ(set_positioner_xvalue\(\))p FN(,)16 b FJ(set_positioner_yvalue\(\))p FN(,)208 382 y FJ(set_positioner_xbounds\(\))p FN(,)g FJ(set_positioner_ybounds\(\)) p FN(,)g FJ(get_positioner_xvalue\(\))p FN(,)208 482 y FJ(get_positioner_yvalue\(\))p FN(,)g FJ(get_positioner_xbounds\(\))p FN(,)g FJ(get_positioner_ybounds\(\))p FN(.)0 628 y FD(add_counter)p FJ(\()p FK(type)o(,)i(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 728 y FN(Add)f(a)i(counter)e(object)g(to)i(the) f(form.)208 828 y(Methods:)k FJ(set_counter_value\(\))p FN(,)17 b FJ(get_counter_value\(\))p FN(,)g FJ(set_counter_bounds\(\))p FN(,)208 927 y FJ(set_counter_step\(\))p FN(,)g FJ (set_counter_precision\(\))p FN(,)f FJ(set_counter_return\(\))p FN(.)0 1074 y FD(add_input)p FJ(\()p FK(type)o(,)i(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 1174 y FN(Add)f(a)i(input) e(object)h(to)g(the)h(form.)208 1273 y(Methods:)j FJ(set_input\(\))p FN(,)18 b FJ(get_input\(\))p FN(,)h FJ(set_input_color\(\))p FN(,)e FJ(set_input_return\(\))p FN(.)0 1420 y FD(add_menu)p FJ(\()p FK(type)o(,)h(x,)j(y)-5 b(,)20 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 1520 y FN(Add)f(a)i(menu)e(object)h(to)g(the)g (form.)208 1620 y(Methods:)k FJ(set_menu\(\))p FN(,)19 b FJ(get_menu\(\))p FN(,)f FJ(addto_menu\(\))p FN(.)0 1766 y FD(add_choice)p FJ(\()p FK(type)o(,)g(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 1866 y FN(Add)f(a)i (choice)e(object)h(to)g(the)h(form.)208 1966 y(Methods:)j FJ(set_choice\(\))p FN(,)18 b FJ(get_choice\(\))p FN(,)g FJ(clear_choice\(\))p FN(,)g FJ(addto_choice\(\))p FN(,)208 2065 y FJ(replace_choice\(\))p FN(,)f FJ(delete_choice\(\))p FN(,)h FJ(get_choice_text\(\))p FN(,)f FJ(set_choice_fontsize\(\))p FN(,)208 2165 y FJ(set_choice_fontstyle\(\))p FN(.)0 2312 y FD(add_browser)p FJ(\()p FK(type)o(,)h(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 2411 y FN(Add)f(a)i(bro)n (wser)e(object)h(to)g(the)g(form.)208 2511 y(Methods:)k FJ(set_browser_topline\(\))p FN(,)17 b FJ(clear_browser\(\))p FN(,)g FJ(add_browser_line\(\))p FN(,)208 2611 y FJ(addto_browser\(\))p FN(,)g FJ(insert_browser_line\(\))p FN(,)g FJ(delete_browser_line\(\))p FN(,)208 2710 y FJ(replace_browser_line\(\))p FN(,)f FJ(get_browser_line\(\))p FN(,)h FJ(load_browser\(\))p FN(,)208 2810 y FJ(get_browser_maxline\(\))p FN(,)f FJ (select_browser_line\(\))p FN(,)h FJ(deselect_browser_line\(\))p FN(,)208 2910 y FJ(deselect_browser\(\))p FN(,)g FJ (isselected_browser_line\(\))p FN(,)f FJ(get_browser\(\))p FN(,)208 3009 y FJ(set_browser_fontsize\(\))p FN(,)g FJ(set_browser_fontstyle\(\))p FN(,)g FJ(set_browser_specialkey\(\))p FN(.)0 3156 y FD(add_timer)p FJ(\()p FK(type)o(,)i(x,)i(y)-5 b(,)21 b(w)-6 b(,)21 b(h,)f(name)p FJ(\))208 3256 y FN(Add)f(a)i(timer) f(object)g(to)g(the)g(form.)208 3355 y(Methods:)k FJ(set_timer\(\))p FN(,)18 b FJ(get_timer\(\))p FN(.)0 3566 y(F)o(orm)h(objects)h(ha)n(v)o (e)g(the)g(follo)n(wing)f(data)h(attrib)n(utes;)g(see)h(the)f(FORMS)h (documentation:)828 3774 y FL(Name)p 1424 3804 4 100 v 439 w(C)g(T)-6 b(ype)p 2005 3804 V 327 w(Meaning)p 778 3807 2345 4 v 828 3877 a FJ(window)p 1424 3907 4 100 v 347 w FN(int)21 b(\(read-only\))p 2005 3907 V 96 w(GL)f(windo)n(w)f(id)828 3976 y FJ(w)p 1424 4006 V 597 w FN(\003oat)p 2005 4006 V 434 w(form)g(width)828 4076 y FJ(h)p 1424 4106 V 597 w FN(\003oat)p 2005 4106 V 434 w(form)g(height)828 4176 y FJ(x)p 1424 4205 V 597 w FN(\003oat)p 2005 4205 V 434 w(form)g(x)h(origin)828 4275 y FJ(y)p 1424 4305 V 597 w FN(\003oat)p 2005 4305 V 434 w(form)f(y)h(origin)828 4375 y FJ(deactivated)p 1424 4405 V 97 w FN(int)p 2005 4405 V 494 w(nonzero)e(if)i(form)g(is)h(deacti)n(v)n(ated)828 4474 y FJ(visible)p 1424 4504 V 297 w FN(int)p 2005 4504 V 494 w(nonzero)d(if)i(form)g(is)h(visible)828 4574 y FJ(frozen)p 1424 4604 V 347 w FN(int)p 2005 4604 V 494 w(nonzero)d(if)i(form)g(is)h(frozen)828 4674 y FJ(doublebuf)p 1424 4704 V 197 w FN(int)p 2005 4704 V 494 w(nonzero)d(if)i(double)f(b) n(uf)n(fering)f(on)0 4951 y Fv(34.4.3)101 b(FORMS)27 b(Objects)0 5154 y FN(Besides)20 b(methods)f(speci\002c)h(to)g (particular)e(kinds)h(of)h(FORMS)g(objects,)g(all)g(FORMS)g(objects)g (also)g(ha)n(v)o(e)f(the)h(follo)n(wing)e(methods:)0 5300 y FD(set_call_back)p FJ(\()p FK(function,)e(ar)m(gument)q FJ(\))208 5400 y FN(Set)h(the)g(object')-5 b(s)17 b(callback)g (function)e(and)i(ar)o(gument.)k(When)c(the)g(object)g(needs)g (interaction,)f(the)h(callback)f(function)g(will)i(be)p 0 5549 3901 4 v 0 5649 a FI(922)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 923 935 TeXDict begin 923 934 bop 208 83 a FN(called)19 b(with)g(tw)o(o)h(ar)o (guments:)j(the)c(object,)g(and)g(the)h(callback)e(ar)o(gument.)23 b(\(FORMS)d(objects)f(without)g(a)h(callback)e(function)208 183 y(are)25 b(returned)f(by)h FJ(fl.do_forms\(\))e FN(or)j FJ(fl.check_forms\(\))d FN(when)i(the)o(y)f(need)h(interaction.\))39 b(Call)27 b(this)f(method)208 282 y(without)19 b(ar)o(guments)f(to)i (remo)o(v)o(e)f(the)h(callback)f(function.)0 429 y FD(delete_object)p FJ(\(\))208 529 y FN(Delete)h(the)g(object.)0 676 y FD(show_object)p FJ(\(\))208 775 y FN(Sho)n(w)f(the)i(object.)0 922 y FD(hide_object)p FJ(\(\))208 1022 y FN(Hide)f(the)g(object.)0 1169 y FD(redraw_object)p FJ(\(\))208 1268 y FN(Redra)o(w)f(the)h (object.)0 1415 y FD(freeze_object)p FJ(\(\))208 1515 y FN(Freeze)g(the)g(object.)0 1662 y FD(unfreeze_object)p FJ(\(\))208 1761 y FN(Unfreeze)f(the)h(object.)0 1908 y(FORMS)h(objects)f(ha)n(v)o(e)g(these)g(data)g(attrib)n(utes;)g(see)h (the)f(FORMS)i(documentation:)1042 2134 y FL(Name)p 1588 2164 4 100 v 390 w(C)f(T)-6 b(ype)p 2170 2164 V 326 w(Meaning)p 992 2168 1916 4 v 1042 2237 a FJ(objclass)p 1588 2267 4 100 v 198 w FN(int)20 b(\(read-only\))p 2170 2267 V 96 w(object)g(class)1042 2337 y FJ(type)p 1588 2367 V 398 w FN(int)g(\(read-only\))p 2170 2367 V 96 w(object)g(type)1042 2437 y FJ(boxtype)p 1588 2466 V 248 w FN(int)p 2170 2466 V 493 w(box)g(type)1042 2536 y FJ(x)p 1588 2566 V 548 w FN(\003oat)p 2170 2566 V 433 w(x)h(origin)1042 2636 y FJ(y)p 1588 2666 V 548 w FN(\003oat)p 2170 2666 V 433 w(y)g(origin)1042 2735 y FJ(w)p 1588 2765 V 548 w FN(\003oat)p 2170 2765 V 433 w(width)1042 2835 y FJ(h)p 1588 2865 V 548 w FN(\003oat)p 2170 2865 V 433 w(height)1042 2935 y FJ(col1)p 1588 2965 V 398 w FN(int)p 2170 2965 V 493 w(primary)e(color)1042 3034 y FJ(col2)p 1588 3064 V 398 w FN(int)p 2170 3064 V 493 w(secondary)g(color)1042 3134 y FJ(align)p 1588 3164 V 348 w FN(int)p 2170 3164 V 493 w(alignment)1042 3234 y FJ(lcol)p 1588 3264 V 398 w FN(int)p 2170 3264 V 493 w(label)i(color)1042 3333 y FJ(lsize)p 1588 3363 V 348 w FN(\003oat)p 2170 3363 V 433 w(label)g(font)e(size) 1042 3433 y FJ(label)p 1588 3463 V 348 w FN(string)p 2170 3463 V 391 w(label)i(string)1042 3532 y FJ(lstyle)p 1588 3562 V 298 w FN(int)p 2170 3562 V 493 w(label)g(style)1042 3632 y FJ(pushed)p 1588 3662 V 298 w FN(int)f(\(read-only\))p 2170 3662 V 96 w(\(see)h(FORMS)g(docs\))1042 3732 y FJ(focus)p 1588 3762 V 348 w FN(int)f(\(read-only\))p 2170 3762 V 96 w(\(see)h(FORMS)g(docs\))1042 3831 y FJ(belowmouse)p 1588 3861 V 98 w FN(int)f(\(read-only\))p 2170 3861 V 96 w(\(see)h(FORMS)g(docs\))1042 3931 y FJ(frozen)p 1588 3961 V 298 w FN(int)f(\(read-only\))p 2170 3961 V 96 w(\(see)h(FORMS)g(docs\))1042 4031 y FJ(active)p 1588 4061 V 298 w FN(int)f(\(read-only\))p 2170 4061 V 96 w(\(see)h(FORMS)g(docs\))1042 4130 y FJ(input)p 1588 4160 V 348 w FN(int)f(\(read-only\))p 2170 4160 V 96 w(\(see)h(FORMS)g(docs\))1042 4230 y FJ(visible)p 1588 4260 V 248 w FN(int)f(\(read-only\))p 2170 4260 V 96 w(\(see)h(FORMS)g(docs\))1042 4330 y FJ(radio)p 1588 4359 V 348 w FN(int)f(\(read-only\))p 2170 4359 V 96 w(\(see)h(FORMS)g(docs\))1042 4429 y FJ(automatic)p 1588 4459 V 148 w FN(int)f(\(read-only\))p 2170 4459 V 96 w(\(see)h(FORMS)g(docs\))0 4816 y FE(34.5)121 b Fx(FL)33 b FE(\227)g(Constants)i(used)g(with)e(the)i Fx(fl)d FE(module)0 5049 y FN(This)19 b(module)e(de\002nes)i(symbolic)e(constants)h(needed) g(to)h(use)f(the)h(b)n(uilt-in)f(module)f FJ(fl)i FN(\(see)g(abo)o(v)o (e\);)e(the)o(y)h(are)h(equi)n(v)n(alent)e(to)i(those)0 5149 y(de\002ned)h(in)h(the)g(C)h(header)e(\002le)h FJ(<forms.h>)f FN(e)o(xcept)g(that)h(the)g(name)g(pre\002x)f(`)p FJ(FL_)p FN(')g(is)i(omitted.)27 b(Read)21 b(the)g(module)f(source)g(for)g(a)0 5249 y(complete)f(list)i(of)f(the)h(de\002ned)e(names.)24 b(Suggested)19 b(use:)p 0 5549 3901 4 v 0 5649 a FI(34.5.)52 b FJ(FL)23 b FI(\227)g(Constants)g(used)g(with)h(the)f FJ(fl)g FI(module)1994 b(923)p eop end %%Page: 924 936 TeXDict begin 924 935 bop 236 174 a FA(import)44 b(fl)236 266 y(from)g(FL)h(import)909 279 y(*)0 712 y FE(34.6)121 b Fx(flp)33 b FE(\227)f(Functions)j(f)l(or)f(loading)h(stored)f(FORMS)f (designs)0 945 y FN(This)26 b(module)f(de\002nes)h(functions)f(that)h (can)g(read)g(form)f(de\002nitions)g(created)g(by)h(the)g(`form)f (designer')g(\()p FL(fdesign)p FN(\))g(program)f(that)0 1045 y(comes)c(with)g(the)g(FORMS)i(library)d(\(see)h(module)f FJ(fl)h FN(abo)o(v)o(e\).)0 1192 y(F)o(or)g(no)n(w)-5 b(,)19 b(see)i(the)f(\002le)h(`)p FO(\003p)m(.doc)p FN(')e(in)i(the)f (Python)f(library)g(source)g(directory)g(for)g(a)i(description.)0 1339 y(XXX)g(A)f(complete)f(description)g(should)g(be)h(inserted)g (here!)0 1664 y FE(34.7)121 b Fx(fm)33 b FE(\227)g Fb(F)l(ont)i (Manager)g FE(interf)l(ace)0 1897 y FN(This)25 b(module)f(pro)o(vides)g (access)i(to)f(the)g(IRIS)h FK(F)-9 b(ont)25 b(Mana)o(g)o(er)f FN(library)-5 b(.)79 b(It)26 b(is)g(a)n(v)n(ailable)f(only)f(on)h (Silicon)g(Graphics)g(machines.)0 1996 y(See)c(also:)k FK(4Sight)19 b(User')m(s)i(Guide)p FN(,)e(section)h(1,)g(chapter)f(5:) 26 b(\223Using)20 b(the)g(IRIS)g(F)o(ont)g(Manager)-5 b(.)f(\224)0 2143 y(This)17 b(is)g(not)f(yet)h(a)g(full)f(interf)o(ace) g(to)g(the)h(IRIS)g(F)o(ont)f(Manager)-5 b(.)23 b(Among)15 b(the)h(unsupported)e(features)i(are:)23 b(matrix)16 b(operations;)g(cache)0 2243 y(operations;)27 b(character)e(operations) f(\(use)i(string)f(operations)g(instead\);)j(some)e(details)g(of)g (font)f(info;)j(indi)n(vidual)c(glyph)h(metrics;)0 2342 y(and)20 b(printer)f(matching.)0 2489 y(It)h(supports)g(the)g(follo)n (wing)e(operations:)0 2636 y FD(init)p FJ(\(\))208 2736 y FN(Initialization)25 b(function.)43 b(Calls)28 b FJ(fminit\(\))p FN(.)43 b(It)27 b(is)h(normally)d(not)h(necessary)g(to)h(call)g(this)g (function,)g(since)g(it)g(is)h(called)208 2835 y(automatically)18 b(the)i(\002rst)h(time)g(the)f FJ(fm)g FN(module)f(is)i(imported.)0 2982 y FD(findfont)p FJ(\()p FK(fontname)p FJ(\))208 3082 y FN(Return)e(a)i(font)e(handle)h(object.)k(Calls)d FJ(fmfindfont\()p FK(fontname)p FJ(\))p FN(.)0 3229 y FD(enumerate)p FJ(\(\))208 3328 y FN(Returns)f(a)g(list)h(of)f(a)n(v)n (ailable)g(font)g(names.)k(This)d(is)g(an)f(interf)o(ace)f(to)i FJ(fmenumerate\(\))p FN(.)0 3475 y FD(prstr)p FJ(\()p FK(string)p FJ(\))208 3575 y FN(Render)55 b(a)h(string)g(using)g(the)g (current)e(font)i(\(see)g(the)g FJ(setfont\(\))f FN(font)g(handle)g (method)g(belo)n(w\).)131 b(Calls)208 3675 y FJ(fmprstr\()p FK(string)p FJ(\))p FN(.)0 3821 y FD(setpath)p FJ(\()p FK(string)p FJ(\))208 3921 y FN(Sets)21 b(the)f(font)f(search)h(path.) 25 b(Calls)c FJ(fmsetpath\()p FK(string)p FJ(\))p FN(.)i(\(XXX)e(Does)f (not)g(w)o(ork!?!\))0 4068 y FD(fontpath)p FJ(\(\))208 4168 y FN(Returns)g(the)g(current)f(font)g(search)h(path.)0 4314 y(F)o(ont)g(handle)f(objects)h(support)f(the)h(follo)n(wing)e (operations:)0 4461 y FD(scalefont)p FJ(\()p FK(factor)r FJ(\))208 4561 y FN(Returns)i(a)g(handle)f(for)h(a)g(scaled)h(v)o (ersion)e(of)h(this)g(font.)k(Calls)e FJ(fmscalefont\()p FK(fh)p FJ(,)47 b FK(factor)r FJ(\))p FN(.)0 4708 y FD(setfont)p FJ(\(\))208 4807 y FN(Mak)o(es)18 b(this)i(font)e(the)g(current)g (font.)24 b(Note:)g(the)19 b(ef)n(fect)f(is)i(undone)c(silently)j(when) f(the)h(font)f(handle)g(object)g(is)i(deleted.)j(Calls)208 4907 y FJ(fmsetfont\()p FK(fh)p FJ(\))p FN(.)0 5054 y FD(getfontname)p FJ(\(\))208 5154 y FN(Returns)d(this)g(font')-5 b(s)20 b(name.)25 b(Calls)c FJ(fmgetfontname\()p FK(fh)p FJ(\))p FN(.)0 5300 y FD(getcomment)p FJ(\(\))208 5400 y FN(Returns)46 b(the)h(comment)f(string)g(associated)h(with)g(this)h (font.)104 b(Raises)49 b(an)d(e)o(xception)g(if)h(there)f(is)i(none.) 104 b(Calls)p 0 5549 3901 4 v 0 5649 a FI(924)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 925 937 TeXDict begin 925 936 bop 208 83 a FJ(fmgetcomment\()p FK(fh)p FJ(\))p FN(.)0 230 y FD(getfontinfo)p FJ(\(\))208 330 y FN(Returns)24 b(a)g(tuple)g(gi)n(ving)f(some)h(pertinent)e(data)i (about)g(this)g(font.)36 b(This)25 b(is)g(an)f(interf)o(ace)f(to)h FJ(fmgetfontinfo\(\))p FN(.)35 b(The)208 429 y(returned)20 b(tuple)h(contains)h(the)g(follo)n(wing)e(numbers:)27 b FJ(\()p FK(printermatc)o(hed)r FN(,)21 b FK(\002xed)p 2570 429 25 4 v 28 w(width)p FN(,)i FK(xorig)p FN(,)f FK(yorig)p FN(,)g FK(xsize)p FN(,)h FK(ysize)p FN(,)g FK(height)q FN(,)208 529 y FK(nglyphs)p FJ(\))p FN(.)0 676 y FD(getstrwidth)p FJ(\()p FK(string)p FJ(\))208 775 y FN(Returns)d(the)g(width,)f(in)i(pix)o(els,)e(of)h FK(string)h FN(when)e(dra)o(wn)g(in)i(this)f(font.)25 b(Calls)c FJ(fmgetstrwidth\()p FK(fh)p FJ(,)47 b FK(string)p FJ(\))p FN(.)0 1103 y FE(34.8)121 b Fx(gl)33 b FE(\227)g Fb(Gr)o(aphics)g(Libr)o(ar)t(y)g FE(interf)l(ace)0 1336 y FN(This)g(module)e(pro)o(vides)f(access)j(to)g(the)f(Silicon)g (Graphics)g FK(Gr)o(aphics)g(Libr)o(ary)p FN(.)61 b(It)33 b(is)h(a)n(v)n(ailable)d(only)h(on)g(Silicon)g(Graphics)0 1435 y(machines.)0 1582 y FL(W)-5 b(ar)o(ning:)23 b FN(Some)18 b(ille)o(gal)f(calls)i(to)f(the)g(GL)g(library)f(cause)h(the)g(Python)f (interpreter)f(to)i(dump)f(core.)23 b(In)18 b(particular)m(,)f(the)h (use)g(of)g(most)0 1682 y(GL)i(calls)h(is)g(unsafe)f(before)f(the)h (\002rst)h(windo)n(w)e(is)i(opened.)0 1829 y(The)16 b(module)f(is)i (too)f(lar)o(ge)g(to)g(document)f(here)h(in)g(its)i(entirety)-5 b(,)15 b(b)n(ut)i(the)f(follo)n(wing)f(should)g(help)h(you)g(to)g(get)g (started.)24 b(The)16 b(parameter)0 1928 y(con)m(v)o(entions)h(for)j (the)g(C)h(functions)e(are)h(translated)g(to)g(Python)f(as)i(follo)n (ws:)125 2158 y FM(\017)41 b FN(All)20 b(\(short,)g(long,)f(unsigned\)) f(int)i(v)n(alues)g(are)g(represented)f(by)g(Python)g(inte)o(gers.)125 2324 y FM(\017)41 b FN(All)25 b(\003oat)h(and)e(double)g(v)n(alues)g (are)h(represented)f(by)g(Python)g(\003oating)g(point)h(numbers.)38 b(In)25 b(most)g(cases,)h(Python)e(inte)o(gers)208 2424 y(are)c(also)g(allo)n(wed.)125 2590 y FM(\017)41 b FN(All)20 b(arrays)g(are)g(represented)f(by)g(one-dimensional)e(Python)i(lists.) 27 b(In)20 b(most)g(cases,)h(tuples)f(are)g(also)g(allo)n(wed.)125 2756 y FM(\017)41 b FN(All)16 b(string)g(and)f(character)f(ar)o (guments)g(are)i(represented)e(by)h(Python)g(strings,)h(for)g (instance,)g FJ(winopen\('Hi)47 b(There!'\))208 2855 y FN(and)19 b FJ(rotate\(900,)48 b('z'\))p FN(.)125 3021 y FM(\017)41 b FN(All)19 b(\(short,)f(long,)g(unsigned\))f(inte)o(ger)g (ar)o(guments)g(or)i(return)e(v)n(alues)i(that)f(are)h(only)f(used)h (to)g(specify)f(the)g(length)g(of)h(an)f(array)208 3121 y(ar)o(gument)f(are)k(omitted.)j(F)o(or)c(e)o(xample,)e(the)i(C)h(call) 444 3345 y FA(lmdef\(deftype,)42 b(index,)i(np,)g(props\))208 3618 y FN(is)21 b(translated)e(to)i(Python)e(as)444 3842 y FA(lmdef\(deftype,)42 b(index,)i(props\))125 4148 y FM(\017)d FN(Output)21 b(ar)o(guments)g(are)h(omitted)g(from)g(the)g (ar)o(gument)e(list;)25 b(the)o(y)d(are)h(transmitted)e(as)j(function)c (return)i(v)n(alues)g(instead.)32 b(If)208 4247 y(more)25 b(than)g(one)g(v)n(alue)g(must)h(be)g(returned,)f(the)h(return)e(v)n (alue)i(is)g(a)h(tuple.)41 b(If)26 b(the)f(C)i(function)d(has)i(both)f (a)i(re)o(gular)d(return)208 4347 y(v)n(alue)e(\(that)g(is)i(not)f (omitted)f(because)g(of)h(the)g(pre)n(vious)e(rule\))h(and)h(an)g (output)e(ar)o(gument,)g(the)i(return)f(v)n(alue)g(comes)h(\002rst)g (in)208 4446 y(the)d(tuple.)k(Examples:)h(the)20 b(C)h(call)444 4671 y FA(getmcolor\(i,)43 b(&red,)h(&green,)f(&blue\))208 4943 y FN(is)21 b(translated)e(to)i(Python)e(as)444 5167 y FA(red,)44 b(green,)g(blue)g(=)h(getmcolor\(i\))p 0 5549 3901 4 v 0 5649 a FI(34.8.)52 b FJ(gl)23 b FI(\227)g Fa(Gr)o(aphics)f(Libr)o(ar)r(y)i FI(interf)n(ace)2348 b(925)p eop end %%Page: 926 938 TeXDict begin 926 937 bop 0 83 a FN(The)20 b(follo)n(wing)e(functions)h (are)h(non-standard)d(or)j(ha)n(v)o(e)g(special)g(ar)o(gument)e(con)m (v)o(entions:)0 230 y FD(varray)p FJ(\()p FK(ar)m(gument)q FJ(\))208 330 y FN(Equi)n(v)n(alent)j(to)i(b)n(ut)h(f)o(aster)f(than)g (a)h(number)d(of)i FJ(v3d\(\))g FN(calls.)35 b(The)23 b FK(ar)m(gument)h FN(is)g(a)g(list)g(\(or)f(tuple\))g(of)g(points.)33 b(Each)23 b(point)208 429 y(must)18 b(be)g(a)g(tuple)g(of)g (coordinates)e FJ(\()p FK(x)p FJ(,)49 b FK(y)p FJ(,)h FK(z)p FJ(\))19 b FN(or)e FJ(\()p FK(x)p FJ(,)50 b FK(y)p FJ(\))p FN(.)24 b(The)18 b(points)g(may)f(be)h(2-)g(or)g(3-dimensional) d(b)n(ut)j(must)h(all)f(ha)n(v)o(e)208 529 y(the)h(same)g(dimension.)k (Float)c(and)g(int)g(v)n(alues)f(may)h(be)g(mix)o(ed)f(ho)n(we)n(v)o (er)-5 b(.)23 b(The)18 b(points)h(are)g(al)o(w)o(ays)g(con)m(v)o(erted) e(to)i(3D)g(double)208 628 y(precision)h(points)i(by)f(assuming)g FK(z)50 b FJ(=)g(0.0)21 b FN(if)h(necessary)f(\(as)i(indicated)d(in)i (the)g(man)f(page\),)g(and)g(for)g(each)h(point)f FJ(v3d\(\))208 728 y FN(is)g(called.)0 875 y FD(nvarray)p FJ(\(\))208 975 y FN(Equi)n(v)n(alent)g(to)j(b)n(ut)g(f)o(aster)g(than)f(a)h (number)e(of)i FJ(n3f)f FN(and)g FJ(v3f)h FN(calls.)36 b(The)24 b(ar)o(gument)d(is)k(an)e(array)g(\(list)i(or)e(tuple\))g(of)h (pairs)208 1074 y(of)c(normals)f(and)h(points.)26 b(Each)20 b(pair)g(is)i(a)f(tuple)f(of)g(a)h(point)f(and)g(a)h(normal)e(for)h (that)g(point.)26 b(Each)20 b(point)g(or)g(normal)f(must)i(be)208 1174 y(a)i(tuple)h(of)f(coordinates)e FJ(\()p FK(x)p FJ(,)50 b FK(y)p FJ(,)f FK(z)p FJ(\))p FN(.)36 b(Three)22 b(coordinates)g(must)i(be)f(gi)n(v)o(en.)34 b(Float)23 b(and)g(int)h(v)n(alues)f(may)g(be)g(mix)o(ed.)34 b(F)o(or)208 1273 y(each)19 b(pair)m(,)h FJ(n3f\(\))g FN(is)h(called)f(for)f(the)h (normal,)f(and)h(then)f FJ(v3f\(\))h FN(is)h(called)f(for)g(the)g (point.)0 1420 y FD(vnarray)p FJ(\(\))208 1520 y FN(Similar)g(to)g FJ(nvarray\(\))f FN(b)n(ut)h(the)h(pairs)f(ha)n(v)o(e)f(the)i(point)e (\002rst)i(and)f(the)g(normal)f(second.)0 1667 y FD(nurbssurface)p FJ(\()p FK(s)p 687 1667 25 4 v 28 w(k,)h(t)p 816 1667 V 30 w(k,)g(ctl,)h(s)p 1081 1667 V 30 w(or)m(d,)f(t)p 1288 1667 V 30 w(or)m(d,)g(type)p FJ(\))208 1766 y FN(De\002nes)38 b(a)h(nurbs)f(surf)o(ace.)80 b(The)38 b(dimensions)f(of)h FK(ctl)p FJ([][])h FN(are)f(computed)f(as)i(follo)n(ws:)62 b FJ([len\()p FK(s)p 3391 1766 V 29 w(k)q FJ(\))50 b(-)g FK(s)p 3690 1766 V 30 w(or)m(d)r FJ(])p FN(,)208 1866 y FJ([len\()p FK(t)p 486 1866 V 29 w(k)q FJ(\))f(-)h FK(t)p 775 1866 V 30 w(or)m(d)r FJ(])p FN(.)0 2013 y FD(nurbscurve)p FJ(\()p FK(knots,)18 b(ctlpoints,)h(or)m(der)-9 b(,)20 b(type)p FJ(\))208 2113 y FN(De\002nes)g(a)h(nurbs)e(curv)o(e.)k (The)d(length)g(of)f(ctlpoints)h(is)h FJ(len\()p FK(knots)p FJ(\))49 b(-)g FK(or)m(der)r FN(.)0 2259 y FD(pwlcurve)p FJ(\()p FK(points,)18 b(type)p FJ(\))208 2359 y FN(De\002nes)i(a)h (piece)n(wise-linear)d(curv)o(e.)24 b FK(points)c FN(is)h(a)f(list)i (of)e(points.)k FK(type)c FN(must)g(be)h FJ(N_ST)p FN(.)0 2506 y FD(pick)p FJ(\()p FK(n)p FJ(\))0 2606 y FD(select)p FJ(\()p FK(n)p FJ(\))208 2705 y FN(The)e(only)h(ar)o(gument)e(to)i (these)g(functions)f(speci\002es)i(the)f(desired)f(size)i(of)f(the)g (pick)g(or)g(select)h(b)n(uf)n(fer)-5 b(.)0 2852 y FD(endpick)p FJ(\(\))0 2952 y FD(endselect)p FJ(\(\))208 3051 y FN(These)23 b(functions)g(ha)n(v)o(e)g(no)g(ar)o(guments.)34 b(The)o(y)23 b(return)g(a)h(list)h(of)f(inte)o(gers)f(representing)e(the)j(used)g (part)f(of)h(the)g(pick/select)208 3151 y(b)n(uf)n(fer)-5 b(.)24 b(No)c(method)f(is)i(pro)o(vided)c(to)k(detect)f(b)n(uf)n(fer)f (o)o(v)o(errun.)0 3298 y(Here)h(is)h(a)g(tin)o(y)f(b)n(ut)g(complete)f (e)o(xample)g(GL)h(program)e(in)i(Python:)p 0 5549 3901 4 v 0 5649 a FI(926)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 927 939 TeXDict begin 927 938 bop 236 174 a FA(import)44 b(gl,)g(GL,)h(time)236 357 y(def)g(main\(\):)416 448 y(gl.foreground\(\))416 540 y(gl.prefposition\(500,)c(900,)j(500,)g(900\))416 631 y(w)g(=)h(gl.winopen\('CrissCross'\))416 722 y(gl.ortho2\(0.0,)d (400.0,)i(0.0,)g(400.0\))416 814 y(gl.color\(GL.WHITE\))416 905 y(gl.clear\(\))416 996 y(gl.color\(GL.RED\))416 1088 y(gl.bgnline\(\))416 1179 y(gl.v2f\(0.0,)f(0.0\))416 1270 y(gl.v2f\(400.0,)f(400.0\))416 1362 y(gl.endline\(\))416 1453 y(gl.bgnline\(\))416 1544 y(gl.v2f\(400.0,)g(0.0\))416 1636 y(gl.v2f\(0.0,)h(400.0\))416 1727 y(gl.endline\(\))416 1818 y(time.sleep\(5\))236 2001 y(main\(\))0 2288 y FL(See)21 b(Also:)0 2435 y FK(PyOpenGL:)e(The)h(Python)f(OpenGL)h(Binding)0 2534 y Fy(\()p FO(http://p)n(y)o(opengl.sour)o(cef)n(o)o(rge)n(.ne)o (t/)-6 b Fy(\))208 2634 y FN(An)51 b(interf)o(ace)g(to)i(OpenGL)d(is)j (also)f(a)n(v)n(ailable;)68 b(see)52 b(information)e(about)h(the)h FL(PyOpenGL)f FN(project)g(online)g(at)208 2734 y FO(http://p)n(y)o (opengl.sou)o(rcef)n(o)o(rg)o(e)o(.n)o(et/)-7 b FN(.)50 b(This)28 b(may)g(be)g(a)h(better)f(option)f(if)i(support)d(for)i(SGI)h (hardw)o(are)d(from)i(before)f(about)208 2833 y(1996)18 b(is)j(not)f(required.)0 3161 y FE(34.9)121 b Fx(DEVICE)32 b FE(\227)h(Constants)i(used)f(with)g(the)h Fx(gl)d FE(module)0 3394 y FN(This)c(modules)e(de\002nes)h(the)h(constants)f(used)g(by)g (the)g(Silicon)g(Graphics)g FK(Gr)o(aphics)g(Libr)o(ary)g FN(that)h(C)g(programmers)d(\002nd)i(in)h(the)0 3493 y(header)19 b(\002le)i FJ(<gl/device.h>)p FN(.)i(Read)d(the)g(module)f (source)h(\002le)h(for)e(details.)0 3821 y FE(34.10)122 b Fx(GL)32 b FE(\227)h(Constants)j(used)e(with)g(the)g Fx(gl)f FE(module)0 4053 y FN(This)23 b(module)e(contains)h(constants)g (used)h(by)f(the)g(Silicon)h(Graphics)f FK(Gr)o(aphics)g(Libr)o(ary)g FN(from)g(the)h(C)g(header)f(\002le)h FJ(<gl/gl.h>)p FN(.)0 4153 y(Read)d(the)h(module)d(source)i(\002le)h(for)e(details.)0 4480 y FE(34.11)122 b Fx(imgfile)31 b FE(\227)i(Suppor)5 b(t)34 b(f)l(or)h(SGI)e(imglib)f(\002les)0 4713 y FN(The)27 b FJ(imgfile)f FN(module)f(allo)n(ws)j(Python)e(programs)f(to)i(access) g(SGI)h(imglib)e(image)g(\002les)i(\(also)f(kno)n(wn)f(as)h(`)p FO(.rgb)p FN(')f(\002les\).)46 b(The)0 4813 y(module)30 b(is)j(f)o(ar)f(from)f(complete,)i(b)n(ut)f(is)h(pro)o(vided)c(an)o(yw) o(ay)h(since)i(the)g(functionality)e(that)i(there)f(is)i(enough)c(in)j (some)g(cases.)0 4913 y(Currently)-5 b(,)18 b(colormap)h(\002les)i(are) f(not)g(supported.)0 5059 y(The)g(module)f(de\002nes)h(the)g(follo)n (wing)e(v)n(ariables)i(and)f(functions:)0 5206 y FL(exception)g FD(error)208 5306 y FN(This)h(e)o(xception)e(is)j(raised)f(on)g(all)h (errors,)e(such)h(as)h(unsupported)c(\002le)k(type,)e(etc.)p 0 5549 3901 4 v 0 5649 a FI(34.9.)52 b FJ(DEVICE)22 b FI(\227)h(Constants)g(used)g(with)h(the)f FJ(gl)g FI(module)1795 b(927)p eop end %%Page: 928 940 TeXDict begin 928 939 bop 0 83 a FD(getsizes)p FJ(\()p FK(\002le)p FJ(\))208 183 y FN(This)22 b(function)f(returns)g(a)i (tuple)f FJ(\()p FK(x)p FJ(,)49 b FK(y)p FJ(,)h FK(z)p FJ(\))23 b FN(where)e FK(x)i FN(and)f FK(y)h FN(are)f(the)g(size)h(of)f (the)h(image)e(in)i(pix)o(els)f(and)g FK(z)h FN(is)g(the)f(number)208 282 y(of)d(bytes)h(per)g(pix)o(el.)25 b(Only)19 b(3)i(byte)e(RGB)j(pix) o(els)e(and)f(1)i(byte)e(gre)o(yscale)g(pix)o(els)h(are)g(currently)f (supported.)0 429 y FD(read)p FJ(\()p FK(\002le)p FJ(\))208 529 y FN(This)h(function)e(reads)i(and)g(decodes)f(the)h(image)f(on)h (the)g(speci\002ed)g(\002le,)g(and)g(returns)f(it)i(as)g(a)f(Python)f (string.)25 b(The)20 b(string)f(has)208 628 y(either)g(1)h(byte)f(gre)o (yscale)g(pix)o(els)h(or)f(4)h(byte)g(RGB)m(A)h(pix)o(els.)j(The)c (bottom)e(left)j(pix)o(el)e(is)i(the)f(\002rst)g(in)g(the)g(string.)25 b(This)20 b(format)208 728 y(is)h(suitable)f(to)g(pass)h(to)f FJ(gl.lrectwrite\(\))p FN(,)e(for)h(instance.)0 875 y FD(readscaled)p FJ(\()p FK(\002le)o(,)f(x,)i(y)-5 b(,)21 b(\002lter)r FC([)p FK(,)f(blur)14 b FC(])p FJ(\))208 975 y FN(This)20 b(function)f(is)i(identical)f(to)h(read)f(b)n(ut)g(it) i(returns)d(an)i(image)f(that)g(is)i(scaled)e(to)h(the)f(gi)n(v)o(en)g FK(x)h FN(and)f FK(y)h FN(sizes.)26 b(If)21 b(the)f FK(\002lter)j FN(and)208 1074 y FK(blur)h FN(parameters)e(are)g(omitted)g(scaling)h (is)g(done)f(by)g(simply)h(dropping)d(or)i(duplicating)f(pix)o(els,)i (so)g(the)g(result)f(will)i(be)e(less)208 1174 y(than)d(perfect,)g (especially)h(for)g(computer)n(-generated)c(images.)208 1307 y(Alternati)n(v)o(ely)-5 b(,)23 b(you)g(can)h(specify)g(a)h (\002lter)g(to)f(use)h(to)g(smooth)e(the)h(image)g(after)g(scaling.)38 b(The)24 b(\002lter)h(forms)e(supported)g(are)208 1406 y FJ('impulse')p FN(,)j FJ('box')p FN(,)i FJ('triangle')p FN(,)e FJ('quadratic')f FN(and)h FJ('gaussian')p FN(.)43 b(If)26 b(a)h(\002lter)g(is)h(speci\002ed)e FK(blur)i FN(is)g(an)208 1506 y(optional)18 b(parameter)h(specifying)g(the)h (blurriness)f(of)h(the)g(\002lter)-5 b(.)26 b(It)20 b(def)o(aults)g(to) h FJ(1.0)p FN(.)208 1639 y FJ(readscaled\(\))d FN(mak)o(es)i(no)g (attempt)g(to)g(k)o(eep)g(the)g(aspect)g(ratio)g(correct,)f(so)i(that)f (is)h(the)f(users')g(responsibility)-5 b(.)0 1786 y FD(ttob)p FJ(\()p FK(\003a)o(g)p FJ(\))208 1885 y FN(This)16 b(function)f(sets)j (a)f(global)f(\003ag)h(which)f(de\002nes)g(whether)g(the)h(scan)f (lines)h(of)g(the)f(image)h(are)f(read)g(or)h(written)f(from)g(bottom) 208 1985 y(to)j(top)g(\(\003ag)f(is)i(zero,)f(compatible)f(with)h(SGI)g (GL\))g(or)g(from)f(top)h(to)g(bottom\(\003ag)e(is)j(one,)f(compatible) e(with)j(X\).)f(The)f(def)o(ault)208 2084 y(is)j(zero.)0 2231 y FD(write)p FJ(\()p FK(\002le)o(,)e(data,)g(x,)i(y)-5 b(,)20 b(z)p FJ(\))208 2331 y FN(This)h(function)e(writes)i(the)g(RGB)h (or)e(gre)o(yscale)g(data)h(in)g FK(data)f FN(to)h(image)f(\002le)h FK(\002le)p FN(.)27 b FK(x)22 b FN(and)e FK(y)h FN(gi)n(v)o(e)f(the)h (size)g(of)g(the)g(image,)f FK(z)i FN(is)208 2431 y(1)g(for)g(1)g(byte) g(gre)o(yscale)f(images)h(or)g(3)g(for)g(RGB)h(images)f(\(which)g(are)g (stored)g(as)h(4)f(byte)g(v)n(alues)g(of)g(which)f(only)h(the)g(lo)n (wer)208 2530 y(three)d(bytes)h(are)g(used\).)25 b(These)20 b(are)g(the)g(formats)f(returned)g(by)h FJ(gl.lrectread\(\))p FN(.)0 2858 y FE(34.12)122 b Fx(jpeg)32 b FE(\227)h(Read)i(and)f(wr)r (ite)g(JPEG)e(\002les)0 3090 y FN(The)19 b(module)g FJ(jpeg)g FN(pro)o(vides)f(access)i(to)g(the)g(jpe)o(g)e(compressor)g(and)h (decompressor)f(written)h(by)g(the)h(Independent)d(JPEG)j(Group)0 3190 y(\(IJG\).)e(JPEG)h(is)g(a)f(standard)f(for)h(compressing)e (pictures;)j(it)g(is)g(de\002ned)e(in)h(ISO)h(10918.)j(F)o(or)c (details)h(on)f(JPEG)g(or)g(the)h(Independent)0 3290 y(JPEG)i(Group)e(softw)o(are)h(refer)f(to)h(the)g(JPEG)h(standard)e(or) h(the)h(documentation)c(pro)o(vided)g(with)k(the)f(softw)o(are.)0 3437 y(A)h(portable)e(interf)o(ace)h(to)h(JPEG)g(image)f(\002les)h(is)h (a)n(v)n(ailable)e(with)g(the)h(Python)e(Imaging)g(Library)g(\(PIL\))h (by)g(Fredrik)g(Lundh.)k(Infor)n(-)0 3536 y(mation)19 b(on)h(PIL)g(is)i(a)n(v)n(ailable)d(at)i FO(http://www)l(.p)n(ythonw)o (are)o(.co)o(m/pro)o(ducts/p)o(il/)-7 b FN(.)0 3683 y(The)20 b FJ(jpeg)g FN(module)f(de\002nes)h(an)g(e)o(xception)e(and)i(some)g (functions.)0 3830 y FL(exception)f FD(error)208 3930 y FN(Exception)f(raised)i(by)g FJ(compress\(\))f FN(and)g FJ(decompress\(\))g FN(in)h(case)h(of)f(errors.)0 4076 y FD(compress)p FJ(\()p FK(data,)d(w)-6 b(,)21 b(h,)f(b)p FJ(\))208 4176 y FN(T)m(reat)g(data)h(as)g(a)g(pixmap)f(of)g(width)h FK(w)g FN(and)f(height)g FK(h)p FN(,)h(with)g FK(b)g FN(bytes)f(per)g(pix)o(el.)26 b(The)21 b(data)f(is)i(in)f(SGI)g(GL)g (order)m(,)e(so)i(the)g(\002rst)208 4276 y(pix)o(el)e(is)j(in)e(the)h (lo)n(wer)n(-left)e(corner)-5 b(.)25 b(This)c(means)f(that)g FJ(gl.lrectread\(\))f FN(return)g(data)h(can)h(immediately)e(be)h (passed)g(to)208 4375 y FJ(compress\(\))p FN(.)30 b(Currently)21 b(only)g(1)i(byte)f(and)g(4)g(byte)g(pix)o(els)g(are)g(allo)n(wed,)g (the)h(former)e(being)g(treated)h(as)h(gre)o(yscale)e(and)208 4475 y(the)f(latter)g(as)h(RGB)g(color)-5 b(.)25 b FJ(compress\(\))19 b FN(returns)g(a)i(string)f(that)g(contains)f(the)i(compressed)d (picture,)h(in)i(JFIF)g(format.)0 4622 y FD(decompress)p FJ(\()p FK(data)p FJ(\))208 4721 y FN(Data)f(is)g(a)h(string)e (containing)f(a)i(picture)f(in)h(JFIF)h(format.)i(It)d(returns)f(a)h (tuple)g FJ(\()p FK(data)p FJ(,)48 b FK(width)p FJ(,)h FK(height)q FJ(,)g FK(bytesperpixel)p FJ(\))p FN(.)208 4821 y(Again,)19 b(the)h(data)g(is)h(suitable)f(to)g(pass)h(to)f FJ(gl.lrectwrite\(\))p FN(.)0 4968 y FD(setoption)p FJ(\()p FK(name)o(,)e(value)p FJ(\))208 5068 y FN(Set)i(v)n(arious)g(options.)k (Subsequent)18 b FJ(compress\(\))h FN(and)h FJ(decompress\(\))f FN(calls)i(will)g(use)f(these)h(options.)j(The)c(follo)n(w-)208 5167 y(ing)f(options)h(are)g(a)n(v)n(ailable:)p 0 5549 3901 4 v 0 5649 a FI(928)2291 b(Chapter)24 b(34.)52 b(SGI)23 b(IRIX)g(Speci\002c)g(Ser)r(vices)p eop end %%Page: 929 941 TeXDict begin 929 940 bop 830 70 a FL(Option)p 1426 100 4 100 v 398 w(Effect)p 780 103 2548 4 v 830 173 a FJ('forcegray')p 1426 203 4 100 v 98 w FN(F)o(orce)19 b(output)g(to)h(be)h(grayscale,)e (e)n(v)o(en)g(if)h(input)g(is)h(RGB.)830 272 y FJ('quality')p 1426 501 4 299 v 198 w FN(Set)g(the)f(quality)g(of)g(the)h(compressed)e (image)h(to)h(a)g(v)n(alue)f(be-)1478 372 y(tween)30 b FJ(0)h FN(and)f FJ(100)h FN(\(def)o(ault)f(is)h FJ(75)p FN(\).)57 b(This)31 b(only)e(af)n(fects)1478 472 y(compression.)830 571 y FJ('optimize')p 1426 800 V 148 w FN(Perform)k(Huf)n(fman)f(table) i(optimization.)66 b(T)-7 b(ak)o(es)35 b(longer)m(,)1478 671 y(b)n(ut)d(results)g(in)h(smaller)f(compressed)f(image.)61 b(This)32 b(only)1478 770 y(af)n(fects)19 b(compression.)830 870 y FJ('smooth')p 1426 1099 V 248 w FN(Perform)26 b(inter)n(-block)g (smoothing)g(on)h(uncompressed)e(im-)1478 970 y(age.)55 b(Only)29 b(useful)h(for)g(lo)n(w-quality)e(images.)55 b(This)31 b(only)1478 1069 y(af)n(fects)19 b(decompression.)0 1212 y FL(See)i(Also:)0 1359 y FK(JPEG)f(Still)h(Ima)o(g)o(e)e(Data)h (Compr)m(ession)g(Standar)m(d)208 1458 y FN(The)f(canonical)g (reference)g(for)g(the)i(JPEG)f(image)g(format,)f(by)h(Pennebak)o(er)e (and)i(Mitchell.)0 1605 y FK(Information)e(T)-8 b(ec)o(hnolo)o(gy)19 b(-)h(Digital)g(Compr)m(ession)g(and)f(Coding)h(of)g(Continuous-tone)d (Still)k(Ima)o(g)o(es)f(-)g(Requir)m(ements)f(and)h(Guidelines)0 1705 y Fy(\()p FO(http://www)l(.w3.org/Gr)o(aphi)o(cs/JPEG/itu-t)o(81.) o(pd)o(f)-6 b Fy(\))208 1805 y FN(The)19 b(ISO)i(standard)e(for)h(JPEG) g(is)i(also)e(published)f(as)i(ITU)f(T)-6 b(.81.)23 b(This)e(is)g(a)n (v)n(ailable)f(online)f(in)h(PDF)h(form.)p 0 5549 3901 4 v 0 5649 a FI(34.12.)52 b FJ(jpeg)23 b FI(\227)g(Read)g(and)h(wr)q (ite)g(JPEG)e(\002les)2181 b(929)p eop end %%Page: 930 942 TeXDict begin 930 941 bop 0 5549 3901 4 v 0 5649 a FI(930)p eop end %%Page: 931 943 TeXDict begin 931 942 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3205 427 y FG(THIR)n(TYFIVE)p 0 515 V 1598 978 a FT(SunOS)56 b(Speci\002c)i(Ser)6 b(vices)0 1465 y FN(The)18 b(modules)g(described)f (in)i(this)g(chapter)e(pro)o(vide)f(interf)o(aces)i(to)h(features)f (that)h(are)f(unique)f(to)i(SunOS)f(5)h(\(also)f(kno)n(wn)f(as)i (Solaris)0 1565 y(v)o(ersion)g(2\).)0 1892 y FE(35.1)121 b Fx(sunaudiodev)30 b FE(\227)j(Access)g(to)h(Sun)g(audio)g(hardw)n (are)0 2125 y FN(This)17 b(module)f(allo)n(ws)i(you)e(to)i(access)g (the)f(Sun)g(audio)f(interf)o(ace.)23 b(The)17 b(Sun)g(audio)g(hardw)o (are)f(is)i(capable)e(of)h(recording)e(and)i(playing)0 2224 y(back)g(audio)f(data)h(in)h(u-LA)-7 b(W)16 b(format)h(with)g(a)h (sample)f(rate)g(of)g(8K)h(per)f(second.)23 b(A)18 b(full)f (description)f(can)h(be)g(found)f(in)h(the)g FK(audio)p FN(\(7I\))0 2324 y(manual)i(page.)0 2471 y(The)h(module)f FJ(SUNAUDIODEV)f FN(de\002nes)i(constants)g(which)g(may)f(be)i(used)f (with)g(this)h(module.)0 2618 y(This)f(module)f(de\002nes)h(the)g (follo)n(wing)f(v)n(ariables)g(and)h(functions:)0 2765 y FL(exception)f FD(error)208 2864 y FN(This)h(e)o(xception)e(is)j (raised)f(on)g(all)h(errors.)j(The)c(ar)o(gument)e(is)j(a)f(string)g (describing)f(what)h(went)g(wrong.)0 3011 y FD(open)p FJ(\()p FK(mode)p FJ(\))208 3111 y FN(This)h(function)f(opens)h(the)g (audio)g(de)n(vice)f(and)h(returns)g(a)h(Sun)f(audio)f(de)n(vice)h (object.)28 b(This)22 b(object)f(can)g(then)g(be)g(used)g(to)h(do)208 3210 y(I/O)c(on.)24 b(The)18 b FK(mode)g FN(parameter)e(is)k(one)d(of)h FJ('r')h FN(for)e(record-only)f(access,)j FJ('w')f FN(for)g(play-only)e (access,)j FJ('rw')f FN(for)g(both)f(and)208 3310 y FJ('control')j FN(for)h(access)h(to)g(the)g(control)e(de)n(vice.)29 b(Since)22 b(only)f(one)g(process)g(is)i(allo)n(wed)e(to)h(ha)n(v)o(e)f (the)g(recorder)f(or)i(player)208 3410 y(open)c(at)i(the)g(same)g(time) g(it)g(is)h(a)f(good)e(idea)h(to)h(open)f(the)h(de)n(vice)e(only)h(for) g(the)h(acti)n(vity)f(needed.)24 b(See)c FK(audio)p FN(\(7I\))c(for)j (details.)208 3543 y(As)k(per)g(the)g(manpage,)f(this)i(module)d (\002rst)j(looks)f(in)g(the)g(en)m(vironment)d(v)n(ariable)i FJ(AUDIODEV)g FN(for)h(the)g(base)g(audio)f(de)n(vice)208 3642 y(\002lename.)34 b(If)24 b(not)f(found,)f(it)j(f)o(alls)f(back)f (to)h(`)p FO(/de)n(v/audio)p FN('.)31 b(The)23 b(control)g(de)n(vice)f (is)j(calculated)e(by)g(appending)e(\223ctl\224)j(to)g(the)208 3742 y(base)c(audio)f(de)n(vice.)0 4027 y Fv(35.1.1)101 b(A)m(udio)29 b(De)m(vice)f(Objects)0 4230 y FN(The)17 b(audio)g(de)n(vice)g(objects)h(are)f(returned)f(by)h FJ(open\(\))h FN(de\002ne)f(the)h(follo)n(wing)e(methods)g(\(e)o(xcept) h FJ(control)g FN(objects)g(which)g(only)0 4329 y(pro)o(vide)h FJ(getinfo\(\))p FN(,)h FJ(setinfo\(\))p FN(,)g FJ(fileno\(\))p FN(,)g(and)g FJ(drain\(\))p FN(\):)0 4476 y FD(close)p FJ(\(\))208 4576 y FN(This)e(method)e(e)o(xplicitly)h(closes)h(the)g (de)n(vice.)23 b(It)17 b(is)h(useful)f(in)g(situations)f(where)h (deleting)e(the)i(object)g(does)f(not)h(immediately)208 4675 y(close)j(it)h(since)f(there)g(are)g(other)f(references)g(to)i (it.)k(A)c(closed)f(de)n(vice)f(should)g(not)h(be)g(used)g(again.)0 4822 y FD(fileno)p FJ(\(\))208 4922 y FN(Returns)28 b(the)h(\002le)g (descriptor)e(associated)h(with)h(the)g(de)n(vice.)49 b(This)28 b(can)h(be)f(used)h(to)f(set)i(up)e FJ(SIGPOLL)g FN(noti\002cation,)h(as)208 5022 y(described)18 b(belo)n(w)-5 b(.)0 5168 y FD(drain)p FJ(\(\))208 5268 y FN(This)31 b(method)e(w)o(aits)j(until)f(all)h(pending)d(output)h(is)i(processed)e (and)g(then)h(returns.)56 b(Calling)31 b(this)h(method)e(is)i(often)e (not)208 5368 y(necessary:)24 b(destro)o(ying)19 b(the)h(object)f(will) i(automatically)e(close)h(the)h(audio)e(de)n(vice)g(and)h(this)h(will)f (do)g(an)g(implicit)h(drain.)p 0 5549 3901 4 v 3762 5649 a FI(931)p eop end %%Page: 932 944 TeXDict begin 932 943 bop 0 83 a FD(flush)p FJ(\(\))208 183 y FN(This)20 b(method)g(discards)g(all)h(pending)e(output.)25 b(It)c(can)f(be)h(used)f(a)n(v)n(oid)h(the)g(slo)n(w)g(response)e(to)i (a)g(user')-5 b(s)21 b(stop)g(request)f(\(due)f(to)208 282 y(b)n(uf)n(fering)e(of)j(up)g(to)h(one)e(second)g(of)h(sound\).)0 429 y FD(getinfo)p FJ(\(\))208 529 y FN(This)28 b(method)g(retrie)n(v)o (es)f(status)i(information)e(lik)o(e)h(input)g(and)g(output)g(v)n (olume,)h(etc.)50 b(and)28 b(returns)g(it)h(in)g(the)g(form)e(of)i(an) 208 628 y(audio)d(status)i(object.)46 b(This)27 b(object)g(has)g(no)g (methods)f(b)n(ut)i(it)g(contains)e(a)i(number)e(of)h(attrib)n(utes)g (describing)f(the)h(current)208 728 y(de)n(vice)i(status.)57 b(The)30 b(names)h(and)f(meanings)f(of)i(the)f(attrib)n(utes)h(are)f (described)g(in)g FJ(<sun/audioio.h>)f FN(and)h(in)h(the)208 828 y FK(audio)p FN(\(7I\))20 b(manual)i(page.)32 b(Member)22 b(names)h(are)g(slightly)f(dif)n(ferent)g(from)g(their)g(C)i (counterparts:)29 b(a)23 b(status)h(object)e(is)i(only)208 927 y(a)f(single)g(structure.)32 b(Members)22 b(of)h(the)g FJ(play)g FN(substructure)e(ha)n(v)o(e)i(`)p FJ(o_)p FN(')f(prepended)e(to)j(their)g(name)g(and)f(members)g(of)h(the)208 1027 y FJ(record)j FN(structure)h(ha)n(v)o(e)f(`)p FJ(i_)p FN('.)46 b(So,)29 b(the)f(C)g(member)e FJ(play.sample_rate)f FN(is)j(accessed)g(as)g FJ(o_sample_rate)p FN(,)208 1127 y FJ(record.gain)18 b FN(as)j FJ(i_gain)f FN(and)f FJ(monitor_gain)g FN(plainly)g(as)i FJ(monitor_gain)p FN(.)0 1273 y FD(ibufcount)p FJ(\(\))208 1373 y FN(This)26 b(method)g(returns)g(the)h(number)e(of)h (samples)h(that)g(are)f(b)n(uf)n(fered)f(on)i(the)f(recording)f(side,)j (i.e.)f(the)g(program)d(will)k(not)208 1473 y(block)19 b(on)h(a)g FJ(read\(\))g FN(call)g(of)g(so)h(man)o(y)e(samples.)0 1620 y FD(obufcount)p FJ(\(\))208 1719 y FN(This)24 b(method)e(returns) h(the)h(number)e(of)i(samples)g(b)n(uf)n(fered)e(on)i(the)g(playback)e (side.)36 b(Unfortunately)-5 b(,)22 b(this)j(number)d(cannot)208 1819 y(be)i(used)g(to)h(determine)e(a)i(number)e(of)h(samples)g(that)h (can)f(be)h(written)f(without)g(blocking)f(since)h(the)h(k)o(ernel)e (output)h(queue)208 1918 y(length)19 b(seems)i(to)f(be)g(v)n(ariable.)0 2065 y FD(read)p FJ(\()p FK(size)p FJ(\))208 2165 y FN(This)i(method)f (reads)h FK(size)h FN(samples)g(from)e(the)h(audio)f(input)h(and)g (returns)f(them)h(as)h(a)g(Python)e(string.)31 b(The)22 b(function)e(blocks)208 2265 y(until)g(enough)e(data)i(is)h(a)n(v)n (ailable.)0 2411 y FD(setinfo)p FJ(\()p FK(status)p FJ(\))208 2511 y FN(This)f(method)e(sets)k(the)e(audio)f(de)n(vice)g(status)i (parameters.)i(The)d FK(status)h FN(parameter)d(is)j(an)f(de)n(vice)f (status)i(object)f(as)g(returned)208 2611 y(by)f FJ(getinfo\(\))g FN(and)h(possibly)g(modi\002ed)f(by)g(the)i(program.)0 2758 y FD(write)p FJ(\()p FK(samples)p FJ(\))208 2857 y FN(Write)k(is)h(passed)f(a)g(Python)f(string)g(containing)f(audio)h (samples)h(to)g(be)g(played.)38 b(If)25 b(there)f(is)i(enough)d(b)n(uf) n(fer)h(space)g(free)h(it)208 2957 y(will)20 b(immediately)f(return,)g (otherwise)h(it)h(will)g(block.)0 3104 y(The)d(audio)g(de)n(vice)g (supports)f(asynchronous)f(noti\002cation)h(of)h(v)n(arious)g(e)n(v)o (ents,)g(through)e(the)j(SIGPOLL)f(signal.)24 b(Here')-5 b(s)19 b(an)g(e)o(xam-)0 3203 y(ple)h(of)g(ho)n(w)g(you)f(might)h (enable)f(this)i(in)f(Python:)236 3441 y FA(def)45 b (handle_sigpoll\(signum,)c(frame\):)416 3533 y(print)j('I)g(got)g(a)h (SIGPOLL)f(update')236 3715 y(import)g(fcntl,)g(signal,)g(STROPTS)236 3898 y(signal.signal\(signal.SIGPOLL,)c(handle_sigpoll\))236 3989 y(fcntl.ioctl\(audio_obj.fileno\(\),)g(STROPTS.I_SETSIG,)i (STROPTS.S_MSG\))0 4438 y FE(35.2)121 b Fx(SUNAUDIODEV)30 b FE(\227)j(Constants)j(used)e(with)g Fx(sunaudiodev)0 4671 y FN(This)48 b(is)h(a)g(companion)c(module)i(to)h FJ(sunaudiodev)f FN(which)g(de\002nes)h(useful)g(symbolic)f(constants)g (lik)o(e)i FJ(MIN_GAIN)p FN(,)0 4771 y FJ(MAX_GAIN)p FN(,)40 b FJ(SPEAKER)p FN(,)g(etc.)87 b(The)41 b(names)g(of)f(the)h (constants)g(are)g(the)g(same)g(names)g(as)g(used)g(in)g(the)g(C)h (include)e(\002le)0 4870 y FJ(<sun/audioio.h>)p FN(,)18 b(with)i(the)g(leading)f(string)h(`)p FJ(AUDIO_)p FN(')f(stripped.)p 0 5549 3901 4 v 0 5649 a FI(932)2351 b(Chapter)24 b(35.)52 b(SunOS)23 b(Speci\002c)g(Ser)r(vices)p eop end %%Page: 933 945 TeXDict begin 933 944 bop 0 83 3901 9 v 3503 230 a FI(CHAPTER)3278 427 y FG(THIR)n(TYSIX)p 0 515 V 1062 978 a FT(MS)57 b(Windo)m(ws)g (Speci\002c)h(Ser)6 b(vices)0 1465 y FN(This)20 b(chapter)f(describes)h (modules)f(that)i(are)f(only)f(a)n(v)n(ailable)h(on)g(MS)g(W)m(indo)n (ws)g(platforms.)50 1608 y FD(msilib)198 b FN(Creation)20 b(of)g(Microsoft)f(Installer)h(\002les,)g(and)g(CAB)i(\002les.)50 1708 y FD(msvcrt)198 b FN(Miscellaneous)19 b(useful)h(routines)f(from)g (the)i(MS)f(VC)2120 1701 y(++)2235 1708 y(runtime.)50 1808 y FD(_winreg)148 b FN(Routines)20 b(and)g(objects)g(for)f (manipulating)f(the)i(W)m(indo)n(ws)g(re)o(gistry)-5 b(.)50 1907 y FD(winsound)98 b FN(Access)21 b(to)f(the)g(sound-playing) d(machinery)h(for)i(W)m(indo)n(ws.)0 2211 y FE(36.1)121 b Fx(msilib)32 b FE(\227)h(Read)i(and)f(wr)r(ite)g(Microsoft)f (Installer)h(\002les)0 2443 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.5.)0 2590 y(The)g FJ(msilib)f FN(supports)g(the)h(creation)f(of)h(Microsoft) f(Installer)h(\()p FJ(.msi)p FN(\))f(\002les.)25 b(Because)19 b(these)h(\002les)g(often)e(contain)g(an)h(embedded)0 2690 y(\223cabinet\224)26 b(\002le)i(\()p FJ(.cab)p FN(\),)g(it)g(also) g(e)o(xposes)f(an)g(API)h(to)f(create)g(CAB)i(\002les.)47 b(Support)26 b(for)h(reading)f FJ(.cab)h FN(\002les)h(is)g(currently)e (not)0 2790 y(implemented;)18 b(read)i(support)f(for)g(the)i FJ(.msi)f FN(database)f(is)i(possible.)0 2936 y(This)f(package)f(aims)i (to)f(pro)o(vide)e(complete)h(access)i(to)f(all)h(tables)f(in)g(an)g FJ(.msi)g FN(\002le,)h(therefore,)d(it)j(is)g(a)g(f)o(airly)e(lo)n (w-le)n(v)o(el)g(API.)h(T)-7 b(w)o(o)0 3036 y(primary)16 b(applications)g(of)g(this)i(package)e(are)h(the)g FJ(distutils)f FN(command)f FJ(bdist_msi)p FN(,)i(and)f(the)h(creation)g(of)g(Python)f (installer)0 3136 y(package)j(itself)i(\(although)d(that)i(currently)e (uses)j(a)g(dif)n(ferent)d(v)o(ersion)h(of)h FJ(msilib)p FN(\).)0 3283 y(The)15 b(package)f(contents)h(can)h(be)f(roughly)f (split)i(into)f(four)g(parts:)23 b(lo)n(w-le)n(v)o(el)14 b(CAB)j(routines,)e(lo)n(w-le)n(v)o(el)g(MSI)g(routines,)h(higher)n (-le)n(v)o(el)0 3382 y(MSI)k(routines,)f(and)h(standard)f(table)h (structures.)0 3529 y FD(FCICreate)p FJ(\()p FK(cabname)o(,)d(\002les)p FJ(\))208 3629 y FN(Create)24 b(a)h(ne)n(w)f(CAB)i(\002le)f(named)f FK(cabname)p FN(.)36 b FK(\002les)24 b FN(must)h(be)f(a)h(list)h(of)e (tuples,)h(each)f(containing)f(the)h(name)g(of)g(the)h(\002le)g(on)208 3728 y(disk,)19 b(and)h(the)g(name)g(of)g(the)g(\002le)h(inside)f(the)g (CAB)i(\002le.)208 3861 y(The)d(\002les)h(are)f(added)f(to)i(the)f(CAB) i(\002le)f(in)f(the)h(order)e(the)o(y)h(appear)f(in)h(the)h(list.)25 b(All)c(\002les)f(are)f(added)f(into)h(a)h(single)g(CAB)g(\002le,)208 3961 y(using)f(the)h(MSZIP)h(compression)d(algorithm.)208 4094 y(Callbacks)i(to)g(Python)f(for)h(the)g(v)n(arious)f(steps)i(of)f (MSI)g(creation)f(are)h(currently)f(not)h(e)o(xposed.)0 4240 y FD(UUIDCreate)p FJ(\(\))208 4340 y FN(Return)46 b(the)g(string)h(representation)d(of)j(a)g(ne)n(w)f(unique)f (identi\002er)-5 b(.)104 b(This)47 b(wraps)f(the)h(W)m(indo)n(ws)f(API) h(functions)208 4440 y FJ(UuidCreate)18 b FN(and)i FJ(UuidToString)p FN(.)0 4587 y FD(OpenDatabase)p FJ(\()p FK(path,)d(per)o(sist)q FJ(\))208 4686 y FN(Return)36 b(a)i(ne)n(w)f(database)f(object)h(by)f (calling)h(MsiOpenDatabase.)74 b FK(path)37 b FN(is)h(the)f(\002le)g (name)g(of)g(the)g(MSI)g(\002le;)46 b FK(per)n(-)208 4786 y(sist)36 b FN(can)d(be)g(one)g(of)g(the)g(constants)g FJ(MSIDBOPEN_CREATEDIRECT)p FN(,)c FJ(MSIDBOPEN_CREATE)p FN(,)i FJ(MSIDBOPEN_-)208 4886 y(DIRECT)p FN(,)19 b FJ (MSIDBOPEN_READONLY)p FN(,)e(or)j FJ(MSIDBOPEN_TRANSACT)p FN(,)e(and)h(may)h(include)f(the)i(\003ag)f FJ(MSIDBOPEN_-)208 4985 y(PATCHFILE)p FN(.)30 b(See)i(the)f(Microsoft)g(documentation)e (for)i(the)g(meaning)f(of)i(these)f(\003ags;)38 b(depending)29 b(on)i(the)h(\003ags,)j(an)208 5085 y(e)o(xisting)19 b(database)h(is)h(opened,)d(or)i(a)h(ne)n(w)f(one)f(created.)0 5232 y FD(CreateRecord)p FJ(\()p FK(count)q FJ(\))208 5331 y FN(Return)g(a)i(ne)n(w)f(record)f(object)g(by)h(calling)g FJ(MSICreateRecord)p FN(.)j FK(count)d FN(is)h(the)g(number)d(of)i (\002elds)h(of)e(the)i(record.)p 0 5549 3901 4 v 3762 5649 a FI(933)p eop end %%Page: 934 946 TeXDict begin 934 945 bop 0 83 a FD(init_database)p FJ(\()p FK(name)o(,)17 b(sc)o(hema,)i(Pr)l(oductName)o(,)g(Pr)l(oductCode)o(,)g (Pr)l(oductV)-9 b(er)o(sion,)18 b(Manufactur)m(er)r FJ(\))208 183 y FN(Create)i(and)f(return)g(a)i(ne)n(w)f(database)f FK(name)p FN(,)g(initialize)i(it)f(with)h FK(sc)o(hema)p FN(,)e(and)g(set)i(the)f(properties)f FK(Pr)l(oductName)p FN(,)g FK(Pr)l(oduct-)208 282 y(Code)p FN(,)g FK(Pr)l(oductV)-9 b(er)o(sion)p FN(,)19 b(and)g FK(Manufactur)m(er)r FN(.)208 415 y FK(sc)o(hema)31 b FN(must)h(be)g(a)g(module)f(object)g (containing)f FJ(tables)i FN(and)f FJ(_Validation_records)e FN(attrib)n(utes;)38 b(typically)-5 b(,)208 515 y FJ(msilib.schema)18 b FN(should)h(be)h(used.)208 648 y(The)f(database)h(will)h(contain)e (just)i(the)f(schema)g(and)f(the)i(v)n(alidation)d(records)h(when)h (this)h(function)d(returns.)0 794 y FD(add_data)p FJ(\()p FK(database)o(,)f(r)m(ecor)m(ds)p FJ(\))208 894 y FN(Add)e(all)h FK(r)m(ecor)m(ds)f FN(to)h FK(database)p FN(.)21 b FK(r)m(ecor)m(ds)16 b FN(should)e(be)i(a)f(list)i(of)e(tuples,)h(each)f(one)g(containing)f (all)i(\002elds)g(of)f(a)h(record)e(according)208 994 y(to)20 b(the)g(schema)g(of)g(the)g(table.)25 b(F)o(or)20 b(optional)f(\002elds,)h FJ(None)g FN(can)g(be)g(passed.)208 1127 y(Field)g(v)n(alues)g(can)g(be)g(int)g(or)g(long)g(numbers,)e (strings,)i(or)g(instances)g(of)g(the)g(Binary)g(class.)0 1273 y FL(class)h FD(Binary)p FJ(\()p FK(\002lename)p FJ(\))208 1373 y FN(Represents)f(entries)h(in)g(the)g(Binary)f(table;)h (inserting)f(such)h(an)g(object)f(using)g FJ(add_data)g FN(reads)h(the)g(\002le)g(named)f FK(\002lename)208 1473 y FN(into)f(the)i(table.)0 1620 y FD(add_tables)p FJ(\()p FK(database)o(,)16 b(module)p FJ(\))208 1719 y FN(Add)26 b(all)i(table)f(content)e(from)h FK(module)g FN(to)h FK(database)p FN(.)44 b FK(module)26 b FN(must)h(contain)f(an)h(attrib) n(ute)f FK(tables)h FN(listing)g(all)h(tables)f(for)208 1819 y(which)19 b(content)g(should)h(be)g(added,)e(and)i(one)g(attrib)n (ute)g(per)f(table)h(that)h(has)f(the)g(actual)g(content.)208 1952 y(This)g(is)h(typically)e(used)h(to)h(install)f(the)h(sequence)e (tables.)0 2098 y FD(add_stream)p FJ(\()p FK(database)o(,)d(name)o(,)k (path)p FJ(\))208 2198 y FN(Add)f(the)h(\002le)h FK(path)f FN(into)g(the)g FJ(_Stream)f FN(table)h(of)g FK(database)p FN(,)f(with)h(the)g(stream)g(name)g FK(name)p FN(.)0 2345 y FD(gen_uuid)p FJ(\(\))208 2445 y FN(Return)26 b(a)g(ne)n(w)h(UUID,)f(in)h(the)f(format)f(that)i(MSI)f(typically)g (requires)f(\(i.e.)44 b(in)27 b(curly)e(braces,)j(and)e(with)g(all)h (he)o(xdigits)e(in)208 2544 y(upper)n(-case\).)0 2691 y FL(See)c(Also:)0 2838 y FK(FCICr)m(eateF)l(ile)0 2938 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o (sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/de)m(vnot)o(es/win)o (pro)o(g/)o(fcicrea)o(te)o(.)o(asp)-6 b Fy(\))0 3084 y FK(UuidCr)m(eate)0 3184 y Fy(\()p FO(http://msdn.microsoft.com/libr)o (ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o (s/r)r(pc/r)r(pc/u)o(uid)o(crea)o(te)o(.)o(asp)g Fy(\))0 3331 y FK(UuidT)e(oString)0 3431 y Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/r)r(pc/r)r(pc/u)o(uid)o(to)o(str)q (ing)o(.asp)h Fy(\))0 3715 y Fv(36.1.1)101 b(Database)29 b(Objects)0 3904 y FD(OpenView)p FJ(\()p FK(sql)p FJ(\))208 4004 y FN(Return)19 b(a)i(vie)n(w)f(object,)f(by)h(calling)g FJ(MSIDatabaseOpenView)p FN(.)i FK(sql)f FN(is)g(the)f(SQL)g(statement) g(to)h(e)o(x)o(ecute.)0 4151 y FD(Commit)p FJ(\(\))208 4250 y FN(Commit)f(the)g(changes)f(pending)f(in)j(the)f(current)f (transaction,)f(by)i(calling)g FJ(MSIDatabaseCommit)p FN(.)0 4397 y FD(GetSummaryInformation)p FJ(\()p FK(count)q FJ(\))208 4497 y FN(Return)j(a)h(ne)n(w)g(summary)f(information)e (object,)j(by)g(calling)f FJ(MsiGetSummaryInformation)p FN(.)32 b FK(count)25 b FN(is)f(the)g(maxi-)208 4597 y(mum)19 b(number)f(of)i(updated)f(v)n(alues.)0 4743 y FL(See)i(Also:)0 4890 y FK(MSIDatabaseOpenV)-6 b(ie)o(w)0 4990 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msida)o(ta)o(base)o(ope)o(n)n(vie)n(w)l(.)o(asp)g Fy(\))0 5137 y FK(MSIDatabaseCommit)0 5236 y Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msida)o(ta)o(base)o (commit.a)o(sp)g Fy(\))0 5383 y FK(MSIGetSummaryInformation)p 0 5549 3901 4 v 0 5649 a FI(934)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g(Ser)r(vices)p eop end %%Page: 935 947 TeXDict begin 935 946 bop 0 83 a Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msige)o(tsummar)r(yin) o(f)n(or)q(mati)o(on)o(.asp)-6 b Fy(\))0 368 y Fv(36.1.2)101 b(Vie)n(w)28 b(Objects)0 566 y FD(Execute)p FJ(\()p FC([)p FK(par)o(ams=None)12 b FC(])p FJ(\))208 666 y FN(Ex)o(ecute)28 b(the)h(SQL)h(query)e(of)h(the)h(vie)n(w)-5 b(,)31 b(through)c FJ(MSIViewExecute)p FN(.)50 b FK(par)o(ams)29 b FN(is)i(an)e(optional)f (record)g(describing)208 765 y(actual)20 b(v)n(alues)f(of)h(the)g (parameter)f(tok)o(ens)h(in)g(the)g(query)-5 b(.)0 912 y FD(GetColumnInfo)p FJ(\()p FK(kind)r FJ(\))208 1012 y FN(Return)20 b(a)h(record)e(describing)g(the)i(columns)f(of)g(the)h (vie)n(w)-5 b(,)20 b(through)e(calling)i FJ(MsiViewGetColumnInfo)p FN(.)k FK(kind)e FN(can)f(be)208 1111 y(either)e FJ(MSICOLINFO_NAMES)f FN(or)i FJ(MSICOLINFO_TYPES)p FN(.)0 1258 y FD(Fetch)p FJ(\(\))208 1358 y FN(Return)f(a)i(result)f(record)f(of)h(the)g(query) -5 b(,)18 b(through)g(calling)i FJ(MsiViewFetch)p FN(.)0 1505 y FD(Modify)p FJ(\()p FK(kind,)e(data)p FJ(\))208 1604 y FN(Modify)28 b(the)j(vie)n(w)-5 b(,)31 b(by)f(calling)g FJ(MsiViewModify)p FN(.)53 b FK(kind)32 b FN(can)e(be)g(one)f(of)h FJ(MSIMODIFY_SEEK)p FN(,)e FJ(MSIMODIFY_-)208 1704 y(REFRESH)p FN(,)78 b FJ(MSIMODIFY_INSERT)p FN(,)g FJ(MSIMODIFY_UPDATE)p FN(,)f FJ(MSIMODIFY_ASSIGN)p FN(,)g FJ(MSIMODIFY_-)208 1804 y(REPLACE)p FN(,)138 b FJ(MSIMODIFY_MERGE)p FN(,)g FJ(MSIMODIFY_DELETE)p FN(,)f FJ(MSIMODIFY_INSERT_TEMPORARY)p FN(,)208 1903 y FJ(MSIMODIFY_VALIDATE)p FN(,)120 b FJ (MSIMODIFY_VALIDATE_NEW)p FN(,)g FJ(MSIMODIFY_VALIDATE_FIELD)p FN(,)g(or)208 2003 y FJ(MSIMODIFY_VALIDATE_DELETE)p FN(.)208 2136 y FK(data)19 b FN(must)h(be)g(a)h(record)e(describing)f(the)j(ne)n (w)f(data.)0 2283 y FD(Close)p FJ(\(\))208 2382 y FN(Close)g(the)h(vie) n(w)-5 b(,)19 b(through)f FJ(MsiViewClose)p FN(.)0 2529 y FL(See)j(Also:)0 2676 y FK(MsiV)-6 b(ie)o(wExecute)0 2776 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msivie)n(w)o(e)n(x)n(e)o(cute)n(.asp)g Fy(\))0 2923 y FK(MSIV)g(ie)o(wGetColumnInfo)0 3022 y Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msivie)n(wge)o(tcol)o (umni)o(nf)m(o)m(.a)o(sp)g Fy(\))0 3169 y FK(MsiV)g(ie)o(wF)g(etc)o(h)0 3269 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msivie)n(wf)n(e)o(tch.)o(asp)g Fy(\))0 3416 y FK(MsiV)g(ie)o(wModify) 0 3515 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msivie)n(wmod)o(ify)f(.)o(asp)h Fy(\))0 3662 y FK(MsiV)g(ie)o(wClose) 0 3762 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msivie)n(wclo)o(se)o(.asp)f Fy(\))0 4047 y Fv(36.1.3)101 b(Summar)s(y)28 b(Inf)m(or)r(mation)i(Objects)0 4235 y FD(GetProperty)p FJ(\()p FK(\002eld)r FJ(\))208 4335 y FN(Return)j(a)g(property)f(of)h(the)g(summary)-5 b(,)35 b(through)c FJ(MsiSummaryInfoGetProperty)p FN(.)61 b FK(\002eld)35 b FN(is)f(the)g(name)e(of)i(the)208 4435 y(property)-5 b(,)26 b(and)g(can)h(be)h(one)e(of)h(the)h(constants)e FJ(PID_CODEPAGE)p FN(,)g FJ(PID_TITLE)p FN(,)g FJ(PID_SUBJECT)p FN(,)f FJ(PID_AUTHOR)p FN(,)208 4534 y FJ(PID_KEYWORDS)p FN(,)37 b FJ(PID_COMMENTS)p FN(,)h FJ(PID_TEMPLATE)p FN(,)g FJ(PID_LASTAUTHOR)p FN(,)f FJ(PID_REVNUMBER)p FN(,)h FJ(PID_-)208 4634 y(LASTPRINTED)p FN(,)60 b FJ(PID_CREATE_DTM)p FN(,)g FJ(PID_LASTSAVE_DTM)p FN(,)g FJ(PID_PAGECOUNT)p FN(,)g FJ(PID_WORDCOUNT)p FN(,)208 4734 y FJ(PID_CHARCOUNT)p FN(,)18 b FJ(PID_APPNAME)p FN(,)g(or)i FJ(PID_SECURITY)p FN(.)0 4880 y FD(GetPropertyCount)p FJ(\(\))208 4980 y FN(Return)f(the)i(number)d(of)i(summary)f(properties,)f(through)g FJ(MsiSummaryInfoGetPropertyCount)p FN(.)0 5127 y FD(SetProperty)p FJ(\()p FK(\002eld,)f(value)p FJ(\))208 5227 y FN(Set)53 b(a)h(property)d(through)f FJ(MsiSummaryInfoSetProperty)p FN(.)120 b FK(\002eld)55 b FN(can)d(ha)n(v)o(e)h(the)g(same)g(v)n (alues)g(as)g(in)208 5326 y FJ(GetProperty)p FN(,)18 b FK(value)i FN(is)h(the)f(ne)n(w)g(v)n(alue)f(of)h(the)h(property)-5 b(.)22 b(Possible)e(v)n(alue)g(types)g(are)g(inte)o(ger)f(and)h (string.)p 0 5549 3901 4 v 0 5649 a FI(36.1.)52 b FJ(msilib)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h(Microsoft)f(Installer)h(\002les) 1693 b(935)p eop end %%Page: 936 948 TeXDict begin 936 947 bop 0 83 a FD(Persist)p FJ(\(\))208 183 y FN(Write)20 b(the)h(modi\002ed)e(properties)f(to)j(the)f(summary) f(information)e(stream,)j(using)g FJ(MsiSummaryInfoPersist)p FN(.)0 330 y FL(See)h(Also:)0 476 y FK(MsiSummaryInfoGetPr)l(operty)0 576 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msisummar)r(yinf)m(og)o(etp)o(ro)o(per)r(ty)-7 b(.a)o(sp)h Fy(\))0 723 y FK(MsiSummaryInfoGetPr)l(opertyCount)0 823 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msisummar)r(yinf)m(og)o(etp)o(ro)o(per)r(tycount)o(.asp)g Fy(\))0 969 y FK(MsiSummaryInfoSetPr)l(operty)0 1069 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o (sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msisummar)r (yinf)m(oset)o(pro)o(pe)o(r)s(ty)f(.a)o(sp)h Fy(\))0 1216 y FK(MsiSummaryInfoP)f(er)o(sist)0 1316 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msisummar)r(yinf)m(op) o(ersist.)o(asp)h Fy(\))0 1598 y Fv(36.1.4)101 b(Record)28 b(Objects)0 1783 y FD(GetFieldCount)p FJ(\(\))208 1883 y FN(Return)19 b(the)i(number)d(of)i(\002elds)g(of)g(the)h(record,)d (through)g FJ(MsiRecordGetFieldCount)p FN(.)0 2030 y FD(SetString)p FJ(\()p FK(\002eld,)g(value)p FJ(\))208 2129 y FN(Set)i FK(\002eld)i FN(to)f FK(value)e FN(through)f FJ(MsiRecordSetString)p FN(.)k FK(\002eld)g FN(must)f(be)f(an)g(inte)o (ger;)f FK(value)h FN(a)g(string.)0 2276 y FD(SetStream)p FJ(\()p FK(\002eld,)e(value)p FJ(\))208 2376 y FN(Set)24 b FK(\002eld)i FN(to)e(the)h(contents)e(of)h(the)g(\002le)h(named)e FK(value)p FN(,)h(through)e FJ(MsiRecordSetStream)p FN(.)34 b FK(\002eld)25 b FN(must)g(be)f(an)g(inte)o(ger;)208 2475 y FK(value)19 b FN(a)i(string.)0 2622 y FD(SetInteger)p FJ(\()p FK(\002eld,)c(value)p FJ(\))208 2722 y FN(Set)j FK(\002eld)i FN(to)f FK(value)e FN(through)f FJ(MsiRecordSetInteger)p FN(.)k(Both)f FK(\002eld)g FN(and)f FK(value)g FN(must)g(be)g(an)g (inte)o(ger)-5 b(.)0 2869 y FD(ClearData)p FJ(\(\))208 2968 y FN(Set)20 b(all)h(\002elds)g(of)f(the)g(record)f(to)h(0,)g (through)e FJ(MsiRecordClearData)p FN(.)0 3115 y FL(See)j(Also:)0 3262 y FK(MsiRecor)m(dGetF)l(ieldCount)0 3362 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msire)o(cordg)o (et\002el)o(dcou)o(nt)o(.asp)-6 b Fy(\))0 3509 y FK(MsiRecor)m (dSetString)0 3608 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r (y/def)m(au)o(lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o (s/msi/setup)o(/msire)o(cordset)o(str)q(ing)o(.asp)f Fy(\))0 3755 y FK(MsiRecor)m(dSetStr)m(eam)0 3855 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msire)o(cordset)o (stream.a)o(sp)h Fy(\))0 4002 y FK(MsiRecor)m(dSetInte)m(g)o(er)0 4101 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o (lt.a)o(sp?u)o(r)q(l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o (/msire)o(cordset)o(int)o(eg)o(er)l(.a)o(sp)g Fy(\))0 4248 y FK(MsiRecor)m(dClear)0 4348 y Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/def)m(au)o(lt.a)o(sp?u)o(r)q (l=)o(/li)o(br)o(a)o(r)r(y/en-u)o(s/msi/setup)o(/msire)o(cordcle)o(ar)l (.a)o(sp)g Fy(\))0 4630 y Fv(36.1.5)101 b(Errors)0 4833 y FN(All)21 b(wrappers)e(around)f(MSI)j(functions)d(raise)j FJ(MsiError)p FN(;)e(the)h(string)g(inside)g(the)h(e)o(xception)d(will) j(contain)e(more)g(detail.)0 5115 y Fv(36.1.6)101 b(CAB)28 b(Objects)0 5300 y FL(class)21 b FD(CAB)p FJ(\()p FK(name)p FJ(\))208 5400 y FN(The)16 b(class)i FJ(CAB)f FN(represents)f(a)h(CAB)i (\002le.)24 b(During)16 b(MSI)h(construction,)e(\002les)j(will)g(be)f (added)f(simultaneously)f(to)i(the)g FJ(Files)p 0 5549 3901 4 v 0 5649 a FI(936)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g(Ser)r(vices)p eop end %%Page: 937 949 TeXDict begin 937 948 bop 208 83 a FN(table,)23 b(and)g(to)g(a)g(CAB)i (\002le.)34 b(Then,)23 b(when)f(all)i(\002les)g(ha)n(v)o(e)e(been)h (added,)f(the)h(CAB)i(\002le)f(can)e(be)h(written,)h(then)e(added)g(to) i(the)208 183 y(MSI)c(\002le.)208 315 y FK(name)f FN(is)i(the)f(name)g (of)g(the)g(CAB)i(\002le)e(in)h(the)f(MSI)g(\002le.)0 462 y FD(append)p FJ(\()p FK(full,)f(lo)o(gical)p FJ(\))208 562 y FN(Add)26 b(the)g(\002le)i(with)e(the)h(pathname)e FK(full)i FN(to)g(the)f(CAB)i(\002le,)h(under)c(the)h(name)g FK(lo)o(gical)p FN(.)44 b(If)26 b(there)g(is)i(already)d(a)i(\002le)h (named)208 662 y FK(lo)o(gical)p FN(,)19 b(a)i(ne)n(w)f(\002le)g(name)g (is)h(created.)208 794 y(Return)e(the)i(inde)o(x)d(of)i(the)h(\002le)f (in)h(the)f(CAB)h(\002le,)g(and)f(the)g(ne)n(w)g(name)f(of)h(the)h (\002le)f(inside)h(the)f(CAB)h(\002le.)0 941 y FD(append)p FJ(\()p FK(database)p FJ(\))208 1041 y FN(Generate)h(a)h(CAB)h(\002le,) g(add)f(it)h(as)f(a)h(stream)e(to)i(the)f(MSI)g(\002le,)h(put)e(it)i (into)f(the)g FJ(Media)f FN(table,)i(and)e(remo)o(v)o(e)f(the)i (generated)208 1141 y(\002le)d(from)g(the)g(disk.)0 1425 y Fv(36.1.7)101 b(Director)s(y)28 b(Objects)0 1624 y FL(class)21 b FD(Directory)p FJ(\()p FK(database)o(,)16 b(cab,)k(basedir)-9 b(,)19 b(physical,)g(lo)o(gical,)h(default,)f (component,)f FC([)p FK(component\003a)o(gs)12 b FC(])p FJ(\))208 1724 y FN(Create)k(a)g(ne)n(w)g(directory)e(in)i(the)g (Directory)f(table.)23 b(There)16 b(is)g(a)h(current)e(component)e(at)j (each)g(point)f(in)h(time)h(for)e(the)h(directory)-5 b(,)208 1823 y(which)20 b(is)j(either)e(e)o(xplicitly)f(created)h (through)e FJ(start_component)p FN(,)g(or)i(implicitly)g(when)g (\002les)h(are)f(added)g(for)f(the)i(\002rst)208 1923 y(time.)36 b(Files)25 b(are)f(added)f(into)h(the)g(current)f (component,)f(and)i(into)f(the)h(cab)g(\002le.)38 b(T)-7 b(o)24 b(create)g(a)g(directory)-5 b(,)23 b(a)h(base)g(directory)208 2023 y(object)j(needs)g(to)g(be)h(speci\002ed)f(\(can)g(be)g FJ(None)p FN(\),)i(the)e(path)g(to)h(the)f(physical)g(directory)-5 b(,)27 b(and)g(a)h(logical)f(directory)e(name.)208 2122 y FK(default)g FN(speci\002es)g(the)g(Def)o(aultDir)f(slot)h(in)f(the)h (directory)e(table.)38 b FK(component\003a)o(gs)21 b FN(speci\002es)26 b(the)e(def)o(ault)g(\003ags)h(that)g(ne)n(w)208 2222 y(components)18 b(get.)0 2369 y FD(start_component)p FJ(\()p FC([)p FK(component)q FC([)p FK(,)d(featur)m(e)p FC([)p FK(,)k(\003a)o(gs)p FC([)p FK(,)h(k)o(e)n(y\002le)p FC([)p FK(,)f(uuid)12 b FC(])g(])g(])g(])g(])p FJ(\))208 2468 y FN(Add)26 b(an)h(entry)e(to)i(the)g(Component)e(table,)j(and)e (mak)o(e)h(this)g(component)d(the)j(current)e(component)g(for)h(this)h (directory)-5 b(.)43 b(If)208 2568 y(no)23 b(component)e(name)j(is)h (gi)n(v)o(en,)e(the)h(directory)e(name)h(is)i(used.)36 b(If)24 b(no)f FK(featur)m(e)h FN(is)g(gi)n(v)o(en,)g(the)g(current)e (feature)h(is)i(used.)36 b(If)208 2668 y(no)25 b FK(\003a)o(gs)h FN(are)h(gi)n(v)o(en,)f(the)g(directory')-5 b(s)25 b(def)o(ault)h (\003ags)g(are)h(used.)43 b(If)26 b(no)g FK(k)o(e)n(y\002le)f FN(is)i(gi)n(v)o(en,)g(the)f(K)n(e)o(yP)o(ath)f(is)j(left)e(null)g(in)h (the)208 2767 y(Component)18 b(table.)0 2914 y FD(add_file)p FJ(\()p FK(\002le)p FC([)p FK(,)g(sr)m(c)p FC([)p FK(,)j(ver)o(sion)p FC([)p FK(,)f(langua)o(g)o(e)12 b FC(])g(])g(])p FJ(\))208 3014 y FN(Add)24 b(a)i(\002le)g(to)f(the)g(current)f(component)f(of)i (the)g(directory)-5 b(,)24 b(starting)h(a)h(ne)n(w)f(one)f(if)i(there)f (is)h(no)f(current)f(component.)37 b(By)208 3113 y(def)o(ault,)19 b(the)i(\002le)h(name)e(in)h(the)f(source)g(and)h(the)f(\002le)i(table) e(will)i(be)f(identical.)26 b(If)20 b(the)h FK(sr)m(c)h FN(\002le)f(is)h(speci\002ed,)e(it)i(is)f(interpreted)208 3213 y(relati)n(v)o(e)h(to)h(the)g(current)f(directory)-5 b(.)32 b(Optionally)-5 b(,)22 b(a)i FK(ver)o(sion)f FN(and)g(a)g FK(langua)o(g)o(e)e FN(can)i(be)g(speci\002ed)g(for)g(the)g(entry)f(in) i(the)f(File)208 3313 y(table.)0 3460 y FD(glob)p FJ(\()p FK(pattern)p FC([)p FK(,)18 b(e)n(xclude)12 b FC(])p FJ(\))208 3559 y FN(Add)22 b(a)g(list)i(of)e(\002les)i(to)e(the)h (current)e(component)f(as)j(speci\002ed)f(in)h(the)f(glob)g(pattern.)31 b(Indi)n(vidual)20 b(\002les)j(can)g(be)f(e)o(xcluded)e(in)208 3659 y(the)g FK(e)n(xclude)f FN(list.)0 3806 y FD(remove_pyc)p FJ(\(\))208 3905 y FN(Remo)o(v)o(e)g FJ(.pyc)p FN(/)p FJ(.pyo)g FN(\002les)i(on)f(uninstall.)0 4052 y FL(See)h(Also:)0 4199 y FK(Dir)m(ectory)f(T)-8 b(able)0 4299 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o(/d)o (ire)o(ctor)r(y)p 1973 4299 23 4 v 21 w(tab)o(le)o(.asp)m Fy(\))0 4446 y FK(F)l(ile)21 b(T)-8 b(able)0 4545 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o (/\002le)p 1780 4545 V 20 w(tab)o(le)o(.asp)m Fy(\))0 4692 y FK(Component)19 b(T)-8 b(able)0 4792 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o(/compo) o(ne)o(nt)p 2054 4792 V 20 w(tab)o(le)o(.asp)m Fy(\))0 4939 y FK(F)i(eatur)m(eComponents)17 b(T)-8 b(able)0 5038 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o (s/msi/setup)o(/f)m(ea)o(ture)o(compo)o(ne)o(nts)p 2322 5038 V 21 w(tab)o(le)o(.asp)m Fy(\))p 0 5549 3901 4 v 0 5649 a FI(36.1.)52 b FJ(msilib)22 b FI(\227)h(Read)h(and)f(wr)q(ite)h (Microsoft)f(Installer)h(\002les)1693 b(937)p eop end %%Page: 938 950 TeXDict begin 938 949 bop 0 83 a Fv(36.1.8)101 b(F)m(eatures)0 272 y FL(class)21 b FD(Feature)p FJ(\()p FK(database)o(,)c(id,)j(title) o(,)h(desc,)f(display)p FC([)p FK(,)f(le)o(vel=1)p FC([)p FK(,)g(par)m(ent)q FC([)p FK(,)h(dir)m(ectory)p FC([)p FK(,)f(attrib)n(utes=0)12 b FC(])g(])g(])g(])p FJ(\))208 372 y FN(Add)19 b(a)h(ne)n(w)g(record)f(to)h(the)g FJ(Feature)f FN(table,)h(using)f(the)h(v)n(alues)f FK(id)r FN(,)i FK(par)m(ent.id)r FN(,)d FK(title)p FN(,)j FK(desc)p FN(,)e FK(display)p FN(,)h FK(le)o(vel)p FN(,)g FK(dir)m(ectory)p FN(,)f(and)208 471 y FK(attrib)n(utes)p FN(.)25 b(The)20 b(resulting)f(feature)g(object)h(can)g(be)g(passed)g(to)g(the)h FJ(start_component)c FN(method)i(of)h FJ(Directory)p FN(.)0 618 y FD(set_current)p FJ(\(\))208 718 y FN(Mak)o(e)30 b(this)h(feature)f(the)h(current)e(feature)h(of)g FJ(msilib)p FN(.)56 b(Ne)n(w)31 b(components)d(are)j(automatically)e(added)h(to)h (the)f(def)o(ault)208 817 y(feature,)19 b(unless)h(a)g(feature)g(is)h (e)o(xplicitly)e(speci\002ed.)0 964 y FL(See)i(Also:)0 1111 y FK(F)-6 b(eatur)m(e)19 b(T)-8 b(able)0 1211 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o (/f)m(ea)o(ture)p 1915 1211 23 4 v 20 w(tab)o(le)o(.asp)m Fy(\))0 1496 y Fv(36.1.9)101 b(GUI)26 b(classes)0 1698 y FJ(msilib)19 b FN(pro)o(vides)e(se)n(v)o(eral)h(classes)j(that)e (wrap)f(the)h(GUI)h(tables)f(in)g(an)g(MSI)h(database.)k(Ho)n(we)n(v)o (er)m(,)17 b(no)h(standard)g(user)h(interf)o(ace)g(is)0 1798 y(pro)o(vided;)f(use)i FJ(bdist_msi)f FN(to)i(create)e(MSI)i (\002les)g(with)f(a)h(user)n(-interf)o(ace)e(for)g(installing)h(Python) f(packages.)0 1945 y FL(class)i FD(Control)p FJ(\()p FK(dlg)o(,)d(name)p FJ(\))208 2045 y FN(Base)i(class)g(of)f(the)g (dialog)g(controls.)k FK(dlg)c FN(is)h(the)g(dialog)e(object)h(the)g (control)f(belongs)g(to,)h(and)g FK(name)g FN(is)h(the)f(control')-5 b(s)18 b(name.)0 2191 y FD(event)p FJ(\()p FK(e)o(vent,)g(ar)m(gument)q FC([)p FK(,)h(condition)g(=)h(\2231\224)p FC([)p FK(,)h(or)m(dering)12 b FC(])g(])p FJ(\))208 2291 y FN(Mak)o(e)20 b(an)g(entry)f(into)h(the)g FJ(ControlEvent)f FN(table)h(for)f(this)i(control.)0 2438 y FD(mapping)p FJ(\()p FK(e)o(vent,)d(attrib)n(ute)p FJ(\))208 2538 y FN(Mak)o(e)i(an)g(entry)f(into)h(the)g FJ(EventMapping)f FN(table)h(for)f(this)i(control.)0 2684 y FD(condition)p FJ(\()p FK(action,)c(condition)p FJ(\))208 2784 y FN(Mak)o(e)j(an)g(entry)f(into)h(the)g FJ(ControlCondition)e FN(table)i(for)g(this)g(control.)0 2931 y FL(class)h FD(RadioButtonGroup)p FJ(\()p FK(dlg)o(,)16 b(name)o(,)k(pr)l(operty)p FJ(\))208 3031 y FN(Create)g(a)i(radio)d(b)n (utton)h(control)g(named)f FK(name)p FN(.)26 b FK(pr)l(operty)20 b FN(is)i(the)f(installer)f(property)f(that)h(gets)h(set)h(when)e(a)h (radio)f(b)n(utton)g(is)208 3130 y(selected.)0 3277 y FD(add)p FJ(\()p FK(name)o(,)f(x,)h(y)-5 b(,)21 b(width,)f(height,)f (te)n(xt)k FC([)p FK(,)d(value)12 b FC(])p FJ(\))208 3377 y FN(Add)23 b(a)h(radio)f(b)n(utton)g(named)g FK(name)g FN(to)h(the)g(group,)f(at)h(the)g(coordinates)e FK(x)p FN(,)j FK(y)p FN(,)g FK(width)p FN(,)g FK(height)q FN(,)f(and)f(with)h (the)g(label)g FK(te)n(xt)q FN(.)37 b(If)208 3476 y FK(value)19 b FN(is)i(omitted,)e(it)i(def)o(aults)f(to)h FK(name)p FN(.)0 3623 y FL(class)g FD(Dialog)p FJ(\()p FK(db,)d(name)o(,)i(x,)g (y)-5 b(,)21 b(w)-6 b(,)20 b(h,)g(attr)-9 b(,)21 b(title)o(,)g(\002r)o (st,)f(default,)g(cancel)p FJ(\))208 3723 y FN(Return)25 b(a)h(ne)n(w)f FJ(Dialog)g FN(object.)40 b(An)26 b(entry)e(in)i(the)f FJ(Dialog)g FN(table)h(is)g(made,)g(with)g(the)f(speci\002ed)h (coordinates,)e(dialog)208 3822 y(attrib)n(utes,)19 b(title,)i(name)f (of)g(the)g(\002rst,)g(def)o(ault,)g(and)f(cancel)h(controls.)0 3969 y FD(control)p FJ(\()p FK(name)o(,)e(type)o(,)i(x,)g(y)-5 b(,)21 b(width,)f(height,)f(attrib)n(utes,)h(pr)l(operty)-5 b(,)21 b(te)n(xt,)f(contr)l(ol)p 2504 3969 25 4 v 29 w(ne)n(xt,)g(help)p FJ(\))208 4069 y FN(Return)f(a)i(ne)n(w)f FJ(Control)f FN(object.)25 b(An)20 b(entry)f(in)i(the)f FJ(Control)f FN(table)h(is)i(made)d(with)i(the)f(speci\002ed)g (parameters.)208 4202 y(This)g(is)h(a)g(generic)e(method;)g(for)g (speci\002c)i(types,)e(specialized)h(methods)f(are)h(pro)o(vided.)0 4349 y FD(text)p FJ(\()p FK(name)o(,)f(x,)h(y)-5 b(,)21 b(width,)f(height,)f(attrib)n(utes,)h(te)n(xt)q FJ(\))208 4448 y FN(Add)f(and)h(return)f(a)i FJ(Text)f FN(control.)0 4595 y FD(bitmap)p FJ(\()p FK(name)o(,)e(x,)j(y)-5 b(,)20 b(width,)g(height,)g(te)n(xt)q FJ(\))208 4695 y FN(Add)f(and)h(return)f (a)i FJ(Bitmap)e FN(control.)0 4842 y FD(line)p FJ(\()p FK(name)o(,)g(x,)h(y)-5 b(,)21 b(width,)f(height)q FJ(\))208 4941 y FN(Add)f(and)h(return)f(a)i FJ(Line)f FN(control.)0 5088 y FD(pushbutton)p FJ(\()p FK(name)o(,)d(x,)k(y)-5 b(,)21 b(width,)f(height,)f(attrib)n(utes,)h(te)n(xt,)h(ne)n(xt)p 2056 5088 V 29 w(contr)l(ol)p FJ(\))208 5188 y FN(Add)e(and)h(return)f (a)i FJ(PushButton)d FN(control.)0 5335 y FD(radiogroup)p FJ(\()p FK(name)o(,)f(x,)k(y)-5 b(,)21 b(width,)f(height,)f(attrib)n (utes,)h(pr)l(operty)-5 b(,)20 b(te)n(xt,)h(ne)n(xt)p 2375 5335 V 29 w(contr)l(ol)p FJ(\))p 0 5549 3901 4 v 0 5649 a FI(938)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f (Speci\002c)g(Ser)r(vices)p eop end %%Page: 939 951 TeXDict begin 939 950 bop 208 83 a FN(Add)19 b(and)h(return)f(a)i FJ(RadioButtonGroup)c FN(control.)0 230 y FD(checkbox)p FJ(\()p FK(name)o(,)h(x,)i(y)-5 b(,)21 b(width,)f(height,)f(attrib)n (utes,)h(pr)l(operty)-5 b(,)20 b(te)n(xt,)h(ne)n(xt)p 2275 230 25 4 v 30 w(contr)l(ol)p FJ(\))208 330 y FN(Add)e(and)h (return)f(a)i FJ(CheckBox)e FN(control.)0 476 y FL(See)i(Also:)0 623 y FK(Dialo)o(g)f(T)-8 b(able)0 723 y Fy(\()p FO (http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o(/d)o(ia)o (log)p 1884 723 23 4 v 20 w(tab)o(le)o(.asp)m Fy(\))0 870 y FK(Contr)l(ol)20 b(T)-8 b(able)0 969 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o(/con)o (tro)o(l)p 1909 969 V 21 w(tab)o(le)o(.asp)m Fy(\))0 1116 y FK(Contr)l(ol)20 b(T)-6 b(ypes)0 1216 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r(y/en-u)o(s/msi/setup)o(/con)o (tro)o(ls)o(.asp)g Fy(\))0 1363 y FK(Contr)l(olCondition)19 b(T)-8 b(able)0 1462 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r (y/en-u)o(s/msi/setup)o(/con)o(tro)o(lcon)o(dit)o(ion)p 2208 1462 V 20 w(tab)o(le)o(.asp)m Fy(\))0 1609 y FK(Contr)l(olEvent)19 b(T)-8 b(able)0 1709 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r (y/en-u)o(s/msi/setup)o(/con)o(tro)o(le)m(v)n(ent)p 2088 1709 V 21 w(tab)o(le)o(.asp)l Fy(\))0 1856 y FK(EventMapping)18 b(T)-8 b(able)0 1955 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r (y/en-u)o(s/msi/setup)o(/e)m(v)n(ent)o(mapp)o(in)o(g)p 2150 1955 V 21 w(tab)o(le)o(.asp)m Fy(\))0 2102 y FK(RadioButton)18 b(T)-8 b(able)0 2202 y Fy(\()p FO(http://msdn.microsoft.com/libr)o(ar)r (y/en-u)o(s/msi/setup)o(/r)o(a)o(dio)o(b)n(utt)o(on)p 2056 2202 V 20 w(tab)o(le)o(.asp)m Fy(\))0 2487 y Fv(36.1.10)101 b(Precomputed)30 b(tab)n(les)0 2690 y FJ(msilib)22 b FN(pro)o(vides)g(a)h(fe)n(w)g(subpackages)e(that)i(contain)f(only)g (schema)g(and)h(table)f(de\002nitions.)33 b(Currently)-5 b(,)21 b(these)j(de\002nitions)e(are)0 2789 y(based)e(on)g(MSI)g(v)o (ersion)f(2.0.)0 2936 y FD(schema)208 3036 y FN(This)k(is)g(the)g (standard)f(MSI)h(schema)f(for)h(MSI)g(2.0,)f(with)h(the)g FK(tables)g FN(v)n(ariable)f(pro)o(viding)e(a)j(list)h(of)f(table)g (de\002nitions,)f(and)p 208 3135 25 4 v 232 3135 a FK(V)-9 b(alidation)p 581 3135 V 28 w(r)m(ecor)m(ds)20 b FN(pro)o(viding)d(the) k(data)f(for)f(MSI)i(v)n(alidation.)0 3282 y FD(sequence)208 3382 y FN(This)30 b(module)f(contains)g(table)h(contents)g(for)g(the)g (standard)f(sequence)g(tables:)46 b FK(AdminExecuteSequence)p FN(,)28 b FK(AdminUISe-)208 3482 y(quence)p FN(,)18 b FK(AdvtExecuteSequence)p FN(,)e FK(InstallExecuteSequence)p FN(,)g(and)k FK(InstallUISequence)p FN(.)0 3628 y FD(text)208 3728 y FN(This)g(module)f(contains)g(de\002nitions)h(for)f(the)h(UIT)-6 b(e)o(xt)20 b(and)f(ActionT)-6 b(e)o(xt)19 b(tables,)h(for)g(the)g (standard)f(installer)i(actions.)0 4055 y FE(36.2)121 b Fx(msvcrt)32 b FE(\226)i(Useful)g(routines)g(from)f(the)i(MS)d(VC) 2596 4044 y(++)2769 4055 y(r)r(untime)0 4288 y FN(These)26 b(functions)f(pro)o(vide)g(access)i(to)f(some)g(useful)g(capabilities)g (on)g(W)m(indo)n(ws)g(platforms.)43 b(Some)26 b(higher)n(-le)n(v)o(el)e (modules)h(use)0 4388 y(these)20 b(functions)f(to)h(b)n(uild)f(the)h(W) m(indo)n(ws)f(implementations)f(of)i(their)f(services.)25 b(F)o(or)20 b(e)o(xample,)e(the)i FJ(getpass)f FN(module)g(uses)h(this) 0 4488 y(in)g(the)h(implementation)d(of)h(the)i FJ(getpass\(\))e FN(function.)0 4634 y(Further)g(documentation)e(on)j(these)h(functions) d(can)i(be)g(found)f(in)h(the)g(Platform)g(API)g(documentation.)0 4919 y Fv(36.2.1)101 b(File)28 b(Oper)o(ations)0 5108 y FD(locking)p FJ(\()p FK(fd,)19 b(mode)o(,)g(nbytes)p FJ(\))208 5208 y FN(Lock)26 b(part)h(of)h(a)f(\002le)i(based)e(on)g (\002le)h(descriptor)e FK(fd)k FN(from)c(the)i(C)g(runtime.)46 b(Raises)28 b FJ(IOError)f FN(on)g(f)o(ailure.)46 b(The)27 b(lock)o(ed)208 5307 y(re)o(gion)17 b(of)i(the)g(\002le)g(e)o(xtends)f (from)g(the)h(current)f(\002le)i(position)e(for)g FK(nbytes)h FN(bytes,)g(and)f(may)h(continue)f(be)o(yond)e(the)j(end)g(of)g(the)p 0 5549 3901 4 v 0 5649 a FI(36.2.)52 b FJ(msvcrt)22 b FI(\226)h(Useful)h(routines)f(from)g(the)h(MS)f(VC)1794 5641 y(++)1915 5649 y(r)q(untime)1570 b(939)p eop end %%Page: 940 952 TeXDict begin 940 951 bop 208 83 a FN(\002le.)26 b FK(mode)19 b FN(must)i(be)f(one)g(of)g(the)g FJ(LK_)p FK(*)g FN(constants)g (listed)g(belo)n(w)-5 b(.)25 b(Multiple)20 b(re)o(gions)f(in)h(a)h (\002le)g(may)f(be)g(lock)o(ed)f(at)i(the)f(same)208 183 y(time,)g(b)n(ut)g(may)g(not)f(o)o(v)o(erlap.)k(Adjacent)d(re)o (gions)f(are)h(not)g(mer)o(ged;)e(the)o(y)i(must)g(be)g(unlock)o(ed)e (indi)n(vidually)-5 b(.)0 330 y FD(LK_LOCK)0 429 y(LK_RLCK)208 529 y FN(Locks)19 b(the)h(speci\002ed)g(bytes.)25 b(If)20 b(the)g(bytes)g(cannot)f(be)h(lock)o(ed,)f(the)h(program)e(immediately) h(tries)i(again)e(after)h(1)g(second.)k(If,)208 628 y(after)19 b(10)h(attempts,)g(the)g(bytes)g(cannot)f(be)h(lock)o(ed,)g FJ(IOError)f FN(is)i(raised.)0 775 y FD(LK_NBLCK)0 875 y(LK_NBRLCK)208 975 y FN(Locks)e(the)h(speci\002ed)g(bytes.)25 b(If)20 b(the)g(bytes)g(cannot)f(be)i(lock)o(ed,)e FJ(IOError)g FN(is)i(raised.)0 1121 y FD(LK_UNLCK)208 1221 y FN(Unlocks)e(the)h (speci\002ed)g(bytes,)g(which)g(must)g(ha)n(v)o(e)f(been)h(pre)n (viously)e(lock)o(ed.)0 1368 y FD(setmode)p FJ(\()p FK(fd,)h(\003a)o (gs)p FJ(\))208 1468 y FN(Set)i(the)g(line-end)e(translation)h(mode)f (for)h(the)h(\002le)g(descriptor)f FK(fd)r FN(.)26 b(T)-7 b(o)21 b(set)h(it)f(to)g(te)o(xt)g(mode,)e FK(\003a)o(gs)h FN(should)g(be)h FJ(os.O_TEXT)p FN(;)208 1567 y(for)e(binary)-5 b(,)18 b(it)j(should)e(be)i FJ(os.O_BINARY)p FN(.)0 1714 y FD(open_osfhandle)p FJ(\()p FK(handle)o(,)16 b(\003a)o(gs)p FJ(\))208 1814 y FN(Create)22 b(a)h(C)g(runtime)e(\002le)i(descriptor)e (from)h(the)g(\002le)h(handle)e FK(handle)p FN(.)30 b(The)22 b FK(\003a)o(gs)g FN(parameter)f(should)g(be)h(a)h(bit-wise)g(OR)g(of) 208 1913 y FJ(os.O_APPEND)p FN(,)e FJ(os.O_RDONLY)p FN(,)h(and)h FJ(os.O_TEXT)p FN(.)f(The)h(returned)e(\002le)j(descriptor)e(may)h(be)g (used)g(as)h(a)g(parameter)208 2013 y(to)c FJ(os.fdopen\(\))f FN(to)h(create)g(a)g(\002le)h(object.)0 2160 y FD(get_osfhandle)p FJ(\()p FK(fd)r FJ(\))208 2259 y FN(Return)e(the)i(\002le)f(handle)f (for)h(the)g(\002le)h(descriptor)e FK(fd)r FN(.)25 b(Raises)d FJ(IOError)d FN(if)i FK(fd)h FN(is)f(not)f(recognized.)0 2544 y Fv(36.2.2)101 b(Console)29 b(I/O)0 2733 y FD(kbhit)p FJ(\(\))208 2833 y FN(Return)19 b(true)h(if)h(a)f(k)o(e)o(ypress)f(is)j (w)o(aiting)e(to)g(be)g(read.)0 2980 y FD(getch)p FJ(\(\))208 3079 y FN(Read)k(a)g(k)o(e)o(ypress)f(and)h(return)f(the)h(resulting)f (character)-5 b(.)36 b(Nothing)23 b(is)i(echoed)e(to)h(the)g(console.) 36 b(This)24 b(call)h(will)g(block)e(if)h(a)208 3179 y(k)o(e)o(ypress)f(is)j(not)e(already)g(a)n(v)n(ailable,)h(b)n(ut)g (will)h(not)e(w)o(ait)h(for)g FJ(Enter)f FN(to)h(be)g(pressed.)38 b(If)24 b(the)h(pressed)g(k)o(e)o(y)f(w)o(as)h(a)g(special)208 3279 y(function)h(k)o(e)o(y)-5 b(,)28 b(this)h(will)f(return)f FJ('\\000')g FN(or)h FJ('\\xe0')p FN(;)j(the)d(ne)o(xt)f(call)h(will)h (return)d(the)i(k)o(e)o(ycode.)46 b(The)28 b FJ(Control-C)208 3378 y FN(k)o(e)o(ypress)19 b(cannot)g(be)h(read)g(with)g(this)h (function.)0 3525 y FD(getche)p FJ(\(\))208 3625 y FN(Similar)f(to)g FJ(getch\(\))p FN(,)f(b)n(ut)i(the)f(k)o(e)o(ypress)f(will)i(be)f (echoed)f(if)h(it)h(represents)f(a)g(printable)f(character)-5 b(.)0 3772 y FD(putch)p FJ(\()p FK(c)o(har)r FJ(\))208 3871 y FN(Print)20 b(the)g(character)f FK(c)o(har)j FN(to)e(the)g (console)f(without)h(b)n(uf)n(fering.)0 4018 y FD(ungetch)p FJ(\()p FK(c)o(har)r FJ(\))208 4118 y FN(Cause)30 b(the)g(character)f FK(c)o(har)j FN(to)e(be)g(\223pushed)f(back\224)g(into)h(the)h(console) e(b)n(uf)n(fer;)34 b(it)d(will)g(be)f(the)g(ne)o(xt)f(character)g(read) h(by)208 4217 y FJ(getch\(\))19 b FN(or)h FJ(getche\(\))p FN(.)0 4502 y Fv(36.2.3)101 b(Other)27 b(Functions)0 4691 y FD(heapmin)p FJ(\(\))208 4791 y FN(F)o(orce)18 b(the)h FJ(malloc\(\))f FN(heap)h(to)g(clean)g(itself)h(up)f(and)f (return)g(unused)g(blocks)h(to)g(the)g(operating)e(system.)25 b(This)20 b(only)e(w)o(orks)208 4890 y(on)h(W)m(indo)n(ws)h(NT)-6 b(.)20 b(On)g(f)o(ailure,)g(this)g(raises)h FJ(IOError)p FN(.)p 0 5549 3901 4 v 0 5649 a FI(940)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g(Ser)r(vices)p eop end %%Page: 941 953 TeXDict begin 941 952 bop 0 86 a FE(36.3)121 b Fx(_winreg)32 b FE(\226)h(Windo)n(ws)i(registr)t(y)d(access)0 319 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(2.0.)0 466 y(These)28 b(functions)f(e)o(xpose)g(the)i(W)m(indo)n(ws)e(re)o(gistry)h(API)g(to) h(Python.)48 b(Instead)28 b(of)g(using)g(an)g(inte)o(ger)f(as)i(the)g (re)o(gistry)e(handle,)i(a)0 566 y(handle)17 b(object)g(is)i(used)e(to) h(ensure)f(that)h(the)g(handles)f(are)g(closed)h(correctly)-5 b(,)16 b(e)n(v)o(en)h(if)h(the)g(programmer)d(ne)o(glects)i(to)h(e)o (xplicitly)e(close)0 665 y(them.)0 812 y(This)h(module)f(e)o(xposes)g (a)h(v)o(ery)f(lo)n(w-le)n(v)o(el)f(interf)o(ace)h(to)h(the)g(W)m(indo) n(ws)g(re)o(gistry;)g(it)g(is)h(e)o(xpected)d(that)i(in)g(the)g(future) f(a)h(ne)n(w)g FJ(winreg)0 912 y FN(module)i(will)i(be)f(created)f(of)n (fering)f(a)j(higher)n(-le)n(v)o(el)d(interf)o(ace)h(to)i(the)f(re)o (gistry)f(API.)0 1059 y(This)h(module)f(of)n(fers)g(the)i(follo)n(wing) d(functions:)0 1206 y FD(CloseKey)p FJ(\()p FK(hk)o(e)n(y)p FJ(\))208 1305 y FN(Closes)j(a)f(pre)n(viously)f(opened)f(re)o(gistry)h (k)o(e)o(y)-5 b(.)24 b(The)c(hk)o(e)o(y)f(ar)o(gument)f(speci\002es)j (a)f(pre)n(viously)e(opened)h(k)o(e)o(y)-5 b(.)208 1438 y(Note)20 b(that)g(if)g FK(hk)o(e)n(y)g FN(is)h(not)f(closed)g(using)f (this)i(method)e(\(or)g(via)i FJ(handle.Close\(\))p FN(\),)c(it)k(is)g (closed)f(when)f(the)i FK(hk)o(e)n(y)e FN(object)208 1538 y(is)i(destro)o(yed)d(by)i(Python.)0 1684 y FD(ConnectRegistry)p FJ(\()p FK(computer)p 1120 1684 25 4 v 25 w(name)o(,)g(k)o(e)n(y)p FJ(\))208 1784 y FN(Establishes)g(a)h(connection)d(to)i(a)h (prede\002ned)d(re)o(gistry)h(handle)g(on)h(another)e(computer)m(,)g (and)i(returns)f(a)i FK(handle)e(object)208 1917 y(computer)p 528 1917 V 28 w(name)j FN(is)i(the)f(name)f(of)h(the)g(remote)e (computer)m(,)h(of)g(the)h(form)f FJ(r"\\\\computername")p FN(.)30 b(If)23 b FJ(None)p FN(,)g(the)g(local)208 2017 y(computer)18 b(is)j(used.)208 2149 y FK(k)o(e)n(y)f FN(is)h(the)f(prede\002ned)e(handle)h(to)i(connect)d(to.)208 2282 y(The)k(return)h(v)n(alue)f(is)i(the)g(handle)e(of)h(the)g(opened) f(k)o(e)o(y)-5 b(.)33 b(If)23 b(the)g(function)f(f)o(ails,)i(an)f FJ(EnvironmentError)e FN(e)o(xception)h(is)208 2382 y(raised.)0 2529 y FD(CreateKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(sub)p 763 2529 V 30 w(k)o(e)n(y)p FJ(\))208 2628 y FN(Creates)i(or)g(opens)g(the)g(speci\002ed)g(k)o(e)o(y)-5 b(,)19 b(returning)f(a)i FK(handle)f(object)208 2761 y(k)o(e)n(y)h FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f(the)i(prede\002ned)d FJ(HKEY_)2176 2776 y(*)2245 2761 y FN(constants.)208 2894 y FK(sub)p 329 2894 V 29 w(k)o(e)n(y)i FN(is)h(a)g(string)e(that)i(names)f(the)g (k)o(e)o(y)f(this)i(method)e(opens)g(or)h(creates.)208 3027 y(If)25 b FK(k)o(e)n(y)g FN(is)i(one)e(of)g(the)h(prede\002ned)d (k)o(e)o(ys,)k FK(sub)p 1569 3027 V 29 w(k)o(e)n(y)e FN(may)g(be)h FJ(None)p FN(.)41 b(In)25 b(that)h(case,)h(the)e(handle)g (returned)e(is)k(the)e(same)h(k)o(e)o(y)208 3127 y(handle)19 b(passed)h(in)g(to)g(the)h(function.)208 3259 y(If)f(the)g(k)o(e)o(y)f (already)g(e)o(xists,)i(this)g(function)d(opens)h(the)i(e)o(xisting)e (k)o(e)o(y)-5 b(.)208 3392 y(The)22 b(return)h(v)n(alue)f(is)i(the)g (handle)e(of)h(the)g(opened)f(k)o(e)o(y)-5 b(.)33 b(If)23 b(the)g(function)f(f)o(ails,)i(an)f FJ(EnvironmentError)e FN(e)o(xception)h(is)208 3492 y(raised.)0 3639 y FD(DeleteKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(sub)p 763 3639 V 30 w(k)o(e)n(y)p FJ(\))208 3738 y FN(Deletes)i(the)g(speci\002ed)g(k)o(e)o (y)-5 b(.)208 3871 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k) o(e)o(y)-5 b(,)19 b(or)h(an)o(y)f(one)h(of)g(the)g(prede\002ned)e FJ(HKEY_)2315 3886 y(*)2385 3871 y FN(constants.)208 4004 y FK(sub)p 329 4004 V 29 w(k)o(e)n(y)27 b FN(is)i(a)f(string)f (that)h(must)f(be)h(a)g(subk)o(e)o(y)e(of)h(the)h(k)o(e)o(y)f (identi\002ed)g(by)g(the)h FK(k)o(e)n(y)f FN(parameter)-5 b(.)46 b(This)28 b(v)n(alue)f(must)g(not)h(be)208 4104 y FJ(None)p FN(,)19 b(and)h(the)g(k)o(e)o(y)g(may)f(not)h(ha)n(v)o(e)g (subk)o(e)o(ys.)208 4236 y FK(This)g(method)g(can)f(not)h(delete)g(k)o (e)n(ys)g(with)h(subk)o(e)n(ys.)208 4369 y FN(If)38 b(the)g(method)f (succeeds,)43 b(the)38 b(entire)g(k)o(e)o(y)-5 b(,)42 b(including)36 b(all)j(of)f(its)i(v)n(alues,)i(is)d(remo)o(v)o(ed.)78 b(If)38 b(the)g(method)f(f)o(ails,)44 b(an)208 4469 y FJ(EnvironmentError)17 b FN(e)o(xception)i(is)i(raised.)0 4616 y FD(DeleteValue)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(value)p FJ(\))208 4715 y FN(Remo)o(v)o(es)h(a)h(named)g(v)n(alue)f (from)g(a)i(re)o(gistry)e(k)o(e)o(y)-5 b(.)208 4848 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f(the)i(prede\002ned)d FJ(HKEY_)2176 4863 y(*)2245 4848 y FN(constants.)208 4981 y FK(value)h FN(is)i(a)g(string)f(that)g(identi\002es)g(the)g(v)n(alue)g(to)g(remo)o (v)o(e.)0 5128 y FD(EnumKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(inde)n(x)p FJ(\))208 5228 y FN(Enumerates)f(subk)o(e)o(ys)h (of)h(an)g(open)g(re)o(gistry)f(k)o(e)o(y)-5 b(,)19 b(returning)f(a)i (string.)208 5360 y FK(k)o(e)n(y)g FN(is)h(an)f(already)f(open)g(k)o(e) o(y)-5 b(,)19 b(or)h(an)o(y)f(one)h(of)g(the)g(prede\002ned)e FJ(HKEY_)2315 5375 y(*)2385 5360 y FN(constants.)p 0 5549 3901 4 v 0 5649 a FI(36.3.)52 b FJ(_winreg)22 b FI(\226)h(Windo)o(ws)h(registr)r(y)f(access)2168 b(941)p eop end %%Page: 942 954 TeXDict begin 942 953 bop 208 83 a FK(inde)n(x)20 b FN(is)h(an)f(inte)o (ger)f(that)h(identi\002es)h(the)f(inde)o(x)f(of)h(the)g(k)o(e)o(y)f (to)i(retrie)n(v)o(e.)208 216 y(The)k(function)e(retrie)n(v)o(es)i(the) g(name)g(of)g(one)g(subk)o(e)o(y)f(each)h(time)h(it)g(is)g(called.)41 b(It)25 b(is)i(typically)d(called)i(repeatedly)d(until)j(an)208 315 y FJ(EnvironmentError)17 b FN(e)o(xception)i(is)i(raised,)f (indicating,)e(no)i(more)f(v)n(alues)h(are)g(a)n(v)n(ailable.)0 462 y FD(EnumValue)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(inde)n(x)p FJ(\))208 562 y FN(Enumerates)g(v)n(alues)i(of)g(an)g(open)f(re)o (gistry)g(k)o(e)o(y)-5 b(,)19 b(returning)f(a)j(tuple.)208 695 y FK(k)o(e)n(y)f FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(an)o(y)f(one)h(of)g(the)g(prede\002ned)e FJ(HKEY_)2315 710 y(*)2385 695 y FN(constants.)208 828 y FK(inde)n(x)i FN(is)h(an)f(inte)o(ger)f(that)h(identi\002es)h(the)f (inde)o(x)f(of)h(the)g(v)n(alue)f(to)i(retrie)n(v)o(e.)208 960 y(The)j(function)f(retrie)n(v)o(es)g(the)i(name)f(of)h(one)f(subk)o (e)o(y)f(each)h(time)h(it)g(is)h(called.)38 b(It)25 b(is)g(typically)f (called)h(repeatedly)-5 b(,)23 b(until)i(an)208 1060 y FJ(EnvironmentError)17 b FN(e)o(xception)i(is)i(raised,)f(indicating) e(no)i(more)f(v)n(alues.)208 1193 y(The)g(result)i(is)g(a)f(tuple)g(of) g(3)g(items:)1002 1322 y FL(Index)p 1254 1352 4 100 v 100 w(Meaning)p 953 1355 2203 4 v 1079 1425 a FJ(0)p 1254 1455 4 100 v 176 w FN(A)h(string)f(that)g(identi\002es)g(the)g(v)n (alue)g(name)1079 1525 y FJ(1)p 1254 1654 4 200 v 176 w FN(An)30 b(object)g(that)g(holds)f(the)h(v)n(alue)g(data,)i(and)d (whose)h(type)1305 1624 y(depends)19 b(on)h(the)g(underlying)d(re)o (gistry)j(type)1079 1724 y FJ(2)p 1254 1754 4 100 v 176 w FN(An)g(inte)o(ger)f(that)i(identi\002es)f(the)g(type)g(of)g(the)g(v) n(alue)f(data)0 1866 y FD(FlushKey)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 1966 y FN(Writes)i(all)f(the)h(attrib)n(utes)f(of)g(a)g(k)o (e)o(y)g(to)g(the)g(re)o(gistry)-5 b(.)208 2099 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f (the)i(prede\002ned)d FJ(HKEY_)2176 2114 y(*)2245 2099 y FN(constants.)208 2232 y(It)26 b(is)h(not)f(necessary)f(to)h(call)h (Re)o(gFlushK)n(e)o(y)d(to)j(change)d(a)j(k)o(e)o(y)-5 b(.)41 b(Re)o(gistry)26 b(changes)f(are)h(\003ushed)g(to)g(disk)g(by)g (the)g(re)o(gistry)208 2331 y(using)20 b(its)h(lazy)g(\003usher)-5 b(.)26 b(Re)o(gistry)20 b(changes)g(are)g(also)h(\003ushed)f(to)h(disk) g(at)g(system)g(shutdo)n(wn.)j(Unlik)o(e)c FJ(CloseKey\(\))p FN(,)g(the)208 2431 y FJ(FlushKey\(\))k FN(method)g(returns)h(only)g (when)g(all)h(the)g(data)g(has)g(been)f(written)g(to)h(the)g(re)o (gistry)-5 b(.)40 b(An)25 b(application)g(should)208 2530 y(only)19 b(call)i FJ(FlushKey\(\))d FN(if)j(it)g(requires)e (absolute)g(certainty)h(that)g(re)o(gistry)f(changes)g(are)h(on)g (disk.)208 2663 y FK(If)g(you)g(don')n(t)e(know)i(whether)g(a)h Fn(FlushKey\(\))e FK(call)h(is)h(r)m(equir)m(ed,)e(it)i(pr)l(obably)e (isn')n(t.)0 2810 y FD(RegLoadKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(sub)p 813 2810 25 4 v 29 w(k)o(e)n(y)-5 b(,)21 b(\002le)p 1089 2810 V 29 w(name)p FJ(\))208 2910 y FN(Creates)16 b(a)h(subk)o(e)o(y)e(under)g(the)h(speci\002ed)g(k)o(e)o(y)g(and)f (stores)i(re)o(gistration)e(information)e(from)j(a)g(speci\002ed)g (\002le)h(into)f(that)h(subk)o(e)o(y)-5 b(.)208 3043 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(an)o(y)f(of)h(the)g(prede\002ned)f FJ(HKEY_)2175 3058 y(*)2244 3043 y FN(constants.)208 3175 y FK(sub)p 329 3175 V 29 w(k)o(e)n(y)h FN(is)h(a)g(string)e(that)i(identi\002es)f (the)g(sub)p 1538 3175 V 29 w(k)o(e)o(y)g(to)g(load.)208 3308 y FK(\002le)p 315 3308 V 29 w(name)15 b FN(is)h(the)f(name)g(of)g (the)g(\002le)h(to)f(load)g(re)o(gistry)f(data)h(from.)23 b(This)15 b(\002le)h(must)f(ha)n(v)o(e)g(been)f(created)h(with)g(the)h FJ(SaveKey\(\))208 3408 y FN(function.)23 b(Under)c(the)h(\002le)h (allocation)e(table)h(\(F)-6 b(A)d(T\))20 b(\002le)h(system,)f(the)g (\002lename)g(may)g(not)f(ha)n(v)o(e)h(an)g(e)o(xtension.)208 3541 y(A)h(call)h(to)f(LoadK)n(e)o(y\(\))e(f)o(ails)j(if)g(the)f (calling)g(process)f(does)h(not)g(ha)n(v)o(e)g(the)g FJ(SE_RESTORE_PRIVILEGE)d FN(pri)n(vile)o(ge.)27 b(Note)208 3640 y(that)20 b(pri)n(vile)o(ges)f(are)h(dif)n(ferent)e(than)i (permissions)g(-)g(see)h(the)f(W)m(in32)f(documentation)f(for)h(more)g (details.)208 3773 y(If)27 b FK(k)o(e)n(y)g FN(is)i(a)f(handle)e (returned)g(by)h FJ(ConnectRegistry\(\))p FN(,)g(then)g(the)g(path)g (speci\002ed)h(in)f FK(\002leName)h FN(is)g(relati)n(v)o(e)f(to)h(the) 208 3873 y(remote)19 b(computer)-5 b(.)208 4006 y(The)27 b(W)m(in32)f(documentation)f(implies)i FK(k)o(e)n(y)g FN(must)h(be)f(in)h(the)f FJ(HKEY_USER)f FN(or)h FJ(HKEY_LOCAL_MACHINE) e FN(tree.)46 b(This)208 4105 y(may)19 b(or)h(may)g(not)g(be)g(true.)0 4252 y FD(OpenKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(sub)p 664 4252 V 29 w(k)o(e)n(y)p FC([)p FK(,)h(r)m(es)50 b Fn(=)f(0)12 b FC(][)p FK(,)20 b(sam)50 b Fn(=)f(KEY_READ)14 b FC(])p FJ(\))208 4352 y FN(Opens)19 b(the)i(speci\002ed)f(k)o(e)o(y) -5 b(,)18 b(returning)h(a)h FK(handle)f(object)208 4485 y(k)o(e)n(y)h FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(an)o(y)f(one)h(of)g(the)g(prede\002ned)e FJ(HKEY_)2315 4500 y(*)2385 4485 y FN(constants.)208 4617 y FK(sub)p 329 4617 V 29 w(k)o(e)n(y)i FN(is)h(a)g(string)e(that)i (identi\002es)f(the)g(sub)p 1538 4617 V 29 w(k)o(e)o(y)g(to)g(open.)208 4750 y FK(r)m(es)h FN(is)g(a)f(reserv)o(ed)f(inte)o(ger)m(,)g(and)g (must)i(be)f(zero.)k(The)c(def)o(ault)f(is)i(zero.)208 4883 y FK(sam)h FN(is)h(an)e(inte)o(ger)g(that)h(speci\002es)h(an)e (access)i(mask)f(that)g(describes)f(the)h(desired)f(security)g(access)i (for)e(the)h(k)o(e)o(y)-5 b(.)29 b(Def)o(ault)22 b(is)208 4983 y FJ(KEY_READ)208 5116 y FN(The)d(result)i(is)g(a)f(ne)n(w)g (handle)f(to)i(the)f(speci\002ed)g(k)o(e)o(y)-5 b(.)208 5248 y(If)20 b(the)g(function)e(f)o(ails,)j FJ(EnvironmentError)d FN(is)j(raised.)p 0 5549 3901 4 v 0 5649 a FI(942)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g(Ser)r(vices)p eop end %%Page: 943 955 TeXDict begin 943 954 bop 0 83 a FD(OpenKeyEx)p FJ(\(\))208 183 y FN(The)19 b(functionality)f(of)i FJ(OpenKeyEx\(\))f FN(is)i(pro)o(vided)d(via)i FJ(OpenKey\(\))p FN(,)f(by)h(the)g(use)g (of)g(def)o(ault)g(ar)o(guments.)0 330 y FD(QueryInfoKey)p FJ(\()p FK(k)o(e)n(y)p FJ(\))208 429 y FN(Returns)g(information)d (about)j(a)g(k)o(e)o(y)-5 b(,)19 b(as)i(a)g(tuple.)208 561 y FK(k)o(e)n(y)f FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f(the)i(prede\002ned)d FJ(HKEY_)2176 576 y(*)2245 561 y FN(constants.)208 692 y(The)h(result)i(is)g(a)f (tuple)g(of)g(3)g(items:)1002 820 y FL(Index)p 1254 850 4 100 v 100 w(Meaning)p 953 854 2203 4 v 1079 923 a FJ(0)p 1254 953 4 100 v 176 w FN(An)g(inte)o(ger)e(gi)n(ving)g(the)i(number)d (of)i(sub)h(k)o(e)o(ys)f(this)h(k)o(e)o(y)f(has.)1079 1023 y FJ(1)p 1254 1053 V 176 w FN(An)h(inte)o(ger)f(gi)n(ving)g(the)h (number)f(of)h(v)n(alues)g(this)g(k)o(e)o(y)g(has.)1079 1123 y FJ(2)p 1254 1352 4 299 v 176 w FN(A)35 b(long)e(inte)o(ger)g(gi) n(ving)g(when)g(the)h(k)o(e)o(y)g(w)o(as)h(last)g(modi-)1305 1222 y(\002ed)c(\(if)f(a)n(v)n(ailable\))g(as)i(100')-5 b(s)30 b(of)g(nanoseconds)f(since)h(Jan)1305 1322 y(1,)20 b(1600.)0 1464 y FD(QueryValue)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(sub)p 813 1464 25 4 v 29 w(k)o(e)n(y)p FJ(\))208 1564 y FN(Retrie)n(v)o(es)i(the)g(unnamed)e(v)n(alue)h(for)h(a)h(k)o(e) o(y)-5 b(,)18 b(as)j(a)g(string)208 1695 y FK(k)o(e)n(y)f FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f (the)i(prede\002ned)d FJ(HKEY_)2176 1710 y(*)2245 1695 y FN(constants.)208 1827 y FK(sub)p 329 1827 V 29 w(k)o(e)n(y)26 b FN(is)i(a)f(string)f(that)g(holds)g(the)h(name)f(of)g(the)h(subk)o(e) o(y)e(with)i(which)f(the)g(v)n(alue)g(is)h(associated.)44 b(If)27 b(this)g(parameter)e(is)208 1926 y FJ(None)20 b FN(or)f(empty)-5 b(,)19 b(the)h(function)f(retrie)n(v)o(es)g(the)h(v) n(alue)g(set)h(by)f(the)g FJ(SetValue\(\))f FN(method)f(for)i(the)g(k)o (e)o(y)g(identi\002ed)f(by)h FK(k)o(e)n(y)p FN(.)208 2058 y(V)-9 b(alues)26 b(in)g(the)g(re)o(gistry)f(ha)n(v)o(e)g(name,)i (type,)g(and)e(data)h(components.)41 b(This)26 b(method)f(retrie)n(v)o (es)g(the)h(data)g(for)f(a)i(k)o(e)o(y')-5 b(s)26 b(\002rst)208 2158 y(v)n(alue)19 b(that)i(has)f(a)h(NULL)g(name.)k(But)c(the)f (underlying)e(API)j(call)g(doesn')o(t)d(return)i(the)g(type,)g(Lame)g (Lame)g(Lame,)g(DO)h(NO)m(T)208 2257 y(USE)f(THIS!!!)0 2404 y FD(QueryValueEx)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(value)p 978 2404 V 28 w(name)p FJ(\))208 2504 y FN(Retrie)n(v)o(es)i (the)g(type)f(and)h(data)g(for)g(a)g(speci\002ed)g(v)n(alue)g(name)f (associated)h(with)h(an)f(open)f(re)o(gistry)g(k)o(e)o(y)-5 b(.)208 2635 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k)o(e)o (y)-5 b(,)19 b(or)h(one)g(of)f(the)i(prede\002ned)d FJ(HKEY_)2176 2650 y(*)2245 2635 y FN(constants.)208 2767 y FK(value)p 394 2767 V 28 w(name)i FN(is)h(a)g(string)e(indicating)g(the)i(v)n (alue)e(to)h(query)-5 b(.)208 2899 y(The)19 b(result)i(is)g(a)f(tuple)g (of)g(2)g(items:)1002 3027 y FL(Index)p 1254 3056 4 100 v 100 w(Meaning)p 953 3060 2203 4 v 1079 3130 a FJ(0)p 1254 3159 4 100 v 176 w FN(The)g(v)n(alue)f(of)h(the)h(re)o(gistry)e (item.)1079 3229 y FJ(1)p 1254 3259 V 176 w FN(An)h(inte)o(ger)f(gi)n (ving)g(the)h(re)o(gistry)g(type)f(for)h(this)h(v)n(alue.)0 3371 y FD(SaveKey)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(\002le)p 650 3371 25 4 v 29 w(name)p FJ(\))208 3471 y FN(Sa)n(v)o(es)h(the)g (speci\002ed)g(k)o(e)o(y)-5 b(,)19 b(and)h(all)h(its)g(subk)o(e)o(ys)e (to)h(the)g(speci\002ed)g(\002le.)208 3603 y FK(k)o(e)n(y)g FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f (the)i(prede\002ned)d FJ(HKEY_)2176 3618 y(*)2245 3603 y FN(constants.)208 3734 y FK(\002le)p 315 3734 V 29 w(name)i FN(is)j(the)e(name)f(of)h(the)h(\002le)f(to)h(sa)n(v)o(e)f(re) o(gistry)f(data)h(to.)28 b(This)22 b(\002le)g(cannot)e(already)g(e)o (xist.)28 b(If)21 b(this)h(\002lename)e(includes)208 3834 y(an)d(e)o(xtension,)f(it)h(cannot)f(be)h(used)g(on)g(\002le)g (allocation)g(table)g(\(F)-6 b(A)d(T\))16 b(\002le)i(systems)f(by)g (the)g FJ(LoadKey\(\))p FN(,)f FJ(ReplaceKey\(\))208 3933 y FN(or)j FJ(RestoreKey\(\))g FN(methods.)208 4065 y(If)f FK(k)o(e)n(y)h FN(represents)g(a)g(k)o(e)o(y)f(on)h(a)h(remote)e (computer)m(,)f(the)i(path)f(described)g(by)h FK(\002le)p 2551 4065 V 29 w(name)f FN(is)i(relati)n(v)o(e)f(to)g(the)g(remote)f (computer)-5 b(.)208 4165 y(The)19 b(caller)h(of)g(this)h(method)e (must)h(possess)h(the)f FJ(SeBackupPrivilege)e FN(security)h(pri)n (vile)o(ge.)k(Note)e(that)f(pri)n(vile)o(ges)f(are)208 4264 y(dif)n(ferent)f(than)i(permissions)f(-)i(see)f(the)h(W)m(in32)e (documentation)e(for)j(more)f(details.)208 4396 y(This)h(function)e (passes)j(NULL)f(for)g FK(security)p 1534 4396 V 30 w(attrib)n(utes)g FN(to)g(the)h(API.)0 4543 y FD(SetValue)p FJ(\()p FK(k)o(e)n(y)-5 b(,)19 b(sub)p 714 4543 V 29 w(k)o(e)n(y)-5 b(,)20 b(type)o(,)g(value)p FJ(\))208 4642 y FN(Associates)g(a)h(v)n(alue)f(with)g(a)g(speci\002ed) g(k)o(e)o(y)-5 b(.)208 4774 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f (open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f(the)i(prede\002ned)d FJ(HKEY_)2176 4789 y(*)2245 4774 y FN(constants.)208 4906 y FK(sub)p 329 4906 V 29 w(k)o(e)n(y)i FN(is)h(a)g(string)e(that)i (names)f(the)g(subk)o(e)o(y)f(with)h(which)g(the)g(v)n(alue)f(is)j (associated.)208 5037 y FK(type)g FN(is)i(an)e(inte)o(ger)g(that)h (speci\002es)g(the)g(type)f(of)h(the)f(data.)33 b(Currently)21 b(this)i(must)g(be)g FJ(REG_SZ)p FN(,)f(meaning)f(only)h(strings)h(are) 208 5137 y(supported.)f(Use)f(the)g FJ(SetValueEx\(\))d FN(function)h(for)g(support)g(for)g(other)h(data)g(types.)208 5268 y FK(value)f FN(is)i(a)g(string)f(that)g(speci\002es)h(the)f(ne)n (w)g(v)n(alue.)208 5400 y(If)g(the)g(k)o(e)o(y)f(speci\002ed)h(by)g (the)g FK(sub)p 1207 5400 V 29 w(k)o(e)n(y)g FN(parameter)f(does)h(not) g(e)o(xist,)g(the)g(SetV)-9 b(alue)20 b(function)f(creates)h(it.)p 0 5549 3901 4 v 0 5649 a FI(36.3.)52 b FJ(_winreg)22 b FI(\226)h(Windo)o(ws)h(registr)r(y)f(access)2168 b(943)p eop end %%Page: 944 956 TeXDict begin 944 955 bop 208 83 a FN(V)-9 b(alue)24 b(lengths)h(are)g(limited)g(by)f(a)n(v)n(ailable)h(memory)-5 b(.)37 b(Long)24 b(v)n(alues)h(\(more)f(than)g(2048)g(bytes\))g(should) g(be)h(stored)g(as)h(\002les)208 183 y(with)20 b(the)g(\002lenames)g (stored)g(in)g(the)g(con\002guration)e(re)o(gistry)-5 b(.)23 b(This)e(helps)f(the)g(re)o(gistry)f(perform)f(ef)n(\002ciently) -5 b(.)208 315 y(The)19 b(k)o(e)o(y)h(identi\002ed)f(by)h(the)g FK(k)o(e)n(y)g FN(parameter)f(must)h(ha)n(v)o(e)g(been)f(opened)g(with) h FJ(KEY_SET_VALUE)f FN(access.)0 462 y FD(SetValueEx)p FJ(\()p FK(k)o(e)n(y)-5 b(,)18 b(value)p 878 462 25 4 v 29 w(name)o(,)h(r)m(eserved,)i(type)o(,)f(value)p FJ(\))208 562 y FN(Stores)g(data)g(in)g(the)g(v)n(alue)g(\002eld)g(of)g(an)g (open)g(re)o(gistry)f(k)o(e)o(y)-5 b(.)208 695 y FK(k)o(e)n(y)20 b FN(is)h(an)f(already)f(open)g(k)o(e)o(y)-5 b(,)19 b(or)h(one)g(of)f (the)i(prede\002ned)d FJ(HKEY_)2176 710 y(*)2245 695 y FN(constants.)208 828 y FK(value)p 394 828 V 28 w(name)i FN(is)h(a)g(string)e(that)i(names)f(the)g(subk)o(e)o(y)f(with)h(which)g (the)g(v)n(alue)f(is)j(associated.)208 960 y FK(type)c FN(is)i(an)e(inte)o(ger)g(that)h(speci\002es)g(the)f(type)h(of)f(the)h (data.)24 b(This)19 b(should)f(be)g(one)g(of)h(the)f(follo)n(wing)f (constants)i(de\002ned)e(in)i(this)208 1060 y(module:)531 1172 y FL(Constant)p 1725 1202 4 100 v 921 w(Meaning)p 481 1206 3145 4 v 531 1275 a FJ(REG_BINARY)p 1725 1305 4 100 v 745 w FN(Binary)h(data)g(in)h(an)o(y)e(form.)531 1375 y FJ(REG_DWORD)p 1725 1405 V 795 w FN(A)i(32-bit)e(number)-5 b(.)531 1475 y FJ(REG_DWORD_LITTLE_ENDIAN)p 1725 1504 V 95 w FN(A)21 b(32-bit)e(number)g(in)h(little-endian)f(format.)531 1574 y FJ(REG_DWORD_BIG_ENDIAN)p 1725 1604 V 245 w FN(A)i(32-bit)e (number)g(in)h(big-endian)e(format.)531 1674 y FJ(REG_EXPAND_SZ)p 1725 1803 4 200 v 595 w FN(Null-terminated)29 b(string)i(containing)e (references)g(to)i(en)m(vi-)1776 1773 y(ronment)19 b(v)n(ariables)g (\(`)p FJ(\045PATH\045)p FN('\).)531 1873 y FJ(REG_LINK)p 1725 1903 4 100 v 845 w FN(A)i(Unicode)e(symbolic)g(link.)531 1973 y FJ(REG_MULTI_SZ)p 1725 2202 4 299 v 645 w FN(A)29 b(sequence)e(of)h(null-terminated)e(strings,)k(terminated)c(by)1776 2072 y(tw)o(o)g(null)f(characters.)39 b(\(Python)24 b(handles)h(this)h (termination)1776 2172 y(automatically)-5 b(.\))531 2272 y FJ(REG_NONE)p 1725 2301 4 100 v 845 w FN(No)21 b(de\002ned)e(v)n (alue)g(type.)531 2371 y FJ(REG_RESOURCE_LIST)p 1725 2401 V 395 w FN(A)i(de)n(vice-dri)n(v)o(er)c(resource)i(list.)531 2471 y FJ(REG_SZ)p 1725 2501 V 945 w FN(A)i(null-terminated)d(string.) 208 2599 y FK(r)m(eserved)k FN(can)e(be)g(an)o(ything)f(-)h(zero)g(is)h (al)o(w)o(ays)f(passed)g(to)h(the)f(API.)208 2732 y FK(value)f FN(is)i(a)g(string)f(that)g(speci\002es)h(the)f(ne)n(w)g(v)n(alue.)208 2865 y(This)i(method)f(can)h(also)g(set)h(additional)e(v)n(alue)g(and)h (type)g(information)e(for)h(the)h(speci\002ed)g(k)o(e)o(y)-5 b(.)30 b(The)22 b(k)o(e)o(y)f(identi\002ed)h(by)g(the)208 2964 y(k)o(e)o(y)d(parameter)g(must)h(ha)n(v)o(e)g(been)f(opened)g (with)h FJ(KEY_SET_VALUE)e FN(access.)208 3097 y(T)-7 b(o)20 b(open)f(the)h(k)o(e)o(y)-5 b(,)19 b(use)i(the)f FJ(CreateKeyEx\(\))e FN(or)i FJ(OpenKey\(\))f FN(methods.)208 3230 y(V)-9 b(alue)24 b(lengths)h(are)g(limited)g(by)f(a)n(v)n(ailable) h(memory)-5 b(.)37 b(Long)24 b(v)n(alues)h(\(more)f(than)g(2048)g (bytes\))g(should)g(be)h(stored)g(as)h(\002les)208 3330 y(with)20 b(the)g(\002lenames)g(stored)g(in)g(the)g(con\002guration)e (re)o(gistry)-5 b(.)23 b(This)e(helps)f(the)g(re)o(gistry)f(perform)f (ef)n(\002ciently)-5 b(.)0 3614 y Fv(36.3.1)101 b(Registr)s(y)28 b(Handle)h(Objects)0 3817 y FN(This)h(object)g(wraps)g(a)g(W)m(indo)n (ws)g(HKEY)g(object,)i(automatically)d(closing)g(it)i(when)f(the)g (object)g(is)h(destro)o(yed.)53 b(T)-7 b(o)30 b(guarantee)0 3917 y(cleanup,)19 b(you)g(can)h(call)h(either)e(the)i FJ(Close\(\))e FN(method)g(on)h(the)g(object,)f(or)h(the)g FJ(CloseKey\(\))f FN(function.)0 4064 y(All)i(re)o(gistry)e(functions)g (in)h(this)h(module)e(return)g(one)g(of)h(these)h(objects.)0 4211 y(All)j(re)o(gistry)e(functions)g(in)h(this)g(module)f(which)h (accept)g(a)g(handle)f(object)h(also)g(accept)g(an)g(inte)o(ger)m(,)f (ho)n(we)n(v)o(er)m(,)f(use)j(of)f(the)g(handle)0 4310 y(object)d(is)h(encouraged.)0 4457 y(Handle)f(objects)f(pro)o(vide)g (semantics)h(for)f FJ(__nonzero__\(\))g FN(-)h(thus)416 4695 y FA(if)44 b(handle:)595 4787 y(print)g("Yes")0 5026 y FN(will)21 b(print)f FJ(Yes)g FN(if)g(the)g(handle)f(is)j (currently)c(v)n(alid)i(\(has)g(not)g(been)f(closed)h(or)g(detached\).) 0 5173 y(The)26 b(object)f(also)i(support)d(comparison)g(semantics,)k (so)e(handle)f(objects)h(will)h(compare)d(true)i(if)g(the)o(y)g(both)f (reference)f(the)i(same)0 5273 y(underlying)17 b(W)m(indo)n(ws)j (handle)f(v)n(alue.)p 0 5549 3901 4 v 0 5649 a FI(944)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g(Ser)r(vices)p eop end %%Page: 945 957 TeXDict begin 945 956 bop 0 83 a FN(Handle)22 b(objects)h(can)g(be)g (con)m(v)o(erted)d(to)j(an)g(inte)o(ger)f(\(e.g.,)h(using)f(the)h(b)n (uiltin)g FJ(int\(\))g FN(function\),)e(in)i(which)g(case)g(the)g (underlying)0 183 y(W)m(indo)n(ws)j(handle)f(v)n(alue)h(is)h(returned.) 42 b(Y)-9 b(ou)25 b(can)i(also)f(use)h(the)f FJ(Detach\(\))g FN(method)f(to)h(return)f(the)i(inte)o(ger)e(handle,)h(and)g(also)0 282 y(disconnect)19 b(the)h(W)m(indo)n(ws)g(handle)f(from)g(the)h (handle)f(object.)0 429 y FD(Close)p FJ(\(\))208 529 y FN(Closes)i(the)f(underlying)d(W)m(indo)n(ws)j(handle.)208 662 y(If)g(the)g(handle)f(is)i(already)e(closed,)h(no)g(error)f(is)i (raised.)0 808 y FD(Detach)p FJ(\(\))208 908 y FN(Detaches)f(the)g(W)m (indo)n(ws)f(handle)g(from)h(the)g(handle)f(object.)208 1041 y(The)j(result)g(is)i(an)e(inte)o(ger)f(\(or)h(long)g(on)g(64)g (bit)h(W)m(indo)n(ws\))e(that)i(holds)f(the)h(v)n(alue)e(of)i(the)f (handle)f(before)h(it)h(is)g(detached.)31 b(If)208 1141 y(the)20 b(handle)f(is)i(already)e(detached)g(or)h(closed,)f(this)i (will)g(return)e(zero.)208 1273 y(After)f(calling)h(this)h(function,)d (the)i(handle)f(is)i(ef)n(fecti)n(v)o(ely)d(in)m(v)n(alidated,)g(b)n (ut)j(the)f(handle)f(is)i(not)e(closed.)25 b(Y)-9 b(ou)18 b(w)o(ould)h(call)g(this)208 1373 y(function)f(when)i(you)f(need)g(the) i(underlying)c(W)m(in32)j(handle)f(to)h(e)o(xist)g(be)o(yond)e(the)i (lifetime)g(of)g(the)h(handle)e(object.)0 1700 y FE(36.4)121 b Fx(winsound)31 b FE(\227)i(Sound-pla)l(ying)j(interf)l(ace)f(f)l(or)f (Windo)n(ws)0 1933 y FN(Ne)n(w)20 b(in)h(v)o(ersion)e(1.5.2.)0 2080 y(The)25 b FJ(winsound)g FN(module)g(pro)o(vides)f(access)i(to)g (the)g(basic)g(sound-playing)c(machinery)i(pro)o(vided)f(by)j(W)m(indo) n(ws)f(platforms.)40 b(It)0 2180 y(includes)19 b(functions)g(and)h(se)n (v)o(eral)f(constants.)0 2327 y FD(Beep)p FJ(\()p FK(fr)m(equency)-5 b(,)18 b(dur)o(ation)p FJ(\))208 2426 y FN(Beep)j(the)h(PC')-5 b(s)23 b(speak)o(er)-5 b(.)30 b(The)21 b FK(fr)m(equency)g FN(parameter)f(speci\002es)i(frequenc)o(y)-5 b(,)19 b(in)j(hertz,)f(of) h(the)f(sound,)g(and)g(must)h(be)g(in)g(the)208 2526 y(range)h(37)h(through)e(32,767.)34 b(The)24 b FK(dur)o(ation)f FN(parameter)g(speci\002es)h(the)h(number)d(of)i(milliseconds)f(the)i (sound)e(should)g(last.)208 2626 y(If)d(the)h(system)g(is)h(not)e(able) h(to)g(beep)f(the)h(speak)o(er)m(,)f FJ(RuntimeError)f FN(is)i(raised.)27 b FL(Note:)f FN(Under)19 b(W)m(indo)n(ws)i(95)f(and) g(98,)h(the)208 2725 y(W)m(indo)n(ws)g FJ(Beep\(\))h FN(function)f(e)o(xists)h(b)n(ut)h(is)g(useless)g(\(it)g(ignores)e(its) j(ar)o(guments\).)k(In)23 b(that)f(case)h(Python)e(simulates)h(it)i (via)208 2825 y(direct)f(port)g(manipulation)e(\(added)h(in)i(v)o (ersion)f(2.1\).)34 b(It')-5 b(s)25 b(unkno)n(wn)c(whether)h(that)i (will)h(w)o(ork)e(on)g(all)h(systems.)72 b(Ne)n(w)24 b(in)208 2924 y(v)o(ersion)18 b(1.6.)0 3071 y FD(PlaySound)p FJ(\()p FK(sound,)f(\003a)o(gs)p FJ(\))208 3171 y FN(Call)22 b(the)g(underlying)d FJ(PlaySound\(\))h FN(function)g(from)h(the)g (Platform)g(API.)h(The)f FK(sound)i FN(parameter)d(may)i(be)f(a)h (\002lename,)208 3271 y(audio)f(data)g(as)i(a)f(string,)g(or)g FJ(None)p FN(.)30 b(Its)22 b(interpretation)e(depends)h(on)g(the)h(v)n (alue)g(of)f FK(\003a)o(gs)p FN(,)h(which)f(can)h(be)g(a)g(bit-wise)g (ORed)208 3370 y(combination)17 b(of)j(the)h(constants)e(described)g (belo)n(w)-5 b(.)24 b(If)c(the)g(system)h(indicates)f(an)g(error)m(,)e FJ(RuntimeError)h FN(is)i(raised.)0 3517 y FD(MessageBeep)p FJ(\()p FC([)p FK(type=)p Fn(MB_OK)14 b FC(])p FJ(\))208 3617 y FN(Call)23 b(the)g(underlying)d FJ(MessageBeep\(\))h FN(function)g(from)g(the)i(Platform)f(API.)h(This)g(plays)f(a)h(sound)f (as)h(speci\002ed)g(in)g(the)208 3716 y(re)o(gistry)-5 b(.)22 b(The)17 b FK(type)g FN(ar)o(gument)e(speci\002es)i(which)g (sound)f(to)h(play;)h(possible)f(v)n(alues)f(are)h FJ(-1)p FN(,)h FJ(MB_ICONASTERISK)p FN(,)d FJ(MB_-)208 3816 y(ICONEXCLAMATION)p FN(,)e FJ(MB_ICONHAND)p FN(,)i FJ(MB_ICONQUESTION)p FN(,)e(and)j FJ(MB_OK)p FN(,)f(all)i(described)e(belo)n(w)-5 b(.)22 b(The)16 b(v)n(alue)f FJ(-1)208 3916 y FN(produces)j(a)j(\223simple)f (beep\224;)f(this)i(is)g(the)f(\002nal)h(f)o(allback)e(if)h(a)h(sound)e (cannot)g(be)h(played)f(otherwise.)50 b(Ne)n(w)21 b(in)f(v)o(ersion)f (2.3.)0 4062 y FD(SND_FILENAME)208 4162 y FN(The)g FK(sound)j FN(parameter)c(is)k(the)e(name)f(of)h(a)h(W)-10 b(A)f(V)21 b(\002le.)k(Do)c(not)e(use)i(with)f FJ(SND_ALIAS)p FN(.)0 4309 y FD(SND_ALIAS)208 4409 y FN(The)g FK(sound)i FN(parameter)e(is)i (a)g(sound)e(association)g(name)h(from)f(the)h(re)o(gistry)-5 b(.)26 b(If)21 b(the)g(re)o(gistry)f(contains)g(no)h(such)g(name,)f (play)208 4508 y(the)27 b(system)h(def)o(ault)f(sound)g(unless)h FJ(SND_NODEFAULT)e FN(is)i(also)h(speci\002ed.)47 b(If)27 b(no)h(def)o(ault)f(sound)f(is)j(re)o(gistered,)f(raise)208 4608 y FJ(RuntimeError)p FN(.)23 b(Do)d(not)g(use)g(with)h FJ(SND_FILENAME)p FN(.)208 4741 y(All)f(W)m(in32)g(systems)h(support)d (at)j(least)g(the)f(follo)n(wing;)f(most)h(systems)h(support)e(man)o(y) g(more:)776 4870 y FD(PlaySound\(\))g Fo(name)p 1771 4900 4 100 v 287 w FL(Corr)o(esponding)h(Contr)o(ol)f(P)o(anel)h(Sound) h(name)p 726 4903 2655 4 v 776 4973 a FJ('SystemAsterisk')p 1771 5003 4 100 v 246 w FN(Asterisk)776 5072 y FJ('SystemExclamation')p 1771 5102 V 96 w FN(Exclamation)776 5172 y FJ('SystemExit')p 1771 5202 V 446 w FN(Exit)f(W)m(indo)n(ws)776 5272 y FJ('SystemHand')p 1771 5302 V 446 w FN(Critical)h(Stop)776 5371 y FJ('SystemQuestion')p 1771 5401 V 246 w FN(Question)p 0 5549 3901 4 v 0 5649 a FI(36.4.)52 b FJ(winsound)22 b FI(\227)h(Sound-pla)n(ying)h(interf)n(ace)f(f)n(or)g(Windo)o(ws)1655 b(945)p eop end %%Page: 946 958 TeXDict begin 946 957 bop 208 83 a FN(F)o(or)19 b(e)o(xample:)444 216 y FA(import)44 b(winsound)444 307 y(#)g(Play)h(Windows)e(exit)h (sound.)444 399 y(winsound.PlaySound\("SystemExit",)39 b(winsound.SND_ALIAS\))444 581 y(#)44 b(Probably)g(play)g(Windows)g (default)f(sound,)h(if)h(any)f(is)h(registered)e(\(because)444 672 y(#)h(")578 685 y(*)623 672 y(")h(probably)e(isn't)h(the)h (registered)e(name)h(of)g(any)h(sound\).)444 764 y (winsound.PlaySound\(")1344 777 y(*)1389 764 y(",)c (winsound.SND_ALIAS\))0 959 y FD(SND_LOOP)208 1058 y FN(Play)26 b(the)f(sound)g(repeatedly)-5 b(.)40 b(The)25 b FJ(SND_ASYNC)g FN(\003ag)h(must)g(also)g(be)g(used)f(to)h(a)n(v)n (oid)g(blocking.)40 b(Cannot)25 b(be)h(used)f(with)208 1158 y FJ(SND_MEMORY)p FN(.)0 1305 y FD(SND_MEMORY)208 1404 y FN(The)19 b FK(sound)j FN(parameter)c(to)j FJ(PlaySound\(\))d FN(is)k(a)e(memory)f(image)g(of)h(a)h(W)-10 b(A)f(V)21 b(\002le,)f(as)h(a)g(string.)208 1537 y FL(Note:)33 b FN(This)25 b(module)f(does)g(not)h(support)e(playing)g(from)h(a)h (memory)e(image)i(asynchronously)-5 b(,)22 b(so)j(a)g(combination)e(of) h(this)208 1637 y(\003ag)c(and)f FJ(SND_ASYNC)h FN(will)g(raise)h FJ(RuntimeError)p FN(.)0 1784 y FD(SND_PURGE)208 1883 y FN(Stop)f(playing)e(all)j(instances)f(of)g(the)g(speci\002ed)g (sound.)0 2030 y FD(SND_ASYNC)208 2130 y FN(Return)f(immediately)-5 b(,)19 b(allo)n(wing)g(sounds)g(to)i(play)e(asynchronously)-5 b(.)0 2277 y FD(SND_NODEFAULT)208 2376 y FN(If)20 b(the)g(speci\002ed)g (sound)f(cannot)g(be)h(found,)e(do)i(not)g(play)g(the)g(system)g(def)o (ault)g(sound.)0 2523 y FD(SND_NOSTOP)208 2623 y FN(Do)g(not)g (interrupt)e(sounds)i(currently)e(playing.)0 2770 y FD(SND_NOWAIT)208 2869 y FN(Return)h(immediately)g(if)i(the)f(sound)f(dri)n(v)o(er)g(is)i (b)n(usy)-5 b(.)0 3016 y FD(MB_ICONASTERISK)208 3116 y FN(Play)20 b(the)g FJ(SystemDefault)e FN(sound.)0 3263 y FD(MB_ICONEXCLAMATION)208 3362 y FN(Play)i(the)g FJ (SystemExclamation)e FN(sound.)0 3509 y FD(MB_ICONHAND)208 3609 y FN(Play)i(the)g FJ(SystemHand)f FN(sound.)0 3756 y FD(MB_ICONQUESTION)208 3855 y FN(Play)h(the)g FJ(SystemQuestion)e FN(sound.)0 4002 y FD(MB_OK)208 4102 y FN(Play)i(the)g FJ(SystemDefault)e FN(sound.)p 0 5549 3901 4 v 0 5649 a FI(946)2136 b(Chapter)23 b(36.)52 b(MS)24 b(Windo)o(ws)f(Speci\002c)g (Ser)r(vices)p eop end %%Page: 947 959 TeXDict begin 947 958 bop 0 83 3901 9 v 3480 230 a FI(APPENDIX)3814 427 y FG(A)p 0 515 V 1604 978 a FT(Undocumented)57 b(Modules)0 1457 y FN(Here')-5 b(s)32 b(a)g(quick)e(listing)i(of)f(modules)g(that)h (are)f(currently)f(undocumented,)g(b)n(ut)i(that)g(should)e(be)i (documented.)56 b(Feel)32 b(free)f(to)0 1556 y(contrib)n(ute)19 b(documentation)e(for)j(them!)k(\(Send)19 b(via)i(email)f(to)g FO(docs@p)n(ython.org)p FN(.\))0 1703 y(The)j(idea)h(and)f(original)g (contents)g(for)g(this)i(chapter)e(were)g(tak)o(en)h(from)e(a)j (posting)e(by)g(Fredrik)g(Lundh;)h(the)g(speci\002c)g(contents)f(of)0 1803 y(this)e(chapter)e(ha)n(v)o(e)g(been)h(substantially)f(re)n (vised.)0 2130 y FE(A.1)120 b(F)-5 b(r)o(ame)n(w)o(or)r(ks)0 2362 y FN(Frame)n(w)o(orks)19 b(tend)h(to)g(be)g(harder)f(to)h (document,)e(b)n(ut)i(are)g(well)h(w)o(orth)f(the)g(ef)n(fort)f(spent.) 42 2589 y(None)g(at)i(this)g(time.)0 2916 y FE(A.2)120 b(Miscellaneous)34 b(useful)g(utilities)0 3149 y FN(Some)20 b(of)g(these)g(are)g(v)o(ery)f(old)h(and/or)f(not)h(v)o(ery)f(rob)n (ust;)h(mark)o(ed)f(with)h(\223hmm.)-6 b(\224)0 3375 y FD(bdb)41 b FN(\227)21 b(A)f(generic)g(Python)f(deb)n(ugger)f(base)i (class)h(\(used)f(by)f(pdb\).)0 3540 y FD(ihooks)40 b FN(\227)21 b(Import)e(hook)g(support)g(\(for)g FJ(rexec)p FN(;)h(may)f(become)g(obsolete\).)0 3867 y FE(A.3)120 b(Platf)l(or)s(m)34 b(speci\002c)f(modules)0 4100 y FN(These)23 b(modules)f(are)h(used)g(to)g(implement)f(the)h FJ(os.path)f FN(module,)g(and)g(are)h(not)g(documented)e(be)o(yond)f(this)k (mention.)32 b(There')-5 b(s)0 4199 y(little)21 b(need)f(to)g(document) e(these.)0 4426 y FD(ntpath)40 b FN(\227)21 b(Implementation)d(of)i FJ(os.path)f FN(on)h(W)m(in32,)f(W)m(in64,)g(W)m(inCE,)h(and)g(OS/2)h (platforms.)0 4591 y FD(posixpath)40 b FN(\227)21 b(Implementation)c (of)j FJ(os.path)f FN(on)h(POSIX.)0 4755 y FD(bsddb185)40 b FN(\227)31 b(Backw)o(ards)e(compatibility)g(module)f(for)i(systems)g (which)g(still)h(use)f(the)g(Berk)o(ele)o(y)f(DB)i(1.85)e(module.)53 b(It)31 b(is)208 4855 y(normally)18 b(only)h(a)n(v)n(ailable)h(on)g (certain)g(BSD)j(U)t FH(N)t(I)t(X)r FN(-based)d(systems.)25 b(It)c(should)e(ne)n(v)o(er)g(be)h(used)g(directly)-5 b(.)0 5182 y FE(A.4)120 b(Multimedia)0 5400 y FD(audiodev)40 b FN(\227)21 b(Platform-independent)16 b(API)k(for)g(playing)e(audio)i (data.)p 0 5549 3901 4 v 3762 5649 a FI(947)p eop end %%Page: 948 960 TeXDict begin 948 959 bop 0 83 a FD(linuxaudiodev)39 b FN(\227)26 b(Play)g(audio)f(data)h(on)f(the)h(Linux)e(audio)h(de)n (vice.)40 b(Replaced)26 b(in)f(Python)g(2.3)g(by)g(the)h FJ(ossaudiodev)208 183 y FN(module.)0 349 y FD(sunaudio)40 b FN(\227)21 b(Interpret)d(Sun)i(audio)g(headers)f(\(may)g(become)g (obsolete)h(or)g(a)g(tool/demo\).)0 515 y FD(toaiff)40 b FN(\227)30 b(Con)m(v)o(ert)d(\224arbitrary\224)h(sound)f(\002les)j (to)f(AIFF)h(\002les;)k(should)28 b(probably)f(become)h(a)h(tool)g(or)g (demo.)50 b(Requires)29 b(the)208 614 y(e)o(xternal)18 b(program)h FL(sox)p FN(.)0 942 y FE(A.5)120 b(Obsolete)0 1175 y FN(These)20 b(modules)f(are)h(not)g(normally)f(a)n(v)n(ailable)g (for)h(import;)f(additional)g(w)o(ork)h(must)g(be)g(done)f(to)h(mak)o (e)g(them)g(a)n(v)n(ailable.)0 1321 y(These)g(e)o(xtension)f(modules)h (written)g(in)h(C)g(are)f(not)g(b)n(uilt)h(by)f(def)o(ault.)25 b(Under)d(U)t FH(N)t(I)t(X)r FN(,)f(these)g(must)f(be)h(enabled)e(by)h (uncommenting)0 1421 y(the)27 b(appropriate)e(lines)i(in)g(`)p FO(Modules/Setup)p FN(')c(in)k(the)g(b)n(uild)g(tree)g(and)f(either)g (reb)n(uilding)g(Python)f(if)j(the)f(modules)e(are)i(statically)0 1521 y(link)o(ed,)19 b(or)h(b)n(uilding)f(and)h(installing)g(the)g (shared)f(object)h(if)g(using)g(dynamically-loaded)c(e)o(xtensions.)0 1751 y FD(timing)40 b FN(\227)21 b(Measure)f(time)g(interv)n(als)g(to)g (high)f(resolution)g(\(use)h FJ(time.clock\(\))f FN(instead\).)0 2078 y FE(A.6)120 b(SGI-speci\002c)33 b(Extension)h(modules)0 2311 y FN(The)20 b(follo)n(wing)e(are)j(SGI)f(speci\002c,)g(and)g(may)g (be)g(out)g(of)f(touch)h(with)g(the)g(current)f(v)o(ersion)g(of)h (reality)-5 b(.)0 2541 y FD(cl)41 b FN(\227)21 b(Interf)o(ace)e(to)h (the)g(SGI)h(compression)d(library)-5 b(.)0 2707 y FD(sv)41 b FN(\227)21 b(Interf)o(ace)e(to)h(the)g(\223simple)g(video\224)f (board)g(on)h(SGI)h(Indigo)d(\(obsolete)h(hardw)o(are\).)p 0 5549 3901 4 v 0 5649 a FI(948)2345 b(Appendix)25 b(A.)46 b(Undocumented)24 b(Modules)p eop end %%Page: 949 961 TeXDict begin 949 960 bop 0 83 3901 9 v 3480 230 a FI(APPENDIX)3814 427 y FG(B)p 0 515 V 2468 978 a FT(Repor)8 b(ting)57 b(Bugs)0 1468 y FN(Python)23 b(is)i(a)g(mature)e(programming)e (language)i(which)g(has)i(established)f(a)g(reputation)f(for)g (stability)-5 b(.)37 b(In)24 b(order)f(to)i(maintain)e(this)0 1568 y(reputation,)18 b(the)i(de)n(v)o(elopers)e(w)o(ould)i(lik)o(e)g (to)h(kno)n(w)e(of)h(an)o(y)f(de\002ciencies)h(you)f(\002nd)h(in)g (Python)g(or)f(its)j(documentation.)0 1714 y(Before)e(submitting)g(a)h (report,)f(you)g(will)i(be)f(required)e(to)i(log)f(into)h(SourceF)o(or) o(ge;)e(this)i(will)h(mak)o(e)e(it)i(possible)e(for)h(the)g(de)n(v)o (elopers)0 1814 y(to)f(contact)g(you)f(for)h(additional)f(information)e (if)k(needed.)i(It)e(is)g(not)f(possible)g(to)g(submit)g(a)h(b)n(ug)e (report)g(anon)o(ymously)-5 b(.)0 1961 y(All)24 b(b)n(ug)f(reports)f (should)h(be)g(submitted)f(via)i(the)f(Python)f(Bug)i(T)m(rack)o(er)e (at)i(\()p FO(http://b)o(ugs)o(.p)n(ython.o)o(rg)-6 b FN(\).)34 b(The)23 b(b)n(ug)g(track)o(er)g(of)n(fers)f(a)0 2061 y(W)-7 b(eb)21 b(form)e(which)h(allo)n(ws)g(pertinent)f (information)f(to)i(be)g(entered)f(and)h(submitted)f(to)i(the)f(de)n(v) o(elopers.)0 2207 y(The)f(\002rst)i(step)f(in)f(\002ling)h(a)g(report)e (is)j(to)f(determine)e(whether)g(the)i(problem)e(has)i(already)e(been)h (reported.)k(The)c(adv)n(antage)f(in)i(doing)0 2307 y(so,)f(aside)g (from)f(sa)n(ving)h(the)g(de)n(v)o(elopers)e(time,)i(is)h(that)f(you)f (learn)g(what)h(has)g(been)g(done)f(to)h(\002x)g(it;)h(it)g(may)e(be)h (that)g(the)g(problem)e(has)0 2407 y(already)h(been)h(\002x)o(ed)g(for) f(the)i(ne)o(xt)e(release,)i(or)f(additional)f(information)f(is)j (needed)e(\(in)h(which)g(case)h(you)e(are)h(welcome)g(to)h(pro)o(vide)0 2506 y(it)h(if)f(you)g(can!\).)k(T)-7 b(o)20 b(do)g(this,)g(search)g (the)g(b)n(ug)g(database)g(using)f(the)h(search)g(box)f(on)h(the)g(top) g(side)h(of)f(the)g(page.)0 2653 y(If)e(the)g(problem)f(you')l(re)f (reporting)g(is)j(not)f(already)f(in)h(the)g(b)n(ug)g(track)o(er)m(,)f (go)h(back)f(to)i(the)f(Python)f(Bug)h(T)m(rack)o(er)-5 b(.)24 b(Select)18 b(the)g(\223Create)0 2753 y(ne)n(w\224)i(link)g(at)g (the)h(left)f(of)g(the)g(page)g(to)g(open)f(the)h(b)n(ug)g(reporting)e (form.)0 2900 y(The)g(submission)f(form)g(has)h(a)g(number)e(of)i (\002elds.)25 b(The)17 b(only)g(\002elds)i(that)f(are)g(required)e(are) i(the)g(\223T)m(itle\224)g(and)f(\223T)-7 b(ype\224)17 b(\002elds.)25 b(F)o(or)18 b(the)0 2999 y(title,)24 b(enter)e(a)i FK(very)f FN(short)f(description)g(of)g(the)h(problem;)g(less)h(than)e (ten)h(w)o(ords)g(is)g(good.)32 b(In)22 b(the)h(\223Change)f(Note\224)h (\002eld,)g(describe)0 3099 y(the)f(problem)e(in)h(detail,)h(including) e(what)i(you)f(e)o(xpected)f(to)h(happen)f(and)i(what)f(did)h(happen.) 27 b(Be)c(sure)e(to)h(include)f(the)g(v)o(ersion)g(of)0 3199 y(Python)f(you)h(used,)g(whether)f(an)o(y)g(e)o(xtension)g (modules)h(were)g(in)m(v)n(olv)o(ed,)e(and)i(what)g(hardw)o(are)f(and)h (softw)o(are)f(platform)g(you)h(were)0 3298 y(using)f(\(including)e(v)o (ersion)h(information)e(as)k(appropriate\).)0 3445 y(The)e(only)g (other)g(\002eld)h(that)f(you)g(may)g(w)o(ant)h(to)f(set)i(is)f(the)g (\223Components\224)e(\002eld,)h(which)g(allo)n(ws)h(you)f(to)g(place)h (the)f(b)n(ug)g(report)g(into)0 3545 y(broad)g(cate)o(gories)g(\(such)g (as)i(\223Documentation\224)d(or)i(\223Library\224\).)0 3692 y(Each)e(b)n(ug)g(report)f(will)j(be)e(assigned)g(to)h(a)g(de)n(v) o(eloper)d(who)i(will)h(determine)e(what)i(needs)f(to)h(be)f(done)g(to) g(correct)g(the)h(problem.)j(Y)-9 b(ou)0 3791 y(will)21 b(recei)n(v)o(e)e(an)h(update)f(each)h(time)g(action)g(is)h(tak)o(en)f (on)g(the)g(b)n(ug.)0 3938 y FL(See)h(Also:)0 4085 y FK(How)g(to)f(Report)g(Bugs)f(Ef)o(fectively)0 4185 y Fy(\()p FO(http://www-mice)o(.cs)o(.ucl.ac.uk/m)o(ultimedia)o(/softw)n (are)o(/do)o(cumen)o(tati)o(on)o(/Re)o(por)r(tin)o(gBu)o(gs)o(.h)o(tml) -6 b Fy(\))208 4284 y FN(Article)32 b(which)f(goes)h(into)f(some)h (detail)g(about)f(ho)n(w)g(to)i(create)e(a)i(useful)e(b)n(ug)g(report.) 59 b(This)32 b(describes)g(what)g(kind)f(of)208 4384 y(information)17 b(is)k(useful)f(and)g(why)f(it)i(is)g(useful.)0 4531 y FK(Bug)f(Writing)g(Guidelines)0 4630 y Fy(\()p FO(http://www)l(.mozilla.org/q)o(ual)o(it)o(y/b)o(u)o(g-writin)o(g-g)o (ui)o(de)o(li)o(nes)o(.h)o(tml)-6 b Fy(\))208 4730 y FN(Information)27 b(about)i(writing)h(a)g(good)f(b)n(ug)h(report.)54 b(Some)30 b(of)f(this)i(is)g(speci\002c)g(to)f(the)g(Mozilla)g (project,)i(b)n(ut)e(describes)208 4830 y(general)19 b(good)f(practices.)p 0 5549 3901 4 v 3762 5649 a FI(949)p eop end %%Page: 950 962 TeXDict begin 950 961 bop 0 5549 3901 4 v 0 5649 a FI(950)p eop end %%Page: 951 963 TeXDict begin 951 962 bop 0 83 3901 9 v 3480 230 a FI(APPENDIX)3814 427 y FG(C)p 0 515 V 2080 978 a FT(Histor)6 b(y)58 b(and)f(License)0 1506 y FE(C)l(.1)121 b(Histor)t(y)33 b(of)h(the)g(softw)n(are)0 1739 y FN(Python)39 b(w)o(as)i(created)f(in)g(the)h(early)e(1990s)h(by) g(Guido)f(v)n(an)h(Rossum)g(at)h(Stichting)f(Mathematisch)f(Centrum)g (\(CWI,)i(see)0 1839 y FO(http://www)l(.cwi.nl/)l FN(\))30 b(in)g(the)g(Netherlands)e(as)j(a)f(successor)g(of)f(a)i(language)d (called)i(ABC.)g(Guido)f(remains)h(Python')-5 b(s)29 b(principal)0 1939 y(author)m(,)18 b(although)h(it)i(includes)e(man)o (y)g(contrib)n(utions)f(from)h(others.)0 2085 y(In)36 b(1995,)j(Guido)c(continued)f(his)j(w)o(ork)e(on)h(Python)f(at)i(the)f (Corporation)e(for)i(National)g(Research)g(Initiati)n(v)o(es)f(\(CNRI,) i(see)0 2185 y FO(http://www)l(.cnr)q(i.reston.v)n(a.us/)-6 b FN(\))21 b(in)f(Reston,)g(V)-5 b(ir)o(ginia)19 b(where)h(he)g (released)g(se)n(v)o(eral)f(v)o(ersions)g(of)h(the)g(softw)o(are.)0 2332 y(In)h(May)h(2000,)e(Guido)h(and)g(the)h(Python)e(core)h(de)n(v)o (elopment)e(team)j(mo)o(v)o(ed)d(to)j(BeOpen.com)e(to)i(form)e(the)i (BeOpen)f(PythonLabs)0 2432 y(team.)49 b(In)27 b(October)g(of)h(the)g (same)h(year)m(,)g(the)f(PythonLabs)e(team)i(mo)o(v)o(ed)e(to)i (Digital)h(Creations)f(\(no)n(w)f(Zope)g(Corporation;)j(see)0 2531 y FO(http://www)l(.z)o(ope)o(.com/)l FN(\).)g(In)21 b(2001,)g(the)h(Python)f(Softw)o(are)g(F)o(oundation)f(\(PSF)-7 b(,)22 b(see)h FO(http://www)l(.p)n(ython.org/)o(psf/)-6 b FN(\))22 b(w)o(as)h(formed,)d(a)0 2631 y(non-pro\002t)h(or)o (ganization)f(created)i(speci\002cally)h(to)g(o)n(wn)g(Python-related)d (Intellectual)j(Property)-5 b(.)32 b(Zope)22 b(Corporation)f(is)j(a)g (spon-)0 2730 y(soring)19 b(member)g(of)h(the)g(PSF)-7 b(.)0 2877 y(All)26 b(Python)d(releases)j(are)e(Open)h(Source)f(\(see)h FO(http://www)l(.opensource)o(.o)o(rg/)19 b FN(for)24 b(the)h(Open)g(Source)f(De\002nition\).)38 b(Historically)-5 b(,)0 2977 y(most,)20 b(b)n(ut)g(not)g(all,)h(Python)e(releases)h(ha)n (v)o(e)g(also)g(been)g(GPL-compatible;)e(the)i(table)g(belo)n(w)g (summarizes)f(the)h(v)n(arious)g(releases.)p 0 5549 3901 4 v 3762 5649 a FI(951)p eop end %%Page: 952 964 TeXDict begin 952 963 bop 670 70 a FL(Release)p 1074 100 4 100 v 188 w(Deri)o(v)o(ed)20 b(fr)o(om)p 1648 100 V 195 w(Y)-9 b(ear)p 2107 100 V 291 w(Owner)p 2643 100 V 195 w(GPL)21 b(compatible?)p 531 103 2838 4 v 581 173 a FN(0.9.0)e(thru)g(1.2)p 1074 203 4 100 v 285 w(n/a)p 1648 203 V 285 w(1991-1995)p 2107 203 V 233 w(CWI)p 2643 203 V 494 w(yes)581 272 y(1.3)g(thru)h(1.5.2)p 1074 302 V 283 w(1.2)p 1648 302 V 283 w(1995-1999)p 2107 302 V 214 w(CNRI)p 2643 302 V 476 w(yes)752 372 y(1.6)p 1074 402 V 423 w(1.5.2)p 1648 402 V 348 w(2000)p 2107 402 V 313 w(CNRI)p 2643 402 V 490 w(no)752 472 y(2.0)p 1074 501 V 454 w(1.6)p 1648 501 V 380 w(2000)p 2107 501 V 195 w(BeOpen.com)p 2643 501 V 368 w(no)720 571 y(1.6.1)p 1074 601 V 423 w(1.6)p 1648 601 V 380 w(2001)p 2107 601 V 313 w(CNRI)p 2643 601 V 490 w(no)752 671 y(2.1)p 1074 701 V 347 w(2.0+1.6.1)p 1648 701 V 272 w(2001)p 2107 701 V 343 w(PSF)p 2643 701 V 520 w(no)720 770 y(2.0.1)p 1074 800 V 316 w(2.0+1.6.1)p 1648 800 V 272 w(2001)p 2107 800 V 343 w(PSF)p 2643 800 V 506 w(yes)720 870 y(2.1.1)p 1074 900 V 316 w(2.1+2.0.1)p 1648 900 V 272 w(2001)p 2107 900 V 343 w(PSF)p 2643 900 V 506 w(yes)752 970 y(2.2)p 1074 1000 V 423 w(2.1.1)p 1648 1000 V 348 w(2001)p 2107 1000 V 343 w(PSF)p 2643 1000 V 506 w(yes)720 1069 y(2.1.2)p 1074 1099 V 392 w(2.1.1)p 1648 1099 V 348 w(2002)p 2107 1099 V 343 w(PSF)p 2643 1099 V 506 w(yes)720 1169 y(2.1.3)p 1074 1199 V 392 w(2.1.2)p 1648 1199 V 348 w(2002)p 2107 1199 V 343 w(PSF)p 2643 1199 V 506 w(yes)720 1269 y(2.2.1)p 1074 1298 V 423 w(2.2)p 1648 1298 V 380 w(2002)p 2107 1298 V 343 w(PSF)p 2643 1298 V 506 w(yes)720 1368 y(2.2.2)p 1074 1398 V 392 w(2.2.1)p 1648 1398 V 348 w(2002)p 2107 1398 V 343 w(PSF)p 2643 1398 V 506 w(yes)720 1468 y(2.2.3)p 1074 1498 V 392 w(2.2.2)p 1648 1498 V 251 w(2002-2003)p 2107 1498 V 244 w(PSF)p 2643 1498 V 506 w(yes)752 1567 y(2.3)p 1074 1597 V 423 w(2.2.2)p 1648 1597 V 251 w(2002-2003)p 2107 1597 V 244 w(PSF)p 2643 1597 V 506 w(yes)720 1667 y(2.3.1)p 1074 1697 V 423 w(2.3)p 1648 1697 V 283 w(2002-2003)p 2107 1697 V 244 w(PSF)p 2643 1697 V 506 w(yes)720 1767 y(2.3.2)p 1074 1797 V 392 w(2.3.1)p 1648 1797 V 348 w(2003)p 2107 1797 V 343 w(PSF)p 2643 1797 V 506 w(yes)720 1866 y(2.3.3)p 1074 1896 V 392 w(2.3.2)p 1648 1896 V 348 w(2003)p 2107 1896 V 343 w(PSF)p 2643 1896 V 506 w(yes)720 1966 y(2.3.4)p 1074 1996 V 392 w(2.3.3)p 1648 1996 V 348 w(2004)p 2107 1996 V 343 w(PSF)p 2643 1996 V 506 w(yes)720 2066 y(2.3.5)p 1074 2095 V 392 w(2.3.4)p 1648 2095 V 348 w(2005)p 2107 2095 V 343 w(PSF)p 2643 2095 V 506 w(yes)752 2165 y(2.4)p 1074 2195 V 454 w(2.3)p 1648 2195 V 380 w(2004)p 2107 2195 V 343 w(PSF)p 2643 2195 V 506 w(yes)720 2265 y(2.4.1)p 1074 2295 V 423 w(2.4)p 1648 2295 V 380 w(2005)p 2107 2295 V 343 w(PSF)p 2643 2295 V 506 w(yes)720 2364 y(2.4.2)p 1074 2394 V 392 w(2.4.1)p 1648 2394 V 348 w(2005)p 2107 2394 V 343 w(PSF)p 2643 2394 V 506 w(yes)720 2464 y(2.4.3)p 1074 2494 V 392 w(2.4.2)p 1648 2494 V 348 w(2006)p 2107 2494 V 343 w(PSF)p 2643 2494 V 506 w(yes)720 2564 y(2.4.4)p 1074 2594 V 392 w(2.4.3)p 1648 2594 V 348 w(2006)p 2107 2594 V 343 w(PSF)p 2643 2594 V 506 w(yes)752 2663 y(2.5)p 1074 2693 V 454 w(2.4)p 1648 2693 V 380 w(2006)p 2107 2693 V 343 w(PSF)p 2643 2693 V 506 w(yes)720 2763 y(2.5.1)p 1074 2793 V 423 w(2.5)p 1648 2793 V 380 w(2007)p 2107 2793 V 343 w(PSF)p 2643 2793 V 506 w(yes)720 2863 y(2.5.2)p 1074 2892 V 392 w(2.5.1)p 1648 2892 V 348 w(2008)p 2107 2892 V 343 w(PSF)p 2643 2892 V 506 w(yes)0 3088 y FL(Note:)35 b FN(GPL-compatible)24 b(doesn')o(t)g(mean)g(that)i(we')l (re)f(distrib)n(uting)f(Python)h(under)f(the)h(GPL.)h(All)g(Python)f (licenses,)i(unlik)o(e)e(the)0 3187 y(GPL,)e(let)g(you)f(distrib)n(ute) h(a)g(modi\002ed)f(v)o(ersion)f(without)h(making)g(your)f(changes)h (open)g(source.)32 b(The)22 b(GPL-compatible)f(licenses)0 3287 y(mak)o(e)f(it)h(possible)f(to)g(combine)f(Python)g(with)h(other)f (softw)o(are)h(that)g(is)i(released)d(under)g(the)h(GPL;)h(the)f (others)g(don')o(t.)0 3434 y(Thanks)f(to)i(the)f(man)o(y)f(outside)g(v) n(olunteers)g(who)h(ha)n(v)o(e)g(w)o(ork)o(ed)f(under)f(Guido')-5 b(s)20 b(direction)f(to)h(mak)o(e)g(these)g(releases)h(possible.)0 3761 y FE(C)l(.2)121 b(T)-14 b(er)s(ms)33 b(and)h(conditions)h(f)l(or)f (accessing)g(or)f(otherwise)i(using)f(Python)1024 3947 y FL(PSF)20 b(LICENSE)j(A)-5 b(GREEMENT)22 b(FOR)e(PYTHON)g(2.5.3)104 4094 y FN(1.)41 b(This)22 b(LICENSE)g(A)m(GREEMENT)f(is)j(between)d (the)h(Python)f(Softw)o(are)h(F)o(oundation)e(\(\223PSF\224\),)i(and)f (the)i(Indi)n(vidual)c(or)j(Or)n(-)208 4193 y(ganization)g (\(\223Licensee\224\))h(accessing)h(and)g(otherwise)f(using)h(Python)f (2.5.3)g(softw)o(are)h(in)h(source)e(or)h(binary)f(form)h(and)g(its)208 4293 y(associated)c(documentation.)104 4459 y(2.)41 b(Subject)28 b(to)g(the)h(terms)f(and)g(conditions)f(of)h(this)h(License)f (Agreement,)h(PSF)g(hereby)e(grants)h(Licensee)g(a)h(none)o(xclusi)n(v) o(e,)208 4559 y(ro)o(yalty-free,)e(w)o(orld-wide)g(license)h(to)g (reproduce,)f(analyze,)i(test,)i(perform)26 b(and/or)h(display)g (publicly)-5 b(,)28 b(prepare)f(deri)n(v)n(a-)208 4658 y(ti)n(v)o(e)g(w)o(orks,)h(distrib)n(ute,)h(and)e(otherwise)g(use)h (Python)e(2.5.3)g(alone)h(or)g(in)h(an)o(y)e(deri)n(v)n(ati)n(v)o(e)g (v)o(ersion,)i(pro)o(vided,)e(ho)n(we)n(v)o(er)m(,)208 4758 y(that)e(PSF')-5 b(s)26 b(License)e(Agreement)f(and)h(PSF')-5 b(s)25 b(notice)f(of)g(cop)o(yright,)f(i.e.,)j(\223Cop)o(yright)2871 4755 y(c)2848 4758 y FM(\015)f FN(2001-2008)c(Python)i(Softw)o(are)208 4857 y(F)o(oundation;)i(All)h(Rights)g(Reserv)o(ed\224)e(are)i (retained)e(in)h(Python)f(2.5.3)g(alone)h(or)g(in)h(an)o(y)e(deri)n(v)n (ati)n(v)o(e)g(v)o(ersion)g(prepared)f(by)208 4957 y(Licensee.)104 5123 y(3.)41 b(In)16 b(the)h(e)n(v)o(ent)f(Licensee)h(prepares)e(a)j (deri)n(v)n(ati)n(v)o(e)d(w)o(ork)h(that)h(is)h(based)e(on)h(or)g (incorporates)d(Python)i(2.5.3)g(or)g(an)o(y)h(part)f(thereof,)208 5223 y(and)25 b(w)o(ants)h(to)f(mak)o(e)g(the)h(deri)n(v)n(ati)n(v)o(e) d(w)o(ork)i(a)n(v)n(ailable)g(to)h(others)f(as)h(pro)o(vided)d(herein,) j(then)f(Licensee)g(hereby)f(agrees)h(to)208 5322 y(include)19 b(in)h(an)o(y)f(such)h(w)o(ork)g(a)h(brief)e(summary)g(of)h(the)g (changes)f(made)h(to)g(Python)f(2.5.3.)p 0 5549 3901 4 v 0 5649 a FI(952)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 953 965 TeXDict begin 953 964 bop 104 83 a FN(4.)41 b(PSF)30 b(is)g(making)e(Python)h(2.5.3)f(a)n(v)n(ailable)h(to)g(Licensee)g(on)g (an)g(\223)-7 b(AS)31 b(IS\224)e(basis.)53 b(PSF)31 b(MAKES)e(NO)h (REPRESENT)-8 b(A-)208 183 y(TIONS)25 b(OR)h(W)-10 b(ARRANTIES,)26 b(EXPRESS)g(OR)g(IMPLIED.)f(BY)h(W)-10 b(A)h(Y)26 b(OF)g(EXAMPLE,)f(B)o (UT)h(NO)m(T)f(LIMIT)-8 b(A)f(TION,)208 282 y(PSF)26 b(MAKES)f(NO)h(AND)g(DISCLAIMS)f(ANY)h(REPRESENT)-8 b(A)f(TION)25 b(OR)h(W)-10 b(ARRANTY)27 b(OF)f(MERCHANT)-8 b(ABIL-)208 382 y(ITY)17 b(OR)h(FITNESS)f(FOR)i(ANY)e(P)-8 b(AR)j(TICULAR)19 b(PURPOSE)f(OR)g(THA)-9 b(T)17 b(THE)g(USE)h(OF)g(PYTHON)f(2.5.3)f (WILL)i(NO)m(T)208 482 y(INFRINGE)i(ANY)g(THIRD)h(P)-8 b(AR)j(TY)21 b(RIGHTS.)104 648 y(5.)41 b(PSF)29 b(SHALL)g(NO)m(T)g(BE)g (LIABLE)g(T)o(O)f(LICENSEE)g(OR)i(ANY)f(O)m(THER)g(USERS)h(OF)f(PYTHON) g(2.5.3)e(FOR)j(ANY)208 747 y(INCIDENT)-8 b(AL,)18 b(SPECIAL,)h(OR)h (CONSEQ)o(UENTIAL)f(D)m(AMA)m(GES)f(OR)i(LOSS)g(AS)g(A)g(RESUL)-8 b(T)19 b(OF)h(MODIFYING,)208 847 y(DISTRIB)o(UTING,)j(OR)h(O)m(THER)-5 b(WISE)24 b(USING)g(PYTHON)g(2.5.3,)f(OR)h(ANY)g(DERIV)-11 b(A)i(TIVE)23 b(THEREOF)-7 b(,)24 b(EVEN)f(IF)208 946 y(AD)m(VISED)c(OF)i(THE)f(POSSIBILITY)g(THEREOF)-7 b(.)104 1112 y(6.)41 b(This)20 b(License)g(Agreement)e(will)j(automatically)e (terminate)g(upon)g(a)i(material)f(breach)f(of)h(its)h(terms)f(and)g (conditions.)104 1279 y(7.)41 b(Nothing)23 b(in)i(this)g(License)g (Agreement)e(shall)i(be)g(deemed)e(to)i(create)g(an)o(y)f(relationship) f(of)i(agenc)o(y)-5 b(,)23 b(partnership,)h(or)h(joint)208 1378 y(v)o(enture)20 b(between)h(PSF)h(and)g(Licensee.)29 b(This)22 b(License)f(Agreement)g(does)g(not)h(grant)f(permission)f(to) i(use)g(PSF)h(trademarks)208 1478 y(or)c(trade)h(name)g(in)g(a)h (trademark)d(sense)j(to)f(endorse)f(or)h(promote)e(products)h(or)h (services)g(of)g(Licensee,)g(or)f(an)o(y)h(third)f(party)-5 b(.)104 1644 y(8.)41 b(By)18 b(cop)o(ying,)e(installing)h(or)h (otherwise)f(using)g(Python)g(2.5.3,)g(Licensee)g(agrees)g(to)h(be)g (bound)e(by)h(the)h(terms)g(and)f(conditions)208 1743 y(of)i(this)i(License)f(Agreement.)846 1926 y FL(BEOPEN.COM)h(LICENSE)h (A)-5 b(GREEMENT)23 b(FOR)d(PYTHON)g(2.0)579 2026 y(BEOPEN)h(PYTHON)f (OPEN)g(SOURCE)h(LICENSE)h(A)-5 b(GREEMENT)23 b(VERSION)e(1)104 2256 y FN(1.)41 b(This)20 b(LICENSE)g(A)m(GREEMENT)f(is)i(between)f (BeOpen.com)e(\(\223BeOpen\224\),)h(ha)n(ving)g(an)h(of)n(\002ce)g(at)g (160)g(Saratoga)e(A)-6 b(v)o(enue,)208 2355 y(Santa)29 b(Clara,)i(CA)f(95051,)f(and)f(the)h(Indi)n(vidual)e(or)i(Or)o (ganization)d(\(\223Licensee\224\))h(accessing)i(and)f(otherwise)h (using)f(this)208 2455 y(softw)o(are)19 b(in)i(source)e(or)h(binary)f (form)g(and)h(its)h(associated)f(documentation)d(\(\223the)j(Softw)o (are\224\).)104 2621 y(2.)41 b(Subject)18 b(to)g(the)h(terms)g(and)f (conditions)f(of)h(this)h(BeOpen)f(Python)f(License)i(Agreement,)e (BeOpen)h(hereby)f(grants)h(Licensee)208 2721 y(a)25 b(non-e)o(xclusi)n(v)o(e,)e(ro)o(yalty-free,)h(w)o(orld-wide)f(license) j(to)f(reproduce,)f(analyze,)h(test,)i(perform)c(and/or)h(display)g (publicly)-5 b(,)208 2820 y(prepare)16 b(deri)n(v)n(ati)n(v)o(e)f(w)o (orks,)j(distrib)n(ute,)f(and)g(otherwise)g(use)h(the)g(Softw)o(are)f (alone)g(or)g(in)h(an)o(y)f(deri)n(v)n(ati)n(v)o(e)f(v)o(ersion,)g(pro) o(vided,)208 2920 y(ho)n(we)n(v)o(er)m(,)f(that)i(the)g(BeOpen)g (Python)f(License)i(is)g(retained)e(in)h(the)h(Softw)o(are,)f(alone)f (or)h(in)h(an)o(y)e(deri)n(v)n(ati)n(v)o(e)g(v)o(ersion)g(prepared)208 3019 y(by)j(Licensee.)104 3185 y(3.)41 b(BeOpen)25 b(is)j(making)c(the) j(Softw)o(are)e(a)n(v)n(ailable)h(to)g(Licensee)g(on)g(an)g(\223)-7 b(AS)27 b(IS\224)g(basis.)43 b(BEOPEN)27 b(MAKES)f(NO)h(REPRE-)208 3285 y(SENT)-8 b(A)f(TIONS)27 b(OR)i(W)-10 b(ARRANTIES,)29 b(EXPRESS)g(OR)g(IMPLIED.)f(BY)h(W)-10 b(A)h(Y)29 b(OF)g(EXAMPLE,)e(B)o (UT)i(NO)m(T)g(LIMI-)208 3385 y(T)-8 b(A)f(TION,)20 b(BEOPEN)h(MAKES)f (NO)i(AND)f(DISCLAIMS)f(ANY)h(REPRESENT)-8 b(A)f(TION)21 b(OR)g(W)-10 b(ARRANTY)22 b(OF)f(MER-)208 3484 y(CHANT)-8 b(ABILITY)21 b(OR)i(FITNESS)e(FOR)i(ANY)f(P)-8 b(AR)j(TICULAR)23 b(PURPOSE)g(OR)f(THA)-9 b(T)21 b(THE)h(USE)g(OF)g(THE)g(SOFT)-8 b(-)208 3584 y(W)e(ARE)21 b(WILL)f(NO)m(T)g(INFRINGE)g(ANY)h(THIRD)f(P) -8 b(AR)j(TY)21 b(RIGHTS.)104 3750 y(4.)41 b(BEOPEN)24 b(SHALL)f(NO)m(T)h(BE)g(LIABLE)g(T)o(O)f(LICENSEE)g(OR)i(ANY)f(O)m (THER)f(USERS)i(OF)f(THE)g(SOFTW)-10 b(ARE)25 b(FOR)208 3850 y(ANY)c(INCIDENT)-8 b(AL,)20 b(SPECIAL,)h(OR)h(CONSEQ)o(UENTIAL)e (D)m(AMA)m(GES)h(OR)h(LOSS)f(AS)h(A)f(RESUL)-8 b(T)22 b(OF)g(USING,)208 3949 y(MODIFYING)j(OR)i(DISTRIB)o(UTING)f(THE)h (SOFTW)-10 b(ARE,)27 b(OR)g(ANY)f(DERIV)-11 b(A)i(TIVE)25 b(THEREOF)-7 b(,)27 b(EVEN)f(IF)g(AD-)208 4049 y(VISED)20 b(OF)h(THE)f(POSSIBILITY)g(THEREOF)-7 b(.)104 4215 y(5.)41 b(This)20 b(License)g(Agreement)e(will)j(automatically)e(terminate)g (upon)g(a)i(material)f(breach)f(of)h(its)h(terms)f(and)g(conditions.) 104 4381 y(6.)41 b(This)27 b(License)f(Agreement)g(shall)h(be)g(go)o(v) o(erned)d(by)j(and)f(interpreted)f(in)j(all)f(respects)g(by)g(the)g(la) o(w)g(of)g(the)g(State)g(of)g(Cali-)208 4481 y(fornia,)22 b(e)o(xcluding)e(con\003ict)j(of)f(la)o(w)i(pro)o(visions.)31 b(Nothing)21 b(in)j(this)f(License)g(Agreement)e(shall)i(be)g(deemed)f (to)h(create)f(an)o(y)208 4580 y(relationship)i(of)h(agenc)o(y)-5 b(,)25 b(partnership,)g(or)g(joint)h(v)o(enture)e(between)h(BeOpen)g (and)g(Licensee.)41 b(This)26 b(License)f(Agreement)208 4680 y(does)18 b(not)h(grant)f(permission)f(to)i(use)h(BeOpen)e (trademarks)f(or)i(trade)f(names)h(in)g(a)g(trademark)e(sense)i(to)g (endorse)f(or)g(promote)208 4779 y(products)k(or)h(services)g(of)h (Licensee,)f(or)h(an)o(y)e(third)h(party)-5 b(.)34 b(As)24 b(an)g(e)o(xception,)e(the)i(\223BeOpen)f(Python\224)f(logos)h(a)n(v)n (ailable)g(at)208 4879 y(http://www)-5 b(.p)o(ythonlabs.com/logo)o (s.htm)o(l)15 b(may)20 b(be)g(used)g(according)e(to)i(the)h (permissions)e(granted)g(on)h(that)g(web)g(page.)104 5045 y(7.)41 b(By)19 b(cop)o(ying,)e(installing)h(or)g(otherwise)g (using)h(the)f(softw)o(are,)h(Licensee)f(agrees)g(to)h(be)f(bound)f(by) i(the)f(terms)h(and)f(conditions)208 5145 y(of)h(this)i(License)f (Agreement.)992 5327 y FL(CNRI)h(LICENSE)h(A)-5 b(GREEMENT)22 b(FOR)e(PYTHON)g(1.6.1)p 0 5549 3901 4 v 0 5649 a FI(C)n(.2.)51 b(T)-10 b(er)r(ms)23 b(and)g(conditions)h(f)n(or)f(accessing)f(or)h (otherwise)g(using)h(Python)1287 b(953)p eop end %%Page: 954 966 TeXDict begin 954 965 bop 104 83 a FN(1.)41 b(This)25 b(LICENSE)g(A)m(GREEMENT)f(is)i(between)e(the)h(Corporation)e(for)h (National)h(Research)g(Initiati)n(v)o(es,)g(ha)n(ving)f(an)h(of)n (\002ce)208 183 y(at)j(1895)f(Preston)h(White)h(Dri)n(v)o(e,)g(Reston,) h(V)-11 b(A)29 b(20191)d(\(\223CNRI\224\),)i(and)f(the)i(Indi)n(vidual) d(or)i(Or)o(ganization)d(\(\223Licensee\224\))208 282 y(accessing)18 b(and)g(otherwise)g(using)g(Python)f(1.6.1)h(softw)o (are)g(in)h(source)e(or)i(binary)e(form)h(and)g(its)h(associated)g (documentation.)104 443 y(2.)41 b(Subject)24 b(to)g(the)h(terms)f(and)g (conditions)f(of)h(this)h(License)g(Agreement,)e(CNRI)j(hereby)d (grants)h(Licensee)g(a)h(none)o(xclusi)n(v)o(e,)208 542 y(ro)o(yalty-free,)18 b(w)o(orld-wide)i(license)h(to)g(reproduce,)d (analyze,)j(test,)g(perform)e(and/or)h(display)h(publicly)-5 b(,)19 b(prepare)g(deri)n(v)n(ati)n(v)o(e)208 642 y(w)o(orks,)28 b(distrib)n(ute,)g(and)f(otherwise)f(use)i(Python)e(1.6.1)f(alone)i(or) g(in)g(an)o(y)f(deri)n(v)n(ati)n(v)o(e)g(v)o(ersion,)h(pro)o(vided,)f (ho)n(we)n(v)o(er)m(,)g(that)208 741 y(CNRI')-5 b(s)30 b(License)f(Agreement)f(and)g(CNRI')-5 b(s)31 b(notice)e(of)g(cop)o (yright,)g(i.e.,)i(\223Cop)o(yright)2893 738 y(c)2870 741 y FM(\015)f FN(1995-2001)25 b(Corporation)i(for)208 841 y(National)k(Research)h(Initiati)n(v)o(es;)37 b(All)32 b(Rights)g(Reserv)o(ed\224)f(are)h(retained)f(in)h(Python)e(1.6.1)h (alone)g(or)g(in)h(an)o(y)f(deri)n(v)n(ati)n(v)o(e)208 941 y(v)o(ersion)22 b(prepared)g(by)h(Licensee.)35 b(Alternately)-5 b(,)23 b(in)h(lieu)g(of)f(CNRI')-5 b(s)25 b(License)f(Agreement,)e (Licensee)i(may)f(substitute)h(the)208 1040 y(follo)n(wing)j(te)o(xt)i (\(omitting)e(the)i(quotes\):)42 b(\223Python)27 b(1.6.1)h(is)h(made)g (a)n(v)n(ailable)f(subject)h(to)g(the)g(terms)g(and)f(conditions)f(in) 208 1140 y(CNRI')-5 b(s)24 b(License)f(Agreement.)33 b(This)24 b(Agreement)d(together)h(with)i(Python)e(1.6.1)g(may)h(be)g (located)g(on)g(the)g(Internet)f(using)208 1240 y(the)27 b(follo)n(wing)f(unique,)h(persistent)g(identi\002er)g(\(kno)n(wn)f(as) i(a)f(handle\):)39 b(1895.22/1013.)j(This)27 b(Agreement)f(may)h(also)h (be)208 1339 y(obtained)18 b(from)h(a)i(proxy)d(serv)o(er)i(on)g(the)g (Internet)f(using)g(the)i(follo)n(wing)d(URL:)j FO(http://hdl.handle)o (.)o(ne)o(t/18)o(95)o(.2)o(2/1)o(01)o(3)-6 b FN(.)g(\224)104 1499 y(3.)41 b(In)16 b(the)h(e)n(v)o(ent)f(Licensee)h(prepares)e(a)j (deri)n(v)n(ati)n(v)o(e)d(w)o(ork)h(that)h(is)h(based)e(on)h(or)g (incorporates)d(Python)i(1.6.1)g(or)g(an)o(y)h(part)f(thereof,)208 1599 y(and)25 b(w)o(ants)h(to)f(mak)o(e)g(the)h(deri)n(v)n(ati)n(v)o(e) d(w)o(ork)i(a)n(v)n(ailable)g(to)h(others)f(as)h(pro)o(vided)d(herein,) j(then)f(Licensee)g(hereby)f(agrees)h(to)208 1699 y(include)19 b(in)h(an)o(y)f(such)h(w)o(ork)g(a)h(brief)e(summary)g(of)h(the)g (changes)f(made)h(to)g(Python)f(1.6.1.)104 1859 y(4.)41 b(CNRI)23 b(is)h(making)d(Python)h(1.6.1)f(a)n(v)n(ailable)h(to)h (Licensee)g(on)f(an)h(\223)-7 b(AS)23 b(IS\224)g(basis.)34 b(CNRI)23 b(MAKES)g(NO)g(REPRESENT)-8 b(A-)208 1959 y(TIONS)25 b(OR)h(W)-10 b(ARRANTIES,)26 b(EXPRESS)g(OR)g(IMPLIED.)f(BY)h(W)-10 b(A)h(Y)26 b(OF)g(EXAMPLE,)f(B)o(UT)h(NO)m(T)f(LIMIT)-8 b(A)f(TION,)208 2058 y(CNRI)20 b(MAKES)f(NO)h(AND)g(DISCLAIMS)f(ANY)h (REPRESENT)-8 b(A)f(TION)19 b(OR)h(W)-10 b(ARRANTY)21 b(OF)f(MERCHANT)-8 b(ABIL-)208 2158 y(ITY)17 b(OR)h(FITNESS)f(FOR)i (ANY)e(P)-8 b(AR)j(TICULAR)19 b(PURPOSE)f(OR)g(THA)-9 b(T)17 b(THE)g(USE)h(OF)g(PYTHON)f(1.6.1)f(WILL)i(NO)m(T)208 2257 y(INFRINGE)i(ANY)g(THIRD)h(P)-8 b(AR)j(TY)21 b(RIGHTS.)104 2418 y(5.)41 b(CNRI)25 b(SHALL)g(NO)m(T)g(BE)g(LIABLE)g(T)o(O)f (LICENSEE)g(OR)i(ANY)f(O)m(THER)g(USERS)h(OF)f(PYTHON)g(1.6.1)e(FOR)j (ANY)208 2517 y(INCIDENT)-8 b(AL,)18 b(SPECIAL,)h(OR)h(CONSEQ)o (UENTIAL)f(D)m(AMA)m(GES)f(OR)i(LOSS)g(AS)g(A)g(RESUL)-8 b(T)19 b(OF)h(MODIFYING,)208 2617 y(DISTRIB)o(UTING,)j(OR)h(O)m(THER)-5 b(WISE)24 b(USING)g(PYTHON)g(1.6.1,)f(OR)h(ANY)g(DERIV)-11 b(A)i(TIVE)23 b(THEREOF)-7 b(,)24 b(EVEN)f(IF)208 2717 y(AD)m(VISED)c(OF)i(THE)f(POSSIBILITY)g(THEREOF)-7 b(.)104 2877 y(6.)41 b(This)20 b(License)g(Agreement)e(will)j(automatically)e (terminate)g(upon)g(a)i(material)f(breach)f(of)h(its)h(terms)f(and)g (conditions.)104 3037 y(7.)41 b(This)16 b(License)f(Agreement)f(shall)j (be)e(go)o(v)o(erned)e(by)j(the)f(federal)g(intellectual)h(property)d (la)o(w)j(of)g(the)g(United)f(States,)i(including)208 3137 y(without)28 b(limitation)g(the)g(federal)g(cop)o(yright)f(la)o(w) -5 b(,)30 b(and,)g(to)f(the)g(e)o(xtent)e(such)i(U.S.)g(federal)e(la)o (w)i(does)g(not)f(apply)-5 b(,)29 b(by)g(the)208 3236 y(la)o(w)f(of)h(the)f(Commonwealth)f(of)h(V)-5 b(ir)o(ginia,)30 b(e)o(xcluding)c(V)-5 b(ir)o(ginia')g(s)28 b(con\003ict)g(of)g(la)o(w)h (pro)o(visions.)49 b(Notwithstanding)27 b(the)208 3336 y(fore)o(going,)c(with)i(re)o(gard)f(to)h(deri)n(v)n(ati)n(v)o(e)e(w)o (orks)i(based)g(on)g(Python)f(1.6.1)g(that)h(incorporate)e (non-separable)g(material)h(that)208 3435 y(w)o(as)29 b(pre)n(viously)d(distrib)n(uted)i(under)f(the)h(GNU)h(General)f (Public)g(License)h(\(GPL\),)f(the)g(la)o(w)h(of)f(the)g(Commonwealth)f (of)208 3535 y(V)-5 b(ir)o(ginia)19 b(shall)j(go)o(v)o(ern)c(this)k (License)e(Agreement)g(only)g(as)h(to)g(issues)h(arising)f(under)e(or)i (with)g(respect)g(to)g(P)o(aragraphs)e(4,)i(5,)208 3635 y(and)d(7)i(of)f(this)h(License)f(Agreement.)k(Nothing)18 b(in)h(this)h(License)f(Agreement)f(shall)i(be)f(deemed)f(to)h(create)g (an)o(y)g(relationship)208 3734 y(of)24 b(agenc)o(y)-5 b(,)24 b(partnership,)g(or)g(joint)h(v)o(enture)e(between)h(CNRI)h(and) f(Licensee.)39 b(This)25 b(License)f(Agreement)f(does)i(not)f(grant)208 3834 y(permission)29 b(to)i(use)g(CNRI)g(trademarks)e(or)h(trade)g (name)g(in)h(a)g(trademark)e(sense)i(to)f(endorse)g(or)g(promote)f (products)g(or)208 3934 y(services)20 b(of)g(Licensee,)f(or)h(an)o(y)g (third)f(party)-5 b(.)104 4094 y(8.)41 b(By)17 b(clicking)f(on)g(the)h (\223)-7 b(A)m(CCEPT\224)18 b(b)n(utton)e(where)g(indicated,)g(or)h(by) f(cop)o(ying,)g(installing)g(or)h(otherwise)f(using)g(Python)g(1.6.1,) 208 4193 y(Licensee)j(agrees)h(to)h(be)f(bound)e(by)i(the)g(terms)g (and)g(conditions)e(of)i(this)h(License)f(Agreement.)1793 4362 y(A)m(CCEPT)722 4461 y FL(CWI)h(LICENSE)h(A)-5 b(GREEMENT)23 b(FOR)d(PYTHON)g(0.9.0)e(THR)n(OUGH)h(1.2)0 4608 y FN(Cop)o(yright)380 4605 y(c)357 4608 y FM(\015)h FN(1991)f(-)i(1995,)d(Stichting)i (Mathematisch)f(Centrum)g(Amsterdam,)g(The)h(Netherlands.)k(All)d (rights)e(reserv)o(ed.)0 4755 y(Permission)g(to)h(use,)g(cop)o(y)-5 b(,)19 b(modify)-5 b(,)17 b(and)i(distrib)n(ute)h(this)g(softw)o(are)f (and)h(its)g(documentation)d(for)i(an)o(y)g(purpose)g(and)g(without)g (fee)h(is)0 4855 y(hereby)i(granted,)g(pro)o(vided)f(that)i(the)h(abo)o (v)o(e)d(cop)o(yright)h(notice)g(appear)h(in)g(all)h(copies)f(and)g (that)g(both)g(that)g(cop)o(yright)e(notice)i(and)0 4954 y(this)f(permission)f(notice)g(appear)f(in)i(supporting)d (documentation,)g(and)i(that)h(the)f(name)g(of)h(Stichting)f (Mathematisch)f(Centrum)h(or)0 5054 y(CWI)26 b(not)f(be)h(used)f(in)g (adv)o(ertising)f(or)h(publicity)f(pertaining)g(to)h(distrib)n(ution)g (of)g(the)g(softw)o(are)g(without)g(speci\002c,)h(written)g(prior)0 5154 y(permission.)0 5300 y(STICHTING)18 b(MA)-9 b(THEMA)g(TISCH)18 b(CENTR)m(UM)g(DISCLAIMS)h(ALL)f(W)-10 b(ARRANTIES)20 b(WITH)f(REGARD)g(T)o(O)f(THIS)h(SOFT)-8 b(-)0 5400 y(W)e(ARE,)23 b(INCLUDING)e(ALL)h(IMPLIED)f(W)-10 b(ARRANTIES)23 b(OF)g(MERCHANT)-8 b(ABILITY)21 b(AND)i(FITNESS,)e(IN)i(NO)f(EVENT)p 0 5549 3901 4 v 0 5649 a FI(954)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 955 967 TeXDict begin 955 966 bop 0 83 a FN(SHALL)30 b(STICHTING)g(MA)-9 b(THEMA)g(TISCH)29 b(CENTR)m(UM)h(BE)g(LIABLE)g(FOR)h(ANY)f(SPECIAL,)g (INDIRECT)g(OR)h(CON-)0 183 y(SEQ)o(UENTIAL)e(D)m(AMA)m(GES)h(OR)h(ANY) f(D)m(AMA)m(GES)f(WHA)-9 b(TSOEVER)31 b(RESUL)-8 b(TING)30 b(FR)m(OM)g(LOSS)h(OF)g(USE,)f(D)m(A)-9 b(T)h(A)0 282 y(OR)25 b(PR)m(OFITS,)f(WHETHER)h(IN)f(AN)h(A)m(CTION)f(OF)h(CONTRA)m (CT)-6 b(,)24 b(NEGLIGENCE)g(OR)h(O)m(THER)f(T)o(OR)-5 b(TIOUS)24 b(A)m(CTION,)0 382 y(ARISING)c(OUT)h(OF)g(OR)g(IN)f (CONNECTION)g(WITH)h(THE)f(USE)h(OR)g(PERFORMANCE)g(OF)g(THIS)f(SOFTW) -10 b(ARE.)0 709 y FE(C)l(.3)121 b(Licenses)34 b(and)h(Ac)n(kno)n (wledgements)g(f)l(or)f(Incor)t(por)o(ated)i(Softw)n(are)0 942 y FN(This)18 b(section)f(is)h(an)g(incomplete,)e(b)n(ut)h(gro)n (wing)f(list)i(of)g(licenses)f(and)g(ackno)n(wledgements)e(for)h (third-party)f(softw)o(are)i(incorporated)0 1042 y(in)j(the)h(Python)e (distrib)n(ution.)0 1327 y Fv(C)m(.3.1)100 b(Mersenne)29 b(T)-12 b(wister)0 1530 y FN(The)15 b FJ(_random)f FN(module)g (includes)h(code)f(based)h(on)g(a)g(do)n(wnload)f(from)g FO(http://www)l(.math.k)o(eio)m(.ac.j)o(p/)g(matumoto/MT2002/emt19937)o (ar)l(.h)o(tml)-6 b FN(.)0 1629 y(The)20 b(follo)n(wing)e(are)j(the)f (v)o(erbatim)e(comments)h(from)h(the)g(original)f(code:)p 0 5549 3901 4 v 0 5649 a FI(C)n(.3.)51 b(Licenses)23 b(and)h(Ac)n(kno)o(wledgements)g(f)n(or)e(Incor)r(por)o(ated)i(Softw)o (are)1374 b(955)p eop end %%Page: 956 968 TeXDict begin 956 967 bop 236 174 a FA(A)45 b(C-program)e(for)i (MT19937,)e(with)h(initialization)f(improved)g(2002/1/26.)236 266 y(Coded)h(by)h(Takuji)f(Nishimura)f(and)h(Makoto)g(Matsumoto.)236 448 y(Before)g(using,)g(initialize)f(the)h(state)g(by)h(using)f (init_genrand\(seed\))236 540 y(or)h(init_by_array\(init_key,)c (key_length\).)236 722 y(Copyright)j(\(C\))g(1997)g(-)h(2002,)f(Makoto) g(Matsumoto)f(and)h(Takuji)g(Nishimura,)236 814 y(All)h(rights)e (reserved.)236 996 y(Redistribution)g(and)h(use)g(in)h(source)f(and)g (binary)g(forms,)g(with)g(or)g(without)236 1088 y(modification,)f(are)h (permitted)g(provided)f(that)h(the)g(following)g(conditions)236 1179 y(are)h(met:)281 1362 y(1.)g(Redistributions)d(of)i(source)g(code) g(must)g(retain)g(the)h(above)f(copyright)416 1453 y(notice,)f(this)h (list)h(of)f(conditions)f(and)h(the)h(following)e(disclaimer.)281 1636 y(2.)i(Redistributions)d(in)i(binary)g(form)g(must)g(reproduce)g (the)g(above)g(copyright)416 1727 y(notice,)f(this)h(list)h(of)f (conditions)f(and)h(the)h(following)e(disclaimer)g(in)i(the)416 1818 y(documentation)d(and/or)i(other)g(materials)f(provided)h(with)g (the)g(distribution.)281 2001 y(3.)h(The)f(names)g(of)g(its)h (contributors)e(may)h(not)g(be)h(used)f(to)g(endorse)g(or)g(promote)416 2092 y(products)f(derived)h(from)g(this)g(software)f(without)h (specific)g(prior)g(written)416 2183 y(permission.)236 2366 y(THIS)g(SOFTWARE)g(IS)g(PROVIDED)g(BY)g(THE)h(COPYRIGHT)e (HOLDERS)h(AND)g(CONTRIBUTORS)236 2457 y("AS)h(IS")f(AND)g(ANY)h (EXPRESS)e(OR)i(IMPLIED)e(WARRANTIES,)g(INCLUDING,)g(BUT)i(NOT)236 2549 y(LIMITED)f(TO,)g(THE)h(IMPLIED)e(WARRANTIES)g(OF)i (MERCHANTABILITY)d(AND)i(FITNESS)g(FOR)236 2640 y(A)h(PARTICULAR)e (PURPOSE)h(ARE)g(DISCLAIMED.)88 b(IN)44 b(NO)h(EVENT)f(SHALL)g(THE)g (COPYRIGHT)f(OWNER)h(OR)236 2731 y(CONTRIBUTORS)f(BE)i(LIABLE)e(FOR)i (ANY)f(DIRECT,)g(INDIRECT,)f(INCIDENTAL,)g(SPECIAL,)236 2823 y(EXEMPLARY,)g(OR)i(CONSEQUENTIAL)e(DAMAGES)g(\(INCLUDING,)g(BUT)h (NOT)h(LIMITED)e(TO,)236 2914 y(PROCUREMENT)g(OF)i(SUBSTITUTE)e(GOODS)h (OR)g(SERVICES;)g(LOSS)g(OF)g(USE,)g(DATA,)g(OR)236 3005 y(PROFITS;)g(OR)g(BUSINESS)g(INTERRUPTION\))e(HOWEVER)i(CAUSED)g(AND)g (ON)h(ANY)f(THEORY)g(OF)236 3097 y(LIABILITY,)f(WHETHER)h(IN)h (CONTRACT,)e(STRICT)h(LIABILITY,)f(OR)h(TORT)g(\(INCLUDING)236 3188 y(NEGLIGENCE)f(OR)i(OTHERWISE\))e(ARISING)h(IN)g(ANY)g(WAY)h(OUT)f (OF)h(THE)f(USE)g(OF)h(THIS)236 3279 y(SOFTWARE,)f(EVEN)g(IF)g(ADVISED) g(OF)g(THE)h(POSSIBILITY)e(OF)h(SUCH)g(DAMAGE.)236 3553 y(Any)h(feedback)e(is)i(very)f(welcome.)236 3645 y (http://www.math.keio.ac.jp/matumoto/emt.)o(html)236 3736 y(email:)g(matumoto@math.keio.ac.jp)0 4161 y Fv(C)m(.3.2)100 b(Soc)n(k)n(ets)0 4364 y FN(The)23 b FJ(socket)g FN(module)e(uses)j (the)g(functions,)e FJ(getaddrinfo)p FN(,)g(and)h FJ(getnameinfo)p FN(,)f(which)h(are)g(coded)f(in)i(separate)e(source)0 4463 y(\002les)f(from)e(the)i(WIDE)f(Project,)g FO(http://www)l(.wide)o (.ad.j)o(p/a)o(bo)o(ut/)o(ind)o(e)m(x.html)-6 b FN(.)p 0 5549 3901 4 v 0 5649 a FI(956)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 957 969 TeXDict begin 957 968 bop 236 83 a FA(Copyright)44 b(\(C\))g(1995,)g (1996,)g(1997,)g(and)g(1998)g(WIDE)g(Project.)236 174 y(All)h(rights)e(reserved.)236 357 y(Redistribution)g(and)h(use)g(in)h (source)f(and)g(binary)g(forms,)g(with)g(or)g(without)236 448 y(modification,)f(are)h(permitted)g(provided)f(that)h(the)g (following)g(conditions)236 540 y(are)h(met:)236 631 y(1.)g(Redistributions)d(of)j(source)e(code)i(must)f(retain)f(the)i (above)f(copyright)371 722 y(notice,)f(this)i(list)f(of)g(conditions)f (and)i(the)f(following)f(disclaimer.)236 814 y(2.)i(Redistributions)d (in)j(binary)e(form)i(must)f(reproduce)f(the)h(above)g(copyright)371 905 y(notice,)f(this)i(list)f(of)g(conditions)f(and)i(the)f(following)f (disclaimer)g(in)i(the)371 996 y(documentation)d(and/or)i(other)g (materials)f(provided)h(with)g(the)g(distribution.)236 1088 y(3.)h(Neither)e(the)i(name)f(of)g(the)h(project)e(nor)i(the)f (names)g(of)g(its)h(contributors)371 1179 y(may)f(be)h(used)f(to)g (endorse)g(or)g(promote)g(products)f(derived)h(from)g(this)g(software) 371 1270 y(without)f(specific)h(prior)g(written)g(permission.)236 1453 y(THIS)g(SOFTWARE)g(IS)g(PROVIDED)g(BY)g(THE)h(PROJECT)e(AND)i (CONTRIBUTORS)d(``AS)j(IS'')f(AND)236 1544 y(GAI_ANY)g(EXPRESS)g(OR)g (IMPLIED)g(WARRANTIES,)f(INCLUDING,)g(BUT)h(NOT)g(LIMITED)g(TO,)g(THE) 236 1636 y(IMPLIED)g(WARRANTIES)f(OF)i(MERCHANTABILITY)d(AND)i(FITNESS) g(FOR)g(A)h(PARTICULAR)e(PURPOSE)236 1727 y(ARE)i(DISCLAIMED.)87 b(IN)45 b(NO)f(EVENT)g(SHALL)g(THE)h(PROJECT)e(OR)i(CONTRIBUTORS)e(BE)h (LIABLE)236 1818 y(FOR)h(GAI_ANY)e(DIRECT,)h(INDIRECT,)f(INCIDENTAL,)g (SPECIAL,)h(EXEMPLARY,)f(OR)h(CONSEQUENTIAL)236 1910 y(DAMAGES)g(\(INCLUDING,)f(BUT)h(NOT)h(LIMITED)e(TO,)h(PROCUREMENT)f (OF)i(SUBSTITUTE)e(GOODS)236 2001 y(OR)i(SERVICES;)e(LOSS)h(OF)h(USE,)f (DATA,)g(OR)g(PROFITS;)g(OR)g(BUSINESS)g(INTERRUPTION\))236 2092 y(HOWEVER)g(CAUSED)g(AND)g(ON)h(GAI_ANY)e(THEORY)h(OF)g (LIABILITY,)g(WHETHER)f(IN)i(CONTRACT,)e(STRICT)236 2183 y(LIABILITY,)g(OR)i(TORT)f(\(INCLUDING)f(NEGLIGENCE)g(OR)i(OTHERWISE\)) e(ARISING)h(IN)g(GAI_ANY)g(WAY)236 2275 y(OUT)h(OF)f(THE)g(USE)h(OF)f (THIS)g(SOFTWARE,)g(EVEN)g(IF)g(ADVISED)g(OF)g(THE)h(POSSIBILITY)e(OF) 236 2366 y(SUCH)h(DAMAGE.)0 2791 y Fv(C)m(.3.3)100 b(Floating)29 b(point)f(e)m(xception)i(control)0 2994 y FN(The)20 b(source)f(for)h (the)g FJ(fpectl)g FN(module)f(includes)g(the)h(follo)n(wing)f(notice:) p 0 5549 3901 4 v 0 5649 a FI(C)n(.3.)51 b(Licenses)23 b(and)h(Ac)n(kno)o(wledgements)g(f)n(or)e(Incor)r(por)o(ated)i(Softw)o (are)1374 b(957)p eop end %%Page: 958 970 TeXDict begin 958 969 bop 460 174 a FA (-----------------------------------------)o(------)o(------)o(------)o (------)o(----)416 266 y(/)1031 b(Copyright)43 b(\(c\))h(1996.)1210 b(\\)371 357 y(|)448 b(The)44 b(Regents)g(of)g(the)h(University)e(of)h (California.)761 b(|)371 448 y(|)1076 b(All)44 b(rights)g(reserved.) 1209 b(|)371 540 y(|)3183 b(|)371 631 y(|)134 b(Permission)43 b(to)i(use,)f(copy,)g(modify,)f(and)i(distribute)e(this)h(software)g (for)134 b(|)371 722 y(|)g(any)44 b(purpose)g(without)g(fee)g(is)h (hereby)e(granted,)h(provided)f(that)h(this)h(en-)134 b(|)371 814 y(|)g(tire)44 b(notice)g(is)h(included)e(in)i(all)f(copies) g(of)g(any)g(software)g(which)g(is)g(or)135 b(|)371 905 y(|)f(includes)88 b(a)i(copy)f(or)g(modification)f(of)h(this)44 b(software)g(and)g(in)h(all)134 b(|)371 996 y(|)g(copies)44 b(of)g(the)h(supporting)e(documentation)f(for)j(such)f(software.)492 b(|)371 1088 y(|)3183 b(|)371 1179 y(|)134 b(This)89 b(work)44 b(was)h(produced)e(at)i(the)f(University)f(of)h(California,)f (Lawrence)134 b(|)371 1270 y(|)g(Livermore)43 b(National)h(Laboratory)f (under)89 b(contract)f(no.)h(W-7405-ENG-48)133 b(|)371 1362 y(|)h(between)89 b(the)g(U.S.)g(Department)f(of)h(Energy)44 b(and)g(The)g(Regents)g(of)h(the)134 b(|)371 1453 y(|)g(University)43 b(of)i(California)e(for)h(the)g(operation)g(of)g(UC)h(LLNL.)627 b(|)371 1544 y(|)3183 b(|)371 1636 y(|)1345 b(DISCLAIMER)1388 b(|)371 1727 y(|)3183 b(|)371 1818 y(|)134 b(This)89 b(software)44 b(was)g(prepared)f(as)i(an)f(account)g(of)g(work)h (sponsored)e(by)h(an)135 b(|)371 1910 y(|)f(agency)44 b(of)g(the)h(United)f(States)f(Government.)g(Neither)h(the)g(United)g (States)134 b(|)371 2001 y(|)g(Government)88 b(nor)44 b(the)h(University)e(of)h(California)f(nor)i(any)f(of)h(their)f(em-)134 b(|)371 2092 y(|)g(ployees,)44 b(makes)g(any)g(warranty,)f(express)h (or)g(implied,)g(or)89 b(assumes)g(any)134 b(|)371 2183 y(|)g(liability)88 b(or)i(responsibility)d(for)44 b(the)g(accuracy,)g (completeness,)e(or)135 b(|)371 2275 y(|)f(usefulness)43 b(of)i(any)f(information,)88 b(apparatus,)g(product,)g(or)h(process)134 b(|)371 2366 y(|)g(disclosed,)f(or)89 b(represents)f(that)h(its)g(use)g (would)g(not)g(infringe)134 b(|)371 2457 y(|)g(privately-owned)42 b(rights.)i(Reference)f(herein)h(to)h(any)f(specific)88 b(commer-)134 b(|)371 2549 y(|)g(cial)89 b(products,)f(process,)h(or)g (service)f(by)45 b(trade)f(name,)g(trademark,)133 b(|)371 2640 y(|)h(manufacturer,)43 b(or)h(otherwise,)f(does)h(not)90 b(necessarily)d(constitute)h(or)135 b(|)371 2731 y(|)f(imply)89 b(its)44 b(endorsement,)f(recommendation,)f(or)j(favoring)e(by)i(the)f (United)134 b(|)371 2823 y(|)g(States)44 b(Government)f(or)i(the)f (University)f(of)h(California.)f(The)i(views)89 b(and)134 b(|)371 2914 y(|)g(opinions)88 b(of)45 b(authors)f(expressed)f(herein)h (do)g(not)g(necessarily)f(state)h(or)135 b(|)371 3005 y(|)f(reflect)44 b(those)g(of)g(the)h(United)e(States)h(Government)f (or)90 b(the)f(University)133 b(|)371 3097 y(|)h(of)89 b(California,)f(and)45 b(shall)f(not)g(be)g(used)g(for)h(advertising)e (or)h(product)134 b(|)416 3188 y(\\)89 b(endorsement)43 b(purposes.)2061 b(/)460 3279 y (-----------------------------------------)o(------)o(------)o(------)o (------)o(----)0 3704 y Fv(C)m(.3.4)100 b(MD5)28 b(message)h(digest)f (algor)q(ithm)0 3907 y FN(The)20 b(source)f(code)h(for)f(the)i FJ(md5)f FN(module)f(contains)g(the)h(follo)n(wing)f(notice:)p 0 5549 3901 4 v 0 5649 a FI(958)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 959 971 TeXDict begin 959 970 bop 326 174 a FA(Copyright)43 b(\(C\))i(1999,)f (2002)g(Aladdin)f(Enterprises.)88 b(All)44 b(rights)g(reserved.)326 357 y(This)g(software)g(is)g(provided)g('as-is',)f(without)h(any)g (express)g(or)g(implied)326 448 y(warranty.)88 b(In)45 b(no)f(event)g(will)g(the)h(authors)e(be)i(held)f(liable)g(for)g(any)g (damages)326 540 y(arising)g(from)g(the)g(use)g(of)h(this)f(software.) 326 722 y(Permission)f(is)i(granted)e(to)i(anyone)f(to)g(use)g(this)g (software)g(for)g(any)h(purpose,)326 814 y(including)e(commercial)g (applications,)g(and)h(to)h(alter)f(it)g(and)h(redistribute)d(it)326 905 y(freely,)i(subject)f(to)i(the)f(following)f(restrictions:)326 1088 y(1.)h(The)h(origin)f(of)g(this)g(software)g(must)g(not)g(be)h (misrepresented;)d(you)i(must)g(not)460 1179 y(claim)g(that)h(you)f (wrote)g(the)g(original)g(software.)f(If)h(you)h(use)f(this)g(software) 460 1270 y(in)h(a)g(product,)e(an)i(acknowledgment)d(in)i(the)h (product)e(documentation)g(would)h(be)460 1362 y(appreciated)f(but)i (is)f(not)h(required.)326 1453 y(2.)f(Altered)g(source)g(versions)f (must)i(be)f(plainly)g(marked)f(as)i(such,)f(and)g(must)g(not)h(be)460 1544 y(misrepresented)e(as)h(being)g(the)h(original)e(software.)326 1636 y(3.)h(This)h(notice)e(may)i(not)f(be)h(removed)e(or)i(altered)e (from)h(any)h(source)f(distribution.)326 1818 y(L.)g(Peter)g(Deutsch) 326 1910 y(ghost@aladdin.com)326 2092 y(Independent)f(implementation)f (of)j(MD5)f(\(RFC)g(1321\).)326 2275 y(This)g(code)g(implements)f(the)i (MD5)f(Algorithm)f(defined)h(in)g(RFC)h(1321,)f(whose)326 2366 y(text)g(is)h(available)e(at)236 2457 y (http://www.ietf.org/rfc/rfc1321.txt)326 2549 y(The)h(code)g(is)h (derived)f(from)g(the)g(text)g(of)h(the)f(RFC,)g(including)f(the)i (test)f(suite)326 2640 y(\(section)f(A.5\))i(but)f(excluding)f(the)i (rest)f(of)g(Appendix)g(A.)89 b(It)44 b(does)h(not)f(include)326 2731 y(any)g(code)g(or)h(documentation)e(that)h(is)g(identified)f(in)i (the)f(RFC)g(as)h(being)326 2823 y(copyrighted.)326 3005 y(The)f(original)g(and)g(principal)f(author)h(of)h(md5.h)f(is)g(L.)h (Peter)f(Deutsch)326 3097 y(<ghost@aladdin.com>.)86 b(Other)44 b(authors)g(are)g(noted)g(in)h(the)f(change)g(history)326 3188 y(that)g(follows)g(\(in)g(reverse)g(chronological)e(order\):)326 3371 y(2002-04-13)h(lpd)h(Removed)g(support)g(for)g(non-ANSI)f (compilers;)h(removed)236 3462 y(references)f(to)i(Ghostscript;)e (clarified)g(derivation)g(from)h(RFC)h(1321;)236 3553 y(now)g(handles)e(byte)h(order)g(either)g(statically)f(or)i (dynamically.)326 3645 y(1999-11-04)e(lpd)h(Edited)g(comments)g (slightly)f(for)h(automatic)g(TOC)g(extraction.)326 3736 y(1999-10-18)f(lpd)h(Fixed)g(typo)h(in)f(header)g(comment)f(\(ansi2knr) h(rather)g(than)g(md5\);)236 3827 y(added)g(conditionalization)e(for)i (C++)h(compilation)e(from)h(Martin)236 3919 y(Purschke)g (<purschke@bnl.gov>.)326 4010 y(1999-05-03)f(lpd)h(Original)g(version.) 0 4435 y Fv(C)m(.3.5)100 b(Asynchronous)30 b(soc)n(k)n(et)d(ser)s (vices)0 4638 y FN(The)20 b FJ(asynchat)f FN(and)h FJ(asyncore)f FN(modules)g(contain)g(the)i(follo)n(wing)d(notice:)p 0 5549 3901 4 v 0 5649 a FI(C)n(.3.)51 b(Licenses)23 b(and)h(Ac)n(kno)o(wledgements)g(f)n(or)e(Incor)r(por)o(ated)i(Softw)o (are)1374 b(959)p eop end %%Page: 960 972 TeXDict begin 960 971 bop 281 174 a FA(Copyright)43 b(1996)i(by)f(Sam)g (Rushing)1357 357 y(All)g(Rights)g(Reserved)281 540 y(Permission)f(to)i (use,)f(copy,)g(modify,)g(and)g(distribute)f(this)h(software)g(and)281 631 y(its)g(documentation)f(for)h(any)h(purpose)e(and)i(without)e(fee)i (is)f(hereby)281 722 y(granted,)g(provided)f(that)h(the)h(above)f (copyright)f(notice)h(appear)f(in)i(all)281 814 y(copies)f(and)g(that)g (both)h(that)f(copyright)f(notice)h(and)g(this)g(permission)281 905 y(notice)g(appear)g(in)g(supporting)f(documentation,)g(and)h(that)g (the)h(name)f(of)g(Sam)281 996 y(Rushing)g(not)g(be)h(used)f(in)g (advertising)f(or)i(publicity)e(pertaining)g(to)281 1088 y(distribution)g(of)h(the)h(software)e(without)h(specific,)f(written)h (prior)281 1179 y(permission.)281 1362 y(SAM)g(RUSHING)g(DISCLAIMS)f (ALL)i(WARRANTIES)e(WITH)h(REGARD)g(TO)g(THIS)g(SOFTWARE,)281 1453 y(INCLUDING)f(ALL)i(IMPLIED)e(WARRANTIES)h(OF)g(MERCHANTABILITY)e (AND)j(FITNESS,)e(IN)281 1544 y(NO)i(EVENT)f(SHALL)g(SAM)g(RUSHING)g (BE)g(LIABLE)g(FOR)g(ANY)g(SPECIAL,)g(INDIRECT)f(OR)281 1636 y(CONSEQUENTIAL)g(DAMAGES)g(OR)i(ANY)f(DAMAGES)g(WHATSOEVER)f (RESULTING)g(FROM)h(LOSS)281 1727 y(OF)h(USE,)f(DATA)g(OR)g(PROFITS,)g (WHETHER)g(IN)g(AN)g(ACTION)g(OF)h(CONTRACT,)281 1818 y(NEGLIGENCE)e(OR)i(OTHER)f(TORTIOUS)f(ACTION,)h(ARISING)f(OUT)i(OF)f (OR)h(IN)281 1910 y(CONNECTION)e(WITH)h(THE)h(USE)f(OR)h(PERFORMANCE)d (OF)j(THIS)f(SOFTWARE.)0 2334 y Fv(C)m(.3.6)100 b(Cookie)28 b(management)0 2537 y FN(The)20 b FJ(Cookie)f FN(module)g(contains)h (the)g(follo)n(wing)f(notice:)281 2775 y FA(Copyright)43 b(2000)i(by)f(Timothy)g(O'Malley)f(<timo@alum.mit.edu>)954 2958 y(All)h(Rights)g(Reserved)281 3141 y(Permission)f(to)i(use,)f (copy,)g(modify,)g(and)g(distribute)f(this)h(software)281 3232 y(and)g(its)h(documentation)d(for)j(any)f(purpose)g(and)g(without) g(fee)g(is)g(hereby)281 3323 y(granted,)g(provided)f(that)h(the)h (above)f(copyright)f(notice)h(appear)f(in)i(all)281 3415 y(copies)f(and)g(that)g(both)h(that)f(copyright)f(notice)h(and)g(this)g (permission)281 3506 y(notice)g(appear)g(in)g(supporting)f (documentation,)g(and)h(that)g(the)h(name)f(of)281 3597 y(Timothy)g(O'Malley)88 b(not)44 b(be)h(used)f(in)h(advertising)d(or)j (publicity)281 3689 y(pertaining)e(to)i(distribution)e(of)h(the)g (software)g(without)f(specific,)h(written)281 3780 y(prior)g (permission.)281 3963 y(Timothy)g(O'Malley)f(DISCLAIMS)h(ALL)g (WARRANTIES)f(WITH)h(REGARD)g(TO)g(THIS)281 4054 y(SOFTWARE,)f (INCLUDING)h(ALL)g(IMPLIED)g(WARRANTIES)f(OF)h(MERCHANTABILITY)281 4145 y(AND)g(FITNESS,)g(IN)g(NO)h(EVENT)f(SHALL)g(Timothy)f(O'Malley)h (BE)g(LIABLE)g(FOR)281 4237 y(ANY)g(SPECIAL,)g(INDIRECT)f(OR)i (CONSEQUENTIAL)d(DAMAGES)i(OR)h(ANY)f(DAMAGES)281 4328 y(WHATSOEVER)f(RESULTING)h(FROM)g(LOSS)g(OF)g(USE,)g(DATA)h(OR)f (PROFITS,)281 4419 y(WHETHER)g(IN)g(AN)h(ACTION)f(OF)g(CONTRACT,)f (NEGLIGENCE)g(OR)i(OTHER)f(TORTIOUS)281 4511 y(ACTION,)g(ARISING)f(OUT) i(OF)f(OR)h(IN)f(CONNECTION)f(WITH)h(THE)h(USE)f(OR)281 4602 y(PERFORMANCE)f(OF)i(THIS)f(SOFTWARE.)0 5027 y Fv(C)m(.3.7)100 b(Pro\002ling)0 5229 y FN(The)20 b FJ(profile)f FN(and)h FJ(pstats)g FN(modules)f(contain)g(the)h(follo)n(wing)f(notice:)p 0 5549 3901 4 v 0 5649 a FI(960)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 961 973 TeXDict begin 961 972 bop 281 174 a FA(Copyright)43 b(1994,)h(by)h (InfoSeek)e(Corporation,)g(all)h(rights)g(reserved.)281 266 y(Written)g(by)g(James)g(Roskind)281 448 y(Permission)f(to)i(use,)f (copy,)g(modify,)g(and)g(distribute)f(this)h(Python)g(software)281 540 y(and)g(its)h(associated)e(documentation)g(for)h(any)g(purpose)g (\(subject)f(to)i(the)281 631 y(restriction)e(in)i(the)f(following)f (sentence\))g(without)h(fee)g(is)h(hereby)f(granted,)281 722 y(provided)g(that)g(the)g(above)g(copyright)f(notice)h(appears)g (in)g(all)h(copies,)e(and)281 814 y(that)h(both)g(that)h(copyright)e (notice)h(and)g(this)g(permission)f(notice)h(appear)g(in)281 905 y(supporting)f(documentation,)g(and)h(that)g(the)g(name)h(of)f (InfoSeek)g(not)g(be)g(used)h(in)281 996 y(advertising)e(or)i (publicity)e(pertaining)g(to)h(distribution)f(of)i(the)f(software)281 1088 y(without)g(specific,)f(written)h(prior)g(permission.)87 b(This)45 b(permission)e(is)281 1179 y(explicitly)g(restricted)g(to)i (the)f(copying)g(and)g(modification)f(of)h(the)h(software)281 1270 y(to)g(remain)e(in)i(Python,)f(compiled)f(Python,)h(or)g(other)g (languages)f(\(such)h(as)h(C\))281 1362 y(wherein)f(the)g(modified)g (or)g(derived)g(code)g(is)g(exclusively)f(imported)h(into)g(a)281 1453 y(Python)g(module.)281 1636 y(INFOSEEK)g(CORPORATION)f(DISCLAIMS)g (ALL)h(WARRANTIES)f(WITH)h(REGARD)g(TO)h(THIS)281 1727 y(SOFTWARE,)e(INCLUDING)h(ALL)g(IMPLIED)g(WARRANTIES)f(OF)h (MERCHANTABILITY)f(AND)281 1818 y(FITNESS.)h(IN)g(NO)h(EVENT)f(SHALL)g (INFOSEEK)f(CORPORATION)g(BE)h(LIABLE)g(FOR)h(ANY)281 1910 y(SPECIAL,)f(INDIRECT)f(OR)i(CONSEQUENTIAL)d(DAMAGES)i(OR)g(ANY)h (DAMAGES)e(WHATSOEVER)281 2001 y(RESULTING)g(FROM)i(LOSS)f(OF)g(USE,)g (DATA)h(OR)f(PROFITS,)f(WHETHER)h(IN)h(AN)f(ACTION)g(OF)281 2092 y(CONTRACT,)f(NEGLIGENCE)h(OR)g(OTHER)g(TORTIOUS)f(ACTION,)h (ARISING)g(OUT)g(OF)h(OR)f(IN)281 2183 y(CONNECTION)f(WITH)h(THE)h(USE) f(OR)h(PERFORMANCE)d(OF)j(THIS)f(SOFTWARE.)0 2608 y Fv(C)m(.3.8)100 b(Ex)m(ecution)29 b(tr)o(acing)0 2811 y FN(The)20 b FJ(trace)g FN(module)e(contains)i(the)g(follo)n(wing)f(notice:)p 0 5549 3901 4 v 0 5649 a FI(C)n(.3.)51 b(Licenses)23 b(and)h(Ac)n(kno)o(wledgements)g(f)n(or)e(Incor)r(por)o(ated)i(Softw)o (are)1374 b(961)p eop end %%Page: 962 974 TeXDict begin 962 973 bop 281 174 a FA(portions)44 b(copyright)f(2001,) h(Autonomous)f(Zones)h(Industries,)f(Inc.,)h(all)g(rights...)281 266 y(err...)89 b(reserved)43 b(and)i(offered)e(to)i(the)f(public)g (under)g(the)g(terms)g(of)h(the)281 357 y(Python)f(2.2)g(license.)281 448 y(Author:)g(Zooko)g(O'Whielacronx)281 540 y(http://zooko.com/)281 631 y(mailto:zooko@zooko.com)281 814 y(Copyright)f(2000,)h(Mojam)g (Media,)g(Inc.,)g(all)g(rights)g(reserved.)281 905 y(Author:)g(Skip)g (Montanaro)281 1088 y(Copyright)f(1999,)h(Bioreason,)g(Inc.,)g(all)g (rights)g(reserved.)281 1179 y(Author:)g(Andrew)g(Dalke)281 1362 y(Copyright)f(1995-1997,)h(Automatrix,)f(Inc.,)g(all)i(rights)f (reserved.)281 1453 y(Author:)g(Skip)g(Montanaro)281 1636 y(Copyright)f(1991-1995,)h(Stichting)f(Mathematisch)g(Centrum,)g (all)h(rights)g(reserved.)281 1910 y(Permission)f(to)i(use,)f(copy,)g (modify,)g(and)g(distribute)f(this)h(Python)g(software)f(and)281 2001 y(its)h(associated)g(documentation)e(for)j(any)f(purpose)f (without)h(fee)g(is)h(hereby)281 2092 y(granted,)f(provided)f(that)h (the)h(above)f(copyright)f(notice)h(appears)f(in)i(all)f(copies,)281 2183 y(and)g(that)h(both)f(that)g(copyright)f(notice)h(and)g(this)g (permission)g(notice)f(appear)h(in)281 2275 y(supporting)f (documentation,)g(and)h(that)g(the)g(name)h(of)f(neither)g(Automatrix,) 281 2366 y(Bioreason)f(or)i(Mojam)f(Media)g(be)g(used)h(in)f (advertising)f(or)h(publicity)g(pertaining)f(to)281 2457 y(distribution)g(of)h(the)h(software)e(without)h(specific,)f(written)h (prior)g(permission.)0 2882 y Fv(C)m(.3.9)100 b(UUencode)29 b(and)g(UUdecode)g(functions)0 3085 y FN(The)20 b FJ(uu)g FN(module)f(contains)h(the)g(follo)n(wing)e(notice:)p 0 5549 3901 4 v 0 5649 a FI(962)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 963 975 TeXDict begin 963 974 bop 281 174 a FA(Copyright)43 b(1994)i(by)f (Lance)g(Ellinghouse)281 266 y(Cathedral)f(City,)h(California)g (Republic,)f(United)h(States)f(of)i(America.)1312 357 y(All)g(Rights)e(Reserved)281 448 y(Permission)g(to)i(use,)f(copy,)g (modify,)g(and)g(distribute)f(this)h(software)g(and)g(its)281 540 y(documentation)f(for)h(any)g(purpose)g(and)g(without)g(fee)g(is)h (hereby)f(granted,)281 631 y(provided)g(that)g(the)g(above)g(copyright) f(notice)h(appear)g(in)g(all)h(copies)f(and)g(that)281 722 y(both)g(that)g(copyright)g(notice)g(and)g(this)g(permission)f (notice)h(appear)g(in)281 814 y(supporting)f(documentation,)g(and)h (that)g(the)g(name)h(of)f(Lance)g(Ellinghouse)281 905 y(not)g(be)h(used)f(in)h(advertising)e(or)h(publicity)f(pertaining)g (to)i(distribution)281 996 y(of)g(the)f(software)f(without)h(specific,) f(written)h(prior)g(permission.)281 1088 y(LANCE)g(ELLINGHOUSE)f (DISCLAIMS)g(ALL)i(WARRANTIES)e(WITH)h(REGARD)g(TO)281 1179 y(THIS)g(SOFTWARE,)g(INCLUDING)f(ALL)h(IMPLIED)g(WARRANTIES)f(OF)h (MERCHANTABILITY)f(AND)281 1270 y(FITNESS,)h(IN)g(NO)h(EVENT)f(SHALL)g (LANCE)g(ELLINGHOUSE)e(CENTRUM)i(BE)h(LIABLE)281 1362 y(FOR)f(ANY)h(SPECIAL,)e(INDIRECT)h(OR)g(CONSEQUENTIAL)f(DAMAGES)g(OR)i (ANY)f(DAMAGES)281 1453 y(WHATSOEVER)f(RESULTING)h(FROM)g(LOSS)g(OF)g (USE,)g(DATA)h(OR)f(PROFITS,)g(WHETHER)f(IN)i(AN)281 1544 y(ACTION)f(OF)g(CONTRACT,)g(NEGLIGENCE)f(OR)h(OTHER)g(TORTIOUS)g (ACTION,)f(ARISING)h(OUT)281 1636 y(OF)h(OR)f(IN)h(CONNECTION)e(WITH)h (THE)g(USE)h(OR)f(PERFORMANCE)f(OF)h(THIS)h(SOFTWARE.)281 1818 y(Modified)f(by)g(Jack)g(Jansen,)g(CWI,)g(July)g(1995:)281 1910 y(-)h(Use)f(binascii)g(module)f(to)i(do)f(the)h(actual)e (line-by-line)g(conversion)371 2001 y(between)g(ascii)h(and)h(binary.)e (This)i(results)e(in)i(a)f(1000-fold)g(speedup.)f(The)h(C)371 2092 y(version)f(is)i(still)f(5)h(times)f(faster,)f(though.)281 2183 y(-)i(Arguments)e(more)h(compliant)g(with)g(python)f(standard)0 2608 y Fv(C)m(.3.10)100 b(XML)29 b(Remote)f(Procedure)i(Calls)0 2811 y FN(The)20 b FJ(xmlrpclib)f FN(module)g(contains)g(the)h(follo)n (wing)f(notice:)p 0 5549 3901 4 v 0 5649 a FI(C)n(.3.)51 b(Licenses)23 b(and)h(Ac)n(kno)o(wledgements)g(f)n(or)e(Incor)r(por)o (ated)i(Softw)o(are)1374 b(963)p eop end %%Page: 964 976 TeXDict begin 964 975 bop 460 174 a FA(The)45 b(XML-RPC)e(client)h (interface)g(is)281 357 y(Copyright)f(\(c\))i(1999-2002)e(by)i(Secret)e (Labs)h(AB)281 448 y(Copyright)f(\(c\))i(1999-2002)e(by)i(Fredrik)e (Lundh)281 631 y(By)i(obtaining,)e(using,)h(and/or)f(copying)h(this)g (software)g(and/or)f(its)281 722 y(associated)g(documentation,)g(you)h (agree)g(that)g(you)g(have)h(read,)f(understood,)281 814 y(and)g(will)h(comply)e(with)i(the)f(following)f(terms)h(and)g (conditions:)281 996 y(Permission)f(to)i(use,)f(copy,)g(modify,)g(and)g (distribute)f(this)h(software)g(and)281 1088 y(its)g(associated)g (documentation)e(for)j(any)f(purpose)f(and)i(without)e(fee)i(is)281 1179 y(hereby)f(granted,)f(provided)h(that)g(the)g(above)g(copyright)g (notice)f(appears)h(in)281 1270 y(all)g(copies,)g(and)g(that)h(both)f (that)g(copyright)f(notice)h(and)g(this)g(permission)281 1362 y(notice)g(appear)g(in)g(supporting)f(documentation,)g(and)h(that) g(the)h(name)f(of)281 1453 y(Secret)g(Labs)g(AB)h(or)f(the)g(author)g (not)h(be)f(used)g(in)h(advertising)e(or)h(publicity)281 1544 y(pertaining)f(to)i(distribution)e(of)h(the)g(software)g(without)f (specific,)h(written)281 1636 y(prior)g(permission.)281 1818 y(SECRET)g(LABS)g(AB)h(AND)f(THE)g(AUTHOR)g(DISCLAIMS)f(ALL)i (WARRANTIES)e(WITH)h(REGARD)281 1910 y(TO)h(THIS)f(SOFTWARE,)f (INCLUDING)g(ALL)i(IMPLIED)e(WARRANTIES)g(OF)i(MERCHANT-)281 2001 y(ABILITY)f(AND)g(FITNESS.)88 b(IN)45 b(NO)f(EVENT)g(SHALL)g (SECRET)g(LABS)g(AB)h(OR)f(THE)h(AUTHOR)281 2092 y(BE)g(LIABLE)e(FOR)i (ANY)f(SPECIAL,)g(INDIRECT)f(OR)h(CONSEQUENTIAL)f(DAMAGES)h(OR)g(ANY) 281 2183 y(DAMAGES)g(WHATSOEVER)f(RESULTING)g(FROM)h(LOSS)g(OF)h(USE,)f (DATA)g(OR)h(PROFITS,)281 2275 y(WHETHER)f(IN)g(AN)h(ACTION)f(OF)g (CONTRACT,)f(NEGLIGENCE)g(OR)i(OTHER)f(TORTIOUS)281 2366 y(ACTION,)g(ARISING)f(OUT)i(OF)f(OR)h(IN)f(CONNECTION)f(WITH)h(THE)h (USE)f(OR)h(PERFORMANCE)281 2457 y(OF)g(THIS)f(SOFTWARE.)p 0 5549 3901 4 v 0 5649 a FI(964)2535 b(Appendix)24 b(C)n(.)46 b(Histor)r(y)22 b(and)i(License)p eop end %%Page: 965 977 TeXDict begin 965 976 bop 2328 567 a FT(MODULE)57 b(INDEX)0 1323 y FE(Symbols)0 1446 y FJ(__builtin__)p FN(,)18 b(834)0 1546 y FJ(__future__)p FN(,)h(842)0 1646 y FJ(__main__)p FN(,)g(834)0 1745 y FJ(_winreg)p FN(,)g(941)0 1928 y FE(A)0 2051 y FJ(aifc)p FN(,)h(697)0 2151 y FJ(AL)p FN(,)g(915)0 2250 y FJ(al)p FN(,)g(913)0 2350 y FJ(anydbm)p FN(,)f(375)0 2450 y FJ(array)p FN(,)h(125)0 2549 y FJ(asynchat)p FN(,)f(595)0 2649 y FJ(asyncore)p FN(,)g(592)0 2748 y FJ(atexit)p FN(,)g(839)0 2848 y FJ(audioop)p FN(,)g(693)0 3031 y FE(B)0 3154 y FJ(base64)p FN(,)g(251)0 3254 y FJ(BaseHTTPServer)p FN(,)f(667)0 3353 y FJ(Bastion)p FN(,)h(863)0 3453 y FJ(binascii)p FN(,)g(253)0 3552 y FJ(binhex)p FN(,)g(253)0 3652 y FJ(bisect)p FN(,)g(124)0 3752 y FJ(bsddb)p FN(,)h(379)0 3851 y FJ(bz2)p FN(,)g(346)0 4042 y FE(C)0 4166 y FJ(calendar)p FN(,)f(113)0 4265 y FJ(cd)p FN(,)h(915)0 4365 y FJ(cgi)p FN(,)g(602)0 4465 y FJ(CGIHTTPServer)p FN(,)e(671)0 4564 y FJ(cgitb)p FN(,)i(609)0 4664 y FJ(chunk)p FN(,)g(704)0 4763 y FJ(cmath)p FN(,)g(151)0 4863 y FJ(cmd)p FN(,)g(757)0 4963 y FJ(code)p FN(,)g(855)0 5062 y FJ(codecs)p FN(,)f(77)0 5162 y FJ(codeop)p FN(,)g(857)0 5262 y FJ(collections)p FN(,)f(116)0 5361 y FJ(colorsys)p FN(,)h(705)1992 1318 y FJ(commands)p FN(,)g(569)1992 1418 y FJ(compileall)p FN(,)f(887)1992 1517 y FJ(compiler)p FN(,)h(897)1992 1617 y FJ(compiler.ast)p FN(,)f(898)1992 1716 y FJ(compiler.visitor)p FN(,)f(903)1992 1816 y FJ(ConfigParser)p FN(,)h(310)1992 1916 y FJ(contextlib)p FN(,)g(837)1992 2015 y FJ(Cookie)p FN(,)h(680)1992 2115 y FJ(cookielib)p FN(,)f(672)1992 2215 y FJ(copy)p FN(,)h(143)1992 2314 y FJ(copy_reg)p FN(,)g(371)1992 2414 y FJ(cPickle)p FN(,)g(370)1992 2513 y FJ(cProfile)p FN(,)g(814)1992 2613 y FJ(crypt)p FN(,)g(556)1992 2713 y FJ(cStringIO)p FN(,)f(75)1992 2812 y FJ(csv)p FN(,)h(303)1992 2912 y FJ(ctypes)p FN(,)g(500)1992 3012 y FJ(curses)p FN(,)g(472)1992 3111 y FJ(curses.ascii)p FN(,)f(488)1992 3211 y FJ(curses.panel)p FN(,)g(491)1992 3310 y FJ(curses.textpad)p FN(,)f(487)1992 3410 y FJ(curses.wrapper)p FN(,)g(488)1992 3584 y FE(D)1992 3708 y FJ(datetime)p FN(,)i(95)1992 3807 y FJ(dbhash)p FN(,)g(378)1992 3907 y FJ(dbm)p FN(,)g(376)1992 4007 y FJ(decimal)p FN(,)g(153)1992 4106 y FJ(DEVICE)p FN(,)g(927)1992 4206 y FJ(difflib)p FN(,)g(65)1992 4305 y FJ(dircache)p FN(,)g(340)1992 4405 y FJ(dis)p FN(,)g(888)1992 4505 y FJ(distutils)p FN(,)f(896)1992 4604 y FJ(dl)p FN(,)i(557)1992 4704 y FJ(doctest)p FN(,)f(764)1992 4804 y FJ(DocXMLRPCServer)p FN(,)e(691)1992 4903 y FJ(dumbdbm)p FN(,)i(382)1992 5003 y FJ(dummy_thread)p FN(,)f(546)1992 5102 y FJ(dummy_threading)p FN(,)f(547)1992 5277 y FE(E)1992 5400 y FJ(email)p FN(,)i(189)p 0 5549 3901 4 v 3762 5649 a FI(965)p eop end %%Page: 966 978 TeXDict begin 966 977 bop 0 83 a FJ(email.charset)p FN(,)18 b(203)0 183 y FJ(email.encoders)p FN(,)g(206)0 282 y FJ(email.errors)p FN(,)g(206)0 382 y FJ(email.generator)p FN(,)g(198)0 482 y FJ(email.header)p FN(,)g(201)0 581 y FJ(email.iterators)p FN(,)g(209)0 681 y FJ(email.message)p FN(,)g(190)0 780 y FJ(email.mime)p FN(,)h(199)0 880 y FJ(email.mime.audio)p FN(,)f(199)0 980 y FJ(email.mime.base)p FN(,)g(199)0 1079 y FJ(email.mime.image)p FN(,)g(199)0 1179 y FJ(email.mime.message)p FN(,)f(199)0 1279 y FJ (email.mime.multipart)p FN(,)g(199)0 1378 y FJ(email.mime.nonmultipart) p FN(,)f(199)0 1478 y FJ(email.mime.text)p FN(,)i(199)0 1577 y FJ(email.parser)p FN(,)g(196)0 1677 y FJ(email.utils)p FN(,)g(207)0 1777 y FJ(encodings.idna)p FN(,)g(89)0 1876 y FJ(encodings.utf-8-sig)p FN(,)f(90)0 1976 y FJ(errno)p FN(,)j(494)0 2076 y FJ(exceptions)p FN(,)f(17)0 2258 y FE(F)0 2381 y FJ(fcntl)p FN(,)h(560)0 2481 y FJ(filecmp)p FN(,)f(333)0 2581 y FJ(fileinput)p FN(,)g(328)0 2680 y FJ(FL)p FN(,)h(923)0 2780 y FJ(fl)p FN(,)g(919)0 2880 y FJ(flp)p FN(,)g(924)0 2979 y FJ(fm)p FN(,)g(924)0 3079 y FJ(fnmatch)p FN(,)f(337)0 3178 y FJ(formatter)p FN(,)g(909)0 3278 y FJ(fpectl)p FN(,)g(852)0 3378 y FJ(fpformat)p FN(,)g(93)0 3477 y FJ(ftplib)p FN(,)g(636)0 3577 y FJ(functools)p FN(,)g(181)0 3768 y FE(G)0 3891 y FJ(gc)p FN(,)h(843)0 3991 y FJ(gdbm)p FN(,)g(377)0 4091 y FJ(getopt)p FN(,)f(448)0 4190 y FJ(getpass)p FN(,)g(472)0 4290 y FJ(gettext)p FN(,)g(739)0 4389 y FJ(GL)p FN(,)h(927)0 4489 y FJ(gl)p FN(,)g(925)0 4589 y FJ(glob)p FN(,)g(336)0 4688 y FJ(gopherlib)p FN(,)f(640)0 4788 y FJ(grp)p FN(,)h(556)0 4888 y FJ(gzip)p FN(,)g(345)0 5070 y FE(H)0 5194 y FJ(hashlib)p FN(,)f(319)0 5293 y FJ(heapq)p FN(,)h(121)0 5393 y FJ(hmac)p FN(,)g(321)1992 83 y FJ(hotshot)p FN(,)f(819)1992 183 y FJ(hotshot.stats)p FN(,)f(820)1992 282 y FJ(htmlentitydefs)p FN(,)f(264)1992 382 y FJ(htmllib)p FN(,)i(262)1992 482 y FJ(HTMLParser)p FN(,)f(257)1992 581 y FJ(httplib)p FN(,)h(632)1992 761 y FE(I)1992 884 y FJ(imageop)p FN(,)g(696)1992 984 y FJ(imaplib)p FN(,)g(642)1992 1083 y FJ(imgfile)p FN(,)g(927)1992 1183 y FJ(imghdr)p FN(,)g(706)1992 1282 y FJ(imp)p FN(,)g(865)1992 1382 y FJ(inspect)p FN(,)g(845)1992 1482 y FJ(itertools)p FN(,)f(172)1992 1661 y FE(J)1992 1784 y FJ(jpeg)p FN(,)h(928)1992 1964 y FE(K)1992 2087 y FJ(keyword)p FN(,)g(883)1992 2267 y FE(L)1992 2390 y FJ(linecache)p FN(,)f(338)1992 2489 y FJ(locale)p FN(,)h(749)1992 2589 y FJ(logging)p FN(,)g(450)1992 2769 y FE(M)1992 2892 y FJ(mailbox)p FN(,)g(218)1992 2991 y FJ(mailcap)p FN(,)g(218)1992 3091 y FJ(marshal)p FN(,)g(374)1992 3191 y FJ(math)p FN(,)g(149)1992 3290 y FJ(md5)p FN(,)g(321)1992 3390 y FJ(mhlib)p FN(,)g(237)1992 3490 y FJ(mimetools)p FN(,)f(239)1992 3589 y FJ(mimetypes)p FN(,)g(241)1992 3689 y FJ(MimeWriter)p FN(,)g(243)1992 3788 y FJ(mimify)p FN(,)h(244)1992 3888 y FJ(mmap)p FN(,)g(547)1992 3988 y FJ(modulefinder)p FN(,)f(870)1992 4087 y FJ(msilib)p FN(,)h(933)1992 4187 y FJ(msvcrt)p FN(,)g(939)1992 4287 y FJ(multifile)p FN(,)f(245)1992 4386 y FJ(mutex)p FN(,)h(132)1992 4566 y FE(N)1992 4689 y FJ(netrc)p FN(,)g(314)1992 4789 y FJ(new)p FN(,)g(143)1992 4888 y FJ(nis)p FN(,)g(568)1992 4988 y FJ(nntplib)p FN(,)g(647)1992 5177 y FE(O)1992 5300 y FJ(operator)p FN(,)g(182)1992 5400 y FJ(optparse)p FN(,)g(420)p 0 5549 3901 4 v 0 5649 a FI(966)3266 b(Module)24 b(Inde)n(x)p eop end %%Page: 967 979 TeXDict begin 967 978 bop 0 83 a FJ(os)p FN(,)20 b(395)0 183 y FJ(os.path)p FN(,)f(325)0 282 y FJ(ossaudiodev)p FN(,)f(707)0 462 y FE(P)0 585 y FJ(parser)p FN(,)h(873)0 685 y FJ(pdb)p FN(,)h(805)0 785 y FJ(pickle)p FN(,)f(359)0 884 y FJ(pickletools)p FN(,)f(896)0 984 y FJ(pipes)p FN(,)i(562)0 1084 y FJ(pkgutil)p FN(,)f(870)0 1183 y FJ(platform)p FN(,)g(492)0 1283 y FJ(popen2)p FN(,)g(590)0 1382 y FJ(poplib)p FN(,)g(640)0 1482 y FJ(posix)p FN(,)h(553)0 1582 y FJ(posixfile)p FN(,)f(563)0 1681 y FJ(pprint)p FN(,)g(144)0 1781 y FJ(profile)p FN(,)g(814)0 1881 y FJ(pstats)p FN(,)g(815)0 1980 y FJ(pty)p FN(,)h(560)0 2080 y FJ(pwd)p FN(,)g(554)0 2179 y FJ(py_compile)p FN(,)f(887)0 2279 y FJ(pyclbr)p FN(,)g(886)0 2379 y FJ(pydoc)p FN(,)h(763)0 2568 y FE(Q)0 2692 y FJ(Queue)p FN(,)g(133)0 2791 y FJ(quopri)p FN(,)f(255)0 2971 y FE(R)0 3094 y FJ(random)p FN(,)g(169)0 3194 y FJ(re)p FN(,)h(52)0 3294 y FJ(readline)p FN(,)f(549)0 3393 y FJ(repr)p FN(,)h(147)0 3493 y FJ(resource)p FN(,)f(565)0 3593 y FJ(rexec)p FN(,)h(860)0 3692 y FJ(rfc822)p FN(,)f(247)0 3792 y FJ(rgbimg)p FN(,)g(705)0 3891 y FJ(rlcompleter)p FN(,)f(551)0 3991 y FJ(robotparser)p FN(,)g(313)0 4091 y FJ(runpy)p FN(,)i(871)0 4280 y FE(S)0 4404 y FJ(sched)p FN(,)g(131)0 4503 y FJ(ScrolledText)p FN(,)e(730)0 4603 y FJ(select)p FN(,)h(535)0 4703 y FJ(sets)p FN(,)h(128)0 4802 y FJ(sgmllib)p FN(,)f(259)0 4902 y FJ(sha)p FN(,)h(322)0 5001 y FJ(shelve)p FN(,)f(371)0 5101 y FJ(shlex)p FN(,)h(759)0 5201 y FJ(shutil)p FN(,)f(338)0 5300 y FJ(signal)p FN(,)g(588)0 5400 y FJ(SimpleHTTPServer)p FN(,)f(670)1992 83 y FJ (SimpleXMLRPCServer)p FN(,)f(688)1992 183 y FJ(site)p FN(,)i(850)1992 282 y FJ(smtpd)p FN(,)g(655)1992 382 y FJ(smtplib)p FN(,)g(651)1992 482 y FJ(sndhdr)p FN(,)g(707)1992 581 y FJ(socket)p FN(,)g(577)1992 681 y FJ(SocketServer)p FN(,)f(664)1992 780 y FJ(spwd)p FN(,)h(555)1992 880 y FJ(sqlite3)p FN(,)g(383)1992 980 y FJ(stat)p FN(,)g(330)1992 1079 y FJ(statvfs)p FN(,)g(332)1992 1179 y FJ(string)p FN(,)g(47)1992 1279 y FJ(StringIO)p FN(,)g(74)1992 1378 y FJ(stringprep)p FN(,)f(91)1992 1478 y FJ(struct)p FN(,)h(62)1992 1577 y FJ(subprocess)p FN(,)f(571)1992 1677 y FJ(sunau)p FN(,)h(699)1992 1777 y FJ(SUNAUDIODEV)p FN(,)f(932)1992 1876 y FJ(sunaudiodev)p FN(,)g(931)1992 1976 y FJ(symbol)p FN(,)h(882)1992 2076 y FJ(sys)p FN(,)g(827)1992 2175 y FJ(syslog)p FN(,)g(568)1992 2358 y FE(T)1992 2481 y FJ(tabnanny)p FN(,)g(885)1992 2581 y FJ(tarfile)p FN(,)g(351)1992 2680 y FJ(telnetlib)p FN(,)f(656)1992 2780 y FJ(tempfile)p FN(,)h(334)1992 2880 y FJ(termios)p FN(,)g(558)1992 2979 y FJ(test)p FN(,)g(801)1992 3079 y FJ(test.test_support)p FN(,)e(803)1992 3178 y FJ(textwrap)p FN(,)i(75)1992 3278 y FJ(thread)p FN(,)g(536)1992 3378 y FJ(threading)p FN(,)f(538)1992 3477 y FJ(time)p FN(,)h(415)1992 3577 y FJ(timeit)p FN(,)g(821)1992 3677 y FJ(Tix)p FN(,)g(725)1992 3776 y FJ(Tkinter)p FN(,)g(713)1992 3876 y FJ(token)p FN(,)g(883)1992 3975 y FJ(tokenize)p FN(,)g(883)1992 4075 y FJ(trace)p FN(,)g(823)1992 4175 y FJ(traceback)p FN(,)f(840)1992 4274 y FJ(tty)p FN(,)h(559)1992 4374 y FJ(turtle)p FN(,)g(730)1992 4474 y FJ(types)p FN(,)g(140)1992 4656 y FE(U)1992 4779 y FJ(unicodedata)p FN(,)f(90)1992 4879 y FJ(unittest)p FN(,)h(789)1992 4979 y FJ(urllib)p FN(,)g(617)1992 5078 y FJ(urllib2)p FN(,)g(622)1992 5178 y FJ(urlparse)p FN(,)g(661)1992 5278 y FJ(user)p FN(,)g(851)1992 5377 y FJ(UserDict)p FN(,)g(138)p 0 5549 3901 4 v 0 5649 a FI(Module)24 b(Inde)n(x)3266 b(967)p eop end %%Page: 968 980 TeXDict begin 968 979 bop 0 83 a FJ(UserList)p FN(,)19 b(139)0 183 y FJ(UserString)p FN(,)g(140)0 282 y FJ(uu)p FN(,)h(256)0 382 y FJ(uuid)p FN(,)g(658)0 565 y FE(W)0 688 y FJ(warnings)p FN(,)f(834)0 787 y FJ(wave)p FN(,)h(702)0 887 y FJ(weakref)p FN(,)f(134)0 987 y FJ(webbrowser)p FN(,)g(599)0 1086 y FJ(whichdb)p FN(,)g(376)0 1186 y FJ(winsound)p FN(,)g(945)0 1286 y FJ(wsgiref)p FN(,)g(610)0 1385 y FJ(wsgiref.handlers)p FN(,)f(614)0 1485 y FJ(wsgiref.headers)p FN(,)g(611)0 1584 y FJ(wsgiref.simple_server)p FN(,)f(612)0 1684 y FJ(wsgiref.util)p FN(,)h(610)0 1784 y FJ(wsgiref.validate)p FN(,)g(614)0 1966 y FE(X)0 2090 y FJ(xdrlib)p FN(,)h(315)0 2189 y FJ(xml.dom)p FN(,)g(272)0 2289 y FJ(xml.dom.minidom)p FN(,)f(282)0 2388 y FJ(xml.dom.pulldom)p FN(,)g(287)0 2488 y FJ(xml.etree.ElementTree)p FN(,)f(298)0 2588 y FJ(xml.parsers.expat)p FN(,)g(264)0 2687 y FJ(xml.sax)p FN(,)i(288)0 2787 y FJ(xml.sax.handler)p FN(,)f(289)0 2887 y FJ(xml.sax.saxutils)p FN(,)g(293)0 2986 y FJ(xml.sax.xmlreader)p FN(,)f(294)0 3086 y FJ(xmlrpclib)p FN(,)i(684)0 3268 y FE(Z)0 3392 y FJ(zipfile)p FN(,)g(348)0 3491 y FJ(zipimport)p FN(,)g(868)0 3591 y FJ(zlib)p FN(,)h(343)p 0 5549 3901 4 v 0 5649 a FI(968)3266 b(Module)24 b(Inde)n(x)p eop end %%Page: 969 981 TeXDict begin 969 980 bop 3269 564 a FT(INDEX)0 1317 y FE(Symbols)0 1440 y FN(.ini)166 1540 y(\002le,)21 b(310)0 1639 y(.pdbrc)166 1739 y(\002le,)g(807)0 1838 y(.p)o(ythonrc.p)o(y)166 1938 y(\002le,)g(851)0 2038 y(\241protocol\277)p 349 2038 25 4 v 27 w(proxy)-5 b(,)18 b(624)0 2137 y FJ(==)166 2237 y FN(operator)m(,)g(24)0 2337 y(\045)j(formatting,)d(32)0 2436 y(\045)j(interpolation,)d(32)0 2536 y FJ(_CData)i FN(\(class)g(in)h(ctypes\),)e(530)0 2635 y FJ(_FuncPtr)g FN(\(class)i(in)f(ctypes\),)g(525)0 2735 y FJ(_SimpleCData)f FN(\(class)h(in)h(ctypes\),)e(530)0 2835 y FJ(__abs__\(\))g FN(\(in)h(module)f(operator\),)f(183)0 2934 y FJ(__add__\(\))166 3034 y FN(AddressList)i(method,)f(250)166 3134 y(in)h(module)f (operator)m(,)f(183)0 3233 y FJ(__and__\(\))h FN(\(in)h(module)f (operator\),)f(183)0 3333 y FJ(__bases__)h FN(\(class)i(attrib)n (ute\),)e(45)0 3432 y FJ(__builtin__)g FN(\(b)n(uilt-in)g(module\),)f FL(834)0 3532 y FJ(__class__)h FN(\(instance)h(attrib)n(ute\),)f(45)0 3632 y FJ(__cmp__\(\))g FN(\(instance)h(method\),)e(24)0 3731 y FJ(__concat__\(\))h FN(\(in)h(module)e(operator\),)g(184)0 3831 y FJ(__contains__\(\))166 3931 y FN(in)i(module)f(operator)m(,)f (184)166 4030 y(Mailbox)h(method,)g(220)166 4130 y(Message)h(method,)f (192)0 4229 y FJ(__copy__\(\))g FN(\(cop)o(y)g(protocol\),)f(144)0 4329 y FJ(__deepcopy__\(\))g FN(\(cop)o(y)h(protocol\),)f(144)0 4429 y FJ(__delitem__\(\))166 4528 y FN(in)i(module)f(operator)m(,)f (185)166 4628 y(Mailbox)h(method,)g(219)166 4728 y(Message)h(method,)f (192)166 4827 y(MH)i(method,)d(224)0 4927 y FJ(__delslice__\(\))g FN(\(in)i(module)f(operator\),)f(185)0 5026 y FJ(__dict__)166 5126 y FN(instance)i(attrib)n(ute,)f(364)166 5226 y(object)h(attrib)n (ute,)f(45)0 5325 y FJ(__displayhook__)f FN(\(data)i(in)g(sys\),)g(828) 1992 1312 y FJ(__div__\(\))f FN(\(in)h(module)e(operator\),)g(183)1992 1411 y FJ(__enter__\(\))g FN(\(conte)o(xt)h(manager)f(method\),)h(42) 1992 1511 y FJ(__eq__\(\))2158 1610 y FN(Charset)h(method,)f(205)2158 1710 y(Header)g(method,)g(203)2158 1810 y(in)h(module)f(operator)m(,)f (183)1992 1909 y FJ(__excepthook__)g FN(\(data)h(in)i(sys\),)f(828)1992 2009 y FJ(__exit__\(\))e FN(\(conte)o(xt)h(manager)g(method\),)f(42) 1992 2109 y FJ(__floordiv__\(\))g FN(\(in)i(module)e(operator\),)g(183) 1992 2208 y FJ(__future__)g FN(\(standard)h(module\),)f FL(842)1992 2308 y FJ(__ge__\(\))h FN(\(in)h(module)f(operator\),)e (183)1992 2407 y FJ(__getinitargs__\(\))g FN(\(cop)o(y)i(protocol\),)f (364)1992 2507 y FJ(__getitem__\(\))2158 2607 y FN(in)i(module)f (operator)m(,)f(185)2158 2706 y(Mailbox)h(method,)f(220)2158 2806 y(Message)i(method,)e(192)1992 2906 y FJ(__getnewargs__\(\))f FN(\(cop)o(y)i(protocol\),)f(364)1992 3005 y FJ(__getslice__\(\))g FN(\(in)i(module)e(operator\),)g(185)1992 3105 y FJ(__getstate__\(\))g FN(\(cop)o(y)h(protocol\),)e(364)1992 3204 y FJ(__gt__\(\))i FN(\(in)h(module)f(operator\),)e(183)1992 3304 y FJ(__iadd__\(\))2158 3404 y FN(AddressList)j(method,)e(250)2158 3503 y(in)i(module)f (operator)m(,)f(185)1992 3603 y FJ(__iand__\(\))g FN(\(in)i(module)f (operator\),)f(185)1992 3703 y FJ(__iconcat__\(\))g FN(\(in)i(module)f (operator\),)e(185)1992 3802 y FJ(__idiv__\(\))h FN(\(in)i(module)f (operator\),)f(185)1992 3902 y FJ(__ifloordiv__\(\))f FN(\(in)j(module)f(operator\),)f(186)1992 4001 y FJ(__ilshift__\(\))g FN(\(in)i(module)f(operator\),)e(186)1992 4101 y FJ(__imod__\(\))h FN(\(in)i(module)f(operator\),)f(186)1992 4201 y FJ(__import__\(\))g FN(\(in)i(module)f(\),)h(3)1992 4300 y FJ(__imul__\(\))e FN(\(in)i(module)f(operator\),)f(186)1992 4400 y FJ(__index__\(\))g FN(\(in)i(module)f(operator\),)f(184)1992 4500 y FJ(__init__\(\))2178 4599 y FN(method,)h(461)2158 4699 y(in)h(module)f(dif)n(\003ib,)g(66) 2158 4798 y(instance)g(constructor)m(,)f(364)2158 4898 y(NullT)m(ranslations)g(method,)h(742)1992 4998 y FJ(__inv__\(\))g FN(\(in)h(module)e(operator\),)g(183)1992 5097 y FJ(__invert__\(\))g FN(\(in)i(module)f(operator\),)f(183)1992 5197 y FJ(__ior__\(\))h FN(\(in)h(module)e(operator\),)g(186)1992 5297 y FJ(__ipow__\(\))g FN(\(in)i(module)f(operator\),)f(186)1992 5396 y FJ(__irepeat__\(\))g FN(\(in)i(module)f(operator\),)e(186)p 0 5549 3901 4 v 3762 5649 a FI(969)p eop end %%Page: 970 982 TeXDict begin 970 981 bop 0 83 a FJ(__irshift__\(\))18 b FN(\(in)i(module)f(operator\),)f(186)0 183 y FJ(__isub__\(\))166 282 y FN(AddressList)i(method,)f(251)166 382 y(in)h(module)f(operator)m (,)f(186)0 482 y FJ(__iter__\(\))166 581 y FN(container)h(method,)f(26) 166 681 y(iterator)i(method,)e(27)166 780 y(Mailbox)h(method,)g(220)0 880 y FJ(__itruediv__\(\))f FN(\(in)i(module)f(operator\),)f(186)0 980 y FJ(__ixor__\(\))h FN(\(in)h(module)f(operator\),)e(186)0 1079 y FJ(__le__\(\))i FN(\(in)h(module)f(operator\),)f(183)0 1179 y FJ(__len__\(\))166 1279 y FN(AddressList)i(method,)f(250)166 1378 y(Mailbox)g(method,)g(220)166 1478 y(Message)h(method,)f(191)0 1577 y FJ(__lshift__\(\))g FN(\(in)h(module)e(operator\),)g(184)0 1677 y FJ(__lt__\(\))h FN(\(in)h(module)f(operator\),)f(183)0 1777 y FJ(__main__)h FN(\(b)n(uilt-in)g(module\),)g FL(834)0 1876 y FJ(__members__)g FN(\(object)g(attrib)n(ute\),)g(45)0 1976 y FJ(__methods__)g FN(\(object)g(attrib)n(ute\),)g(45)0 2076 y FJ(__missing__\(\))f FN(\()j(method\),)d(120)0 2175 y FJ(__mod__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 2275 y FJ(__mul__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 2374 y FJ(__name__)h FN(\(class)i(attrib)n(ute\),)e(45)0 2474 y FJ(__ne__\(\))166 2574 y FN(Header)g(method,)g(203,)g(205)166 2673 y(in)h(module)f(operator)m(,)f(183)0 2773 y FJ(__neg__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 2873 y FJ(__not__\(\))h FN(\(in)h(module)f(operator\),)f(183)0 2972 y FJ(__or__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 3072 y FJ(__pos__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 3171 y FJ(__pow__\(\))h FN(\(in)h(module)f(operator\),)f(184)0 3271 y FJ(__repeat__\(\))h FN(\(in)h(module)e(operator\),)g(185)0 3371 y FJ(__repr__\(\))h FN(\(netrc)g(method\),)f(314)0 3470 y FJ(__rshift__\(\))h FN(\(in)h(module)e(operator\),)g(184)0 3570 y FJ(__setitem__\(\))166 3670 y FN(in)i(module)f(operator)m(,)f(185)166 3769 y(Mailbox)h (method,)g(220)166 3869 y(Maildir)h(method,)e(222)166 3968 y(Message)i(method,)f(192)0 4068 y FJ(__setslice__\(\))f FN(\(in)i(module)f(operator\),)f(185)0 4168 y FJ(__setstate__\(\))g FN(\(cop)o(y)h(protocol\),)f(364)0 4267 y FJ(__stderr__)h FN(\(data)h(in)g(sys\),)g(833)0 4367 y FJ(__stdin__)f FN(\(data)h(in)g(sys\),)g(833)0 4467 y FJ(__stdout__)f FN(\(data)h(in)g(sys\),)g(833)0 4566 y FJ(__str__\(\))166 4666 y FN(AddressList)g(method,)f(250)166 4765 y(Charset)h(method,)f (205)166 4865 y(date)h(method,)f(100)166 4965 y(datetime)h(method,)e (105)166 5064 y(Header)h(method,)g(203)166 5164 y(Message)h(method,)f (190)166 5264 y(time)h(method,)f(107)0 5363 y FJ(__sub__\(\))2158 83 y FN(AddressList)h(method,)e(250)2158 183 y(in)i(module)f(operator)m (,)f(184)1992 282 y FJ(__truediv__\(\))g FN(\(in)i(module)f (operator\),)e(184)1992 382 y FJ(__unicode__\(\))h FN(\(Header)h (method\),)f(203)1992 482 y FJ(__xor__\(\))h FN(\(in)h(module)e (operator\),)g(184)1992 581 y FJ(_anonymous_)g FN(\(Structure)h(attrib) n(ute\),)g(533)1992 681 y FJ(_b_base_)g FN(\()p 2444 681 25 4 v 29 w(CData)i(attrib)n(ute\),)e(530)1992 780 y FJ(_b_needsfree_)f FN(\()p 2693 780 V 29 w(CData)j(attrib)n(ute\),)e (530)1992 880 y FJ(_current_frames\(\))e FN(\(in)j(module)f(sys\),)h (828)1992 980 y FJ(_exit\(\))f FN(\(in)h(module)f(os\),)h(409)1992 1079 y FJ(_fields_)f FN(\(Structure)g(attrib)n(ute\),)g(533)1992 1179 y FJ(_flush\(\))g FN(\(BaseHandler)g(method\),)f(615)1992 1279 y FJ(_getframe\(\))g FN(\(in)i(module)f(sys\),)h(830)1992 1378 y FJ(_handle)f FN(\(PyDLL)g(attrib)n(ute\),)h(524)1992 1478 y FJ(_locale)f FN(\(b)n(uilt-in)g(module\),)f(749)1992 1577 y FJ(_name)h FN(\(PyDLL)h(attrib)n(ute\),)f(524)1992 1677 y FJ(_objects)g FN(\()p 2444 1677 V 29 w(CData)i(attrib)n(ute\),)e (530)1992 1777 y FJ(_pack_)g FN(\(Structure)g(attrib)n(ute\),)g(533) 1992 1876 y FJ(_parse\(\))g FN(\(NullT)m(ranslations)f(method\),)h(742) 1992 1976 y FJ(_setroot\(\))f FN(\(ElementT)m(ree)h(method\),)f(300) 1992 2076 y FJ(_structure\(\))g FN(\(in)i(module)f(email.iterators\),)f (209)1992 2175 y FJ(_urlopener)g FN(\(data)i(in)g(urllib\),)g(618)1992 2275 y FJ(_winreg)f FN(\(e)o(xtension)f(module\),)h FL(941)1992 2374 y FJ(_write\(\))g FN(\(BaseHandler)g(method\),)f(615)1992 2567 y FE(A)1992 2690 y FN(A-LA)-7 b(W)f(,)20 b(699,)f(707)1992 2790 y(a-LA)-7 b(W)f(,)19 b(693)1992 2889 y FJ(a2b_base64\(\))f FN(\(in)i(module)f(binascii\),)g(254)1992 2989 y FJ(a2b_hex\(\))g FN(\(in)h(module)e(binascii\),)i(254)1992 3089 y FJ(a2b_hqx\(\))f FN(\(in)h(module)e(binascii\),)i(254)1992 3188 y FJ(a2b_qp\(\))f FN(\(in)h(module)f(binascii\),)g(254)1992 3288 y FJ(a2b_uu\(\))g FN(\(in)h(module)f(binascii\),)g(253)1992 3387 y FJ(ABDAY_1)48 b(...)99 b(ABDAY_7)20 b FN(\(data)f(in)i(locale\),)e(753)1992 3487 y FJ(ABMON_1)48 b(...)99 b(ABMON_12)19 b FN(\(data)h(in)g (locale\),)g(753)1992 3587 y FJ(abort\(\))2158 3686 y FN(FTP)g(method,)f(638)2158 3786 y(in)h(module)f(os,)h(408)1992 3886 y FJ(above\(\))f FN(\()h(method\),)f(491)1992 3985 y FJ(abs\(\))2158 4085 y FN(Conte)o(xt)g(method,)g(160)2158 4185 y(in)h(module)f(,)h(4)2158 4284 y(in)g(module)f(operator)m(,)f (183)1992 4384 y FJ(abspath\(\))h FN(\(in)h(module)e(os.path\),)h(325) 1992 4483 y FJ(AbstractBasicAuthHandler)11 b FN(\(class)16 b(in)g(urllib2\),)e(624)1992 4583 y FJ(AbstractDigestAuthHandler)41 b FN(\(class)47 b(in)f(urllib2\),)2324 4683 y(624)1992 4782 y FJ(AbstractFormatter)17 b FN(\(class)k(in)f(formatter\),)e(911) 1992 4882 y FJ(AbstractWriter)g FN(\(class)i(in)h(formatter\),)d(912) 1992 4982 y FJ(ac_in_buffer_size)f FN(\(data)j(in)g(asynchat\),)f(595) 1992 5081 y FJ(ac_out_buffer_size)e FN(\(data)j(in)g(asynchat\),)f(596) 1992 5181 y FJ(accept\(\))2158 5280 y FN(dispatcher)g(method,)f(594) 2158 5380 y(sock)o(et)i(method,)e(581)p 0 5549 3901 4 v 0 5649 a FI(970)3561 b(Inde)n(x)p eop end %%Page: 971 983 TeXDict begin 971 982 bop 0 83 a FJ(accept2dyear)19 b FN(\(data)g(in)i(time\),)e(416)0 183 y FJ(access\(\))g FN(\(in)h(module)f(os\),)h(402)0 282 y FJ(acos\(\))166 382 y FN(in)g(module)f(cmath,)h(151)166 482 y(in)g(module)f(math,)h (150)0 581 y FJ(acosh\(\))f FN(\(in)h(module)f(cmath\),)g(151)0 681 y FJ(acquire\(\))187 780 y FN(method,)f(461)166 880 y(Condition)h(method,)g(542)166 980 y(lock)h(method,)e(537)166 1079 y(Semaphore)g(method,)h(543)166 1179 y(T)m(imer)h(method,)e(540,)h (541)0 1279 y FJ(acquire_lock\(\))f FN(\(in)i(module)f(imp\),)g(866)0 1378 y FJ(activate_form\(\))f FN(\(form)h(method\),)f(921)0 1478 y FJ(activeCount\(\))g FN(\(in)i(module)f(threading\),)f(538)0 1577 y FJ(add\(\))166 1677 y FN(Conte)o(xt)h(method,)g(160)166 1777 y(in)h(module)f(audioop,)f(693)166 1876 y(in)i(module)f(operator)m (,)f(183)166 1976 y(Mailbox)h(method,)g(219)166 2076 y(Maildir)h(method,)e(222)166 2175 y(RadioButtonGroup)f(method,)i(938) 166 2275 y(Stats)i(method,)e(815)166 2374 y(T)-7 b(arFile)21 b(method,)d(354)0 2474 y FJ(add_alias\(\))h FN(\(in)h(module)f (email.charset\),)f(206)0 2574 y FJ(add_box\(\))h FN(\(form)g (method\),)f(921)0 2673 y FJ(add_browser\(\))g FN(\(form)h(method\),)f (922)0 2773 y FJ(add_button\(\))h FN(\(form)f(method\),)h(921)0 2873 y FJ(add_cgi_vars\(\))f FN(\(BaseHandler)h(method\),)g(615)0 2972 y FJ(add_charset\(\))f FN(\(in)i(module)f(email.charset\),)g(205)0 3072 y FJ(add_choice\(\))g FN(\(form)f(method\),)h(922)0 3171 y FJ(add_clock\(\))g FN(\(form)f(method\),)h(921)0 3271 y FJ(add_codec\(\))g FN(\(in)h(module)f(email.charset\),)f(206)0 3371 y FJ(add_cookie_header\(\))f FN(\(CookieJar)i(method\),)f(673)0 3470 y FJ(add_counter\(\))g FN(\(form)h(method\),)f(922)0 3570 y FJ(add_data\(\))166 3670 y FN(in)i(module)f(msilib,)h(934)166 3769 y(Request)g(method,)f(625)0 3869 y FJ(add_dial\(\))g FN(\(form)g(method\),)f(921)0 3968 y FJ(add_fallback\(\))g FN(\(NullT)m(ranslations)h(method\),)f(742)0 4068 y FJ(add_file\(\))h FN(\(Directory)f(method\),)h(937)0 4168 y FJ(add_flag\(\))166 4267 y FN(MaildirMessage)g(method,)g(227)166 4367 y(mboxMessage)f (method,)h(229)166 4467 y(MMDFMessage)h(method,)f(233)0 4566 y FJ(add_flowing_data\(\))e FN(\(formatter)i(method\),)f(910)0 4666 y FJ(add_folder\(\))166 4765 y FN(Maildir)i(method,)e(222)166 4865 y(MH)j(method,)d(224)0 4965 y FJ(add_handler\(\))g FN(\(OpenerDirector)g(method\),)g(625)0 5064 y FJ(add_header\(\))166 5164 y FN(Headers)i(method,)e(612)166 5264 y(Message)i(method,)f(192) 166 5363 y(Request)h(method,)f(625)1992 83 y FJ(add_history\(\))f FN(\(in)i(module)f(readline\),)f(550)1992 183 y FJ(add_hor_rule\(\))g FN(\(formatter)g(method\),)g(910)1992 282 y FJ(add_input\(\))g FN(\(form)h(method\),)f(922)1992 382 y FJ(add_label\(\))g FN(\(BabylMessage)h(method\),)g(231)1992 482 y FJ(add_label_data\(\))e FN(\(formatter)i(method\),)f(910)1992 581 y FJ(add_lightbutton\(\))f FN(\(form)i(method\),)f(921)1992 681 y FJ(add_line_break\(\))f FN(\(formatter)i(method\),)f(909)1992 780 y FJ(add_literal_data\(\))f FN(\(formatter)h(method\),)g(910)1992 880 y FJ(add_menu\(\))g FN(\(form)h(method\),)f(922)1992 980 y FJ(add_parent\(\))g FN(\(BaseHandler)h(method\),)f(626)1992 1079 y FJ(add_password\(\))g FN(\(HTTPP)o(assw)o(ordMgr)g(method\),)g(628)1992 1179 y FJ(add_positioner\(\))f FN(\(form)i(method\),)f(921)1992 1279 y FJ(add_roundbutton\(\))f FN(\(form)i(method\),)f(921)1992 1378 y FJ(add_section\(\))g FN(\(SafeCon\002gP)o(arser)g(method\),)g (311)1992 1478 y FJ(add_sequence\(\))g FN(\(MHMessage)h(method\),)g (230)1992 1577 y FJ(add_slider\(\))f FN(\(form)h(method\),)f(921)1992 1677 y FJ(add_stream\(\))g FN(\(in)i(module)f(msilib\),)h(934)1992 1777 y FJ(add_tables\(\))e FN(\(in)i(module)f(msilib\),)h(934)1992 1876 y FJ(add_text\(\))e FN(\(form)h(method\),)f(921)1992 1976 y FJ(add_timer\(\))g FN(\(form)h(method\),)f(922)1992 2076 y FJ(add_type\(\))g FN(\(in)i(module)f(mimetypes\),)g(241)1992 2175 y FJ(add_unredirected_header\(\))30 b FN(\(Request)35 b(method\),)2324 2275 y(625)1992 2374 y FJ(add_valslider\(\))17 b FN(\(form)i(method\),)f(921)1992 2474 y FJ(addcallback\(\))g FN(\(CD)j(parser)e(method\),)f(918)1992 2574 y FJ(addch\(\))h FN(\(windo)n(w)g(method\),)f(478)1992 2673 y FJ(addError\(\))g FN(\(T)-6 b(estResult)21 b(method\),)d(799)1992 2773 y FJ(addFailure\(\))g FN(\(T)-6 b(estResult)21 b(method\),)d(799)1992 2873 y FJ(addfile\(\))h FN(\(T)-7 b(arFile)20 b(method\),)e(354)1992 2972 y FJ(addFilter\(\))g FN(\()j(method\),)d(455,)h(461)1992 3072 y FJ(addHandler\(\))f FN(\()i(method\),)f(455)1992 3171 y FJ(addheader\(\))f FN(\(MimeWriter)i(method\),)e(243)1992 3271 y FJ(addinfo\(\))h FN(\(Pro\002le)g(method\),)g(819)1992 3371 y FJ(addLevelName\(\))f FN(\(in)i(module)e(logging\),)g(453)1992 3470 y FJ(addnstr\(\))h FN(\(windo)n(w)f(method\),)h(478)1992 3570 y FJ(AddPackagePath\(\))e FN(\(in)j(module)f(module\002nder\),)e (870)1992 3670 y FJ(address_family)h FN(\(data)h(in)i(Sock)o(etServ)o (er\),)c(666)1992 3769 y FJ(address_string\(\))177 b FN(\(BaseHTTPRequestHandler)2324 3869 y(method\),)18 b(670)1992 3968 y FJ(AddressList)g FN(\(class)j(in)f(rfc822\),)e(248) 1992 4068 y FJ(addresslist)g FN(\(AddressList)i(attrib)n(ute\),)f(251) 1992 4168 y FJ(addressof\(\))f FN(\(in)i(module)f(ctypes\),)g(528)1992 4267 y FJ(addstr\(\))g FN(\(windo)n(w)g(method\),)f(478)1992 4367 y FJ(addSuccess\(\))g FN(\(T)-6 b(estResult)21 b(method\),)d(800) 1992 4467 y FJ(addTest\(\))h FN(\(T)-6 b(estSuite)20 b(method\),)e(798)1992 4566 y FJ(addTests\(\))g FN(\(T)-6 b(estSuite)21 b(method\),)d(798)1992 4666 y FJ(adjusted\(\))g FN(\(Decimal)i(method\),)e(157)1992 4765 y FJ(adler32\(\))h FN(\(in)h(module)e(zlib\),)i(343)1992 4865 y(ADPCM,)g(Intel/D)m(VI,)f (693)1992 4965 y FJ(adpcm2lin\(\))f FN(\(in)i(module)f(audioop\),)f (693)1992 5064 y(AES)2158 5164 y(algorithm,)g(319)1992 5264 y FJ(AF_INET)h FN(\(data)h(in)g(sock)o(et\),)f(578)1992 5363 y FJ(AF_INET6)g FN(\(data)g(in)i(sock)o(et\),)e(578)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(971)p eop end %%Page: 972 984 TeXDict begin 972 983 bop 0 83 a FJ(AF_UNIX)19 b FN(\(data)h(in)h(sock) o(et\),)e(578)0 183 y FJ(AI_)150 198 y(*)220 183 y FN(\(data)h(in)g (sock)o(et\),)g(578)0 282 y FJ(aifc\(\))g FN(\(aifc)f(method\),)g(698)0 382 y FJ(aifc)h FN(\(standard)f(module\),)f FL(697)0 482 y FN(AIFF)-7 b(,)21 b(697,)e(704)0 581 y FJ(aiff\(\))h FN(\(aifc)f(method\),)g(698)0 681 y(AIFF-C,)h(697,)f(704)0 780 y FJ(AL)h FN(\(standard)f(module\),)f(913,)h FL(915)0 880 y FJ(al)h FN(\(b)n(uilt-in)g(module\),)e FL(913)0 980 y FJ(alarm\(\))h FN(\(in)h(module)f(signal\),)h(589)0 1079 y FJ(alaw2lin\(\))f FN(\(in)h(module)f(audioop\),)e(693)0 1179 y(algorithm)166 1279 y(AES,)j(319)0 1378 y FJ(alignment\(\))f FN(\(in)h(module)f(ctypes\),)g(528)0 1478 y FJ(all\(\))h FN(\(in)g(module)f(\),)h(4)0 1577 y FJ(all_errors)f FN(\(data)h(in)g (ftplib\),)f(637)0 1677 y FJ(all_features)g FN(\(data)g(in)i (xml.sax.handler\),)16 b(290)0 1777 y FJ(all_properties)i FN(\(data)i(in)g(xml.sax.handler\),)d(291)0 1876 y FJ (allocate_lock\(\))h FN(\(in)i(module)f(thread\),)f(537)0 1976 y FJ(allow_reuse_address)f FN(\(data)j(in)g(Sock)o(etServ)o(er\),) e(666)0 2076 y FJ(allowed_domains\(\))e FN(\(Def)o(aultCookiePolic)o(y) f(method\),)332 2175 y(677)0 2275 y FJ(allowremoval\(\))j FN(\(CD)j(player)e(method\),)f(917)0 2374 y FJ(alt\(\))i FN(\(in)g(module)f(curses.ascii\),)g(490)0 2474 y FJ(ALT_DIGITS)g FN(\(data)h(in)g(locale\),)f(753)0 2574 y FJ(altsep)h FN(\(data)f(in)i(os\),)f(414)0 2673 y FJ(altzone)f FN(\(data)h(in)h (time\),)e(416)0 2773 y FJ(anchor_bgn\(\))g FN(\(HTMLP)o(arser)f (method\),)h(263)0 2873 y FJ(anchor_end\(\))g FN(\(HTMLP)o(arser)f (method\),)h(263)0 2972 y FJ(and)166 3072 y FN(operator)m(,)f(23,)h(24) 0 3171 y FJ(and_\(\))h FN(\(in)g(module)e(operator\),)g(183)0 3271 y FJ(annotate\(\))h FN(\(in)h(module)f(dircache\),)f(340)0 3371 y FJ(any\(\))i FN(\(in)g(module)f(\),)h(4)0 3470 y FJ(anydbm)g FN(\(standard)e(module\),)h FL(375)0 3570 y FJ(api_version)g FN(\(data)g(in)i(sys\),)f(833)0 3670 y FJ(apop\(\))g FN(\(POP3)p 547 3670 25 4 v 29 w(SSL)h(method\),)d(641) 0 3769 y FJ(append\(\))187 3869 y FN(method,)g(117)166 3968 y(array)h(method,)g(126)166 4068 y(CAB)i(method,)e(937)166 4168 y(Header)g(method,)g(202)166 4267 y(IMAP4)p 421 4267 V 29 w(stream)h(method,)f(643)166 4367 y(list)i(method,)e(35)166 4467 y(T)-6 b(emplate)20 b(method,)e(563)0 4566 y FJ(appendChild\(\))g FN(\(Node)i(method\),)e(276)0 4666 y FJ(appendleft\(\))h FN(\()h(method\),)e(117)0 4765 y FJ(application_uri\(\))g FN(\(in)i(module)e(wsgiref.util\),)h(610)0 4865 y FJ(apply\(\))g FN(\(in)h(module)f(\),)h(17)0 4965 y FJ(architecture\(\))e FN(\(in)i(module)f(platform\),)f(492)0 5064 y FJ(aRepr)i FN(\(data)g(in)g(repr\),)f(147)0 5164 y FJ(args)h FN(\(tuple)f(attrib)n (ute\),)h(182)0 5264 y FJ(argtypes)f FN(\()p 452 5264 V 30 w(FuncPtr)g(attrib)n(ute\),)h(525)0 5363 y FJ(ArgumentError\(\))e FN(\(e)o(xception)g(in)i(ctypes\),)g(525)1992 83 y FJ(argv)g FN(\(data)f(in)i(sys\),)f(827)1992 183 y(arithmetic,)f(25)1992 282 y FJ(ArithmeticError)e FN(\(e)o(xception)h(in)j(e)o(xceptions\),)d (18)1992 382 y FJ(array\(\))h FN(\(in)h(module)f(array\),)f(125)1992 482 y FJ(array)h FN(\(b)n(uilt-in)h(module\),)e FL(125)1992 581 y FN(arrays,)h(125)1992 681 y FJ(ArrayType)g FN(\(data)g(in)i (array\),)d(125)1992 780 y FJ(article\(\))h FN(\(NNTP)h(method\),)e (650)1992 880 y FJ(AS_IS)h FN(\(data)h(in)g(formatter\),)e(909)1992 980 y FJ(as_string\(\))g FN(\(Message)i(method\),)e(190)1992 1079 y FJ(as_tuple\(\))g FN(\(Decimal)i(method\),)e(157)1992 1179 y FJ(ascii\(\))h FN(\(in)h(module)f(curses.ascii\),)g(490)1992 1279 y FJ(ascii_letters)f FN(\(data)i(in)g(string\),)f(47)1992 1378 y FJ(ascii_lowercase)e FN(\(data)j(in)h(string\),)e(47)1992 1478 y FJ(ascii_uppercase)e FN(\(data)j(in)h(string\),)e(47)1992 1577 y FJ(asctime\(\))g FN(\(in)h(module)e(time\),)i(416)1992 1677 y FJ(asin\(\))2158 1777 y FN(in)g(module)f(cmath,)g(152)2158 1876 y(in)h(module)f(math,)g(150)1992 1976 y FJ(asinh\(\))g FN(\(in)h(module)f(cmath\),)g(152)1992 2076 y FJ(assert)2158 2175 y FN(statement,)g(18)1992 2275 y FJ(assert_\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 2374 y FJ(assert_line_data\(\))f FN(\(formatter)h(method\),)g(911)1992 2474 y FJ(assertAlmostEqual\(\))f FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 2574 y FJ(assertEqual\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 2673 y FJ(AssertionError)g FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e(18)1992 2773 y FJ(assertNotAlmostEqual\(\))e FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 2873 y FJ(assertNotEqual\(\))f FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 2972 y FJ(assertRaises\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 3072 y(assignment)2158 3171 y(e)o(xtended)g(slice,)i(35)2158 3271 y(slice,)g(35)2158 3371 y(subscript,)f(35)1992 3470 y FJ(ast2list\(\))f FN(\(in)i(module)f(parser\),)g(875)1992 3570 y FJ(ast2tuple\(\))f FN(\(in)i(module)f(parser\),)g(875)1992 3670 y FJ(astimezone\(\))f FN(\(datetime)h(method\),)g(104)1992 3769 y FJ(ASTType)g FN(\(data)h(in)g(parser\),)f(876)1992 3869 y FJ(ASTVisitor)f FN(\(class)j(in)g(compiler)-5 b(.visitor\),)17 b(903)1992 3968 y FJ(async_chat)h FN(\(class)j(in)g (asynchat\),)d(595)1992 4068 y FJ(asynchat)h FN(\(standard)f(module\),) h FL(595)1992 4168 y FJ(asyncore)g FN(\(b)n(uilt-in)g(module\),)f FL(592)1992 4267 y FJ(atan\(\))2158 4367 y FN(in)i(module)f(cmath,)g (152)2158 4467 y(in)h(module)f(math,)g(150)1992 4566 y FJ(atan2\(\))g FN(\(in)h(module)f(math\),)g(150)1992 4666 y FJ(atanh\(\))g FN(\(in)h(module)f(cmath\),)g(152)1992 4765 y FJ(atexit)g FN(\(standard)g(module\),)f FL(839)1992 4865 y FJ(atime)h FN(\(data)h(in)g(cd\),)g(916)1992 4965 y FJ(atof\(\))2158 5064 y FN(in)g(module)f(locale,)g(752)2158 5164 y(in)h(module)f(string,)g(50)1992 5264 y FJ(atoi\(\))2158 5363 y FN(in)h(module)f(locale,)g(752)p 0 5549 3901 4 v 0 5649 a FI(972)3561 b(Inde)n(x)p eop end %%Page: 973 985 TeXDict begin 973 984 bop 166 83 a FN(in)20 b(module)f(string,)h(50)0 183 y FJ(atol\(\))g FN(\(in)g(module)e(string\),)i(50)0 282 y FJ(attach\(\))f FN(\(Message)h(method\),)e(191)0 382 y FJ(AttlistDeclHandler\(\))f FN(\(xmlparser)h(method\),)h(267)0 482 y FJ(attrgetter\(\))g FN(\(in)h(module)e(operator\),)g(187)0 581 y FJ(AttributeError)g FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e (18)0 681 y FJ(attributes)h FN(\(Node)g(attrib)n(ute\),)g(275)0 780 y FJ(AttributesImpl)f FN(\(class)j(in)f(xml.sax.xmlreader\),)c(295) 0 880 y FJ(AttributesNSImpl)e FN(\(class)i(in)g(xml.sax.xmlreader\),)d (295)0 980 y FJ(attroff\(\))19 b FN(\(windo)n(w)g(method\),)f(478)0 1079 y FJ(attron\(\))h FN(\(windo)n(w)g(method\),)f(478)0 1179 y FJ(attrset\(\))h FN(\(windo)n(w)g(method\),)f(478)0 1279 y FJ(audio)i FN(\(data)g(in)g(cd\),)f(916)0 1378 y(Audio)g(Interchange)f(File)j(F)o(ormat,)e(697,)g(704)0 1478 y FJ(AUDIO_FILE_ENCODING_ADPCM_G721)86 b FN(\(data)91 b(in)332 1577 y(sunau\),)19 b(700)0 1677 y FJ (AUDIO_FILE_ENCODING_ADPCM_G722)86 b FN(\(data)91 b(in)332 1777 y(sunau\),)19 b(700)0 1876 y FJ(AUDIO_FILE_ENCODING_ADPCM_G723_3) 36 b FN(\(data)41 b(in)332 1976 y(sunau\),)19 b(700)0 2076 y FJ(AUDIO_FILE_ENCODING_ADPCM_G723_5)36 b FN(\(data)41 b(in)332 2175 y(sunau\),)19 b(700)0 2275 y FJ (AUDIO_FILE_ENCODING_ALAW_8)42 b FN(\(data)k(in)g(sunau\),)332 2374 y(700)0 2474 y FJ(AUDIO_FILE_ENCODING_DOUBLE)c FN(\(data)k(in)g (sunau\),)332 2574 y(700)0 2673 y FJ(AUDIO_FILE_ENCODING_FLOAT)12 b FN(\(data)j(in)h(sunau\),)f(700)0 2773 y FJ (AUDIO_FILE_ENCODING_LINEAR_16)111 b FN(\(data)116 b(in)332 2873 y(sunau\),)19 b(700)0 2972 y FJ(AUDIO_FILE_ENCODING_LINEAR_24)111 b FN(\(data)116 b(in)332 3072 y(sunau\),)19 b(700)0 3171 y FJ(AUDIO_FILE_ENCODING_LINEAR_32)111 b FN(\(data)116 b(in)332 3271 y(sunau\),)19 b(700)0 3371 y FJ (AUDIO_FILE_ENCODING_LINEAR_8)136 b FN(\(data)141 b(in)332 3470 y(sunau\),)19 b(700)0 3570 y FJ(AUDIO_FILE_ENCODING_MULAW_8)25 b FN(\(data)30 b(in)f(sunau\),)332 3670 y(700)0 3769 y FJ(AUDIO_FILE_MAGIC)18 b FN(\(data)h(in)i(sunau\),)e(700)0 3869 y(A)-5 b(UDIODEV)-11 b(,)20 b(708)0 3968 y FJ(audioop)f FN(\(b)n(uilt-in)h(module\),)e FL(693)0 4068 y FJ(authenticate\(\))g FN(\(IMAP4)p 1001 4068 25 4 v 29 w(stream)i(method\),)e(643)0 4168 y FJ(authenticators\(\))g FN(\(netrc)h(method\),)f(314)0 4267 y FJ(avg\(\))i FN(\(in)g(module)f(audioop\),)e(694)0 4367 y FJ(avgpp\(\))i FN(\(in)h(module)f(audioop\),)f(694)0 4563 y FE(B)0 4686 y FJ(b16decode\(\))h FN(\(in)h(module)f(base64\),)f (252)0 4786 y FJ(b16encode\(\))h FN(\(in)h(module)f(base64\),)f(252)0 4885 y FJ(b2a_base64\(\))h FN(\(in)h(module)e(binascii\),)i(254)0 4985 y FJ(b2a_hex\(\))f FN(\(in)h(module)f(binascii\),)g(254)0 5084 y FJ(b2a_hqx\(\))g FN(\(in)h(module)f(binascii\),)g(254)0 5184 y FJ(b2a_qp\(\))g FN(\(in)h(module)f(binascii\),)h(254)0 5284 y FJ(b2a_uu\(\))f FN(\(in)h(module)f(binascii\),)h(253)0 5383 y FJ(b32decode\(\))f FN(\(in)h(module)f(base64\),)f(251)1992 83 y FJ(b32encode\(\))g FN(\(in)i(module)f(base64\),)g(251)1992 183 y FJ(b64decode\(\))f FN(\(in)i(module)f(base64\),)g(251)1992 282 y FJ(b64encode\(\))f FN(\(in)i(module)f(base64\),)g(251)1992 382 y FJ(Babyl)g FN(\(class)i(in)f(mailbox\),)f(225)1992 482 y FJ(BabylMailbox)f FN(\(class)j(in)f(mailbox\),)e(235)1992 581 y FJ(BabylMessage)g FN(\(class)j(in)f(mailbox\),)e(231)1992 681 y FJ(backslashreplace_errors_errors\(\))f FN(\(in)23 b(mod-)2324 780 y(ule)d(codecs\),)f(79)1992 880 y FJ(backward\(\))f FN(\(in)i(module)f(turtle\),)h(731)1992 980 y FJ(backward_compatible)d FN(\(data)i(in)i(imageop\),)d(697)1992 1079 y FJ(BadStatusLine)g FN(\(e)o(xception)g(in)i(httplib\),)f(633)1992 1179 y FJ(Balloon)g FN(\(class)i(in)f(T)m(ix\),)g(726)1992 1279 y(base64)2158 1378 y(encoding,)d(251)1992 1478 y FJ(base64)i FN(\(standard)g(module\),)f FL(251)p FN(,)h(253)1992 1577 y FJ(BaseCGIHandler)f FN(\(class)i(in)h(wsgiref.handlers\),)c(614) 1992 1677 y FJ(BaseCookie)h FN(\(class)j(in)g(Cookie\),)e(680)1992 1777 y FJ(BaseException)f FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e (18)1992 1876 y FJ(BaseHandler)2158 1976 y FN(class)j(in)f(urllib2,)f (623)2158 2076 y(class)i(in)f(wsgiref.handlers,)e(615)1992 2175 y FJ(BaseHTTPRequestHandler)119 b FN(\(class)k(in)g(Base-)2324 2275 y(HTTPServ)o(er\),)18 b(668)1992 2374 y FJ(BaseHTTPServer)g FN(\(standard)g(module\),)h FL(667)1992 2474 y FJ(basename\(\))f FN(\(in)i(module)f(os.path\),)g(325)1992 2574 y FJ(BaseResult)f FN(\(class)j(in)g(urlparse\),)d(664)1992 2673 y FJ(basestring\(\))g FN(\(in)i(module)f(\),)h(4)1992 2773 y FJ(basicConfig\(\))e FN(\(in)i(module)f(logging\),)f(453)1992 2873 y FJ(BasicContext)g FN(\(class)j(in)f(decimal\),)f(159)1992 2972 y FJ(Bastion\(\))g FN(\(in)h(module)e(Bastion\),)i(863)1992 3072 y FJ(Bastion)f FN(\(standard)g(module\),)f FL(863)1992 3171 y FJ(BastionClass)g FN(\(class)j(in)f(Bastion\),)g(863)1992 3271 y FJ(baudrate\(\))e FN(\(in)i(module)f(curses\),)h(473)1992 3371 y FJ(bdb)g FN(\(standard)e(module\),)h(805)1992 3470 y FJ(Beep\(\))g FN(\(in)h(module)f(winsound\),)f(945)1992 3570 y FJ(beep\(\))h FN(\(in)h(module)f(curses\),)h(473)1992 3670 y FJ(begin_fill\(\))e FN(\(in)i(module)f(turtle\),)g(731)1992 3769 y FJ(below\(\))g FN(\()h(method\),)f(491)1992 3869 y(Benchmarking,)e(821)1992 3968 y(benchmarking,)f(417)1992 4068 y FJ(bestreadsize\(\))i FN(\(CD)i(player)g(method\),)e(917)1992 4168 y FJ(betavariate\(\))g FN(\(in)i(module)f(random\),)e(171)1992 4267 y FJ(bgn_group\(\))h FN(\(form)h(method\),)f(921)1992 4367 y FJ(bias\(\))h FN(\(in)h(module)f(audioop\),)f(694)1992 4467 y FJ(bidirectional\(\))f FN(\(in)j(module)f(unicodedata\),)f(90)1992 4566 y FJ (BigEndianStructure)f FN(\(class)k(in)f(ctypes\),)f(533)1992 4666 y FJ(Binary)g FN(\(class)i(in)f(msilib\),)g(934)1992 4765 y(binary)2158 4865 y(data,)f(packing,)g(62)1992 4965 y(binary)f(semaphores,)h(536)1992 5064 y FJ(binascii)g FN(\(b)n(uilt-in)g(module\),)f FL(253)1992 5164 y FJ(bind\(\))2158 5264 y FN(dispatcher)h(method,)f(594)2158 5363 y(sock)o(et)i(method,)e (581)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(973)p eop end %%Page: 974 986 TeXDict begin 974 985 bop 0 83 a FN(bind)19 b(\(widgets\),)g(723)0 183 y FJ(bind_textdomain_codeset\(\))12 b FN(\(in)j(module)f(gette)o (xt\),)332 282 y(739)0 382 y FJ(bindtextdomain\(\))k FN(\(in)i(module)f(gette)o(xt\),)f(739)0 482 y FJ(binhex\(\))h FN(\(in)h(module)f(binhe)o(x\),)f(253)0 581 y FJ(binhex)i FN(\(standard)e(module\),)h(253,)g FL(253)0 681 y FJ(bisect\(\))g FN(\(in)h(module)f(bisect\),)h(124)0 780 y FJ(bisect)g FN(\(standard)e(module\),)h FL(124)0 880 y FJ(bisect_left\(\))f FN(\(in)i(module)f(bisect\),)h(124)0 980 y FJ(bisect_right\(\))e FN(\(in)i(module)f(bisect\),)h(124)0 1079 y(bit-string)166 1179 y(operations,)e(26)0 1279 y FJ(bitmap\(\))h FN(\(Dialog)h (method\),)e(938)0 1378 y FJ(bkgd\(\))i FN(\(windo)n(w)e(method\),)h (478)0 1478 y FJ(bkgdset\(\))g FN(\(windo)n(w)g(method\),)f(478)0 1577 y FJ(block_size)h FN(\(data)h(in)g(hashlib\),)f(320)0 1677 y FJ(blocked_domains\(\))d FN(\(Def)o(aultCookiePolic)o(y)f (method\),)332 1777 y(677)0 1876 y FJ(BLOCKSIZE)k FN(\(data)h(in)g (cd\),)g(916)0 1976 y FJ(blocksize)f FN(\(data)h(in)g(sha\),)g(322)0 2076 y FJ(body\(\))g FN(\(NNTP)g(method\),)e(650)0 2175 y FJ(body_encode\(\))g FN(\(Charset)i(method\),)f(205)0 2275 y FJ(body_encoding)f FN(\(data)i(in)g(email.charset\),)f(204)0 2374 y FJ(body_line_iterator\(\))282 b FN(\(in)i(module)332 2474 y(email.iterators\),)19 b(209)0 2574 y FJ(BOM)h FN(\(data)g(in)g(codecs\),)f(80)0 2673 y FJ(BOM_BE)h FN(\(data)f(in)i(codecs\),)e(80)0 2773 y FJ(BOM_LE)h FN(\(data)f(in)i(codecs\),)e(80)0 2873 y FJ(BOM_UTF16)g FN(\(data)h(in)g(codecs\),)f(80)0 2972 y FJ(BOM_UTF16_BE)g FN(\(data)g(in)i(codecs\),)e(80)0 3072 y FJ(BOM_UTF16_LE)g FN(\(data)g(in)i(codecs\),)e(80)0 3171 y FJ(BOM_UTF32)g FN(\(data)h(in)g(codecs\),)f(80)0 3271 y FJ(BOM_UTF32_BE)g FN(\(data)g(in)i(codecs\),)e(80)0 3371 y FJ(BOM_UTF32_LE)g FN(\(data)g(in)i(codecs\),)e(80)0 3470 y FJ(BOM_UTF8)g FN(\(data)h(in)g(codecs\),)f(80)0 3570 y FJ(bool\(\))h FN(\(in)g(module)e(\),)j(4)0 3670 y(Boolean)166 3769 y(object,)e(25)166 3869 y(operations,)f(23)166 3968 y(type,)i(4)166 4068 y(v)n(alues,)g(44)0 4168 y FJ(boolean\(\))f FN(\(in)h(module)f (xmlrpclib\),)f(687)0 4267 y FJ(BooleanType)h FN(\(data)g(in)i (types\),)e(141)0 4367 y FJ(border\(\))g FN(\(windo)n(w)g(method\),)f (479)0 4467 y FJ(bottom\(\))h FN(\()i(method\),)d(491)0 4566 y FJ(bottom_panel\(\))g FN(\(in)i(module)f(curses.panel\),)f(491)0 4666 y FJ(BoundaryError)g FN(\(e)o(xception)g(in)j(email.errors\),)d (207)0 4765 y FJ(BoundedSemaphore\(\))f FN(\(in)j(module)f (threading\),)f(539)0 4865 y FJ(box\(\))i FN(\(windo)n(w)f(method\),)f (479)0 4965 y FJ(break_long_words)g FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(77)0 5064 y(BR)m(O)m(WSER,)j(600)0 5164 y FJ(bsddb)166 5264 y FN(b)n(uilt-in)e(module,)e(372,)h(375,)g (378)166 5363 y(e)o(xtension)g(module,)f FL(379)1992 83 y FJ(BsdDbShelf)g FN(\(class)j(in)g(shelv)o(e\),)e(372)1992 183 y FJ(btopen\(\))g FN(\(in)h(module)f(bsddb\),)f(380)1992 282 y(b)n(uf)n(fer)2158 382 y(object,)h(27)1992 482 y FJ(buffer\(\))2158 581 y FN(b)n(uilt-in)g(function,)f(27,)i(142)2158 681 y(in)g(module)f(,)h(17)1992 780 y(b)n(uf)n(fer)e(size,)j(I/O,)f(10) 1992 880 y FJ(buffer_info\(\))e FN(\(array)h(method\),)f(126)1992 980 y FJ(buffer_size)g FN(\(xmlparser)h(attrib)n(ute\),)g(266)1992 1079 y FJ(buffer_text)f FN(\(xmlparser)h(attrib)n(ute\),)g(266)1992 1179 y FJ(buffer_used)f FN(\(xmlparser)h(attrib)n(ute\),)g(266)1992 1279 y FJ(BufferingHandler)e FN(\(class)k(in)f(logging\),)e(466)1992 1378 y FJ(BufferType)g FN(\(data)i(in)g(types\),)g(142)1992 1478 y FJ(bufsize\(\))f FN(\(audio)f(de)n(vice)i(method\),)e(710)1992 1577 y FJ(build_opener\(\))g FN(\(in)i(module)e(urllib2\),)h(623)1992 1677 y(b)n(uilt-in)2158 1777 y(constants,)g(3)2158 1876 y(e)o(xceptions,)f(3)2158 1976 y(functions,)g(3)2158 2076 y(types,)h(3,)h(23)1992 2175 y FJ(builtin_module_names)d FN(\(data)i(in)i(sys\),)f(827)1992 2275 y FJ(BuiltinFunctionType)d FN(\(data)i(in)i(types\),)e(142)1992 2374 y FJ(BuiltinMethodType)e FN(\(data)j(in)g(types\),)g(142)1992 2474 y FJ(ButtonBox)f FN(\(class)h(in)h(T)m(ix\),)e(726)1992 2574 y FJ(byref\(\))g FN(\(in)h(module)f(ctypes\),)g(528)1992 2673 y(byte-code)2158 2773 y(\002le,)h(865,)f(867,)g(887)1992 2873 y FJ(byteorder)g FN(\(data)g(in)i(sys\),)f(827)1992 2972 y FJ(bytes)f FN(\(UUID)h(attrib)n(ute\),)f(659)1992 3072 y FJ(bytes_le)g FN(\(UUID)h(attrib)n(ute\),)f(659)1992 3171 y FJ(byteswap\(\))f FN(\(array)h(method\),)g(126)1992 3271 y FJ(bz2)h FN(\(b)n(uilt-in)f (module\),)f FL(346)1992 3371 y FJ(BZ2Compressor)g FN(\(class)j(in)f (bz2\),)f(347)1992 3470 y FJ(BZ2Decompressor)e FN(\(class)k(in)g (bz2\),)e(347)1992 3570 y FJ(BZ2File)g FN(\(class)i(in)f(bz2\),)f(346) 1992 3764 y FE(C)1992 3887 y FN(C)2158 3987 y(language,)f(25)2158 4087 y(structures,)h(62)1992 4186 y FJ(C_BUILTIN)g FN(\(data)g(in)i (imp\),)e(866)1992 4286 y FJ(c_byte)g FN(\(class)i(in)f(ctypes\),)g (531)1992 4385 y FJ(c_char)f FN(\(class)i(in)f(ctypes\),)g(531)1992 4485 y FJ(c_char_p)f FN(\(class)i(in)f(ctypes\),)f(531)1992 4585 y FJ(c_double)g FN(\(class)i(in)f(ctypes\),)f(531)1992 4684 y FJ(C_EXTENSION)f FN(\(data)i(in)g(imp\),)g(866)1992 4784 y FJ(c_float)f FN(\(class)i(in)f(ctypes\),)f(531)1992 4884 y FJ(c_int)g FN(\(class)i(in)f(ctypes\),)g(531)1992 4983 y FJ(c_int16)f FN(\(class)i(in)f(ctypes\),)f(531)1992 5083 y FJ(c_int32)g FN(\(class)i(in)f(ctypes\),)f(531)1992 5183 y FJ(c_int64)g FN(\(class)i(in)f(ctypes\),)f(531)1992 5282 y FJ(c_int8)g FN(\(class)i(in)f(ctypes\),)g(531)1992 5382 y FJ(c_long)f FN(\(class)i(in)f(ctypes\),)g(531)p 0 5549 3901 4 v 0 5649 a FI(974)3561 b(Inde)n(x)p eop end %%Page: 975 987 TeXDict begin 975 986 bop 0 83 a FJ(c_longlong)19 b FN(\(class)i(in)f (ctypes\),)f(531)0 183 y FJ(c_short)g FN(\(class)i(in)g(ctypes\),)e (531)0 282 y FJ(c_size_t)g FN(\(class)i(in)f(ctypes\),)g(532)0 382 y FJ(c_ubyte)f FN(\(class)i(in)g(ctypes\),)e(532)0 482 y FJ(c_uint)h FN(\(class)g(in)h(ctypes\),)e(532)0 581 y FJ(c_uint16)g FN(\(class)i(in)f(ctypes\),)g(532)0 681 y FJ(c_uint32)f FN(\(class)i(in)f(ctypes\),)g(532)0 780 y FJ(c_uint64)f FN(\(class)i(in)f(ctypes\),)g(532)0 880 y FJ(c_uint8)f FN(\(class)i(in)g(ctypes\),)e(532)0 980 y FJ(c_ulong)g FN(\(class)i(in)g(ctypes\),)e(532)0 1079 y FJ(c_ulonglong)g FN(\(class)h(in)h(ctypes\),)e(532)0 1179 y FJ(c_ushort)g FN(\(class)i(in)f(ctypes\),)g(532)0 1279 y FJ(c_void_p)f FN(\(class)i(in)f(ctypes\),)g(532)0 1378 y FJ(c_wchar)f FN(\(class)i(in)g(ctypes\),)e(532)0 1478 y FJ(c_wchar_p)g FN(\(class)i(in)f(ctypes\),)f(532)0 1577 y FJ(CAB)h FN(\(class)h(in)f(msilib\),)g(936)0 1677 y FJ(CacheFTPHandler)e FN(\(class)j(in)f(urllib2\),)f(624)0 1777 y FJ(calcsize\(\))g FN(\(in)h(module)f(struct\),)g(63)0 1876 y FJ(Calendar)g FN(\(class)i(in)f(calendar\),)f(114)0 1976 y FJ(calendar\(\))g FN(\(in)h(module)f(calendar\),)f(116)0 2076 y FJ(calendar)h FN(\(standard)g(module\),)f FL(113)0 2175 y FJ(call\(\))187 2275 y FN(method,)g(558)166 2374 y(in)i(module)f(subprocess,)g(572)0 2474 y FJ(callable\(\))g FN(\(in)h(module)f(\),)h(4)0 2574 y FJ(CallableProxyType)e FN(\(data)h(in)i(weakref\),)d(136)0 2673 y FJ(can_change_color\(\))f FN(\(in)j(module)f(curses\),)h(473)0 2773 y FJ(can_fetch\(\))f FN(\(RobotFileP)o(arser)f(method\),)h(313)0 2873 y FJ(cancel\(\))166 2972 y FN(scheduler)g(method,)g(132)166 3072 y(T)m(imer)h(method,)e (546)0 3171 y FJ(CannotSendHeader)g FN(\(e)o(xception)g(in)i (httplib\),)f(633)0 3271 y FJ(CannotSendRequest)f FN(\(e)o(xception)g (in)i(httplib\),)f(633)0 3371 y FJ(capitalize\(\))166 3470 y FN(in)h(module)f(string,)h(50)166 3570 y(string)g(method,)e(29)0 3670 y FJ(capwords\(\))h FN(\(in)h(module)f(string\),)g(50)0 3769 y FJ(cast\(\))h FN(\(in)g(module)e(ctypes\),)i(528)0 3869 y FJ(cat\(\))g FN(\(in)g(module)f(nis\),)h(568)0 3968 y FJ(catalog)f FN(\(data)h(in)h(cd\),)e(916)0 4068 y FJ(category\(\))g FN(\(in)h(module)f(unicodedata\),)e(90)0 4168 y FJ(cbreak\(\))i FN(\(in)h(module)f(curses\),)h(473)0 4267 y FJ(cd)g FN(\(b)n(uilt-in)g(module\),)e FL(915)0 4367 y FJ(CDLL)i FN(\(class)h(in)f(ctypes\),)f(523)0 4467 y FJ(CDROM)h FN(\(data)g(in)g(cd\),)f(916)0 4566 y FJ(ceil\(\))166 4666 y FN(in)h(module)f(math,)h(149)166 4765 y(in)g(module)f(math,)h(25)0 4865 y FJ(center\(\))166 4965 y FN(in)g(module)f(string,)h(52)166 5064 y(string)g(method,)e(29)0 5164 y FJ(CFUNCTYPE\(\))h FN(\(in)h(module)f(ctypes\),)g(526)0 5264 y(CGI)166 5363 y(deb)n(ugging,)e(608)2158 83 y(e)o(xceptions,)h (609)2158 183 y(protocol,)g(602)2158 282 y(security)-5 b(,)19 b(607)2158 382 y(tracebacks,)f(609)1992 482 y FJ(cgi)i FN(\(standard)e(module\),)h FL(602)1992 581 y FJ(cgi_directories)245 b FN(\(CGIHTTPRequestHandler)2324 681 y(attrib)n(ute\),)19 b(671)1992 780 y FJ(CGIHandler)f FN(\(class)j(in)g(wsgiref.handlers\),)c(614)1992 880 y FJ(CGIHTTPRequestHandler)142 b FN(\(class)k(in)f(CGI-)2324 980 y(HTTPServ)o(er\),)18 b(671)1992 1079 y FJ(CGIHTTPServer)g FN(\(standard)h(module\),)f(667,)h FL(671)1992 1179 y FJ(cgitb)g FN(\(standard)g(module\),)f FL(609)1992 1279 y FJ(CGIXMLRPCRequestHandler)e FN(\(class)k(in)h(SimpleXML-)2324 1378 y(RPCServ)o(er\),)e(689)1992 1478 y FJ(chain\(\))g FN(\(in)h(module)f(itertools\),)g(173)1992 1577 y(chaining)2158 1677 y(comparisons,)f(24)1992 1777 y FJ(channels\(\))g FN(\(audio)h(de)n(vice)h(method\),)e(709)1992 1876 y FJ(CHAR_MAX)h FN(\(data)g(in)i(locale\),)e(752)1992 1976 y(character)m(,)f(90)1992 2076 y FJ(CharacterDataHandler\(\))73 b FN(\(xmlparser)j(method\),)2324 2175 y(267)1992 2275 y FJ(characters\(\))18 b FN(\(ContentHandler)g(method\),)g(292)1992 2374 y FJ(CHARSET)h FN(\(data)h(in)g(mimify\),)f(244)1992 2474 y FJ(Charset)g FN(\(class)i(in)f(email.charset\),)f(203)1992 2574 y FJ(charset\(\))g FN(\(NullT)m(ranslations)f(method\),)g(742)1992 2673 y FJ(chdir\(\))h FN(\(in)h(module)f(os\),)h(402)1992 2773 y FJ(check\(\))2158 2873 y FN(IMAP4)p 2413 2873 25 4 v 29 w(stream)g(method,)e(644)2158 2972 y(in)i(module)f(tabnann)o (y)-5 b(,)17 b(885)1992 3072 y FJ(check_call\(\))h FN(\(in)i(module)f (subprocess\),)f(573)1992 3171 y FJ(check_forms\(\))g FN(\(in)i(module)f(\003\),)h(919)1992 3271 y FJ(check_output\(\))e FN(\(OutputCheck)o(er)f(method\),)i(784)1992 3371 y FJ(checkbox\(\))f FN(\(Dialog)i(method\),)e(939)1992 3470 y FJ(checkcache\(\))g FN(\(in)i(module)f(linecache\),)f(338)1992 3570 y FJ(CheckList)h FN(\(class)h(in)h(T)m(ix\),)e(727)1992 3670 y(checksum)2158 3769 y(Cyclic)h(Redundanc)o(y)e(Check,)h(344)2158 3869 y(MD5,)g(321)2158 3968 y(SHA,)h(322)1992 4068 y FJ(childerr)f FN(\(Popen4)f(attrib)n(ute\),)h(591)1992 4168 y FJ(childNodes)f FN(\(Node)i(attrib)n(ute\),)f(275)1992 4267 y FJ(chmod\(\))g FN(\(in)h(module)f(os\),)h(402)1992 4367 y FJ(choice\(\))f FN(\(in)h(module)f(random\),)e(170)1992 4467 y FJ(choose_boundary\(\))g FN(\(in)j(module)f(mimetools\),)g(239)1992 4566 y FJ(chown\(\))g FN(\(in)h(module)f(os\),)h(403)1992 4666 y FJ(chr\(\))f FN(\(in)h(module)f(\),)h(4)1992 4765 y FJ(chroot\(\))f FN(\(in)h(module)f(os\),)h(402)1992 4865 y FJ(Chunk)f FN(\(class)i(in)f(chunk\),)f(704)1992 4965 y FJ(chunk)g FN(\(standard)g(module\),)f FL(704)1992 5064 y FN(cipher)2158 5164 y(DES,)i(556)1992 5264 y FJ(circle\(\))f FN(\(in)h(module)f (turtle\),)g(732)1992 5363 y FJ(Clamped)g FN(\(class)i(in)f(decimal\),) f(162)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(975)p eop end %%Page: 976 988 TeXDict begin 976 987 bop 0 83 a FN(Class)22 b(bro)n(wser)m(,)c(733)0 183 y FJ(classmethod\(\))g FN(\(in)i(module)f(\),)h(5)0 282 y FJ(classobj\(\))f FN(\(in)h(module)f(ne)n(w\),)g(143)0 382 y FJ(ClassType)g FN(\(data)h(in)g(types\),)g(141)0 482 y FJ(clean\(\))f FN(\(Maildir)h(method\),)e(222)0 581 y FJ(clear\(\))187 681 y FN(method,)g(117)166 780 y(CookieJar)h(method,)g(674)166 880 y(dictionary)f(method,)h(37)166 980 y(Ev)o(ent)g(method,)g(544)166 1079 y(in)h(module)f(turtle,)h(731) 166 1179 y(Mailbox)f(method,)g(221)166 1279 y(windo)n(w)g(method,)g (479)0 1378 y FJ(clear_flags\(\))f FN(\(Conte)o(xt)h(method\),)g(160)0 1478 y FJ(clear_history\(\))f FN(\(in)i(module)f(readline\),)f(549)0 1577 y FJ(clear_memo\(\))h FN(\(Pickler)g(method\),)f(362)0 1677 y FJ(clear_session_cookies\(\))46 b FN(\(CookieJar)j(method\),)332 1777 y(674)0 1876 y FJ(clearcache\(\))19 b FN(\(in)h(module)e (linecache\),)h(338)0 1976 y FJ(ClearData\(\))g FN(\(Binary)g (method\),)f(936)0 2076 y FJ(clearok\(\))h FN(\(windo)n(w)g(method\),)f (479)0 2175 y FJ(client_address)93 b FN(\(BaseHTTPRequestHandler)h(at-) 332 2275 y(trib)n(ute\),)19 b(668)0 2374 y FJ(clock\(\))g FN(\(in)h(module)f(time\),)h(416)0 2474 y FJ(clone\(\))166 2574 y FN(Generator)f(method,)f(199)166 2673 y(T)-6 b(emplate)20 b(method,)e(563)0 2773 y FJ(cloneNode\(\))h FN(\(Node)g(method\),)f (276,)h(285)0 2873 y FJ(Close\(\))187 2972 y FN(method,)f(945)166 3072 y(Binary)i(method,)e(935)0 3171 y FJ(close\(\))187 3271 y FN(method,)g(380,)h(461,)g(548,)h(558)166 3371 y(aifc)g(method,)f(698,)g(699)166 3470 y(A)-5 b(U)p 286 3470 25 4 v 30 w(read)20 b(method,)e(700)166 3570 y(A)-5 b(U)p 286 3570 V 30 w(write)21 b(method,)d(701)166 3670 y(audio)h(de)n(vice)h(method,)e(708,)h(931)166 3769 y(BaseHandler)h (method,)e(626)166 3869 y(BZ2File)j(method,)d(346)166 3968 y(CD)j(player)e(method,)g(917)166 4068 y(Chunk)g(method,)g(704)166 4168 y(dispatcher)g(method,)g(594)166 4267 y(FeedP)o(arser)g(method,)g (197)166 4367 y(\002le)i(method,)d(39)166 4467 y(FileHandler)h(method,) g(462)166 4566 y(FTP)i(method,)d(639)166 4666 y(HTMLP)o(arser)h (method,)g(258)166 4765 y(HTTPResponse)h(method,)e(635)166 4865 y(IMAP4)p 421 4865 V 29 w(stream)i(method,)f(644)166 4965 y(in)h(module)f(\002leinput,)h(329)166 5064 y(in)g(module)f(os,)i (399)166 5164 y(IncrementalP)o(arser)d(method,)g(296)166 5264 y(Mailbox)h(method,)g(221)166 5363 y(Maildir)h(method,)e(222)2158 83 y(MemoryHandler)f(method,)h(466)2158 183 y(MH)i(method,)f(225)2158 282 y(mix)o(er)g(de)n(vice)g(method,)g(710)2158 382 y(NTEv)o (entLogHandler)d(method,)i(465)2158 482 y(Pro\002le)i(method,)e(819) 2158 581 y(SGMLP)o(arser)h(method,)g(260)2158 681 y(sock)o(et)h (method,)e(582)2158 780 y(Sock)o(etHandler)g(method,)g(463)2158 880 y(StringIO)h(method,)f(74)2158 980 y(SysLogHandler)f(method,)i(464) 2158 1079 y(T)-7 b(arFile)20 b(method,)f(354)2158 1179 y(T)-6 b(elnet)20 b(method,)e(657)2158 1279 y(T)m(reeBuilder)h(method,) f(301)2158 1378 y(W)-7 b(a)n(v)o(e)p 2347 1378 V 30 w(read)19 b(method,)g(702)2158 1478 y(W)-7 b(a)n(v)o(e)p 2347 1478 V 30 w(write)20 b(method,)e(703)2158 1577 y(XML)-8 b(T)m(reeBuilder)18 b(method,)h(302)2158 1677 y(ZipFile)h(method,)e(349)1992 1777 y FJ(close_when_done\(\))f FN(\(async)p 3082 1777 V 29 w(chat)j(method\),)e(596)1992 1876 y FJ(closed)2158 1976 y FN(audio)h(de)n(vice)g(attrib)n(ute,)h(710)2158 2076 y(\002le)g(attrib)n(ute,)g(41)1992 2175 y FJ(CloseKey\(\))e FN(\(in)i(module)p 2898 2175 V 49 w(winre)o(g\),)f(941)1992 2275 y FJ(closelog\(\))f FN(\(in)i(module)f(syslog\),)h(568)1992 2374 y FJ(closeport\(\))e FN(\(audio)h(port)h(method\),)e(914)1992 2474 y FJ(closing\(\))h FN(\(in)h(module)e(conte)o(xtlib\),)g(838)1992 2574 y FJ(clrtobot\(\))g FN(\(windo)n(w)h(method\),)f(479)1992 2673 y FJ(clrtoeol\(\))g FN(\(windo)n(w)h(method\),)f(479)1992 2773 y FJ(cmath)h FN(\(b)n(uilt-in)h(module\),)e FL(151)1992 2873 y FJ(Cmd)i FN(\(class)g(in)h(cmd\),)e(757)1992 2972 y FJ(cmd)h FN(\(standard)e(module\),)h FL(757)p FN(,)g(805)1992 3072 y FJ(cmdloop\(\))g FN(\(Cmd)g(method\),)g(757)1992 3171 y FJ(cmp\(\))2158 3271 y FN(b)n(uilt-in)g(function,)f(751)2158 3371 y(in)i(module)f(,)h(5)2158 3470 y(in)g(module)f(\002lecmp,)g(333) 1992 3570 y FJ(cmp_op)g FN(\(data)h(in)g(dis\),)g(889)1992 3670 y FJ(cmpfiles\(\))e FN(\(in)i(module)f(\002lecmp\),)g(333)1992 3769 y(code)2158 3869 y(object,)g(44,)h(374)1992 3968 y FJ(code\(\))f FN(\(in)h(module)f(ne)n(w\),)g(143)1992 4068 y FJ(code)2158 4168 y FN(ExpatError)e(attrib)n(ute,)j(269)2158 4267 y(standard)f(module,)f FL(855)1992 4367 y FN(Codecs,)h(77)2158 4467 y(decode,)f(77)2158 4566 y(encode,)g(77)1992 4666 y FJ(codecs)h FN(\(standard)g(module\),)f FL(77)1992 4765 y FJ(coded_value)g FN(\(Morsel)i(attrib)n(ute\),)f(681)1992 4865 y FJ(codeop)g FN(\(standard)g(module\),)f FL(857)1992 4965 y FJ(codepoint2name)g FN(\(data)h(in)i(htmlentitydefs\),)d(264) 1992 5064 y FJ(CODESET)h FN(\(data)h(in)g(locale\),)f(752)1992 5164 y FJ(CodeType)g FN(\(data)g(in)i(types\),)e(141)1992 5264 y FJ(coerce\(\))g FN(\(in)h(module)f(\),)h(17)p 0 5549 3901 4 v 0 5649 a FI(976)3561 b(Inde)n(x)p eop end %%Page: 977 989 TeXDict begin 977 988 bop 0 83 a FJ(collapse_rfc2231_value\(\))181 b FN(\(in)k(module)332 183 y(email.utils\),)20 b(209)0 282 y FJ(collect\(\))f FN(\(in)h(module)f(gc\),)g(843)0 382 y FJ(collect_incoming_data\(\))36 b FN(\(async)p 1409 382 25 4 v 28 w(chat)k(method\),)332 482 y(596)0 581 y FJ(collections)19 b FN(\(standard)f(module\),)h FL(116)0 681 y FJ(color\(\))166 780 y FN(in)h(module)f(\003,)i(920)166 880 y(in)f(module)f(turtle,)h(731)0 980 y FJ(color_content\(\))e FN(\(in)i(module)f(curses\),)g(473)0 1079 y FJ(color_pair\(\))g FN(\(in)h(module)e(curses\),)i(473)0 1179 y FJ(colorsys)f FN(\(standard)g(module\),)f FL(705)0 1279 y FN(COLUMNS,)i(478)0 1378 y FJ(combine\(\))f FN(\(datetime)g(method\),)g(102)0 1478 y FJ(combining\(\))g FN(\(in)h(module)f(unicodedata\),)e(90)0 1577 y FJ(ComboBox)i FN(\(class)i(in)f(T)m(ix\),)g(726)0 1677 y FJ(command)f FN(\(BaseHTTPRequestHandler)g(attrib)n(ute\),)g (668)0 1777 y FJ(CommandCompiler)f FN(\(class)j(in)f(codeop\),)e(857)0 1876 y FJ(commands)h FN(\(standard)g(module\),)f FL(569)0 1976 y FJ(COMMENT)h FN(\(data)h(in)h(tok)o(enize\),)d(884)0 2076 y FJ(Comment\(\))h FN(\(in)h(module)f(xml.etree.ElementT)m(ree\),) d(299)0 2175 y FJ(comment)166 2275 y FN(Cookie)k(attrib)n(ute,)f(678) 166 2374 y(ZipInfo)f(attrib)n(ute,)i(351)0 2474 y FJ(comment_url)f FN(\(Cookie)g(attrib)n(ute\),)g(678)0 2574 y FJ(commenters)g FN(\(shle)o(x)g(attrib)n(ute\),)h(760)0 2673 y FJ(CommentHandler\(\))e FN(\(xmlparser)g(method\),)g(268)0 2773 y FJ(Commit\(\))h FN(\(Binary)h(method\),)e(934)0 2873 y FJ(common)i FN(\(dircmp)e (attrib)n(ute\),)h(334)0 2972 y(Common)g(Gate)n(w)o(ay)h(Interf)o(ace,) e(602)0 3072 y FJ(common_dirs)h FN(\(dircmp)f(attrib)n(ute\),)i(334)0 3171 y FJ(common_files)f FN(\(dircmp)f(attrib)n(ute\),)h(334)0 3271 y FJ(common_funny)g FN(\(dircmp)f(attrib)n(ute\),)h(334)0 3371 y FJ(common_types)g FN(\(data)g(in)i(mimetypes\),)d(242,)h(243)0 3470 y FJ(commonprefix\(\))f FN(\(in)i(module)f(os.path\),)g(325)0 3570 y FJ(communicate\(\))f FN(\(Popen)h(method\),)g(573)0 3670 y FJ(compare\(\))166 3769 y FN(Conte)o(xt)g(method,)g(160)166 3869 y(Decimal)h(method,)f(157)166 3968 y(Dif)n(fer)h(method,)e(72)0 4068 y(comparing)166 4168 y(objects,)i(24)0 4267 y(comparison)166 4367 y(operator)m(,)e(24)0 4467 y FJ(COMPARISON_FLAGS)g FN(\(data)h(in)i(doctest\),)e(773)0 4566 y(comparisons)166 4666 y(chaining,)f(24)0 4765 y FJ(Compile)h FN(\(class)i(in)g (codeop\),)d(857)0 4865 y FJ(compile\(\))166 4965 y FN(AST)j(method,)d (876)166 5064 y(b)n(uilt-in)i(function,)e(44,)h(141,)g(875,)g(876)166 5164 y(in)h(module)f(,)i(5)166 5264 y(in)f(module)f(compiler)m(,)g(897) 166 5363 y(in)h(module)f(p)o(y)p 609 5363 V 29 w(compile,)g(887)2158 83 y(in)h(module)f(re,)h(57)1992 183 y FJ(compile_command\(\))2158 282 y FN(in)g(module)f(code,)g(855)2158 382 y(in)h(module)f(codeop,)f (857)1992 482 y FJ(compile_dir\(\))g FN(\(in)i(module)f(compileall\),)f (887)1992 581 y FJ(compile_path\(\))g FN(\(in)i(module)e(compileall\),) h(888)1992 681 y FJ(compileall)f FN(\(standard)h(module\),)f FL(887)1992 780 y FJ(compileast\(\))g FN(\(in)i(module)f(parser\),)g (875)1992 880 y FJ(compileFile\(\))f FN(\(in)i(module)f(compiler\),)f (898)1992 980 y FJ(compiler)h FN(\(module\),)f FL(897)1992 1079 y FJ(compiler.ast)g FN(\(module\),)g FL(898)1992 1179 y FJ(compiler.visitor)f FN(\(module\),)h FL(903)1992 1279 y FJ(complete\(\))g FN(\(Completer)h(method\),)g(552)1992 1378 y FJ(complete_statement\(\))e FN(\(in)j(module)e(sqlite3\),)i(386) 1992 1478 y FJ(completedefault\(\))d FN(\(Cmd)j(method\),)e(758)1992 1577 y FJ(complex\(\))2158 1677 y FN(b)n(uilt-in)h(function,)f(25)2158 1777 y(in)i(module)f(,)h(5)1992 1876 y(comple)o(x)e(number)2158 1976 y(literals,)i(25)2158 2076 y(object,)f(25)1992 2175 y FJ(ComplexType)f FN(\(data)i(in)g(types\),)g(141)1992 2275 y FJ(compress\(\))2158 2374 y FN(BZ2Compressor)e(method,)h(347) 2158 2474 y(Compress)g(method,)g(344)2158 2574 y(in)h(module)f(bz2,)g (348)2158 2673 y(in)h(module)f(jpe)o(g,)g(928)2158 2773 y(in)h(module)f(zlib,)h(343)1992 2873 y FJ(compress_size)e FN(\(ZipInfo)g(attrib)n(ute\),)h(351)1992 2972 y FJ(compress_type)f FN(\(ZipInfo)g(attrib)n(ute\),)h(351)1992 3072 y FJ(CompressionError)e FN(\(e)o(xception)h(in)j(tar\002le\),)e(353)1992 3171 y FJ(compressobj\(\))f FN(\(in)i(module)f(zlib\),)g(343)1992 3271 y(COMSPEC,)i(412,)e(572)1992 3371 y FJ(concat\(\))g FN(\(in)h(module)f(operator\),)e(184)1992 3470 y(concatenation)2158 3570 y(operation,)h(28)1992 3670 y FJ(Condition\(\))g FN(\(in)i(module)f(threading\),)f(538)1992 3769 y FJ(Condition)h FN(\(class)h(in)h(threading\),)c(542)1992 3869 y FJ(condition\(\))h FN(\(Control)h(method\),)g(938)1992 3968 y FJ(ConfigParser)2158 4068 y FN(class)i(in)f(Con\002gP)o(arser)m(,)f(310)2158 4168 y(standard)g(module,)f FL(310)1992 4267 y FN(con\002guration)2158 4367 y(\002le,)i(310)2158 4467 y(\002le,)g(deb)n(ugger)m(,)e(807)2158 4566 y(\002le,)i(path,)g(850)2158 4666 y(\002le,)g(user)m(,)g(851)1992 4765 y FJ(confstr\(\))f FN(\(in)h(module)e(os\),)i(414)1992 4865 y FJ(confstr_names)e FN(\(data)i(in)g(os\),)g(414)1992 4965 y FJ(conjugate\(\))e FN(\(comple)o(x)g(number)h(method\),)f(25) 1992 5064 y FJ(connect\(\))2158 5164 y FN(dispatcher)h(method,)f(594) 2158 5264 y(FTP)i(method,)f(638)2158 5363 y(HTTPResponse)g(method,)g (635)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(977)p eop end %%Page: 978 990 TeXDict begin 978 989 bop 166 83 a FN(in)20 b(module)f(sqlite3,)h(385) 166 183 y(SMTP)h(method,)d(652)166 282 y(sock)o(et)i(method,)f(582)0 382 y FJ(connect_ex\(\))g FN(\(sock)o(et)g(method\),)f(582)0 482 y FJ(ConnectRegistry\(\))g FN(\(in)i(module)p 1255 482 25 4 v 48 w(winre)o(g\),)f(941)0 581 y(constants)166 681 y(b)n(uilt-in,)g(3)0 780 y FJ(constructor\(\))f FN(\(in)i(module)f (cop)o(y)p 1218 780 V 29 w(re)o(g\),)g(371)0 880 y(container)166 980 y(iteration)h(o)o(v)o(er)m(,)e(26)0 1079 y FJ(contains\(\))h FN(\(in)h(module)f(operator\),)e(184)0 1179 y(content)i(type)166 1279 y(MIME,)h(241)0 1378 y FJ(ContentHandler)e FN(\(class)j(in)f (xml.sax.handler\),)d(289)0 1478 y FJ(ContentTooShortError)g FN(\(e)o(xception)h(in)i(urllib\),)f(620)0 1577 y FJ(Context)g FN(\(class)i(in)g(decimal\),)e(159)0 1677 y(conte)o(xt)g(management)f (protocol,)g(42)0 1777 y(conte)o(xt)h(manager)m(,)f(42)0 1876 y FJ(context_diff\(\))g FN(\(in)i(module)f(dif)n(\003ib\),)g(67)0 1976 y FJ(contextlib)g FN(\(standard)g(module\),)f FL(837)0 2076 y FJ(contextmanager\(\))g FN(\(in)i(module)f(conte)o(xtlib\),)f (837)0 2175 y FJ(Control)166 2275 y FN(class)j(in)g(msilib,)f(938)166 2374 y(class)h(in)g(T)m(ix,)e(726)0 2474 y FJ(control\(\))g FN(\(Dialog)g(method\),)g(938)0 2574 y FJ(control)g FN(\(data)h(in)h (cd\),)e(916)0 2673 y FJ(controlnames)g FN(\(data)g(in)i (curses.ascii\),)e(490)0 2773 y FJ(controls\(\))g FN(\(mix)o(er)g(de)n (vice)g(method\),)f(710)0 2873 y FJ(ConversionError)g FN(\(e)o(xception)g(in)i(xdrlib\),)f(317)0 2972 y(con)m(v)o(ersions)166 3072 y(numeric,)g(25)0 3171 y FJ(convert\(\))g FN(\(Charset)h (method\),)e(204)0 3271 y FJ(convert_charref\(\))g FN(\(SGMLP)o(arser)h (method\),)f(261)0 3371 y FJ(convert_codepoint\(\))f FN(\(SGMLP)o(arser)i(method\),)g(261)0 3470 y FJ(convert_entityref\(\)) e FN(\(SGMLP)o(arser)i(method\),)g(261)0 3570 y FJ(Cookie)166 3670 y FN(class)i(in)g(cookielib,)d(673)166 3769 y(standard)h(module,)g FL(680)0 3869 y FJ(CookieError)g FN(\(e)o(xception)f(in)i(Cookie\),)f (680)0 3968 y FJ(CookieJar)g FN(\(class)i(in)f(cookielib\),)e(672)0 4068 y FJ(cookiejar)h FN(\(Unkno)n(wnHandler)d(attrib)n(ute\),)j(628)0 4168 y FJ(cookielib)g FN(\(standard)g(module\),)f FL(672)0 4267 y FJ(CookiePolicy)h FN(\(class)h(in)h(cookielib\),)d(672)0 4367 y(Coordinated)g(Uni)n(v)o(ersal)h(T)m(ime,)h(415)0 4467 y FJ(copy\(\))166 4566 y FN(Compress)g(method,)e(344)166 4666 y(Conte)o(xt)h(method,)g(160)166 4765 y(Decompress)g(method,)g (345)166 4865 y(hash)h(method,)f(320)166 4965 y(hmac)h(method,)e(321) 166 5064 y(IMAP4)p 421 5064 V 29 w(stream)i(method,)f(644)166 5164 y(in)h(module)f(shutil,)h(339)166 5264 y(md5)f(method,)g(322)166 5363 y(sha)h(method,)f(323)2158 83 y(T)-6 b(emplate)19 b(method,)g(563)1992 183 y FJ(copy)h FN(\(standard)e(module\),)g FL(143)p FN(,)h(371)1992 282 y FJ(copy\(\))2158 382 y FN(dictionary)f(method,)h(37)2158 482 y(in)h(cop)o(y)-5 b(,)19 b(143)1992 581 y FJ(copy2\(\))g FN(\(in)h(module)f(shutil\),)g (339)1992 681 y FJ(copy_reg)g FN(\(standard)f(module\),)h FL(371)1992 780 y FJ(copybinary\(\))f FN(\(in)i(module)f(mimetools\),)g (240)1992 880 y FJ(copyfile\(\))f FN(\(in)i(module)f(shutil\),)h(338) 1992 980 y FJ(copyfileobj\(\))e FN(\(in)i(module)f(shutil\),)g(339)1992 1079 y(cop)o(ying)f(\002les,)j(338)1992 1179 y FJ(copyliteral\(\))d FN(\(in)i(module)f(mimetools\),)f(240)1992 1279 y FJ(copymessage\(\))g FN(\(F)o(older)h(method\),)f(239)1992 1378 y FJ(copymode\(\))g FN(\(in)i(module)f(shutil\),)h(339)1992 1478 y FJ(copyright)f FN(\(data)g(in)i(sys\),)f(828)1992 1577 y FJ(copystat\(\))e FN(\(in)i(module)f(shutil\),)h(339)1992 1677 y FJ(copytree\(\))e FN(\(in)i(module)f(shutil\),)h(339)1992 1777 y FJ(cos\(\))2158 1876 y FN(in)g(module)f(cmath,)g(152)2158 1976 y(in)h(module)f(math,)g (150)1992 2076 y FJ(cosh\(\))2158 2175 y FN(in)h(module)f(cmath,)g(152) 2158 2275 y(in)h(module)f(math,)g(151)1992 2374 y FJ(count\(\))2158 2474 y FN(array)g(method,)f(126)2158 2574 y(in)i(module)f(itertools,)g (173)2158 2673 y(in)h(module)f(string,)g(51)2158 2773 y(list)i(method,)d(35)2158 2873 y(string)h(method,)g(29)1992 2972 y FJ(countOf\(\))g FN(\(in)h(module)e(operator\),)g(185)1992 3072 y FJ(countTestCases\(\))2158 3171 y FN(T)-6 b(estCase)21 b(method,)d(798)2158 3271 y(T)-6 b(estSuite)20 b(method,)f(798)1992 3371 y FJ(cPickle)g FN(\(b)n(uilt-in)g(module\),)f FL(370)p FN(,)h(371)1992 3470 y FJ(cProfile)g FN(\(standard)f(module\),)h FL(814)1992 3570 y FN(CPU)i(time,)f(417)1992 3670 y FJ(CRC)g FN(\(ZipInfo)e(attrib)n(ute\),)h(351)1992 3769 y FJ(crc32\(\))2158 3869 y FN(in)h(module)f(binascii,)h(254)2158 3968 y(in)g(module)f (zlib,)h(344)1992 4068 y FJ(crc_hqx\(\))f FN(\(in)h(module)e (binascii\),)i(254)1992 4168 y FJ(create\(\))f FN(\(IMAP4)p 2694 4168 V 28 w(stream)h(method\),)f(644)1992 4267 y FJ(create_aggregate\(\))e FN(\()j(method\),)f(387)1992 4367 y FJ(create_collation\(\))e FN(\()j(method\),)f(387)1992 4467 y FJ(create_decimal\(\))e FN(\(Conte)o(xt)i(method\),)g(160)1992 4566 y FJ(create_function\(\))e FN(\()j(method\),)f(387)1992 4666 y FJ(create_socket\(\))e FN(\(dispatcher)i(method\),)f(594)1992 4765 y FJ(create_string_buffer\(\))e FN(\(in)k(module)f(ctypes\),)g (528)1992 4865 y FJ(create_system)f FN(\(ZipInfo)g(attrib)n(ute\),)h (351)1992 4965 y FJ(create_unicode_buffer\(\))49 b FN(\(in)k(module)e (ctypes\),)2324 5064 y(528)1992 5164 y FJ(create_version)18 b FN(\(ZipInfo)g(attrib)n(ute\),)h(351)1992 5264 y FJ (createAttribute\(\))e FN(\(Document)h(method\),)h(278)1992 5363 y FJ(createAttributeNS\(\))e FN(\(Document)h(method\),)g(278)p 0 5549 3901 4 v 0 5649 a FI(978)3561 b(Inde)n(x)p eop end %%Page: 979 991 TeXDict begin 979 990 bop 0 83 a FJ(createComment\(\))18 b FN(\(Document)g(method\),)g(277)0 183 y FJ(createDocument\(\))30 b FN(\(DOMImplementation)g(method\),)332 282 y(274)0 382 y FJ(createDocumentType\(\))161 b FN(\(DOMImplementation)332 482 y(method\),)18 b(274)0 581 y FJ(createElement\(\))g FN(\(Document)g(method\),)g(277)0 681 y FJ(createElementNS\(\))g FN(\(Document)g(method\),)g(277)0 780 y FJ(CreateKey\(\))h FN(\(in)h(module)p 956 780 25 4 v 48 w(winre)o(g\),)f(941)0 880 y FJ(createLock\(\))g FN(\()h(method\),)e(461)0 980 y FJ(createparser\(\))g FN(\(in)i(module)f(cd\),)g(915)0 1079 y FJ(createProcessingInstruction\(\))85 b FN(\(Document)332 1179 y(method\),)18 b(277)0 1279 y FJ(CreateRecord\(\))g FN(\(in)i(module)f(msilib\),)h(933)0 1378 y FJ(createTextNode\(\))e FN(\(Document)g(method\),)g(277)0 1478 y FJ(critical\(\))187 1577 y FN(method,)g(455)166 1677 y(in)i(module)f(logging,)f(452)0 1777 y FJ(CRNCYSTR)h FN(\(data)h(in)g(locale\),)g(753)0 1876 y FJ(crop\(\))g FN(\(in)g(module)e(imageop\),)h(696)0 1976 y FJ(cross\(\))g FN(\(in)h(module)f(audioop\),)f(694)0 2076 y FJ(crypt\(\))h FN(\(in)h(module)f(crypt\),)g(556)0 2175 y FJ(crypt)h FN(\(b)n(uilt-in)f(module\),)f(555,)h FL(556)0 2275 y FN(crypt\(3\),)f(556,)h(557)0 2374 y(cryptography)-5 b(,)15 b(319)0 2474 y FJ(cStringIO)k FN(\(b)n(uilt-in)g(module\),)g FL(75)0 2574 y FN(csv)-5 b(,)20 b(303)0 2673 y FJ(csv)g FN(\(standard)f(module\),)f FL(303)0 2773 y FJ(ctermid\(\))h FN(\(in)h(module)f(os\),)h(396)0 2873 y FJ(ctime\(\))166 2972 y FN(date)g(method,)f(100)166 3072 y(datetime)h(method,)e(105)166 3171 y(in)i(module)f(time,)h(417)0 3271 y FJ(ctrl\(\))g FN(\(in)g(module)e(curses.ascii\),)i(490)0 3371 y FJ(ctypes)g FN(\(standard)e(module\),)h FL(500)0 3470 y FJ(curdir)h FN(\(data)f(in)i(os\),)f(414)0 3570 y FJ(currency\(\))f FN(\(in)h(module)f(locale\),)g(751)0 3670 y FJ(CurrentByteIndex)f FN(\(xmlparser)g(attrib)n(ute\),)h(267)0 3769 y FJ(CurrentColumnNumber) e FN(\(xmlparser)i(attrib)n(ute\),)g(267)0 3869 y FJ(currentframe\(\))f FN(\(in)i(module)f(inspect\),)g(850)0 3968 y FJ(CurrentLineNumber)f FN(\(xmlparser)g(attrib)n(ute\),)h(267)0 4068 y FJ(currentThread\(\))f FN(\(in)i(module)f(threading\),)e(538)0 4168 y FJ(curs_set\(\))i FN(\(in)h(module)f(curses\),)g(473)0 4267 y FJ(curses)h FN(\(standard)e(module\),)h FL(472)0 4367 y FJ(curses.ascii)g FN(\(standard)f(module\),)g FL(488)0 4467 y FJ(curses.panel)h FN(\(standard)f(module\),)g FL(491)0 4566 y FJ(curses.textpad)g FN(\(standard)h(module\),)f FL(487)0 4666 y FJ(curses.wrapper)g FN(\(standard)h(module\),)f FL(488)0 4765 y FJ(cursor\(\))h FN(\()i(method\),)d(386)0 4865 y FJ(cursyncup\(\))h FN(\(windo)n(w)g (method\),)f(479)0 4965 y FJ(cwd\(\))i FN(\(FTP)g(method\),)e(639)0 5064 y FJ(cycle\(\))h FN(\(in)h(module)f(itertools\),)h(173)0 5164 y(Cyclic)h(Redundanc)o(y)c(Check,)j(344)1992 86 y FE(D)1992 210 y FJ(D_FMT)f FN(\(data)h(in)g(locale\),)g(752)1992 309 y FJ(D_T_FMT)f FN(\(data)h(in)g(locale\),)f(752)1992 409 y(data)2158 509 y(packing)f(binary)-5 b(,)18 b(62)2158 608 y(tab)n(ular)m(,)h(303)1992 708 y FJ(data\(\))g FN(\(T)m (reeBuilder)g(method\),)f(301)1992 807 y FJ(data)2158 907 y FN(Binary)h(attrib)n(ute,)h(686)2158 1007 y(Comment)f(attrib)n (ute,)g(279)2158 1106 y(IterableUserDict)g(attrib)n(ute,)g(139)2158 1206 y(MutableString)f(attrib)n(ute,)i(140)2158 1306 y(ProcessingInstruction)d(attrib)n(ute,)i(280)2158 1405 y(T)-6 b(e)o(xt)19 b(attrib)n(ute,)h(280)2158 1505 y(UserList)g(attrib) n(ute,)g(139)1992 1604 y(database)2158 1704 y(Unicode,)e(90)1992 1804 y(databases,)h(382)1992 1903 y FJ(DatagramHandler)e FN(\(class)k(in)g(logging\),)c(464)1992 2003 y FJ(DATASIZE)i FN(\(data)g(in)i(cd\),)e(916)1992 2103 y FJ(date\(\))2158 2202 y FN(datetime)g(method,)g(103)2158 2302 y(NNTP)h(method,)f(651) 1992 2401 y FJ(date)h FN(\(class)g(in)h(datetime\),)e(96,)g(98)1992 2501 y FJ(date_time)g FN(\(ZipInfo)f(attrib)n(ute\),)h(350)1992 2601 y FJ(date_time_string\(\))77 b FN(\(BaseHTTPRequestHandler)2324 2700 y(method\),)18 b(670)1992 2800 y FJ(datetime)2158 2900 y FN(b)n(uilt-in)h(module,)g FL(95)2158 2999 y FN(class)i(in)f (datetime,)f(96,)h(101)1992 3099 y FJ(day)2158 3198 y FN(date)g(attrib)n(ute,)f(99)2158 3298 y(datetime)g(attrib)n(ute,)h (102)1992 3398 y FJ(DAY_1)48 b(...)99 b(DAY_7)20 b FN(\(data)g(in)g (locale\),)g(752)1992 3497 y FJ(day_abbr)f FN(\(data)g(in)i (calendar\),)d(116)1992 3597 y FJ(day_name)h FN(\(data)g(in)i (calendar\),)d(116)1992 3697 y FJ(daylight)h FN(\(data)g(in)i(time\),)f (417)1992 3796 y(Daylight)f(Sa)n(ving)h(T)m(ime,)f(416)1992 3896 y FJ(DbfilenameShelf)e FN(\(class)k(in)g(shelv)o(e\),)e(372)1992 3995 y FJ(dbhash)g FN(\(standard)g(module\),)f(375,)h FL(378)1992 4095 y FJ(dbm)h FN(\(b)n(uilt-in)f(module\),)f(372,)h(375,) g FL(376)p FN(,)g(377)1992 4195 y FJ(deactivate_form\(\))e FN(\(form)i(method\),)f(921)1992 4294 y FJ(debug\(\))2178 4394 y FN(method,)h(454)2158 4494 y(in)h(module)f(doctest,)g(787)2158 4593 y(in)h(module)f(logging,)f(452)2158 4693 y(T)-6 b(emplate)19 b(method,)g(563)2158 4792 y(T)-6 b(estCase)21 b(method,)d(797)2158 4892 y(T)-6 b(estSuite)20 b(method,)f(798)1992 4992 y FJ(debug)2158 5091 y FN(IMAP4)p 2413 5091 V 29 w(stream)h(attrib)n(ute,)f(647)2158 5191 y(shle)o(x)g(attrib)n(ute,)h (761)2158 5291 y(ZipFile)g(attrib)n(ute,)f(350)1992 5390 y FJ(debug=0)g FN(\(T)-7 b(arFile)20 b(attrib)n(ute\),)f(355)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(979)p eop end %%Page: 980 992 TeXDict begin 980 991 bop 0 83 a FJ(DEBUG_COLLECTABLE)18 b FN(\(data)h(in)i(gc\),)e(844)0 183 y FJ(DEBUG_INSTANCES)f FN(\(data)i(in)g(gc\),)g(844)0 282 y FJ(DEBUG_LEAK)f FN(\(data)h(in)g(gc\),)f(845)0 382 y FJ(DEBUG_OBJECTS)f FN(\(data)i(in)g(gc\),)g(845)0 482 y FJ(DEBUG_SAVEALL)e FN(\(data)i(in)g(gc\),)g(845)0 581 y FJ(debug_src\(\))f FN(\(in)h(module)f(doctest\),)g(787)0 681 y FJ(DEBUG_STATS)g FN(\(data)g(in)i(gc\),)e(844)0 780 y FJ(DEBUG_UNCOLLECTABLE)e FN(\(data)j(in)g(gc\),)g(844)0 880 y(deb)n(ugger)m(,)d(735,)i(832)166 980 y(con\002guration)f(\002le,)i(807)0 1079 y(deb)n(ugging,)d(805)166 1179 y(CGI,)k(608)0 1279 y FJ(DebuggingServer)d FN(\(class)j(in)f (smtpd\),)f(655)0 1378 y FJ(DebugRunner)g FN(\(class)h(in)h(doctest\),) e(788)0 1478 y FJ(Decimal)g FN(\(class)i(in)g(decimal\),)e(157)0 1577 y FJ(decimal\(\))g FN(\(in)h(module)f(unicodedata\),)e(90)0 1677 y FJ(decimal)i FN(\(standard)g(module\),)f FL(153)0 1777 y FJ(DecimalException)g FN(\(class)j(in)f(decimal\),)f(162)0 1876 y(decode)166 1976 y(Codecs,)h(77)0 2076 y FJ(decode\(\))187 2175 y FN(method,)e(81)166 2275 y(Binary)i(method,)e(686)166 2374 y(in)i(module)f(base64,)g(252)166 2474 y(in)h(module)f(mimetools,) g(239)166 2574 y(in)h(module)f(quopri,)f(255)166 2673 y(in)i(module)f(uu,)h(256)166 2773 y(IncrementalDecoder)d(method,)h(82) 166 2873 y(Serv)o(erProxy)g(method,)g(686)166 2972 y(string)i(method,)e (29)0 3072 y FJ(decode_header\(\))g FN(\(in)i(module)f(email.header\),) e(203)0 3171 y FJ(decode_params\(\))h FN(\(in)i(module)f (email.utils\),)g(209)0 3271 y FJ(decode_rfc2231\(\))f FN(\(in)i(module)f(email.utils\),)g(209)0 3371 y FJ(DecodedGenerator)f FN(\(class)j(in)f(email.generator\),)d(199)0 3470 y FJ (decodestring\(\))166 3570 y FN(in)j(module)f(base64,)g(252)166 3670 y(in)h(module)f(quopri,)f(255)0 3769 y FJ(decomposition\(\))g FN(\(in)i(module)f(unicodedata\),)e(90)0 3869 y FJ(decompress\(\))166 3968 y FN(BZ2Decompressor)h(method,)h(348)166 4068 y(Decompress)g (method,)g(345)166 4168 y(in)h(module)f(bz2,)h(348)166 4267 y(in)g(module)f(jpe)o(g,)g(928)166 4367 y(in)h(module)f(zlib,)h (344)0 4467 y FJ(decompressobj\(\))e FN(\(in)i(module)f(zlib\),)g(344)0 4566 y FJ(dedent\(\))g FN(\(in)h(module)f(te)o(xtwrap\),)f(76)0 4666 y FJ(deepcopy\(\))h FN(\(in)h(cop)o(y\),)f(143)0 4765 y FJ(def_prog_mode\(\))f FN(\(in)i(module)f(curses\),)g(473)0 4865 y FJ(def_shell_mode\(\))f FN(\(in)i(module)f(curses\),)g(473)0 4965 y FJ(default\(\))166 5064 y FN(ASTV)-5 b(isitor)20 b(method,)f(903)166 5164 y(Cmd)h(method,)f(758)0 5264 y FJ(default_bufsize)f FN(\(data)i(in)g(xml.dom.pulldom\),)15 b(287)0 5363 y FJ(default_factory)j FN(\(data)i(in)g(collections\),)f (120)1992 83 y FJ(default_open\(\))f FN(\(BaseHandler)h(method\),)f (627)1992 183 y FJ(DefaultContext)g FN(\(class)i(in)h(decimal\),)e(159) 1992 282 y FJ(DefaultCookiePolicy)e FN(\(class)k(in)f(cookielib\),)e (672)1992 382 y FJ(defaultdict\(\))g FN(\(in)i(module)f(collections\),) g(120)1992 482 y FJ(DefaultHandler\(\))e FN(\(xmlparser)i(method\),)f (268)1992 581 y FJ(DefaultHandlerExpand\(\))73 b FN(\(xmlparser)j (method\),)2324 681 y(268)1992 780 y FJ(defaults\(\))18 b FN(\(SafeCon\002gP)o(arser)h(method\),)f(311)1992 880 y FJ(defaultTestLoader)f FN(\(data)j(in)g(unittest\),)g(796)1992 980 y FJ(defaultTestResult\(\))d FN(\(T)-6 b(estCase)21 b(method\),)d(798)1992 1079 y FJ(defects)h FN(\(data)h(in)g (email.message\),)f(196)1992 1179 y FJ(defpath)g FN(\(data)h(in)g (os\),)g(415)1992 1279 y FJ(degrees\(\))2158 1378 y FN(in)g(module)f (math,)g(151)2158 1478 y(in)h(module)f(turtle,)g(730)2158 1577 y(Ra)o(wPen)h(method,)e(733)1992 1677 y FJ(del)2158 1777 y FN(statement,)h(35,)h(37)1992 1876 y FJ(del_param\(\))e FN(\(Message)i(method\),)e(194)1992 1976 y FJ(delattr\(\))h FN(\(in)h(module)e(\),)j(6)1992 2076 y FJ(delay\(\))e FN(\(in)h(module)f(turtle\),)g(731)1992 2175 y FJ(delay_output\(\))f FN(\(in)i(module)e(curses\),)i(473)1992 2275 y FJ(delayload)f FN(\(Cookie)g(attrib)n(ute\),)g(675)1992 2374 y FJ(delch\(\))g FN(\(windo)n(w)g(method\),)f(479)1992 2474 y FJ(dele\(\))h FN(\(POP3)p 2538 2474 25 4 v 29 w(SSL)i(method\),)d(641)1992 2574 y FJ(delete\(\))2158 2673 y FN(FTP)i(method,)f(639)2158 2773 y(IMAP4)p 2413 2773 V 29 w(stream)h(method,)e(644)1992 2873 y FJ(delete_object\(\))f FN(\(FORMS)k(object)f(method\),)e(923) 1992 2972 y FJ(deleteacl\(\))g FN(\(IMAP4)p 2843 2972 V 29 w(stream)i(method\),)e(644)1992 3072 y FJ(deletefolder\(\))g FN(\(MH)i(method\),)e(238)1992 3171 y FJ(DeleteKey\(\))g FN(\(in)i(module)p 2948 3171 V 49 w(winre)o(g\),)e(941)1992 3271 y FJ(deleteln\(\))g FN(\(windo)n(w)h(method\),)f(479)1992 3371 y FJ(deleteparser\(\))g FN(\(CD)i(parser)g(method\),)e(918)1992 3470 y FJ(DeleteValue\(\))g FN(\(in)i(module)p 3048 3470 V 49 w(winre)o(g\),)e(941)1992 3570 y FJ(delimiter)h FN(\(Dialect)h(attrib)n(ute\),)f(306)1992 3670 y FJ(delitem\(\))g FN(\(in)h(module)e(operator\),)g(185)1992 3769 y FJ(delslice\(\))g FN(\(in)i(module)f(operator\),)f(185)1992 3869 y FJ(demo\(\))h FN(\(in)h(module)f(turtle\),)g(732)1992 3968 y FJ(demo_app\(\))f FN(\(in)i(module)f(wsgiref.simple)p 3391 3968 V 28 w(serv)o(er\),)g (613)1992 4068 y FJ(DeprecationWarning)e FN(\(e)o(xception)h(in)i(e)o (xceptions\),)e(21)1992 4168 y FJ(deque\(\))h FN(\(in)h(module)f (collections\),)g(117)1992 4267 y FJ(dereference)f FN(\(T)-7 b(arFile)20 b(attrib)n(ute\),)g(355)1992 4367 y FJ(derwin\(\))f FN(\(windo)n(w)g(method\),)f(479)1992 4467 y(DES)2158 4566 y(cipher)m(,)g(556)1992 4666 y FJ(description\(\))g FN(\(NNTP)i(method\),)e(650)1992 4765 y FJ(descriptions\(\))g FN(\(NNTP)i(method\),)e(649)1992 4865 y(descriptor)m(,)g(\002le,)i(39) 1992 4965 y FJ(Detach\(\))f FN(\()h(method\),)e(945)1992 5064 y(deterministic)h(pro\002ling,)f(811)1992 5164 y FJ(DEVICE)h FN(\(standard)g(module\),)f FL(927)1992 5264 y FJ(devnull)h FN(\(data)h(in)g(os\),)g(415)1992 5363 y FJ(dgettext\(\))e FN(\(in)i(module)f(gette)o(xt\),)g(740)p 0 5549 3901 4 v 0 5649 a FI(980)3561 b(Inde)n(x)p eop end %%Page: 981 993 TeXDict begin 981 992 bop 0 83 a FJ(Dialect)19 b FN(\(class)i(in)g (csv\),)e(305)0 183 y FJ(dialect)166 282 y FN(csv)h(reader)g(attrib)n (ute,)f(307)166 382 y(csv)h(writer)g(attrib)n(ute,)g(307)0 482 y FJ(Dialog)g FN(\(class)g(in)h(msilib\),)f(938)0 581 y FJ(dict\(\))g FN(\(in)g(module)e(\),)j(6)0 681 y(dictionary)166 780 y(object,)e(37)166 880 y(type,)h(operations)e(on,) i(37)0 980 y FJ(DictionaryType)e FN(\(data)i(in)g(types\),)g(141)0 1079 y FJ(DictMixin)f FN(\(class)i(in)f(UserDict\),)g(139)0 1179 y FJ(DictProxyType)e FN(\(data)i(in)g(types\),)g(142)0 1279 y FJ(DictReader)f FN(\(class)i(in)f(csv\),)g(304)0 1378 y FJ(DictType)f FN(\(data)h(in)g(types\),)g(141)0 1478 y FJ(DictWriter)f FN(\(class)i(in)f(csv\),)g(305)0 1577 y FJ(diff_files)f FN(\(dircmp)f(attrib)n(ute\),)i(334)0 1677 y FJ(Differ)g FN(\(class)g(in)h(dif)n(\003ib\),)e(66,)g(72)0 1777 y FJ(difflib)g FN(\(standard)g(module\),)f FL(65)0 1876 y FJ(digest\(\))166 1976 y FN(hash)i(method,)f(320)166 2076 y(hmac)h(method,)e(321)166 2175 y(md5)h(method,)g(322)166 2275 y(sha)h(method,)f(323)0 2374 y FJ(digest_size)166 2474 y FN(data)h(in)g(hashlib,)g(320)166 2574 y(data)g(in)g(md5,)g(322) 166 2673 y(data)g(in)g(sha,)h(322)0 2773 y FJ(digit\(\))e FN(\(in)h(module)f(unicodedata\),)f(90)0 2873 y FJ(digits)i FN(\(data)f(in)i(string\),)e(47)0 2972 y FJ(dir\(\))166 3072 y FN(FTP)i(method,)d(639)166 3171 y(in)i(module)f(,)i(6)0 3271 y FJ(dircache)e FN(\(standard)g(module\),)f FL(340)0 3371 y FJ(dircmp)i FN(\(class)g(in)h(\002lecmp\),)e(333)0 3470 y FJ(Directory)g FN(\(class)i(in)f(msilib\),)g(937)0 3570 y(directory)166 3670 y(changing,)e(402)166 3769 y(creating,)h(404)166 3869 y(deleting,)g(339,)g(405)166 3968 y(site-packages,)g(850)166 4068 y(site-p)o(ython,)f(850)166 4168 y(tra)n(v)o(ersal,)h(407)166 4267 y(w)o(alking,)g(407)0 4367 y FJ(DirList)g FN(\(class)i(in)g(T)m(ix\),)e(727)0 4467 y FJ(dirname\(\))g FN(\(in)h(module)f(os.path\),)g(326)0 4566 y FJ(DirSelectBox)g FN(\(class)h(in)h(T)m(ix\),)e(727)0 4666 y FJ(DirSelectDialog)f FN(\(class)j(in)f(T)m(ix\),)g(727)0 4765 y FJ(DirTree)f FN(\(class)i(in)g(T)m(ix\),)e(727)0 4865 y FJ(dis\(\))166 4965 y FN(in)h(module)f(dis,)i(888)166 5064 y(in)f(module)f(pickletools,)g(896)0 5164 y FJ(dis)h FN(\(standard)f(module\),)f FL(888)0 5264 y FJ(disable\(\))166 5363 y FN(in)i(module)f(gc,)h(843)2158 83 y(in)g(module)f(logging,)f (452)1992 183 y FJ(disassemble\(\))g FN(\(in)i(module)f(dis\),)h(888) 1992 282 y FJ(discard\(\))2158 382 y FN(Mailbox)f(method,)f(219)2158 482 y(MH)i(method,)f(224)1992 581 y FJ(discard)g FN(\(Cookie)g(attrib)n (ute\),)g(678)1992 681 y FJ(discard_buffers\(\))e FN(\(async)p 3082 681 25 4 v 29 w(chat)j(method\),)e(596)1992 780 y FJ(disco\(\))h FN(\(in)h(module)f(dis\),)h(889)1992 880 y FJ(dispatch\(\))e FN(\(ASTV)-5 b(isitor)20 b(method\),)e(904)1992 980 y FJ(dispatcher)g FN(\(class)j(in)g(asyncore\),)d(593)1992 1079 y FJ(displayhook\(\))g FN(\(in)i(module)f(sys\),)h(828)1992 1179 y FJ(dist\(\))f FN(\(in)h(module)f(platform\),)f(494)1992 1279 y FJ(distb\(\))h FN(\(in)h(module)f(dis\),)h(888)1992 1378 y FJ(distutils)f FN(\(standard)f(module\),)g FL(896)1992 1478 y FJ(dither2grey2\(\))g FN(\(in)i(module)e(imageop\),)h(697)1992 1577 y FJ(dither2mono\(\))f FN(\(in)i(module)f(imageop\),)f(696)1992 1677 y FJ(div\(\))h FN(\(in)h(module)f(operator\),)f(183)1992 1777 y FJ(divide\(\))h FN(\(Conte)o(xt)g(method\),)f(161)1992 1876 y(di)n(vision)2158 1976 y(inte)o(ger)m(,)g(25)2158 2076 y(long)h(inte)o(ger)m(,)f(25)1992 2175 y FJ(DivisionByZero)g FN(\(class)i(in)h(decimal\),)e(162)1992 2275 y FJ(divmod\(\))2158 2374 y FN(Conte)o(xt)g(method,)g(161)2158 2474 y(in)h(module)f(,)h(6) 1992 2574 y FJ(dl)g FN(\(e)o(xtension)e(module\),)g FL(557)1992 2673 y FJ(DllCanUnloadNow\(\))f FN(\(in)j(module)f(ctypes\),)g(529)1992 2773 y FJ(DllGetClassObject\(\))e FN(\(in)j(module)f(ctypes\),)g(529) 1992 2873 y FJ(dllhandle)g FN(\(data)g(in)i(sys\),)f(828)1992 2972 y FJ(dngettext\(\))e FN(\(in)i(module)f(gette)o(xt\),)g(740)1992 3072 y FJ(do_command\(\))f FN(\(T)-6 b(e)o(xtbox)18 b(method\),)g(487) 1992 3171 y FJ(do_forms\(\))g FN(\(in)i(module)f(\003\),)i(919)1992 3271 y FJ(do_GET\(\))e FN(\(SimpleHTTPRequestHandler)e(method\),)h(670) 1992 3371 y FJ(do_HEAD\(\))76 b FN(\(SimpleHTTPRequestHandler)g (method\),)2324 3470 y(670)1992 3570 y FJ(do_POST\(\))19 b FN(\(CGIHTTPRequestHandler)e(method\),)i(671)1992 3670 y FJ(doc_header)f FN(\(Cmd)i(attrib)n(ute\),)f(759)1992 3769 y FJ(DocCGIXMLRPCRequestHandler)175 b FN(\(class)k(in)2324 3869 y(DocXMLRPCServ)o(er\),)18 b(691)1992 3968 y FJ(DocFileSuite\(\))g FN(\(in)i(module)e(doctest\),)i(778)1992 4068 y FJ(docmd\(\))f FN(\(SMTP)h(method\),)e(652)1992 4168 y FJ(docstring)h FN(\(DocT)-6 b(est)19 b(attrib)n(ute\),)h(781)1992 4267 y(docstrings,)e(877)1992 4367 y FJ(DocTest)h FN(\(class)i(in)f (doctest\),)f(781)1992 4467 y FJ(doctest)g FN(\(standard)g(module\),)f FL(764)1992 4566 y FJ(DocTestFailure)g FN(\(e)o(xception)g(in)i (doctest\),)f(788)1992 4666 y FJ(DocTestFinder)f FN(\(class)j(in)f (doctest\),)f(782)1992 4765 y FJ(DocTestParser)f FN(\(class)j(in)f (doctest\),)f(783)1992 4865 y FJ(DocTestRunner)f FN(\(class)j(in)f (doctest\),)f(783)1992 4965 y FJ(DocTestSuite\(\))f FN(\(in)i(module)e (doctest\),)i(779)1992 5064 y FJ(doctype\(\))f FN(\(XML)-8 b(T)m(reeBuilder)18 b(method\),)g(302)1992 5164 y(documentation)2158 5264 y(generation,)f(763)2158 5363 y(online,)i(763)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(981)p eop end %%Page: 982 994 TeXDict begin 982 993 bop 0 83 a FJ(documentElement)18 b FN(\(Document)g(attrib)n(ute\),)h(277)0 183 y FJ (DocXMLRPCRequestHandler)30 b FN(\(class)35 b(in)f(DocXMLR-)332 282 y(PCServ)o(er\),)19 b(691)0 382 y FJ(DocXMLRPCServer)166 482 y FN(class)i(in)g(DocXMLRPCServ)o(er)m(,)d(691)166 581 y(standard)h(module,)g FL(691)0 681 y FJ(domain_initial_dot)e FN(\(Cookie)j(attrib)n(ute\),)f(679)0 780 y FJ(domain_return_ok\(\))e FN(\(CookiePolic)o(y)i(method\),)f(675)0 880 y FJ(domain_specified)g FN(\(Cookie)h(attrib)n(ute\),)g(679)0 980 y FJ(DomainLiberal)f FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)h(678)0 1079 y FJ(DomainRFC2965Match)74 b FN(\(L)-6 b(WPCookieJar)76 b(attrib)n(ute\),)332 1179 y(678)0 1279 y FJ(DomainStrict)19 b FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)g(678)0 1378 y FJ(DomainStrictNoDots)74 b FN(\(L)-6 b(WPCookieJar)76 b(attrib)n(ute\),)332 1478 y(677)0 1577 y FJ(DomainStrictNonDomain)117 b FN(\(L)-6 b(WPCookieJar)119 b(at-)332 1677 y(trib)n(ute\),)19 b(677)0 1777 y FJ(DOMEventStream)f FN(\(class)j(in)f (xml.dom.pulldom\),)c(287)0 1876 y FJ(DOMException)j FN(\(e)o(xception)e(in)k(xml.dom\),)d(280)0 1976 y FJ(DomstringSizeErr) g FN(\(e)o(xception)g(in)i(xml.dom\),)e(280)0 2076 y FJ(done\(\))166 2175 y FN(in)i(module)f(turtle,)h(731)166 2275 y(Unpack)o(er)f(method,)f(316)0 2374 y FJ(DONT_ACCEPT_BLANKLINE)f FN(\(data)j(in)g(doctest\),)f(772)0 2474 y FJ(DONT_ACCEPT_TRUE_FOR_1)e FN(\(data)i(in)i(doctest\),)e(772)0 2574 y FJ(doRollover\(\))166 2673 y FN(RotatingFileHandler)f(method,)h(463)166 2773 y(T)m(imedRotatingFileHandler)e(method,)i(463)0 2873 y FJ(DOTALL)h FN(\(data)f(in)i(re\),)e(57)0 2972 y FJ(doublequote)g FN(\(Dialect)h(attrib)n(ute\),)f(306)0 3072 y FJ(doupdate\(\))g FN(\(in)h(module)f(curses\),)g(474)0 3171 y FJ(down\(\))h FN(\(in)g(module)e(turtle\),)i(731)0 3271 y FJ(drain\(\))f FN(\(audio)g(de)n(vice)h(method\),)e(931)0 3371 y FJ(dropwhile\(\))h FN(\(in)h(module)f(itertools\),)g(174)0 3470 y FJ(dst\(\))166 3570 y FN(datetime)h(method,)e(104)166 3670 y(time)i(method,)f(107,)g (108)0 3769 y FJ(DTDHandler)g FN(\(class)i(in)f(xml.sax.handler\),)d (289)0 3869 y FJ(dumbdbm)i FN(\(standard)g(module\),)f(375,)h FL(382)0 3968 y FJ(DumbWriter)g FN(\(class)i(in)f(formatter\),)e(912)0 4068 y FJ(dummy_thread)h FN(\(standard)f(module\),)g FL(546)0 4168 y FJ(dummy_threading)g FN(\(standard)h(module\),)f FL(547)0 4267 y FJ(dump\(\))166 4367 y FN(in)i(module)f(marshal,)h(374) 166 4467 y(in)g(module)f(pickle,)h(361)166 4566 y(in)g(module)f (xml.etree.ElementT)m(ree,)e(299)166 4666 y(Pickler)j(method,)f(362)0 4765 y FJ(dump_address_pair\(\))e FN(\(in)j(module)f(rfc822\),)f(248)0 4865 y FJ(dump_stats\(\))h FN(\(Stats)h(method\),)f(816)0 4965 y FJ(dumps\(\))166 5064 y FN(in)h(module)f(marshal,)h(374)166 5164 y(in)g(module)f(pickle,)h(361)166 5264 y(in)g(module)f(xmlrpclib,) g(687)0 5363 y FJ(dup\(\))2158 83 y FN(in)h(module)f(os,)h(399)2158 183 y(in)g(module)f(posix\002le,)g(564)1992 282 y FJ(dup2\(\))2158 382 y FN(in)h(module)f(os,)h(400)2158 482 y(in)g(module)f(posix\002le,) g(564)1992 581 y FJ(DuplicateSectionError)61 b FN(\(e)o(xception)h(in)i (Con\002g-)2324 681 y(P)o(arser\),)19 b(310)1992 873 y FE(E)1992 996 y FJ(e)2158 1096 y FN(data)h(in)g(cmath,)f(152)2158 1196 y(data)h(in)g(math,)g(151)1992 1295 y FJ(E2BIG)f FN(\(data)h(in)g(errno\),)f(495)1992 1395 y FJ(EACCES)g FN(\(data)h(in)g(errno\),)f(495)1992 1495 y FJ(EADDRINUSE)f FN(\(data)i(in)g(errno\),)f(499)1992 1594 y FJ(EADDRNOTAVAIL)f FN(\(data)i(in)g(errno\),)e(499)1992 1694 y FJ(EADV)i FN(\(data)f(in)i(errno\),)d(497)1992 1793 y FJ(EAFNOSUPPORT)g FN(\(data)i(in)g(errno\),)e(499)1992 1893 y FJ(EAGAIN)h FN(\(data)h(in)g(errno\),)f(495)1992 1993 y FJ(EAI_)2192 2008 y(*)2261 1993 y FN(\(data)h(in)g(sock)o(et\),)g(578)1992 2092 y FJ(EALREADY)f FN(\(data)g(in)i(errno\),)d(500)1992 2192 y FJ(east_asian_width\(\))f FN(\(in)j(module)f(unicodedata\),)e (90)1992 2292 y FJ(EBADE)i FN(\(data)h(in)g(errno\),)f(497)1992 2391 y FJ(EBADF)g FN(\(data)h(in)g(errno\),)f(495)1992 2491 y FJ(EBADFD)g FN(\(data)h(in)g(errno\),)f(498)1992 2590 y FJ(EBADMSG)g FN(\(data)h(in)g(errno\),)e(498)1992 2690 y FJ(EBADR)h FN(\(data)h(in)g(errno\),)f(497)1992 2790 y FJ(EBADRQC)g FN(\(data)h(in)g(errno\),)e(497)1992 2889 y FJ(EBADSLT)h FN(\(data)h(in)g(errno\),)e(497)1992 2989 y FJ(EBFONT)h FN(\(data)h(in)g(errno\),)f(497)1992 3089 y FJ(EBUSY)g FN(\(data)h(in)g(errno\),)f(495)1992 3188 y FJ(ECHILD)g FN(\(data)h(in)g(errno\),)f(495)1992 3288 y FJ(echo\(\))g FN(\(in)h(module)f(curses\),)h(474)1992 3387 y FJ(echochar\(\))e FN(\(windo)n(w)h(method\),)f(479)1992 3487 y FJ(ECHRNG)h FN(\(data)h(in)g(errno\),)f(496)1992 3587 y FJ(ECOMM)g FN(\(data)h(in)g(errno\),)f(498)1992 3686 y FJ(ECONNABORTED)f FN(\(data)i(in)g(errno\),)e(499)1992 3786 y FJ(ECONNREFUSED)g FN(\(data)i(in)g(errno\),)e(499)1992 3886 y FJ(ECONNRESET)g FN(\(data)i(in)g(errno\),)f(499)1992 3985 y FJ(EDEADLK)g FN(\(data)h(in)g(errno\),)e(496)1992 4085 y FJ(EDEADLOCK)h FN(\(data)g(in)i(errno\),)d(497)1992 4185 y FJ(EDESTADDRREQ)g FN(\(data)i(in)g(errno\),)e(498)1992 4284 y FJ(edit\(\))h FN(\(T)-6 b(e)o(xtbox)18 b(method\),)g(487)1992 4384 y FJ(EDOM)i FN(\(data)f(in)i(errno\),)d(496)1992 4483 y FJ(EDOTDOT)h FN(\(data)h(in)g(errno\),)e(498)1992 4583 y FJ(EDQUOT)h FN(\(data)h(in)g(errno\),)f(500)1992 4683 y FJ(EEXIST)g FN(\(data)h(in)g(errno\),)f(495)1992 4782 y FJ(EFAULT)g FN(\(data)h(in)g(errno\),)f(495)1992 4882 y FJ(EFBIG)g FN(\(data)h(in)g(errno\),)f(496)1992 4982 y FJ(ehlo\(\))g FN(\(SMTP)h(method\),)f(653)1992 5081 y FJ(EHOSTDOWN)g FN(\(data)g(in)i(errno\),)d(499)1992 5181 y FJ(EHOSTUNREACH)g FN(\(data)i(in)g(errno\),)e(499)1992 5280 y FJ(EIDRM)h FN(\(data)h(in)g(errno\),)f(496)1992 5380 y FJ(EILSEQ)g FN(\(data)h(in)g(errno\),)f(498)p 0 5549 3901 4 v 0 5649 a FI(982)3561 b(Inde)n(x)p eop end %%Page: 983 995 TeXDict begin 983 994 bop 0 83 a FJ(EINPROGRESS)19 b FN(\(data)g(in)i(errno\),)d(500)0 183 y FJ(EINTR)i FN(\(data)g(in)g (errno\),)e(495)0 282 y FJ(EINVAL)i FN(\(data)f(in)i(errno\),)d(495)0 382 y FJ(EIO)i FN(\(data)g(in)g(errno\),)f(495)0 482 y FJ(EISCONN)g FN(\(data)h(in)h(errno\),)d(499)0 581 y FJ(EISDIR)i FN(\(data)f(in)i(errno\),)d(495)0 681 y FJ(EISNAM)i FN(\(data)f(in)i(errno\),)d(500)0 780 y FJ(eject\(\))h FN(\(CD)i(player)e(method\),)g(917)0 880 y FJ(EL2HLT)h FN(\(data)f(in)i(errno\),)d(497)0 980 y FJ(EL2NSYNC)h FN(\(data)h(in)g(errno\),)f(496)0 1079 y FJ(EL3HLT)h FN(\(data)f(in)i(errno\),)d(496)0 1179 y FJ(EL3RST)i FN(\(data)f(in)i(errno\),)d(496)0 1279 y FJ(Element\(\))h FN(\(in)h(module)f(xml.etree.ElementT)m(ree\),)d(299)0 1378 y FJ(ElementDeclHandler\(\))h FN(\(xmlparser)h(method\),)h(267)0 1478 y FJ(ElementTree)g FN(\(class)h(in)h(xml.etree.ElementT)m(ree\),) 16 b(300)0 1577 y FJ(ELIBACC)j FN(\(data)h(in)h(errno\),)d(498)0 1677 y FJ(ELIBBAD)h FN(\(data)h(in)h(errno\),)d(498)0 1777 y FJ(ELIBEXEC)h FN(\(data)h(in)g(errno\),)f(498)0 1876 y FJ(ELIBMAX)g FN(\(data)h(in)h(errno\),)d(498)0 1976 y FJ(ELIBSCN)h FN(\(data)h(in)h(errno\),)d(498)0 2076 y(Ellinghouse,)g(Lance,)i(256)0 2175 y FJ(ELLIPSIS)f FN(\(data)h(in)g(doctest\),)g(773)0 2275 y FJ(Ellipsis)f FN(\(data)h(in)g(\),)g(22)0 2374 y FJ(EllipsisType)f FN(\(data)g(in)i(types\),)e(142)0 2474 y FJ(ELNRNG)h FN(\(data)f(in)i(errno\),)d(497)0 2574 y FJ(ELOOP)i FN(\(data)g(in)g (errno\),)e(496)0 2673 y FJ(email)i FN(\(standard)e(module\),)h FL(189)0 2773 y FJ(email.charset)f FN(\(standard)h(module\),)f FL(203)0 2873 y FJ(email.encoders)g FN(\(standard)h(module\),)f FL(206)0 2972 y FJ(email.errors)h FN(\(standard)f(module\),)g FL(206)0 3072 y FJ(email.generator)g FN(\(standard)h(module\),)f FL(198)0 3171 y FJ(email.header)h FN(\(standard)f(module\),)g FL(201)0 3271 y FJ(email.iterators)g FN(\(standard)h(module\),)f FL(209)0 3371 y FJ(email.message)g FN(\(standard)h(module\),)f FL(190)0 3470 y FJ(email.mime)h FN(\(standard)g(module\),)f FL(199)0 3570 y FJ(email.mime.audio)g FN(\(standard)g(module\),)h FL(199)0 3670 y FJ(email.mime.base)f FN(\(standard)h(module\),)f FL(199)0 3769 y FJ(email.mime.image)g FN(\(standard)g(module\),)h FL(199)0 3869 y FJ(email.mime.message)e FN(\(standard)i(module\),)f FL(199)0 3968 y FJ(email.mime.multipart)f FN(\(standard)i(module\),)f FL(199)0 4068 y FJ(email.mime.nonmultipart)74 b FN(\(standard)i (module\),)332 4168 y FL(199)0 4267 y FJ(email.mime.text)18 b FN(\(standard)h(module\),)f FL(199)0 4367 y FJ(email.parser)h FN(\(standard)f(module\),)g FL(196)0 4467 y FJ(email.utils)h FN(\(standard)f(module\),)h FL(207)0 4566 y FJ(EMFILE)h FN(\(data)f(in)i(errno\),)d(495)0 4666 y FJ(emit\(\))187 4765 y FN(method,)g(462)166 4865 y(Buf)n(feringHandler)f(method,)h(466) 166 4965 y(DatagramHandler)g(method,)g(464)166 5064 y(FileHandler)h (method,)g(462)166 5164 y(HTTPHandler)g(method,)f(466)166 5264 y(NTEv)o(entLogHandler)e(method,)j(465)166 5363 y(RotatingFileHandler)f(method,)h(463)2158 83 y(SMTPHandler)g(method,)f (465)2158 183 y(Sock)o(etHandler)g(method,)g(464)2158 282 y(StreamHandler)g(method,)g(462)2158 382 y(SysLogHandler)f(method,) i(464)2158 482 y(T)m(imedRotatingFileHandler)e(method,)h(463)1992 581 y FJ(EMLINK)h FN(\(data)h(in)g(errno\),)f(496)1992 681 y FJ(Empty)g FN(\(e)o(xception)f(in)j(Queue\),)d(133)1992 780 y FJ(empty\(\))2158 880 y FN(Queue)h(method,)g(133)2158 980 y(scheduler)f(method,)h(132)1992 1079 y FJ(EMPTY_NAMESPACE)e FN(\(data)j(in)h(xml.dom\),)c(273)1992 1179 y FJ(emptyline\(\))h FN(\(Cmd)i(method\),)e(758)1992 1279 y FJ(EMSGSIZE)h FN(\(data)g(in)i(errno\),)d(498)1992 1378 y FJ(EMULTIHOP)h FN(\(data)g(in)i(errno\),)d(498)1992 1478 y FJ(enable\(\))2158 1577 y FN(in)i(module)f(cgitb,)g(610)2158 1677 y(in)h(module)f(gc,)h (843)1992 1777 y FJ(enable_callback_tracebacks\(\))80 b FN(\(in)86 b(module)2324 1876 y(sqlite3\),)19 b(386)1992 1976 y FJ(ENAMETOOLONG)f FN(\(data)i(in)g(errno\),)e(496)1992 2076 y FJ(ENAVAIL)h FN(\(data)h(in)g(errno\),)e(500)1992 2175 y FJ(enclose\(\))h FN(\(windo)n(w)f(method\),)h(479)1992 2275 y(encode)2158 2374 y(Codecs,)g(77)1992 2474 y FJ(encode\(\))2178 2574 y FN(method,)g(81)2158 2673 y(Binary)g(method,)g(686)2158 2773 y(Header)g(method,)g(203)2158 2873 y(in)h(module)f(base64,)g(252) 2158 2972 y(in)h(module)f(mimetools,)g(240)2158 3072 y(in)h(module)f(quopri,)f(255)2158 3171 y(in)i(module)f(uu,)g(256)2158 3271 y(IncrementalEncoder)c(method,)k(82)2158 3371 y(Serv)o(erProxy)e (method,)i(686)2158 3470 y(string)g(method,)g(29)1992 3570 y FJ(encode_7or8bit\(\))e FN(\(in)j(module)f(email.encoders\),)f (206)1992 3670 y FJ(encode_base64\(\))f FN(\(in)j(module)f (email.encoders\),)f(206)1992 3769 y FJ(encode_noop\(\))g FN(\(in)i(module)f(email.encoders\),)e(206)1992 3869 y FJ(encode_quopri\(\))g FN(\(in)j(module)f(email.encoders\),)f(206) 1992 3968 y FJ(encode_rfc2231\(\))f FN(\(in)j(module)f(email.utils\),)h (209)1992 4068 y FJ(encoded_header_len\(\))d FN(\(Charset)j(method\),)e (205)1992 4168 y FJ(EncodedFile\(\))g FN(\(in)i(module)f(codecs\),)g (80)1992 4267 y FJ(encodePriority\(\))e FN(\(SysLogHandler)h(method\),) g(465)1992 4367 y FJ(encodestring\(\))2158 4467 y FN(in)i(module)f (base64,)g(252)2158 4566 y(in)h(module)f(quopri,)f(255)1992 4666 y(encoding)2158 4765 y(base64,)h(251)2158 4865 y (quoted-printable,)d(255)1992 4965 y FJ(encoding)j FN(\(\002le)h (attrib)n(ute\),)f(41)1992 5064 y FJ(encodings.idna)f FN(\(standard)g(module\),)h FL(89)1992 5164 y FJ(encodings.utf-8-sig)e FN(\(standard)h(module\),)h FL(90)1992 5264 y FJ(encodings_map)f FN(\(data)i(in)g(mimetypes\),)e(242)1992 5363 y FJ(end\(\))p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(983)p eop end %%Page: 984 996 TeXDict begin 984 995 bop 166 83 a FN(MatchObject)19 b(method,)g(61)166 183 y(T)m(reeBuilder)g(method,)g(301)0 282 y FJ(end_fill\(\))g FN(\(in)h(module)f(turtle\),)g(731)0 382 y FJ(end_group\(\))g FN(\(form)f(method\),)h(921)0 482 y FJ(end_headers\(\))14 b FN(\(BaseHTTPRequestHandler)f(method\),) 332 581 y(669)0 681 y FJ(end_marker\(\))19 b FN(\(MultiFile)h (method\),)e(246)0 780 y FJ(end_paragraph\(\))g FN(\(formatter)g (method\),)g(909)0 880 y FJ(EndCdataSectionHandler\(\))23 b FN(\(xmlparser)j(method\),)332 980 y(268)0 1079 y FJ (EndDoctypeDeclHandler\(\))49 b FN(\(xmlparser)h(method\),)332 1179 y(267)0 1279 y FJ(endDocument\(\))18 b FN(\(ContentHandler)g (method\),)g(291)0 1378 y FJ(endElement\(\))h FN(\(ContentHandler)e (method\),)h(292)0 1478 y FJ(EndElementHandler\(\))f FN(\(xmlparser)i(method\),)f(267)0 1577 y FJ(endElementNS\(\))g FN(\(ContentHandler)g(method\),)g(292)0 1677 y FJ(endheaders\(\))h FN(\(HTTPResponse)g(method\),)f(635)0 1777 y FJ (EndNamespaceDeclHandler\(\))299 b FN(\(xmlparser)332 1876 y(method\),)18 b(268)0 1976 y FJ(endpick\(\))h FN(\(in)h(module)f (gl\),)h(926)0 2076 y FJ(endpos)g FN(\(MatchObject)e(attrib)n(ute\),)i (61)0 2175 y FJ(endPrefixMapping\(\))75 b FN(\(ContentHandler)g (method\),)332 2275 y(291)0 2374 y FJ(endselect\(\))19 b FN(\(in)h(module)f(gl\),)g(926)0 2474 y FJ(endswith\(\))g FN(\(string)g(method\),)g(29)0 2574 y FJ(endwin\(\))g FN(\(in)h(module)f(curses\),)h(474)0 2673 y FJ(ENETDOWN)f FN(\(data)h(in)g(errno\),)f(499)0 2773 y FJ(ENETRESET)g FN(\(data)h(in)g(errno\),)e(499)0 2873 y FJ(ENETUNREACH)h FN(\(data)g(in)i(errno\),)d(499)0 2972 y FJ(ENFILE)i FN(\(data)f(in)i(errno\),)d(495)0 3072 y FJ(ENOANO)i FN(\(data)f(in)i(errno\),)d(497)0 3171 y FJ(ENOBUFS)h FN(\(data)h(in)h(errno\),)d(499)0 3271 y FJ(ENOCSI)i FN(\(data)f(in)i(errno\),)d(497)0 3371 y FJ(ENODATA)h FN(\(data)h(in)h(errno\),)d(497)0 3470 y FJ(ENODEV)i FN(\(data)f(in)i(errno\),)d(495)0 3570 y FJ(ENOENT)i FN(\(data)f(in)i(errno\),)d(494)0 3670 y FJ(ENOEXEC)h FN(\(data)h(in)h(errno\),)d(495)0 3769 y FJ(ENOLCK)i FN(\(data)f(in)i(errno\),)d(496)0 3869 y FJ(ENOLINK)h FN(\(data)h(in)h(errno\),)d(497)0 3968 y FJ(ENOMEM)i FN(\(data)f(in)i(errno\),)d(495)0 4068 y FJ(ENOMSG)i FN(\(data)f(in)i(errno\),)d(496)0 4168 y FJ(ENONET)i FN(\(data)f(in)i(errno\),)d(497)0 4267 y FJ(ENOPKG)i FN(\(data)f(in)i(errno\),)d(497)0 4367 y FJ(ENOPROTOOPT)h FN(\(data)g(in)i(errno\),)d(499)0 4467 y FJ(ENOSPC)i FN(\(data)f(in)i(errno\),)d(496)0 4566 y FJ(ENOSR)i FN(\(data)g(in)g (errno\),)e(497)0 4666 y FJ(ENOSTR)i FN(\(data)f(in)i(errno\),)d(497)0 4765 y FJ(ENOSYS)i FN(\(data)f(in)i(errno\),)d(496)0 4865 y FJ(ENOTBLK)h FN(\(data)h(in)h(errno\),)d(495)0 4965 y FJ(ENOTCONN)h FN(\(data)h(in)g(errno\),)f(499)0 5064 y FJ(ENOTDIR)g FN(\(data)h(in)h(errno\),)d(495)0 5164 y FJ(ENOTEMPTY)h FN(\(data)h(in)g(errno\),)e(496)0 5264 y FJ(ENOTNAM)h FN(\(data)h(in)h(errno\),)d(500)0 5363 y FJ(ENOTSOCK)h FN(\(data)h(in)g(errno\),)f(498)1992 83 y FJ(ENOTTY)g FN(\(data)h(in)g(errno\),)f(495)1992 183 y FJ(ENOTUNIQ)g FN(\(data)g(in)i(errno\),)d(498)1992 282 y FJ(enter\(\))h FN(\(scheduler)f(method\),)h(132)1992 382 y FJ(enterabs\(\))f FN(\(scheduler)h(method\),)f(131)1992 482 y FJ(entities)h FN(\(DocumentT)-7 b(ype)17 b(attrib)n(ute\),)i(277) 1992 581 y FJ(EntityDeclHandler\(\))e FN(\(xmlparser)h(method\),)g(268) 1992 681 y FJ(entitydefs)g FN(\(data)i(in)g(htmlentitydefs\),)e(264) 1992 780 y FJ(EntityResolver)g FN(\(class)i(in)h(xml.sax.handler\),)16 b(289)1992 880 y FJ(enumerate\(\))2158 980 y FN(in)k(module)f(,)h(7) 2158 1079 y(in)g(module)f(fm,)g(924)2158 1179 y(in)h(module)f (threading,)f(538)1992 1279 y FJ(EnumKey\(\))h FN(\(in)h(module)p 2848 1279 25 4 v 48 w(winre)o(g\),)f(941)1992 1378 y FJ(EnumValue\(\))f FN(\(in)i(module)p 2948 1378 V 49 w(winre)o(g\),)e(942)1992 1478 y FJ(environ)2158 1577 y FN(data)i(in)g(os,)g(396)2158 1677 y(data)g(in)g(posix,)f(554)1992 1777 y(en)m(vironment)e(v)n(ariables)2158 1876 y(\241protocol\277)p 2507 1876 V 27 w(proxy,)h(624)2158 1976 y(A)-5 b(UDIODEV,)20 b(708)2158 2076 y(BR)m(O)m(WSER,)h(600)2158 2175 y(COLUMNS,)f(478)2158 2275 y(COMSPEC,)h(412,)e(572)2158 2374 y(HOMEDRIVE,)g(326)2158 2474 y(HOMEP)-8 b(A)f(TH,)19 b(326)2158 2574 y(HOME,)g(326,)h(851)2158 2673 y(KDEDIR,)g(601)2158 2773 y(LANGU)m(A)m(GE,)f(739,)g(741)2158 2873 y(LANG,)h(739,)f(741,)g(749,)g(750)2158 2972 y(LC)p 2269 2972 V 30 w(ALL,)g(739,)g(741)2158 3072 y(LC)p 2269 3072 V 30 w(MESSA)m(GES,)g(739,)g(741)2158 3171 y(LINES,)g(478)2158 3271 y(LN)m(AME,)g(472)2158 3371 y(LOGN)m(AME,)g(397,)g(472)2158 3470 y(MIXERDEV,)g(708)2158 3570 y(P)-8 b(A)m(GER,)20 b(807)2158 3670 y(P)-8 b(A)f(TH,)20 b(409,)f(411,)g(415,)g(607,)g(609) 2158 3769 y(PYTHONDOCS,)h(764)2158 3869 y(PYTHONP)-8 b(A)f(TH,)20 b(607,)f(831)2158 3968 y(PYTHONST)-8 b(AR)j(TUP,)20 b(550,)f(551,)g(851)2158 4068 y(PYTHONY2K,)g(415,)g(416)2158 4168 y(PYTHON)p 2500 4168 V 29 w(DOM,)h(273)2158 4267 y(TEMP,)f(336)2158 4367 y(TIX)p 2302 4367 V 29 w(LIBRAR)-5 b(Y,)20 b(725)2158 4467 y(TMPDIR,)g(336,)f(406)2158 4566 y(TMP,)h(336,)f(406)2158 4666 y(TZ,)h(419,)f(420)2158 4765 y(USERN)m(AME,)h(472)2158 4865 y(USER,)g(472)2158 4965 y(W)m(imp$ScrapDir,)e(336)2158 5064 y(ftp)p 2256 5064 V 29 w(proxy,)g(617)2158 5164 y(gopher)p 2396 5164 V 27 w(proxy,)g(617)2158 5264 y(http)p 2293 5264 V 29 w(proxy,)g(617,)h(631)2158 5363 y(deleting,)g(398)p 0 5549 3901 4 v 0 5649 a FI(984)3561 b(Inde)n(x)p eop end %%Page: 985 997 TeXDict begin 985 996 bop 166 83 a FN(setting,)20 b(397)0 183 y FJ(EnvironmentError)e FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e (18)0 282 y FJ(ENXIO)i FN(\(data)g(in)g(errno\),)e(495)0 382 y FJ(eof)i FN(\(shle)o(x)g(attrib)n(ute\),)f(761)0 482 y FJ(EOFError)g FN(\(e)o(xception)f(in)j(e)o(xceptions\),)d(18)0 581 y FJ(EOPNOTSUPP)h FN(\(data)h(in)g(errno\),)e(499)0 681 y FJ(EOVERFLOW)h FN(\(data)h(in)g(errno\),)e(498)0 780 y FJ(EPERM)i FN(\(data)g(in)g(errno\),)e(494)0 880 y FJ(EPFNOSUPPORT)h FN(\(data)g(in)i(errno\),)d(499)0 980 y FJ(epilogue)h FN(\(data)h(in)g(email.message\),)f(195)0 1079 y FJ(EPIPE)h FN(\(data)g(in)g(errno\),)e(496)0 1179 y(epoch,)h(415)0 1279 y FJ(EPROTO)h FN(\(data)f(in)i(errno\),)d(498)0 1378 y FJ(EPROTONOSUPPORT)g FN(\(data)i(in)g(errno\),)e(499)0 1478 y FJ(EPROTOTYPE)h FN(\(data)h(in)g(errno\),)e(498)0 1577 y FJ(eq\(\))i FN(\(in)g(module)f(operator\),)f(183)0 1677 y FJ(ERA)i FN(\(data)g(in)g(locale\),)g(753)0 1777 y FJ(ERA_D_FMT)f FN(\(data)h(in)g(locale\),)g(753)0 1876 y FJ(ERA_D_T_FMT)f FN(\(data)g(in)i(locale\),)e(753)0 1976 y FJ(ERA_YEAR)g FN(\(data)h(in)g(locale\),)g(753)0 2076 y FJ(ERANGE)g FN(\(data)f(in)i(errno\),)d(496)0 2175 y FJ(erase\(\))h FN(\(windo)n(w)g(method\),)f(479)0 2275 y FJ(erasechar\(\))h FN(\(in)h(module)f(curses\),)g(474)0 2374 y FJ(EREMCHG)g FN(\(data)h(in)h(errno\),)d(498)0 2474 y FJ(EREMOTE)h FN(\(data)h(in)h(errno\),)d(497)0 2574 y FJ(EREMOTEIO)h FN(\(data)h(in)g(errno\),)e(500)0 2673 y FJ(ERESTART)h FN(\(data)h(in)g(errno\),)f(498)0 2773 y FJ(EROFS)h FN(\(data)g(in)g(errno\),)e(496)0 2873 y FJ(ERR)i FN(\(data)g(in)g(curses\),)g(483)0 2972 y FJ(errcheck)f FN(\()p 452 2972 25 4 v 30 w(FuncPtr)g(attrib)n(ute\),)h (525)0 3072 y FJ(errcode)f FN(\(Serv)o(erProxy)f(attrib)n(ute\),)h(686) 0 3171 y FJ(errmsg)h FN(\(Serv)o(erProxy)d(attrib)n(ute\),)i(687)0 3271 y FJ(errno)166 3371 y FN(b)n(uilt-in)h(module,)e(395,)h(578)166 3470 y(standard)g(module,)g FL(494)0 3570 y FJ(ERROR)h FN(\(data)g(in)g(cd\),)f(916)0 3670 y FJ(Error)166 3769 y FN(class)i(in)g(mailbox,)d(234)166 3869 y(e)o(xception)g(in)j (binascii,)e(255)166 3968 y(e)o(xception)f(in)j(binhe)o(x,)d(253)166 4068 y(e)o(xception)g(in)j(csv)-5 b(,)19 b(306)166 4168 y(e)o(xception)f(in)j(locale,)e(749)166 4267 y(e)o(xception)f(in)j (shutil,)f(339)166 4367 y(e)o(xception)e(in)j(sunau,)e(700)166 4467 y(e)o(xception)f(in)j(turtle,)e(732)166 4566 y(e)o(xception)f(in)j (uu,)e(256)166 4666 y(e)o(xception)f(in)j(w)o(a)n(v)o(e,)f(702)166 4765 y(e)o(xception)e(in)j(webbro)n(wser)m(,)d(600)166 4865 y(e)o(xception)g(in)j(xdrlib,)e(317)0 4965 y FJ(error\(\))187 5064 y FN(method,)f(455)166 5164 y(ErrorHandler)f(method,)i(293)166 5264 y(F)o(older)g(method,)g(238)166 5363 y(in)h(module)f(logging,)f (452)2158 83 y(MH)i(method,)f(238)2158 183 y(OpenerDirector)e(method,)i (626)1992 282 y FJ(error)2158 382 y FN(e)o(xception)f(in)i(an)o(ydbm,)e (375)2158 482 y(e)o(xception)g(in)i(audioop,)e(693)2158 581 y(e)o(xception)g(in)i(cd,)g(916)2158 681 y(e)o(xception)e(in)i (curses,)g(473)2158 780 y(e)o(xception)e(in)i(dbhash,)f(379)2158 880 y(e)o(xception)f(in)i(dbm,)f(377)2158 980 y(e)o(xception)f(in)i (dl,)g(557)2158 1079 y(e)o(xception)e(in)i(dumbdbm,)d(382)2158 1179 y(e)o(xception)h(in)i(gdbm,)f(377)2158 1279 y(e)o(xception)f(in)i (getopt,)f(448)2158 1378 y(e)o(xception)f(in)i(imageop,)f(696)2158 1478 y(e)o(xception)f(in)i(img\002le,)g(927)2158 1577 y(e)o(xception)e(in)i(jpe)o(g,)f(928)2158 1677 y(e)o(xception)f(in)i (nis,)h(568)2158 1777 y(e)o(xception)d(in)i(os,)h(395)2158 1876 y(e)o(xception)d(in)i(re,)g(59)2158 1976 y(e)o(xception)e(in)i (resource,)f(565)2158 2076 y(e)o(xception)f(in)i(r)o(gbimg,)e(706)2158 2175 y(e)o(xception)g(in)i(select,)h(535)2158 2275 y(e)o(xception)d(in) i(sock)o(et,)g(577)2158 2374 y(e)o(xception)e(in)i(struct,)g(63)2158 2474 y(e)o(xception)e(in)i(sunaudiode)n(v)-5 b(,)17 b(931)2158 2574 y(e)o(xception)h(in)i(thread,)f(537)2158 2673 y(e)o(xception)f(in) i(xml.parsers.e)o(xpat,)d(264)2158 2773 y(e)o(xception)h(in)i (zip\002le,)g(348)2158 2873 y(e)o(xception)e(in)i(zlib,)g(343)1992 2972 y FJ(error_body)e FN(\(BaseHandler)i(attrib)n(ute\),)f(616)1992 3072 y FJ(error_headers)f FN(\(BaseHandler)h(attrib)n(ute\),)g(616)1992 3171 y FJ(error_leader\(\))f FN(\(shle)o(x)h(method\),)f(760)1992 3271 y FJ(error_message_format)36 b FN(\(BaseHTTPRequestHand-)2324 3371 y(ler)20 b(attrib)n(ute\),)f(668)1992 3470 y FJ(error_output\(\))f FN(\(BaseHandler)h(method\),)f(616)1992 3570 y FJ(error_perm)g FN(\(e)o(xception)g(in)j(ftplib\),)e(637)1992 3670 y FJ(error_proto)2158 3769 y FN(e)o(xception)f(in)i(ftplib,)g(637)2158 3869 y(e)o(xception)e(in)i(poplib,)f(640)1992 3968 y FJ(error_reply)f FN(\(e)o(xception)g(in)j(ftplib\),)e(637)1992 4068 y FJ(error_status)f FN(\(BaseHandler)h(attrib)n(ute\),)g(616)1992 4168 y FJ(error_temp)f FN(\(e)o(xception)g(in)j(ftplib\),)e(637)1992 4267 y FJ(ErrorByteIndex)f FN(\(xmlparser)g(attrib)n(ute\),)h(266)1992 4367 y FJ(ErrorCode)g FN(\(xmlparser)f(attrib)n(ute\),)h(266)1992 4467 y FJ(errorcode)g FN(\(data)g(in)i(errno\),)d(494)1992 4566 y FJ(ErrorColumnNumber)f FN(\(xmlparser)h(attrib)n(ute\),)i(266) 1992 4666 y FJ(ErrorHandler)e FN(\(class)j(in)f(xml.sax.handler\),)d (289)1992 4765 y FJ(errorlevel)h FN(\(T)-7 b(arFile)21 b(attrib)n(ute\),)e(355)1992 4865 y FJ(ErrorLineNumber)e FN(\(xmlparser)i(attrib)n(ute\),)g(266)1992 4965 y(Errors)2158 5064 y(logging,)f(450)1992 5164 y FJ(errors)h FN(\(T)-6 b(estResult)21 b(attrib)n(ute\),)e(799)1992 5264 y FJ(ErrorString\(\))f FN(\(in)i(module)f(xml.parsers.e)o(xpat\),)d(264)1992 5363 y FJ(escape\(\))p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(985)p eop end %%Page: 986 998 TeXDict begin 986 997 bop 166 83 a FN(in)20 b(module)f(cgi,)h(607)166 183 y(in)g(module)f(re,)h(59)166 282 y(in)g(module)f(xml.sax.saxutils,) g(294)0 382 y FJ(escape)h FN(\(shle)o(x)f(attrib)n(ute\),)g(761)0 482 y FJ(escapechar)g FN(\(Dialect)h(attrib)n(ute\),)f(306)0 581 y FJ(escapedquotes)f FN(\(shle)o(x)i(attrib)n(ute\),)f(761)0 681 y FJ(ESHUTDOWN)g FN(\(data)h(in)g(errno\),)e(499)0 780 y FJ(ESOCKTNOSUPPORT)g FN(\(data)i(in)g(errno\),)e(499)0 880 y FJ(ESPIPE)i FN(\(data)f(in)i(errno\),)d(496)0 980 y FJ(ESRCH)i FN(\(data)g(in)g(errno\),)e(495)0 1079 y FJ(ESRMNT)i FN(\(data)f(in)i(errno\),)d(497)0 1179 y FJ(ESTALE)i FN(\(data)f(in)i(errno\),)d(500)0 1279 y FJ(ESTRPIPE)h FN(\(data)h(in)g(errno\),)f(498)0 1378 y FJ(ETIME)h FN(\(data)g(in)g(errno\),)e(497)0 1478 y FJ(ETIMEDOUT)h FN(\(data)h(in)g(errno\),)e(499)0 1577 y FJ(Etiny\(\))h FN(\(Conte)o(xt)h(method\),)e(160)0 1677 y FJ(ETOOMANYREFS)h FN(\(data)g(in)i(errno\),)d(499)0 1777 y FJ(Etop\(\))i FN(\(Conte)o(xt)f(method\),)f(160)0 1876 y FJ(ETXTBSY)h FN(\(data)h(in)h(errno\),)d(496)0 1976 y FJ(EUCLEAN)h FN(\(data)h(in)h(errno\),)d(500)0 2076 y FJ(EUNATCH)h FN(\(data)h(in)h(errno\),)d(497)0 2175 y FJ(EUSERS)i FN(\(data)f(in)i(errno\),)d(498)0 2275 y FJ(eval\(\))166 2374 y FN(b)n(uilt-in)i(function,)e(44,)h(50,)h (146,)f(875)166 2474 y(in)h(module)f(,)i(7)0 2574 y FJ(Event\(\))e FN(\(in)h(module)f(threading\),)f(539)0 2673 y FJ(Event)i FN(\(class)h(in)f(threading\),)e(544)0 2773 y FJ(event\(\))h FN(\(Control)h(method\),)e(938)0 2873 y(e)n(v)o(ent)h(scheduling,)g (131)0 2972 y(e)n(v)o(ents)h(\(widgets\),)f(723)0 3072 y FJ(EWOULDBLOCK)g FN(\(data)g(in)i(errno\),)d(496)0 3171 y FJ(EX_CANTCREAT)h FN(\(data)g(in)i(os\),)f(409)0 3271 y FJ(EX_CONFIG)f FN(\(data)h(in)g(os\),)g(410)0 3371 y FJ(EX_DATAERR)f FN(\(data)h(in)g(os\),)g(409)0 3470 y FJ(EX_IOERR)f FN(\(data)h(in)g(os\),)g(410)0 3570 y FJ(EX_NOHOST)f FN(\(data)h(in)g(os\),)g(409)0 3670 y FJ(EX_NOINPUT)f FN(\(data)h(in)g(os\),)g(409)0 3769 y FJ(EX_NOPERM)f FN(\(data)h(in)g(os\),)g(410)0 3869 y FJ(EX_NOTFOUND)f FN(\(data)g(in)i(os\),)f(410)0 3968 y FJ(EX_NOUSER)f FN(\(data)h(in)g(os\),)g(409)0 4068 y FJ(EX_OK)g FN(\(data)g(in)g(os\),)g(409)0 4168 y FJ(EX_OSERR)f FN(\(data)h(in)g(os\),)g(409)0 4267 y FJ(EX_OSFILE)f FN(\(data)h(in)g(os\),)g(409)0 4367 y FJ(EX_PROTOCOL)f FN(\(data)g(in)i(os\),)f(410)0 4467 y FJ(EX_SOFTWARE)f FN(\(data)g(in)i(os\),)f(409)0 4566 y FJ(EX_TEMPFAIL)f FN(\(data)g(in)i(os\),)f(410)0 4666 y FJ(EX_UNAVAILABLE)e FN(\(data)i(in)g(os\),)g(409)0 4765 y FJ(EX_USAGE)f FN(\(data)h(in)g (os\),)g(409)0 4865 y FJ(Example)f FN(\(class)i(in)g(doctest\),)e(781)0 4965 y FJ(example)166 5064 y FN(DocT)-6 b(estF)o(ailure)19 b(attrib)n(ute,)h(788)166 5164 y(Une)o(xpectedException)c(attrib)n (ute,)j(788)0 5264 y FJ(examples)g FN(\(DocT)-6 b(est)20 b(attrib)n(ute\),)f(781)0 5363 y FJ(exc_clear\(\))g FN(\(in)h(module)f (sys\),)h(829)1992 83 y FJ(exc_info\(\))e FN(\(in)i(module)f(sys\),)h (828)1992 183 y FJ(exc_info)f FN(\(Une)o(xpectedException)c(attrib)n (ute\),)k(788)1992 282 y FJ(exc_msg)g FN(\(Example)g(attrib)n(ute\),)g (782)1992 382 y FJ(exc_traceback)f FN(\(data)i(in)g(sys\),)g(829)1992 482 y FJ(exc_type)f FN(\(data)g(in)i(sys\),)f(829)1992 581 y FJ(exc_value)f FN(\(data)g(in)i(sys\),)f(829)1992 681 y FJ(excel)f FN(\(class)i(in)f(csv\),)g(305)1992 780 y FJ(excel_tab)f FN(\(class)h(in)h(csv\),)f(305)1992 880 y FJ(except)2158 980 y FN(statement,)f(17)1992 1079 y FJ(excepthook\(\))2158 1179 y FN(in)h(module)f(sys,)h(610)2158 1279 y(in)g(module)f(sys,)h(828)1992 1378 y FJ(Exception)f FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(18)1992 1478 y FJ(exception\(\))2178 1577 y FN(method,)h(455)2158 1677 y(in)h(module)f(logging,)f(452)1992 1777 y(e)o(xceptions)2158 1876 y(b)n(uilt-in,)h(3)2158 1976 y(in)h(CGI)h(scripts,)f(609)1992 2076 y FJ(exceptions)e FN(\(standard)h(module\),)f FL(17)1992 2175 y FJ(EXDEV)h FN(\(data)h(in)g(errno\),)f(495)1992 2275 y FJ(exec)2158 2374 y FN(statement,)g(44)1992 2474 y FJ(exec_prefix)f FN(\(data)i(in)g(sys\),)h(829)1992 2574 y FJ(execfile\(\))2158 2673 y FN(b)n(uilt-in)e(function,)f(851) 2158 2773 y(in)i(module)f(,)h(7)1992 2873 y FJ(execl\(\))f FN(\(in)h(module)f(os\),)h(408)1992 2972 y FJ(execle\(\))f FN(\(in)h(module)f(os\),)h(408)1992 3072 y FJ(execlp\(\))f FN(\(in)h(module)f(os\),)h(408)1992 3171 y FJ(execlpe\(\))f FN(\(in)h(module)e(os\),)i(408)1992 3271 y FJ(executable)e FN(\(data)i(in)g(sys\),)h(829)1992 3371 y FJ(Execute\(\))e FN(\(Binary)g(method\),)f(935)1992 3470 y FJ(execute\(\))h FN(\()h(method\),)e(386,)h(389)1992 3570 y FJ(executemany\(\))f FN(\()i(method\),)e(386,)i(389)1992 3670 y FJ(executescript\(\))d FN(\()k(method\),)d(386,)h(389)1992 3769 y FJ(execv\(\))g FN(\(in)h(module)f(os\),)h(408)1992 3869 y FJ(execve\(\))f FN(\(in)h(module)f(os\),)h(408)1992 3968 y FJ(execvp\(\))f FN(\(in)h(module)f(os\),)h(408)1992 4068 y FJ(execvpe\(\))f FN(\(in)h(module)e(os\),)i(408)1992 4168 y FJ(ExFileSelectBox)d FN(\(class)k(in)g(T)m(ix\),)e(727)1992 4267 y FJ(EXFULL)g FN(\(data)h(in)g(errno\),)f(497)1992 4367 y FJ(exists\(\))g FN(\(in)h(module)f(os.path\),)f(326)1992 4467 y FJ(exit\(\))2158 4566 y FN(in)i(module)f(sys,)h(829)2158 4666 y(in)g(module)f(thread,)g (537)1992 4765 y FJ(exitfunc)2158 4865 y FN(data)h(in)g(sys,)h(829)2158 4965 y(in)f(sys,)h(839)1992 5064 y FJ(exp\(\))2158 5164 y FN(in)f(module)f(cmath,)g(152)2158 5264 y(in)h(module)f(math,)g(150) 1992 5363 y FJ(expand\(\))g FN(\(MatchObject)g(method\),)f(60)p 0 5549 3901 4 v 0 5649 a FI(986)3561 b(Inde)n(x)p eop end %%Page: 987 999 TeXDict begin 987 998 bop 0 83 a FJ(expand_tabs)19 b FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(76)0 183 y FJ(expandNode\(\))g FN(\(DOMEv)o(entStream)e(method\),)h(287)0 282 y FJ(expandtabs\(\))166 382 y FN(in)i(module)f(string,)h(50)166 482 y(string)g(method,)e(29)0 581 y FJ(expanduser\(\))h FN(\(in)h(module)e(os.path\),)h(326)0 681 y FJ(expandvars\(\))g FN(\(in)h(module)e(os.path\),)h(326)0 780 y(Expat,)g(264)0 880 y FJ(ExpatError)g FN(\(e)o(xception)f(in)i(xml.parsers.e)o(xpat\),) d(264)0 980 y FJ(expect\(\))i FN(\(T)-6 b(elnet)20 b(method\),)e(658)0 1079 y FJ(expires)h FN(\(Cookie)h(attrib)n(ute\),)f(678)0 1179 y FJ(expovariate\(\))f FN(\(in)i(module)f(random\),)f(171)0 1279 y FJ(expr\(\))i FN(\(in)g(module)e(parser\),)h(874)0 1378 y FJ(expunge\(\))g FN(\(IMAP4)p 752 1378 25 4 v 29 w(stream)h(method\),)e(644)0 1478 y FJ(extend\(\))187 1577 y FN(method,)g(117)166 1677 y(array)h(method,)g(126)166 1777 y(list)i(method,)e(35)0 1876 y FJ(extend_path\(\))f FN(\(in)i(module)f(pkgutil\),)g(870)0 1976 y(e)o(xtended)f(slice)166 2076 y(assignment,)h(35)166 2175 y(operation,)f(28)0 2275 y FJ(ExtendedContext)g FN(\(class)j(in)f(decimal\),)f(159)0 2374 y FJ(extendleft\(\))g FN(\()h(method\),)e(117)0 2474 y FJ(extensions_map)56 b FN(\(SimpleHTTPRequestHandler)g(at-)332 2574 y(trib)n(ute\),)19 b(670)0 2673 y(External)g(Data)i (Representation,)d(315,)h(360)0 2773 y FJ(external_attr)f FN(\(ZipInfo)g(attrib)n(ute\),)i(351)0 2873 y FJ(ExternalClashError)d FN(\(class)k(in)g(mailbox\),)d(234)0 2972 y FJ (ExternalEntityParserCreate\(\))149 b FN(\(xmlparser)332 3072 y(method\),)18 b(265)0 3171 y FJ(ExternalEntityRefHandler\(\))249 b FN(\(xmlparser)332 3271 y(method\),)18 b(268)0 3371 y FJ(extra)i FN(\(ZipInfo)e(attrib)n(ute\),)h(351)0 3470 y FJ(extract\(\))g FN(\(T)-7 b(arFile)20 b(method\),)e(354)0 3570 y FJ(extract_cookies\(\))g FN(\(CookieJar)h(method\),)f(673)0 3670 y FJ(extract_stack\(\))g FN(\(in)i(module)f(traceback\),)f(841)0 3769 y FJ(extract_tb\(\))h FN(\(in)h(module)e(traceback\),)h(841)0 3869 y FJ(extract_version)f FN(\(ZipInfo)g(attrib)n(ute\),)h(351)0 3968 y FJ(extractall\(\))g FN(\(T)-7 b(arFile)20 b(method\),)e(354)0 4068 y FJ(ExtractError)h FN(\(e)o(xception)e(in)k(tar\002le\),)f(353)0 4168 y FJ(extractfile\(\))e FN(\(T)-7 b(arFile)21 b(method\),)d(354)0 4267 y FJ(extsep)i FN(\(data)f(in)i(os\),)f(414)0 4460 y FE(F)0 4583 y FJ(F_BAVAIL)f FN(\(data)h(in)g(statvfs\),)g(332)0 4683 y FJ(F_BFREE)f FN(\(data)h(in)h(statvfs\),)e(332)0 4782 y FJ(F_BLOCKS)g FN(\(data)h(in)g(statvfs\),)g(332)0 4882 y FJ(F_BSIZE)f FN(\(data)h(in)h(statvfs\),)e(332)0 4982 y FJ(F_FAVAIL)g FN(\(data)h(in)g(statvfs\),)g(332)0 5081 y FJ(F_FFREE)f FN(\(data)h(in)h(statvfs\),)e(332)0 5181 y FJ(F_FILES)g FN(\(data)h(in)h(statvfs\),)e(332)0 5280 y FJ(F_FLAG)h FN(\(data)f(in)i(statvfs\),)f(333)0 5380 y FJ(F_FRSIZE)f FN(\(data)h(in)g(statvfs\),)g(332)1992 83 y FJ(F_NAMEMAX)f FN(\(data)g(in)i(statvfs\),)f(333)1992 183 y FJ(F_OK)g FN(\(data)f(in)i(os\),)f(402)1992 282 y FJ(fabs\(\))f FN(\(in)h(module)f(math\),)g(149)1992 382 y FJ(fail\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(798)1992 482 y FJ(failIf\(\))h FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 581 y FJ(failIfAlmostEqual\(\))f FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 681 y FJ(failIfEqual\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 780 y FJ(failUnless\(\))g FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 880 y FJ (failUnlessAlmostEqual\(\))65 b FN(\(T)-6 b(estCase)70 b(method\),)2324 980 y(797)1992 1079 y FJ(failUnlessEqual\(\))17 b FN(\(T)-6 b(estCase)21 b(method\),)d(797)1992 1179 y FJ(failUnlessRaises\(\))f FN(\(T)-6 b(estCase)21 b(method\),)d(797) 1992 1279 y FJ(failureException)f FN(\(T)-6 b(estCase)21 b(attrib)n(ute\),)e(798)1992 1378 y FJ(failures)g FN(\(T)-6 b(estResult)21 b(attrib)n(ute\),)e(799)1992 1478 y(F)o(alse,)h(23,)g (44)1992 1577 y FJ(False)2158 1677 y FN(Built-in)g(object,)f(23)2158 1777 y(data)h(in)g(,)g(22)1992 1876 y(f)o(alse,)g(23)1992 1976 y FJ(family)f FN(\(sock)o(et)h(attrib)n(ute\),)f(584)1992 2076 y FJ(FancyURLopener)f FN(\(class)i(in)h(urllib\),)e(620)1992 2175 y FJ(fatalError\(\))f FN(\(ErrorHandler)f(method\),)h(293)1992 2275 y FJ(faultCode)h FN(\(Serv)o(erProxy)e(attrib)n(ute\),)i(686)1992 2374 y FJ(faultString)f FN(\(Serv)o(erProxy)f(attrib)n(ute\),)j(686) 1992 2474 y FJ(fchdir\(\))f FN(\(in)h(module)f(os\),)h(402)1992 2574 y FJ(FCICreate\(\))e FN(\(in)i(module)f(msilib\),)h(933)1992 2673 y FJ(fcntl\(\))f FN(\(in)h(module)f(fcntl\),)g(560)1992 2773 y FJ(fcntl)g FN(\(b)n(uilt-in)h(module\),)e(39,)h FL(560)1992 2873 y FJ(fcntl\(\))g FN(\(in)h(module)f(fcntl\),)g(563) 1992 2972 y FJ(fdatasync\(\))f FN(\(in)i(module)f(os\),)h(400)1992 3072 y FJ(fdopen\(\))f FN(\(in)h(module)f(os\),)h(398)1992 3171 y FJ(Feature)f FN(\(class)i(in)f(msilib\),)g(938)1992 3271 y FJ(feature_external_ges)30 b FN(\(data)j(in)h (xml.sax.handler\),)2324 3371 y(290)1992 3470 y FJ (feature_external_pes)c FN(\(data)j(in)h(xml.sax.handler\),)2324 3570 y(290)1992 3670 y FJ(feature_namespace_prefixes)186 b FN(\(data)k(in)2324 3769 y(xml.sax.handler\),)16 b(290)1992 3869 y FJ(feature_namespaces)g FN(\(data)i(in)h(xml.sax.handler\),)c (289)1992 3968 y FJ(feature_string_interning)236 b FN(\(data)k(in)2324 4068 y(xml.sax.handler\),)16 b(290)1992 4168 y FJ(feature_validation)g FN(\(data)i(in)h(xml.sax.handler\),)c(290)1992 4267 y FJ(feed\(\))2158 4367 y FN(FeedP)o(arser)k(method,)g(196)2158 4467 y(HTMLP)o(arser)g(method,)f(258)2158 4566 y(IncrementalP)o(arser)f (method,)i(296)2158 4666 y(SGMLP)o(arser)g(method,)g(260)2158 4765 y(XML)-8 b(T)m(reeBuilder)18 b(method,)h(302)1992 4865 y FJ(FeedParser)f FN(\(class)j(in)g(email.parser\),)d(196)1992 4965 y FJ(Fetch\(\))h FN(\(Binary)g(method\),)g(935)1992 5064 y FJ(fetch\(\))g FN(\(IMAP4)p 2644 5064 V 29 w(stream)h(method\),) e(644)1992 5164 y FJ(field_size_limit\(\))f FN(\(in)j(module)f(csv\),)h (304)1992 5264 y FJ(fields)f FN(\(UUID)h(attrib)n(ute\),)f(659)1992 5363 y FJ(fifo)h FN(\(class)g(in)h(asynchat\),)d(597)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(987)p eop end %%Page: 988 1000 TeXDict begin 988 999 bop 0 83 a FN(\002le)166 183 y(.ini,)20 b(310)166 282 y(.pdbrc,)e(807)166 382 y(.p)o(ythonrc.p)o(y)-5 b(,)16 b(851)166 482 y(byte-code,)i(865,)h(867,)g(887)166 581 y(con\002guration,)e(310)166 681 y(cop)o(ying,)h(338)166 780 y(deb)n(ugger)g(con\002guration,)f(807)166 880 y(lar)o(ge)i (\002les,)i(554)166 980 y(mime.types,)e(242)166 1079 y(object,)g(39)166 1179 y(path)h(con\002guration,)d(850)166 1279 y(temporary)-5 b(,)17 b(334)166 1378 y(user)j(con\002guration,)d (851)0 1478 y FJ(file\(\))166 1577 y FN(b)n(uilt-in)j(function,)e(39) 166 1677 y(in)i(module)f(,)i(7)166 1777 y(in)f(module)f(posix\002le,)h (564)0 1876 y FJ(file)166 1976 y FN(class)h(descriptor)e(attrib)n(ute,) h(886)166 2076 y(function)f(descriptor)f(attrib)n(ute,)i(887)0 2175 y(\002le)h(control)168 2275 y(U)t FH(N)t(I)t(X)r FN(,)g(560)0 2374 y(\002le)g(descriptor)m(,)d(39)0 2474 y(\002le)j(name)166 2574 y(temporary)-5 b(,)17 b(334)0 2673 y(\002le)k(object)166 2773 y(POSIX,)f(563)0 2873 y FJ(file_open\(\))f FN(\(FileHandler)g(method\),)f(630)0 2972 y FJ(file_size)h FN(\(ZipInfo)f(attrib)n(ute\),)h(351)0 3072 y FJ(filecmp)g FN(\(standard)g(module\),)f FL(333)0 3171 y FJ(fileConfig\(\))h FN(\(in)h(module)e(logging\),)g(468)0 3271 y FJ(FileCookieJar)g FN(\(class)j(in)f(cookielib\),)f(672)0 3371 y FJ(FileEntry)g FN(\(class)i(in)f(T)m(ix\),)g(727)0 3470 y FJ(FileHandler)166 3570 y FN(class)h(in)g(logging,)d(462)166 3670 y(class)j(in)g(urllib2,)d(624)0 3769 y FJ(FileInput)h FN(\(class)i(in)f(\002leinput\),)f(329)0 3869 y FJ(fileinput)g FN(\(standard)g(module\),)f FL(328)0 3968 y FJ(filelineno\(\))h FN(\(in)h(module)e(\002leinput\),)h(329)0 4068 y FJ(filename\(\))g FN(\(in)h(module)f(\002leinput\),)g(329)0 4168 y FJ(filename)166 4267 y FN(Cookie)h(attrib)n(ute,)f(675)166 4367 y(DocT)-6 b(est)20 b(attrib)n(ute,)g(781)166 4467 y(ZipInfo)e(attrib)n(ute,)i (350)0 4566 y FJ(filename_only)e FN(\(data)i(in)g(tabnann)o(y\),)e(885) 0 4666 y(\002lenames)166 4765 y(pathname)h(e)o(xpansion,)f(336)166 4865 y(wildcard)h(e)o(xpansion,)f(337)0 4965 y FJ(fileno\(\))166 5064 y FN(audio)h(de)n(vice)h(method,)e(708,)h(931)166 5164 y(\002le)i(method,)d(39)166 5264 y(in)i(module)f(\002leinput,)h (329)166 5363 y(in)g(module)f(Sock)o(etServ)o(er)m(,)f(666)2158 83 y(mix)o(er)h(de)n(vice)g(method,)g(710)2158 183 y(Pro\002le)h (method,)e(819)2158 282 y(sock)o(et)i(method,)e(582)2158 382 y(T)-6 b(elnet)20 b(method,)e(657)1992 482 y FJ(fileopen\(\))g FN(\(in)i(module)f(posix\002le\),)g(564)1992 581 y FJ(FileSelectBox)f FN(\(class)j(in)f(T)m(ix\),)g(727)1992 681 y FJ(FileType)f FN(\(data)g(in)i(types\),)e(142)1992 780 y FJ(FileWrapper)f FN(\(class)j(in)f(wsgiref.util\),)f(611)1992 880 y FJ(fill\(\))2158 980 y FN(in)h(module)f(te)o(xtwrap,)f(76)2158 1079 y(in)i(module)f (turtle,)g(731)2158 1179 y(T)-6 b(e)o(xtWrapper)18 b(method,)g(77)1992 1279 y FJ(Filter)h FN(\(class)i(in)f(logging\),)e(468)1992 1378 y FJ(filter\(\))2178 1478 y FN(method,)h(455,)g(461)2158 1577 y(Filter)h(method,)f(468)2158 1677 y(in)h(module)f(,)h(7)2158 1777 y(in)g(module)f(curses,)h(474)2158 1876 y(in)g(module)f(fnmatch,)f (337)1992 1976 y FJ(filterwarnings\(\))f FN(\(in)j(module)f(w)o (arnings\),)g(837)1992 2076 y FJ(find\(\))2178 2175 y FN(method,)g(548)2158 2275 y(DocT)-6 b(estFinder)19 b(method,)f(782) 2158 2374 y(ElementT)m(ree)g(method,)h(300)2158 2474 y(in)h(module)f(gette)o(xt,)g(741)2158 2574 y(in)h(module)f(string,)g (51)2158 2673 y(string)g(method,)g(29)1992 2773 y FJ(find_first\(\))f FN(\(form)h(method\),)f(921)1992 2873 y FJ(find_last\(\))g FN(\(form)h(method\),)f(921)1992 2972 y FJ(find_longest_match\(\))286 b FN(\(SequenceMatcher)2324 3072 y(method\),)18 b(69)1992 3171 y FJ(find_module\(\))2158 3271 y FN(in)i(module)f(imp,)g(865)2158 3371 y(NullImporter)e(method,)i(867)2158 3470 y(zipimporter)f(method,)g (869)1992 3570 y FJ(find_prefix_at_end\(\))f FN(\(in)j(module)e (asynchat\),)h(597)1992 3670 y FJ(find_user_password\(\))214 b FN(\(HTTPP)o(assw)o(ordMgr)2324 3769 y(method\),)18 b(628)1992 3869 y FJ(findall\(\))2158 3968 y FN(ElementT)m(ree)g (method,)h(300)2158 4068 y(in)h(module)f(re,)h(58)2158 4168 y(Re)o(ge)o(xObject)e(method,)h(60)1992 4267 y FJ(findCaller\(\))f FN(\()i(method\),)f(455)1992 4367 y FJ(findfactor\(\))f FN(\(in)i(module)f(audioop\),)e(694)1992 4467 y FJ(findfile\(\))h FN(\(in)i(module)f(test.test)p 3149 4467 25 4 v 30 w(support\),)g(804) 1992 4566 y FJ(findfit\(\))g FN(\(in)h(module)e(audioop\),)g(694)1992 4666 y FJ(findfont\(\))g FN(\(in)i(module)f(fm\),)h(924)1992 4765 y FJ(finditer\(\))2158 4865 y FN(in)g(module)f(re,)h(58)2158 4965 y(Re)o(ge)o(xObject)e(method,)h(60)1992 5064 y FJ(findmatch\(\))f FN(\(in)i(module)f(mailcap\),)g(218)1992 5164 y FJ(findmax\(\))g FN(\(in)h(module)e(audioop\),)g(694)1992 5264 y FJ(findtext\(\))g FN(\(ElementT)m(ree)h(method\),)f(300)1992 5363 y FJ(finish\(\))h FN(\(in)h(module)f(Sock)o(etServ)o(er\),)e(667)p 0 5549 3901 4 v 0 5649 a FI(988)3561 b(Inde)n(x)p eop end %%Page: 989 1001 TeXDict begin 989 1000 bop 0 83 a FJ(finish_request\(\))18 b FN(\(in)i(module)f(Sock)o(etServ)o(er\),)e(666)0 183 y FJ(first\(\))187 282 y FN(method,)h(381)166 382 y(dbhash)h(method,)g (379)166 482 y(\002fo)h(method,)f(597)0 581 y FJ(firstChild)g FN(\(Node)g(attrib)n(ute\),)g(275)0 681 y FJ(firstkey\(\))g FN(\(in)h(module)f(gdbm\),)f(378)0 780 y FJ(firstweekday\(\))g FN(\(in)i(module)f(calendar\),)f(115)0 880 y FJ(fix\(\))i FN(\(in)g(module)f(fpformat\),)e(93)0 980 y FJ(fix_sentence_endings)59 b FN(\(T)-6 b(e)o(xtWrapper)60 b(attrib)n(ute\),)332 1079 y(77)0 1179 y FJ(FL)20 b FN(\(standard)f(module\),)f FL(923)0 1279 y FJ(fl)i FN(\(b)n(uilt-in)g(module\),)e FL(919)0 1378 y FJ(flag_bits)h FN(\(ZipInfo)f(attrib)n(ute\),)h(351)0 1478 y FJ(flags\(\))g FN(\(in)h(module)f(posix\002le\),)g(564)0 1577 y FJ(flags)h FN(\(Re)o(ge)o(xObject)e(attrib)n(ute\),)h(60)0 1677 y FJ(flash\(\))g FN(\(in)h(module)f(curses\),)h(474)0 1777 y FJ(flatten\(\))f FN(\(Generator)f(method\),)h(199)0 1876 y(\003attening)166 1976 y(objects,)h(359)0 2076 y FJ(float\(\))166 2175 y FN(b)n(uilt-in)g(function,)e(25,)h(50)166 2275 y(in)h(module)f(,)i(8)0 2374 y(\003oating)e(point)166 2474 y(literals,)i(25)166 2574 y(object,)e(25)0 2673 y FJ(FloatingPointError)166 2773 y FN(e)o(xception)f(in)j(e)o (xceptions,)d(19)166 2873 y(e)o(xception)g(in)j(fpectl,)e(852)0 2972 y FJ(FloatType)g FN(\(data)h(in)g(types\),)g(141)0 3072 y FJ(flock\(\))f FN(\(in)h(module)f(fcntl\),)h(561)0 3171 y FJ(floor\(\))166 3271 y FN(in)g(module)f(math,)h(149)166 3371 y(in)g(module)f(math,)h(25)0 3470 y FJ(floordiv\(\))f FN(\(in)h(module)f(operator\),)e(183)0 3570 y FJ(flp)j FN(\(standard)f(module\),)f FL(924)0 3670 y FJ(flush\(\))187 3769 y FN(method,)g(461,)h(548)166 3869 y(audio)g(de)n(vice)h(method,)e (932)166 3968 y(Buf)n(feringHandler)f(method,)h(466)166 4068 y(BZ2Compressor)h(method,)f(347)166 4168 y(Compress)i(method,)e (344)166 4267 y(Decompress)h(method,)g(345)166 4367 y(\002le)i(method,) d(39)166 4467 y(Mailbox)h(method,)g(221)166 4566 y(Maildir)h(method,)e (222)166 4666 y(MemoryHandler)f(method,)i(466)166 4765 y(MH)i(method,)d(224)166 4865 y(StreamHandler)g(method,)h(462)166 4965 y(writer)h(method,)f(911)0 5064 y FJ(flush_softspace\(\))f FN(\(formatter)g(method\),)g(910)0 5164 y FJ(flushheaders\(\))g FN(\(MimeWriter)i(method\),)e(243)0 5264 y FJ(flushinp\(\))h FN(\(in)h(module)f(curses\),)g(474)0 5363 y FJ(FlushKey\(\))g FN(\(in)h(module)p 907 5363 25 4 v 49 w(winre)o(g\),)e(942)1992 83 y FJ(fm)i FN(\(b)n(uilt-in)f(module\),)f FL(924)1992 183 y FJ(fmod\(\))h FN(\(in)h(module)f(math\),)g(149)1992 282 y FJ(fnmatch\(\))g FN(\(in)h(module)e(fnmatch\),)h(337)1992 382 y FJ(fnmatch)g FN(\(standard)g(module\),)f FL(337)1992 482 y FJ(fnmatchcase\(\))g FN(\(in)i(module)f(fnmatch\),)f(337)1992 581 y FJ(Folder)h FN(\(class)i(in)f(mhlib\),)f(237)1992 681 y(F)o(ont)g(Manager)m(,)g(IRIS,)h(924)1992 780 y FJ(fontpath\(\))e FN(\(in)i(module)f(fm\),)h(924)1992 880 y FJ(forget\(\))f FN(\(in)h(module)f(test.test)p 3050 880 V 30 w(support\),)f(804)1992 980 y FJ(fork\(\))2158 1079 y FN(in)i(module)f(os,)h(410)2158 1179 y(in)g(module)f(pty)-5 b(,)19 b(560)1992 1279 y FJ(forkpty\(\))g FN(\(in)h(module)e(os\),)i (410)1992 1378 y FJ(Form)g FN(\(class)g(in)h(T)m(ix\),)e(728)1992 1478 y FJ(format\(\))2178 1577 y FN(method,)g(462)2158 1677 y(F)o(ormatter)f(method,)h(467)2158 1777 y(in)h(module)f(locale,)g (751)2158 1876 y(PrettyPrinter)g(method,)f(147)1992 1976 y FJ(format)h FN(\(Struct)h(attrib)n(ute\),)f(65)1992 2076 y FJ(format_exc\(\))f FN(\(in)i(module)f(traceback\),)f(841)1992 2175 y FJ(format_exception\(\))f FN(\(in)j(module)f(traceback\),)f(841) 1992 2275 y FJ(format_exception_only\(\))c FN(\(in)j(module)g (traceback\),)2324 2374 y(841)1992 2474 y FJ(format_list\(\))h FN(\(in)i(module)f(traceback\),)f(841)1992 2574 y FJ(format_stack\(\))g FN(\(in)i(module)e(traceback\),)h(841)1992 2673 y FJ(format_string\(\)) e FN(\(in)j(module)f(locale\),)h(751)1992 2773 y FJ(format_tb\(\))e FN(\(in)i(module)f(traceback\),)f(841)1992 2873 y FJ(formataddr\(\))g FN(\(in)i(module)f(email.utils\),)g(208)1992 2972 y FJ (formatargspec\(\))e FN(\(in)j(module)f(inspect\),)h(849)1992 3072 y FJ(formatargvalues\(\))d FN(\(in)j(module)f(inspect\),)g(849) 1992 3171 y FJ(formatdate\(\))f FN(\(in)i(module)f(email.utils\),)g (208)1992 3271 y FJ(FormatError\(\))f FN(\(in)i(module)f(ctypes\),)g (529)1992 3371 y FJ(FormatError)f FN(\(class)j(in)f(mailbox\),)f(234) 1992 3470 y FJ(formatException\(\))e FN(\(F)o(ormatter)i(method\),)f (467)1992 3570 y FJ(formatmonth\(\))2158 3670 y FN(HTMLCalendar)g (method,)h(115)2158 3769 y(T)-6 b(e)o(xtCalendar)18 b(method,)h(114) 1992 3869 y FJ(Formatter)g FN(\(class)h(in)h(logging\),)d(467)1992 3968 y FJ(formatter)2158 4068 y FN(HTMLP)o(arser)h(attrib)n(ute,)g(263) 2158 4168 y(standard)g(module,)f(262,)h FL(909)1992 4267 y FJ(formatTime\(\))f FN(\(F)o(ormatter)h(method\),)f(467)1992 4367 y(formatting,)g(string)h(\(\045\),)h(32)1992 4467 y FJ(formatwarning\(\))d FN(\(in)j(module)f(w)o(arnings\),)g(837)1992 4566 y FJ(formatyear\(\))2158 4666 y FN(HTMLCalendar)f(method,)h(115) 2158 4765 y(T)-6 b(e)o(xtCalendar)18 b(method,)h(115)1992 4865 y FJ(formatyearpage\(\))e FN(\(HTMLCalendar)i(method\),)f(115)1992 4965 y(FORMS)j(Library)-5 b(,)18 b(919)1992 5064 y FJ(forward\(\))h FN(\(in)h(module)e(turtle\),)i(731)1992 5164 y FJ(found_terminator\(\)) d FN(\(async)p 3132 5164 V 28 w(chat)k(method\),)d(596)1992 5264 y FJ(fp)i FN(\(AddressList)g(attrib)n(ute\),)f(250)1992 5363 y FJ(fpathconf\(\))f FN(\(in)i(module)f(os\),)h(400)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(989)p eop end %%Page: 990 1002 TeXDict begin 990 1001 bop 0 83 a FJ(fpectl)20 b FN(\(e)o(xtension)e (module\),)g FL(852)0 183 y FJ(fpformat)h FN(\(standard)g(module\),)f FL(93)0 282 y FJ(frame)i FN(\(ScrolledT)-6 b(e)o(xt)18 b(attrib)n(ute\),)h(730)0 382 y FJ(FrameType)g FN(\(data)h(in)g (types\),)g(142)0 482 y FJ(freeze_form\(\))e FN(\(form)h(method\),)f (921)0 581 y FJ(freeze_object\(\))g FN(\(FORMS)j(object)e(method\),)g (923)0 681 y FJ(frexp\(\))g FN(\(in)h(module)f(math\),)g(150)0 780 y FJ(from_address\(\))f FN(\()p 751 780 25 4 v 30 w(CData)j(method\),)d(530)0 880 y FJ(from_param\(\))h FN(\()p 652 880 V 29 w(CData)i(method\),)d(530)0 980 y FJ(from_splittable\(\))g FN(\(Charset)i(method\),)e(205)0 1079 y FJ(frombuf\(\))h FN(\(T)-7 b(arInfo)18 b(method\),)h(355)0 1179 y FJ(fromchild)g FN(\(Popen4)g(attrib)n(ute\),)g(591)0 1279 y FJ(fromfd\(\))g FN(\(in)h(module)f(sock)o(et\),)h(580)0 1378 y FJ(fromfile\(\))f FN(\(array)g(method\),)f(126)0 1478 y FJ(fromkeys\(\))h FN(\(dictionary)f(method\),)g(37)0 1577 y FJ(fromlist\(\))h FN(\(array)g(method\),)f(126)0 1677 y FJ(fromordinal\(\))166 1777 y FN(date)i(method,)f(99)166 1876 y(datetime)h(method,)e(102)0 1976 y FJ(fromstring\(\))166 2076 y FN(array)h(method,)g(126)166 2175 y(in)h(module)f (xml.etree.ElementT)m(ree,)e(299)0 2275 y FJ(fromtimestamp\(\))166 2374 y FN(date)j(method,)f(99)166 2474 y(datetime)h(method,)e(101)0 2574 y FJ(fromunicode\(\))g FN(\(array)h(method\),)f(126)0 2673 y FJ(fromutc\(\))h FN(\(time)h(method\),)e(109)0 2773 y FJ(frozenset\(\))h FN(\(in)h(module)f(\),)h(8)0 2873 y FJ(fstat\(\))f FN(\(in)h(module)f(os\),)h(400)0 2972 y FJ(fstatvfs\(\))f FN(\(in)h(module)f(os\),)h(400)0 3072 y FJ(fsync\(\))f FN(\(in)h(module)f(os\),)h(400)0 3171 y(FTP)-9 b(,)20 b(620)166 3271 y FJ(ftplib)g FN(\(standard)e (module\),)h(636)166 3371 y(protocol,)f(620,)h(636)0 3470 y FJ(FTP)h FN(\(class)h(in)f(ftplib\),)f(637)0 3570 y FJ(ftp_open\(\))g FN(\(FTPHandler)g(method\),)f(630)0 3670 y(ftp)p 98 3670 V 29 w(proxy)-5 b(,)18 b(617)0 3769 y FJ(FTPHandler)h FN(\(class)i(in)f(urllib2\),)f(624)0 3869 y FJ(ftplib)h FN(\(standard)e(module\),)h FL(636)0 3968 y FN(ftpmirror)-5 b(.p)o(y)g(,)17 b(637)0 4068 y FJ(ftruncate\(\))i FN(\(in)h(module)f(os\),)g(400)0 4168 y FJ(Full)h FN(\(e)o(xception)e(in)i(Queue\),)f(133)0 4267 y FJ(full\(\))h FN(\(Queue)f(method\),)f(133)0 4367 y FJ(func)i FN(\(callable)g(attrib)n(ute\),)f(182)0 4467 y FJ(func_code)g FN(\(function)f(object)i(attrib)n(ute\),)f(44)0 4566 y FJ(function\(\))g FN(\(in)h(module)f(ne)n(w\),)g(143)0 4666 y(functions)166 4765 y(b)n(uilt-in,)g(3)0 4865 y FJ(FunctionTestCase)f FN(\(class)j(in)f(unittest\),)g(796)0 4965 y FJ(FunctionType)f FN(\(data)g(in)i(types\),)e(141)0 5064 y FJ(functools)g FN(\(standard)g(module\),)f FL(181)0 5164 y FJ(funny_files)h FN(\(dircmp)f(attrib)n(ute\),)i(334)0 5264 y FJ(FutureWarning)e FN(\(e)o(xception)g(in)j(e)o(xceptions\),)d (21)1992 88 y FE(G)1992 211 y FN(G.722,)g(699)1992 311 y FJ(gaierror)h FN(\(e)o(xception)f(in)i(sock)o(et\),)g(578)1992 411 y FJ(gammavariate\(\))e FN(\(in)i(module)e(random\),)g(171)1992 510 y FJ(garbage)h FN(\(data)h(in)g(gc\),)g(844)1992 610 y FJ(gather\(\))f FN(\(T)-6 b(e)o(xtbox)18 b(method\),)g(488)1992 709 y FJ(gauss\(\))h FN(\(in)h(module)f(random\),)f(171)1992 809 y FJ(gc)i FN(\(e)o(xtension)e(module\),)g FL(843)1992 909 y FJ(gdbm)i FN(\(b)n(uilt-in)f(module\),)f(372,)h(375,)g FL(377)1992 1008 y FJ(ge\(\))h FN(\(in)g(module)e(operator\),)g(183) 1992 1108 y FJ(gen_uuid\(\))g FN(\(in)i(module)f(msilib\),)h(934)1992 1208 y FJ(generate_tokens\(\))d FN(\(in)j(module)f(tok)o(enize\),)g (883)1992 1307 y FJ(Generator)g FN(\(class)h(in)h(email.generator\),)c (198)1992 1407 y FJ(GeneratorExit)h FN(\(e)o(xception)g(in)i(e)o (xceptions\),)e(19)1992 1507 y FJ(GeneratorType)g FN(\(data)i(in)g (types\),)f(141)1992 1606 y FJ(genops\(\))g FN(\(in)h(module)f (pickletools\),)f(896)1992 1706 y FJ(get\(\))2158 1805 y FN(AddressList)i(method,)e(249)2158 1905 y(dictionary)g(method,)h(37) 2158 2005 y(in)h(module)f(webbro)n(wser)m(,)f(600)2158 2104 y(Mailbox)h(method,)f(220)2158 2204 y(Message)i(method,)e(192)2158 2304 y(mix)o(er)h(de)n(vice)g(method,)g(711)2158 2403 y(Queue)g(method,)g(133)2158 2503 y(SafeCon\002gP)o(arser)f(method,)h (312,)g(313)1992 2602 y FJ(get_all\(\))2158 2702 y FN(Headers)g (method,)g(612)2158 2802 y(Message)h(method,)e(192)1992 2901 y FJ(get_app\(\))h FN(\(WSGIServ)o(er)g(method\),)f(613)1992 3001 y FJ(get_begidx\(\))g FN(\(in)i(module)f(readline\),)f(550)1992 3101 y FJ(get_body_encoding\(\))f FN(\(Charset)j(method\),)e(204)1992 3200 y FJ(get_boundary\(\))g FN(\(Message)i(method\),)e(194)1992 3300 y FJ(get_buffer\(\))2158 3399 y FN(P)o(ack)o(er)h(method,)g(315) 2158 3499 y(Unpack)o(er)f(method,)h(316)1992 3599 y FJ(get_charset\(\)) f FN(\(Message)i(method\),)e(191)1992 3698 y FJ(get_charsets\(\))g FN(\(Message)i(method\),)e(195)1992 3798 y FJ(get_close_matches\(\))f FN(\(in)j(module)f(dif)n(\003ib\),)g(67)1992 3898 y FJ(get_code\(\))f FN(\(zipimporter)g(method\),)g(869)1992 3997 y FJ(get_completer\(\))f FN(\(in)j(module)f(readline\),)g(550)1992 4097 y FJ (get_completer_delims\(\))47 b FN(\(in)k(module)f(readline\),)2324 4196 y(550)1992 4296 y FJ(get_content_charset\(\))16 b FN(\(Message)k(method\),)e(195)1992 4396 y FJ (get_content_maintype\(\))e FN(\(Message)k(method\),)e(193)1992 4495 y FJ(get_content_subtype\(\))e FN(\(Message)k(method\),)e(193)1992 4595 y FJ(get_content_type\(\))f FN(\(Message)j(method\),)e(193)1992 4695 y FJ(get_count\(\))g FN(\(in)i(module)f(gc\),)h(843)1992 4794 y FJ(get_current_history_length\(\))80 b FN(\(in)86 b(module)2324 4894 y(readline\),)18 b(549)1992 4993 y FJ(get_data\(\))2158 5093 y FN(Request)i(method,)e(625)2158 5193 y(zipimporter)g(method,)g(869)1992 5292 y FJ(get_date\(\))g FN(\(MaildirMessage)h(method\),)g(227)1992 5392 y FJ(get_debug\(\))f FN(\(in)i(module)f(gc\),)h(843)p 0 5549 3901 4 v 0 5649 a FI(990)3561 b(Inde)n(x)p eop end %%Page: 991 1003 TeXDict begin 991 1002 bop 0 83 a FJ(get_default_domain\(\))17 b FN(\(in)j(module)f(nis\),)h(568)0 183 y FJ(get_default_type\(\))d FN(\(Message)j(method\),)f(193)0 282 y FJ(get_dialect\(\))f FN(\(in)i(module)f(csv\),)h(304)0 382 y FJ(get_directory\(\))e FN(\(in)i(module)f(\003\),)h(920)0 482 y FJ(get_doctest\(\))e FN(\(DocT)-6 b(estP)o(arser)19 b(method\),)g(783)0 581 y FJ(get_endidx\(\))g FN(\(in)h(module)e(readline\),)h(550)0 681 y FJ(get_environ\(\))f FN(\(WSGIRequestHandler)h(method\),)f(613)0 780 y FJ(get_examples\(\))g FN(\(DocT)-6 b(estP)o(arser)19 b(method\),)f(783)0 880 y FJ(get_file\(\))166 980 y FN(Babyl)i(method,) f(225)166 1079 y(Mailbox)g(method,)g(220)166 1179 y(Maildir)h(method,)e (222)166 1279 y(mbox)h(method,)f(223)166 1378 y(MH)j(method,)d(224)166 1478 y(MMDF)j(method,)d(226)0 1577 y FJ(get_filename\(\))166 1677 y FN(in)i(module)f(\003,)i(920)166 1777 y(Message)f(method,)f(194) 0 1876 y FJ(get_flags\(\))166 1976 y FN(MaildirMessage)g(method,)g(227) 166 2076 y(mboxMessage)f(method,)h(229)166 2175 y(MMDFMessage)h (method,)f(233)0 2275 y FJ(get_folder\(\))166 2374 y FN(Maildir)h(method,)e(222)166 2474 y(MH)j(method,)d(224)0 2574 y FJ(get_from\(\))166 2673 y FN(mboxMessage)g(method,)h(229)166 2773 y(MMDFMessage)h(method,)f(232)0 2873 y FJ(get_full_url\(\))f FN(\(Request)i(method\),)e(625)0 2972 y FJ(get_grouped_opcodes\(\))236 b FN(\(SequenceMatcher)332 3072 y(method\),)18 b(70)0 3171 y FJ(get_history_item\(\))f FN(\(in)j(module)f(readline\),)g(549)0 3271 y FJ(get_history_length\(\))e FN(\(in)j(module)f(readline\),)f (549)0 3371 y FJ(get_host\(\))h FN(\(Request)h(method\),)e(625)0 3470 y FJ(get_ident\(\))h FN(\(in)h(module)f(thread\),)f(537)0 3570 y FJ(get_info\(\))h FN(\(MaildirMessage)g(method\),)f(227)0 3670 y FJ(get_labels\(\))166 3769 y FN(Babyl)i(method,)f(225)166 3869 y(BabylMessage)h(method,)e(231)0 3968 y FJ(get_line_buffer\(\))g FN(\(in)i(module)e(readline\),)h(549)0 4068 y FJ(get_magic\(\))g FN(\(in)h(module)f(imp\),)g(865)0 4168 y FJ(get_matching_blocks\(\))236 b FN(\(SequenceMatcher)332 4267 y(method\),)18 b(70)0 4367 y FJ(get_message\(\))g FN(\(Mailbox)h(method\),)f(220)0 4467 y FJ(get_method\(\))h FN(\(Request)g(method\),)g(625)0 4566 y FJ(get_mouse\(\))g FN(\(in)h(module)f(\003\),)h(920)0 4666 y FJ(get_nonstandard_attr\(\))d FN(\(Cookie)i(method\),)f(679)0 4765 y FJ(get_nowait\(\))h FN(\(Queue)g(method\),)f(134)0 4865 y FJ(get_objects\(\))g FN(\(in)i(module)f(gc\),)h(843)0 4965 y FJ(get_opcodes\(\))e FN(\(SequenceMatcher)f(method\),)i(70)0 5064 y FJ(get_origin_req_host\(\))e FN(\(Request)j(method\),)e(625)0 5164 y FJ(get_osfhandle\(\))g FN(\(in)i(module)f(msvcrt\),)g(940)0 5264 y FJ(get_output_charset\(\))e FN(\(Charset)j(method\),)e(205)0 5363 y FJ(get_param\(\))h FN(\(Message)h(method\),)e(193)1992 83 y FJ(get_params\(\))g FN(\(Message)i(method\),)e(193)1992 183 y FJ(get_pattern\(\))g FN(\(in)i(module)f(\003\),)h(920)1992 282 y FJ(get_payload\(\))e FN(\(Message)i(method\),)e(191)1992 382 y FJ(get_position\(\))g FN(\(Unpack)o(er)g(method\),)g(316)1992 482 y FJ(get_recsrc\(\))g FN(\(mix)o(er)h(de)n(vice)g(method\),)f(711) 1992 581 y FJ(get_referents\(\))f FN(\(in)j(module)f(gc\),)h(844)1992 681 y FJ(get_referrers\(\))d FN(\(in)j(module)f(gc\),)h(844)1992 780 y FJ(get_request\(\))e FN(\(in)i(module)f(Sock)o(etServ)o(er\),)e (666)1992 880 y FJ(get_rgbmode\(\))h FN(\(in)i(module)f(\003\),)h(919) 1992 980 y FJ(get_scheme\(\))e FN(\(BaseHandler)h(method\),)f(615)1992 1079 y FJ(get_selector\(\))g FN(\(Request)i(method\),)e(625)1992 1179 y FJ(get_sequences\(\))2158 1279 y FN(MH)i(method,)f(224)2158 1378 y(MHMessage)h(method,)e(230)1992 1478 y FJ(get_socket\(\))g FN(\(T)-6 b(elnet)20 b(method\),)e(657)1992 1577 y FJ(get_source\(\))g FN(\(zipimporter)g(method\),)g(869)1992 1677 y FJ (get_starttag_text\(\))2158 1777 y FN(HTMLP)o(arser)h(method,)f(258) 2158 1876 y(SGMLP)o(arser)h(method,)g(260)1992 1976 y FJ(get_stderr\(\))2158 2076 y FN(BaseHandler)g(method,)g(615)2158 2175 y(WSGIRequestHandler)f(method,)h(613)1992 2275 y FJ(get_stdin\(\))f FN(\(BaseHandler)h(method\),)g(615)1992 2374 y FJ(get_string\(\))f FN(\(Mailbox)h(method\),)f(220)1992 2474 y FJ(get_subdir\(\))g FN(\(MaildirMessage)h(method\),)f(227)1992 2574 y FJ(get_suffixes\(\))g FN(\(in)i(module)e(imp\),)i(865)1992 2673 y FJ(get_terminator\(\))d FN(\(async)p 3032 2673 25 4 v 29 w(chat)j(method\),)e(596)1992 2773 y FJ(get_threshold\(\))f FN(\(in)j(module)f(gc\),)h(844)1992 2873 y FJ(get_token\(\))e FN(\(shle)o(x)i(method\),)e(760)1992 2972 y FJ(get_type\(\))g FN(\(Request)i(method\),)f(625)1992 3072 y FJ(get_unixfrom\(\))f FN(\(Message)i(method\),)e(191)1992 3171 y FJ(get_visible\(\))g FN(\(BabylMessage)h(method\),)f(231)1992 3271 y FJ(getacl\(\))h FN(\(IMAP4)p 2694 3271 V 28 w(stream)h(method\),)f(644)1992 3371 y FJ(getaddr\(\))g FN(\(AddressList)g(method\),)f(249)1992 3470 y FJ(getaddresses\(\))g FN(\(in)i(module)e(email.utils\),)i(208) 1992 3570 y FJ(getaddrinfo\(\))e FN(\(in)i(module)f(sock)o(et\),)g(578) 1992 3670 y FJ(getaddrlist\(\))f FN(\(AddressList)h(method\),)g(249) 1992 3769 y FJ(getallmatchingheaders\(\))13 b FN(\(AddressList)18 b(method\),)2324 3869 y(249)1992 3968 y FJ(getannotation\(\))f FN(\(IMAP4)p 3042 3968 V 29 w(stream)j(method\),)e(644)1992 4068 y FJ(getargspec\(\))g FN(\(in)i(module)f(inspect\),)g(848)1992 4168 y FJ(getargvalues\(\))f FN(\(in)i(module)e(inspect\),)i(849)1992 4267 y FJ(getatime\(\))e FN(\(in)i(module)f(os.path\),)g(326)1992 4367 y FJ(getattr\(\))g FN(\(in)h(module)e(\),)j(8)1992 4467 y FJ(getAttribute\(\))d FN(\(Element)h(method\),)f(278)1992 4566 y FJ(getAttributeNode\(\))f FN(\(Element)i(method\),)f(278)1992 4666 y FJ(getAttributeNodeNS\(\))f FN(\(Element)i(method\),)f(278)1992 4765 y FJ(getAttributeNS\(\))f FN(\(Element)i(method\),)g(278)1992 4865 y FJ(GetBase\(\))g FN(\(xmlparser)f(method\),)g(265)1992 4965 y FJ(getbegyx\(\))g FN(\(windo)n(w)h(method\),)f(479)1992 5064 y FJ(getboolean\(\))g FN(\(SafeCon\002gP)o(arser)g(method\),)g (312)1992 5164 y FJ(getByteStream\(\))f FN(\(InputSource)h(method\),)g (297)1992 5264 y FJ(getcaps\(\))h FN(\(in)h(module)e(mailcap\),)h(218) 1992 5363 y FJ(getch\(\))p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(991)p eop end %%Page: 992 1004 TeXDict begin 992 1003 bop 166 83 a FN(in)20 b(module)f(msvcrt,)h(940) 166 183 y(windo)n(w)f(method,)g(480)0 282 y FJ(getchannels\(\))f FN(\(audio)h(con\002guration)f(method\),)g(914)0 382 y FJ(getCharacterStream\(\))d FN(\(InputSource)g(method\),)i(297)0 482 y FJ(getche\(\))i FN(\(in)h(module)f(msvcrt\),)g(940)0 581 y FJ(getcheckinterval\(\))e FN(\(in)j(module)f(sys\),)h(829)0 681 y FJ(getChildNodes\(\))e FN(\(Node)h(method\),)f(899)0 780 y FJ(getChildren\(\))g FN(\(Node)i(method\),)e(898)0 880 y FJ(getclasstree\(\))g FN(\(in)i(module)f(inspect\),)g(848)0 980 y FJ(GetColumnInfo\(\))f FN(\(Binary)h(method\),)g(935)0 1079 y FJ(getColumnNumber\(\))f FN(\(Locator)g(method\),)g(296)0 1179 y FJ(getcomment\(\))h FN(\(in)h(module)e(fm\),)i(924)0 1279 y FJ(getcomments\(\))e FN(\(in)i(module)f(inspect\),)g(848)0 1378 y FJ(getcompname\(\))166 1478 y FN(aifc)h(method,)f(698)166 1577 y(A)-5 b(U)p 286 1577 25 4 v 30 w(read)20 b(method,)e(700)166 1677 y(W)-7 b(a)n(v)o(e)p 355 1677 V 30 w(read)20 b(method,)e(702)0 1777 y FJ(getcomptype\(\))166 1876 y FN(aifc)i(method,)f(698)166 1976 y(A)-5 b(U)p 286 1976 V 30 w(read)20 b(method,)e(700)166 2076 y(W)-7 b(a)n(v)o(e)p 355 2076 V 30 w(read)20 b(method,)e(702)0 2175 y FJ(getconfig\(\))h FN(\(audio)g(port)g(method\),)f(915)0 2275 y FJ(getContentHandler\(\))f FN(\(XMLReader)i(method\),)f(295)0 2374 y FJ(getcontext\(\))166 2474 y FN(in)i(module)f(decimal,)h(158)166 2574 y(MH)h(method,)d(238)0 2673 y FJ(getctime\(\))h FN(\(in)h(module)f(os.path\),)f(326)0 2773 y FJ(getcurrent\(\))h FN(\(F)o(older)f(method\),)h(238)0 2873 y FJ(getcwd\(\))g FN(\(in)h(module)f(os\),)h(402)0 2972 y FJ(getcwdu\(\))f FN(\(in)h(module)f(os\),)h(402)0 3072 y FJ(getdate\(\))f FN(\(AddressList)h(method\),)e(250)0 3171 y FJ(getdate_tz\(\))h FN(\(AddressList)g(method\),)f(250)0 3271 y FJ(getdecoder\(\))h FN(\(in)h(module)e(codecs\),)h(78)0 3371 y FJ(getdefaultencoding\(\))e FN(\(in)j(module)f(sys\),)h(829)0 3470 y FJ(getdefaultlocale\(\))d FN(\(in)j(module)f(locale\),)h(750)0 3570 y FJ(getdefaulttimeout\(\))d FN(\(in)j(module)f(sock)o(et\),)g(581)0 3670 y FJ(getdlopenflags\(\))f FN(\(in)i(module)f(sys\),)h(830)0 3769 y FJ(getdoc\(\))f FN(\(in)h(module)f(inspect\),)g(848)0 3869 y FJ (getDOMImplementation\(\))38 b FN(\(in)j(module)f(xml.dom\),)332 3968 y(273)0 4068 y FJ(getDTDHandler\(\))18 b FN(\(XMLReader)h (method\),)f(295)0 4168 y FJ(getEffectiveLevel\(\))f FN(\()k(method\),)d(454)0 4267 y FJ(getegid\(\))h FN(\(in)h(module)f (os\),)h(396)0 4367 y FJ(getElementsByTagName\(\))166 4467 y FN(Document)f(method,)f(278)166 4566 y(Element)i(method,)e(278)0 4666 y FJ(getElementsByTagNameNS\(\))166 4765 y FN(Document)h(method,)f (278)166 4865 y(Element)i(method,)e(278)0 4965 y FJ(getencoder\(\))h FN(\(in)h(module)e(codecs\),)h(78)0 5064 y FJ(getEncoding\(\))f FN(\(InputSource)g(method\),)g(297)0 5164 y FJ(getencoding\(\))g FN(\(Message)i(method\),)e(240)0 5264 y FJ(getEntityResolver\(\))f FN(\(XMLReader)i(method\),)f(296)0 5363 y FJ(getenv\(\))h FN(\(in)h(module)f(os\),)h(397)1992 83 y FJ(getErrorHandler\(\))d FN(\(XMLReader)i(method\),)f(296)1992 183 y FJ(geteuid\(\))h FN(\(in)h(module)e(os\),)i(396)1992 282 y FJ(getEvent\(\))e FN(\(DOMEv)o(entStream)g(method\),)g(287)1992 382 y FJ (getEventCategory\(\))276 b FN(\(NTEv)o(entLogHandler)2324 482 y(method\),)18 b(465)1992 581 y FJ(getEventType\(\))e FN(\(NTEv)o(entLogHandler)e(method\),)i(465)1992 681 y FJ(getException\(\))i FN(\(SAXException)g(method\),)g(289)1992 780 y FJ(getfd\(\))h FN(\(audio)g(port)g(method\),)g(914)1992 880 y FJ(getFeature\(\))f FN(\(XMLReader)h(method\),)f(296)1992 980 y FJ(GetFieldCount\(\))f FN(\(Binary)j(method\),)e(936)1992 1079 y FJ(getfile\(\))h FN(\(in)h(module)e(inspect\),)i(848)1992 1179 y FJ(getfilesystemencoding\(\))c FN(\(in)k(module)f(sys\),)h(830) 1992 1279 y FJ(getfillable\(\))e FN(\(audio)h(port)g(method\),)f(914) 1992 1378 y FJ(getfilled\(\))g FN(\(audio)h(port)h(method\),)e(914)1992 1478 y FJ(getfillpoint\(\))g FN(\(audio)h(port)g(method\),)f(915)1992 1577 y FJ(getfirst\(\))g FN(\(FieldStorage)h(method\),)f(605)1992 1677 y FJ(getfirstmatchingheader\(\))279 b FN(\(AddressList)2324 1777 y(method\),)18 b(249)1992 1876 y FJ(getfloat\(\))g FN(\(SafeCon\002gP)o(arser)h(method\),)f(312)1992 1976 y FJ(getfloatmax\(\))g FN(\(audio)h(con\002guration)e(method\),)h(914) 1992 2076 y FJ(getfmts\(\))h FN(\(audio)f(de)n(vice)i(method\),)e(709) 1992 2175 y FJ(getfontinfo\(\))g FN(\(in)i(module)f(fm\),)g(925)1992 2275 y FJ(getfontname\(\))f FN(\(in)i(module)f(fm\),)g(924)1992 2374 y FJ(getfqdn\(\))g FN(\(in)h(module)e(sock)o(et\),)i(579)1992 2474 y FJ(getframeinfo\(\))e FN(\(in)i(module)e(inspect\),)i(849)1992 2574 y FJ(getframerate\(\))2158 2673 y FN(aifc)g(method,)e(698)2158 2773 y(A)-5 b(U)p 2278 2773 V 30 w(read)19 b(method,)g(700)2158 2873 y(W)-7 b(a)n(v)o(e)p 2347 2873 V 30 w(read)19 b(method,)g(702)1992 2972 y FJ(getfullname\(\))f FN(\(F)o(older)h(method\),)f(238)1992 3072 y FJ(getgid\(\))h FN(\(in)h(module)f(os\),)h(396)1992 3171 y FJ(getgrall\(\))e FN(\(in)i(module)f(grp\),)g(556)1992 3271 y FJ(getgrgid\(\))f FN(\(in)i(module)f(grp\),)g(556)1992 3371 y FJ(getgrnam\(\))f FN(\(in)i(module)f(grp\),)g(556)1992 3470 y FJ(getgroups\(\))f FN(\(in)i(module)f(os\),)h(396)1992 3570 y FJ(getheader\(\))2158 3670 y FN(AddressList)g(method,)e(249)2158 3769 y(HTTPResponse)h(method,)g(635)1992 3869 y FJ(getheaders\(\))f FN(\(HTTPResponse)h(method\),)f(635)1992 3968 y FJ(gethostbyaddr\(\)) 2158 4068 y FN(in)i(module)f(sock)o(et,)h(398)2158 4168 y(in)g(module)f(sock)o(et,)h(579)1992 4267 y FJ(gethostbyname\(\))d FN(\(in)j(module)f(sock)o(et\),)h(579)1992 4367 y FJ (gethostbyname_ex\(\))d FN(\(in)j(module)f(sock)o(et\),)g(579)1992 4467 y FJ(gethostname\(\))2158 4566 y FN(in)h(module)f(sock)o(et,)h (398)2158 4666 y(in)g(module)f(sock)o(et,)h(579)1992 4765 y FJ(getincrementaldecoder\(\))11 b FN(\(in)k(module)f(codecs\),)h (79)1992 4865 y FJ(getincrementalencoder\(\))c FN(\(in)k(module)f (codecs\),)h(78)1992 4965 y FJ(getinfo\(\))2158 5064 y FN(audio)k(de)n(vice)g(method,)g(932)2158 5164 y(ZipFile)h(method,)e (349)1992 5264 y FJ(getinnerframes\(\))f FN(\(in)j(module)f(inspect\),) g(849)1992 5363 y FJ(GetInputContext\(\))e FN(\(xmlparser)h(method\),)h (265)p 0 5549 3901 4 v 0 5649 a FI(992)3561 b(Inde)n(x)p eop end %%Page: 993 1005 TeXDict begin 993 1004 bop 0 83 a FJ(getint\(\))19 b FN(\(SafeCon\002gP)o(arser)f(method\),)h(312)0 183 y FJ(getitem\(\))g FN(\(in)h(module)f(operator\),)f(185)0 282 y FJ(getiterator\(\))g FN(\(ElementT)m(ree)h(method\),)f(300)0 382 y FJ(getkey\(\))h FN(\(windo)n(w)g(method\),)f(480)0 482 y FJ(getlast\(\))h FN(\(F)o(older)g(method\),)f(239)0 581 y FJ(GetLastError\(\))g FN(\(in)i(module)f(ctypes\),)g(529)0 681 y FJ(getLength\(\))g FN(\(Attrib)n(utes)h(method\),)e(298)0 780 y FJ(getLevelName\(\))g FN(\(in)i(module)f(logging\),)f(453)0 880 y FJ(getline\(\))h FN(\(in)h(module)f(linecache\),)g(338)0 980 y FJ(getLineNumber\(\))f FN(\(Locator)h(method\),)f(297)0 1079 y FJ(getlist\(\))h FN(\(FieldStorage)g(method\),)f(605)0 1179 y FJ(getloadavg\(\))h FN(\(in)h(module)e(os\),)i(414)0 1279 y FJ(getlocale\(\))f FN(\(in)h(module)f(locale\),)g(751)0 1378 y FJ(getLogger\(\))g FN(\(in)h(module)f(logging\),)e(451)0 1478 y FJ(getLoggerClass\(\))h FN(\(in)i(module)f(logging\),)e(451)0 1577 y FJ(getlogin\(\))i FN(\(in)h(module)f(os\),)h(396)0 1677 y FJ(getmaintype\(\))e FN(\(Message)i(method\),)e(240)0 1777 y FJ(getmark\(\))166 1876 y FN(aifc)i(method,)f(698)166 1976 y(A)-5 b(U)p 286 1976 25 4 v 30 w(read)20 b(method,)e(701)166 2076 y(W)-7 b(a)n(v)o(e)p 355 2076 V 30 w(read)20 b(method,)e(703)0 2175 y FJ(getmarkers\(\))166 2275 y FN(aifc)i(method,)f(698)166 2374 y(A)-5 b(U)p 286 2374 V 30 w(read)20 b(method,)e(701)166 2474 y(W)-7 b(a)n(v)o(e)p 355 2474 V 30 w(read)20 b(method,)e(703)0 2574 y FJ(getmaxyx\(\))h FN(\(windo)n(w)g(method\),)f(480)0 2673 y FJ(getmcolor\(\))h FN(\(in)h(module)f(\003\),)h(920)0 2773 y FJ(getmember\(\))f FN(\(T)-7 b(arFile)20 b(method\),)e(353)0 2873 y FJ(getmembers\(\))166 2972 y FN(in)i(module)f(inspect,)h(846)166 3072 y(T)-7 b(arFile)21 b(method,)d(353)0 3171 y FJ(getMessage\(\))166 3271 y FN(LogRecord)g(method,)h(468)166 3371 y(SAXException)f(method,)h (289)0 3470 y FJ(getmessagefilename\(\))e FN(\(F)o(older)i(method\),)f (238)0 3570 y FJ(getMessageID\(\))e FN(\(NTEv)o(entLogHandler)e (method\),)j(465)0 3670 y FJ(getmodule\(\))i FN(\(in)h(module)f (inspect\),)g(848)0 3769 y FJ(getmoduleinfo\(\))f FN(\(in)i(module)f (inspect\),)g(847)0 3869 y FJ(getmodulename\(\))f FN(\(in)i(module)f (inspect\),)g(847)0 3968 y FJ(getmouse\(\))g FN(\(in)h(module)f (curses\),)g(474)0 4068 y FJ(getmro\(\))g FN(\(in)h(module)f (inspect\),)g(849)0 4168 y FJ(getmtime\(\))g FN(\(in)h(module)f (os.path\),)f(326)0 4267 y FJ(getName\(\))h FN(\(Thread)g(method\),)f (545)0 4367 y FJ(getname\(\))h FN(\(Chunk)g(method\),)f(704)0 4467 y FJ(getNameByQName\(\))g FN(\(Attrib)n(utesNS)i(method\),)e(298)0 4566 y FJ(getnameinfo\(\))g FN(\(in)i(module)f(sock)o(et\),)h(579)0 4666 y FJ(getNames\(\))f FN(\(Attrib)n(utes)h(method\),)e(298)0 4765 y FJ(getnames\(\))h FN(\(T)-7 b(arFile)20 b(method\),)e(353)0 4865 y FJ(getnchannels\(\))166 4965 y FN(aifc)i(method,)f(697)166 5064 y(A)-5 b(U)p 286 5064 V 30 w(read)20 b(method,)e(700)166 5164 y(W)-7 b(a)n(v)o(e)p 355 5164 V 30 w(read)20 b(method,)e(702)0 5264 y FJ(getnframes\(\))166 5363 y FN(aifc)i(method,)f(698)2158 83 y(A)-5 b(U)p 2278 83 V 30 w(read)19 b(method,)g(700)2158 183 y(W)-7 b(a)n(v)o(e)p 2347 183 V 30 w(read)19 b(method,)g(702)1992 282 y(getnode,)f(660)1992 382 y FJ(getnode\(\))h FN(\(in)h(module)e (uuid\),)h(659)1992 482 y FJ(getopt\(\))g FN(\(in)h(module)f(getopt\),) f(448)1992 581 y FJ(getopt)h FN(\(standard)g(module\),)f FL(448)1992 681 y FJ(GetoptError)g FN(\(e)o(xception)g(in)j(getopt\),)d (448)1992 780 y FJ(getouterframes\(\))f FN(\(in)j(module)f(inspect\),)g (849)1992 880 y FJ(getoutput\(\))f FN(\(in)i(module)f(commands\),)f (569)1992 980 y FJ(getpagesize\(\))g FN(\(in)i(module)f(resource\),)f (567)1992 1079 y FJ(getparam\(\))g FN(\(Message)i(method\),)f(240)1992 1179 y FJ(getparams\(\))2158 1279 y FN(aifc)h(method,)e(698)2158 1378 y(A)-5 b(U)p 2278 1378 V 30 w(read)19 b(method,)g(700)2158 1478 y(in)h(module)f(al,)h(914)2158 1577 y(W)-7 b(a)n(v)o(e)p 2347 1577 V 30 w(read)19 b(method,)g(702)1992 1677 y FJ(getparyx\(\))f FN(\(windo)n(w)h(method\),)f(480)1992 1777 y FJ(getpass\(\))h FN(\(in)h(module)e(getpass\),)i(472)1992 1876 y FJ(getpass)f FN(\(standard)g(module\),)f FL(472)1992 1976 y FJ(getpath\(\))h FN(\(MH)h(method\),)e(238)1992 2076 y FJ(getpeername\(\))g FN(\(sock)o(et)i(method\),)e(582)1992 2175 y FJ(getpgid\(\))h FN(\(in)h(module)e(os\),)i(397)1992 2275 y FJ(getpgrp\(\))f FN(\(in)h(module)e(os\),)i(397)1992 2374 y FJ(getpid\(\))f FN(\(in)h(module)f(os\),)h(397)1992 2474 y FJ(getplist\(\))e FN(\(Message)i(method\),)f(240)1992 2574 y FJ(getpos\(\))g FN(\(HTMLP)o(arser)g(method\),)f(258)1992 2673 y FJ(getppid\(\))h FN(\(in)h(module)e(os\),)i(397)1992 2773 y FJ(getpreferredencoding\(\))c FN(\(in)k(module)f(locale\),)g (751)1992 2873 y FJ(getprofile\(\))f FN(\(MH)i(method\),)e(238)1992 2972 y FJ(GetProperty\(\))g FN(\(Binary)h(method\),)f(935)1992 3072 y FJ(getProperty\(\))g FN(\(XMLReader)h(method\),)f(296)1992 3171 y FJ(GetPropertyCount\(\))f FN(\(Binary)i(method\),)g(935)1992 3271 y FJ(getprotobyname\(\))e FN(\(in)j(module)f(sock)o(et\),)h(579) 1992 3371 y FJ(getPublicId\(\))2158 3470 y FN(InputSource)d(method,)i (297)2158 3570 y(Locator)g(method,)f(297)1992 3670 y FJ(getpwall\(\))g FN(\(in)i(module)f(pwd\),)g(555)1992 3769 y FJ(getpwnam\(\))f FN(\(in)i(module)f(pwd\),)g(555)1992 3869 y FJ(getpwuid\(\))f FN(\(in)i(module)f(pwd\),)g(555)1992 3968 y FJ(getQNameByName\(\))e FN(\(Attrib)n(utesNS)j(method\),)e(298) 1992 4068 y FJ(getQNames\(\))g FN(\(Attrib)n(utesNS)i(method\),)e(298) 1992 4168 y FJ(getqueuesize\(\))g FN(\(audio)h(con\002guration)e (method\),)h(914)1992 4267 y FJ(getquota\(\))g FN(\(IMAP4)p 2793 4267 V 29 w(stream)i(method\),)e(644)1992 4367 y FJ(getquotaroot\(\))g FN(\(IMAP4)p 2993 4367 V 28 w(stream)i(method\),) f(644)1992 4467 y FJ(getrandbits\(\))f FN(\(in)i(module)f(random\),)e (170)1992 4566 y FJ(getrawheader\(\))h FN(\(AddressList)h(method\),)g (249)1992 4666 y FJ(getreader\(\))f FN(\(in)i(module)f(codecs\),)g(79) 1992 4765 y FJ(getrecursionlimit\(\))e FN(\(in)j(module)f(sys\),)h(830) 1992 4865 y FJ(getrefcount\(\))e FN(\(in)i(module)f(sys\),)h(830)1992 4965 y FJ(getresponse\(\))e FN(\(HTTPResponse)h(method\),)f(635)1992 5064 y FJ(getrlimit\(\))g FN(\(in)i(module)f(resource\),)f(566)1992 5164 y FJ(getroot\(\))h FN(\(ElementT)m(ree)f(method\),)g(301)1992 5264 y FJ(getrusage\(\))g FN(\(in)i(module)f(resource\),)f(567)1992 5363 y FJ(getsampfmt\(\))g FN(\(audio)h(con\002guration)e(method\),)i (914)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(993)p eop end %%Page: 994 1006 TeXDict begin 994 1005 bop 0 83 a FJ(getsample\(\))19 b FN(\(in)h(module)f(audioop\),)e(694)0 183 y FJ(getsampwidth\(\))166 282 y FN(aifc)j(method,)f(697)166 382 y(A)-5 b(U)p 286 382 25 4 v 30 w(read)20 b(method,)e(700)166 482 y(W)-7 b(a)n(v)o(e)p 355 482 V 30 w(read)20 b(method,)e(702)0 581 y FJ(getsequences\(\))g FN(\(F)o(older)h(method\),)f(239)0 681 y FJ(getsequencesfilename\(\))f FN(\(F)o(older)i(method\),)f(238)0 780 y FJ(getservbyname\(\))g FN(\(in)i(module)f(sock)o(et\),)g(579)0 880 y FJ(getservbyport\(\))f FN(\(in)i(module)f(sock)o(et\),)g(580)0 980 y FJ(GetSetDescriptorType)e FN(\(data)j(in)g(types\),)f(142)0 1079 y FJ(getsid\(\))g FN(\(in)h(module)f(os\),)h(398)0 1179 y FJ(getsignal\(\))f FN(\(in)h(module)f(signal\),)g(589)0 1279 y FJ(getsize\(\))166 1378 y FN(Chunk)g(method,)g(704)166 1478 y(in)h(module)f(os.path,)g(326)0 1577 y FJ(getsizes\(\))g FN(\(in)h(module)f(img\002le\),)g(928)0 1677 y FJ(getslice\(\))g FN(\(in)h(module)f(operator\),)e(185)0 1777 y FJ(getsockname\(\))h FN(\(sock)o(et)i(method\),)e(582)0 1876 y FJ(getsockopt\(\))h FN(\(sock)o(et)g(method\),)f(582)0 1976 y FJ(getsource\(\))h FN(\(in)h(module)f(inspect\),)g(848)0 2076 y FJ(getsourcefile\(\))f FN(\(in)i(module)f(inspect\),)g(848)0 2175 y FJ(getsourcelines\(\))f FN(\(in)i(module)f(inspect\),)g(848)0 2275 y FJ(getspall\(\))g FN(\(in)h(module)f(spwd\),)g(555)0 2374 y FJ(getspnam\(\))g FN(\(in)h(module)f(spwd\),)g(555)0 2474 y FJ(getstate\(\))g FN(\(in)h(module)f(random\),)e(169)0 2574 y FJ(getstatus\(\))166 2673 y FN(audio)i(port)h(method,)e(915)166 2773 y(CD)j(player)e (method,)g(917)166 2873 y(in)h(module)f(commands,)f(569)0 2972 y FJ(getstatusoutput\(\))g FN(\(in)i(module)e(commands\),)g(569)0 3072 y FJ(getstr\(\))h FN(\(windo)n(w)g(method\),)f(480)0 3171 y FJ(getstrwidth\(\))g FN(\(in)i(module)f(fm\),)h(925)0 3271 y FJ(getSubject\(\))f FN(\(SMTPHandler)f(method\),)g(466)0 3371 y FJ(getsubtype\(\))h FN(\(Message)g(method\),)g(240)0 3470 y FJ(GetSummaryInformation\(\))d FN(\(Binary)k(method\),)e(934)0 3570 y FJ(getSystemId\(\))166 3670 y FN(InputSource)g(method,)g(297)166 3769 y(Locator)h(method,)g(297)0 3869 y FJ(getsyx\(\))g FN(\(in)h(module)f(curses\),)h(474)0 3968 y FJ(gettarinfo\(\))f FN(\(T)-7 b(arFile)20 b(method\),)e(354)0 4068 y FJ(gettempdir\(\))h FN(\(in)h(module)e(temp\002le\),)i(336)0 4168 y FJ(gettempprefix\(\))e FN(\(in)i(module)f(temp\002le\),)g(336)0 4267 y FJ (getTestCaseNames\(\))e FN(\(T)-6 b(estLoader)19 b(method\),)f(800)0 4367 y FJ(gettext\(\))166 4467 y FN(GNUT)m(ranslations)h(method,)g(743) 166 4566 y(in)h(module)f(gette)o(xt,)g(740)166 4666 y(NullT)m (ranslations)g(method,)g(742)0 4765 y FJ(gettext)g FN(\(standard)g (module\),)f FL(739)0 4865 y FJ(gettimeout\(\))h FN(\(sock)o(et)g (method\),)f(583)0 4965 y FJ(gettrackinfo\(\))g FN(\(CD)j(player)e (method\),)f(917)0 5064 y FJ(getType\(\))h FN(\(Attrib)n(utes)h (method\),)e(298)0 5164 y FJ(gettype\(\))h FN(\(Message)h(method\),)e (240)0 5264 y FJ(getuid\(\))h FN(\(in)h(module)f(os\),)h(397)0 5363 y FJ(geturl\(\))f FN(\(P)o(arseResult)h(method\),)f(663)1992 83 y FJ(getuser\(\))g FN(\(in)h(module)e(getpass\),)i(472)1992 183 y FJ(getValue\(\))e FN(\(Attrib)n(utes)i(method\),)e(298)1992 282 y FJ(getvalue\(\))g FN(\(StringIO)h(method\),)g(74)1992 382 y FJ(getValueByQName\(\))e FN(\(Attrib)n(utesNS)j(method\),)e(298) 1992 482 y FJ(getweakrefcount\(\))f FN(\(in)j(module)f(weakref\),)f (135)1992 581 y FJ(getweakrefs\(\))g FN(\(in)i(module)f(weakref\),)f (135)1992 681 y FJ(getwelcome\(\))2158 780 y FN(FTP)i(method,)f(638) 2158 880 y(NNTP)h(method,)f(649)2158 980 y(POP3)p 2357 980 V 29 w(SSL)i(method,)e(641)1992 1079 y FJ(getwidth\(\))f FN(\(audio)h(con\002guration)f(method\),)g(914)1992 1179 y FJ(getwin\(\))h FN(\(in)h(module)f(curses\),)g(474)1992 1279 y FJ(getwindowsversion\(\))e FN(\(in)j(module)f(sys\),)h(830)1992 1378 y FJ(getwriter\(\))e FN(\(in)i(module)f(codecs\),)g(79)1992 1478 y FJ(getyx\(\))g FN(\(windo)n(w)g(method\),)f(480)1992 1577 y FJ(gid)i FN(\(T)-7 b(arInfo)18 b(attrib)n(ute\),)h(356)1992 1677 y FJ(GL)h FN(\(standard)f(module\),)f FL(927)1992 1777 y FJ(gl)i FN(\(b)n(uilt-in)f(module\),)f FL(925)1992 1876 y FJ(glob\(\))2158 1976 y FN(Directory)g(method,)h(937)2158 2076 y(in)h(module)f(glob,)g(336)1992 2175 y FJ(glob)h FN(\(standard)e(module\),)g FL(336)p FN(,)h(337)1992 2275 y FJ(globals\(\))g FN(\(in)h(module)e(\),)j(8)1992 2374 y FJ(globs)e FN(\(DocT)-6 b(est)20 b(attrib)n(ute\),)f(781)1992 2474 y FJ(gmtime\(\))g FN(\(in)h(module)f(time\),)g(417)1992 2574 y FJ(gname)g FN(\(T)-7 b(arInfo)19 b(attrib)n(ute\),)g(356)1992 2673 y(GNOME,)g(744)1992 2773 y FJ(gnu_getopt\(\))f FN(\(in)i(module)f (getopt\),)g(448)1992 2873 y(Gopher)2158 2972 y(protocol,)f(620,)h(640) 1992 3072 y FJ(gopher_open\(\))f FN(\(GopherHandler)f(method\),)h(630) 1992 3171 y(gopher)p 2230 3171 V 27 w(proxy)-5 b(,)18 b(617)1992 3271 y FJ(GopherError)g FN(\(e)o(xception)g(in)j(urllib2\),) d(623)1992 3371 y FJ(GopherHandler)g FN(\(class)j(in)f(urllib2\),)f (624)1992 3470 y FJ(gopherlib)g FN(\(standard)f(module\),)g FL(640)1992 3570 y FJ(got)i FN(\(DocT)-6 b(estF)o(ailure)19 b(attrib)n(ute\),)g(788)1992 3670 y FJ(goto\(\))g FN(\(in)h(module)f (turtle\),)g(732)1992 3769 y(Graphical)g(User)h(Interf)o(ace,)f(713) 1992 3869 y(Greenwich)f(Mean)i(T)m(ime,)g(415)1992 3968 y FJ(grey22grey\(\))e FN(\(in)i(module)f(imageop\),)f(697)1992 4068 y FJ(grey2grey2\(\))g FN(\(in)i(module)f(imageop\),)f(697)1992 4168 y FJ(grey2grey4\(\))g FN(\(in)i(module)f(imageop\),)f(697)1992 4267 y FJ(grey2mono\(\))g FN(\(in)i(module)f(imageop\),)f(696)1992 4367 y FJ(grey42grey\(\))g FN(\(in)i(module)f(imageop\),)f(697)1992 4467 y FJ(group\(\))2158 4566 y FN(MatchObject)h(method,)f(60)2158 4666 y(NNTP)i(method,)f(650)1992 4765 y FJ(groupby\(\))g FN(\(in)h(module)e(itertools\),)i(174)1992 4865 y FJ(groupdict\(\))e FN(\(MatchObject)h(method\),)f(61)1992 4965 y FJ(groupindex)g FN(\(Re)o(ge)o(xObject)h(attrib)n(ute\),)g(60)1992 5064 y FJ(groups\(\))g FN(\(MatchObject)g(method\),)f(60)1992 5164 y FJ(grp)i FN(\(b)n(uilt-in)f(module\),)f FL(556)1992 5264 y FJ(gt\(\))i FN(\(in)g(module)e(operator\),)g(183)p 0 5549 3901 4 v 0 5649 a FI(994)3561 b(Inde)n(x)p eop end %%Page: 995 1007 TeXDict begin 995 1006 bop 0 83 a FJ(guess_all_extensions\(\))15 b FN(\(in)k(module)f(mimetypes\),)332 183 y(241)0 282 y FJ(guess_extension\(\))166 382 y FN(in)i(module)f(mimetypes,)g(241) 166 482 y(MimeT)-7 b(ypes)19 b(method,)g(243)0 581 y FJ(guess_scheme\(\))f FN(\(in)i(module)f(wsgiref.util\),)g(610)0 681 y FJ(guess_type\(\))166 780 y FN(in)h(module)f(mimetypes,)g(241)166 880 y(MimeT)-7 b(ypes)19 b(method,)g(243)0 980 y(GUI,)h(713)0 1079 y FJ(gzip)g FN(\(standard)f(module\),)f FL(345)0 1179 y FJ(GzipFile)h FN(\(class)i(in)f(gzip\),)g(345)0 1375 y FE(H)0 1498 y FJ(halfdelay\(\))f FN(\(in)h(module)f(curses\),)g (475)0 1597 y FJ(handle\(\))187 1697 y FN(method,)f(455,)h(461)166 1797 y(BaseHTTPRequestHandler)g(method,)f(669)166 1896 y(in)i(module)f(Sock)o(etServ)o(er)m(,)f(667)166 1996 y(WSGIRequestHandler)h(method,)f(613)0 2096 y FJ(handle_accept\(\))g FN(\(dispatcher)h(method\),)f(593)0 2195 y FJ(handle_charref\(\))166 2295 y FN(HTMLP)o(arser)h(method,)g(258)166 2394 y(SGMLP)o(arser)h (method,)e(261)0 2494 y FJ(handle_close\(\))166 2594 y FN(async)p 361 2594 25 4 v 29 w(chat)i(method,)f(596)166 2693 y(dispatcher)g(method,)g(593)0 2793 y FJ(handle_comment\(\))166 2893 y FN(HTMLP)o(arser)g(method,)g(259)166 2992 y(SGMLP)o(arser)h (method,)e(261)0 3092 y FJ(handle_connect\(\))g FN(\(dispatcher)g (method\),)h(593)0 3191 y FJ(handle_data\(\))166 3291 y FN(HTMLP)o(arser)g(method,)g(258)166 3391 y(SGMLP)o(arser)h(method,)e (260)0 3490 y FJ(handle_decl\(\))166 3590 y FN(HTMLP)o(arser)h(method,) g(259)166 3690 y(SGMLP)o(arser)h(method,)e(261)0 3789 y FJ(handle_endtag\(\))166 3889 y FN(HTMLP)o(arser)h(method,)g(258)166 3988 y(SGMLP)o(arser)h(method,)e(260)0 4088 y FJ(handle_entityref\(\)) 166 4188 y FN(HTMLP)o(arser)h(method,)g(259)166 4287 y(SGMLP)o(arser)h(method,)e(261)0 4387 y FJ(handle_error\(\))166 4487 y FN(dispatcher)h(method,)g(593)166 4586 y(in)h(module)f(Sock)o (etServ)o(er)m(,)f(666)0 4686 y FJ(handle_expt\(\))g FN(\(dispatcher)h(method\),)f(593)0 4786 y FJ(handle_image\(\))g FN(\(HTMLP)o(arser)h(method\),)f(263)0 4885 y FJ (handle_one_request\(\))37 b FN(\(BaseHTTPRequestHand-)332 4985 y(ler)20 b(method\),)f(669)0 5084 y FJ(handle_pi\(\))g FN(\(HTMLP)o(arser)g(method\),)f(259)0 5184 y FJ(handle_read\(\))166 5284 y FN(async)p 361 5284 V 29 w(chat)i(method,)f(596)166 5383 y(dispatcher)g(method,)g(593)1992 83 y FJ(handle_request\(\))2158 183 y FN(in)h(module)f(Sock)o(etServ)o(er)m(,)f(666)2158 282 y(SimpleXMLRPCRequestHandler)g(method,)g(691)1992 382 y FJ(handle_startendtag\(\))69 b FN(\(HTMLP)o(arser)i(method\),) 2324 482 y(258)1992 581 y FJ(handle_starttag\(\))2158 681 y FN(HTMLP)o(arser)19 b(method,)f(258)2158 780 y(SGMLP)o(arser)h (method,)g(260)1992 880 y FJ(handle_write\(\))2158 980 y FN(async)p 2353 980 V 28 w(chat)i(method,)d(596)2158 1079 y(dispatcher)h(method,)f(593)1992 1179 y FJ(handleError\(\))2178 1279 y FN(method,)h(461)2158 1378 y(Sock)o(etHandler)f(method,)g(463,)h (464)1992 1478 y FJ(handler\(\))g FN(\(in)h(module)e(cgitb\),)i(610) 1992 1577 y FJ(has_colors\(\))e FN(\(in)i(module)f(curses\),)g(474)1992 1677 y FJ(has_data\(\))f FN(\(Request)i(method\),)f(625)1992 1777 y FJ(has_extn\(\))f FN(\(SMTP)j(method\),)d(653)1992 1876 y FJ(has_header\(\))2158 1976 y FN(Request)i(method,)e(625)2158 2076 y(Snif)n(fer)h(method,)f(305)1992 2175 y FJ(has_ic\(\))h FN(\(in)h(module)f(curses\),)g(474)1992 2275 y FJ(has_il\(\))g FN(\(in)h(module)f(curses\),)g(474)1992 2374 y FJ(has_ipv6)g FN(\(data)g(in)i(sock)o(et\),)e(578)1992 2474 y FJ(has_key\(\))2178 2574 y FN(method,)g(381)2158 2673 y(dictionary)f(method,)h(37)2158 2773 y(in)h(module)f(curses,)h(475)2158 2873 y(Mailbox)f(method,)f(220) 2158 2972 y(Message)i(method,)e(192)1992 3072 y FJ (has_nonstandard_attr\(\))e FN(\(Cookie)j(method\),)g(679)1992 3171 y FJ(has_option\(\))f FN(\(SafeCon\002gP)o(arser)g(method\),)g (311)1992 3271 y FJ(has_section\(\))g FN(\(SafeCon\002gP)o(arser)g (method\),)g(311)1992 3371 y FJ(hasattr\(\))h FN(\(in)h(module)e(\),)j (8)1992 3470 y FJ(hasAttribute\(\))d FN(\(Element)h(method\),)f(278) 1992 3570 y FJ(hasAttributeNS\(\))f FN(\(Element)i(method\),)g(278)1992 3670 y FJ(hasAttributes\(\))e FN(\(Node)j(method\),)e(275)1992 3769 y FJ(hasChildNodes\(\))f FN(\(Node)j(method\),)e(276)1992 3869 y FJ(hascompare)g FN(\(data)i(in)g(dis\),)h(889)1992 3968 y FJ(hasconst)e FN(\(data)g(in)i(dis\),)f(889)1992 4068 y FJ(hasFeature\(\))e FN(\(DOMImplementation)f(method\),)h(274) 1992 4168 y FJ(hasfree)h FN(\(data)h(in)g(dis\),)g(889)1992 4267 y FJ(hash\(\))f FN(\(in)h(module)f(\),)h(8)1992 4367 y FJ(hashlib)f FN(\(b)n(uilt-in)g(module\),)f FL(319)1992 4467 y FJ(hashopen\(\))g FN(\(in)i(module)f(bsddb\),)g(380)1992 4566 y FJ(hasjabs)g FN(\(data)h(in)g(dis\),)g(889)1992 4666 y FJ(hasjrel)f FN(\(data)h(in)g(dis\),)g(889)1992 4765 y FJ(haslocal)f FN(\(data)g(in)i(dis\),)f(889)1992 4865 y FJ(hasname)f FN(\(data)h(in)g(dis\),)g(889)1992 4965 y FJ(have_unicode)e FN(\(data)i(in)g(test.test)p 3138 4965 V 30 w(support\),)f(804)1992 5064 y FJ(head\(\))g FN(\(NNTP)h(method\),)f(650)1992 5164 y FJ(Header)g FN(\(class)i(in)f (email.header\),)e(202)1992 5264 y FJ(header_encode\(\))f FN(\(Charset)j(method\),)f(205)1992 5363 y FJ(header_encoding)e FN(\(data)j(in)h(email.charset\),)d(204)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(995)p eop end %%Page: 996 1008 TeXDict begin 996 1007 bop 0 83 a FJ(header_offset)18 b FN(\(ZipInfo)g(attrib)n(ute\),)i(351)0 183 y FJ(HeaderParseError)e FN(\(e)o(xception)g(in)i(email.errors\),)e(207)0 282 y FJ(Headers)h FN(\(class)i(in)g(wsgiref.headers\),)c(611)0 382 y(headers)166 482 y(MIME,)j(241,)f(602)0 581 y FJ(headers)166 681 y FN(AddressList)h(attrib)n(ute,)g(250)166 780 y (BaseHTTPRequestHandler)f(attrib)n(ute,)g(668)166 880 y(Serv)o(erProxy)f(attrib)n(ute,)h(687)0 980 y FJ(heading\(\))g FN(\(in)h(module)f(turtle\),)g(732)0 1079 y FJ(heapify\(\))g FN(\(in)h(module)f(heapq\),)f(122)0 1179 y FJ(heapmin\(\))h FN(\(in)h(module)f(msvcrt\),)g(940)0 1279 y FJ(heappop\(\))g FN(\(in)h(module)f(heapq\),)f(122)0 1378 y FJ(heappush\(\))h FN(\(in)h(module)f(heapq\),)f(122)0 1478 y FJ(heapq)i FN(\(standard)e(module\),)h FL(121)0 1577 y FJ(heapreplace\(\))f FN(\(in)i(module)f(heapq\),)g(122)0 1677 y FJ(helo\(\))h FN(\(SMTP)g(method\),)e(653)0 1777 y(help)166 1876 y(online,)h(763)0 1976 y FJ(help\(\))166 2076 y FN(in)h(module)f(,)i(8)166 2175 y(NNTP)g(method,)d(650)0 2275 y FJ(herror)i FN(\(e)o(xception)e (in)i(sock)o(et\),)f(578)0 2374 y FJ(hex\(\))h FN(\(in)g(module)f(\),)h (8)0 2474 y FJ(hex)g FN(\(UUID)g(attrib)n(ute\),)f(659)0 2574 y(he)o(xadecimal)166 2673 y(literals,)i(25)0 2773 y FJ(hexbin\(\))e FN(\(in)h(module)f(binhe)o(x\),)f(253)0 2873 y FJ(hexdigest\(\))166 2972 y FN(hash)i(method,)f(320)166 3072 y(hmac)h(method,)e(321)166 3171 y(md5)h(method,)g(322)166 3271 y(sha)h(method,)f(323)0 3371 y FJ(hexdigits)g FN(\(data)h(in)g (string\),)f(47)0 3470 y FJ(hexlify\(\))g FN(\(in)h(module)f (binascii\),)g(254)0 3570 y FJ(hexversion)g FN(\(data)h(in)g(sys\),)g (830)0 3670 y FJ(hidden\(\))f FN(\()i(method\),)d(491)0 3769 y FJ(hide\(\))i FN(\()g(method\),)e(491)0 3869 y FJ(hide_cookie2)h FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)g(676)0 3968 y FJ(hide_form\(\))g FN(\(form)f(method\),)h(920)0 4068 y FJ(hide_object\(\))f FN(\(FORMS)j(object)f(method\),)e(923)0 4168 y FJ(HierarchyRequestErr)e FN(\(e)o(xception)g(in)j(xml.dom\),)e (280)0 4267 y FJ(HIGHEST_PROTOCOL)h FN(\(data)h(in)i(pickle\),)e(361)0 4367 y FJ(hline\(\))g FN(\(windo)n(w)g(method\),)f(480)0 4467 y FJ(HList)i FN(\(class)h(in)f(T)m(ix\),)g(727)0 4566 y FJ(hls_to_rgb\(\))f FN(\(in)h(module)e(colorsys\),)h(705)0 4666 y FJ(hmac)h FN(\(standard)f(module\),)f FL(321)0 4765 y FN(HOME,)i(326,)f(851)0 4865 y(HOMEDRIVE,)h(326)0 4965 y(HOMEP)-8 b(A)f(TH,)20 b(326)0 5064 y FJ(hook_compressed\(\))e FN(\(in)i(module)e(\002leinput\),)h(329)0 5164 y FJ(hook_encoded\(\))f FN(\(in)i(module)f(\002leinput\),)g(330)0 5264 y FJ(hosts)h FN(\(netrc)f(attrib)n(ute\),)g(314)0 5363 y FJ(hotshot)g FN(\(standard)g(module\),)f FL(819)1992 83 y FJ(hotshot.stats)g FN(\(standard)h(module\),)f FL(820)1992 183 y FJ(hour)2158 282 y FN(datetime)h(attrib)n(ute,)h(102)2158 382 y(time)g(attrib)n (ute,)f(106)1992 482 y FJ(HRESULT)g FN(\(class)i(in)f(ctypes\),)f(532) 1992 581 y FJ(hsv_to_rgb\(\))f FN(\(in)i(module)f(colorsys\),)g(705) 1992 681 y(HTML,)g(257,)g(262,)g(620)1992 780 y FJ(HTMLCalendar)f FN(\(class)j(in)f(calendar\),)f(115)1992 880 y FJ(HtmlDiff)g FN(\(class)i(in)f(dif)n(\003ib\),)f(66)1992 980 y FJ(htmlentitydefs)f FN(\(standard)g(module\),)h FL(264)1992 1079 y FJ(htmllib)g FN(\(standard)g(module\),)f FL(262)p FN(,)h(620)1992 1179 y FJ(HTMLParseError)2158 1279 y FN(e)o(xception)f(in)i(htmllib,)g (263)2158 1378 y(e)o(xception)e(in)i(HTMLP)o(arser)m(,)f(258)1992 1478 y FJ(HTMLParser)2158 1577 y FN(class)i(in)f(htmllib,)f(263,)h(909) 2158 1677 y(class)h(in)f(HTMLP)o(arser)m(,)f(257)2158 1777 y(standard)g(module,)f FL(257)1992 1876 y FJ(htonl\(\))h FN(\(in)h(module)f(sock)o(et\),)g(580)1992 1976 y FJ(htons\(\))g FN(\(in)h(module)f(sock)o(et\),)g(580)1992 2076 y(HTTP)2158 2175 y FJ(httplib)g FN(\(standard)g(module\),)f(632)2158 2275 y(protocol,)g(602,)h(620,)g(632,)g(667)1992 2374 y FJ(http_error_301\(\))324 b FN(\(HTTPRedirectHandler)2324 2474 y(method\),)18 b(628)1992 2574 y FJ(http_error_302\(\))324 b FN(\(HTTPRedirectHandler)2324 2673 y(method\),)18 b(628)1992 2773 y FJ(http_error_303\(\))324 b FN(\(HTTPRedirectHandler)2324 2873 y(method\),)18 b(628)1992 2972 y FJ(http_error_307\(\))324 b FN(\(HTTPRedirectHandler)2324 3072 y(method\),)18 b(628)1992 3171 y FJ(http_error_401\(\))2158 3271 y FN(HTTPBasicAuthHandler)g (method,)g(629)2158 3371 y(HTTPDigestAuthHandler)f(method,)i(629)1992 3470 y FJ(http_error_407\(\))2158 3570 y FN(ProxyBasicAuthHandler)e (method,)h(629)2158 3670 y(ProxyDigestAuthHandler)e(method,)i(629)1992 3769 y FJ(http_error_auth_reqed\(\))2158 3869 y FN (AbstractBasicAuthHandler)g(method,)g(629)2158 3968 y (AbstractDigestAuthHandler)f(method,)h(629)1992 4068 y FJ(http_error_default\(\))75 b FN(\(BaseHandler)j(method\),)2324 4168 y(627)1992 4267 y FJ(http_open\(\))18 b FN(\(HTTPHandler)h (method\),)f(629)1992 4367 y FJ(HTTP_PORT)h FN(\(data)g(in)i (httplib\),)e(633)1992 4467 y(http)p 2127 4467 25 4 v 29 w(proxy)-5 b(,)17 b(617,)i(631)1992 4566 y FJ(http_version)f FN(\(BaseHandler)h(attrib)n(ute\),)g(617)1992 4666 y FJ(HTTPBasicAuthHandler)e FN(\(class)j(in)h(urllib2\),)d(624)1992 4765 y FJ(HTTPConnection)g FN(\(class)i(in)h(httplib\),)e(632)1992 4865 y FJ(HTTPCookieProcessor)e FN(\(class)k(in)f(urllib2\),)e(624)1992 4965 y(httpd,)h(667)1992 5064 y FJ(HTTPDefaultErrorHandler)d FN(\(class)21 b(in)f(urllib2\),)f(623)1992 5164 y FJ (HTTPDigestAuthHandler)d FN(\(class)21 b(in)f(urllib2\),)f(624)1992 5264 y FJ(HTTPError)g FN(\(e)o(xception)f(in)i(urllib2\),)e(623)1992 5363 y FJ(HTTPException)g FN(\(e)o(xception)g(in)i(httplib\),)f(633)p 0 5549 3901 4 v 0 5649 a FI(996)3561 b(Inde)n(x)p eop end %%Page: 997 1009 TeXDict begin 997 1008 bop 0 83 a FJ(HTTPHandler)166 183 y FN(class)21 b(in)g(logging,)d(466)166 282 y(class)j(in)g (urllib2,)d(624)0 382 y FJ(httplib)h FN(\(standard)g(module\),)f FL(632)0 482 y FJ(HTTPPasswordMgr)g FN(\(class)j(in)f(urllib2\),)f(624) 0 581 y FJ(HTTPPasswordMgrWithDefaultRealm)50 b FN(\(class)55 b(in)332 681 y(urllib2\),)19 b(624)0 780 y FJ(HTTPRedirectHandler)e FN(\(class)k(in)f(urllib2\),)f(624)0 880 y FJ(HTTPResponse)g FN(\(class)h(in)h(httplib\),)e(633)0 980 y FJ(https_open\(\))g FN(\(HTTPSHandler)f(method\),)g(629)0 1079 y FJ(HTTPS_PORT)h FN(\(data)h(in)g(httplib\),)f(633)0 1179 y FJ(HTTPSConnection)f FN(\(class)j(in)f(httplib\),)f(632)0 1279 y FJ(HTTPServer)g FN(\(class)i(in)f(BaseHTTPServ)o(er\),)f(668)0 1378 y FJ(HTTPSHandler)g FN(\(class)h(in)h(urllib2\),)d(624)0 1478 y(hyperte)o(xt,)f(262)0 1577 y FJ(hypot\(\))i FN(\(in)h(module)f (math\),)g(150)0 1770 y FE(I)0 1893 y FJ(I)i FN(\(data)e(in)i(re\),)e (57)0 1993 y(I/O)h(control)166 2092 y(b)n(uf)n(fering,)e(10,)h(398,)g (582)166 2192 y(POSIX,)h(558)166 2292 y(tty)-5 b(,)20 b(558)168 2391 y(U)t FH(N)t(I)t(X)r FN(,)h(560)0 2491 y FJ(iadd\(\))f FN(\(in)g(module)e(operator\),)g(185)0 2590 y FJ(iand\(\))i FN(\(in)g(module)e(operator\),)g(185)0 2690 y FJ(ibufcount\(\))h FN(\(audio)g(de)n(vice)g(method\),)f(932)0 2790 y FJ(iconcat\(\))h FN(\(in)h(module)f(operator\),)f(185)0 2889 y FJ(id\(\))166 2989 y FN(in)i(module)f(,)i(8)166 3089 y(T)-6 b(estCase)21 b(method,)e(798)0 3188 y FJ(idcok\(\))g FN(\(windo)n(w)g(method\),)f(480)0 3288 y FJ(ident)i FN(\(data)g(in)g(cd\),)f(916)0 3387 y FJ(identchars)g FN(\(Cmd)h(attrib)n(ute\),)f(758)0 3487 y FJ(idiv\(\))h FN(\(in)g(module)e(operator\),)g(185)0 3587 y(Idle,)i(733)0 3686 y FJ(idlok\(\))f FN(\(windo)n(w)g(method\),)f(480)0 3786 y(IEEE-754,)g(852)0 3886 y FJ(if)166 3985 y FN(statement,)i(23)0 4085 y FJ(ifilter\(\))f FN(\(in)h(module)f(itertools\),)g(175)0 4185 y FJ(ifilterfalse\(\))f FN(\(in)i(module)f(itertools\),)g(175)0 4284 y FJ(ifloordiv\(\))g FN(\(in)h(module)f(operator\),)e(185)0 4384 y FJ(iglob\(\))i FN(\(in)h(module)f(glob\),)g(336)0 4483 y FJ(ignorableWhitespace\(\))301 b FN(\(ContentHandler)332 4583 y(method\),)18 b(292)0 4683 y FJ(ignore_errors\(\))g FN(\(in)i(module)f(codecs\),)g(79)0 4782 y FJ(IGNORE_EXCEPTION_DETAIL)d FN(\(data)k(in)h(doctest\),)e(773)0 4882 y FJ(ignore_zeros)g FN(\(T)-7 b(arFile)20 b(attrib)n(ute\),)f(355)0 4982 y FJ(IGNORECASE)g FN(\(data)h(in)g(re\),)g(57)0 5081 y FJ(ihave\(\))f FN(\(NNTP)i(method\),)d(651)0 5181 y FJ(ihooks)i FN(\(standard)e(module\),)h(3)0 5280 y FJ(ilshift\(\))g FN(\(in)h(module)f(operator\),)f(186)0 5380 y FJ(imageop)h FN(\(b)n(uilt-in)h(module\),)e FL(696)1992 83 y FJ(imap\(\))h FN(\(in)h(module)f(itertools\),)g(175)1992 183 y(IMAP4)2158 282 y(protocol,)f(642)1992 382 y FJ(IMAP4)h FN(\(class)i(in)f (imaplib\),)f(642)1992 482 y FJ(IMAP4.abort)f FN(\(e)o(xception)g(in)j (imaplib\),)d(642)1992 581 y FJ(IMAP4.error)g FN(\(e)o(xception)g(in)j (imaplib\),)d(642)1992 681 y FJ(IMAP4.readonly)g FN(\(e)o(xception)g (in)i(imaplib\),)f(642)1992 780 y(IMAP4)p 2247 780 25 4 v 28 w(SSL)2158 880 y(protocol,)f(642)1992 980 y FJ(IMAP4_SSL)h FN(\(class)h(in)h(imaplib\),)e(642)1992 1079 y(IMAP4)p 2247 1079 V 28 w(stream)2158 1179 y(protocol,)f(642)1992 1279 y FJ(IMAP4_stream)g FN(\(class)j(in)f(imaplib\),)f(643)1992 1378 y FJ(imaplib)g FN(\(standard)g(module\),)f FL(642)1992 1478 y FJ(imgfile)h FN(\(b)n(uilt-in)g(module\),)f FL(927)1992 1577 y FJ(imghdr)h FN(\(standard)g(module\),)f FL(706)1992 1677 y FJ(immedok\(\))h FN(\(windo)n(w)f(method\),)h(480)1992 1777 y FJ(ImmutableSet)f FN(\(class)j(in)f(sets\),)h(128)1992 1876 y FJ(imod\(\))e FN(\(in)h(module)f(operator\),)f(186)1992 1976 y FJ(imp)i FN(\(b)n(uilt-in)f(module\),)f(3,)i FL(865)1992 2076 y FJ(import)2158 2175 y FN(statement,)f(3,)h(865)1992 2275 y(Import)e(module,)h(734)1992 2374 y FJ(ImportError)f FN(\(e)o(xception)g(in)j(e)o(xceptions\),)c(19)1992 2474 y FJ(ImportWarning)h FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e(21) 1992 2574 y FJ(ImproperConnectionState)23 b FN(\(e)o(xception)i(in)j (httplib\),)2324 2673 y(633)1992 2773 y FJ(imul\(\))19 b FN(\(in)h(module)f(operator\),)f(186)1992 2873 y FJ(in)2158 2972 y FN(operator)m(,)f(24,)j(28)1992 3072 y FJ(in_dll\(\))f FN(\()p 2444 3072 V 29 w(CData)i(method\),)d(530)1992 3171 y FJ(in_table_a1\(\))g FN(\(in)i(module)f(stringprep\),)e(92)1992 3271 y FJ(in_table_b1\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 3371 y FJ(in_table_c11\(\))h FN(\(in)i(module)e(stringprep\),)g(92)1992 3470 y FJ(in_table_c11_c12\(\))f FN(\(in)j(module)f(stringprep\),)f(92) 1992 3570 y FJ(in_table_c12\(\))g FN(\(in)i(module)e(stringprep\),)g (92)1992 3670 y FJ(in_table_c21\(\))g FN(\(in)i(module)e(stringprep\),) g(92)1992 3769 y FJ(in_table_c21_c22\(\))f FN(\(in)j(module)f (stringprep\),)f(92)1992 3869 y FJ(in_table_c22\(\))g FN(\(in)i(module)e(stringprep\),)g(92)1992 3968 y FJ(in_table_c3\(\))g FN(\(in)i(module)f(stringprep\),)e(92)1992 4068 y FJ(in_table_c4\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 4168 y FJ(in_table_c5\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 4267 y FJ(in_table_c6\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 4367 y FJ(in_table_c7\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 4467 y FJ(in_table_c8\(\))h FN(\(in)i(module)f(stringprep\),)e(92)1992 4566 y FJ(in_table_c9\(\))h FN(\(in)i(module)f(stringprep\),)e(93)1992 4666 y FJ(in_table_d1\(\))h FN(\(in)i(module)f(stringprep\),)e(93)1992 4765 y FJ(in_table_d2\(\))h FN(\(in)i(module)f(stringprep\),)e(93)1992 4865 y FJ(INADDR_)2342 4880 y(*)2411 4865 y FN(\(data)i(in)i(sock)o(et\),)e(578)1992 4965 y FJ(inch\(\))g FN(\(windo)n(w)g(method\),)f(480)1992 5064 y FJ(Incomplete)g FN(\(e)o(xception)g(in)j(binascii\),)e(255)1992 5164 y FJ(IncompleteRead)f FN(\(e)o(xception)g(in)i(httplib\),)f(633) 1992 5264 y FJ(IncrementalDecoder)e FN(\(class)k(in)f(codecs\),)f(82) 1992 5363 y FJ(IncrementalEncoder)e FN(\(class)k(in)f(codecs\),)f(81)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(997)p eop end %%Page: 998 1010 TeXDict begin 998 1009 bop 0 83 a FJ(IncrementalParser)44 b FN(\(class)j(in)g(xml.sax.xmlreader\),)332 183 y(294)0 282 y FJ(indent)20 b FN(\(Example)e(attrib)n(ute\),)h(782)0 382 y(indentation,)f(735)0 482 y(Independent)f(JPEG)k(Group,)e(928)0 581 y FJ(index\(\))166 681 y FN(array)g(method,)g(126)166 780 y(in)h(module)f(operator)m(,)f(184)166 880 y(in)i(module)f(string,) h(51)166 980 y(string)g(method,)e(29)0 1079 y FJ(index)i FN(\(data)g(in)g(cd\),)f(916)0 1179 y FJ(index\(\))g FN(\(list)i(method\),)e(35)0 1279 y FJ(IndexError)g FN(\(e)o(xception)f (in)i(e)o(xceptions\),)e(19)0 1378 y FJ(indexOf\(\))h FN(\(in)h(module)f(operator\),)f(185)0 1478 y FJ(IndexSizeErr)h FN(\(e)o(xception)e(in)k(xml.dom\),)d(280)0 1577 y FJ(inet_aton\(\))h FN(\(in)h(module)f(sock)o(et\),)g(580)0 1677 y FJ(inet_ntoa\(\))g FN(\(in)h(module)f(sock)o(et\),)g(580)0 1777 y FJ(inet_ntop\(\))g FN(\(in)h(module)f(sock)o(et\),)g(581)0 1876 y FJ(inet_pton\(\))g FN(\(in)h(module)f(sock)o(et\),)g(581)0 1976 y FJ(Inexact)g FN(\(class)i(in)g(decimal\),)e(162)0 2076 y FJ(infile)h FN(\(shle)o(x)f(attrib)n(ute\),)g(761)0 2175 y(In\002nity)-5 b(,)19 b(8,)h(50)0 2275 y FJ(info\(\))187 2374 y FN(method,)e(455)166 2474 y(in)i(module)f(logging,)f(452)166 2574 y(NullT)m(ranslations)h (method,)g(742)0 2673 y FJ(infolist\(\))g FN(\(ZipFile)h(method\),)e (349)0 2773 y(InfoSeek)g(Corporation,)g(811)0 2873 y(ini)i(\002le,)h (310)0 2972 y FJ(init\(\))166 3072 y FN(in)f(module)f(fm,)h(924)166 3171 y(in)g(module)f(mimetypes,)g(241)0 3271 y FJ(init_builtin\(\))f FN(\(in)i(module)f(imp\),)g(867)0 3371 y FJ(init_color\(\))g FN(\(in)h(module)e(curses\),)i(475)0 3470 y FJ(init_database\(\))e FN(\(in)i(module)f(msilib\),)h(934)0 3570 y FJ(init_frozen\(\))e FN(\(in)i(module)f(imp\),)g(867)0 3670 y FJ(init_pair\(\))g FN(\(in)h(module)f(curses\),)g(475)0 3769 y FJ(inited)h FN(\(data)f(in)i(mimetypes\),)d(241)0 3869 y FJ(initial_indent)g FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(77)0 3968 y FJ(initscr\(\))g FN(\(in)h(module)f(curses\),)h(475)0 4068 y FJ(input\(\))166 4168 y FN(b)n(uilt-in)g(function,)e(833)166 4267 y(in)i(module)f(,)i(9)166 4367 y(in)f(module)f(\002leinput,)h(328) 0 4467 y FJ(input_charset)e FN(\(data)i(in)g(email.charset\),)f(204)0 4566 y FJ(input_codec)g FN(\(data)g(in)i(email.charset\),)d(204)0 4666 y FJ(InputOnly)h FN(\(class)i(in)f(T)m(ix\),)g(728)0 4765 y FJ(InputSource)f FN(\(class)h(in)h(xml.sax.xmlreader\),)16 b(295)0 4865 y FJ(InputType)j FN(\(data)h(in)g(cStringIO\),)f(75)0 4965 y FJ(insch\(\))g FN(\(windo)n(w)g(method\),)f(480)0 5064 y FJ(insdelln\(\))h FN(\(windo)n(w)g(method\),)f(480)0 5164 y FJ(insert\(\))166 5264 y FN(array)h(method,)g(126)166 5363 y(list)i(method,)e(35)1992 83 y FJ(insert_text\(\))f FN(\(in)i(module)f(readline\),)f(549)1992 183 y FJ(insertBefore\(\))g FN(\(Node)h(method\),)f(276)1992 282 y FJ(insertln\(\))g FN(\(windo)n(w)h(method\),)f(480)1992 382 y FJ(insnstr\(\))h FN(\(windo)n(w)f(method\),)h(480)1992 482 y FJ(insort\(\))g FN(\(in)h(module)f(bisect\),)g(124)1992 581 y FJ(insort_left\(\))f FN(\(in)i(module)f(bisect\),)g(124)1992 681 y FJ(insort_right\(\))f FN(\(in)i(module)e(bisect\),)i(124)1992 780 y FJ(inspect)f FN(\(standard)g(module\),)f FL(845)1992 880 y FJ(insstr\(\))h FN(\(windo)n(w)g(method\),)f(480)1992 980 y FJ(install\(\))2158 1079 y FN(in)i(module)f(gette)o(xt,)g(741)2158 1179 y(NullT)m (ranslations)f(method,)h(743)1992 1279 y FJ(install_opener\(\))e FN(\(in)j(module)f(urllib2\),)g(622)1992 1378 y FJ(instance\(\))f FN(\(in)i(module)f(ne)n(w\),)h(143)1992 1478 y FJ(instancemethod\(\))d FN(\(in)j(module)f(ne)n(w\),)g(143)1992 1577 y FJ(InstanceType)f FN(\(data)i(in)g(types\),)f(142)1992 1677 y FJ(instr\(\))g FN(\(windo)n(w)g(method\),)f(481)1992 1777 y FJ(instream)h FN(\(shle)o(x)g(attrib)n(ute\),)g(761)1992 1876 y FJ(int\(\))2158 1976 y FN(b)n(uilt-in)g(function,)f(25)2158 2076 y(in)i(module)f(,)h(9) 1992 2175 y FJ(int)g FN(\(UUID)g(attrib)n(ute\),)f(659)1992 2275 y FJ(Int2AP\(\))g FN(\(in)h(module)f(imaplib\),)f(643)1992 2374 y(inte)o(ger)2158 2474 y(di)n(vision,)h(25)2158 2574 y(di)n(vision,)g(long,)g(25)2158 2673 y(literals,)h(25)2158 2773 y(literals,)g(long,)f(25)2158 2873 y(object,)g(25)2158 2972 y(types,)g(operations)g(on,)g(26)1992 3072 y(Inte)o(grated)f(De)n (v)o(elopment)f(En)m(vironment,)g(733)1992 3171 y(Intel/D)m(VI)i (ADPCM,)h(693)1992 3271 y FJ(interact\(\))2158 3371 y FN(in)g(module)f(code,)g(855)2158 3470 y(Interacti)n(v)o(eConsole)e (method,)i(856)2158 3570 y(T)-6 b(elnet)20 b(method,)e(657)1992 3670 y FJ(InteractiveConsole)f FN(\(class)k(in)f(code\),)f(855)1992 3769 y FJ(InteractiveInterpreter)d FN(\(class)21 b(in)f(code\),)f(855) 1992 3869 y FJ(intern\(\))g FN(\(in)h(module)f(\),)h(17)1992 3968 y FJ(internal_attr)e FN(\(ZipInfo)g(attrib)n(ute\),)h(351)1992 4068 y FJ(Internaldate2tuple\(\))e FN(\(in)j(module)e(imaplib\),)h(643) 1992 4168 y FJ(internalSubset)f FN(\(DocumentT)-7 b(ype)17 b(attrib)n(ute\),)i(277)1992 4267 y(Internet,)f(599)1992 4367 y(Internet)g(Con\002g,)i(617)1992 4467 y(interpolation,)d(string)j (\(\045\),)g(32)1992 4566 y FJ(InterpolationDepthError)27 b FN(\(e)o(xception)i(in)i(Con\002g-)2324 4666 y(P)o(arser\),)19 b(311)1992 4765 y FJ(InterpolationError)35 b FN(\(e)o(xception)i(in)h (Con\002gP)o(arser\),)2324 4865 y(311)1992 4965 y FJ (InterpolationMissingOptionError)110 b FN(\(e)o(xcep-)2324 5064 y(tion)20 b(in)g(Con\002gP)o(arser\),)e(311)1992 5164 y FJ(InterpolationSyntaxError)39 b FN(\(e)o(xception)j(in)i(Con-) 2324 5264 y(\002gP)o(arser\),)19 b(311)1992 5363 y(interpreter)f (prompts,)h(832)p 0 5549 3901 4 v 0 5649 a FI(998)3561 b(Inde)n(x)p eop end %%Page: 999 1011 TeXDict begin 999 1010 bop 0 83 a FJ(interrupt\(\))19 b FN(\()h(method\),)e(388)0 183 y FJ(interrupt_main\(\))g FN(\(in)i(module)f(thread\),)f(537)0 282 y FJ(intro)i FN(\(Cmd)g(attrib)n(ute\),)f(759)0 382 y FJ(IntType)g FN(\(data)h(in)h(types\),)e(141)0 482 y FJ(InuseAttributeErr)f FN(\(e)o(xception)g(in)i(xml.dom\),)e(280)0 581 y FJ(inv\(\))i FN(\(in)g(module)f(operator\),)e(183)0 681 y FJ(InvalidAccessErr)h FN(\(e)o(xception)g(in)i(xml.dom\),)e(280)0 780 y FJ (InvalidCharacterErr)e FN(\(e)o(xception)g(in)j(xml.dom\),)e(280)0 880 y FJ(InvalidModificationErr)d FN(\(e)o(xception)g(in)k(xml.dom\),) 332 980 y(280)0 1079 y FJ(InvalidOperation)g FN(\(class)j(in)f (decimal\),)f(162)0 1179 y FJ(InvalidStateErr)f FN(\(e)o(xception)g(in) i(xml.dom\),)e(281)0 1279 y FJ(InvalidURL)h FN(\(e)o(xception)f(in)i (httplib\),)f(633)0 1378 y FJ(invert\(\))g FN(\(in)h(module)f (operator\),)f(183)0 1478 y FJ(ioctl\(\))h FN(\(in)h(module)f(fcntl\),) h(561)0 1577 y FJ(IOError)f FN(\(e)o(xception)f(in)j(e)o(xceptions\),)d (19)0 1677 y FJ(ior\(\))i FN(\(in)g(module)f(operator\),)e(186)0 1777 y FJ(IP_)150 1792 y(*)220 1777 y FN(\(data)j(in)g(sock)o(et\),)g (578)0 1876 y FJ(ipow\(\))g FN(\(in)g(module)e(operator\),)g(186)0 1976 y FJ(IPPORT_)350 1991 y(*)419 1976 y FN(\(data)i(in)g(sock)o (et\),)g(578)0 2076 y FJ(IPPROTO_)400 2091 y(*)469 2076 y FN(\(data)g(in)g(sock)o(et\),)g(578)0 2175 y FJ(IPV6_)250 2190 y(*)320 2175 y FN(\(data)f(in)i(sock)o(et\),)e(578)0 2275 y FJ(irepeat\(\))g FN(\(in)h(module)f(operator\),)f(186)0 2374 y(IRIS)j(F)o(ont)e(Manager)m(,)g(924)0 2474 y(IRIX)166 2574 y(threads,)g(538)0 2673 y FJ(irshift\(\))g FN(\(in)h(module)f (operator\),)f(186)0 2773 y FJ(is)166 2873 y FN(operator)m(,)g(24)0 2972 y FJ(is)49 b(not)166 3072 y FN(operator)m(,)18 b(24)0 3171 y FJ(is_\(\))i FN(\(in)g(module)f(operator\),)e(183)0 3271 y FJ(is_blocked\(\))i FN(\(Def)o(aultCookiePolic)o(y)e(method\),)h (677)0 3371 y FJ(is_builtin\(\))h FN(\(in)h(module)e(imp\),)i(867)0 3470 y FJ(IS_CHARACTER_JUNK\(\))d FN(\(in)j(module)f(dif)n(\003ib\),)g (68)0 3570 y FJ(is_data\(\))g FN(\(MultiFile)h(method\),)e(246)0 3670 y FJ(is_empty\(\))h FN(\(\002fo)h(method\),)e(597)0 3769 y FJ(is_expired\(\))h FN(\(Cookie)g(method\),)f(679)0 3869 y FJ(is_frozen\(\))h FN(\(in)h(module)f(imp\),)g(867)0 3968 y FJ(is_hop_by_hop\(\))f FN(\(in)i(module)f(wsgiref.util\),)f(611) 0 4068 y FJ(is_jython)h FN(\(data)h(in)g(test.test)p 997 4068 25 4 v 30 w(support\),)f(804)0 4168 y FJ(IS_LINE_JUNK\(\))f FN(\(in)i(module)f(dif)n(\003ib\),)g(68)0 4267 y FJ(is_linetouched\(\)) f FN(\(windo)n(w)h(method\),)f(481)0 4367 y FJ(is_multipart\(\))g FN(\(Message)i(method\),)e(190)0 4467 y FJ(is_not\(\))h FN(\(in)h(module)f(operator\),)f(183)0 4566 y FJ(is_not_allowed\(\))41 b FN(\(Def)o(aultCookiePolic)o(y)f(method\),)332 4666 y(677)0 4765 y FJ(is_package\(\))19 b FN(\(zipimporter)e(method\),)i (869)0 4865 y FJ(is_resource_enabled\(\))28 b FN(\(in)k(module)e (test.test)p 1740 4865 V 31 w(sup-)332 4965 y(port\),)19 b(804)0 5064 y FJ(is_tarfile\(\))g FN(\(in)h(module)e(tar\002le\),)i (352)0 5164 y FJ(is_unverifiable\(\))e FN(\(Request)h(method\),)g(625)0 5264 y FJ(is_wintouched\(\))f FN(\(windo)n(w)h(method\),)f(481)0 5363 y FJ(is_zipfile\(\))h FN(\(in)h(module)e(zip\002le\),)i(348)1992 83 y FJ(isabs\(\))f FN(\(in)h(module)f(os.path\),)f(326)1992 183 y FJ(isAlive\(\))h FN(\(Thread)f(method\),)g(545)1992 282 y FJ(isalnum\(\))2158 382 y FN(in)i(module)f(curses.ascii,)h(489) 2158 482 y(string)f(method,)g(29)1992 581 y FJ(isalpha\(\))2158 681 y FN(in)h(module)f(curses.ascii,)h(489)2158 780 y(string)f(method,) g(29)1992 880 y FJ(isascii\(\))g FN(\(in)h(module)e(curses.ascii\),)i (489)1992 980 y FJ(isatty\(\))2158 1079 y FN(Chunk)f(method,)f(704)2158 1179 y(\002le)i(method,)f(39)2158 1279 y(in)h(module)f(os,)h(400)1992 1378 y FJ(isblank\(\))f FN(\(in)h(module)e(curses.ascii\),)i(489)1992 1478 y FJ(isblk\(\))f FN(\(T)-7 b(arInfo)18 b(method\),)g(356)1992 1577 y FJ(isbuiltin\(\))g FN(\(in)i(module)f(inspect\),)g(847)1992 1677 y FJ(isCallable\(\))f FN(\(in)i(module)f(operator\),)f(186)1992 1777 y FJ(ischr\(\))h FN(\(T)-7 b(arInfo)18 b(method\),)g(356)1992 1876 y FJ(isclass\(\))h FN(\(in)h(module)e(inspect\),)i(847)1992 1976 y FJ(iscntrl\(\))f FN(\(in)h(module)e(curses.ascii\),)i(490)1992 2076 y FJ(iscode\(\))f FN(\(in)h(module)f(inspect\),)g(847)1992 2175 y FJ(iscomment\(\))f FN(\(AddressList)i(method\),)e(249)1992 2275 y FJ(isctrl\(\))h FN(\(in)h(module)f(curses.ascii\),)g(490)1992 2374 y FJ(isDaemon\(\))f FN(\(Thread)h(method\),)f(545)1992 2474 y FJ(isdatadescriptor\(\))f FN(\(in)j(module)f(inspect\),)g(847) 1992 2574 y FJ(isdev\(\))g FN(\(T)-7 b(arInfo)18 b(method\),)g(356)1992 2673 y FJ(isdigit\(\))2158 2773 y FN(in)i(module)f(curses.ascii,)h(490) 2158 2873 y(string)f(method,)g(30)1992 2972 y FJ(isdir\(\))2158 3072 y FN(in)h(module)f(os.path,)g(326)2158 3171 y(T)-7 b(arInfo)18 b(method,)h(356)1992 3271 y FJ(iselement\(\))f FN(\(in)i(module)f(xml.etree.ElementT)m(ree\),)d(299)1992 3371 y FJ(isenabled\(\))i FN(\(in)i(module)f(gc\),)h(843)1992 3470 y FJ(isEnabledFor\(\))e FN(\()i(method\),)e(454)1992 3570 y FJ(isendwin\(\))g FN(\(in)i(module)f(curses\),)h(475)1992 3670 y FJ(ISEOF\(\))f FN(\(in)h(module)f(tok)o(en\),)g(883)1992 3769 y FJ(isexpr\(\))2158 3869 y FN(AST)h(method,)f(876)2158 3968 y(in)h(module)f(parser)m(,)g(875)1992 4068 y FJ(isfifo\(\))g FN(\(T)-7 b(arInfo)18 b(method\),)g(356)1992 4168 y FJ(isfile\(\))2158 4267 y FN(in)i(module)f(os.path,)g(326)2158 4367 y(T)-7 b(arInfo)18 b(method,)h(356)1992 4467 y FJ(isfirstline\(\))f FN(\(in)i(module)f(\002leinput\),)g(329)1992 4566 y FJ(isframe\(\))g FN(\(in)h(module)e(inspect\),)i(847)1992 4666 y FJ(isfunction\(\))e FN(\(in)i(module)f(inspect\),)g(847)1992 4765 y FJ (isgetsetdescriptor\(\))e FN(\(in)j(module)e(inspect\),)i(848)1992 4865 y FJ(isgraph\(\))f FN(\(in)h(module)e(curses.ascii\),)i(490)1992 4965 y FJ(isheader\(\))e FN(\(AddressList)i(method\),)e(249)1992 5064 y FJ(isinstance\(\))g FN(\(in)i(module)f(\),)h(9)1992 5164 y FJ(iskeyword\(\))e FN(\(in)i(module)f(k)o(e)o(yw)o(ord\),)f(883) 1992 5264 y FJ(islast\(\))h FN(\(AddressList)g(method\),)g(249)1992 5363 y FJ(isleap\(\))g FN(\(in)h(module)f(calendar\),)f(115)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3561 b(999)p eop end %%Page: 1000 1012 TeXDict begin 1000 1011 bop 0 83 a FJ(islice\(\))19 b FN(\(in)h(module)f(itertools\),)g(176)0 183 y FJ(islink\(\))g FN(\(in)h(module)f(os.path\),)g(326)0 282 y FJ(islnk\(\))g FN(\(T)-7 b(arInfo)19 b(method\),)f(356)0 382 y FJ(islower\(\))166 482 y FN(in)i(module)f(curses.ascii,)h(490)166 581 y(string)g(method,)e (30)0 681 y FJ(isMappingType\(\))g FN(\(in)i(module)f(operator\),)f (187)0 780 y FJ(ismemberdescriptor\(\))f FN(\(in)j(module)f(inspect\),) g(848)0 880 y FJ(ismeta\(\))g FN(\(in)h(module)f(curses.ascii\),)h(490) 0 980 y FJ(ismethod\(\))f FN(\(in)h(module)f(inspect\),)g(847)0 1079 y FJ(ismethoddescriptor\(\))e FN(\(in)j(module)f(inspect\),)g(847) 0 1179 y FJ(ismodule\(\))g FN(\(in)h(module)f(inspect\),)g(847)0 1279 y FJ(ismount\(\))g FN(\(in)h(module)f(os.path\),)g(327)0 1378 y FJ(ISNONTERMINAL\(\))f FN(\(in)i(module)f(tok)o(en\),)g(883)0 1478 y FJ(isNumberType\(\))f FN(\(in)i(module)f(operator\),)f(187)0 1577 y FJ(isocalendar\(\))166 1677 y FN(date)i(method,)f(100)166 1777 y(datetime)h(method,)e(105)0 1876 y FJ(isoformat\(\))166 1976 y FN(date)i(method,)f(100)166 2076 y(datetime)h(method,)e(105)166 2175 y(time)i(method,)f(107)0 2275 y FJ(isolation_level)f FN(\()i(attrib)n(ute\),)g(386)0 2374 y FJ(isoweekday\(\))166 2474 y FN(date)g(method,)f(100)166 2574 y(datetime)h(method,)e(105)0 2673 y FJ(isprint\(\))h FN(\(in)h(module)f(curses.ascii\),)g(490)0 2773 y FJ(ispunct\(\))g FN(\(in)h(module)f(curses.ascii\),)g(490)0 2873 y FJ(isqueued\(\))g FN(\(in)h(module)f(\003\),)h(920)0 2972 y FJ(isreadable\(\))166 3072 y FN(in)g(module)f(pprint,)g(146)166 3171 y(PrettyPrinter)g(method,)g(146)0 3271 y FJ(isrecursive\(\))166 3371 y FN(in)h(module)f(pprint,)g(146)166 3470 y(PrettyPrinter)g (method,)g(146)0 3570 y FJ(isreg\(\))g FN(\(T)-7 b(arInfo)19 b(method\),)f(356)0 3670 y FJ(isReservedKey\(\))g FN(\(Morsel)i (method\),)e(682)0 3769 y FJ(isroutine\(\))h FN(\(in)h(module)f (inspect\),)g(847)0 3869 y FJ(isSameNode\(\))g FN(\(Node)g(method\),)f (276)0 3968 y FJ(isSequenceType\(\))g FN(\(in)i(module)f(operator\),)e (187)0 4068 y FJ(isSet\(\))i FN(\(Ev)o(ent)g(method\),)g(544)0 4168 y FJ(isspace\(\))166 4267 y FN(in)h(module)f(curses.ascii,)h(490) 166 4367 y(string)g(method,)e(30)0 4467 y FJ(isstdin\(\))h FN(\(in)h(module)f(\002leinput\),)g(329)0 4566 y FJ(issubclass\(\))g FN(\(in)h(module)e(\),)i(9)0 4666 y FJ(issuer\(\))f FN(\()i(method\),)d (584)0 4765 y FJ(issuite\(\))166 4865 y FN(AST)j(method,)d(876)166 4965 y(in)i(module)f(parser)m(,)g(876)0 5064 y FJ(issym\(\))g FN(\(T)-7 b(arInfo)19 b(method\),)f(356)0 5164 y FJ(ISTERMINAL\(\))h FN(\(in)h(module)e(tok)o(en\),)h(883)0 5264 y FJ(istitle\(\))g FN(\(string)h(method\),)e(30)0 5363 y FJ(istraceback\(\))g FN(\(in)i(module)f(inspect\),)g(847)1992 83 y FJ(isub\(\))g FN(\(in)h(module)f(operator\),)f(186)1992 183 y FJ(isupper\(\))2158 282 y FN(in)i(module)f(curses.ascii,)h(490)2158 382 y(string)f(method,) g(30)1992 482 y FJ(isxdigit\(\))f FN(\(in)i(module)f(curses.ascii\),)h (490)1992 581 y FJ(item\(\))2158 681 y FN(NamedNodeMap)d(method,)i(279) 2158 780 y(NodeList)g(method,)g(276)1992 880 y FJ(itemgetter\(\))f FN(\(in)i(module)f(operator\),)f(187)1992 980 y FJ(items\(\))2158 1079 y FN(dictionary)g(method,)h(37)2158 1179 y(Mailbox)g(method,)f (220)2158 1279 y(Message)i(method,)e(192)2158 1378 y(SafeCon\002gP)o (arser)g(method,)h(312,)g(313)1992 1478 y FJ(itemsize)g FN(\(array)g(attrib)n(ute\),)g(126)1992 1577 y FJ(iter\(\))g FN(\(in)h(module)f(\),)h(9)1992 1677 y FJ(IterableUserDict)d FN(\(class)k(in)f(UserDict\),)g(139)1992 1777 y(iterator)f(protocol,)f (26)1992 1876 y FJ(iterdecode\(\))g FN(\(in)i(module)f(codecs\),)g(80) 1992 1976 y FJ(iterencode\(\))f FN(\(in)i(module)f(codecs\),)g(80)1992 2076 y FJ(iteritems\(\))2158 2175 y FN(dictionary)f(method,)h(37)2158 2275 y(Mailbox)g(method,)f(220)1992 2374 y FJ(iterkeyrefs\(\))g FN(\(W)-7 b(eakK)n(e)o(yDictionary)17 b(method\),)h(136)1992 2474 y FJ(iterkeys\(\))2158 2574 y FN(dictionary)g(method,)h(37)2158 2673 y(Mailbox)g(method,)f(220)1992 2773 y FJ(itermonthdates\(\))f FN(\(Calendar)i(method\),)g(114)1992 2873 y FJ(itermonthdays\(\))e FN(\(Calendar)j(method\),)e(114)1992 2972 y FJ(itermonthdays2\(\))f FN(\(Calendar)i(method\),)g(114)1992 3072 y FJ(iterparse\(\))f FN(\(in)i(module)f(xml.etree.ElementT)m(ree\),)d(299)1992 3171 y FJ(itertools)j FN(\(standard)f(module\),)g FL(172)1992 3271 y FJ(itervaluerefs\(\))49 b FN(\(W)-7 b(eakV)e(alueDictionary)50 b(method\),)2324 3371 y(136)1992 3470 y FJ(itervalues\(\))2158 3570 y FN(dictionary)18 b(method,)h(37)2158 3670 y(Mailbox)g(method,)f (220)1992 3769 y FJ(iterweekdays\(\))g FN(\(Calendar)h(method\),)f(114) 1992 3869 y FJ(itruediv\(\))g FN(\(in)i(module)f(operator\),)f(186)1992 3968 y FJ(ixor\(\))h FN(\(in)h(module)f(operator\),)f(186)1992 4068 y FJ(izip\(\))h FN(\(in)h(module)f(itertools\),)g(176)1992 4261 y FE(J)1992 4384 y FN(Jansen,)g(Jack,)h(256)1992 4483 y FJ(java_ver\(\))e FN(\(in)i(module)f(platform\),)f(493)1992 4583 y(JFIF)-7 b(,)21 b(928)1992 4683 y FJ(join\(\))2158 4782 y FN(in)f(module)f(os.path,)g(327)2158 4882 y(in)h(module)f (string,)g(51)2158 4982 y(Queue)g(method,)g(134)2158 5081 y(string)g(method,)g(30)2158 5181 y(Thread)f(method,)h(545)1992 5280 y FJ(joinfields\(\))f FN(\(in)i(module)f(string\),)g(51)1992 5380 y FJ(jpeg)h FN(\(b)n(uilt-in)f(module\),)f FL(928)p 0 5549 3901 4 v 0 5649 a FI(1000)3515 b(Inde)n(x)p eop end %%Page: 1001 1013 TeXDict begin 1001 1012 bop 0 83 a FJ(js_output\(\))166 183 y FN(BaseCookie)20 b(method,)f(681)166 282 y(Morsel)h(method,)f (682)0 382 y FJ(jumpahead\(\))g FN(\(in)h(module)f(random\),)e(170)0 574 y FE(K)0 698 y FJ(kbhit\(\))i FN(\(in)h(module)f(msvcrt\),)g(940)0 797 y(KDEDIR,)h(601)0 897 y FJ(key)g FN(\(Morsel)g(attrib)n(ute\),)f (681)0 996 y FJ(KeyboardInterrupt)f FN(\(e)o(xception)g(in)i(e)o (xceptions\),)e(19)0 1096 y FJ(KeyError)h FN(\(e)o(xception)f(in)j(e)o (xceptions\),)d(19)0 1196 y FJ(keyname\(\))h FN(\(in)h(module)f (curses\),)h(475)0 1295 y FJ(keypad\(\))f FN(\(windo)n(w)g(method\),)f (481)0 1395 y FJ(keyrefs\(\))h FN(\(W)-7 b(eakK)n(e)o(yDictionary)18 b(method\),)g(136)0 1495 y FJ(keys\(\))187 1594 y FN(method,)g(381)166 1694 y(dictionary)g(method,)h(37)166 1793 y(Mailbox)g(method,)g(220)166 1893 y(Message)h(method,)f(192)0 1993 y FJ(keyword)g FN(\(standard)g(module\),)f FL(883)0 2092 y FJ(keywords)h FN(\(dict)h(attrib)n(ute\),)f(182)0 2192 y FJ(kill\(\))h FN(\(in)g(module)e(os\),)i(410)0 2292 y FJ(killchar\(\))f FN(\(in)h(module)f(curses\),)g(475)0 2391 y FJ(killpg\(\))g FN(\(in)h(module)f(os\),)h(410)0 2491 y FJ(knee)g FN(\(module\),)e(868) 0 2590 y FJ(knownfiles)h FN(\(data)h(in)g(mimetypes\),)e(242)0 2690 y(K)o(uchling,)g(Andre)n(w)-5 b(,)19 b(319)0 2790 y FJ(kwlist)h FN(\(data)f(in)i(k)o(e)o(yw)o(ord\),)c(883)0 2985 y FE(L)0 3109 y FJ(L)k FN(\(data)e(in)i(re\),)e(57)0 3208 y FJ(LabelEntry)g FN(\(class)i(in)f(T)m(ix\),)g(726)0 3308 y FJ(LabelFrame)f FN(\(class)i(in)f(T)m(ix\),)g(726)0 3407 y FJ(LambdaType)f FN(\(data)h(in)g(types\),)f(141)0 3507 y(LANG,)h(739,)f(741,)g(749,)g(750)0 3607 y(LANGU)m(A)m(GE,)g (739,)g(741)0 3706 y(language)166 3806 y(C,)i(25)0 3906 y(lar)o(ge)e(\002les,)i(554)0 4005 y FJ(LargeZipFile)e FN(\(e)o(xception)e(in)k(zip\002le\),)f(348)0 4105 y FJ(last\(\))187 4204 y FN(method,)e(381)166 4304 y(dbhash)h(method,)g (379)166 4404 y(NNTP)i(method,)d(650)0 4503 y FJ(last)i FN(\(MultiFile)g(attrib)n(ute\),)f(246)0 4603 y FJ(last_traceback)f FN(\(data)i(in)g(sys\),)g(831)0 4703 y FJ(last_type)f FN(\(data)h(in)g(sys\),)g(831)0 4802 y FJ(last_value)f FN(\(data)h(in)g(sys\),)g(831)0 4902 y FJ(lastChild)f FN(\(Node)g(attrib)n(ute\),)h(275)0 5001 y FJ(lastcmd)f FN(\(Cmd)h(attrib)n(ute\),)g(759)0 5101 y FJ(lastgroup)f FN(\(MatchObject)g(attrib)n(ute\),)g(61)0 5201 y FJ(lastindex)g FN(\(MatchObject)g(attrib)n(ute\),)g(61)0 5300 y FJ(lastpart\(\))g FN(\(MimeWriter)g(method\),)g(244)0 5400 y(LC)p 111 5400 25 4 v 30 w(ALL,)h(739,)f(741)1992 83 y FJ(LC_ALL)g FN(\(data)h(in)g (locale\),)g(752)1992 183 y FJ(LC_COLLATE)e FN(\(data)i(in)g(locale\),) g(752)1992 282 y FJ(LC_CTYPE)f FN(\(data)g(in)i(locale\),)e(752)1992 382 y(LC)p 2103 382 V 30 w(MESSA)m(GES,)g(739,)g(741)1992 482 y FJ(LC_MESSAGES)f FN(\(data)i(in)g(locale\),)g(752)1992 581 y FJ(LC_MONETARY)e FN(\(data)i(in)g(locale\),)g(752)1992 681 y FJ(LC_NUMERIC)e FN(\(data)i(in)g(locale\),)g(752)1992 780 y FJ(LC_TIME)f FN(\(data)h(in)g(locale\),)f(752)1992 880 y FJ(lchown\(\))g FN(\(in)h(module)f(os\),)h(403)1992 980 y FJ(ldexp\(\))f FN(\(in)h(module)f(math\),)g(150)1992 1079 y FJ(ldgettext\(\))f FN(\(in)i(module)f(gette)o(xt\),)g(740)1992 1179 y FJ(ldngettext\(\))f FN(\(in)i(module)f(gette)o(xt\),)g(740)1992 1279 y FJ(le\(\))h FN(\(in)g(module)e(operator\),)g(183)1992 1378 y FJ(leapdays\(\))g FN(\(in)i(module)f(calendar\),)g(115)1992 1478 y FJ(leaveok\(\))g FN(\(windo)n(w)f(method\),)h(481)1992 1577 y FJ(left\(\))g FN(\(in)h(module)f(turtle\),)g(731)1992 1677 y FJ(left_list)g FN(\(dircmp)f(attrib)n(ute\),)h(334)1992 1777 y FJ(left_only)g FN(\(dircmp)f(attrib)n(ute\),)h(334)1992 1876 y FJ(len\(\))2158 1976 y FN(b)n(uilt-in)g(function,)f(28,)i(37) 2158 2076 y(in)g(module)f(,)h(9)1992 2175 y FJ(length)2158 2275 y FN(NamedNodeMap)d(attrib)n(ute,)j(279)2158 2374 y(NodeList)f(attrib)n(ute,)h(276)1992 2474 y FJ(letters)f FN(\(data)h(in)g(string\),)f(48)1992 2574 y FJ(level)g FN(\(MultiFile)h(attrib)n(ute\),)g(246)1992 2673 y FJ(lexists\(\))f FN(\(in)h(module)e(os.path\),)h(326)1992 2773 y FJ(lgettext\(\))2158 2873 y FN(GNUT)m(ranslations)g(method,)f(743)2158 2972 y(in)i(module)f(gette)o(xt,)g(740)2158 3072 y(NullT)m(ranslations)f (method,)h(742)1992 3171 y FJ(libc_ver\(\))f FN(\(in)i(module)f (platform\),)f(494)1992 3271 y FJ(library)h FN(\(data)h(in)g(dbm\),)f (377)1992 3371 y FJ(LibraryLoader)f FN(\(class)j(in)f(ctypes\),)f(524) 1992 3470 y(light-weight)f(processes,)i(536)1992 3570 y FJ(lin2adpcm\(\))e FN(\(in)i(module)f(audioop\),)f(694)1992 3670 y FJ(lin2alaw\(\))g FN(\(in)i(module)f(audioop\),)f(694)1992 3769 y FJ(lin2lin\(\))h FN(\(in)h(module)e(audioop\),)g(694)1992 3869 y FJ(lin2ulaw\(\))g FN(\(in)i(module)f(audioop\),)f(694)1992 3968 y FJ(line\(\))h FN(\(Dialog)h(method\),)e(938)1992 4068 y(line-b)n(uf)n(fered)f(I/O,)j(10)1992 4168 y FJ(line_num)f FN(\(csv)h(reader)f(attrib)n(ute\),)g(307)1992 4267 y FJ(linecache)g FN(\(standard)f(module\),)g FL(338)1992 4367 y FJ(lineno\(\))h FN(\(in)h(module)f(\002leinput\),)g(329)1992 4467 y FJ(lineno)2158 4566 y FN(class)i(descriptor)d(attrib)n(ute,)i (886)2158 4666 y(DocT)-6 b(est)20 b(attrib)n(ute,)f(781)2158 4765 y(Example)f(attrib)n(ute,)i(782)2158 4865 y(ExpatError)d(attrib)n (ute,)j(269)2158 4965 y(function)e(descriptor)h(attrib)n(ute,)g(887) 2158 5064 y(shle)o(x)g(attrib)n(ute,)h(761)1992 5164 y(LINES,)f(478)1992 5264 y FJ(linesep)g FN(\(data)h(in)g(os\),)g(415) 1992 5363 y FJ(lineterminator)e FN(\(Dialect)i(attrib)n(ute\),)f(306)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1001)p eop end %%Page: 1002 1014 TeXDict begin 1002 1013 bop 0 83 a FJ(link\(\))20 b FN(\(in)g(module)e (os\),)i(403)0 183 y FJ(linkname)f FN(\(T)-7 b(arInfo)19 b(attrib)n(ute\),)g(355)0 282 y(list)166 382 y(object,)g(27,)h(34)166 482 y(type,)g(operations)e(on,)i(35)0 581 y FJ(list\(\))166 681 y FN(IMAP4)p 421 681 25 4 v 29 w(stream)g(method,)f(644)166 780 y(in)h(module)f(,)i(9)166 880 y(NNTP)g(method,)d(649)166 980 y(POP3)p 365 980 V 30 w(SSL)j(method,)d(641)166 1079 y(T)-7 b(arFile)21 b(method,)d(354)0 1179 y FJ(list_dialects\(\))g FN(\(in)i(module)f(csv\),)h(304)0 1279 y FJ(list_folders\(\))166 1378 y FN(Maildir)g(method,)e(222)166 1478 y(MH)j(method,)d(224)0 1577 y FJ(listallfolders\(\))g FN(\(MH)i(method\),)e(238)0 1677 y FJ(listallsubfolders\(\))f FN(\(MH)j(method\),)f(238)0 1777 y FJ(listdir\(\))166 1876 y FN(in)h(module)f(dircache,)g(340)166 1976 y(in)h(module)f(os,)i(403)0 2076 y FJ(listen\(\))166 2175 y FN(dispatcher)e(method,)g(594)166 2275 y(in)h(module)f(logging,) f(469)166 2374 y(sock)o(et)i(method,)f(582)0 2474 y FJ(listfolders\(\)) f FN(\(MH)i(method\),)f(238)0 2574 y FJ(listmessages\(\))f FN(\(F)o(older)h(method\),)f(238)0 2673 y FJ(ListNoteBook)h FN(\(class)h(in)h(T)m(ix\),)e(728)0 2773 y FJ(listsubfolders\(\))f FN(\(MH)i(method\),)e(238)0 2873 y FJ(ListType)h FN(\(data)h(in)g (types\),)g(141)0 2972 y(literals)166 3072 y(comple)o(x)e(number)m(,)g (25)166 3171 y(\003oating)i(point,)f(25)166 3271 y(he)o(xadecimal,)f (25)166 3371 y(inte)o(ger)m(,)h(25)166 3470 y(long)g(inte)o(ger)m(,)g (25)166 3570 y(numeric,)g(25)166 3670 y(octal,)h(25)0 3769 y FJ(LittleEndianStructure)d FN(\(class)k(in)f(ctypes\),)f(533)0 3869 y FJ(ljust\(\))166 3968 y FN(in)h(module)f(string,)h(52)166 4068 y(string)g(method,)e(30)0 4168 y FJ(LK_LOCK)h FN(\(data)h(in)h (msvcrt\),)e(940)0 4267 y FJ(LK_NBLCK)g FN(\(data)h(in)g(msvcrt\),)f (940)0 4367 y FJ(LK_NBRLCK)g FN(\(data)h(in)g(msvcrt\),)f(940)0 4467 y FJ(LK_RLCK)g FN(\(data)h(in)h(msvcrt\),)e(940)0 4566 y FJ(LK_UNLCK)g FN(\(data)h(in)g(msvcrt\),)f(940)0 4666 y(LN)m(AME,)h(472)0 4765 y FJ(lngettext\(\))166 4865 y FN(GNUT)m(ranslations)f(method,)g(744)166 4965 y(in)h(module)f(gette)o(xt,)g(740)166 5064 y(NullT)m(ranslations)g (method,)g(742)0 5164 y FJ(load\(\))166 5264 y FN(BaseCookie)h(method,) f(681)166 5363 y(FileCookieJar)h(method,)e(674)2158 83 y(in)i(module)f(hotshot.stats,)g(820)2158 183 y(in)h(module)f(marshal,) g(374)2158 282 y(in)h(module)f(pickle,)g(361)2158 382 y(Unpickler)f(method,)h(363)1992 482 y FJ(load_compiled\(\))e FN(\(in)j(module)f(imp\),)h(867)1992 581 y FJ(load_dynamic\(\))e FN(\(in)i(module)e(imp\),)i(867)1992 681 y FJ(load_module\(\))2158 780 y FN(in)g(module)f(imp,)g(866)2158 880 y(zipimporter)f(method,)g (869)1992 980 y FJ(load_source\(\))g FN(\(in)i(module)f(imp\),)g(867) 1992 1079 y FJ(LoadError)g FN(\(e)o(xception)f(in)i(cookielib\),)e(672) 1992 1179 y FJ(LoadLibrary\(\))g FN(\(LibraryLoader)e(method\),)j(524) 1992 1279 y FJ(loads\(\))2158 1378 y FN(in)h(module)f(marshal,)g(375) 2158 1478 y(in)h(module)f(pickle,)g(361)2158 1577 y(in)h(module)f (xmlrpclib,)f(687)1992 1677 y FJ(loadTestsFromModule\(\))78 b FN(\(T)-6 b(estLoader)81 b(method\),)2324 1777 y(800)1992 1876 y FJ(loadTestsFromName\(\))17 b FN(\(T)-6 b(estLoader)18 b(method\),)h(800)1992 1976 y FJ(loadTestsFromNames\(\))e FN(\(T)-6 b(estLoader)18 b(method\),)g(800)1992 2076 y FJ(loadTestsFromTestCase\(\))28 b FN(\(T)-6 b(estLoader)31 b(method\),)2324 2175 y(800)1992 2275 y FJ(local)19 b FN(\(class)i(in)f(threading\),)e(539)1992 2374 y FJ(localcontext\(\))g FN(\(in)i(module)e(decimal\),)h(158)1992 2474 y FJ(LOCALE)g FN(\(data)h(in)g(re\),)g(57)1992 2574 y FJ(locale)f FN(\(standard)g (module\),)f FL(749)1992 2673 y FJ(localeconv\(\))g FN(\(in)i(module)f (locale\),)g(749)1992 2773 y FJ(LocaleHTMLCalendar)e FN(\(class)k(in)f(calendar\),)e(115)1992 2873 y FJ(LocaleTextCalendar)f FN(\(class)k(in)f(calendar\),)e(115)1992 2972 y FJ(localName)2158 3072 y FN(Attr)i(attrib)n(ute,)g(279)2158 3171 y(Node)f(attrib)n(ute,)h (275)1992 3271 y FJ(locals\(\))f FN(\(in)h(module)f(\),)h(9)1992 3371 y FJ(localtime\(\))e FN(\(in)i(module)f(time\),)h(417)1992 3470 y FJ(Locator)f FN(\(class)i(in)f(xml.sax.xmlreader\),)c(295)1992 3570 y FJ(Lock\(\))j FN(\(in)h(module)f(threading\),)f(539)1992 3670 y FJ(lock\(\))2158 3769 y FN(Babyl)i(method,)e(225)2158 3869 y(in)i(module)f(posix\002le,)g(564)2158 3968 y(Mailbox)g(method,)f (221)2158 4068 y(Maildir)h(method,)g(222)2158 4168 y(mbox)f(method,)h (223)2158 4267 y(MH)h(method,)f(224)2158 4367 y(MMDF)h(method,)f(226) 2158 4467 y(mute)o(x)g(method,)f(133)1992 4566 y FJ(lock_held\(\))g FN(\(in)i(module)f(imp\),)g(866)1992 4666 y FJ(locked\(\))g FN(\(lock)g(method\),)f(537)1992 4765 y FJ(lockf\(\))2158 4865 y FN(in)i(module)f(fcntl,)g(561)2158 4965 y(in)h(module)f(fcntl,)g (563)1992 5064 y FJ(locking\(\))g FN(\(in)h(module)e(msvcrt\),)i(939) 1992 5164 y FJ(LockType)f FN(\(data)g(in)i(thread\),)d(537)1992 5264 y FJ(log\(\))2178 5363 y FN(method,)h(455)p 0 5549 3901 4 v 0 5649 a FI(1002)3515 b(Inde)n(x)p eop end %%Page: 1003 1015 TeXDict begin 1003 1014 bop 166 83 a FN(in)20 b(module)f(cmath,)h(152) 166 183 y(in)g(module)f(logging,)f(452)166 282 y(in)i(module)f(math,)h (150)0 382 y FJ(log10\(\))166 482 y FN(in)g(module)f(cmath,)h(152)166 581 y(in)g(module)f(math,)h(150)0 681 y FJ(log_date_time_string\(\))117 b FN(\(BaseHTTPRequest-)332 780 y(Handler)19 b(method\),)f(670)0 880 y FJ(log_error\(\))64 b FN(\(BaseHTTPRequestHandler)f(method\),)332 980 y(669)0 1079 y FJ(log_exception\(\))18 b FN(\(BaseHandler)h (method\),)f(616)0 1179 y FJ(log_message\(\))c FN (\(BaseHTTPRequestHandler)f(method\),)332 1279 y(669)0 1378 y FJ(log_request\(\))h FN(\(BaseHTTPRequestHandler)f(method\),)332 1478 y(669)0 1577 y(logging)166 1677 y(Errors,)19 b(450)0 1777 y FJ(logging)g FN(\(standard)g(module\),)f FL(450)0 1876 y FJ(login\(\))166 1976 y FN(FTP)j(method,)d(638)166 2076 y(IMAP4)p 421 2076 25 4 v 29 w(stream)i(method,)f(644)166 2175 y(SMTP)i(method,)d(653)0 2275 y FJ(login_cram_md5\(\))g FN(\(IMAP4)p 1101 2275 V 28 w(stream)i(method\),)f(644)0 2374 y(LOGN)m(AME,)h(397,)f(472)0 2474 y FJ(lognormvariate\(\))f FN(\(in)i(module)f(random\),)e(171)0 2574 y FJ(logout\(\))i FN(\(IMAP4)p 702 2574 V 29 w(stream)h(method\),)e(644)0 2673 y FJ(LogRecord)h FN(\(class)i(in)f(logging\),)e(468)0 2773 y(long)166 2873 y(inte)o(ger)h(di)n(vision,)g(25)166 2972 y(inte)o(ger)g(literals,)i(25)0 3072 y FJ(long\(\))166 3171 y FN(b)n(uilt-in)f(function,)e(25,)h(50)166 3271 y(in)h(module)f(,)i(9)0 3371 y(long)e(inte)o(ger)166 3470 y(object,)g(25)0 3570 y FJ(longimagedata\(\))f FN(\(in)i(module)f (r)o(gbimg\),)e(706)0 3670 y FJ(longname\(\))i FN(\(in)h(module)f (curses\),)g(475)0 3769 y FJ(longstoimage\(\))f FN(\(in)i(module)f(r)o (gbimg\),)e(706)0 3869 y FJ(LongType)i FN(\(data)h(in)g(types\),)g(141) 0 3968 y FJ(lookup\(\))166 4068 y FN(in)g(module)f(codecs,)h(78)166 4168 y(in)g(module)f(unicodedata,)f(90)0 4267 y FJ(lookup_error\(\))g FN(\(in)i(module)f(codecs\),)g(79)0 4367 y FJ(LookupError)g FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(18)0 4467 y FJ(loop\(\))i FN(\(in)g(module)e(asyncore\),)h(592)0 4566 y FJ(lower\(\))166 4666 y FN(in)h(module)f(string,)h(51)166 4765 y(string)g(method,)e(30)0 4865 y FJ(lowercase)h FN(\(data)h(in)g(string\),)f(48)0 4965 y FJ(lseek\(\))g FN(\(in)h(module)f(os\),)h(400)0 5064 y FJ(lshift\(\))f FN(\(in)h(module)f(operator\),)f(184)0 5164 y FJ(lstat\(\))h FN(\(in)h(module)f(os\),)h(403)0 5264 y FJ(lstrip\(\))166 5363 y FN(in)g(module)f(string,)h(51)2158 83 y(string)f(method,)g(30) 1992 183 y FJ(lsub\(\))g FN(\(IMAP4)p 2594 183 V 29 w(stream)h (method\),)e(644)1992 282 y FJ(lt\(\))i FN(\(in)g(module)e(operator\),) g(182)1992 382 y(Lundh,)g(Fredrik,)h(928)1992 482 y FJ(LWPCookieJar)f FN(\(class)j(in)f(cookielib\),)e(675)1992 674 y FE(M)1992 797 y FJ(M)i FN(\(data)g(in)g(re\),)g(57)1992 897 y FJ(mac_ver\(\))f FN(\(in)h(module)e(platform\),)g(494)1992 996 y FJ(machine\(\))h FN(\(in)h(module)e(platform\),)g(492)1992 1096 y FJ(macros)h FN(\(netrc)h(attrib)n(ute\),)f(314)1992 1196 y FJ(Mailbox)g FN(\(class)i(in)f(mailbox\),)e(219)1992 1295 y FJ(mailbox)2158 1395 y FN(module,)g FL(218)2158 1495 y FN(standard)h(module,)f(247)1992 1594 y FJ(mailcap)h FN(\(standard)g(module\),)f FL(218)1992 1694 y FJ(Maildir)h FN(\(class)i(in)f(mailbox\),)e(221)1992 1793 y FJ(MaildirMessage)g FN(\(class)i(in)h(mailbox\),)d(227)1992 1893 y FJ(MailmanProxy)g FN(\(class)j(in)f(smtpd\),)f(656)1992 1993 y FJ(main\(\))2158 2092 y FN(in)h(module)f(p)o(y)p 2601 2092 V 29 w(compile,)g(887)2158 2192 y(in)h(module)f(unittest,)h (796)1992 2292 y FJ(major\(\))f FN(\(in)h(module)f(os\),)h(404)1992 2391 y FJ(make_cookies\(\))e FN(\(CookieJar)h(method\),)f(674)1992 2491 y FJ(make_file\(\))g FN(\(in)i(module)f(dif)n(\003ib\),)g(66)1992 2590 y FJ(make_form\(\))f FN(\(in)i(module)f(\003\),)h(919)1992 2690 y FJ(make_header\(\))e FN(\(in)i(module)f(email.header\),)e(203) 1992 2790 y FJ(make_msgid\(\))h FN(\(in)i(module)f(email.utils\),)g (209)1992 2889 y FJ(make_parser\(\))f FN(\(in)i(module)f(xml.sax\),)f (288)1992 2989 y FJ(make_server\(\))47 b FN(\(in)h(module)g (wsgiref.simple)p 3627 2989 V 28 w(serv)o(er\),)2324 3089 y(612)1992 3188 y FJ(make_table\(\))18 b FN(\(in)i(module)f(dif)n (\003ib\),)g(66)1992 3288 y FJ(makedev\(\))g FN(\(in)h(module)e(os\),)i (404)1992 3387 y FJ(makedirs\(\))e FN(\(in)i(module)f(os\),)h(404)1992 3487 y FJ(makefile\(\))e FN(\(sock)o(et)i(method\),)e(582)1992 3587 y FJ(makefolder\(\))g FN(\(MH)i(method\),)e(238)1992 3686 y FJ(makeLogRecord\(\))f FN(\(in)j(module)f(logging\),)f(453)1992 3786 y FJ(makePickle\(\))g FN(\(Sock)o(etHandler)g(method\),)g(464)1992 3886 y FJ(makeRecord\(\))g FN(\()i(method\),)f(455)1992 3985 y FJ(makeSocket\(\))2158 4085 y FN(DatagramHandler)e(method,)i (464)2158 4185 y(Sock)o(etHandler)f(method,)g(464)1992 4284 y FJ(maketrans\(\))g FN(\(in)i(module)f(string\),)g(50)1992 4384 y FJ(map\(\))g FN(\(in)h(module)f(\),)h(10)1992 4483 y FJ(map_table_b2\(\))e FN(\(in)i(module)e(stringprep\),)g(92)1992 4583 y FJ(map_table_b3\(\))g FN(\(in)i(module)e(stringprep\),)g(92)1992 4683 y FJ(mapcolor\(\))g FN(\(in)i(module)f(\003\),)i(920)1992 4782 y(mapping)2158 4882 y(object,)e(37)2158 4982 y(types,)g (operations)g(on,)g(37)1992 5081 y FJ(mapping\(\))g FN(\(Control)g (method\),)f(938)1992 5181 y FJ(maps\(\))h FN(\(in)h(module)f(nis\),)h (568)1992 5280 y FJ(marshal)f FN(\(b)n(uilt-in)g(module\),)f FL(374)1992 5380 y FN(marshalling)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1003)p eop end %%Page: 1004 1016 TeXDict begin 1004 1015 bop 166 83 a FN(objects,)20 b(359)0 183 y(masking)166 282 y(operations,)e(26)0 382 y FJ(match\(\))166 482 y FN(in)i(module)f(nis,)i(568)166 581 y(in)f(module)f(re,)h(58)166 681 y(Re)o(ge)o(xObject)f(method,)f(59)0 780 y FJ(math)i FN(\(b)n(uilt-in)f(module\),)f(25,)i FL(149)p FN(,)f(152)0 880 y FJ(max\(\))166 980 y FN(b)n(uilt-in)h(function,)e(28)166 1079 y(Conte)o(xt)h(method,)g(161)166 1179 y(Decimal)h(method,)f(157) 166 1279 y(in)h(module)f(,)i(10)166 1378 y(in)f(module)f(audioop,)f (695)0 1478 y FJ(max)166 1577 y FN(date)i(attrib)n(ute,)g(99)166 1677 y(datetime)g(attrib)n(ute,)f(102)166 1777 y(time)h(attrib)n(ute,)g (106)166 1876 y(timedelta)g(attrib)n(ute,)f(97)0 1976 y FJ(MAX_INTERPOLATION_DEPTH)13 b FN(\(data)j(in)h(Con\002gP)o (arser\),)332 2076 y(311)0 2175 y FJ(maxarray)i FN(\(Repr)h(attrib)n (ute\),)f(147)0 2275 y FJ(maxdeque)g FN(\(Repr)h(attrib)n(ute\),)f(147) 0 2374 y FJ(maxdict)g FN(\(Repr)h(attrib)n(ute\),)f(147)0 2474 y FJ(maxfrozenset)g FN(\(Repr)g(attrib)n(ute\),)h(147)0 2574 y FJ(maxint)g FN(\(data)f(in)i(sys\),)f(831)0 2673 y FJ(MAXLEN)g FN(\(data)f(in)i(mimify\),)d(244)0 2773 y FJ(maxlevel)h FN(\(Repr)h(attrib)n(ute\),)f(147)0 2873 y FJ(maxlist)g FN(\(Repr)h(attrib)n(ute\),)f(147)0 2972 y FJ(maxlong)g FN(\(Repr)h(attrib)n(ute\),)f(147)0 3072 y FJ(maxother)g FN(\(Repr)h(attrib)n(ute\),)f(148)0 3171 y FJ(maxpp\(\))g FN(\(in)h(module)f(audioop\),)f(695)0 3271 y FJ(maxset)i FN(\(Repr)f(attrib)n(ute\),)h(147)0 3371 y FJ(maxstring)f FN(\(Repr)h(attrib)n(ute\),)f(147)0 3470 y FJ(maxtuple)g FN(\(Repr)h(attrib)n(ute\),)f(147)0 3570 y FJ(maxunicode)g FN(\(data)h(in)g(sys\),)g(831)0 3670 y FJ(MAXYEAR)f FN(\(data)h(in)h(datetime\),)e(96)0 3769 y FJ(MB_ICONASTERISK)f FN(\(data)i(in)g(winsound\),)e(946)0 3869 y FJ(MB_ICONEXCLAMATION)f FN(\(data)j(in)g(winsound\),)e(946)0 3968 y FJ(MB_ICONHAND)h FN(\(data)g(in)i(winsound\),)d(946)0 4068 y FJ(MB_ICONQUESTION)g FN(\(data)i(in)g(winsound\),)e(946)0 4168 y FJ(MB_OK)i FN(\(data)g(in)g(winsound\),)e(946)0 4267 y FJ(mbox)i FN(\(class)h(in)f(mailbox\),)e(223)0 4367 y FJ(mboxMessage)h FN(\(class)h(in)h(mailbox\),)d(228)0 4467 y FJ(md5\(\))i FN(\(in)g(module)f(md5\),)f(322)0 4566 y FJ(md5)i FN(\(b)n(uilt-in)f(module\),)g FL(321)0 4666 y FJ(MemberDescriptorType)e FN(\(data)j(in)g(types\),)f(142)0 4765 y FJ(memmove\(\))g FN(\(in)h(module)f(ctypes\),)g(529)0 4865 y FJ(MemoryError)g FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(19) 0 4965 y FJ(MemoryHandler)g FN(\(class)j(in)f(logging\),)e(466)0 5064 y FJ(memset\(\))h FN(\(in)h(module)f(ctypes\),)g(529)0 5164 y FJ(Message)166 5264 y FN(class)i(in)g(email.message,)e(190)166 5363 y(class)i(in)g(mailbox,)d(226)2158 83 y(class)j(in)f(mhlib,)f(237) 2158 183 y(class)i(in)f(mimetools,)f(239)2158 282 y(class)i(in)f (rfc822,)e(247)2158 382 y(in)i(module)f(mimetools,)g(669)1992 482 y(message)h(digest,)f(MD5,)h(319,)f(321)1992 581 y FJ(message_from_file\(\))51 b FN(\(in)j(module)f(email.parser\),)2324 681 y(197)1992 780 y FJ(message_from_string\(\))17 b FN(\(in)k(module)f(email.parser\),)2324 880 y(197)1992 980 y FJ(MessageBeep\(\))e FN(\(in)i(module)f(winsound\),)f(945)1992 1079 y FJ(MessageClass)25 b FN(\(BaseHTTPRequestHandler)h(attrib)n (ute\),)2324 1179 y(669)1992 1279 y FJ(MessageError)18 b FN(\(e)o(xception)g(in)i(email.errors\),)e(206)1992 1378 y FJ(MessageParseError)d FN(\(e)o(xception)h(in)j(email.errors\),) d(206)1992 1478 y FJ(meta\(\))j FN(\(in)h(module)f(curses\),)h(475)1992 1577 y FJ(Meter)f FN(\(class)i(in)f(T)m(ix\),)g(726)1992 1677 y(method)2158 1777 y(object,)f(43)1992 1876 y(methods)2158 1976 y(string,)g(29)1992 2076 y FJ(methods)g FN(\(class)i(descriptor)e (attrib)n(ute\),)g(886)1992 2175 y FJ(MethodType)f FN(\(data)i(in)g (types\),)g(142)1992 2275 y FJ(MH)2158 2374 y FN(class)h(in)f(mailbox,) f(223)2158 2474 y(class)i(in)f(mhlib,)f(237)1992 2574 y FJ(mhlib)g FN(\(standard)g(module\),)f FL(237)1992 2673 y FJ(MHMailbox)h FN(\(class)h(in)h(mailbox\),)d(235)1992 2773 y FJ(MHMessage)h FN(\(class)h(in)h(mailbox\),)d(230)1992 2873 y FJ(microsecond)2158 2972 y FN(datetime)h(attrib)n(ute,)h(102) 2158 3072 y(time)g(attrib)n(ute,)f(106)1992 3171 y(MIME)2158 3271 y(base64)g(encoding,)f(251)2158 3371 y(content)h(type,)g(241)2158 3470 y(headers,)g(241,)g(602)2158 3570 y(quoted-printable)d(encoding,)i (255)1992 3670 y FJ(mime_decode_header\(\))f FN(\(in)j(module)e (mimify\),)h(244)1992 3769 y FJ(mime_encode_header\(\))e FN(\(in)j(module)e(mimify\),)h(244)1992 3869 y FJ(MIMEApplication)e FN(\(class)k(in)g(email.mime.te)o(xt\),)c(200)1992 3968 y FJ(MIMEAudio)i FN(\(class)h(in)h(email.mime.te)o(xt\),)c(200)1992 4068 y FJ(MIMEBase)i FN(\(class)i(in)f(email.mime.te)o(xt\),)d(200)1992 4168 y FJ(MIMEImage)i FN(\(class)h(in)h(email.mime.te)o(xt\),)c(201) 1992 4267 y FJ(MIMEMessage)h FN(\(class)j(in)f(email.mime.te)o(xt\),)e (201)1992 4367 y FJ(MIMEMultipart)g FN(\(class)j(in)f(email.mime.te)o (xt\),)e(200)1992 4467 y FJ(MIMENonMultipart)f FN(\(class)k(in)f (email.mime.te)o(xt\),)e(200)1992 4566 y FJ(MIMEText)h FN(\(class)i(in)f(email.mime.te)o(xt\),)d(201)1992 4666 y FJ(mimetools)i FN(\(standard)f(module\),)g FL(239)p FN(,)i(617)1992 4765 y FJ(MimeTypes)f FN(\(class)h(in)h(mimetypes\),)d (242)1992 4865 y FJ(mimetypes)h FN(\(standard)f(module\),)g FL(241)1992 4965 y FJ(MimeWriter)2158 5064 y FN(class)j(in)f (MimeWriter)m(,)f(243)2158 5164 y(standard)g(module,)f FL(243)1992 5264 y FJ(mimify\(\))h FN(\(in)h(module)f(mimify\),)f(244) 1992 5363 y FJ(mimify)h FN(\(standard)g(module\),)f FL(244)p 0 5549 3901 4 v 0 5649 a FI(1004)3515 b(Inde)n(x)p eop end %%Page: 1005 1017 TeXDict begin 1005 1016 bop 0 83 a FJ(min\(\))166 183 y FN(b)n(uilt-in)20 b(function,)e(28)166 282 y(Conte)o(xt)h(method,)g (161)166 382 y(Decimal)h(method,)f(158)166 482 y(in)h(module)f(,)i(10)0 581 y FJ(min)166 681 y FN(date)f(attrib)n(ute,)g(99)166 780 y(datetime)g(attrib)n(ute,)f(102)166 880 y(time)h(attrib)n(ute,)g (106)166 980 y(timedelta)g(attrib)n(ute,)f(97)0 1079 y FJ(minmax\(\))g FN(\(in)h(module)f(audioop\),)f(694)0 1179 y FJ(minor\(\))h FN(\(in)h(module)f(os\),)h(404)0 1279 y FJ(minus\(\))f FN(\(Conte)o(xt)h(method\),)e(161)0 1378 y FJ(minute)166 1478 y FN(datetime)i(attrib)n(ute,)f(102)166 1577 y(time)h(attrib)n(ute,)g(106)0 1677 y FJ(MINYEAR)f FN(\(data)h(in)h(datetime\),)e(96)0 1777 y FJ(mirrored\(\))g FN(\(in)h(module)f(unicodedata\),)e(90)0 1876 y FJ(misc_header)i FN(\(Cmd)h(attrib)n(ute\),)f(759)0 1976 y FJ(MissingSectionHeaderError) k FN(\(e)o(xception)i(in)i(Con-)332 2076 y(\002gP)o(arser\),)19 b(311)0 2175 y(MIXERDEV)-11 b(,)20 b(708)0 2275 y FJ(mkd\(\))g FN(\(FTP)g(method\),)e(639)0 2374 y FJ(mkdir\(\))h FN(\(in)h(module)f (os\),)h(404)0 2474 y FJ(mkdtemp\(\))f FN(\(in)h(module)f (temp\002le\),)g(335)0 2574 y FJ(mkfifo\(\))g FN(\(in)h(module)f(os\),) h(404)0 2673 y FJ(mknod\(\))f FN(\(in)h(module)f(os\),)h(404)0 2773 y FJ(mkstemp\(\))f FN(\(in)h(module)f(temp\002le\),)g(335)0 2873 y FJ(mktemp\(\))g FN(\(in)h(module)f(temp\002le\),)g(335)0 2972 y FJ(mktime\(\))g FN(\(in)h(module)f(time\),)h(417)0 3072 y FJ(mktime_tz\(\))166 3171 y FN(in)g(module)f(email.utils,)h(208) 166 3271 y(in)g(module)f(rfc822,)f(248)0 3371 y FJ(mmap\(\))i FN(\(in)g(module)e(mmap\),)h(547)0 3470 y FJ(mmap)h FN(\(b)n(uilt-in)f (module\),)f FL(547)0 3570 y FJ(MMDF)i FN(\(class)h(in)f(mailbox\),)e (226)0 3670 y FJ(MmdfMailbox)h FN(\(class)h(in)h(mailbox\),)d(235)0 3769 y FJ(MMDFMessage)h FN(\(class)h(in)h(mailbox\),)d(232)0 3869 y FJ(mod\(\))i FN(\(in)g(module)f(operator\),)e(184)0 3968 y FJ(mode)166 4068 y FN(audio)i(de)n(vice)h(attrib)n(ute,)f(710) 166 4168 y(\002le)i(attrib)n(ute,)e(41)166 4267 y(T)-7 b(arInfo)19 b(attrib)n(ute,)g(355)0 4367 y FJ(modf\(\))h FN(\(in)g(module)e(math\),)i(150)0 4467 y FJ(modified\(\))f FN(\(RobotFileP)o(arser)g(method\),)f(313)0 4566 y FJ(Modify\(\))h FN(\(Binary)h(method\),)e(935)0 4666 y(module)166 4765 y(search)i(path,)f(338,)g(831,)g(850)0 4865 y FJ(module\(\))g FN(\(in)h(module)f(ne)n(w\),)g(143)0 4965 y FJ(module)166 5064 y FN(class)i(descriptor)e(attrib)n(ute,)h(886)166 5164 y(function)f(descriptor)f(attrib)n(ute,)i(886)0 5264 y FJ(ModuleFinder)f FN(\(class)h(in)h(module\002nder\),)c(871)0 5363 y FJ(modulefinder)i FN(\(standard)f(module\),)g FL(870)1992 83 y FJ(modules)h FN(\(data)h(in)g(sys\),)g(831)1992 183 y FJ(ModuleType)e FN(\(data)i(in)g(types\),)g(142)1992 282 y FJ(MON_1)48 b(...)99 b(MON_12)20 b FN(\(data)g(in)g(locale\),)g (753)1992 382 y FJ(mono2grey\(\))e FN(\(in)i(module)f(imageop\),)f(696) 1992 482 y FJ(month\(\))h FN(\(in)h(module)f(calendar\),)f(116)1992 581 y FJ(month)2158 681 y FN(date)i(attrib)n(ute,)f(99)2158 780 y(datetime)g(attrib)n(ute,)h(102)1992 880 y FJ(month_abbr)e FN(\(data)i(in)g(calendar\),)f(116)1992 980 y FJ(month_name)f FN(\(data)i(in)g(calendar\),)f(116)1992 1079 y FJ(monthcalendar\(\))e FN(\(in)j(module)f(calendar\),)g(116)1992 1179 y FJ (monthdatescalendar\(\))e FN(\(Calendar)i(method\),)f(114)1992 1279 y FJ(monthdays2calendar\(\))f FN(\(Calendar)i(method\),)f(114)1992 1378 y FJ(monthdayscalendar\(\))f FN(\(Calendar)i(method\),)f(114)1992 1478 y FJ(monthrange\(\))g FN(\(in)i(module)f(calendar\),)f(116)1992 1577 y FJ(more\(\))h FN(\(simple)p 2566 1577 25 4 v 29 w(producer)f(method\),)g(597)1992 1677 y FJ(Morsel)h FN(\(class)i(in)f(Cookie\),)f(681)1992 1777 y FJ(mouseinterval\(\))e FN(\(in)j(module)f(curses\),)h(475)1992 1876 y FJ(mousemask\(\))e FN(\(in)i(module)f(curses\),)h(475)1992 1976 y FJ(move\(\))2178 2076 y FN(method,)f(491,)g(548)2158 2175 y(in)h(module)f(shutil,)h(339) 2158 2275 y(windo)n(w)f(method,)f(481)1992 2374 y FJ(movemessage\(\))g FN(\(F)o(older)h(method\),)f(239)1992 2474 y FJ(MozillaCookieJar)f FN(\(class)k(in)f(cookielib\),)f(675)1992 2574 y FJ(msftoblock\(\))f FN(\(CD)j(player)e(method\),)f(917)1992 2673 y FJ(msftoframe\(\))g FN(\(in)i(module)f(cd\),)g(916)1992 2773 y FJ(msg\(\))g FN(\(T)-6 b(elnet)20 b(method\),)e(657)1992 2873 y FJ(msg)i FN(\(data)f(in)i(httplib\),)e(635)1992 2972 y FJ(MSG_)2192 2987 y(*)2261 2972 y FN(\(data)h(in)g(sock)o(et\),)g(578)1992 3072 y(msi,)g(933)1992 3171 y FJ(msilib)f FN(\(standard)g(module\),)f FL(933)1992 3271 y FJ(msvcrt)h FN(\(b)n(uilt-in)g(module\),)g FL(939)1992 3371 y FJ(mt_interact\(\))f FN(\(T)-6 b(elnet)20 b(method\),)e(657)1992 3470 y FJ(mtime\(\))h FN(\(RobotFileP)o(arser)g (method\),)f(313)1992 3570 y FJ(mtime)h FN(\(T)-7 b(arInfo)19 b(attrib)n(ute\),)g(355)1992 3670 y FJ(mul\(\))2158 3769 y FN(in)h(module)f(audioop,)f(695)2158 3869 y(in)i(module)f(operator)m (,)f(184)1992 3968 y FJ(MultiCall)h FN(\(class)h(in)h(xmlrpclib\),)d (687)1992 4068 y FJ(MultiFile)h FN(\(class)h(in)h(multi\002le\),)e(245) 1992 4168 y FJ(multifile)g FN(\(standard)f(module\),)g FL(245)1992 4267 y FJ(MULTILINE)h FN(\(data)g(in)i(re\),)e(57)1992 4367 y FJ(MultipartConversionError)145 b FN(\(e)o(xception)h(in)2324 4467 y(email.errors\),)18 b(207)1992 4566 y FJ(multiply\(\))g FN(\(Conte)o(xt)h(method\),)g(161)1992 4666 y(mutable)2158 4765 y(sequence)g(types,)g(34)2158 4865 y(sequence)g(types,)g (operations)g(on,)h(35)1992 4965 y FJ(MutableString)e FN(\(class)j(in)f(UserString\),)f(140)1992 5064 y FJ(mutex)2158 5164 y FN(class)i(in)f(mute)o(x,)f(132)2158 5264 y(standard)g(module,)f FL(132)1992 5363 y FJ(mvderwin\(\))g FN(\(windo)n(w)h(method\),)f(481)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1005)p eop end %%Page: 1006 1018 TeXDict begin 1006 1017 bop 0 83 a FJ(mvwin\(\))19 b FN(\(windo)n(w)g(method\),)f(481)0 183 y FJ(myrights\(\))h FN(\(IMAP4)p 802 183 25 4 v 28 w(stream)i(method\),)d(645)0 375 y FE(N)0 498 y FJ(name\(\))i FN(\(in)g(module)e(unicodedata\),)g (90)0 598 y FJ(name)166 698 y FN(Attr)j(attrib)n(ute,)e(279)166 797 y(audio)g(de)n(vice)h(attrib)n(ute,)f(710)166 897 y(class)i(descriptor)e(attrib)n(ute,)h(886)166 996 y(Cookie)g(attrib)n (ute,)f(678)166 1096 y(data)h(in)g(os,)h(396)166 1196 y(DocT)-6 b(est)20 b(attrib)n(ute,)g(781)166 1295 y(DocumentT)-7 b(ype)18 b(attrib)n(ute,)h(277)166 1395 y(\002le)i(attrib)n(ute,)e(41) 166 1495 y(function)g(descriptor)f(attrib)n(ute,)i(887)166 1594 y(T)-7 b(arInfo)19 b(attrib)n(ute,)g(355)0 1694 y FJ(name2codepoint)f FN(\(data)i(in)g(htmlentitydefs\),)e(264)0 1793 y FJ(NamedTemporaryFile\(\))f FN(\(in)j(module)f(temp\002le\),)g (335)0 1893 y FJ(NameError)g FN(\(e)o(xception)f(in)i(e)o(xceptions\),) e(19)0 1993 y FJ(namelist\(\))h FN(\(ZipFile)h(method\),)e(349)0 2092 y FJ(nameprep\(\))h FN(\(in)h(module)f(encodings.idna\),)d(89)0 2192 y FJ(namespace\(\))j FN(\(IMAP4)p 852 2192 V 28 w(stream)h(method\),)f(645)0 2292 y FJ(NAMESPACE_DNS)f FN(\(data)i(in)g(uuid\),)f(660)0 2391 y FJ(NAMESPACE_OID)f FN(\(data)i(in)g(uuid\),)f(660)0 2491 y FJ(NAMESPACE_URL)f FN(\(data)i(in)g(uuid\),)f(660)0 2590 y FJ(NAMESPACE_X500)f FN(\(data)i(in)g(uuid\),)f(660)0 2690 y FJ(NamespaceErr)g FN(\(e)o(xception)e(in)k(xml.dom\),)d(281)0 2790 y FJ(namespaceURI)h FN(\(Node)g(attrib)n(ute\),)g(275)0 2889 y(NaN,)h(8,)g(50)0 2989 y FJ(NannyNag)f FN(\(e)o(xception)f(in)j(tabnann)o(y\),)c(885)0 3089 y FJ(napms\(\))i FN(\(in)h(module)f(curses\),)h(475)0 3188 y FJ(ndiff\(\))f FN(\(in)h(module)f(dif)n(\003ib\),)g(67)0 3288 y FJ(ne\(\))h FN(\(in)g(module)f(operator\),)f(183)0 3387 y FJ(neg\(\))i FN(\(in)g(module)f(operator\),)e(184)0 3487 y FJ(nested\(\))i FN(\(in)h(module)f(conte)o(xtlib\),)f(838)0 3587 y FJ(netrc)166 3686 y FN(class)j(in)g(netrc,)e(314)166 3786 y(standard)g(module,)g FL(314)0 3886 y FJ(NetrcParseError)f FN(\(e)o(xception)g(in)i(netrc\),)f(314)0 3985 y FJ(netscape)g FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)h(676)0 4085 y(Netw)o(ork)f(Ne)n(ws)i(T)m(ransfer)e(Protocol,)g(647)0 4185 y FJ(new\(\))166 4284 y FN(in)h(module)f(hmac,)h(321)166 4384 y(in)g(module)f(md5,)g(322)166 4483 y(in)h(module)f(sha,)h(322)0 4583 y FJ(new)g FN(\(b)n(uilt-in)f(module\),)g FL(143)0 4683 y FJ(new_alignment\(\))f FN(\(writer)i(method\),)e(911)0 4782 y FJ(new_font\(\))h FN(\(writer)h(method\),)e(911)0 4882 y FJ(new_margin\(\))h FN(\(writer)g(method\),)f(911)0 4982 y FJ(new_module\(\))h FN(\(in)h(module)e(imp\),)i(866)0 5081 y FJ(new_panel\(\))f FN(\(in)h(module)f(curses.panel\),)f(491)0 5181 y FJ(new_spacing\(\))g FN(\(writer)i(method\),)e(911)0 5280 y FJ(new_styles\(\))h FN(\(writer)g(method\),)f(911)0 5380 y FJ(newconfig\(\))h FN(\(in)h(module)f(al\),)h(913)1992 83 y FJ(newgroups\(\))e FN(\(NNTP)i(method\),)f(649)1992 183 y FJ(newlines)g FN(\(\002le)h(attrib)n(ute\),)f(41)1992 282 y FJ(newnews\(\))g FN(\(NNTP)h(method\),)e(649)1992 382 y FJ(newpad\(\))h FN(\(in)h(module)f(curses\),)g(476)1992 482 y FJ(newwin\(\))g FN(\(in)h(module)f(curses\),)g(476)1992 581 y FJ(next\(\))2178 681 y FN(method,)g(381)2158 780 y(csv)h(reader)f(method,)g(306)2158 880 y(dbhash)g(method,)f(379)2158 980 y(\002le)i(method,)f(40)2158 1079 y(F)o(ormatError)e(method,)i(234) 2158 1179 y(iterator)g(method,)g(27)2158 1279 y(MultiFile)h(method,)f (246)2158 1378 y(NNTP)h(method,)f(650)2158 1478 y(T)-7 b(arFile)20 b(method,)f(354)1992 1577 y FJ(nextfile\(\))f FN(\(in)i(module)f(\002leinput\),)g(329)1992 1677 y FJ(nextkey\(\))g FN(\(in)h(module)e(gdbm\),)h(378)1992 1777 y FJ(nextpart\(\))f FN(\(MimeWriter)i(method\),)e(244)1992 1876 y FJ(nextSibling)g FN(\(Node)h(attrib)n(ute\),)h(275)1992 1976 y FJ(ngettext\(\))2158 2076 y FN(GNUT)m(ranslations)f(method,)f(744)2158 2175 y(in)i(module)f(gette)o(xt,)g(740)2158 2275 y(NullT)m(ranslations)f (method,)h(742)1992 2374 y FJ(NI_)2142 2389 y(*)2212 2374 y FN(\(data)g(in)i(sock)o(et\),)e(578)1992 2474 y FJ(nice\(\))g FN(\(in)h(module)f(os\),)h(410)1992 2574 y FJ(nis)g FN(\(e)o(xtension)e(module\),)g FL(568)1992 2673 y FN(NIST)-6 b(,)19 b(322)1992 2773 y FJ(NL)h FN(\(data)g(in)g (tok)o(enize\),)f(884)1992 2873 y FJ(nl\(\))h FN(\(in)g(module)e (curses\),)i(476)1992 2972 y FJ(nl_langinfo\(\))e FN(\(in)i(module)f (locale\),)g(750)1992 3072 y FJ(nlargest\(\))f FN(\(in)i(module)f (heapq\),)g(122)1992 3171 y FJ(nlst\(\))g FN(\(FTP)i(method\),)d(639) 1992 3271 y(NNTP)2158 3371 y(protocol,)g(647)1992 3470 y FJ(NNTP)i FN(\(class)g(in)h(nntplib\),)d(648)1992 3570 y FJ(NNTPDataError)g FN(\(e)o(xception)g(in)i(nntplib\),)f(649)1992 3670 y FJ(NNTPError)g FN(\(e)o(xception)f(in)i(nntplib\),)e(648)1992 3769 y FJ(nntplib)h FN(\(standard)g(module\),)f FL(647)1992 3869 y FJ(NNTPPermanentError)f FN(\(e)o(xception)h(in)i(nntplib\),)f (648)1992 3968 y FJ(NNTPProtocolError)e FN(\(e)o(xception)h(in)i (nntplib\),)f(649)1992 4068 y FJ(NNTPReplyError)f FN(\(e)o(xception)g (in)i(nntplib\),)e(648)1992 4168 y FJ(NNTPTemporaryError)f FN(\(e)o(xception)h(in)i(nntplib\),)f(648)1992 4267 y FJ(nocbreak\(\))f FN(\(in)i(module)f(curses\),)h(476)1992 4367 y FJ(NoDataAllowedErr)d FN(\(e)o(xception)h(in)j(xml.dom\),)c(281) 1992 4467 y FJ(Node)j FN(\(class)g(in)h(compiler)-5 b(.ast\),)18 b(898)1992 4566 y FJ(node\(\))h FN(\(in)h(module)f(platform\),)f(492) 1992 4666 y FJ(nodelay\(\))h FN(\(windo)n(w)f(method\),)h(481)1992 4765 y FJ(nodeName)g FN(\(Node)g(attrib)n(ute\),)g(275)1992 4865 y FJ(nodeType)g FN(\(Node)g(attrib)n(ute\),)g(275)1992 4965 y FJ(nodeValue)g FN(\(Node)g(attrib)n(ute\),)g(275)1992 5064 y FJ(NODISC)g FN(\(data)h(in)g(cd\),)g(916)1992 5164 y FJ(noecho\(\))f FN(\(in)h(module)f(curses\),)g(476)1992 5264 y FJ(NOEXPR)g FN(\(data)h(in)g(locale\),)g(753)1992 5363 y FJ(nofill)f FN(\(HTMLP)o(arser)g(attrib)n(ute\),)g(263)p 0 5549 3901 4 v 0 5649 a FI(1006)3515 b(Inde)n(x)p eop end %%Page: 1007 1019 TeXDict begin 1007 1018 bop 0 83 a FJ(nok_builtin_names)18 b FN(\(REx)o(ec)h(attrib)n(ute\),)g(861)0 183 y FJ(noload\(\))g FN(\(Unpickler)g(method\),)f(363)0 282 y FJ(NoModificationAllowedErr) 145 b FN(\(e)o(xception)i(in)332 382 y(xml.dom\),)18 b(281)0 482 y FJ(nonblock\(\))h FN(\(audio)g(de)n(vice)g(method\),)f (709)0 581 y FJ(None)166 681 y FN(Built-in)i(object,)g(23)166 780 y(data)g(in)g(,)h(22)0 880 y FJ(NoneType)e FN(\(data)h(in)g (types\),)g(141)0 980 y FJ(nonl\(\))g FN(\(in)g(module)e(curses\),)i (476)0 1079 y FJ(noop\(\))166 1179 y FN(IMAP4)p 421 1179 25 4 v 29 w(stream)g(method,)f(645)166 1279 y(POP3)p 365 1279 V 30 w(SSL)i(method,)d(641)0 1378 y FJ(NoOptionError)g FN(\(e)o(xception)g(in)j(Con\002gP)o(arser\),)d(310)0 1478 y FJ(noqiflush\(\))h FN(\(in)h(module)f(curses\),)g(476)0 1577 y FJ(noraw\(\))g FN(\(in)h(module)f(curses\),)h(476)0 1677 y FJ(normalize\(\))166 1777 y FN(Conte)o(xt)f(method,)g(161)166 1876 y(Decimal)h(method,)f(158)166 1976 y(in)h(module)f(locale,)h(751) 166 2076 y(in)g(module)f(unicodedata,)f(90)166 2175 y(Node)i(method,)e (276)0 2275 y FJ(NORMALIZE_WHITESPACE)f FN(\(data)j(in)g(doctest\),)f (773)0 2374 y FJ(normalvariate\(\))f FN(\(in)i(module)f(random\),)f (171)0 2474 y FJ(normcase\(\))h FN(\(in)h(module)f(os.path\),)f(327)0 2574 y FJ(normpath\(\))h FN(\(in)h(module)f(os.path\),)f(327)0 2673 y FJ(NoSectionError)g FN(\(e)o(xception)g(in)i(Con\002gP)o (arser\),)f(310)0 2773 y FJ(NoSuchMailboxError)e FN(\(class)k(in)g (mailbox\),)d(234)0 2873 y FJ(not)166 2972 y FN(operator)m(,)g(24)0 3072 y FJ(not)49 b(in)166 3171 y FN(operator)m(,)18 b(24,)h(28)0 3271 y FJ(not_\(\))h FN(\(in)g(module)e(operator\),)g(183)0 3371 y FJ(NotANumber)h FN(\(e)o(xception)f(in)i(fpformat\),)e(93)0 3470 y FJ(notationDecl\(\))g FN(\(DTDHandler)h(method\),)f(293)0 3570 y FJ(NotationDeclHandler\(\))f FN(\(xmlparser)h(method\),)g(268)0 3670 y FJ(notations)h FN(\(DocumentT)-7 b(ype)17 b(attrib)n(ute\),)j (277)0 3769 y FJ(NotConnected)f FN(\(e)o(xception)e(in)k(httplib\),)e (633)0 3869 y FJ(NoteBook)g FN(\(class)i(in)f(T)m(ix\),)g(728)0 3968 y FJ(NotEmptyErrorError)d FN(\(class)k(in)g(mailbox\),)d(234)0 4068 y FJ(NotFoundErr)h FN(\(e)o(xception)f(in)i(xml.dom\),)e(281)0 4168 y FJ(notify\(\))h FN(\(Condition)g(method\),)f(542)0 4267 y FJ(notifyAll\(\))h FN(\(Condition)f(method\),)g(542)0 4367 y FJ(notimeout\(\))h FN(\(windo)n(w)g(method\),)f(481)0 4467 y FJ(NotImplemented)g FN(\(data)i(in)g(\),)g(22)0 4566 y FJ(NotImplementedError)45 b FN(\(e)o(xception)h(in)i(e)o (xceptions\),)332 4666 y(19)0 4765 y FJ(NotImplementedType)17 b FN(\(data)j(in)g(types\),)g(142)0 4865 y FJ(NotStandaloneHandler\(\)) 74 b FN(\(xmlparser)h(method\),)332 4965 y(268)0 5064 y FJ(NotSupportedErr)18 b FN(\(e)o(xception)g(in)i(xml.dom\),)e(281)0 5164 y FJ(noutrefresh\(\))g FN(\(windo)n(w)h(method\),)f(481)0 5264 y FJ(now\(\))i FN(\(datetime)f(method\),)f(101)0 5363 y FJ(NSIG)i FN(\(data)g(in)g(signal\),)g(589)1992 83 y FJ(nsmallest\(\))e FN(\(in)i(module)f(heapq\),)f(123)1992 183 y FJ(NTEventLogHandler)f FN(\(class)k(in)f(logging\),)e(465)1992 282 y FJ(ntohl\(\))h FN(\(in)h(module)f(sock)o(et\),)g(580)1992 382 y FJ(ntohs\(\))g FN(\(in)h(module)f(sock)o(et\),)g(580)1992 482 y FJ(ntransfercmd\(\))f FN(\(FTP)i(method\),)e(639)1992 581 y FJ(NullFormatter)g FN(\(class)j(in)f(formatter\),)e(911)1992 681 y FJ(NullImporter)g FN(\(class)j(in)f(imp\),)g(867)1992 780 y FJ(NullWriter)e FN(\(class)j(in)g(formatter\),)d(912)1992 880 y(numeric)2158 980 y(con)m(v)o(ersions,)f(25)2158 1079 y(literals,)j(25)2158 1179 y(object,)f(24,)h(25)2158 1279 y(types,)f(operations)g(on,)g(25)1992 1378 y FJ(numeric\(\))g FN(\(in)h(module)e(unicodedata\),)g(90)1992 1478 y(Numerical)h(Python,) f(14)1992 1577 y FJ(nurbscurve\(\))g FN(\(in)i(module)f(gl\),)h(926) 1992 1677 y FJ(nurbssurface\(\))e FN(\(in)i(module)e(gl\),)i(926)1992 1777 y FJ(nvarray\(\))f FN(\(in)h(module)e(gl\),)i(926)1992 1974 y FE(O)1992 2097 y FJ(O_APPEND)f FN(\(data)g(in)i(os\),)f(401)1992 2197 y FJ(O_BINARY)f FN(\(data)g(in)i(os\),)f(401)1992 2297 y FJ(O_CREAT)f FN(\(data)h(in)g(os\),)g(401)1992 2396 y FJ(O_DSYNC)f FN(\(data)h(in)g(os\),)g(401)1992 2496 y FJ(O_EXCL)f FN(\(data)h(in)g(os\),)g(401)1992 2595 y FJ(O_EXLOCK)f FN(\(data)g(in)i(os\),)f(401)1992 2695 y FJ(O_NDELAY)f FN(\(data)g(in)i(os\),)f(401)1992 2795 y FJ(O_NOCTTY)f FN(\(data)g(in)i(os\),)f(401)1992 2894 y FJ(O_NOINHERIT)e FN(\(data)i(in)g(os\),)g(401)1992 2994 y FJ(O_NONBLOCK)e FN(\(data)i(in)g(os\),)g(401)1992 3094 y FJ(O_RANDOM)f FN(\(data)g(in)i(os\),)f(402)1992 3193 y FJ(O_RDONLY)f FN(\(data)g(in)i(os\),)f(401)1992 3293 y FJ(O_RDWR)f FN(\(data)h(in)g(os\),)g(401)1992 3392 y FJ(O_RSYNC)f FN(\(data)h(in)g(os\),)g(401)1992 3492 y FJ(O_SEQUENTIAL)e FN(\(data)i(in)g(os\),)g(402)1992 3592 y FJ(O_SHLOCK)f FN(\(data)g(in)i(os\),)f(401)1992 3691 y FJ(O_SHORT_LIVED)e FN(\(data)i(in)g(os\),)g(401)1992 3791 y FJ(O_SYNC)f FN(\(data)h(in)g(os\),)g(401)1992 3891 y FJ(O_TEMPORARY)e FN(\(data)i(in)g(os\),)g(402)1992 3990 y FJ(O_TEXT)f FN(\(data)h(in)g(os\),)g(402)1992 4090 y FJ(O_TRUNC)f FN(\(data)h(in)g(os\),)g(401)1992 4189 y FJ(O_WRONLY)f FN(\(data)g(in)i(os\),)f(401)1992 4289 y(object)2158 4389 y(Boolean,)f(25)2158 4488 y(b)n(uf)n(fer)m(,)f (27)2158 4588 y(code,)h(44,)g(374)2158 4688 y(comple)o(x)f(number)m(,)g (25)2158 4787 y(dictionary)-5 b(,)17 b(37)2158 4887 y(\002le,)j(39)2158 4986 y(\003oating)f(point,)g(25)2158 5086 y(inte)o(ger)m(,)f(25)2158 5186 y(list,)j(27,)e(34)2158 5285 y(long)g(inte)o(ger)m(,)f(25)2158 5385 y(mapping,)g(37)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1007)p eop end %%Page: 1008 1020 TeXDict begin 1008 1019 bop 166 83 a FN(method,)19 b(43)166 183 y(numeric,)g(24,)g(25)166 282 y(sequence,)g(27)166 382 y(set,)i(36)166 482 y(sock)o(et,)f(577)166 581 y(string,)g(27)166 681 y(traceback,)f(828,)g(840)166 780 y(tuple,)h(27)166 880 y(type,)g(15)166 980 y(Unicode,)f(27)166 1079 y(xrange,)f(27,)i(34) 0 1179 y FJ(object\(\))f FN(\(in)h(module)f(\),)h(10)0 1279 y(objects)166 1378 y(comparing,)e(24)166 1478 y(\003attening,)h (359)166 1577 y(marshalling,)g(359)166 1677 y(persistent,)h(359)166 1777 y(pickling,)f(359)166 1876 y(serializing,)g(359)0 1976 y FJ(obufcount\(\))g FN(\(audio)g(de)n(vice)g(method\),)f(710,)h (932)0 2076 y FJ(obuffree\(\))g FN(\(audio)g(de)n(vice)g(method\),)f (710)0 2175 y FJ(oct\(\))i FN(\(in)g(module)f(\),)h(10)0 2275 y(octal)166 2374 y(literals,)h(25)0 2474 y FJ(octdigits)e FN(\(data)h(in)g(string\),)f(48)0 2574 y FJ(offset)h FN(\(ExpatError)d(attrib)n(ute\),)i(269)0 2673 y FJ(OK)h FN(\(data)g(in)g(curses\),)g(483)0 2773 y FJ(ok_builtin_modules)d FN(\(REx)o(ec)j(attrib)n(ute\),)f(862)0 2873 y FJ(ok_file_types)f FN(\(REx)o(ec)i(attrib)n(ute\),)f(862)0 2972 y FJ(ok_path)g FN(\(REx)o(ec)h(attrib)n(ute\),)f(862)0 3072 y FJ(ok_posix_names)f FN(\(REx)o(ec)i(attrib)n(ute\),)f(862)0 3171 y FJ(ok_sys_names)g FN(\(REx)o(ec)g(attrib)n(ute\),)g(862)0 3271 y FJ(OleDLL)h FN(\(class)g(in)h(ctypes\),)e(523)0 3371 y FJ(onecmd\(\))g FN(\(Cmd)h(method\),)e(758)0 3470 y FJ(open\(\))166 3570 y FN(IMAP4)p 421 3570 25 4 v 29 w(stream)i(method,)f(645)166 3670 y(in)h(module)f(,)i(10)166 3769 y(in)f(module)f(aifc,)h(697)166 3869 y(in)g(module)f(an)o(ydbm,)f(375)166 3968 y(in)i(module)f(cd,)h (916)166 4068 y(in)g(module)f(codecs,)h(79)166 4168 y(in)g(module)f (dbhash,)g(379)166 4267 y(in)h(module)f(dbm,)g(377)166 4367 y(in)h(module)f(dl,)h(557)166 4467 y(in)g(module)f(dumbdbm,)e(382) 166 4566 y(in)j(module)f(gdbm,)g(377)166 4666 y(in)h(module)f(gzip,)h (346)166 4765 y(in)g(module)f(os,)i(400)166 4865 y(in)f(module)f (ossaudiode)n(v)-5 b(,)18 b(707)166 4965 y(in)i(module)f(posix\002le,)h (564)166 5064 y(in)g(module)f(shelv)o(e,)h(371)166 5164 y(in)g(module)f(sunau,)g(699)166 5264 y(in)h(module)f(sunaudiode)n(v)-5 b(,)17 b(931)166 5363 y(in)j(module)f(tar\002le,)h(352)2158 83 y(in)g(module)f(w)o(a)n(v)o(e,)h(702)2158 183 y(in)g(module)f (webbro)n(wser)m(,)f(600,)h(601)2158 282 y(OpenerDirector)e(method,)i (626)2158 382 y(T)-7 b(arFile)20 b(method,)f(353)2158 482 y(T)-6 b(elnet)20 b(method,)e(657)2158 581 y(T)-6 b(emplate)19 b(method,)g(563)2158 681 y(URLopener)f(method,)h(621)1992 780 y FJ(open_new\(\))f FN(\(in)i(module)f(webbro)n(wser\),)f(600,)h (602)1992 880 y FJ(open_new_tab\(\))f FN(\(in)i(module)e(webbro)n (wser\),)g(600,)h(602)1992 980 y FJ(open_osfhandle\(\))e FN(\(in)j(module)f(msvcrt\),)g(940)1992 1079 y FJ(open_unknown\(\))f FN(\(URLopener)g(method\),)g(621)1992 1179 y FJ(OpenDatabase\(\))g FN(\(in)i(module)e(msilib\),)i(933)1992 1279 y FJ(opendir\(\))f FN(\(in)h(module)e(dircache\),)h(340)1992 1378 y FJ(OpenerDirector)f FN(\(class)i(in)h(urllib2\),)d(623)1992 1478 y FJ(openfolder\(\))g FN(\(MH)i(method\),)e(238)1992 1577 y FJ(openfp\(\))2158 1677 y FN(in)i(module)f(sunau,)g(700)2158 1777 y(in)h(module)f(w)o(a)n (v)o(e,)h(702)1992 1876 y(OpenGL,)f(927)1992 1976 y FJ(OpenKey\(\))g FN(\(in)h(module)p 2848 1976 V 48 w(winre)o(g\),)f(942)1992 2076 y FJ(OpenKeyEx\(\))f FN(\(in)i(module)p 2948 2076 V 49 w(winre)o(g\),)e(943)1992 2175 y FJ(openlog\(\))h FN(\(in)h(module)e(syslog\),)i(568)1992 2275 y FJ(openmessage\(\))e FN(\(Message)i(method\),)e(239)1992 2374 y FJ(openmixer\(\))g FN(\(in)i(module)f(ossaudiode)n(v\),)f(708)1992 2474 y FJ(openport\(\))g FN(\(in)i(module)f(al\),)h(913)1992 2574 y FJ(openpty\(\))2158 2673 y FN(in)g(module)f(os,)h(400)2158 2773 y(in)g(module)f(pty)-5 b(,)19 b(560)1992 2873 y(OpenSSL,)g(319) 1992 2972 y FJ(OpenView\(\))f FN(\(Binary)i(method\),)e(934)1992 3072 y(operation)2158 3171 y(concatenation,)f(28)2158 3271 y(e)o(xtended)h(slice,)i(28)2158 3371 y(repetition,)e(28)2158 3470 y(slice,)i(28)2158 3570 y(subscript,)f(28)1992 3670 y(operations)2158 3769 y(bit-string,)g(26)2158 3869 y(Boolean,)g(23) 2158 3968 y(masking,)f(26)2158 4068 y(shifting,)h(26)1992 4168 y(operations)f(on)2158 4267 y(dictionary)g(type,)h(37)2158 4367 y(inte)o(ger)g(types,)g(26)2158 4467 y(list)i(type,)e(35)2158 4566 y(mapping)f(types,)i(37)2158 4666 y(mutable)f(sequence)g(types,)h (35)2158 4765 y(numeric)e(types,)i(25)2158 4865 y(sequence)f(types,)g (28,)h(35)1992 4965 y(operator)2158 5064 y FJ(==)p FN(,)g(24)2158 5164 y FJ(and)p FN(,)g(23,)f(24)2158 5264 y(comparison,)e(24)2158 5363 y FJ(in)p FN(,)j(24,)f(28)p 0 5549 3901 4 v 0 5649 a FI(1008)3515 b(Inde)n(x)p eop end %%Page: 1009 1021 TeXDict begin 1009 1020 bop 166 83 a FJ(is)p FN(,)20 b(24)166 183 y FJ(is)49 b(not)p FN(,)20 b(24)166 282 y FJ(not)p FN(,)g(24)166 382 y FJ(not)49 b(in)p FN(,)20 b(24,)g(28)166 482 y FJ(or)p FN(,)g(23,)g(24)0 581 y FJ(operator)f FN(\(b)n(uilt-in)g(module\),)g FL(182)0 681 y FJ(opmap)h FN(\(data)g(in)g(dis\),)g(889)0 780 y FJ(opname)g FN(\(data)f(in)i(dis\),)f(889)0 880 y FJ(OptionMenu)f FN(\(class)i(in)f(T)m(ix\),)g(726)0 980 y FJ(options\(\))f FN(\(SafeCon\002gP)o(arser)f(method\),)h(311)0 1079 y FJ(options)g FN(\(Example)g(attrib)n(ute\),)g(782)0 1179 y FJ(optionxform\(\))f FN(\(SafeCon\002gP)o(arser)h(method\),)f(312)0 1279 y FJ(optparse)h FN(\(standard)g(module\),)f FL(420)0 1378 y FJ(or)166 1478 y FN(operator)m(,)g(23,)h(24)0 1577 y FJ(or_\(\))h FN(\(in)g(module)f(operator\),)e(184)0 1677 y FJ(ord\(\))j FN(\(in)g(module)f(\),)h(11)0 1777 y FJ(ordered_attributes)d FN(\(xmlparser)i(attrib)n(ute\),)g(266)0 1876 y FJ(origin_server)f FN(\(BaseHandler)i(attrib)n(ute\),)f(616)0 1976 y FJ(os)h FN(\(standard)f(module\),)f(39,)i FL(395)p FN(,)f(553)0 2076 y FJ(os.path)g FN(\(standard)g(module\),)f FL(325)0 2175 y FJ(os_environ)h FN(\(BaseHandler)g(attrib)n(ute\),)g (615)0 2275 y FJ(OSError)g FN(\(e)o(xception)f(in)j(e)o(xceptions\),)d (19)0 2374 y FJ(ossaudiodev)h FN(\(b)n(uilt-in)g(module\),)f FL(707)0 2474 y FJ(OSSAudioError)g FN(\(e)o(xception)g(in)j(ossaudiode) n(v\),)c(707)0 2574 y FJ(output\(\))166 2673 y FN(BaseCookie)j(method,) f(681)166 2773 y(Morsel)h(method,)f(682)0 2873 y FJ(output_charset\(\)) f FN(\(NullT)m(ranslations)g(method\),)h(742)0 2972 y FJ(output_charset)f FN(\(data)i(in)g(email.charset\),)f(204)0 3072 y FJ(output_codec)g FN(\(data)g(in)i(email.charset\),)d(204)0 3171 y FJ(output_difference\(\))62 b FN(\(OutputCheck)o(er)g(method\),) 332 3271 y(785)0 3371 y FJ(OutputChecker)18 b FN(\(class)j(in)f (doctest\),)g(784)0 3470 y FJ(OutputString\(\))e FN(\(Morsel)i (method\),)e(682)0 3570 y FJ(OutputType)h FN(\(data)h(in)g (cStringIO\),)f(75)0 3670 y FJ(Overflow)g FN(\(class)i(in)f(decimal\),) f(163)0 3769 y FJ(OverflowError)f FN(\(e)o(xception)g(in)j(e)o (xceptions\),)d(19)0 3869 y FJ(overlay\(\))h FN(\(windo)n(w)g (method\),)f(481)0 3968 y(Ov)o(ermars,)h(Mark,)g(919)0 4068 y FJ(overwrite\(\))g FN(\(windo)n(w)g(method\),)f(481)0 4261 y FE(P)0 4384 y FJ(P_DETACH)h FN(\(data)h(in)g(os\),)g(411)0 4483 y FJ(P_NOWAIT)f FN(\(data)h(in)g(os\),)g(411)0 4583 y FJ(P_NOWAITO)f FN(\(data)h(in)g(os\),)g(411)0 4683 y FJ(P_OVERLAY)f FN(\(data)h(in)g(os\),)g(411)0 4782 y FJ(P_WAIT)g FN(\(data)f(in)i(os\),)f(411)0 4882 y FJ(pack\(\))166 4982 y FN(in)g(module)f(struct,)h(63)166 5081 y(MH)h(method,)d(224)166 5181 y(Struct)i(method,)f(65)0 5280 y FJ(pack_array\(\))g FN(\(P)o(ack)o(er)g(method\),)f(316)0 5380 y FJ(pack_bytes\(\))h FN(\(P)o(ack)o(er)g(method\),)f(316)1992 83 y FJ(pack_double\(\))g FN(\(P)o(ack)o(er)h(method\),)f(315)1992 183 y FJ(pack_farray\(\))g FN(\(P)o(ack)o(er)h(method\),)f(316)1992 282 y FJ(pack_float\(\))g FN(\(P)o(ack)o(er)h(method\),)f(315)1992 382 y FJ(pack_fopaque\(\))g FN(\(P)o(ack)o(er)h(method\),)f(315)1992 482 y FJ(pack_fstring\(\))g FN(\(P)o(ack)o(er)h(method\),)f(315)1992 581 y FJ(pack_into\(\))2158 681 y FN(in)i(module)f(struct,)h(63)2158 780 y(Struct)g(method,)e(65) 1992 880 y FJ(pack_list\(\))g FN(\(P)o(ack)o(er)h(method\),)g(316)1992 980 y FJ(pack_opaque\(\))f FN(\(P)o(ack)o(er)h(method\),)f(315)1992 1079 y FJ(pack_string\(\))g FN(\(P)o(ack)o(er)h(method\),)f(315)1992 1179 y(package,)g(850)1992 1279 y FJ(Packer)h FN(\(class)i(in)f (xdrlib\),)f(315)1992 1378 y(packing)2158 1478 y(binary)f(data,)i(62) 1992 1577 y(packing)e(\(widgets\),)h(719)1992 1677 y(P)-8 b(A)m(GER,)20 b(807)1992 1777 y FJ(pair_content\(\))e FN(\(in)i(module)e(curses\),)i(476)1992 1876 y FJ(pair_number\(\))e FN(\(in)i(module)f(curses\),)g(476)1992 1976 y FJ(PanedWindow)f FN(\(class)j(in)f(T)m(ix\),)g(728)1992 2076 y FJ(pardir)f FN(\(data)h(in)g(os\),)g(414)1992 2175 y FJ(parent)f FN(\(BaseHandler)g(attrib)n(ute\),)h(627)1992 2275 y FJ(parentNode)e FN(\(Node)i(attrib)n(ute\),)f(275)1992 2374 y FJ(paretovariate\(\))e FN(\(in)j(module)f(random\),)f(171)1992 2474 y FJ(Parse\(\))h FN(\(xmlparser)f(method\),)h(265)1992 2574 y FJ(parse\(\))2158 2673 y FN(DocT)-6 b(estP)o(arser)19 b(method,)g(783)2158 2773 y(ElementT)m(ree)f(method,)h(301)2158 2873 y(in)h(module)f(cgi,)h(606)2158 2972 y(in)g(module)f(compiler)m(,) f(897)2158 3072 y(in)i(module)f(xml.dom.minidom,)c(283)2158 3171 y(in)20 b(module)f(xml.dom.pulldom,)c(287)2158 3271 y(in)20 b(module)f(xml.etree.ElementT)m(ree,)d(299)2158 3371 y(in)k(module)f(xml.sax,)g(288)2158 3470 y(P)o(arser)h(method,)e (197)2158 3570 y(RobotFileP)o(arser)h(method,)f(313)2158 3670 y(XMLReader)h(method,)f(295)1992 3769 y FJ(parse_and_bind\(\))f FN(\(in)j(module)f(readline\),)g(549)1992 3869 y FJ(PARSE_COLNAMES)f FN(\(data)h(in)i(sqlite3\),)e(385)1992 3968 y FJ(PARSE_DECLTYPES)e FN(\(data)j(in)h(sqlite3\),)e(385)1992 4068 y FJ(parse_header\(\))f FN(\(in)i(module)e(cgi\),)i(606)1992 4168 y FJ(parse_multipart\(\))d FN(\(in)j(module)f(cgi\),)h(606)1992 4267 y FJ(parse_qs\(\))e FN(\(in)i(module)f(cgi\),)h(606)1992 4367 y FJ(parse_qsl\(\))e FN(\(in)i(module)f(cgi\),)h(606)1992 4467 y FJ(parseaddr\(\))2158 4566 y FN(in)g(module)f(email.utils,)h(208)2158 4666 y(in)g(module)f(rfc822,)f(248)1992 4765 y FJ(parsedate\(\))2158 4865 y FN(in)i(module)f(email.utils,)h(208)2158 4965 y(in)g(module)f(rfc822,)f(248)1992 5064 y FJ(parsedate_tz\(\))2158 5164 y FN(in)i(module)f(email.utils,)h(208)2158 5264 y(in)g(module)f(rfc822,)f(248)1992 5363 y FJ(ParseFile\(\))g FN(\(xmlparser)h(method\),)f(265)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1009)p eop end %%Page: 1010 1022 TeXDict begin 1010 1021 bop 0 83 a FJ(parseFile\(\))19 b FN(\(in)h(module)f(compiler\),)f(897)0 183 y FJ(ParseFlags\(\))h FN(\(in)h(module)e(imaplib\),)h(643)0 282 y FJ(parseframe\(\))g FN(\(CD)h(parser)g(method\),)e(918)0 382 y FJ(Parser)i FN(\(class)g(in)h(email.parser\),)d(197)0 482 y FJ(parser)i FN(\(b)n(uilt-in)f(module\),)f FL(873)0 581 y FJ(ParserCreate\(\))g FN(\(in)i(module)f(xml.parsers.e)o(xpat\),)d(264)0 681 y FJ(ParserError)j FN(\(e)o(xception)f(in)i(parser\),)f(876)0 780 y FJ(ParseResult)g FN(\(class)h(in)h(urlparse\),)d(664)0 880 y FJ(parsesequence\(\))g FN(\(F)o(older)h(method\),)f(239)0 980 y FJ(parsestr\(\))h FN(\(P)o(arser)h(method\),)e(197)0 1079 y FJ(parseString\(\))166 1179 y FN(in)i(module)f(xml.dom.minidom,) d(283)166 1279 y(in)k(module)f(xml.dom.pulldom,)d(287)166 1378 y(in)k(module)f(xml.sax,)g(288)0 1478 y(parsing)166 1577 y(Python)g(source)h(code,)f(873)166 1677 y(URL,)i(661)0 1777 y FJ(ParsingError)e FN(\(e)o(xception)e(in)k(Con\002gP)o(arser\),) d(311)0 1876 y FJ(partial\(\))166 1976 y FN(IMAP4)p 421 1976 25 4 v 29 w(stream)i(method,)f(645)166 2076 y(in)h(module)f (functools,)g(181)0 2175 y FJ(partition\(\))g FN(\(string)g(method\),)f (30)0 2275 y FJ(pass_\(\))h FN(\(POP3)p 596 2275 V 30 w(SSL)i(method\),)d(641)0 2374 y(P)-8 b(A)f(TH,)20 b(409,)f(411,)h (415,)f(607,)g(609)0 2474 y(path)166 2574 y(con\002guration)f(\002le,)i (850)166 2673 y(module)f(search,)g(338,)g(831,)g(850)166 2773 y(operations,)f(325)0 2873 y FJ(path)166 2972 y FN(BaseHTTPRequestHandler)h(attrib)n(ute,)g(668)166 3072 y(Cookie)h(attrib)n(ute,)f(678)166 3171 y(data)h(in)g(os,)h(396)166 3271 y(data)f(in)g(sys,)h(831)0 3371 y(P)o(ath)f(bro)n(wser)m(,)f(733)0 3470 y FJ(path_return_ok\(\))f FN(\(CookiePolic)o(y)g(method\),)g(676)0 3570 y FJ(pathconf\(\))h FN(\(in)h(module)f(os\),)h(404)0 3670 y FJ(pathconf_names)e FN(\(data)i(in)g(os\),)g(404)0 3769 y FJ(pathname2url\(\))e FN(\(in)i(module)f(urllib\),)g(619)0 3869 y FJ(pathsep)g FN(\(data)h(in)h(os\),)e(414)0 3968 y FJ(pattern)g FN(\(Re)o(ge)o(xObject)g(attrib)n(ute\),)g(60)0 4068 y FJ(pause\(\))g FN(\(in)h(module)f(signal\),)h(589)0 4168 y FJ(PAUSED)g FN(\(data)f(in)i(cd\),)e(916)0 4267 y FJ(Pdb)h FN(\(class)h(in)f(pdb\),)f(805)0 4367 y FJ(pdb)h FN(\(standard)f(module\),)f FL(805)0 4467 y FJ(Pen)i FN(\(class)h(in)f(turtle\),)g(732)0 4566 y FJ (PendingDeprecationWarning)44 b FN(\(e)o(xception)h(in)j(e)o(x-)332 4666 y(ceptions\),)19 b(21)0 4765 y(Performance,)f(821)0 4865 y FJ(Persist\(\))h FN(\(Binary)g(method\),)g(936)0 4965 y(persistence,)g(359)0 5064 y(persistent)166 5164 y(objects,)h(359)0 5264 y FJ(pformat\(\))166 5363 y FN(in)g(module)f (pprint,)g(145)2158 83 y(PrettyPrinter)g(method,)f(146)1992 183 y FJ(pi)2158 282 y FN(data)i(in)g(cmath,)f(152)2158 382 y(data)h(in)g(math,)g(151)1992 482 y FJ(pick\(\))f FN(\(in)h(module)f(gl\),)h(926)1992 581 y FJ(pickle\(\))f FN(\(in)h(module)f(cop)o(y)p 2961 581 V 28 w(re)o(g\),)g(371)1992 681 y FJ(pickle)g FN(\(standard)g(module\),)f(144,)h FL(359)p FN(,)g(370,)g(371,)g(374)1992 780 y FJ(PickleError)f FN(\(e)o(xception)g(in)j(pickle\),)e(362)1992 880 y FJ(Pickler)g FN(\(class)i(in)f(pickle\),)f(362)1992 980 y FJ(pickletools)f FN(\(standard)h(module\),)f FL(896)1992 1079 y FN(pickling)2158 1179 y(objects,)h(359)1992 1279 y FJ(PicklingError)f FN(\(e)o(xception)g(in)i(pickle\),)f(362)1992 1378 y FJ(pid)2158 1478 y FN(Popen4)f(attrib)n(ute,)i(591)2158 1577 y(Popen)f(attrib)n(ute,)g(574)1992 1677 y(PIL)h(\(the)g(Python)f (Imaging)f(Library\),)g(928)1992 1777 y FJ(pipe\(\))h FN(\(in)h(module)f(os\),)h(401)1992 1876 y FJ(pipes)f FN(\(standard)g(module\),)f FL(562)1992 1976 y FJ(PKG_DIRECTORY)g FN(\(data)i(in)g(imp\),)f(866)1992 2076 y FJ(pkgutil)g FN(\(standard)g(module\),)f FL(870)1992 2175 y FJ(platform\(\))g FN(\(in)i(module)f(platform\),)f(492)1992 2275 y FJ(platform)2158 2374 y FN(data)i(in)g(sys,)h(831)2158 2474 y(standard)e(module,)f FL(492)1992 2574 y FJ(play\(\))h FN(\(CD)i(player)e(method\),)f(917) 1992 2673 y FJ(playabs\(\))h FN(\(CD)h(player)g(method\),)e(917)1992 2773 y FJ(PLAYING)h FN(\(data)h(in)g(cd\),)g(916)1992 2873 y FJ(PlaySound\(\))e FN(\(in)i(module)f(winsound\),)f(945)1992 2972 y FJ(playtrack\(\))g FN(\(CD)j(player)e(method\),)f(917)1992 3072 y FJ(playtrackabs\(\))g FN(\(CD)i(player)g(method\),)e(917)1992 3171 y FJ(plock\(\))h FN(\(in)h(module)f(os\),)h(410)1992 3271 y FJ(plus\(\))f FN(\(Conte)o(xt)g(method\),)f(161)1992 3371 y FJ(pm\(\))i FN(\(in)g(module)e(pdb\),)h(806)1992 3470 y FJ(pnum)h FN(\(data)f(in)i(cd\),)e(916)1992 3570 y FJ(POINTER\(\))g FN(\(in)h(module)e(ctypes\),)i(529)1992 3670 y FJ(pointer\(\))f FN(\(in)h(module)e(ctypes\),)i(529)1992 3769 y FJ(poll\(\))2178 3869 y FN(method,)f(536)2158 3968 y(in)h(module)f(select,)h(535)2158 4068 y(Popen4)e(method,)h(591) 2158 4168 y(Popen)g(method,)f(573)1992 4267 y FJ(pop\(\))2178 4367 y FN(method,)h(117)2158 4467 y(array)g(method,)f(127)2158 4566 y(dictionary)g(method,)h(37)2158 4666 y(\002fo)h(method,)e(597) 2158 4765 y(list)j(method,)d(35)2158 4865 y(Mailbox)h(method,)f(221) 2158 4965 y(MultiFile)i(method,)f(246)1992 5064 y(POP3)2158 5164 y(protocol,)f(640)1992 5264 y FJ(POP3)i FN(\(class)g(in)h (poplib\),)d(640)1992 5363 y FJ(POP3_SSL)h FN(\(class)i(in)f(poplib\),) e(640)p 0 5549 3901 4 v 0 5649 a FI(1010)3515 b(Inde)n(x)p eop end %%Page: 1011 1023 TeXDict begin 1011 1022 bop 0 83 a FJ(pop_alignment\(\))18 b FN(\(formatter)g(method\),)g(910)0 183 y FJ(pop_font\(\))h FN(\(formatter)f(method\),)g(910)0 282 y FJ(pop_margin\(\))h FN(\(formatter)f(method\),)g(910)0 382 y FJ(pop_source\(\))h FN(\(shle)o(x)g(method\),)f(760)0 482 y FJ(pop_style\(\))h FN(\(formatter)f(method\),)g(911)0 581 y FJ(Popen)i FN(\(class)h(in)f (subprocess\),)e(571)0 681 y FJ(popen\(\))166 780 y FN(in)i(module)f (os,)i(398)166 880 y(in)f(module)f(os,)i(536)166 980 y(in)f(module)f(platform,)g(494)0 1079 y FJ(popen2\(\))166 1179 y FN(in)h(module)f(os,)i(399)166 1279 y(in)f(module)f(popen2,)f (590)0 1378 y FJ(popen2)i FN(\(standard)e(module\),)h FL(590)0 1478 y FJ(Popen3)h FN(\(class)g(in)h(popen2\),)c(590)0 1577 y FJ(popen3\(\))166 1677 y FN(in)j(module)f(os,)i(399)166 1777 y(in)f(module)f(popen2,)f(590)0 1876 y FJ(Popen4)i FN(\(class)g(in)h(popen2\),)c(591)0 1976 y FJ(popen4\(\))166 2076 y FN(in)j(module)f(os,)i(399)166 2175 y(in)f(module)f(popen2,)f (590)0 2275 y FJ(popitem\(\))166 2374 y FN(dictionary)g(method,)h(37) 166 2474 y(Mailbox)g(method,)g(221)0 2574 y FJ(popleft\(\))g FN(\()h(method\),)f(117)0 2673 y FJ(poplib)h FN(\(standard)e(module\),) h FL(640)0 2773 y FJ(PopupMenu)g FN(\(class)i(in)f(T)m(ix\),)g(726)0 2873 y FJ(port)g FN(\(Cookie)f(attrib)n(ute\),)g(678)0 2972 y FJ(port_specified)f FN(\(Cookie)h(attrib)n(ute\),)h(679)0 3072 y FJ(PortableUnixMailbox)d FN(\(class)k(in)f(mailbox\),)f(235)0 3171 y FJ(pos\(\))h FN(\(in)g(module)f(operator\),)e(184)0 3271 y FJ(pos)j FN(\(MatchObject)f(attrib)n(ute\),)g(61)0 3371 y FJ(position\(\))g FN(\(in)h(module)f(turtle\),)g(732)0 3470 y(POSIX)166 3570 y(\002le)i(object,)e(563)166 3670 y(I/O)h(control,)f(558)166 3769 y(threads,)g(537)0 3869 y FJ(posix)166 3968 y FN(b)n(uilt-in)h(module,)e FL(553)166 4068 y FN(T)-7 b(arFile)21 b(attrib)n(ute,)e(354)0 4168 y FJ(posixfile)g FN(\(b)n(uilt-in)g(module\),)g FL(563)0 4267 y FJ(post\(\))166 4367 y FN(audio)g(de)n(vice)h(method,)e(709)166 4467 y(NNTP)j(method,)d(650)0 4566 y FJ(post_mortem\(\))g FN(\(in)i(module)f(pdb\),)g(806)0 4666 y FJ(postcmd\(\))g FN(\(Cmd)h(method\),)e(758)0 4765 y FJ(postloop\(\))h FN(\(Cmd)h(method\),)e(758)0 4865 y FJ(pow\(\))166 4965 y FN(in)i(module)f(,)i(11)166 5064 y(in)f(module)f(math,)h(150)166 5164 y(in)g(module)f(operator)m(,)f(184)0 5264 y FJ(power\(\))h FN(\(Conte)o(xt)h(method\),)e(161)0 5363 y FJ(pprint\(\))2158 83 y FN(in)i(module)f(pprint,)g(145)2158 183 y(PrettyPrinter)g(method,) f(146)1992 282 y FJ(pprint)h FN(\(standard)g(module\),)f FL(144)1992 382 y FJ(prcal\(\))h FN(\(in)h(module)f(calendar\),)f(116) 1992 482 y FJ(preamble)h FN(\(data)g(in)i(email.message\),)d(195)1992 581 y FJ(precmd\(\))h FN(\(Cmd)h(method\),)e(758)1992 681 y FJ(prefix)2158 780 y FN(Attr)i(attrib)n(ute,)g(279)2158 880 y(data)g(in)g(sys,)h(831)2158 980 y(Node)e(attrib)n(ute,)h(275)1992 1079 y FJ(preloop\(\))f FN(\(Cmd)g(method\),)g(758)1992 1179 y FJ(preorder\(\))f FN(\(ASTV)-5 b(isitor)20 b(method\),)e(904) 1992 1279 y FJ(prepare_input_source\(\))231 b FN(\(in)k(module)2324 1378 y(xml.sax.saxutils\),)18 b(294)1992 1478 y FJ(prepend\(\))h FN(\(T)-6 b(emplate)19 b(method\),)f(563)1992 1577 y FJ(PrettyPrinter)g FN(\(class)j(in)f(pprint\),)e(144)1992 1677 y FJ(preventremoval\(\))f FN(\(CD)k(player)e(method\),)f(917)1992 1777 y FJ(previous\(\))2178 1876 y FN(method,)h(381)2158 1976 y(dbhash)g(method,)f(379)1992 2076 y FJ(previousSibling)f FN(\(Node)j(attrib)n(ute\),)f(275)1992 2175 y FJ(print)2158 2275 y FN(statement,)g(23)1992 2374 y FJ(print_callees\(\))e FN(\(Stats)k(method\),)e(817)1992 2474 y FJ(print_callers\(\))e FN(\(Stats)k(method\),)e(817)1992 2574 y FJ(print_directory\(\))e FN(\(in)j(module)f(cgi\),)h(606)1992 2673 y FJ(print_environ\(\))d FN(\(in)j(module)f(cgi\),)h(606)1992 2773 y FJ(print_environ_usage\(\)) c FN(\(in)k(module)f(cgi\),)h(606)1992 2873 y FJ(print_exc\(\))2158 2972 y FN(in)g(module)f(traceback,)f(840)2158 3072 y(T)m(imer)h (method,)g(821)1992 3171 y FJ(print_exception\(\))e FN(\(in)j(module)f (traceback\),)f(840)1992 3271 y FJ(print_form\(\))g FN(\(in)i(module)f (cgi\),)g(606)1992 3371 y FJ(print_last\(\))f FN(\(in)i(module)f (traceback\),)f(841)1992 3470 y FJ(print_stack\(\))g FN(\(in)i(module)f(traceback\),)f(841)1992 3570 y FJ(print_stats\(\))g FN(\(Stats)j(method\),)d(816)1992 3670 y FJ(print_tb\(\))g FN(\(in)i(module)f(traceback\),)f(840)1992 3769 y FJ(printable)h FN(\(data)g(in)i(string\),)e(48)1992 3869 y FJ(printdir\(\))f FN(\(ZipFile)i(method\),)f(349)1992 3968 y(printf-style)f(formatting,)g (32)1992 4068 y FJ(prmonth\(\))2158 4168 y FN(in)i(module)f(calendar)m (,)f(116)2158 4267 y(T)-6 b(e)o(xtCalendar)18 b(method,)h(114)1992 4367 y(process)2158 4467 y(group,)f(396,)h(397)2158 4566 y(id,)h(397)2158 4666 y(id)g(of)g(parent,)f(397)2158 4765 y(killing,)g(410)2158 4865 y(signalling,)g(410)1992 4965 y FJ(process_message\(\))e FN(\(SMTPServ)o(er)i(method\),)f(655) 1992 5064 y FJ(process_request\(\))f FN(\(in)j(module)f(Sock)o(etServ)o (er\),)f(667)1992 5164 y(processes,)h(light-weight,)g(536)1992 5264 y FJ(ProcessingInstruction\(\))206 b FN(\(in)k(module)2324 5363 y(xml.etree.ElementT)m(ree\),)16 b(299)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1011)p eop end %%Page: 1012 1024 TeXDict begin 1012 1023 bop 0 83 a FJ(processingInstruction\(\))201 b FN(\(ContentHandler)332 183 y(method\),)18 b(292)0 282 y FJ(ProcessingInstructionHandler\(\))49 b FN(\(xmlparser)332 382 y(method\),)18 b(267)0 482 y FJ(processor\(\))h FN(\(in)h(module)f (platform\),)f(492)0 581 y(processor)h(time,)h(417)0 681 y FJ(Profile)f FN(\(class)i(in)g(hotshot\),)d(819)0 780 y FJ(profile)h FN(\(standard)g(module\),)f FL(814)0 880 y FN(pro\002le)i(function,)e(539,)h(832)0 980 y(pro\002ler)m(,)g (832)0 1079 y(pro\002ling,)g(deterministic,)g(811)0 1179 y FJ(prompt)h FN(\(Cmd)g(attrib)n(ute\),)f(758)0 1279 y FJ(prompt_user_passwd\(\))288 b FN(\(F)o(anc)o(yURLopener)332 1378 y(method\),)18 b(621)0 1478 y(prompts,)h(interpreter)m(,)f(832)0 1577 y FJ(propagate)h FN(\(data)h(in)g(logging\),)e(454)0 1677 y FJ(property\(\))h FN(\(in)h(module)f(\),)h(11)0 1777 y FJ(property_declaration_handler)136 b FN(\(data)141 b(in)332 1876 y(xml.sax.handler\),)17 b(290)0 1976 y FJ(property_dom_node)h FN(\(data)h(in)i(xml.sax.handler\),)16 b(290)0 2076 y FJ(property_lexical_handler)237 b FN(\(data)j(in)332 2175 y(xml.sax.handler\),)17 b(290)0 2275 y FJ(property_xml_string)47 b FN(\(data)j(in)h(xml.sax.handler\),)332 2374 y(291)0 2474 y FJ(proto)20 b FN(\(sock)o(et)g(attrib)n(ute\),)f(584)0 2574 y(protocol)166 2673 y(CGI,)i(602)166 2773 y(conte)o(xt)e (management,)f(42)166 2873 y(FTP)-9 b(,)20 b(620,)f(636)166 2972 y(Gopher)m(,)f(620,)h(640)166 3072 y(HTTP)-9 b(,)20 b(602,)f(620,)g(632,)g(667)166 3171 y(IMAP4,)h(642)166 3271 y(IMAP4)p 421 3271 25 4 v 29 w(SSL,)h(642)166 3371 y(IMAP4)p 421 3371 V 29 w(stream,)f(642)166 3470 y(iterator)m(,)f(26) 166 3570 y(NNTP)-9 b(,)20 b(647)166 3670 y(POP3,)g(640)166 3769 y(SMTP)-9 b(,)20 b(651)166 3869 y(T)-6 b(elnet,)20 b(656)0 3968 y FJ(PROTOCOL_VERSION)e FN(\(IMAP4)p 1101 3968 V 28 w(stream)i(attrib)n(ute\),)g(647)0 4068 y FJ (protocol_version)43 b FN(\(BaseHTTPRequestHandler)h(at-)332 4168 y(trib)n(ute\),)19 b(669)0 4267 y FJ(proxy\(\))g FN(\(in)h(module)f(weakref\),)g(135)0 4367 y FJ(proxyauth\(\))g FN(\(IMAP4)p 852 4367 V 28 w(stream)h(method\),)f(645)0 4467 y FJ(ProxyBasicAuthHandler)e FN(\(class)k(in)f(urllib2\),)f(624)0 4566 y FJ(ProxyDigestAuthHandler)e FN(\(class)j(in)h(urllib2\),)d(624)0 4666 y FJ(ProxyHandler)h FN(\(class)h(in)h(urllib2\),)d(624)0 4765 y FJ(ProxyType)h FN(\(data)h(in)g(weakref\),)f(136)0 4865 y FJ(ProxyTypes)g FN(\(data)h(in)g(weakref\),)e(136)0 4965 y FJ(prstr\(\))h FN(\(in)h(module)f(fm\),)h(924)0 5064 y FJ(pryear\(\))f FN(\(T)-6 b(e)o(xtCalendar)18 b(method\),)h(115)0 5164 y FJ(ps1)h FN(\(data)g(in)g(sys\),)h(832)0 5264 y FJ(ps2)f FN(\(data)g(in)g(sys\),)h(832)0 5363 y FJ(pstats)f FN(\(standard)e(module\),)h FL(815)1992 83 y FN(pthreads,)f(537)1992 183 y FJ(ptime)h FN(\(data)h(in)g(cd\),)g (916)1992 282 y FJ(pty)g FN(\(standard)e(module\),)h(400,)g FL(560)1992 382 y FJ(publicId)g FN(\(DocumentT)-7 b(ype)17 b(attrib)n(ute\),)i(277)1992 482 y FJ(PullDOM)g FN(\(class)i(in)f (xml.dom.pulldom\),)15 b(287)1992 581 y FJ(punctuation)j FN(\(data)i(in)g(string\),)g(48)1992 681 y FJ(PureProxy)f FN(\(class)h(in)h(smtpd\),)e(656)1992 780 y FJ(push\(\))2158 880 y FN(async)p 2353 880 V 28 w(chat)i(method,)d(596)2158 980 y(\002fo)i(method,)e(597)2158 1079 y(Interacti)n(v)o(eConsole)f (method,)i(856)2158 1179 y(MultiFile)h(method,)f(246)1992 1279 y FJ(push_alignment\(\))e FN(\(formatter)i(method\),)f(910)1992 1378 y FJ(push_font\(\))g FN(\(formatter)h(method\),)f(910)1992 1478 y FJ(push_margin\(\))g FN(\(formatter)g(method\),)g(910)1992 1577 y FJ(push_source\(\))g FN(\(shle)o(x)h(method\),)f(760)1992 1677 y FJ(push_style\(\))g FN(\(formatter)g(method\),)h(910)1992 1777 y FJ(push_token\(\))f FN(\(shle)o(x)h(method\),)g(760)1992 1876 y FJ(push_with_producer\(\))e FN(\(async)p 3232 1876 V 28 w(chat)j(method\),)e(596)1992 1976 y FJ(pushbutton\(\))g FN(\(Dialog)h(method\),)g(938)1992 2076 y FJ(put\(\))g FN(\(Queue)g(method\),)g(133)1992 2175 y FJ(put_nowait\(\))f FN(\(Queue)h(method\),)f(133)1992 2275 y FJ(putch\(\))h FN(\(in)h(module)f(msvcrt\),)g(940)1992 2374 y FJ(putenv\(\))g FN(\(in)h(module)f(os\),)h(397)1992 2474 y FJ(putheader\(\))e FN(\(HTTPResponse)h(method\),)g(635)1992 2574 y FJ(putp\(\))g FN(\(in)h(module)f(curses\),)h(476)1992 2673 y FJ(putrequest\(\))e FN(\(HTTPResponse)h(method\),)f(635)1992 2773 y FJ(putsequences\(\))g FN(\(F)o(older)h(method\),)f(239)1992 2873 y FJ(putwin\(\))h FN(\(windo)n(w)g(method\),)f(482)1992 2972 y FJ(pwd\(\))h FN(\(FTP)i(method\),)d(639)1992 3072 y FJ(pwd)i FN(\(b)n(uilt-in)f (module\),)f(326,)h FL(554)1992 3171 y FJ(pwlcurve\(\))f FN(\(in)i(module)f(gl\),)h(926)1992 3271 y FJ(py_compile)e FN(\(standard)h(module\),)f FL(887)1992 3371 y FJ(PY_COMPILED)g FN(\(data)i(in)g(imp\),)g(866)1992 3470 y FJ(PY_FROZEN)f FN(\(data)g(in)i(imp\),)e(867)1992 3570 y FJ(py_object)g FN(\(class)h(in)h(ctypes\),)e(532)1992 3670 y FJ(PY_RESOURCE)f FN(\(data)i(in)g(imp\),)g(866)1992 3769 y FJ(PY_SOURCE)f FN(\(data)g(in)i(imp\),)e(866)1992 3869 y FJ(pyclbr)g FN(\(standard)g(module\),)f FL(886)1992 3968 y FJ(PyCompileError)g FN(\(e)o(xception)g(in)i(p)o(y)p 3253 3968 V 29 w(compile\),)f(887)1992 4068 y FJ(PyDLL)g FN(\(class)i(in)f(ctypes\),)g(524)1992 4168 y FJ(pydoc)f FN(\(standard)g(module\),)f FL(763)1992 4267 y FJ(pyexpat)h FN(\(b)n(uilt-in)g(module\),)f(264)1992 4367 y FJ(PYFUNCTYPE\(\))g FN(\(in)i(module)f(ctypes\),)g(526)1992 4467 y(PyOpenGL,)f(927)1992 4566 y(Python)h(Editor)m(,)f(733)1992 4666 y(Python)h(Enhancement)e(Proposals)2158 4765 y(PEP)j(0205,)f(136) 2158 4865 y(PEP)h(0273,)f(869)2158 4965 y(PEP)h(0302,)f(869)2158 5064 y(PEP)h(0343,)f(839)2158 5164 y(PEP)h(236,)f(5)2158 5264 y(PEP)h(246,)f(391)2158 5363 y(PEP)h(249,)f(383,)g(385)p 0 5549 3901 4 v 0 5649 a FI(1012)3515 b(Inde)n(x)p eop end %%Page: 1013 1025 TeXDict begin 1013 1024 bop 166 83 a FN(PEP)21 b(282,)e(453)166 183 y(PEP)i(292,)e(48)166 282 y(PEP)i(302,)e(338,)g(867)166 382 y(PEP)i(305,)e(303)166 482 y(PEP)i(333,)e(610\226614,)e(616)166 581 y(PEP)k(338,)e(872)166 681 y(PEP)i(8,)f(210)0 780 y(Python)f(Imaging)g(Library)-5 b(,)18 b(928)0 880 y FJ(python_build\(\))g FN(\(in)i(module)f(platform\),)f(493)0 980 y FJ(python_compiler\(\))g FN(\(in)i(module)e(platform\),)g(493)0 1079 y(PYTHON)p 342 1079 25 4 v 30 w(DOM,)i(273)0 1179 y FJ(python_version\(\))e FN(\(in)i(module)f(platform\),)f(493)0 1279 y FJ(python_version_tuple\(\))42 b FN(\(in)i(module)g(platform\),) 332 1378 y(493)0 1478 y(PYTHONDOCS,)21 b(764)0 1577 y(PYTHONP)-8 b(A)f(TH,)20 b(607,)f(831)0 1677 y(PYTHONST)-8 b(AR)j(TUP)c(,)20 b(550,)f(551,)g(851)0 1777 y(PYTHONY2K,)h(415,)f(416)0 1876 y FJ(PyZipFile)g FN(\(class)i(in)f(zip\002le\),)g(348)0 2074 y FE(Q)0 2197 y FJ(qdevice\(\))f FN(\(in)h(module)f(\003\),)h(920) 0 2297 y FJ(qenter\(\))f FN(\(in)h(module)f(\003\),)h(920)0 2396 y FJ(qiflush\(\))f FN(\(in)h(module)f(curses\),)h(476)0 2496 y FJ(QName)g FN(\(class)h(in)f(xml.etree.ElementT)m(ree\),)c(301)0 2595 y FJ(qread\(\))j FN(\(in)h(module)f(\003\),)i(920)0 2695 y FJ(qreset\(\))e FN(\(in)h(module)f(\003\),)h(920)0 2795 y FJ(qsize\(\))f FN(\(Queue)h(method\),)e(133)0 2894 y FJ(qtest\(\))h FN(\(in)h(module)f(\003\),)i(920)0 2994 y FJ(quantize\(\))166 3094 y FN(Conte)o(xt)e(method,)g(161)166 3193 y(Decimal)h(method,)f(158)0 3293 y FJ(QueryInfoKey\(\))f FN(\(in)i(module)p 1106 3293 V 49 w(winre)o(g\),)e(943)0 3392 y FJ(queryparams\(\))g FN(\(in)i(module)f(al\),)h(913)0 3492 y FJ(QueryValue\(\))f FN(\(in)h(module)p 1006 3492 V 48 w(winre)o(g\),)f(943)0 3592 y FJ(QueryValueEx\(\))f FN(\(in)i(module)p 1106 3592 V 49 w(winre)o(g\),)e(943)0 3691 y FJ(Queue)166 3791 y FN(class)j(in)g(Queue,)e(133)166 3891 y(standard)g(module,)g FL(133)0 3990 y FJ(quick_ratio\(\))f FN(\(SequenceMatcher)f(method\),)i(71)0 4090 y FJ(quit\(\))166 4189 y FN(FTP)i(method,)d(639)166 4289 y(NNTP)j(method,)d(651)166 4389 y(POP3)p 365 4389 V 30 w(SSL)j(method,)d(641)166 4488 y(SMTP)j(method,)d(654)0 4588 y FJ(quopri)i FN(\(standard)e (module\),)h FL(255)0 4688 y FJ(quote\(\))166 4787 y FN(in)h(module)f(email.utils,)h(207)166 4887 y(in)g(module)f(rfc822,)f (248)166 4986 y(in)i(module)f(urllib,)h(619)0 5086 y FJ(QUOTE_ALL)f FN(\(data)h(in)g(csv\),)g(305)0 5186 y FJ(QUOTE_MINIMAL)e FN(\(data)i(in)g(csv\),)g(305)0 5285 y FJ(QUOTE_NONE)f FN(\(data)h(in)g(csv\),)g(305)0 5385 y FJ(QUOTE_NONNUMERIC)e FN(\(data)h(in)i(csv\),)f(305)1992 83 y FJ(quote_plus\(\))e FN(\(in)i(module)f(urllib\),)g(619)1992 183 y FJ(quoteattr\(\))f FN(\(in)i(module)f(xml.sax.saxutils\),)f(294) 1992 282 y FJ(quotechar)h FN(\(Dialect)h(attrib)n(ute\),)f(306)1992 382 y(quoted-printable)2158 482 y(encoding,)e(255)1992 581 y FJ(quotes)i FN(\(shle)o(x)h(attrib)n(ute\),)f(761)1992 681 y FJ(quoting)g FN(\(Dialect)h(attrib)n(ute\),)f(306)1992 873 y FE(R)1992 996 y FJ(r_eval\(\))g FN(\(REx)o(ec)g(method\),)f(860) 1992 1096 y FJ(r_exec\(\))h FN(\(REx)o(ec)g(method\),)f(861)1992 1196 y FJ(r_execfile\(\))g FN(\(REx)o(ec)i(method\),)e(861)1992 1295 y FJ(r_import\(\))g FN(\(REx)o(ec)i(method\),)e(861)1992 1395 y FJ(R_OK)i FN(\(data)f(in)i(os\),)f(402)1992 1495 y FJ(r_open\(\))f FN(\(REx)o(ec)g(method\),)f(861)1992 1594 y FJ(r_reload\(\))g FN(\(REx)o(ec)i(method\),)e(861)1992 1694 y FJ(r_unload\(\))g FN(\(REx)o(ec)i(method\),)e(861)1992 1793 y FJ(radians\(\))2158 1893 y FN(in)i(module)f(math,)g(151)2158 1993 y(in)h(module)f(turtle,)g(730)1992 2092 y FJ(RadioButtonGroup)e FN(\(class)k(in)f(msilib\),)g(938)1992 2192 y FJ(radiogroup\(\))e FN(\(Dialog)h(method\),)g(938)1992 2292 y FJ(RADIXCHAR)g FN(\(data)g(in)i(locale\),)e(753)1992 2391 y FJ(raise)2158 2491 y FN(statement,)g(17)1992 2590 y FJ(randint\(\))g FN(\(in)h(module)e(random\),)g(170)1992 2690 y FJ(random\(\))h FN(\(in)h(module)f(random\),)e(170)1992 2790 y FJ(random)i FN(\(standard)g(module\),)f FL(169)1992 2889 y FJ(randrange\(\))g FN(\(in)i(module)f(random\),)f(170)1992 2989 y FJ(range\(\))h FN(\(in)h(module)f(\),)h(12)1992 3089 y FJ(ratecv\(\))f FN(\(in)h(module)f(audioop\),)e(695)1992 3188 y FJ(ratio\(\))i FN(\(SequenceMatcher)e(method\),)h(70)1992 3288 y FJ(raw\(\))h FN(\(in)h(module)f(curses\),)h(476)1992 3387 y FJ(raw_input\(\))2158 3487 y FN(b)n(uilt-in)f(function,)f(833)2158 3587 y(in)i(module)f(,)h (12)2158 3686 y(Interacti)n(v)o(eConsole)d(method,)i(857)1992 3786 y FJ(RawConfigParser)e FN(\(class)k(in)g(Con\002gP)o(arser\),)d (310)1992 3886 y FJ(RawPen)h FN(\(class)i(in)f(turtle\),)g(732)1992 3985 y FJ(re)2158 4085 y FN(MatchObject)f(attrib)n(ute,)g(61)2158 4185 y(standard)g(module,)f(34,)i(47,)f FL(52)p FN(,)h(337)1992 4284 y FJ(read\(\))2178 4384 y FN(method,)f(548,)g(584)2158 4483 y(array)g(method,)f(127)2158 4583 y(audio)h(de)n(vice)g(method,)g (708,)g(932)2158 4683 y(BZ2File)h(method,)f(347)2158 4782 y(Chunk)g(method,)f(704)2158 4882 y(\002le)i(method,)f(40)2158 4982 y(HTTPResponse)g(method,)g(635)2158 5081 y(IMAP4)p 2413 5081 V 29 w(stream)h(method,)e(645)2158 5181 y(in)i(module)f (img\002le,)h(928)2158 5280 y(in)g(module)f(os,)h(401)2158 5380 y(MimeT)-7 b(ypes)19 b(method,)f(243)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1013)p eop end %%Page: 1014 1026 TeXDict begin 1014 1025 bop 166 83 a FN(MultiFile)21 b(method,)d(246)166 183 y(RobotFileP)o(arser)h(method,)g(313)166 282 y(SafeCon\002gP)o(arser)g(method,)f(311)166 382 y(StreamReader)h (method,)g(84)166 482 y(ZipFile)h(method,)f(349)0 581 y FJ(read_all\(\))g FN(\(T)-6 b(elnet)20 b(method\),)e(656)0 681 y FJ(read_byte\(\))h FN(\()h(method\),)e(548)0 780 y FJ(read_eager\(\))h FN(\(T)-6 b(elnet)19 b(method\),)f(657)0 880 y FJ(read_history_file\(\))f FN(\(in)j(module)f(readline\),)g(549)0 980 y FJ(read_init_file\(\))f FN(\(in)i(module)f(readline\),)f(549)0 1079 y FJ(read_lazy\(\))h FN(\(T)-6 b(elnet)19 b(method\),)g(657)0 1179 y FJ(read_mime_types\(\))f FN(\(in)i(module)e(mimetypes\),)h(241)0 1279 y FJ(read_sb_data\(\))f FN(\(T)-6 b(elnet)20 b(method\),)e(657)0 1378 y FJ(read_some\(\))h FN(\(T)-6 b(elnet)19 b(method\),)g(657)0 1478 y FJ(read_token\(\))g FN(\(shle)o(x)g(method\),)f(760)0 1577 y FJ(read_until\(\))h FN(\(T)-6 b(elnet)19 b(method\),)f(656)0 1677 y FJ(read_very_eager\(\))g FN(\(T)-6 b(elnet)19 b(method\),)g(657)0 1777 y FJ(read_very_lazy\(\))f FN(\(T)-6 b(elnet)19 b(method\),)g(657)0 1876 y FJ(readable\(\))166 1976 y FN(async)p 361 1976 25 4 v 29 w(chat)h(method,)f(596)166 2076 y(dispatcher)g(method,)g(593)0 2175 y FJ(readda\(\))g FN(\(CD)i(player)e(method\),)f(917)0 2275 y FJ(reader\(\))h FN(\(in)h(module)f(csv\),)h(303)0 2374 y FJ(ReadError)f FN(\(e)o(xception)f(in)i(tar\002le\),)g(353)0 2474 y FJ(readfp\(\))166 2574 y FN(MimeT)-7 b(ypes)19 b(method,)g(243)166 2673 y(SafeCon\002gP)o(arser)g(method,)f(312)0 2773 y FJ(readframes\(\))166 2873 y FN(aifc)i(method,)f(698)166 2972 y(A)-5 b(U)p 286 2972 V 30 w(read)20 b(method,)e(701)166 3072 y(W)-7 b(a)n(v)o(e)p 355 3072 V 30 w(read)20 b(method,)e(703)0 3171 y FJ(readline\(\))187 3271 y FN(method,)g(548)166 3371 y(BZ2File)j(method,)d(347)166 3470 y(\002le)j(method,)d(40)166 3570 y(IMAP4)p 421 3570 V 29 w(stream)i(method,)f(645)166 3670 y(MultiFile)i(method,)d(245)166 3769 y(StreamReader)h(method,)g (84)0 3869 y FJ(readline)g FN(\(b)n(uilt-in)g(module\),)g FL(549)0 3968 y FJ(readlines\(\))166 4068 y FN(BZ2File)i(method,)d(347) 166 4168 y(\002le)j(method,)d(40)166 4267 y(MultiFile)j(method,)d(245) 166 4367 y(StreamReader)h(method,)g(84)0 4467 y FJ(readlink\(\))g FN(\(in)h(module)f(os\),)h(404)0 4566 y FJ(readmodule\(\))f FN(\(in)h(module)e(p)o(yclbr\),)h(886)0 4666 y FJ(readmodule_ex\(\))f FN(\(in)i(module)f(p)o(yclbr\),)f(886)0 4765 y FJ(readsamps\(\))h FN(\(audio)g(port)g(method\),)f(914)0 4865 y FJ(readscaled\(\))h FN(\(in)h(module)e(img\002le\),)i(928)0 4965 y FJ(READY)g FN(\(data)g(in)g(cd\),)f(916)0 5064 y(Real)i(Media)f(File)h(F)o(ormat,) e(704)0 5164 y FJ(real_quick_ratio\(\))43 b FN(\(SequenceMatcher)f (method\),)332 5264 y(71)0 5363 y FJ(realpath\(\))19 b FN(\(in)h(module)f(os.path\),)f(327)1992 83 y FJ(reason)h FN(\(data)h(in)g(httplib\),)f(636)1992 183 y FJ(reccontrols\(\))f FN(\(mix)o(er)h(de)n(vice)g(method\),)f(711)1992 282 y FJ(recent\(\))h FN(\(IMAP4)p 2694 282 V 28 w(stream)h(method\),)f (645)1992 382 y FJ(rectangle\(\))f FN(\(in)i(module)f(curses.te)o (xtpad\),)f(487)1992 482 y FJ(recv\(\))2158 581 y FN(dispatcher)h (method,)f(594)2158 681 y(sock)o(et)i(method,)e(582)1992 780 y FJ(recv_into\(\))g FN(\(sock)o(et)i(method\),)e(583)1992 880 y FJ(recvfrom\(\))g FN(\(sock)o(et)i(method\),)e(582)1992 980 y FJ(recvfrom_into\(\))f FN(\(sock)o(et)j(method\),)e(583)1992 1079 y FJ(redirect_request\(\))224 b FN(\(HTTPRedirectHandler)2324 1179 y(method\),)18 b(628)1992 1279 y FJ(redisplay\(\))g FN(\(in)i(module)f(readline\),)g(549)1992 1378 y FJ(redraw_form\(\))f FN(\(form)h(method\),)f(920)1992 1478 y FJ(redraw_object\(\))f FN(\(FORMS)k(object)f(method\),)e(923)1992 1577 y FJ(redrawln\(\))g FN(\(windo)n(w)h(method\),)f(482)1992 1677 y FJ(redrawwin\(\))g FN(\(windo)n(w)h(method\),)f(482)1992 1777 y FJ(reduce\(\))h FN(\(in)h(module)f(\),)h(12)1992 1876 y FJ(ref)g FN(\(class)g(in)h (weakref\),)d(135)1992 1976 y FJ(ReferenceError)2158 2076 y FN(e)o(xception)g(in)i(e)o(xceptions,)f(20)2158 2175 y(e)o(xception)f(in)i(weakref,)f(136)1992 2275 y FJ(ReferenceType)f FN(\(data)i(in)g(weakref\),)e(136)1992 2374 y FJ(refilemessages\(\))f FN(\(F)o(older)i(method\),)f(239)1992 2474 y FJ(refill_buffer\(\))f FN(\(async)p 2982 2474 V 29 w(chat)j(method\),)e(597)1992 2574 y FJ(refresh\(\))h FN(\(windo)n(w)f(method\),)h(482)1992 2673 y FJ(register\(\))2178 2773 y FN(method,)g(536)2158 2873 y(in)h(module)f(ate)o(xit,)g(839)2158 2972 y(in)h(module)f(codecs,)g(77)2158 3072 y(in)h(module)f(webbro)n (wser)m(,)f(600)1992 3171 y FJ(register_adapter\(\))f FN(\(in)j(module)f(sqlite3\),)g(386)1992 3271 y FJ (register_converter\(\))e FN(\(in)j(module)e(sqlite3\),)i(386)1992 3371 y FJ(register_dialect\(\))d FN(\(in)j(module)f(csv\),)h(304)1992 3470 y FJ(register_error\(\))d FN(\(in)j(module)f(codecs\),)g(79)1992 3570 y FJ(register_function\(\))2158 3670 y FN (SimpleXMLRPCRequestHandler)f(method,)g(690)2158 3769 y(SimpleXMLRPCServ)o(er)g(method,)h(689)1992 3869 y FJ (register_instance\(\))2158 3968 y FN(SimpleXMLRPCRequestHandler)f (method,)g(690)2158 4068 y(SimpleXMLRPCServ)o(er)g(method,)h(689)1992 4168 y FJ(register_introspection_functions\()o(\))h FN(\(Sim-)2324 4267 y(pleXMLRPCRequestHandler)14 b(method\),)i(689)f(691)1992 4367 y FJ(register_multicall_functions\(\))219 b FN(\(Sim-)2324 4467 y(pleXMLRPCRequestHandler)69 b(method\),)82 b(689,)2324 4566 y(691)1992 4666 y FJ(register_optionflag\(\))16 b FN(\(in)k(module)f(doctest\),)h(775)1992 4765 y FJ (registerDOMImplementation\(\))106 b FN(\(in)k(module)2324 4865 y(xml.dom\),)17 b(273)1992 4965 y FJ(RegLoadKey\(\))h FN(\(in)i(module)p 2998 4965 V 49 w(winre)o(g\),)e(942)1992 5064 y(relati)n(v)o(e)2158 5164 y(URL,)i(661)1992 5264 y FJ(release\(\))2178 5363 y FN(method,)f(461)p 0 5549 3901 4 v 0 5649 a FI(1014)3515 b(Inde)n(x)p eop end %%Page: 1015 1027 TeXDict begin 1015 1026 bop 166 83 a FN(Condition)19 b(method,)g(542)166 183 y(in)h(module)f(platform,)g(493)166 282 y(lock)h(method,)e(537)166 382 y(Semaphore)g(method,)h(543)166 482 y(T)m(imer)h(method,)e(540,)h(541)0 581 y FJ(release_lock\(\))f FN(\(in)i(module)f(imp\),)g(866)0 681 y FJ(reload\(\))166 780 y FN(b)n(uilt-in)h(function,)e(831,)h(866,)g(868)166 880 y(in)h(module)f(,)i(13)0 980 y FJ(remainder\(\))e FN(\(Conte)o(xt)g(method\),)f(161)0 1079 y FJ(remainder_near\(\))166 1179 y FN(Conte)o(xt)h(method,)g(162)166 1279 y(Decimal)h(method,)f (158)0 1378 y FJ(remove\(\))187 1478 y FN(method,)f(117)166 1577 y(array)h(method,)g(127)166 1677 y(in)h(module)f(os,)i(405)166 1777 y(list)g(method,)e(35)166 1876 y(Mailbox)g(method,)g(219)166 1976 y(MH)i(method,)d(224)0 2076 y FJ(remove_flag\(\))166 2175 y FN(MaildirMessage)h(method,)g(227)166 2275 y(mboxMessage)f (method,)h(229)166 2374 y(MMDFMessage)h(method,)f(233)0 2474 y FJ(remove_folder\(\))166 2574 y FN(Maildir)h(method,)e(222)166 2673 y(MH)j(method,)d(224)0 2773 y FJ(remove_history_item\(\))e FN(\(in)k(module)e(readline\),)g(549)0 2873 y FJ(remove_label\(\))g FN(\(BabylMessage)h(method\),)g(231)0 2972 y FJ(remove_option\(\))f FN(\(SafeCon\002gP)o(arser)g(method\),)g(312)0 3072 y FJ(remove_pyc\(\))h FN(\(Directory)f(method\),)g(937)0 3171 y FJ(remove_section\(\))g FN(\(SafeCon\002gP)o(arser)g(method\),)g (312)0 3271 y FJ(remove_sequence\(\))g FN(\(MHMessage)h(method\),)f (230)0 3371 y FJ(removeAttribute\(\))g FN(\(Element)h(method\),)f(278)0 3470 y FJ(removeAttributeNode\(\))f FN(\(Element)i(method\),)f(278)0 3570 y FJ(removeAttributeNS\(\))f FN(\(Element)i(method\),)g(278)0 3670 y FJ(removecallback\(\))f FN(\(CD)i(parser)g(method\),)e(918)0 3769 y FJ(removeChild\(\))g FN(\(Node)i(method\),)e(276)0 3869 y FJ(removedirs\(\))h FN(\(in)h(module)e(os\),)i(405)0 3968 y FJ(removeFilter\(\))e FN(\()j(method\),)d(455,)h(461)0 4068 y FJ(removeHandler\(\))f FN(\()i(method\),)f(455)0 4168 y FJ(removemessages\(\))f FN(\(F)o(older)h(method\),)f(239)0 4267 y FJ(rename\(\))166 4367 y FN(FTP)j(method,)d(639)166 4467 y(IMAP4)p 421 4467 25 4 v 29 w(stream)i(method,)f(645)166 4566 y(in)h(module)f(os,)i(405)0 4666 y FJ(renames\(\))e FN(\(in)h(module)f(os\),)h(405)0 4765 y FJ(reorganize\(\))f FN(\(in)h(module)e(gdbm\),)h(378)0 4865 y FJ(repeat\(\))166 4965 y FN(in)h(module)f(itertools,)h(177)166 5064 y(in)g(module)f (operator)m(,)f(185)166 5164 y(T)m(imer)i(method,)e(821)0 5264 y(repetition)166 5363 y(operation,)g(28)1992 83 y FJ(replace\(\))2178 183 y FN(method,)h(491)2158 282 y(date)h(method,)e(100)2158 382 y(datetime)h(method,)g(104)2158 482 y(in)h(module)f(string,)g(52)2158 581 y(string)g(method,)g(30)2158 681 y(time)h(method,)e(107)1992 780 y FJ(replace_errors\(\))f FN(\(in)j(module)f(codecs\),)g(79)1992 880 y FJ(replace_header\(\))e FN(\(Message)j(method\),)e(193)1992 980 y FJ(replace_history_item\(\)) 47 b FN(\(in)k(module)f(readline\),)2324 1079 y(549)1992 1179 y FJ(replace_whitespace)17 b FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(77)1992 1279 y FJ(replaceChild\(\))f FN(\(Node)h(method\),)f(276)1992 1378 y FJ(ReplacePackage\(\))f FN(\(in)j(module)f(module\002nder\),)e(871)1992 1478 y FJ(report\(\))2158 1577 y FN(dircmp)i(method,)f(333)2158 1677 y(ModuleFinder)f(method,)i(871)1992 1777 y FJ(REPORT_CDIFF)f FN(\(data)i(in)g(doctest\),)f(773)1992 1876 y FJ(report_failure\(\))e FN(\(DocT)-6 b(estRunner)19 b(method\),)f(784)1992 1976 y FJ(report_full_closure\(\))e FN(\(dircmp)j(method\),)f(334)1992 2076 y FJ(REPORT_NDIFF)g FN(\(data)i(in)g(doctest\),)f(773)1992 2175 y FJ(REPORT_ONLY_FIRST_FAILURE)44 b FN(\(data)49 b(in)g(doctest\),)2324 2275 y(773)1992 2374 y FJ (report_partial_closure\(\))71 b FN(\(dircmp)k(method\),)2324 2474 y(333)1992 2574 y FJ(report_start\(\))18 b FN(\(DocT)-6 b(estRunner)18 b(method\),)g(784)1992 2673 y FJ(report_success\(\))f FN(\(DocT)-6 b(estRunner)19 b(method\),)f(784)1992 2773 y FJ(REPORT_UDIFF)g FN(\(data)i(in)g(doctest\),)f(773)1992 2873 y FJ(report_unbalanced\(\))e FN(\(SGMLP)o(arser)i(method\),)f(261) 1992 2972 y FJ(report_unexpected_exception\(\))2324 3072 y FN(\(DocT)-6 b(estRunner)18 b(method\),)g(784)1992 3171 y FJ(REPORTING_FLAGS)f FN(\(data)j(in)h(doctest\),)e(774)1992 3271 y FJ(Repr)h FN(\(class)g(in)h(repr\),)d(147)1992 3371 y FJ(repr\(\))2158 3470 y FN(in)i(module)f(,)h(13)2158 3570 y(in)g(module)f(repr)m(,)g(147)2158 3670 y(Repr)h(method,)e(148) 1992 3769 y FJ(repr)i FN(\(standard)e(module\),)g FL(147)1992 3869 y FJ(repr1\(\))h FN(\(Repr)h(method\),)e(148)1992 3968 y FJ(Request)h FN(\(class)i(in)f(urllib2\),)f(623)1992 4068 y FJ(request\(\))g FN(\(HTTPResponse)g(method\),)f(635)1992 4168 y FJ(request_queue_size)f FN(\(data)j(in)g(Sock)o(etServ)o(er\),)e (666)1992 4267 y FJ(request_uri\(\))g FN(\(in)i(module)f (wsgiref.util\),)f(610)1992 4367 y FJ(request_version)68 b FN(\(BaseHTTPRequestHandler)g(at-)2324 4467 y(trib)n(ute\),)19 b(668)1992 4566 y FJ(RequestHandlerClass)e FN(\(data)i(in)i(Sock)o (etServ)o(er\),)d(666)1992 4666 y FJ(requires\(\))g FN(\(in)i(module)f (test.test)p 3149 4666 V 30 w(support\),)g(804)1992 4765 y FJ(reserved)g FN(\(ZipInfo)f(attrib)n(ute\),)h(351)1992 4865 y FJ(RESERVED_FUTURE)e FN(\(data)j(in)h(uuid\),)d(660)1992 4965 y FJ(RESERVED_MICROSOFT)f FN(\(data)j(in)g(uuid\),)f(660)1992 5064 y FJ(RESERVED_NCS)f FN(\(data)i(in)g(uuid\),)f(660)1992 5164 y FJ(reset\(\))2158 5264 y FN(audio)g(de)n(vice)g(method,)g(709) 2158 5363 y(DOMEv)o(entStream)f(method,)g(287)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1015)p eop end %%Page: 1016 1028 TeXDict begin 1016 1027 bop 166 83 a FN(HTMLP)o(arser)19 b(method,)g(258)166 183 y(in)h(module)f(dircache,)g(340)166 282 y(in)h(module)f(turtle,)h(731)166 382 y(IncrementalDecoder)d (method,)h(82)166 482 y(IncrementalEncoder)e(method,)j(82)166 581 y(IncrementalP)o(arser)f(method,)g(296)166 681 y(P)o(ack)o(er)i (method,)e(315)166 780 y(SGMLP)o(arser)i(method,)e(260)166 880 y(StreamReader)h(method,)g(84)166 980 y(StreamWriter)h(method,)e (83)166 1079 y(T)-6 b(emplate)20 b(method,)e(563)166 1179 y(Unpack)o(er)h(method,)f(316)0 1279 y FJ(reset_prog_mode\(\))g FN(\(in)i(module)e(curses\),)i(477)0 1378 y FJ(reset_shell_mode\(\))d FN(\(in)j(module)f(curses\),)h(477)0 1478 y FJ(resetbuffer\(\))e FN(\(Interacti)n(v)o(eConsole)g(method\),)g(857)0 1577 y FJ(resetlocale\(\))g FN(\(in)i(module)f(locale\),)h(751)0 1677 y FJ(resetparser\(\))e FN(\(CD)j(parser)f(method\),)e(918)0 1777 y FJ(resetwarnings\(\))g FN(\(in)i(module)f(w)o(arnings\),)f(837)0 1876 y FJ(resize\(\))187 1976 y FN(method,)g(548)166 2076 y(in)i(module)f(ctypes,)h(529)0 2175 y FJ(resolution)166 2275 y FN(date)g(attrib)n(ute,)g(99)166 2374 y(datetime)g(attrib)n (ute,)f(102)166 2474 y(time)h(attrib)n(ute,)g(106)166 2574 y(timedelta)g(attrib)n(ute,)f(97)0 2673 y FJ(resolveEntity\(\))f FN(\(EntityResolv)o(er)g(method\),)g(293)0 2773 y FJ(resource)h FN(\(b)n(uilt-in)g(module\),)g FL(565)0 2873 y FJ(ResourceDenied)f FN(\(e)o(xception)g(in)i(test.test)p 1429 2873 25 4 v 31 w(support\),)e(804)0 2972 y FJ(response\(\))h FN(\(IMAP4)p 802 2972 V 28 w(stream)i(method\),)d(645)0 3072 y FJ(ResponseNotReady)g FN(\(e)o(xception)g(in)i(httplib\),)f(633)0 3171 y FJ(responses)166 3271 y FN(BaseHTTPRequestHandler)g(attrib)n(ute,)g(669)166 3371 y(data)h(in)g(httplib,)g(634)0 3470 y FJ(restore\(\))f FN(\(in)h(module)f(dif)n(\003ib\),)g(68)0 3570 y FJ(restype)g FN(\()p 402 3570 V 30 w(FuncPtr)h(attrib)n(ute\),)f(525)0 3670 y FJ(retr\(\))h FN(\(POP3)p 547 3670 V 29 w(SSL)h(method\),)d(641) 0 3769 y FJ(retrbinary\(\))h FN(\(FTP)h(method\),)e(638)0 3869 y FJ(retrieve\(\))h FN(\(URLopener)f(method\),)g(621)0 3968 y FJ(retrlines\(\))h FN(\(FTP)h(method\),)e(638)0 4068 y FJ(return_ok\(\))h FN(\(CookiePolic)o(y)f(method\),)g(675)0 4168 y FJ(returncode)h FN(\(Popen)g(attrib)n(ute\),)g(574)0 4267 y FJ(returns_unicode)f FN(\(xmlparser)g(attrib)n(ute\),)i(266)0 4367 y FJ(reverse\(\))166 4467 y FN(array)f(method,)g(127)166 4566 y(in)h(module)f(audioop,)f(695)166 4666 y(list)j(method,)e(35)0 4765 y FJ(reverse_order\(\))f FN(\(Stats)j(method\),)d(816)0 4865 y FJ(reversed\(\))h FN(\(in)h(module)f(\),)h(13)0 4965 y FJ(revert\(\))f FN(\(FileCookieJar)g(method\),)g(674)0 5064 y FJ(rewind\(\))166 5164 y FN(aifc)h(method,)f(698)166 5264 y(A)-5 b(U)p 286 5264 V 30 w(read)20 b(method,)e(701)166 5363 y(W)-7 b(a)n(v)o(e)p 355 5363 V 30 w(read)20 b(method,)e(703)1992 83 y FJ(rewindbody\(\))g FN(\(AddressList)i(method\),)e(249)1992 183 y FJ(RExec)h FN(\(class)i(in)f(re)o(x)o(ec\),)f(860)1992 282 y FJ(rexec)g FN(\(standard)g(module\),)f(3,)i FL(860)1992 382 y FN(RFC)2158 482 y(RFC)h(1014,)e(315)2158 581 y(RFC)i(1321,)e (319,)g(321)2158 681 y(RFC)i(1521,)e(253,)g(255)2158 780 y(RFC)i(1522,)e(255)2158 880 y(RFC)i(1524,)e(218)2158 980 y(RFC)i(1725,)e(640)2158 1079 y(RFC)i(1730,)e(642)2158 1179 y(RFC)i(1738,)e(663)2158 1279 y(RFC)i(1766,)e(750,)g(751)2158 1378 y(RFC)i(1808,)e(663)2158 1478 y(RFC)i(1832,)e(315)2158 1577 y(RFC)i(1866,)e(262)2158 1677 y(RFC)i(1869,)e(651,)g(652)2158 1777 y(RFC)i(1894,)e(213)2158 1876 y(RFC)i(2045,)e(189,)g(193,)g(194,)g (201,)g(246)2158 1976 y(RFC)i(2046,)e(189,)g(201)2158 2076 y(RFC)i(2047,)e(189,)g(201\226203)2158 2175 y(RFC)i(2060,)e(642,)g (646)2158 2275 y(RFC)i(2068,)e(680)2158 2374 y(RFC)i(2104,)e(321)2158 2474 y(RFC)i(2109,)e(672,)g(673,)g(680,)g(681)2158 2574 y(RFC)i(2231,)e(189,)g(194,)g(201,)g(209,)g(210)2158 2673 y(RFC)i(2396,)e(662,)g(663)2158 2773 y(RFC)i(2553,)e(577)2158 2873 y(RFC)i(2616,)e(611,)g(620,)g(627,)g(628)2158 2972 y(RFC)i(2774,)e(634)2158 3072 y(RFC)i(2817,)e(634)2158 3171 y(RFC)i(2821,)e(189)2158 3271 y(RFC)29 b(2822,)g(189\226191,)f (197\226199,)f(201\226203,)h(207\226209,)2324 3371 y(226,)19 b(247\226249,)e(418,)i(655)2158 3470 y(RFC)i(2964,)e(673)2158 3570 y(RFC)i(2965,)e(623,)g(625,)g(672,)g(673)2158 3670 y(RFC)i(3229,)e(634)2158 3769 y(RFC)i(3454,)e(92)2158 3869 y(RFC)i(3490,)e(89)2158 3968 y(RFC)i(3492,)e(89)2158 4068 y(RFC)i(3548,)e(251,)g(252)2158 4168 y(RFC)i(4122,)e(658,)g(660) 2158 4267 y(RFC)i(821,)e(651,)g(652)2158 4367 y(RFC)i(822,)e(201,)g (247,)g(310,)g(418,)g(635,)g(653,)h(654,)f(743)2158 4467 y(RFC)i(854,)e(656)2158 4566 y(RFC)i(959,)e(636)2158 4666 y(RFC)i(977,)e(647)1992 4765 y FJ(rfc2109)g FN(\(Cookie)g(attrib)n (ute\),)g(678)1992 4865 y FJ(rfc2109_as_netscape)49 b FN(\(L)-6 b(WPCookieJar)51 b(attrib)n(ute\),)2324 4965 y(677)1992 5064 y FJ(rfc2965)19 b FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)g(676)1992 5164 y FJ(rfc822)g FN(\(standard)g (module\),)f(239,)h FL(247)1992 5264 y FJ(RFC_4122)g FN(\(data)g(in)i(uuid\),)e(660)1992 5363 y FJ(rfile)g FN(\(BaseHTTPRequestHandler)g(attrib)n(ute\),)g(668)p 0 5549 3901 4 v 0 5649 a FI(1016)3515 b(Inde)n(x)p eop end %%Page: 1017 1029 TeXDict begin 1017 1028 bop 0 83 a FJ(rfind\(\))166 183 y FN(in)20 b(module)f(string,)h(51)166 282 y(string)g(method,)e(31)0 382 y FJ(rgb_to_hls\(\))h FN(\(in)h(module)e(colorsys\),)h(705)0 482 y FJ(rgb_to_hsv\(\))g FN(\(in)h(module)e(colorsys\),)h(705)0 581 y FJ(rgb_to_yiq\(\))g FN(\(in)h(module)e(colorsys\),)h(705)0 681 y FJ(rgbimg)h FN(\(b)n(uilt-in)f(module\),)f FL(705)0 780 y FJ(right\(\))h FN(\(in)h(module)f(turtle\),)h(731)0 880 y FJ(right_list)f FN(\(dircmp)f(attrib)n(ute\),)i(334)0 980 y FJ(right_only)f FN(\(dircmp)f(attrib)n(ute\),)i(334)0 1079 y FJ(rindex\(\))166 1179 y FN(in)g(module)f(string,)h(51)166 1279 y(string)g(method,)e(31)0 1378 y FJ(rjust\(\))166 1478 y FN(in)i(module)f(string,)h(52)166 1577 y(string)g(method,)e(31)0 1677 y FJ(rlcompleter)h FN(\(standard)f(module\),)h FL(551)0 1777 y FJ(rlecode_hqx\(\))f FN(\(in)i(module)f(binascii\),)h(254)0 1876 y FJ(rledecode_hqx\(\))e FN(\(in)i(module)f(binascii\),)g(254)0 1976 y FJ(RLIMIT_AS)g FN(\(data)h(in)g(resource\),)e(566)0 2076 y FJ(RLIMIT_CORE)h FN(\(data)g(in)i(resource\),)d(566)0 2175 y FJ(RLIMIT_CPU)h FN(\(data)h(in)g(resource\),)e(566)0 2275 y FJ(RLIMIT_DATA)h FN(\(data)g(in)i(resource\),)d(566)0 2374 y FJ(RLIMIT_FSIZE)h FN(\(data)g(in)i(resource\),)d(566)0 2474 y FJ(RLIMIT_MEMLOCK)g FN(\(data)i(in)g(resource\),)f(566)0 2574 y FJ(RLIMIT_NOFILE)f FN(\(data)i(in)g(resource\),)f(566)0 2673 y FJ(RLIMIT_NPROC)g FN(\(data)g(in)i(resource\),)d(566)0 2773 y FJ(RLIMIT_OFILE)h FN(\(data)g(in)i(resource\),)d(566)0 2873 y FJ(RLIMIT_RSS)h FN(\(data)h(in)g(resource\),)e(566)0 2972 y FJ(RLIMIT_STACK)h FN(\(data)g(in)i(resource\),)d(566)0 3072 y FJ(RLIMIT_VMEM)h FN(\(data)g(in)i(resource\),)d(566)0 3171 y FJ(RLock\(\))h FN(\(in)h(module)f(threading\),)f(539)0 3271 y FJ(rmd\(\))i FN(\(FTP)g(method\),)e(639)0 3371 y FJ(rmdir\(\))h FN(\(in)h(module)f(os\),)h(405)0 3470 y(RMFF)-7 b(,)21 b(704)0 3570 y FJ(rms\(\))f FN(\(in)g(module)f (audioop\),)e(695)0 3670 y FJ(rmtree\(\))i FN(\(in)h(module)f (shutil\),)h(339)0 3769 y FJ(rnopen\(\))f FN(\(in)h(module)f(bsddb\),)g (380)0 3869 y FJ(RobotFileParser)f FN(\(class)j(in)f(robotparser\),)d (313)0 3968 y FJ(robotparser)i FN(\(standard)f(module\),)h FL(313)0 4068 y FN(robots.txt,)f(313)0 4168 y FJ(rotate\(\))h FN(\()i(method\),)d(117)0 4267 y FJ(RotatingFileHandler)f FN(\(class)k(in)f(logging\),)e(462)0 4367 y FJ(round\(\))h FN(\(in)h(module)f(\),)h(14)0 4467 y FJ(Rounded)f FN(\(class)i(in)g (decimal\),)e(163)0 4566 y FJ(row_factory)g FN(\()h(attrib)n(ute\),)f (388)0 4666 y FJ(rowcount)g FN(\()i(attrib)n(ute\),)e(390)0 4765 y FJ(rpartition\(\))g FN(\(string)g(method\),)f(31)0 4865 y FJ(rpc_paths)h FN(\(SimpleXMLRPCServ)o(er)g(attrib)n(ute\),)g (689)0 4965 y FJ(rpop\(\))h FN(\(POP3)p 547 4965 25 4 v 29 w(SSL)h(method\),)d(641)0 5064 y FJ(rset\(\))i FN(\(POP3)p 547 5064 V 29 w(SSL)h(method\),)d(641)0 5164 y FJ(rshift\(\))h FN(\(in)h(module)f(operator\),)f(184)0 5264 y FJ(rsplit\(\))166 5363 y FN(in)i(module)f(string,)h(51)2158 83 y(string)f(method,)g(31) 1992 183 y FJ(rstrip\(\))2158 282 y FN(in)h(module)f(string,)g(52)2158 382 y(string)g(method,)g(31)1992 482 y FJ(RTLD_LAZY)g FN(\(data)g(in)i(dl\),)e(557)1992 581 y FJ(RTLD_NOW)g FN(\(data)g(in)i(dl\),)f(557)1992 681 y FJ(ruler)f FN(\(Cmd)h(attrib)n (ute\),)f(759)1992 780 y FJ(run\(\))2158 880 y FN(BaseHandler)g (method,)g(615)2158 980 y(DocT)-6 b(estRunner)18 b(method,)h(784)2158 1079 y(in)h(module)f(cPro\002le,)h(814)2158 1179 y(in)g(module)f(pdb,)g (806)2158 1279 y(Pro\002le)h(method,)e(820)2158 1378 y(scheduler)g(method,)h(132)2158 1478 y(T)-6 b(estCase)21 b(method,)d(797)2158 1577 y(T)-6 b(estSuite)20 b(method,)f(798)2158 1677 y(Thread)f(method,)h(545)2158 1777 y(T)m(race)g(method,)g(824)1992 1876 y(Run)h(script,)g(734)1992 1976 y FJ(run_docstring_examples\(\))k FN(\(in)29 b(module)e(doctest\),)2324 2076 y(778)1992 2175 y FJ(run_module\(\))18 b FN(\(in)i(module)f(runp)o(y\),)f(871)1992 2275 y FJ(run_script\(\))g FN(\(ModuleFinder)f(method\),)i(871)1992 2374 y FJ(run_suite\(\))f FN(\(in)i(module)f(test.test)p 3199 2374 V 30 w(support\),)g(804)1992 2474 y FJ(run_unittest\(\))f FN(\(in)i(module)e(test.test)p 3348 2474 V 31 w(support\),)g(804)1992 2574 y FJ(runcall\(\))2158 2673 y FN(in)i(module)f(pdb,)g(806)2158 2773 y(Pro\002le)h(method,)e(820)1992 2873 y FJ(runcode\(\))h FN(\(Interacti)n(v)o(eConsole)e(method\),)h(856)1992 2972 y FJ(runctx\(\))2158 3072 y FN(in)i(module)f(cPro\002le,)h(815) 2158 3171 y(Pro\002le)g(method,)e(820)2158 3271 y(T)m(race)h(method,)g (824)1992 3371 y FJ(runeval\(\))g FN(\(in)h(module)e(pdb\),)h(806)1992 3470 y FJ(runfunc\(\))g FN(\(T)m(race)g(method\),)f(824)1992 3570 y FJ(runpy)h FN(\(standard)g(module\),)f FL(871)1992 3670 y FJ(runsource\(\))g FN(\(Interacti)n(v)o(eConsole)f(method\),)i (856)1992 3769 y FJ(RuntimeError)f FN(\(e)o(xception)g(in)i(e)o (xceptions\),)e(20)1992 3869 y FJ(RuntimeWarning)g FN(\(e)o(xception)g (in)i(e)o(xceptions\),)e(21)1992 3968 y FJ(RUSAGE_BOTH)g FN(\(data)i(in)g(resource\),)f(567)1992 4068 y FJ(RUSAGE_CHILDREN)e FN(\(data)j(in)h(resource\),)d(567)1992 4168 y FJ(RUSAGE_SELF)g FN(\(data)i(in)g(resource\),)f(567)1992 4362 y FE(S)1992 4485 y FJ(S)h FN(\(data)g(in)g(re\),)g(57)1992 4585 y FJ(s_eval\(\))f FN(\(REx)o(ec)g(method\),)f(861)1992 4684 y FJ(s_exec\(\))h FN(\(REx)o(ec)g(method\),)f(861)1992 4784 y FJ(s_execfile\(\))g FN(\(REx)o(ec)i(method\),)e(861)1992 4884 y FJ(S_IFMT\(\))h FN(\(in)h(module)f(stat\),)h(330)1992 4983 y FJ(S_IMODE\(\))f FN(\(in)h(module)e(stat\),)j(330)1992 5083 y FJ(s_import\(\))d FN(\(REx)o(ec)i(method\),)e(861)1992 5183 y FJ(S_ISBLK\(\))h FN(\(in)h(module)e(stat\),)j(330)1992 5282 y FJ(S_ISCHR\(\))e FN(\(in)h(module)e(stat\),)j(330)1992 5382 y FJ(S_ISDIR\(\))e FN(\(in)h(module)e(stat\),)j(330)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1017)p eop end %%Page: 1018 1030 TeXDict begin 1018 1029 bop 0 83 a FJ(S_ISFIFO\(\))19 b FN(\(in)h(module)f(stat\),)h(330)0 183 y FJ(S_ISLNK\(\))f FN(\(in)h(module)f(stat\),)h(330)0 282 y FJ(S_ISREG\(\))f FN(\(in)h(module)f(stat\),)h(330)0 382 y FJ(S_ISSOCK\(\))f FN(\(in)h(module)f(stat\),)h(330)0 482 y FJ(s_reload\(\))f FN(\(REx)o(ec)g(method\),)g(861)0 581 y FJ(s_unload\(\))g FN(\(REx)o(ec)g(method\),)g(861)0 681 y FJ(safe_substitute\(\))f FN(\(T)-6 b(emplate)19 b(method\),)f(49)0 780 y FJ(SafeConfigParser)g FN(\(class)j(in)f(Con\002gP)o(arser\),)e(310)0 880 y FJ(saferepr\(\))h FN(\(in)h(module)f(pprint\),)f(146)0 980 y FJ(same_files)h FN(\(dircmp)f(attrib)n(ute\),)i(334)0 1079 y FJ(same_quantum\(\))166 1179 y FN(Conte)o(xt)f(method,)g(162)166 1279 y(Decimal)h(method,)f(158)0 1378 y FJ(samefile\(\))g FN(\(in)h(module)f(os.path\),)f(327)0 1478 y FJ(sameopenfile\(\))g FN(\(in)i(module)f(os.path\),)g(327)0 1577 y FJ(samestat\(\))g FN(\(in)h(module)f(os.path\),)f(327)0 1677 y FJ(sample\(\))h FN(\(in)h(module)f(random\),)f(170)0 1777 y FJ(save\(\))i FN(\(FileCookieJar)f(method\),)f(674)0 1876 y FJ(save_bgn\(\))h FN(\(HTMLP)o(arser)g(method\),)f(263)0 1976 y FJ(save_end\(\))h FN(\(HTMLP)o(arser)g(method\),)f(263)0 2076 y FJ(SaveKey\(\))h FN(\(in)h(module)p 857 2076 25 4 v 49 w(winre)o(g\),)e(943)0 2175 y FJ(SAX2DOM)h FN(\(class)i(in)g(xml.dom.pulldom\),)15 b(287)0 2275 y FJ(SAXException)k FN(\(e)o(xception)e(in)k(xml.sax\),)e (288)0 2374 y FJ(SAXNotRecognizedException)120 b FN(\(e)o(xception)i (in)332 2474 y(xml.sax\),)19 b(288)0 2574 y FJ (SAXNotSupportedException)145 b FN(\(e)o(xception)i(in)332 2673 y(xml.sax\),)19 b(289)0 2773 y FJ(SAXParseException)f FN(\(e)o(xception)g(in)i(xml.sax\),)f(288)0 2873 y FJ(scale\(\))g FN(\(in)h(module)f(imageop\),)f(696)0 2972 y FJ(scalefont\(\))h FN(\(in)h(module)f(fm\),)g(924)0 3072 y FJ(scanf\(\))g FN(\(in)h(module)f(re\),)h(61)0 3171 y FJ(sched)g FN(\(standard)e (module\),)h FL(131)0 3271 y FJ(scheduler)g FN(\(class)i(in)f(sched\),) f(131)0 3371 y FJ(schema)h FN(\(data)f(in)i(msilib\),)e(939)0 3470 y FJ(sci\(\))h FN(\(in)g(module)f(fpformat\),)e(93)0 3570 y FJ(script_from_examples\(\))58 b FN(\(in)k(module)f(doctest\),) 332 3670 y(786)0 3769 y FJ(scroll\(\))19 b FN(\(windo)n(w)g(method\),)f (482)0 3869 y FJ(ScrolledText)h FN(\(standard)f(module\),)g FL(730)0 3968 y FJ(scrollok\(\))h FN(\(windo)n(w)g(method\),)f(482)0 4068 y(search)166 4168 y(path,)i(module,)e(338,)h(831,)g(850)0 4267 y FJ(search\(\))166 4367 y FN(IMAP4)p 421 4367 V 29 w(stream)h(method,)f(645)166 4467 y(in)h(module)f(re,)h(58)166 4566 y(Re)o(ge)o(xObject)f(method,)f(59)0 4666 y FJ(SEARCH_ERROR)h FN(\(data)g(in)i(imp\),)e(867)0 4765 y FJ(second)166 4865 y FN(datetime)h(attrib)n(ute,)f(102)166 4965 y(time)h(attrib)n (ute,)g(106)0 5064 y FJ(section_divider\(\))e FN(\(MultiFile)i (method\),)e(246)0 5164 y FJ(sections\(\))h FN(\(SafeCon\002gP)o(arser) f(method\),)g(311)0 5264 y FJ(secure)i FN(\(Cookie)f(attrib)n(ute\),)g (678)0 5363 y(Secure)h(Hash)g(Algorithm,)e(322)1992 83 y(secure)62 b(hash)h(algorithm,)72 b(SHA1,)h(SHA224,)g(SHA256,)2324 183 y(SHA384,)19 b(SHA512,)g(319)1992 282 y(security)2158 382 y(CGI,)h(607)1992 482 y FJ(seed\(\))f FN(\(in)h(module)f(random\),) f(169)1992 581 y FJ(seek\(\))2178 681 y FN(method,)h(548)2158 780 y(BZ2File)h(method,)f(347)2158 880 y(CD)i(player)e(method,)f(917) 2158 980 y(Chunk)h(method,)f(704)2158 1079 y(\002le)i(method,)f(40)2158 1179 y(MultiFile)h(method,)f(246)1992 1279 y FJ(SEEK_CUR)2158 1378 y FN(data)h(in)g(os,)g(402)2158 1478 y(data)g(in)g(posix\002le,)f (563)1992 1577 y FJ(SEEK_END)2158 1677 y FN(data)h(in)g(os,)g(402)2158 1777 y(data)g(in)g(posix\002le,)f(563)1992 1876 y FJ(SEEK_SET)2158 1976 y FN(data)h(in)g(os,)g(402)2158 2076 y(data)g(in)g(posix\002le,)f (563)1992 2175 y FJ(seekblock\(\))f FN(\(CD)j(player)e(method\),)f(917) 1992 2275 y FJ(seektrack\(\))g FN(\(CD)j(player)e(method\),)f(918)1992 2374 y FJ(Select)h FN(\(class)i(in)f(T)m(ix\),)g(726)1992 2474 y FJ(select\(\))2158 2574 y FN(IMAP4)p 2413 2574 V 29 w(stream)g(method,)e(645)2158 2673 y(in)i(module)f(gl,)h(926)2158 2773 y(in)g(module)f(select,)h(535)1992 2873 y FJ(select)f FN(\(b)n(uilt-in)g(module\),)g FL(535)1992 2972 y FJ(Semaphore\(\))f FN(\(in)i(module)f(threading\),)f(539)1992 3072 y FJ(Semaphore)h FN(\(class)h(in)h(threading\),)c(543)1992 3171 y(semaphores,)h(binary) -5 b(,)18 b(536)1992 3271 y FJ(send\(\))2158 3371 y FN(DatagramHandler) f(method,)i(464)2158 3470 y(dispatcher)g(method,)f(594)2158 3570 y(HTTPResponse)h(method,)g(635)2158 3670 y(IMAP4)p 2413 3670 V 29 w(stream)h(method,)e(645)2158 3769 y(sock)o(et)i (method,)e(583)2158 3869 y(Sock)o(etHandler)g(method,)g(464)1992 3968 y FJ(send_error\(\))38 b FN(\(BaseHTTPRequestHandler)h(method\),) 2324 4068 y(669)1992 4168 y FJ(send_flowing_data\(\))17 b FN(\(writer)i(method\),)g(912)1992 4267 y FJ(send_header\(\))13 b FN(\(BaseHTTPRequestHandler)h(method\),)2324 4367 y(669)1992 4467 y FJ(send_hor_rule\(\))j FN(\(writer)j(method\),)e(912)1992 4566 y FJ(send_label_data\(\))f FN(\(writer)j(method\),)e(912)1992 4666 y FJ(send_line_break\(\))f FN(\(writer)j(method\),)e(912)1992 4765 y FJ(send_literal_data\(\))f FN(\(writer)i(method\),)g(912)1992 4865 y FJ(send_paragraph\(\))e FN(\(writer)j(method\),)e(912)1992 4965 y FJ(send_query\(\))g FN(\(in)i(module)f(gopherlib\),)e(640)1992 5064 y FJ(send_response\(\))227 b FN(\(BaseHTTPRequestHandler)2324 5164 y(method\),)18 b(669)1992 5264 y FJ(send_selector\(\))f FN(\(in)j(module)f(gopherlib\),)f(640)1992 5363 y FJ(sendall\(\))h FN(\(sock)o(et)g(method\),)f(583)p 0 5549 3901 4 v 0 5649 a FI(1018)3515 b(Inde)n(x)p eop end %%Page: 1019 1031 TeXDict begin 1019 1030 bop 0 83 a FJ(sendcmd\(\))19 b FN(\(FTP)i(method\),)d(638)0 183 y FJ(sendfile\(\))h FN(\(BaseHandler)g(method\),)f(616)0 282 y FJ(sendmail\(\))h FN(\(SMTP)h(method\),)e(653)0 382 y FJ(sendto\(\))h FN(\(sock)o(et)h (method\),)e(583)0 482 y FJ(sep)i FN(\(data)g(in)g(os\),)g(414)0 581 y(sequence)166 681 y(iteration,)f(26)166 780 y(object,)g(27)166 880 y(types,)h(mutable,)f(34)166 980 y(types,)h(operations)e(on,)i(28,) f(35)166 1079 y(types,)h(operations)e(on)i(mutable,)f(35)0 1179 y FJ(sequence)g FN(\(data)h(in)g(msilib\),)g(939)0 1279 y FJ(sequence2ast\(\))e FN(\(in)i(module)f(parser\),)g(874)0 1378 y FJ(sequenceIncludes\(\))e FN(\(in)j(module)f(operator\),)f(185)0 1478 y FJ(SequenceMatcher)g FN(\(class)j(in)f(dif)n(\003ib\),)f(65,)h (69)0 1577 y FJ(SerialCookie)f FN(\(class)h(in)h(Cookie\),)e(680)0 1677 y(serializing)166 1777 y(objects,)h(359)0 1876 y FJ(serve_forever\(\))e FN(\(in)i(module)f(Sock)o(etServ)o(er\),)f(666)0 1976 y(serv)o(er)166 2076 y(WWW)-8 b(,)22 b(602,)d(667)0 2175 y FJ(server\(\))g FN(\()i(method\),)d(584)0 2275 y FJ(server_activate\(\))g FN(\(in)i(module)e(Sock)o(etServ)o(er\),)g (667)0 2374 y FJ(server_address)g FN(\(data)i(in)g(Sock)o(etServ)o (er\),)e(666)0 2474 y FJ(server_bind\(\))g FN(\(in)i(module)f(Sock)o (etServ)o(er\),)f(667)0 2574 y FJ(server_software)g FN(\(BaseHandler)h (attrib)n(ute\),)g(615)0 2673 y FJ(server_version)166 2773 y FN(BaseHTTPRequestHandler)g(attrib)n(ute,)g(668)166 2873 y(SimpleHTTPRequestHandler)f(attrib)n(ute,)h(670)0 2972 y FJ(ServerProxy)g FN(\(class)h(in)h(xmlrpclib\),)d(684)0 3072 y FJ(Set)i FN(\(class)h(in)f(sets\),)h(128)0 3171 y(set)166 3271 y(object,)e(36)0 3371 y FJ(set\(\))166 3470 y FN(Ev)o(ent)g(method,)g(544)166 3570 y(in)h(module)f(,)i(14)166 3670 y(mix)o(er)e(de)n(vice)h(method,)e(711)166 3769 y(Morsel)i(method,)f(682)166 3869 y(SafeCon\002gP)o(arser)g(method,)f (312,)h(313)0 3968 y FJ(set_allowed_domains\(\))132 b FN(\(Def)o(aultCookiePolic)o(y)332 4068 y(method\),)18 b(677)0 4168 y FJ(set_app\(\))h FN(\(WSGIServ)o(er)g(method\),)f(613)0 4267 y FJ(set_authorizer\(\))g FN(\()i(method\),)e(388)0 4367 y FJ(set_blocked_domains\(\))132 b FN(\(Def)o(aultCookiePolic)o(y) 332 4467 y(method\),)18 b(677)0 4566 y FJ(set_boundary\(\))g FN(\(Message)i(method\),)e(194)0 4666 y FJ(set_call_back\(\))g FN(\(FORMS)j(object)e(method\),)g(922)0 4765 y FJ(set_charset\(\))f FN(\(Message)i(method\),)e(191)0 4865 y FJ(set_completer\(\))g FN(\(in)i(module)f(readline\),)f(550)0 4965 y FJ (set_completer_delims\(\))48 b FN(\(in)j(module)f(readline\),)332 5064 y(550)0 5164 y FJ(set_conversion_mode\(\))17 b FN(\(in)j(module)f (ctypes\),)g(529)0 5264 y FJ(set_cookie\(\))g FN(\(CookieJar)g (method\),)f(674)0 5363 y FJ(set_cookie_if_ok\(\))f FN(\(CookieJar)i (method\),)g(674)1992 83 y FJ(set_current\(\))f FN(\(Feature)h (method\),)f(938)1992 183 y FJ(set_date\(\))g FN(\(MaildirMessage)h (method\),)g(227)1992 282 y FJ(set_debug\(\))f FN(\(in)i(module)f (gc\),)h(843)1992 382 y FJ(set_debuglevel\(\))2158 482 y FN(FTP)g(method,)f(637)2158 581 y(HTTPResponse)g(method,)g(635)2158 681 y(NNTP)h(method,)f(649)2158 780 y(POP3)p 2357 780 25 4 v 29 w(SSL)i(method,)e(641)2158 880 y(SMTP)h(method,)f(652)2158 980 y(T)-6 b(elnet)20 b(method,)e(657)1992 1079 y FJ (set_default_type\(\))f FN(\(Message)j(method\),)e(193)1992 1179 y FJ(set_event_call_back\(\))e FN(\(in)k(module)f(\003\),)h(919) 1992 1279 y FJ(set_flags\(\))2158 1378 y FN(MaildirMessage)f(method,)f (227)2158 1478 y(mboxMessage)g(method,)g(229)2158 1577 y(MMDFMessage)i(method,)e(233)1992 1677 y FJ(set_form_position\(\))f FN(\(form)i(method\),)f(920)1992 1777 y FJ(set_from\(\))2158 1876 y FN(mboxMessage)g(method,)g(229)2158 1976 y(MMDFMessage)i (method,)e(232)1992 2076 y FJ(set_graphics_mode\(\))f FN(\(in)j(module)f(\003\),)h(919)1992 2175 y FJ(set_history_length\(\)) d FN(\(in)j(module)e(readline\),)h(549)1992 2275 y FJ(set_info\(\))f FN(\(MaildirMessage)h(method\),)g(228)1992 2374 y FJ(set_labels\(\))f FN(\(BabylMessage)h(method\),)f(231)1992 2474 y FJ(set_location\(\))g FN(\()i(method\),)e(381)1992 2574 y FJ(set_nonstandard_attr\(\))e FN(\(Cookie)j(method\),)g(679)1992 2673 y FJ(set_ok\(\))g FN(\(CookiePolic)o(y)f(method\),)g(675)1992 2773 y FJ (set_option_negotiation_callback\(\))24 b FN(\(T)-6 b(elnet)2324 2873 y(method\),)18 b(658)1992 2972 y FJ(set_output_charset\(\))12 b FN(\(NullT)m(ranslations)i(method\),)2324 3072 y(743)1992 3171 y FJ(set_param\(\))k FN(\(Message)i(method\),)e(194)1992 3271 y FJ(set_pasv\(\))g FN(\(FTP)j(method\),)d(638)1992 3371 y FJ(set_payload\(\))g FN(\(Message)i(method\),)e(191)1992 3470 y FJ(set_policy\(\))g FN(\(CookieJar)h(method\),)f(674)1992 3570 y FJ(set_position\(\))g FN(\(Unpack)o(er)g(method\),)g(316)1992 3670 y FJ(set_pre_input_hook\(\))f FN(\(in)j(module)e(readline\),)h (550)1992 3769 y FJ(set_proxy\(\))f FN(\(Request)i(method\),)e(625)1992 3869 y FJ(set_recsrc\(\))g FN(\(mix)o(er)h(de)n(vice)g(method\),)f(711) 1992 3968 y FJ(set_seq1\(\))g FN(\(SequenceMatcher)g(method\),)g(69) 1992 4068 y FJ(set_seq2\(\))g FN(\(SequenceMatcher)g(method\),)g(69) 1992 4168 y FJ(set_seqs\(\))g FN(\(SequenceMatcher)g(method\),)g(69) 1992 4267 y FJ(set_sequences\(\))2158 4367 y FN(MH)i(method,)f(224)2158 4467 y(MHMessage)h(method,)e(230)1992 4566 y FJ (set_server_documentation\(\))175 b FN(\(DocXMLR-)2324 4666 y(PCRequestHandler)19 b(method\),)f(692)1992 4765 y FJ(set_server_name\(\))e FN(\(DocXMLRPCRequestHandler)2324 4865 y(method\),)i(692)1992 4965 y FJ(set_server_title\(\))381 b FN(\(DocXMLRPCRe-)2324 5064 y(questHandler)18 b(method\),)g(692)1992 5164 y FJ(set_spacing\(\))g FN(\(formatter)g(method\),)g(911)1992 5264 y FJ(set_startup_hook\(\))f FN(\(in)j(module)f(readline\),)f(549) 1992 5363 y FJ(set_subdir\(\))g FN(\(MaildirMessage)h(method\),)f(227)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1019)p eop end %%Page: 1020 1032 TeXDict begin 1020 1031 bop 0 83 a FJ(set_terminator\(\))18 b FN(\(async)p 1041 83 25 4 v 28 w(chat)i(method\),)f(597)0 183 y FJ(set_threshold\(\))f FN(\(in)i(module)f(gc\),)g(843)0 282 y FJ(set_trace\(\))g FN(\(in)h(module)f(pdb\),)f(806)0 382 y FJ(set_type\(\))h FN(\(Message)h(method\),)e(194)0 482 y FJ(set_unittest_reportflags\(\))131 b FN(\(in)k(module)332 581 y(doctest\),)19 b(780)0 681 y FJ(set_unixfrom\(\))f FN(\(Message)i(method\),)e(191)0 780 y FJ(set_url\(\))h FN(\(RobotFileP)o(arser)g(method\),)f(313)0 880 y FJ(set_userptr\(\))g FN(\()j(method\),)d(491)0 980 y FJ(set_visible\(\))g FN(\(BabylMessage)i(method\),)e(231)0 1079 y FJ(setacl\(\))h FN(\(IMAP4)p 702 1079 V 29 w(stream)h(method\),)e(645)0 1179 y FJ(setannotation\(\))g FN(\(IMAP4)p 1051 1179 V 29 w(stream)i(method\),)e(645)0 1279 y FJ(setattr\(\))h FN(\(in)h(module)f(\),)h(14)0 1378 y FJ(setAttribute\(\))e FN(\(Element)h(method\),)f(279)0 1478 y FJ(setAttributeNode\(\))f FN(\(Element)j(method\),)e(279)0 1577 y FJ(setAttributeNodeNS\(\))f FN(\(Element)i(method\),)f(279)0 1677 y FJ(setAttributeNS\(\))g FN(\(Element)h(method\),)f(279)0 1777 y FJ(SetBase\(\))h FN(\(xmlparser)f(method\),)h(265)0 1876 y FJ(setblocking\(\))f FN(\(sock)o(et)i(method\),)e(583)0 1976 y FJ(setByteStream\(\))g FN(\(InputSource)f(method\),)h(297)0 2076 y FJ(setcbreak\(\))h FN(\(in)h(module)f(tty\),)g(560)0 2175 y FJ(setchannels\(\))f FN(\(audio)h(con\002guration)f(method\),)g(914)0 2275 y FJ(setCharacterStream\(\))d FN(\(InputSource)g(method\),)i(297)0 2374 y FJ(setcheckinterval\(\))g FN(\(in)j(module)f(sys\),)h(832)0 2474 y FJ(setcomptype\(\))166 2574 y FN(aifc)g(method,)f(699)166 2673 y(A)-5 b(U)p 286 2673 V 30 w(write)21 b(method,)d(701)166 2773 y(W)-7 b(a)n(v)o(e)p 355 2773 V 30 w(write)20 b(method,)f(703)0 2873 y FJ(setconfig\(\))g FN(\(audio)g(port)g(method\),)f(915)0 2972 y FJ(setContentHandler\(\))f FN(\(XMLReader)i(method\),)f(295)0 3072 y FJ(setcontext\(\))166 3171 y FN(in)i(module)f(decimal,)h(158)166 3271 y(MH)h(method,)d(238)0 3371 y FJ(setcurrent\(\))h FN(\(F)o(older)f(method\),)h(238)0 3470 y FJ(setDaemon\(\))g FN(\(Thread)f(method\),)g(545)0 3570 y FJ(setdefault\(\))h FN(\(dictionary)f(method\),)g(37)0 3670 y FJ(setdefaultencoding\(\))f FN(\(in)j(module)f(sys\),)h(832)0 3769 y FJ(setdefaulttimeout\(\))d FN(\(in)j(module)f(sock)o(et\),)g(581)0 3869 y FJ(setdlopenflags\(\))f FN(\(in)i(module)f(sys\),)h(832)0 3968 y FJ(setDocumentLocator\(\))25 b FN(\(ContentHandler)g(method\),)332 4068 y(291)0 4168 y FJ(setDTDHandler\(\))18 b FN(\(XMLReader)h(method\),)f(295)0 4267 y FJ(setegid\(\))h FN(\(in)h(module)f(os\),)h(397)0 4367 y FJ(setEncoding\(\))e FN(\(InputSource)g(method\),)g(297)0 4467 y FJ(setEntityResolver\(\))f FN(\(XMLReader)i(method\),)f(296)0 4566 y FJ(setErrorHandler\(\))g FN(\(XMLReader)h(method\),)f(296)0 4666 y FJ(seteuid\(\))h FN(\(in)h(module)f(os\),)h(397)0 4765 y FJ(setFeature\(\))f FN(\(XMLReader)g(method\),)f(296)0 4865 y FJ(setfillpoint\(\))g FN(\(audio)h(port)h(method\),)e(915)0 4965 y FJ(setfirstweekday\(\))g FN(\(in)i(module)e(calendar\),)h(115)0 5064 y FJ(setfloatmax\(\))f FN(\(audio)h(con\002guration)f(method\),)g (914)0 5164 y FJ(setfmt\(\))h FN(\(audio)g(de)n(vice)h(method\),)e(709) 0 5264 y FJ(setfont\(\))h FN(\(in)h(module)f(fm\),)g(924)0 5363 y FJ(setFormatter\(\))f FN(\()j(method\),)d(461)1992 83 y FJ(setframerate\(\))2158 183 y FN(aifc)i(method,)e(698)2158 282 y(A)-5 b(U)p 2278 282 V 30 w(write)20 b(method,)f(701)2158 382 y(W)-7 b(a)n(v)o(e)p 2347 382 V 30 w(write)20 b(method,)e(703)1992 482 y FJ(setgid\(\))h FN(\(in)h(module)f(os\),)h(397)1992 581 y FJ(setgroups\(\))e FN(\(in)i(module)f(os\),)h(397)1992 681 y FJ(setheading\(\))e FN(\(in)i(module)f(turtle\),)g(732)1992 780 y FJ(setinfo\(\))g FN(\(audio)f(de)n(vice)i(method\),)e(932)1992 880 y FJ(SetInteger\(\))g FN(\(Binary)h(method\),)g(936)1992 980 y FJ(setitem\(\))g FN(\(in)h(module)e(operator\),)g(185)1992 1079 y FJ(setlast\(\))h FN(\(F)o(older)g(method\),)f(239)1992 1179 y FJ(setLevel\(\))g FN(\()j(method\),)d(454,)h(461)1992 1279 y FJ(setliteral\(\))f FN(\(SGMLP)o(arser)h(method\),)g(260)1992 1378 y FJ(setLocale\(\))f FN(\(XMLReader)h(method\),)f(296)1992 1478 y FJ(setlocale\(\))g FN(\(in)i(module)f(locale\),)g(749)1992 1577 y FJ(setLoggerClass\(\))e FN(\(in)j(module)f(logging\),)f(453)1992 1677 y FJ(setlogmask\(\))g FN(\(in)i(module)f(syslog\),)g(569)1992 1777 y FJ(setmark\(\))g FN(\(aifc)g(method\),)g(699)1992 1876 y FJ(setMaxConns\(\))f FN(\(CacheFTPHandler)g(method\),)g(630)1992 1976 y FJ(setmode\(\))h FN(\(in)h(module)e(msvcrt\),)i(940)1992 2076 y FJ(setName\(\))f FN(\(Thread)f(method\),)g(545)1992 2175 y FJ(setnchannels\(\))2158 2275 y FN(aifc)i(method,)e(698)2158 2374 y(A)-5 b(U)p 2278 2374 V 30 w(write)20 b(method,)f(701)2158 2474 y(W)-7 b(a)n(v)o(e)p 2347 2474 V 30 w(write)20 b(method,)e(703) 1992 2574 y FJ(setnframes\(\))2158 2673 y FN(aifc)i(method,)e(698)2158 2773 y(A)-5 b(U)p 2278 2773 V 30 w(write)20 b(method,)f(701)2158 2873 y(W)-7 b(a)n(v)o(e)p 2347 2873 V 30 w(write)20 b(method,)e(703) 1992 2972 y FJ(setnomoretags\(\))f FN(\(SGMLP)o(arser)j(method\),)e (260)1992 3072 y FJ(setoption\(\))g FN(\(in)i(module)f(jpe)o(g\),)g (928)1992 3171 y FJ(setparameters\(\))e FN(\(audio)i(de)n(vice)h (method\),)e(709)1992 3271 y FJ(setparams\(\))2158 3371 y FN(aifc)i(method,)e(699)2158 3470 y(A)-5 b(U)p 2278 3470 V 30 w(write)20 b(method,)f(701)2158 3570 y(in)h(module)f(al,)h (914)2158 3670 y(W)-7 b(a)n(v)o(e)p 2347 3670 V 30 w(write)20 b(method,)e(703)1992 3769 y FJ(setpath\(\))h FN(\(in)h(module)e(fm\),)i (924)1992 3869 y FJ(setpgid\(\))f FN(\(in)h(module)e(os\),)i(397)1992 3968 y FJ(setpgrp\(\))f FN(\(in)h(module)e(os\),)i(397)1992 4068 y FJ(setpos\(\))2158 4168 y FN(aifc)g(method,)e(698)2158 4267 y(A)-5 b(U)p 2278 4267 V 30 w(read)19 b(method,)g(701)2158 4367 y(W)-7 b(a)n(v)o(e)p 2347 4367 V 30 w(read)19 b(method,)g(703)1992 4467 y FJ(setprofile\(\))2158 4566 y FN(in)h(module)f(sys,)h(832)2158 4666 y(in)g(module)f(threading,)f(539)1992 4765 y FJ(SetProperty\(\))g FN(\(Binary)h(method\),)f(935)1992 4865 y FJ(setProperty\(\))g FN(\(XMLReader)h(method\),)f(296)1992 4965 y FJ(setPublicId\(\))g FN(\(InputSource)f(method\),)h(297)1992 5064 y FJ(setqueuesize\(\))g FN(\(audio)h(con\002guration)e(method\),)h(914)1992 5164 y FJ(setquota\(\))g FN(\(IMAP4)p 2793 5164 V 29 w(stream)i(method\),)e (646)1992 5264 y FJ(setraw\(\))h FN(\(in)h(module)f(tty\),)g(559)1992 5363 y FJ(setrecursionlimit\(\))e FN(\(in)j(module)f(sys\),)h(832)p 0 5549 3901 4 v 0 5649 a FI(1020)3515 b(Inde)n(x)p eop end %%Page: 1021 1033 TeXDict begin 1021 1032 bop 0 83 a FJ(setregid\(\))19 b FN(\(in)h(module)f(os\),)h(397)0 183 y FJ(setreuid\(\))f FN(\(in)h(module)f(os\),)h(397)0 282 y FJ(setrlimit\(\))f FN(\(in)h(module)f(resource\),)f(566)0 382 y FJ(sets)i FN(\(standard)f(module\),)f FL(128)0 482 y FJ(setsampfmt\(\))h FN(\(audio)f(con\002guration)g(method\),)g(914)0 581 y FJ(setsampwidth\(\))166 681 y FN(aifc)i(method,)f(698)166 780 y(A)-5 b(U)p 286 780 25 4 v 30 w(write)21 b(method,)d(701)166 880 y(W)-7 b(a)n(v)o(e)p 355 880 V 30 w(write)20 b(method,)f(703)0 980 y FJ(setscrreg\(\))g FN(\(windo)n(w)g(method\),)f(482)0 1079 y FJ(setsid\(\))h FN(\(in)h(module)f(os\),)h(398)0 1179 y FJ(setslice\(\))f FN(\(in)h(module)f(operator\),)e(185)0 1279 y FJ(setsockopt\(\))i FN(\(sock)o(et)g(method\),)f(583)0 1378 y FJ(setstate\(\))h FN(\(in)h(module)f(random\),)e(170)0 1478 y FJ(SetStream\(\))i FN(\(Binary)g(method\),)f(936)0 1577 y FJ(SetString\(\))h FN(\(Binary)g(method\),)f(936)0 1677 y FJ(setSystemId\(\))g FN(\(InputSource)g(method\),)g(297)0 1777 y FJ(setsyx\(\))h FN(\(in)h(module)f(curses\),)h(477)0 1876 y FJ(setTarget\(\))f FN(\(MemoryHandler)d(method\),)j(466)0 1976 y FJ(setTimeout\(\))g FN(\(CacheFTPHandler)f(method\),)g(630)0 2076 y FJ(settimeout\(\))h FN(\(sock)o(et)g(method\),)f(583)0 2175 y FJ(settrace\(\))166 2275 y FN(in)i(module)f(sys,)i(832)166 2374 y(in)f(module)f(threading,)f(539)0 2474 y FJ(settscdump\(\))h FN(\(in)h(module)e(sys\),)j(832)0 2574 y FJ(setuid\(\))e FN(\(in)h(module)f(os\),)h(398)0 2673 y FJ(setUp\(\))f FN(\(T)-6 b(estCase)21 b(method\),)e(796)0 2773 y FJ(setup\(\))166 2873 y FN(in)h(module)f(Sock)o(etServ)o(er)m(,)f(667)166 2972 y(in)i(module)f(turtle,)h(730)0 3072 y FJ(setup_environ\(\))e FN(\(BaseHandler)h(method\),)f(616)0 3171 y FJ (setup_testing_defaults\(\))79 b FN(\(in)84 b(module)e(ws-)332 3271 y(giref.util\),)18 b(611)0 3371 y FJ(setupterm\(\))h FN(\(in)h(module)f(curses\),)g(477)0 3470 y FJ(SetValue\(\))g FN(\(in)h(module)p 907 3470 V 49 w(winre)o(g\),)e(943)0 3570 y FJ(SetValueEx\(\))h FN(\(in)h(module)p 1006 3570 V 48 w(winre)o(g\),)f(944)0 3670 y FJ(setwidth\(\))g FN(\(audio)g(con\002guration)e(method\),)h(914)0 3769 y FJ(setx\(\))i FN(\(in)g(module)e(turtle\),)i(732)0 3869 y FJ(sety\(\))g FN(\(in)g(module)e(turtle\),)i(732)0 3968 y(SGML,)g(259)0 4068 y FJ(sgmllib)f FN(\(standard)g(module\),)f FL(259)p FN(,)h(262)0 4168 y FJ(SGMLParseError)f FN(\(e)o(xception)g (in)i(sgmllib\),)g(260)0 4267 y FJ(SGMLParser)166 4367 y FN(class)h(in)g(sgmllib,)e(259)166 4467 y(in)h(module)f(sgmllib,)h (262)0 4566 y FJ(sha)g FN(\(b)n(uilt-in)f(module\),)g FL(322)0 4666 y FJ(Shelf)h FN(\(class)h(in)f(shelv)o(e\),)f(372)0 4765 y FJ(shelve)h FN(\(standard)e(module\),)h FL(371)p FN(,)g(374)0 4865 y FJ(shift_path_info\(\))f FN(\(in)i(module)e (wsgiref.util\),)h(611)0 4965 y(shifting)166 5064 y(operations,)f(26)0 5164 y FJ(shlex)166 5264 y FN(class)j(in)g(shle)o(x,)e(759)166 5363 y(standard)g(module,)g FL(759)1992 83 y FJ(shortDescription\(\))e FN(\(T)-6 b(estCase)21 b(method\),)d(798)1992 183 y FJ(shouldFlush\(\)) 2158 282 y FN(Buf)n(feringHandler)e(method,)j(466)2158 382 y(MemoryHandler)e(method,)h(466)1992 482 y FJ(show\(\))h FN(\()i(method\),)d(492)1992 581 y FJ(show_choice\(\))g FN(\(in)i(module)f(\003\),)h(919)1992 681 y FJ(show_file_selector\(\))d FN(\(in)j(module)e(\003\),)j(920)1992 780 y FJ(show_form\(\))d FN(\(form)h(method\),)f(920)1992 880 y FJ(show_input\(\))g FN(\(in)i(module)f(\003\),)h(920)1992 980 y FJ(show_message\(\))e FN(\(in)i(module)e(\003\),)j(919)1992 1079 y FJ(show_object\(\))d FN(\(FORMS)j(object)e(method\),)g(923)1992 1179 y FJ(show_question\(\)) e FN(\(in)j(module)f(\003\),)i(919)1992 1279 y FJ(showsyntaxerror\(\)) 53 b FN(\(Interacti)n(v)o(eConsole)g(method\),)2324 1378 y(856)1992 1478 y FJ(showtraceback\(\))17 b FN(\(Interacti)n(v)o (eConsole)h(method\),)g(856)1992 1577 y FJ(showwarning\(\))g FN(\(in)i(module)f(w)o(arnings\),)f(837)1992 1677 y FJ(shuffle\(\))h FN(\(in)h(module)e(random\),)g(170)1992 1777 y FJ(shutdown\(\))2158 1876 y FN(IMAP4)p 2413 1876 V 29 w(stream)i(method,)e(646)2158 1976 y(in)i(module)f(logging,)f(453)2158 2076 y(sock)o(et)i(method,)e (584)1992 2175 y FJ(shutil)h FN(\(standard)g(module\),)f FL(338)1992 2275 y FJ(SIG)2142 2290 y(*)2212 2275 y FN(\(data)h(in)i (signal\),)e(589)1992 2374 y FJ(SIG_DFL)g FN(\(data)h(in)g(signal\),)g (588)1992 2474 y FJ(SIG_IGN)f FN(\(data)h(in)g(signal\),)g(588)1992 2574 y FJ(signal\(\))f FN(\(in)h(module)f(signal\),)g(589)1992 2673 y FJ(signal)g FN(\(b)n(uilt-in)g(module\),)g(538,)g FL(588)1992 2773 y FN(Simple)h(Mail)g(T)m(ransfer)f(Protocol,)g(651) 1992 2873 y FJ(simple_producer)e FN(\(class)k(in)g(asynchat\),)d(597) 1992 2972 y FJ(SimpleCookie)g FN(\(class)j(in)f(Cookie\),)f(680)1992 3072 y FJ(simplefilter\(\))f FN(\(in)i(module)e(w)o(arnings\),)h(837) 1992 3171 y FJ(SimpleHandler)f FN(\(class)j(in)f(wsgiref.handlers\),)d (614)1992 3271 y FJ(SimpleHTTPRequestHandler)61 b FN(\(class)k(in)g (Simple-)2324 3371 y(HTTPServ)o(er\),)18 b(670)1992 3470 y FJ(SimpleHTTPServer)f FN(\(standard)i(module\),)f(667,)h FL(670)1992 3570 y FJ(SimpleXMLRPCRequestHandler)61 b FN(\(class)66 b(in)g(Sim-)2324 3670 y(pleXMLRPCServ)o(er\),)18 b(689)1992 3769 y FJ(SimpleXMLRPCServer)2158 3869 y FN(class)j(in)f (SimpleXMLRPCServ)o(er)m(,)e(688)2158 3968 y(standard)h(module,)f FL(688)1992 4068 y FJ(sin\(\))2158 4168 y FN(in)i(module)f(cmath,)g (152)2158 4267 y(in)h(module)f(math,)g(151)1992 4367 y FJ(sinh\(\))2158 4467 y FN(in)h(module)f(cmath,)g(152)2158 4566 y(in)h(module)f(math,)g(151)1992 4666 y FJ(site)h FN(\(standard)e(module\),)g FL(850)1992 4765 y FN(site-packages)2158 4865 y(directory)-5 b(,)17 b(850)1992 4965 y(site-p)o(ython)2158 5064 y(directory)-5 b(,)17 b(850)1992 5164 y FJ(sitecustomize)h FN(\(module\),)g(851)1992 5264 y FJ(size\(\))2178 5363 y FN(method,)h(548)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1021)p eop end %%Page: 1022 1034 TeXDict begin 1022 1033 bop 166 83 a FN(FTP)21 b(method,)d(639)0 183 y FJ(size)i FN(\(T)-7 b(arInfo)18 b(attrib)n(ute\),)i(355)0 282 y FJ(sizeof\(\))f FN(\(in)h(module)f(ctypes\),)g(529)0 382 y FJ(sizeofimage\(\))f FN(\(in)i(module)f(r)o(gbimg\),)f(706)0 482 y FJ(SKIP)i FN(\(data)g(in)g(doctest\),)f(773)0 581 y FJ(skip\(\))h FN(\(Chunk)e(method\),)h(705)0 681 y FJ(skipinitialspace)f FN(\(Dialect)i(attrib)n(ute\),)f(306)0 780 y FJ(skippedEntity\(\))f FN(\(ContentHandler)g(method\),)g(293)0 880 y FJ(slave\(\))h FN(\(NNTP)i(method\),)d(650)0 980 y FJ(sleep\(\))h FN(\(in)h(module)f(time\),)h(417)0 1079 y(slice)166 1179 y(assignment,)f(35)166 1279 y(operation,)f(28)0 1378 y FJ(slice\(\))166 1478 y FN(b)n(uilt-in)i(function,)e(142,)h(895) 166 1577 y(in)h(module)f(,)i(14)0 1677 y FJ(SliceType)e FN(\(data)h(in)g(types\),)g(142)0 1777 y FJ(SmartCookie)f FN(\(class)h(in)h(Cookie\),)e(680)0 1876 y(SMTP)166 1976 y(protocol,)f(651)0 2076 y FJ(SMTP)i FN(\(class)h(in)f(smtplib\),)f (651)0 2175 y FJ(SMTPAuthenticationError)13 b FN(\(e)o(xception)h(in)j (smtplib\),)332 2275 y(652)0 2374 y FJ(SMTPConnectError)h FN(\(e)o(xception)g(in)i(smtplib\),)f(652)0 2474 y FJ(smtpd)h FN(\(standard)e(module\),)h FL(655)0 2574 y FJ(SMTPDataError)f FN(\(e)o(xception)g(in)j(smtplib\),)e(652)0 2673 y FJ(SMTPException)f FN(\(e)o(xception)g(in)j(smtplib\),)e(651)0 2773 y FJ(SMTPHandler)g FN(\(class)h(in)h(logging\),)d(465)0 2873 y FJ(SMTPHeloError)g FN(\(e)o(xception)g(in)j(smtplib\),)e(652)0 2972 y FJ(smtplib)g FN(\(standard)g(module\),)f FL(651)0 3072 y FJ(SMTPRecipientsRefused)46 b FN(\(e)o(xception)i(in)i(smtplib\),)332 3171 y(652)0 3271 y FJ(SMTPResponseException)c FN(\(e)o(xception)i(in)i(smtplib\),) 332 3371 y(652)0 3470 y FJ(SMTPSenderRefused)18 b FN(\(e)o(xception)g (in)i(smtplib\),)f(652)0 3570 y FJ(SMTPServer)g FN(\(class)i(in)f (smtpd\),)f(655)0 3670 y FJ(SMTPServerDisconnected)30 b FN(\(e)o(xception)h(in)i(smtplib\),)332 3769 y(651)0 3869 y FJ(SND_ALIAS)19 b FN(\(data)h(in)g(winsound\),)e(945)0 3968 y FJ(SND_ASYNC)h FN(\(data)h(in)g(winsound\),)e(946)0 4068 y FJ(SND_FILENAME)h FN(\(data)g(in)i(winsound\),)d(945)0 4168 y FJ(SND_LOOP)h FN(\(data)h(in)g(winsound\),)e(946)0 4267 y FJ(SND_MEMORY)h FN(\(data)h(in)g(winsound\),)e(946)0 4367 y FJ(SND_NODEFAULT)g FN(\(data)i(in)g(winsound\),)e(946)0 4467 y FJ(SND_NOSTOP)h FN(\(data)h(in)g(winsound\),)e(946)0 4566 y FJ(SND_NOWAIT)h FN(\(data)h(in)g(winsound\),)e(946)0 4666 y FJ(SND_PURGE)h FN(\(data)h(in)g(winsound\),)e(946)0 4765 y FJ(sndhdr)i FN(\(standard)e(module\),)h FL(707)0 4865 y FJ(sniff\(\))g FN(\(Snif)n(fer)g(method\),)g(305)0 4965 y FJ(Sniffer)g FN(\(class)i(in)g(csv\),)e(305)0 5064 y FJ(SO_)150 5079 y(*)220 5064 y FN(\(data)h(in)g(sock)o(et\),)g (578)0 5164 y FJ(SOCK_DGRAM)f FN(\(data)h(in)g(sock)o(et\),)f(578)0 5264 y FJ(SOCK_RAW)g FN(\(data)h(in)g(sock)o(et\),)g(578)0 5363 y FJ(SOCK_RDM)f FN(\(data)h(in)g(sock)o(et\),)g(578)1992 83 y FJ(SOCK_SEQPACKET)e FN(\(data)h(in)i(sock)o(et\),)e(578)1992 183 y FJ(SOCK_STREAM)f FN(\(data)i(in)g(sock)o(et\),)g(578)1992 282 y(sock)o(et)2158 382 y(object,)f(577)1992 482 y FJ(socket\(\))2158 581 y FN(IMAP4)p 2413 581 25 4 v 29 w(stream)h(method,)e(646)2158 681 y(in)i(module)f(sock)o(et,)h(580)1992 780 y FJ(socket)2158 880 y FN(b)n(uilt-in)f(module,)g(39,)g FL(577)p FN(,)g(599)2158 980 y(data)h(in)g(Sock)o(etServ)o(er)m(,)e(666)1992 1079 y FJ(socket\(\))h FN(\(in)h(module)f(sock)o(et\),)g(536)1992 1179 y FJ(socket_type)f FN(\(data)i(in)g(Sock)o(etServ)o(er\),)e(666) 1992 1279 y FJ(SocketHandler)g FN(\(class)j(in)f(logging\),)e(463)1992 1378 y FJ(socketpair\(\))g FN(\(in)i(module)f(sock)o(et\),)g(580)1992 1478 y FJ(SocketServer)f FN(\(standard)h(module\),)f FL(664)1992 1577 y FJ(SocketType)g FN(\(data)i(in)g(sock)o(et\),)g(581) 1992 1677 y FJ(softspace)f FN(\(\002le)h(attrib)n(ute\),)f(41)1992 1777 y FJ(SOL_)2192 1792 y(*)2261 1777 y FN(\(data)h(in)g(sock)o(et\),) g(578)1992 1876 y FJ(SOMAXCONN)f FN(\(data)g(in)i(sock)o(et\),)e(578) 1992 1976 y FJ(sort\(\))2158 2076 y FN(IMAP4)p 2413 2076 V 29 w(stream)h(method,)e(646)2158 2175 y(list)j(method,)d(35)1992 2275 y FJ(sort_stats\(\))g FN(\(Stats)j(method\),)d(816)1992 2374 y FJ(sorted\(\))h FN(\(in)h(module)f(\),)h(14)1992 2474 y FJ(sortTestMethodsUsing)d FN(\(T)-6 b(estLoader)18 b(attrib)n(ute\),)h(800)1992 2574 y FJ(source)2158 2673 y FN(Example)f(attrib)n(ute,)i(781)2158 2773 y(shle)o(x)f(attrib)n (ute,)h(761)1992 2873 y FJ(sourcehook\(\))e FN(\(shle)o(x)h(method\),)g (760)1992 2972 y FJ(span\(\))g FN(\(MatchObject)g(method\),)f(61)1992 3072 y FJ(spawn\(\))h FN(\(in)h(module)f(pty\),)g(560)1992 3171 y FJ(spawnl\(\))g FN(\(in)h(module)f(os\),)h(410)1992 3271 y FJ(spawnle\(\))f FN(\(in)h(module)e(os\),)i(410)1992 3371 y FJ(spawnlp\(\))f FN(\(in)h(module)e(os\),)i(410)1992 3470 y FJ(spawnlpe\(\))e FN(\(in)i(module)f(os\),)h(410)1992 3570 y FJ(spawnv\(\))f FN(\(in)h(module)f(os\),)h(411)1992 3670 y FJ(spawnve\(\))f FN(\(in)h(module)e(os\),)i(411)1992 3769 y FJ(spawnvp\(\))f FN(\(in)h(module)e(os\),)i(411)1992 3869 y FJ(spawnvpe\(\))e FN(\(in)i(module)f(os\),)h(411)1992 3968 y FJ(specified_attributes)d FN(\(xmlparser)h(attrib)n(ute\),)h (266)1992 4068 y FJ(speed\(\))2158 4168 y FN(audio)g(de)n(vice)g (method,)g(709)2158 4267 y(in)h(module)f(turtle,)g(731)1992 4367 y FJ(split\(\))2158 4467 y FN(in)h(module)f(os.path,)g(327)2158 4566 y(in)h(module)f(re,)h(58)2158 4666 y(in)g(module)f(shle)o(x,)g (759)2158 4765 y(in)h(module)f(string,)g(51)2158 4865 y(Re)o(ge)o(xObject)f(method,)h(60)2158 4965 y(string)g(method,)g(31) 1992 5064 y FJ(splitdrive\(\))f FN(\(in)i(module)f(os.path\),)g(327) 1992 5164 y FJ(splitext\(\))f FN(\(in)i(module)f(os.path\),)g(327)1992 5264 y FJ(splitfields\(\))f FN(\(in)i(module)f(string\),)g(51)1992 5363 y FJ(splitlines\(\))f FN(\(string)i(method\),)e(31)p 0 5549 3901 4 v 0 5649 a FI(1022)3515 b(Inde)n(x)p eop end %%Page: 1023 1035 TeXDict begin 1023 1034 bop 0 83 a FJ(SplitResult)19 b FN(\(class)h(in)h(urlparse\),)d(664)0 183 y FJ(splitunc\(\))h FN(\(in)h(module)f(os.path\),)f(327)0 282 y(sprintf-style)h (formatting,)f(32)0 382 y FJ(spwd)i FN(\(b)n(uilt-in)f(module\),)f FL(555)0 482 y FJ(sqlite3)h FN(\(b)n(uilt-in)h(module\),)e FL(383)0 581 y FJ(sqrt\(\))166 681 y FN(Conte)o(xt)h(method,)g(162)166 780 y(Decimal)h(method,)f(158)166 880 y(in)h(module)f(cmath,)h(152)166 980 y(in)g(module)f(math,)h(150)0 1079 y FJ(ssl\(\))166 1179 y FN(IMAP4)p 421 1179 25 4 v 29 w(stream)g(method,)f(647)166 1279 y(in)h(module)f(sock)o(et,)h(580)0 1378 y FJ(ST_ATIME)f FN(\(data)h(in)g(stat\),)h(331)0 1478 y FJ(ST_CTIME)e FN(\(data)h(in)g(stat\),)h(331)0 1577 y FJ(ST_DEV)f FN(\(data)f(in)i (stat\),)f(331)0 1677 y FJ(ST_GID)g FN(\(data)f(in)i(stat\),)f(331)0 1777 y FJ(ST_INO)g FN(\(data)f(in)i(stat\),)f(331)0 1876 y FJ(ST_MODE)f FN(\(data)h(in)h(stat\),)f(331)0 1976 y FJ(ST_MTIME)f FN(\(data)h(in)g(stat\),)h(331)0 2076 y FJ(ST_NLINK)e FN(\(data)h(in)g(stat\),)h(331)0 2175 y FJ(ST_SIZE)e FN(\(data)h(in)h(stat\),)f(331)0 2275 y FJ(ST_UID)g FN(\(data)f(in)i(stat\),)f(331)0 2374 y FJ(stack\(\))f FN(\(in)h(module)f(inspect\),)h(850)0 2474 y(stack)g(vie)n(wer)m(,)f(735)0 2574 y FJ(stack_size\(\))166 2673 y FN(in)h(module)f(thread,)g(537)166 2773 y(in)h(module)f (threading,)f(539)0 2873 y(stackable)166 2972 y(streams,)i(77)0 3072 y FJ(standard_b64decode\(\))d FN(\(in)j(module)f(base64\),)g(251)0 3171 y FJ(standard_b64encode\(\))e FN(\(in)j(module)f(base64\),)g(251)0 3271 y FJ(StandardError)f FN(\(e)o(xception)g(in)j(e)o(xceptions\),)d (18)0 3371 y FJ(standend\(\))h FN(\(windo)n(w)g(method\),)f(482)0 3470 y FJ(standout\(\))h FN(\(windo)n(w)g(method\),)f(482)0 3570 y FJ(starmap\(\))h FN(\(in)h(module)f(itertools\),)g(177)0 3670 y FJ(start\(\))166 3769 y FN(MatchObject)g(method,)g(61)166 3869 y(Pro\002le)h(method,)f(820)166 3968 y(Thread)g(method,)f(545)166 4068 y(T)m(reeBuilder)h(method,)g(301)0 4168 y FJ(start_color\(\))f FN(\(in)i(module)f(curses\),)h(477)0 4267 y FJ(start_component\(\))e FN(\(Directory)g(method\),)g(937)0 4367 y FJ(start_new_thread\(\))f FN(\(in)j(module)f(thread\),)g(537)0 4467 y FJ(startbody\(\))g FN(\(MimeWriter)g(method\),)f(243)0 4566 y FJ (StartCdataSectionHandler\(\))249 b FN(\(xmlparser)332 4666 y(method\),)18 b(268)0 4765 y FJ(StartDoctypeDeclHandler\(\))299 b FN(\(xmlparser)332 4865 y(method\),)18 b(267)0 4965 y FJ(startDocument\(\))g FN(\(ContentHandler)g(method\),)g(291)0 5064 y FJ(startElement\(\))g FN(\(ContentHandler)g(method\),)g(292)0 5164 y FJ(StartElementHandler\(\))f FN(\(xmlparser)h(method\),)g(267)0 5264 y FJ(startElementNS\(\))g FN(\(ContentHandler)g(method\),)g(292)0 5363 y FJ(startfile\(\))h FN(\(in)h(module)f(os\),)g(412)1992 83 y FJ(startmultipartbody\(\))82 b FN(\(MimeWriter)j(method\),)2324 183 y(243)1992 282 y FJ(StartNamespaceDeclHandler\(\))198 b FN(\(xmlparser)2324 382 y(method\),)18 b(268)1992 482 y FJ(startPrefixMapping\(\))24 b FN(\(ContentHandler)i(method\),)2324 581 y(291)1992 681 y FJ(startswith\(\))18 b FN(\(string)i(method\),)e (31)1992 780 y FJ(startTest\(\))g FN(\(T)-6 b(estResult)21 b(method\),)d(799)1992 880 y FJ(starttls\(\))g FN(\(SMTP)j(method\),)d (653)1992 980 y FJ(stat\(\))2158 1079 y FN(in)i(module)f(os,)h(405)2158 1179 y(NNTP)g(method,)f(650)2158 1279 y(POP3)p 2357 1279 V 29 w(SSL)i(method,)e(641)1992 1378 y FJ(stat)h FN(\(standard)e (module\),)g FL(330)p FN(,)h(406)1992 1478 y FJ(stat_float_times\(\))e FN(\(in)j(module)f(os\),)h(406)1992 1577 y(statement)2158 1677 y FJ(assert)p FN(,)f(18)2158 1777 y FJ(del)p FN(,)h(35,)f(37)2158 1876 y FJ(except)p FN(,)g(17)2158 1976 y FJ(exec)p FN(,)g(44)2158 2076 y FJ(if)p FN(,)h(23)2158 2175 y FJ(import)p FN(,)f(3,)h(865)2158 2275 y FJ(print)p FN(,)f(23)2158 2374 y FJ(raise)p FN(,)g(17)2158 2474 y FJ(try)p FN(,)h(17)2158 2574 y FJ(while)p FN(,)f(23)1992 2673 y FJ(staticmethod\(\))f FN(\(in)i(module)e(\),)j(14)1992 2773 y FJ(Stats)e FN(\(class)i(in)f(pstats\),)h(815)1992 2873 y FJ(status\(\))e FN(\(IMAP4)p 2694 2873 V 28 w(stream)h (method\),)f(646)1992 2972 y FJ(status)g FN(\(data)h(in)g(httplib\),)f (636)1992 3072 y FJ(statvfs\(\))g FN(\(in)h(module)e(os\),)i(406)1992 3171 y FJ(statvfs)f FN(\(standard)g(module\),)f FL(332)p FN(,)h(406)1992 3271 y FJ(StdButtonBox)f FN(\(class)j(in)f(T)m(ix\),)g (726)1992 3371 y FJ(stderr)2158 3470 y FN(data)g(in)g(sys,)h(832)2158 3570 y(Popen)e(attrib)n(ute,)g(574)1992 3670 y FJ(stdin)2158 3769 y FN(data)h(in)g(sys,)h(832)2158 3869 y(Popen)e(attrib)n(ute,)g (573)1992 3968 y FJ(stdout)2158 4068 y FN(data)h(in)g(sys,)h(832)2158 4168 y(Popen)e(attrib)n(ute,)g(574)1992 4267 y(Stein,)h(Gre)o(g,)f(898) 1992 4367 y FJ(stereocontrols\(\))e FN(\(mix)o(er)i(de)n(vice)g (method\),)g(711)1992 4467 y FJ(STILL)g FN(\(data)h(in)g(cd\),)g(916) 1992 4566 y FJ(stop\(\))2158 4666 y FN(CD)h(player)e(method,)f(918)2158 4765 y(Pro\002le)i(method,)e(820)2158 4865 y(T)-6 b(estResult)21 b(method,)d(799)1992 4965 y FJ(StopIteration)g FN(\(e)o(xception)g(in)i (e)o(xceptions\),)e(20)1992 5064 y FJ(stopListening\(\))f FN(\(in)j(module)f(logging\),)f(469)1992 5164 y FJ(stopTest\(\))g FN(\(T)-6 b(estResult)21 b(method\),)d(799)1992 5264 y FJ(storbinary\(\))g FN(\(FTP)i(method\),)f(638)1992 5363 y FJ(store\(\))g FN(\(IMAP4)p 2644 5363 V 29 w(stream)h(method\),) e(646)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1023)p eop end %%Page: 1024 1036 TeXDict begin 1024 1035 bop 0 83 a FJ(storlines\(\))19 b FN(\(FTP)h(method\),)e(638)0 183 y FJ(str\(\))166 282 y FN(in)i(module)f(,)i(15)166 382 y(in)f(module)f(locale,)h(752)0 482 y FJ(strcoll\(\))f FN(\(in)h(module)f(locale\),)g(751)0 581 y FJ(StreamError)g FN(\(e)o(xception)f(in)i(tar\002le\),)g(353)0 681 y FJ(StreamHandler)e FN(\(class)j(in)f(logging\),)e(462)0 780 y FJ(StreamReader)h FN(\(class)h(in)h(codecs\),)e(83)0 880 y FJ(StreamReaderWriter)e FN(\(class)k(in)g(codecs\),)e(84)0 980 y FJ(StreamRecoder)f FN(\(class)j(in)f(codecs\),)g(85)0 1079 y(streams,)g(77)166 1179 y(stackable,)f(77)0 1279 y FJ(StreamWriter)g FN(\(class)h(in)h(codecs\),)e(83)0 1378 y FJ(strerror\(\))g FN(\(in)h(module)f(os\),)h(398)0 1478 y FJ(strftime\(\))166 1577 y FN(date)g(method,)f(101)166 1677 y(datetime)h(method,)e(105)166 1777 y(in)i(module)f(time,)h(417) 166 1876 y(time)g(method,)f(107)0 1976 y FJ(strict_domain)f FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)h(677)0 2076 y FJ(strict_errors\(\))e FN(\(in)i(module)f(codecs\),)g(79)0 2175 y FJ(strict_ns_domain)f FN(\(L)-6 b(WPCookieJar)19 b(attrib)n(ute\),)g(677)0 2275 y FJ(strict_ns_set_initial_dollar)44 b FN(\(L)-6 b(WPCookie-)332 2374 y(Jar)21 b(attrib)n(ute\),)e(677)0 2474 y FJ(strict_ns_set_path)74 b FN(\(L)-6 b(WPCookieJar)76 b(attrib)n(ute\),)332 2574 y(677)0 2673 y FJ(strict_ns_unverifiable)92 b FN(\(L)-6 b(WPCookieJar)94 b(at-)332 2773 y(trib)n(ute\),)19 b(677)0 2873 y FJ(strict_rfc2965_unverifiable)25 b FN(\(L)-6 b(WPCookieJar)332 2972 y(attrib)n(ute\),)19 b(677)0 3072 y(string)166 3171 y(documentation,)e(877)166 3271 y(formatting,)h(32) 166 3371 y(interpolation,)g(32)166 3470 y(methods,)h(29)166 3570 y(object,)g(27)0 3670 y FJ(string)166 3769 y FN(MatchObject)g (attrib)n(ute,)h(61)166 3869 y(standard)f(module,)g(34,)g FL(47)p FN(,)h(752,)f(754)0 3968 y FJ(string_at\(\))g FN(\(in)h(module)f(ctypes\),)g(529)0 4068 y FJ(StringIO)166 4168 y FN(class)i(in)g(StringIO,)e(74)166 4267 y(standard)g(module,)g FL(74)0 4367 y FJ(stringprep)g FN(\(standard)g(module\),)f FL(91)0 4467 y FJ(StringType)h FN(\(data)h(in)g(types\),)f(141)0 4566 y FJ(StringTypes)g FN(\(data)g(in)i(types\),)e(142)0 4666 y FJ(strip\(\))166 4765 y FN(in)h(module)f(string,)h(52)166 4865 y(string)g(method,)e(31)0 4965 y FJ(strip_dirs\(\))h FN(\(Stats)h(method\),)f(815)0 5064 y FJ(stripspaces)g FN(\(T)-6 b(e)o(xtbox)18 b(attrib)n(ute\),)h(488)0 5164 y FJ(strptime\(\))166 5264 y FN(datetime)h(method,)e(102)166 5363 y(in)i(module)f(time,)h(418)1992 83 y FJ(Struct)f FN(\(class)i(in)f(struct\),)g(65)1992 183 y FJ(struct)f FN(\(b)n(uilt-in)g(module\),)g FL(62)p FN(,)g(584)1992 282 y FJ(struct_time)f FN(\(data)i(in)g(time\),)g(419)1992 382 y FJ(Structure)f FN(\(class)h(in)h(ctypes\),)e(533)1992 482 y(structures)2158 581 y(C,)h(62)1992 681 y FJ(strxfrm\(\))f FN(\(in)h(module)e(locale\),)i(751)1992 780 y FJ(sub\(\))2158 880 y FN(in)g(module)f(operator)m(,)f(184)2158 980 y(in)i(module)f(re,) h(58)2158 1079 y(Re)o(ge)o(xObject)e(method,)h(60)1992 1179 y FJ(subdirs)g FN(\(dircmp)g(attrib)n(ute\),)g(334)1992 1279 y FJ(SubElement\(\))52 b FN(\(in)h(module)g(xml.etree.ElementT)m (ree\),)2324 1378 y(299)1992 1478 y FJ(subn\(\))2158 1577 y FN(in)20 b(module)f(re,)h(59)2158 1677 y(Re)o(ge)o(xObject)e (method,)h(60)1992 1777 y FJ(Subnormal)g FN(\(class)h(in)h(decimal\),)e (163)1992 1876 y FJ(subpad\(\))g FN(\(windo)n(w)g(method\),)f(482)1992 1976 y FJ(subprocess)g FN(\(standard)h(module\),)f FL(571)1992 2076 y FJ(subscribe\(\))g FN(\(IMAP4)p 2843 2076 25 4 v 29 w(stream)i(method\),)e(646)1992 2175 y(subscript)2158 2275 y(assignment,)h(35)2158 2374 y(operation,)f(28)1992 2474 y FJ(subsequent_indent)f FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(77)1992 2574 y FJ(substitute\(\))f FN(\(T)-6 b(emplate)19 b(method\),)f(48)1992 2673 y FJ(subtract\(\))g FN(\(Conte)o(xt)h(method\),)g(162)1992 2773 y FJ(subversion)f FN(\(data)i(in)g(sys\),)h(827)1992 2873 y FJ(subwin\(\))e FN(\(windo)n(w)g(method\),)f(482)1992 2972 y FJ(suffix_map)g FN(\(data)i(in)g(mimetypes\),)f(242)1992 3072 y FJ(suite\(\))g FN(\(in)h(module)f(parser\),)g(874)1992 3171 y FJ(suiteClass)f FN(\(T)-6 b(estLoader)19 b(attrib)n(ute\),)g(801)1992 3271 y FJ(sum\(\))g FN(\(in)h(module)f(\),)h(15)1992 3371 y FJ(summarize\(\))e FN(\(DocT)-6 b(estRunner)18 b(method\),)h(784)1992 3470 y FJ(sunau)g FN(\(standard)g(module\),)f FL(699)1992 3570 y FJ(SUNAUDIODEV)g FN(\(standard)h(module\),)f(931,)h FL(932)1992 3670 y FJ(sunaudiodev)f FN(\(b)n(uilt-in)h(module\),)g FL(931)p FN(,)g(932)1992 3769 y FJ(super\(\))g FN(\(in)h(module)f(\),)h (15)1992 3869 y FJ(super)f FN(\(class)i(descriptor)e(attrib)n(ute\),)g (886)1992 3968 y FJ(supports_unicode_filenames)27 b FN(\(data)k(in)h (os.path\),)2324 4068 y(328)1992 4168 y FJ(swapcase\(\))2158 4267 y FN(in)20 b(module)f(string,)g(52)2158 4367 y(string)g(method,)g (32)1992 4467 y FJ(sym\(\))g FN(\()i(method\),)d(558)1992 4566 y FJ(sym_name)h FN(\(data)g(in)i(symbol\),)d(882)1992 4666 y FJ(symbol)h FN(\(standard)g(module\),)f FL(882)1992 4765 y FN(symbol)h(table,)h(3)1992 4865 y FJ(symlink\(\))f FN(\(in)h(module)e(os\),)i(406)1992 4965 y FJ(sync\(\))2178 5064 y FN(method,)f(381,)g(383)2158 5164 y(audio)g(de)n(vice)g(method,) g(709)2158 5264 y(dbhash)g(method,)f(379)2158 5363 y(in)i(module)f (gdbm,)f(378)p 0 5549 3901 4 v 0 5649 a FI(1024)3515 b(Inde)n(x)p eop end %%Page: 1025 1037 TeXDict begin 1025 1036 bop 166 83 a FN(Shelf)20 b(method,)f(371)0 183 y FJ(syncdown\(\))g FN(\(windo)n(w)g(method\),)f(482)0 282 y FJ(syncok\(\))h FN(\(windo)n(w)g(method\),)f(482)0 382 y FJ(syncup\(\))h FN(\(windo)n(w)g(method\),)f(482)0 482 y FJ(SyntaxErr)h FN(\(e)o(xception)f(in)i(xml.dom\),)e(281)0 581 y FJ(SyntaxError)h FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(20)0 681 y FJ(SyntaxWarning)g FN(\(e)o(xception)g(in)j(e)o(xceptions\),)d (21)0 780 y FJ(sys)i FN(\(b)n(uilt-in)f(module\),)g FL(827)0 880 y FJ(sys_version)51 b FN(\(BaseHTTPRequestHandler)f(attrib)n (ute\),)332 980 y(668)0 1079 y FJ(sysconf\(\))19 b FN(\(in)h(module)f (os\),)h(414)0 1179 y FJ(sysconf_names)e FN(\(data)i(in)g(os\),)g(414)0 1279 y FJ(syslog\(\))f FN(\(in)h(module)f(syslog\),)g(568)0 1378 y FJ(syslog)h FN(\(b)n(uilt-in)f(module\),)f FL(568)0 1478 y FJ(SysLogHandler)g FN(\(class)j(in)f(logging\),)e(464)0 1577 y FJ(system\(\))166 1677 y FN(in)i(module)f(os,)i(412)166 1777 y(in)f(module)f(platform,)g(493)0 1876 y FJ (system.listMethods\(\))12 b FN(\(Serv)o(erProxy)h(method\),)h(685)0 1976 y FJ(system.methodHelp\(\))j FN(\(Serv)o(erProxy)g(method\),)i (685)0 2076 y FJ(system.methodSignature\(\))267 b FN(\(Serv)o(erProxy) 332 2175 y(method\),)18 b(685)0 2275 y FJ(system_alias\(\))g FN(\(in)i(module)f(platform\),)f(493)0 2374 y FJ(SystemError)h FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(20)0 2474 y FJ(SystemExit)h FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(20)0 2574 y FJ(systemId)h FN(\(DocumentT)-7 b(ype)17 b(attrib)n(ute\),)j (277)0 2673 y FJ(SystemRandom)f FN(\(class)h(in)h(random\),)c(171)0 2866 y FE(T)0 2989 y FJ(T_FMT)j FN(\(data)g(in)g(locale\),)f(752)0 3089 y FJ(T_FMT_AMPM)g FN(\(data)h(in)g(locale\),)f(752)0 3188 y FJ(tabnanny)g FN(\(standard)g(module\),)f FL(885)0 3288 y FN(tab)n(ular)166 3387 y(data,)i(303)0 3487 y FJ(tagName)f FN(\(Element)h(attrib)n(ute\),)f(278)0 3587 y FJ(takewhile\(\))g FN(\(in)h(module)f(itertools\),)g(177)0 3686 y FJ(tan\(\))166 3786 y FN(in)h(module)f(cmath,)h(152)166 3886 y(in)g(module)f(math,)h(151)0 3985 y FJ(tanh\(\))166 4085 y FN(in)g(module)f(cmath,)h(152)166 4185 y(in)g(module)f(math,)h (151)0 4284 y FJ(TAR_GZIPPED)f FN(\(data)g(in)i(tar\002le\),)f(353)0 4384 y FJ(TAR_PLAIN)f FN(\(data)h(in)g(tar\002le\),)g(353)0 4483 y FJ(TarError)f FN(\(e)o(xception)f(in)j(tar\002le\),)e(353)0 4583 y FJ(TarFile)g FN(\(class)i(in)g(tar\002le\),)e(352,)g(353)0 4683 y FJ(tarfile)g FN(\(standard)g(module\),)f FL(351)0 4782 y FJ(TarFileCompat)g FN(\(class)j(in)f(tar\002le\),)g(352)0 4882 y FJ(target)g FN(\(ProcessingInstruction)c(attrib)n(ute\),)k(280)0 4982 y FJ(TarInfo)f FN(\(class)i(in)g(tar\002le\),)e(355)0 5081 y FJ(task_done\(\))g FN(\(Queue)g(method\),)f(134)0 5181 y FJ(tb_lineno\(\))h FN(\(in)h(module)f(traceback\),)f(841)0 5280 y FJ(tcdrain\(\))h FN(\(in)h(module)f(termios\),)g(559)0 5380 y FJ(tcflow\(\))g FN(\(in)h(module)f(termios\),)g(559)1992 83 y FJ(tcflush\(\))g FN(\(in)h(module)e(termios\),)i(559)1992 183 y FJ(tcgetattr\(\))e FN(\(in)i(module)f(termios\),)g(558)1992 282 y FJ(tcgetpgrp\(\))f FN(\(in)i(module)f(os\),)h(401)1992 382 y FJ(Tcl\(\))f FN(\(in)h(module)f(Tkinter\),)g(714)1992 482 y FJ(TCP_)2192 497 y(*)2261 482 y FN(\(data)h(in)g(sock)o(et\),)g (578)1992 581 y FJ(tcsendbreak\(\))e FN(\(in)i(module)f(termios\),)g (559)1992 681 y FJ(tcsetattr\(\))f FN(\(in)i(module)f(termios\),)g(559) 1992 780 y FJ(tcsetpgrp\(\))f FN(\(in)i(module)f(os\),)h(401)1992 880 y FJ(tearDown\(\))e FN(\(T)-6 b(estCase)21 b(method\),)e(796)1992 980 y FJ(tee\(\))g FN(\(in)h(module)f(itertools\),)g(177)1992 1079 y FJ(tell\(\))2178 1179 y FN(method,)g(548)2158 1279 y(aifc)h(method,)e(698,)h(699)2158 1378 y(A)-5 b(U)p 2278 1378 25 4 v 30 w(read)19 b(method,)g(701)2158 1478 y(A)-5 b(U)p 2278 1478 V 30 w(write)20 b(method,)f(701)2158 1577 y(BZ2File)h(method,)f(347)2158 1677 y(Chunk)g(method,)f(704)2158 1777 y(\002le)i(method,)f(40)2158 1876 y(MultiFile)h(method,)f(246)2158 1976 y(W)-7 b(a)n(v)o(e)p 2347 1976 V 30 w(read)19 b(method,)g(703)2158 2076 y(W)-7 b(a)n(v)o(e)p 2347 2076 V 30 w(write)20 b(method,)e(703) 1992 2175 y FJ(Telnet)h FN(\(class)i(in)f(telnetlib\),)g(656)1992 2275 y FJ(telnetlib)f FN(\(standard)f(module\),)g FL(656)1992 2374 y FN(TEMP)-9 b(,)19 b(336)1992 2474 y FJ(tempdir)g FN(\(data)h(in)g(temp\002le\),)f(336)1992 2574 y FJ(tempfile)g FN(\(standard)f(module\),)h FL(334)1992 2673 y FJ(Template)2158 2773 y FN(class)i(in)f(pipes,)g(562)2158 2873 y(class)h(in)f(string,)g (48)1992 2972 y FJ(template)2158 3072 y FN(data)g(in)g(temp\002le,)g (336)2158 3171 y(string)f(attrib)n(ute,)h(49)1992 3271 y FJ(tempnam\(\))f FN(\(in)h(module)e(os\),)i(406)1992 3371 y(temporary)2158 3470 y(\002le,)g(334)2158 3570 y(\002le)g(name,)g(334)1992 3670 y FJ(TemporaryFile\(\))d FN(\(in)j(module)f(temp\002le\),)h(334)1992 3769 y FJ(termattrs\(\))e FN(\(in)i(module)f(curses\),)h(477)1992 3869 y FJ(termios)f FN(\(b)n(uilt-in)g(module\),)f FL(558)1992 3968 y FJ(termname\(\))g FN(\(in)i(module)f(curses\),)h(477)1992 4068 y FJ(test\(\))2158 4168 y FN(in)g(module)f(cgi,)h(606)2158 4267 y(mute)o(x)f(method,)f (132)1992 4367 y FJ(test)2158 4467 y FN(DocT)-6 b(estF)o(ailure)19 b(attrib)n(ute,)g(788)2158 4566 y(standard)g(module,)f FL(801)2158 4666 y FN(Une)o(xpectedException)d(attrib)n(ute,)20 b(788)1992 4765 y FJ(test.test_support)d FN(\(standard)i(module\),)f FL(803)1992 4865 y FJ(testandset\(\))g FN(\(mute)o(x)h(method\),)f(132) 1992 4965 y FJ(TestCase)h FN(\(class)i(in)f(unittest\),)g(795)1992 5064 y FJ(TestFailed)e FN(\(e)o(xception)g(in)j(test.test)p 3222 5064 V 30 w(support\),)d(804)1992 5164 y FJ(testfile\(\))g FN(\(in)i(module)f(doctest\),)h(776)1992 5264 y FJ(TESTFN)f FN(\(data)h(in)g(test.test)p 2839 5264 V 30 w(support\),)f(804)1992 5363 y FJ(TestLoader)f FN(\(class)j(in)g(unittest\),)e(796)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1025)p eop end %%Page: 1026 1038 TeXDict begin 1026 1037 bop 0 83 a FJ(testMethodPrefix)18 b FN(\(T)-6 b(estLoader)18 b(attrib)n(ute\),)i(800)0 183 y FJ(testmod\(\))f FN(\(in)h(module)f(doctest\),)g(777)0 282 y FJ(TestResult)g FN(\(class)i(in)f(unittest\),)g(796)0 382 y FJ(tests)g FN(\(data)g(in)g(imghdr\),)e(706)0 482 y FJ(TestSkipped)h FN(\(e)o(xception)f(in)i(test.test)p 1280 482 25 4 v 30 w(support\),)e(804)0 581 y FJ(testsource\(\))h FN(\(in)h(module)e(doctest\),)i(787)0 681 y FJ(testsRun)f FN(\(T)-6 b(estResult)21 b(attrib)n(ute\),)e(799)0 780 y FJ(TestSuite)g FN(\(class)i(in)f(unittest\),)g(796)0 880 y FJ(testzip\(\))f FN(\(ZipFile)h(method\),)e(349)0 980 y FJ(text\(\))i FN(\(Dialog)f(method\),)f(938)0 1079 y FJ(text)i FN(\(data)g(in)g(msilib\),)g(939)0 1179 y FJ(text_factory)f FN(\()h(attrib)n(ute\),)f(388)0 1279 y FJ(Textbox)g FN(\(class)i(in)g(curses.te)o(xtpad\),)c(487)0 1378 y FJ(TextCalendar)i FN(\(class)h(in)h(calendar\),)d(114)0 1478 y FJ(textdomain\(\))h FN(\(in)h(module)e(gette)o(xt\),)h(740)0 1577 y FJ(TextTestRunner)f FN(\(class)j(in)f(unittest\),)g(796)0 1677 y FJ(textwrap)f FN(\(standard)g(module\),)f FL(75)0 1777 y FJ(TextWrapper)h FN(\(class)h(in)h(te)o(xtwrap\),)d(76)0 1876 y FJ(THOUSEP)h FN(\(data)h(in)h(locale\),)e(753)0 1976 y FJ(Thread)h FN(\(class)g(in)h(threading\),)d(539,)h(544)0 2076 y FJ(thread\(\))g FN(\(IMAP4)p 702 2076 V 29 w(stream)h(method\),) e(646)0 2175 y FJ(thread)i FN(\(b)n(uilt-in)f(module\),)f FL(536)0 2275 y FJ(threading)h FN(\(standard)g(module\),)f FL(538)0 2374 y FN(threads)166 2474 y(IRIX,)i(538)166 2574 y(POSIX,)g(537)0 2673 y FJ(tie\(\))g FN(\(in)g(module)f(\003\),)h (920)0 2773 y FJ(tigetflag\(\))f FN(\(in)h(module)f(curses\),)g(477)0 2873 y FJ(tigetnum\(\))g FN(\(in)h(module)f(curses\),)g(477)0 2972 y FJ(tigetstr\(\))g FN(\(in)h(module)f(curses\),)g(477)0 3072 y FJ(time\(\))166 3171 y FN(datetime)h(method,)e(103)166 3271 y(in)i(module)f(time,)h(419)0 3371 y FJ(time)166 3470 y FN(b)n(uilt-in)g(module,)e FL(415)166 3570 y FN(class)j(in)g (datetime,)e(96,)h(105)0 3670 y FJ(Time2Internaldate\(\))d FN(\(in)j(module)f(imaplib\),)g(643)0 3769 y FJ(timedelta)g FN(\(class)i(in)f(datetime\),)f(96,)h(97)0 3869 y FJ (TimedRotatingFileHandler)48 b FN(\(class)k(in)g(logging\),)332 3968 y(463)0 4068 y FJ(timegm\(\))19 b FN(\(in)h(module)f(calendar\),)f (116)0 4168 y FJ(timeit\(\))h FN(\(T)m(imer)h(method\),)e(821)0 4267 y FJ(timeit)i FN(\(standard)e(module\),)h FL(821)0 4367 y FJ(timeout\(\))g FN(\(windo)n(w)g(method\),)f(483)0 4467 y FJ(timeout)h FN(\(e)o(xception)f(in)j(sock)o(et\),)e(578)0 4566 y FJ(Timer)166 4666 y FN(class)i(in)g(threading,)d(539,)h(546)166 4765 y(class)i(in)g(timeit,)f(821)0 4865 y FJ(times\(\))f FN(\(in)h(module)f(os\),)h(412)0 4965 y FJ(timetuple\(\))166 5064 y FN(date)g(method,)f(100)166 5164 y(datetime)h(method,)e(104)0 5264 y FJ(timetz\(\))h FN(\(datetime)h(method\),)e(103)0 5363 y FJ(timezone)h FN(\(data)h(in)g(time\),)g(419)1992 83 y FJ(title\(\))2158 183 y FN(in)g(module)f(turtle,)g(730)2158 282 y(string)g(method,)g(32)1992 382 y(T)m(ix,)g(725)1992 482 y FJ(Tix)2158 581 y FN(class)i(in)f(T)m(ix,)g(725)2158 681 y(standard)f(module,)f FL(725)1992 780 y FJ(tix_addbitmapdir\(\))f FN(\(tixCommand)h(method\),)g(729)1992 880 y FJ(tix_cget\(\))g FN(\(tixCommand)g(method\),)h(729)1992 980 y FJ(tix_configure\(\))e FN(\(tixCommand)h(method\),)h(729)1992 1079 y FJ(tix_filedialog\(\))e FN(\(tixCommand)h(method\),)h(729)1992 1179 y FJ(tix_getbitmap\(\))e FN(\(tixCommand)h(method\),)h(729)1992 1279 y FJ(tix_getimage\(\))f FN(\(tixCommand)g(method\),)g(729)1992 1378 y(TIX)p 2136 1378 V 29 w(LIBRAR)-5 b(Y)-11 b(,)20 b(725)1992 1478 y FJ(tix_option_get\(\))d FN(\(tixCommand)h(method\),)h(729)1992 1577 y FJ(tix_resetoptions\(\))e FN(\(tixCommand)h(method\),)g(729)1992 1677 y FJ(tixCommand)g FN(\(class)j(in)g(T)m(ix\),)e(728)1992 1777 y(Tk,)g(713)1992 1876 y FJ(Tk)h FN(\(class)h(in)f(Tkinter\),)f (714)1992 1976 y(Tk)h(Option)f(Data)h(T)-7 b(ypes,)20 b(722)1992 2076 y(Tkinter)m(,)e(713)1992 2175 y FJ(Tkinter)h FN(\(standard)g(module\),)f FL(713)1992 2275 y FJ(TList)h FN(\(class)i(in)f(T)m(ix\),)g(727)1992 2374 y(TMP)-9 b(,)19 b(336,)h(406)1992 2474 y FJ(TMP_MAX)f FN(\(data)h(in)g(os\),)g (407)1992 2574 y(TMPDIR,)g(336,)f(406)1992 2673 y FJ(tmpfile\(\))g FN(\(in)h(module)e(os\),)i(399)1992 2773 y FJ(tmpnam\(\))f FN(\(in)h(module)f(os\),)h(407)1992 2873 y FJ(to_eng_string\(\))2158 2972 y FN(Conte)o(xt)f(method,)g(162)2158 3072 y(Decimal)h(method,)e (158)1992 3171 y FJ(to_integral\(\))2158 3271 y FN(Conte)o(xt)h (method,)g(162)2158 3371 y(Decimal)h(method,)e(158)1992 3470 y FJ(to_sci_string\(\))f FN(\(Conte)o(xt)j(method\),)e(162)1992 3570 y FJ(to_splittable\(\))f FN(\(Charset)j(method\),)f(204)1992 3670 y FJ(ToASCII\(\))g FN(\(in)h(module)e(encodings.idna\),)f(89)1992 3769 y FJ(tobuf\(\))i FN(\(T)-7 b(arInfo)18 b(method\),)g(355)1992 3869 y FJ(tochild)h FN(\(Popen4)f(attrib)n(ute\),)i(591)1992 3968 y FJ(today\(\))2158 4068 y FN(date)g(method,)e(99)2158 4168 y(datetime)h(method,)g(101)1992 4267 y FJ(tofile\(\))g FN(\(array)g(method\),)f(127)1992 4367 y FJ(togglepause\(\))g FN(\(CD)j(player)e(method\),)f(918)1992 4467 y FJ(tok_name)h FN(\(data)g(in)i(tok)o(en\),)e(883)1992 4566 y FJ(token)2158 4666 y FN(shle)o(x)g(attrib)n(ute,)h(761)2158 4765 y(standard)f (module,)f FL(883)1992 4865 y FJ(tokeneater\(\))g FN(\(in)i(module)f (tabnann)o(y\),)e(885)1992 4965 y FJ(tokenize\(\))h FN(\(in)i(module)f (tok)o(enize\),)g(884)1992 5064 y FJ(tokenize)g FN(\(standard)f (module\),)h FL(883)1992 5164 y FJ(tolist\(\))2158 5264 y FN(array)g(method,)f(127)2158 5363 y(AST)i(method,)f(876)p 0 5549 3901 4 v 0 5649 a FI(1026)3515 b(Inde)n(x)p eop end %%Page: 1027 1039 TeXDict begin 1027 1038 bop 0 83 a FJ(tomono\(\))19 b FN(\(in)h(module)f(audioop\),)f(695)0 183 y FJ(toordinal\(\))166 282 y FN(date)i(method,)f(100)166 382 y(datetime)h(method,)e(105)0 482 y FJ(top\(\))187 581 y FN(method,)g(492)166 681 y(POP3)p 365 681 25 4 v 30 w(SSL)j(method,)d(641)0 780 y FJ(top_panel\(\))h FN(\(in)h(module)f(curses.panel\),)f(491)0 880 y FJ(toprettyxml\(\))g FN(\(Node)i(method\),)e(284)0 980 y FJ(tostereo\(\))h FN(\(in)h(module)f(audioop\),)e(695)0 1079 y FJ(tostring\(\))166 1179 y FN(array)i(method,)g(127)166 1279 y(in)h(module)f (xml.etree.ElementT)m(ree,)e(300)0 1378 y FJ(total_changes)h FN(\()j(attrib)n(ute\),)e(388)0 1478 y FJ(totuple\(\))g FN(\(AST)h(method\),)f(876)0 1577 y FJ(touchline\(\))g FN(\(windo)n(w)g(method\),)f(483)0 1677 y FJ(touchwin\(\))h FN(\(windo)n(w)g(method\),)f(483)0 1777 y FJ(ToUnicode\(\))h FN(\(in)h(module)f(encodings.idna\),)d(89)0 1876 y FJ(tounicode\(\))j FN(\(array)g(method\),)f(127)0 1976 y FJ(tovideo\(\))h FN(\(in)h(module)f(imageop\),)f(696)0 2076 y FJ(towards\(\))h FN(\(in)h(module)f(turtle\),)g(732)0 2175 y FJ(toxml\(\))g FN(\(Node)h(method\),)e(284)0 2275 y FJ(tparm\(\))h FN(\(in)h(module)f (curses\),)h(477)0 2374 y FJ(Trace)g FN(\(class)h(in)f(trace\),)f(824)0 2474 y FJ(trace\(\))g FN(\(in)h(module)f(inspect\),)h(850)0 2574 y FJ(trace)g FN(\(standard)e(module\),)h FL(823)0 2673 y FN(trace)h(function,)e(539,)h(832)0 2773 y(traceback)166 2873 y(object,)g(828,)h(840)0 2972 y FJ(traceback)f FN(\(standard)g (module\),)f FL(840)0 3072 y FJ(traceback_limit)g FN(\(BaseHandler)h (attrib)n(ute\),)g(616)0 3171 y FJ(tracebacklimit)f FN(\(data)i(in)g (sys\),)g(833)0 3271 y(tracebacks)166 3371 y(in)g(CGI)h(scripts,)f(609) 0 3470 y FJ(TracebackType)e FN(\(data)i(in)g(types\),)g(142)0 3570 y FJ(tracer\(\))f FN(\(in)h(module)f(turtle\),)g(731)0 3670 y FJ(transfercmd\(\))f FN(\(FTP)j(method\),)d(638)0 3769 y FJ(translate\(\))166 3869 y FN(in)i(module)f(fnmatch,)g(337)166 3968 y(in)h(module)f(string,)h(52)166 4068 y(string)g(method,)e(32)0 4168 y FJ(translation\(\))g FN(\(in)i(module)f(gette)o(xt\),)g(741)0 4267 y FJ(Tree)h FN(\(class)h(in)f(T)m(ix\),)g(727)0 4367 y FJ(TreeBuilder)f FN(\(class)h(in)h(xml.etree.ElementT)m(ree\),) 16 b(301)0 4467 y(T)m(rue,)j(23,)h(44)0 4566 y FJ(True)g FN(\(data)g(in)g(\),)g(22)0 4666 y(true,)g(23)0 4765 y FJ(truediv\(\))f FN(\(in)h(module)f(operator\),)f(184)0 4865 y FJ(truncate\(\))h FN(\(\002le)h(method\),)f(40)0 4965 y(truth)166 5064 y(v)n(alue,)g(23)0 5164 y FJ(truth\(\))g FN(\(in)h(module)f(operator\),)f(183)0 5264 y FJ(try)166 5363 y FN(statement,)i(17)1992 83 y FJ(ttob\(\))2158 183 y FN(in)g(module)f(img\002le,)h(928)2158 282 y(in)g(module)f(r)o (gbimg,)f(706)1992 382 y(tty)2158 482 y(I/O)i(control,)f(558)1992 581 y FJ(tty)h FN(\(standard)e(module\),)h FL(559)1992 681 y FJ(ttyname\(\))g FN(\(in)h(module)e(os\),)i(401)1992 780 y(tuple)2158 880 y(object,)f(27)1992 980 y FJ(tuple\(\))g FN(\(in)h(module)f(\),)h(15)1992 1079 y FJ(tuple2ast\(\))e FN(\(in)i(module)f(parser\),)g(875)1992 1179 y FJ(TupleType)g FN(\(data)g(in)i(types\),)e(141)1992 1279 y FJ(turnoff_sigfpe\(\))e FN(\(in)j(module)f(fpectl\),)g(852)1992 1378 y FJ(turnon_sigfpe\(\))e FN(\(in)j(module)f(fpectl\),)g(852)1992 1478 y FJ(Turtle)g FN(\(class)i(in)f(turtle\),)g(732)1992 1577 y FJ(turtle)f FN(\(standard)g(module\),)f FL(730)1992 1677 y FN(T)l(utt,)i(Bill,)h (898)1992 1777 y(type)2158 1876 y(Boolean,)e(4)2158 1976 y(object,)g(15)2158 2076 y(operations)f(on)i(dictionary)-5 b(,)18 b(37)2158 2175 y(operations)g(on)i(list,)h(35)1992 2275 y FJ(type\(\))2158 2374 y FN(b)n(uilt-in)e(function,)f(44,)i(141) 2158 2474 y(in)g(module)f(,)h(15)1992 2574 y FJ(type)2158 2673 y FN(sock)o(et)g(attrib)n(ute,)f(584)2158 2773 y(T)-7 b(arInfo)18 b(attrib)n(ute,)i(355)1992 2873 y FJ(typeahead\(\))e FN(\(in)i(module)f(curses\),)h(477)1992 2972 y FJ(typecode)f FN(\(array)g(attrib)n(ute\),)g(126)1992 3072 y FJ (typed_subpart_iterator\(\))181 b FN(\(in)k(module)2324 3171 y(email.iterators\),)18 b(209)1992 3271 y FJ(TypeError)h FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(20)1992 3371 y(types)2158 3470 y(b)n(uilt-in,)h(3,)h(23)2158 3570 y(mutable)f(sequence,)g(34)2158 3670 y(operations)f(on)i(inte)o(ger)m (,)e(26)2158 3769 y(operations)g(on)i(mapping,)e(37)2158 3869 y(operations)g(on)i(mutable)f(sequence,)g(35)2158 3968 y(operations)f(on)i(numeric,)f(25)2158 4068 y(operations)f(on)i (sequence,)f(28,)g(35)1992 4168 y FJ(types)g FN(\(standard)g(module\),) f(44,)i FL(140)1992 4267 y FJ(types_map)f FN(\(data)g(in)i (mimetypes\),)d(242)1992 4367 y FJ(TypeType)h FN(\(data)g(in)i (types\),)e(141)1992 4467 y(TZ,)g(419,)h(420)1992 4566 y FJ(tzinfo)2158 4666 y FN(class)h(in)f(datetime,)f(96)2158 4765 y(datetime)g(attrib)n(ute,)h(102)2158 4865 y(time)g(attrib)n(ute,) f(106)1992 4965 y FJ(tzname\(\))2158 5064 y FN(datetime)g(method,)g (104)2158 5164 y(time)h(method,)e(107,)i(108)1992 5264 y FJ(tzname)f FN(\(data)h(in)g(time\),)g(419)1992 5363 y FJ(tzset\(\))f FN(\(in)h(module)f(time\),)h(419)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1027)p eop end %%Page: 1028 1040 TeXDict begin 1028 1039 bop 0 86 a FE(U)0 210 y FJ(U)21 b FN(\(data)e(in)i(re\),)e(57)0 309 y(u-LA)-7 b(W)f(,)20 b(693,)f(699,)g(707,)g(931)0 409 y FJ(ucd_3_2_0)g FN(\(data)h(in)g (unicodedata\),)d(91)0 509 y FJ(ugettext\(\))166 608 y FN(GNUT)m(ranslations)i(method,)g(744)166 708 y(NullT)m(ranslations)g (method,)g(742)0 807 y FJ(uid\(\))h FN(\(IMAP4)p 553 807 25 4 v 28 w(stream)h(method\),)d(646)0 907 y FJ(uid)i FN(\(T)-7 b(arInfo)19 b(attrib)n(ute\),)g(356)0 1007 y FJ(uidl\(\))h FN(\(POP3)p 547 1007 V 29 w(SSL)h(method\),)d(641)0 1106 y FJ(ulaw2lin\(\))h FN(\(in)h(module)f(audioop\),)e(695)0 1206 y FJ(umask\(\))i FN(\(in)h(module)f(os\),)h(398)0 1306 y FJ(uname\(\))166 1405 y FN(in)g(module)f(os,)i(398)166 1505 y(in)f(module)f(platform,)g(493)0 1604 y FJ(uname)h FN(\(T)-7 b(arInfo)18 b(attrib)n(ute\),)h(356)0 1704 y FJ(UnboundLocalError)f FN(\(e)o(xception)g(in)i(e)o(xceptions\),)e (20)0 1804 y FJ(UnboundMethodType)g FN(\(data)h(in)i(types\),)e(142)0 1903 y(unb)n(uf)n(fered)e(I/O,)j(10)0 2003 y(UNC)h(paths)166 2103 y(and)f FJ(os.makedirs\(\))p FN(,)e(404)0 2202 y FJ(unconsumed_tail)g FN(\()i(attrib)n(ute\),)g(344)0 2302 y FJ(unctrl\(\))166 2401 y FN(in)g(module)f(curses,)h(477)166 2501 y(in)g(module)f(curses.ascii,)h(490)0 2601 y FJ(Underflow)f FN(\(class)i(in)f(decimal\),)f(163)0 2700 y FJ(undoc_header)g FN(\(Cmd)g(attrib)n(ute\),)h(759)0 2800 y FJ(unescape\(\))f FN(\(in)h(module)f(xml.sax.saxutils\),)f(294)0 2900 y FJ(UnexpectedException)f FN(\(e)o(xception)h(in)i(doctest\),)g(788)0 2999 y FJ(unfreeze_form\(\))e FN(\(form)h(method\),)f(921)0 3099 y FJ(unfreeze_object\(\))g FN(\(FORMS)i(object)g(method\),)e(923)0 3198 y FJ(ungetch\(\))166 3298 y FN(in)i(module)f(curses,)h(478)166 3398 y(in)g(module)f(msvcrt,)h(940)0 3497 y FJ(ungetmouse\(\))f FN(\(in)h(module)e(curses\),)i(478)0 3597 y FJ(ungettext\(\))166 3697 y FN(GNUT)m(ranslations)f(method,)g(744)166 3796 y(NullT)m(ranslations)g(method,)g(742)0 3896 y FJ(unhexlify\(\))g FN(\(in)h(module)f(binascii\),)g(254)0 3995 y FJ(unichr\(\))g FN(\(in)h(module)f(\),)h(15)0 4095 y FJ(UNICODE)f FN(\(data)h(in)h (re\),)e(57)0 4195 y(Unicode,)g(77,)g(90)166 4294 y(database,)g(90)166 4394 y(object,)g(27)0 4494 y FJ(unicode\(\))g FN(\(in)h(module)f(\),)h (16)0 4593 y FJ(unicodedata)f FN(\(standard)f(module\),)h FL(90)0 4693 y FJ(UnicodeDecodeError)e FN(\(e)o(xception)h(in)j(e)o (xceptions\),)d(21)0 4792 y FJ(UnicodeEncodeError)f FN(\(e)o(xception)h (in)j(e)o(xceptions\),)d(21)0 4892 y FJ(UnicodeError)h FN(\(e)o(xception)e(in)k(e)o(xceptions\),)d(21)0 4992 y FJ(UnicodeTranslateError)72 b FN(\(e)o(xception)i(in)h(e)o(xcep-)332 5091 y(tions\),)20 b(21)0 5191 y FJ(UnicodeType)f FN(\(data)g(in)i (types\),)e(141)0 5291 y FJ(UnicodeWarning)f FN(\(e)o(xception)g(in)i (e)o(xceptions\),)e(21)0 5390 y FJ(unidata_version)g FN(\(data)i(in)g(unicodedata\),)d(91)1992 83 y FJ(unified_diff\(\))h FN(\(in)i(module)e(dif)n(\003ib\),)i(68)1992 183 y FJ(uniform\(\))f FN(\(in)h(module)e(random\),)g(170)1992 282 y FJ(UnimplementedFileMode) 57 b FN(\(e)o(xception)h(in)j(httplib\),)2324 382 y(633)1992 482 y FJ(Union)19 b FN(\(class)i(in)f(ctypes\),)g(533)1992 581 y FJ(unittest)f FN(\(standard)f(module\),)h FL(789)1994 681 y FN(U)t FH(N)t(I)t(X)2158 780 y FN(\002le)h(control,)f(560)2158 880 y(I/O)h(control,)f(560)1992 980 y FJ(unixfrom)g FN(\(AddressList)g (attrib)n(ute\),)h(250)1992 1079 y FJ(UnixMailbox)e FN(\(class)j(in)f (mailbox\),)f(234)1992 1179 y FJ(unknown_charref\(\))e FN(\(SGMLP)o(arser)i(method\),)g(261)1992 1279 y FJ(unknown_endtag\(\)) e FN(\(SGMLP)o(arser)j(method\),)e(261)1992 1378 y FJ (unknown_entityref\(\))f FN(\(SGMLP)o(arser)i(method\),)f(261)1992 1478 y FJ(unknown_open\(\))2158 1577 y FN(BaseHandler)h(method,)g(627) 2158 1677 y(HTTPErrorProcessor)e(method,)h(630)2158 1777 y(Unkno)n(wnHandler)e(method,)j(630)1992 1876 y FJ (unknown_starttag\(\))e FN(\(SGMLP)o(arser)i(method\),)f(261)1992 1976 y FJ(UnknownHandler)g FN(\(class)i(in)h(urllib2\),)d(624)1992 2076 y FJ(UnknownProtocol)f FN(\(e)o(xception)h(in)j(httplib\),)e(633) 1992 2175 y FJ(UnknownTransferEncoding)k FN(\(e)o(xception)i(in)j (httplib\),)2324 2275 y(633)1992 2374 y FJ(unlink\(\))2158 2474 y FN(in)20 b(module)f(os,)h(407)2158 2574 y(Node)f(method,)g(284) 1992 2673 y FJ(unlock\(\))2158 2773 y FN(Babyl)h(method,)e(225)2158 2873 y(Mailbox)h(method,)f(221)2158 2972 y(Maildir)h(method,)g(222)2158 3072 y(mbox)f(method,)h(223)2158 3171 y(MH)h(method,)f(224)2158 3271 y(MMDF)h(method,)f(226)2158 3371 y(mute)o(x)g(method,)f(133)1992 3470 y FJ(unmimify\(\))g FN(\(in)i(module)f(mimify\),)g(244)1992 3570 y FJ(unpack\(\))2158 3670 y FN(in)h(module)f(struct,)h(63)2158 3769 y(Struct)g(method,)e(65)1992 3869 y FJ(unpack_array\(\))g FN(\(Unpack)o(er)g(method\),)g(317)1992 3968 y FJ(unpack_bytes\(\))g FN(\(Unpack)o(er)g(method\),)g(317)1992 4068 y FJ(unpack_double\(\))f FN(\(Unpack)o(er)i(method\),)f(316)1992 4168 y FJ(unpack_farray\(\))f FN(\(Unpack)o(er)i(method\),)f(317)1992 4267 y FJ(unpack_float\(\))g FN(\(Unpack)o(er)g(method\),)g(316)1992 4367 y FJ(unpack_fopaque\(\))f FN(\(Unpack)o(er)i(method\),)f(317)1992 4467 y FJ(unpack_from\(\))2158 4566 y FN(in)i(module)f(struct,)h(63)2158 4666 y(Struct)g(method,)e(65) 1992 4765 y FJ(unpack_fstring\(\))f FN(\(Unpack)o(er)i(method\),)f(316) 1992 4865 y FJ(unpack_list\(\))g FN(\(Unpack)o(er)g(method\),)g(317) 1992 4965 y FJ(unpack_opaque\(\))f FN(\(Unpack)o(er)i(method\),)f(317) 1992 5064 y FJ(unpack_string\(\))f FN(\(Unpack)o(er)i(method\),)f(317) 1992 5164 y FJ(Unpacker)h FN(\(class)i(in)f(xdrlib\),)e(315)1992 5264 y FJ(unparsedEntityDecl\(\))70 b FN(\(DTDHandler)j(method\),)2324 5363 y(293)p 0 5549 3901 4 v 0 5649 a FI(1028)3515 b(Inde)n(x)p eop end %%Page: 1029 1041 TeXDict begin 1029 1040 bop 0 83 a FJ(UnparsedEntityDeclHandler\(\))199 b FN(\(xmlparser)332 183 y(method\),)18 b(267)0 282 y FJ(Unpickler)h FN(\(class)i(in)f(pickle\),)f(362)0 382 y FJ(UnpicklingError)f FN(\(e)o(xception)g(in)i(pickle\),)f(362)0 482 y FJ(unqdevice\(\))g FN(\(in)h(module)f(\003\),)h(920)0 581 y FJ(unquote\(\))166 681 y FN(in)g(module)f(email.utils,)h(207)166 780 y(in)g(module)f(rfc822,)f(248)166 880 y(in)i(module)f(urllib,)h (619)0 980 y FJ(unquote_plus\(\))e FN(\(in)i(module)f(urllib\),)g(619)0 1079 y FJ(unregister\(\))g FN(\()h(method\),)e(536)0 1179 y FJ(unregister_dialect\(\))f FN(\(in)j(module)f(csv\),)h(304)0 1279 y FJ(unsetenv\(\))f FN(\(in)h(module)f(os\),)h(398)0 1378 y FJ(unsubscribe\(\))e FN(\(IMAP4)p 951 1378 25 4 v 29 w(stream)i(method\),)e(647)0 1478 y FJ(untokenize\(\))h FN(\(in)h(module)e(tok)o(enize\),)h(884)0 1577 y FJ(untouchwin\(\))g FN(\(windo)n(w)f(method\),)h(483)0 1677 y FJ(unused_data)g FN(\()h(attrib)n(ute\),)f(344)0 1777 y FJ(up\(\))h FN(\(in)g(module)f (turtle\),)g(731)0 1876 y FJ(update\(\))166 1976 y FN(dictionary)f (method,)h(37)166 2076 y(hash)h(method,)f(320)166 2175 y(hmac)h(method,)e(321)166 2275 y(Mailbox)h(method,)g(221)166 2374 y(Maildir)h(method,)e(222)166 2474 y(md5)h(method,)g(322)166 2574 y(sha)h(method,)f(323)0 2673 y FJ(update_panels\(\))f FN(\(in)i(module)f(curses.panel\),)f(491)0 2773 y FJ (update_visible\(\))g FN(\(BabylMessage)h(method\),)f(231)0 2873 y FJ(update_wrapper\(\))g FN(\(in)i(module)f(functools\),)f(181)0 2972 y FJ(upper\(\))166 3072 y FN(in)i(module)f(string,)h(52)166 3171 y(string)g(method,)e(32)0 3271 y FJ(uppercase)h FN(\(data)h(in)g(string\),)f(48)0 3371 y FJ(urandom\(\))g FN(\(in)h(module)f(os\),)h(415)0 3470 y(URL,)h(313,)e(602,)g(617,)g (661,)g(667)166 3570 y(parsing,)g(661)166 3670 y(relati)n(v)o(e,)g(661) 0 3769 y FJ(url)h FN(\(Serv)o(erProxy)d(attrib)n(ute\),)j(686)0 3869 y FJ(url2pathname\(\))e FN(\(in)i(module)f(urllib\),)g(619)0 3968 y FJ(urlcleanup\(\))g FN(\(in)h(module)e(urllib\),)h(619)0 4068 y FJ(urldefrag\(\))g FN(\(in)h(module)f(urlparse\),)f(663)0 4168 y FJ(urlencode\(\))h FN(\(in)h(module)f(urllib\),)g(619)0 4267 y FJ(URLError)g FN(\(e)o(xception)f(in)j(urllib2\),)d(623)0 4367 y FJ(urljoin\(\))h FN(\(in)h(module)f(urlparse\),)f(663)0 4467 y FJ(urllib)i FN(\(standard)e(module\),)h FL(617)p FN(,)g(632)0 4566 y FJ(urllib2)g FN(\(standard)g(module\),)f FL(622)0 4666 y FJ(urlopen\(\))166 4765 y FN(in)i(module)f(urllib,)h (617)166 4865 y(in)g(module)f(urllib2,)g(622)0 4965 y FJ(URLopener)g FN(\(class)i(in)f(urllib\),)f(619)0 5064 y FJ(urlparse\(\))g FN(\(in)h(module)f(urlparse\),)f(661)0 5164 y FJ(urlparse)h FN(\(standard)g(module\),)f(621,)h FL(661)0 5264 y FJ(urlretrieve\(\))f FN(\(in)i(module)f(urllib\),)g (618)0 5363 y FJ(urlsafe_b64decode\(\))e FN(\(in)j(module)f(base64\),)g (251)1992 83 y FJ(urlsafe_b64encode\(\))e FN(\(in)j(module)f(base64\),) f(251)1992 183 y FJ(urlsplit\(\))g FN(\(in)i(module)f(urlparse\),)g (662)1992 282 y FJ(urlunparse\(\))f FN(\(in)i(module)f(urlparse\),)f (662)1992 382 y FJ(urlunsplit\(\))g FN(\(in)i(module)f(urlparse\),)f (663)1992 482 y FJ(urn)i FN(\(UUID)g(attrib)n(ute\),)f(659)1992 581 y FJ(use_default_colors\(\))e FN(\(in)j(module)e(curses\),)i(478) 1992 681 y FJ(use_env\(\))f FN(\(in)h(module)e(curses\),)i(478)1992 780 y FJ(use_rawinput)e FN(\(Cmd)i(attrib)n(ute\),)f(759)1992 880 y FJ(UseForeignDTD\(\))e FN(\(xmlparser)i(method\),)f(265)1992 980 y(USER,)i(472)1992 1079 y(user)2158 1179 y(con\002guration)d (\002le,)k(851)2158 1279 y(ef)n(fecti)n(v)o(e)d(id,)i(396)2158 1378 y(id,)g(397)2158 1478 y(id,)g(setting,)g(398)1992 1577 y FJ(user\(\))f FN(\(POP3)p 2538 1577 V 29 w(SSL)i(method\),)d (641)1992 1677 y FJ(user)i FN(\(standard)e(module\),)g FL(851)1992 1777 y FJ(UserDict)2158 1876 y FN(class)j(in)f(UserDict,)g (138)2158 1976 y(standard)f(module,)f FL(138)1992 2076 y FJ(UserList)2158 2175 y FN(class)j(in)f(UserList,)g(139)2158 2275 y(standard)f(module,)f FL(139)1992 2374 y FN(USERN)m(AME,)i(472) 1992 2474 y FJ(userptr\(\))f FN(\()h(method\),)e(492)1992 2574 y FJ(UserString)2158 2673 y FN(class)j(in)f(UserString,)f(140)2158 2773 y(standard)g(module,)f FL(140)1992 2873 y FJ(UserWarning)g FN(\(e)o(xception)g(in)j(e)o(xceptions\),)c(21)1992 2972 y(UTC,)j(415)1992 3072 y FJ(utcfromtimestamp\(\))d FN(\(datetime)i (method\),)f(102)1992 3171 y FJ(utcnow\(\))h FN(\(datetime)g(method\),) f(101)1992 3271 y FJ(utcoffset\(\))2158 3371 y FN(datetime)h(method,)g (104)2158 3470 y(time)h(method,)e(107)1992 3570 y FJ(utctimetuple\(\))g FN(\(datetime)h(method\),)f(104)1992 3670 y FJ(utime\(\))h FN(\(in)h(module)f(os\),)h(407)1992 3769 y FJ(uu)g FN(\(standard)f (module\),)f(253,)h FL(256)1992 3869 y FJ(UUID)h FN(\(class)g(in)h (uuid\),)d(659)1992 3968 y FJ(uuid)i FN(\(b)n(uilt-in)f(module\),)f FL(658)1992 4068 y FN(uuid1,)g(660)1992 4168 y FJ(uuid1\(\))h FN(\(in)h(module)f(uuid\),)g(660)1992 4267 y(uuid3,)f(660)1992 4367 y FJ(uuid3\(\))h FN(\(in)h(module)f(uuid\),)g(660)1992 4467 y(uuid4,)f(660)1992 4566 y FJ(uuid4\(\))h FN(\(in)h(module)f (uuid\),)g(660)1992 4666 y(uuid5,)f(660)1992 4765 y FJ(uuid5\(\))h FN(\(in)h(module)f(uuid\),)g(660)1992 4865 y FJ(UUIDCreate\(\))f FN(\(in)i(module)f(msilib\),)h(933)1992 5058 y FE(V)1992 5181 y FJ(validator\(\))e FN(\(in)i(module)f(wsgiref.v)n(alidate\),)f (614)1992 5280 y(v)n(alue)2158 5380 y(truth,)h(23)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1029)p eop end %%Page: 1030 1042 TeXDict begin 1030 1041 bop 0 83 a FJ(value)p 171 183 25 4 v 196 183 a FN(SimpleCData)20 b(attrib)n(ute,)g(531)166 282 y(Cookie)g(attrib)n(ute,)f(678)166 382 y(Morsel)h(attrib)n(ute,)g (681)0 482 y FJ(value_decode\(\))e FN(\(BaseCookie)i(method\),)e(681)0 581 y FJ(value_encode\(\))g FN(\(BaseCookie)i(method\),)e(681)0 681 y FJ(ValueError)h FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(21)0 780 y FJ(valuerefs\(\))h FN(\(W)-7 b(eakV)e(alueDictionary)17 b(method\),)h(136)0 880 y(v)n(alues)166 980 y(Boolean,)h(44)0 1079 y FJ(values\(\))166 1179 y FN(dictionary)f(method,)h(37)166 1279 y(Mailbox)g(method,)g(220)166 1378 y(Message)h(method,)f(192)0 1478 y FJ(variant)g FN(\(UUID)h(attrib)n(ute\),)g(659)0 1577 y FJ(varray\(\))f FN(\(in)h(module)f(gl\),)h(926)0 1677 y FJ(vars\(\))g FN(\(in)g(module)e(\),)j(16)0 1777 y FJ(vbar)f FN(\(ScrolledT)-6 b(e)o(xt)18 b(attrib)n(ute\),)h(730)0 1876 y FJ(VERBOSE)g FN(\(data)h(in)h(re\),)e(58)0 1976 y FJ(verbose)166 2076 y FN(data)h(in)g(tabnann)o(y)-5 b(,)18 b(885)166 2175 y(data)i(in)g(test.test)p 666 2175 V 31 w(support,)e(804)0 2275 y FJ(verify\(\))h FN(\(SMTP)i(method\),)d (653)0 2374 y FJ(verify_request\(\))g FN(\(in)i(module)f(Sock)o(etServ) o(er\),)e(667)0 2474 y FJ(version\(\))i FN(\(in)h(module)f(platform\),) f(493)0 2574 y FJ(version)166 2673 y FN(Cookie)i(attrib)n(ute,)f(678) 166 2773 y(data)h(in)g(curses,)g(483)166 2873 y(data)g(in)g(httplib,)g (636)166 2972 y(data)g(in)g(marshal,)g(375)166 3072 y(data)g(in)g(sys,) h(833)166 3171 y(URLopener)e(attrib)n(ute,)g(621)166 3271 y(UUID)h(attrib)n(ute,)g(659)0 3371 y FJ(version_info)f FN(\(data)g(in)i(sys\),)f(833)0 3470 y FJ(version_string\(\))177 b FN(\(BaseHTTPRequestHandler)332 3570 y(method\),)18 b(670)0 3670 y FJ(vline\(\))h FN(\(windo)n(w)g(method\),)f(483)0 3769 y FJ(vnarray\(\))h FN(\(in)h(module)f(gl\),)h(926)0 3869 y FJ(voidcmd\(\))f FN(\(FTP)i(method\),)d(638)0 3968 y FJ(volume)i FN(\(ZipInfo)e(attrib)n(ute\),)h(351)0 4068 y FJ(vonmisesvariate\(\))f FN(\(in)i(module)e(random\),)g(171)0 4261 y FE(W)0 4384 y FJ(W_OK)i FN(\(data)g(in)g(os\),)g(402)0 4483 y FJ(wait\(\))166 4583 y FN(Condition)f(method,)g(542)166 4683 y(Ev)o(ent)g(method,)g(544)166 4782 y(in)h(module)f(os,)i(412)166 4882 y(Popen4)e(method,)f(591)166 4982 y(Popen)h(method,)g(573)0 5081 y FJ(wait3\(\))g FN(\(in)h(module)f(os\),)h(413)0 5181 y FJ(wait4\(\))f FN(\(in)h(module)f(os\),)h(413)0 5280 y FJ(waitpid\(\))f FN(\(in)h(module)f(os\),)h(412)0 5380 y FJ(walk\(\))2158 83 y FN(in)g(module)f(compiler)m(,)f(897)2158 183 y(in)i(module)f(compiler)-5 b(.visitor)m(,)17 b(903)2158 282 y(in)j(module)f(os,)h(407)2158 382 y(in)g(module)f(os.path,)g(328) 2158 482 y(Message)h(method,)e(195)1992 581 y FJ(want)i FN(\(Example)e(attrib)n(ute\),)h(781)1992 681 y FJ(warn\(\))g FN(\(in)h(module)f(w)o(arnings\),)g(836)1992 780 y FJ (warn_explicit\(\))e FN(\(in)j(module)f(w)o(arnings\),)g(836)1992 880 y FJ(Warning)g FN(\(e)o(xception)f(in)i(e)o(xceptions\),)e(21)1992 980 y FJ(warning\(\))2178 1079 y FN(method,)h(455)2158 1179 y(ErrorHandler)e(method,)h(293)2158 1279 y(in)i(module)f(logging,) f(452)1992 1378 y(w)o(arnings,)h(834)1992 1478 y FJ(warnings)g FN(\(standard)f(module\),)h FL(834)1992 1577 y FJ(warnoptions)f FN(\(data)i(in)g(sys\),)h(833)1992 1677 y FJ(wasSuccessful\(\))c FN(\(T)-6 b(estResult)21 b(method\),)d(799)1992 1777 y FJ(wave)i FN(\(standard)e(module\),)g FL(702)1992 1876 y FJ(WCONTINUED)g FN(\(data)i(in)g(os\),)g(413)1992 1976 y FJ(WCOREDUMP\(\))e FN(\(in)i(module)f(os\),)h(413)1992 2076 y FJ(WeakKeyDictionary)d FN(\(class)k(in)f(weakref\),)f(136)1992 2175 y FJ(weakref)g FN(\(e)o(xtension)f(module\),)h FL(134)1992 2275 y FJ(WeakValueDictionary)e FN(\(class)k(in)f(weakref\),)e(136)1992 2374 y FJ(webbrowser)g FN(\(standard)h(module\),)f FL(599)1992 2474 y FJ(weekday\(\))2158 2574 y FN(date)i(method,)e(100)2158 2673 y(datetime)h(method,)g(105)2158 2773 y(in)h(module)f(calendar)m(,) f(115)1992 2873 y FJ(weekheader\(\))g FN(\(in)i(module)f(calendar\),)f (116)1992 2972 y FJ(weibullvariate\(\))f FN(\(in)j(module)f(random\),)f (171)1992 3072 y FJ(WEXITSTATUS\(\))g FN(\(in)i(module)f(os\),)h(413) 1992 3171 y FJ(wfile)f FN(\(BaseHTTPRequestHandler)g(attrib)n(ute\),)g (668)1992 3271 y FJ(what\(\))2158 3371 y FN(in)h(module)f(imghdr)m(,)f (706)2158 3470 y(in)i(module)f(sndhdr)m(,)f(707)1992 3570 y FJ(whathdr\(\))h FN(\(in)h(module)e(sndhdr\),)h(707)1992 3670 y FJ(whichdb\(\))g FN(\(in)h(module)e(whichdb\),)g(376)1992 3769 y FJ(whichdb)h FN(\(standard)g(module\),)f FL(376)1992 3869 y FJ(while)2158 3968 y FN(statement,)h(23)1992 4068 y FJ(whitespace)2158 4168 y FN(data)h(in)g(string,)g(48)2158 4267 y(shle)o(x)f(attrib)n(ute,)h(761)1992 4367 y FJ(whitespace_split)d FN(\(shle)o(x)j(attrib)n(ute\),)f(761)1992 4467 y FJ(whseed\(\))g FN(\(in)h(module)f(random\),)e(171)1992 4566 y FJ(WichmannHill)h FN(\(class)j(in)f(random\),)e(171)1992 4666 y FJ(width\(\))h FN(\(in)h(module)f(turtle\),)g(731)1992 4765 y FJ(width)g FN(\(T)-6 b(e)o(xtWrapper)18 b(attrib)n(ute\),)h(76)1992 4865 y FJ(WIFCONTINUED\(\))f FN(\(in)i(module)e(os\),)i(413)1992 4965 y FJ(WIFEXITED\(\))e FN(\(in)i(module)f(os\),)h(413)1992 5064 y FJ(WIFSIGNALED\(\))e FN(\(in)i(module)f(os\),)h(413)1992 5164 y FJ(WIFSTOPPED\(\))e FN(\(in)i(module)f(os\),)h(413)1992 5264 y(W)m(imp$ScrapDir)m(,)d(336)1992 5363 y FJ(win32_ver\(\))h FN(\(in)i(module)f(platform\),)f(493)p 0 5549 3901 4 v 0 5649 a FI(1030)3515 b(Inde)n(x)p eop end %%Page: 1031 1043 TeXDict begin 1031 1042 bop 0 83 a FJ(WinDLL)20 b FN(\(class)g(in)h (ctypes\),)e(523)0 183 y FJ(window\(\))g FN(\()i(method\),)d(492)0 282 y(windo)n(w)h(manager)g(\(widgets\),)g(721)0 382 y FJ(window_height\(\))f FN(\(in)i(module)f(turtle\),)g(732)0 482 y FJ(window_width\(\))f FN(\(in)i(module)f(turtle\),)g(732)0 581 y(W)m(indo)n(ws)h(ini)g(\002le,)h(310)0 681 y FJ(WindowsError)e FN(\(e)o(xception)e(in)k(e)o(xceptions\),)d(21)0 780 y FJ(WinError\(\))h FN(\(in)h(module)f(ctypes\),)g(529)0 880 y FJ(WINFUNCTYPE\(\))f FN(\(in)i(module)f(ctypes\),)g(526)0 980 y(W)m(inSock,)g(536)0 1079 y FJ(winsound)g FN(\(b)n(uilt-in)g (module\),)g FL(945)0 1179 y FJ(winver)h FN(\(data)f(in)i(sys\),)f(833) 0 1279 y FJ(WNOHANG)f FN(\(data)h(in)h(os\),)e(413)0 1378 y FJ(wordchars)g FN(\(shle)o(x)g(attrib)n(ute\),)h(761)0 1478 y(W)-7 b(orld)20 b(W)m(ide)g(W)-7 b(eb,)21 b(313,)e(599,)g(617,)g (661)0 1577 y FJ(wrap\(\))166 1677 y FN(in)h(module)f(te)o(xtwrap,)g (75)166 1777 y(T)-6 b(e)o(xtWrapper)18 b(method,)h(77)0 1876 y FJ(wrapper\(\))g FN(\(in)h(module)f(curses.wrapper\),)e(488)0 1976 y FJ(wraps\(\))i FN(\(in)h(module)f(functools\),)f(181)0 2076 y FJ(writable\(\))166 2175 y FN(async)p 361 2175 25 4 v 29 w(chat)i(method,)f(597)166 2275 y(dispatcher)g(method,)g(593) 0 2374 y FJ(write\(\))187 2474 y FN(method,)f(548,)h(584)166 2574 y(array)g(method,)g(127)166 2673 y(audio)g(de)n(vice)h(method,)e (708,)h(932)166 2773 y(BZ2File)i(method,)d(347)166 2873 y(ElementT)m(ree)h(method,)f(301)166 2972 y(\002le)j(method,)d(41)166 3072 y(Generator)h(method,)f(199)166 3171 y(in)i(module)f(img\002le,)h (928)166 3271 y(in)g(module)f(os,)i(401)166 3371 y(in)f(module)f (turtle,)h(731)166 3470 y(Interacti)n(v)o(eConsole)e(method,)g(856)166 3570 y(SafeCon\002gP)o(arser)h(method,)f(312)166 3670 y(StreamWriter)i(method,)e(83)166 3769 y(T)-6 b(elnet)20 b(method,)f(657)166 3869 y(ZipFile)h(method,)f(349)0 3968 y FJ(write_byte\(\))g FN(\()h(method\),)e(549)0 4068 y FJ(write_history_file\(\))f FN(\(in)j(module)f(readline\),)f (549)0 4168 y FJ(writeall\(\))h FN(\(audio)g(de)n(vice)g(method\),)f (708)0 4267 y FJ(writeframes\(\))166 4367 y FN(aifc)i(method,)f(699)166 4467 y(A)-5 b(U)p 286 4467 V 30 w(write)21 b(method,)d(701)166 4566 y(W)-7 b(a)n(v)o(e)p 355 4566 V 30 w(write)20 b(method,)f(703)0 4666 y FJ(writeframesraw\(\))166 4765 y FN(aifc)h(method,)f(699)166 4865 y(A)-5 b(U)p 286 4865 V 30 w(write)21 b(method,)d(701)166 4965 y(W)-7 b(a)n(v)o(e)p 355 4965 V 30 w(write)20 b(method,)f(703)0 5064 y FJ(writelines\(\))166 5164 y FN(BZ2File)i(method,)d(347)166 5264 y(\002le)j(method,)d(41)166 5363 y(StreamWriter)i(method,)e(83) 1992 83 y FJ(writepy\(\))h FN(\(PyZipFile)g(method\),)f(350)1992 183 y FJ(writer\(\))h FN(\(in)h(module)f(csv\),)g(304)1992 282 y FJ(writer)g FN(\(formatter)f(attrib)n(ute\),)i(909)1992 382 y FJ(writerow\(\))e FN(\(csv)i(writer)g(method\),)f(307)1992 482 y FJ(writerows\(\))f FN(\(csv)i(writer)g(method\),)f(307)1992 581 y FJ(writesamps\(\))f FN(\(audio)h(port)g(method\),)g(915)1992 681 y FJ(writestr\(\))f FN(\(ZipFile)i(method\),)f(350)1992 780 y FJ(writexml\(\))f FN(\(Node)i(method\),)e(284)1992 880 y FJ(WrongDocumentErr)f FN(\(e)o(xception)h(in)j(xml.dom\),)c(281) 1992 980 y FJ(wsgi_file_wrapper)g FN(\(BaseHandler)i(attrib)n(ute\),)h (616)1992 1079 y FJ(wsgi_multiprocess)d FN(\(BaseHandler)i(attrib)n (ute\),)h(615)1992 1179 y FJ(wsgi_multithread)d FN(\(BaseHandler)i (attrib)n(ute\),)h(615)1992 1279 y FJ(wsgi_run_once)e FN(\(BaseHandler)h(attrib)n(ute\),)g(615)1992 1378 y FJ(wsgiref)g FN(\(module\),)f FL(610)1992 1478 y FJ(wsgiref.handlers)f FN(\(module\),)h FL(614)1992 1577 y FJ(wsgiref.headers)f FN(\(module\),)h FL(611)1992 1677 y FJ(wsgiref.simple_server)e FN(\(module\),)i FL(612)1992 1777 y FJ(wsgiref.util)g FN(\(module\),)g FL(610)1992 1876 y FJ(wsgiref.validate)f FN(\(module\),)h FL(614)1992 1976 y FJ(WSGIRequestHandler)66 b FN(\(class)k(in)f(wsgiref.simple)p 3849 1976 V 28 w(-)2324 2076 y(serv)o(er\),)18 b(613)1992 2175 y FJ(WSGIServer)g FN(\(class)j(in)g(wsgiref.simple)p 3304 2175 V 28 w(serv)o(er\),)d(613) 1992 2275 y FJ(WSTOPSIG\(\))g FN(\(in)i(module)f(os\),)h(413)1992 2374 y FJ(wstring_at\(\))e FN(\(in)i(module)f(ctypes\),)g(530)1992 2474 y FJ(WTERMSIG\(\))f FN(\(in)i(module)f(os\),)h(413)1992 2574 y FJ(WUNTRACED)f FN(\(data)g(in)i(os\),)f(413)1992 2673 y(WWW)-8 b(,)22 b(313,)d(599,)g(617,)g(661)2158 2773 y(serv)o(er)m(,)f(602,)h(667)1992 2956 y FE(X)1992 3079 y FJ(X)h FN(\(data)g(in)g(re\),)g(58)1992 3178 y FJ(X_OK)g FN(\(data)f(in)i(os\),)f(402)1992 3278 y FJ(xatom\(\))f FN(\(IMAP4)p 2644 3278 V 29 w(stream)h(method\),)e(647)1992 3378 y(XDR,)i(315,)f(360)1992 3477 y FJ(xdrlib)g FN(\(standard)g (module\),)f FL(315)1992 3577 y FJ(xgtitle\(\))h FN(\(NNTP)h(method\),) e(651)1992 3677 y FJ(xhdr\(\))h FN(\(NNTP)h(method\),)f(650)1992 3776 y(XHTML,)g(257)1992 3876 y FJ(XHTML_NAMESPACE)e FN(\(data)j(in)h(xml.dom\),)c(274)1992 3975 y FJ(XML\(\))i FN(\(in)h(module)f(xml.etree.ElementT)m(ree\),)d(300)1992 4075 y FJ(xml.dom)j FN(\(standard)g(module\),)f FL(272)1992 4175 y FJ(xml.dom.minidom)f FN(\(standard)i(module\),)f FL(282)1992 4274 y FJ(xml.dom.pulldom)f FN(\(standard)i(module\),)f FL(287)1992 4374 y FJ(xml.etree.ElementTree)e FN(\(standard)j (module\),)f FL(298)1992 4474 y FJ(xml.parsers.expat)f FN(\(standard)i(module\),)f FL(264)1992 4573 y FJ(xml.sax)h FN(\(standard)g(module\),)f FL(288)1992 4673 y FJ(xml.sax.handler)f FN(\(standard)i(module\),)f FL(289)1992 4772 y FJ(xml.sax.saxutils)f FN(\(standard)i(module\),)f FL(293)1992 4872 y FJ(xml.sax.xmlreader)f FN(\(standard)i(module\),)f FL(294)1992 4972 y FJ(XML_NAMESPACE)g FN(\(data)i(in)g(xml.dom\),)e(274)1992 5071 y FJ (xmlcharrefreplace_errors_errors\(\))166 b FN(\(in)2324 5171 y(module)18 b(codecs\),)h(79)1992 5271 y FJ(XmlDeclHandler\(\))e FN(\(xmlparser)i(method\),)f(267)1992 5370 y FJ(XMLFilterBase)g FN(\(class)j(in)f(xml.sax.saxutils\),)e(294)p 0 5549 3901 4 v 0 5649 a FI(Inde)n(x)3514 b(1031)p eop end %%Page: 1032 1044 TeXDict begin 1032 1043 bop 0 83 a FJ(XMLGenerator)19 b FN(\(class)h(in)h(xml.sax.saxutils\),)d(294)0 183 y FJ(XMLID\(\))h FN(\(in)h(module)f(xml.etree.ElementT)m(ree\),)d(300)0 282 y FJ(XMLNS_NAMESPACE)i FN(\(data)i(in)g(xml.dom\),)e(274)0 382 y FJ(XMLParserType)g FN(\(data)i(in)g(xml.parsers.e)o(xpat\),)d (264)0 482 y FJ(XMLReader)i FN(\(class)i(in)f(xml.sax.xmlreader\),)c (294)0 581 y FJ(xmlrpclib)j FN(\(standard)g(module\),)f FL(684)0 681 y FJ(XMLTreeBuilder)48 b FN(\(class)i(in)g (xml.etree.ElementT)m(ree\),)332 780 y(302)0 880 y FJ(xor\(\))20 b FN(\(in)g(module)f(operator\),)e(184)0 980 y FJ(xover\(\))i FN(\(NNTP)i(method\),)d(651)0 1079 y FJ(xpath\(\))h FN(\(NNTP)i (method\),)d(651)0 1179 y(xrange)166 1279 y(object,)h(27,)h(34)0 1378 y FJ(xrange\(\))166 1478 y FN(b)n(uilt-in)g(function,)e(27,)h(142) 166 1577 y(in)h(module)f(,)i(16)0 1677 y FJ(XRangeType)e FN(\(data)h(in)g(types\),)f(142)0 1777 y FJ(xreadlines\(\))166 1876 y FN(BZ2File)i(method,)d(347)166 1976 y(\002le)j(method,)d(40)0 2159 y FE(Y)0 2282 y FN(Y2K,)i(415)0 2381 y FJ(year)166 2481 y FN(date)g(attrib)n(ute,)g(99)166 2581 y(datetime)g(attrib)n (ute,)f(102)0 2680 y(Y)-8 b(ear)20 b(2000,)e(415)0 2780 y(Y)-8 b(ear)20 b(2038,)e(415)0 2880 y FJ(yeardatescalendar\(\))f FN(\(Calendar)i(method\),)g(114)0 2979 y FJ(yeardays2calendar\(\))e FN(\(Calendar)i(method\),)g(114)0 3079 y FJ(yeardayscalendar\(\))e FN(\(Calendar)j(method\),)e(114)0 3178 y FJ(YESEXPR)h FN(\(data)h(in)h(locale\),)e(753)0 3278 y FJ(yiq_to_rgb\(\))g FN(\(in)h(module)e(colorsys\),)h(705)0 3474 y FE(Z)0 3597 y FJ(ZeroDivisionError)f FN(\(e)o(xception)g(in)i(e)o (xceptions\),)e(21)0 3697 y FJ(zfill\(\))166 3796 y FN(in)i(module)f (string,)h(52)166 3896 y(string)g(method,)e(32)0 3996 y FJ(zip\(\))i FN(\(in)g(module)f(\),)h(16)0 4095 y FJ(ZIP_DEFLATED)f FN(\(data)g(in)i(zip\002le\),)e(348)0 4195 y FJ(ZIP_STORED)g FN(\(data)h(in)g(zip\002le\),)g(348)0 4294 y FJ(ZipFile)f FN(\(class)i(in)g(zip\002le\),)e(348,)g(349)0 4394 y FJ(zipfile)g FN(\(standard)g(module\),)f FL(348)0 4494 y FJ(zipimport)h FN(\(standard)g(module\),)f FL(868)0 4593 y FJ(zipimporter)h FN(\(class)h(in)h(zipimport\),)d(869)0 4693 y FJ(ZipImportError)g FN(\(e)o(xception)g(in)i(zipimport\),)e(869) 0 4793 y FJ(ZipInfo)h FN(\(class)i(in)g(zip\002le\),)e(348)0 4892 y FJ(zlib)h FN(\(b)n(uilt-in)f(module\),)f FL(343)p 0 5549 3901 4 v 0 5649 a FI(1032)3515 b(Inde)n(x)p eop end %%Trailer userdict /end-hook known{end-hook}if %%EOF .