Class Attribute Export Macros

Detailed Description

Export values and nested types as attributes on the Python class itself.

Unlike properties which install descriptors that get or set member data from or on instances, these attributes are set directly on the Python type object when the class is frozen and are immutable. In Python, they are reached as Foo.CONSTANT or Outer.Inner, without an instance.

Nested enums work the same way, but are exported with PY_CLASS_ENUM(), which is documented in Enum Definitions.

Static Constants
These macros allow you to expose compile-time constant values as static attributes of Python classes. The values are converted to Python objects using PyExportTraits and become accessible as class-level attributes in Python.
#define	PY_CLASS_STATIC_CONST(i_cppClass, s_name, v_value)
	Export a static constant value as a class attribute.

Inner Classes
Macros for adding inner classes (nested classes) to Python-exported classes. These macros establish class relationships where inner classes become attributes of their outer class in Python. The basic form is PY_CLASS_INNER_CLASS( i_outerCppClass, i_innerCppClass ) with: i_outerCppClass : C++ class that will contain the inner class i_innerCppClass : C++ class to be exported as inner class Common suffixes The _NAME, _DOC and _EX suffixes allow you to specify a custom Python name, docstring, or (in rare cases) fully qualified typenames. Macro Fixed parameters Adds parameters Use for ... PY_CLASS_INNER_CLASS_NAME i_outerCppClass, i_innerCppClass s_name Custom Python name PY_CLASS_INNER_CLASS_DOC i_outerCppClass, i_innerCppClass s_doc With docstring (deprecated) PY_CLASS_INNER_CLASS_NAME_DOC i_outerCppClass, i_innerCppClass s_name, s_doc Custom Python name + Docstring (deprecated) PY_CLASS_INNER_CLASS_EX t_outerCppClass, t_innerCppClass s_name, s_doc, i_uniqueSuffix Fully qualified typenames Note Inner classes must be declared with PY_DECLARE_CLASS* macros before using these macros. The outer class may also be the parent class of the inner class. The two *_DOC forms are deprecated as you should set the docstring when declaring the innerclass using PY_DECLARE_CLASS_DOC() or PY_DECLARE_CLASS_NAME_DOC() Example // Declare both classes first PY_DECLARE_CLASS_DOC(Outer, "Outer class") PY_DECLARE_CLASS_DOC(Inner, "Inner class") // Establish inner class relationship PY_CLASS_INNER_CLASS(Outer, Inner)
#define	PY_CLASS_INNER_CLASS_EX(t_outerCppClass, t_innerCppClass, s_name, s_doc, i_uniqueSuffix)
	Exports an inner class with full customization of name, documentation, and symbol suffix.
#define	PY_CLASS_INNER_CLASS_NAME_DOC(i_outerCppClass, i_innerCppClass, s_name, s_doc)
	Exports an inner class with custom name and documentation.
#define	PY_CLASS_INNER_CLASS_NAME(i_outerCppClass, i_innerCppClass, s_name)
	Exports an inner class with custom name but no documentation.
#define	PY_CLASS_INNER_CLASS_DOC(i_outerCppClass, i_innerCppClass, s_doc)
	Exports an inner class with default name and custom documentation.
#define	PY_CLASS_INNER_CLASS(i_outerCppClass, i_innerCppClass)
	Exports an inner class with default name and no documentation.

Macro Definition Documentation

PY_CLASS_STATIC_CONST

#define PY_CLASS_STATIC_CONST	(		i_cppClass,
			s_name,
			v_value )

Export a static constant value as a class attribute.

Adds a static constant to a Python class that can be accessed as a class attribute. The constant value is converted to a Python object at module initialization time and becomes accessible via the class in Python.

Parameters

i_cppClass	Python binding class identifier (must be declared with PY_DECLARE_CLASS_*)
s_name	Name of the constant as it will appear in Python (string literal)
v_value	The constant value to export (must be convertible via PyExportTraits::build)

Example

class MyClass: public PyObjectPlus { ... };
PY_DECLARE_CLASS(MyClass)
PY_CLASS_STATIC_CONST(MyClass, "PI", 3.14159)
PY_CLASS_STATIC_CONST(MyClass, "MAX_SIZE", 1024)
 
// In Python:
// MyClass.PI == 3.14159
// MyClass.MAX_SIZE == 1024

Definition at line 4030 of file pyobject_macros.h.

PY_CLASS_INNER_CLASS_EX

#define PY_CLASS_INNER_CLASS_EX	(		t_outerCppClass,
			t_innerCppClass,
			s_name,
			s_doc,
			i_uniqueSuffix )

Exports an inner class with full customization of name, documentation, and symbol suffix.

This is the most flexible inner class macro, allowing complete control over all parameters. The inner class becomes accessible as an attribute of the outer class in Python. In contrast to the convenience macros, here you can provide fully qualified typenames, at the cost of having to provide a unique suffix.

