~launchpad-committers/ubuntu/lucid/pysvn/launchpad-ppa
» Revision
14
: Import/pycxx-5.4.0/Doc/PyCXX.html
« back to all changes in this revision
Viewing changes to Import/pycxx-5.4.0/Doc/PyCXX.html
- browse files at revision 14
- compare with another revision
- download diff
- download tarball
- view history from revision 14
- Committer: Bazaar Package Importer
- Author(s): Matthias Klose
- Date: 2007-02-18 14:30:49 UTC
- Revision ID: james.westby@ubuntu.com-20070218143049-m3wxtj3m79xqo0by
Tags: 1.5.1-0ubuntu1
New upstream version; bug fix release.
- files added:
- Import/pycxx-5.4.0
- Import/pycxx-5.4.0/CXX
- Import/pycxx-5.4.0/Demo
- Import/pycxx-5.4.0/Doc
- Import/pycxx-5.4.0/Lib
- Import/pycxx-5.4.0/SourceForge
- Import/pycxx-5.4.0/Src
- files removed:
- Import/pycxx-5.3.6
- Import/pycxx-5.3.6/CXX
- Import/pycxx-5.3.6/Demo
- Import/pycxx-5.3.6/Doc
- Import/pycxx-5.3.6/Lib
- Import/pycxx-5.3.6/SourceForge
- Import/pycxx-5.3.6/Src
- files modified:
- Builder/builder_custom_init.sh
added
removed
Import/pycxx-5.4.0/Doc/PyCXX.html
1
<html>
2
3
<head>
4
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
5
<title>Writing Python Extensions in C++</title>
6
<style>
7
H1, H2, H3, H4 {color: #000099;
8
background-color: lightskyblue}
9
h3 {position: relative; left: 20px}
10
11
p {position: relative; left: 20px; margin-right: 20px}
12
pre {color: #0000cc; background-color: #eeeeee; position: relative; left: 40px; margin-right: 80px;
13
border-style: solid; border-color: black; border-width: thin}
14
kbd {color: #990000}
15
p cite, ol cite, ul cite {font-family: monospace; font-style: normal; font-size: normal}
16
li var, pre var, p var, kbd var {color: #009900; font-style: italic}
17
li samp, pre samp, p samp, kbd samp {color: #009900; font-weight: bold}
18
li p {position: relative; left: 0}
19
table { position: relative; left: 20px; border: solid #888888 1px; background-color: #eeeeee}
20
table th {border: solid #888888 1px; background-color: #88dd88; color: black}
21
table td {border: solid #888888 1px}
22
table td.code {border: solid #888888 1px;font-family: monospace; font-style: normal; font-size: normal}
23
p.param {background-color: #eeeeee; border-top: lightskyblue solid 4}
24
</style>
25
26
</head>
27
28
<body bgcolor="#FFFFFF">
29
30
<h1 ALIGN="center">Writing Python Extensions in C++</h1>
31
32
<p ALIGN="CENTER">Barry Scott<br>
33
Reading, Berkshire, England<br>
34
<a href="mailto:barry@barrys-emacs.org">barry@barrys-emacs.org</a><br>
35
</p>
36
37
<p ALIGN="CENTER">Paul F. Dubois, <a href="mailto:dubois1@llnl.gov">dubois1@llnl.gov</a><br>
38
Lawrence Livermore National Laboratory<br>
39
Livermore, California, U.S.A.</p>
40
41
42
<p>PyCXX is designed to make it easier to extend Python with C++</p>
43
44
45
<p>PyCXX is a set of C++ facilities to make it easier to write Python extensions.
46
The chief way in which PyCXX makes it easier to write Python extensions is that it greatly
47
increases the probability that your program will not make a reference-counting error and
48
will not have to continually check error returns from the Python C API. PyCXX
49
integrates Python with C++ in these ways: </p>
50
51
<ul>
52
<li>C++ exception handling is relied on to detect errors and clean up. In a complicated
53
function this is often a tremendous problem when writing in C. With PyCXX, we let the
54
compiler keep track of what objects need to be dereferenced when an error occurs.
55
<li>The Standard Template Library (STL) and its many algorithms plug and play with Python
56
containers such as lists and tuples.
57
<li>The optional CXX_Extensions facility allows you to replace the clumsy C tables with
58
objects and method calls that define your modules and extension objects.
59
</ul>
60
61
<h3>Download and Installation</h3>
62
63
<p>Download PyCXX from <a href="http://sourceforge.net/projects/cxx/">http://sourceforge.net/projects/cxx/</a>.</p>
64
65
<p>The distribution layout is:</p>
66
<table>
67
<tr><th>Directory</th><th>Description</th></tr>
68
<tr><td class=code>.</td><td>Makefile for Unix and Windows, Release documentation</td>
69
<tr><td class=code>./CXX</td><td>Header files</td>
70
<tr><td class=code>./Src</td><td>Source files</td>
71
<tr><td class=code>./Doc</td><td>Documentation</td>
72
<tr><td class=code>./Demo</td><td>Testing and Demonstartion files</td>
73
</table>
74
75
<p>To use PyCXX you use its include files and add its source routines to your module.</p>
76
77
<p>Installation:</p>
78
<ul>
79
<li>Install the PyCXX files into a directory of your choice. For example:<br>
80
Windows: <cite>C:\PyCXX</cite><br>
81
Unix: <cite>/usr/local/PyCXX</cite>
82
<li>Tell your compiler where the PyCXX header files are:<br>
83
Windows: <cite>cl /I=C:\PyCXX ...</cite><br>
84
Unix: <cite>g++ -I/usr/local/PyCXX ...</cite>
85
<li>Include PyCXX headers files in your code using the CXX prefix:<br>
86
<cite>#include "CXX/Object.hxx"</cite>
87
</ul>
88
89
<p>The header file CXX/config.h may need to be adjusted for the
90
compiler you use. As of this writing, only a fairly obscure reference to part of the
91
standard library needs this adjustment. Unlike prior releases, PyCXX now assumes namespace
92
support and a standard C++ library. </p>
93
94
<h3>Use of namespaces</h3>
95
96
<p>All PyCXX assets are in namespace "Py". You need to include
97
the Py:: prefix when referring to them, or include the statement:</p>
98
99
<p>using namespace Py;</p>
100
101
<h2>Wrappers for standard objects: CXX_Objects.h</h2>
102
103
<p>Header file CXX_Objects.h requires adding file Src/cxxsupport.cxx to
104
your module sources. CXX_Objects provides a set of wrapper classes that allow you access
105
to most of the Python C API using a C++ notation that closely resembles Python. For
106
example, this Python:</p>
107
108
<pre>d = {}
109
d["a"] = 1
110
d["b"] = 2
111
alist = d.keys()
112
print alist</pre>
113
114
<p>Can be written in C++:</p>
115
116
<pre>Dict d;
117
List alist;
118
d["a"] = Int(1);
119
d["b"] = Int(2);
120
alist = d.keys();
121
std::cout << alist << std::endl;
122
</pre>
123
124
<p>You can optionally use the CXX/Extensions.hxx facility described later
125
to define Python extension modules and extension objects.</p>
126
127
<h3>We avoid programming with Python object pointers</h3>
128
129
<p>The essential idea is that we avoid, as much as possible, programming with pointers to
130
Python objects, that is, variables of type <cite>PyObject*</cite>. Instead,
131
we use instances of a family of C++ classes that represent the
132
usual Python objects. This family is easily extendible to include new kinds of Python
133
objects.</p>
134
135
<p>For example, consider the case in which we wish to write a method, taking a single
136
integer argument, that will create a Python <cite>dict</cite>
137
and insert into it that the integer plus one under the key <cite>value</cite>.
138
In C we might do that as follows:</p>
139
140
<pre>static PyObject* mymodule_addvalue (PyObject* self, PyObject* args)
141
{
142
PyObject *d;
143
PyObject* f;
144
int k;
145
PyArgs_ParseTuple(args, "i", &k);
146
d = PyDict_New();
147
if (!d)
148
return NULL;
149
150
f = PyInt_NEW(k+1);
151
if(!f)
152
{
153
Py_DECREF(d); /* have to get rid of d first */
154
return NULL;
155
}
156
if(PyDict_SetItemString(d, "value", f) == -1)
157
{
158
Py_DECREF(f);
159
Py_DECREF(d);
160
return NULL;
161
}
162
163
return d;
164
}</pre>
165
166
<p>If you have written a significant Python extension, this tedium looks all too familiar.
167
The vast bulk of the coding is error checking and cleanup. Now compare the same thing
168
written in C++ using CXX/Objects.hxx. The things with Python-like names (Int, Dict, Tuple) are
169
from CXX/Objects.hxx.</p>
170
171
<pre>static PyObject* mymodule_addvalue (PyObject* self, PyObject* pargs)
172
{
173
try
174
{
175
Tuple args(pargs);
176
args.verify_length(1);
177
178
Dict d;
179
Int k = args[0];
180
d["value"] = k + 1;
181
182
return new_reference_to(d);
183
}
184
catch (const PyException&)
185
{
186
return NULL;
187
}
188
}</pre>
189
190
<p>If there are not the right number of arguments or the argument is not an
191
integer, an exception is thrown. In this case we choose to catch it and convert it into a
192
Python exception. The C++ exception handling mechanism takes care all the cleanup.</p>
193
194
<p>Note that the creation of the <cite>Int k</cite> got the first argument <em>and</em> verified
195
that it is an <cite>Int</cite>.</p>
196
197
<p>Just to peek ahead, if you wrote this method in an
198
ExtensionModule-derived module of your own, it would be a method and it could be written
199
even more simply:</p>
200
201
<pre>
202
Object addvalue (Object & self, const Tuple & args)
203
{
204
args.verify_length(1);
205
Dict d;
206
Int k = args[0];
207
d["value"] = k + 1;
208
return d;
209
}
210
</pre>
211
212
<h2>The basic concept is to wrap Python pointers</h2>
213
214
215
<p>The basic concept of CXX/Objects.hxx is to create a wrapper around
216
each <cite>PyObject *</cite> so that the reference counting can be
217
done automatically, thus eliminating the most frequent source of errors. In addition, we
218
can then add methods and operators so that Python objects can be manipulated in C++
219
much like you would in Python.</p>
220
221
<p>Each <cite>Object</cite> contains a <cite>PyObject *</cite>
222
to which it owns a reference. When an <cite>Object</cite> is destroyed, it releases its ownership on
223
the pointer. Since C++ calls the destructors on objects that are about to go out of scope,
224
we are guaranteed that we will keep the reference counts right even if we unexpectedly
225
leave a routine with an exception.</p>
226
227
<p>As a matter of philosophy, CXX/Objects.hxx prevents the creation of instances of its
228
classes unless the instance will be a valid instance of its class. When an attempt is made
229
to create an object that will not be valid, an exception is thrown.</p>
230
231
<p>Class <cite>Object</cite> represents the most general kind of Python object. The rest of the classes
232
that represent Python objects inherit from it.</p>
233
234
<pre>Object
235
Type
236
Int
237
Float
238
Long
239
Complex
240
Char
241
Sequence -> SeqBase<T>
242
String
243
Tuple
244
List
245
Mapping -> MapBase<T>
246
Dict
247
Callable
248
Module</pre>
249
250
<p>There are several constructors for each of these classes. For example, you can create
251
an <cite>Int</cite> from an integer as in</p>
252
253
<pre>Int s(3)</pre>
254
255
<p>However, you can also create an instance of one of these classes using any <cite>PyObject*</cite> or
256
another <cite>Object</cite>. If the corresponding Python object does not actually have the type
257
desired, an exception is thrown. This is accomplished as follows. Class <cite>Object</cite> defines a
258
virtual function <cite>accepts</cite>:</p>
259
260
<pre>virtual bool accepts(PyObject* p)</pre>
261
262
<p>The base class version of <cite>accepts</cite> returns true for any pointer p except 0. This means
263
we can create an Object using any <cite>PyObject *</cite>, or from any other
264
<cite>Object</cite>. However, if we attempt to create an <cite>Int</cite> from a <cite>PyObject *</cite>,
265
the overridding version
266
of <cite>accepts</cite> in class <cite>Int</cite> will only accept pointers that correspond to Python ints.
267
Therefore if we have a <cite>Tuple t</cite> and we wish to get the first element and be sure it is an
268
<cite>Int</cite>, we do</p>
269
270
<pre>Int first_element = t[0]</pre>
271
272
<p>This will not only accomplish the goal of extracting the first element of the <cite>Tuple t</cite>,
273
but it will ensure that the result is an <cite>Int</cite>. If not, an exception is thrown. The
274
exception mechanism is discussed later.</p>
275
276
<h2>Class Object</h2>
277
278
<p>Class <cite>Object</cite> serves as the base class for the other classes. Its default constructor
279
constructs a <cite>Py_None</cite>, the unique object of Python type <cite>None</cite>. The interface to <cite>Object</cite>
280
consists of a large number of methods corresponding to the operations that are defined for
281
every Python object. In each case, the methods throw an exception if anything goes
282
wrong.</p>
283
284
<p>There is no method corresponding to <cite>PyObject_SetItem</cite> with an arbitrary Python object
285
as a key. Instead, create an instance of a more specific child of <cite>Object</cite> and use the
286
appropriate facilities.</p>
287
288
<p>The comparison operators use the Python comparison function to compare values. The
289
method <cite>is</cite> is available to test for absolute identity.</p>
290
291
<p>A conversion to standard library string type <cite>std::string</cite> is supplied using method
292
<cite>as_string</cite>. Stream output of PyCXX <cite>Object</cite> instances uses this conversion,
293
which in turn uses the Python object's str() representation.</p>
294
295
<p>All the numeric operators are defined on all possible combinations of <cite>Object</cite>,
296
<cite>long</cite>, and <cite>double</cite>. These use the corresponding Python operators,
297
and should the operation fail for some reason, an exception is thrown.</p>
298
299
<h3>Dealing with pointers returned by the Python C API</h3>
300
301
<p>Often, <cite>PyObject *</cite> pointers are acquired from some function,
302
particularly functions in the Python C API. If you wish to make an object from the pointer
303
returned by such a function, you need to know if the function returns you an <i>owned</i>
304
or <i>unowned</i> reference. Unowned references are unusual but there are some cases where
305
unowned references are returned.</p>
306
307
<p>Usually, <cite>Object</cite> and its children acquire a new reference when constructed from a
308
<cite>PyObject *</cite>. This is usually not the right behavior if the reference comes from one
309
of the Python C API calls.</p>
310
311
<p>If p is an owned reference, you can add the boolean <cite>true</cite> as an extra
312
argument in the creation routine, <cite>Object(p, true)</cite>, or use the function <cite>asObject(p)</cite> which
313
returns an <cite>Object</cite> created using the owned reference. For example, the routine
314
<cite>PyString_FromString</cite> returns an owned reference to a Python string object. You could write:</p>
315
316
<pre>Object w = asObject( PyString_FromString("my string") );</pre>
317
318
<p>or using the constructor,</p>
319
320
<pre>Object w( PyString_FromString("my string"), true );</pre>
321
322
<p>In fact, you would never do this, since PyCXX has a class String and you can just say: </p>
323
324
<pre>String w( "my string" );</pre>
325
326
<p>Indeed, since most of the Python C API is similarly embodied in <cite>Object</cite>
327
and its descendents, you probably will not use asObject all that often.</p>
328
<h3>Table 1: Class Object</h3>
329
330
<table cellspacing=0 cellpadding=3px width="95%">
331
<tr>
332
<th>Returns</th>
333
<th>Name(signature)</th>
334
<th>Comment</th>
335
</tr>
336
<tr>
337
<td colspan="3"><p align="center"><strong>Basic Methods</strong></td>
338
</tr>
339
<tr>
340
<td class=code>explicit </td>
341
<td class=code>Object (PyObject* pyob=Py_None, bool owned=false) </td>
342
<td>Construct from pointer. </td>
343
</tr>
344
<tr>
345
<td class=code>explicit</td>
346
<td class=code>Object (const Object& ob)</td>
347
<td>Copycons; acquires an owned reference.</td>
348
</tr>
349
<tr>
350
<td class=code>Object&</td>
351
<td class=code>operator= (const Object& rhs) </td>
352
<td>Acquires an owned reference.</td>
353
</tr>
354
<tr>
355
<td class=code>Object&</td>
356
<td class=code>operator= (PyObject* rhsp) </td>
357
<td>Acquires an owned reference.</td>
358
</tr>
359
<tr>
360
<td class=code>virtual</td>
361
<td class=code>~Object () </td>
362
<td>Releases the reference.</td>
363
</tr>
364
<tr>
365
<td class=code>void</td>
366
<td class=code>increment_reference_count() </td>
367
<td>Explicitly increment the count</td>
368
</tr>
369
<tr>
370
<td class=code>void</td>
371
<td class=code>decrement_reference_count()</td>
372
<td>Explicitly decrement count but not to zero</td>
373
</tr>
374
<tr>
375
<td class=code>PyObject*</td>
376
<td class=code>operator* () const</td>
377
<td>Lends the pointer</td>
378
</tr>
379
<tr>
380
<td class=code>PyObject*</td>
381
<td class=code>ptr () const</td>
382
<td>Lends the pointer</td>
383
</tr>
384
<tr>
385
<td class=code>virtual bool</td>
386
<td class=code>accepts (PyObject *pyob) const</td>
387
<td>Would assignment of pyob to this object succeed?</td>
388
</tr>
389
<tr>
390
<td class=code>std::string</td>
391
<td class=code>as_string() const</td>
392
<td>str() representation</td>
393
</tr>
394
<tr>
395
<td colspan="3" align="center"><strong>Python API Interface</strong></td>
396
</tr>
397
<tr>
398
<td class=code>int</td>
399
<td class=code>reference_count () const </td>
400
<td>reference count</td>
401
</tr>
402
<tr>
403
<td class=code>Type</td>
404
<td class=code>type () const</td>
405
<td>associated type object</td>
406
</tr>
407
<tr>
408
<td class=code>String</td>
409
<td class=code>str () const</td>
410
<td>str() representation</td>
411
</tr>
412
<tr>
413
<td class=code>String</td>
414
<td class=code>repr () const</td>
415
<td>repr () representation</td>
416
</tr>
417
<tr>
418
<td class=code>bool</td>
419
<td class=code>hasAttr (const std::string& s) const</td>
420
<td>hasattr(this, s)</td>
421
</tr>
422
<tr>
423
<td class=code>Object</td>
424
<td class=code>getAttr (const std::string& s) const</td>
425
<td>getattr(this, s)</td>
426
</tr>
427
<tr>
428
<td class=code>Object</td>
429
<td class=code>getItem (const Object& key) const</td>
430
<td>getitem(this, key)</td>
431
</tr>
432
<tr>
433
<td class=code>long</td>
434
<td class=code>hashValue () const</td>
435
<td>hash(this)</td>
436
</tr>
437
<tr>
438
<td class=code>void</td>
439
<td class=code>setAttr (const std::string& s,<br>const Object& value)</td>
440
<td>this.s = value</td>
441
</tr>
442
<tr>
443
<td class=code>void</td>
444
<td class=code>delAttr (const std::string& s) </td>
445
<td>del this.s</td>
446
</tr>
447
<tr>
448
<td class=code>void</td>
449
<td class=code>delItem (const Object& key) </td>
450
<td>del this[key]</td>
451
</tr>
452
<tr>
453
<td class=code>bool</td>
454
<td class=code>isCallable () const</td>
455
<td>does this have callable behavior?</td>
456
</tr>
457
<tr>
458
<td class=code>bool</td>
459
<td class=code>isList () const</td>
460
<td>is this a Python list?</td>
461
</tr>
462
<tr>
463
<td class=code>bool</td>
464
<td class=code>isMapping () const</td>
465
<td>does this have mapping behaviors?</td>
466
</tr>
467
<tr>
468
<td class=code>bool</td>
469
<td class=code>isNumeric () const</td>
470
<td>does this have numeric behaviors?</td>
471
</tr>
472
<tr>
473
<td class=code>bool</td>
474
<td class=code>isSequence () const </td>
475
<td>does this have sequence behaviors?</td>
476
</tr>
477
<tr>
478
<td class=code>bool</td>
479
<td class=code>isTrue () const</td>
480
<td>is this true in the Python sense?</td>
481
</tr>
482
<tr>
483
<td class=code>bool</td>
484
<td class=code>isType (const Type& t) const</td>
485
<td>is type(this) == t?</td>
486
</tr>
487
<tr>
488
<td class=code>bool</td>
489
<td class=code>isTuple() const</td>
490
<td>is this a Python tuple?</td>
491
</tr>
492
<tr>
493
<td class=code>bool</td>
494
<td class=code>isString() const</td>
495
<td>is this a Python string?</td>
496
</tr>
497
<tr>
498
<td class=code>bool</td>
499
<td class=code>isUnicode() const</td>
500
<td>is this a Python Unicode string?</td>
501
</tr>
502
<tr>
503
<td class=code>bool</td>
504
<td class=code>isDict() const</td>
505
<td>is this a Python dictionary?</td>
506
</tr>
507
<tr>
508
<td colspan="3" align="center"><strong>Comparison Operators</strong></td>
509
</tr>
510
<tr>
511
<td class=code>bool</td>
512
<td class=code>is(PyObject* pother) const</td>
513
<td>test for identity</td>
514
</tr>
515
<tr>
516
<td class=code>bool</td>
517
<td class=code>is(const Object& other) const</td>
518
<td>test for identity</td>
519
</tr>
520
<tr>
521
<td class=code>bool </td>
522
<td class=code>operator==(const Object& o2) const</td>
523
<td>Comparisons use Python cmp</td>
524
</tr>
525
<tr>
526
<td class=code>bool</td>
527
<td class=code>operator!=(const Object& o2) const</td>
528
<td>Comparisons use Python cmp</td>
529
</tr>
530
<tr>
531
<td class=code>bool</td>
532
<td class=code>operator>=(const Object& o2) const</td>
533
<td>Comparisons use Python cmp</td>
534
</tr>
535
<tr>
536
<td class=code>bool</td>
537
<td class=code>operator<=(const Object& o2) const </td>
538
<td>Comparisons use Python cmp</td>
539
</tr>
540
<tr>
541
<td class=code>bool</td>
542
<td class=code>operator<(const Object& o2) const</td>
543
<td>Comparisons use Python cmp</td>
544
</tr>
545
<tr>
546
<td class=code>bool</td>
547
<td class=code>operator>(const Object& o2) const</td>
548
<td>Comparisons use Python cmp</td>
549
</tr>
550
</table>
551
552
<h1>The Basic Types</h1>
553
554
<p>Corresponding to each of the basic Python types is a class that inherits from Object.
555
Here are the interfaces for those types. Each of them inherits from Object and therefore
556
has all of the inherited methods listed for Object. Where a virtual function is overridden
557
in a class, the name is underlined. </p>
558
559
<h2>Class Type</h2>
560
561
<p>Class Type corresponds to Python type objects. There is no default constructor.</p>
562
563
<h3>Table 2: class Type</h3>
564
565
<table cellspacing=0 cellpadding=3px width="95%">
566
<tr>
567
<th>Returns</th>
568
<th>Name and Signature</th>
569
<th>Comments</th>
570
</tr>
571
<tr>
572
<td class=code>explicit</td>
573
<td class=code>Type (PyObject* pyob, bool owned = false)</td>
574
<td>Constructor</td>
575
</tr>
576
<tr>
577
<td class=code>explicit</td>
578
<td class=code>Type (const Object& ob)</td>
579
<td>Constructor</td>
580
</tr>
581
<tr>
582
<td class=code>explicit</td>
583
<td class=code>Type(const Type& t)</td>
584
<td>Copycons</td>
585
</tr>
586
<tr>
587
<td class=code>Type&</td>
588
<td class=code>operator= (const Object& rhs) </td>
589
<td>Assignment</td>
590
</tr>
591
<tr>
592
<td class=code>Type&</td>
593
<td class=code>operator= (PyObject* rhsp) </td>
594
<td>Assignment</td>
595
</tr>
596
<tr>
597
<td class=code>virtual bool</td>
598
<td class=code><u>accepts</u> (PyObject *pyob) const</td>
599
<td>Uses PyType_Check</td>
600
</tr>
601
</table>
602
603
<h2>Class Int</h2>
604
605
<p>Class Int, derived publically from Object, corresponds to Python ints. Note that the
606
latter correspond to C long ints. Class Int has an implicit user-defined conversion to
607
long int. All constructors, on the other hand, are explicit. The default constructor
608
creates a Python int zero.</p>
609
610
<h3>Table 3: class Int</h3>
611
612
613
<table cellspacing=0 cellpadding=3px width="95%">
614
<tr>
615
<th>Returns</td>
616
<th>Name and Signature</td>
617
<th>Comments</td>
618
</tr>
619
<tr>
620
<td class=code>explicit</td>
621
<td class=code>Int (PyObject *pyob, bool owned= false, bool owned = false)</td>
622
<td>Constructor</td>
623
</tr>
624
<tr>
625
<td class=code>explicit</td>
626
<td class=code>Int (const Int& ob)</td>
627
<td>Constructor</td>
628
</tr>
629
<tr>
630
<td class=code>explicit</td>
631
<td class=code>Int (long v = 0L)</td>
632
<td>Construct from long</td>
633
</tr>
634
<tr>
635
<td class=code>explicit</td>
636
<td class=code>Int (int v)</td>
637
<td>Contruct from int</td>
638
</tr>
639
<tr>
640
<td class=code>explicit</td>
641
<td class=code>Int (const Object& ob)</td>
642
<td>Copycons</td>
643
</tr>
644
<tr>
645
<td class=code>Int&</td>
646
<td class=code>operator= (const Object& rhs)</td>
647
<td>Assignment</td>
648
</tr>
649
<tr>
650
<td class=code>Int&</td>
651
<td class=code>operator= (PyObject* rhsp)</td>
652
<td>Assignment</td>
653
</tr>
654
<tr>
655
<td class=code>virtual bool </td>
656
<td class=code> (PyObject *pyob) const </td>
657
<td>Based on PyInt_Check</td>
658
</tr>
659
<tr>
660
<td class=code>long</td>
661
<td class=code>operator long() const </td>
662
<td><em>Implicit</em> conversion to long int</td>
663
</tr>
664
<tr>
665
<td class=code>Int&</td>
666
<td class=code>operator= (int v)</td>
667
<td>Assign from int</td>
668
</tr>
669
<tr>
670
<td class=code>Int&</td>
671
<td class=code>operator= (long v) </td>
672
<td>Assign from long</td>
673
</tr>
674
</table>
675
676
<hr>
677
678
<h2>Class Long</h2>
679
680
<p>Class Long, derived publically from Object, corresponds to Python type long. In Python,
681
a long is an integer type of unlimited size, and is usually used for applications such as
682
cryptography, not as a normal integer. Implicit conversions to both double and long are
683
provided, although the latter may of course fail if the number is actually too big. All
684
constructors are explicit. The default constructor produces a Python long zero.</p>
685
686
<h3>Table 4: Class Long</h3>
687
688
<table cellspacing=0 cellpadding=3px width="95%">
689
<tr>
690
<th>Returns</td>
691
<th>Name and Signature</td>
692
<th>Comments</td>
693
</tr>
694
<tr>
695
<td class=code>explicit</td>
696
<td class=code>Long (PyObject *pyob</a>, bool owned = false)</td>
697
<td>Constructor</td>
698
</tr>
699
<tr>
700
<td class=code>explicit</td>
701
<td class=code>Long (const Int& ob)</td>
702
<td>Constructor</td>
703
</tr>
704
<tr>
705
<td class=code>explicit</td>
706
<td class=code>Long (long v = 0L)</td>
707
<td>Construct from long</td>
708
</tr>
709
<tr>
710
<td class=code>explicit</td>
711
<td class=code>Long (int v)</td>
712
<td>Contruct from int</td>
713
</tr>
714
<tr>
715
<td class=code>explicit</td>
716
<td class=code>Long (const Object& ob)</td>
717
<td>Copycons</td>
718
</tr>
719
<tr>
720
<td class=code>Long&</td>
721
<td class=code>operator= (const Object& rhs)</td>
722
<td>Assignment</td>
723
</tr>
724
<tr>
725
<td class=code>Long&</td>
726
<td class=code>operator= (PyObject* rhsp)</td>
727
<td>Assignment</td>
728
</tr>
729
<tr>
730
<td class=code>virtual bool</td>
731
<td class=code>(PyObject *pyob) const </td>
732
<td>Based on PyLong_Check</td>
733
</tr>
734
<tr>
735
<td class=code>double</td>
736
<td class=code>operator double() const </td>
737
<td><em>Implicit</em> conversion to double</td>
738
</tr>
739
<tr>
740
<td class=code>long</td>
741
<td class=code>operator long() const</td>
742
<td><em>Implicit</em> conversion to long</td>
743
</tr>
744
<tr>
745
<td class=code>Long&</td>
746
<td class=code>operator= (int v)</td>
747
<td>Assign from int</td>
748
</tr>
749
<tr>
750
<td class=code>Long&</td>
751
<td class=code>operator= (long v) </td>
752
<td>Assign from long</td>
753
</tr>
754
</table>
755
756
<h2>Class Float</h2>
757
758
<p>Class Float corresponds to Python floats, which in turn correspond to C double. The
759
default constructor produces the Python float 0.0. </p>
760
761
<h3>Table 5: Class Float</h3>
762
763
<table cellspacing=0 cellpadding=3px width="95%">
764
<tr>
765
<th>Returns</td>
766
<th>Name and Signature</td>
767
<th>Comments</td>
768
</tr>
769
<tr>
770
<td class=code>explicit</td>
771
<td class=code>Float (PyObject *pyob</a>, bool owned = false)
772
</td>
773
<td>Constructor</td>
774
</tr>
775
<tr>
776
<td class=code></td>
777
<td class=code>Float (const Float& f) </td>
778
<td>Construct from float</td>
779
</tr>
780
<tr>
781
<td class=code>explicit</td>
782
<td class=code>Float (double v=0.0)</td>
783
<td>Construct from double</td>
784
</tr>
785
<tr>
786
<td class=code>explicit</td>
787
<td class=code>Float (const Object& ob)</td>
788
<td>Copycons</td>
789
</tr>
790
<tr>
791
<td class=code>Float&</td>
792
<td class=code>operator= (const Object& rhs)</td>
793
<td>Assignment</td>
794
</tr>
795
<tr>
796
<td class=code>Float&</td>
797
<td class=code>operator= (PyObject* rhsp)</td>
798
<td>Assignment</td>
799
</tr>
800
<tr>
801
<td class=code>virtual bool </td>
802
<td class=code>accepts (PyObject *pyob) const</td>
803
<td>Based on PyFloat_Check</td>
804
</tr>
805
<tr>
806
<td class=code>double </td>
807
<td class=code>operator double () const</td>
808
<td><em>Implicit</em> conversion to double</td>
809
</tr>
810
<tr>
811
<td class=code>Float& </td>
812
<td class=code>operator= (double v)</td>
813
<td>Assign from double</td>
814
</tr>
815
<tr>
816
<td class=code>Float& </td>
817
<td class=code>operator= (int v)</td>
818
<td>Assign from int</td>
819
</tr>
820
<tr>
821
<td class=code>Float& </td>
822
<td class=code>operator= (long v)</td>
823
<td>Assign from long</td>
824
</tr>
825
<tr>
826
<td class=code>Float& </td>
827
<td class=code>operator= (const Int& iob)</td>
828
<td>Assign from Int</td>
829
</tr>
830
</table>
831
832
<h1>Sequences</h1>
833
834
<p>PyCXX implements a quite sophisticated wrapper class for Python sequences. While every
835
effort has been made to disguise the sophistication, it may pop up in the form of obscure
836
compiler error messages, so in this documentation we will first detail normal usage and
837
then discuss what is under the hood.</p>
838
839
<p>The basic idea is that we would like the subscript operator [] to work properly, and to
840
be able to use STL-style iterators and STL algorithms across the elements of the sequence.</p>
841
842
<p>Sequences are implemented in terms of a templated base class, SeqBase<T>. The
843
parameter T is the answer to the question, sequence of what? For Lists, for example, T is
844
Object, because the most specific thing we know about an element of a List is simply that
845
it is an Object. (Class List is defined below; it is a descendent of Object that holds a
846
pointer to a Python list). For strings, T is Char, which is a wrapper in turn of Python
847
strings whose length is one.</p>
848
849
<p>For convenience, the word <strong>Sequence</strong> is a typedef of SeqBase<Object>.</p>
850
851
<h2>General sequences</h2>
852
853
<p>Suppose you are writing an extension module method that expects the first argument to
854
be any kind of Python sequence, and you wish to return the length of that sequence. You
855
might write:</p>
856
857
<pre>static PyObject*
858
my_module_seqlen (PyObject *self, PyObject* args) {
859
try
860
{
861
Tuple t(args); // set up a Tuple pointing to the arguments.
862
if(t.length() != 1)
863
throw PyException("Incorrect number of arguments to seqlen.");
864
Sequence s = t[0]; // get argument and be sure it is a sequence
865
return new_reference_to(Int(s.length()));
866
}
867
catch(const PyException&)
868
{
869
return Py_Null;
870
}
871
}</pre>
872
873
<p>As we will explain later, the try/catch structure converts any errors, such as the
874
first argument not being a sequence, into a Python exception.</p>
875
876
<h3>Subscripting</h3>
877
878
<p>When a sequence is subscripted, the value returned is a special kind of object which
879
serves as a proxy object. The general idea of proxy objects is discussed in Scott Meyers'
880
book, "More Effective C++". Proxy objects are necessary because when one
881
subscripts a sequence it is not clear whether the value is to be used or the location
882
assigned to. Our proxy object is even more complicated than normal because a sequence
883
reference such as s[i] is not a direct reference to the i'th object of s. </p>
884
885
<p>In normal use, you are not supposed to notice this magic going on behind your back. You
886
write:</p>
887
888
<pre>Object t;
889
Sequence s;
890
s[2] = t + s[1]</pre>
891
892
<p>and here is what happens: s[1] returns a proxy object. Since there is no addition
893
operator in Object that takes a proxy as an argument, the compiler decides to invoke an
894
automatic conversion of the proxy to an Object, which returns the desired component of s.
895
The addition takes place, and then there is an assignment operator in the proxy class
896
created by the s[2], and that assignment operator stuffs the result into the 2 component
897
of s.</p>
898
899
<p>It is possible to fool this mechanism and end up with a compiler failing to admit that
900
a s[i] is an Object. If that happens, you can work around it by writing Object(s[i]),
901
which makes the desired implicit conversion, explicit.</p>
902
903
<h3>Iterators</h3>
904
905
<p>Each sequence class provides the following interface. The class seqref<T> is the
906
proxy class. We omit the details of the iterator, const_iterator, and seqref<T>
907
here. See CXX_Objects.h if necessary. The purpose of most of this interface is to satisfy
908
requirements of the STL.</p>
909
910
<h3>The SeqBase<T> Interface</h3>
911
912
<p>SeqBase<T> inherits from Object.</p>
913
914
<table cellspacing=0 cellpadding=3px width="95%">
915
<tr>
916
<th>Type</td>
917
<th>Name</td>
918
</tr>
919
<tr>
920
<td class=code>typedef int </td>
921
<td class=code>size_type</td>
922
</tr>
923
<tr>
924
<td class=code>typedef seqref<T></td>
925
<td class=code>reference</td>
926
</tr>
927
<tr>
928
<td class=code>typedef T </td>
929
<td class=code>const_reference</td>
930
</tr>
931
<tr>
932
<td class=code>typedef seqref<T>*</td>
933
<td class=code>pointer</td>
934
</tr>
935
<tr>
936
<td class=code>typedef int </td>
937
<td class=code>difference_type</td>
938
</tr>
939
<tr>
940
<td class=code>virtual size_type</td>
941
<td class=code>max_size() const</td>
942
</tr>
943
<tr>
944
<td class=code>virtual size_type </td>
945
<td class=code>capacity() const;</td>
946
</tr>
947
<tr>
948
<td class=code>virtual void </td>
949
<td class=code>swap(SeqBase<T>& c);</td>
950
</tr>
951
<tr>
952
<td class=code>virtual size_type </td>
953
<td class=code>size () const;</td>
954
</tr>
955
<tr>
956
<td class=code>explicit </td>
957
<td class=code>SeqBase<T> ();</td>
958
</tr>
959
<tr>
960
<td class=code>explicit </td>
961
<td class=code>SeqBase<T> (PyObject* pyob, bool owned = false);</td>
962
</tr>
963
<tr>
964
<td class=code>explicit </td>
965
<td class=code>SeqBase<T> (const Object& ob);</td>
966
</tr>
967
<tr>
968
<td class=code>SeqBase<T>& </td>
969
<td class=code>operator= (const Object& rhs);</td>
970
</tr>
971
<tr>
972
<td class=code>SeqBase<T>& </td>
973
<td class=code>operator= (PyObject* rhsp);</td>
974
</tr>
975
<tr>
976
<td class=code>virtual bool </td>
977
<td class=code>accepts (PyObject *pyob) const;</td>
978
</tr>
979
<tr>
980
<td class=code>size_type </td>
981
<td class=code>length () const ;</td>
982
</tr>
983
<tr>
984
<td class=code>const T </td>
985
<td class=code>operator[](size_type index) const; </td>
986
</tr>
987
<tr>
988
<td class=code>seqref<T> </td>
989
<td class=code>operator[](size_type index); </td>
990
</tr>
991
<tr>
992
<td class=code>virtual T </td>
993
<td class=code>getItem (size_type i) const;</td>
994
</tr>
995
<tr>
996
<td class=code>virtual void </td>
997
<td class=code>setItem (size_type i, const T& ob);</td>
998
</tr>
999
<tr>
1000
<td class=code>SeqBase<T> </td>
1001
<td class=code>repeat (int count) const;</td>
1002
</tr>
1003
<tr>
1004
<td class=code>SeqBase<T> </td>
1005
<td class=code>concat (const SeqBase<T>& other) const ;</td>
1006
</tr>
1007
<tr>
1008
<td class=code>const T </td>
1009
<td class=code>front () const;</td>
1010
</tr>
1011
<tr>
1012
<td class=code>seqref<T> </td>
1013
<td class=code>front();</td>
1014
</tr>
1015
<tr>
1016
<td class=code>const T </td>
1017
<td class=code>back () const;</td>
1018
</tr>
1019
<tr>
1020
<td class=code>seqref<T> </td>
1021
<td class=code>back(); </td>
1022
</tr>
1023
<tr>
1024
<td class=code>void </td>
1025
<td class=code>verify_length(size_type required_size);</td>
1026
</tr>
1027
<tr>
1028
<td class=code>void </td>
1029
<td class=code>verify_length(size_type min_size, size_type max_size);</td>
1030
</tr>
1031
<tr>
1032
<td class=code>class</td>
1033
<td class=code>iterator;</td>
1034
</tr>
1035
<tr>
1036
<td class=code>iterator </td>
1037
<td class=code>begin (); </td>
1038
</tr>
1039
<tr>
1040
<td class=code>iterator </td>
1041
<td class=code>end ();</td>
1042
</tr>
1043
<tr>
1044
<td class=code>class </td>
1045
<td class=code>const_iterator;</td>
1046
</tr>
1047
<tr>
1048
<td class=code>const_iterator </td>
1049
<td class=code>begin () const;</td>
1050
</tr>
1051
<tr>
1052
<td class=code>const_iterator </td>
1053
<td class=code>end () const;</td>
1054
</tr>
1055
</table>
1056
1057
<p>Any heir of class Object that has a sequence behavior should inherit from class
1058
SeqBase<T>, where T is specified as the type of object that represents the
1059
individual elements of the sequence. The requirements on T are that it has a constructor
1060
that takes a PyObject* as an argument, that it has a default constructor, a copy
1061
constructor, and an assignment operator. In short, any properly defined heir of Object
1062
will work. </p>
1063
1064
<h2>Classes Char and String</h2>
1065
1066
<p>Python strings are unusual in that they are immutable sequences of characters. However,
1067
there is no character type per se; rather, when subscripted strings return a string of
1068
length one. To simulate this, we define two classes Char and String. The Char class
1069
represents a Python string object of length one. The String class represents a Python
1070
string, and its elements make up a sequence of Char's.</p>
1071
1072
<p>The user interface for Char is limited. Unlike String, for example, it is not a
1073
sequence.</p>
1074
1075
<h3>The Char interface</h3>
1076
1077
<p>Char inherits from Object.</p>
1078
1079
<table cellspacing=0 cellpadding=3px width="95%">
1080
<tr>
1081
<th>Type</td>
1082
<th>Name</td>
1083
</tr>
1084
<tr>
1085
<td class=code>explicit</td>
1086
<td class=code>Char (PyObject *pyob, bool owned = false)</td>
1087
</tr>
1088
<tr>
1089
<td class=code></td>
1090
<td class=code>Char (const Object& ob) </td>
1091
</tr>
1092
<tr>
1093
<td class=code></td>
1094
<td class=code>Char (const std::string& v = "") </td>
1095
</tr>
1096
<tr>
1097
<td class=code></td>
1098
<td class=code>Char (char v)</td>
1099
</tr>
1100
<tr>
1101
<td class=code></td>
1102
<td class=code>Char (Py_UNICODE v)</td>
1103
</tr>
1104
<tr>
1105
<td class=code>Char&</td>
1106
<td class=code>operator= (const std::string& v)</td>
1107
</tr>
1108
<tr>
1109
<td class=code>Char&</td>
1110
<td class=code>operator= (char v) </td>
1111
</tr>
1112
<tr>
1113
<td class=code>Char&</td>
1114
<td class=code>operator= (Py_UNICODE v) </td>
1115
</tr>
1116
<tr>
1117
<td class=code>Char&</td>
1118
<td class=code>operator= (std::basic_string<Py_UNICODE> v) </td>
1119
</tr>
1120
<tr>
1121
<td class=code></td>
1122
<td class=code>operator String() const</td>
1123
</tr>
1124
<tr>
1125
<td class=code></td>
1126
<td class=code>operator std::string () const </td>
1127
</tr>
1128
</table>
1129
1130
<h3>The String Interface</h3>
1131
1132
<p>String inherits from SeqBase<Char>.</p>
1133
1134
<table cellspacing=0 cellpadding=3px width="95%">
1135
<tr>
1136
<th>Type</td>
1137
<th>Name</td>
1138
</tr>
1139
<tr>
1140
<td class=code>explicit </td>
1141
<td class=code>String (PyObject *pyob, bool owned = false)</td>
1142
</tr>
1143
<tr>
1144
<td class=code> </td>
1145
<td class=code>String (const Object& ob)</td>
1146
</tr>
1147
<tr>
1148
<td class=code> </td>
1149
<td class=code>String (const std::string& v = "")</td>
1150
</tr>
1151
<tr>
1152
<td class=code> </td>
1153
<td class=code>String (const std::string& v, const char *encoding, const char *error="strict")</td>
1154
</tr>
1155
<tr>
1156
<td class=code> </td>
1157
<td class=code>String (const char *s, const char *encoding, const char *error="strict")</td>
1158
</tr>
1159
<tr>
1160
<td class=code> </td>
1161
<td class=code>String (const char *s, int len, const char *encoding, const char *error="strict")</td>
1162
</tr>
1163
<tr>
1164
<td class=code> </td>
1165
<td class=code>String (const std::string& v, std::string::size_type vsize)</td>
1166
</tr>
1167
<tr>
1168
<td class=code> </td>
1169
<td class=code>String (const char* v)</td>
1170
</tr>
1171
<tr>
1172
<td class=code>String&</td>
1173
<td class=code>operator= (const std::string& v) </td>
1174
</tr>
1175
<tr>
1176
<td class=code>std::string</td>
1177
<td class=code>operator std::string () const</td>
1178
</tr>
1179
<tr>
1180
<td class=code>String</td>
1181
<td class=code>encode( const char *encoding, const char *error="strict" )</td>
1182
</tr>
1183
<tr>
1184
<td class=code>String</td>
1185
<td class=code>decode( const char *encoding, const char *error="strict" )</td>
1186
</tr>
1187
<tr>
1188
<td class=code>std::string</td>
1189
<td class=code>as_std_string() const</td>
1190
</tr>
1191
<tr>
1192
<td class=code>unicodestring</td>
1193
<td class=code>as_unicodestring() const</td>
1194
</tr>
1195
</table>
1196
1197
<h2>Class Tuple</h2>
1198
1199
<p>Class Tuple represents Python tuples. A Tuple is a Sequence. There are two kinds of
1200
constructors: one takes a PyObject* as usual, the other takes an integer number as an
1201
argument and returns a Tuple of that length, each component initialized to Py_None. The
1202
default constructor produces an empty Tuple. </p>
1203
1204
<p>Tuples are not immutable, but attempts to assign to their components will fail if the
1205
reference count is not 1. That is, it is safe to set the elements of a Tuple you have just
1206
made, but not thereafter.</p>
1207
1208
<p>Example: create a Tuple containing (1, 2, 4)</p>
1209
1210
<pre>Tuple t(3)
1211
t[0] = Int(1)
1212
t[1] = Int(2)
1213
t[2] = Int(4)</pre>
1214
1215
<p>Example: create a Tuple from a list:</p>
1216
1217
<pre>Dict d
1218
...
1219
Tuple t(d.keys())</pre>
1220
1221
<h3>The Tuple Interface</h3>
1222
1223
<p>Tuple inherits from Sequence.. Special run-time checks prevent modification if the
1224
reference count is greater than one.</p>
1225
1226
<table cellspacing=0 cellpadding=3px width="95%">
1227
<tr>
1228
<th>Type</td>
1229
<th>Name</td>
1230
<th>Comment</td>
1231
</tr>
1232
<tr>
1233
<td class=code>virtual void</td>
1234
<td class=code>setItem (int offset, const Object&ob) </td>
1235
<td>setItem is overriden to handle tuples properly. </td>
1236
</tr>
1237
<tr>
1238
<td class=code>explicit</td>
1239
<td class=code>Tuple (PyObject *pyob, bool owned = false)</td>
1240
<td></td>
1241
</tr>
1242
<tr>
1243
<td class=code> </td>
1244
<td class=code>Tuple (const Object& ob)</td>
1245
<td></td>
1246
</tr>
1247
<tr>
1248
<td class=code>explicit</td>
1249
<td class=code>Tuple (int size = 0)</td>
1250
<td>Create a tuple of the given size. Items initialize to Py_None. Default is an empty
1251
tuple.</td>
1252
</tr>
1253
<tr>
1254
<td class=code>explicit</td>
1255
<td class=code>Tuple (const Sequence& s)</td>
1256
<td>Create a tuple from any sequence.</td>
1257
</tr>
1258
<tr>
1259
<td class=code>Tuple&</td>
1260
<td class=code>operator= (const Object& rhs)</td>
1261
<td></td>
1262
</tr>
1263
<tr>
1264
<td class=code>Tuple&</td>
1265
<td class=code>operator= (PyObject* rhsp)</td>
1266
<td></td>
1267
</tr>
1268
<tr>
1269
<td class=code>Tuple</td>
1270
<td class=code>getSlice (int i, int j) const </td>
1271
<td>Equivalent to python's t[i:j]</td>
1272
</tr>
1273
</table>
1274
1275
<h2>Class List</h2>
1276
1277
<p>Class List represents a Python list, and the methods available faithfully reproduce the
1278
Python API for lists. A List is a Sequence.</p>
1279
1280
<h3>The List Interface</h3>
1281
1282
<p>List inherits from Sequence.</p>
1283
1284
<table cellspacing=0 cellpadding=3px width="95%">
1285
<tr>
1286
<th>Type</td>
1287
<th>Name</td>
1288
<th>Comment</td>
1289
</tr>
1290
<tr>
1291
<td class=code>explicit</td>
1292
<td class=code>List (PyObject *pyob, bool owned = false)</td>
1293
<td></td>
1294
</tr>
1295
<tr>
1296
<td class=code> </td>
1297
<td class=code>List (const Object& ob)</td>
1298
<td></td>
1299
</tr>
1300
<tr>
1301
<td class=code> </td>
1302
<td class=code>List (int size = 0)</td>
1303
<td>Create a list of the given size. Items initialized to Py_None. Default is an empty list.</td>
1304
</tr>
1305
<tr>
1306
<td class=code> </td>
1307
<td class=code>List (const Sequence& s)</td>
1308
<td>Create a list from any sequence.</td>
1309
</tr>
1310
<tr>
1311
<td class=code>List&</td>
1312
<td class=code>operator= (const Object& rhs)</td>
1313
<td></td>
1314
</tr>
1315
<tr>
1316
<td class=code>List&</td>
1317
<td class=code>operator= (PyObject* rhsp)</td>
1318
<td></td>
1319
</tr>
1320
<tr>
1321
<td class=code>List</td>
1322
<td class=code>getSlice (int i, int j) const</td>
1323
<td></td>
1324
</tr>
1325
<tr>
1326
<td class=code>void</td>
1327
<td class=code>setSlice (int i, int j, const Object& v) </td>
1328
<td></td>
1329
</tr>
1330
<tr>
1331
<td class=code>void</td>
1332
<td class=code>append (const Object& ob)</td>
1333
<td></td>
1334
</tr>
1335
<tr>
1336
<td class=code>void</td>
1337
<td class=code>insert (int i, const Object& ob)</td>
1338
<td></td>
1339
</tr>
1340
<tr>
1341
<td class=code>void</td>
1342
<td class=code>sort ()</td>
1343
<td>Sorts the list in place, using Python's member function. You can also use
1344
the STL sort function on any List instance.</td>
1345
</tr>
1346
<tr>
1347
<td class=code>void</td>
1348
<td class=code>reverse ()</td>
1349
<td>Reverses the list in place, using Python's member function.</td>
1350
</tr>
1351
</table>
1352
1353
<h1>Mappings</h1>
1354
1355
<p>A class MapBase<T> is used as the base class for Python objects with a mapping
1356
behavior. The key behavior of this class is the ability to set and use items by
1357
subscripting with strings. A proxy class mapref<T> is defined to produce the correct
1358
behavior for both use and assignment.</p>
1359
1360
<p>For convenience, <cite>Mapping</cite> is a typedef for <cite>MapBase<Object></cite>.</p>
1361
1362
<h3>The MapBase<T> interface</h3>
1363
1364
<p>MapBase<T> inherits from Object. T should be chosen to reflect the kind of
1365
element returned by the mapping.</p>
1366
1367
<table cellspacing=0 cellpadding=3px width="95%">
1368
<tr>
1369
<th>Type</td>
1370
<th>Name</td>
1371
<th>Comment</td>
1372
</tr>
1373
<tr>
1374
<td class=code>T</td>
1375
<td class=code>operator[](const std::string& key) const</td>
1376
<td></td>
1377
</tr>
1378
<tr>
1379
<td class=code>mapref<T> </td>
1380
<td class=code>operator[](const std::string& key)</td>
1381
<td></td>
1382
</tr>
1383
<tr>
1384
<td class=code>int</td>
1385
<td class=code>length () const</td>
1386
<td>Number of entries.</td>
1387
</tr>
1388
<tr>
1389
<td class=code>int</td>
1390
<td class=code>hasKey (const std::string& s) const </td>
1391
<td>Is m[s] defined?</td>
1392
</tr>
1393
<tr>
1394
<td class=code>T</td>
1395
<td class=code>getItem (const std::string& s) const</td>
1396
<td>m[s]</td>
1397
</tr>
1398
<tr>
1399
<td class=code>virtual void</td>
1400
<td class=code>setItem (const std::string& s, const Object& ob)</td>
1401
<td>m[s] = ob</td>
1402
</tr>
1403
<tr>
1404
<td class=code>void</td>
1405
<td class=code>delItem (const std::string& s)</td>
1406
<td>del m[s]</td>
1407
</tr>
1408
<tr>
1409
<td class=code>void</td>
1410
<td class=code>delItem (const Object& s)</td>
1411
<td></td>
1412
</tr>
1413
<tr>
1414
<td class=code>List</td>
1415
<td class=code>keys () const</td>
1416
<td>A list of the keys.</td>
1417
</tr>
1418
<tr>
1419
<td class=code>List</td>
1420
<td class=code>values () const</td>
1421
<td>A list of the values.</td>
1422
</tr>
1423
<tr>
1424
<td class=code>List</td>
1425
<td class=code>items () const</td>
1426
<td>Each item is a key-value pair.</td>
1427
</tr>
1428
</table>
1429
1430
<h2>Class Dict</h2>
1431
1432
<p>Class Dict represents Python dictionarys. A Dict is a Mapping. Assignment to
1433
subscripts can be used to set the components.</p>
1434
1435
<pre>Dict d
1436
d["Paul Dubois"] = "(925)-422-5426"</pre>
1437
1438
<h3>Interface for Class Dict</h3>
1439
1440
<p>Dict inherits from MapBase<Object>.</p>
1441
1442
<table cellspacing=0 cellpadding=3px width="95%">
1443
<tr>
1444
<th>Type</td>
1445
<th>Name</td>
1446
<th>Comment</td>
1447
</tr>
1448
<tr>
1449
<td class=code>explicit</td>
1450
<td class=code>Dict (PyObject *pyob</a>, bool owned = false)</td>
1451
<td></td>
1452
</tr>
1453
<tr>
1454
<td class=code> </td>
1455
<td class=code>Dict (const Dict& ob)</td>
1456
<td></td>
1457
</tr>
1458
<tr>
1459
<td class=code> </td>
1460
<td class=code>Dict () </td>
1461
<td>Creates an empty dictionary</td>
1462
</tr>
1463
<tr>
1464
<td class=code>Dict&</td>
1465
<td class=code>operator= (const Object& rhs)</td>
1466
<td></td>
1467
</tr>
1468
<tr>
1469
<td class=code>Dict&</td>
1470
<td class=code>operator= (PyObject* rhsp)</td>
1471
<td></td>
1472
</tr>
1473
</table>
1474
1475
<h1>Other classes and facilities.</h1>
1476
1477
<p>Class Callable provides an interface to those Python objects that support a call
1478
method. Class Module holds a pointer to a module. If you want to create an extension
1479
module, however, see the extension facility. There is a large set of numeric operators.</p>
1480
1481
<h3>Interface to class Callable</h3>
1482
1483
<table cellspacing=0 cellpadding=3px width="95%">
1484
<tr>
1485
<th>Type</td>
1486
<th>Name</td>
1487
<th>Comment</td>
1488
</tr>
1489
<tr>
1490
<td class=code>explicit</td>
1491
<td class=code>Callable (PyObject *pyob</a>, bool owned = false)</td>
1492
<td></td>
1493
</tr>
1494
<tr>
1495
<td class=code>Callable& </td>
1496
<td class=code>operator= (const Object& rhs)</td>
1497
<td></td>
1498
</tr>
1499
<tr>
1500
<td class=code>Callable& </td>
1501
<td class=code>operator= (PyObject* rhsp)</td>
1502
<td></td>
1503
</tr>
1504
<tr>
1505
<td class=code>Object</td>
1506
<td class=code>apply(const Tuple& args) const</td>
1507
<td>Call the object with the given arguments</td>
1508
</tr>
1509
<tr>
1510
<td class=code>Object</td>
1511
<td class=code>apply(PyObject* pargs = 0) const </td>
1512
<td>Call the object with args as the arguments. Checks that pargs is a tuple.</td>
1513
</tr>
1514
</table>
1515
1516
<h3>Interface to class Module</h3>
1517
1518
<table cellspacing=0 cellpadding=3px width="95%">
1519
<tr>
1520
<th>Type</td>
1521
<th>Name</td>
1522
<th>Comment</td>
1523
</tr>
1524
<tr>
1525
<td class=code>explicit</td>
1526
<td class=code>Module (PyObject* pyob, bool owned = false)</td>
1527
<td></td>
1528
</tr>
1529
<tr>
1530
<td class=code>explicit</td>
1531
<td class=code>Module (const std::string name)</td>
1532
<td>Construct from name of module; does the import if needed.</td>
1533
</tr>
1534
<tr>
1535
<td class=code></td>
1536
<td class=code>Module (const Module& ob) </td>
1537
<td>Copy constructor</td>
1538
</tr>
1539
<tr>
1540
<td class=code>Module&</td>
1541
<td class=code>operator= (const Object& rhs) </td>
1542
<td>Assignment</td>
1543
</tr>
1544
<tr>
1545
<td class=code>Module&</td>
1546
<td class=code>operator= (PyObject* rhsp) </td>
1547
<td>Assignment</td>
1548
</tr>
1549
</table>
1550
1551
<h3>Numeric interface</h3>
1552
1553
<p>Unary operators for plus and minus, and binary operators +, -, *, /, and % are defined
1554
for pairs of objects and for objects with scalar integers or doubles (in either
1555
order). Functions abs(ob) and coerce(o1, o2) are also defined. </p>
1556
1557
<p>The signature for coerce is:</p>
1558
1559
<pre>inline std::pair<Object,Object> coerce(const Object& a, const Object& b)</pre>
1560
1561
<p>Unlike the C API function, this simply returns the pair after coercion.</p>
1562
1563
<h3>Stream I/O</h3>
1564
1565
<p>Any object can be printed using stream I/O, using std::ostream& operator<<
1566
(std::ostream& os, const Object& ob). The object's str() representation is
1567
converted to a standard string which is passed to std::ostream& operator<<
1568
(std::ostream& os, const std::string&).</p>
1569
1570
<h2>Exceptions</h2>
1571
1572
<p>The Python exception facility and the C++ exception facility can be merged via the use
1573
of try/catch blocks in the bodies of extension objects and module functions.</p>
1574
1575
<h3>Class Exception and its children</h3>
1576
1577
<p>A set of classes is provided. Each is derived from class Exception, and represents a
1578
particular sort of Python exception, such as IndexError, RuntimeError, ValueError. Each of
1579
them (other than Exception) has a constructor which takes an explanatory string as an
1580
argument, and is used in a throw statement such as:</p>
1581
1582
<pre>throw IndexError("Index too large in MyObject access.");</pre>
1583
1584
<p>If in using a routine from the Python API, you discover that it has returned a NULL
1585
indicating an error, then Python has already set the error message. In that case you
1586
merely throw Exception.</p>
1587
1588
<h3>List of Exceptions</h3>
1589
1590
<p>The exception hierarchy mirrors the Python exception hierarchy. The concrete exception
1591
classes are shown here.</p>
1592
1593
<table cellspacing=0 cellpadding=3px width="95%">
1594
<tr>
1595
<th>Type</th>
1596
<th>Interface for class Exception</th>
1597
</tr>
1598
<tr>
1599
<td class=code>explicit </td>
1600
<td class=code>Exception()</td>
1601
</tr>
1602
<tr>
1603
<td class=code> </td>
1604
<td class=code>Exception (const std::string& reason) </td>
1605
</tr>
1606
<tr>
1607
<td class=code> </td>
1608
<td class=code>Exception (PyObject* exception, const std::string& reason) </td>
1609
</tr>
1610
<tr>
1611
<td class=code>void </td>
1612
<td class=code>clear()</td>
1613
</tr>
1614
<tr>
1615
<td class=code></td>
1616
<td>Constructors for other children of class Exception</td>
1617
</tr>
1618
<tr>
1619
<td class=code> </td>
1620
<td class=code>TypeError (const std::string& reason)</td>
1621
</tr>
1622
<tr>
1623
<td class=code> </td>
1624
<td class=code>IndexError (const std::string& reason)</td>
1625
</tr>
1626
<tr>
1627
<td class=code> </td>
1628
<td class=code>AttributeError (const std::string& reason)</td>
1629
</tr>
1630
<tr>
1631
<td class=code> </td>
1632
<td class=code>NameError (const std::string& reason)</td>
1633
</tr>
1634
<tr>
1635
<td class=code> </td>
1636
<td class=code>RuntimeError (const std::string& reason)</td>
1637
</tr>
1638
<tr>
1639
<td class=code> </td>
1640
<td class=code>SystemError (const std::string& reason)</td>
1641
</tr>
1642
<tr>
1643
<td class=code> </td>
1644
<td class=code>KeyError (const std::string& reason)</td>
1645
</tr>
1646
<tr>
1647
<td class=code> </td>
1648
<td class=code>ValueError (const std::string& reason)</td>
1649
</tr>
1650
<tr>
1651
<td class=code> </td>
1652
<td class=code>OverflowError (const std::string& reason)</td>
1653
</tr>
1654
<tr>
1655
<td class=code> </td>
1656
<td class=code>ZeroDivisionError (const std::string& reason)</td>
1657
</tr>
1658
<tr>
1659
<td class=code> </td>
1660
<td class=code>MemoryError (const std::string& reason)</td>
1661
</tr>
1662
<tr>
1663
<td class=code> </td>
1664
<td class=code>SystemExit (const std::string& reason)</td>
1665
</tr>
1666
</table>
1667
1668
<h2>Using Exceptions in extension methods</h2>
1669
1670
<p>The exception facility allows you to integrate the C++ and Python exception mechanisms.
1671
To do this, you must use the style described below when writing module methods in the old
1672
C style. </p>
1673
1674
<p>Note: If using the ExtensionModule or PythonExtension mechanisms described below, the
1675
method handlers include exception handling so that you only need to use exceptions
1676
explicitly in unusual cases.</p>
1677
1678
<h3>Catching Exceptions from the Python API or PyCXX.</h3>
1679
1680
<p>When writing an extension module method, you can use the following boilerplate. Any
1681
exceptions caused by the Python API or PyCXX itself will be converted into a Python
1682
exception. Note that Exception is the most general of the exceptions listed above, and
1683
therefore this one catch clause will serve to catch all of them. You may wish to catch
1684
other exceptions, not in the Exception family, in the same way. If so, you need to make
1685
sure you set the error in Python before returning.</p>
1686
1687
<pre>static PyObject *
1688
some_module_method(PyObject* self, PyObject* args)
1689
{
1690
Tuple a( args ); // we know args is a Tuple
1691
try
1692
{
1693
...calculate something from a...
1694
return ...something, usually of the form new_reference_to(some Object);
1695
}
1696
catch( const Exception& )
1697
{
1698
//Exception caught, passing it on to Python
1699
return None();
1700
}
1701
}
1702
</pre>
1703
1704
<h3>How to clear an Exception</h3>
1705
1706
<p>If you anticipate that an Exception may be thrown and wish to recover from it, change
1707
the catch phrase to set a reference to an Exception, and use the method clear() from class
1708
Exception to clear it.:</p>
1709
1710
<pre>catch( Exception& e )
1711
{
1712
e.clear();
1713
...now decide what to do about it...
1714
}
1715
</pre>
1716
1717
<h2>Extension Facilities</h2>
1718
1719
<p>CXX/Extensions.hxx provides facilities for:
1720
1721
<ul>
1722
<li>Creating a Python extension module</li>
1723
<li>Creating new Python extension types</li>
1724
</ul>
1725
1726
<p>These facilities use CXX/Objects.hxx and its support file cxxsupport.cxx.</p>
1727
1728
<p>If you use CXX/Extensions.hxx you must also include source files cxxextensions.c and
1729
cxx_extensions.cxx</p>
1730
1731
<h3>Creating an Python extension module</h3>
1732
1733
<p>The usual method of creating a Python extension module is to declare and initialize its
1734
method table in C. This requires knowledge of the correct form for the table and the order
1735
in which entries are to be made into it, and requires casts to get everything to compile
1736
without warning. The PyCXX header file CXX/Extensions.h offers a simpler method. Here is a
1737
sample usage, in which a module named "example" is created. Note that two
1738
details are necessary:
1739
1740
<ul>
1741
<li>The initialization function must be declared to have external C linkage and to have the
1742
expected name. This is a requirement imposed by Python</li>
1743
<li>The ExtensionModule object must have a storage class that survives the call to the
1744
initialization function. This is most easily accomplished by using a static local inside
1745
the initialization function, as in initexample below.</li>
1746
</ul>
1747
1748
<p>To create an extension module, you inherit from class ExtensionModule templated on
1749
yourself: In the constructor, you make calls to register methods of this class with Python
1750
as extension module methods. In this example, two methods are added (this is a simplified
1751
form of the example in Demo/example.cxx):</p>
1752
1753
<pre>class example_module : public ExtensionModule<example_module>
1754
{
1755
public:
1756
example_module()
1757
: ExtensionModule<example_module>( "example" )
1758
{
1759
add_varargs_method("sum", &example_module::ex_sum, "sum(arglist) = sum of arguments");
1760
add_varargs_method("test", &example_module::ex_test, "test(arglist) runs a test suite");
1761
1762
initialize( "documentation for the example module" );
1763
}
1764
1765
virtual ~example_module() {}
1766
1767
private:
1768
Object ex_sum(const Tuple &a) { ... }
1769
Object ex_test(const Tuple &a) { ... }
1770
};
1771
</pre>
1772
1773
<p>To initialize the extension, you just instantiate one static instance (static so it
1774
does not destroy itself!):</p>
1775
1776
<pre>void initexample()
1777
{
1778
static example_module* example = new example_module;
1779
}</pre>
1780
1781
<p>The methods can be written to take Tuples as arguments and return Objects. If
1782
exceptions occur they are trapped for you and a Python exception is generated. So, for
1783
example, the implementation of ex_sum might be:</p>
1784
1785
<pre>Object ex_sum (const Tuple &a)
1786
{
1787
Float f(0.0);
1788
for( int i = 0; i < a.length(); i++ )
1789
{
1790
Float g(a[i]);
1791
f = f + g;
1792
}
1793
return f;
1794
}</pre>
1795
1796
<p>class ExtensionModule contains methods to return itself as a Module object, or to
1797
return its dictionary.</p>
1798
1799
<h3>Interface to class ExtensionModule</h3>
1800
1801
<table cellspacing=0 cellpadding=3px width="95%">
1802
<tr>
1803
<th>Type</td>
1804
<th>Name</td>
1805
<th>Comment</td>
1806
</tr>
1807
<tr>
1808
<td class=code>explicit</td>
1809
<td class=code>ExtensionModule (char* name) </td>
1810
<td>Create an extension module named "name"</td>
1811
</tr>
1812
<tr>
1813
<td class=code>virtual </td>
1814
<td class=code>~ExtensionModule () </td>
1815
<td>Destructor</td>
1816
</tr>
1817
<tr>
1818
<td class=code>Dict</td>
1819
<td class=code>moduleDictionary() const</td>
1820
<td>Returns the module dictionary; module must be initialized.</td>
1821
</tr>
1822
<tr>
1823
<td class=code>Module</td>
1824
<td class=code>module() const</td>
1825
<td>This module as a Module.</td>
1826
</tr>
1827
<tr>
1828
<td class=code>void </td>
1829
<td class=code>add_varargs_method (char *name, method_varargs_function_t method, char *documentation="")</td>
1830
<td>Add a method to the module.</td>
1831
</tr>
1832
<tr>
1833
<td class=code>void </td>
1834
<td class=code>add_keyword_method (char *name, method_keyword_function_t method, char *documentation=""</td>
1835
<td>Add a method that takes keywords</td>
1836
</tr>
1837
<tr>
1838
<td class=code>void</td>
1839
<td class=code>initialize() (protected, call from constructor)</td>
1840
<td>Initialize the module once all methods have been added. </td>
1841
</tr>
1842
</table>
1843
1844
<p>The signatures above are:</p>
1845
1846
<pre>typedef Object (T::*method_varargs_function_t)( const Tuple &args );
1847
typedef Object (T::*method_keyword_function_t)( const Tuple &args, const Dict &kws
1848
);</pre>
1849
1850
<p>That is, the methods take a Tuple or a Tuple and a Dict, and return an Object. The
1851
example below has an & in front of the name of the method; we found one compiler that
1852
needed this.</p>
1853
1854
<h2>Creating a Python extension type</h2>
1855
1856
<p>One of the great things about Python is the way you can create your own object types
1857
and have Python welcome them as first-class citizens. Unfortunately, part of the way you
1858
have to do this is not great. Key to the process is the creation of a Python "type
1859
object". All instances of this type must share a reference to this one unique type
1860
object. The type object itself has a multitude of "slots" into which the
1861
addresses of functions can be added in order to give the object the desired behavior. </p>
1862
1863
<p>Creating extension objects is of course harder since you must specify
1864
how the object behaves and give it methods. This is shown in some detail in the example
1865
range.h and range.cxx, with the test routine rangetest.cxx, in directory Demo. If you have never
1866
created a Python extension before, you should read the Extension manual first and be very
1867
familiar with Python's "special class methods". Then what follows will make more
1868
sense.</p>
1869
1870
<p>The basic idea is to inherit from PythonExtension templated on your self</p>
1871
1872
<pre>class MyObject: public PythonExtension<MyObject> {...}</pre>
1873
1874
<p>As a consequence:
1875
1876
<ul>
1877
<li>MyObject is a child of PyObject, so that a MyObject* is-a PyObject*. </li>
1878
<li>A static method <cite>check(PyObject*)</cite> is created in class MyObject. This function
1879
returns a boolean, testing whether or not the argument is in fact a pointer to an instance
1880
of MyObject.</li>
1881
<li>The user can connect methods of MyObject to Python so that they are methods on MyObject
1882
objects. Each such method has the signature:<br>
1883
Object method_name (const Tuple& args).</li>
1884
<li>The user can override virtual methods of PythonExtension in order to set behaviors.</li>
1885
<li>A method is created to handle the deletion of an instance if and when its reference
1886
count goes to zero. This method ensures the calling of the class destructor ~MyObject(),
1887
if any, and releases the memory (see below).</li>
1888
<li>Both automatic and heap-based instances of MyObject can be created.</li>
1889
</ul>
1890
1891
<h3>Sample usage of PythonExtension</h3>
1892
1893
<p>Here is a brief overview. You create a class that inherits from PythonExtension
1894
templated upon itself. You override various methods from PythonExtension to implement
1895
behaviors, such as getattr, sequence_item, etc. You can also add methods to the object
1896
that are usable from Python using a similar scheme as for module methods above. </p>
1897
1898
<p>One of the consequences of inheriting from PythonExtension is that you are inheriting
1899
from PyObject itself. So your class is-a PyObject and instances of it can be passed to the
1900
Python C API. Note: this example uses the namespace feature of PyCXX.</p>
1901
1902
<p>Hint: You can avoid needing to specify the Py:: prefix if you include the C++ statement
1903
<cite>using Py;</cite> at the top of your files.</p>
1904
1905
<pre>class range: public Py::PythonExtension<range>
1906
{
1907
public:
1908
... constructors, data, etc.
1909
... methods not callable from Python
1910
// initializer, see below
1911
static void init_type();
1912
// override functions from PythonExtension
1913
virtual Py::Object repr();
1914
virtual Py::Object getattr( const char *name );
1915
1916
virtual int sequence_length();
1917
virtual Py::Object sequence_item( int i );
1918
virtual Py::Object sequence_concat( const Py::Object &j );
1919
virtual Py::Object sequence_slice( int i, int j );
1920
1921
// define python methods of this object
1922
Py::Object amethod (const Py::Tuple& args);
1923
Py::Object value (const Py::Tuple& args);
1924
Py::Object assign (const Py::Tuple& args);
1925
};</pre>
1926
1927
<p>
1928
To initialize the type we provide a static method that we can call from some module's
1929
initializer. We set the name, doc string, and indicate which behaviors range objects
1930
support. Then we adds the methods.</p>
1931
1932
<pre>void range::init_type()
1933
{
1934
behaviors().name("range");
1935
behaviors().doc("range objects: start, stop, step");
1936
behaviors().supportRepr();
1937
behaviors().supportGetattr();
1938
behaviors().supportSequenceType();
1939
1940
add_varargs_method("amethod", &range::amethod,
1941
"demonstrate how to document amethod");
1942
add_varargs_method("assign", &range::assign);
1943
add_varargs_method("value", &range::value);
1944
}</pre>
1945
</a>
1946
1947
<p>Do not forget to add the call range::init_type() to some module's init function. You will want
1948
a method in some module that can create range objects, too.</p>
1949
1950
<h3>Interface to PythonExtension <T></h3>
1951
1952
<p>Your extension class T inherits PythonExtension<T>.</p>
1953
1954
<table cellspacing=0 cellpadding=3px width="95%">
1955
<tr>
1956
<th>Type</td>
1957
<th>Name</td>
1958
<th>Comment</td>
1959
</tr>
1960
<tr>
1961
<td class=code>virtual </td>
1962
<td class=code>~PythonExtension<T>() </td>
1963
<td>Destructor</td>
1964
</tr>
1965
<tr>
1966
<td class=code>PyTypeObject* </td>
1967
<td class=code>type_object() const</td>
1968
<td>Returns the object type object.</td>
1969
</tr>
1970
<tr>
1971
<td class=code>int</td>
1972
<td class=code>check (PyObject* p)</td>
1973
<td>Is p a T?</td>
1974
</tr>
1975
<tr>
1976
<td colspan="3"><strong>Protected </strong></td>
1977
</tr>
1978
<tr>
1979
<td class=code>void </td>
1980
<td class=code>add_varargs_method (char *name, method_keyword_function_t method, char *documentation=""</td>
1981
<td>Add a method that takes arguments</td>
1982
</tr>
1983
<tr>
1984
<td class=code>void </td>
1985
<td class=code>add_keyword_method (char *name, method_keyword_function_t method, char *documentation=""</td>
1986
<td>Add a method that takes keywords</td>
1987
</tr>
1988
<tr>
1989
<td class=code>static PythonType&</td>
1990
<td class=code>behaviors()</td>
1991
<td>The type object</td>
1992
</tr>
1993
<tr>
1994
<td class=code>void</td>
1995
<td class=code>initialize() (protected, call from constructor)</td>
1996
<td>Initialize the module once all methods have been added. </td>
1997
</tr>
1998
</table>
1999
2000
<p>As before the signatures for the methods are Object mymethod(const Tuple&
2001
args) and Object mykeywordmethod (const Tuple& args, const Dict& keys). In this
2002
case, the methods must be methods of T.</p>
2003
2004
<p>To set the behaviors of the object you override some or all of these methods from
2005
PythonExtension<T>:</p>
2006
2007
<pre>virtual int print( FILE *, int );
2008
virtual Object getattr( const char * );
2009
virtual int setattr( const char *, const Object & );
2010
virtual Object getattro( const Object & );
2011
virtual int setattro( const Object &, const Object & );
2012
virtual int compare( const Object & );
2013
virtual Object repr();
2014
virtual Object str();
2015
virtual long hash();
2016
virtual Object call( const Object &, const Object & );
2017
2018
// Sequence methods
2019
virtual int sequence_length();
2020
virtual Object sequence_concat( const Object & );
2021
virtual Object sequence_repeat( int );
2022
virtual Object sequence_item( int );
2023
virtual Object sequence_slice( int, int );
2024
virtual int sequence_ass_item( int, const Object & );
2025
virtual int sequence_ass_slice( int, int, const Object & );
2026
2027
// Mapping
2028
virtual int mapping_length();
2029
virtual Object mapping_subscript( const Object & );
2030
virtual int mapping_ass_subscript( const Object &, const Object & );
2031
2032
// Number
2033
virtual int number_nonzero();
2034
virtual Object number_negative();
2035
virtual Object number_positive();
2036
virtual Object number_absolute();
2037
virtual Object number_invert();
2038
virtual Object number_int();
2039
virtual Object number_float();
2040
virtual Object number_long();
2041
virtual Object number_oct();
2042
virtual Object number_hex();
2043
virtual Object number_add( const Object & );
2044
virtual Object number_subtract( const Object & );
2045
virtual Object number_multiply( const Object & );
2046
virtual Object number_divide( const Object & );
2047
virtual Object number_remainder( const Object & );
2048
virtual Object number_divmod( const Object & );
2049
virtual Object number_lshift( const Object & );
2050
virtual Object number_rshift( const Object & );
2051
virtual Object number_and( const Object & );
2052
virtual Object number_xor( const Object & );
2053
virtual Object number_or( const Object & );
2054
virtual Object number_power( const Object &, const Object & );
2055
2056
// Buffer
2057
virtual int buffer_getreadbuffer( int, void** );
2058
virtual int buffer_getwritebuffer( int, void** );
2059
virtual int buffer_getsegcount( int* );</pre>
2060
2061
<p>Note that dealloc is not one of the functions you can override. That is what your
2062
destructor is for. As noted below, dealloc behavior is provided for you by
2063
PythonExtension.</p>
2064
2065
<h3>Type initialization</h3>
2066
2067
<p>To initialize your type, supply a static public member function that can be called
2068
from the extension module. In that function, obtain the PythonType object by calling
2069
behaviors() and apply appropriate "support" methods from PythonType to turn on
2070
the support for that behavior or set of behaviors.</p>
2071
2072
<pre>void supportPrint(void);
2073
void supportGetattr(void);
2074
void supportSetattr(void);
2075
void supportGetattro(void);
2076
void supportSetattro(void);
2077
void supportCompare(void);
2078
void supportRepr(void);
2079
void supportStr(void);
2080
void supportHash(void);
2081
void supportCall(void);
2082
2083
void supportSequenceType(void);
2084
void supportMappingType(void);
2085
void supportNumberType(void);
2086
void supportBufferType(void);</pre>
2087
2088
<p>Then call add_varargs_method or add_keyword_method to add any methods desired to the
2089
object.</p>
2090
2091
<h3>Notes on memory management and extension objects</h3>
2092
2093
<p>Normal Python objects exist only on the heap. That is unfortunate, as object creation
2094
and destruction can be relatively expensive. Class PythonExtension allows creation of both
2095
local and heap-based objects.</p>
2096
2097
<p>If an extension object is created using operator new, as in:</p>
2098
2099
<pre>range* my_r_ref = new range(1, 20, 3)</pre>
2100
2101
<p>then the entity my_r_ref can be thought of as "owning" the reference created
2102
in the new object. Thus, the object will never have a reference count of zero. If the
2103
creator wishes to delete this object, they should either make sure the reference count is
2104
1 and then do delete my_r_ref, or decrement the reference with Py_DECREF(my_r_ref).</p>
2105
2106
<p>Should my_r_ref give up ownership by being used in an Object constructor, all will
2107
still be well. When the Object goes out of scope its destructor will be called, and that
2108
will decrement the reference count, which in turn will trigger the special dealloc routine
2109
that calls the destructor and deletes the pointer.</p>
2110
2111
<p>If the object is created with automatic scope, as in:</p>
2112
2113
<pre>range my_r(1, 20, 3)</pre>
2114
2115
<p>then my_r can be thought of as owning the reference, and when my_r goes out of scope
2116
the object will be destroyed. Of course, care must be taken not to have kept any permanent
2117
reference to this object. Fortunately, in the case of an exception, the C++ exception
2118
facility will call the destructor of my_r. Naturally, care must be taken not to end up
2119
with a dangling reference, but such objects can be created and destroyed more efficiently
2120
than heap-based PyObjects.</p>
2121
2122
<h2>Putting it all together</h2>
2123
2124
<p>The Demo directory of the distribution contains an extensive example of how to use many
2125
of the facilities in PyCXX. It also serves as a test routine. This test is not completely
2126
exhaustive but does excercise much of the facility.</p>
2127
2128
<h2>Acknowledgment</h2>
2129
2130
<p>Thank you to Geoffrey Furnish for patiently teaching me the finer points of C++ and its
2131
template facility, and his critique of PyCXX in particular. With version 4 I welcome Barry
2132
Scott as co-author. -- Paul Dubois</p>
2133
2134
</body>
2135
</html>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1