Paul F. Dubois, dubois1@llnl.gov
Lawrence Livermore National Laboratory
The CXX
Project Page at
gives you access to the releases, the CVS repository, and more.
All declarations in CXX_Objects.h are in a namespace "Py", and so you may wish to use it in the form:
#include "CXX_Objects.h" using namespace Py;The second part of CXX is a facility to make it easier to create extension modules and extension objects. Also provided is a file CXX_Extensions.h and its support file cxxextensions.c. While the latter is a C file, it is written so as to compile properly with either a C or a C++ compiler. It is not necessary to use this part of CXX in order to use CXX_Objects.h.
A directory "example" is provided in the distribution. The example demonstrates both parts of CXX..
First we consider the CXX_Objects.h facilities.
For example, consider the case in which we wish to write a method, taking a single integer argument, that will create a Python dict and insert into it that Python int plus one under the key value. In C we might do that as follows:
static PyObject* mymodule_addvalue (PyObject* self, PyObject* args) { PyObject *d; PyObject* f; int k; PyArgs_ParseTuple(args, "i", &k); d = PyDict_New(); if (!d) { return NULL; } f = PyInt_NEW(k+1); if(!f) { Py_DECREF(d); /* have to get rid of d first */ return NULL; } if(PyDict_SetItemString(d, "value", f) == -1) { Py_DECREF(f); Py_DECREF(d); return NULL; } return d; }If you have written a significant Python extension, this tedium looks all too familiar. The vast bulk of the coding is error checking and cleanup. Now compare the same thing written in C++ using CXX_Objects. The things with Python-like names (Int, Dict, Tuple) are from CXX_Objects.
static PyObject* mymodule_addvalue (PyObject* self, PyObject* pargs) { try { Tuple args(pargs); args.verify_length(1); Dict d; Int k = args[0]; d["value"] = k + 1; return new_reference_to(d); } catch (const PyException&) { return NULL; } }If there aren't the right number of arguments or the argument isn't an integer, an exception is thrown. In this case we choose to catch it and convert it into a Python exception. C++'s exception handling mechanism takes care all the cleanup.
Note that the creation of the Int k
got the first argument and verified that it is an Int.
Each Object contains a PyObject* to which it owns a reference. (If you don't know what this phrase means, it is explained in the Python extension manual. You don't actually need to understand it very well if you are going to use CXX_Objects. When an Object is destroyed, it releases its ownership on the pointer. Since C++ calls the destructors on objects that are about to go out of scope, we are guaranteed that we will keep the reference counts right even if we unexpectedly leave a routine with an exception.
As a matter of philosophy, CXX_Objects prevents the creation of instances of its classes unless the instance will be a valid instance of its class. When an attempt is made to create an object that will not be valid, an exception is thrown.
Class Object represents the most general kind of Python object. The rest of the classes that represent Python objects inherit from it.
Object
Type
Int
Float
Long
Sequence
String
Tuple
List
Mapping
Dict
Callable
There are several constructors for each of these classes. For example, you can create an Int from an integer as in
Int s(3)However, you can also create an instance of one of these classes using any PyObject* or another Object. If the corresponding Python object does not actually have the type desired, an exception is thrown. This is accomplished as follows. Class Object defines a virtual function accepts:
virtual bool accepts(PyObject* p)The base class version of accepts returns true for any pointer p except 0. This means we can create an Object using any PyObject*, or from any other Object. However, if we attempt to create an Int from a PyObject*, the overridding version of accepts in class Int will only accept pointers that correspond to Python ints. Therefore if we have a Tuple t and we wish to get the first element and be sure it is an Int, we do
Int first_element = t[0]
This will not only accomplish the goal of extracting the first element of the Tuple t, but it will ensure that the result is an Int. If not, an exception is thrown. (The exception mechanism is discussed later.)
Often, PyObject* pointers are acquired from some function, particularly functions in the Python API. If you wish to make an object from the pointer returned by such a function, you need to know if the function returns you an owned or unowned reference. If it is an owned reference, you indicate this by enclosing it in the constructor for a helper class named FromAPI. For example, the routine PyString_FromString returns an owned reference to a Python string object. You could write:
Object w = FromAPI(PyString_FromString("my string"));
FromAPI is a simple helper class that does not increment the reference count in the constructor but decrements it in the destructor. In fact, you probably would never do this, since CXX has a class String and you can just say:
String w("my string")
Indeed, since most of the Python C
API is similarly embodied in Object
and its descendents, you probably will not use FromAPI all that often.
The comparison operators use the Python comparison function to compare values. The method "is" is available to test for absolute identity.
A conversion to standard library string type std::string is supplied using method "as_string". Stream output of Objects uses this conversion, which in turn uses the Python object's str() representation.
All the numeric operators are defined on all possible combinations of Object, long, and double. These use the corresponding Python operators, and should the operation fail for some reason, an exception is thrown.
|
|
|
|
||
explicit | Object (PyObject* pyob=Py_None) | Construct from pointer. Acquires an owned reference. |
explicit | Object (const Object& ob) | Copycons; acquires an owned reference. |
Object& | operator= (const Object& rhs) | Acquires an owned reference. |
Object& | operator= (PyObject* rhsp) | Acquires an owned reference. |
virtual | ~Object () | Releases the reference. |
void | increment_reference_count() | Explicitly increment the count |
void | decrement_reference_count() | Explicitly decrement count but not to zero |
PyObject* | operator* () const | Lends the pointer |
PyObject* | ptr () const | Lends the pointer |
virtual bool | accepts (PyObject *pyob) const | Would assignment of pyob to this object succeed? |
std::string | as_string() const | str() representation |
Python API Interface | ||
int | reference_count () const | reference count |
Type | type () const | associated type object |
String | str () const | str() representation |
String | epr () const | repr () representation |
bool | hasAttr (const std::string& s) const | hasattr(this, s) |
Object | getAttr (const std::string& s) const | getattr(this, s) |
Object | getItem (const Object& key) const | getitem(this, key) |
long | hashValue () const | hash(this) |
void | setAttr (const std::string&
s,
const Object& value) |
this.s = value |
void | delAttr (const std::string& s) | del this.s |
void | delItem (const Object& key) | del this[key] |
bool | isCallable () const | does this have callable behavior? |
bool | isList () const | is this a Python list? |
bool | isMapping () const | does this have mapping behaviors? |
bool | isNumeric () const | does this have numeric behaviors? |
bool | isSequence () const | does this have sequence behaviors? |
bool | isTrue () const | is this true in the Python sense? |
bool | isType (const Type& t) const | is type(this) == t? |
bool | isTuple() const | is this a Python tuple? |
bool | isString() const | is this a Python string? |
bool | isDict() const | is this a Python dictionary? |
Comparison Operators | ||
bool | is(PyObject* pother) const | test for identity |
bool | is(const Object& other) const | test for identity |
bool | operator==(const Object& o2) const | Comparisons use Python cmp |
bool | operator!=(const Object& o2) const | Comparisons use Python cmp |
bool | operator>=(const Object& o2) const | Comparisons use Python cmp |
bool | operator<=(const Object& o2) const | Comparisons use Python cmp |
bool | operator<(const Object& o2) const | Comparisons use Python cmp |
bool | operator>(const Object& o2) const | Comparisons use Python cmp |
|
|
|
explicit | Type (PyObject* pyob) | Constructor |
explicit | Type (const Object& ob) | Constructor |
explicit | Type(const Type& t) | Copycons |
Type& | operator= (const Object& rhs) | Assignment |
Type& | operator= (PyObject* rhsp) | Assignment |
virtual bool | accepts (PyObject *pyob) const | Uses PyType_Check |
|
|
|
explicit | Int (PyObject *pyob) | Constructor |
explicit | Int (const Int& ob) | Constructor |
explicit | Int (long v = 0L) | Construct from long |
explicit | Int (int v) | Contruct from int |
explicit | Int (const Object& ob) | Copycons |
Int& | operator= (const Object& rhs) | Assignment |
Int& | operator= (PyObject* rhsp) | Assignment |
virtual bool | accepts (PyObject *pyob) const | Based on PyInt_Check |
long | operator long() const | Implicit conversion to long int |
Int& | operator= (int v) | Assign from int |
Int& | operator= (long v) | Assign from long |
|
|
|
explicit | Long (PyObject *pyob) | Constructor |
explicit | Long (const Int& ob) | Constructor |
explicit | Long (long v = 0L) | Construct from long |
explicit | Long (int v) | Contruct from int |
explicit | Long (const Object& ob) | Copycons |
Long& | operator= (const Object& rhs) | Assignment |
Long& | operator= (PyObject* rhsp) | Assignment |
virtual bool | accepts (PyObject *pyob) const | Based on PyLong_Check |
double | operator double() const | Implicit conversion to double |
long | operator long() const | Implicit conversion to long |
Long& | operator= (int v) | Assign from int |
Long& | operator= (long v) | Assign from long |
|
|
|
explicit | Float (PyObject *pyob) | Constructor |
Float (const Float& f) | Construct from float | |
explicit | Float (double v=0.0) | Construct from double |
explicit | Float (const Object& ob) | Copycons |
Float& | operator= (const Object& rhs) | Assignment |
Float& | operator= (PyObject* rhsp) | Assignment |
virtual bool | accepts (PyObject *pyob) const | Based on PyFloat_Check |
double | operator double () const | Implicit conversion to double |
Float& | operator= (double v) | Assign from double |
Float& | operator= (int v) | Assign from int |
Float& | operator= (long v) | Assign from long |
Float& | operator= (const Int& iob) | Assign from Int |
The basic idea is that we would like the subscript operator [] to work properly, and to be able to use STL-style iterators and STL algorithms across the elements of the sequence.
Sequences are implemented in terms of a templated base class, SeqBase<T>. The parameter T is the answer to the question, sequence of what? For Lists, for example, T is Object, because the most specific thing we know about an element of a List is simply that it is an Object. (Class List is defined below; it is a descendent of Object that holds a pointer to a Python list). For strings, T is Char, which is a wrapper in turn of Python strings whose length is one.
For convenience, the word Sequence
is typedef'd to SeqBase<Object>.
static PyObject*
my_module_seqlen (PyObject *self,
PyObject* args) {
try {
Tuple t(args); // set up a Tuple pointing to the arguments.
if(t.length() != 1) throw PyException("Incorrect number of arguments to
seqlen.");
Sequence s = t[0]; // get argument and be sure it is a sequence
return new_reference_to(Int(s.length()));
}
catch(const PyException&)
{
return Py_Null;
}
}
As we will explain later, the try/catch structure converts any errors, such as the first argument not being a sequence, into a Python exception.
In normal use, you are not supposed to notice this magic going on behind your back. You write:
Object t;
Sequence s;
s[2] = t + s[1]
and here is what happens: s[1] returns a proxy object. Since there is no addition operator in Object that takes a proxy as an argument, the compiler decides to invoke an automatic conversion of the proxy to an Object, which returns the desired component of s. The addition takes place, and then there is an assignment operator in the proxy class created by the s[2], and that assignment operator stuffs the result into the 2 component of s.
It is possible to fool this mechanism and end up with a compiler failing to admit that a s[i] is an Object. If that happens, you can work around it by writing Object(s[i]), which makes the desired implicit conversion, explicit.
Type | Name | ||
---|---|---|---|
typedef int | size_type | ||
typedef seqref<T> | reference | ||
typedef T | const_reference | ||
typedef seqref<T>* | pointer | ||
typedef int | difference_type | ||
virtual size_type | max_size() const | ||
virtual size_type | capacity() const; | ||
virtual void | swap(SeqBase<T>& c); | ||
virtual size_type | size () const; | ||
explicit | SeqBase<T> (); | ||
explicit | SeqBase<T> (PyObject* pyob); | ||
explicit | SeqBase<T> (const Object& ob); | ||
SeqBase<T>& | operator= (const Object& rhs); | ||
SeqBase<T>& | operator= (PyObject* rhsp); | ||
virtual bool | accepts (PyObject *pyob) const; | ||
size_type | length () const ; | ||
const T | operator[](size_type index) const; | ||
seqref<T> | operator[](size_type index); | ||
virtual T | getItem (size_type i) const; | ||
virtual void | setItem (size_type i, const T& ob); | ||
SeqBase<T> | repeat (int count) const; | ||
SeqBase<T> | concat (const SeqBase<T>& other) const ; | ||
const T | front () const; | ||
seqref<T> | front(); | ||
const T | back () const; | ||
seqref<T> | back(); | ||
void | verify_length(size_type required_size); | ||
void | verify_length(size_type min_size, size_type max_size); | ||
class | iterator; | ||
iterator | begin (); | ||
iterator | end (); | ||
class | const_iterator; | ||
const_iterator | begin () const; | ||
const_iterator | end () const; |
The user interface for Char is limited. Unlike String, for example, it is not a sequence.
|
|
explicit | Char (PyObject *pyob) |
Char (const Object& ob) | |
Char (const std::string& v = "") | |
Char (char v) | |
Char& | operator= (const std::string& v) |
Char& | operator= (char v) |
operator String() const | |
operator std::string () const |
|
|
explicit | String (PyObject *pyob) |
String (const Object& ob) | |
String (const std::string& v = "") | |
String (const std::string& v, std::string::size_type vsize) | |
String (const char* v) | |
String& | operator= (const std::string& v) |
operator std::string () const |
Tuples are not immutable, but attempts to assign to their components will fail if the reference count is not 1. That is, it is safe to set the elements of a Tuple you have just made, but not thereafter.
Example: create a Tuple containing (1, 2, 4)
Tuple t(3) t[0] = Int(1) t[1] = Int(2) t[2] = Int(4)Example: create a Tuple from a list:
Dict d
...
Tuple t(d.keys())
|
|
|
virtual void | setItem (int offset, const Object&ob) | setItem is overriden to handle tuples properly. |
explicit | Tuple (PyObject *pyob) | |
Tuple (const Object& ob) | ||
explicit | Tuple (int size = 0) | Create a tuple of the given size. Items initialize to Py_None. Default is an empty tuple. |
explicit | Tuple (const Sequence& s) | Create a tuple from any sequence. |
Tuple& | operator= (const Object& rhs) | |
Tuple& | operator= (PyObject* rhsp) | |
Tuple | getSlice (int i, int j) const | Equivalent to python's t[i:j] |
|
|
|
explicit | List (PyObject *pyob) | |
List (const Object& ob) | ||
List (int size = 0) | Create a list of the given size. Items initialized to Py_None. Default is an empty list. | |
List (const Sequence& s) | Create a list from any sequence. | |
List& | operator= (const Object& rhs) | |
List& | operator= (PyObject* rhsp) | |
List | getSlice (int i, int j) const | |
void | setSlice (int i, int j, const Object& v) | |
void | append (const Object& ob) | |
void | insert (int i, const Object& ob) | |
void | sort () | Sorts the list in place, using Python's member function. You can also use the STL sort function on any List instance. |
void | reverse () | Reverses the list in place, using Python's member function. |
For convenience, Mapping is typedefed as MapBase<Object>.
|
|
|
T | operator[](const std::string& key) const | |
mapref<T> | operator[](const std::string& key) | |
int | length () const | Number of entries. |
int | hasKey (const std::string& s) const | Is m[s] defined? |
T | getItem (const std::string& s) const | m[s] |
virtual void | setItem (const std::string& s, const Object& ob) | m[s] = ob |
void | delItem (const std::string& s) | del m[s] |
void | delItem (const Object& s) | |
List | keys () const | A list of the keys. |
List | values () const | A list of the values. |
List | items () const | Each item is a key-value pair. |
Dict d
d["Paul Dubois"] = "(925)-422-5426"
Type | Name |
|
explicit | Dict (PyObject *pyob) | |
Dict (const Dict& ob) | ||
Dict () | Creates an empty dictionary | |
Dict& | operator= (const Object& rhs) | |
Dict& | operator= (PyObject* rhsp) |
|
|
|
explicit | Callable (PyObject *pyob) | |
Callable& | operator= (const Object& rhs) | |
Callable& | operator= (PyObject* rhsp) | |
Object | apply(const Tuple& args) const | Call the object with the given arguments |
Object | apply(PyObject* args = 0) const | Call the object with args as the arguments |
|
|
|
Module (const Module& ob) | Copy constructor | |
Module& | operator= (const Object& rhs) | Assignment |
Module& | operator= (PyObject* rhsp) | Assignment |
The signature for coerce is:
inline std::pair<Object,Object> coerce(const Object& a, const Object& b)
Unlike the C API function, this simply returns the pair after coercion.
throw IndexError("Index too large in MyObject access.");If in using a routine from the Python API, you discover that it has returned a NULL indicating an error, then Python has already set the error message. In that case you merely throw Exception.
Type |
|
explicit | Exception () |
Exception (const std::string& reason) | |
Exception (PyObject* exception, const std::string& reason) | |
void | clear() |
|
|
TypeError (const std::string& reason) | |
IndexError (const std::string& reason) | |
AttributeError (const std::string& reason) | |
NameError (const std::string& reason) | |
RuntimeError (const std::string& reason) | |
SystemError (const std::string& reason) | |
KeyError (const std::string& reason) | |
ValueError (const std::string& reason) | |
OverflowError (const std::string& reason) | |
ZeroDivisionError (const std::string& reason) | |
MemoryError (const std::string& reason) | |
SystemExit (const std::string& reason) |
static PyObject *
some_module_method(PyObject* self,
PyObject* args)
{
Tuple a(args);
// we know args is a Tuple
try {
...calculate something from a...
return ...something, usually of the form new_reference_to(some Object);
}
catch(const Exception&)
{
//Exception caught, passing it on to Python
return Null ();
}
}
catch(Exception& e) {
e.clear();
...now decide what to do about it...
}
This example is a simplified version
of Demo/example.cxx.
class example_module : public ExtensionModule<example_module>
{
public:
example_module()
: ExtensionModule<example_module>(
"example" )
{
add_varargs_method("sum",
&example_module::ex_sum,
"sum(arglist) = sum of arguments");
add_varargs_method("test",
&example_module::ex_test,
"test(arglist)
runs a test suite");
initialize( "documentation
for the example module" );
}
virtual ~example_module() {}
The extension methods are then implemented as methods of this class. The actual example also shows how to check for numbers of arguments and handle exceptions.
private: Object ex_sum (const Tuple &a) { Float f(0.0); for (int i = 0; i < a.length(); ++i) { Float g (a[i]); f = f + g; } return f; }Finally, we need to supply initexample:
void initexample() { static example_module *example = new example_module; }
CXX mitigates this difficulty with class PythonExtension. PythonExtension is a templated class, and the way you use it is very odd indeed: you make your new object type inherit from it, giving itself as the template parameter:
class MyObject: public PythonExtension<MyObject> {...}
The class "r" contains two kinds of
methods:
If an extension object is created using operator new, as in:
r* my_r_ref = new r(1, 20, 3)
then the entity my_r_ref can be thought of as "owning" the reference created in the new object. Thus, the object will never have a reference count of zero. If the creator wishes to delete this object, they should either make sure the reference count is 1 and then do delete my_r_ref, or decrement the reference with Py_DECREF(my_r_ref).
Should my_r_ref give up ownership by being used in an Object constructor, all will still be well. When the Object goes out of scope its destructor will be called, and that will decrement the reference count, which in turn will trigger the special dealloc routine that calls the destructor and deletes the pointer.
If the object is created with automatic scope, as in:
r my_r(1, 20, 3)
then my_r can be thought of as owning the reference, and when my_r goes out of scope the object will be destroyed. Of course, care must be taken not to have kept any permanent reference to this object. Fortunately, in the case of an exception, the C++ exception facility will call the destructor of my_r. Naturally, care must be taken not to end up with a dangling reference, but such objects can be created and destroyed more efficiently than heap-based PyObjects.