Parameters

t_outerCppClass	C++ class that will contain the inner class
t_innerCppClass	C++ class to be exported as inner class
s_name	Python name for the inner class (null-terminated C string literal)
s_doc	Python docstring for the inner class (null-terminated C string literal, deprecated: should be nullptr)
i_uniqueSuffix	Unique C++ identifier to generate unique symbols for the registration code. This prevents symbol collisions when multiple inner class exports exist.

Note

Setting a docstring on the inner class using this macro is deprecated. You should be setting the doc when declaring the innerclass using PY_DECLARE_CLASS_DOC() or PY_DECLARE_CLASS_NAME_DOC().

Example

PY_CLASS_INNER_CLASS_EX(Outer, Inner, "CustomInner", nullptr, MyUniqueSuffix) // Outer.CustomInner

Definition at line 4119 of file pyobject_macros.h.

PY_CLASS_INNER_CLASS_NAME_DOC

#define PY_CLASS_INNER_CLASS_NAME_DOC	(		i_outerCppClass,
			i_innerCppClass,
			s_name,
			s_doc )

Value:

    PY_CLASS_INNER_CLASS_EX( i_outerCppClass, i_innerCppClass, s_name, s_doc,\
        LASS_CONCATENATE(i_outerCppClass, i_innerCppClass) )

Exports an inner class with custom name and documentation.

Convenience macro that automatically generates a unique suffix from the class names. Provides full control over the Python name and documentation string.

Parameters

i_outerCppClass	C++ class that will contain the inner class (unqualified name)
i_innerCppClass	C++ class to be exported as inner class (unqualified name)
s_name	Python name for the inner class (null-terminated C string literal)
s_doc	Python docstring for the inner class (null-terminated C string literal, may be nullptr)

Deprecated

You should be setting the doc when declaring the innerclass using PY_DECLARE_CLASS_DOC() or PY_DECLARE_CLASS_NAME_DOC()

Example

PY_CLASS_INNER_CLASS_NAME_DOC(Outer, Inner, "NestedClass", "Documentation") // Outer.NestedClass

Definition at line 4144 of file pyobject_macros.h.

PY_CLASS_INNER_CLASS_NAME

#define PY_CLASS_INNER_CLASS_NAME	(		i_outerCppClass,
			i_innerCppClass,
			s_name )

Value:

    PY_CLASS_INNER_CLASS_NAME_DOC( i_outerCppClass, i_innerCppClass, s_name, 0)

Exports an inner class with custom name but no documentation.

Convenience macro for cases where you want to customize the Python name, but don't need to provide additional documentation.

Parameters

i_outerCppClass	C++ class that will contain the inner class (unqualified name)
i_innerCppClass	C++ class to be exported as inner class (unqualified name)
s_name	Python name for the inner class (null-terminated C string literal)

Example

PY_CLASS_INNER_CLASS_NAME(Outer, Inner, "CustomName") // Outer.CustomName

Definition at line 4163 of file pyobject_macros.h.

PY_CLASS_INNER_CLASS_DOC

#define PY_CLASS_INNER_CLASS_DOC	(		i_outerCppClass,
			i_innerCppClass,
			s_doc )

Value:

    PY_CLASS_INNER_CLASS_NAME_DOC( i_outerCppClass, i_innerCppClass, LASS_STRINGIFY(i_innerCppClass), s_doc)

Exports an inner class with default name and custom documentation.

The inner class will use its C++ class name as the Python name, but allows you to provide custom documentation.

Parameters

i_outerCppClass	C++ class that will contain the inner class (unqualified name)
i_innerCppClass	C++ class to be exported as inner class (unqualified name)
s_doc	Python docstring for the inner class (null-terminated C string literal)

Deprecated

You should be setting the doc when declaring the innerclass using PY_DECLARE_CLASS_DOC() or PY_DECLARE_CLASS_NAME_DOC()

Example

PY_CLASS_INNER_CLASS_DOC(Outer, Inner, "Custom documentation") // Outer.Inner

Definition at line 4184 of file pyobject_macros.h.

PY_CLASS_INNER_CLASS

#define PY_CLASS_INNER_CLASS	(		i_outerCppClass,
			i_innerCppClass )

Value:

    PY_CLASS_INNER_CLASS_NAME_DOC( i_outerCppClass, i_innerCppClass, LASS_STRINGIFY(i_innerCppClass), 0)

Exports an inner class with default name and no documentation.

The simplest inner class export macro. Uses the C++ class name as the Python name and doesn't provide additional documentation beyond what was set during class declaration.

Parameters

i_outerCppClass	C++ class that will contain the inner class (unqualified name)
i_innerCppClass	C++ class to be exported as inner class (unqualified name)

Example

PY_CLASS_INNER_CLASS(Outer, Inner) // Outer.Inner

Definition at line 4201 of file pyobject_macros.h.