Python Macro Name Conventions

Every export macro is composed as:

PY_<scope>_[FREE_]<kind>[_R|_RW][_QUALIFIED|_CAST][_NAME][_DOC][_<N>]
PY_<scope>_[FREE_]<kind>[_R|_RW][_QUALIFIED|_CAST]_EX[_<N>]

where <scope> is MODULE or CLASS, and <kind> is FUNCTION, METHOD, STATIC_METHOD MEMBER, PUBLIC_MEMBER, CONSTRUCTOR, INNER_CLASS, ...

Every element is optional and they always appear in this order. So PY_CLASS_FREE_MEMBER_RW_NAME_DOC parses as class scope, free function form, property, read/write, custom name, with docstring..

Macro Parameter Prefixes

The macro parameters use Hungarian prefixes to tell you what is expected of the argument:

• t_: The argument must be a type, and may be qualified with namespaces, like std::string.
• i_: The argument must be a valid identifier. It cannot be qualified. This is often required when the identifier must be concatenated to create a unique name.
  • If this argument must also name a type, you must invoke the macro in the correct namespace, or use a typedef or alias to name the type.
  • If this argument must name a class method, just name the method. The class will be prepended.
• f_: The argument must be a function pointer, and may be qualified. It may even be a std::function.
• s_: A null-terminated string literal. "spam" is a string literal, spam is not. If nullptr is allowed, this will be documented.
• v_: some value like an int, float, ...
• o_: some existing object.

Name, Docstring, and Dispatcher Name

Nearly all export macros take common suffixes to add an optional custom Python name or docstring. They all forward to the _EX variant that provides full control over the parameters and the dispatcher name.

At the class scope, the _EX form is unique in that it allows you to pass fully qualified class names, which the other forms cannot since they build the dispatcher name from it.

Normally, you will not be using this _EX variant, but one of the top four:

Suffix	Adds parameters	Use for ...	Example
-	-	Python name = C++ name	PY_MODULE_FUNCTION
_NAME	s_name	Custom Python name	PY_MODULE_FUNCTION_NAME
_DOC	s_doc	With docstring	PY_MODULE_FUNCTION_DOC
_NAME_DOC	s_name, s_doc	Custom Python name + Docstring	PY_MODULE_FUNCTION_NAME_DOC
_EX	s_name, s_doc, i_dispatcher	Custom dispatcher / Qualified class	PY_MODULE_FUNCTION_EX

Examples:

void spam(int a);
 
PY_MODULE_FUNCTION         (foo, spam)                        // foo.spam
PY_MODULE_FUNCTION_DOC     (foo, spam, "eat it")              // foo.spam, documented
PY_MODULE_FUNCTION_NAME    (foo, spam, "eggs")                // foo.eggs
PY_MODULE_FUNCTION_NAME_DOC(foo, spam, "eggs", "eat it")      // foo.eggs, documented
PY_MODULE_FUNCTION_EX      (foo, spam, "eggs", "eat it", dsp) // ... + explicit dispatcher

Qualifying Overloaded Signatures

Macros for exporting functions also come in variants to fully qualify the function signature to disambiguate overloaded functions, by adding the return type (except for constructors) and all parameter types.

The list of parameter types can be passed as a single lass::meta::TypeTuple, or as individual arguments. For the latter, the _<N> tells the number of arguments.

The _<N> form is the most often used one, and simply packs its types into a TypeTuple

Form	Adds parameters	Example
_QUALIFIED	one lass::meta::TypeTuple	PY_MODULE_FUNCTION_QUALIFIED
_QUALIFIED_<N>	N loose types, N = 0…15	PY_MODULE_FUNCTION_QUALIFIED_2

Examples:

double spam(int a, float b);
void spam(const std::string& c);
 
PY_MODULE_FUNCTION_QUALIFIED_2(foo, spam, double, int, float)
PY_MODULE_FUNCTION_QUALIFIED_1(foo, spam, void, const std::string&)

They combine with the _NAME and _DOC suffixes, with the s_name, s_doc, i_dispatcher arguments following the function return and parameter types:

Suffix	Use for ...	Example
_QUALIFIED_<N>	Python name = C++ name	PY_MODULE_FUNCTION_QUALIFIED_2
_QUALIFIED_NAME_<N>	Custom Python name	PY_MODULE_FUNCTION_QUALIFIED_NAME_2
_QUALIFIED_DOC_<N>	With docstring	PY_MODULE_FUNCTION_QUALIFIED_DOC_2
_QUALIFIED_NAME_DOC_<N>	Custom Python name + Docstring	PY_MODULE_FUNCTION_QUALIFIED_NAME_DOC_2
_QUALIFIED_EX_<N>	Full control	PY_MODULE_FUNCTION_QUALIFIED_EX_2