Class wrapping

Exposing D classes to Python is easy! The heart of Pyd's class wrapping features is the wrapped_class template struct:

struct wrapped_class(T, char[] classname = symbolnameof!(T));

To expose the constructors, methods, and properties of the class, wrapped_class provides a series of template member functions.

static void def(alias fn, char[] name = symbolnameof!(fn), fn_t = typeof(&fn)) (char[] docstring="");
This wraps a method of the class. It functions exactly like the def function used to wrap regular functions, with one very important difference: There is no support for default arguments. (This is a side-effect of the fact that you cannot call an alias of a method in D, and delegates do not understand default arguments.)
static void static_def(alias fn, char[] name = symbolnameof!(fn), fn_t = typeof(&fn), uint MIN_ARGS = minArgs!(fn)) (char[] docstring="");
This wraps a static member function of the class. It also functions exactly like the def function used to wrap regular functions, and even includes support for default arguments.
static void prop(alias fn, char[] name = symbolnameof!(fn), bool RO = false) (char[] docstring="");
This wraps a property. See the examples below for more details.
  • fn is the name of the property. prop will automatically attempt to wrap both the "get" and "set" forms of the property, unless RO is specified.
  • name is the name of the property as it will appear in Python. As with def, prop will attempt to derive this automatically.
  • RO specifies whether this is a read-only property. If true, it will only wrap the "get" form of the property. If false, it will wrap both the "get" and "set" forms. (This is a little hackish, and I will probably try to make this detection more automatic in the future. It also means it cannot support a property that only has a "set" form.)
  • docstring is the property's docstring. As usual, note that this is a regular function argument, and not a template argument.
static void init(C ...) ();
This allows you to expose the class's constructors to Python. If the class provides a zero-argument constructor, there is no need to specify it; it is always available. Each element of C should be a function type. Each function type should correspond to a constructor. (That is, the arguments to the function should be the same as arguments to the class constructor. The return type is ignored.) There is an additional limitation at this time: No two constructors may have the same number of arguments. Pyd will always attempt to call the first constructor with the right number of arguments. If you wish to support a constructor with default arguments, you must specify each possible constructor call as a different template argument to this function. The examples show a few uses of the init function.
static void iter(iter_t) ();
This allows the user to specify a different overload of opApply than the default. (The default is always the one that is lexically first.) The iter_t argument should be the type of the delegate that forms the argument to opApply. This might be e.g. int delegate(inout int). Don't forget the inout modifiers! (This is not available in Linux; see the note below on opApply wrapping.)
static void alt_iter(alias fn, char[] name = symbolnameof!(fn), iter_t = implementationDetail) (char[] docstring="");
This wraps alternate iterator methods as Python methods that return iterator objects. The wrapped methods should have a signature like that of opApply. (In other words, they should be methods intended to be used with D's ability to iterate over delgates.) The iter_t argument should be the type of the delegate argument to the method. This will usually be derived automatically. (This is not available in Linux; see the note below on opApply wrapping.)

Once you have called all of the member functions of wrapped_class that you wish to, you must issue a call to finalize_class.

void finalize_class(CLS) (CLS cls, char[] docstring="");

This does some final initialization of the class and then registers it with Python. Unlike calls to def, calls to finalize_class must occur after calling module_init. The cls function argument should be an instance of wrapped_class.

If you ever wish to check whether a given class has been wrapped, Pyd helpfully registers all wrapped classes with the is_wrapped template, which is just a templated bool:

template is_wrapped(T);

If you have a class Foo, you can check whether it is wrapped by simply checking whether is_wrapped!(Foo) is true. It is important to note that this is not a const bool, it is a runtime check.

Automatic operator overloading

Pyd will automatically wrap most of D's operator overload functions with appropriate Python operator overloads. There are some caveats:

At the moment, only the following operator overloads are supported:

opAdd, opSub, opMul, opDiv, opMod, opAnd, opOr, opXor, opShl, opShr, opCat, opAddAssign, opSubAssign, opMulAssign, opDivAssign, opModAssign, opAndAssign, opOrAssign, opXorAssign, opShlAssign, opShrAssign, opCatAssign, opIn_r, opCmp, opCall, opApply, opIndex, opIndexAssign, opSlice, opSliceAssign

Missing from this list are opUShr and opUShrAssign. Python does not have an unsigned right-shift operator, so these operator overloads are not supported. (You may still wrap them with a normal method using wrapped_class.def, of course.) Also missing from the list is opApplyReverse. This must be wrapped explicitly with wrapped_class.alt_iter.

Also missing from the list is opAssign. Python has strict reference semantics for its objects, so overloading the assignment operator is not possible. You must explicitly wrap opAssign with a regular method.

Additionally, if a class provides a length property, Pyd will automatically make it available via Python's built-in function len and the special __len__ method. You may still wrap it with prop or def if you wish it to be available as a normal property or method.

Notes on wrapped operators

opApply
Pyd wraps D's iteration protocol with the help of Mikola Lysenko's StackThreads package. This package does not work in GDC, and so opApply wrapping is not available in Linux. See also the with_st option offered by CeleriD.
opSlice, opSliceAssign
Pyd only supports these overloads if both of their two indexes are implicitly convertable to type int. This is a limitation of the Python/C API. Note that this means the zero-argument form of opSlice (for allowing the "empty slice," e.g. foo[]) cannot be wrapped. (I may work around this in the future.) Because Pyd can only automatically wrap the lexically-first method in a class, it will fail to wrap opSlice and opSliceAssign if you define an empty form first.
opCat, opCatAssign
Python does not have a dedicated array concatenation operator. The plus sign (+) is reused for this purpose. Therefore, odd behavior may result with classes that define both opAdd/opAddAssign and one or both of these operators. (Consider yourself warned.) However, the Python/C API considers addition and concatenation distinct operations, and so both of these sets of operator overloads are supported.
opIn_r
Python expects the in operator to return a boolean value (it is a containment test). D convention is for in to search for the value in the container, and to return a pointer to the found item, or null if the item is not found. That said, D does not enforce any particular signature on the in overload, while the Python/C API does. Pyd will check the boolean result of a call to opIn_r, and return that value to Python.

Examples

Suppose we have the following simple class:

import std.stdio;

class Foo {
    int m_i;

    this() { m_i = 0; }
    this(int j) { m_i = j; }
    this(int j, int k) { m_i = j + k; }

    int i() { return m_i; }
    void i(int j) { m_i = j; }

    void foo(char[] s) {
        writefln(s, m_i);
    }

    Foo opAdd(Foo rhs) {
        return new Foo(m_i + rhs.m_i);
    }
}

We would expose this class to Python by putting this code in PydMain after the call to module_init:

// Make an instance of wrapped_class
wrapped_class!(Foo) f;
// Wrap the "foo" method
f.def!(Foo.foo);
// Wrap the "i" property
f.prop!(Foo.i);
// Wrap the constructors.
f.init!(void function(int), void function(int, int));
finalize_class(f);

Now we can use this type from within Python like any other type.

>>> from testmodule import Foo
>>> f = Foo()
>>> f.i
0
>>> f.i = 20
>>> f.foo("Hello! i is ")
Hello! i is 20
>>> f = Foo(10, 10)
>>> f.i
20
>>> g = Foo(30)
>>> g.i
30
>>> e = f + g
>>> e.i
50
>>> # We can even subclass our D type
>>> class MyFoo(Foo):
... 	def bar(self):
... 		print "Hey, i+3 is", self.i + 3
... 
>>> h = MyFoo(3)
>>> h.bar()
Hey, i+3 is 6
>>>