yade-dev team mailing list archive

[Václav Šmilauer <eudoxos@xxxxxxxx>]

Hi,

in recent commits, I introduced new, much cleaner way of wrapping class
in python using YADE_CLASS_BASE_ATTRS macro in headers. It recreates the
real class hierarchy in python (rather than emulating it), should be
faster and much more extensible, and willl finally get rid of
object['attr'] syntax, instead of real python's way object.attr (the
former will be still supported for some time, but we will give
warnings).

This macro obsoletes REGISTER_ATTRIBUTES, REGISTER_CLASS_AND_BASE,
REGISTER_CLASS_NAME, REGISTER_BASE_CLASS_NAME:

 YADE_CLASS_BASE_ATTRS(FrictMat,ElastMat,(frictionAngle));

(FrictMat is the class, ElastMat is its parent, frictionAngle is its
only attribute; attributes of ElastMat are automatically inherited)

Before putting this to all classes, we have a few choices to make:

1. This macro can be present in the hpp (class declaration) or in cpp
(implementation file). There are pros and cons of both, I prefer keeping
it in headers, but it might make compilation a little slower, since it
expands to lots of template code. Is there agreement?

2. List of attributes is used for both serialization and python access.
For python, we could provide docstrings for each data member, which
would show up in ipython's help and in epydoc documentation as well. It
would necessitate to write this instead (everywhere)

YADE_CLASS_BASE_ATTRS(FrictMat,ElastMat,(frictionAngle,"internal
friction angle. (:dflt:.5; :unit:dimensionless)"))

The disadvantage would be that doxygen's comments would be duplicate (or
would not be present at all) and that all attribute registration code
would have to write at least "" for the docstring. The advantage,
obviously, that everything would be nicely documented inside python,
which is what most people will end up using.

We can imagine wilder things yet (it the macro is in the header), like
the whole class being just

class FrictMat: public ElastMat{
	YADE_CLASS_BASE_ATTRS(FrictMat,ElastMat,
		(frictionAngle,Real,.5,"docstring")
	);
};
REGISTER_SERIALIZABLE(FrictMat);
// in the .cpp file
YADE_PLUGIN((FrictMat))

which would expand to:
class FrictMat: public ElastMat{
	Real frictionAngle; // declaration
	FrictMat(): frictionAngle(.5){ createIndex(); } // create ctor, assign defaults to all values
	// register for serialization
	// create py class, properly documented; append default values to the docstring
};

This would be quite invasive, although perhaps nice to have. What do you think?

Cheers, Vaclav