Class Extension Interface

Namespaces
	docstring_macro_impl

Macros
#define	BEGIN_CLASS_MEMBER_REGISTRATION(python_facing_classname)
#define	REGISTER_CLASS_MEMBER_FUNCTION(function, ...)
#define	REGISTER_NAMED_CLASS_MEMBER_FUNCTION(name, function, ...)
#define	BEGIN_BASE_CLASS_MEMBER_REGISTRATION()
#define	IMPORT_BASE_CLASS_REGISTRATION(base_class)
#define	REGISTER_CLASS_MEMBER_DOCSTRING(name, docstring)   this->register_docstring(docstring_macro_impl::get_docstring(&name, #name, docstring));
#define	REGISTER_CLASS_DOCSTRING(docstring)   this->register_docstring({"__doc__", docstring});
#define	REGISTER_GETTER(propname, function)
#define	REGISTER_SETTER(propname, function)
#define	REGISTER_PROPERTY(propname)
#define	BEGIN_CLASS_REGISTRATION
#define	END_CLASS_MEMBER_REGISTRATION   set_registered(); }
#define	REGISTER_CLASS(class_name)
#define	END_CLASS_REGISTRATION

Detailed Description

The class Extension Interface provides a collection of macros that automate the process of exporting a class to Python. The macros are located in sdk/toolkit_class_macros.hpp.

For detailed usage descriptions, see page_turicreate_extension_interface .

Example:

// class must inherit from model_base
#include <model_server/lib/toolkit_class_macros.hpp>
using namespace turi;

class example: public model_base {
  std::string hello_world() {
    return "hello world";
  }

  std::string concat(std::string a, std::string b) {
    return a + b;
  }
  // register class members.
  BEGIN_CLASS_MEMBER_REGISTRATION("example")
  REGISTER_CLASS_MEMBER_FUNCTION(example::hello_world);
  REGISTER_CLASS_MEMBER_FUNCTION(example::concat, "a", "b");
  END_CLASS_MEMBER_REGISTRATION
};

// register class
BEGIN_CLASS_REGISTRATION
REGISTER_CLASS(example)
END_CLASS_REGISTRATION

Macro Definition Documentation

BEGIN_BASE_CLASS_MEMBER_REGISTRATION

#define BEGIN_BASE_CLASS_MEMBER_REGISTRATION

(

)

Value:

