/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pytexdoc / ext / ind / tex

MacOS 8.1

Win98

DOS

view JSON data

view as text

+--------+-------------------------+-------------------------+--------+--------+
|00000000| 5c 64 6f 63 75 6d 65 6e | 74 73 74 79 6c 65 5b 74 |\documen|tstyle[t|
|00000010| 77 6f 73 69 64 65 2c 31 | 31 70 74 2c 6d 79 66 6f |woside,1|1pt,myfo|
|00000020| 72 6d 61 74 5d 7b 72 65 | 70 6f 72 74 7d 0a 0a 25 |rmat]{re|port}..%|
|00000030| 20 58 58 58 20 50 4d 20 | 4d 6f 64 75 6c 61 74 6f | XXX PM |Modulato|
|00000040| 72 0a 0a 5c 74 69 74 6c | 65 7b 45 78 74 65 6e 64 |r..\titl|e{Extend|
|00000050| 69 6e 67 20 61 6e 64 20 | 45 6d 62 65 64 64 69 6e |ing and |Embeddin|
|00000060| 67 20 74 68 65 20 50 79 | 74 68 6f 6e 20 49 6e 74 |g the Py|thon Int|
|00000070| 65 72 70 72 65 74 65 72 | 7d 0a 0a 5c 69 6e 70 75 |erpreter|}..\inpu|
|00000080| 74 7b 62 6f 69 6c 65 72 | 70 6c 61 74 65 7d 0a 0a |t{boiler|plate}..|
|00000090| 25 20 54 65 6c 6c 20 5c | 69 6e 64 65 78 20 74 6f |% Tell \|index to|
|000000a0| 20 61 63 74 75 61 6c 6c | 79 20 77 72 69 74 65 20 | actuall|y write |
|000000b0| 74 68 65 20 2e 69 64 78 | 20 66 69 6c 65 0a 5c 6d |the .idx| file.\m|
|000000c0| 61 6b 65 69 6e 64 65 78 | 0a 0a 5c 62 65 67 69 6e |akeindex|..\begin|
|000000d0| 7b 64 6f 63 75 6d 65 6e | 74 7d 0a 0a 5c 70 61 67 |{documen|t}..\pag|
|000000e0| 65 6e 75 6d 62 65 72 69 | 6e 67 7b 72 6f 6d 61 6e |enumberi|ng{roman|
|000000f0| 7d 0a 0a 5c 6d 61 6b 65 | 74 69 74 6c 65 0a 0a 5c |}..\make|title..\|
|00000100| 69 6e 70 75 74 7b 63 6f | 70 79 72 69 67 68 74 7d |input{co|pyright}|
|00000110| 0a 0a 5c 62 65 67 69 6e | 7b 61 62 73 74 72 61 63 |..\begin|{abstrac|
|00000120| 74 7d 0a 0a 5c 6e 6f 69 | 6e 64 65 6e 74 0a 50 79 |t}..\noi|ndent.Py|
|00000130| 74 68 6f 6e 20 69 73 20 | 61 6e 20 69 6e 74 65 72 |thon is |an inter|
|00000140| 70 72 65 74 65 64 2c 20 | 6f 62 6a 65 63 74 2d 6f |preted, |object-o|
|00000150| 72 69 65 6e 74 65 64 20 | 70 72 6f 67 72 61 6d 6d |riented |programm|
|00000160| 69 6e 67 20 6c 61 6e 67 | 75 61 67 65 2e 20 20 54 |ing lang|uage.  T|
|00000170| 68 69 73 0a 64 6f 63 75 | 6d 65 6e 74 20 64 65 73 |his.docu|ment des|
|00000180| 63 72 69 62 65 73 20 68 | 6f 77 20 74 6f 20 77 72 |cribes h|ow to wr|
|00000190| 69 74 65 20 6d 6f 64 75 | 6c 65 73 20 69 6e 20 43 |ite modu|les in C|
|000001a0| 20 6f 72 20 5c 43 70 70 | 7b 7d 20 74 6f 20 65 78 | or \Cpp|{} to ex|
|000001b0| 74 65 6e 64 20 74 68 65 | 0a 50 79 74 68 6f 6e 20 |tend the|.Python |
|000001c0| 69 6e 74 65 72 70 72 65 | 74 65 72 20 77 69 74 68 |interpre|ter with|
|000001d0| 20 6e 65 77 20 6d 6f 64 | 75 6c 65 73 2e 20 20 54 | new mod|ules.  T|
|000001e0| 68 6f 73 65 20 6d 6f 64 | 75 6c 65 73 20 63 61 6e |hose mod|ules can|
|000001f0| 20 64 65 66 69 6e 65 20 | 6e 65 77 0a 66 75 6e 63 | define |new.func|
|00000200| 74 69 6f 6e 73 20 62 75 | 74 20 61 6c 73 6f 20 6e |tions bu|t also n|
|00000210| 65 77 20 6f 62 6a 65 63 | 74 20 74 79 70 65 73 20 |ew objec|t types |
|00000220| 61 6e 64 20 74 68 65 69 | 72 20 6d 65 74 68 6f 64 |and thei|r method|
|00000230| 73 2e 20 20 54 68 65 20 | 64 6f 63 75 6d 65 6e 74 |s.  The |document|
|00000240| 0a 61 6c 73 6f 20 64 65 | 73 63 72 69 62 65 73 20 |.also de|scribes |
|00000250| 68 6f 77 20 74 6f 20 65 | 6d 62 65 64 20 74 68 65 |how to e|mbed the|
|00000260| 20 50 79 74 68 6f 6e 20 | 69 6e 74 65 72 70 72 65 | Python |interpre|
|00000270| 74 65 72 20 69 6e 20 61 | 6e 6f 74 68 65 72 0a 61 |ter in a|nother.a|
|00000280| 70 70 6c 69 63 61 74 69 | 6f 6e 2c 20 66 6f 72 20 |pplicati|on, for |
|00000290| 75 73 65 20 61 73 20 61 | 6e 20 65 78 74 65 6e 73 |use as a|n extens|
|000002a0| 69 6f 6e 20 6c 61 6e 67 | 75 61 67 65 2e 20 20 46 |ion lang|uage.  F|
|000002b0| 69 6e 61 6c 6c 79 2c 20 | 69 74 20 73 68 6f 77 73 |inally, |it shows|
|000002c0| 20 68 6f 77 0a 74 6f 20 | 63 6f 6d 70 69 6c 65 20 | how.to |compile |
|000002d0| 61 6e 64 20 6c 69 6e 6b | 20 65 78 74 65 6e 73 69 |and link| extensi|
|000002e0| 6f 6e 20 6d 6f 64 75 6c | 65 73 20 73 6f 20 74 68 |on modul|es so th|
|000002f0| 61 74 20 74 68 65 79 20 | 63 61 6e 20 62 65 20 6c |at they |can be l|
|00000300| 6f 61 64 65 64 0a 64 79 | 6e 61 6d 69 63 61 6c 6c |oaded.dy|namicall|
|00000310| 79 20 28 61 74 20 72 75 | 6e 20 74 69 6d 65 29 20 |y (at ru|n time) |
|00000320| 69 6e 74 6f 20 74 68 65 | 20 69 6e 74 65 72 70 72 |into the| interpr|
|00000330| 65 74 65 72 2c 20 69 66 | 20 74 68 65 20 75 6e 64 |eter, if| the und|
|00000340| 65 72 6c 79 69 6e 67 0a | 6f 70 65 72 61 74 69 6e |erlying.|operatin|
|00000350| 67 20 73 79 73 74 65 6d | 20 73 75 70 70 6f 72 74 |g system| support|
|00000360| 73 20 74 68 69 73 20 66 | 65 61 74 75 72 65 2e 0a |s this f|eature..|
|00000370| 0a 54 68 69 73 20 64 6f | 63 75 6d 65 6e 74 20 61 |.This do|cument a|
|00000380| 73 73 75 6d 65 73 20 62 | 61 73 69 63 20 6b 6e 6f |ssumes b|asic kno|
|00000390| 77 6c 65 64 67 65 20 61 | 62 6f 75 74 20 50 79 74 |wledge a|bout Pyt|
|000003a0| 68 6f 6e 2e 20 20 46 6f | 72 20 61 6e 20 69 6e 66 |hon.  Fo|r an inf|
|000003b0| 6f 72 6d 61 6c 0a 69 6e | 74 72 6f 64 75 63 74 69 |ormal.in|troducti|
|000003c0| 6f 6e 20 74 6f 20 74 68 | 65 20 6c 61 6e 67 75 61 |on to th|e langua|
|000003d0| 67 65 2c 20 73 65 65 20 | 74 68 65 20 50 79 74 68 |ge, see |the Pyth|
|000003e0| 6f 6e 20 54 75 74 6f 72 | 69 61 6c 2e 20 20 54 68 |on Tutor|ial.  Th|
|000003f0| 65 20 50 79 74 68 6f 6e | 0a 52 65 66 65 72 65 6e |e Python|.Referen|
|00000400| 63 65 20 4d 61 6e 75 61 | 6c 20 67 69 76 65 73 20 |ce Manua|l gives |
|00000410| 61 20 6d 6f 72 65 20 66 | 6f 72 6d 61 6c 20 64 65 |a more f|ormal de|
|00000420| 66 69 6e 69 74 69 6f 6e | 20 6f 66 20 74 68 65 20 |finition| of the |
|00000430| 6c 61 6e 67 75 61 67 65 | 2e 20 20 54 68 65 0a 50 |language|.  The.P|
|00000440| 79 74 68 6f 6e 20 4c 69 | 62 72 61 72 79 20 52 65 |ython Li|brary Re|
|00000450| 66 65 72 65 6e 63 65 20 | 64 6f 63 75 6d 65 6e 74 |ference |document|
|00000460| 73 20 74 68 65 20 65 78 | 69 73 74 69 6e 67 20 6f |s the ex|isting o|
|00000470| 62 6a 65 63 74 20 74 79 | 70 65 73 2c 0a 66 75 6e |bject ty|pes,.fun|
|00000480| 63 74 69 6f 6e 73 20 61 | 6e 64 20 6d 6f 64 75 6c |ctions a|nd modul|
|00000490| 65 73 20 28 62 6f 74 68 | 20 62 75 69 6c 74 2d 69 |es (both| built-i|
|000004a0| 6e 20 61 6e 64 20 77 72 | 69 74 74 65 6e 20 69 6e |n and wr|itten in|
|000004b0| 20 50 79 74 68 6f 6e 29 | 20 74 68 61 74 20 67 69 | Python)| that gi|
|000004c0| 76 65 0a 74 68 65 20 6c | 61 6e 67 75 61 67 65 20 |ve.the l|anguage |
|000004d0| 69 74 73 20 77 69 64 65 | 20 61 70 70 6c 69 63 61 |its wide| applica|
|000004e0| 74 69 6f 6e 20 72 61 6e | 67 65 2e 0a 0a 5c 65 6e |tion ran|ge...\en|
|000004f0| 64 7b 61 62 73 74 72 61 | 63 74 7d 0a 0a 5c 70 61 |d{abstra|ct}..\pa|
|00000500| 67 65 62 72 65 61 6b 0a | 0a 7b 0a 5c 70 61 72 73 |gebreak.|.{.\pars|
|00000510| 6b 69 70 20 3d 20 30 6d | 6d 0a 5c 74 61 62 6c 65 |kip = 0m|m.\table|
|00000520| 6f 66 63 6f 6e 74 65 6e | 74 73 0a 7d 0a 0a 5c 70 |ofconten|ts.}..\p|
|00000530| 61 67 65 62 72 65 61 6b | 0a 0a 5c 70 61 67 65 6e |agebreak|..\pagen|
|00000540| 75 6d 62 65 72 69 6e 67 | 7b 61 72 61 62 69 63 7d |umbering|{arabic}|
|00000550| 0a 0a 0a 5c 63 68 61 70 | 74 65 72 7b 45 78 74 65 |...\chap|ter{Exte|
|00000560| 6e 64 69 6e 67 20 50 79 | 74 68 6f 6e 20 77 69 74 |nding Py|thon wit|
|00000570| 68 20 43 20 6f 72 20 5c | 43 70 70 7b 7d 20 63 6f |h C or \|Cpp{} co|
|00000580| 64 65 7d 0a 0a 0a 5c 73 | 65 63 74 69 6f 6e 7b 49 |de}...\s|ection{I|
|00000590| 6e 74 72 6f 64 75 63 74 | 69 6f 6e 7d 0a 0a 49 74 |ntroduct|ion}..It|
|000005a0| 20 69 73 20 71 75 69 74 | 65 20 65 61 73 79 20 74 | is quit|e easy t|
|000005b0| 6f 20 61 64 64 20 6e 65 | 77 20 62 75 69 6c 74 2d |o add ne|w built-|
|000005c0| 69 6e 20 6d 6f 64 75 6c | 65 73 20 74 6f 20 50 79 |in modul|es to Py|
|000005d0| 74 68 6f 6e 2c 20 69 66 | 20 79 6f 75 20 6b 6e 6f |thon, if| you kno|
|000005e0| 77 0a 68 6f 77 20 74 6f | 20 70 72 6f 67 72 61 6d |w.how to| program|
|000005f0| 20 69 6e 20 43 2e 20 20 | 53 75 63 68 20 5c 64 66 | in C.  |Such \df|
|00000600| 6e 7b 65 78 74 65 6e 73 | 69 6f 6e 20 6d 6f 64 75 |n{extens|ion modu|
|00000610| 6c 65 73 7d 20 63 61 6e | 20 64 6f 20 74 77 6f 20 |les} can| do two |
|00000620| 74 68 69 6e 67 73 0a 74 | 68 61 74 20 63 61 6e 27 |things.t|hat can'|
|00000630| 74 20 62 65 20 64 6f 6e | 65 20 64 69 72 65 63 74 |t be don|e direct|
|00000640| 6c 79 20 69 6e 20 50 79 | 74 68 6f 6e 3a 20 74 68 |ly in Py|thon: th|
|00000650| 65 79 20 63 61 6e 20 69 | 6d 70 6c 65 6d 65 6e 74 |ey can i|mplement|
|00000660| 20 6e 65 77 20 62 75 69 | 6c 74 2d 69 6e 0a 6f 62 | new bui|lt-in.ob|
|00000670| 6a 65 63 74 20 74 79 70 | 65 73 2c 20 61 6e 64 20 |ject typ|es, and |
|00000680| 74 68 65 79 20 63 61 6e | 20 63 61 6c 6c 20 43 20 |they can| call C |
|00000690| 6c 69 62 72 61 72 79 20 | 66 75 6e 63 74 69 6f 6e |library |function|
|000006a0| 73 20 61 6e 64 20 73 79 | 73 74 65 6d 20 63 61 6c |s and sy|stem cal|
|000006b0| 6c 73 2e 0a 0a 54 6f 20 | 73 75 70 70 6f 72 74 20 |ls...To |support |
|000006c0| 65 78 74 65 6e 73 69 6f | 6e 73 2c 20 74 68 65 20 |extensio|ns, the |
|000006d0| 50 79 74 68 6f 6e 20 41 | 50 49 20 28 41 70 70 6c |Python A|PI (Appl|
|000006e0| 69 63 61 74 69 6f 6e 20 | 50 72 6f 67 72 61 6d 6d |ication |Programm|
|000006f0| 65 72 73 0a 49 6e 74 65 | 72 66 61 63 65 29 20 64 |ers.Inte|rface) d|
|00000700| 65 66 69 6e 65 73 20 61 | 20 73 65 74 20 6f 66 20 |efines a| set of |
|00000710| 66 75 6e 63 74 69 6f 6e | 73 2c 20 6d 61 63 72 6f |function|s, macro|
|00000720| 73 20 61 6e 64 20 76 61 | 72 69 61 62 6c 65 73 20 |s and va|riables |
|00000730| 74 68 61 74 0a 70 72 6f | 76 69 64 65 20 61 63 63 |that.pro|vide acc|
|00000740| 65 73 73 20 74 6f 20 6d | 6f 73 74 20 61 73 70 65 |ess to m|ost aspe|
|00000750| 63 74 73 20 6f 66 20 74 | 68 65 20 50 79 74 68 6f |cts of t|he Pytho|
|00000760| 6e 20 72 75 6e 2d 74 69 | 6d 65 20 73 79 73 74 65 |n run-ti|me syste|
|00000770| 6d 2e 20 20 54 68 65 0a | 50 79 74 68 6f 6e 20 41 |m.  The.|Python A|
|00000780| 50 49 20 69 73 20 69 6e | 63 6f 72 70 6f 72 61 74 |PI is in|corporat|
|00000790| 65 64 20 69 6e 20 61 20 | 43 20 73 6f 75 72 63 65 |ed in a |C source|
|000007a0| 20 66 69 6c 65 20 62 79 | 20 69 6e 63 6c 75 64 69 | file by| includi|
|000007b0| 6e 67 20 74 68 65 20 68 | 65 61 64 65 72 0a 5c 63 |ng the h|eader.\c|
|000007c0| 6f 64 65 7b 22 50 79 74 | 68 6f 6e 2e 68 22 7d 2e |ode{"Pyt|hon.h"}.|
|000007d0| 0a 0a 54 68 65 20 63 6f | 6d 70 69 6c 61 74 69 6f |..The co|mpilatio|
|000007e0| 6e 20 6f 66 20 61 6e 20 | 65 78 74 65 6e 73 69 6f |n of an |extensio|
|000007f0| 6e 20 6d 6f 64 75 6c 65 | 20 64 65 70 65 6e 64 73 |n module| depends|
|00000800| 20 6f 6e 20 69 74 73 20 | 69 6e 74 65 6e 64 65 64 | on its |intended|
|00000810| 20 75 73 65 20 61 73 0a | 77 65 6c 6c 20 61 73 20 | use as.|well as |
|00000820| 6f 6e 20 79 6f 75 72 20 | 73 79 73 74 65 6d 20 73 |on your |system s|
|00000830| 65 74 75 70 3b 20 64 65 | 74 61 69 6c 73 20 61 72 |etup; de|tails ar|
|00000840| 65 20 67 69 76 65 6e 20 | 69 6e 20 61 20 6c 61 74 |e given |in a lat|
|00000850| 65 72 20 73 65 63 74 69 | 6f 6e 2e 0a 0a 0a 5c 73 |er secti|on....\s|
|00000860| 65 63 74 69 6f 6e 7b 41 | 20 53 69 6d 70 6c 65 20 |ection{A| Simple |
|00000870| 45 78 61 6d 70 6c 65 7d | 0a 0a 4c 65 74 27 73 20 |Example}|..Let's |
|00000880| 63 72 65 61 74 65 20 61 | 6e 20 65 78 74 65 6e 73 |create a|n extens|
|00000890| 69 6f 6e 20 6d 6f 64 75 | 6c 65 20 63 61 6c 6c 65 |ion modu|le calle|
|000008a0| 64 20 5c 73 61 6d 70 7b | 73 70 61 6d 7d 20 28 74 |d \samp{|spam} (t|
|000008b0| 68 65 20 66 61 76 6f 72 | 69 74 65 20 66 6f 6f 64 |he favor|ite food|
|000008c0| 0a 6f 66 20 4d 6f 6e 74 | 79 20 50 79 74 68 6f 6e |.of Mont|y Python|
|000008d0| 20 66 61 6e 73 2e 2e 2e | 29 20 61 6e 64 20 6c 65 | fans...|) and le|
|000008e0| 74 27 73 20 73 61 79 20 | 77 65 20 77 61 6e 74 20 |t's say |we want |
|000008f0| 74 6f 20 63 72 65 61 74 | 65 20 61 20 50 79 74 68 |to creat|e a Pyth|
|00000900| 6f 6e 0a 69 6e 74 65 72 | 66 61 63 65 20 74 6f 20 |on.inter|face to |
|00000910| 74 68 65 20 43 20 6c 69 | 62 72 61 72 79 20 66 75 |the C li|brary fu|
|00000920| 6e 63 74 69 6f 6e 20 5c | 63 6f 64 65 7b 73 79 73 |nction \|code{sys|
|00000930| 74 65 6d 28 29 7d 2e 5c | 66 6f 6f 74 6e 6f 74 65 |tem()}.\|footnote|
|00000940| 7b 41 6e 0a 69 6e 74 65 | 72 66 61 63 65 20 66 6f |{An.inte|rface fo|
|00000950| 72 20 74 68 69 73 20 66 | 75 6e 63 74 69 6f 6e 20 |r this f|unction |
|00000960| 61 6c 72 65 61 64 79 20 | 65 78 69 73 74 73 20 69 |already |exists i|
|00000970| 6e 20 74 68 65 20 73 74 | 61 6e 64 61 72 64 20 6d |n the st|andard m|
|00000980| 6f 64 75 6c 65 0a 5c 63 | 6f 64 65 7b 6f 73 7d 20 |odule.\c|ode{os} |
|00000990| 2d 2d 2d 20 69 74 20 77 | 61 73 20 63 68 6f 73 65 |--- it w|as chose|
|000009a0| 6e 20 61 73 20 61 20 73 | 69 6d 70 6c 65 20 61 6e |n as a s|imple an|
|000009b0| 64 20 73 74 72 61 69 67 | 68 74 66 6f 77 61 72 64 |d straig|htfoward|
|000009c0| 20 65 78 61 6d 70 6c 65 | 2e 7d 0a 54 68 69 73 20 | example|.}.This |
|000009d0| 66 75 6e 63 74 69 6f 6e | 20 74 61 6b 65 73 20 61 |function| takes a|
|000009e0| 20 6e 75 6c 6c 2d 74 65 | 72 6d 69 6e 61 74 65 64 | null-te|rminated|
|000009f0| 20 63 68 61 72 61 63 74 | 65 72 20 73 74 72 69 6e | charact|er strin|
|00000a00| 67 20 61 73 20 61 72 67 | 75 6d 65 6e 74 20 61 6e |g as arg|ument an|
|00000a10| 64 0a 72 65 74 75 72 6e | 73 20 61 6e 20 69 6e 74 |d.return|s an int|
|00000a20| 65 67 65 72 2e 20 20 57 | 65 20 77 61 6e 74 20 74 |eger.  W|e want t|
|00000a30| 68 69 73 20 66 75 6e 63 | 74 69 6f 6e 20 74 6f 20 |his func|tion to |
|00000a40| 62 65 20 63 61 6c 6c 61 | 62 6c 65 20 66 72 6f 6d |be calla|ble from|
|00000a50| 20 50 79 74 68 6f 6e 0a | 61 73 20 66 6f 6c 6c 6f | Python.|as follo|
|00000a60| 77 73 3a 0a 0a 5c 62 65 | 67 69 6e 7b 76 65 72 62 |ws:..\be|gin{verb|
|00000a70| 61 74 69 6d 7d 0a 20 20 | 20 20 3e 3e 3e 20 69 6d |atim}.  |  >>> im|
|00000a80| 70 6f 72 74 20 73 70 61 | 6d 0a 20 20 20 20 3e 3e |port spa|m.    >>|
|00000a90| 3e 20 73 74 61 74 75 73 | 20 3d 20 73 70 61 6d 2e |> status| = spam.|
|00000aa0| 73 79 73 74 65 6d 28 22 | 6c 73 20 2d 6c 22 29 0a |system("|ls -l").|
|00000ab0| 5c 65 6e 64 7b 76 65 72 | 62 61 74 69 6d 7d 0a 0a |\end{ver|batim}..|
|00000ac0| 42 65 67 69 6e 20 62 79 | 20 63 72 65 61 74 69 6e |Begin by| creatin|
|00000ad0| 67 20 61 20 66 69 6c 65 | 20 5c 73 61 6d 70 7b 73 |g a file| \samp{s|
|00000ae0| 70 61 6d 6d 6f 64 75 6c | 65 2e 63 7d 2e 20 20 28 |pammodul|e.c}.  (|
|00000af0| 49 6e 20 67 65 6e 65 72 | 61 6c 2c 20 69 66 20 61 |In gener|al, if a|
|00000b00| 0a 6d 6f 64 75 6c 65 20 | 69 73 20 63 61 6c 6c 65 |.module |is calle|
|00000b10| 64 20 5c 73 61 6d 70 7b | 73 70 61 6d 7d 2c 20 74 |d \samp{|spam}, t|
|00000b20| 68 65 20 43 20 66 69 6c | 65 20 63 6f 6e 74 61 69 |he C fil|e contai|
|00000b30| 6e 69 6e 67 20 69 74 73 | 20 69 6d 70 6c 65 6d 65 |ning its| impleme|
|00000b40| 6e 74 61 74 69 6f 6e 0a | 69 73 20 63 61 6c 6c 65 |ntation.|is calle|
|00000b50| 64 20 5c 66 69 6c 65 7b | 73 70 61 6d 6d 6f 64 75 |d \file{|spammodu|
|00000b60| 6c 65 2e 63 7d 3b 20 69 | 66 20 74 68 65 20 6d 6f |le.c}; i|f the mo|
|00000b70| 64 75 6c 65 20 6e 61 6d | 65 20 69 73 20 76 65 72 |dule nam|e is ver|
|00000b80| 79 20 6c 6f 6e 67 2c 20 | 6c 69 6b 65 0a 5c 73 61 |y long, |like.\sa|
|00000b90| 6d 70 7b 73 70 61 6d 6d | 69 66 79 7d 2c 20 74 68 |mp{spamm|ify}, th|
|00000ba0| 65 20 6d 6f 64 75 6c 65 | 20 6e 61 6d 65 20 63 61 |e module| name ca|
|00000bb0| 6e 20 62 65 20 6a 75 73 | 74 20 5c 66 69 6c 65 7b |n be jus|t \file{|
|00000bc0| 73 70 61 6d 6d 69 66 79 | 2e 63 7d 2e 29 0a 0a 54 |spammify|.c}.)..T|
|00000bd0| 68 65 20 66 69 72 73 74 | 20 6c 69 6e 65 20 6f 66 |he first| line of|
|00000be0| 20 6f 75 72 20 66 69 6c | 65 20 63 61 6e 20 62 65 | our fil|e can be|
|00000bf0| 3a 0a 0a 5c 62 65 67 69 | 6e 7b 76 65 72 62 61 74 |:..\begi|n{verbat|
|00000c00| 69 6d 7d 0a 20 20 20 20 | 23 69 6e 63 6c 75 64 65 |im}.    |#include|
|00000c10| 20 22 50 79 74 68 6f 6e | 2e 68 22 0a 5c 65 6e 64 | "Python|.h".\end|
|00000c20| 7b 76 65 72 62 61 74 69 | 6d 7d 0a 0a 77 68 69 63 |{verbati|m}..whic|
|00000c30| 68 20 70 75 6c 6c 73 20 | 69 6e 20 74 68 65 20 50 |h pulls |in the P|
|00000c40| 79 74 68 6f 6e 20 41 50 | 49 20 28 79 6f 75 20 63 |ython AP|I (you c|
|00000c50| 61 6e 20 61 64 64 20 61 | 20 63 6f 6d 6d 65 6e 74 |an add a| comment|
|00000c60| 20 64 65 73 63 72 69 62 | 69 6e 67 20 74 68 65 0a | describ|ing the.|
|00000c70| 70 75 72 70 6f 73 65 20 | 6f 66 20 74 68 65 20 6d |purpose |of the m|
|00000c80| 6f 64 75 6c 65 20 61 6e | 64 20 61 20 63 6f 70 79 |odule an|d a copy|
|00000c90| 72 69 67 68 74 20 6e 6f | 74 69 63 65 20 69 66 20 |right no|tice if |
|00000ca0| 79 6f 75 20 6c 69 6b 65 | 29 2e 0a 0a 41 6c 6c 20 |you like|)...All |
|00000cb0| 75 73 65 72 2d 76 69 73 | 69 62 6c 65 20 73 79 6d |user-vis|ible sym|
|00000cc0| 62 6f 6c 73 20 64 65 66 | 69 6e 65 64 20 62 79 20 |bols def|ined by |
|00000cd0| 5c 63 6f 64 65 7b 22 50 | 79 74 68 6f 6e 2e 68 22 |\code{"P|ython.h"|
|00000ce0| 7d 20 68 61 76 65 20 61 | 20 70 72 65 66 69 78 20 |} have a| prefix |
|00000cf0| 6f 66 0a 5c 73 61 6d 70 | 7b 50 79 7d 20 6f 72 20 |of.\samp|{Py} or |
|00000d00| 5c 73 61 6d 70 7b 50 59 | 7d 2c 20 65 78 63 65 70 |\samp{PY|}, excep|
|00000d10| 74 20 74 68 6f 73 65 20 | 64 65 66 69 6e 65 64 20 |t those |defined |
|00000d20| 69 6e 20 73 74 61 6e 64 | 61 72 64 20 68 65 61 64 |in stand|ard head|
|00000d30| 65 72 20 66 69 6c 65 73 | 2e 0a 46 6f 72 20 63 6f |er files|..For co|
|00000d40| 6e 76 65 6e 69 65 6e 63 | 65 2c 20 61 6e 64 20 73 |nvenienc|e, and s|
|00000d50| 69 6e 63 65 20 74 68 65 | 79 20 61 72 65 20 75 73 |ince the|y are us|
|00000d60| 65 64 20 65 78 74 65 6e | 73 69 76 65 6c 79 20 62 |ed exten|sively b|
|00000d70| 79 20 74 68 65 20 50 79 | 74 68 6f 6e 0a 69 6e 74 |y the Py|thon.int|
|00000d80| 65 72 70 72 65 74 65 72 | 2c 20 5c 63 6f 64 65 7b |erpreter|, \code{|
|00000d90| 22 50 79 74 68 6f 6e 2e | 68 22 7d 20 69 6e 63 6c |"Python.|h"} incl|
|00000da0| 75 64 65 73 20 61 20 66 | 65 77 20 73 74 61 6e 64 |udes a f|ew stand|
|00000db0| 61 72 64 20 68 65 61 64 | 65 72 20 66 69 6c 65 73 |ard head|er files|
|00000dc0| 3a 0a 5c 63 6f 64 65 7b | 3c 73 74 64 69 6f 2e 68 |:.\code{|<stdio.h|
|00000dd0| 3e 7d 2c 20 5c 63 6f 64 | 65 7b 3c 73 74 72 69 6e |>}, \cod|e{<strin|
|00000de0| 67 2e 68 3e 7d 2c 20 5c | 63 6f 64 65 7b 3c 65 72 |g.h>}, \|code{<er|
|00000df0| 72 6e 6f 2e 68 3e 7d 2c | 20 61 6e 64 0a 5c 63 6f |rno.h>},| and.\co|
|00000e00| 64 65 7b 3c 73 74 64 6c | 69 62 2e 68 3e 7d 2e 20 |de{<stdl|ib.h>}. |
|00000e10| 20 49 66 20 74 68 65 20 | 6c 61 74 74 65 72 20 68 | If the |latter h|
|00000e20| 65 61 64 65 72 20 66 69 | 6c 65 20 64 6f 65 73 20 |eader fi|le does |
|00000e30| 6e 6f 74 20 65 78 69 73 | 74 20 6f 6e 20 79 6f 75 |not exis|t on you|
|00000e40| 72 0a 73 79 73 74 65 6d | 2c 20 69 74 20 64 65 63 |r.system|, it dec|
|00000e50| 6c 61 72 65 73 20 74 68 | 65 20 66 75 6e 63 74 69 |lares th|e functi|
|00000e60| 6f 6e 73 20 5c 63 6f 64 | 65 7b 6d 61 6c 6c 6f 63 |ons \cod|e{malloc|
|00000e70| 28 29 7d 2c 20 5c 63 6f | 64 65 7b 66 72 65 65 28 |()}, \co|de{free(|
|00000e80| 29 7d 20 61 6e 64 0a 5c | 63 6f 64 65 7b 72 65 61 |)} and.\|code{rea|
|00000e90| 6c 6c 6f 63 28 29 7d 20 | 64 69 72 65 63 74 6c 79 |lloc()} |directly|
|00000ea0| 2e 0a 0a 54 68 65 20 6e | 65 78 74 20 74 68 69 6e |...The n|ext thin|
|00000eb0| 67 20 77 65 20 61 64 64 | 20 74 6f 20 6f 75 72 20 |g we add| to our |
|00000ec0| 6d 6f 64 75 6c 65 20 66 | 69 6c 65 20 69 73 20 74 |module f|ile is t|
|00000ed0| 68 65 20 43 20 66 75 6e | 63 74 69 6f 6e 20 74 68 |he C fun|ction th|
|00000ee0| 61 74 20 77 69 6c 6c 0a | 62 65 20 63 61 6c 6c 65 |at will.|be calle|
|00000ef0| 64 20 77 68 65 6e 20 74 | 68 65 20 50 79 74 68 6f |d when t|he Pytho|
|00000f00| 6e 20 65 78 70 72 65 73 | 73 69 6f 6e 20 5c 73 61 |n expres|sion \sa|
|00000f10| 6d 70 7b 73 70 61 6d 2e | 73 79 73 74 65 6d 28 5c |mp{spam.|system(\|
|00000f20| 76 61 72 7b 73 74 72 69 | 6e 67 7d 29 7d 0a 69 73 |var{stri|ng})}.is|
|00000f30| 20 65 76 61 6c 75 61 74 | 65 64 20 28 77 65 27 6c | evaluat|ed (we'l|
|00000f40| 6c 20 73 65 65 20 73 68 | 6f 72 74 6c 79 20 68 6f |l see sh|ortly ho|
|00000f50| 77 20 69 74 20 65 6e 64 | 73 20 75 70 20 62 65 69 |w it end|s up bei|
|00000f60| 6e 67 20 63 61 6c 6c 65 | 64 29 3a 0a 0a 5c 62 65 |ng calle|d):..\be|
|00000f70| 67 69 6e 7b 76 65 72 62 | 61 74 69 6d 7d 0a 20 20 |gin{verb|atim}.  |
|00000f80| 20 20 73 74 61 74 69 63 | 20 50 79 4f 62 6a 65 63 |  static| PyObjec|
|00000f90| 74 20 2a 0a 20 20 20 20 | 73 70 61 6d 5f 73 79 73 |t *.    |spam_sys|
|00000fa0| 74 65 6d 28 73 65 6c 66 | 2c 20 61 72 67 73 29 0a |tem(self|, args).|
|00000fb0| 20 20 20 20 20 20 20 20 | 50 79 4f 62 6a 65 63 74 |        |PyObject|
|00000fc0| 20 2a 73 65 6c 66 3b 0a | 20 20 20 20 20 20 20 20 | *self;.|        |
|00000fd0| 50 79 4f 62 6a 65 63 74 | 20 2a 61 72 67 73 3b 0a |PyObject| *args;.|
|00000fe0| 20 20 20 20 7b 0a 20 20 | 20 20 20 20 20 20 63 68 |    {.  |      ch|
|00000ff0| 61 72 20 2a 63 6f 6d 6d | 61 6e 64 3b 0a 20 20 20 |ar *comm|and;.   |
|00001000| 20 20 20 20 20 69 6e 74 | 20 73 74 73 3b 0a 20 20 |     int| sts;.  |
|00001010| 20 20 20 20 20 20 69 66 | 20 28 21 50 79 41 72 67 |      if| (!PyArg|
|00001020| 5f 50 61 72 73 65 54 75 | 70 6c 65 28 61 72 67 73 |_ParseTu|ple(args|
|00001030| 2c 20 22 73 22 2c 20 26 | 63 6f 6d 6d 61 6e 64 29 |, "s", &|command)|
|00001040| 29 0a 20 20 20 20 20 20 | 20 20 20 20 20 20 72 65 |).      |      re|
|00001050| 74 75 72 6e 20 4e 55 4c | 4c 3b 0a 20 20 20 20 20 |turn NUL|L;.     |
|00001060| 20 20 20 73 74 73 20 3d | 20 73 79 73 74 65 6d 28 |   sts =| system(|
|00001070| 63 6f 6d 6d 61 6e 64 29 | 3b 0a 20 20 20 20 20 20 |command)|;.      |
|00001080| 20 20 72 65 74 75 72 6e | 20 50 79 5f 42 75 69 6c |  return| Py_Buil|
|00001090| 64 56 61 6c 75 65 28 22 | 69 22 2c 20 73 74 73 29 |dValue("|i", sts)|
|000010a0| 3b 0a 20 20 20 20 7d 0a | 5c 65 6e 64 7b 76 65 72 |;.    }.|\end{ver|
|000010b0| 62 61 74 69 6d 7d 0a 0a | 54 68 65 72 65 20 69 73 |batim}..|There is|
|000010c0| 20 61 20 73 74 72 61 69 | 67 68 74 66 6f 72 77 61 | a strai|ghtforwa|
|000010d0| 72 64 20 74 72 61 6e 73 | 6c 61 74 69 6f 6e 20 66 |rd trans|lation f|
|000010e0| 72 6f 6d 20 74 68 65 20 | 61 72 67 75 6d 65 6e 74 |rom the |argument|
|000010f0| 20 6c 69 73 74 20 69 6e | 0a 50 79 74 68 6f 6e 20 | list in|.Python |
|00001100| 28 65 2e 67 2e 5c 20 74 | 68 65 20 73 69 6e 67 6c |(e.g.\ t|he singl|
|00001110| 65 20 65 78 70 72 65 73 | 73 69 6f 6e 20 5c 63 6f |e expres|sion \co|
|00001120| 64 65 7b 22 6c 73 20 2d | 6c 22 7d 29 20 74 6f 20 |de{"ls -|l"}) to |
|00001130| 74 68 65 20 61 72 67 75 | 6d 65 6e 74 73 0a 70 61 |the argu|ments.pa|
|00001140| 73 73 65 64 20 74 6f 20 | 74 68 65 20 43 20 66 75 |ssed to |the C fu|
|00001150| 6e 63 74 69 6f 6e 2e 20 | 20 54 68 65 20 43 20 66 |nction. | The C f|
|00001160| 75 6e 63 74 69 6f 6e 20 | 61 6c 77 61 79 73 20 68 |unction |always h|
|00001170| 61 73 20 74 77 6f 20 61 | 72 67 75 6d 65 6e 74 73 |as two a|rguments|
|00001180| 2c 0a 63 6f 6e 76 65 6e | 74 69 6f 6e 61 6c 6c 79 |,.conven|tionally|
|00001190| 20 6e 61 6d 65 64 20 5c | 76 61 72 7b 73 65 6c 66 | named \|var{self|
|000011a0| 7d 20 61 6e 64 20 5c 76 | 61 72 7b 61 72 67 73 7d |} and \v|ar{args}|
|000011b0| 2e 0a 0a 54 68 65 20 5c | 76 61 72 7b 73 65 6c 66 |...The \|var{self|
|000011c0| 7d 20 61 72 67 75 6d 65 | 6e 74 20 69 73 20 6f 6e |} argume|nt is on|
|000011d0| 6c 79 20 75 73 65 64 20 | 77 68 65 6e 20 74 68 65 |ly used |when the|
|000011e0| 20 43 20 66 75 6e 63 74 | 69 6f 6e 20 69 6d 70 6c | C funct|ion impl|
|000011f0| 65 6d 65 6e 74 73 20 61 | 0a 62 75 69 6c 74 69 6e |ements a|.builtin|
|00001200| 20 6d 65 74 68 6f 64 2e | 20 20 54 68 69 73 20 77 | method.|  This w|
|00001210| 69 6c 6c 20 62 65 20 64 | 69 73 63 75 73 73 65 64 |ill be d|iscussed|
|00001220| 20 6c 61 74 65 72 2e 20 | 49 6e 20 74 68 65 20 65 | later. |In the e|
|00001230| 78 61 6d 70 6c 65 2c 0a | 5c 76 61 72 7b 73 65 6c |xample,.|\var{sel|
|00001240| 66 7d 20 77 69 6c 6c 20 | 61 6c 77 61 79 73 20 62 |f} will |always b|
|00001250| 65 20 61 20 5c 63 6f 64 | 65 7b 4e 55 4c 4c 7d 20 |e a \cod|e{NULL} |
|00001260| 70 6f 69 6e 74 65 72 2c | 20 73 69 6e 63 65 20 77 |pointer,| since w|
|00001270| 65 20 61 72 65 20 64 65 | 66 69 6e 69 6e 67 0a 61 |e are de|fining.a|
|00001280| 20 66 75 6e 63 74 69 6f | 6e 2c 20 6e 6f 74 20 61 | functio|n, not a|
|00001290| 20 6d 65 74 68 6f 64 2e | 20 20 28 54 68 69 73 20 | method.|  (This |
|000012a0| 69 73 20 64 6f 6e 65 20 | 73 6f 20 74 68 61 74 20 |is done |so that |
|000012b0| 74 68 65 20 69 6e 74 65 | 72 70 72 65 74 65 72 0a |the inte|rpreter.|
|000012c0| 64 6f 65 73 6e 27 74 20 | 68 61 76 65 20 74 6f 20 |doesn't |have to |
|000012d0| 75 6e 64 65 72 73 74 61 | 6e 64 20 74 77 6f 20 64 |understa|nd two d|
|000012e0| 69 66 66 65 72 65 6e 74 | 20 74 79 70 65 73 20 6f |ifferent| types o|
|000012f0| 66 20 43 20 66 75 6e 63 | 74 69 6f 6e 73 2e 29 0a |f C func|tions.).|
|00001300| 0a 54 68 65 20 5c 76 61 | 72 7b 61 72 67 73 7d 20 |.The \va|r{args} |
|00001310| 61 72 67 75 6d 65 6e 74 | 20 77 69 6c 6c 20 62 65 |argument| will be|
|00001320| 20 61 20 70 6f 69 6e 74 | 65 72 20 74 6f 20 61 20 | a point|er to a |
|00001330| 50 79 74 68 6f 6e 20 74 | 75 70 6c 65 20 6f 62 6a |Python t|uple obj|
|00001340| 65 63 74 0a 63 6f 6e 74 | 61 69 6e 69 6e 67 20 74 |ect.cont|aining t|
|00001350| 68 65 20 61 72 67 75 6d | 65 6e 74 73 2e 20 20 45 |he argum|ents.  E|
|00001360| 61 63 68 20 69 74 65 6d | 20 6f 66 20 74 68 65 20 |ach item| of the |
|00001370| 74 75 70 6c 65 20 63 6f | 72 72 65 73 70 6f 6e 64 |tuple co|rrespond|
|00001380| 73 20 74 6f 20 61 6e 0a | 61 72 67 75 6d 65 6e 74 |s to an.|argument|
|00001390| 20 69 6e 20 74 68 65 20 | 63 61 6c 6c 27 73 20 61 | in the |call's a|
|000013a0| 72 67 75 6d 65 6e 74 20 | 6c 69 73 74 2e 20 20 54 |rgument |list.  T|
|000013b0| 68 65 20 61 72 67 75 6d | 65 6e 74 73 20 61 72 65 |he argum|ents are|
|000013c0| 20 50 79 74 68 6f 6e 0a | 6f 62 6a 65 63 74 73 20 | Python.|objects |
|000013d0| 2d 2d 20 69 6e 20 6f 72 | 64 65 72 20 74 6f 20 64 |-- in or|der to d|
|000013e0| 6f 20 61 6e 79 74 68 69 | 6e 67 20 77 69 74 68 20 |o anythi|ng with |
|000013f0| 74 68 65 6d 20 69 6e 20 | 6f 75 72 20 43 20 66 75 |them in |our C fu|
|00001400| 6e 63 74 69 6f 6e 20 77 | 65 20 68 61 76 65 0a 74 |nction w|e have.t|
|00001410| 6f 20 63 6f 6e 76 65 72 | 74 20 74 68 65 6d 20 74 |o conver|t them t|
|00001420| 6f 20 43 20 76 61 6c 75 | 65 73 2e 20 20 54 68 65 |o C valu|es.  The|
|00001430| 20 66 75 6e 63 74 69 6f | 6e 20 5c 63 6f 64 65 7b | functio|n \code{|
|00001440| 50 79 41 72 67 5f 50 61 | 72 73 65 54 75 70 6c 65 |PyArg_Pa|rseTuple|
|00001450| 28 29 7d 0a 69 6e 20 74 | 68 65 20 50 79 74 68 6f |()}.in t|he Pytho|
|00001460| 6e 20 41 50 49 20 63 68 | 65 63 6b 73 20 74 68 65 |n API ch|ecks the|
|00001470| 20 61 72 67 75 6d 65 6e | 74 20 74 79 70 65 73 20 | argumen|t types |
|00001480| 61 6e 64 20 63 6f 6e 76 | 65 72 74 73 20 74 68 65 |and conv|erts the|
|00001490| 6d 20 74 6f 20 43 0a 76 | 61 6c 75 65 73 2e 20 20 |m to C.v|alues.  |
|000014a0| 49 74 20 75 73 65 73 20 | 61 20 74 65 6d 70 6c 61 |It uses |a templa|
|000014b0| 74 65 20 73 74 72 69 6e | 67 20 74 6f 20 64 65 74 |te strin|g to det|
|000014c0| 65 72 6d 69 6e 65 20 74 | 68 65 20 72 65 71 75 69 |ermine t|he requi|
|000014d0| 72 65 64 20 74 79 70 65 | 73 20 6f 66 0a 74 68 65 |red type|s of.the|
|000014e0| 20 61 72 67 75 6d 65 6e | 74 73 20 61 73 20 77 65 | argumen|ts as we|
|000014f0| 6c 6c 20 61 73 20 74 68 | 65 20 74 79 70 65 73 20 |ll as th|e types |
|00001500| 6f 66 20 74 68 65 20 43 | 20 76 61 72 69 61 62 6c |of the C| variabl|
|00001510| 65 73 20 69 6e 74 6f 20 | 77 68 69 63 68 20 74 6f |es into |which to|
|00001520| 0a 73 74 6f 72 65 20 74 | 68 65 20 63 6f 6e 76 65 |.store t|he conve|
|00001530| 72 74 65 64 20 76 61 6c | 75 65 73 2e 20 20 4d 6f |rted val|ues.  Mo|
|00001540| 72 65 20 61 62 6f 75 74 | 20 74 68 69 73 20 6c 61 |re about| this la|
|00001550| 74 65 72 2e 0a 0a 5c 63 | 6f 64 65 7b 50 79 41 72 |ter...\c|ode{PyAr|
|00001560| 67 5f 50 61 72 73 65 54 | 75 70 6c 65 28 29 7d 20 |g_ParseT|uple()} |
|00001570| 72 65 74 75 72 6e 73 20 | 74 72 75 65 20 28 6e 6f |returns |true (no|
|00001580| 6e 7a 65 72 6f 29 20 69 | 66 20 61 6c 6c 20 61 72 |nzero) i|f all ar|
|00001590| 67 75 6d 65 6e 74 73 20 | 68 61 76 65 0a 74 68 65 |guments |have.the|
|000015a0| 20 72 69 67 68 74 20 74 | 79 70 65 20 61 6e 64 20 | right t|ype and |
|000015b0| 69 74 73 20 63 6f 6d 70 | 6f 6e 65 6e 74 73 20 68 |its comp|onents h|
|000015c0| 61 76 65 20 62 65 65 6e | 20 73 74 6f 72 65 64 20 |ave been| stored |
|000015d0| 69 6e 20 74 68 65 20 76 | 61 72 69 61 62 6c 65 73 |in the v|ariables|
|000015e0| 0a 77 68 6f 73 65 20 61 | 64 64 72 65 73 73 65 73 |.whose a|ddresses|
|000015f0| 20 61 72 65 20 70 61 73 | 73 65 64 2e 20 20 49 74 | are pas|sed.  It|
|00001600| 20 72 65 74 75 72 6e 73 | 20 66 61 6c 73 65 20 28 | returns| false (|
|00001610| 7a 65 72 6f 29 20 69 66 | 20 61 6e 20 69 6e 76 61 |zero) if| an inva|
|00001620| 6c 69 64 0a 61 72 67 75 | 6d 65 6e 74 20 6c 69 73 |lid.argu|ment lis|
|00001630| 74 20 77 61 73 20 70 61 | 73 73 65 64 2e 20 20 49 |t was pa|ssed.  I|
|00001640| 6e 20 74 68 65 20 6c 61 | 74 74 65 72 20 63 61 73 |n the la|tter cas|
|00001650| 65 20 69 74 20 61 6c 73 | 6f 20 72 61 69 73 65 73 |e it als|o raises|
|00001660| 20 61 6e 0a 61 70 70 72 | 6f 70 72 69 61 74 65 20 | an.appr|opriate |
|00001670| 65 78 63 65 70 74 69 6f | 6e 20 62 79 20 73 6f 20 |exceptio|n by so |
|00001680| 74 68 65 20 63 61 6c 6c | 69 6e 67 20 66 75 6e 63 |the call|ing func|
|00001690| 74 69 6f 6e 20 63 61 6e | 20 72 65 74 75 72 6e 0a |tion can| return.|
|000016a0| 5c 63 6f 64 65 7b 4e 55 | 4c 4c 7d 20 69 6d 6d 65 |\code{NU|LL} imme|
|000016b0| 64 69 61 74 65 6c 79 20 | 28 61 73 20 77 65 20 73 |diately |(as we s|
|000016c0| 61 77 20 69 6e 20 74 68 | 65 20 65 78 61 6d 70 6c |aw in th|e exampl|
|000016d0| 65 29 2e 0a 0a 0a 5c 73 | 65 63 74 69 6f 6e 7b 49 |e)....\s|ection{I|
|000016e0| 6e 74 65 72 6d 65 7a 7a | 6f 3a 20 45 72 72 6f 72 |ntermezz|o: Error|
|000016f0| 73 20 61 6e 64 20 45 78 | 63 65 70 74 69 6f 6e 73 |s and Ex|ceptions|
|00001700| 7d 0a 0a 41 6e 20 69 6d | 70 6f 72 74 61 6e 74 20 |}..An im|portant |
|00001710| 63 6f 6e 76 65 6e 74 69 | 6f 6e 20 74 68 72 6f 75 |conventi|on throu|
|00001720| 67 68 6f 75 74 20 74 68 | 65 20 50 79 74 68 6f 6e |ghout th|e Python|
|00001730| 20 69 6e 74 65 72 70 72 | 65 74 65 72 20 69 73 20 | interpr|eter is |
|00001740| 74 68 65 0a 66 6f 6c 6c | 6f 77 69 6e 67 3a 20 77 |the.foll|owing: w|
|00001750| 68 65 6e 20 61 20 66 75 | 6e 63 74 69 6f 6e 20 66 |hen a fu|nction f|
|00001760| 61 69 6c 73 2c 20 69 74 | 20 73 68 6f 75 6c 64 20 |ails, it| should |
|00001770| 73 65 74 20 61 6e 20 65 | 78 63 65 70 74 69 6f 6e |set an e|xception|
|00001780| 20 63 6f 6e 64 69 74 69 | 6f 6e 0a 61 6e 64 20 72 | conditi|on.and r|
|00001790| 65 74 75 72 6e 20 61 6e | 20 65 72 72 6f 72 20 76 |eturn an| error v|
|000017a0| 61 6c 75 65 20 28 75 73 | 75 61 6c 6c 79 20 61 20 |alue (us|ually a |
|000017b0| 5c 63 6f 64 65 7b 4e 55 | 4c 4c 7d 20 70 6f 69 6e |\code{NU|LL} poin|
|000017c0| 74 65 72 29 2e 20 20 45 | 78 63 65 70 74 69 6f 6e |ter).  E|xception|
|000017d0| 73 0a 61 72 65 20 73 74 | 6f 72 65 64 20 69 6e 20 |s.are st|ored in |
|000017e0| 61 20 73 74 61 74 69 63 | 20 67 6c 6f 62 61 6c 20 |a static| global |
|000017f0| 76 61 72 69 61 62 6c 65 | 20 69 6e 73 69 64 65 20 |variable| inside |
|00001800| 74 68 65 20 69 6e 74 65 | 72 70 72 65 74 65 72 3b |the inte|rpreter;|
|00001810| 20 69 66 20 74 68 69 73 | 0a 76 61 72 69 61 62 6c | if this|.variabl|
|00001820| 65 20 69 73 20 5c 63 6f | 64 65 7b 4e 55 4c 4c 7d |e is \co|de{NULL}|
|00001830| 20 6e 6f 20 65 78 63 65 | 70 74 69 6f 6e 20 68 61 | no exce|ption ha|
|00001840| 73 20 6f 63 63 75 72 72 | 65 64 2e 20 20 41 20 73 |s occurr|ed.  A s|
|00001850| 65 63 6f 6e 64 20 67 6c | 6f 62 61 6c 0a 76 61 72 |econd gl|obal.var|
|00001860| 69 61 62 6c 65 20 73 74 | 6f 72 65 73 20 74 68 65 |iable st|ores the|
|00001870| 20 60 60 61 73 73 6f 63 | 69 61 74 65 64 20 76 61 | ``assoc|iated va|
|00001880| 6c 75 65 27 27 20 6f 66 | 20 74 68 65 20 65 78 63 |lue'' of| the exc|
|00001890| 65 70 74 69 6f 6e 20 28 | 74 68 65 20 73 65 63 6f |eption (|the seco|
|000018a0| 6e 64 0a 61 72 67 75 6d | 65 6e 74 20 74 6f 20 5c |nd.argum|ent to \|
|000018b0| 63 6f 64 65 7b 72 61 69 | 73 65 7d 29 2e 20 20 41 |code{rai|se}).  A|
|000018c0| 20 74 68 69 72 64 20 76 | 61 72 69 61 62 6c 65 20 | third v|ariable |
|000018d0| 63 6f 6e 74 61 69 6e 73 | 20 74 68 65 20 73 74 61 |contains| the sta|
|000018e0| 63 6b 0a 74 72 61 63 65 | 62 61 63 6b 20 69 6e 20 |ck.trace|back in |
|000018f0| 63 61 73 65 20 74 68 65 | 20 65 72 72 6f 72 20 6f |case the| error o|
|00001900| 72 69 67 69 6e 61 74 65 | 64 20 69 6e 20 50 79 74 |riginate|d in Pyt|
|00001910| 68 6f 6e 20 63 6f 64 65 | 2e 20 20 54 68 65 73 65 |hon code|.  These|
|00001920| 20 74 68 72 65 65 0a 76 | 61 72 69 61 62 6c 65 73 | three.v|ariables|
|00001930| 20 61 72 65 20 74 68 65 | 20 43 20 65 71 75 69 76 | are the| C equiv|
|00001940| 61 6c 65 6e 74 73 20 6f | 66 20 74 68 65 20 50 79 |alents o|f the Py|
|00001950| 74 68 6f 6e 20 76 61 72 | 69 61 62 6c 65 73 0a 5c |thon var|iables.\|
|00001960| 63 6f 64 65 7b 73 79 73 | 2e 65 78 63 5f 74 79 70 |code{sys|.exc_typ|
|00001970| 65 7d 2c 20 5c 63 6f 64 | 65 7b 73 79 73 2e 65 78 |e}, \cod|e{sys.ex|
|00001980| 63 5f 76 61 6c 75 65 7d | 20 61 6e 64 20 5c 63 6f |c_value}| and \co|
|00001990| 64 65 7b 73 79 73 2e 65 | 78 63 5f 74 72 61 63 65 |de{sys.e|xc_trace|
|000019a0| 62 61 63 6b 7d 0a 28 73 | 65 65 20 74 68 65 20 73 |back}.(s|ee the s|
|000019b0| 65 63 74 69 6f 6e 20 6f | 6e 20 6d 6f 64 75 6c 65 |ection o|n module|
|000019c0| 20 5c 63 6f 64 65 7b 73 | 79 73 7d 20 69 6e 20 74 | \code{s|ys} in t|
|000019d0| 68 65 20 4c 69 62 72 61 | 72 79 20 52 65 66 65 72 |he Libra|ry Refer|
|000019e0| 65 6e 63 65 0a 4d 61 6e | 75 61 6c 29 2e 20 20 49 |ence.Man|ual).  I|
|000019f0| 74 20 69 73 20 69 6d 70 | 6f 72 74 61 6e 74 20 74 |t is imp|ortant t|
|00001a00| 6f 20 6b 6e 6f 77 20 61 | 62 6f 75 74 20 74 68 65 |o know a|bout the|
|00001a10| 6d 20 74 6f 20 75 6e 64 | 65 72 73 74 61 6e 64 20 |m to und|erstand |
|00001a20| 68 6f 77 20 65 72 72 6f | 72 73 0a 61 72 65 20 70 |how erro|rs.are p|
|00001a30| 61 73 73 65 64 20 61 72 | 6f 75 6e 64 2e 0a 0a 54 |assed ar|ound...T|
|00001a40| 68 65 20 50 79 74 68 6f | 6e 20 41 50 49 20 64 65 |he Pytho|n API de|
|00001a50| 66 69 6e 65 73 20 61 20 | 6e 75 6d 62 65 72 20 6f |fines a |number o|
|00001a60| 66 20 66 75 6e 63 74 69 | 6f 6e 73 20 74 6f 20 73 |f functi|ons to s|
|00001a70| 65 74 20 76 61 72 69 6f | 75 73 20 74 79 70 65 73 |et vario|us types|
|00001a80| 20 6f 66 0a 65 78 63 65 | 70 74 69 6f 6e 73 2e 0a | of.exce|ptions..|
|00001a90| 0a 54 68 65 20 6d 6f 73 | 74 20 63 6f 6d 6d 6f 6e |.The mos|t common|
|00001aa0| 20 6f 6e 65 20 69 73 20 | 5c 63 6f 64 65 7b 50 79 | one is |\code{Py|
|00001ab0| 45 72 72 5f 53 65 74 53 | 74 72 69 6e 67 28 29 7d |Err_SetS|tring()}|
|00001ac0| 2e 20 20 49 74 73 20 61 | 72 67 75 6d 65 6e 74 73 |.  Its a|rguments|
|00001ad0| 20 61 72 65 20 61 6e 0a | 65 78 63 65 70 74 69 6f | are an.|exceptio|
|00001ae0| 6e 20 6f 62 6a 65 63 74 | 20 61 6e 64 20 61 20 43 |n object| and a C|
|00001af0| 20 73 74 72 69 6e 67 2e | 20 20 54 68 65 20 65 78 | string.|  The ex|
|00001b00| 63 65 70 74 69 6f 6e 20 | 6f 62 6a 65 63 74 20 69 |ception |object i|
|00001b10| 73 20 75 73 75 61 6c 6c | 79 20 61 0a 70 72 65 64 |s usuall|y a.pred|
|00001b20| 65 66 69 6e 65 64 20 6f | 62 6a 65 63 74 20 6c 69 |efined o|bject li|
|00001b30| 6b 65 20 5c 63 6f 64 65 | 7b 50 79 45 78 63 5f 5a |ke \code|{PyExc_Z|
|00001b40| 65 72 6f 44 69 76 69 73 | 69 6f 6e 45 72 72 6f 72 |eroDivis|ionError|
|00001b50| 7d 2e 20 20 54 68 65 20 | 43 20 73 74 72 69 6e 67 |}.  The |C string|
|00001b60| 0a 69 6e 64 69 63 61 74 | 65 73 20 74 68 65 20 63 |.indicat|es the c|
|00001b70| 61 75 73 65 20 6f 66 20 | 74 68 65 20 65 72 72 6f |ause of |the erro|
|00001b80| 72 20 61 6e 64 20 69 73 | 20 63 6f 6e 76 65 72 74 |r and is| convert|
|00001b90| 65 64 20 74 6f 20 61 20 | 50 79 74 68 6f 6e 20 73 |ed to a |Python s|
|00001ba0| 74 72 69 6e 67 0a 6f 62 | 6a 65 63 74 20 61 6e 64 |tring.ob|ject and|
|00001bb0| 20 73 74 6f 72 65 64 20 | 61 73 20 74 68 65 20 60 | stored |as the `|
|00001bc0| 60 61 73 73 6f 63 69 61 | 74 65 64 20 76 61 6c 75 |`associa|ted valu|
|00001bd0| 65 27 27 20 6f 66 20 74 | 68 65 20 65 78 63 65 70 |e'' of t|he excep|
|00001be0| 74 69 6f 6e 2e 0a 0a 41 | 6e 6f 74 68 65 72 20 75 |tion...A|nother u|
|00001bf0| 73 65 66 75 6c 20 66 75 | 6e 63 74 69 6f 6e 20 69 |seful fu|nction i|
|00001c00| 73 20 5c 63 6f 64 65 7b | 50 79 45 72 72 5f 53 65 |s \code{|PyErr_Se|
|00001c10| 74 46 72 6f 6d 45 72 72 | 6e 6f 28 29 7d 2c 20 77 |tFromErr|no()}, w|
|00001c20| 68 69 63 68 20 6f 6e 6c | 79 0a 74 61 6b 65 73 20 |hich onl|y.takes |
|00001c30| 61 6e 20 65 78 63 65 70 | 74 69 6f 6e 20 61 72 67 |an excep|tion arg|
|00001c40| 75 6d 65 6e 74 20 61 6e | 64 20 63 6f 6e 73 74 72 |ument an|d constr|
|00001c50| 75 63 74 73 20 74 68 65 | 20 61 73 73 6f 63 69 61 |ucts the| associa|
|00001c60| 74 65 64 20 76 61 6c 75 | 65 20 62 79 0a 69 6e 73 |ted valu|e by.ins|
|00001c70| 70 65 63 74 69 6f 6e 20 | 6f 66 20 74 68 65 20 28 |pection |of the (|
|00001c80| 5c 55 4e 49 58 7b 7d 29 | 20 67 6c 6f 62 61 6c 20 |\UNIX{})| global |
|00001c90| 76 61 72 69 61 62 6c 65 | 20 5c 63 6f 64 65 7b 65 |variable| \code{e|
|00001ca0| 72 72 6e 6f 7d 2e 20 20 | 54 68 65 20 6d 6f 73 74 |rrno}.  |The most|
|00001cb0| 0a 67 65 6e 65 72 61 6c | 20 66 75 6e 63 74 69 6f |.general| functio|
|00001cc0| 6e 20 69 73 20 5c 63 6f | 64 65 7b 50 79 45 72 72 |n is \co|de{PyErr|
|00001cd0| 5f 53 65 74 4f 62 6a 65 | 63 74 28 29 7d 2c 20 77 |_SetObje|ct()}, w|
|00001ce0| 68 69 63 68 20 74 61 6b | 65 73 20 74 77 6f 20 6f |hich tak|es two o|
|00001cf0| 62 6a 65 63 74 0a 61 72 | 67 75 6d 65 6e 74 73 2c |bject.ar|guments,|
|00001d00| 20 74 68 65 20 65 78 63 | 65 70 74 69 6f 6e 20 61 | the exc|eption a|
|00001d10| 6e 64 20 69 74 73 20 61 | 73 73 6f 63 69 61 74 65 |nd its a|ssociate|
|00001d20| 64 20 76 61 6c 75 65 2e | 20 20 59 6f 75 20 64 6f |d value.|  You do|
|00001d30| 6e 27 74 20 6e 65 65 64 | 20 74 6f 0a 5c 63 6f 64 |n't need| to.\cod|
|00001d40| 65 7b 50 79 5f 49 4e 43 | 52 45 46 28 29 7d 20 74 |e{Py_INC|REF()} t|
|00001d50| 68 65 20 6f 62 6a 65 63 | 74 73 20 70 61 73 73 65 |he objec|ts passe|
|00001d60| 64 20 74 6f 20 61 6e 79 | 20 6f 66 20 74 68 65 73 |d to any| of thes|
|00001d70| 65 20 66 75 6e 63 74 69 | 6f 6e 73 2e 0a 0a 59 6f |e functi|ons...Yo|
|00001d80| 75 20 63 61 6e 20 74 65 | 73 74 20 6e 6f 6e 2d 64 |u can te|st non-d|
|00001d90| 65 73 74 72 75 63 74 69 | 76 65 6c 79 20 77 68 65 |estructi|vely whe|
|00001da0| 74 68 65 72 20 61 6e 20 | 65 78 63 65 70 74 69 6f |ther an |exceptio|
|00001db0| 6e 20 68 61 73 20 62 65 | 65 6e 20 73 65 74 20 77 |n has be|en set w|
|00001dc0| 69 74 68 0a 5c 63 6f 64 | 65 7b 50 79 45 72 72 5f |ith.\cod|e{PyErr_|
|00001dd0| 4f 63 63 75 72 72 65 64 | 28 29 7d 2e 20 20 54 68 |Occurred|()}.  Th|
|00001de0| 69 73 20 72 65 74 75 72 | 6e 73 20 74 68 65 20 63 |is retur|ns the c|
|00001df0| 75 72 72 65 6e 74 20 65 | 78 63 65 70 74 69 6f 6e |urrent e|xception|
|00001e00| 20 6f 62 6a 65 63 74 2c | 0a 6f 72 20 5c 63 6f 64 | object,|.or \cod|
|00001e10| 65 7b 4e 55 4c 4c 7d 20 | 69 66 20 6e 6f 20 65 78 |e{NULL} |if no ex|
|00001e20| 63 65 70 74 69 6f 6e 20 | 68 61 73 20 6f 63 63 75 |ception |has occu|
|00001e30| 72 72 65 64 2e 20 20 59 | 6f 75 20 6e 6f 72 6d 61 |rred.  Y|ou norma|
|00001e40| 6c 6c 79 20 64 6f 6e 27 | 74 20 6e 65 65 64 0a 74 |lly don'|t need.t|
|00001e50| 6f 20 63 61 6c 6c 20 5c | 63 6f 64 65 7b 50 79 45 |o call \|code{PyE|
|00001e60| 72 72 5f 4f 63 63 75 72 | 72 65 64 28 29 7d 20 74 |rr_Occur|red()} t|
|00001e70| 6f 20 73 65 65 20 77 68 | 65 74 68 65 72 20 61 6e |o see wh|ether an|
|00001e80| 20 65 72 72 6f 72 20 6f | 63 63 75 72 72 65 64 20 | error o|ccurred |
|00001e90| 69 6e 20 61 0a 66 75 6e | 63 74 69 6f 6e 20 63 61 |in a.fun|ction ca|
|00001ea0| 6c 6c 2c 20 73 69 6e 63 | 65 20 79 6f 75 20 73 68 |ll, sinc|e you sh|
|00001eb0| 6f 75 6c 64 20 62 65 20 | 61 62 6c 65 20 74 6f 20 |ould be |able to |
|00001ec0| 74 65 6c 6c 20 66 72 6f | 6d 20 74 68 65 20 72 65 |tell fro|m the re|
|00001ed0| 74 75 72 6e 20 76 61 6c | 75 65 2e 0a 0a 57 68 65 |turn val|ue...Whe|
|00001ee0| 6e 20 61 20 66 75 6e 63 | 74 69 6f 6e 20 5c 76 61 |n a func|tion \va|
|00001ef0| 72 7b 66 7d 20 74 68 61 | 74 20 63 61 6c 6c 73 20 |r{f} tha|t calls |
|00001f00| 61 6e 6f 74 68 65 72 20 | 66 75 6e 63 74 69 6f 6e |another |function|
|00001f10| 20 76 61 72 7b 67 7d 20 | 64 65 74 65 63 74 73 0a | var{g} |detects.|
|00001f20| 74 68 61 74 20 74 68 65 | 20 6c 61 74 74 65 72 20 |that the| latter |
|00001f30| 66 61 69 6c 73 2c 20 5c | 76 61 72 7b 66 7d 20 73 |fails, \|var{f} s|
|00001f40| 68 6f 75 6c 64 20 69 74 | 73 65 6c 66 20 72 65 74 |hould it|self ret|
|00001f50| 75 72 6e 20 61 6e 20 65 | 72 72 6f 72 20 76 61 6c |urn an e|rror val|
|00001f60| 75 65 0a 28 65 2e 67 2e | 20 5c 63 6f 64 65 7b 4e |ue.(e.g.| \code{N|
|00001f70| 55 4c 4c 7d 20 6f 72 20 | 5c 63 6f 64 65 7b 2d 31 |ULL} or |\code{-1|
|00001f80| 7d 29 2e 20 20 49 74 20 | 73 68 6f 75 6c 64 20 5c |}).  It |should \|
|00001f90| 65 6d 70 68 7b 6e 6f 74 | 7d 20 63 61 6c 6c 20 6f |emph{not|} call o|
|00001fa0| 6e 65 20 6f 66 20 74 68 | 65 0a 5c 63 6f 64 65 7b |ne of th|e.\code{|
|00001fb0| 50 79 45 72 72 5f 2a 28 | 29 7d 20 66 75 6e 63 74 |PyErr_*(|)} funct|
|00001fc0| 69 6f 6e 73 20 2d 2d 2d | 20 6f 6e 65 20 68 61 73 |ions ---| one has|
|00001fd0| 20 61 6c 72 65 61 64 79 | 20 62 65 65 6e 20 63 61 | already| been ca|
|00001fe0| 6c 6c 65 64 20 62 79 20 | 5c 76 61 72 7b 67 7d 2e |lled by |\var{g}.|
|00001ff0| 0a 5c 76 61 72 7b 66 7d | 27 73 20 63 61 6c 6c 65 |.\var{f}|'s calle|
|00002000| 72 20 69 73 20 74 68 65 | 6e 20 73 75 70 70 6f 73 |r is the|n suppos|
|00002010| 65 64 20 74 6f 20 61 6c | 73 6f 20 72 65 74 75 72 |ed to al|so retur|
|00002020| 6e 20 61 6e 20 65 72 72 | 6f 72 20 69 6e 64 69 63 |n an err|or indic|
|00002030| 61 74 69 6f 6e 0a 74 6f | 20 5c 65 6d 70 68 7b 69 |ation.to| \emph{i|
|00002040| 74 73 7d 20 63 61 6c 6c | 65 72 2c 20 61 67 61 69 |ts} call|er, agai|
|00002050| 6e 20 5c 65 6d 70 68 7b | 77 69 74 68 6f 75 74 7d |n \emph{|without}|
|00002060| 20 63 61 6c 6c 69 6e 67 | 20 5c 63 6f 64 65 7b 50 | calling| \code{P|
|00002070| 79 45 72 72 5f 2a 28 29 | 7d 2c 0a 61 6e 64 20 73 |yErr_*()|},.and s|
|00002080| 6f 20 6f 6e 20 2d 2d 2d | 20 74 68 65 20 6d 6f 73 |o on ---| the mos|
|00002090| 74 20 64 65 74 61 69 6c | 65 64 20 63 61 75 73 65 |t detail|ed cause|
|000020a0| 20 6f 66 20 74 68 65 20 | 65 72 72 6f 72 20 77 61 | of the |error wa|
|000020b0| 73 20 61 6c 72 65 61 64 | 79 0a 72 65 70 6f 72 74 |s alread|y.report|
|000020c0| 65 64 20 62 79 20 74 68 | 65 20 66 75 6e 63 74 69 |ed by th|e functi|
|000020d0| 6f 6e 20 74 68 61 74 20 | 66 69 72 73 74 20 64 65 |on that |first de|
|000020e0| 74 65 63 74 65 64 20 69 | 74 2e 20 20 4f 6e 63 65 |tected i|t.  Once|
|000020f0| 20 74 68 65 20 65 72 72 | 6f 72 0a 72 65 61 63 68 | the err|or.reach|
|00002100| 65 73 20 74 68 65 20 50 | 79 74 68 6f 6e 20 69 6e |es the P|ython in|
|00002110| 74 65 72 70 72 65 74 65 | 72 27 73 20 6d 61 69 6e |terprete|r's main|
|00002120| 20 6c 6f 6f 70 2c 20 74 | 68 69 73 20 61 62 6f 72 | loop, t|his abor|
|00002130| 74 73 20 74 68 65 20 63 | 75 72 72 65 6e 74 6c 79 |ts the c|urrently|
|00002140| 0a 65 78 65 63 75 74 69 | 6e 67 20 50 79 74 68 6f |.executi|ng Pytho|
|00002150| 6e 20 63 6f 64 65 20 61 | 6e 64 20 74 72 69 65 73 |n code a|nd tries|
|00002160| 20 74 6f 20 66 69 6e 64 | 20 61 6e 20 65 78 63 65 | to find| an exce|
|00002170| 70 74 69 6f 6e 20 68 61 | 6e 64 6c 65 72 20 73 70 |ption ha|ndler sp|
|00002180| 65 63 69 66 69 65 64 0a | 62 79 20 74 68 65 20 50 |ecified.|by the P|
|00002190| 79 74 68 6f 6e 20 70 72 | 6f 67 72 61 6d 6d 65 72 |ython pr|ogrammer|
|000021a0| 2e 0a 0a 28 54 68 65 72 | 65 20 61 72 65 20 73 69 |...(Ther|e are si|
|000021b0| 74 75 61 74 69 6f 6e 73 | 20 77 68 65 72 65 20 61 |tuations| where a|
|000021c0| 20 6d 6f 64 75 6c 65 20 | 63 61 6e 20 61 63 74 75 | module |can actu|
|000021d0| 61 6c 6c 79 20 67 69 76 | 65 20 61 20 6d 6f 72 65 |ally giv|e a more|
|000021e0| 20 64 65 74 61 69 6c 65 | 64 0a 65 72 72 6f 72 20 | detaile|d.error |
|000021f0| 6d 65 73 73 61 67 65 20 | 62 79 20 63 61 6c 6c 69 |message |by calli|
|00002200| 6e 67 20 61 6e 6f 74 68 | 65 72 20 5c 63 6f 64 65 |ng anoth|er \code|
|00002210| 7b 50 79 45 72 72 5f 2a | 28 29 7d 20 66 75 6e 63 |{PyErr_*|()} func|
|00002220| 74 69 6f 6e 2c 20 61 6e | 64 20 69 6e 0a 73 75 63 |tion, an|d in.suc|
|00002230| 68 20 63 61 73 65 73 20 | 69 74 20 69 73 20 66 69 |h cases |it is fi|
|00002240| 6e 65 20 74 6f 20 64 6f | 20 73 6f 2e 20 20 41 73 |ne to do| so.  As|
|00002250| 20 61 20 67 65 6e 65 72 | 61 6c 20 72 75 6c 65 2c | a gener|al rule,|
|00002260| 20 68 6f 77 65 76 65 72 | 2c 20 74 68 69 73 20 69 | however|, this i|
|00002270| 73 0a 6e 6f 74 20 6e 65 | 63 65 73 73 61 72 79 2c |s.not ne|cessary,|
|00002280| 20 61 6e 64 20 63 61 6e | 20 63 61 75 73 65 20 69 | and can| cause i|
|00002290| 6e 66 6f 72 6d 61 74 69 | 6f 6e 20 61 62 6f 75 74 |nformati|on about|
|000022a0| 20 74 68 65 20 63 61 75 | 73 65 20 6f 66 20 74 68 | the cau|se of th|
|000022b0| 65 20 65 72 72 6f 72 0a | 74 6f 20 62 65 20 6c 6f |e error.|to be lo|
|000022c0| 73 74 3a 20 6d 6f 73 74 | 20 6f 70 65 72 61 74 69 |st: most| operati|
|000022d0| 6f 6e 73 20 63 61 6e 20 | 66 61 69 6c 20 66 6f 72 |ons can |fail for|
|000022e0| 20 61 20 76 61 72 69 65 | 74 79 20 6f 66 20 72 65 | a varie|ty of re|
|000022f0| 61 73 6f 6e 73 2e 29 0a | 0a 54 6f 20 69 67 6e 6f |asons.).|.To igno|
|00002300| 72 65 20 61 6e 20 65 78 | 63 65 70 74 69 6f 6e 20 |re an ex|ception |
|00002310| 73 65 74 20 62 79 20 61 | 20 66 75 6e 63 74 69 6f |set by a| functio|
|00002320| 6e 20 63 61 6c 6c 20 74 | 68 61 74 20 66 61 69 6c |n call t|hat fail|
|00002330| 65 64 2c 20 74 68 65 20 | 65 78 63 65 70 74 69 6f |ed, the |exceptio|
|00002340| 6e 0a 63 6f 6e 64 69 74 | 69 6f 6e 20 6d 75 73 74 |n.condit|ion must|
|00002350| 20 62 65 20 63 6c 65 61 | 72 65 64 20 65 78 70 6c | be clea|red expl|
|00002360| 69 63 69 74 6c 79 20 62 | 79 20 63 61 6c 6c 69 6e |icitly b|y callin|
|00002370| 67 20 5c 63 6f 64 65 7b | 50 79 45 72 72 5f 43 6c |g \code{|PyErr_Cl|
|00002380| 65 61 72 28 29 7d 2e 20 | 0a 54 68 65 20 6f 6e 6c |ear()}. |.The onl|
|00002390| 79 20 74 69 6d 65 20 43 | 20 63 6f 64 65 20 73 68 |y time C| code sh|
|000023a0| 6f 75 6c 64 20 63 61 6c | 6c 20 5c 63 6f 64 65 7b |ould cal|l \code{|
|000023b0| 50 79 45 72 72 5f 43 6c | 65 61 72 28 29 7d 20 69 |PyErr_Cl|ear()} i|
|000023c0| 73 20 69 66 20 69 74 20 | 64 6f 65 73 6e 27 74 0a |s if it |doesn't.|
|000023d0| 77 61 6e 74 20 74 6f 20 | 70 61 73 73 20 74 68 65 |want to |pass the|
|000023e0| 20 65 72 72 6f 72 20 6f | 6e 20 74 6f 20 74 68 65 | error o|n to the|
|000023f0| 20 69 6e 74 65 72 70 72 | 65 74 65 72 20 62 75 74 | interpr|eter but|
|00002400| 20 77 61 6e 74 73 20 74 | 6f 20 68 61 6e 64 6c 65 | wants t|o handle|
|00002410| 20 69 74 0a 63 6f 6d 70 | 6c 65 74 65 6c 79 20 62 | it.comp|letely b|
|00002420| 79 20 69 74 73 65 6c 66 | 20 28 65 2e 67 2e 20 62 |y itself| (e.g. b|
|00002430| 79 20 74 72 79 69 6e 67 | 20 73 6f 6d 65 74 68 69 |y trying| somethi|
|00002440| 6e 67 20 65 6c 73 65 20 | 6f 72 20 70 72 65 74 65 |ng else |or prete|
|00002450| 6e 64 69 6e 67 0a 6e 6f | 74 68 69 6e 67 20 68 61 |nding.no|thing ha|
|00002460| 70 70 65 6e 65 64 29 2e | 0a 0a 4e 6f 74 65 20 74 |ppened).|..Note t|
|00002470| 68 61 74 20 61 20 66 61 | 69 6c 69 6e 67 20 5c 63 |hat a fa|iling \c|
|00002480| 6f 64 65 7b 6d 61 6c 6c | 6f 63 28 29 7d 20 63 61 |ode{mall|oc()} ca|
|00002490| 6c 6c 20 6d 75 73 74 20 | 62 65 20 74 75 72 6e 65 |ll must |be turne|
|000024a0| 64 20 69 6e 74 6f 20 61 | 6e 0a 65 78 63 65 70 74 |d into a|n.except|
|000024b0| 69 6f 6e 20 2d 2d 2d 20 | 74 68 65 20 64 69 72 65 |ion --- |the dire|
|000024c0| 63 74 20 63 61 6c 6c 65 | 72 20 6f 66 20 5c 63 6f |ct calle|r of \co|
|000024d0| 64 65 7b 6d 61 6c 6c 6f | 63 28 29 7d 20 28 6f 72 |de{mallo|c()} (or|
|000024e0| 0a 5c 63 6f 64 65 7b 72 | 65 61 6c 6c 6f 63 28 29 |.\code{r|ealloc()|
|000024f0| 7d 29 20 6d 75 73 74 20 | 63 61 6c 6c 20 5c 63 6f |}) must |call \co|
|00002500| 64 65 7b 50 79 45 72 72 | 5f 4e 6f 4d 65 6d 6f 72 |de{PyErr|_NoMemor|
|00002510| 79 28 29 7d 20 61 6e 64 | 20 72 65 74 75 72 6e 20 |y()} and| return |
|00002520| 61 0a 66 61 69 6c 75 72 | 65 20 69 6e 64 69 63 61 |a.failur|e indica|
|00002530| 74 6f 72 20 69 74 73 65 | 6c 66 2e 20 20 41 6c 6c |tor itse|lf.  All|
|00002540| 20 74 68 65 20 6f 62 6a | 65 63 74 2d 63 72 65 61 | the obj|ect-crea|
|00002550| 74 69 6e 67 20 66 75 6e | 63 74 69 6f 6e 73 0a 28 |ting fun|ctions.(|
|00002560| 5c 63 6f 64 65 7b 50 79 | 49 6e 74 5f 46 72 6f 6d |\code{Py|Int_From|
|00002570| 4c 6f 6e 67 28 29 7d 20 | 65 74 63 2e 29 20 61 6c |Long()} |etc.) al|
|00002580| 72 65 61 64 79 20 64 6f | 20 74 68 69 73 2c 20 73 |ready do| this, s|
|00002590| 6f 20 6f 6e 6c 79 20 69 | 66 20 79 6f 75 20 63 61 |o only i|f you ca|
|000025a0| 6c 6c 0a 5c 63 6f 64 65 | 7b 6d 61 6c 6c 6f 63 28 |ll.\code|{malloc(|
|000025b0| 29 7d 20 64 69 72 65 63 | 74 6c 79 20 74 68 69 73 |)} direc|tly this|
|000025c0| 20 6e 6f 74 65 20 69 73 | 20 6f 66 20 69 6d 70 6f | note is| of impo|
|000025d0| 72 74 61 6e 63 65 2e 0a | 0a 41 6c 73 6f 20 6e 6f |rtance..|.Also no|
|000025e0| 74 65 20 74 68 61 74 2c | 20 77 69 74 68 20 74 68 |te that,| with th|
|000025f0| 65 20 69 6d 70 6f 72 74 | 61 6e 74 20 65 78 63 65 |e import|ant exce|
|00002600| 70 74 69 6f 6e 20 6f 66 | 0a 5c 63 6f 64 65 7b 50 |ption of|.\code{P|
|00002610| 79 41 72 67 5f 50 61 72 | 73 65 54 75 70 6c 65 28 |yArg_Par|seTuple(|
|00002620| 29 7d 20 61 6e 64 20 66 | 72 69 65 6e 64 73 2c 20 |)} and f|riends, |
|00002630| 66 75 6e 63 74 69 6f 6e | 73 20 74 68 61 74 20 72 |function|s that r|
|00002640| 65 74 75 72 6e 20 61 6e | 0a 69 6e 74 65 67 65 72 |eturn an|.integer|
|00002650| 20 73 74 61 74 75 73 20 | 75 73 75 61 6c 6c 79 20 | status |usually |
|00002660| 72 65 74 75 72 6e 20 61 | 20 70 6f 73 69 74 69 76 |return a| positiv|
|00002670| 65 20 76 61 6c 75 65 20 | 6f 72 20 7a 65 72 6f 20 |e value |or zero |
|00002680| 66 6f 72 20 73 75 63 63 | 65 73 73 20 61 6e 64 0a |for succ|ess and.|
|00002690| 5c 63 6f 64 65 7b 2d 31 | 7d 20 66 6f 72 20 66 61 |\code{-1|} for fa|
|000026a0| 69 6c 75 72 65 2c 20 6c | 69 6b 65 20 5c 55 4e 49 |ilure, l|ike \UNI|
|000026b0| 58 7b 7d 20 73 79 73 74 | 65 6d 20 63 61 6c 6c 73 |X{} syst|em calls|
|000026c0| 2e 0a 0a 46 69 6e 61 6c | 6c 79 2c 20 62 65 20 63 |...Final|ly, be c|
|000026d0| 61 72 65 66 75 6c 20 74 | 6f 20 63 6c 65 61 6e 20 |areful t|o clean |
|000026e0| 75 70 20 67 61 72 62 61 | 67 65 20 28 62 79 20 6d |up garba|ge (by m|
|000026f0| 61 6b 69 6e 67 20 5c 63 | 6f 64 65 7b 50 79 5f 58 |aking \c|ode{Py_X|
|00002700| 44 45 43 52 45 46 28 29 | 7d 0a 6f 72 20 5c 63 6f |DECREF()|}.or \co|
|00002710| 64 65 7b 50 79 5f 44 45 | 43 52 45 46 28 29 7d 20 |de{Py_DE|CREF()} |
|00002720| 63 61 6c 6c 73 20 66 6f | 72 20 6f 62 6a 65 63 74 |calls fo|r object|
|00002730| 73 20 79 6f 75 20 68 61 | 76 65 20 61 6c 72 65 61 |s you ha|ve alrea|
|00002740| 64 79 20 63 72 65 61 74 | 65 64 29 20 77 68 65 6e |dy creat|ed) when|
|00002750| 0a 79 6f 75 20 72 65 74 | 75 72 6e 20 61 6e 20 65 |.you ret|urn an e|
|00002760| 72 72 6f 72 20 69 6e 64 | 69 63 61 74 6f 72 21 0a |rror ind|icator!.|
|00002770| 0a 54 68 65 20 63 68 6f | 69 63 65 20 6f 66 20 77 |.The cho|ice of w|
|00002780| 68 69 63 68 20 65 78 63 | 65 70 74 69 6f 6e 20 74 |hich exc|eption t|
|00002790| 6f 20 72 61 69 73 65 20 | 69 73 20 65 6e 74 69 72 |o raise |is entir|
|000027a0| 65 6c 79 20 79 6f 75 72 | 73 2e 20 20 54 68 65 72 |ely your|s.  Ther|
|000027b0| 65 20 61 72 65 0a 70 72 | 65 64 65 63 6c 61 72 65 |e are.pr|edeclare|
|000027c0| 64 20 43 20 6f 62 6a 65 | 63 74 73 20 63 6f 72 72 |d C obje|cts corr|
|000027d0| 65 73 70 6f 6e 64 69 6e | 67 20 74 6f 20 61 6c 6c |espondin|g to all|
|000027e0| 20 62 75 69 6c 74 2d 69 | 6e 20 50 79 74 68 6f 6e | built-i|n Python|
|000027f0| 20 65 78 63 65 70 74 69 | 6f 6e 73 2c 0a 65 2e 67 | excepti|ons,.e.g|
|00002800| 2e 20 5c 63 6f 64 65 7b | 50 79 45 78 63 5f 5a 65 |. \code{|PyExc_Ze|
|00002810| 72 6f 44 65 76 69 73 69 | 6f 6e 45 72 72 6f 72 7d |roDevisi|onError}|
|00002820| 20 77 68 69 63 68 20 79 | 6f 75 20 63 61 6e 20 75 | which y|ou can u|
|00002830| 73 65 20 64 69 72 65 63 | 74 6c 79 2e 20 20 4f 66 |se direc|tly.  Of|
|00002840| 0a 63 6f 75 72 73 65 2c | 20 79 6f 75 20 73 68 6f |.course,| you sho|
|00002850| 75 6c 64 20 63 68 6f 6f | 73 65 20 65 78 63 65 70 |uld choo|se excep|
|00002860| 74 69 6f 6e 73 20 77 69 | 73 65 6c 79 20 2d 2d 2d |tions wi|sely ---|
|00002870| 20 64 6f 6e 27 74 20 75 | 73 65 0a 5c 63 6f 64 65 | don't u|se.\code|
|00002880| 7b 50 79 45 78 63 5f 54 | 79 70 65 45 72 72 6f 72 |{PyExc_T|ypeError|
|00002890| 7d 20 74 6f 20 6d 65 61 | 6e 20 74 68 61 74 20 61 |} to mea|n that a|
|000028a0| 20 66 69 6c 65 20 63 6f | 75 6c 64 6e 27 74 20 62 | file co|uldn't b|
|000028b0| 65 20 6f 70 65 6e 65 64 | 20 28 74 68 61 74 0a 73 |e opened| (that.s|
|000028c0| 68 6f 75 6c 64 20 70 72 | 6f 62 61 62 6c 79 20 62 |hould pr|obably b|
|000028d0| 65 20 5c 63 6f 64 65 7b | 50 79 45 78 63 5f 49 4f |e \code{|PyExc_IO|
|000028e0| 45 72 72 6f 72 7d 29 2e | 20 20 49 66 20 73 6f 6d |Error}).|  If som|
|000028f0| 65 74 68 69 6e 67 27 73 | 20 77 72 6f 6e 67 20 77 |ething's| wrong w|
|00002900| 69 74 68 0a 74 68 65 20 | 61 72 67 75 6d 65 6e 74 |ith.the |argument|
|00002910| 20 6c 69 73 74 2c 20 74 | 68 65 20 5c 63 6f 64 65 | list, t|he \code|
|00002920| 7b 50 79 41 72 67 5f 50 | 61 72 73 65 54 75 70 6c |{PyArg_P|arseTupl|
|00002930| 65 28 29 7d 20 66 75 6e | 63 74 69 6f 6e 20 75 73 |e()} fun|ction us|
|00002940| 75 61 6c 6c 79 0a 72 61 | 69 73 65 73 20 5c 63 6f |ually.ra|ises \co|
|00002950| 64 65 7b 50 79 45 78 63 | 5f 54 79 70 65 45 72 72 |de{PyExc|_TypeErr|
|00002960| 6f 72 7d 2e 20 20 49 66 | 20 79 6f 75 20 68 61 76 |or}.  If| you hav|
|00002970| 65 20 61 6e 20 61 72 67 | 75 6d 65 6e 74 20 77 68 |e an arg|ument wh|
|00002980| 6f 73 65 20 76 61 6c 75 | 65 0a 77 68 69 63 68 20 |ose valu|e.which |
|00002990| 6d 75 73 74 20 62 65 20 | 69 6e 20 61 20 70 61 72 |must be |in a par|
|000029a0| 74 69 63 75 6c 61 72 20 | 72 61 6e 67 65 20 6f 72 |ticular |range or|
|000029b0| 20 6d 75 73 74 20 73 61 | 74 69 73 66 79 20 6f 74 | must sa|tisfy ot|
|000029c0| 68 65 72 20 63 6f 6e 64 | 69 74 69 6f 6e 73 2c 0a |her cond|itions,.|
|000029d0| 5c 63 6f 64 65 7b 50 79 | 45 78 63 5f 56 61 6c 75 |\code{Py|Exc_Valu|
|000029e0| 65 45 72 72 6f 72 7d 20 | 69 73 20 61 70 70 72 6f |eError} |is appro|
|000029f0| 70 72 69 61 74 65 2e 0a | 0a 59 6f 75 20 63 61 6e |priate..|.You can|
|00002a00| 20 61 6c 73 6f 20 64 65 | 66 69 6e 65 20 61 20 6e | also de|fine a n|
|00002a10| 65 77 20 65 78 63 65 70 | 74 69 6f 6e 20 74 68 61 |ew excep|tion tha|
|00002a20| 74 20 69 73 20 75 6e 69 | 71 75 65 20 74 6f 20 79 |t is uni|que to y|
|00002a30| 6f 75 72 20 6d 6f 64 75 | 6c 65 2e 0a 46 6f 72 20 |our modu|le..For |
|00002a40| 74 68 69 73 2c 20 79 6f | 75 20 75 73 75 61 6c 6c |this, yo|u usuall|
|00002a50| 79 20 64 65 63 6c 61 72 | 65 20 61 20 73 74 61 74 |y declar|e a stat|
|00002a60| 69 63 20 6f 62 6a 65 63 | 74 20 76 61 72 69 61 62 |ic objec|t variab|
|00002a70| 6c 65 20 61 74 20 74 68 | 65 0a 62 65 67 69 6e 6e |le at th|e.beginn|
|00002a80| 69 6e 67 20 6f 66 20 79 | 6f 75 72 20 66 69 6c 65 |ing of y|our file|
|00002a90| 2c 20 65 2e 67 2e 0a 0a | 5c 62 65 67 69 6e 7b 76 |, e.g...|\begin{v|
|00002aa0| 65 72 62 61 74 69 6d 7d | 0a 20 20 20 20 73 74 61 |erbatim}|.    sta|
|00002ab0| 74 69 63 20 50 79 4f 62 | 6a 65 63 74 20 2a 53 70 |tic PyOb|ject *Sp|
|00002ac0| 61 6d 45 72 72 6f 72 3b | 0a 5c 65 6e 64 7b 76 65 |amError;|.\end{ve|
|00002ad0| 72 62 61 74 69 6d 7d 0a | 0a 61 6e 64 20 69 6e 69 |rbatim}.|.and ini|
|00002ae0| 74 69 61 6c 69 7a 65 20 | 69 74 20 69 6e 20 79 6f |tialize |it in yo|
|00002af0| 75 72 20 6d 6f 64 75 6c | 65 27 73 20 69 6e 69 74 |ur modul|e's init|
|00002b00| 69 61 6c 69 7a 61 74 69 | 6f 6e 20 66 75 6e 63 74 |ializati|on funct|
|00002b10| 69 6f 6e 0a 28 5c 63 6f | 64 65 7b 69 6e 69 74 73 |ion.(\co|de{inits|
|00002b20| 70 61 6d 28 29 7d 29 20 | 77 69 74 68 20 61 20 73 |pam()}) |with a s|
|00002b30| 74 72 69 6e 67 20 6f 62 | 6a 65 63 74 2c 20 65 2e |tring ob|ject, e.|
|00002b40| 67 2e 20 28 6c 65 61 76 | 69 6e 67 20 6f 75 74 20 |g. (leav|ing out |
|00002b50| 74 68 65 20 65 72 72 6f | 72 0a 63 68 65 63 6b 69 |the erro|r.checki|
|00002b60| 6e 67 20 66 6f 72 20 6e | 6f 77 29 3a 0a 0a 5c 62 |ng for n|ow):..\b|
|00002b70| 65 67 69 6e 7b 76 65 72 | 62 61 74 69 6d 7d 0a 20 |egin{ver|batim}. |
|00002b80| 20 20 20 76 6f 69 64 0a | 20 20 20 20 69 6e 69 74 |   void.|    init|
|00002b90| 73 70 61 6d 28 29 0a 20 | 20 20 20 7b 0a 20 20 20 |spam(). |   {.   |
|00002ba0| 20 20 20 20 20 50 79 4f | 62 6a 65 63 74 20 2a 6d |     PyO|bject *m|
|00002bb0| 2c 20 2a 64 3b 0a 20 20 | 20 20 20 20 20 20 6d 20 |, *d;.  |      m |
|00002bc0| 3d 20 50 79 5f 49 6e 69 | 74 4d 6f 64 75 6c 65 28 |= Py_Ini|tModule(|
|00002bd0| 22 73 70 61 6d 22 2c 20 | 53 70 61 6d 4d 65 74 68 |"spam", |SpamMeth|
|00002be0| 6f 64 73 29 3b 0a 20 20 | 20 20 20 20 20 20 64 20 |ods);.  |      d |
|00002bf0| 3d 20 50 79 4d 6f 64 75 | 6c 65 5f 47 65 74 44 69 |= PyModu|le_GetDi|
|00002c00| 63 74 28 6d 29 3b 0a 20 | 20 20 20 20 20 20 20 53 |ct(m);. |       S|
|00002c10| 70 61 6d 45 72 72 6f 72 | 20 3d 20 50 79 53 74 72 |pamError| = PyStr|
|00002c20| 69 6e 67 5f 46 72 6f 6d | 53 74 72 69 6e 67 28 22 |ing_From|String("|
|00002c30| 73 70 61 6d 2e 65 72 72 | 6f 72 22 29 3b 0a 20 20 |spam.err|or");.  |
|00002c40| 20 20 20 20 20 20 50 79 | 44 69 63 74 5f 53 65 74 |      Py|Dict_Set|
|00002c50| 49 74 65 6d 53 74 72 69 | 6e 67 28 64 2c 20 22 65 |ItemStri|ng(d, "e|
|00002c60| 72 72 6f 72 22 2c 20 53 | 70 61 6d 45 72 72 6f 72 |rror", S|pamError|
|00002c70| 29 3b 0a 20 20 20 20 7d | 0a 5c 65 6e 64 7b 76 65 |);.    }|.\end{ve|
|00002c80| 72 62 61 74 69 6d 7d 0a | 0a 4e 6f 74 65 20 74 68 |rbatim}.|.Note th|
|00002c90| 61 74 20 74 68 65 20 50 | 79 74 68 6f 6e 20 6e 61 |at the P|ython na|
|00002ca0| 6d 65 20 66 6f 72 20 74 | 68 65 20 65 78 63 65 70 |me for t|he excep|
|00002cb0| 74 69 6f 6e 20 6f 62 6a | 65 63 74 20 69 73 0a 5c |tion obj|ect is.\|
|00002cc0| 63 6f 64 65 7b 73 70 61 | 6d 2e 65 72 72 6f 72 7d |code{spa|m.error}|
|00002cd0| 2e 20 20 49 74 20 69 73 | 20 63 6f 6e 76 65 6e 74 |.  It is| convent|
|00002ce0| 69 6f 6e 61 6c 20 66 6f | 72 20 6d 6f 64 75 6c 65 |ional fo|r module|
|00002cf0| 20 61 6e 64 20 65 78 63 | 65 70 74 69 6f 6e 20 6e | and exc|eption n|
|00002d00| 61 6d 65 73 0a 74 6f 20 | 62 65 20 73 70 65 6c 6c |ames.to |be spell|
|00002d10| 65 64 20 69 6e 20 6c 6f | 77 65 72 20 63 61 73 65 |ed in lo|wer case|
|00002d20| 2e 20 20 49 74 20 69 73 | 20 61 6c 73 6f 20 63 6f |.  It is| also co|
|00002d30| 6e 76 65 6e 74 69 6f 6e | 61 6c 20 74 68 61 74 20 |nvention|al that |
|00002d40| 74 68 65 0a 5c 65 6d 70 | 68 7b 76 61 6c 75 65 7d |the.\emp|h{value}|
|00002d50| 20 6f 66 20 74 68 65 20 | 65 78 63 65 70 74 69 6f | of the |exceptio|
|00002d60| 6e 20 6f 62 6a 65 63 74 | 20 69 73 20 74 68 65 20 |n object| is the |
|00002d70| 73 61 6d 65 20 61 73 20 | 69 74 73 20 6e 61 6d 65 |same as |its name|
|00002d80| 2c 20 65 2e 67 2e 5c 0a | 74 68 65 20 73 74 72 69 |, e.g.\.|the stri|
|00002d90| 6e 67 20 5c 63 6f 64 65 | 7b 22 73 70 61 6d 2e 65 |ng \code|{"spam.e|
|00002da0| 72 72 6f 72 22 7d 2e 0a | 0a 0a 5c 73 65 63 74 69 |rror"}..|..\secti|
|00002db0| 6f 6e 7b 42 61 63 6b 20 | 74 6f 20 74 68 65 20 45 |on{Back |to the E|
|00002dc0| 78 61 6d 70 6c 65 7d 0a | 0a 47 6f 69 6e 67 20 62 |xample}.|.Going b|
|00002dd0| 61 63 6b 20 74 6f 20 6f | 75 72 20 65 78 61 6d 70 |ack to o|ur examp|
|00002de0| 6c 65 20 66 75 6e 63 74 | 69 6f 6e 2c 20 79 6f 75 |le funct|ion, you|
|00002df0| 20 73 68 6f 75 6c 64 20 | 6e 6f 77 20 62 65 20 61 | should |now be a|
|00002e00| 62 6c 65 20 74 6f 0a 75 | 6e 64 65 72 73 74 61 6e |ble to.u|nderstan|
|00002e10| 64 20 74 68 69 73 20 73 | 74 61 74 65 6d 65 6e 74 |d this s|tatement|
|00002e20| 3a 0a 0a 5c 62 65 67 69 | 6e 7b 76 65 72 62 61 74 |:..\begi|n{verbat|
|00002e30| 69 6d 7d 0a 20 20 20 20 | 20 20 20 20 69 66 20 28 |im}.    |    if (|
|00002e40| 21 50 79 41 72 67 5f 50 | 61 72 73 65 54 75 70 6c |!PyArg_P|arseTupl|
|00002e50| 65 28 61 72 67 73 2c 20 | 22 73 22 2c 20 26 63 6f |e(args, |"s", &co|
|00002e60| 6d 6d 61 6e 64 29 29 0a | 20 20 20 20 20 20 20 20 |mmand)).|        |
|00002e70| 20 20 20 20 72 65 74 75 | 72 6e 20 4e 55 4c 4c 3b |    retu|rn NULL;|
|00002e80| 0a 5c 65 6e 64 7b 76 65 | 72 62 61 74 69 6d 7d 0a |.\end{ve|rbatim}.|
|00002e90| 0a 49 74 20 72 65 74 75 | 72 6e 73 20 5c 63 6f 64 |.It retu|rns \cod|
|00002ea0| 65 7b 4e 55 4c 4c 7d 20 | 28 74 68 65 20 65 72 72 |e{NULL} |(the err|
|00002eb0| 6f 72 20 69 6e 64 69 63 | 61 74 6f 72 20 66 6f 72 |or indic|ator for|
|00002ec0| 20 66 75 6e 63 74 69 6f | 6e 73 20 72 65 74 75 72 | functio|ns retur|
|00002ed0| 6e 69 6e 67 0a 6f 62 6a | 65 63 74 20 70 6f 69 6e |ning.obj|ect poin|
|00002ee0| 74 65 72 73 29 20 69 66 | 20 61 6e 20 65 72 72 6f |ters) if| an erro|
|00002ef0| 72 20 69 73 20 64 65 74 | 65 63 74 65 64 20 69 6e |r is det|ected in|
|00002f00| 20 74 68 65 20 61 72 67 | 75 6d 65 6e 74 20 6c 69 | the arg|ument li|
|00002f10| 73 74 2c 20 72 65 6c 79 | 69 6e 67 0a 6f 6e 20 74 |st, rely|ing.on t|
|00002f20| 68 65 20 65 78 63 65 70 | 74 69 6f 6e 20 73 65 74 |he excep|tion set|
|00002f30| 20 62 79 20 5c 63 6f 64 | 65 7b 50 79 41 72 67 5f | by \cod|e{PyArg_|
|00002f40| 50 61 72 73 65 54 75 70 | 6c 65 28 29 7d 2e 20 20 |ParseTup|le()}.  |
|00002f50| 4f 74 68 65 72 77 69 73 | 65 20 74 68 65 0a 73 74 |Otherwis|e the.st|
|00002f60| 72 69 6e 67 20 76 61 6c | 75 65 20 6f 66 20 74 68 |ring val|ue of th|
|00002f70| 65 20 61 72 67 75 6d 65 | 6e 74 20 68 61 73 20 62 |e argume|nt has b|
|00002f80| 65 65 6e 20 63 6f 70 69 | 65 64 20 74 6f 20 74 68 |een copi|ed to th|
|00002f90| 65 20 6c 6f 63 61 6c 20 | 76 61 72 69 61 62 6c 65 |e local |variable|
|00002fa0| 0a 5c 63 6f 64 65 7b 63 | 6f 6d 6d 61 6e 64 7d 2e |.\code{c|ommand}.|
|00002fb0| 20 20 54 68 69 73 20 69 | 73 20 61 20 70 6f 69 6e |  This i|s a poin|
|00002fc0| 74 65 72 20 61 73 73 69 | 67 6e 6d 65 6e 74 20 61 |ter assi|gnment a|
|00002fd0| 6e 64 20 79 6f 75 20 61 | 72 65 20 6e 6f 74 20 73 |nd you a|re not s|
|00002fe0| 75 70 70 6f 73 65 64 0a | 74 6f 20 6d 6f 64 69 66 |upposed.|to modif|
|00002ff0| 79 20 74 68 65 20 73 74 | 72 69 6e 67 20 74 6f 20 |y the st|ring to |
|00003000| 77 68 69 63 68 20 69 74 | 20 70 6f 69 6e 74 73 20 |which it| points |
|00003010| 28 73 6f 20 69 6e 20 53 | 74 61 6e 64 61 72 64 20 |(so in S|tandard |
|00003020| 43 2c 20 74 68 65 20 76 | 61 72 69 61 62 6c 65 0a |C, the v|ariable.|
|00003030| 5c 63 6f 64 65 7b 63 6f | 6d 6d 61 6e 64 7d 20 73 |\code{co|mmand} s|
|00003040| 68 6f 75 6c 64 20 70 72 | 6f 70 65 72 6c 79 20 62 |hould pr|operly b|
|00003050| 65 20 64 65 63 6c 61 72 | 65 64 20 61 73 20 5c 73 |e declar|ed as \s|
|00003060| 61 6d 70 7b 63 6f 6e 73 | 74 20 63 68 61 72 0a 2a |amp{cons|t char.*|
|00003070| 63 6f 6d 6d 61 6e 64 7d | 29 2e 0a 0a 54 68 65 20 |command}|)...The |
|00003080| 6e 65 78 74 20 73 74 61 | 74 65 6d 65 6e 74 20 69 |next sta|tement i|
|00003090| 73 20 61 20 63 61 6c 6c | 20 74 6f 20 74 68 65 20 |s a call| to the |
|000030a0| 5c 55 4e 49 58 7b 7d 20 | 66 75 6e 63 74 69 6f 6e |\UNIX{} |function|
|000030b0| 20 5c 63 6f 64 65 7b 73 | 79 73 74 65 6d 28 29 7d | \code{s|ystem()}|
|000030c0| 2c 0a 70 61 73 73 69 6e | 67 20 69 74 20 74 68 65 |,.passin|g it the|
|000030d0| 20 73 74 72 69 6e 67 20 | 77 65 20 6a 75 73 74 20 | string |we just |
|000030e0| 67 6f 74 20 66 72 6f 6d | 20 5c 63 6f 64 65 7b 50 |got from| \code{P|
|000030f0| 79 41 72 67 5f 50 61 72 | 73 65 54 75 70 6c 65 28 |yArg_Par|seTuple(|
|00003100| 29 7d 3a 0a 0a 5c 62 65 | 67 69 6e 7b 76 65 72 62 |)}:..\be|gin{verb|
|00003110| 61 74 69 6d 7d 0a 20 20 | 20 20 20 20 20 20 73 74 |atim}.  |      st|
|00003120| 73 20 3d 20 73 79 73 74 | 65 6d 28 63 6f 6d 6d 61 |s = syst|em(comma|
|00003130| 6e 64 29 3b 0a 5c 65 6e | 64 7b 76 65 72 62 61 74 |nd);.\en|d{verbat|
|00003140| 69 6d 7d 0a 0a 4f 75 72 | 20 5c 63 6f 64 65 7b 73 |im}..Our| \code{s|
|00003150| 70 61 6d 2e 73 79 73 74 | 65 6d 28 29 7d 20 66 75 |pam.syst|em()} fu|
|00003160| 6e 63 74 69 6f 6e 20 6d | 75 73 74 20 72 65 74 75 |nction m|ust retu|
|00003170| 72 6e 20 74 68 65 20 76 | 61 6c 75 65 20 6f 66 20 |rn the v|alue of |
|00003180| 5c 63 6f 64 65 7b 73 79 | 73 7d 0a 61 73 20 61 20 |\code{sy|s}.as a |
|00003190| 50 79 74 68 6f 6e 20 6f | 62 6a 65 63 74 2e 20 20 |Python o|bject.  |
|000031a0| 54 68 69 73 20 69 73 20 | 64 6f 6e 65 20 75 73 69 |This is |done usi|
|000031b0| 6e 67 20 74 68 65 20 66 | 75 6e 63 74 69 6f 6e 0a |ng the f|unction.|
|000031c0| 5c 63 6f 64 65 7b 50 79 | 5f 42 75 69 6c 64 56 61 |\code{Py|_BuildVa|
|000031d0| 6c 75 65 28 29 7d 2c 20 | 77 68 69 63 68 20 69 73 |lue()}, |which is|
|000031e0| 20 73 6f 6d 65 74 68 69 | 6e 67 20 6c 69 6b 65 20 | somethi|ng like |
|000031f0| 74 68 65 20 69 6e 76 65 | 72 73 65 20 6f 66 0a 5c |the inve|rse of.\|
|00003200| 63 6f 64 65 7b 50 79 41 | 72 67 5f 50 61 72 73 65 |code{PyA|rg_Parse|
|00003210| 54 75 70 6c 65 28 29 7d | 3a 20 69 74 20 74 61 6b |Tuple()}|: it tak|
|00003220| 65 73 20 61 20 66 6f 72 | 6d 61 74 20 73 74 72 69 |es a for|mat stri|
|00003230| 6e 67 20 61 6e 64 20 61 | 6e 20 61 72 62 69 74 72 |ng and a|n arbitr|
|00003240| 61 72 79 0a 6e 75 6d 62 | 65 72 20 6f 66 20 43 20 |ary.numb|er of C |
|00003250| 76 61 6c 75 65 73 2c 20 | 61 6e 64 20 72 65 74 75 |values, |and retu|
|00003260| 72 6e 73 20 61 20 6e 65 | 77 20 50 79 74 68 6f 6e |rns a ne|w Python|
|00003270| 20 6f 62 6a 65 63 74 2e | 20 20 4d 6f 72 65 20 69 | object.|  More i|
|00003280| 6e 66 6f 20 6f 6e 0a 5c | 63 6f 64 65 7b 50 79 5f |nfo on.\|code{Py_|
|00003290| 42 75 69 6c 64 56 61 6c | 75 65 28 29 7d 20 69 73 |BuildVal|ue()} is|
|000032a0| 20 67 69 76 65 6e 20 6c | 61 74 65 72 2e 0a 0a 5c | given l|ater...\|
|000032b0| 62 65 67 69 6e 7b 76 65 | 72 62 61 74 69 6d 7d 0a |begin{ve|rbatim}.|
|000032c0| 20 20 20 20 20 20 20 20 | 72 65 74 75 72 6e 20 50 |        |return P|
|000032d0| 79 5f 42 75 69 6c 64 56 | 61 6c 75 65 28 22 69 22 |y_BuildV|alue("i"|
|000032e0| 2c 20 73 74 73 29 3b 0a | 5c 65 6e 64 7b 76 65 72 |, sts);.|\end{ver|
|000032f0| 62 61 74 69 6d 7d 0a 0a | 49 6e 20 74 68 69 73 20 |batim}..|In this |
|00003300| 63 61 73 65 2c 20 69 74 | 20 77 69 6c 6c 20 72 65 |case, it| will re|
|00003310| 74 75 72 6e 20 61 6e 20 | 69 6e 74 65 67 65 72 20 |turn an |integer |
|00003320| 6f 62 6a 65 63 74 2e 20 | 20 28 59 65 73 2c 20 65 |object. | (Yes, e|
|00003330| 76 65 6e 20 69 6e 74 65 | 67 65 72 73 0a 61 72 65 |ven inte|gers.are|
|00003340| 20 6f 62 6a 65 63 74 73 | 20 6f 6e 20 74 68 65 20 | objects| on the |
|00003350| 68 65 61 70 20 69 6e 20 | 50 79 74 68 6f 6e 21 29 |heap in |Python!)|
|00003360| 0a 0a 49 66 20 79 6f 75 | 20 68 61 76 65 20 61 20 |..If you| have a |
|00003370| 43 20 66 75 6e 63 74 69 | 6f 6e 20 74 68 61 74 20 |C functi|on that |
|00003380| 72 65 74 75 72 6e 73 20 | 6e 6f 20 75 73 65 66 75 |returns |no usefu|
|00003390| 6c 20 61 72 67 75 6d 65 | 6e 74 20 28 61 20 66 75 |l argume|nt (a fu|
|000033a0| 6e 63 74 69 6f 6e 0a 72 | 65 74 75 72 6e 69 6e 67 |nction.r|eturning|
|000033b0| 20 5c 63 6f 64 65 7b 76 | 6f 69 64 7d 29 2c 20 74 | \code{v|oid}), t|
|000033c0| 68 65 20 63 6f 72 72 65 | 73 70 6f 6e 64 69 6e 67 |he corre|sponding|
|000033d0| 20 50 79 74 68 6f 6e 20 | 66 75 6e 63 74 69 6f 6e | Python |function|
|000033e0| 20 6d 75 73 74 20 72 65 | 74 75 72 6e 0a 5c 63 6f | must re|turn.\co|
|000033f0| 64 65 7b 4e 6f 6e 65 7d | 2e 20 20 20 59 6f 75 20 |de{None}|.   You |
|00003400| 6e 65 65 64 20 74 68 69 | 73 20 69 64 69 6f 6d 20 |need thi|s idiom |
|00003410| 74 6f 20 64 6f 20 73 6f | 3a 0a 0a 5c 62 65 67 69 |to do so|:..\begi|
|00003420| 6e 7b 76 65 72 62 61 74 | 69 6d 7d 0a 20 20 20 20 |n{verbat|im}.    |
|00003430| 20 20 20 20 50 79 5f 49 | 4e 43 52 45 46 28 50 79 |    Py_I|NCREF(Py|
|00003440| 5f 4e 6f 6e 65 29 3b 0a | 20 20 20 20 20 20 20 20 |_None);.|        |
|00003450| 72 65 74 75 72 6e 20 50 | 79 5f 4e 6f 6e 65 3b 0a |return P|y_None;.|
|00003460| 5c 65 6e 64 7b 76 65 72 | 62 61 74 69 6d 7d 0a 0a |\end{ver|batim}..|
|00003470| 5c 63 6f 64 65 7b 50 79 | 5f 4e 6f 6e 65 7d 20 69 |\code{Py|_None} i|
|00003480| 73 20 74 68 65 20 43 20 | 6e 61 6d 65 20 66 6f 72 |s the C |name for|
|00003490| 20 74 68 65 20 73 70 65 | 63 69 61 6c 20 50 79 74 | the spe|cial Pyt|
|000034a0| 68 6f 6e 20 6f 62 6a 65 | 63 74 0a 5c 63 6f 64 65 |hon obje|ct.\code|
|000034b0| 7b 4e 6f 6e 65 7d 2e 20 | 20 49 74 20 69 73 20 61 |{None}. | It is a|
|000034c0| 20 67 65 6e 75 69 6e 65 | 20 50 79 74 68 6f 6e 20 | genuine| Python |
|000034d0| 6f 62 6a 65 63 74 20 28 | 6e 6f 74 20 61 20 5c 63 |object (|not a \c|
|000034e0| 6f 64 65 7b 4e 55 4c 4c | 7d 0a 70 6f 69 6e 74 65 |ode{NULL|}.pointe|
|000034f0| 72 2c 20 77 68 69 63 68 | 20 6d 65 61 6e 73 20 60 |r, which| means `|
|00003500| 60 65 72 72 6f 72 27 27 | 20 69 6e 20 6d 6f 73 74 |`error''| in most|
|00003510| 20 63 6f 6e 74 65 78 74 | 73 2c 20 61 73 20 77 65 | context|s, as we|
|00003520| 20 68 61 76 65 20 73 65 | 65 6e 29 2e 0a 0a 0a 5c | have se|en)....\|
|00003530| 73 65 63 74 69 6f 6e 7b | 54 68 65 20 4d 6f 64 75 |section{|The Modu|
|00003540| 6c 65 27 73 20 4d 65 74 | 68 6f 64 20 54 61 62 6c |le's Met|hod Tabl|
|00003550| 65 20 61 6e 64 20 49 6e | 69 74 69 61 6c 69 7a 61 |e and In|itializa|
|00003560| 74 69 6f 6e 20 46 75 6e | 63 74 69 6f 6e 7d 0a 0a |tion Fun|ction}..|
|00003570| 49 20 70 72 6f 6d 69 73 | 65 64 20 74 6f 20 73 68 |I promis|ed to sh|
|00003580| 6f 77 20 68 6f 77 20 5c | 63 6f 64 65 7b 73 70 61 |ow how \|code{spa|
|00003590| 6d 5f 73 79 73 74 65 6d | 28 29 7d 20 69 73 20 63 |m_system|()} is c|
|000035a0| 61 6c 6c 65 64 20 66 72 | 6f 6d 20 50 79 74 68 6f |alled fr|om Pytho|
|000035b0| 6e 0a 70 72 6f 67 72 61 | 6d 73 2e 20 20 46 69 72 |n.progra|ms.  Fir|
|000035c0| 73 74 2c 20 77 65 20 6e | 65 65 64 20 74 6f 20 6c |st, we n|eed to l|
|000035d0| 69 73 74 20 69 74 73 20 | 6e 61 6d 65 20 61 6e 64 |ist its |name and|
|000035e0| 20 61 64 64 72 65 73 73 | 20 69 6e 20 61 20 60 60 | address| in a ``|
|000035f0| 6d 65 74 68 6f 64 0a 74 | 61 62 6c 65 27 27 3a 0a |method.t|able'':.|
|00003600| 0a 5c 62 65 67 69 6e 7b | 76 65 72 62 61 74 69 6d |.\begin{|verbatim|
|00003610| 7d 0a 20 20 20 20 73 74 | 61 74 69 63 20 50 79 4d |}.    st|atic PyM|
|00003620| 65 74 68 6f 64 44 65 66 | 20 53 70 61 6d 4d 65 74 |ethodDef| SpamMet|
|00003630| 68 6f 64 73 5b 5d 20 3d | 20 7b 0a 20 20 20 20 20 |hods[] =| {.     |
|00003640| 20 20 20 2e 2e 2e 0a 20 | 20 20 20 20 20 20 20 7b |   .... |       {|
|00003650| 22 73 79 73 74 65 6d 22 | 2c 20 20 73 70 61 6d 5f |"system"|,  spam_|
|00003660| 73 79 73 74 65 6d 2c 20 | 31 7d 2c 0a 20 20 20 20 |system, |1},.    |
|00003670| 20 20 20 20 2e 2e 2e 0a | 20 20 20 20 20 20 20 20 |    ....|        |
|00003680| 7b 4e 55 4c 4c 2c 20 20 | 20 20 20 20 4e 55 4c 4c |{NULL,  |    NULL|
|00003690| 7d 20 20 20 20 20 20 20 | 20 2f 2a 20 53 65 6e 74 |}       | /* Sent|
|000036a0| 69 6e 65 6c 20 2a 2f 0a | 20 20 20 20 7d 3b 0a 5c |inel */.|    };.\|
|000036b0| 65 6e 64 7b 76 65 72 62 | 61 74 69 6d 7d 0a 0a 4e |end{verb|atim}..N|
|000036c0| 6f 74 65 20 74 68 65 20 | 74 68 69 72 64 20 65 6e |ote the |third en|
|000036d0| 74 72 79 20 28 5c 73 61 | 6d 70 7b 31 7d 29 2e 20 |try (\sa|mp{1}). |
|000036e0| 20 54 68 69 73 20 69 73 | 20 61 20 66 6c 61 67 20 | This is| a flag |
|000036f0| 74 65 6c 6c 69 6e 67 20 | 74 68 65 0a 69 6e 74 65 |telling |the.inte|
|00003700| 72 70 72 65 74 65 72 20 | 74 68 65 20 63 61 6c 6c |rpreter |the call|
|00003710| 69 6e 67 20 63 6f 6e 76 | 65 6e 74 69 6f 6e 20 74 |ing conv|ention t|
|00003720| 6f 20 62 65 20 75 73 65 | 64 20 66 6f 72 20 74 68 |o be use|d for th|
|00003730| 65 20 43 20 66 75 6e 63 | 74 69 6f 6e 2e 20 20 49 |e C func|tion.  I|
|00003740| 74 0a 73 68 6f 75 6c 64 | 20 6e 6f 72 6d 61 6c 6c |t.should| normall|
|00003750| 79 20 61 6c 77 61 79 73 | 20 62 65 20 5c 73 61 6d |y always| be \sam|
|00003760| 70 7b 31 7d 3b 20 61 20 | 76 61 6c 75 65 20 6f 66 |p{1}; a |value of|
|00003770| 20 5c 73 61 6d 70 7b 30 | 7d 20 6d 65 61 6e 73 20 | \samp{0|} means |
|00003780| 74 68 61 74 20 61 6e 0a | 6f 62 73 6f 6c 65 74 65 |that an.|obsolete|
|00003790| 20 76 61 72 69 61 6e 74 | 20 6f 66 20 5c 63 6f 64 | variant| of \cod|
|000037a0| 65 7b 50 79 41 72 67 5f | 50 61 72 73 65 54 75 70 |e{PyArg_|ParseTup|
|000037b0| 6c 65 28 29 7d 20 69 73 | 20 75 73 65 64 2e 0a 0a |le()} is| used...|
|000037c0| 54 68 65 20 6d 65 74 68 | 6f 64 20 74 61 62 6c 65 |The meth|od table|
|000037d0| 20 6d 75 73 74 20 62 65 | 20 70 61 73 73 65 64 20 | must be| passed |
|000037e0| 74 6f 20 74 68 65 20 69 | 6e 74 65 72 70 72 65 74 |to the i|nterpret|
|000037f0| 65 72 20 69 6e 20 74 68 | 65 20 6d 6f 64 75 6c 65 |er in th|e module|
|00003800| 27 73 0a 69 6e 69 74 69 | 61 6c 69 7a 61 74 69 6f |'s.initi|alizatio|
|00003810| 6e 20 66 75 6e 63 74 69 | 6f 6e 20 28 77 68 69 63 |n functi|on (whic|
|00003820| 68 20 73 68 6f 75 6c 64 | 20 62 65 20 74 68 65 20 |h should| be the |
|00003830| 6f 6e 6c 79 20 6e 6f 6e | 2d 5c 63 6f 64 65 7b 73 |only non|-\code{s|
|00003840| 74 61 74 69 63 7d 0a 69 | 74 65 6d 20 64 65 66 69 |tatic}.i|tem defi|
|00003850| 6e 65 64 20 69 6e 20 74 | 68 65 20 6d 6f 64 75 6c |ned in t|he modul|
|00003860| 65 20 66 69 6c 65 29 3a | 0a 0a 5c 62 65 67 69 6e |e file):|..\begin|
|00003870| 7b 76 65 72 62 61 74 69 | 6d 7d 0a 20 20 20 20 76 |{verbati|m}.    v|
|00003880| 6f 69 64 0a 20 20 20 20 | 69 6e 69 74 73 70 61 6d |oid.    |initspam|
|00003890| 28 29 0a 20 20 20 20 7b | 0a 20 20 20 20 20 20 20 |().    {|.       |
|000038a0| 20 28 76 6f 69 64 29 20 | 50 79 5f 49 6e 69 74 4d | (void) |Py_InitM|
|000038b0| 6f 64 75 6c 65 28 22 73 | 70 61 6d 22 2c 20 53 70 |odule("s|pam", Sp|
|000038c0| 61 6d 4d 65 74 68 6f 64 | 73 29 3b 0a 20 20 20 20 |amMethod|s);.    |
|000038d0| 7d 0a 5c 65 6e 64 7b 76 | 65 72 62 61 74 69 6d 7d |}.\end{v|erbatim}|
|000038e0| 0a 0a 57 68 65 6e 20 74 | 68 65 20 50 79 74 68 6f |..When t|he Pytho|
|000038f0| 6e 20 70 72 6f 67 72 61 | 6d 20 69 6d 70 6f 72 74 |n progra|m import|
|00003900| 73 20 6d 6f 64 75 6c 65 | 20 5c 63 6f 64 65 7b 73 |s module| \code{s|
|00003910| 70 61 6d 7d 20 66 6f 72 | 20 74 68 65 20 66 69 72 |pam} for| the fir|
|00003920| 73 74 20 74 69 6d 65 2c | 0a 5c 63 6f 64 65 7b 69 |st time,|.\code{i|
|00003930| 6e 69 74 73 70 61 6d 28 | 29 7d 20 69 73 20 63 61 |nitspam(|)} is ca|
|00003940| 6c 6c 65 64 2e 20 20 49 | 74 20 63 61 6c 6c 73 20 |lled.  I|t calls |
|00003950| 5c 63 6f 64 65 7b 50 79 | 5f 49 6e 69 74 4d 6f 64 |\code{Py|_InitMod|
|00003960| 75 6c 65 28 29 7d 2c 20 | 77 68 69 63 68 0a 63 72 |ule()}, |which.cr|
|00003970| 65 61 74 65 73 20 61 20 | 60 60 6d 6f 64 75 6c 65 |eates a |``module|
|00003980| 20 6f 62 6a 65 63 74 27 | 27 20 28 77 68 69 63 68 | object'|' (which|
|00003990| 20 69 73 20 69 6e 73 65 | 72 74 65 64 20 69 6e 20 | is inse|rted in |
|000039a0| 74 68 65 20 64 69 63 74 | 69 6f 6e 61 72 79 0a 5c |the dict|ionary.\|
|000039b0| 63 6f 64 65 7b 73 79 73 | 2e 6d 6f 64 75 6c 65 73 |code{sys|.modules|
|000039c0| 7d 20 75 6e 64 65 72 20 | 74 68 65 20 6b 65 79 20 |} under |the key |
|000039d0| 5c 63 6f 64 65 7b 22 73 | 70 61 6d 22 7d 29 2c 20 |\code{"s|pam"}), |
|000039e0| 61 6e 64 20 69 6e 73 65 | 72 74 73 20 62 75 69 6c |and inse|rts buil|
|000039f0| 74 2d 69 6e 0a 66 75 6e | 63 74 69 6f 6e 20 6f 62 |t-in.fun|ction ob|
|00003a00| 6a 65 63 74 73 20 69 6e | 74 6f 20 74 68 65 20 6e |jects in|to the n|
|00003a10| 65 77 6c 79 20 63 72 65 | 61 74 65 64 20 6d 6f 64 |ewly cre|ated mod|
|00003a20| 75 6c 65 20 62 61 73 65 | 64 20 75 70 6f 6e 20 74 |ule base|d upon t|
|00003a30| 68 65 20 74 61 62 6c 65 | 0a 28 61 6e 20 61 72 72 |he table|.(an arr|
|00003a40| 61 79 20 6f 66 20 5c 63 | 6f 64 65 7b 50 79 4d 65 |ay of \c|ode{PyMe|
|00003a50| 74 68 6f 64 44 65 66 7d | 20 73 74 72 75 63 74 75 |thodDef}| structu|
|00003a60| 72 65 73 29 20 74 68 61 | 74 20 77 61 73 20 70 61 |res) tha|t was pa|
|00003a70| 73 73 65 64 20 61 73 20 | 69 74 73 0a 73 65 63 6f |ssed as |its.seco|
|00003a80| 6e 64 20 61 72 67 75 6d | 65 6e 74 2e 20 20 5c 63 |nd argum|ent.  \c|
|00003a90| 6f 64 65 7b 50 79 5f 49 | 6e 69 74 4d 6f 64 75 6c |ode{Py_I|nitModul|
|00003aa0| 65 28 29 7d 20 72 65 74 | 75 72 6e 73 20 61 20 70 |e()} ret|urns a p|
|00003ab0| 6f 69 6e 74 65 72 20 74 | 6f 20 74 68 65 0a 6d 6f |ointer t|o the.mo|
|00003ac0| 64 75 6c 65 20 6f 62 6a | 65 63 74 20 74 68 61 74 |dule obj|ect that|
|00003ad0| 20 69 74 20 63 72 65 61 | 74 65 73 20 28 77 68 69 | it crea|tes (whi|
|00003ae0| 63 68 20 69 73 20 75 6e | 75 73 65 64 20 68 65 72 |ch is un|used her|
|00003af0| 65 29 2e 20 20 49 74 20 | 61 62 6f 72 74 73 20 77 |e).  It |aborts w|
|00003b00| 69 74 68 0a 61 20 66 61 | 74 61 6c 20 65 72 72 6f |ith.a fa|tal erro|
|00003b10| 72 20 69 66 20 74 68 65 | 20 6d 6f 64 75 6c 65 20 |r if the| module |
|00003b20| 63 6f 75 6c 64 20 6e 6f | 74 20 62 65 20 69 6e 69 |could no|t be ini|
|00003b30| 74 69 61 6c 69 7a 65 64 | 20 73 61 74 69 73 66 61 |tialized| satisfa|
|00003b40| 63 74 6f 72 69 6c 79 2c | 0a 73 6f 20 74 68 65 20 |ctorily,|.so the |
|00003b50| 63 61 6c 6c 65 72 20 64 | 6f 65 73 6e 27 74 20 6e |caller d|oesn't n|
|00003b60| 65 65 64 20 74 6f 20 63 | 68 65 63 6b 20 66 6f 72 |eed to c|heck for|
|00003b70| 20 65 72 72 6f 72 73 2e | 0a 0a 0a 5c 73 65 63 74 | errors.|...\sect|
|00003b80| 69 6f 6e 7b 43 6f 6d 70 | 69 6c 61 74 69 6f 6e 20 |ion{Comp|ilation |
|00003b90| 61 6e 64 20 4c 69 6e 6b | 61 67 65 7d 0a 0a 54 68 |and Link|age}..Th|
|00003ba0| 65 72 65 20 61 72 65 20 | 74 77 6f 20 6d 6f 72 65 |ere are |two more|
|00003bb0| 20 74 68 69 6e 67 73 20 | 74 6f 20 64 6f 20 62 65 | things |to do be|
|00003bc0| 66 6f 72 65 20 79 6f 75 | 20 63 61 6e 20 75 73 65 |fore you| can use|
|00003bd0| 20 79 6f 75 72 20 6e 65 | 77 20 65 78 74 65 6e 73 | your ne|w extens|
|00003be0| 69 6f 6e 3a 0a 63 6f 6d | 70 69 6c 69 6e 67 20 61 |ion:.com|piling a|
|00003bf0| 6e 64 20 6c 69 6e 6b 69 | 6e 67 20 69 74 20 77 69 |nd linki|ng it wi|
|00003c00| 74 68 20 74 68 65 20 50 | 79 74 68 6f 6e 20 73 79 |th the P|ython sy|
|00003c10| 73 74 65 6d 2e 20 20 49 | 66 20 79 6f 75 20 75 73 |stem.  I|f you us|
|00003c20| 65 20 64 79 6e 61 6d 69 | 63 0a 6c 6f 61 64 69 6e |e dynami|c.loadin|
|00003c30| 67 2c 20 74 68 65 20 64 | 65 74 61 69 6c 73 20 64 |g, the d|etails d|
|00003c40| 65 70 65 6e 64 20 6f 6e | 20 74 68 65 20 73 74 79 |epend on| the sty|
|00003c50| 6c 65 20 6f 66 20 64 79 | 6e 61 6d 69 63 20 6c 6f |le of dy|namic lo|
|00003c60| 61 64 69 6e 67 20 79 6f | 75 72 0a 73 79 73 74 65 |ading yo|ur.syste|
|00003c70| 6d 20 75 73 65 73 3b 20 | 73 65 65 20 74 68 65 20 |m uses; |see the |
|00003c80| 63 68 61 70 74 65 72 20 | 6f 6e 20 44 79 6e 61 6d |chapter |on Dynam|
|00003c90| 69 63 20 4c 6f 61 64 69 | 6e 67 20 66 6f 72 20 6d |ic Loadi|ng for m|
|00003ca0| 6f 72 65 20 69 6e 66 6f | 20 61 62 6f 75 74 0a 74 |ore info| about.t|
|00003cb0| 68 69 73 2e 0a 0a 49 66 | 20 79 6f 75 20 63 61 6e |his...If| you can|
|00003cc0| 27 74 20 75 73 65 20 64 | 79 6e 61 6d 69 63 20 6c |'t use d|ynamic l|
|00003cd0| 6f 61 64 69 6e 67 2c 20 | 6f 72 20 69 66 20 79 6f |oading, |or if yo|
|00003ce0| 75 20 77 61 6e 74 20 74 | 6f 20 6d 61 6b 65 20 79 |u want t|o make y|
|00003cf0| 6f 75 72 20 6d 6f 64 75 | 6c 65 20 61 0a 70 65 72 |our modu|le a.per|
|00003d00| 6d 61 6e 65 6e 74 20 70 | 61 72 74 20 6f 66 20 74 |manent p|art of t|
|00003d10| 68 65 20 50 79 74 68 6f | 6e 20 69 6e 74 65 72 70 |he Pytho|n interp|
|00003d20| 72 65 74 65 72 2c 20 79 | 6f 75 20 77 69 6c 6c 20 |reter, y|ou will |
|00003d30| 68 61 76 65 20 74 6f 20 | 63 68 61 6e 67 65 20 74 |have to |change t|
|00003d40| 68 65 0a 63 6f 6e 66 69 | 67 75 72 61 74 69 6f 6e |he.confi|guration|
|00003d50| 20 73 65 74 75 70 20 61 | 6e 64 20 72 65 62 75 69 | setup a|nd rebui|
|00003d60| 6c 64 20 74 68 65 20 69 | 6e 74 65 72 70 72 65 74 |ld the i|nterpret|
|00003d70| 65 72 2e 20 20 4c 75 63 | 6b 69 6c 79 2c 20 74 68 |er.  Luc|kily, th|
|00003d80| 69 73 20 69 73 0a 76 65 | 72 79 20 73 69 6d 70 6c |is is.ve|ry simpl|
|00003d90| 65 3a 20 6a 75 73 74 20 | 70 6c 61 63 65 20 79 6f |e: just |place yo|
|00003da0| 75 72 20 66 69 6c 65 20 | 28 5c 66 69 6c 65 7b 73 |ur file |(\file{s|
|00003db0| 70 61 6d 6d 6f 64 75 6c | 65 2e 63 7d 20 66 6f 72 |pammodul|e.c} for|
|00003dc0| 20 65 78 61 6d 70 6c 65 | 29 20 69 6e 0a 74 68 65 | example|) in.the|
|00003dd0| 20 5c 66 69 6c 65 7b 4d | 6f 64 75 6c 65 73 7d 20 | \file{M|odules} |
|00003de0| 64 69 72 65 63 74 6f 72 | 79 2c 20 61 64 64 20 61 |director|y, add a|
|00003df0| 20 6c 69 6e 65 20 74 6f | 20 74 68 65 20 66 69 6c | line to| the fil|
|00003e00| 65 0a 5c 66 69 6c 65 7b | 4d 6f 64 75 6c 65 73 2f |e.\file{|Modules/|
|00003e10| 53 65 74 75 70 7d 20 64 | 65 73 63 72 69 62 69 6e |Setup} d|escribin|
|00003e20| 67 20 79 6f 75 72 20 66 | 69 6c 65 3a 0a 0a 5c 62 |g your f|ile:..\b|
|00003e30| 65 67 69 6e 7b 76 65 72 | 62 61 74 69 6d 7d 0a 20 |egin{ver|batim}. |
|00003e40| 20 20 20 73 70 61 6d 20 | 73 70 61 6d 6d 6f 64 75 |   spam |spammodu|
|00003e50| 6c 65 2e 6f 0a 5c 65 6e | 64 7b 76 65 72 62 61 74 |le.o.\en|d{verbat|
|00003e60| 69 6d 7d 0a 0a 61 6e 64 | 20 72 65 62 75 69 6c 64 |im}..and| rebuild|
|00003e70| 20 74 68 65 20 69 6e 74 | 65 72 70 72 65 74 65 72 | the int|erpreter|
|00003e80| 20 62 79 20 72 75 6e 6e | 69 6e 67 20 5c 63 6f 64 | by runn|ing \cod|
|00003e90| 65 7b 6d 61 6b 65 7d 20 | 69 6e 20 74 68 65 20 74 |e{make} |in the t|
|00003ea0| 6f 70 6c 65 76 65 6c 0a | 64 69 72 65 63 74 6f 72 |oplevel.|director|
|00003eb0| 79 2e 20 20 59 6f 75 20 | 63 61 6e 20 61 6c 73 6f |y.  You |can also|
|00003ec0| 20 72 75 6e 20 5c 63 6f | 64 65 7b 6d 61 6b 65 7d | run \co|de{make}|
|00003ed0| 20 69 6e 20 74 68 65 20 | 5c 66 69 6c 65 7b 4d 6f | in the |\file{Mo|
|00003ee0| 64 75 6c 65 73 7d 0a 73 | 75 62 64 69 72 65 63 74 |dules}.s|ubdirect|
|00003ef0| 6f 72 79 2c 20 62 75 74 | 20 74 68 65 6e 20 79 6f |ory, but| then yo|
|00003f00| 75 20 6d 75 73 74 20 66 | 69 72 73 74 20 72 65 62 |u must f|irst reb|
|00003f10| 75 69 6c 74 20 74 68 65 | 20 5c 66 69 6c 65 7b 4d |uilt the| \file{M|
|00003f20| 61 6b 65 66 69 6c 65 7d | 0a 74 68 65 72 65 20 62 |akefile}|.there b|
|00003f30| 79 20 72 75 6e 6e 69 6e | 67 20 5c 63 6f 64 65 7b |y runnin|g \code{|
|00003f40| 6d 61 6b 65 20 4d 61 6b | 65 66 69 6c 65 7d 2e 20 |make Mak|efile}. |
|00003f50| 20 28 54 68 69 73 20 69 | 73 20 6e 65 63 65 73 73 | (This i|s necess|
|00003f60| 61 72 79 20 65 61 63 68 | 20 74 69 6d 65 0a 79 6f |ary each| time.yo|
|00003f70| 75 20 63 68 61 6e 67 65 | 20 74 68 65 20 5c 66 69 |u change| the \fi|
|00003f80| 6c 65 7b 53 65 74 75 70 | 7d 20 66 69 6c 65 2e 29 |le{Setup|} file.)|
|00003f90| 0a 0a 49 66 20 79 6f 75 | 72 20 6d 6f 64 75 6c 65 |..If you|r module|
|00003fa0| 20 72 65 71 75 69 72 65 | 73 20 61 64 64 69 74 69 | require|s additi|
|00003fb0| 6f 6e 61 6c 20 6c 69 62 | 72 61 72 69 65 73 20 74 |onal lib|raries t|
|00003fc0| 6f 20 6c 69 6e 6b 20 77 | 69 74 68 2c 20 74 68 65 |o link w|ith, the|
|00003fd0| 73 65 20 63 61 6e 0a 62 | 65 20 6c 69 73 74 65 64 |se can.b|e listed|
|00003fe0| 20 6f 6e 20 74 68 65 20 | 6c 69 6e 65 20 69 6e 20 | on the |line in |
|00003ff0| 74 68 65 20 5c 66 69 6c | 65 7b 53 65 74 75 70 7d |the \fil|e{Setup}|
|00004000| 20 66 69 6c 65 20 61 73 | 20 77 65 6c 6c 2c 20 66 | file as| well, f|
|00004010| 6f 72 20 69 6e 73 74 61 | 6e 63 65 3a 0a 0a 5c 62 |or insta|nce:..\b|
|00004020| 65 67 69 6e 7b 76 65 72 | 62 61 74 69 6d 7d 0a 20 |egin{ver|batim}. |
|00004030| 20 20 20 73 70 61 6d 20 | 73 70 61 6d 6d 6f 64 75 |   spam |spammodu|
|00004040| 6c 65 2e 6f 20 2d 6c 58 | 31 31 0a 5c 65 6e 64 7b |le.o -lX|11.\end{|
|00004050| 76 65 72 62 61 74 69 6d | 7d 0a 0a 0a 5c 73 65 63 |verbatim|}...\sec|
|00004060| 74 69 6f 6e 7b 43 61 6c | 6c 69 6e 67 20 50 79 74 |tion{Cal|ling Pyt|
|00004070| 68 6f 6e 20 46 75 6e 63 | 74 69 6f 6e 73 20 46 72 |hon Func|tions Fr|
|00004080| 6f 6d 20 43 7d 0a 0a 53 | 6f 20 66 61 72 20 77 65 |om C}..S|o far we|
|00004090| 20 68 61 76 65 20 63 6f | 6e 63 65 6e 74 72 61 74 | have co|ncentrat|
|000040a0| 65 64 20 6f 6e 20 6d 61 | 6b 69 6e 67 20 43 20 66 |ed on ma|king C f|
|000040b0| 75 6e 63 74 69 6f 6e 73 | 20 63 61 6c 6c 61 62 6c |unctions| callabl|
|000040c0| 65 20 66 72 6f 6d 0a 50 | 79 74 68 6f 6e 2e 20 20 |e from.P|ython.  |
|000040d0| 54 68 65 20 72 65 76 65 | 72 73 65 20 69 73 20 61 |The reve|rse is a|
|000040e0| 6c 73 6f 20 75 73 65 66 | 75 6c 3a 20 63 61 6c 6c |lso usef|ul: call|
|000040f0| 69 6e 67 20 50 79 74 68 | 6f 6e 20 66 75 6e 63 74 |ing Pyth|on funct|
|00004100| 69 6f 6e 73 20 66 72 6f | 6d 20 43 2e 0a 54 68 69 |ions fro|m C..Thi|
|00004110| 73 20 69 73 20 65 73 70 | 65 63 69 61 6c 6c 79 20 |s is esp|ecially |
|00004120| 74 68 65 20 63 61 73 65 | 20 66 6f 72 20 6c 69 62 |the case| for lib|
|00004130| 72 61 72 69 65 73 20 74 | 68 61 74 20 73 75 70 70 |raries t|hat supp|
|00004140| 6f 72 74 20 73 6f 2d 63 | 61 6c 6c 65 64 0a 60 60 |ort so-c|alled.``|
|00004150| 63 61 6c 6c 62 61 63 6b | 27 27 20 66 75 6e 63 74 |callback|'' funct|
|00004160| 69 6f 6e 73 2e 20 20 49 | 66 20 61 20 43 20 69 6e |ions.  I|f a C in|
|00004170| 74 65 72 66 61 63 65 20 | 6d 61 6b 65 73 20 75 73 |terface |makes us|
|00004180| 65 20 6f 66 20 63 61 6c | 6c 62 61 63 6b 73 2c 20 |e of cal|lbacks, |
|00004190| 74 68 65 0a 65 71 75 69 | 76 61 6c 65 6e 74 20 50 |the.equi|valent P|
|000041a0| 79 74 68 6f 6e 20 6f 66 | 74 65 6e 20 6e 65 65 64 |ython of|ten need|
|000041b0| 73 20 74 6f 20 70 72 6f | 76 69 64 65 20 61 20 63 |s to pro|vide a c|
|000041c0| 61 6c 6c 62 61 63 6b 20 | 6d 65 63 68 61 6e 69 73 |allback |mechanis|
|000041d0| 6d 20 74 6f 20 74 68 65 | 0a 50 79 74 68 6f 6e 20 |m to the|.Python |
|000041e0| 70 72 6f 67 72 61 6d 6d | 65 72 3b 20 74 68 65 20 |programm|er; the |
|000041f0| 69 6d 70 6c 65 6d 65 6e | 74 61 74 69 6f 6e 20 77 |implemen|tation w|
|00004200| 69 6c 6c 20 72 65 71 75 | 69 72 65 20 63 61 6c 6c |ill requ|ire call|
|00004210| 69 6e 67 20 74 68 65 20 | 50 79 74 68 6f 6e 0a 63 |ing the |Python.c|
|00004220| 61 6c 6c 62 61 63 6b 20 | 66 75 6e 63 74 69 6f 6e |allback |function|
|00004230| 73 20 66 72 6f 6d 20 61 | 20 43 20 63 61 6c 6c 62 |s from a| C callb|
|00004240| 61 63 6b 2e 20 20 4f 74 | 68 65 72 20 75 73 65 73 |ack.  Ot|her uses|
|00004250| 20 61 72 65 20 61 6c 73 | 6f 20 69 6d 61 67 69 6e | are als|o imagin|
|00004260| 61 62 6c 65 2e 0a 0a 46 | 6f 72 74 75 6e 61 74 65 |able...F|ortunate|
|00004270| 6c 79 2c 20 74 68 65 20 | 50 79 74 68 6f 6e 20 69 |ly, the |Python i|
|00004280| 6e 74 65 72 70 72 65 74 | 65 72 20 69 73 20 65 61 |nterpret|er is ea|
|00004290| 73 69 6c 79 20 63 61 6c | 6c 65 64 20 72 65 63 75 |sily cal|led recu|
|000042a0| 72 73 69 76 65 6c 79 2c | 20 61 6e 64 0a 74 68 65 |rsively,| and.the|
|000042b0| 72 65 20 69 73 20 61 20 | 73 74 61 6e 64 61 72 64 |re is a |standard|
|000042c0| 20 69 6e 74 65 72 66 61 | 63 65 20 74 6f 20 63 61 | interfa|ce to ca|
|000042d0| 6c 6c 20 61 20 50 79 74 | 68 6f 6e 20 66 75 6e 63 |ll a Pyt|hon func|
|000042e0| 74 69 6f 6e 2e 20 20 28 | 49 20 77 6f 6e 27 74 0a |tion.  (|I won't.|
|000042f0| 64 77 65 6c 6c 20 6f 6e | 20 68 6f 77 20 74 6f 20 |dwell on| how to |
|00004300| 63 61 6c 6c 20 74 68 65 | 20 50 79 74 68 6f 6e 20 |call the| Python |
|00004310| 70 61 72 73 65 72 20 77 | 69 74 68 20 61 20 70 61 |parser w|ith a pa|
|00004320| 72 74 69 63 75 6c 61 72 | 20 73 74 72 69 6e 67 20 |rticular| string |
|00004330| 61 73 0a 69 6e 70 75 74 | 20 2d 2d 2d 20 69 66 20 |as.input| --- if |
|00004340| 79 6f 75 27 72 65 20 69 | 6e 74 65 72 65 73 74 65 |you're i|ntereste|
|00004350| 64 2c 20 68 61 76 65 20 | 61 20 6c 6f 6f 6b 20 61 |d, have |a look a|
|00004360| 74 20 74 68 65 20 69 6d | 70 6c 65 6d 65 6e 74 61 |t the im|plementa|
|00004370| 74 69 6f 6e 20 6f 66 0a | 74 68 65 20 5c 73 61 6d |tion of.|the \sam|
|00004380| 70 7b 2d 63 7d 20 63 6f | 6d 6d 61 6e 64 20 6c 69 |p{-c} co|mmand li|
|00004390| 6e 65 20 6f 70 74 69 6f | 6e 20 69 6e 20 5c 66 69 |ne optio|n in \fi|
|000043a0| 6c 65 7b 50 79 74 68 6f | 6e 2f 70 79 74 68 6f 6e |le{Pytho|n/python|
|000043b0| 6d 61 69 6e 2e 63 7d 2e | 29 0a 0a 43 61 6c 6c 69 |main.c}.|)..Calli|
|000043c0| 6e 67 20 61 20 50 79 74 | 68 6f 6e 20 66 75 6e 63 |ng a Pyt|hon func|
|000043d0| 74 69 6f 6e 20 69 73 20 | 65 61 73 79 2e 20 20 46 |tion is |easy.  F|
|000043e0| 69 72 73 74 2c 20 74 68 | 65 20 50 79 74 68 6f 6e |irst, th|e Python|
|000043f0| 20 70 72 6f 67 72 61 6d | 20 6d 75 73 74 0a 73 6f | program| must.so|
|00004400| 6d 65 68 6f 77 20 70 61 | 73 73 20 79 6f 75 20 74 |mehow pa|ss you t|
|00004410| 68 65 20 50 79 74 68 6f | 6e 20 66 75 6e 63 74 69 |he Pytho|n functi|
|00004420| 6f 6e 20 6f 62 6a 65 63 | 74 2e 20 20 59 6f 75 20 |on objec|t.  You |
|00004430| 73 68 6f 75 6c 64 20 70 | 72 6f 76 69 64 65 20 61 |should p|rovide a|
|00004440| 0a 66 75 6e 63 74 69 6f | 6e 20 28 6f 72 20 73 6f |.functio|n (or so|
|00004450| 6d 65 20 6f 74 68 65 72 | 20 69 6e 74 65 72 66 61 |me other| interfa|
|00004460| 63 65 29 20 74 6f 20 64 | 6f 20 74 68 69 73 2e 20 |ce) to d|o this. |
|00004470| 20 57 68 65 6e 20 74 68 | 69 73 20 66 75 6e 63 74 | When th|is funct|
|00004480| 69 6f 6e 20 69 73 0a 63 | 61 6c 6c 65 64 2c 20 73 |ion is.c|alled, s|
|00004490| 61 76 65 20 61 20 70 6f | 69 6e 74 65 72 20 74 6f |ave a po|inter to|
|000044a0| 20 74 68 65 20 50 79 74 | 68 6f 6e 20 66 75 6e 63 | the Pyt|hon func|
|000044b0| 74 69 6f 6e 20 6f 62 6a | 65 63 74 20 28 62 65 20 |tion obj|ect (be |
|000044c0| 63 61 72 65 66 75 6c 20 | 74 6f 0a 5c 63 6f 64 65 |careful |to.\code|
|000044d0| 7b 50 79 5f 49 4e 43 52 | 45 46 28 29 7d 20 69 74 |{Py_INCR|EF()} it|
|000044e0| 21 29 20 69 6e 20 61 20 | 67 6c 6f 62 61 6c 20 76 |!) in a |global v|
|000044f0| 61 72 69 61 62 6c 65 20 | 2d 2d 2d 20 6f 72 20 77 |ariable |--- or w|
|00004500| 68 65 72 65 65 76 65 72 | 20 79 6f 75 20 73 65 65 |hereever| you see|
|00004510| 20 66 69 74 2e 0a 46 6f | 72 20 65 78 61 6d 70 6c | fit..Fo|r exampl|
|00004520| 65 2c 20 74 68 65 20 66 | 6f 6c 6c 6f 77 69 6e 67 |e, the f|ollowing|
|00004530| 20 66 75 6e 63 74 69 6f | 6e 20 6d 69 67 68 74 20 | functio|n might |
|00004540| 62 65 20 70 61 72 74 20 | 6f 66 20 61 20 6d 6f 64 |be part |of a mod|
|00004550| 75 6c 65 0a 64 65 66 69 | 6e 69 74 69 6f 6e 3a 0a |ule.defi|nition:.|
|00004560| 0a 5c 62 65 67 69 6e 7b | 76 65 72 62 61 74 69 6d |.\begin{|verbatim|
|00004570| 7d 0a 20 20 20 20 73 74 | 61 74 69 63 20 50 79 4f |}.    st|atic PyO|
|00004580| 62 6a 65 63 74 20 2a 6d | 79 5f 63 61 6c 6c 62 61 |bject *m|y_callba|
|00004590| 63 6b 20 3d 20 4e 55 4c | 4c 3b 0a 0a 20 20 20 20 |ck = NUL|L;..    |
|000045a0| 73 74 61 74 69 63 20 50 | 79 4f 62 6a 65 63 74 20 |static P|yObject |
|000045b0| 2a 0a 20 20 20 20 6d 79 | 5f 73 65 74 5f 63 61 6c |*.    my|_set_cal|
|000045c0| 6c 62 61 63 6b 28 64 75 | 6d 6d 79 2c 20 61 72 67 |lback(du|mmy, arg|
|000045d0| 29 0a 20 20 20 20 20 20 | 20 20 50 79 4f 62 6a 65 |).      |  PyObje|
|000045e0| 63 74 20 2a 64 75 6d 6d | 79 2c 20 2a 61 72 67 3b |ct *dumm|y, *arg;|
|000045f0| 0a 20 20 20 20 7b 0a 20 | 20 20 20 20 20 20 20 50 |.    {. |       P|
|00004600| 79 5f 58 44 45 43 52 45 | 46 28 6d 79 5f 63 61 6c |y_XDECRE|F(my_cal|
|00004610| 6c 62 61 63 6b 29 3b 20 | 2f 2a 20 44 69 73 70 6f |lback); |/* Dispo|
|00004620| 73 65 20 6f 66 20 70 72 | 65 76 69 6f 75 73 20 63 |se of pr|evious c|
|00004630| 61 6c 6c 62 61 63 6b 20 | 2a 2f 0a 20 20 20 20 20 |allback |*/.     |
|00004640| 20 20 20 50 79 5f 58 49 | 4e 43 52 45 46 28 61 72 |   Py_XI|NCREF(ar|
|00004650| 67 29 3b 20 2f 2a 20 41 | 64 64 20 61 20 72 65 66 |g); /* A|dd a ref|
|00004660| 65 72 65 6e 63 65 20 74 | 6f 20 6e 65 77 20 63 61 |erence t|o new ca|
|00004670| 6c 6c 62 61 63 6b 20 2a | 2f 0a 20 20 20 20 20 20 |llback *|/.      |
|00004680| 20 20 6d 79 5f 63 61 6c | 6c 62 61 63 6b 20 3d 20 |  my_cal|lback = |
|00004690| 61 72 67 3b 20 2f 2a 20 | 52 65 6d 65 6d 62 65 72 |arg; /* |Remember|
|000046a0| 20 6e 65 77 20 63 61 6c | 6c 62 61 63 6b 20 2a 2f | new cal|lback */|
|000046b0| 0a 20 20 20 20 20 20 20 | 20 2f 2a 20 42 6f 69 6c |.       | /* Boil|
|000046c0| 65 72 70 6c 61 74 65 20 | 74 6f 20 72 65 74 75 72 |erplate |to retur|
|000046d0| 6e 20 22 4e 6f 6e 65 22 | 20 2a 2f 0a 20 20 20 20 |n "None"| */.    |
|000046e0| 20 20 20 20 50 79 5f 49 | 4e 43 52 45 46 28 50 79 |    Py_I|NCREF(Py|
|000046f0| 5f 4e 6f 6e 65 29 3b 0a | 20 20 20 20 20 20 20 20 |_None);.|        |
|00004700| 72 65 74 75 72 6e 20 50 | 79 5f 4e 6f 6e 65 3b 0a |return P|y_None;.|
|00004710| 20 20 20 20 7d 0a 5c 65 | 6e 64 7b 76 65 72 62 61 |    }.\e|nd{verba|
|00004720| 74 69 6d 7d 0a 0a 54 68 | 65 20 6d 61 63 72 6f 73 |tim}..Th|e macros|
|00004730| 20 5c 63 6f 64 65 7b 50 | 79 5f 58 49 4e 43 52 45 | \code{P|y_XINCRE|
|00004740| 46 28 29 7d 20 61 6e 64 | 20 5c 63 6f 64 65 7b 50 |F()} and| \code{P|
|00004750| 79 5f 58 44 45 43 52 45 | 46 28 29 7d 20 69 6e 63 |y_XDECRE|F()} inc|
|00004760| 72 65 6d 65 6e 74 2f 64 | 65 63 72 65 6d 65 6e 74 |rement/d|ecrement|
|00004770| 0a 74 68 65 20 72 65 66 | 65 72 65 6e 63 65 20 63 |.the ref|erence c|
|00004780| 6f 75 6e 74 20 6f 66 20 | 61 6e 20 6f 62 6a 65 63 |ount of |an objec|
|00004790| 74 20 61 6e 64 20 61 72 | 65 20 73 61 66 65 20 69 |t and ar|e safe i|
|000047a0| 6e 20 74 68 65 20 70 72 | 65 73 65 6e 63 65 20 6f |n the pr|esence o|
|000047b0| 66 0a 5c 63 6f 64 65 7b | 4e 55 4c 4c 7d 20 70 6f |f.\code{|NULL} po|
|000047c0| 69 6e 74 65 72 73 2e 20 | 20 4d 6f 72 65 20 69 6e |inters. | More in|
|000047d0| 66 6f 20 6f 6e 20 74 68 | 65 6d 20 69 6e 20 74 68 |fo on th|em in th|
|000047e0| 65 20 73 65 63 74 69 6f | 6e 20 6f 6e 20 52 65 66 |e sectio|n on Ref|
|000047f0| 65 72 65 6e 63 65 0a 43 | 6f 75 6e 74 73 20 62 65 |erence.C|ounts be|
|00004800| 6c 6f 77 2e 0a 0a 4c 61 | 74 65 72 2c 20 77 68 65 |low...La|ter, whe|
|00004810| 6e 20 69 74 20 69 73 20 | 74 69 6d 65 20 74 6f 20 |n it is |time to |
|00004820| 63 61 6c 6c 20 74 68 65 | 20 66 75 6e 63 74 69 6f |call the| functio|
|00004830| 6e 2c 20 79 6f 75 20 63 | 61 6c 6c 20 74 68 65 20 |n, you c|all the |
|00004840| 43 20 66 75 6e 63 74 69 | 6f 6e 0a 5c 63 6f 64 65 |C functi|on.\code|
|00004850| 7b 50 79 45 76 61 6c 5f | 43 61 6c 6c 4f 62 6a 65 |{PyEval_|CallObje|
|00004860| 63 74 28 29 7d 2e 20 20 | 54 68 69 73 20 66 75 6e |ct()}.  |This fun|
|00004870| 63 74 69 6f 6e 20 68 61 | 73 20 74 77 6f 20 61 72 |ction ha|s two ar|
|00004880| 67 75 6d 65 6e 74 73 2c | 20 62 6f 74 68 0a 70 6f |guments,| both.po|
|00004890| 69 6e 74 65 72 73 20 74 | 6f 20 61 72 62 69 74 72 |inters t|o arbitr|
|000048a0| 61 72 79 20 50 79 74 68 | 6f 6e 20 6f 62 6a 65 63 |ary Pyth|on objec|
|000048b0| 74 73 3a 20 74 68 65 20 | 50 79 74 68 6f 6e 20 66 |ts: the |Python f|
|000048c0| 75 6e 63 74 69 6f 6e 2c | 20 61 6e 64 20 74 68 65 |unction,| and the|
|000048d0| 0a 61 72 67 75 6d 65 6e | 74 20 6c 69 73 74 2e 20 |.argumen|t list. |
|000048e0| 20 54 68 65 20 61 72 67 | 75 6d 65 6e 74 20 6c 69 | The arg|ument li|
|000048f0| 73 74 20 6d 75 73 74 20 | 61 6c 77 61 79 73 20 62 |st must |always b|
|00004900| 65 20 61 20 74 75 70 6c | 65 20 6f 62 6a 65 63 74 |e a tupl|e object|
|00004910| 2c 20 77 68 6f 73 65 0a | 6c 65 6e 67 74 68 20 69 |, whose.|length i|
|00004920| 73 20 74 68 65 20 6e 75 | 6d 62 65 72 20 6f 66 20 |s the nu|mber of |
|00004930| 61 72 67 75 6d 65 6e 74 | 73 2e 20 20 54 6f 20 63 |argument|s.  To c|
|00004940| 61 6c 6c 20 74 68 65 20 | 50 79 74 68 6f 6e 20 66 |all the |Python f|
|00004950| 75 6e 63 74 69 6f 6e 20 | 77 69 74 68 0a 6e 6f 20 |unction |with.no |
|00004960| 61 72 67 75 6d 65 6e 74 | 73 2c 20 70 61 73 73 20 |argument|s, pass |
|00004970| 61 6e 20 65 6d 70 74 79 | 20 74 75 70 6c 65 3b 20 |an empty| tuple; |
|00004980| 74 6f 20 63 61 6c 6c 20 | 69 74 20 77 69 74 68 20 |to call |it with |
|00004990| 6f 6e 65 20 61 72 67 75 | 6d 65 6e 74 2c 20 70 61 |one argu|ment, pa|
|000049a0| 73 73 0a 61 20 73 69 6e | 67 6c 65 74 6f 6e 20 74 |ss.a sin|gleton t|
|000049b0| 75 70 6c 65 2e 20 20 5c | 63 6f 64 65 7b 50 79 5f |uple.  \|code{Py_|
|000049c0| 42 75 69 6c 64 56 61 6c | 75 65 28 29 7d 20 72 65 |BuildVal|ue()} re|
|000049d0| 74 75 72 6e 73 20 61 20 | 74 75 70 6c 65 20 77 68 |turns a |tuple wh|
|000049e0| 65 6e 20 69 74 73 0a 66 | 6f 72 6d 61 74 20 73 74 |en its.f|ormat st|
|000049f0| 72 69 6e 67 20 63 6f 6e | 73 69 73 74 73 20 6f 66 |ring con|sists of|
|00004a00| 20 7a 65 72 6f 20 6f 72 | 20 6d 6f 72 65 20 66 6f | zero or| more fo|
|00004a10| 72 6d 61 74 20 63 6f 64 | 65 73 20 62 65 74 77 65 |rmat cod|es betwe|
|00004a20| 65 6e 0a 70 61 72 65 6e | 74 68 65 73 65 73 2e 20 |en.paren|theses. |
|00004a30| 20 46 6f 72 20 65 78 61 | 6d 70 6c 65 3a 0a 0a 5c | For exa|mple:..\|
|00004a40| 62 65 67 69 6e 7b 76 65 | 72 62 61 74 69 6d 7d 0a |begin{ve|rbatim}.|
|00004a50| 20 20 20 20 69 6e 74 20 | 61 72 67 3b 0a 20 20 20 |    int |arg;.   |
|00004a60| 20 50 79 4f 62 6a 65 63 | 74 20 2a 61 72 67 6c 69 | PyObjec|t *argli|
|00004a70| 73 74 3b 0a 20 20 20 20 | 50 79 4f 62 6a 65 63 74 |st;.    |PyObject|
|00004a80| 20 2a 72 65 73 75 6c 74 | 3b 0a 20 20 20 20 2e 2e | *result|;.    ..|
|00004a90| 2e 0a 20 20 20 20 61 72 | 67 20 3d 20 31 32 33 3b |..    ar|g = 123;|
|00004aa0| 0a 20 20 20 20 2e 2e 2e | 0a 20 20 20 20 2f 2a 20 |.    ...|.    /* |
|00004ab0| 54 69 6d 65 20 74 6f 20 | 63 61 6c 6c 20 74 68 65 |Time to |call the|
|00004ac0| 20 63 61 6c 6c 62 61 63 | 6b 20 2a 2f 0a 20 20 20 | callbac|k */.   |
|00004ad0| 20 61 72 67 6c 69 73 74 | 20 3d 20 50 79 5f 42 75 | arglist| = Py_Bu|
|00004ae0| 69 6c 64 56 61 6c 75 65 | 28 22 28 69 29 22 2c 20 |ildValue|("(i)", |
|00004af0| 61 72 67 29 3b 0a 20 20 | 20 20 72 65 73 75 6c 74 |arg);.  |  result|
|00004b00| 20 3d 20 50 79 45 76 61 | 6c 5f 43 61 6c 6c 4f 62 | = PyEva|l_CallOb|
|00004b10| 6a 65 63 74 28 6d 79 5f | 63 61 6c 6c 62 61 63 6b |ject(my_|callback|
|00004b20| 2c 20 61 72 67 6c 69 73 | 74 29 3b 0a 20 20 20 20 |, arglis|t);.    |
|00004b30| 50 79 5f 44 45 43 52 45 | 46 28 61 72 67 6c 69 73 |Py_DECRE|F(arglis|
|00004b40| 74 29 3b 0a 5c 65 6e 64 | 7b 76 65 72 62 61 74 69 |t);.\end|{verbati|
|00004b50| 6d 7d 0a 0a 5c 63 6f 64 | 65 7b 50 79 45 76 61 6c |m}..\cod|e{PyEval|
|00004b60| 5f 43 61 6c 6c 4f 62 6a | 65 63 74 28 29 7d 20 72 |_CallObj|ect()} r|
|00004b70| 65 74 75 72 6e 73 20 61 | 20 50 79 74 68 6f 6e 20 |eturns a| Python |
|00004b80| 6f 62 6a 65 63 74 20 70 | 6f 69 6e 74 65 72 3a 20 |object p|ointer: |
|00004b90| 74 68 69 73 20 69 73 0a | 74 68 65 20 72 65 74 75 |this is.|the retu|
|00004ba0| 72 6e 20 76 61 6c 75 65 | 20 6f 66 20 74 68 65 20 |rn value| of the |
|00004bb0| 50 79 74 68 6f 6e 20 66 | 75 6e 63 74 69 6f 6e 2e |Python f|unction.|
|00004bc0| 20 20 5c 63 6f 64 65 7b | 50 79 45 76 61 6c 5f 43 |  \code{|PyEval_C|
|00004bd0| 61 6c 6c 4f 62 6a 65 63 | 74 28 29 7d 20 69 73 0a |allObjec|t()} is.|
|00004be0| 60 60 72 65 66 65 72 65 | 6e 63 65 2d 63 6f 75 6e |``refere|nce-coun|
|00004bf0| 74 2d 6e 65 75 74 72 61 | 6c 27 27 20 77 69 74 68 |t-neutra|l'' with|
|00004c00| 20 72 65 73 70 65 63 74 | 20 74 6f 20 69 74 73 20 | respect| to its |
|00004c10| 61 72 67 75 6d 65 6e 74 | 73 2e 20 20 49 6e 20 74 |argument|s.  In t|
|00004c20| 68 65 0a 65 78 61 6d 70 | 6c 65 20 61 20 6e 65 77 |he.examp|le a new|
|00004c30| 20 74 75 70 6c 65 20 77 | 61 73 20 63 72 65 61 74 | tuple w|as creat|
|00004c40| 65 64 20 74 6f 20 73 65 | 72 76 65 20 61 73 20 74 |ed to se|rve as t|
|00004c50| 68 65 20 61 72 67 75 6d | 65 6e 74 20 6c 69 73 74 |he argum|ent list|
|00004c60| 2c 20 77 68 69 63 68 0a | 69 73 20 5c 63 6f 64 65 |, which.|is \code|
|00004c70| 7b 50 79 5f 44 45 43 52 | 45 46 28 29 7d 2d 65 64 |{Py_DECR|EF()}-ed|
|00004c80| 20 69 6d 6d 65 64 69 61 | 74 65 6c 79 20 61 66 74 | immedia|tely aft|
|00004c90| 65 72 20 74 68 65 20 63 | 61 6c 6c 2e 0a 0a 54 68 |er the c|all...Th|
|00004ca0| 65 20 72 65 74 75 72 6e | 20 76 61 6c 75 65 20 6f |e return| value o|
|00004cb0| 66 20 5c 63 6f 64 65 7b | 50 79 45 76 61 6c 5f 43 |f \code{|PyEval_C|
|00004cc0| 61 6c 6c 4f 62 6a 65 63 | 74 28 29 7d 20 69 73 20 |allObjec|t()} is |
|00004cd0| 60 60 6e 65 77 27 27 3a | 20 65 69 74 68 65 72 20 |``new'':| either |
|00004ce0| 69 74 0a 69 73 20 61 20 | 62 72 61 6e 64 20 6e 65 |it.is a |brand ne|
|00004cf0| 77 20 6f 62 6a 65 63 74 | 2c 20 6f 72 20 69 74 20 |w object|, or it |
|00004d00| 69 73 20 61 6e 20 65 78 | 69 73 74 69 6e 67 20 6f |is an ex|isting o|
|00004d10| 62 6a 65 63 74 20 77 68 | 6f 73 65 20 72 65 66 65 |bject wh|ose refe|
|00004d20| 72 65 6e 63 65 0a 63 6f | 75 6e 74 20 68 61 73 20 |rence.co|unt has |
|00004d30| 62 65 65 6e 20 69 6e 63 | 72 65 6d 65 6e 74 65 64 |been inc|remented|
|00004d40| 2e 20 20 53 6f 2c 20 75 | 6e 6c 65 73 73 20 79 6f |.  So, u|nless yo|
|00004d50| 75 20 77 61 6e 74 20 74 | 6f 20 73 61 76 65 20 69 |u want t|o save i|
|00004d60| 74 20 69 6e 20 61 0a 67 | 6c 6f 62 61 6c 20 76 61 |t in a.g|lobal va|
|00004d70| 72 69 61 62 6c 65 2c 20 | 79 6f 75 20 73 68 6f 75 |riable, |you shou|
|00004d80| 6c 64 20 73 6f 6d 65 68 | 6f 77 20 5c 63 6f 64 65 |ld someh|ow \code|
|00004d90| 7b 50 79 5f 44 45 43 52 | 45 46 28 29 7d 20 74 68 |{Py_DECR|EF()} th|
|00004da0| 65 20 72 65 73 75 6c 74 | 2c 0a 65 76 65 6e 20 28 |e result|,.even (|
|00004db0| 65 73 70 65 63 69 61 6c | 6c 79 21 29 20 69 66 20 |especial|ly!) if |
|00004dc0| 79 6f 75 20 61 72 65 20 | 6e 6f 74 20 69 6e 74 65 |you are |not inte|
|00004dd0| 72 65 73 74 65 64 20 69 | 6e 20 69 74 73 20 76 61 |rested i|n its va|
|00004de0| 6c 75 65 2e 0a 0a 42 65 | 66 6f 72 65 20 79 6f 75 |lue...Be|fore you|
|00004df0| 20 64 6f 20 74 68 69 73 | 2c 20 68 6f 77 65 76 65 | do this|, howeve|
|00004e00| 72 2c 20 69 74 20 69 73 | 20 69 6d 70 6f 72 74 61 |r, it is| importa|
|00004e10| 6e 74 20 74 6f 20 63 68 | 65 63 6b 20 74 68 61 74 |nt to ch|eck that|
|00004e20| 20 74 68 65 20 72 65 74 | 75 72 6e 0a 76 61 6c 75 | the ret|urn.valu|
|00004e30| 65 20 69 73 6e 27 74 20 | 5c 63 6f 64 65 7b 4e 55 |e isn't |\code{NU|
|00004e40| 4c 4c 7d 2e 20 20 49 66 | 20 69 74 20 69 73 2c 20 |LL}.  If| it is, |
|00004e50| 74 68 65 20 50 79 74 68 | 6f 6e 20 66 75 6e 63 74 |the Pyth|on funct|
|00004e60| 69 6f 6e 20 74 65 72 6d | 69 6e 61 74 65 64 20 62 |ion term|inated b|
|00004e70| 79 20 72 61 69 73 69 6e | 67 0a 61 6e 20 65 78 63 |y raisin|g.an exc|
|00004e80| 65 70 74 69 6f 6e 2e 20 | 20 49 66 20 74 68 65 20 |eption. | If the |
|00004e90| 43 20 63 6f 64 65 20 74 | 68 61 74 20 63 61 6c 6c |C code t|hat call|
|00004ea0| 65 64 20 5c 63 6f 64 65 | 7b 50 79 45 76 61 6c 5f |ed \code|{PyEval_|
|00004eb0| 43 61 6c 6c 4f 62 6a 65 | 63 74 28 29 7d 20 69 73 |CallObje|ct()} is|
|00004ec0| 0a 63 61 6c 6c 65 64 20 | 66 72 6f 6d 20 50 79 74 |.called |from Pyt|
|00004ed0| 68 6f 6e 2c 20 69 74 20 | 73 68 6f 75 6c 64 20 6e |hon, it |should n|
|00004ee0| 6f 77 20 72 65 74 75 72 | 6e 20 61 6e 20 65 72 72 |ow retur|n an err|
|00004ef0| 6f 72 20 69 6e 64 69 63 | 61 74 69 6f 6e 20 74 6f |or indic|ation to|
|00004f00| 20 69 74 73 0a 50 79 74 | 68 6f 6e 20 63 61 6c 6c | its.Pyt|hon call|
|00004f10| 65 72 2c 20 73 6f 20 74 | 68 65 20 69 6e 74 65 72 |er, so t|he inter|
|00004f20| 70 72 65 74 65 72 20 63 | 61 6e 20 70 72 69 6e 74 |preter c|an print|
|00004f30| 20 61 20 73 74 61 63 6b | 20 74 72 61 63 65 2c 20 | a stack| trace, |
|00004f40| 6f 72 20 74 68 65 0a 63 | 61 6c 6c 69 6e 67 20 50 |or the.c|alling P|
|00004f50| 79 74 68 6f 6e 20 63 6f | 64 65 20 63 61 6e 20 68 |ython co|de can h|
|00004f60| 61 6e 64 6c 65 20 74 68 | 65 20 65 78 63 65 70 74 |andle th|e except|
|00004f70| 69 6f 6e 2e 20 20 49 66 | 20 74 68 69 73 20 69 73 |ion.  If| this is|
|00004f80| 20 6e 6f 74 20 70 6f 73 | 73 69 62 6c 65 0a 6f 72 | not pos|sible.or|
|00004f90| 20 64 65 73 69 72 61 62 | 6c 65 2c 20 74 68 65 20 | desirab|le, the |
|00004fa0| 65 78 63 65 70 74 69 6f | 6e 20 73 68 6f 75 6c 64 |exceptio|n should|
|00004fb0| 20 62 65 20 63 6c 65 61 | 72 65 64 20 62 79 20 63 | be clea|red by c|
|00004fc0| 61 6c 6c 69 6e 67 0a 5c | 63 6f 64 65 7b 50 79 45 |alling.\|code{PyE|
|00004fd0| 72 72 5f 43 6c 65 61 72 | 28 29 7d 2e 20 20 46 6f |rr_Clear|()}.  Fo|
|00004fe0| 72 20 65 78 61 6d 70 6c | 65 3a 0a 0a 5c 62 65 67 |r exampl|e:..\beg|
|00004ff0| 69 6e 7b 76 65 72 62 61 | 74 69 6d 7d 0a 20 20 20 |in{verba|tim}.   |
|00005000| 20 69 66 20 28 72 65 73 | 75 6c 74 20 3d 3d 20 4e | if (res|ult == N|
|00005010| 55 4c 4c 29 0a 20 20 20 | 20 20 20 20 20 72 65 74 |ULL).   |     ret|
|00005020| 75 72 6e 20 4e 55 4c 4c | 3b 20 2f 2a 20 50 61 73 |urn NULL|; /* Pas|
|00005030| 73 20 65 72 72 6f 72 20 | 62 61 63 6b 20 2a 2f 0a |s error |back */.|
|00005040| 20 20 20 20 2e 2e 2e 75 | 73 65 20 72 65 73 75 6c |    ...u|se resul|
|00005050| 74 2e 2e 2e 0a 20 20 20 | 20 50 79 5f 44 45 43 52 |t....   | Py_DECR|
|00005060| 45 46 28 72 65 73 75 6c | 74 29 3b 20 0a 5c 65 6e |EF(resul|t); .\en|
|00005070| 64 7b 76 65 72 62 61 74 | 69 6d 7d 0a 0a 44 65 70 |d{verbat|im}..Dep|
|00005080| 65 6e 64 69 6e 67 20 6f | 6e 20 74 68 65 20 64 65 |ending o|n the de|
|00005090| 73 69 72 65 64 20 69 6e | 74 65 72 66 61 63 65 20 |sired in|terface |
|000050a0| 74 6f 20 74 68 65 20 50 | 79 74 68 6f 6e 20 63 61 |to the P|ython ca|
|000050b0| 6c 6c 62 61 63 6b 20 66 | 75 6e 63 74 69 6f 6e 2c |llback f|unction,|
|000050c0| 0a 79 6f 75 20 6d 61 79 | 20 61 6c 73 6f 20 68 61 |.you may| also ha|
|000050d0| 76 65 20 74 6f 20 70 72 | 6f 76 69 64 65 20 61 6e |ve to pr|ovide an|
|000050e0| 20 61 72 67 75 6d 65 6e | 74 20 6c 69 73 74 20 74 | argumen|t list t|
|000050f0| 6f 20 5c 63 6f 64 65 7b | 50 79 45 76 61 6c 5f 43 |o \code{|PyEval_C|
|00005100| 61 6c 6c 4f 62 6a 65 63 | 74 28 29 7d 2e 0a 49 6e |allObjec|t()}..In|
|00005110| 20 73 6f 6d 65 20 63 61 | 73 65 73 20 74 68 65 20 | some ca|ses the |
|00005120| 61 72 67 75 6d 65 6e 74 | 20 6c 69 73 74 20 69 73 |argument| list is|
|00005130| 20 61 6c 73 6f 20 70 72 | 6f 76 69 64 65 64 20 62 | also pr|ovided b|
|00005140| 79 20 74 68 65 20 50 79 | 74 68 6f 6e 0a 70 72 6f |y the Py|thon.pro|
|00005150| 67 72 61 6d 2c 20 74 68 | 72 6f 75 67 68 20 74 68 |gram, th|rough th|
|00005160| 65 20 73 61 6d 65 20 69 | 6e 74 65 72 66 61 63 65 |e same i|nterface|
|00005170| 20 74 68 61 74 20 73 70 | 65 63 69 66 69 65 64 20 | that sp|ecified |
|00005180| 74 68 65 20 63 61 6c 6c | 62 61 63 6b 0a 66 75 6e |the call|back.fun|
|00005190| 63 74 69 6f 6e 2e 20 20 | 49 74 20 63 61 6e 20 74 |ction.  |It can t|
|000051a0| 68 65 6e 20 62 65 20 73 | 61 76 65 64 20 61 6e 64 |hen be s|aved and|
|000051b0| 20 75 73 65 64 20 69 6e | 20 74 68 65 20 73 61 6d | used in| the sam|
|000051c0| 65 20 6d 61 6e 6e 65 72 | 20 61 73 20 74 68 65 0a |e manner| as the.|
|000051d0| 66 75 6e 63 74 69 6f 6e | 20 6f 62 6a 65 63 74 2e |function| object.|
|000051e0| 20 20 49 6e 20 6f 74 68 | 65 72 20 63 61 73 65 73 |  In oth|er cases|
|000051f0| 2c 20 79 6f 75 20 6d 61 | 79 20 68 61 76 65 20 74 |, you ma|y have t|
|00005200| 6f 20 63 6f 6e 73 74 72 | 75 63 74 20 61 20 6e 65 |o constr|uct a ne|
|00005210| 77 0a 74 75 70 6c 65 20 | 74 6f 20 70 61 73 73 20 |w.tuple |to pass |
|00005220| 61 73 20 74 68 65 20 61 | 72 67 75 6d 65 6e 74 20 |as the a|rgument |
|00005230| 6c 69 73 74 2e 20 20 54 | 68 65 20 73 69 6d 70 6c |list.  T|he simpl|
|00005240| 65 73 74 20 77 61 79 20 | 74 6f 20 64 6f 20 74 68 |est way |to do th|
|00005250| 69 73 20 69 73 20 74 6f | 0a 63 61 6c 6c 20 5c 63 |is is to|.call \c|
|00005260| 6f 64 65 7b 50 79 5f 42 | 75 69 6c 64 56 61 6c 75 |ode{Py_B|uildValu|
|00005270| 65 28 29 7d 2e 20 20 46 | 6f 72 20 65 78 61 6d 70 |e()}.  F|or examp|
|00005280| 6c 65 2c 20 69 66 20 79 | 6f 75 20 77 61 6e 74 20 |le, if y|ou want |
|00005290| 74 6f 20 70 61 73 73 20 | 61 6e 20 69 6e 74 65 67 |to pass |an integ|
|000052a0| 72 61 6c 0a 65 76 65 6e | 74 20 63 6f 64 65 2c 20 |ral.even|t code, |
|000052b0| 79 6f 75 20 6d 69 67 68 | 74 20 75 73 65 20 74 68 |you migh|t use th|
|000052c0| 65 20 66 6f 6c 6c 6f 77 | 69 6e 67 20 63 6f 64 65 |e follow|ing code|
|000052d0| 3a 0a 0a 5c 62 65 67 69 | 6e 7b 76 65 72 62 61 74 |:..\begi|n{verbat|
|000052e0| 69 6d 7d 0a 20 20 20 20 | 50 79 4f 62 6a 65 63 74 |im}.    |PyObject|
|000052f0| 20 2a 61 72 67 6c 69 73 | 74 3b 0a 20 20 20 20 2e | *arglis|t;.    .|
|00005300| 2e 2e 0a 20 20 20 20 61 | 72 67 6c 69 73 74 20 3d |...    a|rglist =|
|00005310| 20 50 79 5f 42 75 69 6c | 64 56 61 6c 75 65 28 22 | Py_Buil|dValue("|
|00005320| 28 6c 29 22 2c 20 65 76 | 65 6e 74 63 6f 64 65 29 |(l)", ev|entcode)|
|00005330| 3b 0a 20 20 20 20 72 65 | 73 75 6c 74 20 3d 20 50 |;.    re|sult = P|
|00005340| 79 45 76 61 6c 5f 43 61 | 6c 6c 4f 62 6a 65 63 74 |yEval_Ca|llObject|
|00005350| 28 6d 79 5f 63 61 6c 6c | 62 61 63 6b 2c 20 61 72 |(my_call|back, ar|
|00005360| 67 6c 69 73 74 29 3b 0a | 20 20 20 20 50 79 5f 44 |glist);.|    Py_D|
|00005370| 45 43 52 45 46 28 61 72 | 67 6c 69 73 74 29 3b 0a |ECREF(ar|glist);.|
|00005380| 20 20 20 20 69 66 20 28 | 72 65 73 75 6c 74 20 3d |    if (|result =|
|00005390| 3d 20 4e 55 4c 4c 29 0a | 20 20 20 20 20 20 20 20 |= NULL).|        |
|000053a0| 72 65 74 75 72 6e 20 4e | 55 4c 4c 3b 20 2f 2a 20 |return N|ULL; /* |
|000053b0| 50 61 73 73 20 65 72 72 | 6f 72 20 62 61 63 6b 20 |Pass err|or back |
|000053c0| 2a 2f 0a 20 20 20 20 2f | 2a 20 48 65 72 65 20 6d |*/.    /|* Here m|
|000053d0| 61 79 62 65 20 75 73 65 | 20 74 68 65 20 72 65 73 |aybe use| the res|
|000053e0| 75 6c 74 20 2a 2f 0a 20 | 20 20 20 50 79 5f 44 45 |ult */. |   Py_DE|
|000053f0| 43 52 45 46 28 72 65 73 | 75 6c 74 29 3b 0a 5c 65 |CREF(res|ult);.\e|
|00005400| 6e 64 7b 76 65 72 62 61 | 74 69 6d 7d 0a 0a 4e 6f |nd{verba|tim}..No|
|00005410| 74 65 20 74 68 65 20 70 | 6c 61 63 65 6d 65 6e 74 |te the p|lacement|
|00005420| 20 6f 66 20 5c 63 6f 64 | 65 7b 50 79 5f 44 45 43 | of \cod|e{Py_DEC|
|00005430| 52 45 46 28 61 72 67 75 | 6d 65 6e 74 29 7d 20 69 |REF(argu|ment)} i|
|00005440| 6d 6d 65 64 69 61 74 65 | 6c 79 20 61 66 74 65 72 |mmediate|ly after|
|00005450| 20 74 68 65 20 63 61 6c | 6c 2c 0a 62 65 66 6f 72 | the cal|l,.befor|
|00005460| 65 20 74 68 65 20 65 72 | 72 6f 72 20 63 68 65 63 |e the er|ror chec|
|00005470| 6b 21 20 20 41 6c 73 6f | 20 6e 6f 74 65 20 74 68 |k!  Also| note th|
|00005480| 61 74 20 73 74 72 69 63 | 74 6c 79 20 73 70 6f 6b |at stric|tly spok|
|00005490| 65 6e 20 74 68 69 73 20 | 63 6f 64 65 20 69 73 0a |en this |code is.|
|000054a0| 6e 6f 74 20 63 6f 6d 70 | 6c 65 74 65 3a 20 5c 63 |not comp|lete: \c|
|000054b0| 6f 64 65 7b 50 79 5f 42 | 75 69 6c 64 56 61 6c 75 |ode{Py_B|uildValu|
|000054c0| 65 28 29 7d 20 6d 61 79 | 20 72 75 6e 20 6f 75 74 |e()} may| run out|
|000054d0| 20 6f 66 20 6d 65 6d 6f | 72 79 2c 20 61 6e 64 20 | of memo|ry, and |
|000054e0| 74 68 69 73 20 73 68 6f | 75 6c 64 0a 62 65 20 63 |this sho|uld.be c|
|000054f0| 68 65 63 6b 65 64 2e 0a | 0a 0a 5c 73 65 63 74 69 |hecked..|..\secti|
|00005500| 6f 6e 7b 46 6f 72 6d 61 | 74 20 53 74 72 69 6e 67 |on{Forma|t String|
|00005510| 73 20 66 6f 72 20 7b 5c | 74 74 20 50 79 41 72 67 |s for {\|tt PyArg|
|00005520| 5f 50 61 72 73 65 54 75 | 70 6c 65 28 29 7d 7d 0a |_ParseTu|ple()}}.|
|00005530| 0a 54 68 65 20 5c 63 6f | 64 65 7b 50 79 41 72 67 |.The \co|de{PyArg|
|00005540| 5f 50 61 72 73 65 54 75 | 70 6c 65 28 29 7d 20 66 |_ParseTu|ple()} f|
|00005550| 75 6e 63 74 69 6f 6e 20 | 69 73 20 64 65 63 6c 61 |unction |is decla|
|00005560| 72 65 64 20 61 73 20 66 | 6f 6c 6c 6f 77 73 3a 0a |red as f|ollows:.|
|00005570| 0a 5c 62 65 67 69 6e 7b | 76 65 72 62 61 74 69 6d |.\begin{|verbatim|
|00005580| 7d 0a 20 20 20 20 69 6e | 74 20 50 79 41 72 67 5f |}.    in|t PyArg_|
|00005590| 50 61 72 73 65 54 75 70 | 6c 65 28 50 79 4f 62 6a |ParseTup|le(PyObj|
|000055a0| 65 63 74 20 2a 61 72 67 | 2c 20 63 68 61 72 20 2a |ect *arg|, char *|
|000055b0| 66 6f 72 6d 61 74 2c 20 | 2e 2e 2e 29 3b 0a 5c 65 |format, |...);.\e|
|000055c0| 6e 64 7b 76 65 72 62 61 | 74 69 6d 7d 0a 0a 54 68 |nd{verba|tim}..Th|
|000055d0| 65 20 5c 76 61 72 7b 61 | 72 67 7d 20 61 72 67 75 |e \var{a|rg} argu|
|000055e0| 6d 65 6e 74 20 6d 75 73 | 74 20 62 65 20 61 20 74 |ment mus|t be a t|
|000055f0| 75 70 6c 65 20 6f 62 6a | 65 63 74 20 63 6f 6e 74 |uple obj|ect cont|
|00005600| 61 69 6e 69 6e 67 20 61 | 6e 20 61 72 67 75 6d 65 |aining a|n argume|
|00005610| 6e 74 0a 6c 69 73 74 20 | 70 61 73 73 65 64 20 66 |nt.list |passed f|
|00005620| 72 6f 6d 20 50 79 74 68 | 6f 6e 20 74 6f 20 61 20 |rom Pyth|on to a |
|00005630| 43 20 66 75 6e 63 74 69 | 6f 6e 2e 20 20 54 68 65 |C functi|on.  The|
|00005640| 20 5c 76 61 72 7b 66 6f | 72 6d 61 74 7d 20 61 72 | \var{fo|rmat} ar|
|00005650| 67 75 6d 65 6e 74 0a 6d | 75 73 74 20 62 65 20 61 |gument.m|ust be a|
|00005660| 20 66 6f 72 6d 61 74 20 | 73 74 72 69 6e 67 2c 20 | format |string, |
|00005670| 77 68 6f 73 65 20 73 79 | 6e 74 61 78 20 69 73 20 |whose sy|ntax is |
|00005680| 65 78 70 6c 61 69 6e 65 | 64 20 62 65 6c 6f 77 2e |explaine|d below.|
|00005690| 20 20 54 68 65 0a 72 65 | 6d 61 69 6e 69 6e 67 20 |  The.re|maining |
|000056a0| 61 72 67 75 6d 65 6e 74 | 73 20 6d 75 73 74 20 62 |argument|s must b|
|000056b0| 65 20 61 64 64 72 65 73 | 73 65 73 20 6f 66 20 76 |e addres|ses of v|
|000056c0| 61 72 69 61 62 6c 65 73 | 20 77 68 6f 73 65 20 74 |ariables| whose t|
|000056d0| 79 70 65 20 69 73 0a 64 | 65 74 65 72 6d 69 6e 65 |ype is.d|etermine|
|000056e0| 64 20 62 79 20 74 68 65 | 20 66 6f 72 6d 61 74 20 |d by the| format |
|000056f0| 73 74 72 69 6e 67 2e 20 | 20 46 6f 72 20 74 68 65 |string. | For the|
|00005700| 20 63 6f 6e 76 65 72 73 | 69 6f 6e 20 74 6f 20 73 | convers|ion to s|
|00005710| 75 63 63 65 65 64 2c 20 | 74 68 65 0a 5c 76 61 72 |ucceed, |the.\var|
|00005720| 7b 61 72 67 7d 20 6f 62 | 6a 65 63 74 20 6d 75 73 |{arg} ob|ject mus|
|00005730| 74 20 6d 61 74 63 68 20 | 74 68 65 20 66 6f 72 6d |t match |the form|
|00005740| 61 74 20 61 6e 64 20 74 | 68 65 20 66 6f 72 6d 61 |at and t|he forma|
|00005750| 74 20 6d 75 73 74 20 62 | 65 0a 65 78 68 61 75 73 |t must b|e.exhaus|
|00005760| 74 65 64 2e 0a 0a 4e 6f | 74 65 20 74 68 61 74 20 |ted...No|te that |
|00005770| 77 68 69 6c 65 20 5c 63 | 6f 64 65 7b 50 79 41 72 |while \c|ode{PyAr|
|00005780| 67 5f 50 61 72 73 65 54 | 75 70 6c 65 28 29 7d 20 |g_ParseT|uple()} |
|00005790| 63 68 65 63 6b 73 20 74 | 68 61 74 20 74 68 65 20 |checks t|hat the |
|000057a0| 50 79 74 68 6f 6e 0a 61 | 72 67 75 6d 65 6e 74 73 |Python.a|rguments|
|000057b0| 20 68 61 76 65 20 74 68 | 65 20 72 65 71 75 69 72 | have th|e requir|
|000057c0| 65 64 20 74 79 70 65 73 | 2c 20 69 74 20 63 61 6e |ed types|, it can|
|000057d0| 6e 6f 74 20 63 68 65 63 | 6b 20 74 68 65 20 76 61 |not chec|k the va|
|000057e0| 6c 69 64 69 74 79 20 6f | 66 20 74 68 65 0a 61 64 |lidity o|f the.ad|
|000057f0| 64 72 65 73 73 65 73 20 | 6f 66 20 43 20 76 61 72 |dresses |of C var|
|00005800| 69 61 62 6c 65 73 20 70 | 61 73 73 65 64 20 74 6f |iables p|assed to|
|00005810| 20 74 68 65 20 63 61 6c | 6c 3a 20 69 66 20 79 6f | the cal|l: if yo|
|00005820| 75 20 6d 61 6b 65 20 6d | 69 73 74 61 6b 65 73 0a |u make m|istakes.|
|00005830| 74 68 65 72 65 2c 20 79 | 6f 75 72 20 63 6f 64 65 |there, y|our code|
|00005840| 20 77 69 6c 6c 20 70 72 | 6f 62 61 62 6c 79 20 63 | will pr|obably c|
|00005850| 72 61 73 68 20 6f 72 20 | 61 74 20 6c 65 61 73 74 |rash or |at least|
|00005860| 20 6f 76 65 72 77 72 69 | 74 65 20 72 61 6e 64 6f | overwri|te rando|
|00005870| 6d 20 62 69 74 73 0a 69 | 6e 20 6d 65 6d 6f 72 79 |m bits.i|n memory|
|00005880| 2e 20 20 53 6f 20 62 65 | 20 63 61 72 65 66 75 6c |.  So be| careful|
|00005890| 21 0a 0a 41 20 66 6f 72 | 6d 61 74 20 73 74 72 69 |!..A for|mat stri|
|000058a0| 6e 67 20 63 6f 6e 73 69 | 73 74 73 20 6f 66 20 7a |ng consi|sts of z|
|000058b0| 65 72 6f 20 6f 72 20 6d | 6f 72 65 20 60 60 66 6f |ero or m|ore ``fo|
|000058c0| 72 6d 61 74 20 75 6e 69 | 74 73 27 27 2e 20 20 41 |rmat uni|ts''.  A|
|000058d0| 20 66 6f 72 6d 61 74 0a | 75 6e 69 74 20 64 65 73 | format.|unit des|
|000058e0| 63 72 69 62 65 73 20 6f | 6e 65 20 50 79 74 68 6f |cribes o|ne Pytho|
|000058f0| 6e 20 6f 62 6a 65 63 74 | 3b 20 69 74 20 69 73 20 |n object|; it is |
|00005900| 75 73 75 61 6c 6c 79 20 | 61 20 73 69 6e 67 6c 65 |usually |a single|
|00005910| 20 63 68 61 72 61 63 74 | 65 72 20 6f 72 0a 61 20 | charact|er or.a |
|00005920| 70 61 72 65 6e 74 68 65 | 73 69 7a 65 64 20 73 65 |parenthe|sized se|
|00005930| 71 75 65 6e 63 65 20 6f | 66 20 66 6f 72 6d 61 74 |quence o|f format|
|00005940| 20 75 6e 69 74 73 2e 20 | 20 57 69 74 68 20 61 20 | units. | With a |
|00005950| 66 65 77 20 65 78 63 65 | 70 74 69 6f 6e 73 2c 20 |few exce|ptions, |
|00005960| 61 0a 66 6f 72 6d 61 74 | 20 75 6e 69 74 20 74 68 |a.format| unit th|
|00005970| 61 74 20 69 73 20 6e 6f | 74 20 61 20 70 61 72 65 |at is no|t a pare|
|00005980| 6e 74 68 65 73 69 7a 65 | 64 20 73 65 71 75 65 6e |nthesize|d sequen|
|00005990| 63 65 20 6e 6f 72 6d 61 | 6c 6c 79 20 63 6f 72 72 |ce norma|lly corr|
|000059a0| 65 73 70 6f 6e 64 73 0a | 74 6f 20 61 20 73 69 6e |esponds.|to a sin|
|000059b0| 67 6c 65 20 61 64 64 72 | 65 73 73 20 61 72 67 75 |gle addr|ess argu|
|000059c0| 6d 65 6e 74 20 74 6f 20 | 5c 63 6f 64 65 7b 50 79 |ment to |\code{Py|
|000059d0| 41 72 67 5f 50 61 72 73 | 65 54 75 70 6c 65 28 29 |Arg_Pars|eTuple()|
|000059e0| 7d 2e 20 20 49 6e 20 74 | 68 65 0a 66 6f 6c 6c 6f |}.  In t|he.follo|
|000059f0| 77 69 6e 67 20 64 65 73 | 63 72 69 70 74 69 6f 6e |wing des|cription|
|00005a00| 2c 20 74 68 65 20 71 75 | 6f 74 65 64 20 66 6f 72 |, the qu|oted for|
|00005a10| 6d 20 69 73 20 74 68 65 | 20 66 6f 72 6d 61 74 20 |m is the| format |
|00005a20| 75 6e 69 74 3b 20 74 68 | 65 20 65 6e 74 72 79 0a |unit; th|e entry.|
|00005a30| 69 6e 20 28 72 6f 75 6e | 64 29 20 70 61 72 65 6e |in (roun|d) paren|
|00005a40| 74 68 65 73 65 73 20 69 | 73 20 74 68 65 20 50 79 |theses i|s the Py|
|00005a50| 74 68 6f 6e 20 6f 62 6a | 65 63 74 20 74 79 70 65 |thon obj|ect type|
|00005a60| 20 74 68 61 74 20 6d 61 | 74 63 68 65 73 20 74 68 | that ma|tches th|
|00005a70| 65 0a 66 6f 72 6d 61 74 | 20 75 6e 69 74 3b 20 61 |e.format| unit; a|
|00005a80| 6e 64 20 74 68 65 20 65 | 6e 74 72 79 20 69 6e 20 |nd the e|ntry in |
|00005a90| 5b 73 71 75 61 72 65 5d | 20 62 72 61 63 6b 65 74 |[square]| bracket|
|00005aa0| 73 20 69 73 20 74 68 65 | 20 74 79 70 65 20 6f 66 |s is the| type of|
|00005ab0| 20 74 68 65 20 43 0a 76 | 61 72 69 61 62 6c 65 28 | the C.v|ariable(|
|00005ac0| 73 29 20 77 68 6f 73 65 | 20 61 64 64 72 65 73 73 |s) whose| address|
|00005ad0| 20 73 68 6f 75 6c 64 20 | 62 65 20 70 61 73 73 65 | should |be passe|
|00005ae0| 64 2e 20 20 28 55 73 65 | 20 74 68 65 20 5c 73 61 |d.  (Use| the \sa|
|00005af0| 6d 70 7b 5c 26 7d 0a 6f | 70 65 72 61 74 6f 72 20 |mp{\&}.o|perator |
|00005b00| 74 6f 20 70 61 73 73 20 | 61 20 76 61 72 69 61 62 |to pass |a variab|
|00005b10| 6c 65 27 73 20 61 64 64 | 72 65 73 73 2e 29 0a 0a |le's add|ress.)..|
|00005b20| 5c 62 65 67 69 6e 7b 64 | 65 73 63 72 69 70 74 69 |\begin{d|escripti|
|00005b30| 6f 6e 7d 0a 0a 5c 69 74 | 65 6d 5b 5c 73 61 6d 70 |on}..\it|em[\samp|
|00005b40| 7b 73 7d 20 28 73 74 72 | 69 6e 67 29 20 5b 63 68 |{s} (str|ing) [ch|
|00005b50| 61 72 20 2a 5d 5d 0a 43 | 6f 6e 76 65 72 74 20 61 |ar *]].C|onvert a|
|00005b60| 20 50 79 74 68 6f 6e 20 | 73 74 72 69 6e 67 20 74 | Python |string t|
|00005b70| 6f 20 61 20 43 20 70 6f | 69 6e 74 65 72 20 74 6f |o a C po|inter to|
|00005b80| 20 61 20 63 68 61 72 61 | 63 74 65 72 20 73 74 72 | a chara|cter str|
|00005b90| 69 6e 67 2e 20 20 59 6f | 75 0a 6d 75 73 74 20 6e |ing.  Yo|u.must n|
|00005ba0| 6f 74 20 70 72 6f 76 69 | 64 65 20 73 74 6f 72 61 |ot provi|de stora|
|00005bb0| 67 65 20 66 6f 72 20 74 | 68 65 20 73 74 72 69 6e |ge for t|he strin|
|00005bc0| 67 20 69 74 73 65 6c 66 | 3b 20 61 20 70 6f 69 6e |g itself|; a poin|
|00005bd0| 74 65 72 20 74 6f 20 61 | 6e 0a 65 78 69 73 74 69 |ter to a|n.existi|
|00005be0| 6e 67 20 73 74 72 69 6e | 67 20 69 73 20 73 74 6f |ng strin|g is sto|
|00005bf0| 72 65 64 20 69 6e 74 6f | 20 74 68 65 20 63 68 61 |red into| the cha|
|00005c00| 72 61 63 74 65 72 20 70 | 6f 69 6e 74 65 72 20 76 |racter p|ointer v|
|00005c10| 61 72 69 61 62 6c 65 20 | 77 68 6f 73 65 0a 61 64 |ariable |whose.ad|
|00005c20| 64 72 65 73 73 20 79 6f | 75 20 70 61 73 73 2e 20 |dress yo|u pass. |
|00005c30| 20 54 68 65 20 43 20 73 | 74 72 69 6e 67 20 69 73 | The C s|tring is|
|00005c40| 20 6e 75 6c 6c 2d 74 65 | 72 6d 69 6e 61 74 65 64 | null-te|rminated|
|00005c50| 2e 20 20 54 68 65 20 50 | 79 74 68 6f 6e 20 73 74 |.  The P|ython st|
|00005c60| 72 69 6e 67 0a 6d 75 73 | 74 20 6e 6f 74 20 63 6f |ring.mus|t not co|
|00005c70| 6e 74 61 69 6e 20 65 6d | 62 65 64 64 65 64 20 6e |ntain em|bedded n|
|00005c80| 75 6c 6c 20 62 79 74 65 | 73 3b 20 69 66 20 69 74 |ull byte|s; if it|
|00005c90| 20 64 6f 65 73 2c 20 61 | 20 5c 63 6f 64 65 7b 54 | does, a| \code{T|
|00005ca0| 79 70 65 45 72 72 6f 72 | 7d 0a 65 78 63 65 70 74 |ypeError|}.except|
|00005cb0| 69 6f 6e 20 69 73 20 72 | 61 69 73 65 64 2e 0a 0a |ion is r|aised...|
|00005cc0| 5c 69 74 65 6d 5b 5c 73 | 61 6d 70 7b 73 5c 23 7d |\item[\s|amp{s\#}|
|00005cd0| 20 28 73 74 72 69 6e 67 | 29 20 7b 5b 63 68 61 72 | (string|) {[char|
|00005ce0| 20 2a 2c 20 69 6e 74 5d | 7d 5d 0a 54 68 69 73 20 | *, int]|}].This |
|00005cf0| 76 61 72 69 61 6e 74 20 | 6f 6e 20 5c 63 6f 64 65 |variant |on \code|
|00005d00| 7b 27 73 27 7d 20 73 74 | 6f 72 65 73 20 69 6e 74 |{'s'} st|ores int|
|00005d10| 6f 20 74 77 6f 20 43 20 | 76 61 72 69 61 62 6c 65 |o two C |variable|
|00005d20| 73 2c 20 74 68 65 20 66 | 69 72 73 74 20 6f 6e 65 |s, the f|irst one|
|00005d30| 0a 61 20 70 6f 69 6e 74 | 65 72 20 74 6f 20 61 20 |.a point|er to a |
|00005d40| 63 68 61 72 61 63 74 65 | 72 20 73 74 72 69 6e 67 |characte|r string|
|00005d50| 2c 20 74 68 65 20 73 65 | 63 6f 6e 64 20 6f 6e 65 |, the se|cond one|
|00005d60| 20 69 74 73 20 6c 65 6e | 67 74 68 2e 20 20 49 6e | its len|gth.  In|
|00005d70| 20 74 68 69 73 0a 63 61 | 73 65 20 74 68 65 20 50 | this.ca|se the P|
|00005d80| 79 74 68 6f 6e 20 73 74 | 72 69 6e 67 20 6d 61 79 |ython st|ring may|
|00005d90| 20 63 6f 6e 74 61 69 6e | 20 65 6d 62 65 64 64 65 | contain| embedde|
|00005da0| 64 20 6e 75 6c 6c 20 62 | 79 74 65 73 2e 0a 0a 5c |d null b|ytes...\|
|00005db0| 69 74 65 6d 5b 5c 73 61 | 6d 70 7b 7a 7d 20 28 73 |item[\sa|mp{z} (s|
|00005dc0| 74 72 69 6e 67 20 6f 72 | 20 5c 63 6f 64 65 7b 4e |tring or| \code{N|
|00005dd0| 6f 6e 65 7d 29 20 7b 5b | 63 68 61 72 20 2a 5d 7d |one}) {[|char *]}|
|00005de0| 5d 0a 4c 69 6b 65 20 5c | 73 61 6d 70 7b 73 7d 2c |].Like \|samp{s},|
|00005df0| 20 62 75 74 20 74 68 65 | 20 50 79 74 68 6f 6e 20 | but the| Python |
|00005e00| 6f 62 6a 65 63 74 20 6d | 61 79 20 61 6c 73 6f 20 |object m|ay also |
|00005e10| 62 65 20 5c 63 6f 64 65 | 7b 4e 6f 6e 65 7d 2c 20 |be \code|{None}, |
|00005e20| 69 6e 20 77 68 69 63 68 | 0a 63 61 73 65 20 74 68 |in which|.case th|
|00005e30| 65 20 43 20 70 6f 69 6e | 74 65 72 20 69 73 20 73 |e C poin|ter is s|
|00005e40| 65 74 20 74 6f 20 5c 63 | 6f 64 65 7b 4e 55 4c 4c |et to \c|ode{NULL|
|00005e50| 7d 2e 0a 0a 5c 69 74 65 | 6d 5b 5c 73 61 6d 70 7b |}...\ite|m[\samp{|
|00005e60| 7a 5c 23 7d 20 28 73 74 | 72 69 6e 67 20 6f 72 20 |z\#} (st|ring or |
|00005e70| 5c 63 6f 64 65 7b 4e 6f | 6e 65 7d 29 20 7b 5b 63 |\code{No|ne}) {[c|
|00005e80| 68 61 72 20 2a 2c 20 69 | 6e 74 5d 7d 5d 0a 54 68 |har *, i|nt]}].Th|
|00005e90| 69 73 20 69 73 20 74 6f | 20 5c 63 6f 64 65 7b 27 |is is to| \code{'|
|00005ea0| 73 5c 23 27 7d 20 61 73 | 20 5c 63 6f 64 65 7b 27 |s\#'} as| \code{'|
|00005eb0| 7a 27 7d 20 69 73 20 74 | 6f 20 5c 63 6f 64 65 7b |z'} is t|o \code{|
|00005ec0| 27 73 27 7d 2e 0a 0a 5c | 69 74 65 6d 5b 5c 73 61 |'s'}...\|item[\sa|
|00005ed0| 6d 70 7b 62 7d 20 28 69 | 6e 74 65 67 65 72 29 20 |mp{b} (i|nteger) |
|00005ee0| 7b 5b 63 68 61 72 5d 7d | 5d 0a 43 6f 6e 76 65 72 |{[char]}|].Conver|
|00005ef0| 74 20 61 20 50 79 74 68 | 6f 6e 20 69 6e 74 65 67 |t a Pyth|on integ|
|00005f00| 65 72 20 74 6f 20 61 20 | 74 69 6e 79 20 69 6e 74 |er to a |tiny int|
|00005f10| 2c 20 73 74 6f 72 65 64 | 20 69 6e 20 61 20 43 20 |, stored| in a C |
|00005f20| 5c 63 6f 64 65 7b 63 68 | 61 72 7d 2e 0a 0a 5c 69 |\code{ch|ar}...\i|
|00005f30| 74 65 6d 5b 5c 73 61 6d | 70 7b 68 7d 20 28 69 6e |tem[\sam|p{h} (in|
|00005f40| 74 65 67 65 72 29 20 7b | 5b 73 68 6f 72 74 20 69 |teger) {|[short i|
|00005f50| 6e 74 5d 7d 5d 0a 43 6f | 6e 76 65 72 74 20 61 20 |nt]}].Co|nvert a |
|00005f60| 50 79 74 68 6f 6e 20 69 | 6e 74 65 67 65 72 20 74 |Python i|nteger t|
|00005f70| 6f 20 61 20 43 20 5c 63 | 6f 64 65 7b 73 68 6f 72 |o a C \c|ode{shor|
|00005f80| 74 20 69 6e 74 7d 2e 0a | 0a 5c 69 74 65 6d 5b 5c |t int}..|.\item[\|
|00005f90| 73 61 6d 70 7b 69 7d 20 | 28 69 6e 74 65 67 65 72 |samp{i} |(integer|
|00005fa0| 29 20 7b 5b 69 6e 74 5d | 7d 5d 0a 43 6f 6e 76 65 |) {[int]|}].Conve|
|00005fb0| 72 74 20 61 20 50 79 74 | 68 6f 6e 20 69 6e 74 65 |rt a Pyt|hon inte|
|00005fc0| 67 65 72 20 74 6f 20 61 | 20 70 6c 61 69 6e 20 43 |ger to a| plain C|
|00005fd0| 20 5c 63 6f 64 65 7b 69 | 6e 74 7d 2e 0a 0a 5c 69 | \code{i|nt}...\i|
|00005fe0| 74 65 6d 5b 5c 73 61 6d | 70 7b 6c 7d 20 28 69 6e |tem[\sam|p{l} (in|
|00005ff0| 74 65 67 65 72 29 20 7b | 5b 6c 6f 6e 67 20 69 6e |teger) {|[long in|
|00006000| 74 5d 7d 5d 0a 43 6f 6e | 76 65 72 74 20 61 20 50 |t]}].Con|vert a P|
|00006010| 79 74 68 6f 6e 20 69 6e | 74 65 67 65 72 20 74 6f |ython in|teger to|
|00006020| 20 61 20 43 20 5c 63 6f | 64 65 7b 6c 6f 6e 67 20 | a C \co|de{long |
|00006030| 69 6e 74 7d 2e 0a 0a 5c | 69 74 65 6d 5b 5c 73 61 |int}...\|item[\sa|
|00006040| 6d 70 7b 63 7d 20 28 73 | 74 72 69 6e 67 20 6f 66 |mp{c} (s|tring of|
|00006050| 20 6c 65 6e 67 74 68 20 | 31 29 20 7b 5b 63 68 61 | length |1) {[cha|
|00006060| 72 5d 7d 5d 0a 43 6f 6e | 76 65 72 74 20 61 20 50 |r]}].Con|vert a P|
|00006070| 79 74 68 6f 6e 20 63 68 | 61 72 61 63 74 65 72 2c |ython ch|aracter,|
|00006080| 20 72 65 70 72 65 73 65 | 6e 74 65 64 20 61 73 20 | represe|nted as |
|00006090| 61 20 73 74 72 69 6e 67 | 20 6f 66 20 6c 65 6e 67 |a string| of leng|
|000060a0| 74 68 20 31 2c 20 74 6f | 20 61 0a 43 20 5c 63 6f |th 1, to| a.C \co|
|000060b0| 64 65 7b 63 68 61 72 7d | 2e 0a 0a 5c 69 74 65 6d |de{char}|...\item|
|000060c0| 5b 5c 73 61 6d 70 7b 66 | 7d 20 28 66 6c 6f 61 74 |[\samp{f|} (float|
|000060d0| 29 20 7b 5b 66 6c 6f 61 | 74 5d 7d 5d 0a 43 6f 6e |) {[floa|t]}].Con|
|000060e0| 76 65 72 74 20 61 20 50 | 79 74 68 6f 6e 20 66 6c |vert a P|ython fl|
|000060f0| 6f 61 74 69 6e 67 20 70 | 6f 69 6e 74 20 6e 75 6d |oating p|oint num|
|00006100| 62 65 72 20 74 6f 20 61 | 20 43 20 5c 63 6f 64 65 |ber to a| C \code|
|00006110| 7b 66 6c 6f 61 74 7d 2e | 0a 0a 5c 69 74 65 6d 5b |{float}.|..\item[|
|00006120| 5c 73 61 6d 70 7b 64 7d | 20 28 66 6c 6f 61 74 29 |\samp{d}| (float)|
|00006130| 20 7b 5b 64 6f 75 62 6c | 65 5d 7d 5d 0a 43 6f 6e | {[doubl|e]}].Con|
|00006140| 76 65 72 74 20 61 20 50 | 79 74 68 6f 6e 20 66 6c |vert a P|ython fl|
|00006150| 6f 61 74 69 6e 67 20 70 | 6f 69 6e 74 20 6e 75 6d |oating p|oint num|
|00006160| 62 65 72 20 74 6f 20 61 | 20 43 20 5c 63 6f 64 65 |ber to a| C \code|
|00006170| 7b 64 6f 75 62 6c 65 7d | 2e 0a 0a 5c 69 74 65 6d |{double}|...\item|
|00006180| 5b 5c 73 61 6d 70 7b 4f | 7d 20 28 6f 62 6a 65 63 |[\samp{O|} (objec|
|00006190| 74 29 20 7b 5b 50 79 4f | 62 6a 65 63 74 20 2a 5d |t) {[PyO|bject *]|
|000061a0| 7d 5d 0a 53 74 6f 72 65 | 20 61 20 50 79 74 68 6f |}].Store| a Pytho|
|000061b0| 6e 20 6f 62 6a 65 63 74 | 20 28 77 69 74 68 6f 75 |n object| (withou|
|000061c0| 74 20 61 6e 79 20 63 6f | 6e 76 65 72 73 69 6f 6e |t any co|nversion|
|000061d0| 29 20 69 6e 20 61 20 43 | 20 6f 62 6a 65 63 74 20 |) in a C| object |
|000061e0| 70 6f 69 6e 74 65 72 2e | 0a 54 68 65 20 43 20 70 |pointer.|.The C p|
|000061f0| 72 6f 67 72 61 6d 20 74 | 68 75 73 20 72 65 63 65 |rogram t|hus rece|
|00006200| 69 76 65 73 20 74 68 65 | 20 61 63 74 75 61 6c 20 |ives the| actual |
|00006210| 6f 62 6a 65 63 74 20 74 | 68 61 74 20 77 61 73 20 |object t|hat was |
|00006220| 70 61 73 73 65 64 2e 20 | 20 54 68 65 0a 6f 62 6a |passed. | The.obj|
|00006230| 65 63 74 27 73 20 72 65 | 66 65 72 65 6e 63 65 20 |ect's re|ference |
|00006240| 63 6f 75 6e 74 20 69 73 | 20 6e 6f 74 20 69 6e 63 |count is| not inc|
|00006250| 72 65 61 73 65 64 2e 20 | 20 54 68 65 20 70 6f 69 |reased. | The poi|
|00006260| 6e 74 65 72 20 73 74 6f | 72 65 64 20 69 73 20 6e |nter sto|red is n|
|00006270| 6f 74 0a 5c 63 6f 64 65 | 7b 4e 55 4c 4c 7d 2e 0a |ot.\code|{NULL}..|
|00006280| 0a 5c 69 74 65 6d 5b 5c | 73 61 6d 70 7b 4f 21 7d |.\item[\|samp{O!}|
|00006290| 20 28 6f 62 6a 65 63 74 | 29 20 7b 5b 5c 76 61 72 | (object|) {[\var|
|000062a0| 7b 74 79 70 65 6f 62 6a | 65 63 74 7d 2c 20 50 79 |{typeobj|ect}, Py|
|000062b0| 4f 62 6a 65 63 74 20 2a | 5d 7d 5d 0a 53 74 6f 72 |Object *|]}].Stor|
|000062c0| 65 20 61 20 50 79 74 68 | 6f 6e 20 6f 62 6a 65 63 |e a Pyth|on objec|
|000062d0| 74 20 69 6e 20 61 20 43 | 20 6f 62 6a 65 63 74 20 |t in a C| object |
|000062e0| 70 6f 69 6e 74 65 72 2e | 20 20 54 68 69 73 20 69 |pointer.|  This i|
|000062f0| 73 20 73 69 6d 69 6c 61 | 72 20 74 6f 0a 5c 73 61 |s simila|r to.\sa|
|00006300| 6d 70 7b 4f 7d 2c 20 62 | 75 74 20 74 61 6b 65 73 |mp{O}, b|ut takes|
|00006310| 20 74 77 6f 20 43 20 61 | 72 67 75 6d 65 6e 74 73 | two C a|rguments|
|00006320| 3a 20 74 68 65 20 66 69 | 72 73 74 20 69 73 20 74 |: the fi|rst is t|
|00006330| 68 65 20 61 64 64 72 65 | 73 73 20 6f 66 20 61 0a |he addre|ss of a.|
|00006340| 50 79 74 68 6f 6e 20 74 | 79 70 65 20 6f 62 6a 65 |Python t|ype obje|
|00006350| 63 74 2c 20 74 68 65 20 | 73 65 63 6f 6e 64 20 69 |ct, the |second i|
|00006360| 73 20 74 68 65 20 61 64 | 64 72 65 73 73 20 6f 66 |s the ad|dress of|
|00006370| 20 74 68 65 20 43 20 76 | 61 72 69 61 62 6c 65 20 | the C v|ariable |
|00006380| 28 6f 66 0a 74 79 70 65 | 20 5c 63 6f 64 65 7b 50 |(of.type| \code{P|
|00006390| 79 4f 62 6a 65 63 74 20 | 2a 7d 29 20 69 6e 74 6f |yObject |*}) into|
|000063a0| 20 77 68 69 63 68 20 74 | 68 65 20 6f 62 6a 65 63 | which t|he objec|
|000063b0| 74 20 70 6f 69 6e 74 65 | 72 20 69 73 20 73 74 6f |t pointe|r is sto|
|000063c0| 72 65 64 2e 0a 49 66 20 | 74 68 65 20 50 79 74 68 |red..If |the Pyth|
|000063d0| 6f 6e 20 6f 62 6a 65 63 | 74 20 64 6f 65 73 20 6e |on objec|t does n|
|000063e0| 6f 74 20 68 61 76 65 20 | 74 68 65 20 72 65 71 75 |ot have |the requ|
|000063f0| 69 72 65 64 20 74 79 70 | 65 2c 20 61 0a 5c 63 6f |ired typ|e, a.\co|
+--------+-------------------------+-------------------------+--------+--------+