README.txt
1Overview
2========
3
4 SCXX (Simplified CXX) is a lightweight C++ wrapper for dealing with PyObjects.
5
6 It is inspired by Paul Dubois' CXX (available from LLNL), but is much simpler.
7 It does not use templates, so almost any compiler should work. It does not try
8 to hide things like the Python method tables, or the init function. In fact, it
9 only covers wrapping the most common PyObjects. No extra support is added (for
10 example, you'll only get STL support for Python sequences from CXX).
11
12 It lets you write C++ that looks a lot more like Python than the C API. Reference
13 counts are handled automatically. It has not been optimized - it generally uses
14 the highest possible level of the Python C API.
15
16Classes
17=======
18 PWOBase Base class; wraps any PyObject *
19 PWONumber Uses PyNumber_xxx calls. Automatically does the right thing.
20 PWOSequence Base class for all Python sequences.
21 PWOTuple
22 PWOString
23 PWOList
24 PWOMapping Wraps a dictionary
25
26internal
27--------
28 PWOMappingMmbr Used to give PWOMappings Python (reference) semantics.
29 PWOListMmbr Used to give PWOLists Python (reference) semantics.
30
31error
32-----
33 PWException A C++ class that holds appropriate Python exception info.
34
35General Notes
36=============
37
38 These classes can be used to create new Python objects, or wrap existing ones.
39
40 Wrapping an existing one forces a typecheck (except for PWOBase, which doesn't
41 care). So "PWOMapping dict(d);" will throw an exception if d is not a Python
42 Mapping object (a set with one member - dicts). Or you can use the Python C API
43 by casting to a PyObject * (e.g. "Pyxxx_Check((PyObject *)x)").
44
45 Since errors are normally reported through exceptions, use code like this:
46
47 try {
48 //....
49 }
50 catch(PWException e) {
51 return e.toPython();
52 }
53
54 To signal errors in your own code, use:
55 throw PWException(PyExc_xxxx, msg);
56
57 That is: throw a stack-based instance (not heap based), and give it the appropriate
58 PyExc_xxx type and a string that the Python exception can show.
59
60 To return a PWOxxx wrapped (or created) instance to Python, use disOwn():
61
62 return PWONumber(7.0).disOwn();
63
64 Without the disOwn(), the object would be deallocated before Python can get it.
65
66 Note that the PWOxxx classes are generally designed to be created on the stack. The
67 corresponding PyObject is on the heap. When the PWOxxx instance goes out of scope,
68 the PyObject is automatically decreffed (unless you've used disOwn()).
69
70 See the MkWrap (http://www.equi4.com/metakit/mk4py/mkwrap/) project for extensive
71 use of SCXX. Just don't confuse the PWOxxx classes (which _wrap_ Python objects) and
72 the classes exposed by MkWrap (which are _both_ C++ objects _and_ Python objects).
73
74Why SCXX
75========
76
77 I realize that a lot of effort has gone into CXX and some of the initiatives on
78 the C++ SIG. I applaud those efforts; indeed, SCXX was inspired by CXX. But CXX
79 uses fairly up to date features of C++, and wouldn't compile with most of the
80 compilers I have, (I have to keep old versions around to support clients who still
81 use them). On the one where it worked, it produced bloated code (because of the
82 way the compiler handles templates).
83
84 For my purposes, I really only wanted one thing: wrap Python objects, and take
85 care of the refcounts. The result is lightweight, and has the great advantage
86 (like CXX) that using PyObjects in C++ looks very much like using them in Python.
87
88Instructions for use
89====================
90
91 Point to the installation directory with a -I directive.
92 Include PWOImp.cpp in your make.
93
94License
95=======
96
97 No restrictions on usage, modification or redistribution, as long as the copyright
98 notice is maintained. No warranty whatsoever.
99
100Contact
101=======
102
103 Gordon McMillan (McMillan Enterprises, Inc.) gmcm@hypernet.com.
104
105
106