public:                                       \
  virtual inline void perform_registration() override { \

Begins a class member registration block for base classes. These

BEGIN_BASE_CLASS_MEMBER_REGISTRATION()

The basic usage is to put this inside a class to be published, and go:

BEGIN_BASE_CLASS_MEMBER_REGISTRATION("python_facing_classname")
REGISTER_ ... OTHER MEMBERS ...
END_CLASS_MEMBER_REGISTRATION

In the parent class, you would register

Definition at line 154 of file toolkit_class_macros.hpp.

BEGIN_CLASS_MEMBER_REGISTRATION

#define BEGIN_CLASS_MEMBER_REGISTRATION

(

python_facing_classname

)

Value:

public:                                                                         \
  virtual inline const char* name() override { return python_facing_classname; } \
  virtual inline const std::string& uid() override {                             \
    static std::string _uid = ("__LINE__," __FILE__);                            \
    return _uid;                                                                 \
  }                                                                              \
  virtual inline void perform_registration() override {                          \
    if (is_registered()) return;

Begins a class member registration block.

BEGIN_CLASS_MEMBER_REGISTRATION(python_facing_classname)

The basic usage is to put this inside a class to be published, and go:

BEGIN_CLASS_MEMBER_REGISTRATION("python_facing_classname")
REGISTER_ ... OTHER MEMBERS ...
END_CLASS_MEMBER_REGISTRATION

Definition at line 68 of file toolkit_class_macros.hpp.

BEGIN_CLASS_REGISTRATION

#define BEGIN_CLASS_REGISTRATION

Value:

__attribute__((visibility("default"))) std::vector<::turi::toolkit_class_specification> get_toolkit_class_registration() { \
     std::vector<::turi::toolkit_class_specification> specs;

Begins a class registration block. Basic usage:

BEGIN_CLASS_REGISTRATION
REGISTER_CLASS(example)
END_CLASS_REGISTRATION

Definition at line 417 of file toolkit_class_macros.hpp.

END_CLASS_MEMBER_REGISTRATION

#define END_CLASS_MEMBER_REGISTRATION   set_registered(); }

Ends a class member registration block. See BEGIN_CLASS_MEMBER_REGISTRATION

Definition at line 427 of file toolkit_class_macros.hpp.

END_CLASS_REGISTRATION

#define END_CLASS_REGISTRATION

Value:

return specs;     \
  }

Ends a class registration block.

Basic usage:

BEGIN_CLASS_REGISTRATION
REGISTER_CLASS(example)
END_CLASS_REGISTRATION

Definition at line 470 of file toolkit_class_macros.hpp.

IMPORT_BASE_CLASS_REGISTRATION

#define IMPORT_BASE_CLASS_REGISTRATION

(

base_class

)

Value:

static_assert(                                                       \
      !std::is_same<decltype(*this), base_class>::value,               \
      "IMPORT_BASE_CLASS_REGISTRATION must be called on base class."); \
  this->base_class::perform_registration();

Begins a class member registration block for a base class.

BEGIN_BASE_CLASS_MEMBER_REGISTRATION()

The basic usage is to put this inside a class that is the base class of an inherited, and go:

BEGIN_BASE_CLASS_MEMBER_REGISTRATION()
REGISTER_ ... OTHER MEMBERS ...
END_CLASS_MEMBER_REGISTRATION

Definition at line 171 of file toolkit_class_macros.hpp.

REGISTER_CLASS

#define REGISTER_CLASS

(

class_name

)

Value:

{ \
       ::turi::toolkit_class_specification spec;  \
       class_name c; \
       spec.name = c.name(); \
       spec.constructor = +[]() { return (::turi::model_base*)(new class_name); }; \
       spec.description["functions"] =  \
          flexible_type_converter<std::map<std::string, \
                                  std::vector<std::string>>>().set(c.list_functions());  \
       spec.description["get_properties"] =  \
          flexible_type_converter<std::vector<std::string>>().set(c.list_get_properties());  \
       spec.description["set_properties"] =  \
          flexible_type_converter<std::vector<std::string>>().set(c.list_set_properties());  \
       spec.description["uid"] =  \
          flexible_type_converter<std::string>().set(c.uid());  \
       specs.push_back(spec); \
    }

Begins a class registration block.

Basic usage:

BEGIN_CLASS_REGISTRATION
REGISTER_CLASS(example)
END_CLASS_REGISTRATION

Definition at line 442 of file toolkit_class_macros.hpp.

REGISTER_CLASS_DOCSTRING

#define REGISTER_CLASS_DOCSTRING

(

docstring

)

this->register_docstring({"__doc__", docstring});

Registers a docstring of a class

BEGIN_CLASS_MEMBER_REGISTRATION("example")
REGISTER_CLASS_MEMBER_FUNCTION(example::hello_world);
REGISTER_CLASS_MEMBER_DOCSTRING(example::hello_world, "prints hello world")

REGISTER_NAMED_CLASS_MEMBER_FUNCTION("hello", example::say_hello, "a", "b")
REGISTER_CLASS_MEMBER_DOCSTRING("hello", "says hello")

REGISTER_PROPERTY(abc)
REGISTER_CLASS_MEMBER_DOCSTRING(abc, "contains the abc property")
REGISTER_CLASS_DOCSTRING("example class")
END_CLASS_MEMBER_REGISTRATION

Definition at line 320 of file toolkit_class_macros.hpp.

REGISTER_CLASS_MEMBER_DOCSTRING

#define REGISTER_CLASS_MEMBER_DOCSTRING	(		name,
			docstring
	)		this->register_docstring(docstring_macro_impl::get_docstring(&name, #name, docstring));

Registers a docstring of a function or property previously registered with any of the registration functions.

Name can be a function, or a string. (Generally for the name, you put the first argument of any of the REGISTER macros and it should work fine)

BEGIN_CLASS_MEMBER_REGISTRATION("example")
REGISTER_CLASS_MEMBER_FUNCTION(example::hello_world);
REGISTER_CLASS_MEMBER_DOCSTRING(example::hello_world, "prints hello world")

REGISTER_NAMED_CLASS_MEMBER_FUNCTION("hello", example::say_hello, "a", "b")
REGISTER_CLASS_MEMBER_DOCSTRING("hello", "says hello")

REGISTER_PROPERTY(abc)
REGISTER_CLASS_MEMBER_DOCSTRING(abc, "contains the abc property")
REGISTER_CLASS_DOCSTRING("example class")
END_CLASS_MEMBER_REGISTRATION

Definition at line 301 of file toolkit_class_macros.hpp.

REGISTER_CLASS_MEMBER_FUNCTION

#define REGISTER_CLASS_MEMBER_FUNCTION	(		function,
			...
	)

Value:

register_function(#function,  \
                    std::vector<std::string>{__VA_ARGS__}, \
                    toolkit_class_wrapper_impl::generate_member_function_wrapper_indirect( \
                    &function, ##__VA_ARGS__));

Registers a single class member function.

REGISTER_CLASS_MEMBER_FUNCTION(function, ...var args of input argument names ...)

Registers a function with no arguments. REGISTER_CLASS_MEMBER_FUNCTION(class::function)

Registers a function with 2 input arguments. The first input argument is named "a" and the 2nd input argument is named "b" REGISTER_CLASS_MEMBER_FUNCTION(class::function, "a", "b")

Example:

class example: public model_base {
  std::string hello_world() {
    return "hello world";
  }

  std::string concat(std::string a, std::string b) {
    return a + b;
  }

  BEGIN_CLASS_MEMBER_REGISTRATION("example")
  REGISTER_CLASS_MEMBER_FUNCTION(example::hello_world);
  REGISTER_CLASS_MEMBER_FUNCTION(example::concat, "a", "b");
  END_CLASS_MEMBER_REGISTRATION
}

The return value of the function will be returned to Python. The function can return void. If the function fails, it should throw an exception which will be forward back to Python as RuntimeError.

Definition at line 113 of file toolkit_class_macros.hpp.

REGISTER_GETTER

#define REGISTER_GETTER	(		propname,
			function
	)

Value:

register_getter(propname,  \
                  toolkit_class_wrapper_impl::generate_getter( \
                  &function));

Registers a function as a getter for a python property.

REGISTER_GETTER(python_property_name, getter_function)

The getter_function must return a single value and take no arguments.

class example: public model_base {

  std::string get_value() {
    return value;
  }
  void set_value(std::string a) {
    a = value;
  }
  std::string value;

  BEGIN_CLASS_MEMBER_REGISTRATION("example")
  REGISTER_GETTER("value", example::get_value)
  REGISTER_SETTER("value", example::set_value)
  END_CLASS_MEMBER_REGISTRATION

Definition at line 347 of file toolkit_class_macros.hpp.

REGISTER_NAMED_CLASS_MEMBER_FUNCTION

#define REGISTER_NAMED_CLASS_MEMBER_FUNCTION	(		name,
			function,
			...
	)

Value:

register_function(name,  \
                    std::vector<std::string>{__VA_ARGS__}, \
                    toolkit_class_wrapper_impl::generate_member_function_wrapper_indirect( \
                    &function, ##__VA_ARGS__));

Like REGISTER_CLASS_MEMBER_FUNCTION but allows the python-facing name of the function to be redefined.

REGISTER_NAMED_CLASS_MEMBER_FUNCTION(python_name, function, ...var args of input argument names ...)

Registers a function with 2 input arguments. The function shall be called "hello" in Python. The first input argument is named "a" and the 2nd input argument is named "b".

REGISTER_NAMED_CLASS_MEMBER_FUNCTION("hello", class::function, "a", "b")

Definition at line 132 of file toolkit_class_macros.hpp.

REGISTER_PROPERTY

#define REGISTER_PROPERTY

(

propname

)

Value:

register_getter(#propname, [=](model_base* curthis, variant_map_type)->variant_type { \
                              return to_variant((dynamic_cast<std::decay<decltype(this)>::type>(curthis))->propname); \
                            }); \
  register_setter(#propname, [=](model_base* curthis, variant_map_type in)->variant_type { \
                              (dynamic_cast<std::decay<decltype(this)>::type>(curthis))->propname =      \
                                        variant_get_value<decltype(propname)>(in["value"]); \
                              return to_variant(0); \
                            });

Registers a member variable, automatically generating a getter and a setter.

REGISTER_PROPERTY(member_variable)

class example: public model_base {
  std::string value;

  BEGIN_CLASS_MEMBER_REGISTRATION("example")
  REGISTER_PROPERTY(value)
  END_CLASS_MEMBER_REGISTRATION

Definition at line 396 of file toolkit_class_macros.hpp.

REGISTER_SETTER

#define REGISTER_SETTER	(		propname,
			function
	)

Value:

register_setter(propname,  \
                  toolkit_class_wrapper_impl::generate_setter( \
                  &function, "value"));

Registers a function as a setter for a python property.

REGISTER_SETTER(python_property_name, setter_function)

The setter_function must have a single argument, and return no values.

class example: public model_base {

  std::string get_value() {
    return value;
  }
  void set_value(std::string a) {
    a = value;
  }
  std::string value;

  BEGIN_CLASS_MEMBER_REGISTRATION("example")
  REGISTER_GETTER("value", example::get_value)
  REGISTER_SETTER("value", example::set_value)
  END_CLASS_MEMBER_REGISTRATION

Definition at line 376 of file toolkit_class_macros.hpp.