Static Method Export Macros

Detailed Description

Export C++ static methods or free functions as Python static methods.

Static methods are called on the class itself rather than on instances, and do not receive an implicit self parameter. Both C++ static member functions and free functions can be exported as static methods, but free functions require you to use the PY_CLASS_STATIC_METHOD_EX() variant.

The basic form is:

PY_CLASS_STATIC_METHOD( i_cppClass, i_cppMethod )

with:

• i_cppClass : C++ class containing the method, or its shadow class
• i_cppMethod : C++ static method name to export

Common suffixes

The _NAME, _DOC and _EX suffixes allow you to specify a custom Python name, docstring, or (in rare cases) a custom dispatcher name.

Macro	Fixed parameters	Adds parameters	Use for ...
PY_CLASS_STATIC_METHOD_NAME	i_cppClass, i_cppMethod	s_name	Custom Python name
PY_CLASS_STATIC_METHOD_DOC	i_cppClass, i_cppMethod	s_doc	With docstring
PY_CLASS_STATIC_METHOD_NAME_DOC	i_cppClass, i_cppMethod	s_name, s_doc	Custom Python name + Docstring
PY_CLASS_STATIC_METHOD_EX	t_cppClass, f_cppFunction	s_name, s_doc, i_dispatcher	Free functions as static method, or custom dispatcher name

There are no _QUALIFIED versions of these macros.

Overloading Python static methods

Multiple static methods can be exported to the same Python name, to create a Python static method that is overloaded on the parameter types.

Note

Overload resolution uses first-fit, not best-fit like C++. The first exported overload that matches the arguments will be called.

Example

class Foo
{
    PY_HEADER(python::PyObjectPlus)
public:
    static void bar(int a);
    static void baz(const std::string& s);
};
 
Foo spam(int b, int c);
 
PY_DECLARE_CLASS(Foo)
PY_CLASS_STATIC_METHOD_DOC(Foo, bar, "a regular C++ static method")
PY_CLASS_STATIC_METHOD_EX(Foo, Foo::baz, "baz", "another C++ static method", foo_baz)
PY_CLASS_STATIC_METHOD_EX(Foo, spam, "spam", "free function as static method", foo_spam)

Macros
#define	PY_CLASS_STATIC_METHOD_EX(t_cppClass, f_cppFunction, s_methodName, s_doc, i_dispatcher)
	Export a C++ static method to Python, with full control.
#define	PY_CLASS_STATIC_METHOD_DOC(i_cppClass, i_cppMethod, s_doc)
	Export a C++ static method to Python, with docstring.
#define	PY_CLASS_STATIC_METHOD_NAME_DOC(i_cppClass, i_cppMethod, s_methodName, s_doc)
	Export a C++ static method to Python, with custom name and docstring.
#define	PY_CLASS_STATIC_METHOD_NAME(i_cppClass, i_cppMethod, s_methodName)
	Export a C++ static method to Python, with custom Python name.
#define	PY_CLASS_STATIC_METHOD(i_cppClass, i_cppMethod)
	Export a C++ static method to Python.

Macro Definition Documentation

PY_CLASS_STATIC_METHOD_EX

#define PY_CLASS_STATIC_METHOD_EX	(		t_cppClass,
			f_cppFunction,
			s_methodName,
			s_doc,
			i_dispatcher )

Export a C++ static method to Python, with full control.

This macro exports a C++ static method or free function as a Python static method (class method).

Here you can use a fully qualified class name, at the cost of having to provide a unique suffix.

Note

Unlike the other convenience macros, you must use the full name of the C++ static method, including the class name.

This is the only macro that allows you to export a free function as static method.

Parameters

t_cppClass	C++ class to add the static method to
f_cppFunction	Full name of the C++ function that implements the static method
s_methodName	Python method name (null-terminated C string literal)
s_doc	Method documentation string (null-terminated C string literal, may be nullptr)
i_dispatcher	Unique identifier for the generated dispatcher function

PY_CLASS_STATIC_METHOD_EX(Foo, Foo::bar, "bar", "a regular C++ static method", foo_bar)
PY_CLASS_STATIC_METHOD_EX(Foo, spam, "spam", "free function as static method", foo_spam)

Definition at line 9491 of file pyobject_macros.h.

PY_CLASS_STATIC_METHOD_DOC

#define PY_CLASS_STATIC_METHOD_DOC	(		i_cppClass,
			i_cppMethod,
			s_doc )

Export a C++ static method to Python, with docstring.

Wraps PY_CLASS_STATIC_METHOD_EX() for C++ static member functions with automatically generated dispatcher name and method name derived from C++ method name.

Parameters

i_cppClass	C++ class to add the static method to (unqualified name)
i_cppMethod	Name of the C++ static method to export
s_doc	Method documentation string (null-terminated C string literal, may be nullptr)

Example

PY_CLASS_STATIC_METHOD_DOC(Foo, bar, "Do some bar")

Definition at line 9528 of file pyobject_macros.h.

PY_CLASS_STATIC_METHOD_NAME_DOC

#define PY_CLASS_STATIC_METHOD_NAME_DOC	(		i_cppClass,
			i_cppMethod,
			s_methodName,
			s_doc )

Export a C++ static method to Python, with custom name and docstring.

Wraps PY_CLASS_STATIC_METHOD_EX() for C++ static member functions with automatically generated dispatcher name.

Parameters

i_cppClass	C++ class to add the static method to (unqualified name)
i_cppMethod	Name of the C++ static method to export
s_methodName	Python method name (null-terminated C string literal)
s_doc	Method documentation string (null-terminated C string literal, may be nullptr)

Example

PY_CLASS_STATIC_METHOD_NAME_DOC(Foo, bar, "do_bar", "Do some bar")

Definition at line 9551 of file pyobject_macros.h.

PY_CLASS_STATIC_METHOD_NAME

#define PY_CLASS_STATIC_METHOD_NAME	(		i_cppClass,
			i_cppMethod,
			s_methodName )

Export a C++ static method to Python, with custom Python name.

Wraps PY_CLASS_STATIC_METHOD_EX() for C++ static member functions with automatically generated dispatcher name and no documentation.

Parameters

i_cppClass	C++ class to add the static method to (unqualified name)
i_cppMethod	Name of the C++ static method to export
s_methodName	Python method name (null-terminated C string literal)

Example

PY_CLASS_STATIC_METHOD_NAME(Foo, bar, "baz")

Definition at line 9574 of file pyobject_macros.h.

PY_CLASS_STATIC_METHOD

#define PY_CLASS_STATIC_METHOD	(		i_cppClass,
			i_cppMethod )

Value:

        PY_CLASS_STATIC_METHOD_DOC( i_cppClass, i_cppMethod, 0 )

Export a C++ static method to Python.

Wraps PY_CLASS_STATIC_METHOD_DOC() with no documentation.

Parameters

i_cppClass	C++ class to add the static method to (unqualified name)
i_cppMethod	Name of the C++ static method to export (used as Python method name)

Example

PY_CLASS_STATIC_METHOD(Foo, bar)

Definition at line 9595 of file pyobject_macros.h.