Add wrap_registry_methods to handle reused wrappers.

Also add _docstrings module for easier definitions of docstrings
to be used in the srreal_ext extension module.

Author: pavoljuhas

diffpy/srreal/_docstrings.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srreal     Complex Modeling Initiative
+#                   (c) 2016 Brookhaven Science Associates,
+#                   Brookhaven National Laboratory.
+#                   All rights reserved.
+#
+# File coded by:    Pavol Juhas
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE.txt for license information.
+#
+##############################################################################
+
+
+"""\
+Docstrings for classes and functions in srreal_ext module.
+"""
+
+# Shared docstrings for classes derived from HasClassRegistry ----------------
+
+def get_registry_docstrings(cls):
+    """Build a dictionary of docstrings per each HasClassRegistry method.
+
+    Parameters
+    ----------
+    cls : class type that is wrapped
+        This parameter is used to extract the class name and substitute
+        it in the docstrings template.
+
+    Returns a dictionary mapping Python method names to their docstrins.
+    """
+    n = cls.__name__
+    rv = {k : v.replace('@NAME@', n) for k, v in (
+        ("create", doc_HasClassRegistry_create),
+        ("clone", doc_HasClassRegistry_clone),
+        ("type", doc_HasClassRegistry_type),
+        ("_registerThisType", doc_HasClassRegistry__registerThisType),
+        ("createByType", doc_HasClassRegistry_createByType),
+        ("getRegisteredTypes", doc_HasClassRegistry_getRegisteredTypes),
+    )}
+    return rv
+
+
+doc_HasClassRegistry_create = """\
+Return a new instance of the same type as self.
+
+This method must be overloaded in a derived class.
+"""
+
+
+doc_HasClassRegistry_clone = """\
+Return a new instance that is a copy of self.
+
+This method must be overloaded in a derived class.
+"""
+
+
+doc_HasClassRegistry_type = """\
+Return a unique string type that identifies a @NAME@-derived class.
+The string type is used for class registration and in the `createByType`
+function.
+
+This method must be overloaded in a derived class.
+"""
+
+
+doc_HasClassRegistry__registerThisType = """\
+Add this class to the global registry of @NAME@ types.
+
+This method must be called once after definition of the derived
+class to support pickling and the `createByType` factory.
+"""
+
+
+doc_HasClassRegistry_createByType = """\
+Return a new @NAME@ instance of the specified string type.
+
+Parameters
+----------
+tp : str
+    string type identifying a registered @NAME@ class.
+
+Returns a new instance of the @NAME@-derived class.
+
+See Also
+--------
+getRegisteredTypes : Return set of the recognized type strings.
+"""
+
+
+doc_HasClassRegistry_getRegisteredTypes = """\
+Return a set of string types of the registered @NAME@ classes.
+
+These are the allowed arguments for the `createByType` factory.
+"""

srrealmodule/srreal_registry.cpp

@@ -0,0 +1,39 @@
+/*****************************************************************************
+*
+* diffpy.srreal     Complex Modeling Initiative
+*                   (c) 2016 Brookhaven Science Associates,
+*                   Brookhaven National Laboratory.
+*                   All rights reserved.
+*
+* File coded by:    Pavol Juhas
+*
+* See AUTHORS.txt for a list of people who contributed.
+* See LICENSE.txt for license information.
+*
+******************************************************************************
+*
+* Utilities for wrapping classes that derive from HasClassRegistry.
+*
+*****************************************************************************/
+
+#include <boost/python/object.hpp>
+#include <boost/python/import.hpp>
+
+namespace srrealmodule {
+
+using namespace boost::python;
+
+
+/// get dictionary of Python-defined docstrings for the cls class.
+object get_registry_docstrings(object& cls)
+{
+    object mod = import("diffpy.srreal._docstrings");
+    object getdocs = mod.attr("get_registry_docstrings");
+    object rv = getdocs(cls);
+    return rv;
+}
+
+
+}   // namespace srrealmodule
+
+// End of file

srrealmodule/srreal_registry.hpp

@@ -20,6 +20,7 @@
 #define SRREAL_REGISTRY_HPP_INCLUDED
 
 #include <boost/python/object.hpp>
+#include <boost/python/extract.hpp>
 
 namespace srrealmodule {
 
@@ -66,6 +67,55 @@ class wrapper_registry_configurator
         mutable PyObject* mpyptr;
 };
 
+
+/// retrieve a dictionary of Python-defined docstrings for the cls class.
+::boost::python::object get_registry_docstrings(::boost::python::object& cls);
+
+
+/// helper wrapper function for return value conversion.
+template <class W>
+::boost::python::object getRegisteredTypes_asset()
+{
+    return convertToPythonSet(W::getRegisteredTypes());
+}
+
+
+/// template function that wraps HasClassRegistry methods
+template <class C>
+C& wrap_registry_methods(C& boostpythonclass)
+{
+    namespace bp = boost::python;
+    using namespace boost::python;
+    typedef typename C::wrapped_type::base B;
+    typedef extract<const char*> CString;
+    // get docstrings for the class registry methods.
+    object d = get_registry_docstrings(boostpythonclass);
+    const char* doc_create = CString(d["create"]);
+    const char* doc_clone = CString(d["clone"]);
+    const char* doc_type = CString(d["type"]);
+    const char* doc__registerThisType = CString(d["_registerThisType"]);
+    const char* doc_createByType = CString(d["createByType"]);
+    const char* doc_getRegisteredTypes = CString(d["getRegisteredTypes"]);
+    // define the class registry related methods.
+    boostpythonclass
+        .def("create", &B::create, doc_create)
+        .def("clone", &B::clone, doc_clone)
+        .def("type", &B::type,
+                return_value_policy<copy_const_reference>(),
+                doc_type)
+        .def("_registerThisType", &B::registerThisType,
+                doc__registerThisType)
+        .def("createByType", &B::createByType,
+                bp::arg("tp"), doc_createByType)
+        .staticmethod("createByType")
+        .def("getRegisteredTypes", getRegisteredTypes_asset<B>,
+                doc_getRegisteredTypes)
+        .staticmethod("getRegisteredTypes")
+        ;
+    return boostpythonclass;
+}
+
+
 }   // namespace srrealmodule
 
 #endif  // SRREAL_REGISTRY_HPP_INCLUDED