Python Properties & Swig

Question

I am attempting to create python bindings for some C++ code using swig. I seem have run into a problem trying to create python properties from some accessor functions I have for methods like the following:

class Player {
public:
  void entity(Entity* entity);
  Entity* entity() const;
};

I tried creating a property using the python property function but it seems that the wrapper classes swig generates are not compatible with it at least for setters.

How do you create properties using swig?

Answer 1

There is an easy way to make python properties from methods with swig.
Suppose C++ code Example.h:

C++ header

class Example{
    public:
      void SetX(int x);
      int  GetX() const;
    };

Lets convert this setter and getter to python propery 'x'. The trick is in .i file. We add some "swiggy" inline python code (with %pythoncode) that is inserted in a body of a resulting python class (in the auto-generated python code).

Swig wrapping Example.i

%module example
%{
     #include "example.h"
%}

class Example{
    public:
      void SetX(int x);
      int  GetX() const;

      %pythoncode %{
         __swig_getmethods__["x"] = GetX
         __swig_setmethods__["x"] = SetX
         if _newclass: x = property(GetX, SetX)
      %}
    };

Check the python code:

python test code

import example

test = example.Example()
test.x = 5
print "Ha ha ha! It works! X = ", repr(test.x)

That is it!

---

---

Make it simplier!

There is no need to rewrite a class definition. Thanks to Joshua advice, one could use SWIG directive %extend ClassName { }.

Swig wrapping Example.i

%module example
%{
     #include "example.h"
%}

%extend Example{
      %pythoncode %{
         __swig_getmethods__["x"] = GetX
         __swig_setmethods__["x"] = SetX
         if _newclass: x = property(GetX, SetX)
      %}
    };

Hiding setter and getter functions

As one may see, test.GetX() and test.SetX() are still in place after conversion. One can hide them by:

a) Rename functions by using %rename, add '_' in the beginning thus making methods "private" for python. In the a SWIG interface .i Example.i

...
class Example{
   %rename(_SetX) SetX(int);
   %rename(_GetX) GetX();
...

(%rename may be placed in some separated place to save the possibility to convert this class to other languages, which don't need these '_')

b) or one can play with %feature("shadow")

Why is it so?

Why do we have to use such things to convert methods to a property by using SWIG? As it was said, SWIG selfishly overrides _setattr_, so one have to use _swig_getmethods_ and _swig_setmethods_ to register functions and stay in the swig way.

Why may one prefer this way?

The methods listed above, especially with PropertyVoodoo are... It is like burning the house to fry an egg. Also it breaks the classes layout, as one have to create inherited classes to make python properties from C++ methods. I mean if class Cow returns class Milk and the inherited class is MilkWithProperties(Milk), how to make Cow to produce MilkWithProperties?

This approach allows one to:

1. explicitly control what C++ methods to convert to python properties
2. conversion rules are located in swig interface(*.i) files, the place where they are supposed to be
3. one resulting autogenerated .py file
4. stay in the swig syntax of insertions in swig generated .py file
5. %pythoncode is ignored if one wraps library to other languages

Update In a newer version SWIG abandoned _swig_property so just use property. It works with old version of swig the same. I've changed the post.

Answer 2

Use Attributes.i

In the SWIG Lib folder is a file called "attributes.i" which is not discussed in the documentation but that contains inline documentation.

All you have to do is add the following line to your interface file.

%include <attributes.i>

You then receive a number of macros (such as %attribute) for defining attributes from existing methods.

An excerpt from the documentation in the attributes.i file:

The following macros convert a pair of set/get methods into a "native" attribute. Use %attribute when you have a pair of get/set methods to a primitive type like in:

  %attribute(A, int, a, get_a, set_a);

  struct A
  {
    int get_a() const;
    void set_a(int aa);
  };

Answer 3

Ooh, this is tricky (and fun). SWIG doesn't recognize this as an opportunity to generate @property: I imagine it'd be all too easy to slip up and recognize lots of false positives if it weren't done really carefully. However, since SWIG won't do it in generating C++, it's still entirely possible to do this in Python using a small metaclass.

So, below, let's say we have a Math class that lets us set and get an integer variable named "pi". Then we can use this code:

example.h

#ifndef EXAMPLE_H
#define EXAMPLE_H

class Math {
 public:
    int pi() const {
        return this->_pi;
    }

    void pi(int pi) {
        this->_pi = pi;
    }

 private:
    int _pi;
};

#endif

example.i

%module example

%{
    #define SWIG_FILE_WITH_INIT
    #include "example.h"
%}

[essentially example.h repeated again]

example.cpp

#include "example.h"

util.py

class PropertyVoodoo(type):
    """A metaclass. Initializes when the *class* is initialized, not
    the object. Therefore, we are free to muck around the class
    methods and, specifically, descriptors."""

    def __init__(cls, *a):
        # OK, so the list of C++ properties using the style described
        # in the OP is stored in a __properties__ magic variable on
        # the class.
        for prop in cls.__properties__:

            # Get accessor.
            def fget(self):
                # Get the SWIG class using super. We have to use super
                # because the only information we're working off of is
                # the class object itself (cls). This is not the most
                # robust way of doing things but works when the SWIG
                # class is the only superclass.
                s = super(cls, self)

                # Now get the C++ method and call its operator().
                return getattr(s, prop)()

            # Set accessor.
            def fset(self, value):
                # Same as above.
                s = super(cls, self)

                # Call its overloaded operator(int value) to set it.
                return getattr(s, prop)(value)

            # Properties in Python are descriptors, which are in turn
            # static variables on the class. So, here we create the
            # static variable and set it to the property.
            setattr(cls, prop, property(fget=fget, fset=fset))

        # type() needs the additional arguments we didn't use to do
        # inheritance. (Parent classes are passed in as arguments as
        # part of the metaclass protocol.) Usually a = [<some swig
        # class>] right now.
        super(PropertyVoodoo, cls).__init__(*a)

        # One more piece of work: SWIG selfishly overrides
        # __setattr__. Normal Python classes use object.__setattr__,
        # so that's what we use here. It's not really important whose
        # __setattr__ we use as long as we skip the SWIG class in the
        # inheritance chain because SWIG's __setattr__ will skip the
        # property we just created.
        def __setattr__(self, name, value):
            # Only do this for the properties listed.
            if name in cls.__properties__:
                object.__setattr__(self, name, value)
            else:
                # Same as above.
                s = super(cls, self)

                s.__setattr__(name, value)

        # Note that __setattr__ is supposed to be an instance method,
        # hence the self. Simply assigning it to the class attribute
        # will ensure it's an instance method; that is, it will *not*
        # turn into a static/classmethod magically.
        cls.__setattr__ = __setattr__

somefile.py

import example
from util import PropertyVoodoo

class Math(example.Math):
    __properties__ = ['pi']
    __metaclass__  = PropertyVoodoo

m = Math()
print m.pi
m.pi = 1024
print m.pi
m.pi = 10000
print m.pi

So the end result is just that you have to create a wrapper class for every SWIG Python class and then type two lines: one to mark which methods should be converted in properties and one to bring in the metaclass.